eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Implement warmup and fetch retry in the weatherapi adapter

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-02 11:33:16 -05:00
parent dc11e08e22
commit 27506168f8
4 changed files with 409 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/integrations/weatherapi.md
View File

@@ -18,6 +18,17 @@ fail before any HTTP request when the base URL is empty or not absolute.
The HTTP client uses `weather_api.timeout`.
Before fetching bundle sources, the adapter performs a warmup `GET` to
`/conditions/current` with the same query parameters as the current-conditions
source request. This is a temporary connectivity check for VPN wake-up behavior
until the upstream service provides a dedicated health endpoint. A successful
warmup requires a 2xx response whose body can be read; the adapter does not
decode or validate the response envelope during warmup.
Warmup attempts, warmup delay, source-fetch retry attempts, and source-fetch
retry delay are internal adapter defaults. They are not configuration-file
fields or CLI flags yet. `weather_api.timeout` applies to each HTTP attempt.
## Response Envelope
Every response used by the adapter must be JSON with a top-level `data` field:
@@ -45,6 +56,12 @@ Malformed JSON envelopes, non-2xx statuses, and response read failures include
endpoint context in returned errors. Decode errors include source context when
they fail the fetch; optional malformed sources follow the missing-source policy.
Source-fetch transport failures and retryable HTTP statuses are retried before
the adapter returns an error. Retryable statuses are `408`, `429`, `500`,
`502`, `503`, and `504`. Non-retryable statuses, malformed JSON envelopes,
missing `data`, `data: null` missing-source outcomes, and source decode errors
are not retried.
## Query Parameters
The adapter sends these query parameters:
@@ -116,7 +133,10 @@ bundle/debug artifacts, but prompt-facing SPC module output omits geometry.
## Endpoints Used
The adapter fetches these endpoints once per bundle:
The adapter warms up `/conditions/current` once before bundle fetching begins,
with retries if needed. It then fetches these source endpoints once per bundle,
except when a source request is retried after a transient transport or server
failure:
- `/observations`
- `/conditions/current`

9
docs/troubleshooting.md
View File

@@ -74,7 +74,7 @@ Relevant docs: [CLI reference](cli.md).
Symptom: generation fails with `fetch /...`, an HTTP status, or request context.
Likely cause: the configured Weather API endpoint is unreachable, returned a
non-2xx response, or returned an invalid response envelope.
non-2xx response after retries, or returned an invalid response envelope.
Diagnostic:
@@ -83,8 +83,11 @@ weatherreporter generate daily --config ./config.yml --date 2026-05-29
```
Safe fix: verify `weather_api.base_url`, network access, and the Weather API
service response. The adapter fetches `/observations`, `/conditions/current`,
`/forecast/hourly`, `/forecast/narrative`, `/alerts/active`, and `/discussion`.
service response. The adapter first warms up `/conditions/current`, then fetches
`/observations`, `/conditions/current`, `/forecast/hourly`,
`/forecast/narrative`, `/alerts/active`, `/discussion`,
`/weatherstories/latest`, and `/outlooks/convective`. Transient VPN wake-up
failures and retryable upstream statuses are retried automatically.
Relevant docs: [Configuration reference](config.md).