OXYGENHUB
◆ main oxygenflow / crates / flow-core / src / canonical.rs
6.4 KiB · Rust · last changed Sealed approvals: approval { sealed } and the oxygen pin 19 days ago source blame history raw
e0918b88 Andy McCall 1
//! The canonical job graph (spec §3.2) and object hashes. Pipelines,
2
//! jobs and receipts are encoded with Oxygen's deterministic CBOR profile
3
//! (Oxygen spec §5.1: unsigned integer map keys in order) and hashed the
4
//! way Oxygen hashes objects: `BLAKE3("oxy1 " || type || " " || len || 0x00 || body)`.
5
6
use crate::pipeline::{Job, Pipeline, Sandbox};
7
use oxy_core::cbor::{encode, Value};
8
9
/// A 32-byte object reference, shown as hex.
10
pub type Hash = [u8; 32];
11
12
/// Oxygen's object hash construction for a Flow object type.
13
pub fn object_hash(ty: &str, body: &[u8]) -> Hash {
14
    let mut h = blake3::Hasher::new();
15
    h.update(format!("oxy1 {ty} {}\0", body.len()).as_bytes());
16
    h.update(body);
17
    *h.finalize().as_bytes()
18
}
19
20
fn text(s: &str) -> Value {
21
    Value::Text(s.to_string())
22
}
23
24
fn texts(v: &[String]) -> Value {
25
    Value::Array(v.iter().map(|s| text(s)).collect())
26
}
27
28
fn hex32(s: &str) -> Value {
29
    Value::Bytes(hex::decode(s).unwrap_or_default())
30
}
31
32
pub fn sandbox_value(s: &Sandbox) -> Value {
a72abeee Andy McCall ↶ 33
    let mut fields = vec![
e0918b88 Andy McCall 34
        (0, text(&s.name)),
35
        (1, text(s.runtime.as_str())),
36
        (2, hex32(&s.rootfs)),
37
        (3, Value::Uint(s.memory_mib as u64)),
38
        (4, Value::Uint(s.cpus as u64)),
39
        (5, text(s.network.as_str())),
a72abeee Andy McCall ↶ 40
    ];
41
    // Environment as sorted [name, value] pairs; absent when empty, so
42
    // sandboxes without one hash as before.
43
    if !s.env.is_empty() {
44
        fields.push((6, Value::Array(s.env.iter().map(|(k, v)| Value::Array(vec![text(k), text(v)])).collect())));
45
    }
1abadd4a Andy McCall ↶ 46
    // The architecture asked for; absent when the image decides.
47
    if let Some(a) = &s.arch {
48
        fields.push((7, text(a)));
49
    }
ea81796b Andy McCall ↶ 50
    // The hosts egress may reach, sorted; absent without egress.
51
    if !s.egress_allow.is_empty() {
52
        fields.push((8, texts(&s.egress_allow)));
53
    }
a72abeee Andy McCall ↶ 54
    Value::map(fields)
e0918b88 Andy McCall 55
}
56
57
pub fn job_value(j: &Job) -> Value {
fc10d9e8 Andy McCall ↶ 58
    let mut fields = vec![
e0918b88 Andy McCall 59
        (0, text(&j.name)),
60
        (1, text(&j.sandbox)),
61
        (2, texts(&j.scope)),
62
        (3, texts(&j.depends_on)),
63
        // Environment as sorted [name, value] pairs: the profile has integer map keys only.
64
        (4, Value::Array(j.env.iter().map(|(k, v)| Value::Array(vec![text(k), text(v)])).collect())),
65
        (5, texts(&j.exec)),
fc10d9e8 Andy McCall ↶ 66
    ];
67
    // Mounts as [source, target, size MiB] sorted by target; absent when
68
    // there are none, so jobs without mounts hash as before.
69
    if !j.mounts.is_empty() {
70
        fields.push((
71
            6,
72
            Value::Array(
73
                j.mounts
74
                    .iter()
d60aac6c Andy McCall ↶ 75
                    .map(|m| {
76
                        // A cache mount adds its name and key files; a plain
77
                        // one encodes as before caches existed.
78
                        let mut v = vec![text(m.source.as_str()), text(&m.target), Value::Uint(m.size_mib as u64)];
79
                        if let Some(c) = &m.cache {
80
                            v.push(text(c));
81
                            v.push(Value::Array(m.key.iter().map(|k| text(k)).collect()));
82
                        }
83
                        Value::Array(v)
84
                    })
fc10d9e8 Andy McCall ↶ 85
                    .collect(),
86
            ),
87
        ));
88
    }
6d53fb7d Andy McCall ↶ 89
    // Outputs as [name, path] sorted by name, a report's with "report"
90
    // after them; absent when there are none.
a67b97e9 Andy McCall ↶ 91
    if !j.outputs.is_empty() {
6d53fb7d Andy McCall ↶ 92
        let output = |o: &crate::pipeline::Output| {
93
            let mut v = vec![text(&o.name), text(&o.path)];
94
            if !o.kind.is_artifact() {
95
                v.push(text(o.kind.word()));
96
            }
97
            Value::Array(v)
98
        };
99
        fields.push((7, Value::Array(j.outputs.iter().map(output).collect())));
a67b97e9 Andy McCall ↶ 100
    }
e2c12561 Andy McCall ↶ 101
    // Secrets as [name, mount path] sorted by name; absent when there are none.
102
    if !j.secrets.is_empty() {
103
        fields.push((8, Value::Array(j.secrets.iter().map(|s| Value::Array(vec![text(&s.name), text(&s.mount_path)])).collect())));
104
    }
720eb819 Andy McCall ↶ 105
    // Identities as [audience, mount path] sorted by audience; absent when none.
106
    if !j.identities.is_empty() {
107
        fields.push((9, Value::Array(j.identities.iter().map(|i| Value::Array(vec![text(&i.audience), text(&i.mount_path)])).collect())));
108
    }
46fe2c81 Andy McCall ↶ 109
    // Inputs as [artifact, from, path] sorted by path; absent when none.
e2089721 Andy McCall ↶ 110
    // Approval as [by, others-only, expires seconds]; absent without one.
111
    if let Some(a) = &j.approval {
2be1fe4a Andy McCall ↶ 112
        fields.push((11, Value::Array(vec![text(&a.by), Value::Bool(a.others_only), Value::Uint(a.expires_s), Value::Bool(a.sealed)])));
e2089721 Andy McCall ↶ 113
    }
f4e51e63 Andy McCall ↶ 114
    // The environment it deploys to; absent without one.
115
    if let Some(e) = &j.environment {
116
        fields.push((12, text(e)));
117
    }
46fe2c81 Andy McCall ↶ 118
    if !j.inputs.is_empty() {
119
        fields.push((
120
            10,
121
            Value::Array(j.inputs.iter().map(|i| Value::Array(vec![text(&i.artifact), text(&i.from), text(&i.path)])).collect()),
122
        ));
123
    }
fc10d9e8 Andy McCall ↶ 124
    Value::map(fields)
e0918b88 Andy McCall 125
}
126
127
impl Pipeline {
128
    /// The canonical CBOR job graph: sandboxes and jobs in name order.
129
    pub fn canonical(&self) -> Vec<u8> {
130
        encode(&Value::map([
131
            (0, Value::Uint(self.schema_version as u64)),
132
            (1, Value::Array(self.sandboxes.values().map(sandbox_value).collect())),
133
            (2, Value::Array(self.jobs.values().map(job_value).collect())),
134
        ]))
135
    }
136
137
    /// `pipeline_hash` of receipts and provenance.
138
    pub fn hash(&self) -> Hash {
139
        object_hash("pipeline", &self.canonical())
140
    }
141
}
142
143
impl Job {
144
    /// `Hash(J)` of spec §6.2: the job with its sandbox, so a change to
145
    /// either is a different job.
146
    pub fn hash(&self, sandbox: &Sandbox) -> Hash {
147
        object_hash("job", &encode(&Value::Array(vec![job_value(self), sandbox_value(sandbox)])))
148
    }
149
}
150
151
/// BLAKE3 tree hash of the files a scope selects (spec §6.2): sorted
152
/// `(path, content hash)` pairs. An empty scope selects every file.
153
pub fn scope_tree_hash<'a>(scope: &[String], files: impl IntoIterator<Item = (&'a str, Hash)>) -> Hash {
154
    let set = {
155
        let mut b = globset::GlobSetBuilder::new();
156
        for g in scope {
157
            if let Ok(g) = globset::Glob::new(g) {
158
                b.add(g);
159
            }
160
        }
161
        b.build().unwrap_or_else(|_| globset::GlobSet::empty())
162
    };
163
    let mut picked: Vec<(&str, Hash)> = files.into_iter().filter(|(p, _)| scope.is_empty() || set.is_match(p)).collect();
164
    picked.sort();
165
    let body = encode(&Value::Array(picked.iter().map(|(p, h)| Value::Array(vec![text(p), Value::Bytes(h.to_vec())])).collect()));
166
    object_hash("scope", &body)
167
}