Skip to main content

services/
gates.rs

1//! `gates.*` (port of `ultron/release-gate.ts`): frozen release-gate definitions plus a recorded baseline-versus-
2//! candidate comparison. A gate definition is immutable once defined and is the only source of which checks exist
3//! and which are required; a run cannot introduce its own checks. Every comparison attempt, blocked or passed, is
4//! recorded before it is returned, with the digest of the definition it was judged against. A required check that
5//! regressed, or is not passed in the candidate, blocks; an optional regression is reported and does not block; a
6//! run on another fixture blocks. This module only records and decides; it never prompts.
7//!
8//! Requests (`release_gate_api.py`): `gates.define` `{id, checks, fixture_hash}`, `gates.compare`
9//! `{gate_id, baseline, candidate}`, `gates.history` `{gate_id}`, `gates.list` `{}`.
10
11use kernel::store::DocumentStore;
12use kernel_apis::store::read_versioned;
13use kernel_apis::util::Clock;
14use serde_json::{Map, Value, json};
15use std::sync::{Arc, Mutex};
16
17const MAX_CHECKS: usize = 256;
18const MAX_ATTEMPTS: usize = 4096;
19const DURABILITY_ERROR: &str = "Release gate store durability is uncertain; reopen the owner";
20const OUTCOMES: [&str; 3] = ["passed", "failed", "missing"];
21
22/// `/^[a-z][a-z0-9._-]{0,127}$/`.
23fn valid_id(value: &str) -> bool {
24    value.as_bytes().first().is_some_and(u8::is_ascii_lowercase)
25        && value.len() <= 128
26        && value
27            .bytes()
28            .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b"._-".contains(&b))
29}
30
31/// `/^[A-Za-z0-9][A-Za-z0-9 ._:/-]{0,127}$/`.
32fn valid_check(value: &str) -> bool {
33    value.as_bytes().first().is_some_and(u8::is_ascii_alphanumeric)
34        && value.len() <= 128
35        && value
36            .bytes()
37            .all(|b| b.is_ascii_alphanumeric() || b" ._:/-".contains(&b))
38}
39
40/// `/^[a-f0-9]{64}$/`.
41fn valid_hash(value: &str) -> bool {
42    value.len() == 64 && value.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))
43}
44
45/// `/^\S.{0,255}$/` in UTF-16 units: no leading space, no line terminator.
46fn valid_variant(value: &str) -> bool {
47    value.chars().next().is_some_and(|ch| !jsrt::string::is_space(ch))
48        && !value
49            .chars()
50            .any(|ch| matches!(ch, '\n' | '\r' | '\u{2028}' | '\u{2029}'))
51        && jsrt::utf16::len(value) <= 256
52}
53
54fn plain_object<'a>(value: Option<&'a Value>, name: &str) -> Result<&'a Map<String, Value>, String> {
55    value
56        .and_then(Value::as_object)
57        .ok_or_else(|| format!("{name} must be a JSON object"))
58}
59
60fn gate_id_field(value: Option<&Value>, name: &str) -> Result<String, String> {
61    match value.and_then(Value::as_str) {
62        Some(id) if valid_id(id) => Ok(id.into()),
63        _ => Err(format!("{name} must be a short lowercase identifier")),
64    }
65}
66
67fn hash_field(value: Option<&Value>, name: &str) -> Result<String, String> {
68    match value.and_then(Value::as_str) {
69        Some(hash) if valid_hash(hash) => Ok(hash.into()),
70        _ => Err(format!("{name} must be a lowercase SHA-256 hex string")),
71    }
72}
73
74/// `checksField`: 1 to 256 uniquely named checks, at least one required, sorted by name.
75fn checks_field(value: Option<&Value>) -> Result<Vec<(String, bool)>, String> {
76    let list = value
77        .and_then(Value::as_array)
78        .filter(|list| !list.is_empty() && list.len() <= MAX_CHECKS)
79        .ok_or_else(|| format!("checks must be a list of 1 to {MAX_CHECKS} entries"))?;
80    let mut checks: Vec<(String, bool)> = Vec::new();
81    for (index, item) in list.iter().enumerate() {
82        let entry = plain_object(Some(item), &format!("checks[{index}]"))?;
83        jsrt::payload::fields(entry, &["name", "required"])?;
84        let name = entry
85            .get("name")
86            .and_then(Value::as_str)
87            .filter(|name| valid_check(name))
88            .ok_or_else(|| format!("checks[{index}].name must be a check name of at most 128 characters"))?;
89        let required = entry
90            .get("required")
91            .and_then(Value::as_bool)
92            .ok_or_else(|| format!("checks[{index}].required must be a boolean"))?;
93        if checks.iter().any(|(seen, _)| seen == name) {
94            return Err(format!("Duplicate check name: {name}"));
95        }
96        checks.push((name.into(), required));
97    }
98    if !checks.iter().any(|(_, required)| *required) {
99        return Err("A gate needs at least one required check; a gate with none could never block".into());
100    }
101    checks.sort_by(|left, right| left.0.cmp(&right.0));
102    Ok(checks)
103}
104
105fn gate_digest(id: &str, checks: &[(String, bool)], fixture_hash: &str) -> String {
106    let checks: Vec<Value> = checks.iter().map(|(name, required)| json!([name, required])).collect();
107    jsrt::hash::sha256_hex(
108        jsrt::json::stringify(&json!({"id": id, "checks": checks, "fixture_hash": fixture_hash})).as_bytes(),
109    )
110}
111
112fn gate_checks(gate: &Value) -> Vec<(String, bool)> {
113    gate["checks"]
114        .as_array()
115        .into_iter()
116        .flatten()
117        .map(|check| {
118            (
119                check["name"].as_str().unwrap_or_default().to_string(),
120                check["required"].as_bool().unwrap_or(false),
121            )
122        })
123        .collect()
124}
125
126/// `runField`: `{variant, fixture_hash, results}` with every gate check present (absent ones `missing`).
127fn run_field(value: Option<&Value>, name: &str, gate: &Value) -> Result<Value, String> {
128    let run = plain_object(value, name)?;
129    if let Some(key) = run
130        .keys()
131        .find(|key| !["variant", "fixture_hash", "results"].contains(&key.as_str()))
132    {
133        return Err(format!(
134            "Unknown field {name}.{key}: a run is {{variant, fixture_hash, results: {{check: \"passed\" | \"failed\" | \"missing\"}}}}"
135        ));
136    }
137    let variant = run
138        .get("variant")
139        .and_then(Value::as_str)
140        .filter(|variant| valid_variant(variant))
141        .ok_or_else(|| format!("{name}.variant must be a nonempty string of at most 256 characters"))?;
142    let fixture_hash = hash_field(run.get("fixture_hash"), &format!("{name}.fixture_hash"))?;
143    let supplied = plain_object(run.get("results"), &format!("{name}.results"))?;
144    let checks = gate_checks(gate);
145    for (check, outcome) in supplied {
146        // The gate definition is the protected checker input: a run cannot introduce its own checks.
147        if !checks.iter().any(|(known, _)| known == check) {
148            return Err(format!(
149                "{name}.results names a check the gate does not define: {check}"
150            ));
151        }
152        if !outcome.as_str().is_some_and(|o| OUTCOMES.contains(&o)) {
153            return Err(format!("{name}.results.{check} must be passed, failed, or missing"));
154        }
155    }
156    let results: Map<String, Value> = checks
157        .iter()
158        .map(|(check, _)| {
159            (
160                check.clone(),
161                supplied.get(check).cloned().unwrap_or_else(|| json!("missing")),
162            )
163        })
164        .collect();
165    Ok(json!({"variant": variant, "fixture_hash": fixture_hash, "results": results}))
166}
167
168/// `judge`: the decision, its reasons, regressions and improvements.
169fn judge(gate: &Value, baseline: &Value, candidate: &Value) -> (bool, Vec<String>, Vec<Value>, Vec<Value>) {
170    let mut reasons = Vec::new();
171    let mut blocked = false;
172    let gate_hash = gate["fixture_hash"].as_str().unwrap_or_default();
173    for (label, run) in [("baseline", baseline), ("candidate", candidate)] {
174        let hash = run["fixture_hash"].as_str().unwrap_or_default();
175        if hash != gate_hash {
176            blocked = true;
177            reasons.push(format!(
178                "Fixture mismatch: {label} {} ran against {hash}, gate {} requires {gate_hash}",
179                run["variant"].as_str().unwrap_or_default(),
180                gate["id"].as_str().unwrap_or_default(),
181            ));
182        }
183    }
184    let (mut regressions, mut improvements) = (Vec::new(), Vec::new());
185    for (check, required) in gate_checks(gate) {
186        let before = baseline["results"][&check].as_str().unwrap_or("missing");
187        let after = candidate["results"][&check].as_str().unwrap_or("missing");
188        let change = json!({"check": check, "required": required, "baseline": before, "candidate": after});
189        if before == "passed" && after != "passed" {
190            regressions.push(change);
191            if required {
192                blocked = true;
193                reasons.push(format!(
194                    "Required check {check} regressed: passed in baseline, {after} in candidate"
195                ));
196            } else {
197                reasons.push(format!(
198                    "Optional check {check} regressed ({after}); reported, not blocking"
199                ));
200            }
201        } else if before != "passed" && after == "passed" {
202            improvements.push(change);
203        } else if required && after != "passed" {
204            blocked = true;
205            reasons.push(format!("Required check {check} is {after} in candidate"));
206        }
207    }
208    if !blocked {
209        reasons.insert(
210            0,
211            format!(
212                "Every required check passed in candidate {}",
213                candidate["variant"].as_str().unwrap_or_default()
214            ),
215        );
216    }
217    (blocked, reasons, regressions, improvements)
218}
219
220fn nonempty_string(value: Option<&Value>) -> bool {
221    value.and_then(Value::as_str).is_some_and(|text| !text.is_empty())
222}
223
224fn string_or_null(value: Option<&Value>) -> bool {
225    value.is_some_and(|v| v.is_null() || nonempty_string(Some(v)))
226}
227
228fn only(map: &Map<String, Value>, keys: &[&str]) -> bool {
229    map.keys().all(|key| keys.contains(&key.as_str()))
230}
231
232/// `gateSchema`.
233fn valid_gate(gate: &Value) -> bool {
234    let Some(map) = gate.as_object() else {
235        return false;
236    };
237    only(
238        map,
239        &["id", "checks", "fixture_hash", "digest", "defined_at", "defined_by"],
240    ) && ["id", "fixture_hash", "digest"]
241        .iter()
242        .all(|key| nonempty_string(map.get(*key)))
243        && map.get("defined_at").is_some_and(Value::is_number)
244        && string_or_null(map.get("defined_by"))
245        && map.get("checks").and_then(Value::as_array).is_some_and(|checks| {
246            checks.iter().all(|check| {
247                check.as_object().is_some_and(|check| {
248                    only(check, &["name", "required"])
249                        && nonempty_string(check.get("name"))
250                        && check.get("required").is_some_and(Value::is_boolean)
251                })
252            })
253        })
254}
255
256fn valid_outcome(value: Option<&Value>) -> bool {
257    value.and_then(Value::as_str).is_some_and(|o| OUTCOMES.contains(&o))
258}
259
260/// `runSchema`.
261fn valid_run(run: Option<&Value>) -> bool {
262    run.and_then(Value::as_object).is_some_and(|map| {
263        only(map, &["variant", "fixture_hash", "results"])
264            && nonempty_string(map.get("variant"))
265            && nonempty_string(map.get("fixture_hash"))
266            && map
267                .get("results")
268                .and_then(Value::as_object)
269                .is_some_and(|results| results.values().all(|o| valid_outcome(Some(o))))
270    })
271}
272
273/// `changeSchema`.
274fn valid_change(change: &Value) -> bool {
275    change.as_object().is_some_and(|map| {
276        only(map, &["check", "required", "baseline", "candidate"])
277            && map.get("check").is_some_and(Value::is_string)
278            && map.get("required").is_some_and(Value::is_boolean)
279            && valid_outcome(map.get("baseline"))
280            && valid_outcome(map.get("candidate"))
281    })
282}
283
284/// `attemptSchema`.
285fn valid_attempt(attempt: &Value) -> bool {
286    let Some(map) = attempt.as_object() else {
287        return false;
288    };
289    let changes = |key: &str| {
290        map.get(key)
291            .and_then(Value::as_array)
292            .is_some_and(|list| list.iter().all(valid_change))
293    };
294    only(
295        map,
296        &[
297            "id",
298            "gate_id",
299            "gate_digest",
300            "at",
301            "requester_task_id",
302            "baseline",
303            "candidate",
304            "decision",
305            "reasons",
306            "regressions",
307            "improvements",
308        ],
309    ) && ["id", "gate_id", "gate_digest"]
310        .iter()
311        .all(|key| nonempty_string(map.get(*key)))
312        && map.get("at").is_some_and(Value::is_number)
313        && string_or_null(map.get("requester_task_id"))
314        && valid_run(map.get("baseline"))
315        && valid_run(map.get("candidate"))
316        && map
317            .get("decision")
318            .and_then(Value::as_str)
319            .is_some_and(|d| d == "passed" || d == "blocked")
320        && map
321            .get("reasons")
322            .and_then(Value::as_array)
323            .is_some_and(|list| list.iter().all(Value::is_string))
324        && changes("regressions")
325        && changes("improvements")
326}
327
328/// `documentSchema`.
329fn valid_document(document: &Value) -> bool {
330    document.as_object().is_some_and(|map| {
331        only(map, &["version", "gates", "attempts"])
332            && map.get("version").and_then(Value::as_f64) == Some(1.0)
333            && map
334                .get("gates")
335                .and_then(Value::as_array)
336                .is_some_and(|gates| gates.iter().all(valid_gate))
337            && map
338                .get("attempts")
339                .and_then(Value::as_array)
340                .is_some_and(|attempts| attempts.iter().all(valid_attempt))
341    })
342}
343
344struct State {
345    document: Value,
346    /// The outcome of loading the stored document, kept as TS keeps its load promise.
347    loaded: Option<Result<(), String>>,
348    broken: bool,
349}
350
351/// The release-gate module over one durable document (`createReleaseGateModule`).
352pub struct ReleaseGateModule {
353    store: Arc<dyn DocumentStore>,
354    /// `None`: the host's clock.
355    now: Option<Clock>,
356    ids: Arc<dyn Fn() -> String + Send + Sync>,
357    state: Mutex<State>,
358}
359
360impl ReleaseGateModule {
361    pub fn new(store: Arc<dyn DocumentStore>, now: Option<Clock>) -> Self {
362        ReleaseGateModule {
363            store,
364            now,
365            ids: Arc::new(jsrt::random::uuid_v4),
366            state: Mutex::new(State {
367                document: json!({"version": 1, "gates": [], "attempts": []}),
368                loaded: None,
369                broken: false,
370            }),
371        }
372    }
373
374    /// Attempt ids from `ids` instead of random UUIDs (fixtures).
375    pub fn with_ids(mut self, ids: Arc<dyn Fn() -> String + Send + Sync>) -> Self {
376        self.ids = ids;
377        self
378    }
379
380    fn load(&self) -> Result<Value, String> {
381        let Some(saved) = read_versioned("ultron.module/release-gates", self.store.read()?, "version")? else {
382            return Ok(json!({"version": 1, "gates": [], "attempts": []}));
383        };
384        if !valid_document(&saved) {
385            return Err("Invalid release gate document".into());
386        }
387        for gate in saved["gates"].as_array().into_iter().flatten() {
388            let id = gate["id"].as_str().unwrap_or_default();
389            if gate["digest"]
390                != gate_digest(
391                    id,
392                    &gate_checks(gate),
393                    gate["fixture_hash"].as_str().unwrap_or_default(),
394                )
395            {
396                return Err(format!("Release gate {id} definition does not match its digest"));
397            }
398        }
399        Ok(saved)
400    }
401
402    /// The loaded state (`enqueue`): refused once a write failed; the stored document is read once.
403    fn ready<'a>(&self, state: &'a mut State) -> Result<&'a mut State, String> {
404        if state.broken {
405            return Err(DURABILITY_ERROR.into());
406        }
407        if state.loaded.is_none() {
408            state.loaded = Some(self.load().map(|document| state.document = document));
409        }
410        state.loaded.clone().unwrap_or(Ok(()))?;
411        Ok(state)
412    }
413
414    fn write(&self, state: &mut State, next: Value) -> Result<(), String> {
415        if self.store.write(&next).is_err() {
416            state.broken = true;
417            return Err(DURABILITY_ERROR.into());
418        }
419        state.document = next;
420        Ok(())
421    }
422
423    fn find_gate(document: &Value, id: &str) -> Result<Value, String> {
424        document["gates"]
425            .as_array()
426            .and_then(|gates| gates.iter().find(|gate| gate["id"] == id))
427            .cloned()
428            .ok_or_else(|| format!("Unknown release gate: {id}"))
429    }
430
431    /// Serves one `gates.*` request from `caller` (a task id, `None` for the root) at time `now`.
432    pub fn handle_at(
433        &self,
434        kind: &str,
435        payload: &Map<String, Value>,
436        caller: Option<&str>,
437        now: i64,
438    ) -> Result<Value, String> {
439        let now = self.now.as_ref().map_or(now, |clock| clock());
440        match kind {
441            "gates.define" => {
442                jsrt::payload::fields(payload, &["id", "checks", "fixture_hash"])?;
443                let id = gate_id_field(payload.get("id"), "id")?;
444                let checks = checks_field(payload.get("checks"))?;
445                let fixture_hash = hash_field(payload.get("fixture_hash"), "fixture_hash")?;
446                let digest = gate_digest(&id, &checks, &fixture_hash);
447                let mut guard = jsrt::sync::lock(&self.state);
448                let state = self.ready(&mut guard)?;
449                if let Ok(existing) = Self::find_gate(&state.document, &id) {
450                    if existing["digest"] != digest.as_str() {
451                        return Err(format!(
452                            "Release gate {id} is already defined with different content and cannot be changed"
453                        ));
454                    }
455                    return Ok(existing);
456                }
457                let checks: Vec<Value> = checks
458                    .iter()
459                    .map(|(name, required)| json!({"name": name, "required": required}))
460                    .collect();
461                let gate = json!({
462                    "id": id, "checks": checks, "fixture_hash": fixture_hash, "digest": digest,
463                    "defined_at": now, "defined_by": caller,
464                });
465                let mut next = state.document.clone();
466                if let Some(gates) = next["gates"].as_array_mut() {
467                    gates.push(gate.clone());
468                }
469                self.write(state, next)?;
470                Ok(gate)
471            }
472            "gates.compare" => {
473                jsrt::payload::fields(payload, &["gate_id", "baseline", "candidate"])?;
474                let gate_id = gate_id_field(payload.get("gate_id"), "gate_id")?;
475                let mut guard = jsrt::sync::lock(&self.state);
476                let state = self.ready(&mut guard)?;
477                if state.document["attempts"].as_array().map_or(0, Vec::len) >= MAX_ATTEMPTS {
478                    return Err(format!("Release gate history is full ({MAX_ATTEMPTS} attempts)"));
479                }
480                let gate = Self::find_gate(&state.document, &gate_id)?;
481                let baseline = run_field(payload.get("baseline"), "baseline", &gate)?;
482                let candidate = run_field(payload.get("candidate"), "candidate", &gate)?;
483                let (blocked, reasons, regressions, improvements) = judge(&gate, &baseline, &candidate);
484                let attempt = json!({
485                    "id": format!("gate-attempt-{}", (self.ids)()),
486                    "gate_id": gate["id"], "gate_digest": gate["digest"], "at": now, "requester_task_id": caller,
487                    "baseline": baseline, "candidate": candidate,
488                    "decision": if blocked { "blocked" } else { "passed" },
489                    "reasons": reasons, "regressions": regressions, "improvements": improvements,
490                });
491                let mut next = state.document.clone();
492                if let Some(attempts) = next["attempts"].as_array_mut() {
493                    attempts.push(attempt.clone());
494                }
495                self.write(state, next)?;
496                Ok(attempt)
497            }
498            "gates.history" => {
499                jsrt::payload::fields(payload, &["gate_id"])?;
500                let gate_id = gate_id_field(payload.get("gate_id"), "gate_id")?;
501                let mut guard = jsrt::sync::lock(&self.state);
502                let state = self.ready(&mut guard)?;
503                let gate = Self::find_gate(&state.document, &gate_id)?;
504                let attempts: Vec<Value> = state.document["attempts"]
505                    .as_array()
506                    .into_iter()
507                    .flatten()
508                    .filter(|attempt| attempt["gate_id"] == gate_id.as_str())
509                    .cloned()
510                    .collect();
511                Ok(json!({"gate": gate, "attempts": attempts}))
512            }
513            "gates.list" => {
514                jsrt::payload::fields(payload, &[])?;
515                let mut guard = jsrt::sync::lock(&self.state);
516                let state = self.ready(&mut guard)?;
517                Ok(json!({"gates": state.document["gates"]}))
518            }
519            _ => Err(format!("Unknown release gate request: {kind}")),
520        }
521    }
522}
523
524impl kernel_apis::ApiModule for ReleaseGateModule {
525    fn prefixes(&self) -> &[&str] {
526        &["gates."]
527    }
528
529    fn start(&self, _host: &dyn kernel_apis::TaskHost) -> Result<(), String> {
530        let mut guard = jsrt::sync::lock(&self.state);
531        self.ready(&mut guard).map(drop)
532    }
533
534    fn handle(&self, request: &kernel_apis::Request<'_>) -> Result<Value, String> {
535        self.handle_at(request.kind, request.payload, request.caller_task, request.host.now())
536    }
537}