Show HN: Cap'n-rs – Rust implementation of Cloudflare's Cap'n Web protocol

1 month ago 2

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

✅ 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

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

use capnweb_server::{Server, ServerConfig, RpcTarget}; use 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(()) }

use capnweb_client::{Client, ClientConfig}; use 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(()) }

The implementation is organized into focused crates:

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

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

// WebSocket transport is implemented and available // Usage requires creating a WebSocketTransport from an established WebSocket connection use capnweb_transport::WebSocketTransport; use tokio_tungstenite::connect_async; let (ws_stream, _) = connect_async("ws://localhost:8080/ws").await?; let transport = WebSocketTransport::new(ws_stream);

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

// 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

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, }, });

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); } } }

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/capnweb-server) cargo run --bin capnweb-server

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

Comprehensive test suite with tests across all core modules:

# Run all tests cargo test --workspace # Run specific crate tests cargo test -p capnweb-core cargo test -p capnweb-server cargo test -p 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 capnweb-interop-tests

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

use tracing::{info, warn, error}; use tracing_subscriber; // Enable structured logging tracing_subscriber::fmt() .with_max_level(tracing::Level::INFO) .json() .init();

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

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass: cargo test
Run benchmarks: cargo bench
Submit a pull request

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

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.

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

API Documentation (GitHub Pages) - Full API documentation for all crates
- capnweb-core - Core protocol types and messages
- capnweb-transport - Transport implementations
- capnweb-server - Server capabilities
- capnweb-client - Client implementation
docs.rs - Published crate documentation:
- capnweb-core - Core protocol types
- capnweb-transport - Transport layers
- capnweb-server - Server implementation
- capnweb-client - Client library

Cap'n Web Protocol Specification - Technical specification
Development Guide - Implementation guide for contributors
Coding Standards - Rust coding standards and best practices
CodeRabbit Setup - Automated code review configuration

🔧 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

All public APIs are documented. To check documentation coverage:

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