2.7 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.
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, lifecycle timestamps, report,
and remote error details.
Status lookup or polling errors are preserved in UploadResult.StatusError so
the caller can report an accepted-but-unconfirmed delivery. 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, timeouts and polling, status translation, conflict handling, and token redaction:
go test ./internal/adapters/distributor