runnerd-core 0.1.5

Config, domain logic and API types shared by runnerd and its clients
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
//! The confirmations this daemon issued and the job actions being sent to GitHub, at most one per workflow run (ADR
//! 0134). A confirmation is an opaque random token bound to what its preview showed and the config revision it was
//! shown under; it lasts a few minutes and is sent once: the same token while its flight is in the air joins that
//! flight, and after it landed it is refused. Concurrent requests for one run meet here, so a double click sends one
//! request. It holds nothing across a restart, so a confirmation from before one is unknown; it never sends anything
//! itself.

use std::collections::HashMap;
use std::fmt::Write as _;
use std::io::{self, Read as _};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use tokio::sync::watch;

use crate::api::{ActionResult, ActionTarget, JobAction, RunSeen, Superseded};
use crate::sync::lock;

/// The most confirmations kept: past it the oldest goes, as if it ran out.
const ISSUED_MAX: usize = 256;

/// A workflow run of a repository.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct RunKey {
    repository: String,
    run: u64,
}

/// What a confirmation was issued for: the target its preview showed, the run's attempt in it, and the config
/// revision it was shown under.
#[derive(Debug, Clone)]
pub(super) struct Issued {
    /// What, of which job, on which run and attempt.
    pub(super) target: ActionTarget,
    /// The policy revision of the preview.
    pub(super) revision: u64,
    /// Who asked for it.
    pub(super) origin: Origin,
}

/// Who asked for an action.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(super) enum Origin {
    /// The owner, through a confirmed preview.
    Owner,
    /// runnerd itself, for a run its runner failed (ADR 0153).
    Automatic,
}

/// Why an automatic action's permit said no, besides another attempt (ADR 0153).
#[derive(Debug, Clone, Copy)]
pub(super) enum Withheld {
    /// The run is not completed as `failure`: cancelled as a whole, say.
    NotFailed,
    /// The run could not be read: GitHub's failure, as a class and a status.
    Unread(crate::github::ActionFailure),
}

/// How a flight ended.
#[derive(Debug, Clone)]
pub(super) enum Landed {
    /// GitHub was asked, or the request ended unknown.
    Done(ActionResult),
    /// Nothing was sent: the run was not as the confirmation showed it, and the requests get a new preview of it.
    Repreview {
        /// The run as read before the send.
        run: RunSeen,
        /// Why the confirmation was not sent.
        why: Superseded,
    },
    /// Nothing was sent: an automatic action's permit said no (ADR 0153).
    Withheld(Withheld),
}

/// One confirmation and what became of it.
struct Confirmation {
    issued: Issued,
    at: Instant,
    used: Use,
}

#[derive(Clone, Copy)]
enum Use {
    /// Not sent yet.
    Open,
    /// Boarded the flight with this ID.
    Boarded(u64),
}

/// What one flight asks: the action, from which job.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Asked {
    action: JobAction,
    job: u64,
}

/// One action in flight and where its answer goes.
struct Flight {
    id: u64,
    asked: Asked,
    origin: Origin,
    answer: watch::Sender<Option<Landed>>,
}

/// The confirmations and flights. Only its methods write it, each in one critical section.
struct Book {
    issued: HashMap<String, Confirmation>,
    runs: HashMap<RunKey, Flight>,
    next_flight: u64,
}

/// The confirmations issued and the actions in flight. A `Landing` has it take its run's entry out when dropped.
pub(super) struct Flights {
    /// How long a confirmation lasts.
    lasts: Duration,
    // Locked with `sync::lock`: every critical section is a few lookups, inserts or removes.
    book: Mutex<Book>,
}

/// What a confirmation got.
pub(super) enum Redeemed {
    /// It holds: the request joins the run's flights, to send what it was issued for.
    Board {
        /// How.
        boarding: Boarding,
        /// What it was issued for.
        issued: Issued,
    },
    /// It does not: the request gets a new preview, and nothing is sent.
    Stale(Superseded),
}

/// How a request joins the run's flights.
pub(super) enum Boarding {
    /// Nothing was in flight for the run: this request sends it, and lands it once GitHub answered.
    Lead {
        /// Takes the run's entry out when dropped.
        landing: Landing,
        /// Where the answer comes.
        answer: watch::Receiver<Option<Landed>>,
    },
    /// The same action from the same job is in flight: this request gets its answer.
    Follow(watch::Receiver<Option<Landed>>),
    /// Another action is in flight for the run.
    Busy(JobAction),
}

/// The lead's hold on its run's entry. Dropped without landing, as by a panic or the runtime's end, the entry goes and
/// the requests waiting see the channel close.
pub(super) struct Landing {
    flights: Arc<Flights>,
    key: RunKey,
    id: u64,
}

impl Flights {
    /// Confirmations that last `lasts`.
    pub(super) fn new(lasts: Duration) -> Flights {
        Flights {
            lasts,
            book: Mutex::new(Book {
                issued: HashMap::new(),
                runs: HashMap::new(),
                next_flight: 0,
            }),
        }
    }

    /// A new confirmation for `issued`, at `now`.
    pub(super) fn issue(&self, issued: Issued, now: Instant) -> io::Result<String> {
        let token = token()?;
        lock(&self.book).issue(token.clone(), issued, now, self.lasts);
        Ok(token)
    }

    /// Takes `token` for `action` from `job`, under the config revision `revision`, at `now`.
    pub(super) fn redeem(
        self: &Arc<Flights>,
        token: &str,
        action: JobAction,
        job: u64,
        revision: u64,
        now: Instant,
    ) -> Redeemed {
        let mut book = lock(&self.book);
        book.forget(now, self.lasts);
        match book.redeem(token, Asked { action, job }, revision) {
            Taken::Stale(why) => Redeemed::Stale(why),
            Taken::Follow { answer, issued } => Redeemed::Board {
                boarding: Boarding::Follow(answer),
                issued,
            },
            Taken::Busy { other, issued } => Redeemed::Board {
                boarding: Boarding::Busy(other),
                issued,
            },
            Taken::Lead {
                key,
                id,
                answer,
                issued,
            } => Redeemed::Board {
                boarding: Boarding::Lead {
                    landing: Landing {
                        flights: self.clone(),
                        key,
                        id,
                    },
                    answer,
                },
                issued,
            },
        }
    }

    /// Boards `issued` without a confirmation, for an action runnerd sends itself (ADR 0153): it leads a new flight,
    /// follows the same automatic action from the same job in flight, or is busy behind another one or an owner's.
    pub(super) fn board(self: &Arc<Flights>, issued: &Issued) -> Boarding {
        let target = &issued.target;
        let key = RunKey {
            repository: target.repository.clone(),
            run: target.run,
        };
        let asked = Asked {
            action: target.action,
            job: target.job,
        };
        match lock(&self.book).board(key.clone(), asked) {
            Joined::Follow(answer) => Boarding::Follow(answer),
            Joined::Busy(other) => Boarding::Busy(other),
            Joined::Lead { id, answer } => Boarding::Lead {
                landing: Landing {
                    flights: self.clone(),
                    key,
                    id,
                },
                answer,
            },
        }
    }

    /// How many runs have an action in flight.
    #[cfg(test)]
    pub(super) fn len(&self) -> usize {
        lock(&self.book).runs.len()
    }

    /// How many requests wait for a flight's answer.
    #[cfg(test)]
    pub(super) fn waiting(&self) -> usize {
        lock(&self.book)
            .runs
            .values()
            .map(|flight| flight.answer.receiver_count())
            .sum()
    }
}

/// What [`Book::redeem`] did.
enum Taken {
    Stale(Superseded),
    Follow {
        answer: watch::Receiver<Option<Landed>>,
        issued: Issued,
    },
    Busy {
        other: JobAction,
        issued: Issued,
    },
    Lead {
        key: RunKey,
        id: u64,
        answer: watch::Receiver<Option<Landed>>,
        issued: Issued,
    },
}

/// What [`Book::board`] did.
enum Joined {
    Follow(watch::Receiver<Option<Landed>>),
    Busy(JobAction),
    Lead {
        id: u64,
        answer: watch::Receiver<Option<Landed>>,
    },
}

impl Book {
    /// Joins the automatic flight of `key` for `asked`, or starts one; an owner's flight, whatever it asks, is busy, so
    /// its outcome is never taken for runnerd's own.
    fn board(&mut self, key: RunKey, asked: Asked) -> Joined {
        match self.runs.get(&key) {
            Some(flight) if flight.asked == asked && flight.origin == Origin::Automatic => {
                Joined::Follow(flight.answer.subscribe())
            }
            Some(flight) => Joined::Busy(flight.asked.action),
            None => {
                let id = self.next_flight;
                self.next_flight += 1;
                let (answer, receiver) = watch::channel(None);
                self.runs.insert(
                    key,
                    Flight {
                        id,
                        asked,
                        origin: Origin::Automatic,
                        answer,
                    },
                );
                Joined::Lead {
                    id,
                    answer: receiver,
                }
            }
        }
    }

    fn issue(&mut self, token: String, issued: Issued, now: Instant, lasts: Duration) {
        self.forget(now, lasts);
        while self.issued.len() >= ISSUED_MAX {
            let oldest = self
                .issued
                .iter()
                .min_by_key(|(_, confirmation)| confirmation.at)
                .map(|(token, _)| token.clone());
            match oldest {
                Some(oldest) => self.issued.remove(&oldest),
                None => break,
            };
        }
        self.issued.insert(
            token,
            Confirmation {
                issued,
                at: now,
                used: Use::Open,
            },
        );
    }

    /// Drops the confirmations issued more than `lasts` before `now`.
    fn forget(&mut self, now: Instant, lasts: Duration) {
        self.issued
            .retain(|_, confirmation| now.saturating_duration_since(confirmation.at) < lasts);
    }

    fn redeem(&mut self, token: &str, asked: Asked, revision: u64) -> Taken {
        let Some(confirmation) = self.issued.get(token) else {
            return Taken::Stale(Superseded::Unknown);
        };
        let issued = confirmation.issued.clone();
        let target = &issued.target;
        if target.action != asked.action || target.job != asked.job {
            return Taken::Stale(Superseded::OtherRequest);
        }
        let key = RunKey {
            repository: target.repository.clone(),
            run: target.run,
        };
        let flight = self.runs.get(&key);
        if let Use::Boarded(boarded) = confirmation.used {
            return match flight {
                Some(flight) if flight.id == boarded => Taken::Follow {
                    answer: flight.answer.subscribe(),
                    issued,
                },
                _ => Taken::Stale(Superseded::Used),
            };
        }
        if issued.revision != revision {
            self.issued.remove(token);
            return Taken::Stale(Superseded::ConfigChanged);
        }
        let joined = match flight {
            Some(flight) if flight.asked == asked => (flight.id, flight.answer.subscribe()),
            Some(flight) => {
                // Not taken: it holds once the other action landed.
                return Taken::Busy {
                    other: flight.asked.action,
                    issued,
                };
            }
            None => {
                let id = self.next_flight;
                self.next_flight += 1;
                let (answer, receiver) = watch::channel(None);
                self.runs.insert(
                    key.clone(),
                    Flight {
                        id,
                        asked,
                        origin: Origin::Owner,
                        answer,
                    },
                );
                if let Some(confirmation) = self.issued.get_mut(token) {
                    confirmation.used = Use::Boarded(id);
                }
                return Taken::Lead {
                    key,
                    id,
                    answer: receiver,
                    issued,
                };
            }
        };
        let (id, answer) = joined;
        if let Some(confirmation) = self.issued.get_mut(token) {
            confirmation.used = Use::Boarded(id);
        }
        Taken::Follow { answer, issued }
    }

    /// Gives the requests waiting for flight `id` its answer.
    fn answer(&self, key: &RunKey, id: u64, landed: Landed) {
        if let Some(flight) = self.runs.get(key).filter(|flight| flight.id == id) {
            flight.answer.send_replace(Some(landed));
        }
    }

    /// Takes flight `id` out: a later request sends anew, and its confirmations are used.
    fn remove(&mut self, key: &RunKey, id: u64) {
        if self.runs.get(key).is_some_and(|flight| flight.id == id) {
            self.runs.remove(key);
        }
    }
}

impl Landing {
    /// Gives every request waiting the answer, and takes the run's entry out.
    pub(super) fn land(self, landed: Landed) {
        lock(&self.flights.book).answer(&self.key, self.id, landed);
    }
}

impl Drop for Landing {
    fn drop(&mut self) {
        lock(&self.flights.book).remove(&self.key, self.id);
    }
}

/// 128 random bits, in hex: a confirmation no one can guess.
fn token() -> io::Result<String> {
    let mut bytes = [0u8; 16];
    std::fs::File::open("/dev/urandom")?.read_exact(&mut bytes)?;
    Ok(bytes
        .iter()
        .fold(String::with_capacity(32), |mut hex, byte| {
            // Writing to a `String` cannot fail.
            let _ = write!(hex, "{byte:02x}");
            hex
        }))
}