100 lines
3.3 KiB
Markdown
100 lines
3.3 KiB
Markdown
# Destination State Contract
|
|
|
|
Audience: operators, integrators, and maintainers who inspect or reason about destination `.distributor.json` files.
|
|
|
|
Each managed destination bundle path contains `.distributor.json`. This file is the destination sentinel and state record used for comparison, skip, replacement, and recovery decisions.
|
|
|
|
## State Schema
|
|
|
|
Current schema version: `1`.
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"distributor_version": "dev",
|
|
"pipeline_id": "reports",
|
|
"destination_id": "archive",
|
|
"published_at": "2026-06-04T12:00:00Z",
|
|
"source": {
|
|
"manifest": {
|
|
"schema_version": 1,
|
|
"id": "reports.example.2026-06-04",
|
|
"digest": "sha256:...",
|
|
"created": "2026-06-04T11:55:00Z",
|
|
"files": [
|
|
{"path": "report.md", "sha256": "sha256:...", "size": 1234}
|
|
]
|
|
}
|
|
},
|
|
"links": {
|
|
"primary_url": "https://reports.example.com/archive/report.html"
|
|
},
|
|
"outputs": [
|
|
{
|
|
"path": "report.html",
|
|
"kind": "generated",
|
|
"source_path": "report.md",
|
|
"transform": "markdown_to_html",
|
|
"url": "https://reports.example.com/archive/report.html",
|
|
"sha256": "sha256:...",
|
|
"size": 2345
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Required fields:
|
|
|
|
- `schema_version`: must be `1`.
|
|
- `pipeline_id`: configured pipeline id that wrote the state.
|
|
- `destination_id`: configured destination id that wrote the state.
|
|
- `published_at`: RFC3339 publication timestamp.
|
|
- `source.manifest`: embedded source bundle manifest.
|
|
- `outputs`: output records array; empty is allowed, but the field is required.
|
|
|
|
Optional fields:
|
|
|
|
- `distributor_version`: application version string when available.
|
|
- `links.primary_url`: absolute HTTP or HTTPS URL selected by destination link policy.
|
|
|
|
## Output Records
|
|
|
|
Each output record has:
|
|
|
|
- `path`: destination-relative output path.
|
|
- `kind`: `source` or `generated`.
|
|
- `source_path`: source manifest path used for the output.
|
|
- `transform`: required for `generated` outputs; omitted for copied source outputs.
|
|
- `url`: optional absolute HTTP or HTTPS URL for the output.
|
|
- `sha256`: lowercase `sha256:<64 hex>` digest of the output bytes.
|
|
- `size`: output byte size, zero or greater.
|
|
|
|
Output paths must be unique and use clean relative slash-separated path rules.
|
|
|
|
## Comparison Semantics
|
|
|
|
`distributor` compares the current source manifest to destination state before writing:
|
|
|
|
- No state and no content: publish new outputs.
|
|
- No state and existing content: treat the destination as unmanaged.
|
|
- Matching embedded source manifest: skip.
|
|
- Same source id with older `created`: replace if policy allows.
|
|
- Same source id with newer `created`: skip by default.
|
|
- Same source id and same `created` with different digest: conflict.
|
|
- Different source id, pipeline id, or destination id: conflict.
|
|
- Invalid state JSON or invalid state fields: conflict.
|
|
|
|
Normal replacement deletes only managed output paths recorded in `outputs` plus `.distributor.json`. Forced replacement deletes the bounded destination bundle path.
|
|
|
|
## Boundaries
|
|
|
|
Destination state is internal managed state written by `distributor`. Operators may inspect it during recovery, but normal workflows should not edit it by hand. Source `manifest.json` is not copied as destination state.
|
|
|
|
## Tests
|
|
|
|
Before changing this contract, inspect and run:
|
|
|
|
```sh
|
|
go test ./internal/state ./internal/publish
|
|
```
|