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

5
docs/integrations/distributor/api.md
View File

@@ -30,6 +30,11 @@ at least one source-file mapping, before calling Distributor. It reads the beare
the configured environment variable and redacts that value from errors. Request
construction and timeout handling belong to the [Distributor adapter](../../internal/distributor-adapter.md).
Weatherreporter reads at most 1 MiB from each Distributor response. An
oversized response fails notification with a stable local diagnostic. Normal
Weatherreporter results retain upload and status identity but do not repeat
Distributor response bodies, status reports, or remote error text.
## Idempotency
Distributor scopes idempotency to the token, pipeline ID, and key. Keys must be

8
docs/integrations/distributor/pkg-upload.md
View File

@@ -11,6 +11,9 @@ bearer token, and an HTTP client whose timeout is the configured Distributor
timeout. The endpoint may include a path prefix but never userinfo, a query, or
a fragment. It passes no custom retry options, so the pinned client's defaults
apply: three attempts, 100 ms base delay, and one-second maximum delay.
The adapter bounds every response to 1 MiB before handing it to the pinned
client. A response above that boundary is rejected as a local overflow rather
than decoding or retaining a prefix.
For each notification, Weatherreporter calls `UploadFiles` with:
@@ -39,8 +42,9 @@ adapter translates it to its own conflict error without exposing the token.
The adapter then calls `Status` for the accepted run. A terminal `failed`
status is a notification failure. A status lookup failure or a timeout before a
terminal status remains attached to the otherwise accepted upload as diagnostic
status information. Polling cadence, final failure handling, and redaction are
internal behavior documented in the
status information. Normal diagnostics use local status classifications; they
do not expose remote response text or the status report. Polling cadence, final
failure handling, and redaction are internal behavior documented in the
[Distributor adapter](../../internal/distributor-adapter.md) and
[application orchestration](../../internal/app-orchestration.md).

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

3
docs/operations.md
View File

@@ -78,6 +78,9 @@ files remain at their selected destinations. A batch notification failure also
leaves all successfully published report files in place. Distributor source
files are those operator-owned Markdown outputs; rendered bundle paths and
delivery status appear in the result, not in a local notification receipt.
Remote Distributor response text is not included in command output. Instead,
notification failures use stable local diagnostics while retaining the upload
and status identities needed to investigate delivery with Distributor.
Report counters count report items only. A batch notification failure therefore
returns a failed batch status even when all report counters show success; the
top-level notification result contains the delivery diagnostic.