72 lines
3.3 KiB
Markdown
72 lines
3.3 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. 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](../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 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:
|
|
|
|
```sh
|
|
go test ./internal/adapters/distributor
|
|
```
|