71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
# Distributor HTTP Upload Contract
|
|
|
|
Weatherreporter integrates with the HTTP upload API provided by
|
|
`gitea.maximumdirect.net/eric/distributor v0.5.0`. It submits source bundles to
|
|
a configured pipeline and reads the resulting run status. Configuration fields
|
|
and notification lifecycle are documented in the [configuration reference](../../config.md)
|
|
and [operations guide](../../operations.md).
|
|
|
|
## Upload Admission
|
|
|
|
Weatherreporter uses an absolute HTTP(S) endpoint as a base URL. The client
|
|
posts a gzip-compressed source bundle to:
|
|
|
|
```text
|
|
POST /v1/pipelines/<pipeline_id>/upload
|
|
Authorization: Bearer <token>
|
|
Content-Type: application/gzip
|
|
Idempotency-Key: <key>
|
|
```
|
|
|
|
The authenticated token must be allowed to use the selected upload pipeline.
|
|
A successful response is `202 Accepted` with JSON containing `run_id` and
|
|
`status`. Acceptance means Distributor staged and validated the source bundle;
|
|
it does not mean downstream destinations have published it.
|
|
|
|
The adapter requires a pipeline ID, bundle ID, idempotency key, and at least one
|
|
source-file mapping before calling Distributor. It reads the bearer token from
|
|
the configured environment variable and redacts that value from errors. Request
|
|
construction and timeout handling belong to the [Distributor adapter](../../internal/distributor-adapter.md).
|
|
|
|
## Idempotency
|
|
|
|
Distributor scopes idempotency to the token, pipeline ID, and key. Keys must be
|
|
non-empty ASCII values of at most 128 bytes using letters, digits, `.`, `_`,
|
|
`-`, and `:`. Weatherreporter always supplies a rendered key; it does not rely
|
|
on the client library's generated-key fallback.
|
|
|
|
Reusing a key for the same normalized source manifest returns the original
|
|
accepted run. Reusing it for different content returns `409 Conflict`, which
|
|
the adapter exposes as a Weatherreporter idempotency-conflict error. A distinct
|
|
report or batch run therefore needs a distinct key; reuse a key only when
|
|
retrying that same upload.
|
|
|
|
## Run Status And Retention
|
|
|
|
After acceptance, Weatherreporter reads:
|
|
|
|
```text
|
|
GET /runs/<run_id>
|
|
Authorization: Bearer <token>
|
|
```
|
|
|
|
The status record provides `run_id`, `pipeline_id`, status timestamps, optional
|
|
JSON `report`, and an `error` for failures. Statuses are `accepted`, `queued`,
|
|
`running`, `succeeded`, and `failed`. A terminal `failed` status makes the
|
|
notification fail; the adapter preserves the returned status details for the
|
|
application to record.
|
|
|
|
Run and idempotency records are in-memory. Completed records expire according
|
|
to Distributor's `server.http.retention`, and a Distributor restart removes
|
|
retained status and idempotency state. Status polling decisions are internal
|
|
orchestration behavior; see the
|
|
[Distributor adapter](../../internal/distributor-adapter.md) and
|
|
[application orchestration](../../internal/app-orchestration.md).
|
|
|
|
## Compatibility Reference
|
|
|
|
The upstream canonical HTTP wire contract is
|
|
`docs/integrations/http-upload.md` in the Distributor repository. This page
|
|
documents only the portion exercised by Weatherreporter.
|