Ubiquity Transport

A platform-agnostic transport layer for the Ubiquity consciousness mesh, enabling seamless communication across native and WASM environments.

Features

• Multi-Platform Support: Works in browsers, edge workers, and native environments
• Multiple Transport Types:
  • Unix Domain Sockets (native)
  • WebSocket (native & WASM)
  • MessageChannel (WASM)
  • BroadcastChannel (WASM)
• Automatic Transport Selection: Chooses the best transport for your platform
• Unified API: Same interface regardless of underlying transport
• Async/Await: Fully async implementation using Tokio

Usage

Basic Example

use ubiquity_transport::prelude::*;
use ubiquity_core::MeshMessage;

#[tokio::main]
async fn main() -> Result<()> {
    // Automatically select best transport for platform
    let transport = TransportFactory::create(TransportType::Auto)?;
    
    // Start listening
    let mut listener = transport.listen("/tmp/my-service.sock").await?;
    
    // Accept connections
    let mut conn = listener.accept().await?;
    
    // Send/receive messages
    let msg = MeshMessage::Heartbeat {
        agent_id: "my-agent".to_string(),
        timestamp: chrono::Utc::now(),
    };
    conn.send(&msg).await?;
    
    Ok(())
}

Platform-Specific Transport

// Native Unix sockets
#[cfg(not(target_arch = "wasm32"))]
let transport = TransportFactory::create(TransportType::UnixSocket)?;

// WASM MessageChannel
#[cfg(target_arch = "wasm32")]
let transport = TransportFactory::create(TransportType::MessageChannel)?;

// WebSocket (works everywhere)
let transport = TransportFactory::create(TransportType::WebSocket)?;

Transport Builder

let transport = TransportBuilder::new(TransportType::Auto)
    .max_message_size(2 * 1024 * 1024)  // 2MB
    .connect_timeout_ms(10000)           // 10 seconds
    .build()?;

Transport Types

Unix Domain Sockets

• Platform: Native only (Linux, macOS, etc.)
• Use Case: High-performance local IPC
• Features: Low latency, high throughput, file-based addressing

WebSocket

• Platform: Both native and WASM
• Use Case: Network communication, cross-origin
• Features: Standard protocol, works through proxies

MessageChannel

• Platform: WASM only (browsers)
• Use Case: Communication between browser contexts
• Features: Structured cloning, transferable objects

BroadcastChannel

• Platform: WASM only (browsers)
• Use Case: Multi-tab/window communication
• Features: Named channels, broadcast to all listeners

Architecture

The transport layer follows a simple trait-based design:

#[async_trait]
pub trait Transport: Send + Sync {
    async fn connect(&self, target: &str) -> Result<Box<dyn Connection>>;
    async fn listen(&self, addr: &str) -> Result<Box<dyn Listener>>;
    fn transport_type(&self) -> &'static str;
}

#[async_trait]
pub trait Connection: Send + Sync {
    async fn send(&mut self, msg: &MeshMessage) -> Result<()>;
    async fn recv(&mut self) -> Result<Option<MeshMessage>>;
    async fn close(&mut self) -> Result<()>;
}

#[async_trait]
pub trait Listener: Send + Sync {
    async fn accept(&mut self) -> Result<Box<dyn Connection>>;
    fn addr(&self) -> String;
}

Testing

Run tests for your platform:

# Native tests
cargo test

# WASM tests (requires wasm-pack)
wasm-pack test --browser

# Specific transport tests
cargo test --features native
cargo test --features websocket

Examples

Check out the examples directory:

# Run consciousness mesh example
cargo run --example consciousness_mesh

Feature Flags

• native: Enable Unix socket transport (default on native platforms)
• websocket: Enable WebSocket transport
• wasm: Enable WASM-specific transports (MessageChannel, BroadcastChannel)

Performance Considerations

• Unix Sockets: Best performance for local communication
• MessageChannel: Low latency for same-origin contexts
• BroadcastChannel: Higher latency but simpler multi-target messaging
• WebSocket: Network overhead but most flexible

License

See LICENSE file in the root of the repository.