Refresh internal state and adapter documentation
This commit is contained in:
@@ -1,134 +1,63 @@
|
||||
# Distributor Adapter Internals
|
||||
|
||||
This document describes the distributor upload adapter in
|
||||
`internal/adapters/distributor`.
|
||||
`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).
|
||||
|
||||
## Purpose
|
||||
## Client construction
|
||||
|
||||
The adapter submits generated weatherreporter Markdown reports to a configured
|
||||
distributor HTTP upload endpoint. It supports one or more file mappings per
|
||||
upload request. It isolates distributor package types, token-env lookup, upload
|
||||
client construction, source-bundle file mapping, timeout handling, status
|
||||
polling, and upload error wrapping from app orchestration.
|
||||
`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.
|
||||
|
||||
## Inputs And Outputs
|
||||
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).
|
||||
|
||||
Inputs:
|
||||
## Upload translation
|
||||
|
||||
- distributor endpoint URL
|
||||
- token environment variable name
|
||||
- upload timeout
|
||||
- pipeline ID
|
||||
- bundle ID
|
||||
- idempotency key
|
||||
- source Markdown report paths and bundle-relative path mappings
|
||||
- bundle created timestamp
|
||||
- context for cancellation
|
||||
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:
|
||||
|
||||
Outputs:
|
||||
| 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 |
|
||||
|
||||
- accepted distributor run ID
|
||||
- accepted distributor upload status
|
||||
- distributor run status, status polling error, and raw run report JSON when available
|
||||
- weatherreporter-owned idempotency conflict error when applicable
|
||||
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.
|
||||
|
||||
## Boundaries
|
||||
## Status and errors
|
||||
|
||||
`internal/adapters/distributor` is the only weatherreporter package that imports
|
||||
`gitea.maximumdirect.net/eric/distributor/pkg/upload` or
|
||||
`gitea.maximumdirect.net/eric/distributor/pkg/bundle`.
|
||||
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.
|
||||
|
||||
The app layer passes weatherreporter-owned request values to the adapter. The
|
||||
adapter does not choose report types, render templates, select output copies,
|
||||
decide whether an upload represents one report or a batch, configure
|
||||
destinations, wait for downstream publication, transform Markdown, or persist
|
||||
notification state.
|
||||
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.
|
||||
|
||||
Full upstream distributor package and HTTP contract details stay under
|
||||
`docs/integrations/distributor/`.
|
||||
## Verification
|
||||
|
||||
## Config Fields Used
|
||||
Focused tests cover configuration validation, request mapping, timeouts and
|
||||
polling, status translation, conflict handling, and token redaction:
|
||||
|
||||
The adapter is built from `notify.distributor` config:
|
||||
|
||||
- `endpoint`
|
||||
- `token_env`
|
||||
- `timeout`
|
||||
|
||||
The app layer renders single-report pipeline ID, bundle ID, idempotency key,
|
||||
and bundle paths from:
|
||||
|
||||
- `pipeline_id_template`
|
||||
- `bundle_id_template`
|
||||
- `idempotency_key_template`
|
||||
- report-specific path templates
|
||||
|
||||
For batch uploads, the app layer renders pipeline ID, bundle ID, and
|
||||
idempotency key from `notify.distributor.batch.*`, resolves report-specific
|
||||
path templates once per included report, and passes the resulting multi-file
|
||||
request to this adapter.
|
||||
|
||||
Report-specific path resolution happens entirely in the app layer. Explicit
|
||||
`reports.<report>.distributor.path_templates` overrides take precedence over
|
||||
report definition defaults.
|
||||
|
||||
The token value is read from the environment variable named by `token_env`
|
||||
after config loading and `secrets.directory` processing.
|
||||
|
||||
## Upload Behavior
|
||||
|
||||
The adapter calls distributor `UploadFiles` with one or more file mappings:
|
||||
|
||||
- pipeline ID: the rendered distributor workflow selector
|
||||
- source paths: managed Markdown report paths selected by app orchestration
|
||||
- bundle paths: rendered bundle-relative report paths for each source
|
||||
- created: the report or batch generation timestamp
|
||||
|
||||
The adapter creates a distributor upload client with the configured endpoint,
|
||||
bearer token, and timeout-backed HTTP client. It also wraps the upload context
|
||||
with the configured timeout when the timeout is greater than zero.
|
||||
|
||||
After upload acceptance, the adapter polls distributor `Status` for the accepted
|
||||
run ID until the run reaches `succeeded` or `failed`, or until the configured
|
||||
timeout expires. It returns the latest status, error text, and raw report JSON in
|
||||
weatherreporter-owned types so app orchestration can persist them in the
|
||||
notification debug artifact. Status lookup failures or timeout before a terminal
|
||||
state are kept as debug status errors on an otherwise accepted upload. A
|
||||
terminal distributor run status of `failed` is returned as a notification failure
|
||||
with the status report preserved.
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
The adapter validates required endpoint, token env name, token value, pipeline
|
||||
ID, bundle ID, idempotency key, upload files, source paths, bundle paths, and
|
||||
upload client inputs before uploading.
|
||||
|
||||
Upload failures include endpoint, pipeline ID, bundle ID, idempotency key,
|
||||
source paths, and bundle paths context. Token values are redacted from adapter
|
||||
errors.
|
||||
|
||||
Distributor idempotency conflicts are exposed as a weatherreporter-owned
|
||||
`IdempotencyConflictError`, so callers do not depend on upstream distributor
|
||||
types.
|
||||
|
||||
## Tests
|
||||
|
||||
Inspect:
|
||||
|
||||
- `internal/adapters/distributor/client_test.go`
|
||||
- `internal/app/app_test.go`
|
||||
- `internal/cli/root_test.go`
|
||||
|
||||
Adapter tests use a fake upload client factory and do not require a live
|
||||
distributor service.
|
||||
|
||||
## Invariants
|
||||
|
||||
- Distributor package types do not leak outside the adapter.
|
||||
- Only managed Markdown report paths selected by app orchestration are
|
||||
uploaded.
|
||||
- The adapter never scans the workspace.
|
||||
- Token values are not included in errors, CLI output, metadata, docs, or
|
||||
examples.
|
||||
- Destination routing and Markdown-to-HTML transformation belong to
|
||||
distributor, not weatherreporter.
|
||||
```sh
|
||||
go test ./internal/adapters/distributor
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user