107 lines
3.2 KiB
Markdown
107 lines
3.2 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, and upload error wrapping from app orchestration.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- distributor endpoint URL
|
|
- token environment variable name
|
|
- upload timeout
|
|
- bundle ID
|
|
- idempotency key
|
|
- source Markdown report path
|
|
- bundle-relative Markdown path
|
|
- context for cancellation
|
|
|
|
Outputs:
|
|
|
|
- accepted distributor run ID
|
|
- accepted distributor status
|
|
- 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 bundle ID, idempotency key, and bundle path from:
|
|
|
|
- `bundle_id_template`
|
|
- `idempotency_key_template`
|
|
- `report_path_template`
|
|
|
|
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 exactly one file:
|
|
|
|
- source path: the managed Markdown report path selected by app orchestration
|
|
- bundle path: the rendered bundle-relative report path
|
|
|
|
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.
|
|
|
|
## Failure Behavior
|
|
|
|
The adapter validates required endpoint, token env name, token value, bundle ID,
|
|
idempotency key, source path, bundle path, and upload client inputs before
|
|
uploading.
|
|
|
|
Upload failures include endpoint, bundle ID, idempotency key, source path, and
|
|
bundle path 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.
|