TypeScript

The TypeScript binding runs on Deno, Bun, and the browser from one source tree. @glowcap/runtime (mod.ts) provides the Session and Host API over the C ABI on Deno. Runtime.open installs transport providers and connectors, and runtime.connect chooses one for the peer’s locator.

  • Transport packages such as @glowcap/iroh build their own locators and own their transport configuration.
  • @glowcap/onion, @glowcap/relay, and @glowcap/tcp provide the other providers and connectors shown below.
  • @glowcap/inproc moves raw frames. It has no provider to install into a Runtime, so the Session API cannot use it.

The browser package, @glowcap/web, uses the same Session API over the core compiled to WebAssembly. A page can dial and accept peers through WebRTC or a registered relay route, without opening a listening socket. In the browser covers how a page reaches its peers.

Bun’s synchronous FFI supports Host and locator calls and clients whose JavaScript supplies the bytes. It cannot run the C driver loop, so driver-based dialing and listening are unavailable.

See installation options for released packages. From a checkout, build the archives and run from bindings/ts or point an import map at bindings/ts/runtime/mod.ts. Set GLOWCAP_LIB_DIR to use archives from another directory. Run the client with deno run --allow-all client.ts. Loading a downloaded SDK needs environment, filesystem, subprocess, and FFI permissions as well as network access.

The same round-trip

This is the Start building round-trip on Deno. fetch and send start the inbound loop on demand, so you only need serve when another task waits for the session to shut down.

noise-tcp

import { noise, provider } from "@glowcap/tcp";
import { Runtime } from "@glowcap/runtime";

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

await using runtime = await Runtime.open({ providers: [provider()] });

iroh

import { Runtime } from "@glowcap/runtime";
import { locator, provider, Reachability } from "@glowcap/iroh";

// Discovery resolves a bare iroh node ID without an address hint.
const nodeId = "<64 lowercase hex characters from the server>";
const partner = locator(nodeId);

await using runtime = await Runtime.open({
	providers: [provider({ reachability: Reachability.Discovery })],
});

webrtc

import { Runtime } from "@glowcap/runtime";
import { locator } from "@glowcap/webrtc";
import { provider, type SignalingAuthority } from "@glowcap/webrtc/driver";

// 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. In a
// browser, `connector(signaling)` from `@glowcap/webrtc` takes its place.
declare const signaling: SignalingAuthority;
const peerKey = "<64 lowercase hex characters from the peer>";
const partner = locator(peerKey);

await using runtime = await Runtime.open({
	providers: [provider(signaling)],
});

noise-relay

import { Runtime } from "@glowcap/runtime";
import { noise, provider } from "@glowcap/relay";

// Noise_XK seals the session end to end; the relay forwards ciphertext.
const peerKey = "<64 lowercase hex characters from the server>";
const relayUrl = "wss://relay.example/relay";
const partner = noise.locator(peerKey, relayUrl);

await using runtime = await Runtime.open({
	providers: [provider({ relayUrl })],
});

onion

import { locator, provider } from "@glowcap/onion";
import { Runtime } from "@glowcap/runtime";

// glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
const partner = locator("<56-character onion service id>");

await using runtime = await Runtime.open({
	providers: [provider({ socks: "/run/tor/socks" })],
});

keyed-tcp

import { keyed, provider } from "@glowcap/tcp";
import { Runtime } from "@glowcap/runtime";

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

await using runtime = await Runtime.open({ providers: [provider({ profiles: [keyed] })] });

keyed-relay

import { Runtime } from "@glowcap/runtime";
import { keyed, provider } from "@glowcap/relay";

// The key names the peer; the hint names the relay that can reach it.
const peerKey = "<64 lowercase hex characters from the server>";
const relayUrl = "wss://relay.example/relay";
const partner = keyed.locator(peerKey, relayUrl);

await using runtime = await Runtime.open({
	providers: [provider({ relayUrl })],
});

tcp

import { locator, plain, provider } from "@glowcap/tcp";
import { Runtime } from "@glowcap/runtime";

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

await using runtime = await Runtime.open({ providers: [provider({ profiles: [plain] })] });

Fetch the greeter and call its greet method:

await using session = await runtime.connect(partner);
const greeter = await session.fetch("greeter"); // a capability this peer published
const reply = await session.send(greeter, "greet", ["world"]);
console.log(reply);

The iroh tab needs @glowcap/iroh and a node id that iroh discovery can resolve.

The serve promise resolves when the session closes cleanly and rejects on a transport or protocol error. When the loop ends, every send still awaiting a reply breaks too, so failures surface on the calls you await.

Listen

listen binds a port and returns a Server. Iterate it to accept each Session, publish an actor by name with publish, and dispatch calls to it with serve. 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 host and port.

noise-tcp

import type { Argument } from "@glowcap/runtime";
import { noise } from "@glowcap/tcp";

// Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
const seed = crypto.getRandomValues(new Uint8Array(32));
await using server = await noise.listen("127.0.0.1", 9099, { seed });

iroh

import type { Argument } from "@glowcap/runtime";
import { type IrohConfig, listen, Reachability } from "@glowcap/iroh";

// This listener is named by its node id. Partners can dial it from anywhere.
const config: IrohConfig = { reachability: Reachability.Discovery };
await using server = await listen(config);

noise-relay

import type { Argument } from "@glowcap/runtime";
import { noise } from "@glowcap/relay";

// Register this key at the relay; Noise_XK seals every accepted CapTP stream.
const seed = crypto.getRandomValues(new Uint8Array(32));
await using server = await noise.listen({
	relayUrl: "wss://relay.example/relay",
	registerUrl: "wss://relay.example/register",
	seed,
});

onion

import type { Argument } from "@glowcap/runtime";
import { listen } from "@glowcap/onion";

// glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
await using server = await listen({
	socks: "/run/tor/socks",
	control: "/run/tor/control",
});
const _serviceKey = server.serviceKey; // persist securely to restore this service

keyed-tcp

import type { Argument } from "@glowcap/runtime";
import { keyed } from "@glowcap/tcp";

// Key designator, cleartext CapTP. Reuse a 32-byte seed to keep the same key.
const seed = crypto.getRandomValues(new Uint8Array(32));
await using server = await keyed.listen("127.0.0.1", 9099, { seed });

tcp

import type { Argument } from "@glowcap/runtime";
import { listen } from "@glowcap/tcp";

// Plain TCP binds the host and port you choose.
await using server = await listen("127.0.0.1", 9099);

Publish the greeter and answer incoming calls:

console.log(server.uri); // hand this locator to partners

function greeter(verb: string | null, args: Argument[]): string {
	if (verb !== "greet") throw new Error("no such method");
	if (args.length !== 1 || typeof args[0] !== "string") {
		throw new Error("bad invocation");
	}
	return `Hello, ${args[0]}`;
}

server.host.publish("greeter", greeter);
for await (const accepted of server) {
	await using session = accepted;
	await session.serve();
}

Async

Sessions return JavaScript promises, and a session is disposable: connect with await using and it closes when the block ends. Concepts explains how one call can pipeline on another before it resolves.

Actors

An actor is a callback, (verb, args) => AppValue, that you register with session.spawn or session.publish. Its return value is the partner’s reply, and a throw breaks the caller’s promise. To let a third peer reach an actor directly through an introduction, publish it on a Host: server.host from listen, or new Host(). Modules describes the Host, and Concepts explains the handoff.

The complete API lives in the TypeScript binding README.