Bindings

The Rust, TypeScript, Python, and Racket bindings wrap glowcap’s C ABI in each language’s conventions. They load the compiled core and the transport libraries you choose. The browser package uses the same core compiled to WebAssembly.

Rust, TypeScript, Python, and Racket wrap the shared C ABI with their own values and lifetimes.

One contract, each language’s idioms

A Runtime owns a Host, which serves your objects, and the transports you choose. Runtime.open(...) installs those transports, and runtime.connect(locator) returns a session whose handshake is complete.

BindingEntry pointAsync idiomActor idiom
RustRuntime, Session, typed enumstokio (opt-in async)spawn over closures
TypeScriptRuntime, Session classJavaScript promisesspawn over callbacks
PythonRuntime, Session, Python valuesasynciospawn over callables
RacketRuntime, session, event structsgreen threads + portsGoblins-style spawn, $, <-

A Session is one connection to a peer, with the operations in the bindings contract, such as fetch, send, publish, and serve. A Host manages many sessions and the introductions between them (modules). A Ref is a capability: passing it as an argument grants its access to the recipient.

A near call runs an actor immediately in the same vat (a container of actors). An eventual send queues a call and returns a promise (modules).

In the browser, @glowcap/web provides the Session API over the WebAssembly core. A page cannot listen on a socket, so it accepts peers over WebRTC or through a relay instead. See In the browser.

Each language page lists its runtime and transport support.

Install a binding

Use a published package or build from a pinned checkout. The package READMEs cover installation for Rust, TypeScript, Python, and Racket. Released packages download the C libraries for their version and verify the release checksums.

Use a binding from a checkout

The packages and archives live in a glowcap checkout. Pin a commit, run zig build, and use the binding in that tree. Set GLOWCAP_LIB_DIR to load the archives from another directory. The packaging notes give the full search order.

The binding README has the path for each language. Add the transports your program needs using the setup instructions for iroh, onion, Noise, or WebRTC. The TCP archive carries Noise over TCP, keyed TCP, and the testing tcp. inproc has its own archive.

Choose an API compares bindings with the Zig package, C ABI, and CLI. Concepts explains the capability model.