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..2c31595 --- /dev/null +++ b/src/main/kotlin/dev/scouterctl/adapters/files/CaptureDirectory.kt @@ -0,0 +1,50 @@ +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 +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) + } 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/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..035afd4 --- /dev/null +++ b/src/test/kotlin/dev/scouterctl/CapturePathTest.kt @@ -0,0 +1,74 @@ +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." + ) + 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" + ) + } + + 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." + ) + 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." + ) + } + + 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 +}