3.3 KiB
Distributor Adapter Internals
internal/adapters/distributor translates a local delivery request into the
Distributor Go client's upload and status calls, then returns a local delivery
result. The external API, authentication, and idempotency contract is owned by
the Distributor API guide and
Distributor bundle guide.
Client construction
Client holds the endpoint, the name of the environment variable containing
the token, an optional timeout, and an injectable upstream-client factory.
New validates its configuration before creating the adapter. For each upload,
the adapter reads the token from the configured environment variable and builds
the upstream client with that endpoint, token, and an HTTP client whose timeout
matches the local positive timeout. Its transport reads at most 1 MiB from any
Distributor response before the pinned client decodes it; an oversized response
is a distinct local failure and does not trigger an extra upload attempt.
The upstream client is an implementation dependency, not a source of application configuration: retry ownership, pipeline selection, path templates, and report rendering are defined by configuration and application orchestration.
Upload translation
Before calling the dependency, Upload validates the endpoint and token
configuration plus the local pipeline ID, bundle ID, idempotency key, and every
file's source and bundle paths. It maps the request as follows:
| Local request | Distributor client value |
|---|---|
| Pipeline ID | Upload pipeline identifier |
| Bundle ID | Bundle identifier |
| Idempotency key | Upload idempotency key |
| File source and bundle paths | Bundle file entries |
| Creation timestamp | Bundle creation time |
The call inherits the caller's context and applies the configured positive timeout. The adapter does not read report files, construct bundle layouts, or persist notification artifacts.
Status and errors
An accepted upload is followed by one status request. When a timeout is
configured, a nonterminal result is polled until succeeded or failed, or
until the context ends. The translated UploadResult contains the run ID,
status, and RunStatus, including pipeline ID and lifecycle timestamps.
Remote response bodies, status reports, and remote error text are not retained
in normal results. HTTP failures retain a local typed status-code and
retryability classification; conflicts retain the local idempotency-conflict
type.
Status lookup or polling errors are preserved in UploadResult.StatusError so
the caller can report an accepted-but-unconfirmed delivery, using a bounded
repository-owned diagnostic rather than remote text. A terminal failed run
returns that result and an error. Upload failures return no result. Upstream
idempotency conflicts become the local IdempotencyConflictError, which adds
endpoint, pipeline, bundle, idempotency, and file-path context while redacting
the token.
Verification
Focused tests cover configuration validation, request mapping, response size boundaries, safe diagnostics, timeouts and polling, status translation, conflict handling, and token redaction. A local HTTP server exercises the production upload and status boundary:
go test ./internal/adapters/distributor