Skip to main content

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}