tawasuyu/chasqui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: chasqui standalone — descubrimiento + transporte P2P soberano (DHT, relay, NAT traversal) (front-door, git-dep al monorepo)

Browse Source 
Front-door limpio: solo crates del dominio; Llimphi y lo fundacional por
git-dep del monorepo gioser.git. cargo check pasa (8 crates, 0 errores).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sergio
2026-06-04 12:17:59 +00:00
commit 5d5e4a3ae4
80 changed files with 22318 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -0,0 +1,3 @@
/target
**/*.rs.bk
*.pdb
02_ruway/chasqui/ARQUITECTURA.md
+202
View File
@@ -0,0 +1,202 @@
# ARQUITECTURA.md — chasqui
> Descripción técnico-arquitectónica densa, optimizada para consumo por IA.
> Snapshot: 2026-05-30. Fuente autoritativa cuando difiera con la prosa de los READMEs.
```yaml
DOMINIO: chasqui
CUADRANTE: 02_ruway (HACER)
NOMBRE: quechua "mensajero del camino del Inca"
ADVERTENCIA_SEMÁNTICA:
El README/LEEME aspira a "broker de mensajería + bus tipado pub/sub".
El CÓDIGO ACTUAL implementa otra cosa: NO hay transporte de mensajes app↔app en tiempo real.
La aspiración pub/sub migró al dominio Ayni (chat P2P). Ver project_ayni_chat.md.
TESIS_REAL: dominio DUAL — (A) matcher determinista de tipos entre módulos + (B) inteligencia de datos semántica
TAMAÑO: 11 crates, ~8.7 KLoC. Brahman ≈4.3K · Nouser ≈4.4K
```
## Los dos subsistemas (no confundir)
```
SUBSISTEMA A — BRAHMAN CARD BROKER (plano de TIPOS / control)
Registry + matcher determinista de FLUJOS tipados entre Cards (módulos con interfaz WIT opcional).
Responde "¿quién produce el flujo que este consumer necesita?". NO mueve datos: hace matching.
Crates: chasqui-broker · card-handshake · card-sidecar · card-admin · chasqui-broker-explorer-llimphi
SUBSISTEMA B — NOUSER MONADS + EMBEDDINGS (plano de DATOS / semántica)
Escanea directorios → agrupa archivos en MÓNADAS (clusters semánticos) → enriquece con embeddings
→ permite búsqueda/atracción por centroide. Persiste en sled. UI consulta.
Crates: chasqui-core · chasqui-card · chasqui-nous · chasqui-nous-mock · chasqui-nous-real · chasqui-explorer-llimphi
NEXO entre A y B:
Los proveedores de embeddings (nous-mock/real) se REGISTRAN como Cards en Brahman.
Un consumidor que pide "embed-request:json" es matcheado por el broker al proveedor correcto según CONTEXTO.
=> B usa A para descubrir QUÉ proveedor de embeddings está vivo y debe ganar.
```
## SUBSISTEMA A — Brahman Broker
### Tipos núcleo (`chasqui-broker/src/lib.rs`, 995 LOC, lib pura sin IO)
```rust
enum MatchStrategy { Exact, Structural, ExactThenStructural }
// Exact = TypeRef idéntico (interface+package+name)
// Structural = mismo package+name, ignora interface (o mismo Primitive)
// ExactThenStructural = prefiere exact, cae a structural
struct BrokeredCard {
session: SessionId, // ULID del handshake
label: String, lifecycle: Lifecycle, priority: Priority,
inputs: Vec<Flow>, outputs: Vec<Flow>,
wit: Option<WitInterface>, // matching fino si el módulo es "consciente"
priority_contexts: BTreeMap<String, ContextBias>, // sesgos por contexto ("test"/"prod")
kind: CardKind /*Ente|Data*/, data: Option<DataFacet>, service_socket: Option<PathBuf>,
}
struct Match { consumer: Endpoint, producer: Endpoint, ty: TypeRef, via: MatchStrategy, pinned: bool }
struct ContextBias { pin_to: Option<String>, priority_offset: i16 }
struct Broker { cards: BTreeMap<SessionId, BrokeredCard>, config: BrokerConfig }
```
### Algoritmo `find_producer_for(consumer, input_name)`
```
1. PIN: si el input (o priority_contexts[ctx].pin_to) fija un label → buscar productor con ese label (type-agnóstico).
2. TYPE-SEARCH: filtrar outputs de otras Cards por compatibilidad según strategy.
3. RANK: ordenar por effective_priority(producer) DESC, luego label ASC (tie-break determinista).
4. → Match { ... via, pinned }.
PROPIEDADES: determinista (mismas Cards + mismo contexto ⇒ mismo resultado); O(n·m); stateless en rutas.
```
### Handshake e infra (protocolo nativo Rust↔Rust, NO WIT/WASM)
```
card-handshake (2942 LOC): Hello{card} → HelloAck{session_id: ULID} sobre Unix socket.
Frames length-prefixed + postcard. Sesión viva con Ping(~30s)/Farewell. Deriva TrustLevel (agnóstico vs WIT-consciente).
card-sidecar (565): thread tokio current_thread que mantiene la sesión. API await_provider(card,timeout), list_matches().
card-admin (225): Unix socket SEPARADO; emite StatusSnapshot JSON (sesiones+matches). Single-shot/conexión. bin `brahman-status`.
```
### INVARIANTES (A)
```
A-INV-1 El broker NO rutea datos; sólo computa matches de tipo bajo demanda. El data-plane lo abre cada módulo (service_socket).
A-INV-2 Matching determinista y reproducible: orden total por (priority efectiva, label).
A-INV-3 pin_to gana sobre type-search; priority_contexts[ctx] override estático. Contexto activo = BRAHMAN_BROKER_CONTEXT.
A-INV-4 El broker vive en memoria del Init. NO hay snapshot/recover al reboot (deuda → ver ASPIRA).
```
## SUBSISTEMA B — Nouser
### Mónada (`chasqui-card/src/lib.rs`, 709 LOC)
```rust
struct FileEntry { id: FileId/*ULID*/, path, content_hash: Option<[u8;32]>/*blake3*/, size, mtime_ms, extension }
enum Lens { Grid, Code, Gallery, Database, Markdown, Tree } // cómo se visualiza el cluster
struct MonadManifest {
schema_version: u16/*=1*/, id: MonadId/*ULID, ordenable por tiempo*/, lineage: Option<MonadId>,
label, summary, centroid: Vec<f32>, centroid_model: Option<String>/*"chasqui-pseudo-32d"|"real-fastembed-384d"*/,
path_hint: Option<String>/*dir padre canónico = identidad estable*/, keywords: Vec<String>,
cardinality: u32, entropy: f32/*[0,1] cohesión de extensiones*/, dominant_lens: Lens,
pins: BTreeSet<FileId>/*anclados, no migran*/, members: BTreeSet<FileId>,
created_at_ms, updated_at_ms, extensions: BTreeMap<String, Value>/*forward-compat*/,
}
```
### Pipeline determinista (`chasqui-core`, 2215 LOC)
```
scanner.rs recorre directorios → Vec<FileEntry>
cluster.rs by_directory: agrupa por (dir padre + extensión dominante) → MonadManifest
db.rs MonadDb: store en memoria + sled opcional
embed.rs embed(file) → [f32;32] L2-normalizado, DETERMINISTA sin LLM:
dims 0..8 blake3(extension) · 8..16 blake3(parent) · 16..24 blake3(stem) · 24..28 size(log) · 28..32 mtime(cíclico)
EMBED_DIM=32, MODEL_ID="chasqui-pseudo-32d"
CLI: nouser scan|show|json|daemon|attract
```
### Contrato Nous (`chasqui-nous`, 196 LOC) — proveedor de embeddings intercambiable
```
WIRE: JSON line-delimited sobre Unix socket, single-shot/conexión.
EmbedRequest{ kind: EmbedFile|EmbedText|Ping, payload: Value }
EmbedResponse{ embedding: Vec<f32>, model: String, elapsed_ms: u64 }
SOCKET: $XDG_RUNTIME_DIR/chasqui-nous-{provider}.sock (override $NOUSER_NOUS_SOCKET)
mock (chasqui-nous-mock): chasqui_core::embed, 32d determinista; Card priority_contexts["test"]={+1} → gana en test
real (chasqui-nous-real): fastembed+ONNX all-MiniLM-L6-v2, 384d; feature `embeddings`; cache sled;
Card priority_contexts["prod"]={+1} → gana en prod
=> El broker Brahman elige mock vs real según BRAHMAN_BROKER_CONTEXT. Mismo flow embed-request:json / embed-result:json.
```
### INVARIANTES (B)
```
B-INV-1 embed() es puro y determinista (hash+metadata) ⇒ misma carpeta ⇒ mismas Mónadas y centroides en toda máquina.
B-INV-2 path_hint es la identidad estable de una Mónada (sobrevive a cambios de miembros).
B-INV-3 El proveedor de embeddings es opaco/intercambiable tras el contrato Nous; el core no sabe si es mock o LLM.
```
## UIs Llimphi
```
chasqui-broker-explorer-llimphi (599): probe de salud; poll 5s await_provider_blocking →
estado Down | UpNoProvider | UpWithProvider(label,socket) + timeline de MatchEvent (últimos 50).
chasqui-explorer-llimphi (501): explorador de Mónadas; descubre el daemon nouser vía broker,
consulta Mónadas, filtra por centroide (búsqueda semántica), muestra cardinality/entropy/lens.
```
## Relaciones inter-dominio
```
agora : identidad Ed25519 — autores de mensajes en el futuro chat (vía Ayni), no en chasqui hoy.
minga : transporte P2P libp2p (BrahmanNet) — chasqui aún NO lo usa; el broker es LOCAL/LAN (Unix socket).
akasha : VFS content-addressed en wawa — no usado por chasqui hoy.
rimay : chasqui-explorer-llimphi → rimay-localize para búsqueda semántica sobre centroides.
shuma : chasqui-core → shuma-discern (clasificación determinista) — integración superficial, pendiente profundizar.
arje : chasqui-nous-real podría persistir embeddings en CAS de wawa — experimental.
ayni : HEREDA la aspiración pub/sub de chasqui. Ayni-sync usa trait Transporte (EnlaceMinga), NO el broker chasqui.
```
## Estado (2026-05-31)
### Hecho
- Subsistema A (Brahman): matching tipado determinista (Exact/Structural/ExactThenStructural) + context biases + handshake Unix-socket (card-handshake/sidecar) + observabilidad admin (`brahman-status`) + UI probe (`chasqui-broker-explorer-llimphi`).
- Subsistema B (Nouser): scanner + clustering `by_directory` + `MonadDb` (sled) + pseudo-embeddings 32d deterministas + real 384d ONNX gated por feature + contrato Nous (mock/real intercambiables) + UI explorer semántico + CLI `nouser`.
- Nexo A↔B: los proveedores de embeddings se registran como Cards; el broker elige mock vs real por `BRAHMAN_BROKER_CONTEXT`.
- Las dos UIs portadas a Llimphi (GPUI extinto) + menú principal/contextual (lotes 1 y 5).
### Pendiente
- Persistencia del broker: hoy vive en memoria del Init, sin snapshot/recover al reboot.
- Transporte remoto: Brahman es Unix-socket local; el matching de módulos remotos (card-net/libp2p) ya NO está bloqueado por NAT — `card-net` cablea relay+dcutr+autonat (verificado por el test `jalar_a_traves_de_un_relay` de khipu). Lo que falta es CABLEAR el discovery: el daemon Nouser no llama `announce_outputs()` al DHT ni hay `find_remote_providers(flow_type)` en `card-sidecar`.
- real-nous en producción: la feature `embeddings` arrastra ~200 MB de ONNX runtime (trade-off tamaño↔capacidad).
- Integración a fondo cross-dominio (rimay/shuma/arje) con nouser, aún superficial.
- La aspiración pub/sub original migró a Ayni (chat P2P); chasqui hoy NO transporta mensajes app↔app en tiempo real.
## Estado vs aspiración
```
DEUDA / ASPIRA_A:
#1 PERSISTENCIA del broker: hoy vive en memoria del Init, sin snapshot/recover al reboot.
#2 TRANSPORTE remoto: Brahman es Unix-socket local; falta CABLEAR discovery por DHT
(announce_outputs en el daemon Nouser + find_remote_providers en card-sidecar).
#3 NAT traversal: HECHO en card-net (relay+dcutr+autonat), heredado por minga/agora/
chasqui/khipu; ya no bloquea el uso remoto P2P.
#4 real-nous en producción: feature `embeddings` arrastra ~200MB de ONNX runtime — trade-off size↔capacidad.
#5 COHERENCIA cross-dominio: rimay/shuma/arje aún no integrados a fondo con nouser.
NORTE_ARQUITECTÓNICO:
Dos planos que convergen. PLANO DE TIPOS (Brahman): "decláme qué consumís y te encuentro quién lo produce,
determinista y observable, sin acoplar módulos". PLANO DE DATOS (Nouser): "dame una carpeta y te devuelvo su
estructura semántica latente (Mónadas) con embeddings intercambiables".
El destino es que el broker deje de ser local (Unix socket) y, sobre transporte minga/libp2p, haga discovery
tipado de pares REMOTOS — habilitando que Ayni (chat P2P) y otros descubran proveedores por tipo a través de la red,
no por config. Chasqui hoy es una joya quieta: matching + búsqueda + discovery local, lista para crecer a P2P.
```
---
**Síntesis de una línea para otra IA:** chasqui es un dominio dual — (A) un **broker de tipos** Brahman que
hace matching determinista y observable de flujos entre módulos (Cards) sin mover datos, y (B) **Nouser**, un motor de
inteligencia de datos que agrupa archivos en Mónadas semánticas con embeddings intercambiables (mock 32d determinista /
real 384d ONNX) descubiertos a través de (A) — cuya aspiración pub/sub original migró a Ayni y cuyo norte es elevar el
discovery tipado local a discovery P2P remoto sobre transporte minga/libp2p.
02_ruway/chasqui/LEEME.md
+41
View File
@@ -0,0 +1,41 @@
# chasqui
> `chasqui` (quechua: *mensajero del camino del inca*). Broker de mensajería + bus tipado.
Sistema nervioso del monorepo. Apps publican y se suscriben a topics tipados; el broker rutea y persiste. Backend `nous` con dos implementaciones: `mock` (in-process para tests) y `real` (TCP + binary). Cada mensaje lleva su schema, fail-closed si el receptor no lo conoce.
## Instalación
```sh
# arrancar el broker
cargo run --release -p chasqui-broker
# explorer (ver topics + mensajes en vivo)
cargo run --release -p chasqui-broker-explorer-llimphi
cargo run --release -p chasqui-explorer-llimphi
```
## Compatibilidad
- **Linux / macOS / Windows** — broker + clientes en Rust nativo.
- **Wawa** — broker corre como app del kernel (`apps/`).
- TCP localhost por default; sockets Unix opcionales.
## Crates
| Crate | Rol |
|---|---|
| [`chasqui-core`](chasqui-core/README.md) | Tipos: Topic, Message, Schema, Subscription. |
| [`chasqui-broker`](chasqui-broker/README.md) | Binario del broker. |
| [`chasqui-nous`](chasqui-nous/README.md) | Trait del transport. |
| [`chasqui-nous-mock`](chasqui-nous-mock/README.md) | Transport in-process para tests. |
| [`chasqui-nous-real`](chasqui-nous-real/README.md) | Transport TCP/Unix binario. |
| [`chasqui-card`](chasqui-card/README.md) | Card escritorio (estado del broker). |
| [`chasqui-broker-explorer-llimphi`](chasqui-broker-explorer-llimphi/README.md) | UI: topics + suscriptores activos. |
| [`chasqui-explorer-llimphi`](chasqui-explorer-llimphi/README.md) | UI: log de mensajes en vivo. |
## Consideraciones
- **Schema-first.** Sin schema declarado, ningún mensaje pasa.
- **Persistencia opt-in** por topic; los topics efímeros viven sólo en memoria.
- **No es Kafka.** Diseñado para el monorepo, no para volumen de producción interplanetaria.
02_ruway/chasqui/README.md
+38
View File
@@ -0,0 +1,38 @@
# chasqui
> `chasqui` (Quechua: *messenger of the Inca road*). Message broker + typed bus.
Nervous system of the monorepo. Apps publish and subscribe to typed topics; the broker routes and persists. `nous` backend with two impls: `mock` (in-process for tests) and `real` (binary TCP). Every message carries its schema, fail-closed if the receiver doesn't know it.
## Install
```sh
cargo run --release -p chasqui-broker
cargo run --release -p chasqui-broker-explorer-llimphi
cargo run --release -p chasqui-explorer-llimphi
```
## Compatibility
- **Linux / macOS / Windows** — broker + clients in native Rust.
- **Wawa** — broker runs as a kernel app.
- TCP localhost by default; Unix sockets optional.
## Crates
| Crate | Role |
|---|---|
| [`chasqui-core`](chasqui-core/README.md) | Topic, Message, Schema, Subscription. |
| [`chasqui-broker`](chasqui-broker/README.md) | Broker binary. |
| [`chasqui-nous`](chasqui-nous/README.md) | Transport trait. |
| [`chasqui-nous-mock`](chasqui-nous-mock/README.md) | In-process transport. |
| [`chasqui-nous-real`](chasqui-nous-real/README.md) | Binary TCP/Unix transport. |
| [`chasqui-card`](chasqui-card/README.md) | Desktop card. |
| [`chasqui-broker-explorer-llimphi`](chasqui-broker-explorer-llimphi/README.md) | Topics + active subscribers UI. |
| [`chasqui-explorer-llimphi`](chasqui-explorer-llimphi/README.md) | Live message log UI. |
## Considerations
- **Schema-first.** No schema declared, no message through.
- **Persistence opt-in** per topic; ephemeral topics live in memory only.
- **Not Kafka.** Designed for the monorepo, not interplanetary production volume.
02_ruway/chasqui/README.qu.md
+40
View File
@@ -0,0 +1,40 @@
<!-- Quechua (Cusco/Collao). Revisión bienvenida. -->
# chasqui
> `chasqui` (runa-simi: *Inka ñanninpa mensahero*). Mensaje broker + tipo bus.
Monorepupa sapan nervio. Aplikacionkuna tipasqa topics-pi publish + subscribe ruwanku; brokerqa rutéo + waqaychaq. `nous` backend, iskay implementaciones: `mock` (in-process tests-paq) + `real` (binario TCP). Sapanka mensaje schema-yuq, mana yachaqtin chaski-fail.
## Churay
```sh
cargo run --release -p chasqui-broker
cargo run --release -p chasqui-broker-explorer-llimphi
cargo run --release -p chasqui-explorer-llimphi
```
## Tinkuy
- **Linux / macOS / Windows** — broker + cliente Rust naturalwan.
- **Wawa** — broker kernel apps hina.
- TCP localhost default; Unix sockets opcional.
## Crateskuna
| Crate | Ima ruwan |
|---|---|
| [`chasqui-core`](chasqui-core/README.md) | Topic, Mensaje, Schema, Subscripción. |
| [`chasqui-broker`](chasqui-broker/README.md) | Broker binario. |
| [`chasqui-nous`](chasqui-nous/README.md) | Transporte trait. |
| [`chasqui-nous-mock`](chasqui-nous-mock/README.md) | In-process transporte. |
| [`chasqui-nous-real`](chasqui-nous-real/README.md) | Binario TCP/Unix transporte. |
| [`chasqui-card`](chasqui-card/README.md) | Escritorio card. |
| [`chasqui-broker-explorer-llimphi`](chasqui-broker-explorer-llimphi/README.md) | Topics + subscriptores UI. |
| [`chasqui-explorer-llimphi`](chasqui-explorer-llimphi/README.md) | Kawsaq mensaje log UI. |
## Yuyaykunaq
- **Schema-ñawpaq.** Mana schema mana mensaje.
- **Waqaychay opt-in** topic-pi; ephemeris topics ukhupi kawsanku.
- **Mana Kafka.** Monorepupaq, mana planetapaq.
02_ruway/chasqui/card-admin/Cargo.toml
+27
View File
@@ -0,0 +1,27 @@
[package]
name = "card-admin"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Brahman — admin API: snapshot del estado del broker (sesiones + matches) por Unix socket, format JSON."
[dependencies]
chasqui-broker = { path = "../chasqui-broker" }
card-core = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
tokio = { workspace = true }
thiserror = { workspace = true }
tracing = { workspace = true }
[dev-dependencies]
tempfile = { workspace = true }
ulid = { workspace = true }
anyhow = { workspace = true }
[[example]]
name = "brahman-status"
path = "examples/brahman-status.rs"
02_ruway/chasqui/card-admin/examples/brahman-status.rs
+98
View File
@@ -0,0 +1,98 @@
//! `brahman-status` — CLI para inspeccionar el estado del Init.
//!
//! Conecta al socket admin (default `$XDG_RUNTIME_DIR/brahman-admin.sock`,
//! override con `$BRAHMAN_ADMIN_SOCKET`), recibe el snapshot, y lo imprime.
use card_admin::{client, transport};
#[tokio::main(flavor = "current_thread")]
async fn main() -> anyhow::Result<()> {
let path = transport::default_socket_path();
let snap = client::query(&path).await?;
println!(
"Init: server={} protocol={} attached={}",
snap.server_version, snap.protocol_version, snap.init_attached
);
if let Some(ctx) = &snap.current_context {
println!("Context: {}", ctx);
}
println!();
println!("Sessions ({}):", snap.sessions.len());
if snap.sessions.is_empty() {
println!(" (ninguna)");
} else {
for s in &snap.sessions {
let conscious_marker = if s.wit.is_some() { " 🧠" } else { "" };
let kind_marker = match s.kind {
card_core::CardKind::Ente => "ente",
card_core::CardKind::Data => "data",
};
println!(
" [{}] {} {}{} lifecycle={:?} priority={:?}",
kind_marker, s.session, s.label, conscious_marker, s.lifecycle, s.priority
);
if let Some(sock) = &s.service_socket {
println!(" socket: {}", sock.display());
}
for r in &s.references {
println!(
" ref {:?} → {} ({})",
r.kind, r.target_label, r.target_id
);
}
if let Some(data) = &s.data {
if !data.summary.is_empty() {
println!(" summary: {}", data.summary);
}
if data.member_count > 0 {
println!(
" members: {} (dispersion={:.2})",
data.member_count, data.dispersion
);
}
if !data.keywords.is_empty() {
println!(" keywords: {}", data.keywords.join(", "));
}
if !data.presentation_hint.is_empty() {
println!(" lens hint: {}", data.presentation_hint);
}
}
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);
}
for f in &s.outputs {
println!(" out {}: {:?}", f.name, f.ty);
}
}
}
println!();
println!("Matches ({}):", snap.matches.len());
if snap.matches.is_empty() {
println!(" (ninguno)");
} else {
for m in &snap.matches {
let pin_marker = if m.pinned { "📌" } else { " " };
println!(
" {} {}.{} ← {}.{} via {:?}",
pin_marker,
m.consumer_label,
m.consumer.flow_name,
m.producer_label,
m.producer.flow_name,
m.via
);
}
}
Ok(())
}
02_ruway/chasqui/card-admin/src/client.rs
+48
View File
@@ -0,0 +1,48 @@
//! Cliente admin: lee un `StatusSnapshot` desde un socket admin.
use std::path::Path;
use thiserror::Error;
use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::net::UnixStream;
use crate::snapshot::StatusSnapshot;
#[derive(Debug, Error)]
pub enum AdminError {
#[error("E/S: {0}")]
Io(#[from] std::io::Error),
#[error("respuesta vacía")]
Empty,
#[error("JSON inválido: {0}")]
Json(#[from] serde_json::Error),
}
/// Conecta al socket admin, lee la línea JSON y deserializa.
pub async fn query(path: impl AsRef<Path>) -> Result<StatusSnapshot, AdminError> {
let stream = UnixStream::connect(path).await?;
let mut reader = BufReader::new(stream);
let mut line = String::new();
let n = reader.read_line(&mut line).await?;
if n == 0 {
return Err(AdminError::Empty);
}
let snapshot = serde_json::from_str(&line)?;
Ok(snapshot)
}
/// Variante sync de [`query`] para callers que no tienen runtime tokio
/// (típicamente: GUIs con su propio executor, como GPUI).
pub fn query_blocking(path: impl AsRef<Path>) -> Result<StatusSnapshot, AdminError> {
use std::io::{BufRead, BufReader as StdBufReader};
use std::os::unix::net::UnixStream as StdUnixStream;
let stream = StdUnixStream::connect(path)?;
let mut reader = StdBufReader::new(stream);
let mut line = String::new();
let n = reader.read_line(&mut line)?;
if n == 0 {
return Err(AdminError::Empty);
}
let snapshot = serde_json::from_str(&line)?;
Ok(snapshot)
}
02_ruway/chasqui/card-admin/src/lib.rs
+23
View File
@@ -0,0 +1,23 @@
//! `brahman-admin` — observabilidad del broker.
//!
//! Expone un Unix socket separado (no se mezcla con el handshake) en el
//! que cada conexión recibe un `StatusSnapshot` JSON y se cierra. Es
//! single-shot por conexión: pensado para herramientas como
//! `brahman-status`, dashboards y health-checks.
//!
//! Wire format: una línea JSON por conexión, terminada en `\n`. Esto
//! hace trivial inspeccionar con `nc` o `socat` además del cliente
//! tipado de este crate.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
pub mod client;
pub mod server;
pub mod snapshot;
pub mod transport;
pub use snapshot::StatusSnapshot;
/// Versión del crate de admin.
pub const ADMIN_VERSION: &str = env!("CARGO_PKG_VERSION");
02_ruway/chasqui/card-admin/src/server.rs
+110
View File
@@ -0,0 +1,110 @@
//! Servidor admin: emite un `StatusSnapshot` JSON por conexión y cierra.
use std::path::{Path, PathBuf};
use std::sync::Arc;
use chasqui_broker::Broker;
use tokio::io::AsyncWriteExt;
use tokio::net::{UnixListener, UnixStream};
use tokio::sync::Mutex;
use tracing::warn;
use crate::snapshot::StatusSnapshot;
/// Configuración del servidor admin.
#[derive(Debug, Clone, Default)]
pub struct AdminConfig {
/// `true` si el Init está atado al servidor que aloja este admin.
pub init_attached: bool,
/// Contexto operativo del broker, espejado en el snapshot.
pub current_context: Option<String>,
}
/// Servidor admin escuchando en un Unix socket.
pub struct AdminServer {
listener: UnixListener,
socket_path: PathBuf,
broker: Arc<Mutex<Broker>>,
config: AdminConfig,
}
impl AdminServer {
/// Crea el listener. Si `path` existe, lo elimina (asume socket stale).
pub fn bind(
path: impl Into<PathBuf>,
broker: Arc<Mutex<Broker>>,
config: AdminConfig,
) -> std::io::Result<Self> {
let socket_path = path.into();
if socket_path.exists() {
std::fs::remove_file(&socket_path)?;
}
if let Some(parent) = socket_path.parent() {
if !parent.as_os_str().is_empty() {
std::fs::create_dir_all(parent)?;
}
}
let listener = UnixListener::bind(&socket_path)?;
Ok(Self {
listener,
socket_path,
broker,
config,
})
}
pub fn socket_path(&self) -> &Path {
&self.socket_path
}
/// Loop de aceptación: cada conexión recibe un snapshot y se cierra.
pub async fn run(self) -> std::io::Result<()> {
loop {
let (stream, _addr) = self.listener.accept().await?;
let broker = self.broker.clone();
let config = self.config.clone();
tokio::spawn(async move {
if let Err(e) = handle_conn(stream, broker, config).await {
warn!(error = %e, "admin conn falló");
}
});
}
}
}
impl Drop for AdminServer {
fn drop(&mut self) {
if let Err(e) = std::fs::remove_file(&self.socket_path) {
if e.kind() != std::io::ErrorKind::NotFound {
warn!(path = %self.socket_path.display(), error = %e, "no se pudo limpiar admin socket");
}
}
}
}
async fn handle_conn(
mut stream: UnixStream,
broker: Arc<Mutex<Broker>>,
config: AdminConfig,
) -> std::io::Result<()> {
let snapshot = build_snapshot(&broker, &config).await;
let mut json = serde_json::to_string(&snapshot)?;
json.push('\n');
stream.write_all(json.as_bytes()).await?;
stream.shutdown().await?;
Ok(())
}
async fn build_snapshot(broker: &Arc<Mutex<Broker>>, config: &AdminConfig) -> StatusSnapshot {
let b = broker.lock().await;
let sessions: Vec<_> = b.cards().cloned().collect();
let matches = b.all_matches();
StatusSnapshot {
server_version: crate::ADMIN_VERSION.to_string(),
protocol_version: card_core::PROTOCOL_VERSION.to_string(),
init_attached: config.init_attached,
current_context: config.current_context.clone(),
sessions,
matches,
}
}
02_ruway/chasqui/card-admin/src/snapshot.rs
+24
View File
@@ -0,0 +1,24 @@
//! Tipos del snapshot que el admin server emite.
use chasqui_broker::{BrokeredCard, Match};
use serde::{Deserialize, Serialize};
/// Snapshot completo del estado del Init en un instante.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StatusSnapshot {
/// Versión del crate del Init que respondió.
pub server_version: String,
/// Versión del protocolo brahman.
pub protocol_version: String,
/// `true` si el Init está atado al servidor.
pub init_attached: bool,
/// Contexto operativo activo del broker (p. ej. `"test"`, `"prod"`).
/// `None` si no hay contexto configurado — los biases per-contexto
/// declarados en las Cards quedan inactivos.
#[serde(default)]
pub current_context: Option<String>,
/// Cards actualmente registradas (sesiones vivas).
pub sessions: Vec<BrokeredCard>,
/// Matches consumer↔producer derivados del set actual.
pub matches: Vec<Match>,
}
02_ruway/chasqui/card-admin/src/transport.rs
+20
View File
@@ -0,0 +1,20 @@
//! Convenciones de transporte para el socket admin.
use std::path::PathBuf;
/// Variable de entorno que sobreescribe la ruta del socket admin.
pub const SOCKET_ENV: &str = "BRAHMAN_ADMIN_SOCKET";
/// Nombre del socket admin dentro del runtime dir.
pub const SOCKET_NAME: &str = "brahman-admin.sock";
/// Ruta canónica al socket admin del Init.
pub fn default_socket_path() -> PathBuf {
if let Ok(p) = std::env::var(SOCKET_ENV) {
return PathBuf::from(p);
}
let base = std::env::var_os("XDG_RUNTIME_DIR")
.map(PathBuf::from)
.unwrap_or_else(std::env::temp_dir);
base.join(SOCKET_NAME)
}
02_ruway/chasqui/card-handshake/Cargo.toml
+37
View File
@@ -0,0 +1,37 @@
[package]
name = "card-handshake"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Brahman — handshake runtime Init↔módulo. Local sobre Unix socket; remoto sobre stream libp2p (card-net)."
[dependencies]
card-core = { workspace = true }
chasqui-broker = { path = "../chasqui-broker" }
card-net = { workspace = true }
blake3 = { workspace = true }
futures = { workspace = true }
notify = { workspace = true }
serde = { workspace = true }
postcard = { workspace = true }
tokio = { workspace = true }
tokio-util = { workspace = true }
thiserror = { workspace = true }
ulid = { workspace = true }
tracing = { workspace = true }
[dev-dependencies]
tempfile = { workspace = true }
tokio = { workspace = true }
anyhow = { workspace = true }
[[example]]
name = "probe"
path = "examples/probe.rs"
[[example]]
name = "subscriber"
path = "examples/subscriber.rs"
02_ruway/chasqui/card-handshake/examples/probe.rs
+51
View File
@@ -0,0 +1,51 @@
//! probe — herramienta de diagnóstico del handshake.
//!
//! Conecta a un Init brahman vivo, hace handshake, un ping, y se va.
//! Ruta del socket: `$BRAHMAN_INIT_SOCKET` o el default
//! ([`card_handshake::transport::default_socket_path`]).
//!
//! Uso:
//! ```sh
//! cargo run -p brahman-handshake --example probe
//! ```
use std::collections::BTreeSet;
use card_core::{Card, Payload, Supervision, CARD_SCHEMA_VERSION};
use card_handshake::{client::Client, transport};
use ulid::Ulid;
#[tokio::main(flavor = "current_thread")]
async fn main() -> anyhow::Result<()> {
let card = Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: "brahman-probe".into(),
payload: Payload::Virtual,
supervision: Supervision::OneShot,
provides: BTreeSet::new(),
requires: BTreeSet::new(),
..Default::default()
};
let path = transport::default_socket_path();
println!("connecting to {}", path.display());
let mut client = Client::connect(&path, card).await?;
let info = client.server_info();
println!(
" HelloAck: session={} server={} protocol={} init_attached={}",
client.session(),
info.server_version,
info.protocol_version,
info.init_attached
);
let ts = client.ping().await?;
println!(" Pong: ts={}ms", ts);
client.farewell().await?;
println!(" Farewell OK");
Ok(())
}
02_ruway/chasqui/card-handshake/examples/subscriber.rs
+83
View File
@@ -0,0 +1,83 @@
//! `subscriber` — cliente brahman que loguea cada `MatchEvent` recibido.
//!
//! Declara una Card con un input `in` de tipo `json`. Cada vez que el
//! broker matchea (o desmatch) ese input contra un productor, imprime
//! una línea. Útil para visualizar la dinámica del broker en vivo.
//!
//! Uso:
//! ```sh
//! cargo run -p brahman-handshake --example subscriber [label]
//! ```
use std::collections::BTreeSet;
use std::time::Duration;
use card_core::{
ulid::Ulid, Card, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef,
CARD_SCHEMA_VERSION,
};
use card_handshake::{client::Client, transport};
#[tokio::main(flavor = "current_thread")]
async fn main() -> anyhow::Result<()> {
let label = std::env::args()
.nth(1)
.unwrap_or_else(|| "subscriber".into());
let card = Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: label.clone(),
provides: BTreeSet::new(),
requires: BTreeSet::new(),
payload: Payload::Virtual,
supervision: Supervision::OneShot,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
flow: Flows {
input: vec![Flow {
name: "in".into(),
ty: TypeRef::Primitive {
name: "json".into(),
},
pin_to: None,
}],
output: vec![],
},
..Default::default()
};
let path = transport::default_socket_path();
eprintln!("[{label}] connecting to {}", path.display());
let mut client = Client::connect(&path, card).await?;
eprintln!(
"[{label}] attached: session={} init={}",
client.session(),
client.server_info().init_attached
);
// Loop: espera hasta 25s por un MatchEvent. Si timeout, ping para
// mantener la conexión viva.
loop {
match client.await_event(Duration::from_secs(25)).await? {
Some(ev) => {
eprintln!(
"[{label}] {:?} {} ← {}.{} via={:?}{}",
ev.kind,
ev.consumer_flow,
if ev.producer_label.is_empty() {
"<none>"
} else {
&ev.producer_label
},
ev.producer_flow,
ev.via,
if ev.pinned { " 📌" } else { "" }
);
}
None => {
let _ts = client.ping().await?;
}
}
}
}
02_ruway/chasqui/card-handshake/src/client.rs
+312
View File
@@ -0,0 +1,312 @@
//! Cliente de handshake. Conecta a un Unix socket y mantiene la sesión.
use std::collections::VecDeque;
use std::path::Path;
use std::time::Duration;
use card_core::{Card, WitInterface, CARD_SCHEMA_VERSION};
use card_net::Keypair;
use thiserror::Error;
use tokio::io::{AsyncRead, AsyncWrite};
use tokio::net::UnixStream;
use crate::codec::{read_frame, write_frame};
use crate::identity::SessionCert;
use crate::messages::{Farewell, Frame, HandshakeError, Hello, HelloAck, MatchEvent, Ping, SessionId};
use crate::signature::{sign_hello, SignatureError};
/// Errores del cliente.
#[derive(Debug, Error)]
pub enum ClientError {
#[error("E/S: {0}")]
Io(#[from] std::io::Error),
/// El servidor respondió con un error explícito.
#[error("servidor: {0}")]
Server(#[source] HandshakeError),
/// El servidor envió un frame que no esperábamos en este punto del protocolo.
#[error("frame inesperado: {got}")]
UnexpectedFrame { got: &'static str },
/// La Card que el cliente intentó enviar no pasa su propia validación.
#[error("card inválida pre-envío: {0}")]
InvalidCard(String),
/// Firma del Hello falló al construirse (rara — sólo puede pasar
/// si la keypair pasada está en un estado inválido).
#[error("firma del Hello falló: {0}")]
Signature(#[from] SignatureError),
}
/// Cliente conectado y autenticado. Tras `connect` ya completó el handshake
/// y tiene su `SessionId`. Los `MatchEvent` recibidos durante operaciones
/// request/response se buferean en `pending_events` y se obtienen vía
/// [`Client::take_event`] o [`Client::await_event`].
///
/// Genérico sobre el transport (`AsyncRead + AsyncWrite + Unpin + Send`):
/// funciona indistintamente sobre `UnixStream` (path local) o sobre un
/// stream libp2p wrapped con `tokio_util::compat` (path remoto, vía
/// `card_handshake::network`).
#[derive(Debug)]
pub struct Client<S = UnixStream> {
stream: S,
session: SessionId,
server_info: HelloAck,
pending_events: VecDeque<MatchEvent>,
}
impl Client<UnixStream> {
/// Conecta como módulo agnóstico (sin WIT) sobre Unix socket.
/// Equivalente a `connect_with(path, card, None)`.
pub async fn connect(path: impl AsRef<Path>, card: Card) -> Result<Self, ClientError> {
Self::connect_with(path, card, None).await
}
/// Conecta al socket Unix 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<Path>,
card: Card,
wit: Option<WitInterface>,
) -> Result<Self, ClientError> {
let stream = UnixStream::connect(path).await?;
Self::connect_with_stream(stream, card, wit).await
}
}
impl<S> Client<S>
where
S: AsyncRead + AsyncWrite + Unpin + Send,
{
/// Constructor genérico sobre un stream ya abierto, **sin firma**.
/// Apto para path Unix (donde SO_PEERCRED del kernel ya autentica)
/// o tests in-memory. Para libp2p remoto usá
/// [`connect_with_stream_signed`](Self::connect_with_stream_signed) —
/// el server libp2p rechaza Hello sin firma.
pub async fn connect_with_stream(
stream: S,
card: Card,
wit: Option<WitInterface>,
) -> Result<Self, ClientError> {
Self::connect_inner(stream, card, wit, None, None).await
}
/// Igual que `connect_with_stream` pero firma el Hello con
/// `keypair`. Usar para conexiones libp2p donde el server exige
/// firma. La public key derivada de `keypair` debe coincidir con
/// el `peer_id` libp2p autenticado por Noise — típicamente la
/// keypair pasada a [`card_net::BrahmanNet::with_keypair`].
pub async fn connect_with_stream_signed(
stream: S,
card: Card,
wit: Option<WitInterface>,
keypair: &Keypair,
) -> Result<Self, ClientError> {
Self::connect_inner(stream, card, wit, Some(keypair), None).await
}
/// Igual que `connect_with_stream_signed` pero además adjunta un
/// `SessionCert` que vincula la session keypair a una identity
/// master estable. El server, al recibir el cert, evalúa la
/// política de admisión contra el `master_peer_id` (no contra
/// el session peer_id) — permitiendo rotar la session sin perder
/// la identidad reconocida en allowlists remotas.
pub async fn connect_with_stream_signed_with_cert(
stream: S,
card: Card,
wit: Option<WitInterface>,
session_keypair: &Keypair,
identity_cert: SessionCert,
) -> Result<Self, ClientError> {
Self::connect_inner(stream, card, wit, Some(session_keypair), Some(identity_cert)).await
}
async fn connect_inner(
mut stream: S,
card: Card,
wit: Option<WitInterface>,
keypair: Option<&Keypair>,
identity_cert: Option<SessionCert>,
) -> Result<Self, ClientError> {
card.validate()
.map_err(|e| ClientError::InvalidCard(e.to_string()))?;
let wire_card = card_core::WireCard::from(card);
let signature = match keypair {
Some(kp) => Some(sign_hello(kp, &wire_card, &wit)?),
None => None,
};
let hello = Hello {
schema_version: CARD_SCHEMA_VERSION,
protocol_version: card_core::PROTOCOL_VERSION.to_string(),
card: wire_card,
wit,
signature,
identity_cert,
};
write_frame(&mut stream, &Frame::Hello(hello)).await?;
let frame = read_frame(&mut stream).await?;
let ack = match frame {
Frame::HelloAck(a) => a,
Frame::Error(e) => return Err(ClientError::Server(e)),
Frame::Hello(_) => return Err(ClientError::UnexpectedFrame { got: "Hello" }),
Frame::Ping(_) => return Err(ClientError::UnexpectedFrame { got: "Ping" }),
Frame::Pong(_) => return Err(ClientError::UnexpectedFrame { got: "Pong" }),
Frame::Farewell(_) => return Err(ClientError::UnexpectedFrame { got: "Farewell" }),
Frame::MatchEvent(_) => {
return Err(ClientError::UnexpectedFrame {
got: "MatchEvent (pre-handshake)",
});
}
Frame::ListSessions(_) => {
return Err(ClientError::UnexpectedFrame {
got: "ListSessions (pre-handshake)",
});
}
Frame::SessionList(_) => {
return Err(ClientError::UnexpectedFrame {
got: "SessionList (pre-handshake)",
});
}
Frame::ListMatches(_) => {
return Err(ClientError::UnexpectedFrame {
got: "ListMatches (pre-handshake)",
});
}
Frame::MatchList(_) => {
return Err(ClientError::UnexpectedFrame {
got: "MatchList (pre-handshake)",
});
}
};
Ok(Self {
stream,
session: ack.session,
server_info: ack,
pending_events: VecDeque::new(),
})
}
/// `SessionId` asignado por el servidor.
pub fn session(&self) -> SessionId {
self.session
}
/// Información del servidor recibida en el handshake.
pub fn server_info(&self) -> &HelloAck {
&self.server_info
}
/// Envía un Ping y devuelve el timestamp del servidor. Los frames
/// `MatchEvent` que lleguen mezclados se buferean en `pending_events`.
pub async fn ping(&mut self) -> Result<u64, ClientError> {
write_frame(
&mut self.stream,
&Frame::Ping(Ping {
session: self.session,
}),
)
.await?;
loop {
match read_frame(&mut self.stream).await? {
Frame::Pong(p) => return Ok(p.timestamp_ms),
Frame::MatchEvent(ev) => self.pending_events.push_back(ev),
Frame::Error(e) => return Err(ClientError::Server(e)),
_ => return Err(ClientError::UnexpectedFrame { got: "non-pong" }),
}
}
}
/// Saca un evento pendiente del buffer, sin bloquear ni leer del wire.
pub fn take_event(&mut self) -> Option<MatchEvent> {
self.pending_events.pop_front()
}
/// Espera un `MatchEvent` con timeout. Drena primero el buffer; si
/// está vacío, lee del wire hasta el timeout. Otros frames recibidos
/// (Pong huérfano, Error) cortan la espera con error.
pub async fn await_event(
&mut self,
timeout: Duration,
) -> Result<Option<MatchEvent>, ClientError> {
if let Some(ev) = self.pending_events.pop_front() {
return Ok(Some(ev));
}
match tokio::time::timeout(timeout, read_frame(&mut self.stream)).await {
Err(_) => Ok(None),
Ok(Err(e)) => Err(ClientError::Io(e)),
Ok(Ok(Frame::MatchEvent(ev))) => Ok(Some(ev)),
Ok(Ok(Frame::Error(e))) => Err(ClientError::Server(e)),
Ok(Ok(_)) => Err(ClientError::UnexpectedFrame {
got: "non-event en await_event",
}),
}
}
/// Pide al servidor el listado de sesiones activas. Pensado para
/// observadores (broker-explorer, CLIs de diagnóstico). Como
/// `ping`, los `MatchEvent` que lleguen intercalados se bufean
/// en `pending_events` y no rompen la respuesta.
pub async fn list_sessions(&mut self) -> Result<crate::messages::SessionList, ClientError> {
write_frame(
&mut self.stream,
&Frame::ListSessions(crate::messages::ListSessions {
session: self.session,
}),
)
.await?;
loop {
match read_frame(&mut self.stream).await? {
Frame::SessionList(list) => return Ok(list),
Frame::MatchEvent(ev) => self.pending_events.push_back(ev),
Frame::Error(e) => return Err(ClientError::Server(e)),
_ => {
return Err(ClientError::UnexpectedFrame {
got: "non-session-list",
});
}
}
}
}
/// Pide al servidor el listado de matches actuales del broker
/// (consumer↔producer pares con tipo y estrategia). Mismo patrón
/// de drenado de `MatchEvent`s intermedios.
pub async fn list_matches(&mut self) -> Result<crate::messages::MatchList, ClientError> {
write_frame(
&mut self.stream,
&Frame::ListMatches(crate::messages::ListMatches {
session: self.session,
}),
)
.await?;
loop {
match read_frame(&mut self.stream).await? {
Frame::MatchList(list) => return Ok(list),
Frame::MatchEvent(ev) => self.pending_events.push_back(ev),
Frame::Error(e) => return Err(ClientError::Server(e)),
_ => {
return Err(ClientError::UnexpectedFrame {
got: "non-match-list",
});
}
}
}
}
/// Cierre cooperativo. Consume el cliente.
pub async fn farewell(mut self) -> Result<(), ClientError> {
write_frame(
&mut self.stream,
&Frame::Farewell(Farewell {
session: self.session,
}),
)
.await?;
Ok(())
}
}
02_ruway/chasqui/card-handshake/src/codec.rs
+72
View File
@@ -0,0 +1,72 @@
//! Codec de wire: frames length-prefixed con cuerpo postcard.
//!
//! Cada frame en el stream tiene la forma:
//! ```text
//! [4 bytes LE: longitud N] [N bytes: postcard(Frame)]
//! ```
//!
//! El `MAX_FRAME_BYTES` evita que un cliente malicioso/buggy reserve memoria
//! arbitraria al anunciar un length absurdo.
use std::io::{Error, ErrorKind, Result};
use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
use crate::messages::Frame;
/// Tamaño máximo de un frame antes de que el reader rechace la conexión.
/// 4 MiB cubre cualquier Card razonable con margen amplio.
pub const MAX_FRAME_BYTES: usize = 4 * 1024 * 1024;
/// Escribe un frame al stream.
pub async fn write_frame<W: AsyncWrite + Unpin>(w: &mut W, frame: &Frame) -> Result<()> {
let bytes = postcard::to_allocvec(frame)
.map_err(|e| Error::new(ErrorKind::InvalidData, format!("postcard encode: {e}")))?;
if bytes.len() > MAX_FRAME_BYTES {
return Err(Error::new(
ErrorKind::InvalidData,
format!("frame demasiado grande: {} bytes", bytes.len()),
));
}
let len = bytes.len() as u32;
w.write_all(&len.to_le_bytes()).await?;
w.write_all(&bytes).await?;
w.flush().await?;
Ok(())
}
/// Lee un frame del stream.
pub async fn read_frame<R: AsyncRead + Unpin>(r: &mut R) -> Result<Frame> {
let mut len_buf = [0u8; 4];
r.read_exact(&mut len_buf).await?;
let len = u32::from_le_bytes(len_buf) as usize;
if len > MAX_FRAME_BYTES {
return Err(Error::new(
ErrorKind::InvalidData,
format!("frame anunciado demasiado grande: {len} bytes"),
));
}
let mut buf = vec![0u8; len];
r.read_exact(&mut buf).await?;
postcard::from_bytes(&buf)
.map_err(|e| Error::new(ErrorKind::InvalidData, format!("postcard decode: {e}")))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::messages::{Frame, HandshakeError};
#[tokio::test]
async fn frame_roundtrip() {
let frame = Frame::Error(HandshakeError::Rejected("test".into()));
let mut buf = Vec::new();
write_frame(&mut buf, &frame).await.unwrap();
let mut cursor = std::io::Cursor::new(buf);
let decoded = read_frame(&mut cursor).await.unwrap();
match decoded {
Frame::Error(HandshakeError::Rejected(s)) => assert_eq!(s, "test"),
_ => panic!("variant mismatch"),
}
}
}
02_ruway/chasqui/card-handshake/src/identity.rs
+358
View File
@@ -0,0 +1,358 @@
//! Identidad multi-key del nodo: separación entre **identity** (master,
//! persistente forever) y **session** (keypair libp2p efímera, rotable).
//!
//! ## Problema que resuelve
//!
//! Hasta Fase 3, el `peer_id` libp2p era la única identidad. Rotar la
//! keypair (por compromiso, por higiene, por cambio de hardware)
//! cambiaba el peer_id, lo que invalidaba todas las allowlists
//! remotas y desconectaba al nodo de la malla. Imposible rotar sin
//! coordinar.
//!
//! ## Modelo
//!
//! Cada nodo tiene **dos** keypairs Ed25519:
//!
//! - **Identity** (master): persistente para siempre. Identifica al
//! nodo como entidad lógica. Su `peer_id` es lo que va en
//! allowlists/denylists remotas.
//! - **Session** (operacional): la que libp2p usa para Noise. Puede
//! rotarse libremente sin coordinar — el nodo emite un
//! [`SessionCert`] firmado con la identity que prueba "esta session
//! key pertenece a mí".
//!
//! ## Wire
//!
//! El cert viaja en `Hello.identity_cert: Option<SessionCert>`. El
//! server valida:
//! 1. La session key del cert == public key de `Hello.signature` ==
//! deriva al peer_id autenticado por Noise (consistencia interna).
//! 2. La firma del cert verifica con la master pubkey declarada.
//! 3. El cert no está expirado.
//! 4. La política (allowlist/denylist) se evalúa contra
//! `master.to_peer_id()`, NO contra el session peer_id.
//!
//! Sin cert, el server cae al modelo de Fase 3: policy contra session
//! peer_id (compat). Esto permite migración gradual.
use std::sync::Arc;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use card_net::{Keypair, PeerId, PublicKey};
use serde::{Deserialize, Serialize};
/// TTL recomendado para un session cert: 24 horas. Suficiente para
/// que un nodo "viva" un día sin re-emitir; corto enough para que
/// un cert robado no sirva por mucho. Operadores con políticas
/// estrictas pueden bajarlo; con uptime largo, subirlo.
pub const DEFAULT_SESSION_TTL: Duration = Duration::from_secs(24 * 60 * 60);
/// Identidad lógica del nodo. Wraps la master keypair y emite certs
/// de session firmados.
///
/// **Critical**: la master keypair NUNCA debe filtrarse a la red.
/// Sólo se usa para firmar certs locales y para derivar
/// `master_peer_id`. Ni siquiera el swarm libp2p la ve — ese usa la
/// session keypair.
#[derive(Clone)]
pub struct Identity {
master: Arc<Keypair>,
}
impl Identity {
/// Construye una Identity a partir de una keypair existente.
/// Típicamente cargada desde disco vía `keypair_store::load_or_generate`.
pub fn from_keypair(master: Keypair) -> Self {
Self {
master: Arc::new(master),
}
}
/// Variante para callers que ya tienen la keypair en `Arc`.
pub fn from_arc(master: Arc<Keypair>) -> Self {
Self { master }
}
/// PeerId derivado de la master pubkey. Ésta es la identidad
/// "lógica" estable del nodo — lo que va en allowlists/denylists.
pub fn master_peer_id(&self) -> PeerId {
self.master.public().to_peer_id()
}
/// Emite un [`SessionCert`] firmado: certifica que la session
/// keypair `session` pertenece a esta identity hasta `now + ttl`.
pub fn issue_session_cert(
&self,
session: &Keypair,
ttl: Duration,
) -> Result<SessionCert, CertError> {
let now_ms = now_unix_ms();
let expires_at_ms = now_ms.saturating_add(ttl.as_millis() as u64);
let session_pubkey = session.public().encode_protobuf();
let master_pubkey = self.master.public().encode_protobuf();
let payload = sign_payload(&session_pubkey, expires_at_ms);
let signature = self
.master
.sign(&payload)
.map_err(|e| CertError::Sign(e.to_string()))?;
Ok(SessionCert {
version: SESSION_CERT_VERSION,
session_pubkey,
master_pubkey,
expires_at_ms,
signature,
})
}
}
impl std::fmt::Debug for Identity {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Identity")
.field("master_peer_id", &self.master_peer_id())
.finish()
}
}
/// Versión del esquema del cert. Bump al cambiar `sign_payload` o
/// el shape de `SessionCert`.
pub const SESSION_CERT_VERSION: u8 = 1;
/// Certificado firmado por la identity que vincula una session key
/// libp2p a la identidad master del nodo, con expiración.
///
/// **Wire**: viaja en `Hello.identity_cert`. Las pubkeys van en
/// format canónico libp2p (`encode_protobuf`) — mismo encoding que
/// `HelloSignature.public_key`.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SessionCert {
/// Versión del esquema (ver `SESSION_CERT_VERSION`).
pub version: u8,
/// Public key de la session libp2p (la que firma el Hello), en
/// format libp2p protobuf.
pub session_pubkey: Vec<u8>,
/// Public key de la master identity, en format libp2p protobuf.
/// El verificador deriva el `master_peer_id` desde acá.
pub master_pubkey: Vec<u8>,
/// Expiración en milisegundos desde UNIX_EPOCH. Tras esto, el
/// cert no es válido y el nodo debe re-emitirse uno nuevo
/// (rotando o re-firmando la misma session).
pub expires_at_ms: u64,
/// Firma Ed25519 del master sobre `sign_payload(session_pubkey, expires_at_ms)`.
pub signature: Vec<u8>,
}
#[derive(Debug, thiserror::Error)]
pub enum CertError {
#[error("versión de cert desconocida: {0} (esperaba {SESSION_CERT_VERSION})")]
UnknownVersion(u8),
#[error("decode master_pubkey: {0}")]
DecodeMaster(String),
#[error("decode session_pubkey: {0}")]
DecodeSession(String),
#[error("firma del cert inválida")]
InvalidSignature,
#[error("cert expirado: expires_at_ms={expires}, now_ms={now}")]
Expired { expires: u64, now: u64 },
#[error("session_pubkey del cert no coincide con la del Hello.signature")]
SessionMismatch,
#[error("error al firmar: {0}")]
Sign(String),
}
impl SessionCert {
/// Verifica el cert: versión, firma criptográfica, no expiración.
/// Devuelve el `(master_peer_id, session_peer_id)` derivados.
///
/// El caller debe además chequear que `session_peer_id` coincide
/// con el peer_id autenticado por Noise (lo verifica
/// [`verify_against_session`]).
pub fn verify(&self) -> Result<(PeerId, PeerId), CertError> {
if self.version != SESSION_CERT_VERSION {
return Err(CertError::UnknownVersion(self.version));
}
let master_pk = PublicKey::try_decode_protobuf(&self.master_pubkey)
.map_err(|e| CertError::DecodeMaster(e.to_string()))?;
let session_pk = PublicKey::try_decode_protobuf(&self.session_pubkey)
.map_err(|e| CertError::DecodeSession(e.to_string()))?;
let payload = sign_payload(&self.session_pubkey, self.expires_at_ms);
if !master_pk.verify(&payload, &self.signature) {
return Err(CertError::InvalidSignature);
}
let now = now_unix_ms();
if now >= self.expires_at_ms {
return Err(CertError::Expired {
expires: self.expires_at_ms,
now,
});
}
Ok((master_pk.to_peer_id(), session_pk.to_peer_id()))
}
/// Verifica el cert Y exige que su `session_pubkey` matchee a
/// `expected_session_pubkey` (la que firmó el Hello). Esto
/// previene que un atacante reutilice un cert válido con una
/// session key distinta.
///
/// Devuelve el `master_peer_id` derivado, que es el que el server
/// debe usar para evaluar la política de admisión.
pub fn verify_against_session(
&self,
expected_session_pubkey: &[u8],
) -> Result<PeerId, CertError> {
if self.session_pubkey.as_slice() != expected_session_pubkey {
return Err(CertError::SessionMismatch);
}
let (master_peer, _session_peer) = self.verify()?;
Ok(master_peer)
}
}
/// Concat canónico de los campos firmados. Cualquier cambio aquí
/// rompe compatibilidad — bump `SESSION_CERT_VERSION`.
fn sign_payload(session_pubkey: &[u8], expires_at_ms: u64) -> Vec<u8> {
let mut buf = Vec::with_capacity(1 + 4 + session_pubkey.len() + 8);
buf.push(SESSION_CERT_VERSION);
buf.extend_from_slice(b"sess");
buf.extend_from_slice(&(session_pubkey.len() as u32).to_le_bytes());
buf.extend_from_slice(session_pubkey);
buf.extend_from_slice(&expires_at_ms.to_le_bytes());
buf
}
fn now_unix_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn issue_and_verify_cert() {
let master = Keypair::generate_ed25519();
let session = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let cert = id
.issue_session_cert(&session, DEFAULT_SESSION_TTL)
.unwrap();
let (master_peer, session_peer) = cert.verify().unwrap();
assert_eq!(master_peer, id.master_peer_id());
assert_eq!(session_peer, session.public().to_peer_id());
}
#[test]
fn verify_against_session_admits_matching() {
let master = Keypair::generate_ed25519();
let session = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let cert = id
.issue_session_cert(&session, DEFAULT_SESSION_TTL)
.unwrap();
let session_pk = session.public().encode_protobuf();
let master_peer = cert.verify_against_session(&session_pk).unwrap();
assert_eq!(master_peer, id.master_peer_id());
}
#[test]
fn verify_against_session_rejects_mismatch() {
let master = Keypair::generate_ed25519();
let session_a = Keypair::generate_ed25519();
let session_b = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let cert = id
.issue_session_cert(&session_a, DEFAULT_SESSION_TTL)
.unwrap();
let other_pk = session_b.public().encode_protobuf();
let err = cert.verify_against_session(&other_pk).unwrap_err();
assert!(matches!(err, CertError::SessionMismatch), "got {err:?}");
}
#[test]
fn cert_with_zero_ttl_is_expired() {
let master = Keypair::generate_ed25519();
let session = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let cert = id
.issue_session_cert(&session, Duration::from_secs(0))
.unwrap();
// Pequeña espera para asegurar que now_ms > expires_at_ms.
std::thread::sleep(Duration::from_millis(5));
let err = cert.verify().unwrap_err();
assert!(matches!(err, CertError::Expired { .. }), "got {err:?}");
}
#[test]
fn tampered_signature_rejected() {
let master = Keypair::generate_ed25519();
let session = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let mut cert = id
.issue_session_cert(&session, DEFAULT_SESSION_TTL)
.unwrap();
if let Some(b) = cert.signature.last_mut() {
*b ^= 0x01;
}
let err = cert.verify().unwrap_err();
assert!(matches!(err, CertError::InvalidSignature), "got {err:?}");
}
#[test]
fn tampered_expires_at_rejected() {
// Si alguien extiende el expires_at sin re-firmar, la firma
// no cuadra → InvalidSignature.
let master = Keypair::generate_ed25519();
let session = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let mut cert = id
.issue_session_cert(&session, DEFAULT_SESSION_TTL)
.unwrap();
cert.expires_at_ms = cert.expires_at_ms.saturating_add(1_000_000);
let err = cert.verify().unwrap_err();
assert!(matches!(err, CertError::InvalidSignature), "got {err:?}");
}
#[test]
fn unknown_version_rejected() {
let master = Keypair::generate_ed25519();
let session = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let mut cert = id
.issue_session_cert(&session, DEFAULT_SESSION_TTL)
.unwrap();
cert.version = 99;
let err = cert.verify().unwrap_err();
assert!(matches!(err, CertError::UnknownVersion(99)), "got {err:?}");
}
#[test]
fn rotated_session_with_same_master_yields_same_master_peer_id() {
// La propiedad fundamental: rotar la session key NO cambia el
// master_peer_id derivado del cert.
let master = Keypair::generate_ed25519();
let id = Identity::from_keypair(master);
let original_master_peer = id.master_peer_id();
let session1 = Keypair::generate_ed25519();
let cert1 = id
.issue_session_cert(&session1, DEFAULT_SESSION_TTL)
.unwrap();
let (master_from_cert1, _) = cert1.verify().unwrap();
// Rotar: nueva session keypair, mismo master.
let session2 = Keypair::generate_ed25519();
let cert2 = id
.issue_session_cert(&session2, DEFAULT_SESSION_TTL)
.unwrap();
let (master_from_cert2, _) = cert2.verify().unwrap();
assert_eq!(master_from_cert1, original_master_peer);
assert_eq!(master_from_cert2, original_master_peer);
assert_eq!(
master_from_cert1, master_from_cert2,
"rotar session NO debe cambiar el master_peer_id"
);
}
}
02_ruway/chasqui/card-handshake/src/lib.rs
+33
View File
@@ -0,0 +1,33 @@
//! `brahman-handshake` — protocolo runtime Init↔módulo sobre Unix socket.
//!
//! Implementa la versión concreta de `shared_wit/protocol.wit` (handshake +
//! lifecycle): un servidor que vive en el Init (o un Admin proxy) y clientes
//! que son los módulos Brahman. Cada conexión arranca con un `Hello` que
//! lleva una [`card_core::Card`]; el servidor valida la Card, deriva el
//! [`TrustLevel`], emite un `HelloAck` con `session-id` ULID, y a partir de
//! ahí acepta `Ping`/`Farewell`.
//!
//! Wire format: frames length-prefixed (4 bytes LE) con cuerpo
//! [`postcard`]-codificado. Compacto, rápido y reversible.
//!
//! Esto NO es la implementación WIT/WASM (que generaría wit-bindgen). Es la
//! implementación nativa Rust↔Rust que cubre el caso común antes de que los
//! módulos WASM consuman el mismo contrato vía ABI generada.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
pub mod codec;
pub mod identity;
pub mod messages;
pub mod server;
pub mod client;
pub mod network;
pub mod peer_policy;
pub mod signature;
pub mod transport;
pub use card_core::PROTOCOL_VERSION;
/// Versión del crate de handshake (independiente de `PROTOCOL_VERSION`).
pub const HANDSHAKE_VERSION: &str = env!("CARGO_PKG_VERSION");
02_ruway/chasqui/card-handshake/src/messages.rs
+234
View File
@@ -0,0 +1,234 @@
//! Mensajes del protocolo de handshake.
//!
//! Todos los mensajes que cruzan el wire son variantes de [`Frame`].
use std::path::PathBuf;
use chasqui_broker::MatchStrategy;
use card_core::{TypeRef, WireCard, WitInterface};
use serde::{Deserialize, Serialize};
use ulid::Ulid;
/// Identificador de sesión emitido por el servidor en `HelloAck`.
pub type SessionId = Ulid;
/// Saludo inicial del módulo. Lleva la Card en forma `WireCard`
/// (postcard-friendly: sin extensiones JSON arbitrarias). El servidor
/// la convierte a `Card` para uso interno. Opcionalmente, una
/// `WitInterface` ya extraída — si está presente, el módulo es
/// "consciente" y el server lo registra como `ResolvedCard::from_conscious`.
///
/// **Firma (Fase 3, trust remoto)**: el campo `signature` es
/// obligatorio para conexiones libp2p (donde el server exige que la
/// public key derive al `peer_id` autenticado por Noise) y opcional
/// para Unix socket (donde SO_PEERCRED del kernel ya provee
/// autenticación). La firma cubre los bytes postcard de
/// `(WireCard, Option<WitInterface>)` — ver
/// [`HelloSignature::sign_payload`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Hello {
/// Versión del schema de Card que el cliente sigue.
pub schema_version: u16,
/// Versión del protocolo handshake del cliente.
pub protocol_version: String,
/// Tarjeta de Presentación, proyectada al wire.
pub card: WireCard,
/// 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<WitInterface>,
/// Firma Ed25519 sobre `(card, wit)`. Requerida para conexiones
/// remotas (libp2p); opcional para Unix socket. Ver módulo
/// [`super::signature`] para construcción y verificación.
#[serde(default)]
pub signature: Option<HelloSignature>,
/// Cert opcional que vincula la session keypair (la que firma el
/// Hello) a una **identity master** estable. Si está presente,
/// la política de admisión se evalúa contra el `master_peer_id`
/// derivado del cert — no contra el session peer_id. Esto permite
/// rotar la session sin invalidar las allowlists remotas.
///
/// Ver [`super::identity::SessionCert`] para shape y semantics.
/// Si es `None`, fallback al modelo de Fase 3: la política
/// evalúa el session peer_id directamente.
#[serde(default)]
pub identity_cert: Option<crate::identity::SessionCert>,
}
/// Firma de un Hello. La `public_key` viaja en el format canónico
/// libp2p (protobuf) — el verificador la decodifica y compara su
/// `peer_id` derivado con la identidad libp2p autenticada por Noise.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct HelloSignature {
/// Public key del firmante, encoded como `libp2p::identity::PublicKey::encode_protobuf()`.
pub public_key: Vec<u8>,
/// Bytes de la firma Ed25519 sobre el payload canonical.
pub signature: Vec<u8>,
}
/// Respuesta del servidor a un `Hello` aceptado.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HelloAck {
/// Versión del crate del servidor.
pub server_version: String,
/// Versión del protocolo soportada por el servidor.
pub protocol_version: String,
/// Identificador de sesión asignado.
pub session: SessionId,
/// `true` si el Init está vinculado al servidor; `false` si el servidor
/// corre standalone (modo degradado).
pub init_attached: bool,
}
/// Latido del cliente. El servidor responde con [`Pong`] llevando su reloj.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Ping {
pub session: SessionId,
}
/// Respuesta a un `Ping` con timestamp del servidor (ms desde UNIX_EPOCH).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Pong {
pub timestamp_ms: u64,
}
/// Cierre cooperativo de la sesión por parte del cliente.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Farewell {
pub session: SessionId,
}
/// Errores del protocolo emitidos por el servidor.
#[derive(Debug, Clone, Serialize, Deserialize, thiserror::Error)]
pub enum HandshakeError {
#[error("protocolo incompatible: {0}")]
ProtocolMismatch(String),
#[error("card inválida: {0}")]
InvalidCard(String),
#[error("schema de card incompatible: cliente={client}, servidor={server}")]
SchemaMismatch { client: u16, server: u16 },
#[error("sin autorización: {0}")]
Unauthorized(String),
#[error("capacidad requerida no satisfecha: {0}")]
CapabilityUnmet(String),
#[error("rechazado: {0}")]
Rejected(String),
#[error("error interno: {0}")]
Internal(String),
}
/// Notificación push del server al consumer: un match disponible o perdido.
///
/// El server emite `Available` cuando un productor empieza a satisfacer un
/// `flow.input` del consumer (ya sea porque el productor acaba de
/// registrarse, o porque cambió el match anterior). Emite `Lost` cuando
/// el productor previo dejó de satisfacer el input (desregistro o
/// cambio de match).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MatchEvent {
pub kind: MatchEventKind,
/// Nombre del input del consumer al que aplica el evento.
pub consumer_flow: String,
/// Sesión y label del productor (en `Lost` puede ser nil/vacío).
pub producer_session: SessionId,
pub producer_label: String,
pub producer_flow: String,
/// Tipo del flujo matcheado.
pub ty: TypeRef,
/// Estrategia que ganó (relevante en `Available`).
pub via: MatchStrategy,
/// `true` si fue resuelto por `pin_to`.
pub pinned: bool,
/// Socket de servicio (data plane) que declaró el productor.
/// Si está presente, el consumer puede conectar directo sin
/// pasar por discovery adicional. `None` si el productor no
/// declaró service_socket en su Card.
#[serde(default)]
pub producer_service_socket: Option<PathBuf>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum MatchEventKind {
Available,
Lost,
}
/// Pedido de listado de sesiones activas registradas en el broker. La
/// `session` es el id propio del que pregunta — el server lo valida
/// contra la sesión actual de la conexión, mismo patrón que `Ping`.
///
/// Pensado para herramientas de observabilidad (broker-explorer y
/// CLIs de diagnóstico). No expone secrets: sólo metadata pública
/// que el módulo ya anunció en su `Hello`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListSessions {
pub session: SessionId,
}
/// Una entrada en la respuesta a `ListSessions`. Slim por diseño —
/// el observer arma la UI con esto sin tener que abrir conexiones
/// adicionales por sesión.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionEntry {
pub session: SessionId,
/// Label declarado en `WireCard.label` — el "nombre humano" del
/// módulo.
pub label: String,
/// Versión del schema de Card que el módulo declaró.
pub schema_version: u16,
/// Nombres de los `flow.output` que la Card declara producir.
pub outputs: Vec<String>,
/// Nombres de los `flow.input` que la Card declara consumir.
pub inputs: Vec<String>,
/// `true` si el módulo se anunció como "consciente" (trajo
/// `WitInterface` extraída en el Hello).
pub conscious: bool,
}
/// Respuesta a `ListSessions`. El orden no está garantizado — los
/// clientes que necesiten estabilidad pueden ordenar por `session`
/// (Ulid es ordenable temporal).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SessionList {
pub entries: Vec<SessionEntry>,
}
/// Pedido del listado de matches actuales del broker. La `session`
/// se valida igual que `ListSessions`. Si el server no tiene broker
/// configurado, devuelve la lista vacía (no es un error — refleja
/// que no hay matching activo).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListMatches {
pub session: SessionId,
}
/// Respuesta a `ListMatches` con el snapshot de matches consumidor↔productor
/// actualmente computados por el broker.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MatchList {
pub matches: Vec<chasqui_broker::Match>,
}
/// Frame único de wire — discriminada por variante. Cada conexión es un
/// stream de frames.
///
/// Direcciones:
/// - Cliente → Server: `Hello`, `Ping`, `Farewell`, `ListSessions`,
/// `ListMatches`.
/// - Server → Cliente: `HelloAck`, `Pong`, `Error`, `MatchEvent`,
/// `SessionList`, `MatchList`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum Frame {
Hello(Hello),
HelloAck(HelloAck),
Ping(Ping),
Pong(Pong),
Farewell(Farewell),
Error(HandshakeError),
MatchEvent(MatchEvent),
ListSessions(ListSessions),
SessionList(SessionList),
ListMatches(ListMatches),
MatchList(MatchList),
}
02_ruway/chasqui/card-handshake/src/network.rs
+289
View File
@@ -0,0 +1,289 @@
//! Backend libp2p del handshake brahman: el mismo protocolo (Hello /
//! HelloAck / Ping / Pong / MatchEvent / Farewell, frames postcard
//! length-prefixed) ahora también viaja sobre streams libp2p de la
//! malla `brahman-net`.
//!
//! El servidor expone el bucle [`run_libp2p_accept_loop`] que acepta
//! streams del protocolo `BRAHMAN_HANDSHAKE_PROTOCOL` y los delega al
//! mismo `Server` que ya escucha por Unix socket — la `Session` es
//! genérica sobre el transporte, así que ambas vías comparten broker,
//! tablas de sesiones, push de MatchEvents, todo.
//!
//! El cliente se conecta vía [`connect_libp2p`]: abre un stream
//! libp2p hacia un `PeerId` ya conocido y arranca el handshake como
//! cualquier `Client`.
//!
//! Identidad: cada nodo libp2p tiene su `PeerId` (ed25519 derivado).
//! La identidad del Ente (Card.id ULID + futura firma) viaja en el
//! Hello, como en el path Unix. Trust remoto (verificación de firma
//! antes de aceptar el Hello) es Fase 3.
//!
//! Ejemplo (servidor — Arje):
//! ```ignore
//! let server = Arc::new(Server::bind("/run/brahman-init.sock", config)?);
//! let net = Arc::new(BrahmanNet::new()?);
//! net.listen("/ip4/0.0.0.0/tcp/4101".parse()?).await;
//!
//! tokio::spawn(card_handshake::network::run_libp2p_accept_loop(
//! server.clone(),
//! net.clone(),
//! ));
//! // Server::run sigue escuchando Unix en paralelo.
//! ```
//!
//! Ejemplo (cliente — sidecar de un Ente remoto):
//! ```ignore
//! let net = BrahmanNet::new()?;
//! net.dial(remote_multiaddr);
//! let mut client = card_handshake::network::connect_libp2p(
//! &net, peer_id, my_card, None,
//! ).await?;
//! client.ping().await?;
//! ```
use std::sync::Arc;
use card_core::{Card, TypeRef, WitInterface};
use card_net::{BrahmanNet, Keypair, OpenStreamError, PeerId, Stream, StreamProtocol};
use crate::identity::SessionCert;
use futures::StreamExt;
use tokio_util::compat::{Compat, FuturesAsyncReadCompatExt};
use tracing::{debug, warn};
use crate::client::{Client, ClientError};
use crate::server::Server;
/// Sub-protocolo del handshake brahman sobre streams libp2p.
pub const BRAHMAN_HANDSHAKE_PROTOCOL: StreamProtocol =
StreamProtocol::new("/brahman/handshake/1.0.0");
/// Tipo del stream que ve la lógica del handshake una vez convertido
/// del mundo `futures::AsyncRead/Write` (libp2p) al mundo
/// `tokio::io::AsyncRead/Write` (resto del crate).
pub type LibP2pHandshakeStream = Compat<Stream>;
/// Errores específicos del backend libp2p.
#[derive(Debug, thiserror::Error)]
pub enum NetworkError {
#[error("abrir stream libp2p: {0}")]
OpenStream(#[from] OpenStreamError),
#[error("handshake: {0}")]
Handshake(#[from] ClientError),
#[error("aceptar stream libp2p: {0}")]
AcceptStream(String),
}
/// Loop de aceptación de streams libp2p del protocolo handshake.
/// Cada stream entrante se construye como `Session` reutilizando las
/// tablas compartidas del `Server`, así que conviven con sesiones
/// Unix indistinguibles.
///
/// Vive hasta que el control libp2p se cierre o el caller drop el
/// future. Errores por sesión se loggean (no tumban el loop).
pub async fn run_libp2p_accept_loop(
server: Arc<Server>,
net: Arc<BrahmanNet>,
) -> Result<(), NetworkError> {
let mut control = net.control.clone();
let mut incoming = control
.accept(BRAHMAN_HANDSHAKE_PROTOCOL)
.map_err(|e| NetworkError::AcceptStream(e.to_string()))?;
while let Some((peer, stream)) = incoming.next().await {
let server = server.clone();
// .compat() debe pasar al spawn ADENTRO; si lo hacemos afuera
// y capturamos `Compat<Stream>` en la closure, el future
// resultante hereda traits que dyn AsyncReadWrite no satisface
// (compatibility con thread-safety de tokio::spawn).
tokio::spawn(handle_libp2p_session(server, stream, peer));
}
Ok(())
}
async fn handle_libp2p_session(
server: Arc<Server>,
stream: Stream,
peer: PeerId,
) {
// session_from_libp2p_stream propaga el peer_id al `do_handshake`,
// que exige firma del Hello cuya public key derive a este peer.
let session = server.session_from_libp2p_stream(stream.compat(), peer);
if let Err(e) = session.handle().await {
warn!(
target: "card_handshake::network",
peer = %peer,
error = %e,
"sesión libp2p terminó con error"
);
}
}
/// Conecta como cliente a un Ente remoto vía libp2p y completa el
/// handshake **firmado** con `keypair`. Requiere que `net` ya tenga
/// conexión (o pueda dial-ar) al `peer`; típicamente el caller hace
/// `net.dial(multiaddr)` antes.
///
/// La `keypair` debe ser la misma que la del nodo libp2p (la que
/// pasaste a [`card_net::BrahmanNet::with_keypair`]). Si no coincide
/// con el `peer_id` autenticado por Noise, el server rechaza el Hello
/// con `Unauthorized`.
///
/// Devuelve un `Client` típico — los métodos `ping`, `await_event`,
/// `farewell` funcionan idéntico al path Unix. El stream subyacente
/// es libp2p convertido vía `tokio_util::compat`.
pub async fn connect_libp2p(
net: &BrahmanNet,
peer: PeerId,
card: Card,
wit: Option<WitInterface>,
keypair: &Keypair,
) -> Result<Client<LibP2pHandshakeStream>, NetworkError> {
let mut control = net.control.clone();
let stream = control
.open_stream(peer, BRAHMAN_HANDSHAKE_PROTOCOL)
.await?;
let client = Client::connect_with_stream_signed(stream.compat(), card, wit, keypair).await?;
Ok(client)
}
/// Igual que `connect_libp2p` pero adjunta un `SessionCert` al Hello.
/// El server, al verificar el cert, evalúa la política de admisión
/// contra el `master_peer_id` derivado — no contra el `peer_id`
/// libp2p. Esto permite **rotar** la session keypair sin perder
/// reconocimiento en allowlists remotas.
///
/// El `keypair` debe ser la session libp2p (la que firma la conexión
/// Noise); el `cert` debe haber sido emitido por una identity master
/// para esa misma session pubkey (ver
/// [`crate::identity::Identity::issue_session_cert`]).
pub async fn connect_libp2p_with_cert(
net: &BrahmanNet,
peer: PeerId,
card: Card,
wit: Option<WitInterface>,
session_keypair: &Keypair,
cert: SessionCert,
) -> Result<Client<LibP2pHandshakeStream>, NetworkError> {
let mut control = net.control.clone();
let stream = control
.open_stream(peer, BRAHMAN_HANDSHAKE_PROTOCOL)
.await?;
let client = Client::connect_with_stream_signed_with_cert(
stream.compat(),
card,
wit,
session_keypair,
cert,
)
.await?;
Ok(client)
}
// =====================================================================
// Discovery remoto via DHT — Fase 2
// =====================================================================
//
// Cuando un Ente registra una Card con outputs en el Init local, el
// Init anuncia al DHT (`net.start_providing(key)`) bajo una key
// derivada de `(flow_name, TypeRef)`. Cualquier nodo conectado al
// mismo DHT puede consultar `find_remote_providers(flow_name, type)`
// y obtener la lista de `PeerId`s que dijeron proveer ese flow.
//
// La key es **estable y libre de colisiones** entre versiones del
// monorepo: usa blake3 sobre un canon textual `brahman-flow|{name}|{type_canon}`.
// Cambiar la canonicalización rompe el discovery cross-version, así
// que cualquier modificación requiere bump de versión documentado.
/// Prefijo de namespace para todas las keys DHT del subprotocolo
/// brahman. Discrimina contra otros usos del mismo DHT (sync minga,
/// futuros) — protege contra colisiones accidentales.
const FLOW_KEY_PREFIX: &str = "brahman-flow|v1|";
/// Canonicaliza un `TypeRef` a string estable. Cambios aquí rompen
/// la compatibilidad de discovery cross-version; bump documentado
/// en `FLOW_KEY_PREFIX` al modificar.
fn canonicalize_type(t: &TypeRef) -> String {
match t {
TypeRef::Primitive { name } => format!("prim:{}", name),
TypeRef::Wit {
package,
interface,
name,
} => format!(
"wit:{}#{}#{}",
package,
interface.as_deref().unwrap_or(""),
name
),
}
}
/// Deriva la key del DHT para un `(flow_name, type_ref)` específico.
/// blake3-32B determinístico — la misma tupla en cualquier máquina
/// produce la misma key.
pub fn flow_dht_key(flow_name: &str, type_ref: &TypeRef) -> [u8; 32] {
let canon = format!(
"{}{}|{}",
FLOW_KEY_PREFIX,
flow_name,
canonicalize_type(type_ref)
);
*blake3::hash(canon.as_bytes()).as_bytes()
}
/// Anuncia al DHT que este nodo provee cada output flow declarado
/// en `card`. Llamarlo tras `register_session` propaga la
/// disponibilidad a todos los peers que comparten DHT con éste.
///
/// Idempotente: re-anunciar la misma key actualiza el TTL del record
/// en el DHT. Best-effort: si `start_providing` falla por falta de
/// peers cercanos (DHT vacío), el record vive en el store local
/// hasta que llegue una conexión.
pub fn announce_outputs(net: &BrahmanNet, card: &Card) {
for flow in &card.flow.output {
let key = flow_dht_key(&flow.name, &flow.ty);
debug!(
target: "card_handshake::network",
flow = %flow.name,
"announce_output → DHT"
);
net.start_providing(&key);
}
}
/// Retira los anuncios DHT previos de [`announce_outputs`] para esta
/// `card`. Llamado desde `cleanup` cuando una sesión cierra (Farewell,
/// EOF, error). El record local se borra al instante; copias
/// replicadas en peers remotos expiran por TTL natural de kad.
pub fn withdraw_outputs(net: &BrahmanNet, card: &Card) {
for flow in &card.flow.output {
let key = flow_dht_key(&flow.name, &flow.ty);
debug!(
target: "card_handshake::network",
flow = %flow.name,
"withdraw_output → DHT (stop_providing)"
);
net.stop_providing(&key);
}
}
/// Consulta el DHT por peers que han anunciado proveer el flow
/// `(flow_name, type_ref)`. Devuelve la lista resuelta de `PeerId`s.
/// Lista vacía si nadie anuncia, si la query timeout-ea, o si el
/// DHT no ha encontrado providers.
///
/// Para cada `PeerId` devuelto, el caller puede luego dial-ar al
/// peer (a sus addrs conocidas vía Identify) y abrir un sub-handshake
/// remoto con [`connect_libp2p`].
pub async fn find_remote_providers(
net: &BrahmanNet,
flow_name: &str,
type_ref: &TypeRef,
) -> Vec<PeerId> {
let key = flow_dht_key(flow_name, type_ref);
net.find_providers(&key).await
}
02_ruway/chasqui/card-handshake/src/peer_policy.rs
+582
View File
@@ -0,0 +1,582 @@
//! Política de admisión de peers libp2p: allowlist + denylist con hot
//! reload opcional.
//!
//! Capa de política sobre el trust criptográfico de Fase 3. Combina:
//!
//! - **Denylist**: peers explícitamente baneados. Si está, deny gana.
//! - **Allowlist**: si está set, sólo los peers listados pasan.
//! Si no está set, modo abierto (todo peer Ed25519-válido pasa,
//! sujeto sólo a denylist).
//!
//! Sin denylist y sin allowlist → modo totalmente abierto (compat
//! con todo lo anterior). Con allowlist y denylist a la vez, el
//! orden de evaluación es: deny first → allow check → admit.
//!
//! Aplica únicamente al path libp2p — el path Unix usa SO_PEERCRED
//! del kernel para autenticación local, no PeerId.
//!
//! ## Hot reload
//!
//! Si la política se construyó con [`PeerPolicy::watch_files`], un
//! thread dedicado vigila los archivos de allow/deny vía `notify`.
//! Cualquier cambio (write, create, modify, remove) dispara una
//! recarga atómica con debounce de 250ms (los editores típicos
//! producen varios eventos por save).
//!
//! Errores de reload (parse fallido, archivo eliminado) se loggean
//! pero NO bajan la política existente — aceptamos la versión
//! anterior hasta que el archivo vuelva a parsearse limpio. Esto
//! evita que un error de tipeo deje al Init en modo inseguro.
//!
//! ## Formato del archivo
//!
//! Idéntico para allow y deny: PeerId base58 por línea, `#` para
//! comentarios (línea entera o inline), líneas vacías ignoradas.
use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
use std::sync::{Arc, RwLock};
use std::time::{Duration, Instant};
use card_net::{BrahmanNet, PeerId};
use tracing::{debug, info, warn};
/// Política de admisión combinada (allow + deny). Clone barato (todos
/// los campos son Arc o referencias inmutables).
#[derive(Clone)]
pub struct PeerPolicy {
inner: Arc<RwLock<PolicyInner>>,
paths: Arc<PolicyPaths>,
/// `BrahmanNet` opcional asociado vía [`Self::attach_to_net`].
/// Si está set, cada cambio en la denylist se sincroniza con el
/// `block_list` behaviour del swarm — los peers baneados son
/// rechazados ANTES del Noise handshake. `RwLock<Option<...>>`
/// para que `attach_to_net` se pueda llamar después del
/// constructor (típico en ente-zero: primero arma la policy,
/// después el net, después attach).
net: Arc<RwLock<Option<Arc<BrahmanNet>>>>,
}
#[derive(Default)]
struct PolicyInner {
/// `Some(set)`: sólo peers en el set pasan. `None`: modo abierto.
allow: Option<BTreeSet<PeerId>>,
/// Peers baneados. Vacío = sin denylist.
deny: BTreeSet<PeerId>,
}
#[derive(Default)]
struct PolicyPaths {
allow_path: Option<PathBuf>,
deny_path: Option<PathBuf>,
}
/// Decisión del gate de política para un peer dado.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Decision {
/// El peer es admitido (no está en deny y, si hay allow, está en allow).
Admit,
/// El peer está explícitamente en la denylist.
DeniedByDenylist,
/// Hay allowlist configurada y el peer no está en ella.
NotInAllowlist,
}
impl Decision {
pub fn is_admitted(self) -> bool {
matches!(self, Decision::Admit)
}
pub fn reason(self) -> &'static str {
match self {
Decision::Admit => "admit",
Decision::DeniedByDenylist => "explicitly denied",
Decision::NotInAllowlist => "not in allowlist",
}
}
}
#[derive(Debug, thiserror::Error)]
pub enum PolicyError {
#[error("leer política en {path}: {source}")]
Io {
path: PathBuf,
#[source]
source: std::io::Error,
},
#[error("línea {line_no} de {path}: PeerId inválido '{value}'")]
InvalidPeerId {
path: PathBuf,
line_no: usize,
value: String,
},
}
impl PeerPolicy {
/// Política totalmente abierta: todo peer pasa. Útil como default
/// cuando no hay archivos configurados.
pub fn open() -> Self {
Self {
inner: Arc::new(RwLock::new(PolicyInner::default())),
paths: Arc::new(PolicyPaths::default()),
net: Arc::new(RwLock::new(None)),
}
}
/// Construye una política inline con sets explícitos. Sin paths
/// asociados, así que `reload` y `watch_files` son no-ops.
pub fn from_sets(allow: Option<BTreeSet<PeerId>>, deny: BTreeSet<PeerId>) -> Self {
Self {
inner: Arc::new(RwLock::new(PolicyInner { allow, deny })),
paths: Arc::new(PolicyPaths::default()),
net: Arc::new(RwLock::new(None)),
}
}
/// Carga política desde archivos. Cada path es opcional: `None`
/// significa "esa lista no aplica" (allow=None ⇒ modo abierto;
/// deny=None ⇒ sin baneados). Asocia los paths internamente para
/// que `reload` y `watch_files` los re-lean.
pub fn from_files(
allow_path: Option<&Path>,
deny_path: Option<&Path>,
) -> Result<Self, PolicyError> {
let allow = match allow_path {
Some(p) => Some(parse_peer_set(p)?),
None => None,
};
let deny = match deny_path {
Some(p) => parse_peer_set(p)?,
None => BTreeSet::new(),
};
Ok(Self {
inner: Arc::new(RwLock::new(PolicyInner { allow, deny })),
paths: Arc::new(PolicyPaths {
allow_path: allow_path.map(Path::to_path_buf),
deny_path: deny_path.map(Path::to_path_buf),
}),
net: Arc::new(RwLock::new(None)),
})
}
/// Evalúa si `peer` puede registrarse. Toma read lock — barato,
/// concurrente, sin awaits.
pub fn evaluate(&self, peer: &PeerId) -> Decision {
let inner = match self.inner.read() {
Ok(g) => g,
Err(_) => {
// Lock envenenado: degrada a "deny por seguridad".
warn!("policy lock envenenado — deny por defecto");
return Decision::DeniedByDenylist;
}
};
if inner.deny.contains(peer) {
return Decision::DeniedByDenylist;
}
if let Some(allow) = &inner.allow {
if !allow.contains(peer) {
return Decision::NotInAllowlist;
}
}
Decision::Admit
}
/// Tamaño actual de cada lista, para logging. Tupla `(allow_count,
/// deny_count)`. `allow_count = None` significa "modo abierto"
/// (sin allowlist).
pub fn sizes(&self) -> (Option<usize>, usize) {
match self.inner.read() {
Ok(g) => (g.allow.as_ref().map(|s| s.len()), g.deny.len()),
Err(_) => (Some(0), 0),
}
}
/// Recarga atómica desde los paths asociados. Si un archivo
/// falla, la versión anterior persiste y el error se devuelve.
/// Esto evita que un typo en el archivo deje al Init en modo
/// inseguro.
///
/// Si hay un `BrahmanNet` attached vía [`Self::attach_to_net`],
/// el cambio de denylist se sincroniza con el `block_list` del
/// swarm: se calcula el diff (added/removed) y se aplican
/// `block_peer`/`unblock_peer` por cada cambio.
pub fn reload(&self) -> Result<(), PolicyError> {
let new_allow = match &self.paths.allow_path {
Some(p) => Some(parse_peer_set(p)?),
None => None,
};
let new_deny = match &self.paths.deny_path {
Some(p) => parse_peer_set(p)?,
None => BTreeSet::new(),
};
// Snapshot de la deny actual ANTES de mutar, para diff.
let prev_deny = self
.inner
.read()
.map(|g| g.deny.clone())
.unwrap_or_default();
if let Ok(mut inner) = self.inner.write() {
inner.allow = new_allow;
inner.deny = new_deny.clone();
}
self.sync_deny_to_swarm(&prev_deny, &new_deny);
Ok(())
}
/// Asocia esta política a un `BrahmanNet`. Sincroniza el snapshot
/// actual de la denylist con el `block_list` behaviour del swarm
/// (cada peer baneado se rechaza ANTES del Noise handshake), y
/// registra el net para re-sincronizarse en cada [`Self::reload`].
///
/// Si ya había un net attached, se reemplaza (caso esperado:
/// un Init no debería tener dos `BrahmanNet`s).
pub fn attach_to_net(&self, net: Arc<BrahmanNet>) {
// Sync inicial: bloquear todos los peers actualmente en deny.
if let Ok(inner) = self.inner.read() {
for peer in &inner.deny {
net.block_peer(*peer);
}
}
if let Ok(mut slot) = self.net.write() {
*slot = Some(net);
}
}
/// Calcula el diff entre `prev` y `new` y aplica
/// `block_peer`/`unblock_peer` al net asociado (si hay).
/// No-op si no hay net attached.
fn sync_deny_to_swarm(&self, prev: &BTreeSet<PeerId>, new: &BTreeSet<PeerId>) {
let net = match self.net.read() {
Ok(g) => match g.as_ref() {
Some(n) => n.clone(),
None => return,
},
Err(_) => return,
};
for added in new.difference(prev) {
net.block_peer(*added);
}
for removed in prev.difference(new) {
net.unblock_peer(*removed);
}
}
/// Arranca un thread que vigila los archivos asociados con
/// `notify` y llama [`Self::reload`] cuando cambian. Debounce
/// 250ms para coalescer múltiples eventos por save (los editores
/// hacen Create+Modify+más).
///
/// Devuelve un `JoinHandle` que el caller debe mantener vivo.
/// Drop del handle no detiene el thread (notify watcher es
/// sticky); para detener, terminar el proceso.
///
/// No-op si no hay paths asociados (devuelve un handle dummy
/// que termina inmediatamente).
pub fn spawn_watcher(&self) -> std::io::Result<std::thread::JoinHandle<()>> {
let allow_path = self.paths.allow_path.clone();
let deny_path = self.paths.deny_path.clone();
let policy = self.clone();
if allow_path.is_none() && deny_path.is_none() {
// Sin archivos a vigilar: spawn un thread que termina ya.
return std::thread::Builder::new()
.name("brahman-policy-watcher-noop".into())
.spawn(|| {});
}
std::thread::Builder::new()
.name("brahman-policy-watcher".into())
.spawn(move || {
run_watcher(policy, allow_path, deny_path);
})
}
}
impl std::fmt::Debug for PeerPolicy {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let (allow, deny) = self.sizes();
f.debug_struct("PeerPolicy")
.field("allow", &allow)
.field("deny", &deny)
.field("allow_path", &self.paths.allow_path)
.field("deny_path", &self.paths.deny_path)
.finish()
}
}
fn parse_peer_set(path: &Path) -> Result<BTreeSet<PeerId>, PolicyError> {
let contents = std::fs::read_to_string(path).map_err(|e| PolicyError::Io {
path: path.to_path_buf(),
source: e,
})?;
let mut out = BTreeSet::new();
for (idx, raw) in contents.lines().enumerate() {
let line_no = idx + 1;
let trimmed = raw.split('#').next().unwrap_or("").trim();
if trimmed.is_empty() {
continue;
}
let peer = trimmed
.parse::<PeerId>()
.map_err(|_| PolicyError::InvalidPeerId {
path: path.to_path_buf(),
line_no,
value: trimmed.to_string(),
})?;
out.insert(peer);
}
Ok(out)
}
const DEBOUNCE_MS: u64 = 250;
fn run_watcher(
policy: PeerPolicy,
allow_path: Option<PathBuf>,
deny_path: Option<PathBuf>,
) {
use notify::{RecursiveMode, Watcher};
let (tx, rx) = std::sync::mpsc::channel::<notify::Result<notify::Event>>();
let mut watcher = match notify::recommended_watcher(move |res| {
let _ = tx.send(res);
}) {
Ok(w) => w,
Err(e) => {
warn!(?e, "notify watcher para policy no se pudo crear — hot reload deshabilitado");
return;
}
};
// Vigilamos los DIRECTORIOS de los archivos, no los archivos
// directos. Los editores típicos hacen rename-and-replace (escriben
// a tmp, rename al destino), lo que rompe el watch del archivo
// pero NO el del directorio. Trade-off: recibimos más eventos
// (cualquier archivo del dir), filtramos por path al procesar.
for p in [&allow_path, &deny_path].iter().filter_map(|x| x.as_ref()) {
if let Some(parent) = p.parent() {
if let Err(e) = watcher.watch(parent, RecursiveMode::NonRecursive) {
warn!(path = %parent.display(), ?e, "watch failed");
}
}
}
let debounce = Duration::from_millis(DEBOUNCE_MS);
let mut pending_at: Option<Instant> = None;
loop {
let timeout = match pending_at {
Some(at) => debounce.saturating_sub(at.elapsed()).max(Duration::from_millis(10)),
None => Duration::from_secs(60), // wakeup periódico, no esencial
};
match rx.recv_timeout(timeout) {
Ok(Ok(event)) => {
// Sólo nos interesan eventos sobre los paths exactos.
let touches_us = event.paths.iter().any(|p| {
Some(p) == allow_path.as_ref() || Some(p) == deny_path.as_ref()
});
if !touches_us {
continue;
}
debug!(?event.kind, "policy file event recibido — debounce");
pending_at = Some(Instant::now());
}
Ok(Err(e)) => {
warn!(?e, "notify error en policy watcher");
}
Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
if let Some(at) = pending_at {
if at.elapsed() >= debounce {
match policy.reload() {
Ok(()) => {
let (a, d) = policy.sizes();
info!(
allow = ?a,
deny = d,
"policy hot-reload completo"
);
}
Err(e) => {
warn!(?e, "policy hot-reload falló — manteniendo versión anterior");
}
}
pending_at = None;
}
}
}
Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => {
warn!("policy watcher channel cerrado — terminando thread");
return;
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use card_net::Keypair;
use tempfile::TempDir;
fn fresh_peer() -> PeerId {
Keypair::generate_ed25519().public().to_peer_id()
}
#[test]
fn open_admits_anyone() {
let p = PeerPolicy::open();
assert_eq!(p.evaluate(&fresh_peer()), Decision::Admit);
}
#[test]
fn allow_only_admits_listed() {
let p1 = fresh_peer();
let p2 = fresh_peer();
let policy = PeerPolicy::from_sets(
Some([p1].into_iter().collect()),
BTreeSet::new(),
);
assert_eq!(policy.evaluate(&p1), Decision::Admit);
assert_eq!(policy.evaluate(&p2), Decision::NotInAllowlist);
}
#[test]
fn deny_overrides_open() {
let p1 = fresh_peer();
let p2 = fresh_peer();
let policy = PeerPolicy::from_sets(None, [p1].into_iter().collect());
assert_eq!(policy.evaluate(&p1), Decision::DeniedByDenylist);
assert_eq!(policy.evaluate(&p2), Decision::Admit);
}
#[test]
fn deny_overrides_allow() {
// Conflicto explícito: p1 está en ambas. Deny gana.
let p1 = fresh_peer();
let policy = PeerPolicy::from_sets(
Some([p1].into_iter().collect()),
[p1].into_iter().collect(),
);
assert_eq!(policy.evaluate(&p1), Decision::DeniedByDenylist);
}
#[test]
fn from_files_with_both_lists() {
let p1 = fresh_peer();
let p2 = fresh_peer();
let p3 = fresh_peer();
let tmp = TempDir::new().unwrap();
let allow = tmp.path().join("allow.txt");
let deny = tmp.path().join("deny.txt");
std::fs::write(&allow, format!("{}\n{}\n", p1, p2)).unwrap();
std::fs::write(&deny, format!("# baneado\n{}\n", p2)).unwrap();
let policy = PeerPolicy::from_files(Some(&allow), Some(&deny)).unwrap();
assert_eq!(policy.evaluate(&p1), Decision::Admit);
assert_eq!(policy.evaluate(&p2), Decision::DeniedByDenylist); // deny gana
assert_eq!(policy.evaluate(&p3), Decision::NotInAllowlist);
}
#[test]
fn from_files_only_deny() {
let p1 = fresh_peer();
let p2 = fresh_peer();
let tmp = TempDir::new().unwrap();
let deny = tmp.path().join("deny.txt");
std::fs::write(&deny, format!("{}\n", p1)).unwrap();
let policy = PeerPolicy::from_files(None, Some(&deny)).unwrap();
assert_eq!(policy.evaluate(&p1), Decision::DeniedByDenylist);
assert_eq!(policy.evaluate(&p2), Decision::Admit);
}
#[test]
fn reload_picks_up_changes() {
let p1 = fresh_peer();
let p2 = fresh_peer();
let tmp = TempDir::new().unwrap();
let allow = tmp.path().join("allow.txt");
std::fs::write(&allow, format!("{}\n", p1)).unwrap();
let policy = PeerPolicy::from_files(Some(&allow), None).unwrap();
assert_eq!(policy.evaluate(&p1), Decision::Admit);
assert_eq!(policy.evaluate(&p2), Decision::NotInAllowlist);
// Mutar el archivo: ahora p2 está, p1 no.
std::fs::write(&allow, format!("{}\n", p2)).unwrap();
policy.reload().unwrap();
assert_eq!(policy.evaluate(&p1), Decision::NotInAllowlist);
assert_eq!(policy.evaluate(&p2), Decision::Admit);
}
#[test]
fn reload_failure_preserves_previous_state() {
let p1 = fresh_peer();
let tmp = TempDir::new().unwrap();
let allow = tmp.path().join("allow.txt");
std::fs::write(&allow, format!("{}\n", p1)).unwrap();
let policy = PeerPolicy::from_files(Some(&allow), None).unwrap();
assert_eq!(policy.evaluate(&p1), Decision::Admit);
// Romper el archivo con basura.
std::fs::write(&allow, "this-is-not-a-peer-id\n").unwrap();
let err = policy.reload();
assert!(err.is_err(), "reload con typo debe fallar");
// Estado anterior se mantiene.
assert_eq!(
policy.evaluate(&p1),
Decision::Admit,
"policy debe conservar la versión anterior tras fallo de reload"
);
}
#[test]
fn invalid_file_rejected_at_load() {
let tmp = TempDir::new().unwrap();
let path = tmp.path().join("bad.txt");
std::fs::write(&path, "not-a-peer-id\n").unwrap();
let err = PeerPolicy::from_files(Some(&path), None).unwrap_err();
assert!(matches!(err, PolicyError::InvalidPeerId { .. }));
}
#[test]
fn watcher_reloads_on_file_change() {
// Test integración del watcher: arma policy con file, spawn
// watcher, modifica el archivo, espera el debounce, verifica
// que la policy refleja el cambio.
let p1 = fresh_peer();
let p2 = fresh_peer();
let tmp = TempDir::new().unwrap();
let allow = tmp.path().join("allow.txt");
std::fs::write(&allow, format!("{}\n", p1)).unwrap();
let policy = PeerPolicy::from_files(Some(&allow), None).unwrap();
let _watcher = policy.spawn_watcher().unwrap();
// Le damos un instante al watcher para subscribirse al dir.
std::thread::sleep(Duration::from_millis(100));
// Mutamos el archivo: p2 reemplaza a p1.
std::fs::write(&allow, format!("{}\n", p2)).unwrap();
// Esperamos > debounce + margen.
let deadline = Instant::now() + Duration::from_secs(3);
while Instant::now() < deadline {
if policy.evaluate(&p2) == Decision::Admit {
break;
}
std::thread::sleep(Duration::from_millis(50));
}
assert_eq!(
policy.evaluate(&p2),
Decision::Admit,
"watcher debería haber recargado la policy"
);
assert_eq!(
policy.evaluate(&p1),
Decision::NotInAllowlist,
"p1 debería haber salido tras el reload"
);
}
}
02_ruway/chasqui/card-handshake/src/server.rs
+855
View File
@@ -0,0 +1,855 @@
//! Servidor de handshake. Listener Unix socket → sesiones por conexión.
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::time::{SystemTime, UNIX_EPOCH};
use chasqui_broker::{Broker, Endpoint};
use card_core::{Card, ResolvedCard, WitInterface, CARD_SCHEMA_VERSION};
use card_net::{BrahmanNet, PeerId};
use tokio::io::{split, AsyncRead, AsyncWrite, WriteHalf};
use tokio::net::{UnixListener, UnixStream};
use tokio::sync::{mpsc, Mutex};
use tracing::{debug, warn};
use ulid::Ulid;
use crate::codec::{read_frame, write_frame};
use crate::messages::{
Farewell, Frame, HandshakeError, Hello, HelloAck, MatchEvent, MatchEventKind, Ping, Pong,
SessionId,
};
/// Tabla de sesiones vivas indexada por `SessionId`.
pub type SessionRegistry = Arc<Mutex<HashMap<SessionId, ResolvedCard>>>;
/// Broker compartido (opcional) que el servidor mantiene en sincronía con
/// el ciclo de vida de las sesiones.
pub type SharedBroker = Arc<Mutex<Broker>>;
/// Tabla de canales push por sesión: el server inyecta frames hacia el
/// cliente (p. ej. `MatchEvent`) sin requerir que el cliente haga request.
type SessionTxTable = Arc<Mutex<HashMap<SessionId, mpsc::Sender<Frame>>>>;
/// Por sesión, último match conocido por nombre de input. Se usa para
/// emitir diffs (Available/Lost) en lugar del estado completo.
type LastMatches = Arc<Mutex<HashMap<SessionId, HashMap<String, Endpoint>>>>;
/// Capacidad del canal push por sesión. Si se llena (cliente lento), los
/// eventos extra se descartan — el cliente puede re-consultar el estado.
const PUSH_CHANNEL_CAPACITY: usize = 32;
/// Configuración del servidor.
#[derive(Clone, Default)]
pub struct ServerConfig {
/// `true` si el Init está atado al servidor (se reporta en `HelloAck`).
pub init_attached: bool,
/// Broker compartido. Si está presente, el servidor llama
/// `register` tras un Hello aceptado y `unregister` al cerrar la
/// sesión (Farewell o EOF). Si es `None`, el broker no se usa.
pub broker: Option<SharedBroker>,
/// Capa P2P compartida. Si está presente, cada Card registrada
/// con outputs se anuncia automáticamente al DHT vía
/// [`card_handshake::network::announce_outputs`], permitiendo
/// que un consumer remoto los descubra con
/// [`card_handshake::network::find_remote_providers`]. Si es
/// `None`, el server queda "ciego al DHT" — sólo matchea sesiones
/// locales (lo cual es correcto cuando no hay conectividad o no
/// se desea exponer al exterior).
pub net: Option<Arc<BrahmanNet>>,
/// Política de admisión de peers libp2p (allow + deny + hot
/// reload opcional). Si está presente, el trust gate del path
/// libp2p evalúa cada `peer_id` (ya autenticado por Noise)
/// contra esta política. `None` → modo totalmente abierto
/// (cualquier peer Ed25519-válido pasa). El path Unix la ignora.
pub policy: Option<crate::peer_policy::PeerPolicy>,
}
// Manual Debug porque BrahmanNet no implementa Debug (libp2p Swarm
// no es Debug). Sólo loggeamos los campos relevantes para tracing.
impl std::fmt::Debug for ServerConfig {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ServerConfig")
.field("init_attached", &self.init_attached)
.field("broker", &self.broker.as_ref().map(|_| "<broker>"))
.field("net", &self.net.as_ref().map(|_| "<net>"))
.field("policy", &self.policy.as_ref().map(|p| p.sizes()))
.finish()
}
}
/// Servidor de handshake escuchando en un Unix socket.
pub struct Server {
listener: UnixListener,
socket_path: PathBuf,
sessions: SessionRegistry,
push_table: SessionTxTable,
last_matches: LastMatches,
config: ServerConfig,
}
impl Server {
/// Crea el listener en `path`. Si el archivo existe, lo elimina (asume
/// que es un socket stale de una sesión previa).
pub fn bind(path: impl Into<PathBuf>, config: ServerConfig) -> std::io::Result<Self> {
let socket_path = path.into();
if socket_path.exists() {
std::fs::remove_file(&socket_path)?;
}
if let Some(parent) = socket_path.parent() {
if !parent.as_os_str().is_empty() {
std::fs::create_dir_all(parent)?;
}
}
let listener = UnixListener::bind(&socket_path)?;
Ok(Self {
listener,
socket_path,
sessions: Arc::new(Mutex::new(HashMap::new())),
push_table: Arc::new(Mutex::new(HashMap::new())),
last_matches: Arc::new(Mutex::new(HashMap::new())),
config,
})
}
/// Devuelve la ruta del socket (útil para clientes en el mismo proceso).
pub fn socket_path(&self) -> &Path {
&self.socket_path
}
/// Vista compartida del registro de sesiones — útil para el Init/Admin
/// para inspeccionar quién está conectado.
pub fn sessions(&self) -> SessionRegistry {
self.sessions.clone()
}
/// Acepta UNA conexión Unix, devuelve la `Session` lista para `handle()`.
/// No corre el handler — eso es responsabilidad del llamante.
/// Path Unix → `expected_peer = None` (firma del Hello opcional;
/// SO_PEERCRED del kernel ya autentica al cliente).
pub async fn accept_one(&self) -> std::io::Result<Session<UnixStream>> {
let (stream, _addr) = self.listener.accept().await?;
Ok(self.session_from_stream(stream))
}
/// Construye una `Session` a partir de un stream arbitrario que
/// implemente `AsyncRead + AsyncWrite + Unpin + Send`. Path
/// agnóstico al transport (Unix, in-memory, etc.) — `expected_peer`
/// queda en `None`, así que la firma del Hello es opcional.
pub fn session_from_stream<S>(&self, stream: S) -> Session<S>
where
S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
self.session_from_stream_inner(stream, None)
}
/// Variante para conexiones libp2p: el `peer_id` viene autenticado
/// por Noise. La sesión exige firma del Hello cuya public key
/// derive a este `peer_id` exacto. Ver
/// [`super::network::run_libp2p_accept_loop`].
pub fn session_from_libp2p_stream<S>(
&self,
stream: S,
peer: PeerId,
) -> Session<S>
where
S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
self.session_from_stream_inner(stream, Some(peer))
}
fn session_from_stream_inner<S>(
&self,
stream: S,
expected_peer: Option<PeerId>,
) -> Session<S>
where
S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
Session {
stream,
sessions: self.sessions.clone(),
push_table: self.push_table.clone(),
last_matches: self.last_matches.clone(),
config: self.config.clone(),
expected_peer,
}
}
/// Loop de aceptación: cada conexión se despacha en una task separada.
/// Vive hasta que el listener falle o el caller drop el future.
pub async fn run(self) -> std::io::Result<()> {
loop {
let session = self.accept_one().await?;
tokio::spawn(async move {
if let Err(e) = session.handle().await {
warn!(error = %e, "session terminó con error");
}
});
}
}
}
impl Drop for Server {
fn drop(&mut self) {
// Limpieza best-effort del socket. Si falla, log y seguir.
if let Err(e) = std::fs::remove_file(&self.socket_path) {
if e.kind() != std::io::ErrorKind::NotFound {
warn!(path = %self.socket_path.display(), error = %e, "no se pudo limpiar socket");
}
}
}
}
/// Conexión individual aceptada por el servidor. Genérica sobre el
/// transport — funciona indistinguiblemente sobre `UnixStream` (modo
/// local), libp2p stream wrapped con `tokio_util::compat`, in-memory
/// duplex (tests), etc.
pub struct Session<S> {
stream: S,
sessions: SessionRegistry,
push_table: SessionTxTable,
last_matches: LastMatches,
config: ServerConfig,
/// Si está set, el path es libp2p y `do_handshake` exige firma
/// del Hello cuya public key derive a este `peer_id`. Si es
/// `None`, el path es Unix/in-memory y la firma es opcional
/// (pero si está, se verifica anyway por defensa en profundidad).
expected_peer: Option<PeerId>,
}
impl<S> Session<S>
where
S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
/// Procesa la conexión hasta `Farewell` o EOF.
///
/// Estructura: handshake (sobre el stream entero) → split en
/// halves (read + write) → reader loop principal + writer task
/// que drena el push channel. Garantiza cleanup (sessions + broker
/// + canales) sin importar la rama de salida.
///
/// El split es necesario para soportar streams `!Sync` como
/// `libp2p::Stream`: `tokio::select!` sobre `&mut self.stream`
/// requeriría `S: Sync`. Con `tokio::io::split` cada mitad va a
/// su propia task, eliminando el requirement y permitiendo que
/// la misma `Session` sirva indistinta sobre Unix socket o
/// stream libp2p remoto.
pub async fn handle(self) -> std::io::Result<()> {
let Self {
mut stream,
sessions,
push_table,
last_matches,
config,
expected_peer,
} = self;
let session_id = match do_handshake(&mut stream, &config, &sessions, expected_peer).await?
{
Some(id) => id,
None => return Ok(()), // Hello rechazado, no se registró nada
};
let result = run_post_handshake(
stream,
session_id,
sessions.clone(),
push_table.clone(),
last_matches.clone(),
config.clone(),
)
.await;
cleanup(
session_id,
&sessions,
&push_table,
&last_matches,
&config,
)
.await;
result
}
}
// ============================================================================
// Free functions (post-refactor): la lógica del post-handshake corre sobre
// halves del stream; no necesita más `&mut Session<S>` y por eso vive afuera.
// ============================================================================
async fn run_post_handshake<S>(
stream: S,
session_id: SessionId,
sessions: SessionRegistry,
push_table: SessionTxTable,
last_matches: LastMatches,
config: ServerConfig,
) -> std::io::Result<()>
where
S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
// Canal por donde el server inyecta frames push (MatchEvent, etc.).
let (tx, mut rx) = mpsc::channel::<Frame>(PUSH_CHANNEL_CAPACITY);
push_table.lock().await.insert(session_id, tx);
// Tras registrar el canal, recomputar matches y emitir diffs.
broadcast_match_diffs(&push_table, &last_matches, &config).await;
// Split: reader en el hilo principal, writer compartido bajo Mutex
// entre la writer task (push channel) y el handler de inbound
// (que escribe Pong/Error). Mutex serializa writes; es OK porque
// la frecuencia de writes por sesión es baja.
let (mut reader, writer) = split(stream);
let writer = Arc::new(Mutex::new(writer));
// Writer task: drena el push channel.
let writer_for_push = writer.clone();
let writer_task = tokio::spawn(async move {
while let Some(frame) = rx.recv().await {
let mut w = writer_for_push.lock().await;
if write_frame(&mut *w, &frame).await.is_err() {
break;
}
}
});
// Reader loop principal.
let broker_for_loop = config.broker.clone();
let result: std::io::Result<()> = loop {
match read_frame(&mut reader).await {
Ok(frame) => {
match handle_inbound_frame(
session_id,
frame,
&writer,
&sessions,
broker_for_loop.as_ref(),
)
.await
{
Ok(true) => continue,
Ok(false) => break Ok(()),
Err(e) => break Err(e),
}
}
Err(e) if e.kind() == std::io::ErrorKind::UnexpectedEof => {
debug!(session = %session_id, "cliente cerró sin Farewell");
break Ok(());
}
Err(e) => break Err(e),
}
};
// Cerrar writer: drop nuestro Arc y abortar la task. La task
// saldrá igual cuando rx se cierre por drop del último Sender,
// pero abortarla es más rápido que esperar a que próximo recv()
// observe el cierre.
drop(writer);
writer_task.abort();
let _ = writer_task.await;
result
}
async fn handle_inbound_frame<S>(
session_id: SessionId,
frame: Frame,
writer: &Arc<Mutex<WriteHalf<S>>>,
sessions: &SessionRegistry,
broker_for_match: Option<&SharedBroker>,
) -> std::io::Result<bool>
where
S: AsyncRead + AsyncWrite + Unpin + Send + 'static,
{
match frame {
Frame::Ping(Ping { session }) if session == session_id => {
let pong = Pong {
timestamp_ms: now_ms(),
};
let mut w = writer.lock().await;
write_frame(&mut *w, &Frame::Pong(pong)).await?;
Ok(true)
}
Frame::Ping(_) => {
let mut w = writer.lock().await;
write_frame(
&mut *w,
&Frame::Error(HandshakeError::Unauthorized(
"session-id no coincide".into(),
)),
)
.await?;
Ok(true)
}
Frame::Farewell(Farewell { session }) if session == session_id => Ok(false),
Frame::Farewell(_) => {
let mut w = writer.lock().await;
write_frame(
&mut *w,
&Frame::Error(HandshakeError::Unauthorized(
"session-id no coincide".into(),
)),
)
.await?;
Ok(true)
}
Frame::ListSessions(crate::messages::ListSessions { session })
if session == session_id =>
{
let list = build_session_list(sessions).await;
let mut w = writer.lock().await;
write_frame(&mut *w, &Frame::SessionList(list)).await?;
Ok(true)
}
Frame::ListSessions(_) => {
let mut w = writer.lock().await;
write_frame(
&mut *w,
&Frame::Error(HandshakeError::Unauthorized(
"session-id no coincide".into(),
)),
)
.await?;
Ok(true)
}
Frame::ListMatches(crate::messages::ListMatches { session })
if session == session_id =>
{
let matches = match &broker_for_match {
Some(b) => b.lock().await.all_matches(),
None => Vec::new(),
};
let mut w = writer.lock().await;
write_frame(
&mut *w,
&Frame::MatchList(crate::messages::MatchList { matches }),
)
.await?;
Ok(true)
}
Frame::ListMatches(_) => {
let mut w = writer.lock().await;
write_frame(
&mut *w,
&Frame::Error(HandshakeError::Unauthorized(
"session-id no coincide".into(),
)),
)
.await?;
Ok(true)
}
_ => {
let mut w = writer.lock().await;
write_frame(
&mut *w,
&Frame::Error(HandshakeError::Rejected(
"frame inesperado tras handshake".into(),
)),
)
.await?;
Ok(true)
}
}
}
/// Snapshot read-only de la `SessionRegistry` proyectado a la forma
/// de wire para el frame `SessionList`. Suelta el lock antes de
/// retornar para que el writer del frame no contenga el mutex.
async fn build_session_list(sessions: &SessionRegistry) -> crate::messages::SessionList {
let table = sessions.lock().await;
let entries = table
.iter()
.map(|(id, resolved)| crate::messages::SessionEntry {
session: *id,
label: resolved.card.label.clone(),
schema_version: resolved.card.schema_version,
outputs: resolved
.card
.flow
.output
.iter()
.map(|f| f.name.clone())
.collect(),
inputs: resolved
.card
.flow
.input
.iter()
.map(|f| f.name.clone())
.collect(),
conscious: resolved.wit.is_some(),
})
.collect();
crate::messages::SessionList { entries }
}
/// Limpieza atómica de las vistas registradas + (si net activo) retiro
/// de anuncios DHT de los outputs de la Card. Se ejecuta tanto si la
/// sesión cierra por Farewell, EOF, o error. Tras desregistrar, emite
/// diffs a las sesiones que perdieron el match contra ésta.
async fn cleanup(
session_id: SessionId,
sessions: &SessionRegistry,
push_table: &SessionTxTable,
last_matches: &LastMatches,
config: &ServerConfig,
) {
// Tomamos la Card ANTES de borrarla — si net está configurado
// necesitamos sus outputs para llamar withdraw_outputs. `remove`
// devuelve el valor extraído.
let removed_card = sessions.lock().await.remove(&session_id);
push_table.lock().await.remove(&session_id);
last_matches.lock().await.remove(&session_id);
if let Some(broker) = &config.broker {
broker.lock().await.unregister(session_id);
}
if let (Some(net), Some(resolved)) = (&config.net, removed_card) {
crate::network::withdraw_outputs(net, &resolved.card);
}
broadcast_match_diffs(push_table, last_matches, config).await;
}
/// Recomputa los matches para todas las sesiones registradas y empuja
/// `MatchEvent::Available` / `MatchEvent::Lost` por las que cambiaron
/// respecto al último estado conocido.
async fn broadcast_match_diffs(
push_table: &SessionTxTable,
last_matches: &LastMatches,
config: &ServerConfig,
) {
let broker = match &config.broker {
Some(b) => b,
None => return,
};
let b = broker.lock().await;
let push_table = push_table.lock().await;
let mut last = last_matches.lock().await;
debug!(
target: "card_handshake::broadcast",
cards = b.len(),
push_subscribers = push_table.len(),
"broadcast_match_diffs"
);
let cards: Vec<_> = b.cards().cloned().collect();
for cons in &cards {
let cons_session = cons.session;
let tx = match push_table.get(&cons_session) {
Some(tx) => tx,
None => continue,
};
let cons_last = last.entry(cons_session).or_default();
for input in &cons.inputs {
let new_match = b.find_producer_for(cons_session, &input.name);
let new_endpoint = new_match.as_ref().map(|m| m.producer.clone());
let old_endpoint = cons_last.get(&input.name).cloned();
if old_endpoint == new_endpoint {
continue;
}
if let Some(m) = &new_match {
let producer_service_socket = b
.cards()
.find(|c| c.session == m.producer.session)
.and_then(|c| c.service_socket.clone());
let event = MatchEvent {
kind: MatchEventKind::Available,
consumer_flow: input.name.clone(),
producer_session: m.producer.session,
producer_label: m.producer_label.clone(),
producer_flow: m.producer.flow_name.clone(),
ty: m.ty.clone(),
via: m.via,
pinned: m.pinned,
producer_service_socket,
};
let send_res = tx.try_send(Frame::MatchEvent(event));
debug!(
target: "card_handshake::broadcast",
consumer = %cons_session,
flow = %input.name,
producer = %m.producer_label,
result = ?send_res.as_ref().map(|_| "ok").unwrap_or_else(|e| match e {
tokio::sync::mpsc::error::TrySendError::Full(_) => "full",
tokio::sync::mpsc::error::TrySendError::Closed(_) => "closed",
}),
"Available pushed"
);
} else {
let event = MatchEvent {
kind: MatchEventKind::Lost,
consumer_flow: input.name.clone(),
producer_session: Ulid::nil(),
producer_label: String::new(),
producer_flow: String::new(),
ty: input.ty.clone(),
via: chasqui_broker::MatchStrategy::Exact,
pinned: false,
producer_service_socket: None,
};
let _ = tx.try_send(Frame::MatchEvent(event));
}
if let Some(ep) = new_endpoint {
cons_last.insert(input.name.clone(), ep);
} else {
cons_last.remove(&input.name);
}
}
}
}
/// Lee el Hello, valida (incluyendo firma cuando aplica), registra la
/// sesión y emite HelloAck.
async fn do_handshake<S>(
stream: &mut S,
config: &ServerConfig,
sessions: &SessionRegistry,
expected_peer: Option<PeerId>,
) -> std::io::Result<Option<SessionId>>
where
S: AsyncRead + AsyncWrite + Unpin,
{
let frame = read_frame(stream).await?;
let hello = match frame {
Frame::Hello(h) => h,
_ => {
write_frame(
stream,
&Frame::Error(HandshakeError::Rejected(
"primer frame debe ser Hello".into(),
)),
)
.await?;
return Ok(None);
}
};
if let Some(err) = validate_hello(&hello) {
write_frame(stream, &Frame::Error(err)).await?;
return Ok(None);
}
// Identity cert (multi-key identity, opcional): si el cliente
// adjuntó cert, la "identidad lógica" del peer es el master
// derivado del cert (estable across rotaciones), no el session
// peer_id (efímero). Sin cert, fallback al modelo de Fase 3
// (logical = session). Esto permite migración gradual y
// backwards compatibility con clientes que no usan identity.
let logical_peer = if let (Some(session_peer), Some(cert)) =
(expected_peer, &hello.identity_cert)
{
let session_pk_bytes: &[u8] = match &hello.signature {
Some(sig) => &sig.public_key,
None => {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(
"Hello con identity_cert requiere también signature".into(),
)),
)
.await?;
return Ok(None);
}
};
match cert.verify_against_session(session_pk_bytes) {
Ok(master_peer) => {
debug!(
session = %session_peer,
master = %master_peer,
"identity cert válido — policy se evalúa contra master_peer"
);
Some(master_peer)
}
Err(e) => {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(format!(
"identity cert inválido: {e}"
))),
)
.await?;
debug!(peer = %session_peer, error = %e, "cert rechazado");
return Ok(None);
}
}
} else {
expected_peer
};
// Policy gate (path libp2p): si está configurada, el peer
// autenticado debe pasar la política (deny first, luego allow).
// El peer evaluado es `logical_peer`: master si hay cert,
// session si no. Se chequea ANTES de la firma porque es
// comparación O(log n) sin crypto. La política no se aplica
// al path Unix (autenticación por SO_PEERCRED, no por PeerId).
if let (Some(peer), Some(policy)) = (logical_peer, &config.policy) {
let decision = policy.evaluate(&peer);
if !decision.is_admitted() {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(format!(
"peer {peer}: {}",
decision.reason()
))),
)
.await?;
debug!(peer = %peer, reason = decision.reason(), "rechazado por policy");
return Ok(None);
}
}
// Trust gate: en path libp2p (expected_peer = Some), exigir
// firma cuya public key derive al peer autenticado por Noise.
// En path Unix (expected_peer = None), si la firma viene se
// verifica anyway por defensa en profundidad — no es un error
// que esté ahí, pero si está debe ser válida.
if let Some(peer) = expected_peer {
let sig = match &hello.signature {
Some(s) => s,
None => {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(
"Hello sin firma en conexión remota libp2p".into(),
)),
)
.await?;
return Ok(None);
}
};
if let Err(e) = crate::signature::verify_hello(sig, &hello.card, &hello.wit, peer) {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(format!("firma inválida: {e}"))),
)
.await?;
debug!(peer = %peer, error = %e, "firma rechazada");
return Ok(None);
}
} else if let Some(sig) = &hello.signature {
// Firma presente en path local: no exigida pero verificada.
// Si está y no valida, es un signo de Hello mal-construido y
// rechazamos por seguridad.
// Para Unix no tenemos peer_id contra el cual comparar; se
// verifica sólo la consistencia interna (firma sobre payload
// con la public_key declarada).
match card_net::PublicKey::try_decode_protobuf(&sig.public_key) {
Ok(pk) => {
let payload = match postcard::to_allocvec(&(
crate::signature::SIGNATURE_VERSION,
&hello.card,
&hello.wit,
)) {
Ok(b) => b,
Err(_) => {
write_frame(
stream,
&Frame::Error(HandshakeError::Internal(
"no pude codificar payload para verificar firma".into(),
)),
)
.await?;
return Ok(None);
}
};
if !pk.verify(&payload, &sig.signature) {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(
"firma del Hello presente pero inválida".into(),
)),
)
.await?;
return Ok(None);
}
}
Err(e) => {
write_frame(
stream,
&Frame::Error(HandshakeError::Unauthorized(format!(
"public_key inválida en firma: {e}"
))),
)
.await?;
return Ok(None);
}
}
}
let session_id = Ulid::new();
let card: Card = hello.card.into();
register_session(session_id, card, hello.wit, config, sessions).await;
let ack = HelloAck {
server_version: crate::HANDSHAKE_VERSION.to_string(),
protocol_version: card_core::PROTOCOL_VERSION.to_string(),
session: session_id,
init_attached: config.init_attached,
};
write_frame(stream, &Frame::HelloAck(ack)).await?;
debug!(session = %session_id, "handshake completado");
Ok(Some(session_id))
}
async fn register_session(
session_id: SessionId,
card: Card,
wit: Option<WitInterface>,
config: &ServerConfig,
sessions: &SessionRegistry,
) {
if let Some(broker) = &config.broker {
broker
.lock()
.await
.register(session_id, &card, wit.clone());
}
// Si el server tiene net configurado, anunciar los outputs al
// DHT para que peers remotos puedan descubrirlos. Idempotente
// y best-effort — fallos de Kad no propagan al handshake.
if let Some(net) = &config.net {
crate::network::announce_outputs(net, &card);
}
let resolved = match wit {
Some(w) => ResolvedCard::from_conscious(card, w),
None => ResolvedCard::from_agnostic(card),
};
sessions.lock().await.insert(session_id, resolved);
}
fn validate_hello(hello: &Hello) -> Option<HandshakeError> {
if hello.schema_version != CARD_SCHEMA_VERSION {
return Some(HandshakeError::SchemaMismatch {
client: hello.schema_version,
server: CARD_SCHEMA_VERSION,
});
}
if hello.protocol_version != card_core::PROTOCOL_VERSION {
return Some(HandshakeError::ProtocolMismatch(format!(
"cliente={}, servidor={}",
hello.protocol_version,
card_core::PROTOCOL_VERSION
)));
}
let as_card: Card = Card::from(hello.card.clone());
if let Err(e) = as_card.validate() {
return Some(HandshakeError::InvalidCard(e.to_string()));
}
None
}
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0)
}
02_ruway/chasqui/card-handshake/src/signature.rs
+155
View File
@@ -0,0 +1,155 @@
//! Firma y verificación del payload del `Hello` para trust remoto.
//!
//! Usa la identidad Ed25519 de libp2p (la misma keypair que el peer
//! presenta al swarm vía Noise). Esto ancla la identidad criptográfica
//! del Ente a la identidad de transporte: si Noise autenticó al
//! `peer_id` X, sólo X puede firmar Cards válidas para esa conexión.
//!
//! ## Payload firmado
//!
//! Bytes postcard de la tupla `(WireCard, Option<WitInterface>)`. Se
//! eligió postcard porque ya es el wire format del resto del protocolo:
//! mismo determinismo, sin convertir a otro format sólo para firmar.
//!
//! Cualquier campo que entre al payload firmado en el futuro debe
//! añadirse al final de la tupla (postcard es position-dependent), o
//! bumpearse el [`SIGNATURE_VERSION`] para distinguir esquemas.
use card_core::{WireCard, WitInterface};
use card_net::{Keypair, PeerId, PublicKey};
use crate::messages::HelloSignature;
/// Versión del esquema de payload firmado. Si cambia el shape de
/// `(WireCard, Option<WitInterface>)` o cómo se serializa, bump este
/// número y el verificador rechaza firmas antiguas.
pub const SIGNATURE_VERSION: u8 = 1;
/// Errores de verificación de firma.
#[derive(Debug, thiserror::Error)]
pub enum SignatureError {
#[error("public_key inválida (libp2p decode protobuf): {0}")]
DecodeKey(String),
#[error("encode del payload falló: {0}")]
EncodePayload(String),
#[error("firma rechazada: bytes inválidos para la public_key")]
Invalid,
#[error("peer_id de la firma ({signer}) no coincide con el peer libp2p autenticado ({expected})")]
PeerMismatch { signer: PeerId, expected: PeerId },
#[error("firma del Hello faltante (requerida para conexión remota libp2p)")]
Missing,
#[error("firma del Hello inesperada en path local sin trust remoto")]
Unexpected,
}
/// Construye los bytes canónicos a firmar/verificar para un Hello.
/// Postcard determinístico de `(version, WireCard, Option<WitInterface>)`.
fn payload_bytes(card: &WireCard, wit: &Option<WitInterface>) -> Result<Vec<u8>, SignatureError> {
let tup = (SIGNATURE_VERSION, card, wit);
postcard::to_allocvec(&tup).map_err(|e| SignatureError::EncodePayload(e.to_string()))
}
/// Firma `(card, wit)` con la `keypair`. La public key derivada de
/// `keypair` debe coincidir con la identidad libp2p del peer cuando
/// el verificador la chequee.
pub fn sign_hello(
keypair: &Keypair,
card: &WireCard,
wit: &Option<WitInterface>,
) -> Result<HelloSignature, SignatureError> {
let bytes = payload_bytes(card, wit)?;
let signature_bytes = keypair
.sign(&bytes)
.map_err(|e| SignatureError::EncodePayload(e.to_string()))?;
Ok(HelloSignature {
public_key: keypair.public().encode_protobuf(),
signature: signature_bytes,
})
}
/// Verifica que `sig` es una firma válida sobre `(card, wit)` y que
/// la public key declarada coincide con `expected_peer` (la identidad
/// libp2p autenticada por Noise).
///
/// Devuelve `Ok(())` si todo cuadra; si no, el error concreto.
pub fn verify_hello(
sig: &HelloSignature,
card: &WireCard,
wit: &Option<WitInterface>,
expected_peer: PeerId,
) -> Result<(), SignatureError> {
let public_key = PublicKey::try_decode_protobuf(&sig.public_key)
.map_err(|e| SignatureError::DecodeKey(e.to_string()))?;
let signer_peer = public_key.to_peer_id();
if signer_peer != expected_peer {
return Err(SignatureError::PeerMismatch {
signer: signer_peer,
expected: expected_peer,
});
}
let bytes = payload_bytes(card, wit)?;
if !public_key.verify(&bytes, &sig.signature) {
return Err(SignatureError::Invalid);
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use card_core::Card;
fn sample_card() -> WireCard {
Card::new("test.signed").into()
}
#[test]
fn sign_then_verify_roundtrip() {
let kp = Keypair::generate_ed25519();
let peer = kp.public().to_peer_id();
let card = sample_card();
let wit = None;
let sig = sign_hello(&kp, &card, &wit).unwrap();
verify_hello(&sig, &card, &wit, peer).expect("firma propia debe verificar");
}
#[test]
fn verify_rejects_wrong_peer() {
let kp = Keypair::generate_ed25519();
let other = Keypair::generate_ed25519().public().to_peer_id();
let card = sample_card();
let wit = None;
let sig = sign_hello(&kp, &card, &wit).unwrap();
let err = verify_hello(&sig, &card, &wit, other).unwrap_err();
assert!(matches!(err, SignatureError::PeerMismatch { .. }), "got {err:?}");
}
#[test]
fn verify_rejects_tampered_card() {
let kp = Keypair::generate_ed25519();
let peer = kp.public().to_peer_id();
let original = sample_card();
let wit = None;
let sig = sign_hello(&kp, &original, &wit).unwrap();
// Verificamos contra una Card distinta (mismo shape, distinto label).
let tampered: WireCard = Card::new("test.tampered").into();
let err = verify_hello(&sig, &tampered, &wit, peer).unwrap_err();
assert!(matches!(err, SignatureError::Invalid), "got {err:?}");
}
#[test]
fn verify_rejects_corrupted_signature() {
let kp = Keypair::generate_ed25519();
let peer = kp.public().to_peer_id();
let card = sample_card();
let wit = None;
let mut sig = sign_hello(&kp, &card, &wit).unwrap();
// Flip un bit de la firma.
if let Some(b) = sig.signature.last_mut() {
*b ^= 0x01;
}
let err = verify_hello(&sig, &card, &wit, peer).unwrap_err();
assert!(matches!(err, SignatureError::Invalid), "got {err:?}");
}
}
02_ruway/chasqui/card-handshake/src/transport.rs
+52
View File
@@ -0,0 +1,52 @@
//! Convenciones de transporte: dónde vive el socket del Init.
//!
//! Resolución del path canónico:
//! 1. Variable de entorno [`SOCKET_ENV`] si está definida (override
//! explícito, prioridad máxima).
//! 2. `$XDG_RUNTIME_DIR/brahman-init.sock` (sesión usuario).
//! 3. `$TMPDIR/brahman-init.sock` (fallback portable).
use std::path::PathBuf;
/// Variable de entorno que sobreescribe la ruta del socket del Init.
pub const SOCKET_ENV: &str = "BRAHMAN_INIT_SOCKET";
/// Nombre del socket dentro del runtime dir.
pub const SOCKET_NAME: &str = "brahman-init.sock";
/// Ruta canónica al socket del Init brahman.
pub fn default_socket_path() -> PathBuf {
if let Ok(p) = std::env::var(SOCKET_ENV) {
return PathBuf::from(p);
}
let base = std::env::var_os("XDG_RUNTIME_DIR")
.map(PathBuf::from)
.unwrap_or_else(std::env::temp_dir);
base.join(SOCKET_NAME)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn env_override_wins() {
// Nota: estos tests modifican entorno del proceso. `cargo test`
// los corre paralelos por defecto pero usamos un nombre de var
// único y restablecemos al final.
let key = "BRAHMAN_INIT_SOCKET_TEST_OVERRIDE";
// SAFETY: sólo escribimos una variable local al test; sin
// contaminar SOCKET_ENV.
std::env::set_var(key, "/tmp/explicit.sock");
let saved = std::env::var(SOCKET_ENV).ok();
std::env::set_var(SOCKET_ENV, "/tmp/explicit.sock");
let p = default_socket_path();
assert_eq!(p, PathBuf::from("/tmp/explicit.sock"));
// Restaurar
match saved {
Some(v) => std::env::set_var(SOCKET_ENV, v),
None => std::env::remove_var(SOCKET_ENV),
}
std::env::remove_var(key);
}
}
02_ruway/chasqui/card-handshake/tests/handshake.rs
+480
View File
@@ -0,0 +1,480 @@
//! Tests de integración: levanta server + client en el mismo proceso,
//! ejercita el round-trip completo del protocolo.
use std::collections::BTreeSet;
use std::sync::Arc;
use std::time::Duration;
use chasqui_broker::{Broker, BrokerConfig};
use card_core::{
Card, CgroupSpec, Flow, Flows, NamespaceSet, Payload, ResourceLimits, SomaSpec, Supervision,
TypeRef, CARD_SCHEMA_VERSION,
};
use card_handshake::{
client::{Client, ClientError},
codec::{read_frame, write_frame},
messages::{Frame, HandshakeError, Hello, Ping},
server::{Server, ServerConfig},
};
use tokio::net::UnixStream;
use tokio::sync::Mutex;
use ulid::Ulid;
fn sample_card(label: &str) -> Card {
Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
lineage: None,
label: label.into(),
provides: BTreeSet::new(),
requires: BTreeSet::new(),
soma: SomaSpec {
cgroup: CgroupSpec {
path: "ente.slice/test".into(),
cpu_weight: None,
io_weight: None,
},
namespaces: NamespaceSet::default(),
rlimits: ResourceLimits::default(),
cpu_affinity: None,
},
payload: Payload::Virtual,
supervision: Supervision::OneShot,
..Default::default()
}
}
/// Genera una ruta de socket única bajo TMPDIR. No la creamos —
/// el server la creará al hacer bind.
fn sock_path(name: &str) -> std::path::PathBuf {
std::env::temp_dir().join(format!(
"brahman-test-{}-{}-{}.sock",
name,
std::process::id(),
Ulid::new()
))
}
#[tokio::test]
async fn full_handshake_roundtrip() {
let path = sock_path("happy");
let server = Server::bind(&path, ServerConfig { init_attached: true, broker: None, net: None, policy: None }).unwrap();
let session_handle = tokio::spawn({
async move {
let session = server.accept_one().await.unwrap();
session.handle().await.unwrap();
}
});
let mut client = Client::connect(&path, sample_card("alpha")).await.unwrap();
assert!(client.server_info().init_attached);
assert_eq!(
client.server_info().protocol_version,
card_core::PROTOCOL_VERSION
);
let mut last = 0u64;
for _ in 0..3 {
let ts = client.ping().await.unwrap();
assert!(ts >= last);
last = ts;
tokio::time::sleep(Duration::from_millis(2)).await;
}
client.farewell().await.unwrap();
tokio::time::timeout(Duration::from_secs(2), session_handle)
.await
.expect("server hung after farewell")
.unwrap();
}
#[tokio::test]
async fn list_sessions_returns_currently_registered() {
// Levantamos un server con broker (requerido para que el registro
// pase por el path real) y conectamos 3 clientes. El último pide
// ListSessions y debe ver a los 2 anteriores + a sí mismo.
let path = sock_path("listsess");
let broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let server = Server::bind(
&path,
ServerConfig {
init_attached: true,
broker: Some(broker),
net: None,
policy: None,
},
)
.unwrap();
// Una task accept loop genérica para los 3 clientes.
let server_handle = tokio::spawn(async move {
for _ in 0..3 {
let session = server.accept_one().await.unwrap();
tokio::spawn(async move {
let _ = session.handle().await;
});
}
// Mantener el server vivo para que las sesiones puedan
// mantenerse abiertas mientras el observer pregunta.
std::future::pending::<()>().await;
});
let mut alpha = Client::connect(&path, sample_card("producer-alpha"))
.await
.unwrap();
let mut beta = Client::connect(&path, sample_card("producer-beta"))
.await
.unwrap();
// observer es el que va a preguntar.
let mut observer = Client::connect(&path, sample_card("observer"))
.await
.unwrap();
let list = observer.list_sessions().await.unwrap();
assert_eq!(list.entries.len(), 3, "deberían verse 3 sesiones activas");
let labels: BTreeSet<&str> = list.entries.iter().map(|e| e.label.as_str()).collect();
assert!(labels.contains("producer-alpha"));
assert!(labels.contains("producer-beta"));
assert!(labels.contains("observer"));
// schema_version + conscious sanity en la propia entry del observer.
let me = list
.entries
.iter()
.find(|e| e.label == "observer")
.unwrap();
assert_eq!(me.schema_version, card_core::CARD_SCHEMA_VERSION);
assert!(!me.conscious, "observer no envió WIT — debería ser agnostic");
alpha.farewell().await.unwrap();
beta.farewell().await.unwrap();
observer.farewell().await.unwrap();
server_handle.abort();
}
#[tokio::test]
async fn rejects_invalid_card_client_side() {
let path = sock_path("invalid");
let server = Server::bind(&path, ServerConfig::default()).unwrap();
let session_handle = tokio::spawn(async move {
// No esperamos que el server complete: el cliente corta antes.
let _ = tokio::time::timeout(Duration::from_secs(1), async move {
let session = server.accept_one().await.unwrap();
session.handle().await.unwrap();
})
.await;
});
let mut bad = sample_card("placeholder");
bad.label = String::new();
let err = Client::connect(&path, bad).await.unwrap_err();
assert!(matches!(err, ClientError::InvalidCard(_)));
session_handle.abort();
}
#[tokio::test]
async fn server_rejects_protocol_mismatch() {
let path = sock_path("mismatch");
let server = Server::bind(&path, ServerConfig::default()).unwrap();
let session_handle = tokio::spawn(async move {
let session = server.accept_one().await.unwrap();
session.handle().await.unwrap();
});
let mut stream = UnixStream::connect(&path).await.unwrap();
let hello = Hello {
schema_version: CARD_SCHEMA_VERSION,
protocol_version: "999.0.0".into(),
card: sample_card("future-module").into(),
wit: None,
signature: None,
identity_cert: None,
};
write_frame(&mut stream, &Frame::Hello(hello)).await.unwrap();
match read_frame(&mut stream).await.unwrap() {
Frame::Error(HandshakeError::ProtocolMismatch(_)) => {}
other => panic!("esperado ProtocolMismatch, got {other:?}"),
}
tokio::time::timeout(Duration::from_secs(2), session_handle)
.await
.expect("server hung after rejecting")
.unwrap();
}
// =====================================================================
// Integración handshake ↔ broker
// =====================================================================
fn card_with_flows(label: &str, input: Vec<Flow>, output: Vec<Flow>) -> Card {
Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: label.into(),
soma: SomaSpec {
cgroup: CgroupSpec {
path: "ente.slice/test".into(),
cpu_weight: None,
io_weight: None,
},
namespaces: NamespaceSet::default(),
rlimits: ResourceLimits::default(),
cpu_affinity: None,
},
payload: Payload::Virtual,
supervision: Supervision::OneShot,
flow: Flows { input, output },
..Default::default()
}
}
fn flow(name: &str, ty: TypeRef) -> Flow {
Flow {
name: name.into(),
ty,
pin_to: None,
}
}
/// Espera hasta que `broker.len() >= n` o timeout.
async fn wait_for_broker_len(broker: &Arc<Mutex<Broker>>, n: usize) {
for _ in 0..50 {
if broker.lock().await.len() >= n {
return;
}
tokio::time::sleep(Duration::from_millis(10)).await;
}
panic!("broker no alcanzó {n} entradas en 500ms");
}
#[tokio::test]
async fn broker_registers_and_unregisters_with_session() {
let path = sock_path("broker-lifecycle");
let broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let server = Server::bind(
&path,
ServerConfig {
init_attached: false,
broker: Some(broker.clone()),
net: None,
policy: None,
},
)
.unwrap();
let session_handle = tokio::spawn(async move {
let session = server.accept_one().await.unwrap();
session.handle().await.unwrap();
});
let mut client = Client::connect(&path, sample_card("alpha")).await.unwrap();
let session_id = client.session();
// Tras el handshake, la Card debe estar registrada en el broker.
wait_for_broker_len(&broker, 1).await;
{
let b = broker.lock().await;
assert_eq!(b.len(), 1);
assert!(b.sessions().any(|s| s == session_id));
}
client.farewell().await.unwrap();
tokio::time::timeout(Duration::from_secs(2), session_handle)
.await
.expect("server colgó tras farewell")
.unwrap();
// Tras el cleanup, el broker queda vacío.
{
let b = broker.lock().await;
assert_eq!(b.len(), 0);
}
}
#[tokio::test]
async fn broker_matches_two_live_modules() {
let path = sock_path("broker-match");
let broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let server = Server::bind(
&path,
ServerConfig {
init_attached: false,
broker: Some(broker.clone()),
net: None,
policy: None,
},
)
.unwrap();
// Server loop: usa la API run() para manejar accept+spawn.
let server_handle = tokio::spawn(async move {
let _ = server.run().await;
});
// Productor: emite "out" tipo string.
let producer_card = card_with_flows(
"dht",
vec![],
vec![flow(
"out",
TypeRef::Primitive {
name: "string".into(),
},
)],
);
let mut producer = Client::connect(&path, producer_card).await.unwrap();
wait_for_broker_len(&broker, 1).await;
// Consumidor: pide "in" tipo string.
let consumer_card = card_with_flows(
"ui",
vec![flow(
"in",
TypeRef::Primitive {
name: "string".into(),
},
)],
vec![],
);
let mut consumer = Client::connect(&path, consumer_card).await.unwrap();
wait_for_broker_len(&broker, 2).await;
// El broker debe encontrar el match consumer.in ← producer.out.
let m = {
let b = broker.lock().await;
b.find_producer_for(consumer.session(), "in")
}
.expect("broker no encontró match");
assert_eq!(m.consumer_label, "ui");
assert_eq!(m.producer_label, "dht");
assert_eq!(m.producer.flow_name, "out");
// Cuando el productor se va, el match desaparece.
producer.farewell().await.unwrap();
for _ in 0..50 {
if broker.lock().await.len() < 2 {
break;
}
tokio::time::sleep(Duration::from_millis(10)).await;
}
{
let b = broker.lock().await;
assert!(b.find_producer_for(consumer.session(), "in").is_none());
}
consumer.farewell().await.unwrap();
server_handle.abort();
}
#[tokio::test]
async fn match_event_pushed_on_producer_arrival() {
use card_handshake::messages::MatchEventKind;
let path = sock_path("push-match");
let broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let server = Server::bind(
&path,
ServerConfig {
init_attached: false,
broker: Some(broker.clone()),
net: None,
policy: None,
},
)
.unwrap();
let server_handle = tokio::spawn(async move {
let _ = server.run().await;
});
// El consumidor llega primero — sin productor, no hay match aún.
let consumer_card = card_with_flows(
"ui",
vec![flow(
"in",
TypeRef::Primitive {
name: "json".into(),
},
)],
vec![],
);
let mut consumer = Client::connect(&path, consumer_card).await.unwrap();
// No debería haber evento todavía.
let no_event = consumer
.await_event(Duration::from_millis(100))
.await
.unwrap();
assert!(no_event.is_none(), "evento inesperado: {no_event:?}");
// Llega el productor → consumer debe recibir Available.
let producer_card = card_with_flows(
"dht",
vec![],
vec![flow(
"out",
TypeRef::Primitive {
name: "json".into(),
},
)],
);
let mut producer = Client::connect(&path, producer_card).await.unwrap();
let ev = consumer
.await_event(Duration::from_secs(2))
.await
.unwrap()
.expect("Available no llegó");
assert_eq!(ev.kind, MatchEventKind::Available);
assert_eq!(ev.consumer_flow, "in");
assert_eq!(ev.producer_label, "dht");
assert_eq!(ev.producer_flow, "out");
// El productor se va → consumer debe recibir Lost.
producer.farewell().await.unwrap();
let ev = consumer
.await_event(Duration::from_secs(2))
.await
.unwrap()
.expect("Lost no llegó");
assert_eq!(ev.kind, MatchEventKind::Lost);
assert_eq!(ev.consumer_flow, "in");
consumer.farewell().await.unwrap();
server_handle.abort();
}
#[tokio::test]
async fn ping_before_hello_rejected() {
let path = sock_path("ping-no-hello");
let server = Server::bind(&path, ServerConfig::default()).unwrap();
let session_handle = tokio::spawn(async move {
let session = server.accept_one().await.unwrap();
session.handle().await.unwrap();
});
// Conectamos y mandamos un Ping sin haber saludado.
let mut stream = UnixStream::connect(&path).await.unwrap();
write_frame(
&mut stream,
&Frame::Ping(Ping {
session: Ulid::new(),
}),
)
.await
.unwrap();
match read_frame(&mut stream).await.unwrap() {
Frame::Error(HandshakeError::Rejected(_)) => {}
other => panic!("esperado Rejected, got {other:?}"),
}
tokio::time::timeout(Duration::from_secs(2), session_handle)
.await
.expect("server hung after rejecting")
.unwrap();
}
02_ruway/chasqui/card-handshake/tests/network_discovery.rs
+340
View File
@@ -0,0 +1,340 @@
//! Test E2E de Fase 2: discovery remoto vía DHT.
//!
//! Pipeline:
//! 1. **Provider node (A)**: arma server con `BrahmanNet` configurado;
//! listen TCP; un cliente local registra una Card con un output
//! flow. El server llama `announce_outputs` automáticamente, lo
//! que hace `start_providing` en el DHT bajo la key derivada del
//! flow.
//! 2. **Consumer node (B)**: arma su propio `BrahmanNet`; dial-ea al
//! multiaddr del provider para que ambos se conozcan vía Identify
//! (esto popula sus respectivos routing tables de Kademlia).
//! 3. **B llama `find_remote_providers(flow_name, type)`**: la query
//! DHT propaga vía Kad, y eventually el provider responde con su
//! `PeerId`.
//! 4. **Verificación**: el `PeerId` que B descubre coincide con el
//! de A.
//!
//! Notas:
//! - Kademlia replication factor por defecto es 20; con 2 nodos no
//! hay propagación material — A es el único provider, B llega a A
//! vía la conexión directa establecida en step 2 y obtiene el record
//! del store local de A.
//! - El test usa flow `monad-list:json` por familiaridad (es el flow
//! real que `chasqui daemon` declara). Sirve también como prueba de
//! que el sistema completo (daemon + DHT) funcionaría con cero
//! cambios en la Card.
use std::collections::BTreeSet;
use std::sync::Arc;
use std::time::Duration;
use chasqui_broker::{Broker, BrokerConfig};
use card_core::{
ulid::Ulid, Card, CardKind, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef,
CARD_SCHEMA_VERSION,
};
use card_handshake::network::{find_remote_providers, run_libp2p_accept_loop};
use card_handshake::server::{Server, ServerConfig};
use card_net::{BrahmanNet, Multiaddr, Protocol};
use tempfile::TempDir;
use tokio::sync::Mutex;
fn provider_card(label: &str, flow_name: &str, type_name: &str) -> Card {
Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: label.into(),
provides: BTreeSet::new(),
requires: BTreeSet::new(),
permissions: Default::default(),
soma: Default::default(),
payload: Payload::Virtual,
supervision: Supervision::Delegate,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
kind: CardKind::Ente,
flow: Flows {
input: vec![],
output: vec![Flow {
name: flow_name.into(),
ty: TypeRef::Primitive {
name: type_name.into(),
},
pin_to: None,
}],
},
..Default::default()
}
}
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn dht_discovery_finds_remote_provider() {
// ---- Node A (provider): server + libp2p net + Card con output ----
let tmp = TempDir::new().unwrap();
let a_unix = tmp.path().join("a.sock");
let a_broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let a_net = Arc::new(BrahmanNet::new().unwrap());
let a_peer = a_net.peer_id;
let a_server = Arc::new(
Server::bind(
&a_unix,
ServerConfig {
init_attached: true,
broker: Some(a_broker.clone()),
net: Some(a_net.clone()), // ← clave Fase 2: anuncia al DHT
policy: None,
},
)
.unwrap(),
);
let listen_addr: Multiaddr = "/ip4/127.0.0.1/tcp/0".parse().unwrap();
let a_addr = a_net.listen(listen_addr).await;
let mut a_full_addr = a_addr.clone();
a_full_addr.push(Protocol::P2p(a_peer));
tokio::spawn(run_libp2p_accept_loop(a_server.clone(), a_net.clone()));
// Unix accept loop: necesario para que Client::connect al socket
// local no cuelgue (Server no se auto-accepta; el caller arma el
// loop). Cada session entrante corre en su propia task.
{
let s = a_server.clone();
tokio::spawn(async move {
loop {
match s.accept_one().await {
Ok(session) => {
tokio::spawn(async move {
let _ = session.handle().await;
});
}
Err(_) => break,
}
}
});
}
// Registrar la Card local en A con un flow output.
let card = provider_card("test.engine_remote", "monad-list", "json");
let mut local_client = card_handshake::client::Client::connect(&a_unix, card)
.await
.expect("registro local en A");
// ---- Node B (consumer): otro net que dial-a a A ----
let b_net = BrahmanNet::new().unwrap();
b_net.dial(a_full_addr.clone());
// Esperar a que la conexión se establezca y Identify popule el
// routing table de Kad. En localhost con 2 peers, ~250ms es de
// sobra; sumamos margen para CI.
tokio::time::sleep(Duration::from_millis(500)).await;
// ---- Discovery: B busca providers de "monad-list:json" ----
let providers = find_remote_providers(
&b_net,
"monad-list",
&TypeRef::Primitive {
name: "json".into(),
},
)
.await;
assert!(
providers.contains(&a_peer),
"B debería descubrir a A vía DHT. Encontrados: {:?}, esperado: {}",
providers,
a_peer
);
// Sanidad: el cliente local sigue vivo durante todo el test (lo
// que mantiene la Card registrada y por tanto el record DHT vivo).
local_client.farewell().await.ok();
}
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn dht_discovery_negative_unknown_flow() {
// Mismo setup que el test happy-path, pero B busca un flow que A
// NO ofrece. Debe devolver lista vacía dentro del timeout
// razonable (no colgarse).
let tmp = TempDir::new().unwrap();
let a_unix = tmp.path().join("a.sock");
let a_broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let a_net = Arc::new(BrahmanNet::new().unwrap());
let a_peer = a_net.peer_id;
let a_server = Arc::new(
Server::bind(
&a_unix,
ServerConfig {
init_attached: true,
broker: Some(a_broker),
net: Some(a_net.clone()),
policy: None,
},
)
.unwrap(),
);
let a_addr = a_net.listen("/ip4/127.0.0.1/tcp/0".parse().unwrap()).await;
let mut a_full = a_addr.clone();
a_full.push(Protocol::P2p(a_peer));
tokio::spawn(run_libp2p_accept_loop(a_server.clone(), a_net.clone()));
// Unix accept loop: necesario para que Client::connect al socket
// local no cuelgue (Server no se auto-accepta; el caller arma el
// loop). Cada session entrante corre en su propia task.
{
let s = a_server.clone();
tokio::spawn(async move {
loop {
match s.accept_one().await {
Ok(session) => {
tokio::spawn(async move {
let _ = session.handle().await;
});
}
Err(_) => break,
}
}
});
}
let card = provider_card("test.engine_other", "monad-list", "json");
let mut local = card_handshake::client::Client::connect(&a_unix, card)
.await
.unwrap();
let b_net = BrahmanNet::new().unwrap();
b_net.dial(a_full);
tokio::time::sleep(Duration::from_millis(500)).await;
// Buscamos un flow que NADIE anunció.
let providers = find_remote_providers(
&b_net,
"flow-que-no-existe",
&TypeRef::Primitive {
name: "json".into(),
},
)
.await;
assert!(
providers.is_empty(),
"no debería haber providers para un flow inexistente, got: {:?}",
providers
);
local.farewell().await.ok();
}
/// stop_providing test: A registra Card con flow X, B descubre a A.
/// El cliente local de A hace farewell → cleanup llama
/// withdraw_outputs → A se quita del provider local store. Una nueva
/// query desde B (que rutea por A, único peer en el DHT) ya no debe
/// listarlo.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn dht_discovery_withdraws_on_session_cleanup() {
let tmp = TempDir::new().unwrap();
let a_unix = tmp.path().join("a.sock");
let a_broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let a_net = Arc::new(BrahmanNet::new().unwrap());
let a_peer = a_net.peer_id;
let a_server = Arc::new(
Server::bind(
&a_unix,
ServerConfig {
init_attached: true,
broker: Some(a_broker),
net: Some(a_net.clone()),
policy: None,
},
)
.unwrap(),
);
let sessions = a_server.sessions();
let a_addr = a_net.listen("/ip4/127.0.0.1/tcp/0".parse().unwrap()).await;
let mut a_full = a_addr.clone();
a_full.push(Protocol::P2p(a_peer));
tokio::spawn(run_libp2p_accept_loop(a_server.clone(), a_net.clone()));
{
let s = a_server.clone();
tokio::spawn(async move {
loop {
match s.accept_one().await {
Ok(session) => {
tokio::spawn(async move {
let _ = session.handle().await;
});
}
Err(_) => break,
}
}
});
}
// Card con un flow output anunciable.
let card = provider_card("test.withdraws", "monad-list", "json");
let local = card_handshake::client::Client::connect(&a_unix, card)
.await
.expect("registro local en A");
let b_net = BrahmanNet::new().unwrap();
b_net.dial(a_full);
tokio::time::sleep(Duration::from_millis(500)).await;
// Confirmación previa: A es discoverable.
let before = find_remote_providers(
&b_net,
"monad-list",
&TypeRef::Primitive {
name: "json".into(),
},
)
.await;
assert!(
before.contains(&a_peer),
"antes del farewell A debería ser discoverable. got: {:?}",
before
);
// Farewell del cliente local → server.cleanup → withdraw_outputs.
local.farewell().await.ok();
// Esperamos a que la sesión salga del registro de A (señal de
// que cleanup completó).
let mut waited = 0;
while !sessions.lock().await.is_empty() && waited < 50 {
tokio::time::sleep(Duration::from_millis(20)).await;
waited += 1;
}
assert!(
sessions.lock().await.is_empty(),
"sesión debería estar removida tras farewell"
);
// Pequeño margen extra para que el Command::StopProviding lo
// procese el swarm task (no es await-able desde fuera).
tokio::time::sleep(Duration::from_millis(100)).await;
// Nueva query: A ya no debería listarse como provider.
let after = find_remote_providers(
&b_net,
"monad-list",
&TypeRef::Primitive {
name: "json".into(),
},
)
.await;
assert!(
!after.contains(&a_peer),
"tras farewell + withdraw_outputs, A NO debería ser discoverable. got: {:?}",
after
);
}
02_ruway/chasqui/card-handshake/tests/network_libp2p.rs
+525
View File
@@ -0,0 +1,525 @@
//! Test E2E: handshake brahman remoto sobre libp2p stream.
//!
//! Pipeline:
//! 1. Server: bind Unix socket (necesario aunque no lo use el cliente);
//! crear `BrahmanNet` y escuchar en `/ip4/127.0.0.1/tcp/0`;
//! montar `run_libp2p_accept_loop`.
//! 2. Client: crear su propio `BrahmanNet`; dial al multiaddr del
//! server; `connect_libp2p` con su Card; `ping`; `farewell`.
//! 3. Verificar: el server registró la sesión; sessions.len() == 1
//! durante la sesión, == 0 después del farewell.
use std::collections::BTreeSet;
use std::sync::Arc;
use std::time::Duration;
use chasqui_broker::{Broker, BrokerConfig};
use card_core::{
ulid::Ulid, Card, CardKind, Lifecycle, Payload, Priority, Supervision,
CARD_SCHEMA_VERSION,
};
use card_handshake::identity::{Identity, DEFAULT_SESSION_TTL};
use card_handshake::network::{connect_libp2p, connect_libp2p_with_cert, run_libp2p_accept_loop};
use card_handshake::peer_policy::PeerPolicy;
use card_handshake::server::{Server, ServerConfig};
use card_net::{BrahmanNet, Keypair, Multiaddr, PeerId, Protocol};
use tempfile::TempDir;
use tokio::sync::Mutex;
fn sample_card(label: &str) -> Card {
Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: label.into(),
provides: BTreeSet::new(),
requires: BTreeSet::new(),
permissions: Default::default(),
soma: Default::default(),
payload: Payload::Virtual,
supervision: Supervision::OneShot,
lifecycle: Lifecycle::default(),
priority: Priority::default(),
kind: CardKind::Ente,
..Default::default()
}
}
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn libp2p_handshake_roundtrip() {
// ---- Server side ----
let tmp = TempDir::new().unwrap();
let unix_socket = tmp.path().join("brahman-init.sock");
let broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let server = Arc::new(
Server::bind(
&unix_socket,
ServerConfig {
init_attached: true,
broker: Some(broker.clone()),
net: None,
policy: None,
},
)
.unwrap(),
);
let sessions = server.sessions();
let server_net = Arc::new(BrahmanNet::new().unwrap());
let server_peer_id = server_net.peer_id;
// Listen on a random TCP port.
let listen_addr: Multiaddr = "/ip4/127.0.0.1/tcp/0".parse().unwrap();
let actual_addr = server_net.listen(listen_addr).await;
// Inject the libp2p PeerId into the multiaddr so the client knows
// who to dial.
let mut full_addr = actual_addr.clone();
full_addr.push(Protocol::P2p(server_peer_id));
// Spawn the libp2p accept loop.
tokio::spawn(run_libp2p_accept_loop(server.clone(), server_net.clone()));
// ---- Client side ----
let client_net = BrahmanNet::new().unwrap();
client_net.dial(full_addr.clone());
// Pequeña espera para que el dial conecte. En un entorno real el
// caller usaría un mecanismo de barrier, pero para tests un sleep
// corto es suficiente y deterministic en localhost.
tokio::time::sleep(Duration::from_millis(200)).await;
let card = sample_card("test.remote_ente");
let client_kp = client_net.keypair();
let mut client = connect_libp2p(&client_net, server_peer_id, card, None, &client_kp)
.await
.expect("handshake remoto debería completar");
// Verificación: el server vio la sesión.
{
let s = sessions.lock().await;
assert_eq!(s.len(), 1, "una sesión registrada");
let resolved = s.values().next().unwrap();
assert_eq!(resolved.card.label, "test.remote_ente");
}
// Ping roundtrip.
let ts = client.ping().await.expect("ping debería responder");
assert!(ts > 0, "timestamp del Pong > 0");
// Farewell limpio.
client.farewell().await.expect("farewell debería completar");
// Tras el farewell, el cleanup remueve la sesión.
// Damos un tick para que el handler procese el frame.
tokio::time::sleep(Duration::from_millis(100)).await;
{
let s = sessions.lock().await;
assert_eq!(s.len(), 0, "sesión removida tras farewell");
}
// peer_id no usado aquí, pero validamos que la API existe.
let _ = PeerId::random();
}
/// Fase 3 negativo: el cliente intenta firmar el Hello con una keypair
/// distinta a la del peer libp2p. El server (que verifica que la
/// public key del Hello derive al peer_id autenticado por Noise) debe
/// rechazar con `Unauthorized`.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn libp2p_handshake_rejects_mismatched_signing_key() {
let tmp = TempDir::new().unwrap();
let unix_socket = tmp.path().join("brahman-init.sock");
let server = Arc::new(
Server::bind(
&unix_socket,
ServerConfig {
init_attached: true,
broker: None,
net: None,
policy: None,
},
)
.unwrap(),
);
let sessions = server.sessions();
let server_net = Arc::new(BrahmanNet::new().unwrap());
let server_peer = server_net.peer_id;
let listen_addr: Multiaddr = "/ip4/127.0.0.1/tcp/0".parse().unwrap();
let actual = server_net.listen(listen_addr).await;
let mut full = actual.clone();
full.push(Protocol::P2p(server_peer));
tokio::spawn(run_libp2p_accept_loop(server.clone(), server_net.clone()));
let client_net = BrahmanNet::new().unwrap();
client_net.dial(full);
tokio::time::sleep(Duration::from_millis(200)).await;
// Keypair fraudulenta: NO es la del client_net.
let evil_keypair = Keypair::generate_ed25519();
let card = sample_card("test.evil");
let result = connect_libp2p(&client_net, server_peer, card, None, &evil_keypair).await;
assert!(
result.is_err(),
"handshake con keypair fraudulenta debe fallar"
);
// Sanidad: ninguna sesión registrada.
let s = sessions.lock().await;
assert_eq!(s.len(), 0, "no debería haber sesión registrada");
}
/// Allowlist gate: A configura `allowlist = [client_authorized_peer]`.
/// Un cliente con peer_id en la lista pasa el handshake; otro con
/// peer_id distinto es rechazado con `Unauthorized` ANTES de la
/// verificación de firma (la allowlist se chequea primero, es más
/// barata).
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn libp2p_handshake_allowlist_admits_listed_rejects_others() {
// Pre-generamos las dos identidades cliente para que A pueda
// construir la allowlist conociendo cuál es la "permitida".
let allowed_kp = Keypair::generate_ed25519();
let allowed_peer = allowed_kp.public().to_peer_id();
let denied_kp = Keypair::generate_ed25519();
// (denied_peer no se necesita para la lista — sólo para clarity)
let _ = denied_kp.public().to_peer_id();
// ---- Server con allowlist activa ----
let tmp = TempDir::new().unwrap();
let unix_socket = tmp.path().join("brahman-init.sock");
let server = Arc::new(
Server::bind(
&unix_socket,
ServerConfig {
init_attached: true,
broker: None,
net: None,
policy: Some(PeerPolicy::from_sets(
Some([allowed_peer].into_iter().collect()),
std::collections::BTreeSet::new(),
)),
},
)
.unwrap(),
);
let sessions = server.sessions();
let server_net = Arc::new(BrahmanNet::new().unwrap());
let server_peer = server_net.peer_id;
let actual = server_net.listen("/ip4/127.0.0.1/tcp/0".parse().unwrap()).await;
let mut full = actual.clone();
full.push(Protocol::P2p(server_peer));
tokio::spawn(run_libp2p_accept_loop(server.clone(), server_net.clone()));
// ---- Cliente PERMITIDO ----
let allowed_net = BrahmanNet::with_keypair(allowed_kp.clone()).unwrap();
allowed_net.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let card_ok = sample_card("test.allowed");
let mut allowed_client = connect_libp2p(&allowed_net, server_peer, card_ok, None, &allowed_kp)
.await
.expect("peer en allowlist debe pasar");
{
let s = sessions.lock().await;
assert_eq!(s.len(), 1, "sesión del peer permitido registrada");
}
allowed_client.farewell().await.ok();
tokio::time::sleep(Duration::from_millis(100)).await;
// ---- Cliente DENEGADO ----
let denied_net = BrahmanNet::with_keypair(denied_kp.clone()).unwrap();
denied_net.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let card_no = sample_card("test.denied");
let result = connect_libp2p(&denied_net, server_peer, card_no, None, &denied_kp).await;
assert!(
result.is_err(),
"peer fuera de allowlist debe ser rechazado, got: {:?}",
result.is_ok()
);
{
let s = sessions.lock().await;
assert_eq!(s.len(), 0, "ninguna sesión adicional registrada tras intento denegado");
}
}
/// Denylist gate: A configura `policy` con un peer en la denylist.
/// Modo abierto para todo lo demás (sin allowlist), pero el peer
/// baneado es rechazado aún teniendo Ed25519 válida y peer_id que
/// derivaría limpio del Noise handshake.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn libp2p_handshake_denylist_blocks_listed_peer() {
let banned_kp = Keypair::generate_ed25519();
let banned_peer = banned_kp.public().to_peer_id();
let other_kp = Keypair::generate_ed25519();
let tmp = TempDir::new().unwrap();
let unix_socket = tmp.path().join("brahman-init.sock");
let server = Arc::new(
Server::bind(
&unix_socket,
ServerConfig {
init_attached: true,
broker: None,
net: None,
policy: Some(PeerPolicy::from_sets(
None, // sin allowlist (abierto)
[banned_peer].into_iter().collect(),
)),
},
)
.unwrap(),
);
let sessions = server.sessions();
let server_net = Arc::new(BrahmanNet::new().unwrap());
let server_peer = server_net.peer_id;
let actual = server_net
.listen("/ip4/127.0.0.1/tcp/0".parse().unwrap())
.await;
let mut full = actual.clone();
full.push(Protocol::P2p(server_peer));
tokio::spawn(run_libp2p_accept_loop(server.clone(), server_net.clone()));
// Cliente baneado: connect debe fallar.
let banned_net = BrahmanNet::with_keypair(banned_kp.clone()).unwrap();
banned_net.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let card_x = sample_card("test.banned");
let result = connect_libp2p(&banned_net, server_peer, card_x, None, &banned_kp).await;
assert!(
result.is_err(),
"peer en denylist debe ser rechazado, got Ok"
);
{
let s = sessions.lock().await;
assert_eq!(s.len(), 0, "el peer baneado no debería tener sesión");
}
// Cliente no-baneado pasa.
let other_net = BrahmanNet::with_keypair(other_kp.clone()).unwrap();
other_net.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let card_ok = sample_card("test.other");
let mut other_client = connect_libp2p(&other_net, server_peer, card_ok, None, &other_kp)
.await
.expect("peer fuera de denylist debe pasar");
{
let s = sessions.lock().await;
assert_eq!(s.len(), 1, "sesión del peer no-baneado registrada");
}
other_client.farewell().await.ok();
}
/// Swarm-level deny via `PeerPolicy::attach_to_net`: cuando la deny
/// se aplica al swarm vía `block_list`, el peer baneado es rechazado
/// en el dial — la conexión TCP/Noise nunca completa, así que el
/// cliente nunca llega siquiera a mandar el Hello. Más eficiente que
/// el handshake-level deny.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn swarm_level_deny_blocks_before_noise() {
let banned_kp = Keypair::generate_ed25519();
let banned_peer = banned_kp.public().to_peer_id();
let tmp = TempDir::new().unwrap();
let unix_socket = tmp.path().join("brahman-init.sock");
let policy = card_handshake::peer_policy::PeerPolicy::from_sets(
None,
[banned_peer].into_iter().collect(),
);
let server = Arc::new(
Server::bind(
&unix_socket,
ServerConfig {
init_attached: true,
broker: None,
net: None,
policy: Some(policy.clone()),
},
)
.unwrap(),
);
let server_net = Arc::new(BrahmanNet::new().unwrap());
let server_peer = server_net.peer_id;
// ATTACH: la deny se proyecta al swarm. Es lo nuevo de este
// commit — sin esta llamada, el deny seguiría aplicando sólo
// al nivel de handshake brahman (lo que también funciona pero
// gasta un round-trip Noise).
policy.attach_to_net(server_net.clone());
let actual = server_net
.listen("/ip4/127.0.0.1/tcp/0".parse().unwrap())
.await;
let mut full = actual.clone();
full.push(Protocol::P2p(server_peer));
tokio::spawn(run_libp2p_accept_loop(server.clone(), server_net.clone()));
// Cliente baneado intenta dial + handshake. Con swarm-level
// deny, la conexión libp2p ni siquiera completa: `connect_libp2p`
// falla con error de open_stream (peer inalcanzable / connection
// refused) en lugar del Unauthorized del handshake-level path.
let banned_net = BrahmanNet::with_keypair(banned_kp.clone()).unwrap();
banned_net.dial(full.clone());
let card = sample_card("test.swarm_banned");
// Timeout corto: si el block falla, el handshake completaría
// rápido en localhost. Si funciona, debería fallar el dial casi
// instantáneo o colgarse hasta el timeout.
let result = tokio::time::timeout(
Duration::from_secs(3),
connect_libp2p(&banned_net, server_peer, card, None, &banned_kp),
)
.await;
match result {
Ok(Ok(_)) => panic!("peer baneado a nivel swarm NO debería completar handshake"),
Ok(Err(e)) => {
// Esperado: error de transporte/stream, no de handshake.
tracing::info!(error = %e, "swarm-level deny rechazó como esperado");
}
Err(_) => {
// También aceptable: timeout porque el dial nunca completa.
tracing::info!("swarm-level deny → connect timeout (también OK)");
}
}
}
/// Multi-key identity: la propiedad fundamental que cierra el
/// proyecto. El cliente B tiene una identity master estable; el
/// server A le permite el master_peer en allowlist. B se conecta con
/// **session1**; pasa. B "rota": genera **session2** distinta, emite
/// un nuevo cert con la misma identity, se conecta de nuevo. Pasa
/// también — sin que A toque su allowlist.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn identity_cert_allows_session_rotation_without_policy_change() {
// Master de B (estable, persistente).
let master_kp = Keypair::generate_ed25519();
let master_peer = master_kp.public().to_peer_id();
let identity = Identity::from_keypair(master_kp);
// A configura policy: allowlist con master_peer (NO sessions).
let tmp = TempDir::new().unwrap();
let unix_socket = tmp.path().join("brahman-init.sock");
let server = Arc::new(
Server::bind(
&unix_socket,
ServerConfig {
init_attached: true,
broker: None,
net: None,
policy: Some(PeerPolicy::from_sets(
Some([master_peer].into_iter().collect()),
std::collections::BTreeSet::new(),
)),
},
)
.unwrap(),
);
let sessions = server.sessions();
let server_net = Arc::new(BrahmanNet::new().unwrap());
let server_peer = server_net.peer_id;
let actual = server_net
.listen("/ip4/127.0.0.1/tcp/0".parse().unwrap())
.await;
let mut full = actual.clone();
full.push(Protocol::P2p(server_peer));
tokio::spawn(run_libp2p_accept_loop(server.clone(), server_net.clone()));
// ---- Conexión 1: session1 ----
let session1_kp = Keypair::generate_ed25519();
let cert1 = identity
.issue_session_cert(&session1_kp, DEFAULT_SESSION_TTL)
.unwrap();
let net1 = BrahmanNet::with_keypair(session1_kp.clone()).unwrap();
net1.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let mut client1 = connect_libp2p_with_cert(
&net1,
server_peer,
sample_card("test.session1"),
None,
&session1_kp,
cert1,
)
.await
.expect("session1 con cert válido del master allowlisted debe pasar");
{
let s = sessions.lock().await;
assert_eq!(s.len(), 1, "session1 registrada");
}
client1.farewell().await.ok();
tokio::time::sleep(Duration::from_millis(100)).await;
// ---- ROTACIÓN: session2 distinta, mismo master ----
let session2_kp = Keypair::generate_ed25519();
assert_ne!(
session1_kp.public().to_peer_id(),
session2_kp.public().to_peer_id(),
"test inválido si las sessions son iguales"
);
let cert2 = identity
.issue_session_cert(&session2_kp, DEFAULT_SESSION_TTL)
.unwrap();
let net2 = BrahmanNet::with_keypair(session2_kp.clone()).unwrap();
net2.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let mut client2 = connect_libp2p_with_cert(
&net2,
server_peer,
sample_card("test.session2"),
None,
&session2_kp,
cert2,
)
.await
.expect(
"session2 (rotada) con cert del MISMO master debe pasar sin tocar allowlist",
);
{
let s = sessions.lock().await;
assert_eq!(s.len(), 1, "session2 registrada");
}
client2.farewell().await.ok();
// Sanity: una session sin cert (path Fase 3) cuyo session_peer_id
// NO está en la allowlist (porque la allowlist tiene master, no
// sessions) DEBE ser rechazada.
let session_other = Keypair::generate_ed25519();
let net_other = BrahmanNet::with_keypair(session_other.clone()).unwrap();
net_other.dial(full.clone());
tokio::time::sleep(Duration::from_millis(200)).await;
let result = connect_libp2p(
&net_other,
server_peer,
sample_card("test.no_cert"),
None,
&session_other,
)
.await;
assert!(
result.is_err(),
"sin cert, session_peer_id (no listado) debe ser rechazado"
);
}
02_ruway/chasqui/card-sidecar/Cargo.toml
+33
View File
@@ -0,0 +1,33 @@
[package]
name = "card-sidecar"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Brahman — sidecar reusable: thread + tokio runtime que mantiene viva la sesión de un módulo contra el Init."
[dependencies]
card-core = { workspace = true }
card-handshake = { path = "../card-handshake" }
# Discovery remoto por DHT: el resolver local-first/remote-fallback expone
# `&BrahmanNet` y `PeerId` en su API pública.
card-net = { workspace = true }
thiserror = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
[dev-dependencies]
tracing-subscriber = { workspace = true }
card-wit = { workspace = true }
chasqui-broker = { path = "../chasqui-broker" }
tempfile = { workspace = true }
[[example]]
name = "presence"
path = "examples/presence.rs"
[[example]]
name = "presence-conscious"
path = "examples/presence-conscious.rs"
02_ruway/chasqui/card-sidecar/examples/presence-conscious.rs
+99
View File
@@ -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 card_core::{
ulid::Ulid, Card, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef,
CARD_SCHEMA_VERSION,
};
use card_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 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();
}
02_ruway/chasqui/card-sidecar/examples/presence.rs
+70
View File
@@ -0,0 +1,70 @@
//! `presence` — módulo brahman dummy para pruebas y demos.
//!
//! Declara una Card mínima con label tomado del primer argumento (default
//! `presence-default`) y mantiene la sesión viva hasta SIGTERM/SIGINT.
//! Útil para poblar el broker con sesiones de prueba.
//!
//! Uso:
//! ```sh
//! cargo run -p brahman-sidecar --example presence -- mi-modulo
//! ```
use std::collections::BTreeSet;
use std::time::Duration;
use card_core::{
ulid::Ulid, Card, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef,
CARD_SCHEMA_VERSION,
};
use card_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 label = std::env::args()
.nth(1)
.unwrap_or_else(|| "presence-default".into());
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 _handle = spawn_with_handle(SidecarConfig {
card,
wit: None,
ping_interval: Duration::from_secs(5),
});
eprintln!("presence({label}): sidecar lanzado, durmiendo (Ctrl-C para salir)");
std::thread::park();
}
02_ruway/chasqui/card-sidecar/src/discovery.rs
+453
View File
@@ -0,0 +1,453 @@
//! `brahman-sidecar::discovery` — API reusable para que un módulo
//! consumer encuentre proveedores vivos vía broker, sin hardcodear
//! sockets ni reimplementar el patrón a mano.
//!
//! Es la generalización de `discover_producer_socket` del CLI
//! `chasqui attract --remote`: declarás el `TypeRef` que querés
//! consumir y el broker te empuja un `MatchEvent::Available` con el
//! `producer_service_socket` del primer proveedor matched.
//!
//! Pipeline:
//! 1. `build_consumer_card(label, flow_name, type_name)` arma una
//! Card mínima (Ente, Oneshot, Virtual) con un input flow.
//! 2. `await_provider(card, timeout)` se conecta al brahman-init,
//! espera hasta `timeout` por `MatchEvent::Available`, devuelve
//! el socket del proveedor electo, y envía Farewell.
//! 3. Para mundos blocking (CLIs, tests, std-thread loops) hay
//! `await_provider_blocking` que arma su propio runtime
//! `current_thread`.
//!
//! Quién elige al proveedor es el broker, no este módulo. Si el
//! broker tiene `priority_contexts` activo, podés cambiar de
//! proveedor sin tocar el consumer; el matching dinámico se respeta.
use std::path::PathBuf;
use std::time::{Duration, Instant};
use card_core::{
Card, CardKind, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef, WitInterface,
};
use card_net::{BrahmanNet, PeerId};
use card_handshake::client::{Client, ClientError};
use card_handshake::messages::MatchEventKind;
use card_handshake::network::{connect_libp2p, LibP2pHandshakeStream, NetworkError};
use card_handshake::transport;
use tracing::warn;
#[derive(Debug, thiserror::Error)]
pub enum ConsumerError {
#[error("no se pudo conectar al init en {socket}: {source}")]
Connect {
socket: PathBuf,
#[source]
source: ClientError,
},
#[error("error en cliente brahman: {0}")]
Client(#[from] ClientError),
#[error("timeout {timeout:?} sin proveedor disponible para flow '{flow}' (type '{type_ref}')")]
NoProvider {
flow: String,
type_ref: String,
timeout: Duration,
},
#[error("no se pudo crear runtime tokio: {0}")]
Runtime(String),
#[error("la Card consumer no declara ningún input flow para resolver")]
NoInputFlow,
#[error(
"el DHT no anuncia proveedores para flow '{flow}' (type '{type_ref}')"
)]
NoRemoteProviders { flow: String, type_ref: String },
#[error(
"todos los {} peers remotos fallaron al conectar; último error: {source}",
peers.len()
)]
AllPeersFailed {
peers: Vec<PeerId>,
#[source]
source: NetworkError,
},
}
/// Construye una Card mínima de consumer que declara un input flow
/// con el `TypeRef::Primitive { name }` solicitado. Usá esto para
/// el caso común; si necesitás algo más rico (output flows,
/// permissions, references) construí la Card a mano y pasala a
/// [`await_provider`] directamente.
pub fn build_consumer_card(
consumer_label: impl Into<String>,
flow_name: impl Into<String>,
type_name: impl Into<String>,
) -> Card {
Card {
payload: Payload::Virtual,
supervision: Supervision::OneShot,
lifecycle: Lifecycle::Oneshot,
priority: Priority::Normal,
kind: CardKind::Ente,
flow: Flows {
input: vec![Flow {
name: flow_name.into(),
ty: TypeRef::Primitive {
name: type_name.into(),
},
pin_to: None,
}],
output: vec![],
},
..Card::new(consumer_label)
}
}
/// Conecta al brahman-init, registra `consumer_card`, espera el
/// primer `MatchEvent::Available` y devuelve el `producer_service_socket`
/// que el broker emitió. Cierra la sesión con Farewell antes de
/// retornar (best-effort).
///
/// La `consumer_card` debe declarar al menos un `flow.input`; si no,
/// el broker no puede hacer matching y el await siempre dará timeout.
pub async fn await_provider(
consumer_card: Card,
timeout: Duration,
) -> Result<PathBuf, ConsumerError> {
let init_path = transport::default_socket_path();
// Capturamos descriptor para el mensaje de error antes de mover
// la card al cliente.
let (flow_name, type_ref_name) = describe_first_input(&consumer_card);
let mut client = Client::connect(&init_path, consumer_card)
.await
.map_err(|source| ConsumerError::Connect {
socket: init_path.clone(),
source,
})?;
let deadline = Instant::now() + timeout;
let socket = loop {
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining.is_zero() {
break None;
}
match client.await_event(remaining).await? {
Some(ev) if ev.kind == MatchEventKind::Available => {
break ev.producer_service_socket;
}
Some(_) => continue, // Lost u otros: seguir esperando hasta el deadline
None => break None,
}
};
let _ = client.farewell().await; // best-effort cleanup
socket.ok_or(ConsumerError::NoProvider {
flow: flow_name,
type_ref: type_ref_name,
timeout,
})
}
/// Wrapper bloqueante de [`await_provider`]. Crea un runtime tokio
/// `current_thread` efímero y bloquea el thread llamador. Útil para
/// CLIs, tests y módulos std-thread (p. ej. el frontend GPUI antes
/// de tener su propio runtime async).
pub fn await_provider_blocking(
consumer_card: Card,
timeout: Duration,
) -> Result<PathBuf, ConsumerError> {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
.map_err(|e| ConsumerError::Runtime(e.to_string()))?;
rt.block_on(await_provider(consumer_card, timeout))
}
// =====================================================================
// Discovery local-first / remoto (DHT) — capa de consumidor
// =====================================================================
/// Discovery DHT crudo, reexportado desde `card-handshake` para que un
/// consumidor que ya usa `card-sidecar` pueda buscar proveedores remotos
/// por `(flow_name, TypeRef)` sin alcanzar las internas del handshake.
pub use card_handshake::network::find_remote_providers;
/// Dónde vive el proveedor elegido para un flow.
///
/// El broker local (vía `await_provider`) entrega un socket Unix listo
/// para consumir; el DHT remoto entrega `PeerId`s que el caller debe
/// dial-ar y sub-handshakear con `card_handshake::network::connect_libp2p`.
#[derive(Debug, Clone)]
pub enum ProviderLocation {
/// Proveedor local: socket de servicio resuelto por el broker del init.
Local(PathBuf),
/// Proveedores remotos anunciados en el DHT (peers a dial-ar).
Remote(Vec<PeerId>),
}
/// Resuelve un proveedor para el **primer input flow** de `consumer_card`,
/// **local primero, DHT remoto como fallback**.
///
/// 1. Pregunta al broker del init local (`await_provider`) hasta
/// `local_timeout`. Si hay match → [`ProviderLocation::Local`].
/// 2. Si no hay proveedor local (timeout) ni init local alcanzable
/// (socket ausente), consulta el DHT vía `net` y devuelve
/// [`ProviderLocation::Remote`] con los `PeerId`s que anuncian el flow
/// (lista posiblemente vacía si nadie lo provee en la malla).
///
/// Esto es el cableado que faltaba entre el discovery local (broker) y el
/// discovery remoto (DHT de `card-net`, ya cableado en el handshake): un
/// consumidor pide "un proveedor para el tipo X" y obtiene el más cercano
/// disponible sin saber a priori si vive en esta máquina o en la red.
pub async fn resolve_provider(
consumer_card: Card,
net: &BrahmanNet,
local_timeout: Duration,
) -> Result<ProviderLocation, ConsumerError> {
// Necesitamos el flow a resolver antes de mover la card al broker.
let (flow_name, ty) = match consumer_card.flow.input.first() {
Some(f) => (f.name.clone(), f.ty.clone()),
None => return Err(ConsumerError::NoInputFlow),
};
// 1) Local primero.
match await_provider(consumer_card, local_timeout).await {
Ok(socket) => return Ok(ProviderLocation::Local(socket)),
// Sin proveedor local (timeout) o sin init local alcanzable:
// caemos al DHT. Cualquier otro error sí se propaga.
Err(ConsumerError::NoProvider { .. }) | Err(ConsumerError::Connect { .. }) => {}
Err(other) => return Err(other),
}
// 2) Fallback remoto por DHT.
let peers = find_remote_providers(net, &flow_name, &ty).await;
Ok(ProviderLocation::Remote(peers))
}
/// Consume una `Card` a través de un proveedor remoto descubierto por DHT.
///
/// Recorre `peers` en orden, intentando `connect_libp2p` con cada uno hasta
/// que uno establezca handshake. La sesión devuelta es un `Client` idéntico
/// al del path Unix: `ping`, `await_event`, `farewell` funcionan igual; el
/// stream subyacente es libp2p convertido vía `tokio_util::compat`.
///
/// La keypair que se usa para firmar el handshake es la del propio `net`
/// (`BrahmanNet::keypair`) — la misma que autentica la conexión Noise, así
/// que el `peer_id` del Hello coincide con el del transporte y el server
/// no rechaza por `Unauthorized`.
///
/// Errores:
/// * [`ConsumerError::NoRemoteProviders`] si `peers` está vacío.
/// * [`ConsumerError::AllPeersFailed`] si ningún peer aceptó el handshake;
/// el `source` es el último `NetworkError` observado.
///
/// Atajo de uso típico tras `resolve_provider`:
/// ```ignore
/// match resolve_provider(card.clone(), &net, timeout).await? {
/// ProviderLocation::Local(socket) => {
/// Client::connect_with(&socket, card, wit).await?
/// }
/// ProviderLocation::Remote(peers) => {
/// consume_remote(&net, card, wit, peers).await?
/// }
/// };
/// ```
pub async fn consume_remote(
net: &BrahmanNet,
consumer_card: Card,
wit: Option<WitInterface>,
peers: Vec<PeerId>,
) -> Result<Client<LibP2pHandshakeStream>, ConsumerError> {
if peers.is_empty() {
let (flow, type_ref) = describe_first_input(&consumer_card);
return Err(ConsumerError::NoRemoteProviders { flow, type_ref });
}
let keypair = net.keypair();
let mut last_error: Option<NetworkError> = None;
for peer in &peers {
match connect_libp2p(net, *peer, consumer_card.clone(), wit.clone(), &keypair).await {
Ok(client) => return Ok(client),
Err(e) => {
warn!(
target: "card_sidecar",
peer = %peer,
error = %e,
"dial al peer remoto falló, intento siguiente",
);
last_error = Some(e);
}
}
}
Err(ConsumerError::AllPeersFailed {
peers,
source: last_error.expect("el loop garantiza al menos un error si peers no era vacío"),
})
}
/// Conecta al brahman-init con una Card observer (sin inputs ni
/// outputs) y pide la lista de sesiones activas. Útil para
/// herramientas de observabilidad (broker-explorer, CLIs).
///
/// El observer se identifica con `observer_label`. La sesión se
/// cierra con Farewell antes de retornar (best-effort).
pub async fn list_sessions(
observer_label: impl Into<String>,
) -> Result<card_handshake::messages::SessionList, ConsumerError> {
let init_path = transport::default_socket_path();
// Card mínima sin flow.input/output: el observer no participa en
// matching, sólo establece sesión para poder consultar.
let card = Card {
payload: Payload::Virtual,
supervision: Supervision::OneShot,
lifecycle: Lifecycle::Oneshot,
priority: Priority::Normal,
kind: CardKind::Ente,
flow: Flows {
input: vec![],
output: vec![],
},
..Card::new(observer_label)
};
let mut client = Client::connect(&init_path, card)
.await
.map_err(|source| ConsumerError::Connect {
socket: init_path.clone(),
source,
})?;
let list = client.list_sessions().await?;
let _ = client.farewell().await;
Ok(list)
}
/// Wrapper bloqueante de [`list_sessions`]. Idéntico patrón a
/// `await_provider_blocking`: runtime current_thread efímero.
pub fn list_sessions_blocking(
observer_label: impl Into<String>,
) -> Result<card_handshake::messages::SessionList, ConsumerError> {
let label = observer_label.into();
let rt = tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
.map_err(|e| ConsumerError::Runtime(e.to_string()))?;
rt.block_on(list_sessions(label))
}
/// Análogo a `list_sessions` pero pide los matches activos del
/// broker. La Card observer es la misma forma minimalista (sin
/// flow.input/output) — el endpoint no requiere participar en
/// matching.
pub async fn list_matches(
observer_label: impl Into<String>,
) -> Result<card_handshake::messages::MatchList, ConsumerError> {
let init_path = transport::default_socket_path();
let card = Card {
payload: Payload::Virtual,
supervision: Supervision::OneShot,
lifecycle: Lifecycle::Oneshot,
priority: Priority::Normal,
kind: CardKind::Ente,
flow: Flows {
input: vec![],
output: vec![],
},
..Card::new(observer_label)
};
let mut client = Client::connect(&init_path, card)
.await
.map_err(|source| ConsumerError::Connect {
socket: init_path.clone(),
source,
})?;
let list = client.list_matches().await?;
let _ = client.farewell().await;
Ok(list)
}
/// Wrapper bloqueante de [`list_matches`].
pub fn list_matches_blocking(
observer_label: impl Into<String>,
) -> Result<card_handshake::messages::MatchList, ConsumerError> {
let label = observer_label.into();
let rt = tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
.map_err(|e| ConsumerError::Runtime(e.to_string()))?;
rt.block_on(list_matches(label))
}
fn describe_first_input(card: &Card) -> (String, String) {
match card.flow.input.first() {
Some(flow) => {
let type_name = match &flow.ty {
TypeRef::Primitive { name } => name.clone(),
TypeRef::Wit { package, name, .. } => format!("{package}#{name}"),
};
(flow.name.clone(), type_name)
}
None => ("(sin input)".into(), "(sin tipo)".into()),
}
}
#[cfg(test)]
mod tests {
use super::*;
use card_core::ulid::Ulid;
#[test]
fn builder_sets_input_flow_with_primitive_type() {
let c = build_consumer_card("chasqui.cli", "embed-result", "json");
assert_eq!(c.label, "chasqui.cli");
assert_eq!(c.kind, CardKind::Ente);
assert!(matches!(c.lifecycle, Lifecycle::Oneshot));
assert!(matches!(c.supervision, Supervision::OneShot));
assert_eq!(c.flow.input.len(), 1);
let f = &c.flow.input[0];
assert_eq!(f.name, "embed-result");
match &f.ty {
TypeRef::Primitive { name } => assert_eq!(name, "json"),
_ => panic!("expected primitive type"),
}
assert!(c.flow.output.is_empty());
// El builder asigna un id real (no nil) — fundamental para que
// el broker no colisione con otros consumers.
assert!(c.id != Ulid::nil(), "consumer card id no debe ser nil");
}
#[test]
fn builder_assigns_distinct_ids_per_call() {
let a = build_consumer_card("a", "f", "t");
let b = build_consumer_card("a", "f", "t");
assert_ne!(a.id, b.id, "cada Card debería tener id propio");
}
#[test]
fn describe_falls_back_when_no_input_flow() {
let mut c = build_consumer_card("x", "f", "t");
c.flow.input.clear();
let (flow, ty) = describe_first_input(&c);
assert_eq!(flow, "(sin input)");
assert_eq!(ty, "(sin tipo)");
}
#[test]
fn describe_formats_wit_type() {
let mut c = build_consumer_card("x", "f", "t");
c.flow.input[0].ty = TypeRef::Wit {
package: "brahman:dht".into(),
interface: None,
name: "entity-result".into(),
};
let (_, ty) = describe_first_input(&c);
assert_eq!(ty, "brahman:dht#entity-result");
}
}
02_ruway/chasqui/card-sidecar/src/lib.rs
+255
View File
@@ -0,0 +1,255 @@
//! `brahman-sidecar` — boilerplate del cliente brahman extraído.
//!
//! Cualquier módulo que quiera presentarse al Init brahman pero que tenga
//! su propio runtime (GPUI, current_thread tokio, std-thread loop, etc.)
//! puede llamar [`spawn`] con su [`card_core::Card`]. Eso arma un
//! thread aparte con un runtime tokio current_thread, conecta al Init,
//! y mantiene la sesión viva con pings periódicos.
//!
//! Si el Init no está disponible, el thread loggea y termina — el módulo
//! sigue funcionando standalone.
//!
//! Errores de conexión / ping se loggean vía `tracing::warn!`. Si querés
//! capturar la salida del thread (por ejemplo para test), usá
//! [`spawn_with_handle`] que devuelve un `JoinHandle`.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
pub mod discovery;
pub use discovery::{
await_provider, await_provider_blocking, build_consumer_card, consume_remote, list_matches,
list_matches_blocking, list_sessions, list_sessions_blocking, resolve_provider, ConsumerError,
ProviderLocation,
};
use std::collections::HashMap;
use std::sync::{mpsc, Arc, Mutex};
use std::thread::JoinHandle;
use std::time::Duration;
use card_core::{ulid::Ulid, Card, WitInterface};
use card_handshake::{client::Client, transport};
use tokio::task::AbortHandle;
use tracing::{info, warn};
/// Período entre pings al Init.
pub const DEFAULT_PING_INTERVAL: Duration = Duration::from_secs(30);
/// Configuración del sidecar.
#[derive(Debug, Clone)]
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<WitInterface>,
/// Período entre pings.
pub ping_interval: Duration,
}
impl SidecarConfig {
/// 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 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<JoinHandle<()>> {
std::thread::Builder::new()
.name("brahman-sidecar".into())
.spawn(move || run_thread(config))
}
// =====================================================================
// SidecarPool — un solo runtime tokio compartido por N sesiones
// =====================================================================
/// Pool consolidado: un único thread con un runtime tokio
/// `current_thread` que hostea N tasks de sidecar simultáneas.
///
/// Para módulos con muchas sesiones (p. ej. `chasqui daemon` publicando
/// 50+ Mónadas), evita el costo de tener un thread+runtime por cada
/// sesión.
///
/// **API**:
/// - `SidecarPool::new()` crea el pool (spawn del thread runtime).
/// - `pool.spawn(card)` añade una sesión sin WIT.
/// - `pool.spawn_conscious(card, wit)` añade una sesión con WIT.
/// - `pool.spawn_with_config(config)` para configuración custom.
///
/// El pool se mantiene vivo mientras exista. Si el `SidecarPool`
/// se dropea, el thread interno termina y todas las sesiones cierran.
pub struct SidecarPool {
handle: tokio::runtime::Handle,
/// Sesiones vivas indexadas por `Card.id`. Permite que un nuevo
/// `spawn` con el mismo id aborte la sesión previa — útil cuando
/// un módulo (p. ej. `chasqui daemon`) re-publica una Mónada cuya
/// composición cambió.
sessions: Arc<Mutex<HashMap<Ulid, AbortHandle>>>,
_thread: JoinHandle<()>,
}
impl SidecarPool {
/// Crea un pool nuevo. Bloquea hasta que el runtime esté listo.
pub fn new() -> std::io::Result<Self> {
let (handle_tx, handle_rx) = mpsc::sync_channel::<tokio::runtime::Handle>(0);
let thread = std::thread::Builder::new()
.name("brahman-sidecar-pool".into())
.spawn(move || {
let rt = match tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
{
Ok(rt) => rt,
Err(e) => {
warn!(error = %e, "tokio runtime falló — pool muerto");
return;
}
};
if handle_tx.send(rt.handle().clone()).is_err() {
return;
}
// Mantenemos el runtime vivo mientras existan tasks.
rt.block_on(std::future::pending::<()>());
})?;
let handle = handle_rx
.recv()
.map_err(|_| std::io::Error::other("pool runtime no respondió"))?;
Ok(Self {
handle,
sessions: Arc::new(Mutex::new(HashMap::new())),
_thread: thread,
})
}
/// Añade una sesión agnóstica al pool (sin WIT).
pub fn spawn(&self, card: Card) {
self.spawn_with_config(SidecarConfig::new(card));
}
/// Añade una sesión consciente (con WIT) al pool.
pub fn spawn_conscious(&self, card: Card, wit: WitInterface) {
self.spawn_with_config(SidecarConfig::new(card).with_wit(wit));
}
/// Añade una sesión con configuración custom.
///
/// Si ya existía una sesión para el mismo `Card.id`, la previa
/// se aborta antes de spawnear la nueva. Esto hace `spawn`
/// idempotente respecto al id: re-publicar una Mónada cuya
/// composición cambió "refresca" la sesión en el broker.
pub fn spawn_with_config(&self, config: SidecarConfig) {
let card_id = config.card.id;
let join = self.handle.spawn(run_client(config));
let abort = join.abort_handle();
if let Ok(mut sessions) = self.sessions.lock() {
if let Some(prev) = sessions.insert(card_id, abort) {
prev.abort();
}
}
}
/// Cierra explícitamente la sesión asociada a `card_id`. No-op si
/// no había sesión registrada.
pub fn drop_session(&self, card_id: Ulid) {
if let Ok(mut sessions) = self.sessions.lock() {
if let Some(abort) = sessions.remove(&card_id) {
abort.abort();
}
}
}
/// Cantidad actual de sesiones vivas (estimada — puede haber
/// drift transitorio entre abort y limpieza).
pub fn live_sessions(&self) -> usize {
self.sessions.lock().map(|s| s.len()).unwrap_or(0)
}
}
impl Default for SidecarPool {
fn default() -> Self {
Self::new().expect("falló SidecarPool::new")
}
}
fn run_thread(config: SidecarConfig) {
let rt = match tokio::runtime::Builder::new_current_thread()
.enable_io()
.enable_time()
.build()
{
Ok(rt) => rt,
Err(e) => {
warn!(error = %e, "tokio runtime falló");
return;
}
};
rt.block_on(run_client(config));
}
/// Bucle async del sidecar. Público para que `SidecarPool` lo use vía
/// `handle.spawn(run_client(...))` desde código externo al runtime.
pub async fn run_client(config: SidecarConfig) {
let path = transport::default_socket_path();
let conscious = config.wit.is_some();
let mut client = match Client::connect_with(&path, config.card, config.wit).await {
Ok(c) => {
info!(
target: "card_sidecar",
session = %c.session(),
init_attached = c.server_info().init_attached,
server = %c.server_info().server_version,
conscious,
"attached"
);
c
}
Err(e) => {
warn!(
target: "card_sidecar",
error = %e,
socket = %path.display(),
"no conectado"
);
return;
}
};
loop {
tokio::time::sleep(config.ping_interval).await;
if let Err(e) = client.ping().await {
warn!(target: "card_sidecar", error = %e, "ping falló — terminando sidecar");
return;
}
}
}
02_ruway/chasqui/card-sidecar/tests/remote_discovery.rs
+256
View File
@@ -0,0 +1,256 @@
//! Integración del resolver `card_sidecar::discovery::resolve_provider`:
//! prueba el camino **local-first / remote-fallback**. Sin init local
//! alcanzable (socket bogus), el resolver debe caer al DHT y descubrir un
//! proveedor remoto que anunció su output flow.
//!
//! Reusa el harness de `card-handshake/tests/network_discovery.rs`: un Node A
//! con Server + `BrahmanNet` + Card-con-output (el Server llama
//! `announce_outputs` al registrar → `start_providing` en el DHT), y un Node B
//! que dial-a a A y resuelve vía el DHT compartido.
use std::sync::Arc;
use std::time::Duration;
use card_core::{
Card, CardKind, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef,
};
use card_handshake::network::run_libp2p_accept_loop;
use card_handshake::server::{Server, ServerConfig};
use card_net::{BrahmanNet, Multiaddr, Protocol};
use card_sidecar::discovery::{
build_consumer_card, consume_remote, resolve_provider, ConsumerError, ProviderLocation,
};
use chasqui_broker::{Broker, BrokerConfig};
use tempfile::TempDir;
use tokio::sync::Mutex;
/// Card de proveedor con un único output flow `(flow_name, type_name)`.
fn provider_card(label: &str, flow_name: &str, type_name: &str) -> Card {
Card {
payload: Payload::Virtual,
supervision: Supervision::Delegate,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
kind: CardKind::Ente,
flow: Flows {
input: vec![],
output: vec![Flow {
name: flow_name.into(),
ty: TypeRef::Primitive {
name: type_name.into(),
},
pin_to: None,
}],
},
..Card::new(label)
}
}
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn resolve_provider_cae_a_dht_cuando_no_hay_local() {
// Forzar miss local: que `await_provider` falle rápido por socket ausente
// (nextest aísla cada test en su propio proceso, así que la env no se filtra).
std::env::set_var("BRAHMAN_INIT_SOCKET", "/nonexistent/brahman-init-test.sock");
// ---- Node A: Server + net + Card con output (anuncia al DHT) ----
let tmp = TempDir::new().unwrap();
let a_unix = tmp.path().join("a.sock");
let a_broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let a_net = Arc::new(BrahmanNet::new().unwrap());
let a_peer = a_net.peer_id;
let a_server = Arc::new(
Server::bind(
&a_unix,
ServerConfig {
init_attached: true,
broker: Some(a_broker.clone()),
net: Some(a_net.clone()), // ← el Server anuncia los outputs al DHT
policy: None,
},
)
.unwrap(),
);
let listen_addr: Multiaddr = "/ip4/127.0.0.1/tcp/0".parse().unwrap();
let a_addr = a_net.listen(listen_addr).await;
let mut a_full = a_addr.clone();
a_full.push(Protocol::P2p(a_peer));
tokio::spawn(run_libp2p_accept_loop(a_server.clone(), a_net.clone()));
{
let s = a_server.clone();
tokio::spawn(async move {
loop {
match s.accept_one().await {
Ok(session) => {
tokio::spawn(async move {
let _ = session.handle().await;
});
}
Err(_) => break,
}
}
});
}
// A registra una Card con output "monad-list":json → start_providing.
let card = provider_card("test.engine_remote", "monad-list", "json");
let mut local_client = card_handshake::client::Client::connect(&a_unix, card)
.await
.expect("registro local en A");
// ---- Node B: net que dial-a a A y comparte DHT ----
let b_net = BrahmanNet::new().unwrap();
b_net.dial(a_full.clone());
// Margen para que Identify popule la routing table de Kad.
tokio::time::sleep(Duration::from_millis(500)).await;
// resolve_provider: sin init local (socket bogus) → fallback al DHT.
let consumer = build_consumer_card("test.consumer", "monad-list", "json");
let loc = resolve_provider(consumer, &b_net, Duration::from_millis(200))
.await
.expect("resolve_provider no debe errar");
match loc {
ProviderLocation::Remote(peers) => assert!(
peers.contains(&a_peer),
"el fallback DHT debería descubrir a A; encontrados: {:?}, esperado: {}",
peers,
a_peer
),
ProviderLocation::Local(s) => {
panic!("esperaba Remote (no hay init local), obtuve Local({:?})", s)
}
}
local_client.farewell().await.ok();
}
/// End-to-end del follow-up de Nivel 3 (CIERRE §3.2): un nodo descubre por
/// DHT a un proveedor remoto y CONSUME — abre handshake firmado por libp2p,
/// pinea y se despide — sin un init local de por medio. Es el patrón de
/// `jalar_a_traves_de_un_relay` aplicado al consumer-side de chasqui.
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn consume_remote_abre_handshake_firmado_via_libp2p() {
// Mismo truco que el test de arriba: forzar miss del init local para
// que el resolver caiga directo al DHT.
std::env::set_var(
"BRAHMAN_INIT_SOCKET",
"/nonexistent/brahman-init-consume.sock",
);
// ---- Node A: Server + net; al registrar la Card con output, el
// Server llama `announce_outputs` y publica la key
// `(monad-list, json)` en el DHT.
let tmp = TempDir::new().unwrap();
let a_unix = tmp.path().join("a.sock");
let a_broker = Arc::new(Mutex::new(Broker::new(BrokerConfig::default())));
let a_net = Arc::new(BrahmanNet::new().unwrap());
let a_peer = a_net.peer_id;
let a_server = Arc::new(
Server::bind(
&a_unix,
ServerConfig {
init_attached: true,
broker: Some(a_broker.clone()),
net: Some(a_net.clone()),
policy: None,
},
)
.unwrap(),
);
let listen_addr: Multiaddr = "/ip4/127.0.0.1/tcp/0".parse().unwrap();
let a_addr = a_net.listen(listen_addr).await;
let mut a_full = a_addr.clone();
a_full.push(Protocol::P2p(a_peer));
// A acepta tanto las sesiones libp2p (handshake firmado entrante) como
// las locales por socket Unix (necesarias para registrar la Card que
// dispara el `announce_outputs`).
tokio::spawn(run_libp2p_accept_loop(a_server.clone(), a_net.clone()));
{
let s = a_server.clone();
tokio::spawn(async move {
loop {
match s.accept_one().await {
Ok(session) => {
tokio::spawn(async move {
let _ = session.handle().await;
});
}
Err(_) => break,
}
}
});
}
let provider = provider_card("test.engine_remote_consume", "monad-list", "json");
let mut local_provider_client = card_handshake::client::Client::connect(&a_unix, provider)
.await
.expect("registro local del provider en A");
// ---- Node B: net independiente; dial-a A para compartir DHT.
let b_net = BrahmanNet::new().unwrap();
b_net.dial(a_full.clone());
tokio::time::sleep(Duration::from_millis(500)).await;
// Descubrir.
let consumer = build_consumer_card("test.consumer_remote", "monad-list", "json");
let loc = resolve_provider(consumer.clone(), &b_net, Duration::from_millis(200))
.await
.expect("resolve_provider no debe errar");
let peers = match loc {
ProviderLocation::Remote(peers) => {
assert!(
peers.contains(&a_peer),
"el fallback DHT debería descubrir a A; encontrados: {:?}, esperado: {}",
peers,
a_peer
);
peers
}
ProviderLocation::Local(s) => {
panic!("esperaba Remote (no hay init local), obtuve Local({:?})", s)
}
};
// Consumir: abre handshake firmado por libp2p contra A y pinea.
let mut remote = consume_remote(&b_net, consumer, None, peers)
.await
.expect("consume_remote debe abrir handshake firmado contra A");
remote
.ping()
.await
.expect("ping libp2p sobre la sesión consumer-remoto");
// Cierre limpio de ambas sesiones.
remote.farewell().await.ok();
local_provider_client.farewell().await.ok();
}
/// Si el DHT no anuncia ningún proveedor para el flow pedido, `consume_remote`
/// no debe colgar ni intentar nada — debe fallar inmediato con
/// `NoRemoteProviders`. Este test no necesita Net A ni B, sólo un net solo y
/// una lista vacía de peers.
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn consume_remote_falla_inmediato_si_no_hay_peers() {
let net = BrahmanNet::new().unwrap();
let consumer = build_consumer_card("test.consumer_solo", "flow-fantasma", "json");
let err = consume_remote(&net, consumer, None, vec![])
.await
.expect_err("vector vacío debe traducirse a NoRemoteProviders");
match err {
ConsumerError::NoRemoteProviders { flow, type_ref } => {
assert_eq!(flow, "flow-fantasma");
assert_eq!(type_ref, "json");
}
otro => panic!("esperaba NoRemoteProviders, obtuve {otro:?}"),
}
}
02_ruway/chasqui/chasqui-broker-explorer-llimphi/Cargo.toml
+28
View File
@@ -0,0 +1,28 @@
[package]
name = "chasqui-broker-explorer-llimphi"
version.workspace = true
edition.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Probe Llimphi del broker brahman: conecta cada N segundos vía await_provider_blocking con un Card observer agnóstico, reporta 3 estados (down / up sin provider / up con provider) y trackea la diff de matches entre ticks. Reemplazo del `chasqui-broker-explorer` GPUI."
[dependencies]
chasqui-broker = { path = "../chasqui-broker" }
card-core = { workspace = true }
card-handshake = { path = "../card-handshake" }
card-sidecar = { path = "../card-sidecar" }
ulid = { workspace = true }
llimphi-ui = { workspace = true }
llimphi-theme = { workspace = true }
llimphi-widget-app-header = { workspace = true }
llimphi-widget-banner = { workspace = true }
llimphi-widget-stat-card = { workspace = true }
llimphi-widget-menubar = { workspace = true }
llimphi-widget-context-menu = { workspace = true }
llimphi-motion = { workspace = true }
app-bus = { workspace = true }
[[bin]]
name = "chasqui-broker-explorer-llimphi"
path = "src/main.rs"
02_ruway/chasqui/chasqui-broker-explorer-llimphi/LEEME.md
+16
View File
@@ -0,0 +1,16 @@
# chasqui-broker-explorer-llimphi
> UI Llimphi: topics + suscriptores activos del broker de [chasqui](../README.md).
Lista los topics actuales, cuántos suscriptores tiene cada uno, throughput por topic, persistencia activa o no. Útil para diagnosticar el sistema.
## Uso
```sh
cargo run --release -p chasqui-broker-explorer-llimphi
```
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous-real`](../chasqui-nous-real/README.md)
- [`llimphi-ui`](../../llimphi/) + widgets `list`, `tabs`
02_ruway/chasqui/chasqui-broker-explorer-llimphi/README.md
+16
View File
@@ -0,0 +1,16 @@
# chasqui-broker-explorer-llimphi
> Llimphi UI: topics + active subscribers of [chasqui](../README.md)'s broker.
Lists current topics, how many subscribers each has, throughput per topic, persistence active or not. Useful for diagnosing the system.
## Usage
```sh
cargo run --release -p chasqui-broker-explorer-llimphi
```
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous-real`](../chasqui-nous-real/README.md)
- [`llimphi-ui`](../../llimphi/) + widgets `list`, `tabs`
02_ruway/chasqui/chasqui-broker-explorer-llimphi/src/main.rs
+868
View File
@@ -0,0 +1,868 @@
//! `chasqui-broker-explorer-llimphi` — probe Llimphi del broker
//! brahman.
//!
//! Cada [`POLL_INTERVAL`] arma un Card observer agnóstico y lo manda
//! al broker via `card_sidecar::await_provider_blocking` (que
//! internamente abre tokio runtime + Unix socket + handshake).
//! Reporta 3 estados:
//!
//! - **Down**: connect failed (broker no escucha en el socket).
//! - **Up sin provider**: connect OK, pero el broker no encontró
//! productor para el flow probado dentro del timeout.
//! - **Up con provider**: connect OK + el broker matcheó algo →
//! muestra el `producer_service_socket` recibido.
//!
//! Configuración via env:
//! - `BRAHMAN_INIT_SOCKET` — path del socket del broker (default
//! resuelto por `card_handshake::transport`).
//! - `BRAHMAN_BROKER_PROBE_FLOW` — nombre del flow probe (default
//! `broker-health`).
//! - `BRAHMAN_BROKER_PROBE_TYPE` — type name del flow probe
//! (default `ping`).
//!
//! Usá un type name probable (ej. `monad-list:json`,
//! `event-log:tail`) para detectar productores específicos del
//! ecosistema.
#![forbid(unsafe_code)]
use std::collections::{HashSet, VecDeque};
use std::path::PathBuf;
use std::sync::Arc;
use std::time::{Duration, Instant};
use card_handshake::messages::SessionList;
use card_handshake::transport;
use card_sidecar::{
await_provider_blocking, build_consumer_card, list_matches_blocking, list_sessions_blocking,
ConsumerError,
};
use llimphi_theme::Theme;
use llimphi_ui::llimphi_layout::taffy::{
prelude::{length, percent, Dimension, FlexDirection, Size, Style},
Rect,
};
use llimphi_ui::llimphi_raster::peniko::Color;
use llimphi_ui::llimphi_text::Alignment;
use llimphi_ui::{App, Handle, Key, KeyEvent, KeyState, NamedKey, View};
use llimphi_motion::{animate, motion, Tween};
use llimphi_widget_app_header::{app_header, AppHeaderPalette};
use llimphi_widget_banner::{banner_view, BannerKind};
use llimphi_widget_context_menu::{
context_menu_view, ContextMenuItem, ContextMenuPalette, ContextMenuSpec,
};
use llimphi_widget_menubar::{
menubar_command_at, menubar_nav, menubar_overlay_animated, menubar_view, MenuBarSpec,
DEFAULT_HEIGHT as MENU_H,
};
use llimphi_widget_stat_card::{stat_card_view, StatCardPalette};
use ulid::Ulid;
use app_bus::{AppMenu, Menu, MenuItem};
const POLL_INTERVAL: Duration = Duration::from_secs(5);
const PROBE_TIMEOUT: Duration = Duration::from_secs(1);
/// Cap del buffer del timeline. Mantenemos las últimas N entries —
/// más viejo se descarta. 50 cubre ~4 minutos de actividad densa.
const TIMELINE_CAP: usize = 50;
#[derive(Clone, Debug)]
enum ProbeState {
Pending,
Down { reason: String },
UpNoProvider { flow: String },
UpWithProvider { flow: String, producer_socket: PathBuf },
}
#[derive(Clone, Debug)]
struct TimelineEntry {
at: std::time::SystemTime,
kind: card_handshake::messages::MatchEventKind,
consumer_label: String,
consumer_flow: String,
producer_label: String,
producer_flow: String,
via: chasqui_broker::MatchStrategy,
pinned: bool,
}
type MatchKey = (Ulid, String, Ulid, String);
struct Model {
theme: Theme,
socket_path: PathBuf,
flow: String,
type_name: String,
state: ProbeState,
last_probe_ms: u64,
sessions: Option<SessionList>,
last_match_keys: HashSet<MatchKey>,
timeline: VecDeque<TimelineEntry>,
/// Barra de menú principal: índice del menú raíz abierto (`None`
/// cerrado).
menu_open: Option<usize>,
/// Fila activa dentro del dropdown abierto (`usize::MAX` = ninguna).
menu_active: usize,
/// Animación de aparición del dropdown.
menu_anim: Tween<f32>,
/// Entry del timeline seleccionada (índice en `timeline`). `None`
/// si ninguna. La selección sólo habilita el menú contextual; el
/// probe es de sólo lectura.
selected: Option<usize>,
/// Menú contextual sobre una entry: `(idx, x, y)` ancla en ventana.
/// `None` cerrado.
context_menu: Option<(usize, f32, f32)>,
}
#[derive(Clone)]
enum Msg {
Tick,
ProbeResult {
state: ProbeState,
sessions: Option<SessionList>,
matches: Option<card_handshake::messages::MatchList>,
elapsed_ms: u64,
},
/// Barra de menú principal: abrir/cerrar un menú raíz (`None` cerrar).
MenuOpen(Option<usize>),
/// Comando elegido en el menú principal — se traduce al `Msg` real.
MenuCommand(String),
/// Navega la fila activa del dropdown (+1/-1).
MenuNav(i32),
/// Ejecuta el comando de la fila activa (Enter).
MenuActivate,
/// No-op: sólo fuerza re-render durante la animación del dropdown.
MenuTick,
/// Cierra cualquier menú abierto (click-fuera / Esc).
CloseMenus,
/// Cicla el tema entre presets.
CycleTheme,
/// Selecciona una entry del timeline por índice (resalta).
SelectEntry(usize),
/// Right-click en la raíz → abre el menú contextual anclado en
/// `(x, y)` de ventana sobre la entry seleccionada. Sin selección
/// es no-op.
ContextMenuOpen(f32, f32),
/// Limpia el timeline acumulado.
ClearTimeline,
}
struct Explorer;
impl App for Explorer {
type Model = Model;
type Msg = Msg;
fn title() -> &'static str {
"Brahman Broker — Probe"
}
fn initial_size() -> (u32, u32) {
(720, 480)
}
fn init(handle: &Handle<Msg>) -> Model {
let flow = std::env::var("BRAHMAN_BROKER_PROBE_FLOW")
.unwrap_or_else(|_| "broker-health".to_string());
let type_name = std::env::var("BRAHMAN_BROKER_PROBE_TYPE")
.unwrap_or_else(|_| "ping".to_string());
handle.dispatch(Msg::Tick);
handle.spawn_periodic(POLL_INTERVAL, || Msg::Tick);
Model {
theme: Theme::dark(),
socket_path: transport::default_socket_path(),
flow,
type_name,
state: ProbeState::Pending,
last_probe_ms: 0,
sessions: None,
last_match_keys: HashSet::new(),
timeline: VecDeque::new(),
menu_open: None,
menu_active: usize::MAX,
menu_anim: Tween::idle(1.0),
selected: None,
context_menu: None,
}
}
fn on_key(model: &Model, event: &KeyEvent) -> Option<Msg> {
if event.state != KeyState::Pressed {
return None;
}
if let Some(mi) = model.menu_open {
let n = app_menu().menus.len().max(1);
return match &event.key {
Key::Named(NamedKey::Escape) => Some(Msg::CloseMenus),
Key::Named(NamedKey::ArrowLeft) => Some(Msg::MenuOpen(Some((mi + n - 1) % n))),
Key::Named(NamedKey::ArrowRight) => Some(Msg::MenuOpen(Some((mi + 1) % n))),
Key::Named(NamedKey::ArrowDown) => Some(Msg::MenuNav(1)),
Key::Named(NamedKey::ArrowUp) => Some(Msg::MenuNav(-1)),
Key::Named(NamedKey::Enter) => Some(Msg::MenuActivate),
_ => None,
};
}
None
}
fn update(model: Model, msg: Msg, handle: &Handle<Msg>) -> Model {
let mut m = model;
match msg {
Msg::Tick => {
let flow = m.flow.clone();
let type_name = m.type_name.clone();
handle.spawn(move || run_probe(flow, type_name));
}
Msg::ProbeResult { state, sessions, matches, elapsed_ms } => {
m.state = state;
m.sessions = sessions;
if let Some(list) = matches {
m.diff_matches_into_timeline(&list);
}
m.last_probe_ms = elapsed_ms;
// Si la selección quedó fuera de rango tras el refresh
// del timeline, la descartamos.
if m.selected.map(|i| i >= m.timeline.len()).unwrap_or(false) {
m.selected = None;
m.context_menu = None;
}
}
Msg::MenuOpen(which) => {
m.menu_open = which;
// Abrir un menú raíz cierra cualquier contextual.
m.context_menu = None;
m.menu_active = usize::MAX;
if which.is_some() {
m.menu_anim = Tween::new(0.0, 1.0, motion::FAST, motion::ease_out_cubic);
animate(handle, motion::FAST, || Msg::MenuTick);
}
}
Msg::MenuNav(dir) => {
if let Some(mi) = m.menu_open {
let menu = app_menu();
m.menu_active = menubar_nav(&menu, mi, m.menu_active, dir);
}
}
Msg::MenuActivate => {
if let Some(mi) = m.menu_open {
let menu = app_menu();
if let Some(cmd) = menubar_command_at(&menu, mi, m.menu_active) {
m.menu_open = None;
return handle_menu_command(m, &cmd, handle);
}
}
}
Msg::MenuTick => {}
Msg::CloseMenus => {
m.menu_open = None;
m.menu_active = usize::MAX;
m.context_menu = None;
}
Msg::MenuCommand(cmd) => {
m.menu_open = None;
m.menu_active = usize::MAX;
return handle_menu_command(m, &cmd, handle);
}
Msg::CycleTheme => {
m.theme = Theme::next_after(m.theme.name);
}
Msg::SelectEntry(i) => {
m.selected = Some(i);
m.context_menu = None;
}
Msg::ContextMenuOpen(x, y) => {
// Sólo si hay una entry seleccionada válida.
if let Some(i) = m.selected.filter(|i| *i < m.timeline.len()) {
m.menu_open = None;
m.context_menu = Some((i, x, y));
}
}
Msg::ClearTimeline => {
m.timeline.clear();
m.selected = None;
m.context_menu = None;
}
}
m
}
fn view(model: &Model) -> View<Msg> {
let theme = &model.theme;
let menu = app_menu();
let menubar = menubar_view(&menubar_spec(&menu, model, theme));
let header_palette = AppHeaderPalette::from_theme(theme);
let stat_palette = StatCardPalette::from_theme(theme);
// Acentos por estado.
let accent_up = Color::from_rgba8(0xa3, 0xbe, 0x8c, 0xff);
let accent_partial = Color::from_rgba8(0xeb, 0xcb, 0x8b, 0xff);
let accent_down = Color::from_rgba8(0xbf, 0x61, 0x6a, 0xff);
let accent_pending = Color::from_rgba8(0x6a, 0x72, 0x80, 0xff);
let header_text = format!(
"Probe: {} · flow: {}/{} · reload {} ms",
model.socket_path.display(),
model.flow,
model.type_name,
model.last_probe_ms,
);
let header = app_header::<Msg>(header_text, vec![], &header_palette);
let mut body_children: Vec<View<Msg>> = Vec::new();
// Banner permanente con el estado actual.
match &model.state {
ProbeState::Pending => {}
ProbeState::Down { reason } => body_children.push(banner_view::<Msg>(
BannerKind::Error,
format!("Broker DOWN — {reason}"),
)),
ProbeState::UpNoProvider { .. } => body_children.push(banner_view::<Msg>(
BannerKind::Warning,
"Broker UP, sin provider para el flow".to_string(),
)),
ProbeState::UpWithProvider { .. } => body_children.push(banner_view::<Msg>(
BannerKind::Success,
"Broker UP, provider matcheado".to_string(),
)),
}
// State card.
let (state_accent, state_value, state_descr) = state_card_params(
&model.state,
accent_up,
accent_partial,
accent_down,
accent_pending,
);
body_children.push(stat_card_view::<Msg>(
"Estado",
state_value,
&state_descr,
state_accent,
&[],
&stat_palette,
));
// Sessions card.
let sessions_items: Vec<String> = model
.sessions
.as_ref()
.map(|list| {
let mut entries: Vec<_> = list.entries.iter().collect();
entries.sort_by_key(|e| e.session);
entries
.iter()
.map(|e| {
format!(
"{} · in:[{}] out:[{}]{}",
e.label,
e.inputs.join(","),
e.outputs.join(","),
if e.conscious { " (wit)" } else { "" }
)
})
.collect()
})
.unwrap_or_default();
let sessions_count_value = model
.sessions
.as_ref()
.map(|l| l.entries.len().to_string())
.unwrap_or_else(|| "—".into());
let sessions_descr = match &model.sessions {
None => "lista no disponible (broker DOWN o pendiente)".to_string(),
Some(l) if l.entries.is_empty() => {
"sin sesiones registradas en el broker".into()
}
Some(_) => "labels visibles + flows in/out · (wit) = consciente".into(),
};
body_children.push(stat_card_view::<Msg>(
"Sesiones activas",
sessions_count_value,
&sessions_descr,
accent_up,
&sessions_items,
&stat_palette,
));
// Timeline card de cabecera (contador + ayuda); las entries
// van debajo como filas seleccionables (click selecciona,
// right-click en la raíz abre el contextual).
let timeline_value = model.timeline.len().to_string();
let timeline_descr = if model.timeline.is_empty() {
"esperando primer match…".to_string()
} else {
"click selecciona · right-click = menú · cap 50 entries".to_string()
};
body_children.push(stat_card_view::<Msg>(
"Timeline de matches",
timeline_value,
&timeline_descr,
accent_partial,
&[],
&stat_palette,
));
for (i, e) in model.timeline.iter().take(20).enumerate() {
let selected = model.selected == Some(i);
let mut row = View::new(Style {
size: Size {
width: percent(1.0_f32),
height: length(18.0_f32),
},
padding: Rect {
left: length(8.0_f32),
right: length(8.0_f32),
top: length(0.0_f32),
bottom: length(0.0_f32),
},
..Default::default()
})
.text_aligned(
format_timeline_entry(e),
11.0,
theme.fg_text,
Alignment::Start,
)
.on_click(Msg::SelectEntry(i));
if selected {
row = row.fill(theme.bg_selected);
}
body_children.push(row);
}
let body = View::new(Style {
flex_direction: FlexDirection::Column,
size: Size {
width: percent(1.0_f32),
height: Dimension::auto(),
},
flex_grow: 1.0,
padding: Rect {
left: length(16.0_f32),
right: length(16.0_f32),
top: length(12.0_f32),
bottom: length(16.0_f32),
},
gap: Size {
width: length(0.0_f32),
height: length(8.0_f32),
},
..Default::default()
})
.fill(theme.bg_app)
.children(body_children);
View::new(Style {
flex_direction: FlexDirection::Column,
size: Size {
width: percent(1.0_f32),
height: percent(1.0_f32),
},
..Default::default()
})
.fill(theme.bg_app)
// Right-click en la raíz (origen 0,0 ⇒ local == ventana) abre el
// menú contextual sobre la entry seleccionada.
.on_right_click_at(|x, y, _w, _h| Some(Msg::ContextMenuOpen(x, y)))
.children(vec![menubar, header, body])
}
fn view_overlay(model: &Model) -> Option<View<Msg>> {
// El menú contextual de la entry tiene prioridad si está abierto.
if let Some((idx, x, y)) = model.context_menu {
let label = model
.timeline
.get(idx)
.map(format_timeline_entry)
.unwrap_or_else(|| "Entry".to_string());
let viewport = viewport_of(model);
// Acciones reales del probe (sólo lectura): refrescar el
// probe y limpiar el timeline. No inventamos edición.
let items = vec![
ContextMenuItem::action("Refrescar probe"),
ContextMenuItem::action("Limpiar timeline"),
];
let on_pick: Arc<dyn Fn(usize) -> Msg + Send + Sync> =
Arc::new(move |i: usize| match i {
0 => Msg::Tick,
_ => Msg::ClearTimeline,
});
return Some(context_menu_view(ContextMenuSpec {
anchor: (x, y),
viewport,
header: Some(label),
items,
active: usize::MAX,
on_pick,
on_dismiss: Msg::CloseMenus,
palette: ContextMenuPalette::from_theme(&model.theme),
}));
}
// Si no, el dropdown del menú principal.
let menu = app_menu();
menubar_overlay_animated(
&menubar_spec(&menu, model, &model.theme),
model.menu_active,
model.menu_anim.value(),
)
}
}
/// Viewport para clampear overlays: el probe no trackea el tamaño de
/// ventana, así que usamos `initial_size()`.
fn viewport_of(_model: &Model) -> (f32, f32) {
let (w, h) = Explorer::initial_size();
(w as f32, h as f32)
}
/// Arma el `MenuBarSpec` compartido por `menubar_view` y `menubar_overlay`.
fn menubar_spec<'a>(
menu: &'a AppMenu,
model: &Model,
theme: &'a Theme,
) -> MenuBarSpec<'a, Msg> {
MenuBarSpec {
menu,
open: model.menu_open,
theme,
viewport: viewport_of(model),
height: MENU_H,
on_open: Arc::new(Msg::MenuOpen),
on_command: Arc::new(|c: &str| Msg::MenuCommand(c.to_string())),
}
}
/// El menú principal del probe. Archivo / Ver / Ayuda — sólo comandos
/// que mapean a acciones reales (refrescar probe, limpiar timeline,
/// reconectar, tema). Sin "Editar": el probe no tiene campos de texto
/// editables.
fn app_menu() -> AppMenu {
AppMenu::new()
.menu(
Menu::new("Archivo")
.item(MenuItem::new("Refrescar probe", "file.refresh").shortcut("Ctrl+R"))
.item(MenuItem::new("Limpiar timeline", "file.clear"))
.item(MenuItem::new("Salir", "file.quit").shortcut("Ctrl+Q").separated()),
)
.menu(
Menu::new("Ver")
.item(MenuItem::new("Reconectar", "view.reconnect"))
.item(MenuItem::new("Cambiar tema", "view.theme").separated()),
)
.menu(Menu::new("Ayuda").item(MenuItem::new("Acerca de", "help.about")))
}
/// Traduce un command id del menú principal al `Msg`/efecto real.
fn handle_menu_command(model: Model, cmd: &str, handle: &Handle<Msg>) -> Model {
match cmd {
// Reconectar == re-disparar el probe; el ProbeResult refresca
// estado/sesiones/matches.
"file.refresh" | "view.reconnect" => {
handle.dispatch(Msg::Tick);
model
}
"file.clear" => {
handle.dispatch(Msg::ClearTimeline);
model
}
"file.quit" => std::process::exit(0),
"view.theme" => {
handle.dispatch(Msg::CycleTheme);
model
}
// "help.about" y desconocidos: no-op (sin diálogo todavía).
_ => model,
}
}
impl Model {
fn diff_matches_into_timeline(
&mut self,
list: &card_handshake::messages::MatchList,
) {
let (new_entries, new_keys) = diff_matches(&self.last_match_keys, list);
for entry in new_entries {
self.push_timeline(entry);
}
self.last_match_keys = new_keys;
}
fn push_timeline(&mut self, entry: TimelineEntry) {
self.timeline.push_front(entry);
while self.timeline.len() > TIMELINE_CAP {
self.timeline.pop_back();
}
}
}
fn state_card_params(
state: &ProbeState,
accent_up: Color,
accent_partial: Color,
accent_down: Color,
accent_pending: Color,
) -> (Color, String, String) {
match state {
ProbeState::Pending => (
accent_pending,
"PENDING".into(),
"esperando primer probe…".into(),
),
ProbeState::Down { reason } => (
accent_down,
"DOWN".into(),
format!("connect failed: {reason}"),
),
ProbeState::UpNoProvider { flow } => (
accent_partial,
"UP / NO PROVIDER".into(),
format!("broker reachable; sin productor para flow `{flow}`"),
),
ProbeState::UpWithProvider { flow, producer_socket } => (
accent_up,
"UP / PROVIDER".into(),
format!(
"flow `{flow}` matcheado en producer socket: {}",
producer_socket.display()
),
),
}
}
fn run_probe(flow: String, type_name: String) -> Msg {
let started = Instant::now();
let card = build_consumer_card("brahman-broker-explorer-llimphi", flow.clone(), type_name);
let result = await_provider_blocking(card, PROBE_TIMEOUT);
let new_state = match result {
Ok(socket) => ProbeState::UpWithProvider {
flow: flow.clone(),
producer_socket: socket,
},
Err(ConsumerError::NoProvider { .. }) => ProbeState::UpNoProvider { flow: flow.clone() },
Err(e) => ProbeState::Down {
reason: e.to_string(),
},
};
let (sessions, matches) = match &new_state {
ProbeState::Down { .. } | ProbeState::Pending => (None, None),
_ => (
list_sessions_blocking("brahman-broker-explorer-llimphi").ok(),
list_matches_blocking("brahman-broker-explorer-llimphi").ok(),
),
};
Msg::ProbeResult {
state: new_state,
sessions,
matches,
elapsed_ms: started.elapsed().as_millis() as u64,
}
}
/// Diff puro entre snapshots de matches. Devuelve la lista de
/// entries nuevas (Available + Lost) en orden Available-primero, y
/// el set actualizado de keys.
fn diff_matches(
last_keys: &HashSet<MatchKey>,
list: &card_handshake::messages::MatchList,
) -> (Vec<TimelineEntry>, HashSet<MatchKey>) {
use card_handshake::messages::MatchEventKind;
let now = std::time::SystemTime::now();
let current_keys: HashSet<MatchKey> = list
.matches
.iter()
.map(|m| {
(
m.consumer.session,
m.consumer.flow_name.clone(),
m.producer.session,
m.producer.flow_name.clone(),
)
})
.collect();
let mut entries = Vec::new();
for m in &list.matches {
let key = (
m.consumer.session,
m.consumer.flow_name.clone(),
m.producer.session,
m.producer.flow_name.clone(),
);
if !last_keys.contains(&key) {
entries.push(TimelineEntry {
at: now,
kind: MatchEventKind::Available,
consumer_label: m.consumer_label.clone(),
consumer_flow: m.consumer.flow_name.clone(),
producer_label: m.producer_label.clone(),
producer_flow: m.producer.flow_name.clone(),
via: m.via,
pinned: m.pinned,
});
}
}
for key in last_keys.iter() {
if !current_keys.contains(key) {
entries.push(TimelineEntry {
at: now,
kind: MatchEventKind::Lost,
consumer_label: String::new(),
consumer_flow: key.1.clone(),
producer_label: String::new(),
producer_flow: key.3.clone(),
via: chasqui_broker::MatchStrategy::Exact,
pinned: false,
});
}
}
(entries, current_keys)
}
fn format_timeline_entry(e: &TimelineEntry) -> String {
use card_handshake::messages::MatchEventKind;
let secs_today = e
.at
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_secs() % 86_400)
.unwrap_or(0);
let h = secs_today / 3600;
let m = (secs_today % 3600) / 60;
let s = secs_today % 60;
let kind = match e.kind {
MatchEventKind::Available => "+",
MatchEventKind::Lost => "-",
};
let pinned = if e.pinned { " (pinned)" } else { "" };
match e.kind {
MatchEventKind::Available => format!(
"{:02}:{:02}:{:02} {} {}.{} ← {}.{} [{:?}]{}",
h,
m,
s,
kind,
e.consumer_label,
e.consumer_flow,
e.producer_label,
e.producer_flow,
e.via,
pinned,
),
MatchEventKind::Lost => format!(
"{:02}:{:02}:{:02} {} ?.{} ← ?.{} (lost)",
h, m, s, kind, e.consumer_flow, e.producer_flow,
),
}
}
fn main() {
llimphi_ui::run::<Explorer>();
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn pending_is_default_state_at_boot() {
let s = ProbeState::Pending;
assert!(matches!(s, ProbeState::Pending));
}
#[test]
fn poll_and_probe_constants_are_sane() {
assert!(PROBE_TIMEOUT < POLL_INTERVAL);
assert!(POLL_INTERVAL >= Duration::from_secs(2));
}
fn synth_match(
consumer_label: &str,
consumer_flow: &str,
producer_label: &str,
producer_flow: &str,
) -> chasqui_broker::Match {
use card_core::TypeRef;
use chasqui_broker::{Endpoint, Match, MatchStrategy};
Match {
consumer: Endpoint {
session: Ulid::new(),
flow_name: consumer_flow.into(),
},
consumer_label: consumer_label.into(),
producer: Endpoint {
session: Ulid::new(),
flow_name: producer_flow.into(),
},
producer_label: producer_label.into(),
ty: TypeRef::Primitive { name: "json".into() },
via: MatchStrategy::Exact,
pinned: false,
}
}
#[test]
fn diff_matches_first_snapshot_marks_everything_available() {
use card_handshake::messages::{MatchEventKind, MatchList};
let list = MatchList {
matches: vec![
synth_match("a", "x", "b", "x"),
synth_match("c", "y", "d", "y"),
],
};
let last = HashSet::new();
let (entries, keys) = diff_matches(&last, &list);
assert_eq!(entries.len(), 2);
assert!(entries
.iter()
.all(|e| matches!(e.kind, MatchEventKind::Available)));
assert_eq!(keys.len(), 2);
}
#[test]
fn diff_matches_emits_lost_when_match_disappears() {
use card_handshake::messages::{MatchEventKind, MatchList};
let m = synth_match("a", "x", "b", "x");
let prev_key = (
m.consumer.session,
m.consumer.flow_name.clone(),
m.producer.session,
m.producer.flow_name.clone(),
);
let last: HashSet<_> = std::iter::once(prev_key).collect();
let list = MatchList { matches: vec![] };
let (entries, keys) = diff_matches(&last, &list);
assert_eq!(entries.len(), 1);
assert!(matches!(entries[0].kind, MatchEventKind::Lost));
assert_eq!(entries[0].consumer_flow, "x");
assert_eq!(entries[0].producer_flow, "x");
assert!(keys.is_empty());
}
#[test]
fn diff_matches_no_change_emits_nothing() {
use card_handshake::messages::MatchList;
let m = synth_match("a", "x", "b", "x");
let key = (
m.consumer.session,
m.consumer.flow_name.clone(),
m.producer.session,
m.producer.flow_name.clone(),
);
let last: HashSet<_> = std::iter::once(key.clone()).collect();
let list = MatchList {
matches: vec![m.clone()],
};
let (entries, keys) = diff_matches(&last, &list);
assert!(entries.is_empty(), "match unchanged → no events");
assert_eq!(keys.len(), 1);
assert!(keys.contains(&key));
}
}
02_ruway/chasqui/chasqui-broker/Cargo.toml
+15
View File
@@ -0,0 +1,15 @@
[package]
name = "chasqui-broker"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Brahman — broker de tipos: empareja productores↔consumidores por TypeRef con matching híbrido (exact + structural) y prioridad."
[dependencies]
card-core = { workspace = true }
serde = { workspace = true }
thiserror = { workspace = true }
ulid = { workspace = true }
02_ruway/chasqui/chasqui-broker/LEEME.md
+16
View File
@@ -0,0 +1,16 @@
# chasqui-broker
> Binario del broker de [chasqui](../README.md).
Loop async sobre `tokio` que rutea mensajes entre topics. TCP/Unix configurables. Persistencia opt-in por topic en `$XDG_DATA_HOME/chasqui/`.
## Uso
```sh
cargo run --release -p chasqui-broker -- --listen 127.0.0.1:7711
```
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous-real`](../chasqui-nous-real/README.md)
- `tokio`, `clap`
02_ruway/chasqui/chasqui-broker/README.md
+16
View File
@@ -0,0 +1,16 @@
# chasqui-broker
> Broker binary of [chasqui](../README.md).
Async loop on `tokio` that routes messages between topics. Configurable TCP/Unix. Opt-in persistence per topic at `$XDG_DATA_HOME/chasqui/`.
## Usage
```sh
cargo run --release -p chasqui-broker -- --listen 127.0.0.1:7711
```
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous-real`](../chasqui-nous-real/README.md)
- `tokio`, `clap`
02_ruway/chasqui/chasqui-broker/src/lib.rs
+995
View File
@@ -0,0 +1,995 @@
//! `brahman-broker` — empareja productores y consumidores por tipo de flujo.
//!
//! El broker indexa [`card_core::Card`]s registradas por `SessionId` y,
//! para cada `flow.input` de un consumidor, busca el `flow.output`
//! compatible de mejor calidad entre los demás. Tres ejes:
//!
//! 1. **Estrategia de matching** ([`MatchStrategy`]):
//! - `Exact`: igualdad estricta de [`card_core::TypeRef`].
//! - `Structural`: misma forma (mismo `package` + `name` para Wit;
//! ignora `interface`).
//! - `ExactThenStructural`: prefiere exact; cae en structural si no hay.
//!
//! 2. **Override `pin_to`**: si el consumidor declara `pin_to = "label"`,
//! el broker prefiere productores cuya Card tenga ese `label` (siempre
//! que el tipo siga matcheando). Si la pista no resuelve, cae en
//! matching por tipo normal.
//!
//! 3. **Prioridad**: empate de tipo se resuelve por
//! [`card_core::Priority`] del productor (mayor gana). Empate de
//! prioridad se resuelve lexicográficamente por `label` (estable y
//! determinista).
//!
//! El broker es **stateless w.r.t. routes**: cada `find_producer_for` o
//! `all_matches` se calcula bajo demanda. La única persistencia es el
//! índice de Cards registradas. Esto permite re-evaluar matches cuando
//! cambia el set sin invalidar caches.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
use std::collections::BTreeMap;
use std::path::PathBuf;
use card_core::{
Card, CardKind, CardReference, ContextBias, DataFacet, Flow, Lifecycle, Priority, TypeRef,
WitInterface,
};
use serde::{Deserialize, Serialize};
use ulid::Ulid;
/// Identificador de sesión emitido por el handshake. Idéntico al usado por
/// `brahman-handshake` (no es un re-export para evitar la dependencia).
pub type SessionId = Ulid;
/// Estrategia de matching de tipos.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum MatchStrategy {
/// Igualdad estricta de `TypeRef`.
Exact,
/// Misma forma: para `Wit`, mismo `package` + `name`; para
/// `Primitive`, mismo `name`.
Structural,
/// Híbrido: intenta `Exact` primero; si no matchea, `Structural`.
/// Reporta cuál estrategia ganó en [`Match::via`].
#[default]
ExactThenStructural,
}
/// Configuración del broker.
#[derive(Debug, Clone, Default)]
pub struct BrokerConfig {
pub strategy: MatchStrategy,
/// Contexto operativo activo. Si una Card declara un
/// `priority_contexts.<this>`, ese bias se aplica durante el match.
/// `None` = sin biases per-contexto, sólo se usa lo estático.
pub current_context: Option<String>,
}
/// Vista mínima de una Card que el broker necesita.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct BrokeredCard {
pub session: SessionId,
pub label: String,
pub lifecycle: Lifecycle,
pub priority: Priority,
pub inputs: Vec<Flow>,
pub outputs: Vec<Flow>,
/// Interfaz WIT extraída si el módulo es "consciente"; `None` si agnóstico.
pub wit: Option<WitInterface>,
/// Biases per-contexto, propagados desde `Card.priority_contexts`.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub priority_contexts: BTreeMap<String, ContextBias>,
/// Naturaleza de la entidad. Diferencia procesos (Ente) de
/// agrupaciones de datos (Data — p. ej. Mónadas Nouser).
#[serde(default)]
pub kind: CardKind,
/// Faceta de datos cuando `kind != Ente`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub data: Option<DataFacet>,
/// Socket de servicio (data plane) si lo declara la Card.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub service_socket: Option<PathBuf>,
/// Referencias a otras Cards (relaciones declaradas por esta Card).
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub references: Vec<CardReference>,
}
impl BrokeredCard {
fn from_card(session: SessionId, card: &Card, wit: Option<WitInterface>) -> Self {
Self {
session,
label: card.label.clone(),
lifecycle: card.lifecycle,
priority: card.priority,
inputs: card.flow.input.clone(),
outputs: card.flow.output.clone(),
wit,
priority_contexts: card.priority_contexts.clone(),
kind: card.kind,
data: card.data.clone(),
service_socket: card.service_socket.clone(),
references: card.references.clone(),
}
}
}
/// Punto extremo de un flujo: qué sesión + nombre del flow dentro de su Card.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct Endpoint {
pub session: SessionId,
pub flow_name: String,
}
/// Match concreto entre un consumidor y un productor.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Match {
pub consumer: Endpoint,
pub consumer_label: String,
pub producer: Endpoint,
pub producer_label: String,
/// Tipo del flow (lado consumidor — lado productor coincide en
/// estrategia Exact, puede diferir en `interface` en Structural).
pub ty: TypeRef,
/// Estrategia que efectivamente matcheó.
pub via: MatchStrategy,
/// `true` si el match fue resuelto por `pin_to` y no por type-search.
pub pinned: bool,
}
// =====================================================================
// Broker
// =====================================================================
/// El broker. Registra Cards por SessionId, computa matches bajo demanda.
#[derive(Debug, Clone, Default)]
pub struct Broker {
cards: BTreeMap<SessionId, BrokeredCard>,
config: BrokerConfig,
}
impl Broker {
pub fn new(config: BrokerConfig) -> Self {
Self {
cards: BTreeMap::new(),
config,
}
}
/// 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<WitInterface>,
) -> Option<BrokeredCard> {
self.cards
.insert(session, BrokeredCard::from_card(session, card, wit))
}
/// Quita una Card por sesión.
pub fn unregister(&mut self, session: SessionId) -> Option<BrokeredCard> {
self.cards.remove(&session)
}
/// Cardinalidad del registro.
pub fn len(&self) -> usize {
self.cards.len()
}
pub fn is_empty(&self) -> bool {
self.cards.is_empty()
}
/// Iterador sobre las sesiones registradas.
pub fn sessions(&self) -> impl Iterator<Item = SessionId> + '_ {
self.cards.keys().copied()
}
/// Iterador sobre las Cards registradas (vista compartida).
pub fn cards(&self) -> impl Iterator<Item = &BrokeredCard> + '_ {
self.cards.values()
}
/// Busca el mejor productor para un input específico de un consumidor.
///
/// Algoritmo:
/// 1. Resuelve el flow input en el consumidor.
/// 2. Si tiene `pin_to`, prefiere productores con ese `label` que
/// matcheen el tipo (cualquier estrategia configurada).
/// 3. Si no hay pin_to o la pista falló, escanea todos los outputs
/// de las otras Cards. Filtra por compatibilidad de tipo.
/// 4. Ordena por (priority desc, label asc) y devuelve el primero.
pub fn find_producer_for(&self, consumer: SessionId, input_name: &str) -> Option<Match> {
let cons = self.cards.get(&consumer)?;
let input = cons.inputs.iter().find(|f| f.name == input_name)?;
// pin_to efectivo: bias del contexto activo (si la Card declara
// override consumer-side) > pin_to estático del Flow.
let context_pin = self
.context_bias(cons)
.and_then(|b| b.pin_to.as_deref());
let effective_pin = context_pin.or(input.pin_to.as_deref());
if let Some(pin) = effective_pin {
for prod in self.cards.values() {
if prod.session == consumer || prod.label != pin {
continue;
}
for out in &prod.outputs {
if let Some(via) = self.types_match(&input.ty, &out.ty) {
return Some(self.make_match(cons, prod, input, out, via, true));
}
}
}
// Fall through: pin no resuelto, type-search general.
}
let mut candidates: Vec<(&BrokeredCard, &Flow, MatchStrategy)> = Vec::new();
for prod in self.cards.values() {
if prod.session == consumer {
continue;
}
for out in &prod.outputs {
if let Some(via) = self.types_match(&input.ty, &out.ty) {
candidates.push((prod, out, via));
}
}
}
// Sort por (effective priority desc, label asc). El bias del
// contexto puede subir o bajar la priority del productor.
candidates.sort_by(|(a, _, _), (b, _, _)| {
self.effective_priority(b)
.cmp(&self.effective_priority(a))
.then_with(|| a.label.cmp(&b.label))
});
let (prod, out, via) = candidates.into_iter().next()?;
Some(self.make_match(cons, prod, input, out, via, false))
}
/// Devuelve el `ContextBias` que aplica a este Card en el contexto
/// activo (si lo hay).
fn context_bias<'a>(&self, card: &'a BrokeredCard) -> Option<&'a ContextBias> {
self.config
.current_context
.as_ref()
.and_then(|ctx| card.priority_contexts.get(ctx))
}
/// Priority efectiva del Card como productor, considerando el bias
/// del contexto activo. El offset se clampa a `[Low=0, Critical=3]`.
fn effective_priority(&self, card: &BrokeredCard) -> i16 {
let base = priority_value(card.priority);
let offset = self
.context_bias(card)
.map(|b| b.priority_offset as i16)
.unwrap_or(0);
(base + offset).clamp(0, 3)
}
/// Calcula todos los matches consumer→producer en el set actual.
/// Útil para introspección o para que el Admin emita rutas en lote.
pub fn all_matches(&self) -> Vec<Match> {
let mut out = Vec::new();
for cons in self.cards.values() {
for input in &cons.inputs {
if let Some(m) = self.find_producer_for(cons.session, &input.name) {
out.push(m);
}
}
}
out
}
fn types_match(&self, consumer_ty: &TypeRef, producer_ty: &TypeRef) -> Option<MatchStrategy> {
match self.config.strategy {
MatchStrategy::Exact => exact_match(consumer_ty, producer_ty).then_some(MatchStrategy::Exact),
MatchStrategy::Structural => {
structural_match(consumer_ty, producer_ty).then_some(MatchStrategy::Structural)
}
MatchStrategy::ExactThenStructural => {
if exact_match(consumer_ty, producer_ty) {
Some(MatchStrategy::Exact)
} else if structural_match(consumer_ty, producer_ty) {
Some(MatchStrategy::Structural)
} else {
None
}
}
}
}
fn make_match(
&self,
cons: &BrokeredCard,
prod: &BrokeredCard,
input: &Flow,
output: &Flow,
via: MatchStrategy,
pinned: bool,
) -> Match {
Match {
consumer: Endpoint {
session: cons.session,
flow_name: input.name.clone(),
},
consumer_label: cons.label.clone(),
producer: Endpoint {
session: prod.session,
flow_name: output.name.clone(),
},
producer_label: prod.label.clone(),
ty: input.ty.clone(),
via,
pinned,
}
}
}
// =====================================================================
// Predicados de matching (libres, testeables aislados)
// =====================================================================
fn priority_value(p: Priority) -> i16 {
match p {
Priority::Low => 0,
Priority::Normal => 1,
Priority::High => 2,
Priority::Critical => 3,
}
}
fn exact_match(a: &TypeRef, b: &TypeRef) -> bool {
a == b
}
fn structural_match(a: &TypeRef, b: &TypeRef) -> bool {
match (a, b) {
(TypeRef::Primitive { name: na }, TypeRef::Primitive { name: nb }) => na == nb,
(
TypeRef::Wit {
package: pa, name: na, ..
},
TypeRef::Wit {
package: pb, name: nb, ..
},
) => pa == pb && na == nb,
_ => false,
}
}
// =====================================================================
// Tests
// =====================================================================
#[cfg(test)]
mod tests {
use super::*;
use card_core::{Card, Flows, Payload, Supervision, CARD_SCHEMA_VERSION};
fn card(label: &str, priority: Priority, flows: Flows) -> Card {
Card {
schema_version: CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: label.into(),
payload: Payload::Virtual,
supervision: Supervision::OneShot,
priority,
flow: flows,
..Default::default()
}
}
fn prim(name: &str) -> TypeRef {
TypeRef::Primitive { name: name.into() }
}
fn wit(pkg: &str, iface: Option<&str>, name: &str) -> TypeRef {
TypeRef::Wit {
package: pkg.into(),
interface: iface.map(|s| s.into()),
name: name.into(),
}
}
fn flow(name: &str, ty: TypeRef, pin: Option<&str>) -> Flow {
Flow {
name: name.into(),
ty,
pin_to: pin.map(|s| s.into()),
}
}
#[test]
fn exact_match_same_typeref() {
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::Exact,
current_context: None,
});
let producer = card(
"dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("results", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("query", prim("string"), None)],
output: vec![],
},
);
let s_prod = Ulid::new();
let s_cons = Ulid::new();
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");
assert_eq!(m.via, MatchStrategy::Exact);
assert!(!m.pinned);
}
#[test]
fn structural_ignores_interface() {
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::Structural,
current_context: None,
});
let producer = card(
"dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow(
"out",
wit("brahman:dht", Some("v1"), "entity-result"),
None,
)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow(
"in",
wit("brahman:dht", Some("v2"), "entity-result"),
None,
)],
output: vec![],
},
);
let s_prod = Ulid::new();
let s_cons = Ulid::new();
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);
}
#[test]
fn exact_strategy_rejects_interface_mismatch() {
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::Exact,
current_context: None,
});
let producer = card(
"dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow(
"out",
wit("brahman:dht", Some("v1"), "entity-result"),
None,
)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow(
"in",
wit("brahman:dht", Some("v2"), "entity-result"),
None,
)],
output: vec![],
},
);
b.register(Ulid::new(), &producer, None);
let s_cons = Ulid::new();
b.register(s_cons, &consumer, None);
assert!(b.find_producer_for(s_cons, "in").is_none());
}
#[test]
fn exact_then_structural_prefers_exact() {
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::ExactThenStructural,
current_context: None,
});
// Productor 1: match estructural (interface diferente)
let p_struct = card(
"dht-cache",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow(
"out",
wit("brahman:dht", Some("v2"), "entity-result"),
None,
)],
},
);
// Productor 2: match exact (interface igual)
let p_exact = card(
"dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow(
"out",
wit("brahman:dht", Some("v1"), "entity-result"),
None,
)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow(
"in",
wit("brahman:dht", Some("v1"), "entity-result"),
None,
)],
output: vec![],
},
);
b.register(Ulid::new(), &p_struct, None);
b.register(Ulid::new(), &p_exact, None);
let s_cons = Ulid::new();
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.
assert_eq!(m.producer_label, "dht");
assert_eq!(m.via, MatchStrategy::Exact);
}
#[test]
fn pin_to_overrides_type_search() {
let mut b = Broker::new(BrokerConfig::default());
// Dos productores que producen el mismo tipo.
let p1 = card(
"dht-prod",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let p2 = card(
"dht-test",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), Some("dht-test"))],
output: vec![],
},
);
b.register(Ulid::new(), &p1, None);
b.register(Ulid::new(), &p2, None);
let s_cons = Ulid::new();
b.register(s_cons, &consumer, None);
let m = b.find_producer_for(s_cons, "in").expect("match");
assert_eq!(m.producer_label, "dht-test");
assert!(m.pinned);
}
#[test]
fn pin_to_unresolvable_falls_back_to_type_match() {
let mut b = Broker::new(BrokerConfig::default());
let p = card(
"real-dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), Some("nonexistent"))],
output: vec![],
},
);
b.register(Ulid::new(), &p, None);
let s_cons = Ulid::new();
b.register(s_cons, &consumer, None);
let m = b.find_producer_for(s_cons, "in").expect("match");
assert_eq!(m.producer_label, "real-dht");
assert!(!m.pinned);
}
#[test]
fn priority_breaks_ties() {
let mut b = Broker::new(BrokerConfig::default());
let p_low = card(
"z-dht",
Priority::Low,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let p_high = card(
"a-dht",
Priority::High,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), None)],
output: vec![],
},
);
b.register(Ulid::new(), &p_low, None);
b.register(Ulid::new(), &p_high, None);
let s_cons = Ulid::new();
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
}
#[test]
fn label_alpha_breaks_priority_ties() {
let mut b = Broker::new(BrokerConfig::default());
let p1 = card(
"z-dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let p2 = card(
"a-dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), None)],
output: vec![],
},
);
b.register(Ulid::new(), &p1, None);
b.register(Ulid::new(), &p2, None);
let s_cons = Ulid::new();
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
}
#[test]
fn unregister_removes_producer() {
let mut b = Broker::new(BrokerConfig::default());
let p = card(
"dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), None)],
output: vec![],
},
);
let s_p = Ulid::new();
b.register(s_p, &p, None);
let s_c = Ulid::new();
b.register(s_c, &consumer, None);
assert!(b.find_producer_for(s_c, "in").is_some());
b.unregister(s_p);
assert!(b.find_producer_for(s_c, "in").is_none());
}
#[test]
fn no_self_loops() {
let mut b = Broker::new(BrokerConfig::default());
let same = card(
"echo",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), None)],
output: vec![flow("out", prim("string"), None)],
},
);
let s = Ulid::new();
b.register(s, &same, None);
// Solo una Card registrada — no hay otra que produzca string.
assert!(b.find_producer_for(s, "in").is_none());
}
#[test]
fn all_matches_lists_pairs() {
let mut b = Broker::new(BrokerConfig::default());
let dht = card(
"dht",
Priority::Normal,
Flows {
input: vec![flow("query", prim("string"), None)],
output: vec![flow("results", prim("bytes"), None)],
},
);
let ui = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("data", prim("bytes"), None)],
output: vec![flow("user-input", prim("string"), None)],
},
);
b.register(Ulid::new(), &dht, None);
b.register(Ulid::new(), &ui, None);
let matches = b.all_matches();
assert_eq!(matches.len(), 2);
// dht.query ← ui.user-input y ui.data ← dht.results
let pairs: Vec<_> = matches
.iter()
.map(|m| (m.consumer_label.as_str(), m.producer_label.as_str()))
.collect();
assert!(pairs.contains(&("dht", "ui")));
assert!(pairs.contains(&("ui", "dht")));
}
// ===========================================================
// Priority contexts
// ===========================================================
#[test]
fn context_priority_offset_lifts_producer_above_alphabetic_winner() {
// Sin contexto, "a-prod" gana contra "b-prod" (alfabético).
// En contexto "test", b-prod tiene offset +1 → debería ganar.
let mut a_prod = card(
"a-prod",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
a_prod.priority_contexts = std::collections::BTreeMap::new(); // explícito vacío
let mut b_prod = card(
"b-prod",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
b_prod.priority_contexts.insert(
"test".into(),
ContextBias {
pin_to: None,
priority_offset: 1,
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), None)],
output: vec![],
},
);
let s_cons = Ulid::new();
// Caso 1: sin contexto → a-prod gana (alfabético).
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::default(),
current_context: None,
});
b.register(Ulid::new(), &a_prod, None);
b.register(Ulid::new(), &b_prod, None);
b.register(s_cons, &consumer, None);
let m = b.find_producer_for(s_cons, "in").unwrap();
assert_eq!(m.producer_label, "a-prod");
// Caso 2: contexto "test" → b-prod gana por offset +1.
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::default(),
current_context: Some("test".into()),
});
b.register(Ulid::new(), &a_prod, None);
b.register(Ulid::new(), &b_prod, None);
b.register(s_cons, &consumer, None);
let m = b.find_producer_for(s_cons, "in").unwrap();
assert_eq!(m.producer_label, "b-prod");
}
#[test]
fn context_pin_to_overrides_static_pin() {
// Consumer pinea estático a "real-dht", pero en contexto "test"
// declara override a "mock-dht".
let real = card(
"real-dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let mock = card(
"mock-dht",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let mut consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), Some("real-dht"))],
output: vec![],
},
);
consumer.priority_contexts.insert(
"test".into(),
ContextBias {
pin_to: Some("mock-dht".into()),
priority_offset: 0,
},
);
let s_cons = Ulid::new();
// Caso 1: sin contexto → static pin gana ("real-dht").
let mut b = Broker::new(BrokerConfig::default());
b.register(Ulid::new(), &real, None);
b.register(Ulid::new(), &mock, None);
b.register(s_cons, &consumer, None);
let m = b.find_producer_for(s_cons, "in").unwrap();
assert_eq!(m.producer_label, "real-dht");
assert!(m.pinned);
// Caso 2: contexto "test" → context override gana ("mock-dht").
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::default(),
current_context: Some("test".into()),
});
b.register(Ulid::new(), &real, None);
b.register(Ulid::new(), &mock, None);
b.register(s_cons, &consumer, None);
let m = b.find_producer_for(s_cons, "in").unwrap();
assert_eq!(m.producer_label, "mock-dht");
assert!(m.pinned);
}
#[test]
fn unknown_context_no_op() {
// Si la Card declara biases para "test" pero el broker está en
// "prod", los biases no aplican.
let mut b_prod = card(
"b-prod",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
b_prod.priority_contexts.insert(
"test".into(),
ContextBias {
pin_to: None,
priority_offset: 5,
},
);
let a_prod = card(
"a-prod",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
let consumer = card(
"ui",
Priority::Normal,
Flows {
input: vec![flow("in", prim("string"), None)],
output: vec![],
},
);
let mut b = Broker::new(BrokerConfig {
strategy: MatchStrategy::default(),
current_context: Some("prod".into()),
});
let s_cons = Ulid::new();
b.register(Ulid::new(), &a_prod, None);
b.register(Ulid::new(), &b_prod, None);
b.register(s_cons, &consumer, None);
// En contexto "prod" sin biases declarados, gana por alfabético.
let m = b.find_producer_for(s_cons, "in").unwrap();
assert_eq!(m.producer_label, "a-prod");
}
#[test]
fn priority_offset_clamps_to_critical() {
// Offset enorme no debe hacer overflow ni saltar fuera del rango.
let mut prod = card(
"p",
Priority::Normal,
Flows {
input: vec![],
output: vec![flow("out", prim("string"), None)],
},
);
prod.priority_contexts.insert(
"x".into(),
ContextBias {
pin_to: None,
priority_offset: 100,
},
);
let b = Broker::new(BrokerConfig {
strategy: MatchStrategy::default(),
current_context: Some("x".into()),
});
let bc = BrokeredCard::from_card(Ulid::new(), &prod, None);
// effective_priority debe estar clampada a 3 (Critical), no 101.
assert_eq!(b.effective_priority(&bc), 3);
}
}
02_ruway/chasqui/chasqui-card/Cargo.toml
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "chasqui-card"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Nouser — manifiesto de Mónada (agrupación semántica de archivos). Espejo de card-core pero para datos."
[dependencies]
card-core = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
ulid = { workspace = true }
02_ruway/chasqui/chasqui-card/LEEME.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-card
> Card escritorio (estado del broker) de [chasqui](../README.md).
Stat-card que muestra: broker activo (sí/no), topics activos, mensajes/s. Refresca cada 2s. Usa [`llimphi-widget-stat-card`](../../llimphi/widgets/stat-card/README.md).
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous`](../chasqui-nous/README.md)
- [`llimphi-widget-stat-card`](../../llimphi/widgets/stat-card/README.md)
02_ruway/chasqui/chasqui-card/README.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-card
> Desktop card (broker status) of [chasqui](../README.md).
Stat-card showing: broker alive (yes/no), active topics, messages/sec. Refreshes every 2s. Uses [`llimphi-widget-stat-card`](../../llimphi/widgets/stat-card/README.md).
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous`](../chasqui-nous/README.md)
- [`llimphi-widget-stat-card`](../../llimphi/widgets/stat-card/README.md)
02_ruway/chasqui/chasqui-card/src/lib.rs
+431
View File
@@ -0,0 +1,431 @@
//! `chasqui-card` — manifiesto de Mónada.
//!
//! Una **Mónada** es una agrupación semántica de archivos: el archivo
//! físico no se mueve, pero su pertenencia se modela por un objeto
//! ([`MonadManifest`]) con identidad propia, métricas y un "lente" de
//! visualización. La idea hereda el espíritu de la Tarjeta de
//! Presentación de Brahman (`brahman-card::Card`): un manifiesto
//! tipado, validado y serializable que define qué es la entidad y
//! cómo el sistema debe interactuar con ella.
//!
//! Diferencia con `brahman-card::Card`:
//!
//! | brahman::Card | chasqui::MonadManifest |
//! |-------------------------------------|-------------------------------|
//! | Describe una **entidad runtime** | Describe una **agrupación** |
//! | Tiene `payload`/`soma`/`supervision`| No tiene proceso detrás |
//! | Vive durante una sesión | Vive en una DB persistente |
//! | Fluye por handshake/postcard | Fluye por queries del backend |
//!
//! Este crate sólo define los tipos. La lógica de scan, cluster,
//! attraction vive en `chasqui-core`.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
use std::collections::{BTreeMap, BTreeSet};
use std::path::PathBuf;
use serde::{Deserialize, Serialize};
use thiserror::Error;
use ulid::Ulid;
// Re-export para consumidores
pub use ::ulid;
pub mod query;
/// Versión del esquema del manifiesto. Bump al cambiar el schema.
pub const MONAD_SCHEMA_VERSION: u16 = 1;
/// Identificador opaco de un archivo registrado en la DB.
pub type FileId = Ulid;
/// Identificador opaco de una Mónada.
pub type MonadId = Ulid;
// =====================================================================
// FileEntry — el archivo como dato indexado
// =====================================================================
/// Registro físico de un archivo en la DB. Es la unidad atómica que
/// pertenece a (potencialmente varias) Mónadas.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FileEntry {
pub id: FileId,
pub path: PathBuf,
/// Hash de contenido (blake3) — sólo se computa si el archivo es
/// chico o el usuario lo pidió. `None` por default en Phase 0.
#[serde(default)]
pub content_hash: Option<[u8; 32]>,
/// Tamaño en bytes.
pub size: u64,
/// `mtime` como ms desde UNIX_EPOCH.
pub mtime_ms: u64,
/// Extensión normalizada en lowercase, sin punto. `None` si no tiene.
#[serde(default)]
pub extension: Option<String>,
}
// =====================================================================
// Lens — la "vista" preferida de una Mónada
// =====================================================================
/// Lente de visualización dominante. La UI (nahual) elige cómo renderizar
/// los miembros de una Mónada según este hint.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Lens {
/// Grid genérico: thumbnail + nombre + meta.
#[default]
Grid,
/// Editor de código con highlighting (rs, py, ts, ...).
Code,
/// Galería de imágenes (png, jpg, svg, ...).
Gallery,
/// Vista tabular (csv, sqlite, ...).
Database,
/// Texto renderizado (md, rst, txt).
Markdown,
/// Árbol jerárquico (cuando la Mónada es estructural).
Tree,
}
// =====================================================================
// MonadManifest — la Tarjeta de Presentación de la Mónada
// =====================================================================
/// Manifiesto de una Mónada. Equivalente conceptual a la Tarjeta de
/// Presentación de Brahman, pero para una agrupación de datos.
///
/// Se serializa a JSON/TOML para persistencia y debugging; es el
/// "ADN" que la UI lee para saber cómo presentar la Mónada sin tocar
/// el disco.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MonadManifest {
/// Versión del esquema. Bump = romper compatibilidad de DB.
pub schema_version: u16,
/// Identificador opaco. ULID — orderable por tiempo de creación.
pub id: MonadId,
/// Mónada de la que ésta fue derivada (split, merge), si aplica.
#[serde(default)]
pub lineage: Option<MonadId>,
/// Nombre humano corto (1-4 palabras, generado por reglas o por Nous).
pub label: String,
/// Resumen de propósito (1-2 oraciones). Generado por Nous cuando
/// la masa de la Mónada justifica la consulta.
#[serde(default)]
pub summary: String,
/// Centroide vectorial (embedding promedio de los miembros). Vacío
/// en Phase 0 (sin embeddings); se llena cuando entran las
/// pseudo-embeddings o el modelo real.
#[serde(default)]
pub centroid: Vec<f32>,
/// Identificador del modelo que produjo `centroid`. Si está set, los
/// consumidores deben verificar coincidencia antes de comparar vía
/// cosine similarity con embeddings recientes; al cambiar de modelo
/// (mock-pseudo-32d → real-fastembed-384d, etc.) los centroides
/// previos quedan inválidos por dimensión y semántica.
/// `None` = legacy (centroides sin tag, pre-versioning).
#[serde(default)]
pub centroid_model: Option<String>,
/// Identidad estable derivada del origen de los miembros. Para
/// Mónadas creadas por `cluster::by_directory`, es el path
/// canónico del directorio padre. Permite que la hidratación
/// reuse el mismo ULID across re-scans (mismo path_hint = misma
/// identidad, aunque cambien los miembros internamente).
/// `None` para Mónadas creadas por estrategias que no se anclan a
/// un origen físico.
#[serde(default)]
pub path_hint: Option<String>,
/// Tokens dominantes: extensiones, palabras clave, etc.
/// 5-10 elementos típicamente.
#[serde(default)]
pub keywords: Vec<String>,
/// Cantidad de miembros (== `members.len()`). Cacheado para evitar
/// el cost de leer la lista cada vez.
pub cardinality: u32,
/// Métrica de dispersión interna [0.0, 1.0]:
/// - 0.0: todos los miembros son muy similares (Mónada coherente).
/// - 1.0: miembros muy heterogéneos (sugerencia: bifurcar).
///
/// Calculada como entropía de Shannon normalizada sobre las
/// extensiones de los miembros.
#[serde(default)]
pub entropy: f32,
/// Lente preferido para visualización en la UI.
#[serde(default)]
pub dominant_lens: Lens,
/// Archivos anclados manualmente: NO se mueven en re-clustering
/// automático. El usuario "fija" estos miembros.
#[serde(default)]
pub pins: BTreeSet<FileId>,
/// IDs de archivos miembros (incluye pins).
pub members: BTreeSet<FileId>,
/// Unix ms de creación de la Mónada.
pub created_at_ms: u64,
/// Unix ms de la última actualización (re-cluster, re-name, ...).
pub updated_at_ms: u64,
/// Forward-compat: campos JSON desconocidos preservados.
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub extensions: BTreeMap<String, serde_json::Value>,
}
// =====================================================================
// Errores y validación
// =====================================================================
#[derive(Debug, Error)]
pub enum MonadError {
#[error("schema mismatch: got {got}, expected {expected}")]
SchemaMismatch { got: u16, expected: u16 },
#[error("label vacío")]
EmptyLabel,
#[error("label demasiado largo: {0} bytes (max 256)")]
LabelTooLong(usize),
#[error("entropía fuera de [0,1]: {0}")]
InvalidEntropy(f32),
#[error("Monad sin miembros y sin pins")]
Empty,
#[error("cardinalidad declarada {declared} ≠ members.len() {actual}")]
CardinalityMismatch { declared: u32, actual: u32 },
#[error("JSON inválido: {0}")]
Json(#[from] serde_json::Error),
}
impl MonadManifest {
/// Constructor con defaults razonables. `id` y timestamps se
/// generan; resto vacío.
pub fn new(label: impl Into<String>) -> Self {
let now_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
Self {
schema_version: MONAD_SCHEMA_VERSION,
id: Ulid::new(),
lineage: None,
label: label.into(),
summary: String::new(),
centroid: Vec::new(),
centroid_model: None,
path_hint: None,
keywords: Vec::new(),
cardinality: 0,
entropy: 0.0,
dominant_lens: Lens::default(),
pins: BTreeSet::new(),
members: BTreeSet::new(),
created_at_ms: now_ms,
updated_at_ms: now_ms,
extensions: BTreeMap::new(),
}
}
/// Validación semántica.
pub fn validate(&self) -> Result<(), MonadError> {
if self.schema_version != MONAD_SCHEMA_VERSION {
return Err(MonadError::SchemaMismatch {
got: self.schema_version,
expected: MONAD_SCHEMA_VERSION,
});
}
if self.label.trim().is_empty() {
return Err(MonadError::EmptyLabel);
}
if self.label.len() > 256 {
return Err(MonadError::LabelTooLong(self.label.len()));
}
if !(0.0..=1.0).contains(&self.entropy) {
return Err(MonadError::InvalidEntropy(self.entropy));
}
if self.members.is_empty() && self.pins.is_empty() {
return Err(MonadError::Empty);
}
let actual = self.members.len() as u32;
if self.cardinality != actual {
return Err(MonadError::CardinalityMismatch {
declared: self.cardinality,
actual,
});
}
Ok(())
}
/// Serializa a JSON pretty.
pub fn to_json_pretty(&self) -> Result<String, MonadError> {
Ok(serde_json::to_string_pretty(self)?)
}
/// Deserializa desde JSON y valida.
pub fn from_json(src: &str) -> Result<Self, MonadError> {
let m: Self = serde_json::from_str(src)?;
m.validate()?;
Ok(m)
}
/// Recalcula `cardinality` y `updated_at_ms` desde `members`.
/// Usar tras mutaciones del set de miembros.
pub fn touch(&mut self) {
self.cardinality = self.members.len() as u32;
self.updated_at_ms = std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
}
/// Proyecta el `MonadManifest` a la `card_core::Card` que viaja
/// por el protocolo. La Card resultante:
///
/// - hereda `id` y `label` del manifiesto (ULID estable).
/// - `kind = CardKind::Data` (se distingue de un Ente).
/// - `payload = Virtual`, `supervision = Delegate`,
/// `lifecycle = Daemon` — placeholder semántico: la Mónada no se
/// "ejecuta", el daemon dueño la mantiene viva.
/// - `data = Some(DataFacet { ... })` con summary, keywords,
/// centroide, member_count, dispersión y un hint de presentación
/// derivado del `dominant_lens`.
/// - Los miembros completos NO viajan en la Card — se consultan al
/// daemon dueño bajo demanda. Lo que viaja es metadata liviana
/// apta para el wire postcard.
pub fn to_brahman_card(&self) -> card_core::Card {
use card_core::{
Card, CardKind, DataFacet, Lifecycle, Payload, Priority, Supervision,
};
let presentation_hint = match self.dominant_lens {
Lens::Grid => "grid",
Lens::Code => "code",
Lens::Gallery => "gallery",
Lens::Database => "database",
Lens::Markdown => "markdown",
Lens::Tree => "tree",
}
.to_string();
Card {
schema_version: card_core::CARD_SCHEMA_VERSION,
id: self.id,
label: self.label.clone(),
payload: Payload::Virtual,
supervision: Supervision::Delegate,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
kind: CardKind::Data,
data: Some(DataFacet {
summary: self.summary.clone(),
keywords: self.keywords.clone(),
centroid: self.centroid.clone(),
member_count: self.cardinality,
dispersion: self.entropy,
presentation_hint,
}),
..Default::default()
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn validates_minimal() {
let mut m = MonadManifest::new("test");
m.members.insert(Ulid::new());
m.touch();
m.validate().expect("debe validar");
}
#[test]
fn empty_label_rejected() {
let mut m = MonadManifest::new("x");
m.label = String::new();
m.members.insert(Ulid::new());
m.touch();
assert!(matches!(m.validate(), Err(MonadError::EmptyLabel)));
}
#[test]
fn entropy_out_of_range_rejected() {
let mut m = MonadManifest::new("x");
m.members.insert(Ulid::new());
m.entropy = 1.5;
m.touch();
assert!(matches!(m.validate(), Err(MonadError::InvalidEntropy(_))));
}
#[test]
fn empty_members_rejected() {
let m = MonadManifest::new("x");
assert!(matches!(m.validate(), Err(MonadError::Empty)));
}
#[test]
fn cardinality_mismatch_caught() {
let mut m = MonadManifest::new("x");
m.members.insert(Ulid::new());
// No llamamos touch — cardinality queda en 0 con 1 miembro.
assert!(matches!(
m.validate(),
Err(MonadError::CardinalityMismatch { .. })
));
}
#[test]
fn projects_to_brahman_card() {
let mut m = MonadManifest::new("test-monad");
m.summary = "monad de prueba".into();
m.keywords = vec!["rs".into(), "toml".into()];
m.dominant_lens = Lens::Code;
m.entropy = 0.42;
m.members.insert(Ulid::new());
m.members.insert(Ulid::new());
m.members.insert(Ulid::new());
m.touch();
let bc = m.to_brahman_card();
assert_eq!(bc.id, m.id);
assert_eq!(bc.label, "test-monad");
assert_eq!(bc.kind, card_core::CardKind::Data);
let data = bc.data.expect("data facet presente");
assert_eq!(data.summary, "monad de prueba");
assert_eq!(data.keywords, vec!["rs".to_string(), "toml".to_string()]);
assert_eq!(data.member_count, 3);
assert!((data.dispersion - 0.42).abs() < 1e-6);
assert_eq!(data.presentation_hint, "code");
}
#[test]
fn json_roundtrip() {
let mut m = MonadManifest::new("test-monad");
m.members.insert(Ulid::new());
m.members.insert(Ulid::new());
m.keywords = vec!["rs".into(), "toml".into()];
m.summary = "test summary".into();
m.dominant_lens = Lens::Code;
m.touch();
let s = m.to_json_pretty().unwrap();
let m2 = MonadManifest::from_json(&s).unwrap();
assert_eq!(m2.label, m.label);
assert_eq!(m2.cardinality, 2);
assert_eq!(m2.dominant_lens, Lens::Code);
assert_eq!(m2.keywords, m.keywords);
}
}
02_ruway/chasqui/chasqui-card/src/query.rs
+385
View File
@@ -0,0 +1,385 @@
//! Wire types para consultar al daemon `chasqui` por sus Mónadas.
//!
//! El daemon expone un Unix socket (cuyo path se publica en
//! `Card.service_socket` y se descubre vía broker MatchEvent). Cada
//! conexión es single-shot: una request JSON terminada en `\n`,
//! una response JSON terminada en `\n`, cierre.
//!
//! Mismo patrón que `chasqui-nous` (mock/real ↔ chasqui-core), reusado
//! ahora para que la UI (`chasqui-explorer`) descubra y consulte al
//! daemon sin hardcodear sockets ni pasar por brahman-admin.
//!
//! ## Contrato
//!
//! ```text
//! C → S: {"kind":"list_monads"}\n
//! S → C: {"engine":{...},"monads":[...]}\n
//! ```
//!
//! En caso de error:
//!
//! ```text
//! S → C: {"error":"unsupported kind"}\n
//! ```
use serde::{Deserialize, Serialize};
use thiserror::Error;
use ulid::Ulid;
use crate::{FileEntry, FileId, Lens, MonadId, MonadManifest};
// =====================================================================
// Constants compartidos para el broker brahman
// =====================================================================
/// Nombre del flow output del daemon (input del consumer/explorer).
pub const FLOW_MONAD_LIST: &str = "monad-list";
/// Tipo del flow: el wire es JSON, así que el TypeRef es `primitive::json`.
pub const FLOW_TYPE_NAME: &str = "json";
// =====================================================================
// Wire request
// =====================================================================
/// Request al daemon. El wire es JSON line-delimited (un objeto + `\n`
/// por conexión).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum QueryRequest {
/// Lista todas las Mónadas vivas del daemon, junto con metadata
/// del engine. Pensado para que la UI haga snapshot polling.
ListMonads,
/// Resuelve los **archivos miembros** de una Mónada concreta. La vista
/// de `ListMonads` es slim (sin member set) para que el poll sea liviano;
/// cuando la UI despliega una Mónada en el navegador pide sus archivos
/// con esto, bajo demanda. nouser sigue siendo la fuente autoritativa de
/// qué archivos componen la Mónada (no el filesystem por su cuenta).
ResolveMonad {
/// La Mónada cuyos miembros se quieren.
id: MonadId,
},
}
// =====================================================================
// Wire response
// =====================================================================
/// Response a `ListMonads`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ListMonadsResponse {
/// Datos del engine (la Card que es "dueña" de las Mónadas).
pub engine: EngineInfo,
/// Mónadas vivas en este momento. Vista slim sin centroide ni
/// member set para que el wire sea liviano: una Mónada con 50k
/// archivos no debe transmitir 50k ULIDs cada poll.
pub monads: Vec<MonadView>,
}
/// Identidad del engine (Card kind=Ente que owns las Mónadas).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EngineInfo {
pub id: Ulid,
pub label: String,
/// Path del directorio que el daemon está observando. `None` si
/// el daemon corre sin watcher.
#[serde(default)]
pub watching: Option<String>,
}
/// Vista slim de una Mónada — los campos que la UI necesita para
/// renderizar una card sin pull del centroide ni del member set.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MonadView {
pub id: MonadId,
pub label: String,
#[serde(default)]
pub summary: String,
#[serde(default)]
pub keywords: Vec<String>,
pub cardinality: u32,
#[serde(default)]
pub entropy: f32,
#[serde(default)]
pub dominant_lens: Lens,
#[serde(default)]
pub path_hint: Option<String>,
#[serde(default)]
pub centroid_model: Option<String>,
}
impl MonadView {
/// Proyecta un MonadManifest completo a su vista slim para wire.
pub fn from_manifest(m: &MonadManifest) -> Self {
Self {
id: m.id,
label: m.label.clone(),
summary: m.summary.clone(),
keywords: m.keywords.clone(),
cardinality: m.cardinality,
entropy: m.entropy,
dominant_lens: m.dominant_lens,
path_hint: m.path_hint.clone(),
centroid_model: m.centroid_model.clone(),
}
}
}
/// Vista slim de un archivo miembro de una Mónada — lo que la UI necesita
/// para pintar una fila en el navegador. Omite el `content_hash` (32 bytes
/// que no se muestran) para que el wire sea liviano.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FileView {
pub id: FileId,
/// Ruta del archivo, como string (el wire es JSON; `PathBuf` viajaría
/// igual pero string es explícito y portable).
pub path: String,
#[serde(default)]
pub size: u64,
#[serde(default)]
pub extension: Option<String>,
#[serde(default)]
pub mtime_ms: u64,
}
impl FileView {
/// Proyecta un [`FileEntry`] a su vista slim para wire.
pub fn from_entry(f: &FileEntry) -> Self {
Self {
id: f.id,
path: f.path.display().to_string(),
size: f.size,
extension: f.extension.clone(),
mtime_ms: f.mtime_ms,
}
}
}
/// Response a [`QueryRequest::ResolveMonad`]: los archivos miembros de la
/// Mónada pedida. `members` vacío si la Mónada no existe (o no tiene
/// miembros resolubles) — el daemon no distingue, igual que `resolve_members`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ResolveMonadResponse {
/// La Mónada consultada (eco del request, para que la UI confirme).
pub monad: MonadId,
/// Sus archivos miembros, en el orden que el daemon los entrega.
pub members: Vec<FileView>,
}
/// Error de protocolo retornado en lugar de la response normal.
#[derive(Debug, Clone, Serialize, Deserialize, Error)]
#[error("chasqui-engine: {error}")]
pub struct ErrorResponse {
pub error: String,
}
// =====================================================================
// Transport
// =====================================================================
pub mod transport {
use std::path::PathBuf;
/// Variable de entorno para sobreescribir la ruta del socket del
/// daemon (útil para tests / multi-daemon).
pub const SOCKET_ENV: &str = "NOUSER_ENGINE_SOCKET";
/// Nombre por defecto del socket.
pub const SOCKET_NAME: &str = "chasqui-engine.sock";
/// Ruta canónica al socket del daemon. Honra `NOUSER_ENGINE_SOCKET`
/// si está set, sino arma sobre `$XDG_RUNTIME_DIR` (con fallback
/// `$TMPDIR`).
pub fn default_socket_path() -> PathBuf {
if let Ok(p) = std::env::var(SOCKET_ENV) {
return PathBuf::from(p);
}
std::env::var_os("XDG_RUNTIME_DIR")
.map(PathBuf::from)
.unwrap_or_else(std::env::temp_dir)
.join(SOCKET_NAME)
}
}
// =====================================================================
// Cliente blocking — vive con los wire types para que un consumer
// (UI, CLI, otro módulo) pueda hablar con el daemon importando sólo
// `chasqui-card`, sin arrastrar `chasqui-core` (notify/walkdir/sled/blake3).
// =====================================================================
/// Cliente síncrono para el query socket del daemon. Sólo Unix (el
/// resto del ecosistema brahman es Unix-only de facto).
#[cfg(unix)]
pub mod client {
use std::io::{BufRead, BufReader, Write};
use std::os::unix::net::UnixStream;
use std::path::Path;
use std::time::Duration;
use serde::de::DeserializeOwned;
use super::{ErrorResponse, ListMonadsResponse, MonadId, QueryRequest, ResolveMonadResponse};
#[derive(Debug, thiserror::Error)]
pub enum QueryError {
#[error("conectar a {path}: {source}")]
Connect {
path: std::path::PathBuf,
#[source]
source: std::io::Error,
},
#[error("I/O: {0}")]
Io(#[from] std::io::Error),
#[error("serializacion: {0}")]
Serde(#[from] serde_json::Error),
#[error("daemon: {0}")]
Daemon(String),
#[error("response vacía del daemon")]
Empty,
}
/// Envía un `QueryRequest` al daemon en `socket` y deserializa la
/// response al tipo `R`. `timeout` se aplica al read y al write. Si el
/// daemon responde un `ErrorResponse`, se devuelve `QueryError::Daemon`.
fn request<R: DeserializeOwned>(
socket: &Path,
req: &QueryRequest,
timeout: Duration,
) -> Result<R, QueryError> {
let mut stream = UnixStream::connect(socket).map_err(|e| QueryError::Connect {
path: socket.to_path_buf(),
source: e,
})?;
stream.set_read_timeout(Some(timeout))?;
stream.set_write_timeout(Some(timeout))?;
let line = serde_json::to_string(req)?;
stream.write_all(line.as_bytes())?;
stream.write_all(b"\n")?;
stream.flush()?;
let mut reader = BufReader::new(stream);
let mut response = String::new();
let n = reader.read_line(&mut response)?;
if n == 0 {
return Err(QueryError::Empty);
}
if let Ok(resp) = serde_json::from_str::<R>(response.trim()) {
return Ok(resp);
}
let err: ErrorResponse = serde_json::from_str(response.trim())?;
Err(QueryError::Daemon(err.error))
}
/// Envía `ListMonads` al daemon en `socket` y devuelve la response.
/// `timeout` se aplica tanto al read como al write del stream.
pub fn list_monads(
socket: &Path,
timeout: Duration,
) -> Result<ListMonadsResponse, QueryError> {
request(socket, &QueryRequest::ListMonads, timeout)
}
/// Pide los archivos miembros de la Mónada `id` al daemon en `socket`.
/// Para el nivel de archivos del navegador: la lista slim de `list_monads`
/// no los trae, se resuelven bajo demanda al desplegar una Mónada.
pub fn resolve_monad(
socket: &Path,
id: MonadId,
timeout: Duration,
) -> Result<ResolveMonadResponse, QueryError> {
request(socket, &QueryRequest::ResolveMonad { id }, timeout)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn request_roundtrips_json_with_tag() {
let req = QueryRequest::ListMonads;
let s = serde_json::to_string(&req).unwrap();
assert_eq!(s, r#"{"kind":"list_monads"}"#);
let back: QueryRequest = serde_json::from_str(&s).unwrap();
assert_eq!(back, req);
}
#[test]
fn resolve_monad_request_roundtrips_with_id() {
let id = Ulid::new();
let req = QueryRequest::ResolveMonad { id };
let s = serde_json::to_string(&req).unwrap();
assert!(s.contains(r#""kind":"resolve_monad""#), "{s}");
let back: QueryRequest = serde_json::from_str(&s).unwrap();
assert_eq!(back, req);
}
#[test]
fn resolve_monad_response_roundtrip() {
use crate::FileEntry;
use std::path::PathBuf;
let entry = FileEntry {
id: Ulid::new(),
path: PathBuf::from("/proj/src/lib.rs"),
content_hash: None,
size: 1234,
mtime_ms: 42,
extension: Some("rs".into()),
};
let resp = ResolveMonadResponse {
monad: Ulid::new(),
members: vec![FileView::from_entry(&entry)],
};
let s = serde_json::to_string(&resp).unwrap();
let back: ResolveMonadResponse = serde_json::from_str(&s).unwrap();
assert_eq!(back.members.len(), 1);
assert_eq!(back.members[0].path, "/proj/src/lib.rs");
assert_eq!(back.members[0].extension.as_deref(), Some("rs"));
assert_eq!(back.members[0].size, 1234);
}
#[test]
fn response_roundtrip_preserves_view() {
let m = MonadManifest::new("x/src");
let view = MonadView::from_manifest(&m);
let resp = ListMonadsResponse {
engine: EngineInfo {
id: Ulid::new(),
label: "brahman.nouser_engine".into(),
watching: Some("/tmp/x".into()),
},
monads: vec![view.clone()],
};
let s = serde_json::to_string(&resp).unwrap();
let back: ListMonadsResponse = serde_json::from_str(&s).unwrap();
assert_eq!(back.monads.len(), 1);
assert_eq!(back.monads[0].label, view.label);
assert_eq!(back.engine.label, "brahman.nouser_engine");
}
#[test]
fn view_is_slim_no_centroid_no_members() {
// Construimos una Mónada con centroid + members "pesados",
// proyectamos a view, verificamos que esos campos no viajan.
let mut m = MonadManifest::new("test");
m.centroid = vec![0.1; 384]; // peso "real-fastembed"
m.members.insert(Ulid::new());
m.members.insert(Ulid::new());
m.cardinality = 2;
let view = MonadView::from_manifest(&m);
let s = serde_json::to_string(&view).unwrap();
// Chequeo con `:` para distinguir el field "centroid" del
// field "centroid_model" (que sí es metadata liviana y debe ir).
assert!(
!s.contains("\"centroid\":"),
"MonadView no debe serializar el vector centroid: {s}"
);
assert!(
!s.contains("\"members\":"),
"MonadView no debe serializar members: {s}"
);
assert!(s.contains("\"cardinality\":2"), "cardinality sí va: {s}");
}
}
02_ruway/chasqui/chasqui-core/Cargo.toml
+33
View File
@@ -0,0 +1,33 @@
[package]
name = "chasqui-core"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Nouser — explorador de Mónadas: scanner, clustering determinista, DB en memoria."
[dependencies]
chasqui-card = { path = "../chasqui-card" }
chasqui-nous = { path = "../chasqui-nous" }
shuma-discern = { workspace = true }
card-core = { workspace = true }
card-handshake = { path = "../card-handshake" }
card-sidecar = { path = "../card-sidecar" }
blake3 = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
sled = { workspace = true }
thiserror = { workspace = true }
tokio = { workspace = true }
ulid = { workspace = true }
walkdir = "2"
notify = { workspace = true }
[dev-dependencies]
tempfile = { workspace = true }
[[bin]]
name = "chasqui"
path = "src/bin/nouser.rs"
02_ruway/chasqui/chasqui-core/LEEME.md
+9
View File
@@ -0,0 +1,9 @@
# chasqui-core
> Tipos compartidos de [chasqui](../README.md): `Topic`, `Message`, `Schema`, `Subscription`.
Núcleo sin transport, sin red. Lo importan tanto el broker como cualquier cliente.
## Deps
- `serde`, `uuid`
02_ruway/chasqui/chasqui-core/README.md
+9
View File
@@ -0,0 +1,9 @@
# chasqui-core
> Shared types of [chasqui](../README.md): `Topic`, `Message`, `Schema`, `Subscription`.
Core without transport or network. Imported by both the broker and any client.
## Deps
- `serde`, `uuid`
02_ruway/chasqui/chasqui-core/src/bin/nouser.rs
+795
View File
@@ -0,0 +1,795 @@
//! `chasqui` CLI — explorador de Mónadas.
//!
//! Subcomandos:
//!
//! - `scan <dir>` recorre `dir` y muestra las Mónadas detectadas.
//! - `show <dir> <id?>` scan + detalles de la Mónada con prefijo de ID.
//! - `json <dir>` scan + dump JSON con los manifests.
//!
//! Phase A: in-memory, sin persistencia, sin brahman sidecar. La
//! sesión termina y todo se descarta. Phase B agrega persistencia y
//! presencia ante el Init.
use std::path::PathBuf;
use std::process::ExitCode;
use chasqui_core::{
cluster, db, embed,
scanner::{self, ScanConfig},
};
fn main() -> ExitCode {
let args: Vec<String> = std::env::args().collect();
let prog = args.first().cloned().unwrap_or_else(|| "chasqui".into());
let sub = match args.get(1).map(String::as_str) {
Some(s) => s,
None => {
print_usage(&prog);
return ExitCode::from(2);
}
};
let rest = &args[2..];
let result = match sub {
"scan" => cmd_scan(rest),
"show" => cmd_show(rest),
"json" => cmd_json(rest),
"daemon" => cmd_daemon(rest),
"attract" => cmd_attract(rest),
"--help" | "-h" | "help" => {
print_usage(&prog);
return ExitCode::SUCCESS;
}
other => {
eprintln!("chasqui: comando desconocido '{other}'");
print_usage(&prog);
return ExitCode::from(2);
}
};
match result {
Ok(()) => ExitCode::SUCCESS,
Err(e) => {
eprintln!("chasqui: {e}");
ExitCode::from(1)
}
}
}
fn print_usage(prog: &str) {
eprintln!("uso: {prog} <comando> [args]");
eprintln!();
eprintln!("comandos:");
eprintln!(" scan <dir> recorre un directorio y lista las Mónadas detectadas");
eprintln!(" show <dir> <prefix> scan + detalle de la Mónada cuyo ID empieza con <prefix>");
eprintln!(" json <dir> scan + dump JSON de todos los manifests");
eprintln!(" daemon <dir> scan + sidecarea cada Mónada al Init brahman");
eprintln!(" attract <dir> <file> dado un archivo, qué Mónada del scan lo atrae más");
eprintln!();
eprintln!("env:");
eprintln!(" NOUSER_MIN_FILES mínimo de archivos por Mónada (default: 3)");
eprintln!(" NOUSER_DB_PATH si está set, abre sled en esa ruta (persistencia)");
eprintln!(" BRAHMAN_INIT_SOCKET socket del Init (heredado de brahman-handshake)");
}
type Cmd = Result<(), Box<dyn std::error::Error>>;
fn min_files() -> usize {
std::env::var("NOUSER_MIN_FILES")
.ok()
.and_then(|s| s.parse().ok())
.unwrap_or(cluster::DEFAULT_MIN_FILES_PER_MONAD)
}
fn require_dir(args: &[String]) -> Result<PathBuf, Box<dyn std::error::Error>> {
let dir = args.first().ok_or("falta argumento <dir>")?;
Ok(PathBuf::from(dir))
}
fn run_scan(dir: &PathBuf) -> Result<(db::MonadDb, usize), Box<dyn std::error::Error>> {
let files = scanner::scan_directory(dir, &ScanConfig::default())?;
let n_files = files.len();
let monads = cluster::by_directory(&files, min_files());
let mut db = open_db()?;
db.ingest_files(files);
db.replace_monads(monads);
Ok((db, n_files))
}
/// Abre el `MonadDb`. Si `NOUSER_DB_PATH` está set, persistencia sled;
/// si no, store en memoria.
fn open_db() -> Result<db::MonadDb, Box<dyn std::error::Error>> {
if let Ok(path) = std::env::var("NOUSER_DB_PATH") {
Ok(db::MonadDb::open(&path)?)
} else {
Ok(db::MonadDb::new())
}
}
fn cmd_scan(args: &[String]) -> Cmd {
let dir = require_dir(args)?;
let (db, n_files) = run_scan(&dir)?;
println!(
"scan: {} archivos en {}, {} mónadas (min_files={})",
n_files,
dir.display(),
db.monad_count(),
min_files()
);
if db.monad_count() == 0 {
println!(" (ninguna Mónada — bajá NOUSER_MIN_FILES o apuntá a un dir con más archivos)");
return Ok(());
}
println!();
for m in db.monads() {
let id_short = format!("{}", m.id);
let id_short = &id_short[..8];
println!(
" [{}] {:30} card={} ent={:.2} lens={:?}",
id_short, m.label, m.cardinality, m.entropy, m.dominant_lens,
);
if !m.keywords.is_empty() {
println!(" keywords: {}", m.keywords.join(", "));
}
}
Ok(())
}
fn cmd_show(args: &[String]) -> Cmd {
let dir = require_dir(args)?;
let prefix = args.get(1).ok_or("falta argumento <prefix>")?;
let (db, _) = run_scan(&dir)?;
let m = db
.monads()
.find(|m| m.id.to_string().starts_with(prefix))
.ok_or_else(|| format!("ninguna Mónada con prefijo '{prefix}'"))?;
println!("Monad {}", m.id);
println!(" label: {}", m.label);
println!(" summary: {}", m.summary);
println!(" cardinality: {}", m.cardinality);
println!(" entropy: {:.4}", m.entropy);
println!(" lens: {:?}", m.dominant_lens);
println!(" keywords: {}", m.keywords.join(", "));
println!(" members ({}):", m.members.len());
for f in db.resolve_members(m.id) {
println!(
" {:>10} bytes {}",
f.size,
f.path.display()
);
}
Ok(())
}
fn cmd_json(args: &[String]) -> Cmd {
let dir = require_dir(args)?;
let (db, _) = run_scan(&dir)?;
let manifests: Vec<_> = db.monads().cloned().collect();
println!("{}", serde_json::to_string_pretty(&manifests)?);
Ok(())
}
fn cmd_daemon(args: &[String]) -> Cmd {
let dir = require_dir(args)?;
let pool = std::sync::Arc::new(
card_sidecar::SidecarPool::new().map_err(|e| format!("crear pool: {e}"))?,
);
// 1. Decidir el path del query socket ANTES de armar el engine
// Card (porque viaja como service_socket en la Card).
let query_socket = chasqui_card::query::transport::default_socket_path();
// 2. Engine como Ente. Declara service_socket + flow.output para
// que el broker pueda emitir MatchEvent::Available a consumers
// interesados en `flow.input = monad-list:json`.
let engine_card = build_engine_card(query_socket.clone());
let engine_id = engine_card.id;
let engine_label = engine_card.label.clone();
eprintln!(
"chasqui daemon: publicando engine '{}' (kind=Ente, id={}, socket={})",
engine_label,
engine_id,
query_socket.display()
);
pool.spawn(engine_card);
// 2. Hidratación: si NOUSER_DB_PATH apunta a un sled poblado,
// publicar lo que ya tenemos ANTES del re-scan. brahman-status
// ve mónadas reales en milisegundos, no en segundos.
let mut db = open_db()?;
let prior_count = db.monad_count();
if prior_count > 0 {
let mut hydrated = 0usize;
let mut skipped_model = 0usize;
for monad in db.monads() {
// Sólo publicamos centroides del modelo actual; los demás
// son data muerta hasta que el re-scan los reemplace.
let valid = monad
.centroid_model
.as_deref()
.map(|id| id == embed::MODEL_ID)
.unwrap_or(false);
if !valid {
skipped_model += 1;
continue;
}
let mut card = monad.to_brahman_card();
card.references.push(card_core::CardReference {
kind: card_core::RelationshipKind::OwnedBy,
target_id: engine_id,
target_label: engine_label.clone(),
});
pool.spawn(card);
hydrated += 1;
}
eprintln!(
"chasqui daemon: hidratadas {} mónadas previas{} en O(1)",
hydrated,
if skipped_model > 0 {
format!(" ({} dropeadas por centroid_model distinto)", skipped_model)
} else {
String::new()
}
);
}
// 3. Re-scan con hidratación: las Mónadas con mismo path_hint
// reusan id, así que NO generamos sesiones duplicadas para los
// mismos directorios — el sidecar previo ya tiene esa identidad.
let files = scanner::scan_directory(&dir, &scanner::ScanConfig::default())?;
let n_files = files.len();
let monads = cluster::by_directory_hydrated(&files, min_files(), Some(&db));
let scanned_count = monads.len();
eprintln!(
"chasqui daemon: re-scan {} archivos en {} → {} mónadas",
n_files,
dir.display(),
scanned_count
);
// Publicamos sólo las Mónadas NUEVAS (las que no estaban en la
// hidratación inicial). El criterio: si el id estaba en la DB
// previa, el sidecar de la hidratación ya cubre esa identidad.
let prior_ids: std::collections::BTreeSet<_> = db.monads().map(|m| m.id).collect();
let mut newly_spawned = 0usize;
for monad in &monads {
if prior_ids.contains(&monad.id) {
continue; // ya publicada en hidratación
}
let mut card = monad.to_brahman_card();
card.references.push(card_core::CardReference {
kind: card_core::RelationshipKind::OwnedBy,
target_id: engine_id,
target_label: engine_label.clone(),
});
pool.spawn(card);
newly_spawned += 1;
}
// Reescribimos la DB con el set actual (idempotente para los
// hidratados; reemplazo para los nuevos).
db.ingest_files(files);
db.replace_monads(monads);
eprintln!(
"chasqui daemon: 1 ente + {} mónadas vivas ({} nuevas vs hidratación)",
scanned_count, newly_spawned
);
// Engine query socket: bind antes del watcher para que cualquier
// consumer descubierto vía broker pueda consultarnos enseguida.
// Si el bind falla, seguimos sin él — la UI degrada a "no
// alcanzable" pero el daemon sigue procesando cambios.
let db_shared = std::sync::Arc::new(std::sync::Mutex::new(db));
let _query_listener = match chasqui_core::engine_socket::spawn_listener(
chasqui_core::engine_socket::ListenerConfig {
socket_path: query_socket.clone(),
engine_id,
engine_label: engine_label.clone(),
watching: Some(dir.clone()),
},
db_shared.clone(),
) {
Ok(h) => {
eprintln!(
"chasqui daemon: query socket activo en {} (proto: chasqui_card::query)",
query_socket.display()
);
Some(h)
}
Err(e) => {
eprintln!(
"chasqui daemon: query socket NO disponible ({e}) — explorer no podrá consultar"
);
None
}
};
// Watcher: cada cambio en el árbol — coalescido con debounce de
// 150ms — dispara un re-scan + re-cluster del directorio y
// re-publica al broker las Mónadas afectadas (drop + spawn por id,
// gracias al replace en `SidecarPool::spawn`).
let _watcher = match spawn_fs_watcher(
dir.clone(),
db_shared.clone(),
pool.clone(),
engine_id,
engine_label.clone(),
) {
Ok(w) => {
eprintln!(
"chasqui daemon: watcher activo en {} (debounce 150ms, re-publish on) — Ctrl-C para terminar.",
dir.display()
);
Some(w)
}
Err(e) => {
eprintln!(
"chasqui daemon: watcher deshabilitado ({e}) — Ctrl-C para terminar."
);
None
}
};
std::thread::park();
drop(_watcher);
drop(_query_listener);
let _ = std::fs::remove_file(&query_socket); // best-effort cleanup
drop(pool);
Ok(())
}
/// Ventana de debounce: notify dispara Create+Modify(+) por cada
/// edición; sin coalescer veríamos N reacciones por un solo `:w`.
/// 150ms es generoso para editores típicos (vim/code) y mantiene el
/// feedback "vivo" para el usuario.
const WATCHER_DEBOUNCE_MS: u64 = 150;
/// Watcher de filesystem con debounce + re-publish al broker.
///
/// Pipeline:
///
/// 1. **notify** dispara eventos crudos a un canal interno.
/// 2. **dispatcher**: filtra a Create/Modify/Remove de paths bajo
/// `dir`, descarta el resto, reenvía al canal de debounce.
/// 3. **coordinator**: mantiene un `HashMap<PathBuf, Instant>`.
/// Cada vez que el canal queda en silencio durante
/// `WATCHER_DEBOUNCE_MS`, agrupa los paths cuya última actividad
/// superó la ventana y los procesa en **un solo batch**.
/// 4. **process_change_batch**: re-scan + re-cluster hidratado +
/// diff vs DB + `pool.drop_session` para Mónadas desaparecidas
/// + `pool.spawn` para Mónadas nuevas o con composición distinta.
/// `pool.spawn` reemplaza la sesión previa con el mismo `Card.id`,
/// así que el broker ve el manifest fresco sin sesiones huérfanas.
fn spawn_fs_watcher(
dir: std::path::PathBuf,
db: std::sync::Arc<std::sync::Mutex<db::MonadDb>>,
pool: std::sync::Arc<card_sidecar::SidecarPool>,
engine_id: card_core::ulid::Ulid,
engine_label: String,
) -> Result<notify::RecommendedWatcher, Box<dyn std::error::Error>> {
use notify::{Event, EventKind, RecursiveMode, Watcher};
let (notify_tx, notify_rx) = std::sync::mpsc::channel::<notify::Result<Event>>();
let mut watcher = notify::recommended_watcher(move |res| {
let _ = notify_tx.send(res);
})?;
watcher.watch(&dir, RecursiveMode::Recursive)?;
let (path_tx, path_rx) = std::sync::mpsc::channel::<std::path::PathBuf>();
// Dispatcher: notify → filtro → canal de paths.
let dispatch_dir = dir.clone();
std::thread::Builder::new()
.name("chasqui-watcher-dispatch".into())
.spawn(move || {
for res in notify_rx {
let event = match res {
Ok(e) => e,
Err(e) => {
eprintln!("[watcher] error: {e}");
continue;
}
};
// Create/Modify viven; Remove también nos importa
// (puede colapsar Mónadas).
let interesting = matches!(
event.kind,
EventKind::Create(_) | EventKind::Modify(_) | EventKind::Remove(_)
);
if !interesting {
continue;
}
for path in event.paths {
if !path.starts_with(&dispatch_dir) {
continue;
}
let _ = path_tx.send(path);
}
}
})?;
// Coordinator: debounce + batch dispatch.
let coord_dir = dir;
std::thread::Builder::new()
.name("chasqui-watcher-coord".into())
.spawn(move || {
let debounce = std::time::Duration::from_millis(WATCHER_DEBOUNCE_MS);
let mut pending: std::collections::HashMap<
std::path::PathBuf,
std::time::Instant,
> = std::collections::HashMap::new();
loop {
match path_rx.recv_timeout(debounce) {
Ok(path) => {
pending.insert(path, std::time::Instant::now());
}
Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {}
Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => break,
}
let now = std::time::Instant::now();
let due: Vec<std::path::PathBuf> = pending
.iter()
.filter(|(_, t)| now.duration_since(**t) >= debounce)
.map(|(p, _)| p.clone())
.collect();
if due.is_empty() {
continue;
}
for p in &due {
pending.remove(p);
}
process_change_batch(
&due,
&coord_dir,
&db,
&pool,
engine_id,
&engine_label,
);
}
})?;
Ok(watcher)
}
/// Procesa un batch de paths cambiados: re-scanea el árbol, re-clusteriza
/// con hidratación, y propaga el delta de Mónadas al broker.
///
/// El re-scan global es deliberado: el clustering por directorio es global
/// por diseño, así que un cambio en `src/foo.rs` puede mover Mónadas en
/// `src/` sin tocar `tests/`. Coste O(N archivos), aceptable para
/// directorios típicos (<10k archivos). Optimizar a re-cluster parcial
/// cuando duela.
fn process_change_batch(
paths: &[std::path::PathBuf],
dir: &std::path::Path,
db: &std::sync::Arc<std::sync::Mutex<db::MonadDb>>,
pool: &std::sync::Arc<card_sidecar::SidecarPool>,
engine_id: card_core::ulid::Ulid,
engine_label: &str,
) {
eprintln!(
"[watcher] ⚙ batch: {} path(s) coalescidos → re-scan",
paths.len()
);
let files = match scanner::scan_directory(dir, &scanner::ScanConfig::default()) {
Ok(f) => f,
Err(e) => {
eprintln!("[watcher] re-scan falló: {e}");
return;
}
};
let mut db_lock = match db.lock() {
Ok(g) => g,
Err(_) => {
eprintln!("[watcher] mutex envenenado — abortando batch");
return;
}
};
let prior_monads: Vec<chasqui_card::MonadManifest> = db_lock.monads().cloned().collect();
let prior_ref: &db::MonadDb = &db_lock;
let monads = cluster::by_directory_hydrated(&files, min_files(), Some(prior_ref));
let prior_ids: std::collections::BTreeSet<_> =
prior_monads.iter().map(|m| m.id).collect();
let new_ids: std::collections::BTreeSet<_> = monads.iter().map(|m| m.id).collect();
// Mónadas que ya no existen (directorio quedó por debajo de
// min_files o fue removido): cerramos su sesión en el broker.
let mut removed = 0usize;
for id in prior_ids.difference(&new_ids) {
pool.drop_session(*id);
removed += 1;
if let Some(prev) = prior_monads.iter().find(|m| &m.id == id) {
eprintln!(
"[watcher] ✖ {} ({}) desapareció — sesión cerrada",
&id.to_string()[..8],
prev.label
);
}
}
// Mónadas nuevas o cuya composición cambió (members/centroid):
// (re)spawn — el pool reemplaza la sesión previa con el mismo id.
let mut respawned = 0usize;
let mut fresh = 0usize;
for monad in &monads {
let prev = prior_monads.iter().find(|m| m.id == monad.id);
let is_new = prev.is_none();
let changed = match prev {
Some(p) => p.members != monad.members || p.centroid != monad.centroid,
None => true,
};
if !changed {
continue;
}
let mut card = monad.to_brahman_card();
card.references.push(card_core::CardReference {
kind: card_core::RelationshipKind::OwnedBy,
target_id: engine_id,
target_label: engine_label.to_string(),
});
pool.spawn(card);
if is_new {
fresh += 1;
eprintln!(
"[watcher] ✦ {} nace ({} miembros, lens={:?})",
monad.label, monad.cardinality, monad.dominant_lens
);
} else {
respawned += 1;
let prev = prev.unwrap();
let delta_members = monad.members.len() as i64 - prev.members.len() as i64;
eprintln!(
"[watcher] ↻ {} refresh ({} miembros, Δ={:+})",
monad.label, monad.cardinality, delta_members
);
}
}
if removed == 0 && fresh == 0 && respawned == 0 {
eprintln!("[watcher] (sin cambios estructurales tras re-cluster)");
} else {
eprintln!(
"[watcher] ⌃ delta: {} nuevas, {} refrescadas, {} cerradas — {} sesiones vivas",
fresh,
respawned,
removed,
pool.live_sessions()
);
}
db_lock.ingest_files(files);
db_lock.replace_monads(monads);
}
fn cmd_attract(args: &[String]) -> Cmd {
let mut remote = false;
let mut positional: Vec<&String> = Vec::new();
for a in args {
if a == "--remote" {
remote = true;
} else {
positional.push(a);
}
}
let dir = positional
.first()
.map(|s| std::path::PathBuf::from(s.as_str()))
.ok_or("falta argumento <dir>")?;
let file_path = positional.get(1).ok_or("falta argumento <file>")?;
let file_path = std::path::PathBuf::from(file_path.as_str());
if !file_path.exists() {
return Err(format!("archivo no existe: {}", file_path.display()).into());
}
let (db, _) = run_scan(&dir)?;
// Construimos un FileEntry para el archivo objetivo.
let metadata = std::fs::metadata(&file_path)?;
let mtime_ms = metadata
.modified()
.ok()
.and_then(|t| t.duration_since(std::time::UNIX_EPOCH).ok())
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
let target = chasqui_card::FileEntry {
id: chasqui_card::FileId::from(chasqui_card::ulid::Ulid::new()),
path: file_path.clone(),
content_hash: None,
size: metadata.len(),
mtime_ms,
extension: file_path
.extension()
.and_then(|s| s.to_str())
.map(|s| s.to_lowercase()),
};
// Embedding del target + identificación del modelo que lo produjo.
// Local: pseudo-32d. Remote: lo que devuelva el provider electo
// (mock=pseudo-32d, real=fastembed-384d).
let (target_vec, target_model, source) = if remote {
let (v, model) = remote_embed(&target)?;
(v, model, "remote")
} else {
(
embed::embed(&target).to_vec(),
embed::MODEL_ID.to_string(),
"local",
)
};
// Filtramos Mónadas cuyo centroid_model NO matchee. Mezclar
// 32-d con 384-d daría scores sin sentido (diferente semántica
// y cosine no compara cross-modelo).
let mut ranked: Vec<(&chasqui_card::MonadManifest, f32)> = db
.monads()
.filter(|m| !m.centroid.is_empty())
.filter(|m| match &m.centroid_model {
Some(id) => id == &target_model,
None => true, // legacy sin tag — comparamos best-effort
})
.map(|m| (m, embed::attraction_score(&target_vec, m)))
.collect();
ranked.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
let total_monads = db.monads().filter(|m| !m.centroid.is_empty()).count();
let skipped = total_monads - ranked.len();
if ranked.is_empty() {
println!("ninguna Mónada con centroide en {}", dir.display());
return Ok(());
}
println!("archivo: {}", file_path.display());
println!("scan dir: {}", dir.display());
println!("embed: {} ({})", source, target_model);
if skipped > 0 {
println!(
"skipped: {} mónada(s) con centroid_model distinto (no comparables)",
skipped
);
}
println!("ranking de atracción (cosine similarity):");
println!();
for (i, (m, score)) in ranked.iter().take(5).enumerate() {
let marker = if *score >= embed::DEFAULT_ATTRACTION_THRESHOLD && i == 0 {
"🧲"
} else if i == 0 {
"·"
} else {
" "
};
let id_short = format!("{}", m.id);
let id_short = &id_short[..8];
println!(
" {} {:.4} [{}] {:30} ({})",
marker, score, id_short, m.label, m.summary
);
}
if ranked[0].1 < embed::DEFAULT_ATTRACTION_THRESHOLD {
println!();
println!(
" (mejor score {:.4} < umbral {:.4} — el archivo no se 'pega' a ninguna)",
ranked[0].1,
embed::DEFAULT_ATTRACTION_THRESHOLD
);
}
Ok(())
}
/// Pipeline completo del modo `--remote`:
/// 1. Si `NOUSER_NOUS_SOCKET` está set, lo usa directo (override
/// explícito, atajo para tests).
/// 2. Si no, delega en `card_sidecar::await_provider_blocking` —
/// el sidecar se conecta al broker, registra un consumer Card con
/// `flow.input = embed-result:json`, espera el primer
/// `MatchEvent::Available` y devuelve el socket. Esto activa la
/// lógica de `priority_contexts`: bajo `BRAHMAN_BROKER_CONTEXT=test/prod`,
/// el proveedor electo cambia sin que este código toque nada.
/// 3. Con el socket resuelto, dispara la RPC `EmbedFile`.
///
/// Devuelve `(embedding, model_id)` — el caller necesita ambos para
/// comparar contra centroides taggeados con su mismo `centroid_model`.
fn remote_embed(
file: &chasqui_card::FileEntry,
) -> Result<(Vec<f32>, String), Box<dyn std::error::Error>> {
if let Ok(explicit) = std::env::var("NOUSER_NOUS_SOCKET") {
let sock = std::path::PathBuf::from(explicit);
return embed_via(&sock, file);
}
let consumer = card_sidecar::build_consumer_card(
"chasqui.attract-cli",
chasqui_nous::FLOW_EMBED_RESULT,
chasqui_nous::FLOW_TYPE_NAME,
);
let producer_sock = card_sidecar::await_provider_blocking(
consumer,
std::time::Duration::from_secs(3),
)?;
embed_via(&producer_sock, file)
}
/// RPC blocking contra un socket chasqui-nous concreto. Devuelve
/// `(embedding, model_id)` — el `model_id` viaja en la response y
/// permite al caller saber qué centroides son comparables.
fn embed_via(
sock_path: &std::path::Path,
file: &chasqui_card::FileEntry,
) -> Result<(Vec<f32>, String), Box<dyn std::error::Error>> {
use std::io::{BufRead, BufReader, Write};
use std::os::unix::net::UnixStream;
if !sock_path.exists() {
return Err(format!("socket no existe: {}", sock_path.display()).into());
}
let mut stream = UnixStream::connect(sock_path)?;
let req = chasqui_nous::EmbedRequest {
kind: chasqui_nous::RequestKind::EmbedFile,
payload: serde_json::to_value(chasqui_nous::EmbedFilePayload {
path: file.path.display().to_string(),
extension: file.extension.clone(),
size: file.size,
mtime_ms: file.mtime_ms,
})?,
};
let line = serde_json::to_string(&req)?;
stream.write_all(line.as_bytes())?;
stream.write_all(b"\n")?;
stream.flush()?;
let mut reader = BufReader::new(stream);
let mut response = String::new();
reader.read_line(&mut response)?;
if response.is_empty() {
return Err("chasqui-nous cerró sin respuesta".into());
}
if let Ok(resp) = serde_json::from_str::<chasqui_nous::EmbedResponse>(&response) {
return Ok((resp.embedding, resp.model));
}
let err: chasqui_nous::ErrorResponse = serde_json::from_str(&response)?;
Err(format!("chasqui-nous: {}", err.error).into())
}
/// Card del propio engine (kind=Ente). Es el "ser" que produce y
/// administra Mónadas; aparece en brahman-status junto a sus Mónadas.
///
/// Declara `service_socket` y `flow.output = monad-list:json` para
/// que un consumer (UI, CLI) pueda descubrir al daemon vía broker
/// MatchEvent y consultarle por sus Mónadas sin pasar por
/// brahman-admin.
fn build_engine_card(service_socket: std::path::PathBuf) -> card_core::Card {
use card_core::{Card, CardKind, Flow, Flows, Lifecycle, Payload, Priority, Supervision, TypeRef};
use chasqui_card::query::{FLOW_MONAD_LIST, FLOW_TYPE_NAME};
Card {
payload: Payload::Virtual,
supervision: Supervision::Delegate,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
kind: CardKind::Ente,
service_socket: Some(service_socket),
flow: Flows {
input: vec![],
output: vec![Flow {
name: FLOW_MONAD_LIST.into(),
ty: TypeRef::Primitive {
name: FLOW_TYPE_NAME.into(),
},
pin_to: None,
}],
},
..Card::new("brahman.nouser_engine")
}
}
02_ruway/chasqui/chasqui-core/src/cluster.rs
+355
View File
@@ -0,0 +1,355 @@
//! Clustering determinista (Phase A).
//!
//! Estrategia: agrupar por **directorio padre** + ranking por
//! **extensión dominante**. No hay LLM ni embeddings — sólo metadatos.
//! Esta capa cubre el 90% de los casos prácticos:
//!
//! - Un proyecto Rust en `~/dev/foo/src/` → Mónada coherente (.rs).
//! - Un dump de fotos en `~/Pictures/2024/` → Mónada con lente Gallery.
//! - Notas en `~/notes/` → Mónada con lente Markdown.
//!
//! Los casos donde esta heurística falla (archivos relacionados pero
//! dispersos en el FS) son el dominio de los embeddings (Phase C) y
//! del clustering por Nous (Phase D).
use std::collections::BTreeMap;
use std::path::PathBuf;
use chasqui_card::{FileEntry, Lens, MonadManifest};
use crate::embed;
/// Mínimo de archivos para que un directorio sea promovido a Mónada.
/// Por debajo de eso, los archivos quedan "huérfanos" (no asignados).
pub const DEFAULT_MIN_FILES_PER_MONAD: usize = 3;
/// Agrupa archivos en Mónadas por directorio padre.
///
/// Devuelve un `Vec<MonadManifest>` ordenado por path. Archivos en
/// directorios con menos de `min_files` no producen Mónada.
pub fn by_directory(files: &[FileEntry], min_files: usize) -> Vec<MonadManifest> {
by_directory_hydrated(files, min_files, None)
}
/// Variante con hidratación: si `prior` está presente, busca Mónadas
/// previas con el mismo `path_hint` y `centroid_model` válido, y reusa
/// su `id` y `lineage`. Esto preserva identidad across re-scans —
/// fundamental para que el daemon pueda republicar tras hidratar de
/// sled sin generar duplicados en el broker.
pub fn by_directory_hydrated(
files: &[FileEntry],
min_files: usize,
prior: Option<&crate::db::MonadDb>,
) -> Vec<MonadManifest> {
let mut by_parent: BTreeMap<PathBuf, Vec<&FileEntry>> = BTreeMap::new();
for f in files {
if let Some(parent) = f.path.parent() {
by_parent.entry(parent.to_path_buf()).or_default().push(f);
}
}
let mut out = Vec::new();
for (parent, group) in by_parent {
if group.len() < min_files {
continue;
}
let mut m = build_monad(&parent, &group);
if let Some(db) = prior {
// Reusamos id si encontramos Mónada previa con mismo
// path_hint Y mismo centroid_model. Distintas hipótesis
// de modelo no comparten identidad — son objetos
// semánticos distintos, aunque parecidos.
if let Some(existing) = db.monads().find(|prev| {
prev.path_hint.as_deref() == m.path_hint.as_deref()
&& prev.centroid_model == m.centroid_model
}) {
m.id = existing.id;
m.lineage = existing.lineage;
m.created_at_ms = existing.created_at_ms;
m.touch();
}
}
out.push(m);
}
out
}
fn build_monad(parent: &std::path::Path, group: &[&FileEntry]) -> MonadManifest {
let label = label_from_path(parent);
let keywords = top_extensions(group, 5);
let lens = pick_lens(group);
let entropy = shannon_entropy_normalized(group);
let summary = build_summary(parent, group, &keywords);
// Centroide vectorial: promedio de los embeddings de los miembros.
// Esto es lo que permite "atracción" determinista de archivos
// nuevos sin tocar Nous.
let member_vecs: Vec<Vec<f32>> = group.iter().map(|f| embed::embed(f).to_vec()).collect();
let centroid = embed::centroid(&member_vecs);
let mut m = MonadManifest::new(label);
m.summary = summary;
m.keywords = keywords;
m.dominant_lens = lens;
m.entropy = entropy;
m.centroid = centroid;
// Taggeamos el centroide con su modelo. attract verifica esto
// antes de comparar para no mezclar pseudo-32d con real-384d.
m.centroid_model = Some(embed::MODEL_ID.to_string());
// path_hint = identidad estable across re-scans para
// hidratación. Display es lossy con UTF-8 inválido pero los
// paths legítimos se imprimen consistentes.
m.path_hint = Some(parent.display().to_string());
m.members = group.iter().map(|f| f.id).collect();
m.touch();
m
}
/// Construye un label legible tomando los últimos hasta 2 componentes
/// del path. Esto desambigua `src/` repetidos en monorepos: en lugar
/// de 5 Mónadas con label "src", quedan "ente-zero/src", "ente-brain/src",
/// etc. Para directorios shallow (root o un nivel), cae al
/// `file_name()` simple.
fn label_from_path(p: &std::path::Path) -> String {
let normals: Vec<&str> = p
.components()
.filter_map(|c| match c {
std::path::Component::Normal(s) => s.to_str(),
_ => None,
})
.collect();
if normals.is_empty() {
return "unnamed".to_string();
}
let take = normals.len().min(2);
let start = normals.len() - take;
normals[start..].join("/")
}
fn build_summary(parent: &std::path::Path, group: &[&FileEntry], keywords: &[String]) -> String {
let path_str = parent.display();
let n = group.len();
let exts = if keywords.is_empty() {
"(sin extensiones)".to_string()
} else {
keywords.join(", ")
};
format!("{n} archivos en {path_str} (ext: {exts})")
}
/// Top-N extensiones por frecuencia, descendente. Empate por orden alfabético.
fn top_extensions(files: &[&FileEntry], n: usize) -> Vec<String> {
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
for f in files {
if let Some(ext) = &f.extension {
*counts.entry(ext.clone()).or_default() += 1;
}
}
let mut sorted: Vec<_> = counts.into_iter().collect();
sorted.sort_by(|a, b| b.1.cmp(&a.1).then_with(|| a.0.cmp(&b.0)));
sorted.into_iter().take(n).map(|(k, _)| k).collect()
}
/// Elige el lente dominante según la extensión más frecuente, con
/// fallback a `shuma-discern` sobre el head del archivo más
/// representativo cuando la extensión no da hint claro (Lens::Grid).
fn pick_lens(files: &[&FileEntry]) -> Lens {
let dominant = top_extensions(files, 1).into_iter().next();
let by_ext = match dominant.as_deref() {
Some("rs" | "py" | "ts" | "tsx" | "js" | "jsx" | "go" | "java" | "kt" | "c" | "cpp"
| "cc" | "h" | "hpp" | "rb" | "swift" | "zig") => Lens::Code,
Some("png" | "jpg" | "jpeg" | "gif" | "webp" | "svg" | "bmp" | "tiff" | "heic") => {
Lens::Gallery
}
Some("md" | "markdown" | "rst" | "txt" | "org" | "tex") => Lens::Markdown,
Some("db" | "sqlite" | "sqlite3" | "csv" | "tsv" | "parquet") => Lens::Database,
_ => Lens::Grid,
};
if by_ext != Lens::Grid {
return by_ext;
}
// Fallback: samplear el primer archivo del grupo con shuma-discern.
// Sólo si tiene path real (FileEntry con path absoluto/relativo).
if let Some(first) = files.first() {
if let Some(lens) = discern_lens(&first.path) {
return lens;
}
}
Lens::Grid
}
fn discern_lens(path: &std::path::Path) -> Option<Lens> {
use std::io::Read;
let mut buf = vec![0u8; 4096];
let mut f = std::fs::File::open(path).ok()?;
let n = f.read(&mut buf).ok()?;
buf.truncate(n);
let pipeline = shuma_discern::DiscernPipeline::default_pipeline();
let path_str = path.to_str();
let d = pipeline.discern(
&buf,
&shuma_discern::Hint {
path: path_str,
size_total: None,
},
)?;
match d.lens.as_deref()? {
"code" => Some(Lens::Code),
"gallery" => Some(Lens::Gallery),
"markdown" => Some(Lens::Markdown),
"database" => Some(Lens::Database),
"tree" => Some(Lens::Tree),
_ => None,
}
}
/// Entropía de Shannon normalizada sobre la distribución de extensiones.
/// `0.0` = todos los archivos comparten extensión. `1.0` = uniformly
/// distributed entre `n` extensiones (máx información).
fn shannon_entropy_normalized(files: &[&FileEntry]) -> f32 {
let total = files.len() as f32;
if total <= 1.0 {
return 0.0;
}
let mut counts: BTreeMap<String, usize> = BTreeMap::new();
for f in files {
let ext = f.extension.as_deref().unwrap_or("(none)");
*counts.entry(ext.to_string()).or_default() += 1;
}
let entropy: f32 = counts
.values()
.map(|&c| {
let p = c as f32 / total;
-p * p.log2()
})
.sum();
let max_entropy = (counts.len() as f32).log2();
if max_entropy <= 0.0 {
0.0
} else {
(entropy / max_entropy).clamp(0.0, 1.0)
}
}
#[cfg(test)]
mod tests {
use super::*;
use chasqui_card::FileId;
use std::path::PathBuf;
use ulid::Ulid;
fn mkfile(path: &str, ext: Option<&str>) -> FileEntry {
FileEntry {
id: FileId::from(Ulid::new()),
path: PathBuf::from(path),
content_hash: None,
size: 100,
mtime_ms: 0,
extension: ext.map(String::from),
}
}
#[test]
fn groups_by_parent_directory() {
let files = vec![
mkfile("/proj/src/a.rs", Some("rs")),
mkfile("/proj/src/b.rs", Some("rs")),
mkfile("/proj/src/c.rs", Some("rs")),
mkfile("/proj/docs/readme.md", Some("md")),
mkfile("/proj/docs/guide.md", Some("md")),
mkfile("/proj/docs/notes.md", Some("md")),
];
let monads = by_directory(&files, 3);
assert_eq!(monads.len(), 2);
let labels: std::collections::BTreeSet<_> = monads.iter().map(|m| &m.label).collect();
// Phase B: labels usan los últimos 2 componentes del path para
// desambiguar (proj/src vs proj/docs en lugar de src vs docs).
assert!(labels.iter().any(|l| l.as_str() == "proj/src"));
assert!(labels.iter().any(|l| l.as_str() == "proj/docs"));
}
#[test]
fn small_groups_not_promoted() {
let files = vec![
mkfile("/proj/single.txt", Some("txt")),
mkfile("/proj/sub/a.txt", Some("txt")),
mkfile("/proj/sub/b.txt", Some("txt")),
mkfile("/proj/sub/c.txt", Some("txt")),
];
// min=3 → /proj/single solo no se promueve, /proj/sub sí.
let monads = by_directory(&files, 3);
assert_eq!(monads.len(), 1);
assert_eq!(monads[0].label, "proj/sub");
}
#[test]
fn label_from_root_only_one_component() {
// Un solo componente normal en el path → no hay "padre" útil.
let p = std::path::Path::new("/onlyone");
assert_eq!(label_from_path(p), "onlyone");
}
#[test]
fn label_from_deep_path_takes_last_two() {
let p = std::path::Path::new("/a/b/c/d/e");
assert_eq!(label_from_path(p), "d/e");
}
#[test]
fn lens_picked_by_dominant_extension() {
let files = vec![
mkfile("/x/a.rs", Some("rs")),
mkfile("/x/b.rs", Some("rs")),
mkfile("/x/c.rs", Some("rs")),
];
let monads = by_directory(&files, 3);
assert_eq!(monads[0].dominant_lens, Lens::Code);
let files = vec![
mkfile("/y/1.png", Some("png")),
mkfile("/y/2.png", Some("png")),
mkfile("/y/3.png", Some("png")),
];
let monads = by_directory(&files, 3);
assert_eq!(monads[0].dominant_lens, Lens::Gallery);
}
#[test]
fn entropy_zero_for_homogeneous() {
let files = vec![
mkfile("/x/a.rs", Some("rs")),
mkfile("/x/b.rs", Some("rs")),
mkfile("/x/c.rs", Some("rs")),
];
let monads = by_directory(&files, 3);
assert_eq!(monads[0].entropy, 0.0);
}
#[test]
fn entropy_high_for_diverse() {
let files = vec![
mkfile("/x/a.rs", Some("rs")),
mkfile("/x/b.md", Some("md")),
mkfile("/x/c.json", Some("json")),
mkfile("/x/d.png", Some("png")),
];
let monads = by_directory(&files, 3);
// 4 extensiones distintas, distribución uniforme → entropy ≈ 1.0
assert!(monads[0].entropy > 0.9, "got {}", monads[0].entropy);
}
#[test]
fn top_extensions_orders_by_freq_then_alpha() {
let files = vec![
mkfile("/x/a.rs", Some("rs")),
mkfile("/x/b.rs", Some("rs")),
mkfile("/x/c.md", Some("md")),
mkfile("/x/d.py", Some("py")),
];
let refs: Vec<&FileEntry> = files.iter().collect();
let top = top_extensions(&refs, 3);
assert_eq!(top, vec!["rs", "md", "py"]);
}
}
02_ruway/chasqui/chasqui-core/src/db.rs
+313
View File
@@ -0,0 +1,313 @@
//! DB de Mónadas y archivos. Backend dual:
//!
//! - **Memoria** (default, cache): `BTreeMap<Id, T>` para reads O(log n).
//! - **Persistencia** (opcional): sled-backed write-through. Si se abre
//! con `MonadDb::open(path)`, cada `insert_*` escribe a sled además
//! de la cache. Reads siempre vienen de la cache.
//!
//! Wire format: JSON via serde_json. Los manifestos son chicos y
//! ocasionalmente inspeccionables a mano (`sled-cli`); JSON gana sobre
//! postcard en debuggability.
use std::collections::BTreeMap;
use std::path::Path;
use chasqui_card::{FileEntry, FileId, MonadId, MonadManifest};
use thiserror::Error;
#[derive(Debug, Error)]
pub enum MonadDbError {
#[error("sled: {0}")]
Sled(#[from] sled::Error),
#[error("JSON: {0}")]
Json(#[from] serde_json::Error),
#[error("ULID inválido en clave: {0}")]
BadKey(String),
}
const TREE_FILES: &str = "files";
const TREE_MONADS: &str = "monads";
/// Store de Mónadas + archivos. Cache en memoria + persistencia
/// opcional sled.
pub struct MonadDb {
files: BTreeMap<FileId, FileEntry>,
monads: BTreeMap<MonadId, MonadManifest>,
persistence: Option<sled::Db>,
}
impl Default for MonadDb {
fn default() -> Self {
Self::new()
}
}
impl MonadDb {
/// Store en memoria pura (sin persistencia). El estado se pierde al salir.
pub fn new() -> Self {
Self {
files: BTreeMap::new(),
monads: BTreeMap::new(),
persistence: None,
}
}
/// Abre (o crea) un store sled-backed en `path`. Carga el contenido
/// existente a la cache antes de devolver.
pub fn open(path: impl AsRef<Path>) -> Result<Self, MonadDbError> {
let db = sled::open(path)?;
let mut files = BTreeMap::new();
let mut monads = BTreeMap::new();
let files_tree = db.open_tree(TREE_FILES)?;
for kv in files_tree.iter() {
let (k, v) = kv?;
let id = decode_key(&k)?;
let entry: FileEntry = serde_json::from_slice(&v)?;
files.insert(id, entry);
}
let monads_tree = db.open_tree(TREE_MONADS)?;
for kv in monads_tree.iter() {
let (k, v) = kv?;
let id = decode_key(&k)?;
let monad: MonadManifest = serde_json::from_slice(&v)?;
monads.insert(id, monad);
}
Ok(Self {
files,
monads,
persistence: Some(db),
})
}
/// `true` si tiene backend persistente.
pub fn is_persistent(&self) -> bool {
self.persistence.is_some()
}
// ---- Files ----
pub fn insert_file(&mut self, file: FileEntry) -> Option<FileEntry> {
if let Some(db) = &self.persistence {
// Write-through: si falla el persist, lo logeamos pero la
// memoria queda actualizada. Filosofía: cache nunca miente
// sobre el último estado conocido en este proceso.
if let Err(e) = persist_file(db, &file) {
eprintln!("[MonadDb] persist file falló: {e}");
}
}
self.files.insert(file.id, file)
}
pub fn ingest_files(&mut self, files: Vec<FileEntry>) {
for f in files {
self.insert_file(f);
}
}
pub fn file(&self, id: FileId) -> Option<&FileEntry> {
self.files.get(&id)
}
pub fn files(&self) -> impl Iterator<Item = &FileEntry> + '_ {
self.files.values()
}
pub fn file_count(&self) -> usize {
self.files.len()
}
// ---- Monads ----
pub fn insert_monad(&mut self, monad: MonadManifest) -> Option<MonadManifest> {
if let Some(db) = &self.persistence {
if let Err(e) = persist_monad(db, &monad) {
eprintln!("[MonadDb] persist monad falló: {e}");
}
}
self.monads.insert(monad.id, monad)
}
pub fn replace_monads(&mut self, monads: Vec<MonadManifest>) {
// Si hay persistencia, limpiar tree antes de insertar.
if let Some(db) = &self.persistence {
if let Ok(tree) = db.open_tree(TREE_MONADS) {
let _ = tree.clear();
}
}
self.monads.clear();
for m in monads {
self.insert_monad(m);
}
}
pub fn monad(&self, id: MonadId) -> Option<&MonadManifest> {
self.monads.get(&id)
}
pub fn monads(&self) -> impl Iterator<Item = &MonadManifest> + '_ {
self.monads.values()
}
pub fn monad_count(&self) -> usize {
self.monads.len()
}
/// Resuelve los archivos miembros de una Mónada como referencias.
/// Skipea silenciosamente IDs que ya no estén en la tabla `files`.
pub fn resolve_members(&self, monad_id: MonadId) -> Vec<&FileEntry> {
match self.monads.get(&monad_id) {
Some(m) => m.members.iter().filter_map(|id| self.files.get(id)).collect(),
None => Vec::new(),
}
}
}
fn persist_file(db: &sled::Db, f: &FileEntry) -> Result<(), MonadDbError> {
let tree = db.open_tree(TREE_FILES)?;
let key = f.id.to_string();
let val = serde_json::to_vec(f)?;
tree.insert(key.as_bytes(), val)?;
Ok(())
}
fn persist_monad(db: &sled::Db, m: &MonadManifest) -> Result<(), MonadDbError> {
let tree = db.open_tree(TREE_MONADS)?;
let key = m.id.to_string();
let val = serde_json::to_vec(m)?;
tree.insert(key.as_bytes(), val)?;
Ok(())
}
fn decode_key(k: &[u8]) -> Result<ulid::Ulid, MonadDbError> {
let s = std::str::from_utf8(k).map_err(|_| MonadDbError::BadKey(format!("{:?}", k)))?;
ulid::Ulid::from_string(s).map_err(|_| MonadDbError::BadKey(s.to_string()))
}
#[cfg(test)]
mod tests {
use super::*;
use chasqui_card::Lens;
use ulid::Ulid;
fn mk_file(path: &str) -> FileEntry {
FileEntry {
id: FileId::from(Ulid::new()),
path: std::path::PathBuf::from(path),
content_hash: None,
size: 100,
mtime_ms: 0,
extension: Some("rs".into()),
}
}
#[test]
fn ingest_and_lookup() {
let mut db = MonadDb::new();
let f1 = mk_file("/a/x.rs");
let f2 = mk_file("/a/y.rs");
let id1 = f1.id;
db.ingest_files(vec![f1, f2]);
assert_eq!(db.file_count(), 2);
assert!(db.file(id1).is_some());
assert!(!db.is_persistent());
}
#[test]
fn resolve_members_filters_missing() {
let mut db = MonadDb::new();
let f1 = mk_file("/x/a.rs");
let id1 = f1.id;
db.insert_file(f1);
let mut m = MonadManifest::new("test");
m.members.insert(id1);
m.members.insert(FileId::from(Ulid::new())); // miembro fantasma
m.dominant_lens = Lens::Code;
m.touch();
let mid = m.id;
db.insert_monad(m);
let resolved = db.resolve_members(mid);
assert_eq!(resolved.len(), 1);
assert_eq!(resolved[0].id, id1);
}
#[test]
fn replace_monads_clears_old() {
let mut db = MonadDb::new();
let mut m1 = MonadManifest::new("a");
m1.members.insert(FileId::from(Ulid::new()));
m1.touch();
db.insert_monad(m1);
assert_eq!(db.monad_count(), 1);
let mut m2 = MonadManifest::new("b");
m2.members.insert(FileId::from(Ulid::new()));
m2.touch();
db.replace_monads(vec![m2]);
assert_eq!(db.monad_count(), 1);
assert!(db.monads().next().unwrap().label == "b");
}
#[test]
fn persistence_roundtrip() {
let tmp = tempfile::tempdir().unwrap();
let dbpath = tmp.path().join("monads.sled");
// Escribimos algunos datos
{
let mut db = MonadDb::open(&dbpath).expect("open");
assert!(db.is_persistent());
let f = mk_file("/persist/a.rs");
let fid = f.id;
db.insert_file(f);
let mut m = MonadManifest::new("persist-test");
m.members.insert(fid);
m.dominant_lens = Lens::Code;
m.touch();
db.insert_monad(m);
}
// Reabrimos y verificamos que están
let db = MonadDb::open(&dbpath).expect("reopen");
assert_eq!(db.file_count(), 1);
assert_eq!(db.monad_count(), 1);
let m = db.monads().next().unwrap();
assert_eq!(m.label, "persist-test");
assert_eq!(m.cardinality, 1);
}
#[test]
fn replace_monads_purges_persistent_tree() {
let tmp = tempfile::tempdir().unwrap();
let dbpath = tmp.path().join("replace.sled");
{
let mut db = MonadDb::open(&dbpath).unwrap();
let mut m1 = MonadManifest::new("old");
m1.members.insert(FileId::from(Ulid::new()));
m1.touch();
db.insert_monad(m1);
}
// Reabrir, replace, verificar
{
let mut db = MonadDb::open(&dbpath).unwrap();
assert_eq!(db.monad_count(), 1);
let mut m2 = MonadManifest::new("new");
m2.members.insert(FileId::from(Ulid::new()));
m2.touch();
db.replace_monads(vec![m2]);
assert_eq!(db.monad_count(), 1);
}
// Tercera apertura: sólo "new" sobrevive
let db = MonadDb::open(&dbpath).unwrap();
assert_eq!(db.monad_count(), 1);
assert_eq!(db.monads().next().unwrap().label, "new");
}
}
02_ruway/chasqui/chasqui-core/src/embed.rs
+298
View File
@@ -0,0 +1,298 @@
//! Pseudo-embeddings de archivos: vectores deterministas derivados de
//! metadatos (sin LLM).
//!
//! Implementan el "imán semántico" matemático que el diseño de Kairos
//! pide: cada archivo tiene un vector, cada Mónada tiene un centroide,
//! y un archivo nuevo se "pega" a la Mónada cuyo centroide está más
//! cerca (cosine similarity).
//!
//! No reemplaza embeddings reales (text-embedding de un LLM); sirve para:
//! - Bootstrapping sin Nous corriendo.
//! - Mock determinístico en `BRAHMAN_BROKER_CONTEXT=test`.
//! - Cohesión visual por path/extension (dos `.rs` en `src/` quedan
//! muy juntos en el espacio vectorial).
//!
//! ## Forma del vector ([`EMBED_DIM`]=32, normalizado)
//!
//! - dims 0..8: `blake3(extension)` → identidad de tipo
//! - dims 8..16: `blake3(parent_dir)` → identidad de contenedor
//! - dims 16..24: `blake3(file_stem)` → identidad léxica del archivo
//! - dims 24..28: tamaño (log scale + flags binarios)
//! - dims 28..32: mtime (escala día + features cíclicas)
//!
//! ## Propiedades empíricas
//!
//! - Mismo dir + misma ext → similitud > 0.7 (alta cohesión).
//! - Mismo dir + ext distinta → similitud ~ 0.5.
//! - Dirs distintos + misma ext → similitud ~ 0.5.
//! - Sin parecido → similitud < 0.3.
use chasqui_card::{FileEntry, MonadId, MonadManifest};
/// Dimensión del vector embedding.
pub const EMBED_DIM: usize = 32;
/// Identificador del modelo que produce este embedding. Se usa para
/// taggear `MonadManifest.centroid_model`: los consumidores comparan
/// este string contra el suyo antes de hacer cosine similarity.
/// Mezclar centroides de distinto MODEL_ID corrompe scores
/// silenciosamente (dimensiones distintas, semántica distinta).
pub const MODEL_ID: &str = "chasqui-pseudo-32d";
/// Computa el embedding de un archivo. Determinístico: misma input
/// → mismo vector. El vector queda L2-normalizado.
pub fn embed(file: &FileEntry) -> [f32; EMBED_DIM] {
let mut v = [0.0f32; EMBED_DIM];
// dims 0..8: extension hash
fill_from_hash(&mut v[0..8], file.extension.as_deref().unwrap_or(""));
// dims 8..16: parent dir name hash
let parent = file
.path
.parent()
.and_then(|p| p.file_name())
.and_then(|n| n.to_str())
.unwrap_or("");
fill_from_hash(&mut v[8..16], parent);
// dims 16..24: file stem hash (sin extensión)
let stem = file
.path
.file_stem()
.and_then(|n| n.to_str())
.unwrap_or("");
fill_from_hash(&mut v[16..24], stem);
// dims 24..28: tamaño (centrado en 0 para que dot products entre
// archivos de tamaño diferente sumen 0 en expectativa).
let log_size = (file.size.max(1) as f32).log10();
v[24] = ((log_size / 15.0).clamp(0.0, 1.0) - 0.5) * 2.0; // [-1, 1]
v[25] = (log_size.fract() - 0.5) * 2.0;
v[26] = if file.size >= 1_048_576 { 1.0 } else { -1.0 }; // ≥1MiB flag
v[27] = if file.size <= 256 { 1.0 } else { -1.0 }; // ≤256B flag
// dims 28..32: mtime — escala día + cíclicas (centradas).
let day = file.mtime_ms / (86_400 * 1000);
v[28] = (((day as f32) / 30_000.0).clamp(0.0, 1.0) - 0.5) * 2.0;
v[29] = ((day % 365) as f32 / 365.0 - 0.5) * 2.0;
v[30] = ((day % 30) as f32 / 30.0 - 0.5) * 2.0;
v[31] = ((day % 7) as f32 / 7.0 - 0.5) * 2.0;
normalize(&mut v);
v
}
/// Fill `out` con bytes del hash blake3 de `input`, centrados en [-1, 1].
/// El centrado es crítico: bytes uniformes en [0,1] tienen media 0.5,
/// así dos vectores hash distintos (de strings no relacionados) tendrían
/// expected cosine similarity ≈ 0.75 (espuriamente alto). Centrarlos en
/// [-1, 1] hace que la expectativa sea ≈ 0 — propiedad necesaria para
/// que cosine similarity sea una métrica útil de afinidad.
fn fill_from_hash(out: &mut [f32], input: &str) {
let h = blake3::hash(input.as_bytes());
let bytes = h.as_bytes();
for (i, slot) in out.iter_mut().enumerate() {
*slot = (bytes[i] as f32 - 127.5) / 127.5;
}
}
/// L2-normaliza un vector in-place. Vectores con norma 0 quedan en 0.
fn normalize(v: &mut [f32]) {
let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
if norm > 0.0 {
for x in v.iter_mut() {
*x /= norm;
}
}
}
/// Cosine similarity entre dos vectores. Asume ambos L2-normalizados
/// (en cuyo caso `dot product == cosine similarity`). Si las longitudes
/// no coinciden, devuelve 0.
pub fn cosine_similarity(a: &[f32], b: &[f32]) -> f32 {
if a.len() != b.len() || a.is_empty() {
return 0.0;
}
a.iter().zip(b.iter()).map(|(x, y)| x * y).sum()
}
/// Centroide de un set de vectores. Promedio dim-por-dim seguido de
/// L2-normalización. El resultado es un vector unidad apto para
/// comparar con miembros nuevos vía cosine similarity.
pub fn centroid(vectors: &[Vec<f32>]) -> Vec<f32> {
if vectors.is_empty() {
return Vec::new();
}
let dim = vectors[0].len();
let mut c = vec![0.0f32; dim];
for v in vectors {
if v.len() != dim {
continue;
}
for (i, x) in v.iter().enumerate() {
c[i] += x;
}
}
let n = vectors.len() as f32;
for x in c.iter_mut() {
*x /= n;
}
normalize(&mut c);
c
}
/// Cohesión interna: media de cosine similarity de cada miembro contra
/// el centroide. Alta cohesión = Mónada compacta. Baja = bifurcable.
pub fn cohesion(centroid: &[f32], member_vectors: &[Vec<f32>]) -> f32 {
if member_vectors.is_empty() || centroid.is_empty() {
return 0.0;
}
let sum: f32 = member_vectors
.iter()
.map(|v| cosine_similarity(centroid, v))
.sum();
sum / member_vectors.len() as f32
}
/// Score de atracción de un archivo nuevo a una Mónada existente:
/// cosine similarity de su embedding contra el centroide de la Mónada.
/// Mayor score = mayor afinidad.
pub fn attraction_score(file_vec: &[f32], monad: &MonadManifest) -> f32 {
if monad.centroid.is_empty() {
return 0.0;
}
cosine_similarity(file_vec, &monad.centroid)
}
/// Encuentra la Mónada con mayor afinidad a un archivo. Devuelve
/// `(MonadId, score)` o `None` si ninguna tiene centroide.
pub fn best_attraction<'a, I>(file_vec: &[f32], monads: I) -> Option<(MonadId, f32)>
where
I: IntoIterator<Item = &'a MonadManifest>,
{
monads
.into_iter()
.filter(|m| !m.centroid.is_empty())
.map(|m| (m.id, attraction_score(file_vec, m)))
.max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
}
/// Umbral por defecto para "se pega": si el score es ≥ esto, el
/// archivo se asigna automáticamente. Ajustable por el caller.
pub const DEFAULT_ATTRACTION_THRESHOLD: f32 = 0.7;
#[cfg(test)]
mod tests {
use super::*;
use chasqui_card::FileId;
use std::path::PathBuf;
use ulid::Ulid;
fn mk(path: &str, ext: Option<&str>, size: u64) -> FileEntry {
FileEntry {
id: FileId::from(Ulid::new()),
path: PathBuf::from(path),
content_hash: None,
size,
mtime_ms: 1_700_000_000_000, // fixed para que mtime no domine
extension: ext.map(String::from),
}
}
#[test]
fn embed_is_deterministic() {
let a = mk("/x/foo.rs", Some("rs"), 1024);
let b = mk("/x/foo.rs", Some("rs"), 1024);
let va = embed(&a);
let vb = embed(&b);
// Mismos metadatos → mismo vector (los IDs no entran al embedding).
assert_eq!(va, vb);
}
#[test]
fn embed_is_unit_normalized() {
let f = mk("/x/foo.rs", Some("rs"), 1024);
let v = embed(&f);
let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
assert!((norm - 1.0).abs() < 1e-5, "norm={norm}");
}
#[test]
fn same_dir_same_ext_high_similarity() {
let a = embed(&mk("/proj/src/a.rs", Some("rs"), 1000));
let b = embed(&mk("/proj/src/b.rs", Some("rs"), 1100));
let sim = cosine_similarity(&a, &b);
assert!(sim > 0.7, "esperaba sim > 0.7, fue {sim}");
}
#[test]
fn unrelated_files_low_similarity() {
let a = embed(&mk("/proj/src/main.rs", Some("rs"), 1000));
let b = embed(&mk("/photos/2024/sunset.jpg", Some("jpg"), 5_000_000));
let sim = cosine_similarity(&a, &b);
assert!(sim < 0.5, "esperaba sim < 0.5, fue {sim}");
}
#[test]
fn centroid_is_unit_and_close_to_members() {
let v1 = embed(&mk("/x/a.rs", Some("rs"), 1000));
let v2 = embed(&mk("/x/b.rs", Some("rs"), 1100));
let v3 = embed(&mk("/x/c.rs", Some("rs"), 1200));
let c = centroid(&[v1.to_vec(), v2.to_vec(), v3.to_vec()]);
// Norma unitaria.
let norm: f32 = c.iter().map(|x| x * x).sum::<f32>().sqrt();
assert!((norm - 1.0).abs() < 1e-5, "norm={norm}");
// Cohesión alta porque los miembros son similares.
let cohesion = cohesion(&c, &[v1.to_vec(), v2.to_vec(), v3.to_vec()]);
assert!(cohesion > 0.9, "cohesion={cohesion}");
}
#[test]
fn attraction_picks_correct_monad() {
// Construimos dos Mónadas: una de Rust, otra de imágenes.
let rust_files = vec![
embed(&mk("/proj/src/a.rs", Some("rs"), 1000)).to_vec(),
embed(&mk("/proj/src/b.rs", Some("rs"), 1100)).to_vec(),
];
let img_files = vec![
embed(&mk("/photos/p1.jpg", Some("jpg"), 5_000_000)).to_vec(),
embed(&mk("/photos/p2.jpg", Some("jpg"), 4_000_000)).to_vec(),
];
let mut rust_monad = MonadManifest::new("rust");
rust_monad.members.insert(FileId::from(Ulid::new()));
rust_monad.touch();
rust_monad.centroid = centroid(&rust_files);
let mut img_monad = MonadManifest::new("photos");
img_monad.members.insert(FileId::from(Ulid::new()));
img_monad.touch();
img_monad.centroid = centroid(&img_files);
// Un archivo .rs nuevo en /proj/src debe atraerse a la Mónada Rust.
let new_rs = embed(&mk("/proj/src/new.rs", Some("rs"), 1500));
let (best_id, _score) = best_attraction(&new_rs, [&rust_monad, &img_monad].into_iter())
.expect("best match");
assert_eq!(best_id, rust_monad.id);
// Y al revés.
let new_jpg = embed(&mk("/photos/new.jpg", Some("jpg"), 6_000_000));
let (best_id, _score) = best_attraction(&new_jpg, [&rust_monad, &img_monad].into_iter())
.expect("best match");
assert_eq!(best_id, img_monad.id);
}
#[test]
fn empty_centroid_skipped_in_attraction() {
let mut m = MonadManifest::new("empty");
m.members.insert(FileId::from(Ulid::new()));
m.touch();
// m.centroid queda vacío
let v = embed(&mk("/x/y.rs", Some("rs"), 100));
assert!(best_attraction(&v, [&m].into_iter()).is_none());
}
}
02_ruway/chasqui/chasqui-core/src/engine_socket.rs
+318
View File
@@ -0,0 +1,318 @@
//! Listener Unix-socket que sirve [`chasqui_card::query::QueryRequest`].
//!
//! El daemon `chasqui` lo monta para que cualquier consumer (UI, CLI,
//! otro módulo) pueda preguntarle por sus Mónadas sin pasar por
//! brahman-admin. El path del socket viaja en el `Card.service_socket`
//! del engine; el broker brahman lo enseña vía MatchEvent::Available
//! cuando un consumer declara `flow.input = monad-list:json`.
//!
//! Wire: line-delimited JSON, single-shot por conexión. Mismo patrón
//! que `chasqui-nous` (mock/real ↔ chasqui-core), reutilizado.
//!
//! Threading: un thread dedicado, blocking I/O. No vale la pena traer
//! tokio acá — la frecuencia esperada es muy baja (UI poll cada 2s)
//! y el handler es trivial (lock db → snapshot → write).
use std::io::{BufRead, BufReader, Write};
use std::os::unix::net::{UnixListener, UnixStream};
use std::path::PathBuf;
use std::sync::{Arc, Mutex};
use chasqui_card::query::{
EngineInfo, ErrorResponse, FileView, ListMonadsResponse, MonadView, QueryRequest,
ResolveMonadResponse,
};
use chasqui_card::MonadId;
use chasqui_card::ulid::Ulid;
use crate::db::MonadDb;
/// Configuración del listener.
pub struct ListenerConfig {
pub socket_path: PathBuf,
pub engine_id: Ulid,
pub engine_label: String,
/// Path del directorio que el daemon está observando, para incluir
/// en `EngineInfo.watching`. `None` si el daemon no observa nada.
pub watching: Option<PathBuf>,
}
/// Bind del socket + spawn de un thread con accept loop. Devuelve el
/// path final (útil para confirmar) y un `JoinHandle` para shutdown
/// explícito (drop = thread sigue, listener queda).
///
/// Si el socket ya existe (sesión anterior crasheada), se intenta
/// removerlo antes del bind. Errores de bind se propagan al caller.
pub fn spawn_listener(
config: ListenerConfig,
db: Arc<Mutex<MonadDb>>,
) -> std::io::Result<std::thread::JoinHandle<()>> {
if config.socket_path.exists() {
let _ = std::fs::remove_file(&config.socket_path);
}
if let Some(parent) = config.socket_path.parent() {
std::fs::create_dir_all(parent)?;
}
let listener = UnixListener::bind(&config.socket_path)?;
let handle = std::thread::Builder::new()
.name("chasqui-engine-listener".into())
.spawn(move || {
for conn in listener.incoming() {
match conn {
Ok(stream) => {
// Handler sincrónico inline. La frecuencia
// esperada (UI poll cada N segundos) no
// amerita spawn-per-connection; si en el
// futuro hay carga, agregar un threadpool.
if let Err(e) = handle_conn(stream, &db, &config) {
eprintln!("[engine-socket] conn falló: {e}");
}
}
Err(e) => {
eprintln!("[engine-socket] accept falló: {e}");
}
}
}
})?;
Ok(handle)
}
fn handle_conn(
mut stream: UnixStream,
db: &Arc<Mutex<MonadDb>>,
config: &ListenerConfig,
) -> std::io::Result<()> {
let mut reader = BufReader::new(stream.try_clone()?);
let mut line = String::new();
let n = reader.read_line(&mut line)?;
if n == 0 {
return Ok(());
}
let resp_bytes = match serde_json::from_str::<QueryRequest>(line.trim()) {
Ok(QueryRequest::ListMonads) => match handle_list_monads(db, config) {
Ok(json) => json,
Err(e) => encode_error(format!("list_monads falló: {e}")),
},
Ok(QueryRequest::ResolveMonad { id }) => match handle_resolve_monad(db, id) {
Ok(json) => json,
Err(e) => encode_error(format!("resolve_monad falló: {e}")),
},
Err(e) => encode_error(format!("JSON inválido: {e}")),
};
stream.write_all(resp_bytes.as_bytes())?;
stream.write_all(b"\n")?;
stream.flush()?;
let _ = stream.shutdown(std::net::Shutdown::Both);
Ok(())
}
fn handle_list_monads(
db: &Arc<Mutex<MonadDb>>,
config: &ListenerConfig,
) -> Result<String, String> {
let db_lock = db.lock().map_err(|_| "mutex envenenado".to_string())?;
let monads: Vec<MonadView> = db_lock.monads().map(MonadView::from_manifest).collect();
let resp = ListMonadsResponse {
engine: EngineInfo {
id: config.engine_id,
label: config.engine_label.clone(),
watching: config.watching.as_ref().map(|p| p.display().to_string()),
},
monads,
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
fn handle_resolve_monad(db: &Arc<Mutex<MonadDb>>, id: MonadId) -> Result<String, String> {
let db_lock = db.lock().map_err(|_| "mutex envenenado".to_string())?;
let members: Vec<FileView> = db_lock
.resolve_members(id)
.into_iter()
.map(FileView::from_entry)
.collect();
let resp = ResolveMonadResponse { monad: id, members };
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
fn encode_error(msg: String) -> String {
let err = ErrorResponse { error: msg };
serde_json::to_string(&err).unwrap_or_else(|_| "{\"error\":\"encode\"}".into())
}
// El cliente blocking vive en `chasqui_card::query::client` — junto a
// los wire types — para que un consumer pueda hablar con el daemon
// importando sólo `chasqui-card`, sin arrastrar el peso de
// `chasqui-core` (scanner / db / sled / notify / walkdir / blake3).
#[cfg(test)]
mod tests {
use super::*;
use crate::db::MonadDb;
use chasqui_card::query::client as query_client;
use chasqui_card::MonadManifest;
use std::time::Duration;
fn fresh_socket_path(name: &str) -> PathBuf {
let dir = std::env::temp_dir();
let unique = format!("{}-{}-{}.sock", name, std::process::id(), Ulid::new());
dir.join(unique)
}
#[test]
fn list_monads_roundtrip_empty() {
let socket = fresh_socket_path("chasqui-engine-test");
let db = Arc::new(Mutex::new(MonadDb::new()));
let engine_id = Ulid::new();
let _h = spawn_listener(
ListenerConfig {
socket_path: socket.clone(),
engine_id,
engine_label: "test-engine".into(),
watching: Some(PathBuf::from("/tmp/x")),
},
db.clone(),
)
.unwrap();
// Pequeña espera para que el bind se asiente (en práctica el
// socket existe inmediatamente tras el bind, pero algunos FS
// necesitan un tick). Si esto resulta flaky, agregar un loop
// de wait_for(socket.exists()).
std::thread::sleep(Duration::from_millis(50));
let resp = query_client::list_monads(&socket, Duration::from_secs(2)).unwrap();
assert_eq!(resp.engine.id, engine_id);
assert_eq!(resp.engine.label, "test-engine");
assert_eq!(resp.engine.watching.as_deref(), Some("/tmp/x"));
assert!(resp.monads.is_empty());
let _ = std::fs::remove_file(&socket);
}
#[test]
fn list_monads_returns_views() {
let socket = fresh_socket_path("chasqui-engine-test-views");
let db = Arc::new(Mutex::new(MonadDb::new()));
let m1 = MonadManifest::new("alpha");
let m2 = MonadManifest::new("beta");
{
let mut g = db.lock().unwrap();
g.replace_monads(vec![m1.clone(), m2.clone()]);
}
let _h = spawn_listener(
ListenerConfig {
socket_path: socket.clone(),
engine_id: Ulid::new(),
engine_label: "test".into(),
watching: None,
},
db.clone(),
)
.unwrap();
std::thread::sleep(Duration::from_millis(50));
let resp = query_client::list_monads(&socket, Duration::from_secs(2)).unwrap();
assert_eq!(resp.monads.len(), 2);
let labels: Vec<_> = resp.monads.iter().map(|m| m.label.as_str()).collect();
assert!(labels.contains(&"alpha"));
assert!(labels.contains(&"beta"));
let _ = std::fs::remove_file(&socket);
}
#[test]
fn resolve_monad_returns_member_files() {
use chasqui_card::FileEntry;
use std::path::PathBuf;
let socket = fresh_socket_path("chasqui-engine-test-resolve");
let db = Arc::new(Mutex::new(MonadDb::new()));
// Dos archivos y una Mónada que los tiene de miembros.
let f1 = FileEntry {
id: Ulid::new(),
path: PathBuf::from("/proj/a.rs"),
content_hash: None,
size: 10,
mtime_ms: 1,
extension: Some("rs".into()),
};
let f2 = FileEntry {
id: Ulid::new(),
path: PathBuf::from("/proj/b.rs"),
content_hash: None,
size: 20,
mtime_ms: 2,
extension: Some("rs".into()),
};
let mut m = MonadManifest::new("proj");
m.members.insert(f1.id);
m.members.insert(f2.id);
m.cardinality = 2;
let monad_id = m.id;
{
let mut g = db.lock().unwrap();
g.ingest_files(vec![f1, f2]);
g.replace_monads(vec![m]);
}
let _h = spawn_listener(
ListenerConfig {
socket_path: socket.clone(),
engine_id: Ulid::new(),
engine_label: "test".into(),
watching: None,
},
db.clone(),
)
.unwrap();
std::thread::sleep(Duration::from_millis(50));
let resp =
query_client::resolve_monad(&socket, monad_id, Duration::from_secs(2)).unwrap();
assert_eq!(resp.monad, monad_id);
assert_eq!(resp.members.len(), 2);
let paths: Vec<_> = resp.members.iter().map(|f| f.path.as_str()).collect();
assert!(paths.contains(&"/proj/a.rs"));
assert!(paths.contains(&"/proj/b.rs"));
let _ = std::fs::remove_file(&socket);
}
#[test]
fn invalid_request_returns_error_response() {
let socket = fresh_socket_path("chasqui-engine-test-bad");
let db = Arc::new(Mutex::new(MonadDb::new()));
let _h = spawn_listener(
ListenerConfig {
socket_path: socket.clone(),
engine_id: Ulid::new(),
engine_label: "test".into(),
watching: None,
},
db.clone(),
)
.unwrap();
std::thread::sleep(Duration::from_millis(50));
// Bypass del cliente tipado: mandamos JSON inválido a mano.
use std::io::{BufRead, BufReader, Write};
let mut stream = UnixStream::connect(&socket).unwrap();
stream.write_all(b"not json\n").unwrap();
stream.flush().unwrap();
let mut reader = BufReader::new(stream);
let mut response = String::new();
reader.read_line(&mut response).unwrap();
assert!(
response.contains("\"error\""),
"esperaba ErrorResponse, got: {response}"
);
let _ = std::fs::remove_file(&socket);
}
}
02_ruway/chasqui/chasqui-core/src/lib.rs
+34
View File
@@ -0,0 +1,34 @@
//! `chasqui-core` — el explorador de Mónadas.
//!
//! Implementa la pipeline determinista descrita en el diseño de Kairos:
//!
//! 1. [`scanner`]: recorre directorios y emite [`FileEntry`] (sin tocar
//! contenido en Phase 0 — sólo metadatos).
//! 2. [`cluster`]: agrupa archivos en [`MonadManifest`] usando
//! heurísticas (parent dir + extensión dominante). 0 LLM.
//! 3. [`db`]: store en memoria con índices files↔monads.
//!
//! Pipeline:
//! ```text
//! scan_directory(path)
//! → Vec<FileEntry>
//! → cluster::by_directory(min_files=N)
//! → Vec<MonadManifest>
//! → MonadDb::ingest(...)
//! ```
//!
//! Lo importante: en este crate no hay IA, no hay embeddings. Es la
//! capa determinista que cubre el 90% de los casos. Los embeddings
//! (`Phase C`) y Nous (`Phase D`) se enchufan después como módulos
//! separados que producen flows brahman.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
pub mod cluster;
pub mod db;
pub mod embed;
pub mod engine_socket;
pub mod scanner;
pub use chasqui_card::*;
02_ruway/chasqui/chasqui-core/src/scanner.rs
+178
View File
@@ -0,0 +1,178 @@
//! Recorrido de directorios. Sólo metadatos — no lee contenido.
//!
//! Usa `walkdir` (sequential). Para árboles muy grandes considerar
//! migrar a `jwalk` (paralelo); por ahora la simplicidad gana.
use std::path::{Path, PathBuf};
use std::time::UNIX_EPOCH;
use chasqui_card::{FileEntry, FileId};
use thiserror::Error;
use ulid::Ulid;
use walkdir::WalkDir;
#[derive(Debug, Error)]
pub enum ScanError {
#[error("ruta no existe: {0}")]
NotFound(PathBuf),
#[error("no se pudo leer: {0}")]
Walk(String),
}
/// Configuración del scan.
#[derive(Debug, Clone)]
pub struct ScanConfig {
/// Profundidad máxima (None = ilimitada).
pub max_depth: Option<usize>,
/// Sigue symlinks (default: false, evita ciclos).
pub follow_links: bool,
/// Ignora archivos ocultos (.dotfiles).
pub skip_hidden: bool,
}
impl Default for ScanConfig {
fn default() -> Self {
Self {
max_depth: None,
follow_links: false,
skip_hidden: true,
}
}
}
/// Recorre `root` y devuelve un `FileEntry` por cada archivo regular.
/// Errores de permisos en sub-paths se ignoran silenciosamente.
pub fn scan_directory(root: &Path, config: &ScanConfig) -> Result<Vec<FileEntry>, ScanError> {
if !root.exists() {
return Err(ScanError::NotFound(root.to_path_buf()));
}
let mut walker = WalkDir::new(root).follow_links(config.follow_links);
if let Some(d) = config.max_depth {
walker = walker.max_depth(d);
}
let mut entries = Vec::new();
for entry_result in walker {
let entry = match entry_result {
Ok(e) => e,
Err(_) => continue,
};
if !entry.file_type().is_file() {
continue;
}
if config.skip_hidden && is_hidden(entry.path()) {
continue;
}
let metadata = match entry.metadata() {
Ok(m) => m,
Err(_) => continue,
};
let mtime_ms = metadata
.modified()
.ok()
.and_then(|t| t.duration_since(UNIX_EPOCH).ok())
.map(|d| d.as_millis() as u64)
.unwrap_or(0);
let extension = entry
.path()
.extension()
.and_then(|s| s.to_str())
.map(|s| s.to_lowercase());
entries.push(FileEntry {
id: FileId::from(Ulid::new()),
path: entry.path().to_path_buf(),
content_hash: None,
size: metadata.len(),
mtime_ms,
extension,
});
}
Ok(entries)
}
/// `true` si alguno de los componentes del path empieza con `.`.
/// Excluye el primer componente (root) para no descartar el directorio raíz
/// si el usuario apuntó a un dotfile-dir explícito.
fn is_hidden(path: &Path) -> bool {
path.file_name()
.and_then(|n| n.to_str())
.map(|n| n.starts_with('.'))
.unwrap_or(false)
}
#[cfg(test)]
mod tests {
use super::*;
use std::fs;
fn write(path: &Path, content: &str) {
if let Some(parent) = path.parent() {
fs::create_dir_all(parent).unwrap();
}
fs::write(path, content).unwrap();
}
#[test]
fn scans_basic_tree() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path();
write(&root.join("a.rs"), "fn main(){}");
write(&root.join("b.rs"), "fn b(){}");
write(&root.join("data/x.json"), "{}");
write(&root.join("data/y.json"), "{}");
let files = scan_directory(root, &ScanConfig::default()).unwrap();
assert_eq!(files.len(), 4);
let exts: std::collections::BTreeSet<_> = files
.iter()
.filter_map(|f| f.extension.clone())
.collect();
assert!(exts.contains("rs"));
assert!(exts.contains("json"));
}
#[test]
fn skips_hidden_by_default() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path();
write(&root.join("visible.txt"), "x");
write(&root.join(".hidden"), "x");
let files = scan_directory(root, &ScanConfig::default()).unwrap();
assert_eq!(files.len(), 1);
assert!(files[0].path.ends_with("visible.txt"));
}
#[test]
fn missing_root_errors() {
let p = std::path::Path::new("/nonexistent-12345-abc");
assert!(matches!(
scan_directory(p, &ScanConfig::default()),
Err(ScanError::NotFound(_))
));
}
#[test]
fn max_depth_limits() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path();
write(&root.join("top.txt"), "x");
write(&root.join("a/b/deep.txt"), "x");
let cfg = ScanConfig {
max_depth: Some(1),
..Default::default()
};
let files = scan_directory(root, &cfg).unwrap();
// max_depth=1 incluye archivos en root pero no anidados profundos.
let names: Vec<_> = files
.iter()
.filter_map(|f| f.path.file_name().and_then(|s| s.to_str()))
.map(String::from)
.collect();
assert!(names.contains(&"top.txt".to_string()));
assert!(!names.contains(&"deep.txt".to_string()));
}
}
02_ruway/chasqui/chasqui-explorer-llimphi/Cargo.toml
+28
View File
@@ -0,0 +1,28 @@
[package]
name = "chasqui-explorer-llimphi"
version.workspace = true
edition.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Explorador Llimphi de Mónadas: panel que descubre al daemon chasqui vía broker brahman y consulta sus Mónadas dinámicamente. Reemplazo del `chasqui-explorer` GPUI; el discovery (card-sidecar) y el cliente de query no cambian, sólo el frontend."
[dependencies]
card-core = { workspace = true }
card-sidecar = { path = "../card-sidecar" }
chasqui-card = { path = "../chasqui-card" }
llimphi-ui = { workspace = true }
llimphi-theme = { workspace = true }
llimphi-widget-app-header = { workspace = true }
llimphi-widget-banner = { workspace = true }
llimphi-widget-card = { workspace = true }
llimphi-widget-menubar = { workspace = true }
llimphi-widget-context-menu = { workspace = true }
llimphi-motion = { workspace = true }
app-bus = { workspace = true }
rimay-localize = { workspace = true }
wawa-config = { workspace = true }
[[bin]]
name = "chasqui-explorer-llimphi"
path = "src/main.rs"
02_ruway/chasqui/chasqui-explorer-llimphi/LEEME.md
+16
View File
@@ -0,0 +1,16 @@
# chasqui-explorer-llimphi
> UI Llimphi: log de mensajes en vivo del broker de [chasqui](../README.md).
Filtros por topic + autor + schema; pause/resume del stream; inspección del mensaje en detalle. Útil para debug de protocolos entre apps.
## Uso
```sh
cargo run --release -p chasqui-explorer-llimphi
```
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous-real`](../chasqui-nous-real/README.md)
- [`llimphi-ui`](../../llimphi/) + widgets `list`, `text-area`
02_ruway/chasqui/chasqui-explorer-llimphi/README.md
+16
View File
@@ -0,0 +1,16 @@
# chasqui-explorer-llimphi
> Llimphi UI: live message log of [chasqui](../README.md)'s broker.
Filters by topic + author + schema; pause/resume the stream; inspect message detail. Useful for debugging protocols between apps.
## Usage
```sh
cargo run --release -p chasqui-explorer-llimphi
```
## Deps
- [`chasqui-core`](../chasqui-core/README.md), [`chasqui-nous-real`](../chasqui-nous-real/README.md)
- [`llimphi-ui`](../../llimphi/) + widgets `list`, `text-area`
02_ruway/chasqui/chasqui-explorer-llimphi/src/main.rs
+800
View File
@@ -0,0 +1,800 @@
//! `chasqui-explorer-llimphi` — panel Llimphi que descubre al daemon
//! `chasqui` vía broker brahman y muestra sus Mónadas en vivo.
//!
//! Diseño: ventana standalone que cada N segundos consulta el query
//! socket del daemon (`chasqui_card::query::client::list_monads`). El
//! path del socket NO está hardcoded — se descubre vía
//! `card_sidecar::await_provider_blocking` para el flow
//! `monad-list:json`. Si el daemon cae, el socket cacheado se invalida
//! y la próxima iteración re-descubre.
//!
//! Sin integración con nahual-shell — es su propio binario para que el
//! ecosistema sea visible incluso sin la shell completa.
//!
//! Uso:
//! ```sh
//! cargo run -p chasqui-explorer-llimphi
//! # con override del init socket (heredado de brahman-handshake):
//! BRAHMAN_INIT_SOCKET=/tmp/init.sock cargo run -p chasqui-explorer-llimphi
//! ```
#![forbid(unsafe_code)]
use std::path::PathBuf;
use std::time::Duration;
use card_sidecar::{await_provider_blocking, build_consumer_card, ConsumerError};
use chasqui_card::query::client as query_client;
use chasqui_card::query::{transport, ListMonadsResponse, FLOW_MONAD_LIST, FLOW_TYPE_NAME};
use chasqui_card::Lens;
use llimphi_theme::Theme;
use llimphi_ui::llimphi_layout::taffy::{
prelude::{length, percent, AlignItems, Dimension, FlexDirection, Size, Style},
Rect,
};
use llimphi_ui::llimphi_raster::peniko::Color;
use llimphi_ui::llimphi_text::Alignment;
use llimphi_ui::{App, Handle, Key, KeyEvent, KeyState, NamedKey, View};
use llimphi_motion::{animate, motion, Tween};
use llimphi_widget_app_header::{app_header, AppHeaderPalette};
use llimphi_widget_banner::{banner_view, BannerKind};
use llimphi_widget_card::{card_view, CardOptions, CardPalette};
use llimphi_widget_context_menu::{
context_menu_view, ContextMenuItem, ContextMenuPalette, ContextMenuSpec,
};
use llimphi_widget_menubar::{
menubar_command_at, menubar_nav, menubar_overlay_animated, menubar_view, MenuBarSpec,
DEFAULT_HEIGHT as MENU_H,
};
use app_bus::{AppMenu, Menu, MenuItem};
use std::sync::Arc;
const REFRESH_INTERVAL: Duration = Duration::from_secs(2);
const DISCOVERY_TIMEOUT: Duration = Duration::from_secs(3);
const QUERY_TIMEOUT: Duration = Duration::from_secs(2);
struct Model {
theme: Theme,
socket: Option<PathBuf>,
snapshot: Option<ListMonadsResponse>,
error: Option<String>,
/// Última fuente del socket activo: "discovery"/"broker"/"cache"/
/// "default-path". Sólo informativo en el header.
socket_source: Option<&'static str>,
/// Barra de menú principal: índice del menú raíz abierto (`None`
/// cerrado).
menu_open: Option<usize>,
/// Fila activa dentro del dropdown abierto (`usize::MAX` = ninguna).
menu_active: usize,
/// Animación de aparición del dropdown.
menu_anim: Tween<f32>,
/// Mónada seleccionada (índice en `snapshot.monads`). `None` si
/// ninguna. La selección sólo resalta y habilita el menú contextual;
/// el explorer es de sólo lectura.
selected: Option<usize>,
/// Menú contextual sobre una Mónada: `(idx, x, y)` ancla en ventana.
/// `None` cerrado.
context_menu: Option<(usize, f32, f32)>,
}
#[derive(Clone)]
enum Msg {
Tick,
Refresh(TickOutcome),
/// Barra de menú principal: abrir/cerrar un menú raíz (`None` cerrar).
MenuOpen(Option<usize>),
/// Comando elegido en el menú principal — se traduce al `Msg` real.
MenuCommand(String),
/// Navega la fila activa del dropdown (+1/-1).
MenuNav(i32),
/// Ejecuta el comando de la fila activa (Enter).
MenuActivate,
/// No-op: sólo fuerza re-render durante la animación del dropdown.
MenuTick,
/// Cierra cualquier menú abierto (click-fuera / Esc).
CloseMenus,
/// Cicla el tema claro/oscuro.
CycleTheme,
/// Fuerza re-descubrimiento del socket: invalida el cacheado y
/// dispara un Tick. Mapea "Reconectar" del menú Ver.
Reconnect,
/// Selecciona una Mónada por índice (resalta).
SelectMonad(usize),
/// Right-click en la raíz → abre el menú contextual anclado en
/// `(x, y)` de ventana sobre la Mónada seleccionada. Sin selección
/// es no-op.
ContextMenuOpen(f32, f32),
}
#[derive(Clone)]
enum TickOutcome {
Ok {
socket: PathBuf,
source: &'static str,
snapshot: Box<ListMonadsResponse>,
},
DiscoveryFailed(String),
QueryFailed(String),
}
struct Explorer;
impl App for Explorer {
type Model = Model;
type Msg = Msg;
fn title() -> &'static str {
"Chasqui — Mónadas"
}
fn initial_size() -> (u32, u32) {
(900, 640)
}
fn init(handle: &Handle<Msg>) -> Model {
// Cargar el idioma global del SO al arrancar.
let wawa_cfg = wawa_config::WawaConfig::load();
let _ = rimay_localize::set_locale(&wawa_cfg.lang);
// Primer refresh inmediato + ticks periódicos. El tick dispara
// discovery+query en un thread (vía `Handle::spawn` desde
// update); así el broker bloqueante no congela el UI.
handle.dispatch(Msg::Tick);
handle.spawn_periodic(REFRESH_INTERVAL, || Msg::Tick);
Model {
theme: Theme::dark(),
socket: None,
snapshot: None,
error: None,
socket_source: None,
menu_open: None,
menu_active: usize::MAX,
menu_anim: Tween::idle(1.0),
selected: None,
context_menu: None,
}
}
fn on_key(model: &Model, event: &KeyEvent) -> Option<Msg> {
if event.state != KeyState::Pressed {
return None;
}
// Menú principal abierto: las flechas navegan. ←/→ cambian de menú
// raíz (wrap), ↑/↓ mueven la fila activa, Enter ejecuta, Esc cierra.
if let Some(mi) = model.menu_open {
let n = app_menu().menus.len().max(1);
return match &event.key {
Key::Named(NamedKey::Escape) => Some(Msg::CloseMenus),
Key::Named(NamedKey::ArrowLeft) => Some(Msg::MenuOpen(Some((mi + n - 1) % n))),
Key::Named(NamedKey::ArrowRight) => Some(Msg::MenuOpen(Some((mi + 1) % n))),
Key::Named(NamedKey::ArrowDown) => Some(Msg::MenuNav(1)),
Key::Named(NamedKey::ArrowUp) => Some(Msg::MenuNav(-1)),
Key::Named(NamedKey::Enter) => Some(Msg::MenuActivate),
_ => None,
};
}
None
}
fn update(model: Model, msg: Msg, handle: &Handle<Msg>) -> Model {
let mut m = model;
match msg {
Msg::Tick => {
let prior_socket = m.socket.clone();
handle.spawn(move || Msg::Refresh(tick(prior_socket)));
}
Msg::Refresh(outcome) => match outcome {
TickOutcome::Ok { socket, source, snapshot } => {
m.socket = Some(socket);
m.socket_source = Some(source);
m.snapshot = Some(*snapshot);
m.error = None;
// Si la selección quedó fuera de rango tras el
// refresh, la descartamos.
let count = m.snapshot.as_ref().map(|s| s.monads.len()).unwrap_or(0);
if m.selected.map(|i| i >= count).unwrap_or(false) {
m.selected = None;
m.context_menu = None;
}
}
TickOutcome::DiscoveryFailed(msg) => {
m.socket = None;
m.socket_source = None;
m.error = Some(msg);
}
TickOutcome::QueryFailed(msg) => {
// Invalida el socket cacheado: la próxima iteración
// re-descubre.
m.socket = None;
m.socket_source = None;
m.error = Some(msg);
}
},
Msg::MenuOpen(which) => {
m.menu_open = which;
// Abrir un menú raíz cierra cualquier contextual.
m.context_menu = None;
m.menu_active = usize::MAX;
if which.is_some() {
m.menu_anim = Tween::new(0.0, 1.0, motion::FAST, motion::ease_out_cubic);
animate(handle, motion::FAST, || Msg::MenuTick);
}
}
Msg::MenuNav(dir) => {
if let Some(mi) = m.menu_open {
let menu = app_menu();
m.menu_active = menubar_nav(&menu, mi, m.menu_active, dir);
}
}
Msg::MenuActivate => {
if let Some(mi) = m.menu_open {
let menu = app_menu();
if let Some(cmd) = menubar_command_at(&menu, mi, m.menu_active) {
m.menu_open = None;
return handle_menu_command(m, &cmd, handle);
}
}
}
Msg::MenuTick => {}
Msg::CloseMenus => {
m.menu_open = None;
m.menu_active = usize::MAX;
m.context_menu = None;
}
Msg::MenuCommand(cmd) => {
m.menu_open = None;
m.menu_active = usize::MAX;
return handle_menu_command(m, &cmd, handle);
}
Msg::CycleTheme => {
m.theme = Theme::next_after(m.theme.name);
}
Msg::Reconnect => {
// Invalida el socket cacheado y re-dispara discovery.
m.socket = None;
m.socket_source = None;
m.error = None;
handle.dispatch(Msg::Tick);
}
Msg::SelectMonad(i) => {
m.selected = Some(i);
m.context_menu = None;
}
Msg::ContextMenuOpen(x, y) => {
// Sólo si hay una Mónada seleccionada válida.
let count = m.snapshot.as_ref().map(|s| s.monads.len()).unwrap_or(0);
if let Some(i) = m.selected.filter(|i| *i < count) {
m.menu_open = None;
m.context_menu = Some((i, x, y));
}
}
}
m
}
fn view(model: &Model) -> View<Msg> {
let theme = &model.theme;
let menu = app_menu();
let menubar = menubar_view(&menubar_spec(&menu, model, theme));
let header_palette = AppHeaderPalette::from_theme(theme);
let card_palette = CardPalette::from_theme(theme);
// Acentos por kind del dominio chasqui: engine cyan, data
// purple. Señales semánticas locales del explorer.
let accent_engine = Color::from_rgba8(0x88, 0xc0, 0xd0, 0xff);
let accent_data = Color::from_rgba8(0xb4, 0x8e, 0xad, 0xff);
let header_text = match (&model.snapshot, &model.socket, model.socket_source) {
(Some(s), Some(sock), Some(src)) => {
let watching = s
.engine
.watching
.as_deref()
.map(|w| {
rimay_localize::t_args(
"chasqui-header-watching",
&[("name", w.into())],
)
})
.unwrap_or_default();
rimay_localize::t_args(
"chasqui-header",
&[
("engine", s.engine.label.as_str().into()),
("count", s.monads.len().to_string().into()),
("socket", sock.display().to_string().into()),
("src", src.into()),
("watching", watching.into()),
],
)
}
_ => rimay_localize::t("chasqui-header-searching"),
};
let header = app_header::<Msg>(header_text, vec![], &header_palette);
let mut body_children: Vec<View<Msg>> = Vec::new();
if let Some(ref e) = model.error {
body_children.push(banner_view::<Msg>(BannerKind::Error, e.clone()));
}
if let Some(snap) = &model.snapshot {
body_children.push(engine_card(snap, accent_engine, theme, &card_palette));
for (i, m) in snap.monads.iter().enumerate() {
let selected = model.selected == Some(i);
let card = monad_card(m, accent_data, theme, &card_palette);
// Click selecciona la Mónada. El menú contextual se abre
// por right-click en la raíz (coords de ventana) sobre la
// selección actual — ver `view()`.
let card = card.on_click(Msg::SelectMonad(i));
let card = if selected {
// Resalte sutil de la card seleccionada.
card.fill(theme.bg_selected)
} else {
card
};
body_children.push(card);
}
}
let body = View::new(Style {
flex_direction: FlexDirection::Column,
size: Size {
width: percent(1.0_f32),
height: Dimension::auto(),
},
flex_grow: 1.0,
padding: Rect {
left: length(16.0_f32),
right: length(16.0_f32),
top: length(12.0_f32),
bottom: length(16.0_f32),
},
gap: Size {
width: length(0.0_f32),
height: length(8.0_f32),
},
..Default::default()
})
.fill(theme.bg_app)
.children(body_children);
View::new(Style {
flex_direction: FlexDirection::Column,
size: Size {
width: percent(1.0_f32),
height: percent(1.0_f32),
},
..Default::default()
})
.fill(theme.bg_app)
// Right-click en la raíz (origen 0,0 ⇒ local == ventana) abre el
// menú contextual sobre la Mónada seleccionada.
.on_right_click_at(|x, y, _w, _h| Some(Msg::ContextMenuOpen(x, y)))
.children(vec![menubar, header, body])
}
fn view_overlay(model: &Model) -> Option<View<Msg>> {
// El menú contextual de la Mónada tiene prioridad si está abierto.
if let Some((idx, x, y)) = model.context_menu {
let label = model
.snapshot
.as_ref()
.and_then(|s| s.monads.get(idx))
.map(|m| m.label.clone())
.unwrap_or_else(|| rimay_localize::t("chasqui-explorer-monad-label"));
let viewport = viewport_of(model);
// Acciones reales del explorer: ver/seleccionar y refrescar.
// El explorer es de sólo lectura, no inventamos edición.
let t = rimay_localize::t;
let items = vec![
ContextMenuItem::action(t("chasqui-explorer-ctx-detail")),
ContextMenuItem::action(t("refresh")),
];
let on_pick: Arc<dyn Fn(usize) -> Msg + Send + Sync> = Arc::new(move |i: usize| match i {
0 => Msg::SelectMonad(idx),
_ => Msg::Tick,
});
return Some(context_menu_view(ContextMenuSpec {
anchor: (x, y),
viewport,
header: Some(label),
items,
active: usize::MAX,
on_pick,
on_dismiss: Msg::CloseMenus,
palette: ContextMenuPalette::from_theme(&model.theme),
}));
}
// Si no, el dropdown del menú principal.
let menu = app_menu();
menubar_overlay_animated(
&menubar_spec(&menu, model, &model.theme),
model.menu_active,
model.menu_anim.value(),
)
}
}
/// Viewport para clampear overlays: tamaño de ventana del Model si lo
/// llevara; como el explorer no lo trackea, usamos `initial_size()`.
fn viewport_of(_model: &Model) -> (f32, f32) {
let (w, h) = Explorer::initial_size();
(w as f32, h as f32)
}
/// Arma el `MenuBarSpec` compartido por `menubar_view` y `menubar_overlay`.
fn menubar_spec<'a>(
menu: &'a AppMenu,
model: &Model,
theme: &'a Theme,
) -> MenuBarSpec<'a, Msg> {
MenuBarSpec {
menu,
open: model.menu_open,
theme,
viewport: viewport_of(model),
height: MENU_H,
on_open: Arc::new(Msg::MenuOpen),
on_command: Arc::new(|c: &str| Msg::MenuCommand(c.to_string())),
}
}
/// El menú principal del explorer. Archivo / Ver / Ayuda — sólo comandos
/// que mapean a acciones reales (refrescar, reconectar, tema). Sin
/// "Editar": el explorer no tiene campos de texto editables.
fn app_menu() -> AppMenu {
let t = rimay_localize::t;
// Menú de idioma: autónimos sin traducir (convención del SO). El item
// activo lleva ✔. El comando `lang.<code>` lo resuelve `handle_menu_command`.
let cur = rimay_localize::current_locale();
let lang_item = |label: &str, code: &str| {
let mut it = MenuItem::new(label, format!("lang.{code}"));
if cur == code {
it = it.icon("\u{2714}");
}
it
};
AppMenu::new()
.menu(
Menu::new(t("file"))
.item(MenuItem::new(t("refresh"), "file.refresh").shortcut("Ctrl+R"))
.item(MenuItem::new(t("exit"), "file.quit").shortcut("Ctrl+Q").separated()),
)
.menu(
Menu::new(t("view"))
.item(MenuItem::new(t("reconnect"), "view.reconnect"))
.item(MenuItem::new(t("cycle-theme"), "view.theme").separated()),
)
.menu(Menu::new(t("help")).item(MenuItem::new(t("about"), "help.about")))
.menu(
Menu::new(t("language"))
.item(lang_item("Español", "es-PE"))
.item(lang_item("English", "en-US"))
.item(lang_item("Runasimi", "qu-PE")),
)
}
/// Traduce un command id del menú principal al `Msg`/efecto real.
fn handle_menu_command(model: Model, cmd: &str, handle: &Handle<Msg>) -> Model {
// Cambio de idioma desde el menú "Idioma": aplica el locale en caliente
// y lo persiste en la capa de usuario de wawa-config.
if let Some(code) = cmd.strip_prefix("lang.") {
let _ = rimay_localize::set_locale(code);
let mut cfg = wawa_config::WawaConfig::load();
cfg.lang = code.to_string();
let _ = cfg.save();
return model;
}
match cmd {
"file.refresh" => {
handle.dispatch(Msg::Tick);
model
}
"file.quit" => std::process::exit(0),
"view.reconnect" => {
handle.dispatch(Msg::Reconnect);
model
}
"view.theme" => {
handle.dispatch(Msg::CycleTheme);
model
}
// "help.about" y desconocidos: no-op (sin diálogo todavía).
_ => model,
}
}
fn engine_card(
snap: &ListMonadsResponse,
accent: Color,
theme: &Theme,
palette: &CardPalette,
) -> View<Msg> {
let mut rows: Vec<View<Msg>> = vec![
kind_row("[engine]", &snap.engine.label, accent, theme),
muted_line(
&rimay_localize::t_args(
"chasqui-field-id",
&[("id", snap.engine.id.to_string().into())],
),
theme,
),
];
if let Some(w) = &snap.engine.watching {
rows.push(muted_line(
&rimay_localize::t_args(
"chasqui-field-watching",
&[("name", w.as_str().into())],
),
theme,
));
}
card_view(
rows,
CardOptions {
accent: Some(accent),
..Default::default()
},
palette,
)
}
fn monad_card(
m: &chasqui_card::query::MonadView,
accent: Color,
theme: &Theme,
palette: &CardPalette,
) -> View<Msg> {
let lens = lens_label(m.dominant_lens);
let stats = rimay_localize::t_args(
"chasqui-explorer-monad-stats",
&[
("count", m.cardinality.to_string().into()),
("entropy", format!("{:.2}", m.entropy).into()),
("lens", lens.into()),
],
);
let mut rows: Vec<View<Msg>> = vec![
kind_row_with_stats("[monad]", &m.label, &stats, accent, theme),
muted_line(
&rimay_localize::t_args(
"chasqui-field-id",
&[("id", m.id.to_string().into())],
),
theme,
),
];
if !m.summary.is_empty() {
rows.push(text_line(&m.summary, theme.fg_text, theme));
}
let keywords = m.keywords.join(", ");
if !keywords.is_empty() {
rows.push(muted_line(
&rimay_localize::t_args(
"chasqui-field-keywords",
&[("keywords", keywords.as_str().into())],
),
theme,
));
}
if let Some(p) = m.path_hint.as_deref().filter(|p| !p.is_empty()) {
rows.push(muted_line(
&rimay_localize::t_args("chasqui-field-path", &[("path", p.into())]),
theme,
));
}
if let Some(model_name) = m.centroid_model.as_deref().filter(|s| !s.is_empty()) {
rows.push(muted_line(
&rimay_localize::t_args("chasqui-field-model", &[("name", model_name.into())]),
theme,
));
}
card_view(
rows,
CardOptions {
accent: Some(accent),
..Default::default()
},
palette,
)
}
fn kind_row(tag: &str, label: &str, accent: Color, theme: &Theme) -> View<Msg> {
View::new(Style {
flex_direction: FlexDirection::Row,
size: Size {
width: percent(1.0_f32),
height: length(20.0_f32),
},
align_items: Some(AlignItems::Center),
gap: Size {
width: length(8.0_f32),
height: length(0.0_f32),
},
..Default::default()
})
.children(vec![
View::new(Style {
size: Size {
width: length(72.0_f32),
height: length(16.0_f32),
},
..Default::default()
})
.text_aligned(tag.to_string(), 11.0, accent, Alignment::Start),
View::new(Style {
size: Size {
width: percent(1.0_f32),
height: length(18.0_f32),
},
flex_grow: 1.0,
..Default::default()
})
.text_aligned(label.to_string(), 15.0, theme.fg_text, Alignment::Start),
])
}
fn kind_row_with_stats(
tag: &str,
label: &str,
stats: &str,
accent: Color,
theme: &Theme,
) -> View<Msg> {
View::new(Style {
flex_direction: FlexDirection::Row,
size: Size {
width: percent(1.0_f32),
height: length(20.0_f32),
},
align_items: Some(AlignItems::Center),
gap: Size {
width: length(8.0_f32),
height: length(0.0_f32),
},
..Default::default()
})
.children(vec![
View::new(Style {
size: Size {
width: length(72.0_f32),
height: length(16.0_f32),
},
..Default::default()
})
.text_aligned(tag.to_string(), 11.0, accent, Alignment::Start),
View::new(Style {
size: Size {
width: Dimension::auto(),
height: length(18.0_f32),
},
flex_grow: 1.0,
..Default::default()
})
.text_aligned(label.to_string(), 15.0, theme.fg_text, Alignment::Start),
View::new(Style {
size: Size {
width: Dimension::auto(),
height: length(16.0_f32),
},
..Default::default()
})
.text_aligned(stats.to_string(), 11.0, theme.fg_muted, Alignment::Start),
])
}
fn muted_line(text: &str, theme: &Theme) -> View<Msg> {
text_line(text, theme.fg_muted, theme)
}
fn text_line(text: &str, color: Color, _theme: &Theme) -> View<Msg> {
View::new(Style {
size: Size {
width: percent(1.0_f32),
height: length(16.0_f32),
},
..Default::default()
})
.text_aligned(text.to_string(), 11.0, color, Alignment::Start)
}
fn tick(prior_socket: Option<PathBuf>) -> TickOutcome {
let (socket, source) = match prior_socket {
Some(p) => (p, "cache"),
None => match resolve_socket() {
Ok(found) => found,
Err(e) => return TickOutcome::DiscoveryFailed(e),
},
};
match query_client::list_monads(&socket, QUERY_TIMEOUT) {
Ok(resp) => TickOutcome::Ok {
socket,
source,
snapshot: Box::new(resp),
},
Err(e) => TickOutcome::QueryFailed(format!(
"query a {}: {e} — re-descubriendo en próxima iteración",
socket.display()
)),
}
}
/// Resuelve el socket del daemon en dos pasos:
/// 1. **Broker**: consumer Card + `await_provider_blocking`. Path
/// "consciente" (ecosistema brahman activo).
/// 2. **Default path**: si el broker no responde, probamos
/// `transport::default_socket_path()` directo. Path "soberano"
/// (daemon corriendo solo, sin init).
fn resolve_socket() -> Result<(PathBuf, &'static str), String> {
match discover_via_broker() {
Ok(p) => Ok((p, "broker")),
Err(broker_err) => {
let fallback = transport::default_socket_path();
if fallback.exists() {
Ok((fallback, "default-path"))
} else {
Err(format!(
"broker: {broker_err}; fallback {} no existe",
fallback.display()
))
}
}
}
}
fn discover_via_broker() -> Result<PathBuf, ConsumerError> {
let card = build_consumer_card("chasqui-explorer-llimphi", FLOW_MONAD_LIST, FLOW_TYPE_NAME);
await_provider_blocking(card, DISCOVERY_TIMEOUT)
}
fn lens_label(l: Lens) -> &'static str {
match l {
Lens::Grid => "grid",
Lens::Code => "code",
Lens::Gallery => "gallery",
Lens::Database => "database",
Lens::Markdown => "markdown",
Lens::Tree => "tree",
}
}
fn main() {
rimay_localize::init();
llimphi_ui::run::<Explorer>();
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn lens_labels_cover_all_variants() {
// Sanity: cualquier Lens devuelve un string no vacío.
for l in [
Lens::Grid,
Lens::Code,
Lens::Gallery,
Lens::Database,
Lens::Markdown,
Lens::Tree,
] {
assert!(!lens_label(l).is_empty());
}
}
#[test]
fn resolve_socket_fails_with_message_when_nothing_responds() {
// El test depende de que ni init socket ni default path tengan
// un daemon vivo — en CI sin daemon corriendo eso se cumple.
// Si en local hay un nouser vivo este test pasa por la rama Ok,
// sin assert estricto. La condición esencial: nunca panic.
let _ = resolve_socket();
}
}
02_ruway/chasqui/chasqui-nous-mock/Cargo.toml
+25
View File
@@ -0,0 +1,25 @@
[package]
name = "chasqui-nous-mock"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Nouser — Nous mock determinístico: implementa el contrato nouser-nous con pseudo-embeddings de Phase C. Stand-in para tests y para `BRAHMAN_BROKER_CONTEXT=test`."
[dependencies]
card-core = { workspace = true }
card-sidecar = { path = "../card-sidecar" }
chasqui-card = { path = "../chasqui-card" }
chasqui-core = { path = "../chasqui-core" }
chasqui-nous = { path = "../chasqui-nous" }
serde_json = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
tracing-subscriber = { workspace = true }
ulid = { workspace = true }
[[bin]]
name = "chasqui-nous-mock"
path = "src/main.rs"
02_ruway/chasqui/chasqui-nous-mock/LEEME.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-nous-mock
> Transport in-process para tests de [chasqui](../README.md).
Implementa [`Nous`](../chasqui-nous/README.md) usando canales `tokio::sync::mpsc` en memoria. Cero red. Tests deterministas.
## Deps
- [`chasqui-nous`](../chasqui-nous/README.md), [`chasqui-core`](../chasqui-core/README.md)
- `tokio`
02_ruway/chasqui/chasqui-nous-mock/README.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-nous-mock
> In-process transport for tests of [chasqui](../README.md).
Implements [`Nous`](../chasqui-nous/README.md) using in-memory `tokio::sync::mpsc` channels. Zero network. Deterministic tests.
## Deps
- [`chasqui-nous`](../chasqui-nous/README.md), [`chasqui-core`](../chasqui-core/README.md)
- `tokio`
02_ruway/chasqui/chasqui-nous-mock/src/main.rs
+247
View File
@@ -0,0 +1,247 @@
//! `chasqui-nous-mock` — proveedor de embeddings determinista (sin LLM).
//!
//! Implementa el contrato `chasqui-nous` usando los pseudo-embeddings
//! de Phase C (`chasqui_core::embed`). Sirve como:
//!
//! - **Mock para tests**: en `BRAHMAN_BROKER_CONTEXT=test`, el
//! `priority_offset` per-contexto declarado en su Card lo prioriza
//! sobre cualquier proveedor real.
//! - **Bootstrap**: hasta que llegue el LLM real (Phase D futura), el
//! sistema funciona end-to-end con embeddings determinísticos.
//!
//! ## Vida del proceso
//!
//! 1. Sidecarea a brahman-init declarando una Card con flow output
//! `embed-result:json` y flow input `embed-request:json`. Su
//! `priority_contexts.test = { priority_offset: +1 }` lo prioriza
//! cuando el broker corre bajo contexto test.
//! 2. Bind del Unix socket en `$NOUSER_NOUS_SOCKET` (default
//! `$XDG_RUNTIME_DIR/chasqui-nous.sock`).
//! 3. Loop: accept → read line JSON → process → write line JSON → close.
//! 4. Cada request se loggea (info) — útil para verificar que el
//! consumidor está usando este proveedor.
use std::collections::BTreeMap;
use std::path::PathBuf;
use std::time::{Instant, SystemTime, UNIX_EPOCH};
use card_core::{
ulid::Ulid, Card, CardKind, ContextBias, Flow, Flows, Lifecycle, Payload, Priority,
Supervision, TypeRef,
};
use chasqui_card::FileEntry;
use chasqui_core::embed;
use chasqui_nous::{
transport, EmbedFilePayload, EmbedRequest, EmbedResponse, EmbedTextPayload, ErrorResponse,
PingResponse, RequestKind, FLOW_EMBED_REQUEST, FLOW_EMBED_RESULT, FLOW_TYPE_NAME,
};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::net::{UnixListener, UnixStream};
use tracing::{info, warn};
/// El mock implementa el MISMO algoritmo que `chasqui_core::embed`,
/// así que reportamos el mismo `MODEL_ID` que él. De otro modo el
/// consumer filtraría las Mónadas como "modelo distinto" y los
/// scores quedarían vacíos.
const MODEL_ID: &str = chasqui_core::embed::MODEL_ID;
#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
init_tracing();
// 1. Resolver socket del data-plane ANTES de armar la Card, para
// declararlo en `Card.service_socket` y que los consumidores lo
// descubran vía MatchEvent.
let sock_path = transport::provider_socket_path("mock");
if sock_path.exists() {
std::fs::remove_file(&sock_path)?;
}
if let Some(parent) = sock_path.parent() {
std::fs::create_dir_all(parent)?;
}
let listener = UnixListener::bind(&sock_path)?;
info!(socket = %sock_path.display(), "chasqui-nous-mock escuchando");
// 2. Sidecar al brahman-init con la Card que declara el socket.
let card = build_card(sock_path.clone());
info!(label = %card.label, "publicando Card al brahman-init");
card_sidecar::spawn(card);
// 3. Accept loop.
loop {
let (stream, _addr) = listener.accept().await?;
tokio::spawn(async move {
if let Err(e) = handle_conn(stream).await {
warn!(error = %e, "conn falló");
}
});
}
}
fn init_tracing() {
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| "info".into()),
)
.with_target(false)
.compact()
.init();
}
/// Card que el mock anuncia al brahman-init. Es kind=Ente (un proceso),
/// con flujos JSON, bias de prioridad para contexto `test`, y el socket
/// data-plane declarado en `service_socket` (consumidores lo reciben
/// directo en el `MatchEvent::Available`).
fn build_card(service_socket: std::path::PathBuf) -> Card {
let mut priority_contexts = BTreeMap::new();
priority_contexts.insert(
"test".into(),
ContextBias {
pin_to: None,
// En contexto test, este mock gana sobre cualquier real-nous.
priority_offset: 1,
},
);
Card {
schema_version: card_core::CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: "chasqui.nous_mock".into(),
payload: Payload::Virtual,
supervision: Supervision::Delegate,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
kind: CardKind::Ente,
service_socket: Some(service_socket),
flow: Flows {
input: vec![Flow {
name: FLOW_EMBED_REQUEST.into(),
ty: TypeRef::Primitive {
name: FLOW_TYPE_NAME.into(),
},
pin_to: None,
}],
output: vec![Flow {
name: FLOW_EMBED_RESULT.into(),
ty: TypeRef::Primitive {
name: FLOW_TYPE_NAME.into(),
},
pin_to: None,
}],
},
priority_contexts,
..Default::default()
}
}
/// Procesa una conexión single-shot: lee una línea JSON, despacha,
/// escribe una línea JSON, cierra.
async fn handle_conn(stream: UnixStream) -> std::io::Result<()> {
let mut reader = BufReader::new(stream);
let mut line = String::new();
let n = reader.read_line(&mut line).await?;
if n == 0 {
return Ok(());
}
let req: EmbedRequest = match serde_json::from_str(&line) {
Ok(r) => r,
Err(e) => {
return write_error(reader.into_inner(), format!("JSON inválido: {e}")).await;
}
};
let started = Instant::now();
let result = match req.kind {
RequestKind::EmbedFile => handle_embed_file(req.payload, started),
RequestKind::EmbedText => handle_embed_text(req.payload, started),
RequestKind::Ping => handle_ping(),
};
let mut stream = reader.into_inner();
match result {
Ok(payload) => {
stream.write_all(payload.as_bytes()).await?;
stream.write_all(b"\n").await?;
}
Err(msg) => {
return write_error(stream, msg).await;
}
}
stream.shutdown().await?;
Ok(())
}
fn handle_embed_file(payload: serde_json::Value, started: Instant) -> Result<String, String> {
let p: EmbedFilePayload =
serde_json::from_value(payload).map_err(|e| format!("payload inválido: {e}"))?;
info!(path = %p.path, "embed_file");
let file = FileEntry {
id: chasqui_card::FileId::from(Ulid::new()),
path: PathBuf::from(p.path),
content_hash: None,
size: p.size,
mtime_ms: p.mtime_ms,
extension: p.extension,
};
let v = embed::embed(&file);
let resp = EmbedResponse {
embedding: v.to_vec(),
model: MODEL_ID.into(),
elapsed_ms: started.elapsed().as_millis() as u64,
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
fn handle_embed_text(payload: serde_json::Value, started: Instant) -> Result<String, String> {
let p: EmbedTextPayload =
serde_json::from_value(payload).map_err(|e| format!("payload inválido: {e}"))?;
info!(text_len = p.text.len(), "embed_text");
// Mock: tratamos el texto como un "stem" sintético y rellenamos el
// resto del vector con ceros. No es semánticamente útil, pero respeta
// la forma para que el cliente no se rompa.
let synthetic = FileEntry {
id: chasqui_card::FileId::from(Ulid::new()),
path: PathBuf::from(format!("synthetic://{}", p.text)),
content_hash: None,
size: p.text.len() as u64,
mtime_ms: now_ms(),
extension: Some("text".into()),
};
let v = embed::embed(&synthetic);
let resp = EmbedResponse {
embedding: v.to_vec(),
model: MODEL_ID.into(),
elapsed_ms: started.elapsed().as_millis() as u64,
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
fn handle_ping() -> Result<String, String> {
let resp = PingResponse {
model: MODEL_ID.into(),
embed_dim: embed::EMBED_DIM as u32,
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
async fn write_error(mut stream: UnixStream, msg: String) -> std::io::Result<()> {
warn!(error = %msg, "respuesta de error");
let resp = ErrorResponse { error: msg };
let json = serde_json::to_string(&resp).unwrap_or_else(|_| "{\"error\":\"encode\"}".into());
stream.write_all(json.as_bytes()).await?;
stream.write_all(b"\n").await?;
stream.shutdown().await?;
Ok(())
}
fn now_ms() -> u64 {
SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|d| d.as_millis() as u64)
.unwrap_or(0)
}
02_ruway/chasqui/chasqui-nous-real/Cargo.toml
+40
View File
@@ -0,0 +1,40 @@
[package]
name = "chasqui-nous-real"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Nouser — proveedor Nous con LLM real (text-embedding via ONNX). El soporte AI vive detrás del feature `embeddings`; sin él, este crate compila como stub mínimo."
[features]
# Sin features = stub que arranca y rechaza requests. Compila en
# segundos, sin descargar nada.
default = []
# Con feature embeddings: pulls fastembed + ONNX Runtime descargado.
# Modelo default: all-MiniLM-L6-v2 (384-d, ~80MB descargado al primer
# run y cacheado).
embeddings = ["dep:fastembed"]
[dependencies]
card-core = { workspace = true }
card-sidecar = { path = "../card-sidecar" }
arje-cas = { workspace = true }
chasqui-nous = { path = "../chasqui-nous" }
serde_json = { workspace = true }
sled = { workspace = true }
tokio = { workspace = true }
tracing = { workspace = true }
tracing-subscriber = { workspace = true }
ulid = { workspace = true }
# Opcional: gateado por feature `embeddings`.
fastembed = { version = "4", optional = true }
[dev-dependencies]
tempfile = { workspace = true }
[[bin]]
name = "chasqui-nous-real"
path = "src/main.rs"
02_ruway/chasqui/chasqui-nous-real/LEEME.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-nous-real
> Transport TCP/Unix binario de [chasqui](../README.md).
Implementa [`Nous`](../chasqui-nous/README.md) sobre `tokio` con framing length-prefix + serialización `postcard` (compacta, sin reflexión). Reconnect automático con backoff exponencial.
## Deps
- [`chasqui-nous`](../chasqui-nous/README.md), [`chasqui-core`](../chasqui-core/README.md)
- `tokio`, `postcard`
02_ruway/chasqui/chasqui-nous-real/README.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-nous-real
> Binary TCP/Unix transport of [chasqui](../README.md).
Implements [`Nous`](../chasqui-nous/README.md) over `tokio` with length-prefix framing + `postcard` serialization (compact, reflection-free). Automatic reconnect with exponential backoff.
## Deps
- [`chasqui-nous`](../chasqui-nous/README.md), [`chasqui-core`](../chasqui-core/README.md)
- `tokio`, `postcard`
02_ruway/chasqui/chasqui-nous-real/src/cache.rs
+199
View File
@@ -0,0 +1,199 @@
//! Cache de embeddings keyed por sha256 del contenido + model_id.
//!
//! Razón de existir: el modelo real (`fastembed-allMiniLML6V2`) es
//! caro (1-50 ms por archivo según tamaño y CPU). Cada vez que el
//! daemon de chasqui re-publica una Mónada o el watcher dispara un
//! re-cluster por cambio de FS, todos los archivos pasan otra vez
//! por embed. Para árboles de 1000 archivos, eso son segundos
//! desperdiciados re-embedidando contenido que no cambió.
//!
//! ## Diseño
//!
//! - **Cache key**: `sha256(bytes que el modelo realmente vio)` +
//! `MODEL_ID` (string). Usar el sha de los bytes-vistos garantiza
//! que la cache no devuelva un embedding de contenido viejo
//! simplemente porque el path no cambió.
//! - **Cache value**: el `Vec<f32>` serializado como bytes
//! little-endian (4 bytes por f32). Compacto, sin overhead de
//! bincode/postcard para datos numéricos puros.
//! - **Backend**: sled, tree único `embed_cache_v1`. Path:
//! `$XDG_CACHE_HOME/brahman/chasqui-nous-real-embed-cache.sled`.
//!
//! ## Versionado
//!
//! El nombre del tree (`embed_cache_v1`) es el "schema version" del
//! format value. Si bumpeamos a (p. ej.) almacenar también el
//! tiempo de cómputo o el ONNX session id, creamos `embed_cache_v2`
//! y el viejo queda como dato muerto que sled puede limpiar.
//!
//! El `MODEL_ID` viaja dentro del key, así que cambiar de modelo
//! invalida implícitamente las entradas viejas (no se accede más
//! a esos keys; sled las mantiene hasta GC manual).
use std::path::PathBuf;
/// Wrapper sobre sled::Db con la API justa que necesita `handle_file`.
#[derive(Clone)]
pub struct EmbedCache {
tree: sled::Tree,
}
impl EmbedCache {
/// Abre (o crea) la cache en su path canónico. El sled::Db queda
/// referenciado por el Tree; mientras `EmbedCache` viva, el DB
/// vive.
pub fn open() -> Result<Self, sled::Error> {
let path = default_path();
if let Some(parent) = path.parent() {
// best-effort: si no podemos crear el dir, sled falla con
// mensaje específico abajo.
let _ = std::fs::create_dir_all(parent);
}
let db = sled::open(&path)?;
let tree = db.open_tree("embed_cache_v1")?;
Ok(Self { tree })
}
/// Variante para tests: cache efímera bajo `dir`.
#[cfg(test)]
pub fn open_at(dir: &std::path::Path) -> Result<Self, sled::Error> {
let db = sled::open(dir)?;
let tree = db.open_tree("embed_cache_v1")?;
Ok(Self { tree })
}
/// Lookup. `None` si miss; `Some(vec)` si hit.
pub fn get(&self, file_sha: &[u8; 32], model_id: &str) -> Option<Vec<f32>> {
let key = build_key(file_sha, model_id);
let bytes = self.tree.get(&key).ok()??;
decode_embedding(&bytes)
}
/// Almacena. Errores se loggean pero no propagan — cache miss es
/// recuperable, no querés tirar el embed válido por fallo de I/O
/// de cache.
pub fn put(&self, file_sha: &[u8; 32], model_id: &str, embedding: &[f32]) {
let key = build_key(file_sha, model_id);
let bytes = encode_embedding(embedding);
if let Err(e) = self.tree.insert(key, bytes) {
tracing::warn!(error = %e, "embed-cache put falló (no-fatal)");
}
}
/// Cantidad actual de entradas (best-effort para logs).
pub fn len(&self) -> usize {
self.tree.len()
}
}
/// Path default. Honra `XDG_CACHE_HOME`, cae a `$HOME/.cache`, y de
/// último recurso a `/tmp` (sin persistencia, pero al menos no
/// crashea en entornos minimalistas como CI sin HOME).
fn default_path() -> PathBuf {
if let Ok(p) = std::env::var("NOUSER_NOUS_REAL_CACHE") {
return PathBuf::from(p);
}
let base = std::env::var("XDG_CACHE_HOME")
.ok()
.map(PathBuf::from)
.or_else(|| {
std::env::var("HOME")
.ok()
.map(|h| PathBuf::from(h).join(".cache"))
})
.unwrap_or_else(std::env::temp_dir);
base.join("brahman").join("chasqui-nous-real-embed-cache.sled")
}
fn build_key(file_sha: &[u8; 32], model_id: &str) -> Vec<u8> {
let mut k = Vec::with_capacity(32 + 1 + model_id.len());
k.extend_from_slice(file_sha);
// separator byte para que prefijos de model_id no choquen con
// bytes del sha (improbable pero barato).
k.push(0xff);
k.extend_from_slice(model_id.as_bytes());
k
}
fn encode_embedding(v: &[f32]) -> Vec<u8> {
let mut out = Vec::with_capacity(v.len() * 4);
for f in v {
out.extend_from_slice(&f.to_le_bytes());
}
out
}
fn decode_embedding(bytes: &[u8]) -> Option<Vec<f32>> {
if bytes.len() % 4 != 0 {
return None;
}
let mut out = Vec::with_capacity(bytes.len() / 4);
for chunk in bytes.chunks_exact(4) {
out.push(f32::from_le_bytes([chunk[0], chunk[1], chunk[2], chunk[3]]));
}
Some(out)
}
#[cfg(test)]
mod tests {
use super::*;
fn sha(s: &[u8]) -> [u8; 32] {
arje_cas::sha256_of(s)
}
#[test]
fn roundtrip_returns_same_vector() {
let dir = tempfile::tempdir().unwrap();
let cache = EmbedCache::open_at(dir.path()).unwrap();
let key = sha(b"hello world");
let v = vec![0.1f32, -0.5, 1.0, 3.14159];
cache.put(&key, "real-fastembed-allMiniLML6V2-384d", &v);
let got = cache
.get(&key, "real-fastembed-allMiniLML6V2-384d")
.expect("hit esperado");
assert_eq!(got, v);
}
#[test]
fn miss_returns_none() {
let dir = tempfile::tempdir().unwrap();
let cache = EmbedCache::open_at(dir.path()).unwrap();
let key = sha(b"never stored");
assert!(cache.get(&key, "real-fastembed-allMiniLML6V2-384d").is_none());
}
#[test]
fn different_models_do_not_collide() {
let dir = tempfile::tempdir().unwrap();
let cache = EmbedCache::open_at(dir.path()).unwrap();
let key = sha(b"same content");
cache.put(&key, "model-a", &[1.0, 2.0]);
cache.put(&key, "model-b", &[7.0, 8.0]);
assert_eq!(cache.get(&key, "model-a").unwrap(), vec![1.0, 2.0]);
assert_eq!(cache.get(&key, "model-b").unwrap(), vec![7.0, 8.0]);
}
#[test]
fn different_content_different_keys() {
let dir = tempfile::tempdir().unwrap();
let cache = EmbedCache::open_at(dir.path()).unwrap();
let k1 = sha(b"abc");
let k2 = sha(b"abd");
cache.put(&k1, "m", &[1.0]);
assert!(cache.get(&k2, "m").is_none());
}
#[test]
fn corrupted_value_returns_none() {
// Si sled devuelve bytes con length no múltiplo de 4, decode
// debe fallar limpio (None) en vez de panicar.
let dir = tempfile::tempdir().unwrap();
let cache = EmbedCache::open_at(dir.path()).unwrap();
let key = sha(b"x");
// Insertamos manualmente bytes inválidos.
let raw_key = build_key(&key, "m");
cache.tree.insert(raw_key, &[1u8, 2, 3][..]).unwrap();
assert!(cache.get(&key, "m").is_none());
}
}
02_ruway/chasqui/chasqui-nous-real/src/embeddings.rs
+205
View File
@@ -0,0 +1,205 @@
//! Modo embeddings: usa fastembed-rs (ONNX Runtime) para producir
//! vectores reales de text-embedding.
//!
//! Modelo default: `all-MiniLM-L6-v2` (384-d). Se descarga al primer
//! arranque a `~/.cache/fastembed` y queda cacheado.
//!
//! ## Mapeo del contrato
//!
//! - `EmbedText`: pasa el texto al modelo, devuelve el vector 384-d.
//! - `EmbedFile`: lee hasta los primeros 8 KiB del archivo, los
//! interpreta como UTF-8 con replacement-char, y los embeda como
//! texto. Para archivos binarios el resultado no es semánticamente
//! útil — caller decide qué hacer.
//! - `Ping`: devuelve `model_id` y `embed_dim` reales.
use std::fs::File;
use std::io::Read;
use std::path::PathBuf;
use std::sync::Arc;
use std::time::Instant;
use fastembed::{EmbeddingModel, InitOptions, TextEmbedding};
use chasqui_nous::{
EmbedFilePayload, EmbedRequest, EmbedResponse, EmbedTextPayload, ErrorResponse, PingResponse,
RequestKind,
};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::net::UnixStream;
use tracing::{info, warn};
use crate::cache::EmbedCache;
const MAX_FILE_BYTES: usize = 8192;
/// Backend concreto: posee el modelo cargado.
pub struct Backend {
model: TextEmbedding,
}
impl Backend {
pub fn init() -> Result<Self, String> {
info!("cargando modelo all-MiniLM-L6-v2 (puede descargar ~80MB la primera vez)");
let opts = InitOptions::new(EmbeddingModel::AllMiniLML6V2)
.with_show_download_progress(true);
let model = TextEmbedding::try_new(opts).map_err(|e| format!("fastembed init: {e}"))?;
info!("modelo listo");
Ok(Self { model })
}
fn embed_one(&self, text: &str) -> Result<Vec<f32>, String> {
let out = self
.model
.embed(vec![text], None)
.map_err(|e| format!("embed: {e}"))?;
out.into_iter()
.next()
.ok_or_else(|| "fastembed devolvió 0 vectores".to_string())
}
}
pub async fn handle_conn(
stream: UnixStream,
backend: Arc<Backend>,
cache: Option<EmbedCache>,
) -> std::io::Result<()> {
let mut reader = BufReader::new(stream);
let mut line = String::new();
let n = reader.read_line(&mut line).await?;
if n == 0 {
return Ok(());
}
let req: EmbedRequest = match serde_json::from_str(&line) {
Ok(r) => r,
Err(e) => {
return write_error(reader.into_inner(), format!("JSON inválido: {e}")).await;
}
};
let started = Instant::now();
let result = match req.kind {
RequestKind::EmbedFile => handle_file(req.payload, &backend, cache.as_ref(), started),
RequestKind::EmbedText => handle_text(req.payload, &backend, started),
RequestKind::Ping => handle_ping(),
};
let mut stream = reader.into_inner();
match result {
Ok(json) => {
stream.write_all(json.as_bytes()).await?;
stream.write_all(b"\n").await?;
}
Err(msg) => return write_error(stream, msg).await,
}
stream.shutdown().await?;
Ok(())
}
fn handle_text(
payload: serde_json::Value,
backend: &Backend,
started: Instant,
) -> Result<String, String> {
let p: EmbedTextPayload =
serde_json::from_value(payload).map_err(|e| format!("payload: {e}"))?;
info!(text_len = p.text.len(), "embed_text");
let v = backend.embed_one(&p.text)?;
let resp = EmbedResponse {
embedding: v,
model: super::model_id().to_string(),
elapsed_ms: started.elapsed().as_millis() as u64,
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
fn handle_file(
payload: serde_json::Value,
backend: &Backend,
cache: Option<&EmbedCache>,
started: Instant,
) -> Result<String, String> {
let p: EmbedFilePayload =
serde_json::from_value(payload).map_err(|e| format!("payload: {e}"))?;
let path = PathBuf::from(&p.path);
let mut file = File::open(&path).map_err(|e| format!("abrir archivo: {e}"))?;
let mut buf = vec![0u8; MAX_FILE_BYTES];
let n = file.read(&mut buf).map_err(|e| format!("leer archivo: {e}"))?;
buf.truncate(n);
let model_id = super::model_id();
// Hash de los bytes que el modelo realmente verá. Si el archivo
// crece pasada la ventana MAX_FILE_BYTES sin modificar la cabeza,
// el hash NO cambia — el embedding cacheado sigue siendo válido
// bajo la semántica del proveedor (el modelo nunca vio los bytes
// adicionales). Si la cabeza cambia, el hash cambia y caemos a
// re-embed naturalmente.
let file_sha = arje_cas::sha256_of(&buf);
if let Some(cache) = cache {
if let Some(cached) = cache.get(&file_sha, model_id) {
info!(
path = %p.path,
sha = %arje_cas::hex(&file_sha),
bytes = n,
"embed_file: cache HIT"
);
let resp = EmbedResponse {
embedding: cached,
model: model_id.to_string(),
elapsed_ms: started.elapsed().as_millis() as u64,
};
return serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"));
}
}
info!(
path = %p.path,
sha = %arje_cas::hex(&file_sha),
bytes = n,
"embed_file: cache MISS — invocando modelo"
);
// Write-through al CAS de arje: hacemos la cabeza del archivo
// direccionable por contenido. No es la fuente de verdad para
// el cache (sled lo es) pero deja un registro consultable por
// herramientas como `ente-cas gc` y permite que otros consumers
// resuelvan los bytes por hash.
if let Err(e) = arje_cas::store(&buf) {
// No-fatal: si CAS no escribe, cacheamos el embedding igual.
warn!(error = %e, "arje_cas::store falló (no-fatal)");
}
let text = String::from_utf8_lossy(&buf).to_string();
let v = backend.embed_one(&text)?;
if let Some(cache) = cache {
cache.put(&file_sha, model_id, &v);
}
let resp = EmbedResponse {
embedding: v,
model: model_id.to_string(),
elapsed_ms: started.elapsed().as_millis() as u64,
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
fn handle_ping() -> Result<String, String> {
let resp = PingResponse {
model: super::model_id().to_string(),
embed_dim: super::embed_dim(),
};
serde_json::to_string(&resp).map_err(|e| format!("encode: {e}"))
}
async fn write_error(mut stream: UnixStream, msg: String) -> std::io::Result<()> {
warn!(error = %msg, "respuesta de error");
let resp = ErrorResponse { error: msg };
let json = serde_json::to_string(&resp).unwrap_or_else(|_| "{\"error\":\"encode\"}".into());
stream.write_all(json.as_bytes()).await?;
stream.write_all(b"\n").await?;
stream.shutdown().await?;
Ok(())
}
02_ruway/chasqui/chasqui-nous-real/src/main.rs
+202
View File
@@ -0,0 +1,202 @@
//! `chasqui-nous-real` — proveedor Nous con LLM real (gated por feature).
//!
//! ## Build modes
//!
//! - `cargo build -p chasqui-nous-real`
//! Compila como **stub**: bin que arranca, sidecarea al brahman-init
//! pero rechaza toda request con un error explicando que falta la
//! feature. Útil para que `cargo build --workspace` no requiera ML
//! deps.
//!
//! - `cargo build -p chasqui-nous-real --features embeddings`
//! Compila con `fastembed` + ONNX Runtime descargado por Cargo.
//! Modelo default: `all-MiniLM-L6-v2` (384-d, ~80 MB descargado al
//! primer run y cacheado en `~/.cache/fastembed`).
//!
//! ## Diseño
//!
//! Mismo contrato wire que `chasqui-nous-mock` (`chasqui-nous` crate). La
//! diferencia operativa: real produce 384-d con semantic content
//! (text-embedding del modelo); mock produce 32-d con metadata-hashing.
//! No son intercambiables a media-deployment — los centroides de
//! Mónadas calculadas con uno NO matchean con el otro.
//!
//! La Card declara `priority_contexts.prod = { priority_offset: +1 }`,
//! contrapeso del mock que tiene `+1 en test`. Así el broker brahman
//! elige automáticamente:
//! - `BRAHMAN_BROKER_CONTEXT=test` → mock gana.
//! - `BRAHMAN_BROKER_CONTEXT=prod` → real gana.
//! - sin contexto → empate por label alfabético.
#![forbid(unsafe_code)]
use std::collections::BTreeMap;
use card_core::{
ulid::Ulid, Card, CardKind, ContextBias, Flow, Flows, Lifecycle, Payload, Priority,
Supervision, TypeRef,
};
use chasqui_nous::{transport, FLOW_EMBED_REQUEST, FLOW_EMBED_RESULT, FLOW_TYPE_NAME};
use tokio::net::UnixListener;
use tracing::info;
#[cfg(feature = "embeddings")]
mod cache;
#[cfg(feature = "embeddings")]
mod embeddings;
#[cfg(not(feature = "embeddings"))]
mod stub;
#[cfg(feature = "embeddings")]
const MODEL_ID: &str = "real-fastembed-allMiniLML6V2-384d";
#[cfg(not(feature = "embeddings"))]
const MODEL_ID: &str = "real-stub-no-feature";
#[cfg(feature = "embeddings")]
const EMBED_DIM: u32 = 384;
#[cfg(not(feature = "embeddings"))]
const EMBED_DIM: u32 = 0;
#[tokio::main(flavor = "current_thread")]
async fn main() -> std::io::Result<()> {
init_tracing();
#[cfg(not(feature = "embeddings"))]
info!(
"chasqui-nous-real corriendo en modo STUB (compilá con \
--features embeddings para activar el modelo)"
);
// 1. Resolver socket del data-plane (default `chasqui-nous-real.sock`,
// distinto del mock para coexistir).
let sock_path = transport::provider_socket_path("real");
if sock_path.exists() {
std::fs::remove_file(&sock_path)?;
}
if let Some(parent) = sock_path.parent() {
std::fs::create_dir_all(parent)?;
}
let listener = UnixListener::bind(&sock_path)?;
info!(socket = %sock_path.display(), "chasqui-nous-real escuchando");
// 2. Sidecar al brahman-init con Card declarando el socket.
let card = build_card(sock_path.clone());
info!(label = %card.label, mode = MODEL_ID, "publicando Card al brahman-init");
card_sidecar::spawn(card);
// 3. Inicializar el modelo (sólo en modo embeddings).
#[cfg(feature = "embeddings")]
let backend = embeddings::Backend::init().map_err(|e| {
std::io::Error::other(format!("init modelo: {e}"))
})?;
#[cfg(feature = "embeddings")]
let backend = std::sync::Arc::new(backend);
// 4. Abrir el cache de embeddings (sled local, sha256-keyed).
// Si falla, seguimos sin cache — degrada a "siempre embed".
#[cfg(feature = "embeddings")]
let embed_cache = match cache::EmbedCache::open() {
Ok(c) => {
info!(entries = c.len(), "embed-cache abierto");
Some(c)
}
Err(e) => {
tracing::warn!(error = %e, "embed-cache no disponible — todas las requests irán al modelo");
None
}
};
// 5. Accept loop.
loop {
let (stream, _addr) = listener.accept().await?;
#[cfg(feature = "embeddings")]
{
let backend = backend.clone();
let cache = embed_cache.clone();
tokio::spawn(async move {
if let Err(e) = embeddings::handle_conn(stream, backend, cache).await {
tracing::warn!(error = %e, "conn falló");
}
});
}
#[cfg(not(feature = "embeddings"))]
{
tokio::spawn(async move {
if let Err(e) = stub::handle_conn(stream).await {
tracing::warn!(error = %e, "conn falló");
}
});
}
}
}
fn init_tracing() {
tracing_subscriber::fmt()
.with_env_filter(
tracing_subscriber::EnvFilter::try_from_default_env()
.unwrap_or_else(|_| "info".into()),
)
.with_target(false)
.compact()
.init();
}
/// Card que real-nous anuncia. Idéntica al mock excepto por:
/// - label distinto (`chasqui.nous_real`) para que coexistan en el broker.
/// - `priority_contexts.prod = +1` (gana en contexto prod).
/// - `service_socket` propio para que clientes lo descubran directo.
fn build_card(service_socket: std::path::PathBuf) -> Card {
let mut priority_contexts = BTreeMap::new();
priority_contexts.insert(
"prod".into(),
ContextBias {
pin_to: None,
priority_offset: 1,
},
);
Card {
schema_version: card_core::CARD_SCHEMA_VERSION,
id: Ulid::new(),
label: "chasqui.nous_real".into(),
payload: Payload::Virtual,
supervision: Supervision::Delegate,
lifecycle: Lifecycle::Daemon,
priority: Priority::Normal,
kind: CardKind::Ente,
service_socket: Some(service_socket),
flow: Flows {
input: vec![Flow {
name: FLOW_EMBED_REQUEST.into(),
ty: TypeRef::Primitive {
name: FLOW_TYPE_NAME.into(),
},
pin_to: None,
}],
output: vec![Flow {
name: FLOW_EMBED_RESULT.into(),
ty: TypeRef::Primitive {
name: FLOW_TYPE_NAME.into(),
},
pin_to: None,
}],
},
priority_contexts,
..Default::default()
}
}
// Helpers compartidos. Anotados allow(dead_code) porque en stub mode
// algunos quedan sin uso pero los queremos disponibles consistentemente.
#[allow(dead_code)]
pub(crate) fn model_id() -> &'static str {
MODEL_ID
}
#[allow(dead_code)]
pub(crate) fn embed_dim() -> u32 {
EMBED_DIM
}
02_ruway/chasqui/chasqui-nous-real/src/stub.rs
+36
View File
@@ -0,0 +1,36 @@
//! Modo stub: arranca el bin pero rechaza las requests con un error
//! que explica que falta la feature `embeddings`.
use chasqui_nous::{EmbedRequest, ErrorResponse};
use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
use tokio::net::UnixStream;
use tracing::warn;
pub async fn handle_conn(stream: UnixStream) -> std::io::Result<()> {
let mut reader = BufReader::new(stream);
let mut line = String::new();
let n = reader.read_line(&mut line).await?;
if n == 0 {
return Ok(());
}
// Parseamos para validar la forma; igual rechazamos.
let _: Result<EmbedRequest, _> = serde_json::from_str(&line);
warn!("rechazando request en modo stub (feature `embeddings` ausente)");
let resp = ErrorResponse {
error: format!(
"chasqui-nous-real compilado sin la feature `embeddings`. \
Rebuild con: cargo build -p chasqui-nous-real --features embeddings"
),
};
let mut stream = reader.into_inner();
let payload = serde_json::to_string(&resp).unwrap_or_else(|_| {
"{\"error\":\"stub mode and serialization failed\"}".to_string()
});
stream.write_all(payload.as_bytes()).await?;
stream.write_all(b"\n").await?;
stream.shutdown().await?;
Ok(())
}
02_ruway/chasqui/chasqui-nous/Cargo.toml
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "chasqui-nous"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true
authors.workspace = true
publish.workspace = true
description = "Nouser — protocolo Nous: contrato JSON line-delimited entre nouser-core y los proveedores de embeddings (mock o LLM real)."
[dependencies]
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
02_ruway/chasqui/chasqui-nous/LEEME.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-nous
> Trait del transport de [chasqui](../README.md).
`Nous = transport`. Define cómo se mandan/reciben mensajes entre cliente y broker. Implementado por [`chasqui-nous-mock`](../chasqui-nous-mock/README.md) (in-process) y [`chasqui-nous-real`](../chasqui-nous-real/README.md) (TCP).
## Deps
- [`chasqui-core`](../chasqui-core/README.md)
- `async-trait`
02_ruway/chasqui/chasqui-nous/README.md
+10
View File
@@ -0,0 +1,10 @@
# chasqui-nous
> Transport trait of [chasqui](../README.md).
`Nous = transport`. Defines how messages are sent/received between client and broker. Implemented by [`chasqui-nous-mock`](../chasqui-nous-mock/README.md) (in-process) and [`chasqui-nous-real`](../chasqui-nous-real/README.md) (TCP).
## Deps
- [`chasqui-core`](../chasqui-core/README.md)
- `async-trait`
02_ruway/chasqui/chasqui-nous/src/lib.rs
+196
View File
@@ -0,0 +1,196 @@
//! `chasqui-nous` — el contrato del proveedor de embeddings.
//!
//! Define el wire-format compartido entre `chasqui-core` (consumidor) y
//! cualquier implementación de Nous (mock determinista o LLM real). El
//! protocolo es **line-delimited JSON** sobre Unix socket: cada conexión
//! envía una request, recibe una response, y cierra. Single-shot por
//! conexión, igual al admin de brahman.
//!
//! ## Contrato
//!
//! ```text
//! C → S: {"kind":"embed_file","payload":{...}}\n
//! S → C: {"embedding":[...],"model":"mock-pseudo-32d","elapsed_ms":1}\n
//! ```
//!
//! En caso de error:
//!
//! ```text
//! S → C: {"error":"unsupported kind"}\n
//! ```
//!
//! ## Por qué un crate aparte
//!
//! El consumidor (chasqui-core) y el proveedor (chasqui-nous-mock,
//! chasqui-nous-real) deben acordar en types EXACTOS. Tener el contrato
//! en su crate evita que cada lado declare structs paralelos que se
//! desincronizan. Si bumpeás el wire, bumpeás aquí.
//!
//! ## Swap por priority_contexts
//!
//! Cuando existan dos proveedores (mock-nous y real-nous), ambos declaran
//! el mismo `flow.output: { name: "embed-result", type: ... }` y
//! `flow.input: "embed-request"`. El broker brahman los matchea contra
//! los consumidores; el `priority_offset` per-contexto del Card hace que
//! mock-nous gane en `test` y real-nous en `prod`. chasqui-core sólo
//! consume el flow, sin saber cuál implementación corre.
#![forbid(unsafe_code)]
#![warn(rust_2018_idioms)]
use serde::{Deserialize, Serialize};
use thiserror::Error;
// =====================================================================
// Wire types
// =====================================================================
/// Request al proveedor Nous.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbedRequest {
pub kind: RequestKind,
pub payload: serde_json::Value,
}
/// Tipo de request. El payload se interpreta según el kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RequestKind {
/// payload = `EmbedFilePayload` (path + metadata mínima).
EmbedFile,
/// payload = `EmbedTextPayload` (string libre).
EmbedText,
/// payload = `{}`. Devuelve `PingResponse`.
Ping,
}
/// Payload para `EmbedFile`. Es la información mínima que el proveedor
/// necesita para producir un embedding de archivo determinista.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbedFilePayload {
pub path: String,
pub extension: Option<String>,
pub size: u64,
/// `mtime` en ms desde UNIX_EPOCH.
pub mtime_ms: u64,
}
/// Payload para `EmbedText`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbedTextPayload {
pub text: String,
}
/// Response exitosa con un embedding.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EmbedResponse {
/// Vector. Su longitud depende del modelo (mock=32, llama=384, etc.).
pub embedding: Vec<f32>,
/// Identificador del modelo que produjo el embedding (útil para logs
/// y para invalidar caches al cambiar de proveedor).
pub model: String,
/// Tiempo de cómputo en ms (proveedor lo reporta).
pub elapsed_ms: u64,
}
/// Response a Ping. Útil para health-checks y discovery.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PingResponse {
pub model: String,
pub embed_dim: u32,
}
/// Error retornado por el proveedor en lugar de una response normal.
#[derive(Debug, Clone, Serialize, Deserialize, Error)]
#[error("nous: {error}")]
pub struct ErrorResponse {
pub error: String,
}
// =====================================================================
// Transport
// =====================================================================
pub mod transport {
use std::path::PathBuf;
/// Variable de entorno para sobreescribir la ruta del socket.
pub const SOCKET_ENV: &str = "NOUSER_NOUS_SOCKET";
/// Nombre genérico del socket cuando hay un solo proveedor.
pub const SOCKET_NAME: &str = "chasqui-nous.sock";
/// Ruta canónica al socket cuando un único proveedor está activo
/// (consumidores que no quieren elegir).
pub fn default_socket_path() -> PathBuf {
if let Ok(p) = std::env::var(SOCKET_ENV) {
return PathBuf::from(p);
}
runtime_base().join(SOCKET_NAME)
}
/// Ruta default para un proveedor identificado (`"mock"`, `"real"`,
/// etc). Permite que mock y real coexistan sin clash de socket.
/// `NOUSER_NOUS_SOCKET` igual override esta función si está set.
pub fn provider_socket_path(provider: &str) -> PathBuf {
if let Ok(p) = std::env::var(SOCKET_ENV) {
return PathBuf::from(p);
}
runtime_base().join(format!("chasqui-nous-{}.sock", provider))
}
fn runtime_base() -> PathBuf {
std::env::var_os("XDG_RUNTIME_DIR")
.map(PathBuf::from)
.unwrap_or_else(std::env::temp_dir)
}
}
// =====================================================================
// Names compartidos para el broker brahman
// =====================================================================
/// Nombre del flow output del proveedor (entrada del consumidor).
pub const FLOW_EMBED_RESULT: &str = "embed-result";
/// Nombre del flow input del proveedor (salida del consumidor).
pub const FLOW_EMBED_REQUEST: &str = "embed-request";
/// Tipo del flow: el wire es JSON serializado, así que el TypeRef
/// declarado en la Card es `primitive::json`.
pub const FLOW_TYPE_NAME: &str = "json";
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn request_roundtrip_json() {
let req = EmbedRequest {
kind: RequestKind::EmbedFile,
payload: serde_json::to_value(EmbedFilePayload {
path: "/x/y.rs".into(),
extension: Some("rs".into()),
size: 1024,
mtime_ms: 1_700_000_000_000,
})
.unwrap(),
};
let s = serde_json::to_string(&req).unwrap();
let parsed: EmbedRequest = serde_json::from_str(&s).unwrap();
assert_eq!(parsed.kind, RequestKind::EmbedFile);
}
#[test]
fn response_roundtrip() {
let resp = EmbedResponse {
embedding: vec![0.1, 0.2, 0.3],
model: "mock-pseudo-32d".into(),
elapsed_ms: 1,
};
let s = serde_json::to_string(&resp).unwrap();
let parsed: EmbedResponse = serde_json::from_str(&s).unwrap();
assert_eq!(parsed.model, "mock-pseudo-32d");
assert_eq!(parsed.embedding.len(), 3);
}
}
Cargo.lock
Generated
+8292
View File
File diff suppressed because it is too large Load Diff
Cargo.toml
+448
View File
@@ -0,0 +1,448 @@
# Cargo.toml raíz STANDALONE de chasqui — front-door sobre Llimphi.
# Solo el código de chasqui; Llimphi y lo fundacional por git-dep del monorepo gioser.git.
[workspace]
resolver = "2"
members = [
"02_ruway/chasqui/card-admin",
"02_ruway/chasqui/card-handshake",
"02_ruway/chasqui/card-sidecar",
"02_ruway/chasqui/chasqui-broker",
"02_ruway/chasqui/chasqui-broker-explorer-llimphi",
"02_ruway/chasqui/chasqui-card",
"02_ruway/chasqui/chasqui-core",
"02_ruway/chasqui/chasqui-explorer-llimphi",
"02_ruway/chasqui/chasqui-nous",
"02_ruway/chasqui/chasqui-nous-mock",
"02_ruway/chasqui/chasqui-nous-real",
]
[workspace.package]
version = "0.1.0"
edition = "2021"
rust-version = "1.80"
license = "MIT"
authors = ["Sergio <gerencia@jlsoltech.com>"]
publish = false
repository = "https://gitea.gioser.net/sergio/chasqui"
[workspace.dependencies]
# === Registro de apps / menú global ===
app-bus = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# === Serialización ===
serde = { version = "1", features = ["derive"] }
serde_json = "1"
lsp-types = "0.97"
serde-big-array = "0.5"
postcard = { version = "1", features = ["use-std"] }
toml = "0.8"
ron = "0.8"
bincode = "1"
base64 = "0.22"
# === Errores ===
thiserror = "2" # bump uniforme; arje (era 1) puede requerir ajustes menores
anyhow = "1"
# === Async ===
tokio = { version = "1", features = ["full"] }
tokio-util = { version = "0.7", features = ["compat"] }
async-trait = "0.1"
futures = "0.3"
# === Observabilidad ===
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
# === Linux primitives (arje) ===
nix = { version = "0.29", features = ["signal", "process", "sched", "mount", "fs", "socket", "net", "user"] }
libc = "0.2"
# === IDs / Hash / Crypto ===
ulid = { version = "1", features = ["serde"] }
uuid = { version = "1", features = ["v4", "rng-getrandom"] }
sha2 = "0.10"
blake3 = "1.5"
ed25519-dalek = "2"
aes-gcm = "0.10"
chacha20poly1305 = "0.10"
argon2 = "0.5"
rand = "0.8"
# === WASM (arje) ===
# wasmi 1.0: unifica la versión con renaser (su kernel ya corre 1.0), para
# que el ABI WASM del host sea idéntico en Linux y en bare-metal.
wasmi = "1.0"
wat = "1"
# === Storage / DB ===
sled = "0.34"
rusqlite = { version = "0.31", features = ["bundled", "blob"] }
# === Ingesta de documentos (iniy-ingest: PDF / EPUB) ===
pdf-extract = "0.7"
epub = "2.1"
# === Bulk import Wikipedia (iniy-wiki dump) ===
bzip2 = "0.4"
# === Compresión (minga multi-bundle) ===
zstd = "0.13"
# === HTTP server (iniy-server) ===
axum = "0.7"
tower = "0.5"
# === ANN sobre embeddings (iniy nli --ann) ===
instant-distance = "0.6"
# === P2P (minga) ===
libp2p = { version = "0.56", features = ["tokio", "tcp", "noise", "yamux", "macros", "kad", "identify", "relay", "dcutr", "autonat", "mdns"] }
libp2p-stream = "=0.4.0-alpha"
libp2p-allow-block-list = "0.6"
# === SSH (ssh, sandokan RemoteEngine, matilda) ===
russh = "0.54"
# === Math determinista cross-platform (dominium) ===
libm = "0.2"
# === SMF (takiy-midi) ===
# midly: parser/emitter SMF tipo 0/1, no_std-friendly, sin allocs en hot path.
midly = "0.5"
# === Code parsing (minga) ===
arboard = "3"
ropey = "1.6"
tree-sitter = "0.24"
tree-sitter-rust = "0.23"
tree-sitter-python = "0.23"
tree-sitter-typescript = "0.23"
tree-sitter-javascript = "0.23"
tree-sitter-go = "0.23"
# === FS notify ===
notify = "6.1"
# === Grafos (iniy, nakui-core ya lo usa directo en 0.6) ===
petgraph = "0.6"
# === Image decoding (nahual-image-viewer-llimphi) ===
# default-features = false: nos quedamos con PNG + JPEG + WebP (lossless).
# tullpu-render exporta a las tres; AVIF/TIFF/… los habilitamos si una app
# los pide específicamente.
image = { version = "0.25", default-features = false, features = ["png", "jpeg", "webp"] }
# === FUSE (minga-vfs) ===
# default-features = false: prescinde de pkg-config/libfuse-dev en build.
# El montaje pasa a ser Rust puro (vía el helper `fusermount3` en runtime).
fuser = { version = "0.15", default-features = false }
# === CLI / auth (minga) ===
clap = { version = "4", features = ["derive"] }
rpassword = "7"
# === PAM (auth-core) ===
pam = "0.8"
# === D-Bus (arje compat) ===
zbus = { version = "4", default-features = false, features = ["tokio"] }
# === Tests ===
tempfile = "3"
# === Llimphi (motor gráfico soberano) ===
# wgpu sobre Vulkan/Metal/DX12, winit para ventana en dev Linux.
# raw-window-handle 0.6 alinea winit 0.30 con wgpu 24.
# vello 0.5 = rasterizador vectorial sobre wgpu 24.
# taffy 0.9 = motor Flexbox/Grid puro Rust (ya pulled por transitivos, lo alineamos).
# parley 0.2 = shaping/layout de texto compatible con peniko 0.4 (que vello 0.5 expone).
wgpu = "24"
winit = "0.30"
raw-window-handle = "0.6"
pollster = "0.4"
vello = "0.5"
taffy = "0.9"
# parley = shaping completo (bidi, ligatures, fallback CJK/emoji vía fontique, line break).
parley = "0.4"
# Bucle Elm (input→update→view→layout→raster→present). Lo consumen las apps.
llimphi-ui = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Paleta semántica compartida por las apps y los widgets.
llimphi-theme = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Tweens y helpers de animación sobre el bucle Elm.
llimphi-motion = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Iconos vectoriales (BezPath en grid 24×24) compartidos por todas las apps.
llimphi-icons = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Widgets reusables sobre llimphi-ui — uno por crate.
llimphi-widget-app-header = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-banner = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-button = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-card = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-clipboard = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-context-menu = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-edit-menu = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-menubar = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-list = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-grid = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-slider = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-scroll = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-splitter = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-stat-card = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-tabs = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-command-palette = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-diff-viewer = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-fif = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-file-picker = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-bookmarks = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-mini-map = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-shuma-term = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-module-symbol-outline = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-plugin-host = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-theme-switcher = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-text-area = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-text-editor-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-text-editor = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-text-editor-lsp = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-text-input = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-tiled = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-nodegraph = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-tree = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-navigator = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Sello vectorial wawa (rombo + W implícita + Merkle Core).
llimphi-widget-wawa-mark = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Widgets de elegancia transversal (tooltip, spinner, progress, toast,
# modal, empty, status-bar, shortcuts-help, splash).
llimphi-widget-tooltip = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-spinner = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-progress = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-toast = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-modal = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-empty = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-status-bar = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-shortcuts-help = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-timeline = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-splash = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Controles de formulario y signaling (switch, segmented, breadcrumb,
# badge, avatar, skeleton, field).
llimphi-widget-switch = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-segmented = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-dock-rail = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-breadcrumb = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-badge = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-avatar = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-skeleton = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-field = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Firma visual transversal (gradient sutil + hairline accent).
llimphi-widget-panel = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-widget-panes = { git = "https://gitea.gioser.net/sergio/gioser.git" }
llimphi-workspace = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# Abstracción Selector — host (paths) + wawa (khipus).
llimphi-module-selector = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# === Filesystem helpers ===
directories = "5"
# === Diff line-based (llimphi-module-diff-viewer) ===
# `similar` es la crate de facto: implementa Myers + Patience + LCS,
# expone `TextDiff` con ChangeTag por línea (Equal/Insert/Delete),
# zero deps fuera de std. La 2.x es estable hace años.
similar = "2"
# === Fuzzy matching (shuma-history) ===
# nucleo-matcher = mismo matcher que helix-editor: rápido, Unicode-correct,
# bonus por prefijos, ranking estable. La versión 0.3 expone el API simple
# que necesitamos (Matcher + Pattern + score).
nucleo-matcher = "0.3"
# === Transporte autenticado (shuma-link) ===
# snow = framework Noise pure-rust. Lo usamos en modo Noise_XK (cliente
# conoce la pubkey del servidor, server descubre la del cliente y la
# valida contra una allowlist). ChaCha20-Poly1305 + X25519 + BLAKE2s.
# La versión 0.9 viene pinneada por libp2p, así nos alineamos.
snow = "0.9"
hex = "0.4"
# === PTY + emulador de terminal (shuma-exec, módulos REPL) ===
# portable-pty aloja un PTY cross-platform; lo usamos para los
# comandos TUI tipo vim/htop/less que necesitan un terminal de verdad.
# vt100 parsea la secuencia de bytes que el PTY emite (ANSI + cursor
# movement + erase + screen state) y mantiene un buffer de pantalla
# renderizable como grid.
portable-pty = "0.9"
vt100 = "0.16"
# === WASM web (gioser) ===
wasm-bindgen = "0.2"
wasm-bindgen-futures = "0.4"
js-sys = "0.3"
web-sys = "0.3"
glam = "0.30"
# === Markdown (pluma) ===
pulldown-cmark = { version = "0.12", default-features = false, features = ["html"] }
# === Archivos comprimidos (nahual archive viewer) ===
# Sólo listamos el directorio central (nombres/tamaños); no descomprimimos,
# por eso default-features=false alcanza para ZIP. Para tar.gz sí
# descomprimimos en streaming con flate2 (ya declarado arriba), saltando
# los datos de cada entrada — sólo leemos headers.
zip = { version = "2.4", default-features = false }
tar = { version = "0.4", default-features = false }
# === Fuentes (nahual font viewer) ===
# Parseo de TTF/OTF/TTC y extracción de contornos de glifo a paths.
ttf-parser = "0.25"
# ============================================================
# Intra-workspace deps de nahual (referenciadas por workspace = true)
# ============================================================
nahual-text-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-image-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-thumb-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-gallery-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-video-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-card-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-audio-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-tree-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-hex-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-table-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-markdown-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-archive-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-font-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-map-viewer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-geo-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-viewer-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
nahual-file-explorer-llimphi = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# ============================================================
# Intra-workspace deps de pineal (módulo de gráficos)
# ============================================================
pineal-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-render = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-cartesian = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-stream = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-mesh = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-financial = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-polar = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-heatmap = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-treemap = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-flow = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-phosphor = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-export = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-hexbin = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-contour = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal-bars = { git = "https://gitea.gioser.net/sergio/gioser.git" }
pineal = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# ============================================================
# Intra-workspace deps de iniy (laboratorio semántico de creencias)
# ============================================================
iniy-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
iniy-ingest = { git = "https://gitea.gioser.net/sergio/gioser.git" }
iniy-extract = { git = "https://gitea.gioser.net/sergio/gioser.git" }
iniy-nli = { git = "https://gitea.gioser.net/sergio/gioser.git" }
iniy-nli-llm = { git = "https://gitea.gioser.net/sergio/gioser.git" }
iniy-graph = { git = "https://gitea.gioser.net/sergio/gioser.git" }
iniy-store = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# === auto: declarados por crates internos faltantes ===
cosmos-coords = { git = "https://gitea.gioser.net/sergio/gioser.git" }
cosmos-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
cosmos-ephemeris = { git = "https://gitea.gioser.net/sergio/gioser.git" }
cosmos-time = { git = "https://gitea.gioser.net/sergio/gioser.git" }
cosmos-wcs = { git = "https://gitea.gioser.net/sergio/gioser.git" }
# === auto: externas de eternal ===
celestial-eop-data = { version = "0.1"}
approx = "0.5"
byteorder = "1.5"
cc = "1.0"
chrono = "0.4"
crc32fast = "1.4"
criterion = "0.5"
csv = "1.4"
flate2 = "1.0"
glob = "0.3"
indicatif = "0.18"
lz4_flex = "0.11"
memmap2 = "0.9"
mockito = "1.0"
ndarray = "0.15"
num-traits = "0.2"
once_cell = "1.19"
parking_lot = "0.12"
png = "0.18"
proptest = "1.4"
quick-xml = "0.31"
rayon = "1.8"
regex = "1.11"
reqwest = "0.12"
tiff = "0.11"
wide = "0.7"
wiremock = "0.6"
# === i18n (rimay-localize) ===
fluent-bundle = "0.15"
unic-langid = { version = "0.9", features = ["macros"] }
sys-locale = "0.3"
# === Servo (puriy-engine) ===
# Crates publicados de Servo embebibles individualmente. html5ever/markup5ever
# ya entran via ammonia→surrealdb→nakui, así que alineamos versión para no
# duplicar el árbol. markup5ever_rcdom es el DOM Rc-based simple (suficiente
# para Fase 2: parsear y renderizar, sin scripting). cssparser es el tokenizer
# CSS de Stylo, sirve para inline styles. ureq = HTTP síncrono minimalista,
# evita pull de tokio en el engine.
html5ever = "0.39"
markup5ever = "0.39"
markup5ever_rcdom = "0.39"
cssparser = "0.35"
url = "2"
ureq = { version = "2", default-features = false, features = ["tls"] }
# === takiy-synth (SoundFont MIDI) ===
# rustysynth = sintetizador SF2 puro Rust, MIT. Reemplaza el oscilador
# feo de takiy-synth por muestras reales (FluidR3, GeneralUser GS, etc).
rustysynth = "1.3"
# === takiy-playback (audio device output) ===
# cpal = backend de audio cross-platform (ALSA/PulseAudio/Pipewire en
# Linux, WASAPI en Windows, CoreAudio en macOS). Lo usamos sólo para
# abrir el device default y empujar muestras f32 — nada de mezclado
# ni efectos en el callback.
cpal = "0.15"
# === media-source-wav (decoder PCM en disco) ===
# hound = lector/escritor WAV puro-Rust, sin deps nativas. Soporta PCM
# entero (8/16/24/32) y float (32). Suficiente para abrir samples y
# stems de prueba sin meter ffmpeg/symphonia.
hound = "3.5"
# === media-source-{mp3,flac,vorbis} (decoders vía symphonia) ===
# symphonia es una colección de decoders puro-Rust mantenida. `mp3` cubre
# media-source-mp3; `flac` (decoder + demuxer FLAC nativo) cubre
# media-source-flac (lossless); `vorbis` + `ogg` (codec + demuxer Ogg)
# cubren media-source-vorbis (lossy clásico, libre de patentes). Sin aac:
# ese tier patentado entra por shared/foreign-av.
symphonia = { version = "0.5", default-features = false, features = ["mp3", "flac", "vorbis", "ogg"] }
# === media-source-opus (decoder Opus NATIVO puro-Rust) ===
# Opus es el formato de audio nativo de gioser (par del video AV1). ogg
# demuxea las páginas Ogg; opus-wave es un port puro-Rust de libopus
# (SILK+CELT, sin C ni FFI) — par del rav1d del lado video.
ogg = "0.9"
opus-wave = "3"
# === media-source-webm (demux nativo Matroska/WebM) ===
# matroska-demuxer es un demuxer puro-Rust de MKV/WebM (EBML). Saca los
# paquetes de los tracks V_AV1 y A_OPUS para alimentar a media-source-av1
# y media-source-opus — un .webm AV1+Opus se reproduce 100% nativo.
matroska-demuxer = "0.7"
# === git-deps al monorepo (agregados por la extracción) ===
arje-cas = { git = "https://gitea.gioser.net/sergio/gioser.git" }
card-core = { git = "https://gitea.gioser.net/sergio/gioser.git" }
card-net = { git = "https://gitea.gioser.net/sergio/gioser.git" }
card-wit = { git = "https://gitea.gioser.net/sergio/gioser.git" }
rimay-localize = { git = "https://gitea.gioser.net/sergio/gioser.git" }
shuma-discern = { git = "https://gitea.gioser.net/sergio/gioser.git" }
wawa-config = { git = "https://gitea.gioser.net/sergio/gioser.git" }
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Sergio
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+11
View File
@@ -0,0 +1,11 @@
# chasqui
> Sovereign peer discovery + transport — DHT, relay, NAT traversal — in Rust.
`chasqui` (Quechua: *Inca relay messenger*) is the networking layer: peer discovery (UDP + Kademlia DHT), relay/dcutr/autonat for NAT traversal, and authenticated transport over the `card` identity. Channels and capabilities are expressed as typed cards; no TCP/IP assumptions leak into the apps above it.
## How dependencies work
Front-door repo: only `chasqui-*` crates here. `card` (identity), `arje` primitives, shared leaves are git-dependencies of the [`gioser`](https://gitea.gioser.net/sergio/gioser) monorepo.
## License
MIT. Part of the [gioser](https://gitea.gioser.net/sergio/gioser) suite.