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

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. 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 ] capnweb-server = " 0.1.0 " capnweb-client = " 0.1.0 " Server Example 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 ( ( ) ) } Client Example 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 ( ( ) ) } Architecture The implementation is organized into focused crates: capnweb-core - Core protocol implementation (messages, IL, validation) - Core protocol implementation (messages, IL, validation) capnweb-transport - Transport layer implementations (HTTP, WebSocket, WebTransport) - Transport layer implementations (HTTP, WebSocket, WebTransport) capnweb-server - Server implementation with capability management - Server implementation with capability management capnweb-client - Client implementation with ergonomic recorder API - Client implementation with ergonomic recorder API capnweb-interop-tests - JavaScript interoperability verification Transport Support HTTP Batch Transport 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 // 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 ? ; 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/capnweb-server) cargo run --bin 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 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 Production Deployment Configuration use 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 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 Development Standards Zero panics - No unwrap() in production code, all errors handled explicitly - No in production code, all errors handled explicitly All code must pass cargo test and cargo clippy and 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: 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. 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 capnweb-core -- -Z unstable-options --show-coverage Roadmap Certificate-based authentication Certificate-based authentication Capability attestation and verification Capability attestation and verification Message compression for large payloads Message compression for large payloads Streaming capabilities for real-time data Streaming capabilities for real-time data Protocol versioning and evolution Protocol versioning and evolution Performance optimizations and caching Built with ❤️ in Rust. Ready for production use.