Skip to main content

runnerd_core/api/jobs/
query.rs

1//! What `GET /v1/jobs` searches, filters and sorts by (ADR 0135). The semantics are here, without the history: the
2//! store implements them in SQL, the demo's fake daemon and the fixtures in memory with [`JobQuery::page`], and a
3//! store test holds the two to the same pages.
4//!
5//! Only the default order, newest first by ID, pages, with `before`: a job's ID never changes. Any other order is one
6//! page of the first `limit` jobs, read in one snapshot, with how many the filters admit: a sort key such as a wait
7//! changes while a job runs, so no continuation of a sorted list could promise to show each job once.
8
9use serde::{Deserialize, Serialize};
10
11use super::{JobList, JobPage, JobQuery, JobSummary};
12use crate::api::{RecordNote, RecordState, Tone};
13
14/// The longest search, `JobQuery::q`, in bytes.
15pub const JOB_SEARCH_MAX: usize = 100;
16
17/// Jobs a page holds unless `limit` says otherwise.
18pub const JOBS_PAGE_DEFAULT: u32 = 50;
19
20/// Jobs a page holds at most.
21pub const JOBS_PAGE_MAX: u32 = 500;
22
23/// The text a page holds at most, in bytes, counted over each job's repository, workflow, name, branch, URL and
24/// labels as the list shows them ([`row_bytes`]): a page ends before the job that would pass it. A job's text is cut
25/// to [`JOB_TEXT_MAX`] and [`JOB_LABELS_MAX`], so even a page's first job is far below it.
26pub const JOBS_PAGE_BYTES: u64 = 1 << 20;
27
28/// The most bytes of a job's repository, workflow, name, branch and URL a list shows, each, to the last whole
29/// character; past them, the text is cut and the job is in `JobList::shortened`.
30pub const JOB_TEXT_MAX: usize = 1024;
31
32/// The most bytes of a job's labels, as stored (a JSON array of strings), a list shows; past them it shows none,
33/// and the job is in `JobList::shortened`.
34pub const JOB_LABELS_MAX: usize = 4096;
35
36/// What a sorted list of jobs is sorted by.
37#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
38#[serde(rename_all = "kebab-case")]
39pub enum JobSort {
40    /// When GitHub queued it, in the order of the jobs' IDs, which GitHub gives as it queues them: the default
41    /// order.
42    Queued,
43    /// How long it waited for a runner, as its page says it ([`JobSummary::waited`]): from queued to started, in
44    /// whole seconds. Unknown until it starts, so a job still queued sorts with the unknown ones.
45    Wait,
46    /// How long it ran ([`JobSummary::ran`]) once its record is final; unknown while it runs.
47    Run,
48    /// Its memory peak once its record is final; unknown while it runs, whose peak still grows.
49    Memory,
50}
51
52impl JobSort {
53    /// `job`'s key: seconds, or bytes for memory; `None` while unknown.
54    pub fn key(self, job: &JobSummary) -> Option<u64> {
55        let timeline = &job.timeline;
56        match self {
57            JobSort::Queued => Some(timeline.queued_at),
58            JobSort::Wait => timeline
59                .started_at
60                .map(|started| started.saturating_sub(timeline.queued_at)),
61            JobSort::Run if job.state.is_final() => {
62                let (started, finished) = (timeline.started_at?, timeline.finished_at?);
63                Some(finished.saturating_sub(started))
64            }
65            JobSort::Memory if job.state.is_final() => job.metrics.memory_peak,
66            JobSort::Run | JobSort::Memory => None,
67        }
68    }
69}
70
71/// Which way a sorted list goes.
72#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
73#[serde(rename_all = "kebab-case")]
74pub enum SortOrder {
75    /// Largest or latest first.
76    #[default]
77    Desc,
78    /// Smallest or earliest first.
79    Asc,
80}
81
82/// `JobQuery::record`: jobs by what became of their record.
83#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
84#[serde(rename_all = "kebab-case")]
85pub enum RecordFilter {
86    /// Every job the history notes a record for: kept, removed or not kept.
87    Any,
88    /// Those whose record is kept.
89    Kept,
90    /// Those whose record was made, then removed.
91    Removed,
92    /// Those whose record was not made.
93    Skipped,
94}
95
96impl RecordFilter {
97    /// Whether a job with `mark` passes.
98    pub fn admits(self, mark: Option<RecordMark>) -> bool {
99        match (self, mark) {
100            (RecordFilter::Any, mark) => mark.is_some(),
101            (RecordFilter::Kept, Some(RecordMark::Kept))
102            | (RecordFilter::Removed, Some(RecordMark::Removed))
103            | (RecordFilter::Skipped, Some(RecordMark::Skipped)) => true,
104            _ => false,
105        }
106    }
107}
108
109/// What became of a failed job's record, as a list marks it (`JobSummary::record_mark`): what the history notes,
110/// which `RecordNote::state` reads in full on the job's page. Docker's images are the inventory (`GET /v1/records`);
111/// a record removed outside runnerd reads removed once runnerd lists the images and finds it gone.
112#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
113#[serde(rename_all = "kebab-case")]
114pub enum RecordMark {
115    /// It is kept: a shell can open in it.
116    Kept,
117    /// It was made, then removed.
118    Removed,
119    /// None was made.
120    Skipped,
121    /// A newer daemon's mark this version does not know.
122    #[serde(other)]
123    Unknown,
124}
125
126impl RecordMark {
127    /// The mark of a record the history notes as `note`, in `RecordNote::state`'s precedence.
128    pub fn of(note: &RecordNote) -> RecordMark {
129        match note.state() {
130            RecordState::Skipped { .. } => RecordMark::Skipped,
131            RecordState::Removed { .. } | RecordState::Gone { .. } => RecordMark::Removed,
132            RecordState::Kept { .. } => RecordMark::Kept,
133        }
134    }
135
136    /// Its words: `record kept`, `record removed` or `no record`; `None` for one this version does not know.
137    pub fn words(self) -> Option<&'static str> {
138        match self {
139            RecordMark::Kept => Some("record kept"),
140            RecordMark::Removed => Some("record removed"),
141            RecordMark::Skipped => Some("no record"),
142            RecordMark::Unknown => None,
143        }
144    }
145
146    /// What it means: a kept record is a fact to act on, the rest are background.
147    pub fn tone(self) -> Tone {
148        match self {
149            RecordMark::Kept => Tone::Neutral,
150            RecordMark::Removed | RecordMark::Skipped | RecordMark::Unknown => Tone::Quiet,
151        }
152    }
153}
154
155impl RecordFilter {
156    /// Every filter, in the order a client offers them.
157    pub const ALL: [RecordFilter; 4] = [
158        RecordFilter::Any,
159        RecordFilter::Kept,
160        RecordFilter::Removed,
161        RecordFilter::Skipped,
162    ];
163
164    /// What a client offers it as: `any record`, then the marks' own words.
165    pub fn words(self) -> &'static str {
166        match self {
167            RecordFilter::Any => "any record",
168            RecordFilter::Kept => "record kept",
169            RecordFilter::Removed => "record removed",
170            RecordFilter::Skipped => "no record",
171        }
172    }
173}
174
175/// An order a list of jobs can be read in: what it is sorted by, and which way.
176#[derive(Debug, Clone, Copy, PartialEq, Eq)]
177pub struct JobOrder {
178    /// What it is sorted by.
179    pub sort: JobSort,
180    /// Which way.
181    pub order: SortOrder,
182}
183
184impl JobOrder {
185    /// The default order, newest first: the one that pages.
186    pub const NEWEST: JobOrder = JobOrder {
187        sort: JobSort::Queued,
188        order: SortOrder::Desc,
189    };
190
191    /// Every order, in the order a client offers them: newest first, then each figure largest first, then the
192    /// reverse of each.
193    pub const ALL: [JobOrder; 8] = [
194        JobOrder::NEWEST,
195        JobOrder::of_sort(JobSort::Wait, SortOrder::Desc),
196        JobOrder::of_sort(JobSort::Run, SortOrder::Desc),
197        JobOrder::of_sort(JobSort::Memory, SortOrder::Desc),
198        JobOrder::of_sort(JobSort::Queued, SortOrder::Asc),
199        JobOrder::of_sort(JobSort::Wait, SortOrder::Asc),
200        JobOrder::of_sort(JobSort::Run, SortOrder::Asc),
201        JobOrder::of_sort(JobSort::Memory, SortOrder::Asc),
202    ];
203
204    const fn of_sort(sort: JobSort, order: SortOrder) -> JobOrder {
205        JobOrder { sort, order }
206    }
207
208    /// The order `query` asks for.
209    pub fn of(query: &JobQuery) -> JobOrder {
210        JobOrder {
211            sort: query.sort.unwrap_or(JobSort::Queued),
212            order: query.order.unwrap_or_default(),
213        }
214    }
215
216    /// Whether it is the default order, which pages.
217    pub fn pages(self) -> bool {
218        self == JobOrder::NEWEST
219    }
220
221    /// Its words: `newest first`, `longest wait first`.
222    pub fn words(self) -> &'static str {
223        match (self.sort, self.order) {
224            (JobSort::Queued, SortOrder::Desc) => "newest first",
225            (JobSort::Queued, SortOrder::Asc) => "oldest first",
226            (JobSort::Wait, SortOrder::Desc) => "longest wait first",
227            (JobSort::Wait, SortOrder::Asc) => "shortest wait first",
228            (JobSort::Run, SortOrder::Desc) => "longest run first",
229            (JobSort::Run, SortOrder::Asc) => "shortest run first",
230            (JobSort::Memory, SortOrder::Desc) => "largest memory peak first",
231            (JobSort::Memory, SortOrder::Asc) => "smallest memory peak first",
232        }
233    }
234
235    /// `query` read in this order: its sort and order set, `None` for the default's, and `before` dropped where it
236    /// does not page.
237    pub fn apply(self, query: &mut JobQuery) {
238        let default = self.pages();
239        query.sort = (!default).then_some(self.sort);
240        query.order = (!default).then_some(self.order);
241        if !default {
242            query.before = None;
243        }
244    }
245}
246
247/// How far back a list of jobs reaches, by when GitHub queued them, as every client offers it.
248#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
249pub enum JobRange {
250    /// The last 24 hours.
251    Day,
252    /// The last 7 days.
253    Week,
254    /// The last 30 days.
255    Month,
256    /// Every job the history keeps.
257    #[default]
258    All,
259}
260
261impl JobRange {
262    /// Every range, shortest first.
263    pub const ALL: [JobRange; 4] = [
264        JobRange::Day,
265        JobRange::Week,
266        JobRange::Month,
267        JobRange::All,
268    ];
269
270    /// Its words: `last 24 hours`, `all kept`.
271    pub fn words(self) -> &'static str {
272        match self {
273            JobRange::Day => "last 24 hours",
274            JobRange::Week => "last 7 days",
275            JobRange::Month => "last 30 days",
276            JobRange::All => "all kept",
277        }
278    }
279
280    /// `JobQuery::since` for it at `now`: none for every job.
281    pub fn since(self, now: u64) -> Option<u64> {
282        let days = match self {
283            JobRange::Day => 1,
284            JobRange::Week => 7,
285            JobRange::Month => 30,
286            JobRange::All => return None,
287        };
288        Some(now.saturating_sub(days * 24 * 3600))
289    }
290
291    /// The timeline of it at `now`: its window, at most the [`super::TIMELINE_WINDOW_MAX`] a timeline shows.
292    pub fn timeline(self, now: u64) -> super::TimelineQuery {
293        let longest = now.saturating_sub(super::TIMELINE_WINDOW_MAX);
294        super::TimelineQuery {
295            since: Some(self.since(now).map_or(longest, |since| since.max(longest))),
296            until: None,
297        }
298    }
299}
300
301impl JobQuery {
302    /// Checks a query before it is read: a search of 1 to [`JOB_SEARCH_MAX`] bytes without control characters,
303    /// `before` only in the default order, and no `cursor`. Returns the reason to refuse it, worded for its user.
304    pub fn check(&self) -> Result<(), String> {
305        if let Some(q) = &self.q {
306            if q.is_empty() || q.len() > JOB_SEARCH_MAX {
307                return Err(format!(
308                    "a search is 1 to {JOB_SEARCH_MAX} bytes; leave q out to list every job"
309                ));
310            }
311            if q.chars().any(char::is_control) {
312                return Err("a search has no control characters".to_owned());
313            }
314        }
315        if self.cursor.is_some() {
316            return Err(
317                "a sorted list is one page, its first jobs; narrow it with a search or the filters"
318                    .to_owned(),
319            );
320        }
321        if self.before.is_some() && !self.pages() {
322            return Err(
323                "before pages the list newest first; a sorted list is one page, which a search or the filters \
324                 narrow"
325                    .to_owned(),
326            );
327        }
328        Ok(())
329    }
330
331    /// Whether it lists in the default order, newest first by ID, the one order that pages, with `before` and
332    /// `next`.
333    pub fn pages(&self) -> bool {
334        self.sort.is_none_or(|sort| sort == JobSort::Queued)
335            && self.order.unwrap_or_default() == SortOrder::Desc
336    }
337
338    /// How many jobs a page holds: `limit`, within 1 and [`JOBS_PAGE_MAX`].
339    pub fn page_size(&self) -> u32 {
340        self.limit
341            .unwrap_or(JOBS_PAGE_DEFAULT)
342            .clamp(1, JOBS_PAGE_MAX)
343    }
344
345    /// Whether `job` passes its filters: not its paging.
346    pub fn admits(&self, job: &JobSummary) -> bool {
347        let equal = |want: &Option<String>, have: Option<&str>| {
348            want.as_deref().is_none_or(|want| have == Some(want))
349        };
350        let queued = job.timeline.queued_at;
351        equal(&self.repository, Some(&job.repository))
352            && self.state.is_none_or(|state| state == job.state)
353            && equal(&self.conclusion, job.conclusion.as_deref())
354            && equal(&self.workflow, job.workflow.as_deref())
355            && equal(&self.name, Some(&job.name))
356            && equal(&self.branch, job.branch.as_deref())
357            && self.since.is_none_or(|since| queued >= since)
358            && self.until.is_none_or(|until| queued < until)
359            && self
360                .record
361                .is_none_or(|record| record.admits(job.record_mark))
362            && self.q.as_deref().is_none_or(|q| {
363                let q = q.to_ascii_lowercase();
364                [
365                    Some(job.name.as_str()),
366                    job.workflow.as_deref(),
367                    job.branch.as_deref(),
368                ]
369                .into_iter()
370                .flatten()
371                .any(|text| text.to_ascii_lowercase().contains(&q))
372            })
373    }
374
375    /// Puts `jobs` in its order: by ID for `queued`, else by its key, unknown last, ties by ID.
376    fn order(&self, jobs: &mut [&JobSummary]) {
377        let order = self.order.unwrap_or_default();
378        let by_id = |a: &JobSummary, b: &JobSummary| match order {
379            SortOrder::Desc => b.id.cmp(&a.id),
380            SortOrder::Asc => a.id.cmp(&b.id),
381        };
382        match self.sort.unwrap_or(JobSort::Queued) {
383            JobSort::Queued => jobs.sort_by(|a, b| by_id(a, b)),
384            sort => jobs.sort_by(|a, b| {
385                let keyed = match (sort.key(a), sort.key(b)) {
386                    (Some(a_key), Some(b_key)) => match order {
387                        SortOrder::Desc => b_key.cmp(&a_key),
388                        SortOrder::Asc => a_key.cmp(&b_key),
389                    },
390                    (a_key, b_key) => a_key.is_none().cmp(&b_key.is_none()),
391                };
392                keyed.then_with(|| by_id(a, b))
393            }),
394        }
395    }
396
397    /// The page this query reads of `jobs`, a whole history held in memory, as the store reads it from the
398    /// database: for the demo's fake daemon and tests. Refuses what [`check`](JobQuery::check) refuses.
399    pub fn page(&self, jobs: &[JobSummary]) -> Result<JobList, String> {
400        self.check()?;
401        let mut listed: Vec<&JobSummary> = jobs
402            .iter()
403            .filter(|job| self.admits(job))
404            .filter(|job| self.before.is_none_or(|before| job.id < before))
405            .collect();
406        self.order(&mut listed);
407        let size = usize::try_from(self.page_size()).unwrap_or(usize::MAX);
408        let mut page = Vec::new();
409        let mut shortened = Vec::new();
410        let mut bytes = 0;
411        for job in listed.iter().take(size) {
412            let (shown, cut) = listed_text(job);
413            let row = row_bytes(&shown);
414            if !page.is_empty() && bytes + row > JOBS_PAGE_BYTES {
415                break;
416            }
417            bytes += row;
418            if cut {
419                shortened.push(shown.id);
420            }
421            page.push(shown);
422        }
423        let total = u64::try_from(listed.len()).unwrap_or(u64::MAX);
424        let more = listed.len() > page.len();
425        Ok(self.answer(page, more, total, shortened))
426    }
427
428    /// A page of `jobs`, in order, of the `total` the filters admit, `shortened` those whose text was cut: with the
429    /// next page's `next` when `more` follow in the default order, and `total` in any other.
430    pub fn answer(
431        &self,
432        jobs: Vec<JobSummary>,
433        more: bool,
434        total: u64,
435        shortened: Vec<u64>,
436    ) -> JobList {
437        let pages = self.pages();
438        let next = jobs.last().filter(|_| more && pages).map(|last| last.id);
439        let mut applied = self.clone();
440        applied.limit = Some(self.page_size());
441        applied.order = Some(self.order.unwrap_or_default());
442        JobList {
443            page: JobPage { jobs, next },
444            total: (!pages).then_some(total),
445            shortened,
446            applied: Some(applied),
447        }
448    }
449}
450
451/// `text` cut to [`JOB_TEXT_MAX`] bytes, to its last whole character.
452fn cut(text: &str) -> &str {
453    &text[..text.floor_char_boundary(JOB_TEXT_MAX)]
454}
455
456/// `job` as a list shows it, as the store reads it: each text cut to [`JOB_TEXT_MAX`] bytes, labels past
457/// [`JOB_LABELS_MAX`] left out. And whether any was.
458fn listed_text(job: &JobSummary) -> (JobSummary, bool) {
459    let cut_option = |text: &Option<String>| text.as_deref().map(|text| cut(text).to_owned());
460    let labels_fit = labels_bytes(&job.labels) <= JOB_LABELS_MAX;
461    let listed = JobSummary {
462        repository: cut(&job.repository).to_owned(),
463        name: cut(&job.name).to_owned(),
464        workflow: cut_option(&job.workflow),
465        branch: cut_option(&job.branch),
466        url: cut_option(&job.url),
467        labels: if labels_fit {
468            job.labels.clone()
469        } else {
470            Vec::new()
471        },
472        ..job.clone()
473    };
474    let shortened = !labels_fit || row_bytes(&listed) != row_bytes(job);
475    (listed, shortened)
476}
477
478/// The bytes of `labels` as the store keeps them: a JSON array of strings, as `serde_json` writes it.
479fn labels_bytes(labels: &[String]) -> usize {
480    2 + labels.len().saturating_sub(1)
481        + labels
482            .iter()
483            .map(|label| json_string_len(label))
484            .sum::<usize>()
485}
486
487/// The bytes of a job's text the page budget counts, as the store counts them in its columns.
488pub fn row_bytes(job: &JobSummary) -> u64 {
489    let text = |text: Option<&str>| text.map_or(0, str::len);
490    u64::try_from(
491        job.repository.len()
492            + text(job.workflow.as_deref())
493            + job.name.len()
494            + text(job.branch.as_deref())
495            + text(job.url.as_deref())
496            + labels_bytes(&job.labels),
497    )
498    .unwrap_or(u64::MAX)
499}
500
501/// The length of `text` as a JSON string, quotes included, escaped as `serde_json` escapes it.
502fn json_string_len(text: &str) -> usize {
503    2 + text
504        .chars()
505        .map(|character| match character {
506            '"' | '\\' | '\n' | '\r' | '\t' | '\u{8}' | '\u{c}' => 2,
507            control if u32::from(control) < 0x20 => 6,
508            other => other.len_utf8(),
509        })
510        .sum::<usize>()
511}
512
513impl JobList {
514    /// Whether the daemon read the query's search, sort and record filter: one older than them leaves out
515    /// `applied`, ignores them and lists every job, which a client says is not supported rather than a result.
516    pub fn understood(&self) -> bool {
517        self.applied.is_some()
518    }
519
520    /// What a client says above a list an older daemon answered without reading its search, sort or record filter:
521    /// that it cannot, and what the list is instead. `None` when the daemon read them.
522    pub fn unread_words(&self) -> Option<String> {
523        (!self.understood()).then(|| {
524            format!(
525                "{}; this is every job, newest first",
526                crate::api::Feature::JobSearch.unsupported()
527            )
528        })
529    }
530
531    /// [`JobList::shown_words`] as a client says it above the list, with what to do about the rest: `50 of 1234 jobs,
532    /// longest wait first; a search or the filters narrow it`.
533    pub fn shown_line(&self) -> Option<String> {
534        self.shown_words()
535            .map(|shown| format!("{shown}; a search or the filters narrow it"))
536    }
537
538    /// What a client says of a page with no jobs.
539    pub fn none_words() -> &'static str {
540        "no jobs match"
541    }
542
543    /// What a sorted page shows of its list when it is not all of it: `50 of 1234 jobs, longest wait first`.
544    /// `None` in the default order, which pages, and when the page holds every job.
545    pub fn shown_words(&self) -> Option<String> {
546        let total = self.total?;
547        let shown = u64::try_from(self.page.jobs.len()).unwrap_or(u64::MAX);
548        if shown >= total {
549            return None;
550        }
551        let query = self.applied.as_ref()?;
552        Some(format!(
553            "{shown} of {total} jobs, {}",
554            JobOrder::of(query).words()
555        ))
556    }
557}
558
559// The tests read the wire format, JSON, which only the host and client features read.
560#[cfg(test)]
561#[cfg(any(feature = "host", feature = "client"))]
562mod tests;