Racket
The Racket binding gives you a Runtime and session API shaped like Spritely Goblins, with Racket values (glowcap.rkt). The transport modules are glowcap-iroh.rkt, glowcap-onion.rkt, glowcap-relay.rkt, glowcap-tcp.rkt, glowcap-webrtc.rkt, and glowcap-inproc.rkt. The Bindings page covers install, and modules has the actor vocabulary.
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. Save the combined code in a file beginning with #lang racket/base, then run it with racket.
The WebRTC tab needs a signaling object supplied by your application. It carries offers, answers, and candidates between the peers.
The same round-trip
Run the Start building round-trip in Racket:
noise-tcp
(require glowcap/glowcap glowcap/glowcap-tcp)
;; Same TCP sockets as keyed dialing; Noise_XK seals the CapTP stream.
(define peer-key "<64 lowercase hex characters from the server>")
(define partner (noise-tcp-locator peer-key "127.0.0.1" 9099))
(define runtime (open-runtime #:providers (list (tcp-provider))))
iroh
(require glowcap/glowcap
glowcap/glowcap-iroh)
;; IROH-REACH-DISCOVERY resolves a bare iroh node ID without an address hint.
(define node-id "<64 lowercase hex characters from the server>")
(define partner (iroh-locator node-id))
(define runtime
(open-runtime
#:providers (list (iroh-provider (make-iroh-config IROH-REACH-DISCOVERY)))))
webrtc
(require glowcap/glowcap
glowcap/glowcap-webrtc)
;; 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.
(define signaling
(make-webrtc-signaling
#:offer (lambda (exchange peer sdp) (error "send the offer, return the answer"))
#:answer (lambda (exchange peer sdp) (error "send the answer to an inbound offer"))
#:candidate (lambda (exchange ice) (error "send one candidate"))
#:on-candidate (lambda (exchange peer sink) (error "call sink with each far candidate"))))
(define partner (webrtc-locator "<64 lowercase hex characters from the peer>"))
(define runtime (open-runtime #:providers (list (webrtc-provider signaling))))
noise-relay
(require glowcap/glowcap glowcap/glowcap-relay)
;; Noise_XK seals the CapTP stream end to end through the relay.
(define peer-key "<64 lowercase hex characters from the server>")
(define relay-url "wss://relay.example/relay")
(define partner (noise-relay-locator peer-key relay-url))
(define runtime
(open-runtime #:providers (list (relay-provider #:relay-url relay-url))))
onion
(require glowcap/glowcap glowcap/glowcap-onion)
;; glowcap starts no Tor; point the provider at an existing SOCKS endpoint.
(define partner (onion-locator "<56-character onion service id>"))
(define runtime
(open-runtime #:providers
(list (onion-provider #:socks "/run/tor/socks"))))
keyed-tcp
(require glowcap/glowcap glowcap/glowcap-tcp)
;; Key designator, cleartext CapTP. Partners dial the public key; the host:port is a hint.
(define peer-key "<64 lowercase hex characters from the server>")
(define partner (keyed-tcp-locator peer-key "127.0.0.1" 9099))
(define runtime (open-runtime #:providers (list (tcp-provider))))
keyed-relay
(require glowcap/glowcap glowcap/glowcap-relay)
;; The key names the peer; the hint names the relay that can reach it.
(define peer-key "<64 lowercase hex characters from the server>")
(define relay-url "wss://relay.example/relay")
(define partner (keyed-relay-locator peer-key relay-url))
(define runtime
(open-runtime #:providers (list (relay-provider #:relay-url relay-url))))
tcp
(require glowcap/glowcap glowcap/glowcap-tcp)
;; Plain TCP uses a cleartext host and port.
(define partner (tcp-locator "127.0.0.1" 9099))
(define runtime (open-runtime #:providers (list (tcp-provider))))
Fetch the greeter and call its greet method:
(define session (runtime-connect runtime partner))
(define greeter (session-fetch session "greeter")) ; a capability this peer published
(printf "~a\n" (session-send session greeter 'greet "world"))
(session-close! session)
(runtime-close! runtime)
The iroh tab needs glowcap-iroh.rkt and a node id that iroh discovery can resolve.
Listen
(accept (listen …)) hands back the same session that runtime-connect returns. 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
(require glowcap/glowcap
glowcap/glowcap-tcp)
;; Same bind as keyed-tcp; Noise_XK seals every accepted CapTP stream.
(define seed (make-bytes 32 7)) ; Replace with durable secret bytes.
(define server (listen-noise-tcp "127.0.0.1" 9099 #:seed seed))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))
iroh
(require glowcap/glowcap
glowcap/glowcap-iroh)
;; This listener is named by its node id. Partners can dial it from anywhere.
(define server (listen-iroh (make-iroh-config IROH-REACH-DISCOVERY)))
(printf "~a\n" (iroh-server-uri server)) ; hand this locator to partners
(define host (iroh-server-host server))
(define (accept-session) (iroh-server-accept server))
noise-relay
(require glowcap/glowcap
glowcap/glowcap-relay)
;; Register this key at the relay; Noise_XK seals every accepted CapTP stream.
(define seed (make-bytes 32 7)) ; Replace with durable secret bytes.
(define server (listen-noise-relay
"wss://relay.example/relay"
"wss://relay.example/register"
#:seed seed))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))
onion
(require glowcap/glowcap glowcap/glowcap-onion)
;; glowcap starts no Tor. Name an already-running daemon's SOCKS (and control to host).
(define server (listen-onion #:socks "/run/tor/socks"
#:control "/run/tor/control"))
(printf "~a\n" (onion-server-uri server)) ; hand this locator to partners
(define service-key (onion-server-service-key server)) ; persist securely
(define host (onion-server-host server))
(define (accept-session) (onion-server-accept server))
keyed-tcp
(require glowcap/glowcap
glowcap/glowcap-tcp)
;; Key designator, cleartext CapTP. Persist the seed to keep the same key.
(define seed (make-bytes 32 7)) ; Replace with durable secret bytes.
(define server (listen-keyed-tcp "127.0.0.1" 9099 #:seed seed))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))
tcp
(require glowcap/glowcap
glowcap/glowcap-tcp)
;; Plain TCP binds the host and port you choose.
(define server (listen "127.0.0.1" 9099))
(printf "~a\n" (server-uri server)) ; hand this locator to partners
(define host (server-host server))
(define (accept-session) (accept server))
Publish the greeter and answer incoming calls:
(host-publish host "greeter"
(methods [(greet who)
(format "Hello, ~a" who)]))
(let loop ()
(define session (accept-session))
(thread (lambda () (session-serve session)))
(loop))
A Goblins-style actor API
The verbs follow Goblins, but the vat (the container that runs your actors one call at a time) and the wire are glowcap’s, so an existing Goblins program will not run unchanged. Inside with-vat, you:
- define an actor constructor with
(define (^name bcom arg ...) ...), return itsmethodsbehavior, andspawnit - call it near with
$, or send it eventually with<-or<-np - observe a promise with
on - become a new behavior with
bcom
To reach a partner, use runtime-connect, session-fetch, and session-send.
$and<-, near-call and eventual-send, come straight from the E language, and The modules page defines both. Across a session only<-and<-npwork, since a partner’s object is never in your vat.
Async
Concurrency is Racket’s own green threads and ports. (session-serve sess) pumps the inbound loop, so run it on its own green thread, and (on vow ...) runs a callback when the vow (Goblins’s word for a promise) settles. Concepts covers the CapTP ideas.
The complete API lives in the Racket binding README. The rooms chat client shows the binding in a complete application.