64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# 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](../integrations/distributor/api.md) and
|
|
[Distributor bundle guide](../integrations/distributor/pkg-bundle.md).
|
|
|
|
## 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](../config.md) and [application orchestration](app-orchestration.md).
|
|
|
|
## 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 record 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:
|
|
|
|
```sh
|
|
go test ./internal/adapters/distributor
|
|
```
|