Module api

Expand description

The daemon’s JSON API, version 1: the request and response types every client deserializes, and the principal a transport authenticates. Plain data only: no I/O, no Docker or GitHub types, no secrets but a Pairing’s one-time link, which its Debug leaves out.

Routes, all under the authenticated principal:

Route	Body
`GET /v1/status`	`Status`
`POST /v1/repositories/{owner}/{name}/pause?PauseQuery`	`Paused`; 409 `Busy` while it runs a job
`POST /v1/repositories/{owner}/{name}/resume`	none, 204
`POST /v1/repositories/pause?PauseQuery`	`Paused`; 409 `Busy` while any runs a job, pausing none
`POST /v1/repositories/resume`	none, 204: every repository resumed
`POST /v1/profiles/{name}/reseed`	none, 202; 409 while it reseeds; `cache.reseeded` when done
`POST /v1/caches/{name}/clean`	none, 204; 409 `Busy` while a runner uses it
`GET /v1/config`	`ConfigFile`
`POST /v1/config/check`	TOML in, `ConfigCheck`
`PUT /v1/config`	TOML in, `ConfigCheck`; 422 `ConfigCheck` when invalid
`GET /v1/doctor`	`Doctor`
`POST /v1/shutdown`	`ShutdownRequest` in, 202
`GET /v1/dashboard`	`Dashboard`
`POST /v1/dashboard/sign-out`	none, 204
`POST /v1/dashboard/pairings?PairingQuery`	`Pairings`; 409 when the dashboard is off or has no `[web] origins`
`GET /v1/jobs?JobQuery`	`JobPage`
`GET /v1/jobs/{id}`	`Job`
`GET /v1/jobs/{id}/samples`	`SampleSeries`
`GET /v1/jobs/{id}/logs?LogQuery`	`text/plain`, one line per log line
`GET /v1/host/samples?HostSampleQuery`	`HostSamples`
`GET /v1/stats?StatsQuery`	`Stats`
`GET /v1/activity?ActivityQuery`	`Activity`
`GET /v1/sizing?SizingQuery`	`Sizing`
`GET /v1/insights?InsightsQuery`	`Insights`
`GET /v1/digest`	`Digest`
`POST /v1/notify/test?NotifyTestQuery`	`NotifyTest`; 404 without `[notify]` targets or with no such one
`GET /v1/caches`	`Caches`
`GET /v1/caches/history?CacheHistoryQuery`	`CacheHistory`
`GET /v1/events?EventQuery`	`text/event-stream` of `EventEnvelope`
`GET /v1/records`	`Records`
`DELETE /v1/records/{job}`	`RemovedRecords`; 409 while a shell is open in it
`DELETE /v1/records?RemoveRecordsQuery`	`RemovedRecords`; records with an open shell stay
`POST /v1/records/{job}/shell?ShellQuery`	`Upgrade:` `SHELL_PROTOCOL`, 101, then the shell’s terminal; 409 when the budget is full

Errors carry an ErrorResponse.

Structs§

Activity: GET /v1/activity: every job runnerd’s runners started or finished in a window, by when that happened rather than when the job was queued, so a job that waited or ran long counts in the window it started or ended in.
ActivityQuery: GET /v1/activity query parameters.
Admission: How a job’s runner was admitted.
AutoPlan: What auto sizing will do: its rules, the changes its next look would make as the history and config are now, and the profiles a recent change holds.
Budget: The memory budget runners and the mirror share, in bytes.
Busy: The body of a 409 refused because runners use what the request would change. Has the message of an ErrorResponse, so a client that reads only that still gets it.
CacheHistory: GET /v1/caches/history: every measurement, oldest first.
CacheHistoryQuery: GET /v1/caches/history query parameters.
CacheSize: One volume’s size at one measurement.
CacheVolume: One cache volume and its size.
Caches: GET /v1/caches: every cache volume of the configured profiles, as last measured. Docker measures volumes slowly, so runnerd measures them at start and whenever no runner runs after jobs ended.
Check: One thing the host needs to run runners. Its Display is the line runnerd doctor prints.
ConfigCheck: POST /v1/config/check and PUT /v1/config: what runnerd check-config prints for a config. PUT refuses an invalid one with 422 and this body, which has an ErrorResponse’s message.
ConfigFile: GET /v1/config: the config the daemon runs with. Parse text with config::Config::parse for its fields.
CpuAdmission: What a runner reserved of the CPU budget. CPU in millicores, times in seconds.
CpuBudget: The CPU budget runners share, in millicores.
Dashboard: GET /v1/dashboard: the dashboard’s [web] settings, as the daemon read them when it started.
Delivery: What one target did with a message.
Digest: GET /v1/digest: the last 24 hours.
Doctor: GET /v1/doctor: what runnerd doctor checks, for the config the daemon runs with.
ErrorResponse: The body of every error response.
EventEnvelope: One event as GET /v1/events sends it: the SSE data field. The SSE event field is event.kind() and the SSE id field is id.
EventQuery: GET /v1/events query parameters. Resume with the Last-Event-ID header.
HostSample: One sample of the whole slice runners run in.
HostSampleQuery: GET /v1/host/samples query parameters.
HostSamples: GET /v1/host/samples: the slice’s use over time, oldest first.
Insight: One thing the history says, about one job or one repository.
Insights: GET /v1/insights: what the history says about the window.
InsightsQuery: GET /v1/insights query parameters.
Job: GET /v1/jobs/{id}: a job with its steps.
JobMetrics: What a job used, over the samples taken while it ran (every few seconds). None until a sample exists.
JobPage: GET /v1/jobs: one page of jobs.
JobQuery: GET /v1/jobs query parameters. Jobs come newest first (by ID, which grows with time).
JobRunner: The runner a job ran on.
JobSizing: The jobs of one name in one workflow of one repository.
JobSummary: A job without its steps: what lists and events carry.
LogQuery: GET /v1/jobs/{id}/logs query parameters. The response is text/plain, one log line per line.
LogSummary: A job’s stored log.
LongWait: A job that waited.
Notification: What a webhook target is posted, as JSON; an ntfy target gets its title, message, priority and link.
NotifyTest: POST /v1/notify/test: what each target did with a test message.
NotifyTestQuery: POST /v1/notify/test query parameters.
Pairing: A link that signs one device in to the dashboard on origin, and nowhere else, within lifetime.
PairingQuery: POST /v1/dashboard/pairings: which of [web] origins to make a link for.
Pairings: POST /v1/dashboard/pairings: fresh one-time links that sign a device in to the dashboard.
PauseQuery: POST /v1/repositories/{owner}/{name}/pause and POST /v1/repositories/pause query parameters.
Paused: POST /v1/repositories/{owner}/{name}/pause and POST /v1/repositories/pause: the repository, or every one, is paused, and stays paused when the daemon restarts.
Peaks: The peaks of a set of jobs, each the highest of its samples.
ProfileSizing: One profile: its limits now, its jobs’ peaks and waits, and the advice.
ProfileStatus: A runner profile and what runs in its slots.
QueuedJob: A queued job runners of this daemon can take, as GitHub listed it at the last poll.
Record: One record: the runner of a failed job as the job left it.
RecordLimits: The limits on records, from [records] in the config.
RecordNote: What the job history keeps about a failed job’s record, after the record is gone too.
Records: GET /v1/records: every record, oldest first, and the limits they are kept within.
RemoveRecordsQuery: DELETE /v1/records query parameters: exactly one of them.
RemovedRecords: DELETE /v1/records…: what was removed.
ReplaceQuery: PUT /v1/config query parameters.
RepositoryStatus: A configured repository and its queue.
RepositoryWaits: A repository’s waits this week against the week before.
Resize: A profile’s new memory, slots and, when auto sizing changed them, cpus.
RunLink: One run of a job, to open in the history or on GitHub.
RunnerFailure: A runner that could not be registered or started (runner.failed).
RunnerStatus: A runner registered for one job, in its container.
RunningJob: A runner of this daemon that holds a slot, and the job it runs, if it took one.
Sample: One sample of a container’s use.
SampleSeries: GET /v1/jobs/{id}/samples: what the job’s container used over time, from its start to its removal. Samples older than history.samples are deleted; the job’s metrics stay.
SeedMemory: A running seed container’s memory cap: its profile’s limit when the reseed started.
ShellMemory: A shell container’s memory cap: its record’s profile’s limit when the shell opened.
ShellQuery: POST /v1/records/{job}/shell query parameters.
ShutdownRequest: POST /v1/shutdown.
Sizing: GET /v1/sizing: what the job history says each configured profile needs.
SizingChange: A profile’s memory and slots as auto sizing changed them in the config file.
SizingHold: A profile auto sizing changes nothing in before until, and lowers nothing in before lower_until.
SizingQuery: GET /v1/sizing query parameters.
SlotStatus: One slot of a profile: room for one job.
Spread: Percentiles of a set of values, by nearest rank: each is one of the values, and with fewer than 100 values p99 is the largest.
Started: A job that started: when, and how long it had waited since it was queued.
Starts: A profile’s jobs by whether their runner was already up when GitHub queued them (ADR 0050).
Stats: GET /v1/stats: finished jobs per repository and time bucket, for trends. Sums, so clients can average.
StatsQuery: GET /v1/stats query parameters.
StatsRow: The finished jobs of one repository in one bucket.
Status: GET /v1/status: what the daemon serves and runs right now.
Step: One step of a job, as GitHub reports it.
Timeline: A job’s phases, in the order they happen. A runner’s container starts before GitHub gives it a job.
WaitSpread: How long some jobs waited.
WeekWaits: The waits of the jobs that started in a week, from queued to started.

Enums§

AdmissionPolicy: [host] admission, as a job’s record and the budget name it.
Advice: What to set a profile’s memory and slots to. memory is the largest sampled peak plus the margin, rounded up to 256M: the cap kills a job that goes over it, so it is sized for the heaviest run, not a percentile.
AutoNote: What auto sizing does about a job near its cap.
Basis: What a runner reserved goes by, in the order measured admission falls back.
Bucket: How GET /v1/stats groups jobs in time.
CacheKind: What a cache volume holds.
CheckStatus: How a Check came out.
Event: Everything that happens, tagged by type.
InsightKind: What an insight is, tagged by kind.
JobPeak: Which of a job’s own peaks Basis::Job goes by.
JobState: Where a job is in its life, as this daemon saw it.
NotifyEvent: What a notification target is sent, and the events [notify] targets choose from.
Principal: Who sent a request, as the transport authenticated it. Handlers get it from one place, so a new transport only has to produce one.
Priority: How urgent a notification is, as ntfy ranks it.
RecordRemoval: Why a record was removed.
Severity: How much an insight matters.
WaitKind: What a Waiting reason waits on, which clients draw it by.
Waiting: Why a queued job has no runner of its own yet. Jobs are served oldest first; each takes the first of these that holds for it.

Constants§

INSIGHT_DAYS: The window GET /v1/insights reads by default, in days.
INSIGHT_DAYS_MAX: The longest window GET /v1/insights reads, in days.
SHELL_PROTOCOL: The Upgrade protocol of POST /v1/records/{job}/shell: after 101 Switching Protocols the connection carries the shell’s terminal, raw bytes both ways.

Functions§

cores: Millicores as a number of CPUs to a tenth, rounded up: 2.5, 32.
cpus: Millicores as 2.5 CPUs or 1 CPU, to a tenth rounded up.
period: A setting’s length in words, as a config’s periods read: 5 minutes, 24 hours, 90 s.

Module api

Module api Copy item path

Structs§

Enums§

Constants§

Functions§

Module api