53 lines
2.1 KiB
Markdown
53 lines
2.1 KiB
Markdown
# Destination State
|
|
|
|
## Purpose
|
|
|
|
`internal/state` parses, validates, writes, and compares `.distributor.json` destination state.
|
|
|
|
## Inputs and outputs
|
|
|
|
Input is JSON destination state plus the current source manifest, pipeline id, destination id, and whether the destination path has unmanaged content. Output is a deterministic comparison outcome and reason.
|
|
|
|
## State behavior
|
|
|
|
`.distributor.json` requires:
|
|
|
|
- `schema_version: 1`
|
|
- `pipeline_id`
|
|
- `destination_id`
|
|
- `published_at`
|
|
- `source.manifest`
|
|
- `outputs`
|
|
|
|
`distributor_version` is optional diagnostic metadata. `published_at` parses as RFC3339 and distributor-written state serializes it as RFC3339 UTC.
|
|
|
|
The embedded `source.manifest` is validated with the same source manifest rules used by `internal/bundle`.
|
|
|
|
## Outputs
|
|
|
|
Each output records `path`, `kind`, `source_path`, `sha256`, and `size`. Supported output kinds are `source` and `generated`. Generated outputs require `transform`.
|
|
|
|
## Comparison
|
|
|
|
Comparison outcomes cover absent destination state, unmanaged destination content, invalid state, pipeline or destination mismatch, same source manifest, older destination source, newer destination source, same-created digest conflict, and different source id conflict.
|
|
|
|
## Failure behavior
|
|
|
|
Invalid JSON, invalid state schema, invalid embedded source manifests, unsafe output paths, unsupported output kinds, missing generated-output transform names, and mismatched pipeline or destination ids produce comparison outcomes that publish planning can turn into fail actions.
|
|
|
|
## Boundaries
|
|
|
|
This package does not publish files, delete files, inspect storage backends, or choose transfer policy actions. Publish planning consumes these comparison outcomes later.
|
|
|
|
## Tests
|
|
|
|
Before changing destination state behavior, inspect tests under `internal/state`.
|
|
|
|
## Invariants
|
|
|
|
- `.distributor.json` is the destination sentinel and state record.
|
|
- Embedded source manifests use the same validation rules as source bundles.
|
|
- Generated outputs always record a transform id.
|
|
- Comparison returns outcomes and reasons; it does not mutate storage.
|
|
- `distributor_version` is diagnostic metadata, not a comparison key.
|