weatherreporter/docs/integrations/distributor/pkg-upload.md

# 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 prevalidated HTTP(S) endpoint,
bearer token, and an HTTP client whose timeout is the configured Distributor
timeout. The endpoint may include a path prefix but never userinfo, a query, or
a fragment. It passes no custom retry options, so the pinned client's defaults
apply: three attempts, 100 ms base delay, and one-second maximum delay.
The adapter bounds every response to 1 MiB before handing it to the pinned
client. A response above that boundary is rejected as a local overflow rather
than decoding or retaining a prefix.

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. Normal diagnostics use local status classifications; they
do not expose remote response text or the status report. 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.