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; 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 and application orchestration.

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.