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.
BuildCacheCounts: What the shared build cache served one runner and took from it (ADR 0052), counted by the cache itself.
BuildCacheStats: The shared build cache (ADR 0052): its size now, and what it served the jobs of the last 7 days.
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.
HostBudget: What the host’s memory leaves the runners (ADR 0055). New runners fit in the lower of MemoryMax and limit; running ones are never stopped for it.
HostMemory: The host’s memory at one moment, beside the slice’s: what admission fits new runners in besides MemoryMax (ADR 0055). Read every few seconds; not kept in the history.
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.
Pressure: One line of a pressure stall file, in hundredths of a percent: 250 is 2.5% of the time.
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, or plus PAGE_CACHE_ROOM when that is more, 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.
HoldCause: What failed, that holds a repository’s runners back for a while.
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.
PAGE_CACHE_ROOM: What a cap keeps at least over the largest peak, for page cache: 1G. Peaks leave page cache out, and a container whose memory past them leaves the kernel less than about 500M of page cache to reclaim at its cap reclaims badly, which throttles its sockets and slows its downloads (ADR 0055).
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.
percent: Hundredths of a percent as a percentage: 1.5%, 12%.
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