runnerd_core/api/events.rs
1//! What `GET /v1/events` streams: one enum of everything that happens, wrapped with its ID and time. Durable events
2//! are stored and get an ID, so a client resumes after them with `Last-Event-ID`; live events (samples and log
3//! lines) are only sent to connected clients, and a client that missed them reads the job's samples or log instead.
4
5use serde::{Deserialize, Serialize};
6
7use super::jobs::{HostSample, JobSummary, Sample, Step};
8use super::{
9 Budget, ProfileStatus, Record, RecordRemoval, RepositoryStatus, SizingChange, SlotStatus,
10};
11
12/// One event as `GET /v1/events` sends it: the SSE `data` field. The SSE `event` field is `event.kind()` and the
13/// SSE `id` field is `id`.
14#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
15pub struct EventEnvelope {
16 /// Increases with every durable event; `None` for live events.
17 pub id: Option<u64>,
18 /// When it happened.
19 pub at: u64,
20 /// What happened.
21 #[serde(flatten)]
22 pub event: Event,
23}
24
25/// Everything that happens, tagged by `type`.
26#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
27#[serde(tag = "type")]
28pub enum Event {
29 /// A job that runners of this daemon may run was queued.
30 #[serde(rename = "job.queued")]
31 JobQueued {
32 /// The job.
33 job: JobSummary,
34 },
35 /// A runner of this daemon took the job.
36 #[serde(rename = "job.started")]
37 JobStarted {
38 /// The job.
39 job: JobSummary,
40 },
41 /// A step of a running job started or completed.
42 #[serde(rename = "job.step")]
43 JobStep {
44 /// The job's ID.
45 job: u64,
46 /// The step as it is now.
47 step: Step,
48 },
49 /// The job's record is final: it completed and its runner was removed, it was lost, or it ran elsewhere. One closed
50 /// because GitHub stopped answering for it is taken back if a runner here then takes it (ADR 0109).
51 #[serde(rename = "job.finished")]
52 JobFinished {
53 /// The job.
54 job: JobSummary,
55 },
56 /// A slot's runner started, took a job, or was removed.
57 #[serde(rename = "slot.changed")]
58 SlotChanged {
59 /// The profile.
60 profile: String,
61 /// The slot as it is now.
62 slot: SlotStatus,
63 },
64 /// The daemon started or a reload added the profile, a reload changed its image, CPUs, memory or slots, or it
65 /// started or stopped reseeding. A slot's runner changing is `slot.changed` only; this event carries every slot as it is now, so a
66 /// client can replace the whole profile.
67 #[serde(rename = "profile.changed")]
68 ProfileChanged {
69 /// The profile as it is now.
70 profile: ProfileStatus,
71 },
72 /// A reload removed the profile and its last runner and reseed are gone.
73 #[serde(rename = "profile.removed")]
74 ProfileRemoved {
75 /// Its name.
76 profile: String,
77 },
78 /// The memory caps in use changed.
79 #[serde(rename = "budget.changed")]
80 BudgetChanged {
81 /// The budget as it is now.
82 budget: Budget,
83 },
84 /// A repository was paused or resumed, its queue changed, a reload changed its profile or labels, or a reload
85 /// added it.
86 #[serde(rename = "repository.changed")]
87 RepositoryChanged {
88 /// The repository as it is now.
89 repository: RepositoryStatus,
90 },
91 /// A reload removed the repository from the config.
92 #[serde(rename = "repository.removed")]
93 RepositoryRemoved {
94 /// Its `owner/name`.
95 repository: String,
96 },
97 /// A profile's snapshot check finished.
98 #[serde(rename = "cache.reseeded")]
99 CacheReseeded {
100 /// The profile.
101 profile: String,
102 /// What the seed container printed, such as why it did not reseed.
103 output: String,
104 /// Set when reseeding failed.
105 error: Option<String>,
106 },
107 /// A failed job's runner was kept as a record.
108 #[serde(rename = "record.created")]
109 RecordCreated {
110 /// The record.
111 record: Record,
112 },
113 /// A record was removed.
114 #[serde(rename = "record.deleted")]
115 RecordDeleted {
116 /// The job whose record it was.
117 job: u64,
118 /// Why.
119 removed_by: RecordRemoval,
120 },
121 /// A record's image was found gone from Docker, removed outside runnerd (ADR 0135): the job's `record` mark is now
122 /// `removed`, and its note's `gone_at` says when runnerd found it. When and why it went are not known.
123 #[serde(rename = "record.gone")]
124 RecordGone {
125 /// The job whose record it was.
126 job: u64,
127 },
128 /// A failed job's record was not made (ADR 0135): the job's `record` mark is now `skipped`. Its page says why.
129 #[serde(rename = "record.skipped")]
130 RecordSkipped {
131 /// The job.
132 job: u64,
133 },
134 /// Auto sizing wrote a profile's new `memory` and `slots` into the config, and the daemon runs with them.
135 #[serde(rename = "sizing.changed")]
136 SizingChanged {
137 /// The change.
138 change: SizingChange,
139 },
140 /// A runner could not be registered or started, and its repository gets no runner for a while: once, until one of
141 /// its runners takes a job again.
142 #[serde(rename = "runner.failed")]
143 RunnerFailed {
144 /// What failed.
145 failure: RunnerFailure,
146 },
147 /// Live: a running job's container was sampled.
148 #[serde(rename = "job.sample")]
149 JobSample {
150 /// The job's ID.
151 job: u64,
152 /// The sample.
153 sample: Sample,
154 },
155 /// Live: the slice runners run in was sampled.
156 #[serde(rename = "host.sample")]
157 HostSample {
158 /// The sample.
159 sample: HostSample,
160 },
161 /// Live: what needs attention changed (ADR 0132); read `GET /v1/attention` for it. Sent on every change, also when
162 /// one item replaces another; a client that missed it reads the snapshot when it connects again.
163 #[serde(rename = "attention.changed")]
164 AttentionChanged {
165 /// The daemon process the snapshot is of: `Attention::instance`.
166 instance: String,
167 /// The snapshot's new `revision`.
168 revision: u64,
169 },
170 /// Live: a line of a running job's log was stored. Only sent with `logs=true`.
171 #[serde(rename = "log.line")]
172 LogLine {
173 /// The job's ID.
174 job: u64,
175 /// The line's number in the job's log, 0-based.
176 line: u64,
177 /// The line, without its newline.
178 text: String,
179 },
180}
181
182impl Event {
183 /// The `type` tag, also the SSE event name.
184 pub fn kind(&self) -> &'static str {
185 match self {
186 Event::JobQueued { .. } => "job.queued",
187 Event::JobStarted { .. } => "job.started",
188 Event::JobStep { .. } => "job.step",
189 Event::JobFinished { .. } => "job.finished",
190 Event::SlotChanged { .. } => "slot.changed",
191 Event::ProfileChanged { .. } => "profile.changed",
192 Event::ProfileRemoved { .. } => "profile.removed",
193 Event::BudgetChanged { .. } => "budget.changed",
194 Event::RepositoryChanged { .. } => "repository.changed",
195 Event::RepositoryRemoved { .. } => "repository.removed",
196 Event::CacheReseeded { .. } => "cache.reseeded",
197 Event::RecordCreated { .. } => "record.created",
198 Event::RecordDeleted { .. } => "record.deleted",
199 Event::RecordGone { .. } => "record.gone",
200 Event::RecordSkipped { .. } => "record.skipped",
201 Event::SizingChanged { .. } => "sizing.changed",
202 Event::RunnerFailed { .. } => "runner.failed",
203 Event::JobSample { .. } => "job.sample",
204 Event::HostSample { .. } => "host.sample",
205 Event::AttentionChanged { .. } => "attention.changed",
206 Event::LogLine { .. } => "log.line",
207 }
208 }
209
210 /// Whether it is stored and can be resumed after; live events are not.
211 pub fn is_durable(&self) -> bool {
212 !matches!(
213 self,
214 Event::JobSample { .. }
215 | Event::HostSample { .. }
216 | Event::AttentionChanged { .. }
217 | Event::LogLine { .. }
218 )
219 }
220
221 /// The job it is about, if any.
222 pub fn job(&self) -> Option<u64> {
223 match self {
224 Event::JobQueued { job } | Event::JobStarted { job } | Event::JobFinished { job } => {
225 Some(job.id)
226 }
227 Event::JobStep { job, .. }
228 | Event::JobSample { job, .. }
229 | Event::LogLine { job, .. }
230 | Event::RecordDeleted { job, .. }
231 | Event::RecordGone { job }
232 | Event::RecordSkipped { job } => Some(*job),
233 Event::RecordCreated { record } => Some(record.job),
234 Event::SlotChanged { .. }
235 | Event::ProfileChanged { .. }
236 | Event::ProfileRemoved { .. }
237 | Event::BudgetChanged { .. }
238 | Event::RepositoryChanged { .. }
239 | Event::RepositoryRemoved { .. }
240 | Event::CacheReseeded { .. }
241 | Event::SizingChanged { .. }
242 | Event::RunnerFailed { .. }
243 | Event::HostSample { .. }
244 | Event::AttentionChanged { .. } => None,
245 }
246 }
247}
248
249/// A runner that could not be registered or started (`runner.failed`).
250#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
251pub struct RunnerFailure {
252 /// `owner/name`.
253 pub repository: String,
254 /// The profile it was for.
255 pub profile: String,
256 /// Why, as GitHub or Docker said.
257 pub error: String,
258 /// Seconds before the repository gets another runner.
259 pub held_for: u64,
260}
261
262/// `GET /v1/events` query parameters. Resume with the `Last-Event-ID` header.
263#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
264pub struct EventQuery {
265 /// Only events about this job.
266 pub job: Option<u64>,
267 /// Also send `log.line` events.
268 #[serde(default)]
269 pub logs: bool,
270}
271
272impl EventQuery {
273 /// Whether an event passes the filter.
274 pub fn matches(&self, event: &Event) -> bool {
275 (self.logs || !matches!(event, Event::LogLine { .. }))
276 && self.job.is_none_or(|job| event.job() == Some(job))
277 }
278}