# Distributor Upload Client Contract

Weatherreporter uses `gitea.maximumdirect.net/eric/distributor/pkg/upload` at
the pinned module version `v0.5.0`. It constructs one client per notification
attempt and calls `UploadFiles`, followed by `Status` for the accepted run.

## Client And Upload

The adapter constructs the client with the configured endpoint, bearer token,
and an HTTP client whose timeout is the configured Distributor timeout. It
passes no custom retry options, so the pinned client's defaults apply: three
attempts, 100 ms base delay, and one-second maximum delay.

For each notification, Weatherreporter calls `UploadFiles` with:

- the rendered pipeline ID;
- the rendered bundle ID as the source manifest ID;
- the report or batch generation time as `Created`;
- the published-output-to-bundle-path mappings described in the
  [bundle mapping contract](pkg-bundle.md); and
- a rendered idempotency key.

It leaves bundle validation enabled. `UploadFiles` creates the temporary source
bundle and sends it as a gzip-compressed tar archive; Weatherreporter does not
call `UploadBundle` or submit prebuilt bundle roots.

## Retry, Conflict, And Status

The pinned upload client retries only `503 Service Unavailable` and retryable
network failures. It does not retry successful `202` responses or other HTTP
errors. Because every Weatherreporter request supplies an idempotency key, a
retry keeps the same upload identity.

The client decodes the accepted upload result (`run_id`, `status`) and the run
status record. A `409` response is an upstream idempotency conflict; the
adapter translates it to its own conflict error without exposing the token.

The adapter then calls `Status` for the accepted run. A terminal `failed`
status is a notification failure. A status lookup failure or a timeout before a
terminal status remains attached to the otherwise accepted upload as diagnostic
status information. Polling cadence, final failure handling, and redaction are
internal behavior documented in the
[Distributor adapter](../../internal/distributor-adapter.md) and
[application orchestration](../../internal/app-orchestration.md).

## Compatibility Reference

The upstream package workflow is documented in
`docs/consumers/pkg-upload.md` in the Distributor repository. Weatherreporter
uses only the client construction, `UploadFiles`, retry/conflict behavior, and
`Status` operations described here.