@agoric/captp

@agoric/captp

A minimal CapTP implementation leveraging Agoric's published modules.

Usage

NOTE: myconn below is not part of the CapTP library, it represents a connection object that you have created where makeCapTP is called on both sides of the connection, passing in the function to send a JSON-able object on the connection, and returning a dispatch function to receive a decoded JSON object from the connection.

import { E, makeCapTP } from '@agoric/captp';

// Create a message dispatcher and bootstrap.
// Messages on myconn are exchanged with JSON-able objects.
const { dispatch, getBootstrap, abort } = makeCapTP('myid', myconn.send, myBootstrap);
myconn.onReceive = obj => dispatch(obj);

// Get the remote's bootstrap object and call a remote method.
E(getBootstrap()).method(args).then(res => console.log('got res', res));

// Tear down the CapTP connection if it fails (e.g. connection is closed).
abort(Error('Connection aborted by user.'));

Loopback

The makeLoopback() function creates an async barrier between "near" and "far" objects. This is useful for testing and isolation within the same address space.

TrapCaps

In addition to the normal CapTP facilities, this library also has the notion of "TrapCaps", which enable a "guest" endpoint to call a "host" object (which may resolve an answer promise at its convenience), but the guest synchronously blocks until it receives the resolved answer.

This is a specialized and advanced use case, not for mutually-suspicious CapTP parties, but instead for clear "guest"/"host" relationship, such as user-space code and synchronous devices.

1. Supply the trapHost and trapGuest protocol implementation (such as the one based on SharedArrayBuffers in src/atomics.js) to the host and guest makeCapTP calls.
2. On the host side, use the returned makeTrapHandler(target) to mark a target as synchronous-enabled.
3. On the guest side, use the returned Trap(target) proxy maker much like E(target), but it will return a synchronous result. Trap will throw an error if target was not marked as a TrapHandler by the host.

To understand how trapHost and trapGuest relate, consider the trapHost as a maker of AsyncIterators which don't return any useful value. These specific iterators are used to drive the transfer of serialized data back to the guest.

trapGuest receives arguments to describe the specific trap request, including startTrap() which sends data to the host to perform the actual work of the trap. The returned (synchronous) iterator from startTrap() drives the async iterator of the host until it fully transfers the trap results to the guest, and the guest unblocks.

The Loopback implementation provides partial support for TrapCaps, except it cannot unwrap promises. Loopback TrapHandlers must return synchronously, or an exception will be thrown.