ejr/weatherapi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Cleanup outlook endpoints and completed roadmap documentation
All checks were successful
ci/woodpecker/push/build-image Pipeline was successful
Details

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-12 09:40:49 -05:00
parent 6316783c3a
commit f4dd701204
11 changed files with 43 additions and 429 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/api.md
View File

@@ -234,7 +234,6 @@ GET /alerts/active?format=text
```http
GET /outlooks/convective
GET /outlooks/convective/active
GET /outlooks/convective/location
```
Returns the latest SPC convective outlook run reconstructed from
@@ -246,9 +245,6 @@ Route behavior:
outlook polygons unless user filters are supplied.
- `/outlooks/convective/active` adds an active-time filter using the server's
current UTC time. Outlooks are active when `validFrom <= now < validTo`.
- `/outlooks/convective/location` adds the same active-time filter and
`containsLocation=true`. It remains as an active local-outlook compatibility
route under the v2 weatherfeeder contract.
When no latest run exists, `data` is null. When a run exists but filters match
no outlooks, `data` remains an object and `outlooks` and `discussions` are
@@ -262,14 +258,10 @@ Query parameters:
| `format`, `units`, `tz` / `TZ` | all outlook routes | shared rules above |
| `day` | all outlook routes | `1`, `2`, or `3` |
| `outlookType` | all outlook routes | `categorical`, `tornado`, `hail`, or `wind` |
| `containsLocation` | `/outlooks/convective`, `/outlooks/convective/active` | boolean |
`outlookType` values are normalized case-insensitively. Weatherfeeder v2
outlooks are already filtered for the configured location, so
`containsLocation` is expected to be true for stored v2 outlooks.
`containsLocation` is rejected on `/outlooks/convective/location` because that
route always applies `containsLocation=true`. `precision` and unknown
parameters are rejected.
outlooks are already filtered for the configured location. `precision`,
`containsLocation`, and unknown parameters are rejected.
Run `data` fields:
@@ -314,7 +306,7 @@ Examples:
```http
GET /outlooks/convective?day=1&outlookType=categorical
GET /outlooks/convective/location?format=text&tz=CDT
GET /outlooks/convective/active?format=text&tz=CDT
```
Example JSON response:
@@ -367,53 +359,8 @@ Example JSON response:
}
```
Example location-filtered JSON response:
```json
{
"data": {
"locationId": "stl",
"asOf": "2026-06-11T18:00:00Z",
"outlooks": [
{
"id": "spc-day1-tor-2pct",
"provider": "spc",
"product": "convective",
"day": 1,
"outlookType": "tornado",
"label": "2%",
"validFrom": "2026-06-11T18:00:00Z",
"validTo": "2026-06-12T12:00:00Z",
"issuedAt": "2026-06-11T17:00:00Z",
"expiresAt": "2026-06-12T12:00:00Z",
"containsLocation": true,
"geometry": {
"type": "Polygon",
"coordinates": [
[
[-90.6, 38.4],
[-90.0, 38.4],
[-90.0, 38.8],
[-90.6, 38.4]
]
]
}
}
],
"discussions": [
{
"day": 1,
"headline": "Tornado risk near the configured location",
"discussion": "SPC tornado outlook discussion text.",
"updatedAt": "2026-06-11T17:30:00Z"
}
]
}
}
```
Text format uses the shared convective outlook template for all three outlook
routes and renders a no-data message when `data` is null.
Text format uses the shared convective outlook template for both outlook routes
and renders a no-data message when `data` is null.
### Forecasts

20
docs/internal/http-adapter.md
View File

@@ -8,7 +8,7 @@ This document describes the internal HTTP adapter under
The HTTP adapter turns feedapi route definitions into calls on the application
service boundary. It owns route registration, query binding, request validation,
forecast day-slice filtering, outlook active/location filter construction,
forecast day-slice filtering, outlook active filter construction,
alert active-time selection, response envelopes, and template names.
## Inputs and Outputs
@@ -36,7 +36,7 @@ The adapter may:
- choose the presenter function for an endpoint;
- filter forecast copies for `/today` and `/tomorrow`;
- pass the current UTC instant to active-alert application filtering;
- construct outlook active/location filters.
- construct outlook active filters.
The adapter must not:
@@ -99,10 +99,8 @@ common query values are lowercased and trimmed before binding where applicable.
available only through binders used by forecast, discussion, weather story, and
outlook routes.
Outlook routes accept `day`, `outlookType`, and, except for
`/outlooks/convective/location`, `containsLocation`. The location route always
adds `containsLocation=true` after binding and rejects an explicit
`containsLocation` query value.
Outlook routes accept `day` and `outlookType`. `containsLocation` is a response
field only and is rejected as a request parameter.
## Timezone Parsing
@@ -144,17 +142,13 @@ Outlook route filters are built at the HTTP boundary and passed to the
application service:
- `/outlooks/convective` uses only user-supplied filters;
- `/outlooks/convective/active` adds `ActiveAt=outlookNow().UTC()`;
- `/outlooks/convective/location` adds the same active timestamp and
`ContainsLocation=true`.
- `/outlooks/convective/active` adds `ActiveAt=outlookNow().UTC()`.
The package variable `outlookNow` exists so endpoint tests can make active and
location filtering deterministic.
The package variable `outlookNow` exists so endpoint tests can make active
filtering deterministic.
The application service returns filtered outlook copies and trims run-level
discussions to days represented by retained outlooks.
`/outlooks/convective/location` is retained for compatibility and active
local-outlook behavior under the weatherfeeder outlook v2 contract.
## Failure Behavior

2
docs/policy/architecture.md
View File

@@ -100,7 +100,7 @@ Outputs are HTTP responses in JSON, XML, or text format. All public endpoint han
`weatherapi` owns no durable weather state. Its runtime state is limited to process memory, loaded configuration, HTTP server state, template registry, renderer registry, and database connection pools. Durable weather data and schema creation are external concerns owned by `weatherfeeder` and Postgres.
The API currently serves latest-resource views: latest observation, current conditions, latest hourly forecast, latest narrative forecast, latest forecast discussion, latest weather story run, latest individual weather story, and latest convective outlook run. Active alert, forecast `today` and `tomorrow`, and convective outlook active/location routes derive filtered copies from the latest stored run.
The API currently serves latest-resource views: latest observation, current conditions, latest hourly forecast, latest narrative forecast, latest forecast discussion, latest weather story run, latest individual weather story, and latest convective outlook run. Active alert, forecast `today` and `tomorrow`, and convective outlook active routes derive filtered copies from the latest stored run.
## Configuration and CLI Boundaries

247
docs/roadmap/implementation.md
View File

@@ -1,247 +0,0 @@
# Active Alert Filtering Cleanup
## Status
Implementation, current-behavior documentation, and automated verification are
complete.
## Verification Record
Completed on 2026-06-12:
- `go test ./internal/app`
- `go test ./internal/adapters/inbound/httpapi`
- `go test ./internal/adapters/inbound/httpapi/presenter`
- `go test ./...`
Deployment smoke checks were not run from this workspace because the local
repository state is not a deployed `weatherapi` instance.
## Summary
Fix `/alerts/active` so it returns alerts that are active at request time, not merely every alert from the latest stored alert snapshot.
The current implementation reads the latest `alert_runs` parent row, loads all child `alerts`, and presents the run unchanged. This can expose expired alerts when the latest persisted weatherfeeder snapshot is stale or when a snapshot contains alerts that later expire before the next successful ingestion cycle.
This cleanup preserves the existing route, response envelope, repository contract, and weatherfeeder table ownership. The change should be implemented as app-layer filtering over the latest stored snapshot, following the same architectural pattern already used by convective outlook active filtering.
## Current Behavior To Correct
- `GET /alerts/active` calls `LatestAlertRun(ctx)`.
- `LatestAlertRun(ctx)` returns the latest stored alert snapshot from Postgres.
- All child alerts for that run are returned unchanged.
- The endpoint does not compare `effective`, `onset`, `expires`, `status`, or `messageType` to the request time.
- Expired alerts can therefore appear under an endpoint named `/alerts/active`.
## Target Behavior
- `GET /alerts/active` returns the latest stored alert run with `alerts` filtered to items active at request time.
- Missing latest alert run still returns `{ "data": null }`.
- A latest run with no currently active alerts returns a non-null run object with `alerts: []`.
- The repository remains a latest-snapshot reader and does not own active-time policy.
- The app service owns alert active filtering policy.
- The HTTP adapter supplies the request-time instant using an injectable clock for tests.
- Presentation remains responsible only for response shape, units no-op behavior, and rendering.
## Active Alert Policy
Use a single app-layer predicate for determining whether an alert is active at an instant `activeAt`.
An alert is active when all of the following are true:
- `messageType` is not `Cancel`, case-insensitive after trimming.
- `effective` is absent or `effective <= activeAt`.
- `expires` is absent or `activeAt < expires`.
Additional policy notes:
- Do not use `onset` as a required active boundary. `onset` can describe hazard onset and may be later than alert effective time; using it as a hard lower bound could hide valid watches, warnings, or advisories that are already in effect from an alerting perspective.
- Do not filter by `status` in the first cleanup unless existing model/test data proves a specific non-active status must be excluded. NWS active feeds commonly use `Actual`; persisted historical snapshots may include other values, but time and cancellation policy are the high-confidence active criteria.
- Treat nil `expires` as active if the other criteria pass. This preserves data when an upstream alert omits an expiration, while still allowing future tightening if real data shows nil expiration should be suppressed.
- Preserve input alert order after filtering.
- Preserve run metadata such as `asOf`, location fields, latitude, and longitude even when all alerts are filtered out.
## Public API Impact
- Route remains `GET /alerts/active`.
- Supported query parameters remain `format` and `units`.
- `precision`, `tz` / `TZ`, and unknown query parameters remain rejected unless a separate roadmap explicitly changes alert query support.
- JSON/XML/text format support remains unchanged.
- Response envelope remains `{ "data": ... }`.
- No Postgres schema or weatherfeeder migration is required.
## Stage 1: App Service Filtering
### Changes
- Keep `app.Repository.LatestAlertRun(ctx)` unchanged.
- Add an app-level alert read use case, either:
- `LatestActiveAlertRun(ctx context.Context, activeAt time.Time) (*model.WeatherAlertRun, error)`, or
- `LatestAlerts(ctx context.Context, filter AlertFilter) (*model.WeatherAlertRun, error)` with `AlertFilter.ActiveAt`.
- Prefer the first option unless another alert route is being added at the same time; it is narrower and clearer for the existing API.
- Implement the new service method by:
- reading `s.repo.LatestAlertRun(ctx)`;
- returning `nil, nil` when no run exists;
- cloning the run before mutation;
- filtering cloned `Alerts` with the active predicate;
- returning the cloned run.
- Add package-local helpers for:
- cloning `WeatherAlertRun`;
- cloning `WeatherAlert` values deeply enough to avoid mutating repository-owned slices;
- copying `References` slices;
- evaluating `isActiveAlert(alert, activeAt)`.
### Clone Requirements
The clone must protect repository-returned data from service mutation:
- allocate a new `Alerts` slice;
- allocate new `References` slices for each alert;
- copy pointer time fields only if the model uses pointer fields for alert timestamps;
- preserve string, boolean, enum, and scalar values exactly.
### Tests
Add app tests covering:
- repository delegation and error propagation;
- `nil, nil` when the repository has no latest alert run;
- expired alerts are removed when `activeAt >= expires`;
- alerts expiring exactly at `activeAt` are inactive;
- alerts effective exactly at `activeAt` are active;
- future-effective alerts are inactive;
- missing `effective` does not make an otherwise valid alert inactive;
- missing `expires` does not make an otherwise valid alert inactive;
- `messageType=Cancel` is excluded case-insensitively;
- alert order is preserved;
- run metadata is preserved when all alerts are filtered out;
- filtering does not mutate the repository-owned run, alerts, references, or timestamp pointers.
### Verification
```sh
go test ./internal/app
```
## Stage 2: HTTP Adapter Wiring
### Changes
- Extend `internal/adapters/inbound/httpapi.Service` with the app service method selected in Stage 1.
- Add adapter-local clock injection near `alerts_endpoint.go`:
```go
var alertNow = time.Now
```
- Update `/alerts/active` handler to call the new active-alert service method with `alertNow().UTC()`.
- Keep `bindQuery` as the binder so public query support remains `format` and `units` only.
- Keep the text template name `alerts_active.txt.tmpl`.
- Do not add timezone support in this cleanup. Alert timestamp presentation currently returns canonical model timestamps; timezone support would be a separate public API expansion.
### Tests
Update HTTP tests covering:
- route registration remains unchanged;
- handler passes `alertNow().UTC()` to the service;
- JSON success response renders filtered service output;
- text output renders zero active alerts as `Alerts: 0` when data is non-null;
- `data: null` still renders no-data behavior;
- `units=us` remains accepted and has no schema effect;
- `precision`, `tz`, `TZ`, and unknown query params still return `400`.
### Verification
```sh
go test ./internal/adapters/inbound/httpapi
```
## Stage 3: Presenter And Template Check
### Changes
- Keep `presenter.AlertsPayload` as a pass-through unless filtering requires defensive copy behavior at presentation time.
- Do not move active filtering into the presenter.
- Review `templates/alerts_active.txt.tmpl` and ensure it behaves correctly when `Data` is non-null and `Alerts` is empty.
- If needed, add an explicit text fixture/assertion rather than changing template wording broadly.
### Tests
Add or update presenter/template-sensitive tests only if current endpoint tests do not prove:
- nil data renders no-data text;
- non-null data with empty alerts renders an active-alert run with `Alerts: 0`;
- expired/canceled alerts do not appear in text output after service filtering.
### Verification
```sh
go test ./internal/adapters/inbound/httpapi ./internal/adapters/inbound/httpapi/presenter
```
## Stage 4: Documentation Updates
### Changes
Update current-behavior docs after implementation is complete:
- `docs/api.md`:
- clarify that `/alerts/active` returns the latest alert run filtered to alerts active at request time;
- document that no current active alerts returns a run with `alerts: []` when a latest run exists;
- keep `data: null` limited to no stored alert run;
- keep supported query params as `format` and `units`.
- `README.md` if endpoint summaries mention active alerts.
- `docs/internal/postgres-repository.md`:
- clarify that `LatestAlertRun` reads the latest stored snapshot and active filtering is performed in the app service.
- `docs/policy/architecture.md` only if its latest-resource wording needs to distinguish latest snapshots from request-time derived active views.
Do not document this unimplemented behavior outside `docs/roadmap/` before the code change lands.
### Tests
No doc-specific tests are required unless existing docs consistency tests cover endpoint summaries.
## Stage 5: Final Verification
Run focused tests:
```sh
go test ./internal/app ./internal/adapters/inbound/httpapi ./internal/adapters/inbound/httpapi/presenter
```
Run the full suite:
```sh
go test ./...
```
Manual smoke checks after deployment:
```sh
curl 'https://weather.api.rakestrawhome.com/alerts/active?format=json'
curl 'https://weather.api.rakestrawhome.com/alerts/active?format=text'
```
Expected behavior when all alerts in the latest stored run are expired:
- JSON returns a non-null `data` object with `alerts: []`.
- Text output shows the run metadata and `Alerts: 0`.
## Guardrails
- Do not change weatherfeeder ingestion behavior in this cleanup.
- Do not alter Postgres tables or SQL filtering unless a later performance issue justifies it.
- Do not make `weatherapi` poll NWS or any upstream provider.
- Do not rename `/alerts/active`.
- Do not add alert history endpoints in this cleanup.
- Do not introduce generic filtering frameworks; use small app-local helpers.
- Do not move route query validation into the app layer.
- Do not move active filtering into presenters or text templates.
## Assumptions
- `weatherfeeder` persists alert snapshots that were active at ingestion time, but `weatherapi` must still enforce request-time active semantics.
- Cancellation messages are operational metadata, not active hazards, and should not be returned by `/alerts/active`.
- Missing `expires` should not suppress an alert unless future real-world data shows this creates stale records.
- Time comparisons should use UTC instants; timezone presentation is not part of this cleanup.