Crate zel_core 

Type-safe RPC framework built on Iroh with macros for easy service definition.

Zel provides four types of RPC endpoints built on top of Iroh’s peer-to-peer networking: methods (request/response), subscriptions (server-to-client streaming), notifications (client-to-server streaming), and raw bidirectional streams for custom protocols.

Quick Start

use zel_core::prelude::*;
use std::time::Duration;

// Define a service using the macro
#[zel_service(name = "math")]
trait Math {
    #[method(name = "add")]
    async fn add(&self, a: i32, b: i32) -> Result<i32, ResourceError>;
}

// Implement the service
#[derive(Clone)]
struct MathImpl;

#[async_trait]
impl MathServer for MathImpl {
    async fn add(&self, ctx: RequestContext, a: i32, b: i32) -> Result<i32, ResourceError> {
        Ok(a + b)
    }
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Build and start server
    let mut server_bundle = IrohBundle::builder(None).await?;
    let endpoint = server_bundle.endpoint().clone();

    let service = MathImpl;
    let server = RpcServerBuilder::new(b"math/1", endpoint)
        .service("math")
        .build()
        .build();

    let server_bundle = server_bundle.accept(b"math/1", server).finish().await;

    // Create client and make RPC calls
    let client_bundle = IrohBundle::builder(None).await?.finish().await;
    let conn = client_bundle.endpoint
        .connect(server_bundle.endpoint.id(), b"math/1")
        .await?;

    let client = RpcClient::new(conn.clone()).await?;
    let math = MathClient::new(client);
    let result = math.add(5, 3).await?; // Returns 8

    // P2P Resilience: Wait for online, retries
    client_bundle.wait_online().await; // Holepunch/relays ready
    let retry_client = RpcClient::builder(conn)
        .with_retry_config(RetryConfig::builder().max_attempts(3).build()?)
        .build()
        .await?;

    server_bundle.shutdown(Duration::from_secs(5)).await?;
    Ok(())
}

Core Components

• IrohBundle - Manages Iroh endpoint, router, and graceful shutdown
• protocol::RpcServerBuilder - Builds RPC servers with services and middleware
• protocol::RpcClient - Makes RPC calls and manages subscriptions
• protocol::zel_service - Macro for defining type-safe services
• protocol::RequestContext - Provides handlers access to connection info and extensions

Service Endpoint Types

• Methods (#[method]) - Request/response RPC calls
• Subscriptions (#[subscription]) - Server-to-client streaming
• Notifications (#[notification]) - Client-to-server streaming
• Raw Streams (#[stream]) - Bidirectional custom protocols

Examples

The examples directory contains working demonstrations:

• macro_service_example.rs - Complete service with methods and subscriptions
• context_extensions_demo.rs - Three-tier extension system
• notification_example.rs - Client-to-server streaming
• raw_stream_example.rs - Custom bidirectional protocol

Re-exports

pub use protocol::ShutdownError;

pub use protocol::ShutdownHandle;

Modules

prelude

Prelude module containing commonly used types for Zel RPC development.

protocol

RPC protocol implementation including server, client, and service definition.

Structs

BundleBuilder

Builder for configuring an IrohBundle with protocol handlers and shutdown management.

IrohBundle

A bundle containing an Iroh endpoint, router, and shutdown management.

ShutdownReplier

A handle used to signal that a shutdown subscriber has completed its cleanup.

Enums

BuilderError

Errors that can occur when building an Iroh endpoint.

ErrorSeverity

Classification of error severity for circuit breaker and protocol decisions.

ResourceError

Resource-level error type shared between core protocol and macros.

Type Aliases

ShutdownListener

A receiver that listens for shutdown notifications and provides a ShutdownReplier to signal completion.