57 lines
2.8 KiB
Markdown
57 lines
2.8 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 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.
|