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/irohbuild their own locators and own their transport configuration. @glowcap/onion,@glowcap/relay, and@glowcap/tcpprovide the other providers and connectors shown below.@glowcap/inprocmoves 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, `;
}
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.