139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# Feedapi Runtime Contract
|
|
|
|
`weatherapi` uses feedapi as its generic HTTP runtime and configuration layer.
|
|
This document describes the feedapi behavior that `weatherapi` relies on.
|
|
|
|
## Version
|
|
|
|
`go.mod` depends on:
|
|
|
|
- `gitea.maximumdirect.net/ejr/feedapi v0.1.0`
|
|
|
|
Only feedapi behavior used by `weatherapi` is documented here.
|
|
|
|
## Packages Used
|
|
|
|
Runtime composition imports:
|
|
|
|
- `feedapi/app`
|
|
- `feedapi/config`
|
|
- `feedapi/db`
|
|
|
|
The HTTP adapter imports:
|
|
|
|
- `feedapi/bind`
|
|
- `feedapi/endpoint`
|
|
- `feedapi/errors`
|
|
- `feedapi/render`
|
|
- `feedapi/response`
|
|
|
|
Tests also use:
|
|
|
|
- `feedapi/templates`
|
|
- `feedapi/transport/httpx`
|
|
|
|
## Config Ownership
|
|
|
|
Feedapi owns loading and validating the YAML config used by `weatherapi`.
|
|
`weatherapi` adds one local runtime check: `databases` must contain at least
|
|
one entry.
|
|
|
|
The implemented config areas used by `weatherapi` are:
|
|
|
|
- `server`: HTTP listen/default format/timeouts;
|
|
- `databases`: named database handles opened into a registry;
|
|
- `templates`: base directory for text templates.
|
|
|
|
The canonical config reference is [`docs/config.md`](../config.md).
|
|
|
|
## Database Registry
|
|
|
|
`cmd/weatherapi` calls feedapi `db.OpenAll` with configured databases and passes
|
|
the resulting registry into `feedapi/app.New`. It also selects the first
|
|
configured database name from the registry as the primary weather store.
|
|
|
|
Feedapi owns opening and closing database handles. `weatherapi` owns choosing
|
|
which opened handle is used by the Postgres repository.
|
|
|
|
## Endpoint Registry
|
|
|
|
`weatherapi` builds endpoint definitions with `httpapi.Definitions` and passes
|
|
them to feedapi through `feedapi/app.WithEndpoints`.
|
|
|
|
Feedapi owns:
|
|
|
|
- route adaptation;
|
|
- HTTP method/path matching;
|
|
- invoking endpoint binders;
|
|
- invoking endpoint handlers;
|
|
- rendering handler results.
|
|
|
|
Endpoint definitions remain owned by `internal/adapters/inbound/httpapi`.
|
|
|
|
## Renderers and Templates
|
|
|
|
Each implemented endpoint declares JSON, XML, and text output through feedapi
|
|
render formats. Text endpoints also name a template file.
|
|
|
|
Feedapi owns:
|
|
|
|
- renderer registration;
|
|
- format negotiation;
|
|
- template loading from `templates.base_dir`;
|
|
- applying templates to response envelopes.
|
|
|
|
`weatherapi` owns the template files under `templates/` and presenter output
|
|
shapes consumed by those templates.
|
|
|
|
## Content Negotiation
|
|
|
|
`weatherapi` relies on feedapi's negotiation order:
|
|
|
|
1. `format` query parameter;
|
|
2. `Accept` header;
|
|
3. configured default format.
|
|
|
|
Unsupported formats are exposed as structured API errors. See
|
|
[`docs/api.md`](../api.md) for the public HTTP contract.
|
|
|
|
## Success and Error Envelopes
|
|
|
|
Endpoint handlers return `response.Envelope{Data: ...}` for successful
|
|
responses. Nil data is rendered as `data: null`.
|
|
|
|
Feedapi error handling exposes structured error envelopes with:
|
|
|
|
- `error.code`;
|
|
- `error.message`.
|
|
|
|
`weatherapi` relies on feedapi invalid-parameter and unsupported-format errors
|
|
for request validation and negotiation failures.
|
|
|
|
## Middleware and Shutdown
|
|
|
|
Feedapi owns generic HTTP middleware and server lifecycle. The architecture
|
|
policy records that recovery, request ID, and timing middleware are installed by
|
|
default.
|
|
|
|
`weatherapi` supplies a signal-cancelable context to feedapi startup. Feedapi
|
|
owns graceful HTTP shutdown after that context is canceled.
|
|
|
|
## Upgrade Checklist
|
|
|
|
Before upgrading feedapi:
|
|
|
|
- verify config field names and defaults still match [`docs/config.md`](../config.md);
|
|
- verify database registry behavior still supports first configured database
|
|
selection;
|
|
- verify endpoint definition APIs still support binders, handlers, formats,
|
|
and template names;
|
|
- verify negotiation order remains `format`, then `Accept`, then default;
|
|
- verify success and error envelopes still match [`docs/api.md`](../api.md);
|
|
- run `go test ./...` with private module access configured.
|
|
|
|
## Related Docs
|
|
|
|
- [`docs/internal/runtime.md`](../internal/runtime.md)
|
|
- [`docs/internal/http-adapter.md`](../internal/http-adapter.md)
|
|
- [`docs/api.md`](../api.md)
|