From 910bd33ea1067df8c3a06d0410ec0fbf84174dbe Mon Sep 17 00:00:00 2001 From: oxspan <36991763+oxspan@users.noreply.github.com> Date: Thu, 12 Nov 2026 02:50:26 +0900 Subject: [PATCH] =?UTF-8?q?=F0=9F=90=9B=20Retry=20denied=20Windows=20file?= =?UTF-8?q?=20replacements?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- QUICKSTART.ko.md | 2 + QUICKSTART.md | 2 + docs/capture-recovery.md | 6 ++ docs/cli-contract.md | 2 + .../adapters/collector/CollectorOperation.kt | 2 +- .../adapters/files/AtomicReplacement.kt | 25 ++++++++ .../scouterctl/adapters/files/CaptureStore.kt | 4 +- .../scouterctl/adapters/files/ContextStore.kt | 4 +- .../adapters/files/CounterCaptureStore.kt | 4 +- .../adapters/files/EvidenceStore.kt | 4 +- .../adapters/files/FileOperation.kt | 2 +- .../kotlin/dev/scouterctl/CaptureWriteTest.kt | 62 +++++++++++++++++++ .../dev/scouterctl/ConnectionDiagnostic.kt | 1 + .../scouterctl/ConnectionDiagnosticTest.kt | 4 +- .../WindowsAtomicReplacementTest.kt | 40 ++++++++++++ 15 files changed, 149 insertions(+), 15 deletions(-) create mode 100644 src/main/kotlin/dev/scouterctl/adapters/files/AtomicReplacement.kt create mode 100644 src/test/kotlin/dev/scouterctl/CaptureWriteTest.kt create mode 100644 src/test/kotlin/dev/scouterctl/WindowsAtomicReplacementTest.kt diff --git a/QUICKSTART.ko.md b/QUICKSTART.ko.md index 84a24fa..0d104be 100644 --- a/QUICKSTART.ko.md +++ b/QUICKSTART.ko.md @@ -55,6 +55,8 @@ scouterctl capture --object-hash 123456 --date 20261107 \ 중단되거나 일부만 저장됐으면 같은 명령에 `--resume`을 붙여 재개합니다. 서비스명·SQL·오류 원문을 저장하려는 경우에만 캡처할 때 `--include-text`를 추가하세요. 민감한 애플리케이션 정보가 포함될 수 있습니다. 자세한 사용법은 [캡처와 오프라인 분석(영문)](docs/captures.md)에 있습니다. +Windows에서는 일시적인 파일 교체 거부를 짧게 재시도합니다. 로컬 파일 오류가 계속되면 캡처를 사용하는 프로그램을 닫고 권한과 디스크 여유 공간을 확인하세요. 정상적으로 저장된 manifest가 있을 때만 재개하고, 없으면 실패한 디렉터리를 보존한 뒤 새 경로로 캡처합니다. 자세한 절차는 [캡처 복구 안내(영문)](docs/capture-recovery.md)를 참고하세요. + ## 4. Collector 없이 분석 ```sh diff --git a/QUICKSTART.md b/QUICKSTART.md index fd7e011..5581358 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -53,6 +53,8 @@ The capture result reports `storageDateVerification: "unverified"`. Check the su Repeat the same command with `--resume` after interruption or partial completion. Add `--include-text` at capture time only if you intend to store potentially sensitive service names, SQL and error text. See [capture and offline analysis](docs/captures.md). +Windows briefly retries temporary file replacement denial. If a local file error persists, close programs using the capture and check permissions and free disk space. Resume only when a valid committed manifest exists; otherwise preserve the failed directory and choose a new destination. See [capture recovery](docs/capture-recovery.md). + ## 4. Inspect without a Collector ```sh diff --git a/docs/capture-recovery.md b/docs/capture-recovery.md index f5b6eba..963acbf 100644 --- a/docs/capture-recovery.md +++ b/docs/capture-recovery.md @@ -20,6 +20,12 @@ A closed transport can report `IO_ERROR` (exit 10), whereas a refused connection Pages that were already committed are validated before resume. An incomplete page is fetched again, including profiles already read but not committed. Temporary files not referenced by the manifest are not evidence. Repeating resume on a complete capture preserves its data. +## Local file failures on Windows + +Windows can deny an atomic file replacement while another program holds the destination open. The CLI briefly retries access-denied replacements, preserving the committed file and the atomic replacement operation. Persistent denial still returns `IO_ERROR` (exit 10); other filesystem failures are not retried. An access-denied error can also mean insufficient permissions. + +The message distinguishes local file I/O from Collector transport I/O. Close programs using the capture and check its path, permissions and available disk space. If the directory contains a valid committed manifest, rerun the original command with `--resume` after correcting the cause. If the first manifest could not be committed, preserve that directory and start a new capture in an unused directory. Do not promote a `.partial` file to a manifest or remove referenced pages to force recovery. + ## Recovery limits Recovery preserves the records available in the fixed query window and the committed capture. It cannot recover telemetry that an agent or Collector lost during an outage, expired retention, deleted databases, or sampled requests. `executionComplete` does not certify complete upstream traffic; `upstreamCoverage` and `sampling` remain `unknown`. diff --git a/docs/cli-contract.md b/docs/cli-contract.md index 3e6cfbb..dee3e2b 100644 --- a/docs/cli-contract.md +++ b/docs/cli-contract.md @@ -46,6 +46,8 @@ The example message is illustrative. `error.code` is the machine-readable identi A mid-response EOF currently maps to `IO_ERROR` (10), whereas socket exceptions/timeouts map to `CONNECTION_FAILED` (5). Exit 8 therefore needs both the exit status and the envelope: it can carry available data or describe a failure without data. Treat unrecognized nonzero exits as failures rather than guessing a known category. +Local file failures and Collector transport I/O have distinct human-readable messages while retaining `IO_ERROR` (10). Integrity errors retain their specific messages. See [capture recovery](capture-recovery.md) before retrying a failed file write; a `.partial` file is not a committed checkpoint. + ## Streaming commands `xlog search` uses `scouterctl.stream/v1` on its first `start` event: diff --git a/src/main/kotlin/dev/scouterctl/adapters/collector/CollectorOperation.kt b/src/main/kotlin/dev/scouterctl/adapters/collector/CollectorOperation.kt index 36a4fa0..b46248f 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/collector/CollectorOperation.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/collector/CollectorOperation.kt @@ -20,7 +20,7 @@ internal inline fun collectorOperation(block: () -> T): T = try { throw OperationFailure(ErrorCode.CONNECTION_FAILED, "Collector connection failed; check --host, --port and TCP access") } catch (_: IOException) { - throw OperationFailure(ErrorCode.IO_ERROR, "Transport or artifact I/O failed") + throw OperationFailure(ErrorCode.IO_ERROR, "Collector transport I/O failed; retry the query or check the Collector connection") } catch (_: IllegalArgumentException) { throw UnexpectedFailure(ErrorCode.INVALID_ARGUMENT, "Invalid argument or manifest") } catch (_: java.time.DateTimeException) { diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/AtomicReplacement.kt b/src/main/kotlin/dev/scouterctl/adapters/files/AtomicReplacement.kt new file mode 100644 index 0000000..df898bc --- /dev/null +++ b/src/main/kotlin/dev/scouterctl/adapters/files/AtomicReplacement.kt @@ -0,0 +1,25 @@ +package dev.scouterctl.adapters.files + +import java.nio.file.AccessDeniedException +import java.nio.file.Files +import java.nio.file.Path +import java.nio.file.StandardCopyOption.ATOMIC_MOVE +import java.nio.file.StandardCopyOption.REPLACE_EXISTING + +internal fun replaceAtomically(partial: Path, target: Path) { + val attempts = if (System.getProperty("os.name").startsWith("Windows")) 5 else 1 + repeat(attempts) { attempt -> + try { + Files.move(partial, target, ATOMIC_MOVE, REPLACE_EXISTING) + return + } catch (failure: AccessDeniedException) { + if (attempt == attempts - 1) throw failure + try { + Thread.sleep(50) + } catch (_: InterruptedException) { + Thread.currentThread().interrupt() + throw failure + } + } + } +} diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt index 059680b..756b4a8 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt @@ -7,8 +7,6 @@ import dev.scouterctl.application.CaptureRepository import dev.scouterctl.adapters.serialization.* import java.nio.file.Files import java.nio.file.Path -import java.nio.file.StandardCopyOption.ATOMIC_MOVE -import java.nio.file.StandardCopyOption.REPLACE_EXISTING import java.security.MessageDigest class CaptureStore(private val directory: Path) : CaptureRepository { @@ -39,7 +37,7 @@ class CaptureStore(private val directory: Path) : CaptureRepository { private fun atomicWrite(path: Path, content: String) { val partial = path.resolveSibling(path.fileName.toString() + ".partial") Files.writeString(partial, content) - Files.move(partial, path, ATOMIC_MOVE, REPLACE_EXISTING) + replaceAtomically(partial, path) } private fun digest(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256") .digest(bytes).joinToString("") { "%02x".format(it) } diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/ContextStore.kt b/src/main/kotlin/dev/scouterctl/adapters/files/ContextStore.kt index a45a3ba..8096652 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/ContextStore.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/ContextStore.kt @@ -10,8 +10,6 @@ import java.nio.channels.FileChannel import java.nio.file.Files import java.nio.file.NoSuchFileException import java.nio.file.Path -import java.nio.file.StandardCopyOption.ATOMIC_MOVE -import java.nio.file.StandardCopyOption.REPLACE_EXISTING import java.nio.file.StandardOpenOption.CREATE import java.nio.file.StandardOpenOption.WRITE import java.nio.file.attribute.PosixFilePermissions @@ -44,7 +42,7 @@ class ContextStore(private val path: Path) : ContextRepository { val temporary = Files.createTempFile(parent, ".scouterctl-", ".tmp", *attributes) try { Files.writeString(temporary, json.encodeToString(updated.toDto()) + "\n") - Files.move(temporary, path, ATOMIC_MOVE, REPLACE_EXISTING) + replaceAtomically(temporary, path) } finally { Files.deleteIfExists(temporary) } return@fileOperation updated } diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/CounterCaptureStore.kt b/src/main/kotlin/dev/scouterctl/adapters/files/CounterCaptureStore.kt index 304bf8c..3bc1c67 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/CounterCaptureStore.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/CounterCaptureStore.kt @@ -10,8 +10,6 @@ import java.nio.channels.OverlappingFileLockException import java.nio.file.Files import java.nio.file.LinkOption.NOFOLLOW_LINKS import java.nio.file.Path -import java.nio.file.StandardCopyOption.ATOMIC_MOVE -import java.nio.file.StandardCopyOption.REPLACE_EXISTING import java.nio.file.StandardOpenOption.* import java.security.MessageDigest import java.util.Locale @@ -109,7 +107,7 @@ class CounterCaptureStore(private val directory: Path) : CounterCaptureRepositor Files.newOutputStream(partial, CREATE, TRUNCATE_EXISTING, WRITE, NOFOLLOW_LINKS).use { it.write(content.toByteArray(Charsets.UTF_8)) } - Files.move(partial, directory.resolve(name), ATOMIC_MOVE, REPLACE_EXISTING) + replaceAtomically(partial, directory.resolve(name)) } private fun digest(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256").digest(bytes).joinToString("") { "%02x".format(Locale.ROOT, it) } diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt b/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt index 19f32ab..ca14040 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt @@ -8,8 +8,6 @@ import kotlinx.serialization.encodeToString import java.nio.file.Files import java.nio.file.LinkOption.NOFOLLOW_LINKS import java.nio.file.Path -import java.nio.file.StandardCopyOption.ATOMIC_MOVE -import java.nio.file.StandardCopyOption.REPLACE_EXISTING import java.security.MessageDigest class EvidenceStore(private val directory: Path) : EvidenceRepository { @@ -89,7 +87,7 @@ class EvidenceStore(private val directory: Path) : EvidenceRepository { java.nio.file.StandardOpenOption.TRUNCATE_EXISTING, java.nio.file.StandardOpenOption.WRITE).use { it.write(content.toByteArray(Charsets.UTF_8)) } - Files.move(partial, directory.resolve(name), ATOMIC_MOVE, REPLACE_EXISTING) + replaceAtomically(partial, directory.resolve(name)) } private fun digest(bytes: ByteArray): String = MessageDigest.getInstance("SHA-256") diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/FileOperation.kt b/src/main/kotlin/dev/scouterctl/adapters/files/FileOperation.kt index 0040416..914af9f 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/FileOperation.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/FileOperation.kt @@ -9,7 +9,7 @@ internal inline fun fileOperation(block: () -> T): T = try { } catch (error: OperationFailure) { throw error } catch (_: IOException) { - throw OperationFailure(ErrorCode.IO_ERROR, "Transport or artifact I/O failed") + throw OperationFailure(ErrorCode.IO_ERROR, "Local file I/O failed; check the path, permissions and available disk space") } catch (_: IllegalArgumentException) { throw UnexpectedFailure(ErrorCode.INVALID_ARGUMENT, "Invalid argument or manifest") } catch (_: java.time.DateTimeException) { diff --git a/src/test/kotlin/dev/scouterctl/CaptureWriteTest.kt b/src/test/kotlin/dev/scouterctl/CaptureWriteTest.kt new file mode 100644 index 0000000..231809f --- /dev/null +++ b/src/test/kotlin/dev/scouterctl/CaptureWriteTest.kt @@ -0,0 +1,62 @@ +package dev.scouterctl + +import com.sun.nio.file.ExtendedOpenOption.NOSHARE_DELETE +import dev.scouterctl.adapters.files.CaptureStore +import dev.scouterctl.adapters.files.EvidenceStore +import dev.scouterctl.core.ErrorCode +import dev.scouterctl.core.OperationFailure +import io.kotest.assertions.throwables.shouldThrow +import io.kotest.core.spec.style.FunSpec +import io.kotest.engine.spec.tempdir +import io.kotest.matchers.shouldBe +import java.nio.channels.FileChannel +import java.nio.file.Files +import java.nio.file.StandardOpenOption.READ +import java.nio.file.attribute.PosixFilePermissions + +class CaptureWriteTest : FunSpec({ + for (includeProfiles in listOf(false, true)) { + test("denied checkpoint replacement preserves committed bytes and identifies local I/O with include-profiles=$includeProfiles") { + val work = tempdir().toPath() + val directory = work.resolve("capture") + val cli = ContractCli(work) + WireFixture().use { server -> + val args = listOf("capture", "--directory", directory.toString()) + evidenceWindow + + if (includeProfiles) listOf("--include-profiles") else emptyList() + cli.run(server, args).exit shouldBe 0 + } + val manifest = directory.resolve("manifest.json") + val partial = directory.resolve("manifest.json.partial") + val before = Files.readString(manifest) + Files.writeString(partial, "prior partial") + val save: () -> Unit = if (includeProfiles) { + val store = EvidenceStore(directory) + val next = store.load().copy(executionComplete = false) + val write = { store.save(next) } + write + } else { + val store = CaptureStore(directory) + val next = store.load().copy(executionComplete = false) + val write = { store.save(next) } + write + } + val checkFailure = { + val failure = shouldThrow { save() } + failure.code shouldBe ErrorCode.IO_ERROR + failure.message shouldBe "Local file I/O failed; check the path, permissions and available disk space" + Files.readString(manifest) shouldBe before + Files.exists(partial) shouldBe true + } + if (System.getProperty("os.name").startsWith("Windows")) { + FileChannel.open(manifest, READ, NOSHARE_DELETE).use { checkFailure() } + } else { + val permissions = Files.getPosixFilePermissions(directory) + Files.setPosixFilePermissions(directory, PosixFilePermissions.fromString("r-x------")) + try { checkFailure() } finally { Files.setPosixFilePermissions(directory, permissions) } + } + save() + Files.exists(partial) shouldBe false + Files.readString(manifest).contains("\"executionComplete\":false") shouldBe true + } + } +}) diff --git a/src/test/kotlin/dev/scouterctl/ConnectionDiagnostic.kt b/src/test/kotlin/dev/scouterctl/ConnectionDiagnostic.kt index ca60c47..74b872a 100644 --- a/src/test/kotlin/dev/scouterctl/ConnectionDiagnostic.kt +++ b/src/test/kotlin/dev/scouterctl/ConnectionDiagnostic.kt @@ -18,6 +18,7 @@ internal fun connectionDiagnostic(exit: Int?, elapsedMs: Long, output: String, s "Collector timeout; check TCP access and --timeout-ms; upstream cancellation is not guaranteed" -> "socket_timeout" "Collector connection failed; check --host, --port and TCP access" -> "socket_failure" "Transport or artifact I/O failed" -> "transport_or_artifact_io" + "Collector transport I/O failed; retry the query or check the Collector connection" -> "collector_transport_io" else -> "unclassified" } return buildJsonObject { diff --git a/src/test/kotlin/dev/scouterctl/ConnectionDiagnosticTest.kt b/src/test/kotlin/dev/scouterctl/ConnectionDiagnosticTest.kt index ff8e1f7..57b3bd3 100644 --- a/src/test/kotlin/dev/scouterctl/ConnectionDiagnosticTest.kt +++ b/src/test/kotlin/dev/scouterctl/ConnectionDiagnosticTest.kt @@ -36,7 +36,9 @@ class ConnectionDiagnosticTest : FunSpec({ val result = ContractCli(tempdir().toPath()).run(server, profile) result.exit shouldBe 10 val diagnostic = requireNotNull(result.diagnostic) - diagnostic["error"]!!.jsonObject["reason"] shouldBe JsonPrimitive("transport_or_artifact_io") + result.events.single()["error"]!!.jsonObject["message"] shouldBe + JsonPrimitive("Collector transport I/O failed; retry the query or check the Collector connection") + diagnostic["error"]!!.jsonObject["reason"] shouldBe JsonPrimitive("collector_transport_io") diagnostic["fixture"]!!.jsonObject["command"] shouldBe JsonPrimitive("dictionary") diagnostic.toString() shouldNotContain "secret-token" diagnostic.toString() shouldNotContain "private-address" diff --git a/src/test/kotlin/dev/scouterctl/WindowsAtomicReplacementTest.kt b/src/test/kotlin/dev/scouterctl/WindowsAtomicReplacementTest.kt new file mode 100644 index 0000000..7d60283 --- /dev/null +++ b/src/test/kotlin/dev/scouterctl/WindowsAtomicReplacementTest.kt @@ -0,0 +1,40 @@ +package dev.scouterctl + +import com.sun.nio.file.ExtendedOpenOption.NOSHARE_DELETE +import dev.scouterctl.adapters.files.replaceAtomically +import io.kotest.core.spec.style.FunSpec +import io.kotest.engine.spec.tempdir +import io.kotest.matchers.shouldBe +import java.io.IOException +import java.nio.channels.FileChannel +import java.nio.file.Files +import java.nio.file.StandardOpenOption.READ +import java.util.concurrent.CompletableFuture +import java.util.concurrent.Executors +import java.util.concurrent.TimeUnit.MILLISECONDS +import java.util.concurrent.TimeUnit.SECONDS + +class WindowsAtomicReplacementTest : FunSpec({ + if (System.getProperty("os.name").startsWith("Windows")) { + test("replacement succeeds after a temporary Windows handle releases the committed file") { + val work = tempdir().toPath() + val target = Files.writeString(work.resolve("manifest.json"), "committed") + val partial = Files.writeString(work.resolve("manifest.json.partial"), "replacement") + val released = CompletableFuture() + + FileChannel.open(target, READ, NOSHARE_DELETE).use { held -> + Executors.newSingleThreadScheduledExecutor().use { scheduler -> + scheduler.schedule({ + try { held.close(); released.complete(Unit) } + catch (failure: IOException) { released.completeExceptionally(failure) } + }, 100, MILLISECONDS) + replaceAtomically(partial, target) + released.get(5, SECONDS) + } + } + + Files.readString(target) shouldBe "replacement" + Files.exists(partial) shouldBe false + } + } +})