kernel/event/record/
provider.rs

1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4// Copyright (c) 2026 2youg1 and the sprawling contributors
5
6//! `provider_degraded`: something this city leans on answered less than
7//! it should, and the line says which of two things that was.
8
9use serde::{Deserialize, Serialize};
10
11use crate::error::AxError;
12
13/// `provider_degraded` has two writers with two shapes.
14///
15/// The carrier table in `kernel::error` sends `E_PROVIDER` here, written
16/// as the error itself; the vault's startup probe writes its fallback to
17/// session memory. A reader tells them apart by reading, not by guessing
18/// from a key, and a line that is neither does not read.
19#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
20#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
21#[serde(untagged)]
22pub enum ProviderDegraded {
23    /// A provider refused a call; this is the refusal, flat.
24    Refused(AxError),
25    /// The platform credential service failed its startup round trip.
26    VaultFellBack(VaultFellBack),
27}
28
29/// Tries the refusal, then the fallback, and when neither reads names
30/// what each shape missed: a derived untagged enum reports only that no
31/// variant matched, which leaves the reader of an unreadable line without
32/// the field to look at.
33impl<'de> Deserialize<'de> for ProviderDegraded {
34    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
35        let line = serde_json::Value::deserialize(deserializer)?;
36        AxError::deserialize(&line)
37            .map(Self::Refused)
38            .or_else(|as_refusal| {
39                VaultFellBack::deserialize(&line)
40                    .map(Self::VaultFellBack)
41                    .map_err(|as_fallback| {
42                        serde::de::Error::custom(format!(
43                            "neither a provider refusal ({as_refusal}) nor a vault fallback                              ({as_fallback})"
44                        ))
45                    })
46            })
47    }
48}
49
50/// The vault's fallback, as the startup probe writes it.
51#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
52#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
53pub struct VaultFellBack {
54    /// Which part degraded; the probe writes `vault`.
55    pub component: String,
56    /// Where credentials rest instead; the probe writes `session-memory`.
57    pub fallback: String,
58    /// `gateway::Persistence` in its own spelling.
59    pub persistence: String,
60    /// Why the platform service was not used.
61    pub reason: String,
62}
63
64#[cfg(test)]
65#[allow(clippy::unwrap_used, reason = "test code")]
66mod tests {
67    use super::*;
68    use crate::event::Payload;
69
70    #[test]
71    fn a_vault_line_keeps_the_bytes_its_ledger_already_holds() {
72        let line = r#"{"component":"vault","fallback":"session-memory","persistence":"this-process","reason":"probe reference unparsable"}"#;
73        let read: ProviderDegraded = serde_json::from_str::<Payload>(line)
74            .unwrap()
75            .read()
76            .unwrap();
77        assert!(matches!(read, ProviderDegraded::VaultFellBack(_)));
78        assert_eq!(
79            serde_json::to_string(&Payload::of(&read).unwrap()).unwrap(),
80            line
81        );
82    }
83
84    #[test]
85    fn a_line_that_is_neither_shape_names_what_each_shape_missed() {
86        let line = r#"{"code":"E_PROVIDER","component":"vault"}"#;
87        let err = serde_json::from_str::<Payload>(line)
88            .unwrap()
89            .read::<ProviderDegraded>()
90            .unwrap_err()
91            .to_string();
92        assert!(
93            err.contains("missing field `action`") && err.contains("missing field `fallback`"),
94            "{err}"
95        );
96    }
97}
kernel/event/record/provider.rs

kernel/event/record/
provider.rs
