1use serde::{Deserialize, Serialize};
10
11use super::{JobList, JobPage, JobQuery, JobSummary};
12use crate::api::{RecordNote, RecordState, Tone};
13
14pub const JOB_SEARCH_MAX: usize = 100;
16
17pub const JOBS_PAGE_DEFAULT: u32 = 50;
19
20pub const JOBS_PAGE_MAX: u32 = 500;
22
23pub const JOBS_PAGE_BYTES: u64 = 1 << 20;
27
28pub const JOB_TEXT_MAX: usize = 1024;
31
32pub const JOB_LABELS_MAX: usize = 4096;
35
36#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
38#[serde(rename_all = "kebab-case")]
39pub enum JobSort {
40 Queued,
43 Wait,
46 Run,
48 Memory,
50}
51
52impl JobSort {
53 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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
73#[serde(rename_all = "kebab-case")]
74pub enum SortOrder {
75 #[default]
77 Desc,
78 Asc,
80}
81
82#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
84#[serde(rename_all = "kebab-case")]
85pub enum RecordFilter {
86 Any,
88 Kept,
90 Removed,
92 Skipped,
94}
95
96impl RecordFilter {
97 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#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
113#[serde(rename_all = "kebab-case")]
114pub enum RecordMark {
115 Kept,
117 Removed,
119 Skipped,
121 #[serde(other)]
123 Unknown,
124}
125
126impl RecordMark {
127 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 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 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 pub const ALL: [RecordFilter; 4] = [
158 RecordFilter::Any,
159 RecordFilter::Kept,
160 RecordFilter::Removed,
161 RecordFilter::Skipped,
162 ];
163
164 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#[derive(Debug, Clone, Copy, PartialEq, Eq)]
177pub struct JobOrder {
178 pub sort: JobSort,
180 pub order: SortOrder,
182}
183
184impl JobOrder {
185 pub const NEWEST: JobOrder = JobOrder {
187 sort: JobSort::Queued,
188 order: SortOrder::Desc,
189 };
190
191 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 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 pub fn pages(self) -> bool {
218 self == JobOrder::NEWEST
219 }
220
221 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 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#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
249pub enum JobRange {
250 Day,
252 Week,
254 Month,
256 #[default]
258 All,
259}
260
261impl JobRange {
262 pub const ALL: [JobRange; 4] = [
264 JobRange::Day,
265 JobRange::Week,
266 JobRange::Month,
267 JobRange::All,
268 ];
269
270 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 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 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 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 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 pub fn page_size(&self) -> u32 {
340 self.limit
341 .unwrap_or(JOBS_PAGE_DEFAULT)
342 .clamp(1, JOBS_PAGE_MAX)
343 }
344
345 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 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 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 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
451fn cut(text: &str) -> &str {
453 &text[..text.floor_char_boundary(JOB_TEXT_MAX)]
454}
455
456fn 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
478fn 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
487pub 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
501fn 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 pub fn understood(&self) -> bool {
517 self.applied.is_some()
518 }
519
520 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 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 pub fn none_words() -> &'static str {
540 "no jobs match"
541 }
542
543 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#[cfg(test)]
561#[cfg(any(feature = "host", feature = "client"))]
562mod tests;