7.5 Using the CapTP API

Goblins relies on a ^mycapn coordination object to communicate over OCapN. The (goblins ocapn captp) module provides a procedure to spawn one:

Procedure: spawn-mycapn netlayers … ¶

Spawn and return a ^mycapn object. netlayers, if provided, are netlayer objects; see Netlayers. The ^mycapn object has three public methods:

• install-netlayer netlayer: Add netlayer to this ^mycapn object’s set of netlayers. Return a promise that will fulfill when the netlayer is ready.
• register obj netlayer-name: Create and return a sturdyref to the object obj using the netlayer named by netlayer-name.
• enliven studyref-vow: Return a promise to the object represented by sturdyref-vow, a promise to a sturdyref.

Persistence Environment: captp-env ¶

The (goblins ocapn ids) module provides procedures for working with sturdyrefs and other ocapn-ids. For example, to share a remote reference to an object, first use the register method of a ^mycapn object, then transform the resulting sturdyref into a string for out-of-band transmission using ocapn-id->string:

Procedure: ocapn-id->string ocapn-id ¶

Return a string representing the sturdyref or peer ID ocapn-id.

This procedure has a corollary for transforming the string representation of a sturdyref back into an object, such as for consumption by the enliven method of a ^mycapn object:

Procedure: string->ocapn-id string-uri ¶

Return a sturdyref or peer ID corresponding to the string string-uri.

Together with netlayers, these three procedures allow for the construction and use of objects which can be accessed from remote machines. If we are operating in the context of a vat and netlayer refers to a configured Tor netlayer (see Tor Onion Services), we could share a greeter actor like this:

> (define (^greeter _bcom name)
    (lambda (friend)
      (format #f "Hello, ~a; I'm ~a!" friend name)))
> (define mycapn (spawn-mycapn netlayer))
> (define alice (spawn ^greeter "Alice"))
> (define alice-ocapn-id ($ mycapn 'register alice 'onion))
> (ocapn-id->string alice-ocapn-id)
=> "ocapn://jv4arqqwntmxs3rljkx3ao5bucci37rxxb575vypovntyve76mmyf4ad.onion/s/nGxw4_p6s91IF-R5r6MMYsZzoByODX46MV7AWTApX5s"

The first string of letters and numbers after “ocapn://” is part of the Tor address. The last one, though, is a swiss-num generated during object registration to uniquely identify that object. See Nonce Registry. Because a swiss-num is a capability and part of a sturdyref, all one must do to enliven Alice on a remote machine with a similarly-configured ^mycapn is provide that sturdyref:

> (define alice ($ mycapn 'enliven (string->ocapn-id "ocapn://...")))
> (on (<- alice "Bob") display)
=> Hello, Bob; I'm Alice!