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 its methods behavior, and spawn it
  • 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 <-np work, 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.