TrapCaps for async host, synchronous guest relationships

packages/captp/NEWS.md

@@ -7,3 +7,7 @@ User-visible changes in captp:
 Moved from https://github.com/Agoric/captp into the `packages/captp/`
 directory in the monorepo at https://github.com/Agoric/agoric-sdk .
 
+## Release 1.8.0
+
+* introduce TrapCaps for synchronous "kernel trap" interfaces (see the
+  README.md).

packages/captp/README.md

@@ -23,3 +23,43 @@ 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.

packages/captp/jsconfig.json

@@ -0,0 +1,18 @@
+// This file can contain .js-specific Typescript compiler config.
+{
+  "compilerOptions": {
+    "target": "esnext",
+
+    "noEmit": true,
+/*
+    // The following flags are for creating .d.ts files:
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+*/
+    "downlevelIteration": true,
+    "strictNullChecks": true,
+    "moduleResolution": "node",
+  },
+  "include": ["src/**/*.js", "src/**/*.d.ts", "exported.js"],
+}