From 6d9a1157040255addc7d41d864977c0529806ad2 Mon Sep 17 00:00:00 2001 From: oxspan <36991763+oxspan@users.noreply.github.com> Date: Wed, 11 Nov 2026 22:41:17 +0900 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=90=9B=20Explain=20invalid=20capture?= =?UTF-8?q?=20directory=20paths?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/captures.md | 4 +- .../adapters/files/CaptureDirectory.kt | 46 +++++++++++++ .../scouterctl/adapters/files/CaptureStore.kt | 3 +- .../adapters/files/EvidenceStore.kt | 5 +- .../kotlin/dev/scouterctl/CapturePathTest.kt | 67 +++++++++++++++++++ 5 files changed, 119 insertions(+), 6 deletions(-) create mode 100644 src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt create mode 100644 src/test/kotlin/dev/scouterctl/CapturePathTest.kt diff --git a/docs/captures.md b/docs/captures.md index 026761b..cfabe71 100644 --- a/docs/captures.md +++ b/docs/captures.md @@ -29,7 +29,7 @@ scouterctl capture \ Add `--include-text` to `xlog search` to resolve service names and error text without downloading profiles. Error text can contain sensitive values, including bound values or values from existing database rows. -The destination directory must not exist for a new capture. If the export is interrupted or partially completes, add `--resume` to the same capture command. Each query covers one date and one object over `[from,to)`. Set `--timezone` to the Collector's actual time zone. +For a new transaction capture, choose an unused destination under an existing parent directory. An occupied destination or a missing or invalid parent returns `INVALID_ARGUMENT` (exit 2). If the export is interrupted or partially completes, add `--resume` to the same capture command. Each query covers one date and one object over `[from,to)`. Set `--timezone` to the Collector's actual time zone. The example saves profiles in a v3 bundle. Add `--include-text` to the capture command only when you intend to store potentially sensitive service, SQL and error text; the default page size is 25 and the maximum is 100. Resume v3 with the same flags and query. Existing v2 bundles remain readable but cannot be resumed by this version; see [Capture compatibility](capture-compatibility.md). Missing profiles are recorded and retried on resume; connection failures preserve earlier page checkpoints. See [Capture recovery](capture-recovery.md) for interruption handling and the limits of recovery. @@ -45,7 +45,7 @@ scouterctl inspect --directory captures/incident-001 \ --txid 9223372036854775806 ``` -Use `--include-text` when the capture was created with stored text and you want to display it. Requesting text that was not stored returns `2`. Inspect verifies all referenced pages and returns `8` with data for partial captures or unavailable profiles. A missing transaction returns `7`; damaged files return `10`. It supports v2 and v3, with no implicit v1 migration. +Use `--include-text` when the capture was created with stored text and you want to display it. Requesting text that was not stored returns `2`. Inspect verifies all referenced pages and returns `8` with data for partial captures or unavailable profiles. A missing transaction returns `7`. A missing capture directory or a path to a file returns `INVALID_ARGUMENT` (exit 2). Damaged capture files return `10`. It supports v2 and v3, with no implicit v1 migration. To find a transaction ID first, search the same bundle offline: diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt new file mode 100644 index 0000000..0fa794b --- /dev/null +++ b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt @@ -0,0 +1,46 @@ +package dev.scouterctl.adapters.files + +import dev.scouterctl.core.ErrorCode +import dev.scouterctl.core.OperationFailure +import java.nio.file.FileAlreadyExistsException +import java.nio.file.Files +import java.nio.file.NoSuchFileException +import java.nio.file.NotDirectoryException +import java.nio.file.Path +import java.nio.file.attribute.BasicFileAttributes + +private const val MISSING_PARENT = "Capture parent directory does not exist. Create it before starting a capture." + +internal fun createCaptureDirectory(directory: Path): Unit = fileOperation { + directory.toAbsolutePath().parent?.let { parent -> + requireDirectory(parent, MISSING_PARENT, "Capture parent path is not a directory. Choose an existing parent directory.") + } + + try { + Files.createDirectory(directory) + } catch (_: FileAlreadyExistsException) { + throw OperationFailure( + ErrorCode.INVALID_ARGUMENT, + "Capture destination already exists. Choose an unused path, or use --resume for a compatible capture." + ) + } catch (_: NoSuchFileException) { + throw OperationFailure(ErrorCode.INVALID_ARGUMENT, MISSING_PARENT) + } +} + +internal fun requireCaptureDirectory(directory: Path) = requireDirectory( + directory, + "Capture directory does not exist. Specify the path to an existing capture.", + "Capture path is not a directory. Specify the path to an existing capture." +) + +private fun requireDirectory(path: Path, missing: String, invalid: String) { + val attributes = try { + Files.readAttributes(path, BasicFileAttributes::class.java) + } catch (_: NoSuchFileException) { + throw OperationFailure(ErrorCode.INVALID_ARGUMENT, missing) + } catch (_: NotDirectoryException) { + throw OperationFailure(ErrorCode.INVALID_ARGUMENT, invalid) + } + if (!attributes.isDirectory) throw OperationFailure(ErrorCode.INVALID_ARGUMENT, invalid) +} diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt index 2910743..059680b 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureStore.kt @@ -12,8 +12,9 @@ import java.nio.file.StandardCopyOption.REPLACE_EXISTING import java.security.MessageDigest class CaptureStore(private val directory: Path) : CaptureRepository { - override fun create() = fileOperation { Files.createDirectory(directory); Unit } + override fun create() = createCaptureDirectory(directory) override fun load(): CaptureManifest = fileOperation { + requireCaptureDirectory(directory) val content = Files.readString(directory.resolve("manifest.json")) requireCaptureSchema(content, "scouterctl.capture/v1") json.decodeFromString(content).toModel() diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt b/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt index 1b8f0e4..19f32ab 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/EvidenceStore.kt @@ -13,11 +13,10 @@ import java.nio.file.StandardCopyOption.REPLACE_EXISTING import java.security.MessageDigest class EvidenceStore(private val directory: Path) : EvidenceRepository { - override fun create(): Unit = fileOperation { - Files.createDirectory(directory) - } + override fun create() = createCaptureDirectory(directory) override fun load(): EvidenceManifest = fileOperation { + requireCaptureDirectory(directory) val content = read("manifest.json", 8_388_608) requireCaptureSchema(content, "scouterctl.capture/v2", "scouterctl.capture/v3") val manifest = json.decodeFromString(content).toModel() diff --git a/src/test/kotlin/dev/scouterctl/CapturePathTest.kt b/src/test/kotlin/dev/scouterctl/CapturePathTest.kt new file mode 100644 index 0000000..06545b9 --- /dev/null +++ b/src/test/kotlin/dev/scouterctl/CapturePathTest.kt @@ -0,0 +1,67 @@ +package dev.scouterctl + +import io.kotest.core.spec.style.FunSpec +import io.kotest.engine.spec.tempdir +import io.kotest.matchers.shouldBe +import kotlinx.serialization.json.jsonObject +import kotlinx.serialization.json.jsonPrimitive +import java.nio.file.Files + +class CapturePathTest : FunSpec({ + test("inspect distinguishes missing and invalid paths from a damaged bundle") { + val work = tempdir().toPath() + Files.writeString(work.resolve("not-a-directory"), "ordinary file") + Files.createDirectory(work.resolve("empty-capture")) + val cli = ContractCli(work) + val inspect = listOf("inspect", "--txid", "1", "--directory") + + cli.run(inspect + "missing-capture", password = null).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture directory does not exist. Specify the path to an existing capture." + ) + cli.run(inspect + "not-a-directory", password = null).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture path is not a directory. Specify the path to an existing capture." + ) + cli.run(inspect + "empty-capture", password = null).shouldFailWith( + 10, "IO_ERROR", "Capture integrity or record validation failed" + ) + } + + for (includeProfiles in listOf(false, true)) { + test("new capture reports occupied destinations and invalid parents with include-profiles=$includeProfiles") { + val work = tempdir().toPath() + val existing = Files.createDirectory(work.resolve("existing")) + val marker = Files.writeString(existing.resolve("marker"), "existing capture data") + val occupiedFile = Files.writeString(work.resolve("occupied-file"), "existing file") + val cli = ContractCli(work) + val args = listOf("capture") + evidenceWindow + if (includeProfiles) listOf("--include-profiles") else emptyList() + val occupied = "Capture destination already exists. Choose an unused path, or use --resume for a compatible capture." + + WireFixture().use { server -> + cli.run(server, args + listOf("--directory", "existing")).shouldFailWith(2, "INVALID_ARGUMENT", occupied) + cli.run(server, args + listOf("--directory", "occupied-file")).shouldFailWith(2, "INVALID_ARGUMENT", occupied) + cli.run(server, args + listOf("--directory", "missing-parent/capture")).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture parent directory does not exist. Create it before starting a capture." + ) + cli.run(server, args + listOf("--directory", "occupied-file/capture")).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture parent path is not a directory. Choose an existing parent directory." + ) + cli.run(server, args + listOf("--resume", "--directory", "missing-capture")).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture directory does not exist. Specify the path to an existing capture." + ) + } + + Files.list(existing).use { it.toList() } shouldBe listOf(marker) + Files.readString(marker) shouldBe "existing capture data" + Files.readString(occupiedFile) shouldBe "existing file" + Files.notExists(work.resolve("missing-parent")) shouldBe true + Files.notExists(work.resolve("missing-capture")) shouldBe true + } + } +}) + +private fun Outcome.shouldFailWith(expectedExit: Int, code: String, message: String) { + exit shouldBe expectedExit + val error = events.single().getValue("error").jsonObject + error.getValue("code").jsonPrimitive.content shouldBe code + error.getValue("message").jsonPrimitive.content shouldBe message +} From 6992741e63c0c79dad5c69a13acb3509c032971e Mon Sep 17 00:00:00 2001 From: oxspan <36991763+oxspan@users.noreply.github.com> Date: Thu, 12 Nov 2026 02:21:31 +0900 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=90=9B=20Classify=20capture=20paths?= =?UTF-8?q?=20beneath=20regular=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../adapters/files/CaptureDirectory.kt | 4 ++++ .../kotlin/dev/scouterctl/CapturePathTest.kt | 19 +++++++++++++------ 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt index 0fa794b..2c31595 100644 --- a/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt +++ b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt @@ -3,6 +3,7 @@ package dev.scouterctl.adapters.files import dev.scouterctl.core.ErrorCode import dev.scouterctl.core.OperationFailure import java.nio.file.FileAlreadyExistsException +import java.nio.file.FileSystemException import java.nio.file.Files import java.nio.file.NoSuchFileException import java.nio.file.NotDirectoryException @@ -41,6 +42,9 @@ private fun requireDirectory(path: Path, missing: String, invalid: String) { throw OperationFailure(ErrorCode.INVALID_ARGUMENT, missing) } catch (_: NotDirectoryException) { throw OperationFailure(ErrorCode.INVALID_ARGUMENT, invalid) + } catch (error: FileSystemException) { + path.toAbsolutePath().parent?.let { requireDirectory(it, missing, invalid) } + throw error } if (!attributes.isDirectory) throw OperationFailure(ErrorCode.INVALID_ARGUMENT, invalid) } diff --git a/src/test/kotlin/dev/scouterctl/CapturePathTest.kt b/src/test/kotlin/dev/scouterctl/CapturePathTest.kt index 06545b9..035afd4 100644 --- a/src/test/kotlin/dev/scouterctl/CapturePathTest.kt +++ b/src/test/kotlin/dev/scouterctl/CapturePathTest.kt @@ -18,9 +18,11 @@ class CapturePathTest : FunSpec({ cli.run(inspect + "missing-capture", password = null).shouldFailWith( 2, "INVALID_ARGUMENT", "Capture directory does not exist. Specify the path to an existing capture." ) - cli.run(inspect + "not-a-directory", password = null).shouldFailWith( - 2, "INVALID_ARGUMENT", "Capture path is not a directory. Specify the path to an existing capture." - ) + for (path in listOf("not-a-directory", "not-a-directory/child", "not-a-directory/child/grandchild")) { + cli.run(inspect + path, password = null).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture path is not a directory. Specify the path to an existing capture." + ) + } cli.run(inspect + "empty-capture", password = null).shouldFailWith( 10, "IO_ERROR", "Capture integrity or record validation failed" ) @@ -42,9 +44,14 @@ class CapturePathTest : FunSpec({ cli.run(server, args + listOf("--directory", "missing-parent/capture")).shouldFailWith( 2, "INVALID_ARGUMENT", "Capture parent directory does not exist. Create it before starting a capture." ) - cli.run(server, args + listOf("--directory", "occupied-file/capture")).shouldFailWith( - 2, "INVALID_ARGUMENT", "Capture parent path is not a directory. Choose an existing parent directory." - ) + for (parent in listOf("occupied-file", "occupied-file/child", "occupied-file/child/grandchild")) { + cli.run(server, args + listOf("--directory", "$parent/capture")).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture parent path is not a directory. Choose an existing parent directory." + ) + cli.run(server, args + listOf("--resume", "--directory", parent)).shouldFailWith( + 2, "INVALID_ARGUMENT", "Capture path is not a directory. Specify the path to an existing capture." + ) + } cli.run(server, args + listOf("--resume", "--directory", "missing-capture")).shouldFailWith( 2, "INVALID_ARGUMENT", "Capture directory does not exist. Specify the path to an existing capture." )