Eric Rakestraw
8041f99782
All checks were successful
ci/woodpecker/push/build-image Pipeline was successful
93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
# Consumer API Guide
|
|
|
|
## Purpose
|
|
|
|
This guide is for developers and LLM coding agents integrating `weatherfeeder`
|
|
from another Go codebase.
|
|
|
|
`weatherfeeder` is primarily a daemon, not an SDK. Its public integration
|
|
surface is intentionally narrow:
|
|
|
|
- `model`: canonical weather payload structs.
|
|
- `standards`: schema strings, event kind strings, and shared WMO constants.
|
|
- JSON event output from stdout and NATS sinks.
|
|
- Postgres tables written by the optional Postgres sink.
|
|
|
|
Packages under `internal/` are implementation details and are not public
|
|
integration surfaces.
|
|
|
|
## Recommended Workflow
|
|
|
|
Consumers should switch on the event `schema` value and decode `payload` into
|
|
the matching `model` type.
|
|
|
|
Minimal example:
|
|
|
|
```go
|
|
package consumer
|
|
|
|
import (
|
|
"encoding/json"
|
|
"fmt"
|
|
|
|
"gitea.maximumdirect.net/ejr/weatherfeeder/model"
|
|
"gitea.maximumdirect.net/ejr/weatherfeeder/standards"
|
|
)
|
|
|
|
type Event struct {
|
|
ID string `json:"id"`
|
|
Kind string `json:"kind"`
|
|
Schema string `json:"schema"`
|
|
Payload json.RawMessage `json:"payload"`
|
|
}
|
|
|
|
func Decode(payload []byte) (any, error) {
|
|
var evt Event
|
|
if err := json.Unmarshal(payload, &evt); err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
switch evt.Schema {
|
|
case standards.SchemaWeatherObservationV1:
|
|
var out model.WeatherObservation
|
|
return &out, json.Unmarshal(evt.Payload, &out)
|
|
case standards.SchemaWeatherForecastV1:
|
|
var out model.WeatherForecastRun
|
|
return &out, json.Unmarshal(evt.Payload, &out)
|
|
case standards.SchemaWeatherForecastDiscussionV1:
|
|
var out model.WeatherForecastDiscussion
|
|
return &out, json.Unmarshal(evt.Payload, &out)
|
|
case standards.SchemaWeatherStoryV1:
|
|
var out model.WeatherStoryRun
|
|
return &out, json.Unmarshal(evt.Payload, &out)
|
|
case standards.SchemaWeatherAlertV1:
|
|
var out model.WeatherAlertRun
|
|
return &out, json.Unmarshal(evt.Payload, &out)
|
|
case standards.SchemaWeatherOutlookV1:
|
|
var out model.WeatherOutlookRun
|
|
return &out, json.Unmarshal(evt.Payload, &out)
|
|
default:
|
|
return nil, fmt.Errorf("unsupported weatherfeeder schema %q", evt.Schema)
|
|
}
|
|
}
|
|
```
|
|
|
|
## Consumer Responsibilities
|
|
|
|
- Treat event IDs as opaque.
|
|
- Treat absent `omitempty` fields as unknown, not zero.
|
|
- Prefer schema constants from `standards` over string literals in Go code.
|
|
- Expect canonical numeric measurements to use metric units.
|
|
- Expect canonical timestamps from normalizers to be UTC unless a field-specific
|
|
contract says otherwise.
|
|
- Handle additive fields within the same schema version.
|
|
- Do not import `internal/...` packages.
|
|
|
|
## Canonical References
|
|
|
|
- Public payload package: [`pkg-model.md`](pkg-model.md).
|
|
- Public constants package: [`pkg-standards.md`](pkg-standards.md).
|
|
- JSON event wire contract: [`../integrations/events.md`](../integrations/events.md).
|
|
- Postgres table contract: [`../integrations/postgres.md`](../integrations/postgres.md).
|
|
- Runtime and adapter architecture: [`../policy/architecture.md`](../policy/architecture.md).
|