# 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)