clm-kernel 0.0.22

Cubical Logic Model (CLM) sovereign execution engine, CPN-VM, and Cordis spatiotemporal substrate
Documentation
//! Reticulum IPC Local Socket & Shared Instance Interface
//! Canonical Path: kernel/clm_rust_core/src/mesh/reticulum_ipc.rs
//!
//! Implements Sprint 358 (INV-L3-RET-358-02):
//! - IPC connection to local Reticulum instance (`rnsd`) or loopback daemon
//! - Zero-copy frame dispatch and packet encapsulation
//! - Fallback in-memory loopback transport for hermetic offline sandboxes

use std::collections::VecDeque;
use std::io::{self, Read, Write};
use std::net::{TcpStream, ToSocketAddrs};
use std::time::Duration;
use thiserror::Error;

#[derive(Debug, Error)]
pub enum ReticulumIpcError {
    #[error("I/O error during IPC communication: {0}")]
    Io(#[from] io::Error),
    #[error("Framing error: invalid packet length or header")]
    FramingError,
    #[error("IPC client not connected")]
    NotConnected,
}

#[derive(Debug, Clone)]
pub struct ReticulumIpcConfig {
    pub socket_path: Option<String>,
    pub tcp_addr: Option<String>,
    pub app_name: String,
    pub timeout_ms: u64,
}

impl Default for ReticulumIpcConfig {
    fn default() -> Self {
        Self {
            socket_path: None,
            tcp_addr: Some("127.0.0.1:4242".to_string()),
            app_name: "clm.pkc.node".to_string(),
            timeout_ms: 200,
        }
    }
}

pub struct ReticulumIpcClient {
    config: ReticulumIpcConfig,
    tcp_stream: Option<TcpStream>,
    in_memory_queue: VecDeque<(Vec<u8>, [u8; 16])>,
    is_loopback: bool,
}

impl ReticulumIpcClient {
    pub fn new(config: ReticulumIpcConfig) -> Self {
        Self {
            config,
            tcp_stream: None,
            in_memory_queue: VecDeque::new(),
            is_loopback: false,
        }
    }

    /// Attempts to connect to the local Reticulum daemon or falls back to loopback mode.
    pub fn connect(&mut self) -> Result<bool, ReticulumIpcError> {
        if let Some(ref addr) = self.config.tcp_addr
            && let Ok(socket_addrs) = addr.to_socket_addrs() {
                for socket_addr in socket_addrs {
                    if let Ok(stream) = TcpStream::connect_timeout(&socket_addr, Duration::from_millis(self.config.timeout_ms)) {
                        let _ = stream.set_nonblocking(true);
                        self.tcp_stream = Some(stream);
                        self.is_loopback = false;
                        return Ok(true);
                    }
                }
            }

        // Fallback to in-memory loopback mode for tests and offline operation
        self.is_loopback = true;
        Ok(false)
    }

    pub fn is_connected(&self) -> bool {
        self.tcp_stream.is_some() || self.is_loopback
    }

    pub fn is_loopback(&self) -> bool {
        self.is_loopback
    }

    /// Sends a Reticulum frame addressed to destination_hash.
    /// Framing: [2B length BE][16B destination][payload]
    pub fn send_frame(&mut self, destination: &[u8; 16], payload: &[u8]) -> Result<(), ReticulumIpcError> {
        if let Some(ref mut stream) = self.tcp_stream {
            let total_len = 16 + payload.len();
            if total_len > u16::MAX as usize {
                return Err(ReticulumIpcError::FramingError);
            }
            let len_bytes = (total_len as u16).to_be_bytes();
            stream.write_all(&len_bytes)?;
            stream.write_all(destination)?;
            stream.write_all(payload)?;
            stream.flush()?;
            Ok(())
        } else if self.is_loopback {
            self.in_memory_queue.push_back((payload.to_vec(), *destination));
            Ok(())
        } else {
            Err(ReticulumIpcError::NotConnected)
        }
    }

    /// Receives a frame if available.
    pub fn receive_frame(&mut self) -> Result<Option<(Vec<u8>, [u8; 16])>, ReticulumIpcError> {
        if let Some(ref mut stream) = self.tcp_stream {
            let mut len_buf = [0u8; 2];
            match stream.read_exact(&mut len_buf) {
                Ok(()) => {
                    let total_len = u16::from_be_bytes(len_buf) as usize;
                    if total_len < 16 {
                        return Err(ReticulumIpcError::FramingError);
                    }
                    let mut dest = [0u8; 16];
                    stream.read_exact(&mut dest)?;
                    let payload_len = total_len - 16;
                    let mut payload = vec![0u8; payload_len];
                    stream.read_exact(&mut payload)?;
                    Ok(Some((payload, dest)))
                }
                Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => Ok(None),
                Err(e) => Err(ReticulumIpcError::Io(e)),
            }
        } else if self.is_loopback {
            Ok(self.in_memory_queue.pop_front())
        } else {
            Err(ReticulumIpcError::NotConnected)
        }
    }

    /// Generates an Announce packet for this node.
    pub fn announce(&mut self, raw_pubkey: &[u8; 32], destination_hash: &[u8; 16]) -> Result<Vec<u8>, ReticulumIpcError> {
        let mut packet = Vec::with_capacity(1 + 16 + 32);
        packet.push(0x01); // Announce opcode
        packet.extend_from_slice(destination_hash);
        packet.extend_from_slice(raw_pubkey);
        self.send_frame(destination_hash, &packet)?;
        Ok(packet)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_ipc_loopback_frame_roundtrip() {
        let config = ReticulumIpcConfig {
            tcp_addr: Some("127.0.0.1:59999".to_string()), // non-existent port forces loopback
            timeout_ms: 10,
            ..Default::default()
        };

        let mut client = ReticulumIpcClient::new(config);
        let connected = client.connect().expect("connect should succeed");
        assert!(!connected, "Should fall back to loopback");
        assert!(client.is_loopback());

        let dest = [0x42u8; 16];
        let payload = b"Hello from Rust IPC mesh!";
        client.send_frame(&dest, payload).expect("send_frame should succeed");

        let received = client.receive_frame().expect("receive_frame should succeed");
        assert!(received.is_some());
        let (rx_payload, rx_dest) = received.unwrap();
        assert_eq!(rx_dest, dest);
        assert_eq!(rx_payload, payload);
    }
}