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/config.md
View File

@@ -2,7 +2,7 @@
Audience: administrators, operators, and advanced users who write YAML configuration for `distributor`.
This document is the canonical user-facing configuration reference. CLI syntax lives in [CLI](cli.md), operating procedures live in [Operations](operations.md), and symptom-oriented recovery lives in [Troubleshooting](troubleshooting.md).
This document is the canonical user-facing configuration reference. CLI syntax lives in [CLI](cli.md), operating procedures live in [Operations](operations.md), symptom-oriented recovery lives in [Troubleshooting](troubleshooting.md), and external contracts live under [Integrations](integrations/source-bundle.md).
## Config File Loading
@@ -153,7 +153,7 @@ path: /srv/distributor/archive
### SSH/SFTP Backend
SSH backends use native SFTP and can be used as sources and destinations.
SSH backends use native SFTP and can be used as sources and destinations. Adapter protocol behavior is documented in [SSH/SFTP Integration](integrations/ssh-sftp.md).
```yaml
backend: ssh
@@ -185,7 +185,7 @@ Authentication uses SSH agent identities when `SSH_AUTH_SOCK` is available, then
### S3-Compatible Backend
S3 backends can be used as sources and destinations.
S3 backends can be used as sources and destinations. Adapter protocol behavior is documented in [S3-Compatible Storage Integration](integrations/s3.md).
```yaml
backend: s3
@@ -212,7 +212,7 @@ The S3 credential variable names must either both be configured or both be omitt
### HTTP Upload Source Backend
HTTP upload backends are valid only as pipeline sources and are served by `distributor serve`.
HTTP upload backends are valid only as pipeline sources and are served by `distributor serve`. The API contract is documented in [HTTP Upload API Contract](integrations/http-upload.md).
```yaml
backend: http_upload
@@ -235,7 +235,7 @@ validation:
- `validation.on_digest_mismatch`: optional. Default and only accepted value: `fail`.
Source bundle digest mismatches fail validation before destination writes occur.
Source bundle digest mismatches fail validation before destination writes occur. The manifest file-format contract is documented in [Source Bundle Contract](integrations/source-bundle.md).
## Destination Fields
@@ -330,7 +330,7 @@ links:
- `links.base_url`: required when `links` is present. It must be an absolute `http` or `https` URL with a host and no query string or fragment.
- `links.primary`: optional. Accepted values are `auto`, `html`, and `source`; default is `auto` when `links` is present.
`distributor` does not infer public URLs from backend config. Output URLs are built from `links.base_url`, the destination bundle path, and output paths using URL path semantics. `index.html` outputs produce directory-style URLs that omit the filename.
`distributor` does not infer public URLs from backend config. Destination state URL fields are documented in [Destination State Contract](integrations/destination-state.md). Output URLs are built from `links.base_url`, the destination bundle path, and output paths using URL path semantics. `index.html` outputs produce directory-style URLs that omit the filename.
Primary URL policies: