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.

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/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/sizing?SizingQuery`	`Sizing`
`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§

Admission: How a job’s runner was admitted.
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.
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.
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.
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.
RepositoryStatus: A configured repository and its queue.
Resize: A profile’s new memory and slots.
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.
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.
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.

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.
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.
JobState: Where a job is in its life, as this daemon saw it.
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.
RecordRemoval: Why a record was removed.

Constants§

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.

Module api

Module api Copy item path

Structs§

Enums§

Constants§

Module api