Rust

The Rust binding gives you typed Runtime, Session, Reference, and Argument over the glowcap archives (lib.rs). See the installation options.

For complete client and server programs, start with the package quick start. Combine a transport tab with the common call or serving code beneath it. Put the asynchronous code inside the quick start’s main and Tokio LocalSet. Enable the Cargo feature named for each optional transport you use.

The WebRTC tab needs a signaling object supplied by your application. It carries offers, answers, and candidates between the peers.

The same round-trip

This is the Start building round-trip in Rust. It uses the crate’s opt-in async feature inside a tokio::task::LocalSet. A session you dial starts reading on its first fetch or send, so the client never calls serve. A session you accept starts reading when you call serve.

noise-tcp

use glowcap::{tcp, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
let peer_key = "<64 lowercase hex characters from the server>";
let partner = tcp::noise::locator(peer_key, "127.0.0.1", 9099);

let runtime = Runtime::open(RuntimeConfig::providers([tcp::provider(tcp::Config::default())])).await?;

iroh

use glowcap::iroh::{self, Reachability};
use glowcap::{Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Discovery resolves a bare iroh node ID without an address hint.
// Cargo.toml: glowcap = { …, features = ["iroh"] }
let node_id = "<64 lowercase hex characters from the server>";
let partner = iroh::locator(node_id, None);

let runtime = Runtime::open(RuntimeConfig::providers([iroh::provider(iroh::Config::new(
    Reachability::Discovery,
))]))
.await?;

webrtc

use std::rc::Rc;

use glowcap::webrtc::{self, SignalingAuthority};
use glowcap::{Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Your signaling carries the offer and each candidate to the peer the locator
// names, over a path you already hold, such as an OCapN capability both peers
// can reach, and brings the answer and the peer's candidates back. Drive the
// runtime from a tokio `LocalSet`: the callbacks run on the thread that steps it.
// Cargo.toml: glowcap = { …, features = ["webrtc"] }
let signaling: Rc<dyn SignalingAuthority> = todo!("your SignalingAuthority");
let partner = webrtc::locator("<64 lowercase hex characters from the peer>");

let runtime =
    Runtime::open(RuntimeConfig::providers([webrtc::provider(signaling, webrtc::Config::default())])).await?;

noise-relay

use glowcap::{relay, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Noise_XK seals the CapTP stream end to end through the relay.
let peer_key = "<64 lowercase hex characters from the server>";
let relay_url = "wss://relay.example/relay";
let partner = relay::noise::locator(peer_key, relay_url);
let runtime = Runtime::open(RuntimeConfig::providers([relay::provider(
	relay::Config::dial_only(relay_url),
)]))
.await?;

onion

use glowcap::onion::{self, Config};
use glowcap::{Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
let partner = onion::locator("<56-character onion service id>");
let runtime = Runtime::open(RuntimeConfig::providers([onion::provider(
	Config::dial_only("/run/tor/socks"),
)]))
.await?;

keyed-tcp

use glowcap::{tcp, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Key designator, cleartext CapTP. Partners dial the public key; the host:port is a hint.
let peer_key = "<64 lowercase hex characters from the server>";
let partner = tcp::keyed::locator(peer_key, "127.0.0.1", 9099);

let runtime = Runtime::open(RuntimeConfig::providers([tcp::provider(tcp::Config::default())])).await?;

keyed-relay

use glowcap::{relay, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// The key names the peer; the hint names the relay that can reach it.
let peer_key = "<64 lowercase hex characters from the server>";
let relay_url = "wss://relay.example/relay";
let partner = relay::keyed::locator(peer_key, relay_url);
let runtime = Runtime::open(RuntimeConfig::providers([relay::provider(
	relay::Config::dial_only(relay_url),
)]))
.await?;

tcp

use glowcap::{tcp, Argument, ConnectOptions, PendingWork, Runtime, RuntimeConfig};

// Plain TCP uses a cleartext host and port.
let partner = tcp::locator("127.0.0.1", 9099);

let runtime = Runtime::open(RuntimeConfig::providers([tcp::provider(tcp::Config::default())])).await?;

Fetch the greeter and call its greet method:

let session = runtime.connect(&partner, ConnectOptions::default()).await?;
let greeter = session.fetch("greeter").await?; // a capability this peer published
match session.send(&greeter, "greet", &["world".into()]).await {
    Ok(Argument::String(reply)) => println!("{reply}"),
    Ok(other) => println!("unexpected reply: {other:?}"),
    Err(reason) => eprintln!("the greeter refused: {reason:?}"),
}
session.close(PendingWork::Cancel).await?;
runtime.close(PendingWork::Cancel).await?;

The iroh tab needs a node id that iroh discovery can resolve.

Listen

listen binds a Server whose accept yields a Session per partner. Keyed and Noise listeners take a 32-byte seed so the listener keeps the same key across restarts. iroh binds a node id instead of a socket address.

noise-tcp

use glowcap::{tcp, Argument};

// Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
let seed = [7u8; 32]; // replace with durable secret bytes across restarts
let server = tcp::noise::listen(
    "127.0.0.1",
    9099,
    tcp::ListenOptions {
        identity: tcp::ListenerIdentity::Seed(seed),
        ..tcp::ListenOptions::default()
    },
)
.await?;

iroh

use glowcap::iroh::{self, Reachability};
use glowcap::Argument;

// This listener is named by its node id. Partners can dial it from anywhere.
// Cargo.toml: glowcap = { …, features = ["iroh"] }
let server = iroh::listen(
    iroh::Config::new(Reachability::Discovery),
    iroh::ListenOptions::default(),
)
.await?;

noise-relay

use glowcap::{relay, Argument};

// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
let seed = [7u8; 32]; // replace with durable secret bytes across restarts
let server = relay::noise::listen(
    "wss://relay.example/relay",
    "wss://relay.example/register",
    relay::ListenOptions {
        identity: relay::ListenerIdentity::Seed(seed),
        ..relay::ListenOptions::default()
    },
)
.await?;

onion

use glowcap::onion::{self, Auth, Config};
use glowcap::Argument;

// glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
let config = Config::dial_only("/run/tor/socks")
    .with_control("/run/tor/control", Auth::None);
let server = onion::listen(config, onion::ListenOptions::default()).await?;
let service_key = server.service_key(); // persist securely to restore this service

keyed-tcp

use glowcap::{tcp, Argument};

// Key designator, cleartext CapTP. Reuse a 32-byte seed to keep the same key.
let seed = [7u8; 32]; // replace with durable secret bytes across restarts
let server = tcp::keyed::listen(
    "127.0.0.1",
    9099,
    tcp::ListenOptions {
        identity: tcp::ListenerIdentity::Seed(seed),
        ..tcp::ListenOptions::default()
    },
)
.await?;

tcp

use glowcap::{tcp, Argument};

// Plain TCP binds the host and port you choose.
let server = tcp::listen("127.0.0.1", 9099, tcp::ListenOptions::default()).await?;

Publish the greeter and answer incoming calls:

println!("{}", server.uri()?); // hand this locator to partners
server.host().publish("greeter", || Box::new(greeter))?;
loop {
    let session = server.accept().await?;
    session.serve().await?;
}

fn greeter(verb: Option<&str>, args: &[Argument]) -> Result<Argument, String> {
    if verb != Some("greet") {
        return Err("no such method".into());
    }
    let Some(Argument::String(name)) = args.first() else {
        return Err("bad invocation".into());
    };
    Ok(Argument::String(format!("Hello, {name}").into()))
}

Async

Async uses tokio behind an opt-in async feature. Handles are !Send, so each lives on one task inside a LocalSet. session.serve().await waits until that session shuts down, and dropping the Session closes the connection.

Actors

session.spawn and session.publish take a FnMut(Option<&str>, &[Argument]) closure returning Result<Argument, String>. An Err breaks the caller’s promise with its message. A panic breaks it too and never unwinds into the C library. To let a third peer reach an actor directly through an introduction, call publish on the Host from server.host(). Concepts covers pipelining and attenuation.

The complete API lives in the Rust binding README, and the rooms chat client shows the binding in a complete application.