diff --git a/CHANGELOG.md b/CHANGELOG.md index 579033b..cf902f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,36 @@ ratio/diff ver `git show `. ## 2026-05-08 +### feat(sidecar): WIT al sidecar — módulos conscientes vivos +- `brahman-card::WitInterface` deriva `Serialize`, `Deserialize`, + `PartialEq`, `Eq` para cruzar el wire postcard. +- `brahman-handshake::Hello` lleva `wit: Option`. Server + usa `ResolvedCard::from_conscious` cuando viene presente, `from_agnostic` + cuando no. +- `brahman-handshake::Client::connect` queda como wrapper agnóstico de + `connect_with(path, card, wit: Option)`. +- `brahman-broker::Broker::register` ahora toma `Option` + como tercer arg. `BrokeredCard` guarda el wit. 25 sitios de tests + actualizados con `, None`. +- `brahman-sidecar::SidecarConfig` con campo `wit`. Helpers nuevos: + `SidecarConfig::new(card).with_wit(wit)` y `spawn_conscious(card, wit)`. + El log `attached` reporta `conscious=true|false`. +- `brahman-status` muestra marker 🧠 + sección `wit:` (package/world, + imports, exports) por sesión consciente. +- Example nuevo `crates/shared/brahman-sidecar/examples/presence-conscious.rs`: + toma label + path .wit (default `shared_wit/protocol.wit`), parsea + con brahman-card-wit, spawna sidecar consciente. +- Validado end-to-end: + ``` + $ presence-conscious demo.conscious shared_wit/protocol.wit & + $ brahman-status + Sessions (1): + 01K... demo.conscious 🧠 lifecycle=Daemon + wit: brahman:protocol@0.1.0 / module + imports: types, handshake, lifecycle + exports: run + ``` + ### feat(core): brahman-card-wit — extractor opcional de contratos WIT - Crate nuevo `crates/core/brahman-card-wit` con `wit-parser = "0.230"`. - API: `parse_wit(source)` y `parse_wit_file(path)` devuelven diff --git a/Cargo.lock b/Cargo.lock index 33cd755..b36595e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1207,6 +1207,7 @@ name = "brahman-sidecar" version = "0.1.0" dependencies = [ "brahman-card", + "brahman-card-wit", "brahman-handshake", "tokio", "tracing", diff --git a/crates/core/brahman-admin/examples/brahman-status.rs b/crates/core/brahman-admin/examples/brahman-status.rs index 21c7f57..3c6f004 100644 --- a/crates/core/brahman-admin/examples/brahman-status.rs +++ b/crates/core/brahman-admin/examples/brahman-status.rs @@ -20,10 +20,20 @@ async fn main() -> anyhow::Result<()> { println!(" (ninguna)"); } else { for s in &snap.sessions { + let conscious_marker = if s.wit.is_some() { " 🧠" } else { "" }; println!( - " {} {} lifecycle={:?} priority={:?}", - s.session, s.label, s.lifecycle, s.priority + " {} {}{} lifecycle={:?} priority={:?}", + s.session, s.label, conscious_marker, s.lifecycle, s.priority ); + if let Some(wit) = &s.wit { + println!(" wit: {} / {}", wit.package, wit.world); + if !wit.imports.is_empty() { + println!(" imports: {}", wit.imports.join(", ")); + } + if !wit.exports.is_empty() { + println!(" exports: {}", wit.exports.join(", ")); + } + } for f in &s.inputs { println!(" in {}: {:?}", f.name, f.ty); } diff --git a/crates/core/brahman-broker/src/lib.rs b/crates/core/brahman-broker/src/lib.rs index 852c7ec..8aa6dfe 100644 --- a/crates/core/brahman-broker/src/lib.rs +++ b/crates/core/brahman-broker/src/lib.rs @@ -30,7 +30,7 @@ use std::collections::BTreeMap; -use brahman_card::{Card, Flow, Lifecycle, Priority, TypeRef}; +use brahman_card::{Card, Flow, Lifecycle, Priority, TypeRef, WitInterface}; use serde::{Deserialize, Serialize}; use ulid::Ulid; @@ -68,10 +68,12 @@ pub struct BrokeredCard { pub priority: Priority, pub inputs: Vec, pub outputs: Vec, + /// Interfaz WIT extraída si el módulo es "consciente"; `None` si agnóstico. + pub wit: Option, } impl BrokeredCard { - fn from_card(session: SessionId, card: &Card) -> Self { + fn from_card(session: SessionId, card: &Card, wit: Option) -> Self { Self { session, label: card.label.clone(), @@ -79,6 +81,7 @@ impl BrokeredCard { priority: card.priority, inputs: card.flow.input.clone(), outputs: card.flow.output.clone(), + wit, } } } @@ -125,9 +128,17 @@ impl Broker { } } - /// Registra una Card. Devuelve `Some(prev)` si reemplazó una existente. - pub fn register(&mut self, session: SessionId, card: &Card) -> Option { - self.cards.insert(session, BrokeredCard::from_card(session, card)) + /// Registra una Card con su WIT opcional. Devuelve `Some(prev)` si + /// reemplazó una existente. Pasar `None` en `wit` indica módulo + /// agnóstico (sin contrato WIT extraído). + pub fn register( + &mut self, + session: SessionId, + card: &Card, + wit: Option, + ) -> Option { + self.cards + .insert(session, BrokeredCard::from_card(session, card, wit)) } /// Quita una Card por sesión. @@ -351,8 +362,8 @@ mod tests { ); let s_prod = Ulid::new(); let s_cons = Ulid::new(); - b.register(s_prod, &producer); - b.register(s_cons, &consumer); + b.register(s_prod, &producer, None); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "query").expect("match"); assert_eq!(m.producer_label, "dht"); @@ -391,8 +402,8 @@ mod tests { ); let s_prod = Ulid::new(); let s_cons = Ulid::new(); - b.register(s_prod, &producer); - b.register(s_cons, &consumer); + b.register(s_prod, &producer, None); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "in").expect("match"); assert_eq!(m.via, MatchStrategy::Structural); @@ -427,9 +438,9 @@ mod tests { output: vec![], }, ); - b.register(Ulid::new(), &producer); + b.register(Ulid::new(), &producer, None); let s_cons = Ulid::new(); - b.register(s_cons, &consumer); + b.register(s_cons, &consumer, None); assert!(b.find_producer_for(s_cons, "in").is_none()); } @@ -477,10 +488,10 @@ mod tests { output: vec![], }, ); - b.register(Ulid::new(), &p_struct); - b.register(Ulid::new(), &p_exact); + b.register(Ulid::new(), &p_struct, None); + b.register(Ulid::new(), &p_exact, None); let s_cons = Ulid::new(); - b.register(s_cons, &consumer); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "in").expect("match"); // El exact gana incluso si tiene priority igual: por estrategia. @@ -516,10 +527,10 @@ mod tests { output: vec![], }, ); - b.register(Ulid::new(), &p1); - b.register(Ulid::new(), &p2); + b.register(Ulid::new(), &p1, None); + b.register(Ulid::new(), &p2, None); let s_cons = Ulid::new(); - b.register(s_cons, &consumer); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "in").expect("match"); assert_eq!(m.producer_label, "dht-test"); @@ -545,9 +556,9 @@ mod tests { output: vec![], }, ); - b.register(Ulid::new(), &p); + b.register(Ulid::new(), &p, None); let s_cons = Ulid::new(); - b.register(s_cons, &consumer); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "in").expect("match"); assert_eq!(m.producer_label, "real-dht"); @@ -581,10 +592,10 @@ mod tests { output: vec![], }, ); - b.register(Ulid::new(), &p_low); - b.register(Ulid::new(), &p_high); + b.register(Ulid::new(), &p_low, None); + b.register(Ulid::new(), &p_high, None); let s_cons = Ulid::new(); - b.register(s_cons, &consumer); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "in").expect("match"); assert_eq!(m.producer_label, "a-dht"); // priority High > Low @@ -617,10 +628,10 @@ mod tests { output: vec![], }, ); - b.register(Ulid::new(), &p1); - b.register(Ulid::new(), &p2); + b.register(Ulid::new(), &p1, None); + b.register(Ulid::new(), &p2, None); let s_cons = Ulid::new(); - b.register(s_cons, &consumer); + b.register(s_cons, &consumer, None); let m = b.find_producer_for(s_cons, "in").expect("match"); assert_eq!(m.producer_label, "a-dht"); // alfabético gana @@ -646,9 +657,9 @@ mod tests { }, ); let s_p = Ulid::new(); - b.register(s_p, &p); + b.register(s_p, &p, None); let s_c = Ulid::new(); - b.register(s_c, &consumer); + b.register(s_c, &consumer, None); assert!(b.find_producer_for(s_c, "in").is_some()); b.unregister(s_p); @@ -667,7 +678,7 @@ mod tests { }, ); let s = Ulid::new(); - b.register(s, &same); + b.register(s, &same, None); // Solo una Card registrada — no hay otra que produzca string. assert!(b.find_producer_for(s, "in").is_none()); @@ -692,8 +703,8 @@ mod tests { output: vec![flow("user-input", prim("string"), None)], }, ); - b.register(Ulid::new(), &dht); - b.register(Ulid::new(), &ui); + b.register(Ulid::new(), &dht, None); + b.register(Ulid::new(), &ui, None); let matches = b.all_matches(); assert_eq!(matches.len(), 2); diff --git a/crates/core/brahman-card/src/lib.rs b/crates/core/brahman-card/src/lib.rs index 3c2c597..7052f10 100644 --- a/crates/core/brahman-card/src/lib.rs +++ b/crates/core/brahman-card/src/lib.rs @@ -610,7 +610,7 @@ impl TrustLevel { /// Resumen de la interfaz WIT extraída del componente WASM/WIT. /// Vacío para módulos agnósticos (sin contrato WIT). -#[derive(Debug, Clone, Default)] +#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] pub struct WitInterface { pub package: String, pub world: String, diff --git a/crates/core/brahman-handshake/src/client.rs b/crates/core/brahman-handshake/src/client.rs index 6050dd6..cf79435 100644 --- a/crates/core/brahman-handshake/src/client.rs +++ b/crates/core/brahman-handshake/src/client.rs @@ -4,7 +4,7 @@ use std::collections::VecDeque; use std::path::Path; use std::time::Duration; -use brahman_card::{Card, CARD_SCHEMA_VERSION}; +use brahman_card::{Card, WitInterface, CARD_SCHEMA_VERSION}; use thiserror::Error; use tokio::net::UnixStream; @@ -43,9 +43,20 @@ pub struct Client { } impl Client { - /// Conecta al socket, envía Hello con la Card dada y procesa la respuesta. + /// Conecta como módulo agnóstico (sin WIT). Equivalente a + /// `connect_with(path, card, None)`. pub async fn connect(path: impl AsRef, card: Card) -> Result { - // Pre-validamos para fallar local antes de hablar con el servidor. + Self::connect_with(path, card, None).await + } + + /// Conecta al socket enviando Hello con la Card dada y opcionalmente + /// una `WitInterface` ya extraída. Si `wit` es `Some`, el server + /// registra el módulo como "consciente". + pub async fn connect_with( + path: impl AsRef, + card: Card, + wit: Option, + ) -> Result { card.validate() .map_err(|e| ClientError::InvalidCard(e.to_string()))?; @@ -54,6 +65,7 @@ impl Client { schema_version: CARD_SCHEMA_VERSION, protocol_version: brahman_card::PROTOCOL_VERSION.to_string(), card, + wit, }; write_frame(&mut stream, &Frame::Hello(hello)).await?; diff --git a/crates/core/brahman-handshake/src/messages.rs b/crates/core/brahman-handshake/src/messages.rs index 2ace614..80423a1 100644 --- a/crates/core/brahman-handshake/src/messages.rs +++ b/crates/core/brahman-handshake/src/messages.rs @@ -3,7 +3,7 @@ //! Todos los mensajes que cruzan el wire son variantes de [`Frame`]. use brahman_broker::MatchStrategy; -use brahman_card::TypeRef; +use brahman_card::{TypeRef, WitInterface}; use serde::{Deserialize, Serialize}; use ulid::Ulid; @@ -11,7 +11,9 @@ use ulid::Ulid; pub type SessionId = Ulid; /// Saludo inicial del módulo. Lleva la Card completa para que el servidor -/// la valide e indexe. +/// la valide e indexe. Opcionalmente, una `WitInterface` ya extraída — si +/// está presente, el módulo es "consciente" y el server lo registra como +/// `ResolvedCard::from_conscious`; si no, como `from_agnostic`. #[derive(Debug, Clone, Serialize, Deserialize)] pub struct Hello { /// Versión del schema de Card que el cliente sigue. @@ -20,6 +22,10 @@ pub struct Hello { pub protocol_version: String, /// Tarjeta de Presentación. pub card: brahman_card::Card, + /// Interfaz WIT extraída por el cliente (típicamente con + /// `brahman-card-wit`). `None` si el módulo es agnóstico. + #[serde(default)] + pub wit: Option, } /// Respuesta del servidor a un `Hello` aceptado. diff --git a/crates/core/brahman-handshake/src/server.rs b/crates/core/brahman-handshake/src/server.rs index 1a84916..454dfc4 100644 --- a/crates/core/brahman-handshake/src/server.rs +++ b/crates/core/brahman-handshake/src/server.rs @@ -6,7 +6,7 @@ use std::sync::Arc; use std::time::{SystemTime, UNIX_EPOCH}; use brahman_broker::{Broker, Endpoint}; -use brahman_card::{Card, ResolvedCard, CARD_SCHEMA_VERSION}; +use brahman_card::{Card, ResolvedCard, WitInterface, CARD_SCHEMA_VERSION}; use tokio::net::{UnixListener, UnixStream}; use tokio::sync::{mpsc, Mutex}; use tracing::{debug, warn}; @@ -367,7 +367,7 @@ impl Session { } let session_id = Ulid::new(); - self.register_session(session_id, hello.card).await; + self.register_session(session_id, hello.card, hello.wit).await; let ack = HelloAck { server_version: crate::HANDSHAKE_VERSION.to_string(), @@ -381,11 +381,23 @@ impl Session { } /// Indexa la sesión: ResolvedCard en sessions + Card en broker (si hay). - async fn register_session(&self, session_id: SessionId, card: Card) { + /// Si `wit` está presente, el módulo se registra como "consciente". + async fn register_session( + &self, + session_id: SessionId, + card: Card, + wit: Option, + ) { if let Some(broker) = &self.config.broker { - broker.lock().await.register(session_id, &card); + broker + .lock() + .await + .register(session_id, &card, wit.clone()); } - let resolved = ResolvedCard::from_agnostic(card); + let resolved = match wit { + Some(w) => ResolvedCard::from_conscious(card, w), + None => ResolvedCard::from_agnostic(card), + }; self.sessions.lock().await.insert(session_id, resolved); } diff --git a/crates/core/brahman-handshake/tests/handshake.rs b/crates/core/brahman-handshake/tests/handshake.rs index 88adc91..076b4ad 100644 --- a/crates/core/brahman-handshake/tests/handshake.rs +++ b/crates/core/brahman-handshake/tests/handshake.rs @@ -124,6 +124,7 @@ async fn server_rejects_protocol_mismatch() { schema_version: CARD_SCHEMA_VERSION, protocol_version: "999.0.0".into(), card: sample_card("future-module"), + wit: None, }; write_frame(&mut stream, &Frame::Hello(hello)).await.unwrap(); diff --git a/crates/shared/brahman-sidecar/Cargo.toml b/crates/shared/brahman-sidecar/Cargo.toml index da80c1b..e4af588 100644 --- a/crates/shared/brahman-sidecar/Cargo.toml +++ b/crates/shared/brahman-sidecar/Cargo.toml @@ -16,7 +16,12 @@ tracing = { workspace = true } [dev-dependencies] tracing-subscriber = { workspace = true } +brahman-card-wit = { path = "../../core/brahman-card-wit" } [[example]] name = "presence" path = "examples/presence.rs" + +[[example]] +name = "presence-conscious" +path = "examples/presence-conscious.rs" diff --git a/crates/shared/brahman-sidecar/examples/presence-conscious.rs b/crates/shared/brahman-sidecar/examples/presence-conscious.rs new file mode 100644 index 0000000..16baa50 --- /dev/null +++ b/crates/shared/brahman-sidecar/examples/presence-conscious.rs @@ -0,0 +1,99 @@ +//! `presence-conscious` — módulo brahman que se presenta con su WIT. +//! +//! Variante de [`presence`] que toma un path a un archivo `.wit` (default +//! `shared_wit/protocol.wit` resuelto desde el cwd) y lo parsea con +//! `brahman-card-wit` antes de spawnear el sidecar. Demuestra el flujo +//! "módulo consciente": Hello incluye `WitInterface`, el server lo +//! registra como `ResolvedCard::from_conscious`, y aparece con marker +//! 🧠 en `brahman-status`. +//! +//! Uso: +//! ```sh +//! cargo run -p brahman-sidecar --example presence-conscious -- mi-modulo [path/al.wit] +//! ``` + +use std::collections::BTreeSet; +use std::path::PathBuf; +use std::time::Duration; + +use brahman_card::{ + ulid::Ulid, Card, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef, + CARD_SCHEMA_VERSION, +}; +use brahman_sidecar::{spawn_with_handle, SidecarConfig}; + +fn main() { + tracing_subscriber::fmt() + .with_env_filter( + tracing_subscriber::EnvFilter::try_from_default_env() + .unwrap_or_else(|_| "info".into()), + ) + .init(); + + let mut args = std::env::args().skip(1); + let label = args.next().unwrap_or_else(|| "conscious-default".into()); + let wit_path: PathBuf = args + .next() + .map(PathBuf::from) + .unwrap_or_else(|| PathBuf::from("shared_wit/protocol.wit")); + + let wit = match brahman_card_wit::parse_wit_file(&wit_path) { + Ok(worlds) => match worlds.into_iter().next() { + Some(w) => { + eprintln!( + "[{label}] cargado wit: {} / {}", + w.package, w.world + ); + Some(w) + } + None => { + eprintln!("[{label}] {} no declara worlds", wit_path.display()); + None + } + }, + Err(e) => { + eprintln!("[{label}] falló parse de {}: {e}", wit_path.display()); + None + } + }; + + let card = Card { + schema_version: CARD_SCHEMA_VERSION, + id: Ulid::new(), + label: label.clone(), + payload: Payload::Virtual, + supervision: Supervision::OneShot, + lifecycle: Lifecycle::Daemon, + priority: Priority::Normal, + provides: BTreeSet::new(), + requires: BTreeSet::new(), + flow: Flows { + input: vec![Flow { + name: "in".into(), + ty: TypeRef::Primitive { + name: "json".into(), + }, + pin_to: None, + }], + output: vec![Flow { + name: "out".into(), + ty: TypeRef::Primitive { + name: "json".into(), + }, + pin_to: None, + }], + }, + ..Default::default() + }; + + let config = SidecarConfig { + card, + wit, + ping_interval: Duration::from_secs(5), + }; + + let _handle = spawn_with_handle(config); + + eprintln!("[{label}] sidecar lanzado, durmiendo (Ctrl-C para salir)"); + std::thread::park(); +} diff --git a/crates/shared/brahman-sidecar/examples/presence.rs b/crates/shared/brahman-sidecar/examples/presence.rs index 5eb0452..239a64b 100644 --- a/crates/shared/brahman-sidecar/examples/presence.rs +++ b/crates/shared/brahman-sidecar/examples/presence.rs @@ -61,6 +61,7 @@ fn main() { let _handle = spawn_with_handle(SidecarConfig { card, + wit: None, ping_interval: Duration::from_secs(5), }); diff --git a/crates/shared/brahman-sidecar/src/lib.rs b/crates/shared/brahman-sidecar/src/lib.rs index 0da806f..4a8469e 100644 --- a/crates/shared/brahman-sidecar/src/lib.rs +++ b/crates/shared/brahman-sidecar/src/lib.rs @@ -19,7 +19,7 @@ use std::thread::JoinHandle; use std::time::Duration; -use brahman_card::Card; +use brahman_card::{Card, WitInterface}; use brahman_handshake::{client::Client, transport}; use tracing::{info, warn}; @@ -31,28 +31,47 @@ pub const DEFAULT_PING_INTERVAL: Duration = Duration::from_secs(30); pub struct SidecarConfig { /// Card que se presenta al Init. pub card: Card, + /// WIT interface opcional. Si es `Some`, el módulo se registra como + /// "consciente" (`ResolvedCard::from_conscious`). + pub wit: Option, /// Período entre pings. pub ping_interval: Duration, } impl SidecarConfig { - /// Configuración con defaults razonables: ping cada 30s. + /// Configuración agnóstica con defaults razonables (sin WIT, ping 30s). pub fn new(card: Card) -> Self { Self { card, + wit: None, ping_interval: DEFAULT_PING_INTERVAL, } } + + /// Configuración consciente con WIT extraída. + pub fn with_wit(mut self, wit: WitInterface) -> Self { + self.wit = Some(wit); + self + } } -/// Spawn fire-and-forget. Devuelve inmediatamente; el handle se descarta. -/// Si el thread no se puede crear (raro), loggea y sigue. +/// Spawn fire-and-forget agnóstico. Para módulos conscientes usá +/// [`spawn_conscious`] o [`spawn_with_handle`] con un `SidecarConfig` +/// personalizado. pub fn spawn(card: Card) { if let Err(e) = spawn_with_handle(SidecarConfig::new(card)) { warn!(error = %e, "no se pudo spawnear el sidecar brahman"); } } +/// Spawn fire-and-forget con WIT. Idéntico a [`spawn`] pero el módulo se +/// registra como consciente en el broker. +pub fn spawn_conscious(card: Card, wit: WitInterface) { + if let Err(e) = spawn_with_handle(SidecarConfig::new(card).with_wit(wit)) { + warn!(error = %e, "no se pudo spawnear el sidecar brahman"); + } +} + /// Spawn devolviendo el `JoinHandle` para tests o cleanup explícito. pub fn spawn_with_handle(config: SidecarConfig) -> std::io::Result> { std::thread::Builder::new() @@ -77,13 +96,15 @@ fn run_thread(config: SidecarConfig) { async fn run_client(config: SidecarConfig) { let path = transport::default_socket_path(); - let mut client = match Client::connect(&path, config.card).await { + let conscious = config.wit.is_some(); + let mut client = match Client::connect_with(&path, config.card, config.wit).await { Ok(c) => { info!( target: "brahman_sidecar", session = %c.session(), init_attached = c.server_info().init_attached, server = %c.server_info().server_version, + conscious, "attached" ); c