# 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 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](../../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.