eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Tighten local MVP user documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 04:02:09 +00:00
parent c36217d0df
commit b3044c5b7b
5 changed files with 299 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
docs/operations.md
View File

@@ -1,6 +1,12 @@
# Distributor Operations
## Normal workflow
## Normal Workflow
Validate a source bundle:
```sh
go run ./cmd/distributor validate examples/source-bundle
```
Preview a local publication:
@@ -20,30 +26,54 @@ Run the local HTML publication:
go run ./cmd/distributor run --config examples/local-html.yml
```
## Filesystem layout
## Filesystem Layout
Source bundles are discovered beneath the configured local source root. Destination bundle paths preserve the source bundle path relative to that source root.
Source bundles are discovered beneath the configured local source root. Each bundle is a directory containing `manifest.json`.
The maintained example writes under `workspace/`, which is ignored by Git.
Destination bundle paths preserve the source bundle path relative to the source root. A source bundle at the source root publishes to the destination root. A source bundle under `daily/` publishes under `daily/` at each destination.
## Destination state
The maintained examples write under `workspace/`, which is ignored by Git.
Each published destination bundle contains `.distributor.json`. This state file records the source manifest, copied source outputs, and generated outputs. It is the authoritative marker that a destination path is managed by `distributor`.
## Destination State
Each published destination bundle contains `.distributor.json`. This file is the managed sentinel and destination state record. It stores:
- pipeline and destination identity;
- publication timestamp;
- source manifest used for publication;
- copied source output metadata;
- generated output metadata.
`manifest.json` from the source bundle is not copied as destination state.
## Retry behavior
Do not edit `.distributor.json` by hand during normal operation. If it is missing or invalid while destination files remain, `distributor` treats the destination as unmanaged or conflicted.
If a destination already has matching `.distributor.json`, publication skips it as already published.
## Dry Runs
If destination state is older than the source manifest, publication replaces only managed outputs recorded in `.distributor.json` plus the state file.
`--dry-run` loads and validates config, discovers source bundles, inspects destination state, plans outputs, and prints summary lines. It does not write output files or destination state.
If a write fails during local publication, `distributor` removes outputs written during that failed attempt where possible so a retry does not see an unmanaged destination.
Dry-run output is useful before publishing to confirm actions such as `publish_new`, `replace_older`, `skip_same`, and `skip_destination_newer`.
If one destination fails, later destinations in the same fan-out are still planned and run where they are independent. The command exits non-zero after printing the final status when any destination fails.
## Retry and Replacement Behavior
After a successful publish or replacement, the internal notifier hook runs as a no-op. Skipped destinations do not invoke it.
If a destination has matching `.distributor.json`, publication skips it as already published.
If destination state is older than the source manifest and transfer policy allows replacement, publication deletes only managed outputs recorded in `.distributor.json` plus the state file, then writes the new outputs and state.
If destination state is newer than the source manifest, the default behavior is to skip. If destination state has the same source id and created timestamp but a different digest, publication fails as a conflict.
If a destination path has files but no valid `.distributor.json`, publication fails as unmanaged content. There is no force overwrite option.
## Failure Handling
If one destination fails in a fan-out run, independent later destinations are still planned and executed. The command exits non-zero after printing the final status if any destination failed.
If a write fails during local publication, `distributor` attempts to remove outputs written during that failed attempt so a retry does not see those partial outputs as unmanaged destination content.
After a successful publish or replacement, the internal notifier hook runs. The current default notifier is a no-op. Skipped destinations do not invoke it.
## Caveats
Only local-to-local publication is implemented. SSH, S3, external notification adapters, and force overwrite behavior are not implemented.
Only local-to-local execution is implemented. SSH execution, S3 execution, external notification adapters, and force overwrite behavior are not implemented.
For symptom-oriented fixes, see [troubleshooting](troubleshooting.md). For config details, see [configuration](config.md). For command syntax, see [CLI](cli.md).