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 /// Auto sizing wrote a profile's new `memory` and `slots` into the config, and the daemon runs with them.
122 #[serde(rename = "sizing.changed")]
123 SizingChanged {
124 /// The change.
125 change: SizingChange,
126 },
127 /// A runner could not be registered or started, and its repository gets no runner for a while: once, until one of
128 /// its runners takes a job again.
129 #[serde(rename = "runner.failed")]
130 RunnerFailed {
131 /// What failed.
132 failure: RunnerFailure,
133 },
134 /// Live: a running job's container was sampled.
135 #[serde(rename = "job.sample")]
136 JobSample {
137 /// The job's ID.
138 job: u64,
139 /// The sample.
140 sample: Sample,
141 },
142 /// Live: the slice runners run in was sampled.
143 #[serde(rename = "host.sample")]
144 HostSample {
145 /// The sample.
146 sample: HostSample,
147 },
148 /// Live: a line of a running job's log was stored. Only sent with `logs=true`.
149 #[serde(rename = "log.line")]
150 LogLine {
151 /// The job's ID.
152 job: u64,
153 /// The line's number in the job's log, 0-based.
154 line: u64,
155 /// The line, without its newline.
156 text: String,
157 },
158}
159
160impl Event {
161 /// The `type` tag, also the SSE event name.
162 pub fn kind(&self) -> &'static str {
163 match self {
164 Event::JobQueued { .. } => "job.queued",
165 Event::JobStarted { .. } => "job.started",
166 Event::JobStep { .. } => "job.step",
167 Event::JobFinished { .. } => "job.finished",
168 Event::SlotChanged { .. } => "slot.changed",
169 Event::ProfileChanged { .. } => "profile.changed",
170 Event::ProfileRemoved { .. } => "profile.removed",
171 Event::BudgetChanged { .. } => "budget.changed",
172 Event::RepositoryChanged { .. } => "repository.changed",
173 Event::RepositoryRemoved { .. } => "repository.removed",
174 Event::CacheReseeded { .. } => "cache.reseeded",
175 Event::RecordCreated { .. } => "record.created",
176 Event::RecordDeleted { .. } => "record.deleted",
177 Event::SizingChanged { .. } => "sizing.changed",
178 Event::RunnerFailed { .. } => "runner.failed",
179 Event::JobSample { .. } => "job.sample",
180 Event::HostSample { .. } => "host.sample",
181 Event::LogLine { .. } => "log.line",
182 }
183 }
184
185 /// Whether it is stored and can be resumed after; live events are not.
186 pub fn is_durable(&self) -> bool {
187 !matches!(
188 self,
189 Event::JobSample { .. } | Event::HostSample { .. } | Event::LogLine { .. }
190 )
191 }
192
193 /// The job it is about, if any.
194 pub fn job(&self) -> Option<u64> {
195 match self {
196 Event::JobQueued { job } | Event::JobStarted { job } | Event::JobFinished { job } => {
197 Some(job.id)
198 }
199 Event::JobStep { job, .. }
200 | Event::JobSample { job, .. }
201 | Event::LogLine { job, .. }
202 | Event::RecordDeleted { job, .. } => Some(*job),
203 Event::RecordCreated { record } => Some(record.job),
204 Event::SlotChanged { .. }
205 | Event::ProfileChanged { .. }
206 | Event::ProfileRemoved { .. }
207 | Event::BudgetChanged { .. }
208 | Event::RepositoryChanged { .. }
209 | Event::RepositoryRemoved { .. }
210 | Event::CacheReseeded { .. }
211 | Event::SizingChanged { .. }
212 | Event::RunnerFailed { .. }
213 | Event::HostSample { .. } => None,
214 }
215 }
216}
217
218/// A runner that could not be registered or started (`runner.failed`).
219#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
220pub struct RunnerFailure {
221 /// `owner/name`.
222 pub repository: String,
223 /// The profile it was for.
224 pub profile: String,
225 /// Why, as GitHub or Docker said.
226 pub error: String,
227 /// Seconds before the repository gets another runner.
228 pub held_for: u64,
229}
230
231/// `GET /v1/events` query parameters. Resume with the `Last-Event-ID` header.
232#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
233pub struct EventQuery {
234 /// Only events about this job.
235 pub job: Option<u64>,
236 /// Also send `log.line` events.
237 #[serde(default)]
238 pub logs: bool,
239}
240
241impl EventQuery {
242 /// Whether an event passes the filter.
243 pub fn matches(&self, event: &Event) -> bool {
244 (self.logs || !matches!(event, Event::LogLine { .. }))
245 && self.job.is_none_or(|job| event.job() == Some(job))
246 }
247}