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.
BudgetParts: The budget as a bar draws it, from Status::budget_parts.
BuildCacheActivity: What the build cache did for one job, from BuildCacheCounts::activity.
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.
CacheLimit: A cache volume against its limit, from CacheVolume::limit_status.
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.
ChartLine: A line across a job’s memory or CPU chart.
ChartLines: The lines across a job’s memory and CPU charts, from Job::chart_lines.
Check: One thing the host needs to run runners. Its Display is the line runnerd doctor prints.
ClosedPart: Room past the bar’s blocks that no runner may start in.
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.
FreePart: What the bar leaves free past every block, less what the host holds back.
Health: Whether CI keeps up now, from Status::health.
HeldPart: Memory the budget holds for something other than a slot.
Holder: A program outside the slice and the memory its processes hold.
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.
JobTitle: A job’s name as every client writes it, in parts for a page that sets the workflow apart.
Limit: One resource’s limit for a job’s container.
Limits: What a job’s container may use, from Job::limits.
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.
Milestone: A moment of a job’s life.
Need: What a set of jobs needs, as the advice sizes for it, from Sizing::need.
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.
Outcome: A job’s or a step’s outcome: its word and what it means.
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.
Phase: A stretch of a job’s life.
PoolStatus: One of a repository’s pools: its runners in one profile.
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.
Reading: A figure and the words that follow it, such as 8G and of 24G reserved in runnerd.slice, for a client that sets the figure apart.
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.
RunComparison: A job’s latest runs and what they say together, from Job::compare.
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.
SampleUsage: What a container used over a stretch of its run, from SampleSeries::usage_between.
SeedMemory: A seed container’s memory cap: its profile’s limit when the reseed started, or, for a requested reseed whose profile drained, the room it holds until it starts.
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.
SlotPart: A slot’s block of the budget.
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.
StatsSummary: Finished jobs summed over a time, every repository of the query together, from Stats::daily.
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.
Toned: Text and what it means, for a client to colour.
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.
ChartLineKind: What a line across a job’s chart stands for.
CheckStatus: How a Check came out.
ClosedKind: What closes room past the bar’s blocks.
Event: Everything that happens, tagged by type.
HeldKind: What holds a part of the budget beside the slots.
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.
LimitSource: Where a job’s limit comes from.
NotifyEvent: What a notification target is sent, and the events [notify] targets choose from.
OutcomeKind: What kind of outcome a job’s or a step’s is, for each client to colour as it colours that meaning.
PhaseKind: The phases of a job, in the order they happen.
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.
ProfilePlan: What auto sizing does next with one profile at a given time, from AutoPlan::profile_plan.
RecordRemoval: Why a record was removed.
RecordState: What became of a failed job’s record, from RecordNote::state.
Severity: How much an insight matters.
SlotState: What a slot is doing, from Status::slot_state.
Tone: What a shown fact means for the reader.
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§

GRANULE: Advice rounds memory up to a multiple of this: 256M.
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).
RECORDS_NEAR_FULL: The share of [records] max_total past which the records are near it, in percent: new ones then remove the oldest to fit.
SAMPLE_INTERVAL: Seconds between two samples of a running job’s container. Clients without a Sizing or SampleSeries that says so, such as a job’s figures in runnerctl, word their sampling caveat from it.
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§

ago: How long ago at was: just now under ten seconds, then as duration writes it, 1h 05m ago.
cores: Millicores as a number of CPUs to a tenth, rounded up: 2.5, 32.
cores_used: Millicores in use as cores, to a hundredth rounded up so use never reads as none: 0.25, 1.5, 12, 0.01.
cpu_time: CPU time given in milliseconds: 4.6s to a tenth under a minute, then as duration writes it.
cpus: Millicores as 2.5 CPUs or 1 CPU, to a tenth rounded up.
duration: Seconds as a stopwatch writes them, its width holding as it counts: 45s, 1m 12s, 2h 05m, 3d 4h.
force_pause_consequence: What forcing a pause does to jobs running jobs: cancels its run on GitHub and removes its runner, or for several, cancels their runs on GitHub and removes their runners.
in_cores: Millicores in use as cores_used writes them, with the unit: 1.5 cores, 1 core.
job_title: workflow / job, or the job’s name alone; for a job whose name the daemon does not know yet, as for one its runner took before the daemon saw it queued, job <id>, or a job without an ID.
need: What a set of jobs whose largest sampled peak is peak needs, with margin percent: the peak plus the margin, or plus PAGE_CACHE_ROOM when that is more, rounded up to GRANULE. The largest, not a percentile: the cap kills a job that goes over it, so a cap below a peak a job reached kills it again.
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.
records_near_full: Whether records taking bytes are near max_total (RECORDS_NEAR_FULL).
reseed_requested: A reseed of profile the daemon accepted: jvm: reseed requested; it runs once the profile's slots are free.
reseeded: A reseed of profile done, as cache.reseeded reports it: jvm: reseeded or jvm: reseed failed: ….
sampled_note: The caveat on a sampled peak, as every client words it: memory peaks are sampled every 2 s; spikes shorter than that do not show.

Module api

Module api Copy item path

Structs§

Enums§

Constants§

Functions§

Module api