GitHub - currentspace/capn-rs

GitHub

6 min read Original article ↗

Cap'n Web Rust Implementation

A complete, production-ready implementation of the Cap'n Web protocol in Rust, providing capability-based RPC with promise pipelining and multi-transport support.

CI Documentation TypeScript Interop docs.rs GitHub Pages Crates.io License Rust 1.85+

Features

✅ Full Protocol Compliance - Implements the complete Cap'n Web wire protocol 🔒 Capability-Based Security - Unforgeable capability references with automatic lifecycle management 🚀 Promise Pipelining - Reduced round-trips through dependency resolution 🌐 Multi-Transport - HTTP batch, WebSocket, and WebTransport support 🛡️ Production-Ready - Zero-panic code, comprehensive error handling with context ✅ IL Expression Evaluation - Complete intermediate language support with array notation 🌍 JavaScript Interop - Validated against official TypeScript implementation

Quick Start

Add to Cargo.toml

[dependencies]
currentspace-capnweb-server = "0.1.0"
currentspace-capnweb-client = "0.1.0"

Server Example

use currentspace_capnweb_server::{Server, ServerConfig, RpcTarget};
use currentspace_capnweb_core::{CapId, RpcError};
use serde_json::{json, Value};
use std::sync::Arc;

#[derive(Debug)]
struct Calculator;

impl RpcTarget for Calculator {
    async fn call(&self, member: &str, args: Vec<Value>) -> Result<Value, RpcError> {
        match member {
            "add" => {
                let a = args[0].as_f64().unwrap();
                let b = args[1].as_f64().unwrap();
                Ok(json!(a + b))
            }
            _ => Err(RpcError::not_found("method not found")),
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = ServerConfig::default();
    let server = Server::new(config);

    // Register capabilities
    server.register_capability(CapId::new(1), Arc::new(Calculator));

    // Run server with HTTP batch endpoint
    server.run().await?;
    Ok(())
}

Client Example

use currentspace_capnweb_client::{Client, ClientConfig};
use currentspace_capnweb_core::CapId;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create client configuration
    let config = ClientConfig {
        url: "http://localhost:8080/rpc/batch".to_string(),
        ..Default::default()
    };
    let client = Client::new(config)?;

    // Make RPC calls
    let result = client.call(CapId::new(1), "add", vec![json!(10), json!(20)]).await?;
    println!("Result: {}", result);

    Ok(())
}

Architecture

The implementation is organized into focused crates:

  • currentspace-capnweb-core - Core protocol implementation (messages, IL, validation)
  • currentspace-capnweb-transport - Transport layer implementations (HTTP, WebSocket, WebTransport)
  • currentspace-capnweb-server - Server implementation with capability management
  • currentspace-capnweb-client - Client implementation with ergonomic recorder API
  • currentspace-capnweb-interop-tests - JavaScript interoperability verification

Transport Support

HTTP Batch Transport

use currentspace_capnweb_client::{Client, ClientConfig};

let config = ClientConfig {
    url: "http://localhost:8080/rpc/batch".to_string(),
    ..Default::default()
};
let client = Client::new(config)?;

WebSocket Transport

// WebSocket transport is implemented and available
// Usage requires creating a WebSocketTransport from an established WebSocket connection
use currentspace_capnweb_transport::WebSocketTransport;
use tokio_tungstenite::connect_async;

let (ws_stream, _) = connect_async("ws://localhost:8080/ws").await?;
let transport = WebSocketTransport::new(ws_stream);

WebTransport/HTTP3

use currentspace_capnweb_server::H3Server;

let mut h3_server = H3Server::new(server);
h3_server.listen("0.0.0.0:8443".parse()?).await?;

Advanced Features

Promise Pipelining

// Promise pipelining is handled internally by the protocol
// Multiple calls in a batch are automatically optimized
let batch = vec![
    Message::Call { /* ... */ },
    Message::Call { /* ... */ },
];
// The server processes these with dependency resolution

Complex Data Structures

use serde_json::json;

// Build complex JSON structures for RPC calls
let request_data = json!({
    "users": [user1, user2, user3],
    "statistics": {
        "total_count": total,
        "active_count": active,
    },
    "metadata": {
        "generated_at": timestamp,
        "version": version_info,
    },
});

Error Handling

match client.call(cap_id, "method", args).await {
    Ok(result) => println!("Success: {}", result),
    Err(e) => {
        // RpcError contains code, message, and optional data
        println!("Error {}: {}", e.code, e.message);
        if let Some(data) = &e.data {
            println!("Additional data: {}", data);
        }
    }
}

Examples

Run the included examples to see the implementation in action:

# Run client examples
cargo run --example basic_client
cargo run --example calculator_client
cargo run --example error_handling
cargo run --example batch_pipelining

# Start the server (using bin/currentspace-capnweb-server)
cargo run --bin currentspace-capnweb-server

Performance

Run benchmarks to measure performance:

cargo bench --bench protocol_benchmarks

The implementation includes optimizations for:

  • Concurrent capability execution
  • Efficient promise dependency resolution
  • Connection pooling and reuse
  • Minimal memory allocations

Testing

Comprehensive test suite with tests across all core modules:

# Run all tests
cargo test --workspace

# Run specific crate tests
cargo test -p currentspace-capnweb-core
cargo test -p currentspace-capnweb-server
cargo test -p currentspace-capnweb-client

# Run with output for debugging
cargo test -- --nocapture

JavaScript Interoperability

The Rust implementation is fully compatible with JavaScript Cap'n Web implementations:

  • ✅ Identical message formats and serialization
  • ✅ Compatible IL plan structures
  • ✅ Matching error handling patterns
  • ✅ Shared protocol semantics

Test interoperability:

cargo test --package currentspace-capnweb-interop-tests

Production Deployment

Configuration

use currentspace_capnweb_server::ServerConfig;

let config = ServerConfig {
    port: 8080,
    host: "0.0.0.0".to_string(),
    max_batch_size: 100,
};

Monitoring

use tracing::{info, warn, error};
use tracing_subscriber;

// Enable structured logging
tracing_subscriber::fmt()
    .with_max_level(tracing::Level::INFO)
    .json()
    .init();

Security

  • Use proper TLS certificates for WebTransport
  • Implement authentication for capability access
  • Configure appropriate rate limiting
  • Enable audit logging for capability calls

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass: cargo test
  5. Run benchmarks: cargo bench
  6. Submit a pull request

Development Standards

  • Zero panics - No unwrap() in production code, all errors handled explicitly
  • All code must pass cargo test and cargo clippy
  • Use latest crate versions unless compatibility requires older versions
  • Research errors before attempting fixes
  • Comprehensive documentation for all public APIs
  • See RUST_CODING_STANDARDS.md for complete guidelines

Automated Code Review

This repository uses CodeRabbit for automated PR reviews. The bot will:

  • Check for compliance with our coding standards
  • Suggest improvements for error handling and performance
  • Verify protocol implementation correctness
  • Ensure no unwrap() or panic! in production code

Configuration is in .coderabbit.yaml. The bot's suggestions are educational but not mandatory - maintainers make final decisions.

License

Licensed under either of:

at your option.

Documentation

📚 Online Documentation

📖 Project Documentation

🔧 Building Documentation Locally

# Build documentation with all features
cargo doc --workspace --all-features --no-deps --open

# Build with private items documented
cargo doc --workspace --all-features --document-private-items --no-deps --open

# Check for documentation issues
cargo doc --workspace --all-features --no-deps 2>&1 | grep warning

📝 Documentation Coverage

All public APIs are documented. To check documentation coverage:

cargo rustdoc -p currentspace-capnweb-core -- -Z unstable-options --show-coverage

Roadmap

  • Certificate-based authentication
  • Capability attestation and verification
  • Message compression for large payloads
  • Streaming capabilities for real-time data
  • Protocol versioning and evolution
  • Performance optimizations and caching

Built with ❤️ in Rust. Ready for production use.