124 lines
4.1 KiB
Markdown
124 lines
4.1 KiB
Markdown
# Distributor Adapter Internals
|
|
|
|
This document describes the distributor upload adapter in
|
|
`internal/adapters/distributor`.
|
|
|
|
## Purpose
|
|
|
|
The adapter submits generated weatherreporter Markdown reports to a configured
|
|
distributor HTTP upload endpoint. 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.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- distributor endpoint URL
|
|
- token environment variable name
|
|
- upload timeout
|
|
- pipeline ID
|
|
- bundle ID
|
|
- idempotency key
|
|
- source Markdown report path and bundle-relative path mappings
|
|
- bundle created timestamp
|
|
- context for cancellation
|
|
|
|
Outputs:
|
|
|
|
- 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
|
|
|
|
## Boundaries
|
|
|
|
`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`.
|
|
|
|
The app layer passes weatherreporter-owned request values to the adapter. The
|
|
adapter does not choose report types, render templates, select output copies,
|
|
configure destinations, wait for downstream publication, transform Markdown, or
|
|
persist notification state.
|
|
|
|
Full upstream distributor package and HTTP contract details stay under
|
|
`docs/integrations/distributor/`.
|
|
|
|
## Config Fields Used
|
|
|
|
The adapter is built from `notify.distributor` config:
|
|
|
|
- `endpoint`
|
|
- `token_env`
|
|
- `timeout`
|
|
|
|
The app layer renders pipeline ID, bundle ID, idempotency key, and bundle paths
|
|
from:
|
|
|
|
- `pipeline_id_template`
|
|
- `bundle_id_template`
|
|
- `idempotency_key_template`
|
|
- `report_path_templates`
|
|
|
|
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 path: the managed Markdown report path selected by app orchestration
|
|
- bundle paths: rendered bundle-relative report paths
|
|
- created: the report 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 the managed Markdown report is 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.
|