OXYGENHUB
# 59078d2b8d46 oxygenflow / crates / flow-core / src / api.rs
2.9 KiB · Rust · last changed Runners sign their receipts 1 month ago source blame history raw
e0918b88 Andy McCall 1 
//! The runner API between OxygenHub and `flow runner` (docs/m0.md §5).
2 
//! Both sides use these types, so they cannot drift.
3
4 
use crate::pipeline::{Job, Sandbox};
5 
use crate::receipt::Receipt;
6 
use serde::{Deserialize, Serialize};
7
8 
/// `POST /api/v1/flow/claim`.
9 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
10 
pub struct ClaimRequest {
11 
    /// The runner's name, shown on job pages.
12 
    pub runner: String,
13 
    /// Tiers this runner can run (`microvm`, `syscall`).
14 
    pub runtimes: Vec<String>,
bb643c25 Andy McCall ↶ 15 
    /// Memory the runner has free for another job, in MiB: the hub hands
16 
    /// out only a job whose sandbox fits. Absent: no limit.
17 
    #[serde(default, skip_serializing_if = "Option::is_none")]
18 
    pub free_memory_mib: Option<u32>,
19 
    /// vCPUs the runner has free for another job. Absent: no limit.
20 
    #[serde(default, skip_serializing_if = "Option::is_none")]
21 
    pub free_cpus: Option<u32>,
e0918b88 Andy McCall 22 
}
23
24 
/// A claimed job: everything the runner needs, nothing more.
25 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
26 
pub struct Claim {
27 
    pub job_id: i64,
28 
    pub run_id: i64,
29 
    /// `owner/name`.
30 
    pub repo: String,
31 
    /// Where to fetch the repository from (`oxy` wire protocol).
32 
    pub clone_url: String,
33 
    /// Read access to this repository only, until the job finishes.
34 
    pub token: String,
35 
    /// The state to build, as full change hashes.
36 
    pub heads: Vec<String>,
37 
    /// Hex BLAKE3 of the canonical pipeline.
38 
    pub pipeline_hash: String,
39 
    pub job: Job,
40 
    pub sandbox: Sandbox,
41 
    /// The hub's limit for this job.
42 
    pub timeout_s: u64,
43 
}
44
45 
/// One line of output (docs/m0.md §2).
46 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
47 
pub struct Record {
48 
    /// Milliseconds since the job started.
49 
    pub t: u64,
50 
    /// `out`, `err`, `console` (the VM outside the job) or `flow` (the runner).
51 
    pub stream: String,
52 
    pub text: String,
53 
}
54
55 
/// `POST /api/v1/flow/jobs/{id}/log`.
56 
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
57 
pub struct LogBatch {
58 
    pub records: Vec<Record>,
59 
}
60
61 
/// `POST /api/v1/flow/jobs/{id}/finish`.
62 
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
63 
pub struct Finish {
64 
    /// The job's exit code; absent when the runner could not run it.
65 
    pub exit_code: Option<i32>,
66 
    pub duration_ms: u64,
67 
    pub receipt: Option<Receipt>,
47c1d64d Andy McCall ↶ 68 
    /// The receipt bound to the job's state and signed by the runner
69 
    /// (Oxygen spec §14.6), hex of the signed receipt's bytes.
70 
    #[serde(default, skip_serializing_if = "Option::is_none")]
71 
    pub signed_receipt: Option<String>,
e0918b88 Andy McCall 72 
    /// Why the runner could not run the job (rootfs missing, VM failed).
73 
    pub error: Option<String>,
74 
}
75
76 
/// Longest text of one record the hub keeps; longer lines are cut.
77 
pub const MAX_RECORD_TEXT: usize = 16 * 1024;
78 
/// Most records the hub keeps per job; later ones are dropped with a note.
79 
pub const MAX_RECORDS: usize = 50_000;