From 39595ad0352ac9181477e248f9ef239db34652c4 Mon Sep 17 00:00:00 2001 From: Marcin Czenko Date: Mon, 29 Jun 2026 17:49:45 +0200 Subject: [PATCH] chore: updates AGENTS files in tools --- tools/libstorage-cpp/AGENTS.md | 14 ++++++++++++++ tools/storage-test/AGENTS.md | 7 +++++++ 2 files changed, 21 insertions(+) diff --git a/tools/libstorage-cpp/AGENTS.md b/tools/libstorage-cpp/AGENTS.md index b79230ac..f5818af8 100644 --- a/tools/libstorage-cpp/AGENTS.md +++ b/tools/libstorage-cpp/AGENTS.md @@ -76,7 +76,11 @@ Keep daemon commands low-level: - `stream-sink` - `manifest` - `connect` +- `start` +- `stop` +- `close` - `shutdown` +- `destroy` Do not add scenario commands like `roundtrip`, `many`, or cross-target tests to the daemon unless explicitly requested. Put scenario orchestration in `tools/storage-test/storage-test.sh` so the same scenario can run against REST targets and the libstorage daemon target. @@ -102,6 +106,16 @@ The protocol currently does not support paths or arguments containing spaces. If `storage_lib_ctl` should return nonzero when the daemon responds with `"ok":false`. +Lifecycle IPC commands are daemon-level state controls over the libstorage C API: + +- Initial daemon state is `RUNNING` after startup calls `StorageClient::start()`. +- `stop` works only from `RUNNING`; repeated `stop` reports the node is not started. +- `start` works only from `STOPPED`; it is rejected after `close` because restarting after close is not supported. +- `close` works only from `STOPPED`; calling it while `RUNNING` tells the caller to stop first. +- `shutdown` and `destroy` are aliases; both stop the daemon loop and process exit triggers `StorageClient` destructor cleanup (`stop` if needed, `close` if needed, then `storage_destroy`). +- In `STOPPED`, normal storage commands are rejected with available commands: `start`, `close`, `shutdown`, `destroy`. +- In `CLOSED`, all commands except `shutdown`/`destroy` are rejected with available commands: `shutdown`, `destroy`. + `stream-sink [local]` uses released libstorage download primitives: `storage_download_init` followed by `storage_download_stream` with an empty output path. It discards progress bytes while counting transferred byte lengths and waits for terminal completion. File paths sent over IPC are resolved by the daemon process. Callers that run from a different working directory, such as `tools/storage-test/storage-test.sh`, should send absolute paths. diff --git a/tools/storage-test/AGENTS.md b/tools/storage-test/AGENTS.md index 852628c5..7694631e 100644 --- a/tools/storage-test/AGENTS.md +++ b/tools/storage-test/AGENTS.md @@ -111,6 +111,7 @@ Lib-only target commands: - `spr` - `debug` +- `peers` - `manifest ` - `connect [addr...]` @@ -134,6 +135,12 @@ Important: lib daemon file paths are resolved in the daemon process working dire `--timeout-ms 0` means wait indefinitely in libstorage C++ tooling. +Lib-only utility behavior: + +- `debug` calls daemon `debug` and pretty-prints the returned JSON with `jq .`. +- `peers` calls daemon `debug` and prints `.table.nodes | length`, giving the number of peers known to the node. +- Lifecycle commands (`start`, `stop`, `close`, `shutdown`, `destroy`) intentionally remain out of `storage-test.sh`; use `tools/libstorage-cpp/storage_lib_ctl` directly for lifecycle testing. + ## Test Scenario `storage-test.sh test` currently runs the remote-to-local scenario: