7.4 Using the CapTP API

Goblins uses an actor to communicate over CapTP. This actor can be spawned using the spawn-mycapn procedure from the (goblins ocapn captp) module:

> (define mycapn (spawn-mycapn netlayer))

Where netlayer refers to a CapTP netlayer object. See the next section for details on available netlayers.

Local actors need to be registered so that they can receive messages over CapTP. Registering an actor generates a CapTP identifier for that actor:

> (define alice (spawn ^greeter "Alice"))
> (define alice-captp-id ($ mycapn 'register alice 'onion))

To use this actor on another machine, that machine needs a “sturdyref” to the actor. A sturdyref is a special URI that uniquely identifies the actor on the network. The ocapn-id->string procedure from the (goblins ocapn ids) module can generate such a URI:

> (ocapn-id->string community-sref)
=> "ocapn://jv4arqqwntmxs3rljkx3ao5bucci37rxxb575vypovntyve76mmyf4ad.onion/s/nGxw4_p6s91IF-R5r6MMYsZzoByODX46MV7AWTApX5s"

To generate a Guile URI object instead of a string, use ocapn-id->uri instead.

On the other machine, the sturdyref can be “enlivened” to create a promise that, when resolved, yields a remote object:

> (define vow ($ mycapn 'enliven "ocapn://..."))
> vow
=> #<local-promise>
> (on vow
      (lambda (obj)
        (display obj)
        (newline)))
; #<remote-object>

Sending messages to remote objects using <- looks the same as sending messages to local objects. The message will be transparently sent over CapTP to the remote object!

1. Keeping a persistant sturdyref for an object

   When an object is registered, it is given a “swiss num” (object specific part of the sturdyref). This can be extracted from the ocapn id:

   > (define swiss-num (ocapn-sturdyref-swiss-num alice-captp-id))
   > swiss-num
   => #vu8(156 108 112 227 250 122 179 221 72 23 228 121 175 163 12 98 198 115 160 28 142 13 126 58 49 94 192 89 48 41 95 155)
   

   Often it is desirable to have an object have a persistant sturdyref between sessions; to do this, you need to do two things:

   • Register the object at a specific swiss num
   • Restore the netlayer (see the netlayer section)

   To install the object at a given swiss num, get the nonce registry. This is an object which holds all of the swiss nums to each registered object in mycapn. The following is how this can be done:

   > (define registry ($ mycapn 'get-registry)) ;; nonce registry
   > (define alice-captp-id ($ registry 'register alice swiss-num))