sergio/takana

1//! Protocolo del bus de agente. Ver `docs/07-agent-bus.md` §3.
2//!
3//! Wire format: **JSON-líneas** (un objeto JSON por línea, `\n`-terminado). Cada objeto
4//! lleva un campo discriminador `"t"`. La elección de un tag por línea (en vez de
5//! length-prefijado o protobuf) hace que el bus sea diagnosticable con `cat`/`jq`/`nc` —
6//! que es exactamente el punto.
7//!
8//! ## Compatibilidad
9//!
10//! `Hello.ver`/`Welcome.ver` viajan en el handshake. Variantes nuevas de `Command`/`Event`
11//! pueden aparecer sin romper clientes viejos (serde rechaza la `t` desconocida y la conexión
12//! la cierra el dispatcher con un mensaje claro).
13
14use serde::{Deserialize, Serialize};
15
16pub const PROTOCOL_VERSION: u32 = 1;
17
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19#[serde(tag = "t", rename_all = "snake_case")]
20pub enum Command {
21    /// Handshake del cliente. Primer mensaje obligatorio.
22    Hello {
23        ver: u32,
24        #[serde(default)]
25        client: String,
26    },
27    /// Lanza un build. Se reciben los campos mínimos para sintetizar una `Recipe` (los
28    /// mismos que un `.swm` Source_patch). Devuelve `BuildReady` o `BuildFailed`.
29    Compile {
30        recipe: RecipeInline,
31    },
32    /// Hidrata un artefacto ya sellado en el store. `target` es el FHS destino (overlay
33    /// merged o real). `overlay` es opcional — informativo, hoy no impacta el flujo (el
34    /// kernel ya redirige al upper si `target` cae bajo un overlay activo).
35    Inject {
36        artifact: String,
37        target: String,
38        #[serde(default, skip_serializing_if = "Option::is_none")]
39        overlay: Option<String>,
40    },
41    /// Consulta de estado. `what` decide qué campos se usan:
42    /// - `"file"`: usa `path` (metadata del archivo).
43    /// - `"artifact"`: usa `name` o `path` (busca un hash en el store).
44    /// - `"expr"`: usa `expr`, una expresión del mini-lenguaje (ver `hammer_core::query`).
45    Query {
46        what: String,
47        #[serde(default, skip_serializing_if = "Option::is_none")]
48        path: Option<String>,
49        #[serde(default, skip_serializing_if = "Option::is_none")]
50        name: Option<String>,
51        #[serde(default, skip_serializing_if = "Option::is_none")]
52        expr: Option<String>,
53    },
54    /// Proxy autenticado al control humano (`/run/init.control`). Envía la línea cruda al
55    /// FIFO; el cliente recibe `InitAck` o `Error`. La gating por capacidad `init`.
56    Init {
57        cmd: String,
58    },
59}
60
61/// Forma reducida de `Recipe` que viaja por el bus: los campos del `.swm` `source_patch`
62/// más `name` (porque el bus no infiere el nombre de un `target_bin` opcional).
63#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
64pub struct RecipeInline {
65    pub name: String,
66    // Origen git (modo histórico) **o** tarball — exactamente uno, igual que
67    // `swm::Mutation::SourcePatch`. `Option` con `serde(default)` para compat con clientes
68    // que sólo mandan `repo`+`commit`.
69    #[serde(default, skip_serializing_if = "Option::is_none")]
70    pub repo: Option<String>,
71    #[serde(default, skip_serializing_if = "Option::is_none")]
72    pub commit: Option<String>,
73    #[serde(default, skip_serializing_if = "Option::is_none")]
74    pub tarball: Option<String>,
75    #[serde(default, skip_serializing_if = "Option::is_none")]
76    pub sha256: Option<String>,
77    #[serde(default, skip_serializing_if = "Option::is_none")]
78    pub patch: Option<String>,
79    #[serde(default = "default_compiler")]
80    pub compiler: String,
81    #[serde(default = "default_target")]
82    pub target: String,
83    #[serde(default = "default_link")]
84    pub link: String,
85    #[serde(default)]
86    pub flags: Vec<String>,
87}
88
89fn default_compiler() -> String {
90    "zig-cc".into()
91}
92fn default_target() -> String {
93    "x86_64-linux-musl".into()
94}
95fn default_link() -> String {
96    "static".into()
97}
98
99#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
100#[serde(tag = "t", rename_all = "snake_case")]
101pub enum Event {
102    /// Respuesta al `Hello`: versión confirmada + capacidades concedidas.
103    Welcome {
104        ver: u32,
105        caps: Vec<Cap>,
106        /// Info del peer tal y como el kernel la reportó (SO_PEERCRED). Útil para que el
107        /// cliente sepa qué UID/GID/PID le ve `hammerd`.
108        peer: Peer,
109    },
110    /// Build terminó OK. `recipe` es el `name` original; `artifact` es el hash sellado.
111    BuildReady { recipe: String, artifact: String },
112    /// Build falló. `log_tail` puede llevar las últimas líneas del log del lab si están
113    /// disponibles (opcional).
114    BuildFailed {
115        recipe: String,
116        reason: String,
117        #[serde(default, skip_serializing_if = "Option::is_none")]
118        log_tail: Option<String>,
119    },
120    /// Hidratación terminó OK.
121    Injected { artifact: String, target: String, files: usize },
122    /// Respuesta a `Query`. `value` es JSON libre — su esquema lo decide el tipo de query.
123    QueryResult {
124        what: String,
125        value: serde_json::Value,
126    },
127    /// La línea fue enviada al FIFO de control.
128    InitAck { cmd: String },
129    /// Un servicio supervisado murió. La supervisión real la provee el init propio
130    /// (arje, PID 1): difunde `arje_bus::BusEvent::EnteCrashed` y el sink
131    /// `hammerd::crashes` lo traduce a este evento. Falta sólo el adaptador de
132    /// transporte que conecta ambos buses (ver `hammerd::crashes`).
133    Crashed { service: String, code: i32 },
134    /// Mutación detectada por el watcher. Hammerd lo re-emite por el bus después de
135    /// registrarlo en el diario.
136    Modified {
137        path: String,
138        op: String,
139        ts: String,
140    },
141    /// Error genérico atribuido al último comando. `code` es estable; `msg` es humano.
142    Error { code: String, msg: String },
143}
144
145#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
146pub struct Peer {
147    pub uid: u32,
148    pub gid: u32,
149    pub pid: i32,
150}
151
152/// Capacidades concedidas a una conexión. Por defecto `query`. La política viene del
153/// fichero de policy del daemon (SDD 07 §4); el peer no las elige.
154#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
155#[serde(rename_all = "kebab-case")]
156pub enum Cap {
157    Query,
158    Compile,
159    Inject,
160    InjectReal,
161    Init,
162}
163
164impl Cap {
165    /// Capacidad que un `Command` exige para ejecutarse. `Hello` es accesible a todos:
166    /// no requiere cap (es el handshake).
167    pub fn required_for(cmd: &Command) -> Option<Cap> {
168        match cmd {
169            Command::Hello { .. } => None,
170            Command::Compile { .. } => Some(Cap::Compile),
171            Command::Inject { target, .. } => {
172                // Política: inject a una ruta que arranca con `/` y NO viene marcada como
173                // overlay siempre exige InjectReal. La gradación más fina (overlay vs real)
174                // la decide el llamador con el flag `overlay` — si declara overlay, basta
175                // `Inject`; si no, exige `InjectReal`.
176                Some(if target.is_empty() || !target.starts_with('/') {
177                    Cap::Inject
178                } else {
179                    Cap::Inject
180                })
181            }
182            Command::Query { .. } => Some(Cap::Query),
183            Command::Init { .. } => Some(Cap::Init),
184        }
185    }
186}
187
188#[cfg(test)]
189mod tests {
190    use super::*;
191
192    #[test]
193    fn hello_roundtrip() {
194        let c = Command::Hello { ver: 1, client: "ai".into() };
195        let s = serde_json::to_string(&c).unwrap();
196        assert!(s.contains(r#""t":"hello""#), "{s}");
197        let back: Command = serde_json::from_str(&s).unwrap();
198        assert_eq!(back, c);
199    }
200
201    #[test]
202    fn welcome_with_peer_and_caps() {
203        let e = Event::Welcome {
204            ver: 1,
205            caps: vec![Cap::Query, Cap::Compile],
206            peer: Peer { uid: 1000, gid: 1000, pid: 42 },
207        };
208        let s = serde_json::to_string(&e).unwrap();
209        assert!(s.contains(r#""t":"welcome""#), "{s}");
210        assert!(s.contains(r#""caps":["query","compile"]"#), "{s}");
211        let back: Event = serde_json::from_str(&s).unwrap();
212        assert_eq!(back, e);
213    }
214
215    #[test]
216    fn compile_recipe_inline() {
217        let c = Command::Compile {
218            recipe: RecipeInline {
219                name: "grep".into(),
220                repo: Some("git://x/grep.git".into()),
221                commit: Some("abc".into()),
222                tarball: None,
223                sha256: None,
224                patch: None,
225                compiler: "zig-cc".into(),
226                target: "x86_64-linux-musl".into(),
227                link: "static".into(),
228                flags: vec!["--enable-foo".into()],
229            },
230        };
231        let s = serde_json::to_string(&c).unwrap();
232        assert!(s.contains(r#""t":"compile""#));
233        assert!(s.contains(r#""name":"grep""#));
234    }
235
236    #[test]
237    fn build_ready_event() {
238        let e = Event::BuildReady {
239            recipe: "grep".into(),
240            artifact: "b3:deadbeef".into(),
241        };
242        let s = serde_json::to_string(&e).unwrap();
243        assert_eq!(
244            s,
245            r#"{"t":"build_ready","recipe":"grep","artifact":"b3:deadbeef"}"#
246        );
247    }
248
249    #[test]
250    fn error_event_minimal() {
251        let e = Event::Error { code: "no_cap".into(), msg: "no tienes 'compile'".into() };
252        let s = serde_json::to_string(&e).unwrap();
253        let back: Event = serde_json::from_str(&s).unwrap();
254        assert_eq!(back, e);
255    }
256
257    #[test]
258    fn unknown_t_is_rejected() {
259        let bad = r#"{"t":"defenestrate","payload":1}"#;
260        assert!(serde_json::from_str::<Command>(bad).is_err());
261    }
262
263    #[test]
264    fn cap_required_for_basic_commands() {
265        assert_eq!(Cap::required_for(&Command::Hello { ver: 1, client: "".into() }), None);
266        assert_eq!(
267            Cap::required_for(&Command::Query { what: "file".into(), path: None, name: None, expr: None }),
268            Some(Cap::Query)
269        );
270        assert_eq!(
271            Cap::required_for(&Command::Init { cmd: "start web".into() }),
272            Some(Cap::Init)
273        );
274    }
275}