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

Add integration contract documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-04 12:15:21 +00:00
parent ecc5254e6b
commit a81f686fae
10 changed files with 473 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/operations.md
View File

@@ -2,7 +2,7 @@
Audience: administrators and operators who run `distributor`, publish bundles, operate the HTTP upload service, or recover from failed runs.
This document covers operating workflows, storage layout, safety behavior, and recovery. Command syntax lives in [CLI](cli.md), configuration fields live in [Configuration](config.md), and symptom-specific fixes live in [Troubleshooting](troubleshooting.md).
This document covers operating workflows, storage layout, safety behavior, and recovery. Command syntax lives in [CLI](cli.md), configuration fields live in [Configuration](config.md), symptom-specific fixes live in [Troubleshooting](troubleshooting.md), and external contracts live under [Integrations](integrations/source-bundle.md).
## Normal Workflow
@@ -41,7 +41,7 @@ Remote examples under `examples/ssh-destination.yml` and `examples/s3-destinatio
## Filesystem And Storage Layout
A source bundle is a directory containing `manifest.json` and every file listed in that manifest. Source discovery walks beneath the configured source backend root and finds bundle directories.
A source bundle is a directory containing `manifest.json` and every file listed in that manifest. See [Source Bundle Contract](integrations/source-bundle.md). Source discovery walks beneath the configured source backend root and finds bundle directories.
Each destination has its own backend root:
@@ -56,7 +56,7 @@ Destination path mapping controls where each source bundle is published beneath
Fixed destinations select the newest discovered source bundle by manifest `created` timestamp. If multiple bundles have the same timestamp, the source-root-relative bundle path in ascending order wins.
Published destination bundle paths contain `.distributor.json`. This file is both the managed sentinel and the destination state record. It records the pipeline id, destination id, publication time, source manifest, copied outputs, generated outputs, and optional public URL metadata.
Published destination bundle paths contain `.distributor.json`. See [Destination State Contract](integrations/destination-state.md). This file is both the managed sentinel and the destination state record. It records the pipeline id, destination id, publication time, source manifest, copied outputs, generated outputs, and optional public URL metadata.
`manifest.json` from the source bundle is not copied as destination state.
@@ -114,7 +114,7 @@ Forced replacement deletes the current destination bundle path before writing ou
## HTTP Upload Operation
`distributor serve` runs the HTTP upload API for pipelines whose source backend is `http_upload`. Each bearer token maps to exactly one configured upload pipeline. Token values come from the process environment or `secrets.directory`, not from YAML literal values.
The [HTTP Upload API Contract](integrations/http-upload.md) defines request and response details. `distributor serve` runs the HTTP upload API for pipelines whose source backend is `http_upload`. Each bearer token maps to exactly one configured upload pipeline. Token values come from the process environment or `secrets.directory`, not from YAML literal values.
Start the maintained local example:
@@ -162,7 +162,7 @@ The default bind address is private loopback. Put TLS, public routing, rate limi
### SSH/SFTP
SSH execution uses native SFTP. It does not shell out to `ssh`, `scp`, or `rsync`.
SSH execution uses native SFTP. See [SSH/SFTP Integration](integrations/ssh-sftp.md). It does not shell out to `ssh`, `scp`, or `rsync`.
Configure `ssh_key_file`, an SSH agent, or both. Agent identities are attempted first, followed by the configured key file. YAML password authentication is not supported.
@@ -170,7 +170,7 @@ The default host key policy is `accept-new`. During dry runs, unknown host keys
### S3-Compatible Storage
S3 execution uses the AWS SDK for Go v2. Configure an endpoint, bucket, optional prefix, optional region, optional path-style setting, and optional explicit credential variable names.
S3 execution uses the AWS SDK for Go v2. See [S3-Compatible Storage Integration](integrations/s3.md). Configure an endpoint, bucket, optional prefix, optional region, optional path-style setting, and optional explicit credential variable names.
When explicit S3 credential variable names are configured, both must resolve to non-empty values through the process environment or `secrets.directory`. When omitted, the AWS SDK default credential chain is used as-is.