3.1 KiB
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
and operations guide.
Upload Admission
Weatherreporter uses an absolute HTTP(S) endpoint with a host as a base URL. It allows a path prefix but rejects userinfo, query strings, and fragments before local report work begins. The client posts a gzip-compressed source bundle to:
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 nonblank pipeline ID, bundle ID, and idempotency key, plus 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.
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:
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 and
application orchestration.
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.