Skip to main content

runnerd_core/api/jobs/
compare.rs

1//! `GET /v1/jobs/{id}/compare` (ADR 0135): a job against an earlier run of the same job, its baseline. Step times
2//! from the stored steps, matched by name only, never by position; whole-job figures where both jobs are final and
3//! have them; a step's memory and CPU only where both steps' samples cover it, marked sampled. What is not known is
4//! `None` and worded as unknown, never 0.
5//!
6//! Pure: the store finds the baseline and reads each step's samples, and [`JobComparison::of`] lays them side by
7//! side, as the demo's fake daemon and the fixtures do from jobs in memory.
8
9use std::collections::BTreeMap;
10
11use serde::{Deserialize, Serialize};
12
13use super::facts::{samples_between, usage_of};
14use super::log::{TITLE_SOURCE_MAX, title};
15use super::{Job, JobState, JobSummary, Sample, Step};
16use crate::api::{SAMPLE_INTERVAL, Tone, cpu_time, duration, in_cores};
17use crate::config::ByteSize;
18
19/// `GET /v1/jobs/{id}/compare` query parameters.
20#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
21pub struct CompareQuery {
22    /// The job to compare with; default the baseline [`baseline_of`](JobComparison::baseline_of) picks.
23    pub with: Option<u64>,
24}
25
26/// What a job is compared with.
27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(rename_all = "kebab-case", tag = "kind")]
29pub enum Baseline {
30    /// This run of the same job.
31    Chosen {
32        /// Its ID.
33        job: u64,
34        /// The branch it ran for.
35        branch: Option<String>,
36        /// When it was queued.
37        queued_at: u64,
38        /// Whether the query named it (`with`), rather than the daemon picking it.
39        asked: bool,
40    },
41    /// None: the reason says why.
42    Unavailable {
43        /// Why.
44        reason: Unavailable,
45    },
46    /// The job `with` named is not a run of the same job.
47    Incompatible {
48        /// That job.
49        job: u64,
50    },
51    /// A newer daemon's answer this version does not know.
52    #[serde(other)]
53    Other,
54}
55
56impl Baseline {
57    /// What the job is compared against, at `now`: `against job 9510 on main, queued 2h ago`; `None` when there is
58    /// no baseline, which [`Baseline::words`] says why.
59    pub fn against(&self, now: u64) -> Option<String> {
60        let Baseline::Chosen {
61            job,
62            branch,
63            queued_at,
64            ..
65        } = self
66        else {
67            return None;
68        };
69        let on = branch
70            .as_deref()
71            .map(|branch| format!(" on {}", title(branch)))
72            .unwrap_or_default();
73        Some(format!(
74            "against job {job}{on}, queued {}",
75            crate::api::ago(*queued_at, now)
76        ))
77    }
78
79    /// Why there is none, worded; `None` when there is one.
80    pub fn words(&self) -> Option<String> {
81        match self {
82            Baseline::Chosen { .. } => None,
83            Baseline::Unavailable { reason } => Some(reason.words().to_owned()),
84            Baseline::Incompatible { job } => Some(format!(
85                "job {job} is not a run of this job: another repository, workflow or name"
86            )),
87            Baseline::Other => Some("not compared".to_owned()),
88        }
89    }
90}
91
92/// Why a job has no baseline.
93#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
94#[serde(rename_all = "kebab-case")]
95pub enum Unavailable {
96    /// No earlier run of the same job on its branch succeeded here, as far as the history keeps.
97    NoEarlierSuccess,
98    /// Its workflow is unknown, so no run is known to be the same job.
99    UnknownWorkflow,
100    /// Its branch is unknown, so no run is known to be on its branch.
101    UnknownBranch,
102    /// A newer daemon's reason this version does not know.
103    #[serde(other)]
104    Other,
105}
106
107impl Unavailable {
108    /// Its words.
109    pub fn words(self) -> &'static str {
110        match self {
111            Unavailable::NoEarlierSuccess => {
112                "no earlier run of this job on its branch succeeded here"
113            }
114            Unavailable::UnknownWorkflow => {
115                "its workflow is unknown, so no earlier run is known to be the same job"
116            }
117            Unavailable::UnknownBranch => {
118                "its branch is unknown, so no earlier run is known to be on it"
119            }
120            Unavailable::Other => "no baseline",
121        }
122    }
123}
124
125/// What a figure measures.
126#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
127#[serde(rename_all = "kebab-case")]
128pub enum FigureKind {
129    /// Seconds from queued to started.
130    Wait,
131    /// Seconds from started to finished.
132    Run,
133    /// The highest memory of its samples, in bytes.
134    MemoryPeak,
135    /// CPU time, in milliseconds.
136    CpuTime,
137    /// CPU time over wall time, in millicores.
138    CpuAverage,
139    /// Bytes received.
140    Received,
141    /// A step's seconds from started to completed.
142    StepTime,
143    /// The highest memory of a step's samples, in bytes.
144    StepMemory,
145    /// A step's samples' CPU use averaged, in millicores.
146    StepCpu,
147    /// A newer daemon's figure this version does not know.
148    #[serde(other)]
149    Other,
150}
151
152impl FigureKind {
153    /// Its label: `Wait`, `Memory peak`, `Step CPU`.
154    pub fn label(self) -> &'static str {
155        match self {
156            FigureKind::Wait => "Wait",
157            FigureKind::Run => "Run time",
158            FigureKind::MemoryPeak | FigureKind::StepMemory => "Memory peak",
159            FigureKind::CpuTime => "CPU time",
160            FigureKind::CpuAverage | FigureKind::StepCpu => "Average CPU",
161            FigureKind::Received => "Received",
162            FigureKind::StepTime => "Time",
163            FigureKind::Other => "Figure",
164        }
165    }
166
167    /// A value of it with its unit: `1m 5s`, `4.1G`, `1.5 cores`.
168    pub fn words(self, value: u64) -> String {
169        match self {
170            FigureKind::Wait | FigureKind::Run | FigureKind::StepTime => duration(value),
171            FigureKind::MemoryPeak | FigureKind::Received | FigureKind::StepMemory => {
172                ByteSize(value).to_string()
173            }
174            FigureKind::CpuTime => cpu_time(value),
175            FigureKind::CpuAverage | FigureKind::StepCpu => in_cores(value),
176            FigureKind::Other => value.to_string(),
177        }
178    }
179
180    /// Whether more of it costs more: time and memory do; a CPU average or bytes received only say how it ran.
181    fn is_cost(self) -> bool {
182        matches!(
183            self,
184            FigureKind::Wait
185                | FigureKind::Run
186                | FigureKind::MemoryPeak
187                | FigureKind::CpuTime
188                | FigureKind::StepTime
189                | FigureKind::StepMemory
190        )
191    }
192
193    /// The least change worth a tone, beside a tenth: 5 seconds for a duration.
194    fn floor(self) -> u64 {
195        match self {
196            FigureKind::Wait | FigureKind::Run | FigureKind::StepTime => 5,
197            _ => 0,
198        }
199    }
200}
201
202/// How a figure changed from the baseline.
203#[derive(Debug, Clone, Copy, PartialEq, Eq)]
204pub enum ChangeKind {
205    /// It grew.
206    More,
207    /// It shrank.
208    Less,
209    /// It is the same.
210    Same,
211    /// One side is unknown.
212    Unknown,
213}
214
215/// One figure of this job beside the baseline's.
216#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
217pub struct FigureDelta {
218    /// What it measures.
219    pub figure: FigureKind,
220    /// This job's; `None` where unknown.
221    pub this: Option<u64>,
222    /// The baseline's; `None` where unknown, or without a baseline.
223    pub baseline: Option<u64>,
224    /// Whether both come from samples taken every few seconds, so a short peak between two is missed.
225    #[serde(default)]
226    pub sampled: bool,
227}
228
229impl FigureDelta {
230    fn new(figure: FigureKind, this: Option<u64>, baseline: Option<u64>) -> FigureDelta {
231        FigureDelta {
232            figure,
233            this,
234            baseline,
235            sampled: false,
236        }
237    }
238
239    /// This job's figure with its unit, or `unknown`.
240    pub fn this_words(&self) -> String {
241        self.this
242            .map_or_else(|| "unknown".to_owned(), |value| self.figure.words(value))
243    }
244
245    /// The baseline's figure with its unit, or `unknown`.
246    pub fn baseline_words(&self) -> String {
247        self.baseline
248            .map_or_else(|| "unknown".to_owned(), |value| self.figure.words(value))
249    }
250
251    /// Which way it went.
252    pub fn change(&self) -> ChangeKind {
253        match (self.this, self.baseline) {
254            (Some(this), Some(baseline)) if this > baseline => ChangeKind::More,
255            (Some(this), Some(baseline)) if this < baseline => ChangeKind::Less,
256            (Some(_), Some(_)) => ChangeKind::Same,
257            _ => ChangeKind::Unknown,
258        }
259    }
260
261    /// The change in words: `+1m 5s (+12%)`, `-300M (-8%)`, `same`, or `unknown`.
262    pub fn change_words(&self) -> String {
263        let (Some(this), Some(baseline)) = (self.this, self.baseline) else {
264            return "unknown".to_owned();
265        };
266        let (sign, by) = match self.change() {
267            ChangeKind::More => ('+', this - baseline),
268            ChangeKind::Less => ('-', baseline - this),
269            ChangeKind::Same | ChangeKind::Unknown => return "same".to_owned(),
270        };
271        let words = format!("{sign}{}", self.figure.words(by));
272        match u128::from(by)
273            .saturating_mul(100)
274            .checked_div(u128::from(baseline))
275        {
276            Some(percent) => format!("{words} ({sign}{percent}%)"),
277            None => words,
278        }
279    }
280
281    /// What the change means: for a cost, a tenth more and past its floor is worth a look, a tenth less is better;
282    /// an unknown side is background.
283    pub fn tone(&self) -> Tone {
284        let (Some(this), Some(baseline)) = (self.this, self.baseline) else {
285            return Tone::Quiet;
286        };
287        let by = this.abs_diff(baseline);
288        let marked = by >= self.figure.floor() && u128::from(by) * 10 > u128::from(baseline);
289        match self.change() {
290            ChangeKind::More if marked && self.figure.is_cost() => Tone::Warn,
291            ChangeKind::Less if marked && self.figure.is_cost() => Tone::Good,
292            _ => Tone::Neutral,
293        }
294    }
295}
296
297/// How a step of one job was paired with the other's.
298#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
299#[serde(rename_all = "kebab-case")]
300pub enum StepMatch {
301    /// The one step of this name in each job.
302    Matched,
303    /// Only this job has a step of this name.
304    OnlyThis,
305    /// Only the baseline has a step of this name.
306    OnlyBaseline,
307    /// A job has several steps of this name, so none of them is paired.
308    Ambiguous,
309    /// A newer daemon's pairing this version does not know.
310    #[serde(other)]
311    Other,
312}
313
314impl StepMatch {
315    /// What it says beside the step, `None` for a matched one: `only in this run`, `only in the baseline`, `name
316    /// not unique`.
317    pub fn words(self) -> Option<&'static str> {
318        match self {
319            StepMatch::Matched => None,
320            StepMatch::OnlyThis => Some("only in this run"),
321            StepMatch::OnlyBaseline => Some("only in the baseline"),
322            StepMatch::Ambiguous => Some("name not unique, not compared"),
323            StepMatch::Other => Some("not compared"),
324        }
325    }
326}
327
328/// One step beside the baseline's step of the same name.
329#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
330pub struct StepDelta {
331    /// The step's name, without escapes or control characters, cut to 200 bytes.
332    pub name: String,
333    /// How it was paired.
334    pub matched: StepMatch,
335    /// This job's step number, if it has the step.
336    pub this: Option<u32>,
337    /// The baseline's step number, if it has the step.
338    pub baseline: Option<u32>,
339    /// Its time on each side.
340    pub time: FigureDelta,
341    /// Its memory peak on each side, sampled: only where both steps' samples cover them.
342    #[serde(default, skip_serializing_if = "Option::is_none")]
343    pub memory: Option<FigureDelta>,
344    /// Its average CPU on each side, as `memory`.
345    #[serde(default, skip_serializing_if = "Option::is_none")]
346    pub cpu: Option<FigureDelta>,
347}
348
349/// Samples further apart than this many sample intervals, or as far from a step's start or end, leave part of the
350/// step unsampled: its peak may be in it.
351pub(crate) const SAMPLE_GAP_INTERVALS: u64 = 3;
352
353/// What a step's samples say, as the store reads them over its window: the samples after its start up to its end.
354#[derive(Debug, Clone, Copy, PartialEq, Eq)]
355pub struct StepUsage {
356    /// The step's number.
357    pub number: u32,
358    /// When its first sample was taken.
359    pub first: u64,
360    /// When its last was.
361    pub last: u64,
362    /// The longest time between two of its samples, in seconds; 0 for one sample.
363    pub widest_gap: u64,
364    /// Their highest memory, in bytes.
365    pub memory_peak: u64,
366    /// Their CPU use averaged, in millicores.
367    pub cpu_average: u64,
368}
369
370impl StepUsage {
371    /// What `samples`, a job's runner's, say over each of `steps` with both times, as the store reads its samples:
372    /// those after a step's start up to its end. For a history held in memory, such as the demo's.
373    pub fn of(samples: &[Sample], steps: &[Step]) -> Vec<StepUsage> {
374        steps
375            .iter()
376            .filter_map(|step| {
377                let (from, to) = (step.started_at?, step.completed_at?);
378                let inside = samples_between(samples, from, to);
379                let usage = usage_of(&inside)?;
380                let widest_gap = inside
381                    .windows(2)
382                    .map(|pair| pair[1].at.saturating_sub(pair[0].at))
383                    .max()
384                    .unwrap_or(0);
385                Some(StepUsage {
386                    number: step.number,
387                    first: inside.first()?.at,
388                    last: inside.last()?.at,
389                    widest_gap,
390                    memory_peak: usage.memory_peak,
391                    cpu_average: usage.cpu_average,
392                })
393            })
394            .collect()
395    }
396}
397
398/// The baseline as the store found it.
399#[derive(Debug, Clone, PartialEq, Eq)]
400pub enum BaselineRead {
401    /// A run of the same job, and its steps' samples.
402    Found {
403        /// The job's summary.
404        job: Box<JobSummary>,
405        /// Its steps, as far as a comparison reads them.
406        steps: ComparedSteps,
407        /// Its steps' samples.
408        usage: Vec<StepUsage>,
409        /// Whether the query named it.
410        asked: bool,
411    },
412    /// None, for this reason.
413    Unavailable(Unavailable),
414    /// The job named is not a run of the same job.
415    Incompatible(u64),
416}
417
418/// `GET /v1/jobs/{id}/compare`: a job beside its baseline.
419#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
420pub struct JobComparison {
421    /// The job.
422    pub job: u64,
423    /// What it is compared with.
424    pub baseline: Baseline,
425    /// Whole-job figures, each given where the job is final; the baseline's always is.
426    pub figures: Vec<FigureDelta>,
427    /// This job's steps in order, then the baseline's steps it does not have; none without a baseline.
428    pub steps: Vec<StepDelta>,
429    /// Whether a job had more steps, or more of their names, than a comparison reads, so `steps` leaves its last
430    /// ones out ([`COMPARE_STEPS_MAX`], [`COMPARE_STEP_BYTES`]).
431    #[serde(default, skip_serializing_if = "is_false")]
432    pub steps_cut: bool,
433}
434
435#[expect(
436    clippy::trivially_copy_pass_by_ref,
437    reason = "serde's skip_serializing_if passes a reference"
438)]
439fn is_false(value: &bool) -> bool {
440    !value
441}
442
443/// The most steps of each job a comparison reads, in order of their numbers.
444pub const COMPARE_STEPS_MAX: usize = 500;
445
446/// The most bytes of step names of each job a comparison reads, each name read from its first 800 bytes, the most a
447/// title is read from; a first step is read whatever its name's length.
448pub const COMPARE_STEP_BYTES: usize = 128 * 1024;
449
450/// A job's steps as far as a comparison reads them: the first [`COMPARE_STEPS_MAX`] in order, while their names,
451/// each cut to its first 800 bytes, add up to at most [`COMPARE_STEP_BYTES`]. Steps pair by these names.
452#[derive(Debug, Clone, Default, PartialEq, Eq)]
453pub struct ComparedSteps {
454    /// The steps read, in order.
455    pub steps: Vec<Step>,
456    /// Whether the job has steps past them.
457    pub cut: bool,
458}
459
460impl ComparedSteps {
461    /// `steps`, in order of their numbers, as the store reads them.
462    pub fn of(steps: &[Step]) -> ComparedSteps {
463        let mut ordered: Vec<&Step> = steps.iter().collect();
464        ordered.sort_by_key(|step| step.number);
465        let mut read = ComparedSteps::default();
466        for step in ordered {
467            let mut step = step.clone();
468            let cut = step.name.floor_char_boundary(TITLE_SOURCE_MAX);
469            step.name.truncate(cut);
470            if !read.push(step) {
471                read.cut = true;
472                break;
473            }
474        }
475        read
476    }
477
478    /// Adds `step`, its name already cut, unless the steps read are at a bound; whether it was added.
479    pub fn push(&mut self, step: Step) -> bool {
480        let bytes: usize = self.steps.iter().map(|step| step.name.len()).sum();
481        let full = self.steps.len() >= COMPARE_STEPS_MAX
482            || (!self.steps.is_empty() && bytes + step.name.len() > COMPARE_STEP_BYTES);
483        if !full {
484            self.steps.push(step);
485        }
486        !full
487    }
488}
489
490/// A step's time in seconds, where both ends are known.
491fn step_time(step: &Step) -> Option<u64> {
492    Some(step.completed_at?.saturating_sub(step.started_at?))
493}
494
495/// Whether `usage` covers its step from start to end: its first sample near the step's start, its last near its
496/// end, and none further apart than the samples' normal tolerance. A step whose samples were partly pruned, or
497/// that ran while sampling stopped, is not covered: its peak may be in the part not sampled.
498fn covers(usage: &StepUsage, step: &Step) -> bool {
499    let tolerance = SAMPLE_INTERVAL * SAMPLE_GAP_INTERVALS;
500    let (Some(from), Some(to)) = (step.started_at, step.completed_at) else {
501        return false;
502    };
503    usage.first.saturating_sub(from) <= tolerance
504        && to.saturating_sub(usage.last) <= tolerance
505        && usage.widest_gap <= tolerance
506}
507
508impl JobComparison {
509    /// Whether `other` is a run of the same job as `job`: the same repository, a known and equal workflow, the same
510    /// name, and not `job` itself.
511    pub fn same_job(job: &JobSummary, other: &JobSummary) -> bool {
512        other.id != job.id
513            && other.repository == job.repository
514            && job.workflow.is_some()
515            && other.workflow == job.workflow
516            && other.name == job.name
517    }
518
519    /// Whether `other` may be `job`'s baseline: a run of the same job on the same known branch, queued before it
520    /// (by time, then ID), that completed `success` with a runner here.
521    pub fn is_baseline(job: &JobSummary, other: &JobSummary) -> bool {
522        JobComparison::same_job(job, other)
523            && job.branch.is_some()
524            && other.branch == job.branch
525            && other.state == JobState::Completed
526            && other.conclusion.as_deref() == Some("success")
527            && other.runner.is_some()
528            && other.timeline.started_at.is_some()
529            && (other.timeline.queued_at, other.id) < (job.timeline.queued_at, job.id)
530    }
531
532    /// `job`'s baseline among `history`: the latest that [`is_baseline`](JobComparison::is_baseline); or why there
533    /// is none. As the store picks it.
534    pub fn baseline_of<'history>(
535        job: &JobSummary,
536        history: &'history [JobSummary],
537    ) -> Result<&'history JobSummary, Unavailable> {
538        if job.workflow.is_none() {
539            return Err(Unavailable::UnknownWorkflow);
540        }
541        if job.branch.is_none() {
542            return Err(Unavailable::UnknownBranch);
543        }
544        history
545            .iter()
546            .filter(|other| JobComparison::is_baseline(job, other))
547            .max_by_key(|other| (other.timeline.queued_at, other.id))
548            .ok_or(Unavailable::NoEarlierSuccess)
549    }
550
551    /// Job `id` beside the job `with` names, or its baseline, in `history` held in memory, `usage` reading a job's
552    /// steps' samples: as the store answers it, for the demo's fake daemon and the fixtures. `None` without either
553    /// job. Steps and samples are read only once a baseline is found.
554    pub fn in_history(
555        id: u64,
556        with: Option<u64>,
557        history: &[Job],
558        usage: impl Fn(&Job) -> Vec<StepUsage>,
559    ) -> Option<JobComparison> {
560        let find = |id: u64| history.iter().find(|job| job.summary.id == id);
561        let this = find(id)?;
562        let found = |other: &Job, asked: bool| BaselineRead::Found {
563            job: Box::new(other.summary.clone()),
564            steps: ComparedSteps::of(&other.steps),
565            usage: usage(other),
566            asked,
567        };
568        let baseline = if let Some(with) = with {
569            let other = find(with)?;
570            if JobComparison::same_job(&this.summary, &other.summary) {
571                found(other, true)
572            } else {
573                BaselineRead::Incompatible(with)
574            }
575        } else {
576            let summaries: Vec<JobSummary> =
577                history.iter().map(|job| job.summary.clone()).collect();
578            match JobComparison::baseline_of(&this.summary, &summaries) {
579                Ok(other) => find(other.id).map_or(
580                    BaselineRead::Unavailable(Unavailable::NoEarlierSuccess),
581                    |other| found(other, false),
582                ),
583                Err(reason) => BaselineRead::Unavailable(reason),
584            }
585        };
586        let (steps, usage) = match baseline {
587            BaselineRead::Found { .. } => (ComparedSteps::of(&this.steps), usage(this)),
588            _ => (ComparedSteps::default(), Vec::new()),
589        };
590        Some(JobComparison::of(&this.summary, &steps, &usage, baseline))
591    }
592
593    /// `job`, whose steps a comparison reads are `steps` and their samples `usage`, beside the baseline the store
594    /// read. Without a baseline, `steps` and `usage` are not looked at, so the store need not read them.
595    pub fn of(
596        job: &JobSummary,
597        steps: &ComparedSteps,
598        usage: &[StepUsage],
599        baseline: BaselineRead,
600    ) -> JobComparison {
601        let (other, other_steps, other_usage, asked) = match baseline {
602            BaselineRead::Found {
603                job,
604                steps,
605                usage,
606                asked,
607            } => (job, steps, usage, asked),
608            BaselineRead::Unavailable(reason) => {
609                return JobComparison::alone(job, Baseline::Unavailable { reason });
610            }
611            BaselineRead::Incompatible(other) => {
612                return JobComparison::alone(job, Baseline::Incompatible { job: other });
613            }
614        };
615        JobComparison {
616            job: job.id,
617            baseline: Baseline::Chosen {
618                job: other.id,
619                branch: other.branch.clone(),
620                queued_at: other.timeline.queued_at,
621                asked,
622            },
623            figures: figures(job, Some(&other)),
624            steps: deltas(&steps.steps, usage, &other_steps.steps, &other_usage),
625            steps_cut: steps.cut || other_steps.cut,
626        }
627    }
628
629    /// `job` with no baseline: its own figures, each baseline side unknown, and no steps to pair.
630    fn alone(job: &JobSummary, baseline: Baseline) -> JobComparison {
631        JobComparison {
632            job: job.id,
633            baseline,
634            figures: figures(job, None),
635            steps: Vec::new(),
636            steps_cut: false,
637        }
638    }
639
640    /// What `steps` leaves out, worded; `None` when nothing.
641    pub fn steps_cut_words(&self) -> Option<&'static str> {
642        self.steps_cut.then_some(
643            "some steps are not compared: a run has more steps, or longer step names, than a comparison reads",
644        )
645    }
646}
647
648/// The whole-job figures: each only for a final job, whose totals no longer change.
649fn figures(job: &JobSummary, baseline: Option<&JobSummary>) -> Vec<FigureDelta> {
650    let read = |job: &JobSummary, figure: FigureKind| -> Option<u64> {
651        let timeline = &job.timeline;
652        let metrics = &job.metrics;
653        match figure {
654            FigureKind::Wait => timeline
655                .started_at
656                .map(|started| started.saturating_sub(timeline.queued_at)),
657            _ if !job.state.is_final() => None,
658            FigureKind::Run => Some(timeline.finished_at?.saturating_sub(timeline.started_at?)),
659            FigureKind::MemoryPeak => metrics.memory_peak,
660            FigureKind::CpuTime => metrics.cpu_time,
661            FigureKind::CpuAverage => metrics.cpu_average,
662            FigureKind::Received => metrics.network_received,
663            _ => None,
664        }
665    };
666    [
667        FigureKind::Wait,
668        FigureKind::Run,
669        FigureKind::MemoryPeak,
670        FigureKind::CpuTime,
671        FigureKind::CpuAverage,
672        FigureKind::Received,
673    ]
674    .into_iter()
675    .map(|figure| {
676        FigureDelta::new(
677            figure,
678            read(job, figure),
679            baseline.and_then(|baseline| read(baseline, figure)),
680        )
681    })
682    .collect()
683}
684
685/// How many steps of each name a job has.
686fn names(steps: &[Step]) -> BTreeMap<&str, usize> {
687    let mut names = BTreeMap::new();
688    for step in steps {
689        *names.entry(step.name.as_str()).or_insert(0) += 1;
690    }
691    names
692}
693
694/// The steps side by side, paired by a name each job has once.
695fn deltas(
696    ours_steps: &[Step],
697    usage: &[StepUsage],
698    theirs_steps: &[Step],
699    other_usage: &[StepUsage],
700) -> Vec<StepDelta> {
701    let ours = names(ours_steps);
702    let theirs = names(theirs_steps);
703    let unique = |name: &str| {
704        ours.get(name).copied().unwrap_or(0) <= 1 && theirs.get(name).copied().unwrap_or(0) <= 1
705    };
706    let usage_of = |usage: &[StepUsage], step: &Step| {
707        usage
708            .iter()
709            .find(|usage| usage.number == step.number)
710            .filter(|usage| covers(usage, step))
711            .copied()
712    };
713    let sampled = |figure: FigureKind, this: u64, other: u64| FigureDelta {
714        figure,
715        this: Some(this),
716        baseline: Some(other),
717        sampled: true,
718    };
719    let mut deltas = Vec::new();
720    for step in ours_steps {
721        let paired = unique(&step.name)
722            .then(|| theirs_steps.iter().find(|theirs| theirs.name == step.name))
723            .flatten();
724        let matched = match (paired, unique(&step.name)) {
725            (Some(_), _) => StepMatch::Matched,
726            (None, false) => StepMatch::Ambiguous,
727            (None, true) => StepMatch::OnlyThis,
728        };
729        let ours_used = usage_of(usage, step);
730        let theirs_used = paired.and_then(|theirs| usage_of(other_usage, theirs));
731        let both = ours_used.zip(theirs_used);
732        deltas.push(StepDelta {
733            name: title(&step.name),
734            matched,
735            this: Some(step.number),
736            baseline: paired.map(|theirs| theirs.number),
737            time: FigureDelta::new(
738                FigureKind::StepTime,
739                step_time(step),
740                paired.and_then(step_time),
741            ),
742            memory: both.map(|(ours, theirs)| {
743                sampled(FigureKind::StepMemory, ours.memory_peak, theirs.memory_peak)
744            }),
745            cpu: both.map(|(ours, theirs)| {
746                sampled(FigureKind::StepCpu, ours.cpu_average, theirs.cpu_average)
747            }),
748        });
749    }
750    for theirs in theirs_steps {
751        let unpaired = !unique(&theirs.name) || !ours.contains_key(theirs.name.as_str());
752        if !unpaired {
753            continue;
754        }
755        deltas.push(StepDelta {
756            name: title(&theirs.name),
757            matched: if unique(&theirs.name) {
758                StepMatch::OnlyBaseline
759            } else {
760                StepMatch::Ambiguous
761            },
762            this: None,
763            baseline: Some(theirs.number),
764            time: FigureDelta::new(FigureKind::StepTime, None, step_time(theirs)),
765            memory: None,
766            cpu: None,
767        });
768    }
769    deltas
770}
771
772// The tests read the wire format, JSON, which only the host and client features read.
773#[cfg(test)]
774#[cfg(any(feature = "host", feature = "client"))]
775mod tests;