Start building

Start with a working conversation: one program publishes an object, and another calls it over encrypted TCP. The Zig example runs both peers for you. Concepts explains capabilities, locators, pipelining, and three-party handoff.

If you prefer another language, choose its guide:

Run a complete example

On Linux or macOS, clone the release branch, main, and install its pinned Zig compiler under your home directory. You need Git, Python 3, Bash, curl, tar, and xz support. The installer verifies the compiler download.

git clone --branch main https://github.com/glowcap-org/glowcap.git
cd glowcap
ZIG_INSTALL_DIR="$HOME/.local/zig" bash .devcontainer/image/zig.sh
export PATH="$HOME/.local/zig:$PATH"
zig build quick-start

The program starts a listener on a free local port, publishes a greeter, connects a second peer, and checks its Hello, world reply. A line beginning 01: greeter fetched by name confirms success.

Read the complete program alongside the walkthrough below. Examples continues with introductions, restricted access, and state that survives a restart.

In Zig

glowcap is a Zig package. Use the compiler version in the toolchain pins, then add a pinned checkout to your build:

zig fetch --save git+https://github.com/glowcap-org/glowcap#COMMIT_SHA

Replace COMMIT_SHA with the revision you want to pin. The public API can still change, so move the pin deliberately.

In build.zig:

const glowcap = b.dependency("glowcap", .{ .target = target, .optimize = optimize });
exe.root_module.addImport("glowcap", glowcap.module("glowcap"));

The glowcap module and the Noise TCP example are pure Zig. Other transports need additional imports.

Dial

Each tab sets up one transport and needs a locator from a running listener. The Listen examples below print that locator. Start with noise-tcp, TCP sealed with the Noise protocol, between two peers that can already reach each other. For a deployment, pick a row from Choosing a transport and use its tab. Plain tcp is cleartext and for local tests only.

One iroh endpoint carries many connections, so the iroh tab registers it once and every connection shares it.

noise-tcp

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Same TCP sockets as cleartext keyed dialing; Noise_XK seals the CapTP stream.
    // The designator is the peer's durable key; the hint is where to dial.
    var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
    const peer_key = "<64 lowercase hex characters from the server>";
    const partner = glowcap.net.tcp.noise.locator(
        peer_key,
        "127.0.0.1:9099",
        &hint_storage,
    );

    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .symbols = &.{.noise_tcp} },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

iroh

const std = @import("std");
const glowcap = @import("glowcap");
const iroh = @import("iroh");

pub fn example(io: std.Io, allocator: std.mem.Allocator, partner_uri: []const u8) !void {
    const partner = try glowcap.ocapn.model.uri.parsePeer(allocator, partner_uri);
    defer glowcap.ocapn.model.freePeerLocator(allocator, partner);
    var endpoint = try iroh.Resident.init(io, null, .{ .reachability = .discovery });
    defer endpoint.deinit() catch |err| std.log.err("iroh endpoint: {s}", .{@errorName(err)});
    var adapter = try iroh.MultiplexedAdapter.init(allocator, &endpoint);
    defer if (adapter.deinit()) |failure| std.log.err("iroh adapter: {s}", .{failure.primaryName()});
    const residents = [_]glowcap.driver.HostRuntime.ProviderRegistration{
        .{ .profile = iroh.transport_profile, .resident = adapter.multiplexed() },
    };

    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .residents = &residents },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

webrtc

const std = @import("std");
const glowcap = @import("glowcap");
const webrtc = @import("webrtc");

// `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. The answer comes back through `Backend.provideAnswer`.
pub fn example(io: std.Io, allocator: std.mem.Allocator, partner_uri: []const u8, signaling: webrtc.SignalingAuthority) !void {
    const partner = try glowcap.ocapn.model.uri.parsePeer(allocator, partner_uri);
    defer glowcap.ocapn.model.freePeerLocator(allocator, partner);
    var endpoint = try webrtc.Resident.init(.{});
    defer endpoint.deinit() catch |err| std.log.err("webrtc endpoint: {s}", .{@errorName(err)});
    var resident = try webrtc.CompletionResident.init(
        allocator,
        try webrtc.Backend.initBound(allocator, &endpoint, signaling, 256, 16 * 1024),
        .{},
    );
    defer resident.deinit();
    const residents = [_]glowcap.driver.HostRuntime.ProviderRegistration{
        .{ .profile = webrtc.transport_profile, .resident = resident.resident() },
    };

    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .residents = &residents },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

noise-relay

const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Noise_XK seals the session end to end; the relay forwards ciphertext.
    const relay_url = "wss://relay.example/relay";
    var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
        .ready => |ready| ready.owner,
        .failed => return error.RelayUnavailable,
    };
    defer switch (tls.release()) {
        .released => {},
        .busy, .failed => std.log.err("relay TLS teardown failed", .{}),
    };
    var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
    try io.randomSecure(&entropy);
    const transports: glowcap.driver.Transports = .{ .symbols = &.{.noise_relay}, .relay = .{
        .url = relay_url,
        .entropy_seed = entropy,
        .resolver_io = io,
        .tls_owner = tls,
    } };
    var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
    const peer_key = "<64 lowercase hex characters from the server>";
    const partner = glowcap.net.relay.noise.locator(peer_key, relay_url, &hint_storage);
    const session = try glowcap.driver.connect(
        allocator,
        io,
        transports,
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

onion

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Dial through a running Tor daemon's SOCKS port.
    const transports: glowcap.driver.Transports = .{ .symbols = &.{.onion}, .onion = .{
        .socks = try glowcap.net.tcp.parseDesignator("127.0.0.1:9050"),
    } };
    const partner = glowcap.net.onion.locator("<56-character onion service id>");
    const session = try glowcap.driver.connect(
        allocator,
        io,
        transports,
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

keyed-tcp

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Key designator, cleartext CapTP. Reuse a seed across restarts to keep the same key.
    var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
    const peer_key = "<64 lowercase hex characters from the server>";
    const partner = glowcap.net.tcp.keyed.locator(
        peer_key,
        "127.0.0.1:9099",
        &hint_storage,
    );

    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .symbols = &.{.keyed_tcp} },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

keyed-relay

const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // The key names the peer; the hint names the relay that can reach it.
    const relay_url = "wss://relay.example/relay";
    var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
        .ready => |ready| ready.owner,
        .failed => return error.RelayUnavailable,
    };
    defer switch (tls.release()) {
        .released => {},
        .busy, .failed => std.log.err("relay TLS teardown failed", .{}),
    };
    var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
    try io.randomSecure(&entropy);
    const transports: glowcap.driver.Transports = .{ .symbols = &.{.keyed_relay}, .relay = .{
        .url = relay_url,
        .entropy_seed = entropy,
        .resolver_io = io,
        .tls_owner = tls,
    } };
    var hint_storage: [1]glowcap.ocapn.model.HintEntry = undefined;
    const peer_key = "<64 lowercase hex characters from the server>";
    const partner = glowcap.net.relay.keyed.locator(peer_key, relay_url, &hint_storage);
    const session = try glowcap.driver.connect(
        allocator,
        io,
        transports,
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

tcp

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Plain TCP uses a cleartext `host:port` locator.
    const partner = glowcap.net.tcp.locator("127.0.0.1:9099");

    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .symbols = &.{.tcp} },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

inproc

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(
    io: std.Io,
    allocator: std.mem.Allocator,
    exchange: *glowcap.net.inproc_completion.Exchange,
) !void {
    // The listening peer and dialer share this process-local switchboard.
    const partner = glowcap.net.inproc.locator("greeter");
    const session = try glowcap.driver.connect(
        allocator,
        io,
        .{ .symbols = &.{.inproc}, .inproc = exchange },
        partner,
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );

Continue the function to fetch the greeter and call greet:

    defer session.deinit();

    const greeter = try session.fetch("greeter"); // a capability this peer published
    var arena = std.heap.ArenaAllocator.init(allocator);
    defer arena.deinit();
    const settled = try session.call(greeter, "greet", &.{.{ .string = "world" }}, arena.allocator());
    switch (settled) {
        .fulfilled => |value| std.debug.print("{s}\n", .{value.string}),
        .broken => |reason| std.debug.print("the greeter refused: {f}\n", .{reason}),
    }
}

The snippets take io and an allocator. Create io from std.Io.Threaded before calling them:

var threaded = std.Io.Threaded.init(allocator, .{});
const io = threaded.io();

A locator says which peer to reach. On the tcp path it is a host:port such as "127.0.0.1:9099". On keyed-tcp (cleartext) and noise-tcp it names the peer by its durable public key, and the address to dial goes in a direct-addresses hint. The relay tabs put the relayโ€™s URL in the hint instead. The Noise guide explains when to choose Noise over iroh, and how noise-relay seals a path through a relay.

handshake is the total time allowed to connect and complete the handshake. settle limits each wait for an answer after that. .ephemeral is a throwaway keypair made for this one connection. The arena owns the memory for replies, and freeing it frees them.

Listen

Each tab is the listening side of the matching Dial tab. It binds an address, publishes a greeter, accepts connections, and serves them.

On keyed and Noise TCP, designator is the address the listener binds, and the durable key goes into the locator it publishes. On iroh, relay, and onion the designator is empty, and the transport fills in the locator it advertises. On inproc it is the name dialers look up.

noise-tcp

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    const seed = @as([32]u8, @splat(7)); // load durable secret bytes in a real service
    const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.noise_tcp} },
        glowcap.ocapn.model.transport.noise_tcp,
        .{ .designator = "127.0.0.1:9099" },
        .{ .keyed = secret },
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // Noise proves this durable key to dialers

    try serve(server);
}

iroh

const std = @import("std");
const glowcap = @import("glowcap");
const iroh = @import("iroh");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    var seed: [32]u8 = undefined;
    try io.randomSecure(&seed); // retain this seed to restore the node identity
    const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
    var endpoint = try iroh.Resident.init(io, &seed, .{ .reachability = .discovery });
    defer endpoint.deinit() catch |err| std.log.err("iroh endpoint: {s}", .{@errorName(err)});
    var adapter = try iroh.MultiplexedAdapter.init(allocator, &endpoint);
    defer if (adapter.deinit()) |failure| std.log.err("iroh adapter: {s}", .{failure.primaryName()});
    const residents = [_]glowcap.driver.HostRuntime.ProviderRegistration{
        .{ .profile = iroh.transport_profile, .resident = adapter.multiplexed() },
    };
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .residents = &residents },
        iroh.transport_name,
        .{ .designator = "" },
        .{ .keyed = secret },
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // hand this locator to partners

    try serve(server);
}

noise-relay

const std = @import("std");
const glowcap = @import("glowcap");
const relay_tls = @import("relay_tls");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // Register this key at the relay; Noise_XK seals every accepted CapTP stream.
    const seed = @as([32]u8, @splat(7)); // load durable secret bytes in a real service
    const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
    var tls = switch (relay_tls.initTlsOwner(io, allocator, .system)) {
        .ready => |ready| ready.owner,
        .failed => return error.RelayUnavailable,
    };
    defer switch (tls.release()) {
        .released => {},
        .busy, .failed => std.log.err("relay TLS teardown failed", .{}),
    };
    var entropy: [std.Random.DefaultCsprng.secret_seed_length]u8 = undefined;
    try io.randomSecure(&entropy);
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.noise_relay}, .relay = .{
            .url = "wss://relay.example/relay",
            .entropy_seed = entropy,
            .resolver_io = io,
            .tls_owner = tls,
            .registration = .{ .url = "wss://relay.example/register" },
        } },
        glowcap.ocapn.model.transport.noise_relay,
        .{ .designator = "" },
        .{ .keyed = secret },
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // Noise seals the relay path end to end

    try serve(server);
}

onion

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    // glowcap starts no Tor. Name an already-running daemon's SOCKS and control ports.
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.onion}, .onion = .{
            .socks = try glowcap.net.tcp.parseDesignator("127.0.0.1:9050"),
            .control = try glowcap.net.tcp.parseDesignator("127.0.0.1:9051"),
        } },
        glowcap.ocapn.model.transport.onion,
        .{ .designator = "" },
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // hand this locator to partners

    var service_key_storage: [256]u8 = undefined;
    const key_len = (try server.restorationState(&service_key_storage)) orelse
        return error.RestorationStateUnavailable;
    const service_key = service_key_storage[0..key_len];
    _ = service_key; // persist securely to restore this service

    try serve(server);
}

keyed-tcp

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    const seed = @as([32]u8, @splat(7)); // load durable secret bytes in a real service
    const secret = glowcap.foundation.crypto.SecretKey.fromSeed(seed);
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.keyed_tcp} },
        glowcap.ocapn.model.transport.keyed_tcp,
        .{ .designator = "127.0.0.1:9099" },
        .{ .keyed = secret },
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // key designator plus direct-addresses hint

    try serve(server);
}

tcp

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.tcp} },
        glowcap.ocapn.model.transport.tcp,
        .{ .designator = "127.0.0.1:9099" },
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    const uri = try glowcap.ocapn.model.uri.writePeer(allocator, (try server.advertisedLocator()));
    defer allocator.free(uri);
    std.debug.print("{s}\n", .{uri}); // hand this locator to partners

    try serve(server);
}

inproc

const std = @import("std");
const glowcap = @import("glowcap");

pub fn example(io: std.Io, allocator: std.mem.Allocator) !void {
    var exchange = glowcap.net.inproc_completion.Exchange.init(allocator);
    defer exchange.deinit();
    const server = try glowcap.driver.listen(
        allocator,
        io,
        .{ .symbols = &.{.inproc}, .inproc = &exchange },
        glowcap.ocapn.model.transport.inproc,
        .{ .designator = "greeter" },
        .ephemeral,
        .{ .handshake = .{ .ms = 10_000 }, .settle = .{ .ms = 10_000 } },
    );
    defer server.deinit();

    try serve(server);
}

Publish the greeter and answer incoming calls:

const Greeter = struct {
    pub fn handle(_: *Greeter, ht: *glowcap.driver.HostTurn, selector: ?[]const u8, args: glowcap.driver.Args) !glowcap.driver.Value {
        defer ht.releaseArguments(args);
        const verb = selector orelse return error.NoSuchMethod;
        if (!std.mem.eql(u8, verb, "greet")) return error.NoSuchMethod;
        if ((try args.len()) != 1) return error.BadInvocation;
        return .{ .string = try ht.turn.arena.print("Hello, {s}", .{try args.string(0)}) };
    }
};

fn serve(server: *glowcap.driver.Server) !void {
    try server.publish("greeter", Greeter, .{});
    while (true) {
        var session = try server.accept();
        defer session.deinit();
        try session.serve();
    }
}

For a runnable program with both peers and their lifetimes in place, use the first example. To try CapTP from a shell instead, see the CapTP CLI.

Add other transports

The iroh, relay, and WebRTC tabs import modules that link outside code. Add .iroh = true or .webrtc = true to the dependency options when using that transport, then add its import:

// iroh: links a Rust library, so the build needs cargo on PATH.
exe.root_module.addImport("iroh", glowcap.module("glowcap_iroh"));
// noise-relay and keyed-relay: builds Mbed TLS from source.
exe.root_module.addImport("relay_tls", glowcap.module("glowcap_relay_tls"));
// webrtc: links a Rust library, so the build needs cargo on PATH.
exe.root_module.addImport("webrtc", glowcap.module("glowcap_webrtc"));