52 lines
2.4 KiB
Markdown
52 lines
2.4 KiB
Markdown
# 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.
|