refactor(monorepo): reorganización lógica + renames + SDDs + split CHANGELOG

Reorganización física de crates/: - core/ (mezclaba 6 propósitos) se divide en protocol/, init/, runtime/, compat/ - shared/ (3 crates) se redistribuye en protocol/ e init/ - lapaloma (sub-módulo de ui_engine) se promueve a modules/pineal/ Renames de proyectos: - shipote → shuma (runtime de sandboxes) - nouser → akasha (explorador de Mónadas) - yahweh → nahual (motor GPUI, antes ui_engine/) - lapaloma → pineal (data-viz agnóstica) Fraccionamiento UI → core agnóstico: - vista-core (DeckState + snap, 175 LOC, 5 tests verdes) - barra-core (Task + render_html + sanitize, 90 LOC, 5 tests verdes) - vista-web y barra-web ahora son thin DOM bindings Documentación nueva: - 16 SDDs por subdirectorio (≤80 LOC c/u): protocol/init/runtime/compat + 10 módulos + apps/ - docs/STATUS.md con cifras reales por proyecto - docs/ROADMAP.md con plan a finalización (6 hitos, ~6-8 semanas) - CHANGELOG.md particionado en docs/changelog/<proyecto>.md (7 buckets) Automatización: - scripts/reorg.py — script idempotente que: git mv directorios, renombra package names, recomputa path = refs, reescribe imports rust, actualiza workspace Cargo.toml. Soporta --dry-run. - scripts/split-changelog.py — particiona CHANGELOG por componente. Validación: - cargo check --workspace pasa (124 crates + 2 nuevos cores). - 10 tests adicionales (5 en vista-core + 5 en barra-core) verdes. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-19 14:48:34 +00:00
parent 86fb6ae20b
commit 550c98f275
375 changed files with 8512 additions and 7155 deletions
@@ -0,0 +1,423 @@
+//! `brahman-net` — capa P2P compartida de la red Brahman.
+//!
+//! Provee un nodo libp2p genérico que cualquier protocolo de la
+//! familia (handshake brahman remoto, sync minga, futuros) puede
+//! reusar. La idea: una sola malla, múltiples sub-protocolos
+//! multiplexados por `StreamProtocol`.
+//!
+//! ## Stack
+//!
+//! - **TCP + Noise + Yamux**: transporte autenticado y multiplexado.
+//! - **`stream::Behaviour`**: streams bidireccionales por
+//!   `StreamProtocol`. Cada protocolo (`/brahman/handshake/1.0.0`,
+//!   `/minga/sync/1.0.0`, …) se registra independientemente vía el
+//!   `stream::Control` que `BrahmanNet` expone.
+//! - **`kad::Behaviour<MemoryStore>`**: Kademlia DHT en modo Server
+//!   para discovery (peers cercanos + content providers).
+//! - **`identify::Behaviour`**: cada peer anuncia sus listen-addrs
+//!   reales; las inyectamos automáticamente al routing table de Kad.
+//!
+//! ## Modelo
+//!
+//! El swarm corre en una task tokio dedicada. La interfaz pública son:
+//! 1. **Comandos** (canal mpsc): `dial`, `listen`, `add_dht_peer`,
+//!    `find_closest_peers`, `start_providing`, `find_providers`.
+//! 2. **`stream::Control`** (acceso directo): para abrir/aceptar
+//!    streams de un protocolo concreto. Cada protocolo se ocupa de
+//!    su propia lógica sobre el stream resultante.
+//!
+//! La separación entre comandos y control permite que la lógica de
+//! red (DHT, dial, listen) y la lógica de protocolos (handshake/sync)
+//! evolucionen independientes — el protocolo no necesita conocer al
+//! swarm, sólo pide streams.
+//!
+//! ## Identidad
+//!
+//! Por defecto se genera una keypair Ed25519 efímera. Para identidad
+//! persistente (la misma `peer_id` across reboots), pasar la keypair
+//! con [`BrahmanNet::with_keypair`]. Esa misma keypair puede ser la
+//! base para firmas de Cards (cuando se implemente trust remoto).
+
+#![forbid(unsafe_code)]
+#![warn(rust_2018_idioms)]
+
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use futures::StreamExt;
+use libp2p::{
+    identify, identity, kad, noise,
+    swarm::{NetworkBehaviour, SwarmEvent},
+    tcp, yamux, Swarm, SwarmBuilder,
+};
+use libp2p_allow_block_list::{self as allow_block_list, BlockedPeers};
+use libp2p_stream as stream;
+use tokio::sync::{mpsc, oneshot, Mutex};
+
+pub use libp2p::{
+    identity::{Keypair, PublicKey},
+    multiaddr::Protocol,
+    Multiaddr, PeerId, Stream, StreamProtocol,
+};
+pub use libp2p_stream::OpenStreamError;
+
+const IDENTIFY_PROTOCOL: &str = "/brahman-net/0.1.0";
+const IDLE_CONNECTION_TIMEOUT: Duration = Duration::from_secs(60);
+
+#[derive(NetworkBehaviour)]
+struct BrahmanBehaviour {
+    /// Block-list a nivel de swarm: peers en este behaviour son
+    /// rechazados ANTES del handshake Noise. Más eficiente que
+    /// rechazar al nivel del handshake brahman (ahorra round-trip
+    /// TCP+Noise por intento denegado). Sincronizado con la
+    /// `PeerPolicy.deny` vía `block_peer`/`unblock_peer` exposed
+    /// en `BrahmanNet`.
+    block_list: allow_block_list::Behaviour<BlockedPeers>,
+    stream: stream::Behaviour,
+    kad: kad::Behaviour<kad::store::MemoryStore>,
+    identify: identify::Behaviour,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum NodeError {
+    #[error("transport build failed: {0}")]
+    Build(String),
+}
+
+#[derive(Debug)]
+enum Command {
+    Dial(Multiaddr),
+    Listen(Multiaddr),
+    AddDhtPeer(PeerId, Multiaddr),
+    FindClosestPeers(PeerId, oneshot::Sender<Vec<DiscoveredPeer>>),
+    StartProviding(Vec<u8>),
+    StopProviding(Vec<u8>),
+    GetProviders(Vec<u8>, oneshot::Sender<Vec<PeerId>>),
+    BlockPeer(PeerId),
+    UnblockPeer(PeerId),
+}
+
+/// Peer descubierto vía DHT: identidad + direcciones conocidas.
+#[derive(Debug, Clone)]
+pub struct DiscoveredPeer {
+    pub peer_id: PeerId,
+    pub addrs: Vec<Multiaddr>,
+}
+
+/// Nodo Brahman en la malla P2P. Maneja el swarm libp2p y expone
+/// API uniforme para listen/dial/DHT/streams.
+pub struct BrahmanNet {
+    /// Identidad libp2p de este nodo. Estable mientras viva la
+    /// keypair (efímera por default; persistente si pasaste una
+    /// vía [`with_keypair`]).
+    pub peer_id: PeerId,
+    /// Keypair compartida (Arc para compartir con consumers que
+    /// necesitan firmar mensajes con la misma identidad — p. ej.
+    /// `brahman_handshake::network::connect_libp2p` que firma el
+    /// Hello). NO se expone públicamente; usar [`Self::keypair`].
+    keypair: Arc<Keypair>,
+    cmd_tx: mpsc::UnboundedSender<Command>,
+    listen_rx: Mutex<mpsc::UnboundedReceiver<Multiaddr>>,
+    /// Control para abrir y aceptar streams. Cada protocolo
+    /// (handshake brahman, sync minga, etc.) llama
+    /// `control.accept(StreamProtocol::new("/foo/1.0.0"))` para
+    /// recibir streams entrantes, o `control.open_stream(peer, proto)`
+    /// para abrirlos. Multiplexado y demultiplexado lo hace libp2p.
+    pub control: stream::Control,
+}
+
+impl BrahmanNet {
+    /// Crea un nodo con keypair Ed25519 generada al vuelo (peer_id
+    /// efímero — cambia en cada arranque).
+    pub fn new() -> Result<Self, NodeError> {
+        Self::with_keypair(identity::Keypair::generate_ed25519())
+    }
+
+    /// Crea un nodo con una keypair libp2p específica. Usá esto para
+    /// `peer_id` estable (por ejemplo si tu identidad se persiste a
+    /// disco, o si la derivás de la identidad criptográfica del
+    /// módulo).
+    ///
+    /// Sólo Ed25519 se soporta — la `keypair` se duplica internamente
+    /// vía clone del `ed25519::Keypair` para que tanto el swarm
+    /// (Noise auth) como el caller (firma de Cards) compartan la
+    /// misma identidad sin la fricción de que `identity::Keypair` no
+    /// implemente `Clone`.
+    pub fn with_keypair(keypair: identity::Keypair) -> Result<Self, NodeError> {
+        let ed_kp = keypair
+            .try_into_ed25519()
+            .map_err(|_| NodeError::Build("brahman-net sólo soporta keypairs Ed25519".into()))?;
+        let kp_for_swarm = identity::Keypair::from(ed_kp.clone());
+        let kp_for_storage = Arc::new(identity::Keypair::from(ed_kp));
+        let peer_id = kp_for_swarm.public().to_peer_id();
+
+        let mut swarm: Swarm<BrahmanBehaviour> = SwarmBuilder::with_existing_identity(kp_for_swarm)
+            .with_tokio()
+            .with_tcp(
+                tcp::Config::default(),
+                noise::Config::new,
+                yamux::Config::default,
+            )
+            .map_err(|e| NodeError::Build(format!("{e}")))?
+            .with_behaviour(|key| {
+                let local = key.public().to_peer_id();
+                let mut kad =
+                    kad::Behaviour::new(local, kad::store::MemoryStore::new(local));
+                // Modo Server: respondemos a queries del DHT. Auto
+                // requiere detectar reachability; para entornos
+                // controlados (localhost, redes privadas) Server es
+                // lo correcto.
+                kad.set_mode(Some(kad::Mode::Server));
+                let identify = identify::Behaviour::new(
+                    identify::Config::new(IDENTIFY_PROTOCOL.to_string(), key.public())
+                        .with_agent_version(format!("brahman-net/{}", env!("CARGO_PKG_VERSION"))),
+                );
+                BrahmanBehaviour {
+                    block_list: allow_block_list::Behaviour::default(),
+                    stream: stream::Behaviour::new(),
+                    kad,
+                    identify,
+                }
+            })
+            .map_err(|e| NodeError::Build(format!("{e}")))?
+            .with_swarm_config(|c| c.with_idle_connection_timeout(IDLE_CONNECTION_TIMEOUT))
+            .build();
+
+        let control = swarm.behaviour().stream.new_control();
+
+        let (cmd_tx, mut cmd_rx) = mpsc::unbounded_channel::<Command>();
+        let (listen_tx, listen_rx) = mpsc::unbounded_channel::<Multiaddr>();
+
+        tokio::spawn(async move {
+            let mut pending_finds: HashMap<
+                kad::QueryId,
+                oneshot::Sender<Vec<DiscoveredPeer>>,
+            > = HashMap::new();
+            let mut pending_providers: HashMap<
+                kad::QueryId,
+                (Vec<PeerId>, oneshot::Sender<Vec<PeerId>>),
+            > = HashMap::new();
+
+            loop {
+                tokio::select! {
+                    Some(cmd) = cmd_rx.recv() => {
+                        match cmd {
+                            Command::Dial(addr) => {
+                                let _ = swarm.dial(addr);
+                            }
+                            Command::Listen(addr) => {
+                                let _ = swarm.listen_on(addr);
+                            }
+                            Command::AddDhtPeer(peer, addr) => {
+                                swarm.behaviour_mut().kad.add_address(&peer, addr);
+                            }
+                            Command::FindClosestPeers(target, tx) => {
+                                let qid = swarm.behaviour_mut().kad.get_closest_peers(target);
+                                pending_finds.insert(qid, tx);
+                            }
+                            Command::StartProviding(key) => {
+                                // Best-effort: si falla (sin peers cercanos para
+                                // replicar), seguirá viviendo en el local store
+                                // y se servirá vía get_providers de quien tenga
+                                // conexión con nosotros.
+                                let _ = swarm.behaviour_mut().kad.start_providing(key.into());
+                            }
+                            Command::StopProviding(key) => {
+                                // Quitamos el record local del provider store.
+                                // Los peers cercanos eventualmente expiran su
+                                // copia replicada por TTL natural (~24h en
+                                // libp2p kad default); para retiro inmediato
+                                // habría que enviar un republish con sentinel,
+                                // pero kad no expone esa primitiva. Aceptable
+                                // para el caso "el provider local desapareció":
+                                // queries que pasen por nosotros dejan de
+                                // listarnos al instante.
+                                swarm.behaviour_mut().kad.stop_providing(&key.into());
+                            }
+                            Command::GetProviders(key, tx) => {
+                                let qid = swarm.behaviour_mut().kad.get_providers(key.into());
+                                pending_providers.insert(qid, (Vec::new(), tx));
+                            }
+                            Command::BlockPeer(peer) => {
+                                swarm.behaviour_mut().block_list.block_peer(peer);
+                            }
+                            Command::UnblockPeer(peer) => {
+                                swarm.behaviour_mut().block_list.unblock_peer(peer);
+                            }
+                        }
+                    }
+                    event = swarm.select_next_some() => {
+                        match event {
+                            SwarmEvent::NewListenAddr { address, .. } => {
+                                let _ = listen_tx.send(address);
+                            }
+                            // Identify nos dice las listen-addrs reales del
+                            // peer. Las inyectamos a Kad para poblar el
+                            // routing table sin necesidad de add_dht_peer
+                            // manual — la propagación pasa a ser automática.
+                            SwarmEvent::Behaviour(BrahmanBehaviourEvent::Identify(
+                                identify::Event::Received { peer_id, info, .. }
+                            )) => {
+                                for addr in info.listen_addrs {
+                                    swarm.behaviour_mut().kad.add_address(&peer_id, addr);
+                                }
+                            }
+                            SwarmEvent::Behaviour(BrahmanBehaviourEvent::Kad(
+                                kad::Event::OutboundQueryProgressed { id, result, step, .. }
+                            )) => {
+                                match result {
+                                    kad::QueryResult::GetClosestPeers(Ok(ok)) if step.last => {
+                                        if let Some(tx) = pending_finds.remove(&id) {
+                                            let infos = ok.peers.into_iter()
+                                                .map(|p| DiscoveredPeer {
+                                                    peer_id: p.peer_id,
+                                                    addrs: p.addrs,
+                                                })
+                                                .collect();
+                                            let _ = tx.send(infos);
+                                        }
+                                    }
+                                    kad::QueryResult::GetClosestPeers(Err(_)) if step.last => {
+                                        if let Some(tx) = pending_finds.remove(&id) {
+                                            let _ = tx.send(Vec::new());
+                                        }
+                                    }
+                                    kad::QueryResult::GetProviders(Ok(ok)) => {
+                                        if let Some((collected, _)) =
+                                            pending_providers.get_mut(&id)
+                                        {
+                                            if let kad::GetProvidersOk::FoundProviders {
+                                                providers, ..
+                                            } = ok
+                                            {
+                                                for p in providers {
+                                                    if !collected.contains(&p) {
+                                                        collected.push(p);
+                                                    }
+                                                }
+                                            }
+                                        }
+                                        if step.last {
+                                            if let Some((providers, tx)) =
+                                                pending_providers.remove(&id)
+                                            {
+                                                let _ = tx.send(providers);
+                                            }
+                                        }
+                                    }
+                                    kad::QueryResult::GetProviders(Err(_)) if step.last => {
+                                        if let Some((providers, tx)) =
+                                            pending_providers.remove(&id)
+                                        {
+                                            let _ = tx.send(providers);
+                                        }
+                                    }
+                                    _ => {}
+                                }
+                            }
+                            _ => {}
+                        }
+                    }
+                }
+            }
+        });
+
+        Ok(Self {
+            peer_id,
+            keypair: kp_for_storage,
+            cmd_tx,
+            listen_rx: Mutex::new(listen_rx),
+            control,
+        })
+    }
+
+    /// Acceso a la keypair de identidad del nodo. Usar para firmar
+    /// payloads que viajan asociados al `peer_id` (handshake brahman
+    /// firmado, futuros sub-protocolos con autenticación). El `Arc`
+    /// permite compartir sin copia — la keypair libp2p no es `Clone`.
+    pub fn keypair(&self) -> Arc<Keypair> {
+        self.keypair.clone()
+    }
+
+    /// Bloquea conexiones desde/hacia `peer` a nivel del swarm.
+    /// Conexiones existentes se cierran y nuevos intentos son
+    /// rechazados ANTES del Noise handshake — más eficiente que
+    /// rechazar al nivel del handshake brahman (ahorra round-trip
+    /// TCP+Noise por intento). Idempotente.
+    pub fn block_peer(&self, peer: PeerId) {
+        let _ = self.cmd_tx.send(Command::BlockPeer(peer));
+    }
+
+    /// Quita a `peer` de la block-list del swarm. Conexiones futuras
+    /// son aceptadas con normalidad. Idempotente.
+    pub fn unblock_peer(&self, peer: PeerId) {
+        let _ = self.cmd_tx.send(Command::UnblockPeer(peer));
+    }
+
+    /// Empieza a escuchar en `addr`. Bloquea hasta que el listener
+    /// publique su dirección real (Multiaddr resuelta — útil cuando
+    /// pediste `/ip4/0.0.0.0/tcp/0` y querés saber qué puerto te tocó).
+    pub async fn listen(&self, addr: Multiaddr) -> Multiaddr {
+        self.cmd_tx
+            .send(Command::Listen(addr))
+            .expect("swarm task alive");
+        let mut rx = self.listen_rx.lock().await;
+        rx.recv().await.expect("listen address arrives")
+    }
+
+    /// Inicia conexión con un peer en `addr`. No-op si ya hay
+    /// conexión. Best-effort — fallos se loggean al swarm pero no se
+    /// propagan al caller (consistente con libp2p).
+    pub fn dial(&self, addr: Multiaddr) {
+        let _ = self.cmd_tx.send(Command::Dial(addr));
+    }
+
+    /// Añade un peer al routing table de Kademlia. Punto de entrada
+    /// para bootstrap: tras esto, el nodo puede dirigir queries DHT
+    /// a través de este peer.
+    pub fn add_dht_peer(&self, peer: PeerId, addr: Multiaddr) {
+        let _ = self.cmd_tx.send(Command::AddDhtPeer(peer, addr));
+    }
+
+    /// Consulta el DHT por los peers más cercanos al `target` PeerId.
+    /// Devuelve la lista resuelta (vacía si la query falla o si no
+    /// hay peers conocidos). Bloquea hasta que la query completa.
+    pub async fn find_closest_peers(&self, target: PeerId) -> Vec<DiscoveredPeer> {
+        let (tx, rx) = oneshot::channel();
+        let _ = self
+            .cmd_tx
+            .send(Command::FindClosestPeers(target, tx));
+        rx.await.unwrap_or_default()
+    }
+
+    /// Anuncia en el DHT que este peer tiene el contenido identificado
+    /// por `key`. Otros peers pueden luego descubrirlo vía
+    /// [`find_providers`](Self::find_providers). Best-effort: si la
+    /// replicación falla inicialmente, el record vive en el store
+    /// local hasta que llegue conexión.
+    pub fn start_providing(&self, key: &[u8]) {
+        let _ = self.cmd_tx.send(Command::StartProviding(key.to_vec()));
+    }
+
+    /// Retira el anuncio previo de [`start_providing`] para `key`.
+    /// El record local se borra al instante (queries que lleguen a
+    /// nosotros dejan de listarnos). Los records replicados en peers
+    /// remotos viven hasta su TTL — kad no expone primitiva para
+    /// retracción inmediata cross-peer. Aceptable: simétrico al
+    /// caso "el provider apareció" (también propagación eventual).
+    pub fn stop_providing(&self, key: &[u8]) {
+        let _ = self.cmd_tx.send(Command::StopProviding(key.to_vec()));
+    }
+
+    /// Consulta el DHT por peers que han anunciado proveer `key`.
+    /// Devuelve la lista de `PeerId`s que se reportan como providers.
+    /// Lista vacía si nadie anuncia.
+    pub async fn find_providers(&self, key: &[u8]) -> Vec<PeerId> {
+        let (tx, rx) = oneshot::channel();
+        let _ = self
+            .cmd_tx
+            .send(Command::GetProviders(key.to_vec(), tx));
+        rx.await.unwrap_or_default()
+    }
+}