Skip to main content

runnerd_core/api/
labels.rs

1//! The names every client gives the same thing: its views and the columns of a table of jobs. A client lays a name
2//! out, upper-cases it or fits it; it does not spell its own.
3
4/// A group of pages of the web dashboard, a group of views of `runnerctl tui`, in the order every client lists them:
5/// what runs now, the jobs, what the history says, the machine's room and the daemon's settings (ADR 0132).
6#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
7#[serde(rename_all = "kebab-case")]
8pub enum View {
9    /// Budget, slots, the queue, what needs attention and the latest jobs.
10    Overview,
11    /// Finished and running jobs, and the records of failed ones.
12    Jobs,
13    /// What the history says: jobs that got slower, are flaky or near their cap.
14    Insights,
15    /// What each profile's jobs use and what to set, and the caches.
16    Capacity,
17    /// The daemon's config and the host's checks.
18    Settings,
19}
20
21impl View {
22    /// Every view, in order.
23    pub const ALL: [View; 5] = [
24        View::Overview,
25        View::Jobs,
26        View::Insights,
27        View::Capacity,
28        View::Settings,
29    ];
30
31    /// What clients call it.
32    pub fn title(self) -> &'static str {
33        match self {
34            View::Overview => "Overview",
35            View::Jobs => "Jobs",
36            View::Insights => "Insights",
37            View::Capacity => "Capacity",
38            View::Settings => "Settings",
39        }
40    }
41
42    /// Its sections, in order: the first is what opening the view shows. A view of one page has none.
43    pub fn sections(self) -> &'static [Section] {
44        match self {
45            View::Overview | View::Insights => &[],
46            View::Jobs => &[Section::History, Section::Records],
47            View::Capacity => &[Section::Sizing, Section::Caches],
48            View::Settings => &[Section::Config],
49        }
50    }
51}
52
53/// A page inside a [`View`] of several, as every client names it.
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub enum Section {
56    /// Finished and running jobs, filtered.
57    History,
58    /// The records of failed jobs.
59    Records,
60    /// What each profile's jobs use and what to set.
61    Sizing,
62    /// The cache volumes and the build cache.
63    Caches,
64    /// The daemon's config and the host's checks.
65    Config,
66}
67
68impl Section {
69    /// What clients call it.
70    pub fn title(self) -> &'static str {
71        match self {
72            Section::History => "History",
73            Section::Records => "Records",
74            Section::Sizing => "Sizing",
75            Section::Caches => "Caches",
76            Section::Config => "Config",
77        }
78    }
79
80    /// The view it is a section of.
81    pub fn view(self) -> View {
82        match self {
83            Section::History | Section::Records => View::Jobs,
84            Section::Sizing | Section::Caches => View::Capacity,
85            Section::Config => View::Settings,
86        }
87    }
88}
89
90/// What a client reads from the daemon that a runnerd older than the client may not serve: a route it lacks, which
91/// the client says is not supported rather than empty (`ClientError::is_unsupported`, `JobList::understood`).
92#[derive(Debug, Clone, Copy, PartialEq, Eq)]
93pub enum Feature {
94    /// `GET /v1/attention`.
95    Attention,
96    /// `GET /v1/jobs/{id}/log/outline` and `/log/lines`.
97    LogOutline,
98    /// `GET /v1/jobs/{id}/log/search`.
99    LogSearch,
100    /// The search, sorts and record filter of `GET /v1/jobs`.
101    JobSearch,
102    /// `GET /v1/timeline`.
103    Timeline,
104    /// `GET /v1/jobs/{id}/compare`.
105    Comparison,
106    /// `GET /v1/insights`.
107    Insights,
108    /// `GET /v1/caches`.
109    Caches,
110    /// `GET /v1/doctor`.
111    Doctor,
112    /// `GET /v1/config`.
113    Config,
114}
115
116impl Feature {
117    /// What a client says in its place: `log search: not supported by this runnerd`, [`NOT_SUPPORTED`] named for
118    /// what is missing.
119    pub fn unsupported(self) -> String {
120        let what = match self {
121            Feature::Attention => "attention",
122            Feature::LogOutline => "log outline",
123            Feature::LogSearch => "log search",
124            Feature::JobSearch => "search, sort and record filter",
125            Feature::Timeline => "timeline",
126            Feature::Comparison => "comparison",
127            Feature::Insights => "insights",
128            Feature::Caches => "caches",
129            Feature::Doctor => "doctor",
130            Feature::Config => "config",
131        };
132        format!("{what}: {NOT_SUPPORTED}")
133    }
134}
135
136/// A column of a table of jobs or of records, as the history, `runnerctl jobs` and the records name it.
137#[derive(Debug, Clone, Copy, PartialEq, Eq)]
138pub enum Column {
139    /// GitHub's number for the job.
140    Id,
141    /// How the job ended, or that it is running.
142    Outcome,
143    /// Its workflow and name.
144    Job,
145    /// Its repository.
146    Repository,
147    /// Its branch.
148    Branch,
149    /// When GitHub queued it.
150    Queued,
151    /// How long it waited for a runner.
152    Waited,
153    /// How long it ran.
154    Ran,
155    /// The highest memory its sampled use reached.
156    MemoryPeak,
157    /// Its average CPU, in cores.
158    Cpu,
159    /// When a record of the failed job was made.
160    Made,
161    /// How much disk a record takes.
162    Size,
163    /// The workflow it ran in.
164    Workflow,
165    /// What became of a failed job's record.
166    Record,
167}
168
169impl Column {
170    /// What clients call it.
171    pub fn title(self) -> &'static str {
172        match self {
173            Column::Id => "ID",
174            Column::Outcome => "Outcome",
175            Column::Job => "Job",
176            Column::Repository => "Repository",
177            Column::Branch => "Branch",
178            Column::Queued => "Queued",
179            Column::Waited => "Waited",
180            Column::Ran => "Ran",
181            Column::MemoryPeak => "Memory peak",
182            Column::Cpu => "CPU",
183            Column::Made => "Made",
184            Column::Size => "Size",
185            Column::Workflow => "Workflow",
186            Column::Record => "Record",
187        }
188    }
189}
190
191/// What a count of jobs, or a list of them on a page, is headed: the history's figures, a profile's facts, the waits
192/// table. Not the name of [`View::Jobs`], though it reads the same.
193pub const JOBS_HEADING: &str = "Jobs";
194
195/// What a client says where an older daemon lacks a route or a field it reads: never an empty answer in its place.
196pub const NOT_SUPPORTED: &str = "not supported by this runnerd";