JetStream

JetStream is an RPC framework built on top of s2n-quic, iroh, and p9. It’s designed to be a high performance, low latency, secure, and reliable RPC framework.

Features:

For detailed API documentation, see the rustdoc documentation.

Examples

echo - Basic QUIC-based echo service example
iroh_echo - Echo service using iroh transport
wasm_example - WebAssembly example
wasm_example_bindings - WebAssembly bindings example

JetStream Cloudflare

Let’s say you’ve defined a service like so

use jetstream::prelude::*;

#[cfg(feature = "server")]
mod server;

#[service]
pub trait Radar {
    async fn ping(&mut self) -> Result<()>;
}

The glue code for running it on Cloudflare Workers is

use jetstream::cloudflare::DefaultHtmlFallback;
use worker::{event, *};

use crate::{radar_protocol, Radar};
struct RadarWorker;

impl Radar for RadarWorker {
    async fn ping(&mut self) -> jetstream::prelude::Result<()> {
        Ok(())
    }
}

#[event(fetch)]
async fn fetch(
    req: Request,
    env: Env,
    ctx: worker::Context,
) -> worker::Result<Response> {
    let handler = radar_protocol::RadarService { inner: RadarWorker };
    let mut router =
        jetstream::cloudflare::Router::<DefaultHtmlFallback>::new([handler]);
    router.fetch(req, env, ctx).await
}

The code for connecting to it is as follows:

#![cfg(feature = "client")]
use std::time::Instant;

use argh::FromArgs;
use jetstream::{
    prelude::{jetstream_rpc::HEADER_KEY_JETSTREAM_PROTO, tracing},
    websocket::tokio_tungstenite::{
        connect_async, tungstenite::client::IntoClientRequest,
    },
};
use jetstream_radar::{
    radar_protocol::{self, RadarChannel},
    Radar,
};
use reqwest::header::HeaderValue;
use url::Url;

#[derive(FromArgs, PartialEq, Debug)]
/// Top-level command.
struct Client {
    #[argh(subcommand)]
    nested: Nested,
}

#[derive(FromArgs, PartialEq, Debug)]
#[argh(subcommand)]
enum Nested {
    Ping(Ping),
}

#[derive(FromArgs, PartialEq, Debug)]
/// First subcommand.
#[argh(subcommand, name = "ping")]
struct Ping {
    #[argh(
        option,
        default = "Url::parse(\"wss://radar.jetstream.rs\").unwrap()"
    )]
    /// url to call
    url: Url,
}

#[tokio::main]
async fn main() {
    rustls::crypto::ring::default_provider()
        .install_default()
        .expect("Failed to install rustls crypto provider");

    let args: Client = argh::from_env();
    match args.nested {
        Nested::Ping(web_socket) => {
            tracing::info!("Connecting to {}", web_socket.url);
            let mut req = web_socket.url.clone().into_client_request().unwrap();
            // this is a custom header, doesn't have anything to do with websocket handshake
            req.headers_mut().insert(
                HEADER_KEY_JETSTREAM_PROTO,
                HeaderValue::from_static(radar_protocol::PROTOCOL_VERSION),
            );

            tracing::info!("Attempting websocket connection...");
            let (ws_stream, response) = connect_async(req).await.unwrap();
            tracing::info!(
                "Connected! Response status: {:?}",
                response.status()
            );

            let ws_transport = jetstream::websocket::WebSocketTransport::<
                RadarChannel,
            >::from(ws_stream);

            let mut client =
                radar_protocol::RadarChannel::new(100, Box::new(ws_transport));

            tracing::info!("Sending ping...");
            let now = Instant::now();
            match tokio::time::timeout(
                std::time::Duration::from_secs(5),
                client.ping(),
            )
            .await
            {
                Ok(Ok(_)) => {
                    println!("pong {}ms", now.elapsed().as_millis());
                }
                Ok(Err(e)) => tracing::error!("Ping failed: {:?}", e),
                Err(_) => tracing::error!("Ping timed out after 5 seconds"),
            }
            tracing::info!("Client completed");
        }
    };
}

JetStream Iroh

Iroh is a peer-to-peer networking library that provides NAT traversal, hole punching, and relay fallback. JetStream integrates with Iroh to enable peer-to-peer RPC communication.

Features

NAT Traversal: Automatic hole punching for direct peer-to-peer connections
Relay Fallback: Falls back to relay servers when direct connection isn’t possible
Discovery: Uses JetStream’s discovery service at discovery.jetstream.rs
ALPN-based Protocol Negotiation: Each service defines its own protocol version

Example

Here’s a complete example of an echo service using Iroh transport:

#![cfg(feature = "iroh")]
use crate::echo_protocol::{EchoChannel, EchoService};
use jetstream::prelude::*;
use jetstream_macros::service;
use okstd::prelude::*;

#[service(tracing)]
pub trait Echo {
    async fn square(&mut self, ctx: Context, i: u32) -> Result<String>;
}

#[derive(Debug, Clone)]
struct EchoServer;

impl Echo for EchoServer {
    async fn square(&mut self, _ctx: Context, i: u32) -> Result<String> {
        Ok((i * i).to_string())
    }
}

#[okstd::main]
async fn main() {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_thread_ids(true)
        .with_span_events(
            tracing_subscriber::fmt::format::FmtSpan::ENTER
                | tracing_subscriber::fmt::format::FmtSpan::EXIT,
        )
        .init();
    // Build the server router with the echo service
    let router = jetstream_iroh::server_builder(EchoService {
        inner: EchoServer {},
    })
    .await
    .unwrap();

    // get our own address. At this point we have a running router
    // that's ready to accept connections.
    let addr = router.endpoint().node_addr();

    // Build client transport and connect
    let transport = jetstream_iroh::client_builder::<EchoChannel>(addr)
        .await
        .unwrap();

    let mut ec = EchoChannel::new(10, Box::new(transport));
    for i in 0..10 {
        let b = ec.square(Context::default(), i).await.unwrap();
        println!("square response: {i} * {i} = {b}");
    }

    router.shutdown().await.unwrap();
}

Server Setup

To create an Iroh server, use the server_builder function:

#![allow(unused)]
fn main() {
use jetstream_iroh::server_builder;

let router = server_builder(EchoService { inner: EchoServer {} })
    .await
    .unwrap();

// Get the node address to share with clients
let addr = router.endpoint().node_addr();
}

Client Setup

To connect to an Iroh server, use the client_builder function:

#![allow(unused)]
fn main() {
use jetstream_iroh::client_builder;

let mut transport = client_builder::<EchoChannel>(addr)
    .await
    .unwrap();
}

Discovery

JetStream uses a custom discovery service for Iroh nodes. The discovery URL is:

https://discovery.jetstream.rs

This allows nodes to find each other using their public keys without needing to exchange IP addresses directly.

Feature Flag

To use Iroh transport, enable the iroh feature in your Cargo.toml:

[dependencies]
jetstream = { version = "10", features = ["iroh"] }

For more details, see the jetstream_iroh API documentation.

🦀 Crates

For detailed API documentation of all crates in this repository, please see the rustdoc documentation.

The main crates include:

jetstream - The main crate with the jetstream::prelude module
jetstream_client - Client implementation
jetstream_server - Server implementation
jetstream_wireformat - Encoding and decoding logic
jetstream_macros - Procedural macros
jetstream_rpc - RPC framework core
jetstream_9p - 9P protocol implementation
jetstream_ufs - UFS (Unix File System) implementation
jetstream_quic - QUIC transport
jetstream_iroh - Iroh transport
jetstream_websocket - WebSocket transport

📦 jetstream

📦 jetstream_9p

📦 jetstream_cloudflare

📦 jetstream_error

📦 jetstream_iroh

📦 jetstream_libc

📦 jetstream_macros

📦 jetstream_quic

📦 jetstream_rpc

📦 jetstream_ufs

📦 jetstream_websocket

📦 jetstream_wireformat

Changelog

12.1.0 (2026-01-24)

Features

publish npm package to gh (9b332b9)

Keyboard shortcuts

JetStream Book