Events and jobs¶

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

Two families with four routes between them: the live event stream, and the envelope a long-running job answers through.

The event stream¶

GET /v1/api/events is a Server-Sent Events stream, and it is intercepted by the serve loop before dispatch - it never reaches the ordinary handler path, because a route that holds its connection open cannot be answered the way a request-response route is.

GET /v1/api/events/journal is the same events addressed by sequence rather than by connection: a caller that dropped its stream reads the ones it missed. One capability covers both, on the argument that a caller allowed to watch this host's events is allowed to read the ones it missed.

Both are per-host. A journal cursor is a position in this host's sequence, so a caller that fails over to another host is reading a different sequence and starts again rather than resuming.

The job envelope¶

A write that cannot be finished inside a request answers with a job id. GET /v1/api/jobs/{id} reports that job's state, and GET /v1/api/jobs/{id}/result returns what it produced once it has one.

The pair is two routes rather than one because the two questions have different answers over time: the state is available immediately and the result is not, and a single route would have to invent a representation for "ask again".

The routes¶

This table is generated out of nerthus.core's daemon/routes.ps1, at the same time as the parameter table and by the same command:

python3 ci/generate-reference-tables.py --check   # what CI runs

Parsed out of daemon/routes.ps1 at main, which declares 249 routes in all.

See also¶

• Admin & lifecycle - the routes that hand back a job id
• Query parameters - what every route declares
• API reference - the closed route table and the middleware chain