86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# Distributor Operations
|
|
|
|
## Normal Workflow
|
|
|
|
Validate a source bundle:
|
|
|
|
```sh
|
|
go run ./cmd/distributor validate examples/source-bundle
|
|
```
|
|
|
|
Preview a local publication:
|
|
|
|
```sh
|
|
go run ./cmd/distributor run --config examples/local-publish.yml --dry-run
|
|
```
|
|
|
|
Run the local publication:
|
|
|
|
```sh
|
|
go run ./cmd/distributor run --config examples/local-publish.yml
|
|
```
|
|
|
|
Run the local HTML publication:
|
|
|
|
```sh
|
|
go run ./cmd/distributor run --config examples/local-html.yml
|
|
```
|
|
|
|
Preview local fan-out publication:
|
|
|
|
```sh
|
|
go run ./cmd/distributor run --config examples/fan-out.yml --dry-run
|
|
```
|
|
|
|
## Filesystem Layout
|
|
|
|
Source bundles are discovered beneath the configured local source root. Each bundle is a directory containing `manifest.json`.
|
|
|
|
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.
|
|
|
|
The maintained examples write under `workspace/`, which is ignored by Git.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
## Dry Runs
|
|
|
|
`--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.
|
|
|
|
Dry-run output is useful before publishing to confirm actions such as `publish_new`, `replace_older`, `skip_same`, and `skip_destination_newer`.
|
|
|
|
## Retry and Replacement Behavior
|
|
|
|
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 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).
|