weatherreporter/docs/internal/distributor-adapter.md

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.