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: VecValue>) -> ResultValue, 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(), Boxdyn 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(), Boxdyn 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 managementcapnweb-client– Client implementation with ergonomic recorder APIcapnweb-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
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 testandcargo 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()orpanic!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:
at your option.
# 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
Built with ❤️ in Rust. Ready for production use.
