weatherreporter/docs/integrations/distributor/api.md

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.

Weatherreporter reads at most 1 MiB from each Distributor response. An oversized response fails notification with a stable local diagnostic. Normal Weatherreporter results retain upload and status identity but do not repeat Distributor response bodies, status reports, or remote error text.

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.