canonical.rs 99.2%

121 of 122 lines run, 24 of 52 functions · run #195 on main · run missed

//! The canonical job graph (spec §3.2) and object hashes. Pipelines,
//! jobs and receipts are encoded with Oxygen's deterministic CBOR profile
//! (Oxygen spec §5.1: unsigned integer map keys in order) and hashed the
//! way Oxygen hashes objects: `BLAKE3("oxy1 " || type || " " || len || 0x00 || body)`.

use crate::pipeline::{Job, Pipeline, Sandbox};
use oxy_core::cbor::{encode, Value};

/// A 32-byte object reference, shown as hex.
pub type Hash = [u8; 32];

/// Oxygen's object hash construction for a Flow object type.
pub fn object_hash(ty: &str, body: &[u8]) -> Hash {
    let mut h = blake3::Hasher::new();
    h.update(format!("oxy1 {ty} {}\0", body.len()).as_bytes());
    h.update(body);
    *h.finalize().as_bytes()
}

fn text(s: &str) -> Value {
    Value::Text(s.to_string())
}

fn texts(v: &[String]) -> Value {
    Value::Array(v.iter().map(|s| text(s)).collect())
}

fn hex32(s: &str) -> Value {
    Value::Bytes(hex::decode(s).unwrap_or_default())
}

pub fn sandbox_value(s: &Sandbox) -> Value {
    let mut fields = vec![
        (0, text(&s.name)),
        (1, text(s.runtime.as_str())),
        (2, hex32(&s.rootfs)),
        (3, Value::Uint(s.memory_mib as u64)),
        (4, Value::Uint(s.cpus as u64)),
        (5, text(s.network.as_str())),
    ];
    // Environment as sorted [name, value] pairs; absent when empty, so
    // sandboxes without one hash as before.
    if !s.env.is_empty() {
        fields.push((6, Value::Array(s.env.iter().map(|(k, v)| Value::Array(vec![text(k), text(v)])).collect())));
    }
    // The architecture asked for; absent when the image decides.
    if let Some(a) = &s.arch {
        fields.push((7, text(a)));
    }
    // The hosts egress may reach, sorted; absent without egress.
    if !s.egress_allow.is_empty() {
        fields.push((8, texts(&s.egress_allow)));
    }
    Value::map(fields)
}

pub fn job_value(j: &Job) -> Value {
    let mut fields = vec![
        (0, text(&j.name)),
        (1, text(&j.sandbox)),
        (2, texts(&j.scope)),
        (3, texts(&j.depends_on)),
        // Environment as sorted [name, value] pairs: the profile has integer map keys only.
        (4, Value::Array(j.env.iter().map(|(k, v)| Value::Array(vec![text(k), text(v)])).collect())),
        (5, texts(&j.exec)),
    ];
    // Mounts as [source, target, size MiB] sorted by target; absent when
    // there are none, so jobs without mounts hash as before.
    if !j.mounts.is_empty() {
        fields.push((
            6,
            Value::Array(
                j.mounts
                    .iter()
                    .map(|m| {
                        // A cache mount adds its name and key files; a plain
                        // one encodes as before caches existed.
                        let mut v = vec![text(m.source.as_str()), text(&m.target), Value::Uint(m.size_mib as u64)];
                        if let Some(c) = &m.cache {
                            v.push(text(c));
                            v.push(Value::Array(m.key.iter().map(|k| text(k)).collect()));
                        }
                        Value::Array(v)
                    })
                    .collect(),
            ),
        ));
    }
    // Outputs as [name, path] sorted by name, a report's with "report"
    // after them; absent when there are none.
    if !j.outputs.is_empty() {
        let output = |o: &crate::pipeline::Output| {
            let mut v = vec![text(&o.name), text(&o.path)];
            if !o.kind.is_artifact() {
                v.push(text(o.kind.word()));
            }
            Value::Array(v)
        };
        fields.push((7, Value::Array(j.outputs.iter().map(output).collect())));
    }
    // Secrets as [name, mount path] sorted by name; absent when there are none.
    if !j.secrets.is_empty() {
        fields.push((8, Value::Array(j.secrets.iter().map(|s| Value::Array(vec![text(&s.name), text(&s.mount_path)])).collect())));
    }
    // Identities as [audience, mount path] sorted by audience; absent when none.
    if !j.identities.is_empty() {
        fields.push((9, Value::Array(j.identities.iter().map(|i| Value::Array(vec![text(&i.audience), text(&i.mount_path)])).collect())));
    }
    // Inputs as [artifact, from, path] sorted by path; absent when none.
    // Approval as [by, others-only, expires seconds]; absent without one.
    if let Some(a) = &j.approval {
        fields.push((11, Value::Array(vec![text(&a.by), Value::Bool(a.others_only), Value::Uint(a.expires_s), Value::Bool(a.sealed)])));
    }
    // The environment it deploys to; absent without one.
    if let Some(e) = &j.environment {
        fields.push((12, text(e)));
    }
    if !j.inputs.is_empty() {
        fields.push((
            10,
            Value::Array(j.inputs.iter().map(|i| Value::Array(vec![text(&i.artifact), text(&i.from), text(&i.path)])).collect()),
        ));
    }
    Value::map(fields)
}

impl Pipeline {
    /// The canonical CBOR job graph: sandboxes and jobs in name order.
    pub fn canonical(&self) -> Vec<u8> {
        encode(&Value::map([
            (0, Value::Uint(self.schema_version as u64)),
            (1, Value::Array(self.sandboxes.values().map(sandbox_value).collect())),
            (2, Value::Array(self.jobs.values().map(job_value).collect())),
        ]))
    }

    /// `pipeline_hash` of receipts and provenance.
    pub fn hash(&self) -> Hash {
        object_hash("pipeline", &self.canonical())
    }
}

impl Job {
    /// `Hash(J)` of spec §6.2: the job with its sandbox, so a change to
    /// either is a different job.
    pub fn hash(&self, sandbox: &Sandbox) -> Hash {
        object_hash("job", &encode(&Value::Array(vec![job_value(self), sandbox_value(sandbox)])))
    }
}

/// BLAKE3 tree hash of the files a scope selects (spec §6.2): sorted
/// `(path, content hash)` pairs. An empty scope selects every file.
pub fn scope_tree_hash<'a>(scope: &[String], files: impl IntoIterator<Item = (&'a str, Hash)>) -> Hash {
    let set = {
        let mut b = globset::GlobSetBuilder::new();
        for g in scope {
            if let Ok(g) = globset::Glob::new(g) {
                b.add(g);
            }
        }
        b.build().unwrap_or_else(|_| globset::GlobSet::empty())
    };
    let mut picked: Vec<(&str, Hash)> = files.into_iter().filter(|(p, _)| scope.is_empty() || set.is_match(p)).collect();
    picked.sort();
    let body = encode(&Value::Array(picked.iter().map(|(p, h)| Value::Array(vec![text(p), Value::Bytes(h.to_vec())])).collect()));
    object_hash("scope", &body)
}

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	47×	pub fn object_hash(ty: &str, body: &[u8]) -> Hash {
14	47×	let mut h = blake3::Hasher::new();
15	47×	h.update(format!("oxy1 {ty} {}\0", body.len()).as_bytes());
16	47×	h.update(body);
17	47×	*h.finalize().as_bytes()
18	47×	}
19
20	386×	fn text(s: &str) -> Value {
21	386×	Value::Text(s.to_string())
22	386×	}
23
24	155×	fn texts(v: &[String]) -> Value {
25	155×	Value::Array(v.iter().map(\|s\| text(s)).collect())
26	155×	}
27
28	42×	fn hex32(s: &str) -> Value {
29	42×	Value::Bytes(hex::decode(s).unwrap_or_default())
30	42×	}
31
32	42×	pub fn sandbox_value(s: &Sandbox) -> Value {
33	42×	let mut fields = vec![
34	42×	(0, text(&s.name)),
35	42×	(1, text(s.runtime.as_str())),
36	42×	(2, hex32(&s.rootfs)),
37	42×	(3, Value::Uint(s.memory_mib as u64)),
38	42×	(4, Value::Uint(s.cpus as u64)),
39	42×	(5, text(s.network.as_str())),
40		];
41		// Environment as sorted [name, value] pairs; absent when empty, so
42		// sandboxes without one hash as before.
43	42×	if !s.env.is_empty() {
44	2×	fields.push((6, Value::Array(s.env.iter().map(\|(k, v)\| Value::Array(vec![text(k), text(v)])).collect())));
45	41×	}
46		// The architecture asked for; absent when the image decides.
47	42×	if let Some(a) = &s.arch {
48	1×	fields.push((7, text(a)));
49	41×	}
50		// The hosts egress may reach, sorted; absent without egress.
51	42×	if !s.egress_allow.is_empty() {
52	2×	fields.push((8, texts(&s.egress_allow)));
53	40×	}
54	42×	Value::map(fields)
55	42×	}
56
57	51×	pub fn job_value(j: &Job) -> Value {
58	51×	let mut fields = vec![
59	51×	(0, text(&j.name)),
60	51×	(1, text(&j.sandbox)),
61	51×	(2, texts(&j.scope)),
62	51×	(3, texts(&j.depends_on)),
63		// Environment as sorted [name, value] pairs: the profile has integer map keys only.
64	51×	(4, Value::Array(j.env.iter().map(\|(k, v)\| Value::Array(vec![text(k), text(v)])).collect())),
65	51×	(5, texts(&j.exec)),
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	51×	if !j.mounts.is_empty() {
70	9×	fields.push((
71		6,
72		Value::Array(
73	9×	j.mounts
74	9×	.iter()
75	14×	.map(\|m\| {
76		// A cache mount adds its name and key files; a plain
77		// one encodes as before caches existed.
78	14×	let mut v = vec![text(m.source.as_str()), text(&m.target), Value::Uint(m.size_mib as u64)];
79	14×	if let Some(c) = &m.cache {
80	3×	v.push(text(c));
81	4×	v.push(Value::Array(m.key.iter().map(\|k\| text(k)).collect()));
82	11×	}
83	14×	Value::Array(v)
84	14×	})
85	9×	.collect(),
86		),
87		));
88	42×	}
89		// Outputs as [name, path] sorted by name, a report's with "report"
90		// after them; absent when there are none.
91	51×	if !j.outputs.is_empty() {
92	8×	let output = \|o: &crate::pipeline::Output\| {
93	8×	let mut v = vec![text(&o.name), text(&o.path)];
94	8×	if !o.kind.is_artifact() {
95	3×	v.push(text(o.kind.word()));
96	5×	}
97	8×	Value::Array(v)
98	8×	};
99	5×	fields.push((7, Value::Array(j.outputs.iter().map(output).collect())));
100	46×	}
101		// Secrets as [name, mount path] sorted by name; absent when there are none.
102	51×	if !j.secrets.is_empty() {
103	3×	fields.push((8, Value::Array(j.secrets.iter().map(\|s\| Value::Array(vec![text(&s.name), text(&s.mount_path)])).collect())));
104	49×	}
105		// Identities as [audience, mount path] sorted by audience; absent when none.
106	51×	if !j.identities.is_empty() {
107	2×	fields.push((9, Value::Array(j.identities.iter().map(\|i\| Value::Array(vec![text(&i.audience), text(&i.mount_path)])).collect())));
108	50×	}
109		// Inputs as [artifact, from, path] sorted by path; absent when none.
110		// Approval as [by, others-only, expires seconds]; absent without one.
111	51×	if let Some(a) = &j.approval {
112	4×	fields.push((11, Value::Array(vec![text(&a.by), Value::Bool(a.others_only), Value::Uint(a.expires_s), Value::Bool(a.sealed)])));
113	47×	}
114		// The environment it deploys to; absent without one.
115	51×	if let Some(e) = &j.environment {
116	1×	fields.push((12, text(e)));
117	50×	}
118	51×	if !j.inputs.is_empty() {
119	1×	fields.push((
120		10,
121	1×	Value::Array(j.inputs.iter().map(\|i\| Value::Array(vec![text(&i.artifact), text(&i.from), text(&i.path)])).collect()),
122		));
123	50×	}
124	51×	Value::map(fields)
125	51×	}
126
127		impl Pipeline {
128		/// The canonical CBOR job graph: sandboxes and jobs in name order.
129	34×	pub fn canonical(&self) -> Vec<u8> {
130	34×	encode(&Value::map([
131	34×	(0, Value::Uint(self.schema_version as u64)),
132	34×	(1, Value::Array(self.sandboxes.values().map(sandbox_value).collect())),
133	34×	(2, Value::Array(self.jobs.values().map(job_value).collect())),
134	34×	]))
135	34×	}
136
137		/// `pipeline_hash` of receipts and provenance.
138	30×	pub fn hash(&self) -> Hash {
139	30×	object_hash("pipeline", &self.canonical())
140	30×	}
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	8×	pub fn hash(&self, sandbox: &Sandbox) -> Hash {
147	8×	object_hash("job", &encode(&Value::Array(vec![job_value(self), sandbox_value(sandbox)])))
148	8×	}
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	5×	pub fn scope_tree_hash<'a>(scope: &[String], files: impl IntoIterator<Item = (&'a str, Hash)>) -> Hash {
154	5×	let set = {
155	5×	let mut b = globset::GlobSetBuilder::new();
156	5×	for g in scope {
157	3×	if let Ok(g) = globset::Glob::new(g) {
158	3×	b.add(g);
159	3×	}
160		}
161	5×	b.build().unwrap_or_else(\|_\| globset::GlobSet::empty())
162		};
163	8×	let mut picked: Vec<(&str, Hash)> = files.into_iter().filter(\|(p, _)\| scope.is_empty() \|\| set.is_match(p)).collect();
164	5×	picked.sort();
165	5×	let body = encode(&Value::Array(picked.iter().map(\|(p, h)\| Value::Array(vec![text(p), Value::Bytes(h.to_vec())])).collect()));
166	5×	object_hash("scope", &body)
167	5×	}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

Coverage / crates/flow-core/src/canonical.rs 99.2%

Keyboard