eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Bound Distributor response diagnostics

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-13 02:55:25 +00:00
parent 0b57d99a97
commit 4b748c2e53
10 changed files with 497 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/internal/distributor-adapter.md
View File

@@ -13,7 +13,9 @@ 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.
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
@@ -43,20 +45,26 @@ persist notification artifacts.
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, 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. A terminal failed
run returns that result and an error. Upload failures return no result. Upstream
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, timeouts and
polling, status translation, conflict handling, and token redaction:
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