Add implementation roadmap for the next feature set
This commit is contained in:
158
docs/roadmap/remote_validate_inspect.md
Normal file
158
docs/roadmap/remote_validate_inspect.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# Roadmap: Remote `validate` and `inspect`
|
||||
|
||||
## Purpose
|
||||
|
||||
Expand `distributor validate` and `distributor inspect` so they can operate on
|
||||
configured pipeline sources, including `local`, `ssh`, and `s3` sources.
|
||||
|
||||
This feature improves operator diagnostics after producer-side manifest
|
||||
creation is available.
|
||||
|
||||
## Current Implementation Grounding
|
||||
|
||||
Current `validate` and `inspect` accept one local path. App-level code opens a
|
||||
local backend with `openLocalPath`, then uses `bundle.Discover`, which walks
|
||||
storage, finds `manifest.json`, and validates bundles.
|
||||
|
||||
`run` already has the app-level backend factory for configured local, SSH, and
|
||||
S3 sources. `run` also loads `secrets.directory` before backend construction so
|
||||
explicit S3 credential environment references can resolve without mutating the
|
||||
process environment.
|
||||
|
||||
This feature should reuse that source backend construction path for configured
|
||||
sources and remain read-only.
|
||||
|
||||
## Goals
|
||||
|
||||
- Preserve the existing local path shortcut:
|
||||
`distributor validate <path>` and `distributor inspect <path>`.
|
||||
- Add config-driven source validation and inspection:
|
||||
`--config <path> --pipeline <id>`.
|
||||
- Support configured `local`, `ssh`, and `s3` sources.
|
||||
- Reuse the same source discovery and validation behavior used by `run`.
|
||||
- Reuse secrets loading and backend credential resolution from `run`.
|
||||
- Avoid opening or inspecting destinations in the first version.
|
||||
- Keep output concise and operator-oriented.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not write to source or destination storage.
|
||||
- Do not inspect destination state in v1.
|
||||
- Do not add new backend types.
|
||||
- Do not change source manifest schema.
|
||||
- Do not add daemon, API, or producer-package dependencies.
|
||||
|
||||
## CLI Mode Rules
|
||||
|
||||
Use two mutually exclusive modes:
|
||||
|
||||
```sh
|
||||
distributor validate <local-path>
|
||||
distributor inspect <local-path>
|
||||
```
|
||||
|
||||
and:
|
||||
|
||||
```sh
|
||||
distributor validate --config config.yml --pipeline weather-daily
|
||||
distributor inspect --config config.yml --pipeline weather-daily
|
||||
```
|
||||
|
||||
Do not allow positional local paths together with `--config` or `--pipeline`.
|
||||
|
||||
Require `--pipeline` in config mode, even when the config has exactly one
|
||||
pipeline. This avoids surprising remote access and keeps the initial behavior
|
||||
explicit.
|
||||
|
||||
Optional narrowing:
|
||||
|
||||
```sh
|
||||
--bundle <source-root-relative-bundle-path>
|
||||
```
|
||||
|
||||
When provided, `--bundle` identifies a source-root-relative bundle directory and
|
||||
the command validates or inspects that bundle rather than discovering all
|
||||
bundles.
|
||||
|
||||
## Behavior
|
||||
|
||||
For config mode:
|
||||
|
||||
1. load config using the same defaulting and validation path as `run`;
|
||||
2. load `secrets.directory`;
|
||||
3. find the requested pipeline id;
|
||||
4. open only the pipeline source backend;
|
||||
5. discover all bundles or validate the requested `--bundle`;
|
||||
6. validate manifest schema, paths, files, per-file digests, and bundle digest;
|
||||
7. return non-zero if any selected bundle fails validation.
|
||||
|
||||
`inspect` should fully validate selected bundles by default, matching current
|
||||
`bundle.Discover` behavior. Output can then report reliable normalized metadata:
|
||||
|
||||
- pipeline id for config mode;
|
||||
- backend type;
|
||||
- source-relative bundle path;
|
||||
- bundle id;
|
||||
- created timestamp;
|
||||
- digest;
|
||||
- file count and total size;
|
||||
- file path, size, and SHA-256.
|
||||
|
||||
## Relationship To Other Roadmaps
|
||||
|
||||
Remote validation works well after `manifest create` and `pkg/bundle` because
|
||||
operators can validate producer output where it actually lands.
|
||||
|
||||
This feature does not depend on HTML index mode, link generation, or latest path
|
||||
destinations. Those features may later make inspection output richer, but v1
|
||||
should stay source-focused.
|
||||
|
||||
Machine-readable output should follow `docs/roadmap/cli_output_policy.md` and
|
||||
use the shared `--format text|json` policy rather than command-specific JSON
|
||||
flags.
|
||||
|
||||
## Testing Expectations
|
||||
|
||||
Suggested coverage:
|
||||
|
||||
- existing local path validation still works;
|
||||
- existing local path inspection still works;
|
||||
- config-mode local source validation works;
|
||||
- fake configured source validation works through the storage abstraction;
|
||||
- `--bundle` validates a specific source-relative bundle when implemented;
|
||||
- missing pipeline id fails clearly;
|
||||
- positional path plus `--config` is rejected;
|
||||
- source backend open failures include pipeline/backend context;
|
||||
- digest mismatch and missing manifest failures are clear;
|
||||
- inspect output includes normalized source metadata.
|
||||
|
||||
Avoid live SSH or S3 tests except existing opt-in integration patterns.
|
||||
|
||||
## Documentation Updates After Implementation
|
||||
|
||||
- Update `docs/cli.md` with both local and config-driven syntax.
|
||||
- Update `docs/operations.md` with remote validation examples.
|
||||
- Update `docs/troubleshooting.md` for common configured-source failures.
|
||||
- Update examples only if useful and environment-gated.
|
||||
|
||||
Keep this roadmap under `docs/roadmap/` until implemented.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Destination-state inspection is not part of v1 remote `validate` or
|
||||
`inspect`. These commands remain source-focused and should not open
|
||||
destinations unexpectedly.
|
||||
- JSON output is deferred to `docs/roadmap/cli_output_policy.md` or to an
|
||||
implementation pass that selects that policy.
|
||||
- `--pipeline` remains required in config mode, even when a config has exactly
|
||||
one pipeline.
|
||||
|
||||
## Future Work
|
||||
|
||||
- Add destination-state inspection behind an explicit flag such as
|
||||
`--with-destinations` if operators need fan-out status diagnostics from
|
||||
`inspect`.
|
||||
- Add JSON output through the CLI-wide `--format text|json` policy in
|
||||
`docs/roadmap/cli_output_policy.md`.
|
||||
- Reconsider optional pipeline selection only if the project later introduces a
|
||||
broader command mode for single-pipeline configs.
|
||||
Reference in New Issue
Block a user