Module api 

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
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/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.

CpuAdmission

What a runner reserved of the CPU budget. CPU in millicores, times in seconds.

CpuBudget

The CPU budget runners share, in millicores.

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.

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.

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.

SizingChange

A profile’s memory and slots as auto sizing changed them in the config file.

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.

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.

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.

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.