Merge pull request #1205 from endojs/mfig-captp-robustness

`@endo/captp` client robustness features

Author: michaelfig

packages/captp/src/captp.js

@@ -0,0 +1,130 @@
+/* global globalThis */
+import { Far, isObject } from '@endo/marshal';
+
+// @ts-check
+const { WeakRef, FinalizationRegistry } = globalThis;
+
+/**
+ * @template K
+ * @template {object} V
+ * @typedef {Pick<Map<K, V>, 'get' | 'has' | 'delete'> &
+ *  {
+ *   set: (key: K, value: V) => void,
+ *   clearWithoutFinalizing: () => void,
+ *   getSize: () => number,
+ * }} FinalizingMap
+ */
+
+/**
+ *
+ * Elsewhere this is known as a "Weak Value Map". Whereas a std JS WeakMap
+ * is weak on its keys, this map is weak on its values. It does not retain these
+ * values strongly. If a given value disappears, then the entries for it
+ * disappear from every weak-value-map that holds it as a value.
+ *
+ * Just as a WeakMap only allows gc-able values as keys, a weak-value-map
+ * only allows gc-able values as values.
+ *
+ * Unlike a WeakMap, a weak-value-map unavoidably exposes the non-determinism of
+ * gc to its clients. Thus, both the ability to create one, as well as each
+ * created one, must be treated as dangerous capabilities that must be closely
+ * held. A program with access to these can read side channels though gc that do
+ * not* rely on the ability to measure duration. This is a separate, and bad,
+ * timing-independent side channel.
+ *
+ * This non-determinism also enables code to escape deterministic replay. In a
+ * blockchain context, this could cause validators to differ from each other,
+ * preventing consensus, and thus preventing chain progress.
+ *
+ * JS standards weakrefs have been carefully designed so that operations which
+ * `deref()` a weakref cause that weakref to remain stable for the remainder of
+ * that turn. The operations below guaranteed to do this derefing are `has`,
+ * `get`, `set`, `delete`. Note that neither `clearWithoutFinalizing` nor
+ * `getSize` are guaranteed to deref. Thus, a call to `map.getSize()` may
+ * reflect values that might still be collected later in the same turn.
+ *
+ * @template K
+ * @template {object} V
+ * @param {(key: K) => void} [finalizer]
+ * @returns {FinalizingMap<K, V> &
+ *  import('@endo/eventual-send').RemotableBrand<{}, FinalizingMap<K, V>>
+ * }
+ */
+export const makeFinalizingMap = finalizer => {
+  if (!WeakRef || !FinalizationRegistry) {
+    /** @type Map<K, V> */
+    const keyToVal = new Map();
+    return Far('fakeFinalizingMap', {
+      clearWithoutFinalizing: keyToVal.clear.bind(keyToVal),
+      get: keyToVal.get.bind(keyToVal),
+      has: keyToVal.has.bind(keyToVal),
+      set: (key, val) => {
+        keyToVal.set(key, val);
+      },
+      delete: keyToVal.delete.bind(keyToVal),
+      getSize: () => keyToVal.size,
+    });
+  }
+  /** @type Map<K, WeakRef<any>> */
+  const keyToRef = new Map();
+  const registry = new FinalizationRegistry(key => {
+    // Because this will delete the current binding of `key`, we need to
+    // be sure that it is not called because a previous binding was collected.
+    // We do this with the `unregister` in `set` below, assuming that
+    // `unregister` *immediately* suppresses the finalization of the thing
+    // it unregisters. TODO If this is not actually guaranteed, i.e., if
+    // finalizations that have, say, already been scheduled might still
+    // happen after they've been unregistered, we will need to revisit this.
+    // eslint-disable-next-line no-use-before-define
+    finalizingMap.delete(key);
+  });
+  const finalizingMap = Far('finalizingMap', {
+    /**
+     * `clearWithoutFinalizing` does not `deref` anything, and so does not
+     * suppress collection of the weakly-pointed-to values until the end of the
+     * turn.  Because `clearWithoutFinalizing` immediately removes all entries
+     * from this map, this possible collection is not observable using only this
+     * map instance.  But it is observable via other uses of WeakRef or
+     * FinalizationGroup, including other map instances made by this
+     * `makeFinalizingMap`.
+     */
+    clearWithoutFinalizing: () => {
+      for (const ref of keyToRef.values()) {
+        registry.unregister(ref);
+      }
+      keyToRef.clear();
+    },
+    // Does deref, and thus does guarantee stability of the value until the
+    // end of the turn.
+    get: key => keyToRef.get(key)?.deref(),
+    has: key => finalizingMap.get(key) !== undefined,
+    // Does deref, and thus does guarantee stability of both old and new values
+    // until the end of the turn.
+    set: (key, ref) => {
+      assert(isObject(ref));
+      finalizingMap.delete(key);
+      const newWR = new WeakRef(ref);
+      keyToRef.set(key, newWR);
+      registry.register(ref, key, newWR);
+    },
+    delete: key => {
+      const wr = keyToRef.get(key);
+      if (!wr) {
+        return false;
+      }
+
+      registry.unregister(wr);
+      keyToRef.delete(key);
+
+      // Our semantics are to finalize upon explicit `delete`, `set` (which
+      // calls `delete`) or garbage collection (which also calls `delete`).
+      // `clearWithoutFinalizing` is exempt.
+      if (finalizer) {
+        finalizer(key);
+      }
+      return true;
+    },
+    getSize: () => keyToRef.size,
+  });
+  return finalizingMap;
+};

packages/captp/src/finalize.js

@@ -1,6 +1,7 @@
 import { Far } from '@endo/marshal';
 import { E, makeCapTP } from './captp.js';
 import { nearTrapImpl } from './trap.js';
+import { makeFinalizingMap } from './finalize.js';
 
 export { E };
 
@@ -13,26 +14,30 @@ export { E };
  * Create an async-isolated channel to an object.
  *
  * @param {string} ourId
+ * @param {import('./captp.js').CapTPOptions} [nearOptions]
+ * @param {import('./captp.js').CapTPOptions} [farOptions]
  * @returns {{
  *   makeFar<T>(x: T): ERef<T>,
  *   makeNear<T>(x: T): ERef<T>,
  *   makeTrapHandler<T>(x: T): T,
+ *   isOnlyNear(x: any): boolean,
+ *   isOnlyFar(x: any): boolean,
+ *   getNearStats(): any,
+ *   getFarStats(): any,
  *   Trap: Trap
  * }}
  */
-export const makeLoopback = ourId => {
-  let nextNonce = 0;
-  const nonceToRef = new Map();
+export const makeLoopback = (ourId, nearOptions, farOptions) => {
+  let lastNonce = 0;
+  const nonceToRef = makeFinalizingMap();
 
-  const bootstrap = harden({
-    refGetter: Far('refGetter', {
-      getRef(nonce) {
-        // Find the local ref for the specified nonce.
-        const xFar = nonceToRef.get(nonce);
-        nonceToRef.delete(nonce);
-        return xFar;
-      },
-    }),
+  const bootstrap = Far('refGetter', {
+    getRef(nonce) {
+      // Find the local ref for the specified nonce.
+      const xFar = nonceToRef.get(nonce);
+      nonceToRef.delete(nonce);
+      return xFar;
+    },
   });
 
   const slotBody = JSON.stringify({
@@ -45,6 +50,8 @@ export const makeLoopback = ourId => {
     Trap,
     dispatch: nearDispatch,
     getBootstrap: getFarBootstrap,
+    getStats: getNearStats,
+    isOnlyLocal: isOnlyNear,
     // eslint-disable-next-line no-use-before-define
   } = makeCapTP(`near-${ourId}`, o => farDispatch(o), bootstrap, {
     trapGuest: ({ trapMethod, slot, trapArgs }) => {
@@ -63,38 +70,48 @@ export const makeLoopback = ourId => {
       // eslint-disable-next-line no-use-before-define
       return [isException, farSerialize(value)];
     },
+    ...nearOptions,
   });
   assert(Trap);
 
   const {
     makeTrapHandler,
     dispatch: farDispatch,
     getBootstrap: getNearBootstrap,
+    getStats: getFarStats,
+    isOnlyLocal: isOnlyFar,
     unserialize: farUnserialize,
     serialize: farSerialize,
-  } = makeCapTP(`far-${ourId}`, nearDispatch, bootstrap);
+  } = makeCapTP(`far-${ourId}`, nearDispatch, bootstrap, farOptions);
 
-  const farGetter = E.get(getFarBootstrap()).refGetter;
-  const nearGetter = E.get(getNearBootstrap()).refGetter;
+  const farGetter = getFarBootstrap();
+  const nearGetter = getNearBootstrap();
 
   /**
-   * @param {ERef<{ getRef(nonce: number): any }>} refGetter
+   * @template T
+   * @param {ERef<{ getRef(nonce: number): T }>} refGetter
    */
   const makeRefMaker =
     refGetter =>
     /**
-     * @param {any} x
+     * @param {T} x
+     * @returns {Promise<T>}
      */
     async x => {
-      const myNonce = nextNonce;
-      nextNonce += 1;
-      nonceToRef.set(myNonce, harden(x));
+      lastNonce += 1;
+      const myNonce = lastNonce;
+      const val = await x;
+      nonceToRef.set(myNonce, harden(val));
       return E(refGetter).getRef(myNonce);
     };
 
   return {
     makeFar: makeRefMaker(farGetter),
     makeNear: makeRefMaker(nearGetter),
+    isOnlyNear,
+    isOnlyFar,
+    getNearStats,
+    getFarStats,
     makeTrapHandler,
     Trap,
   };

packages/captp/src/loopback.js

@@ -0,0 +1,20 @@
+/* global globalThis */
+export const detectEngineGC = async () => {
+  /** @type {() => void} */
+  const globalGC = globalThis.gc;
+  if (typeof globalGC === 'function') {
+    return globalGC;
+  }
+
+  // Node.js v8 wizardry to dynamically find the GC capability, regardless of
+  // interpreter command line flags.
+  const { default: vm } = await import('vm');
+  const nodeGC = vm.runInNewContext(`typeof gc === 'function' && gc`);
+  if (nodeGC) {
+    return nodeGC;
+  }
+
+  const { default: v8 } = await import('v8');
+  v8.setFlagsFromString('--expose_gc');
+  return vm.runInNewContext('gc');
+};

packages/captp/test/engine-gc.js

@@ -0,0 +1,92 @@
+/* global setImmediate */
+
+/* A note on our GC terminology:
+ *
+ * We define four states for any JS object to be in:
+ *
+ * REACHABLE: There exists a path from some root (live export or top-level
+ * global) to this object, making it ineligible for collection. Userspace vat
+ * code has a strong reference to it (and userspace is not given access to
+ * WeakRef, so it has no weak reference that might be used to get access).
+ *
+ * UNREACHABLE: There is no strong reference from a root to the object.
+ * Userspace vat code has no means to access the object, although liveslots
+ * might (via a WeakRef). The object is eligible for collection, but that
+ * collection has not yet happened. The liveslots WeakRef is still alive: if
+ * it were to call `.deref()`, it would get the object.
+ *
+ * COLLECTED: The JS engine has performed enough GC to notice the
+ * unreachability of the object, and has collected it. The liveslots WeakRef
+ * is dead: `wr.deref() === undefined`. Neither liveslots nor userspace has
+ * any way to reach the object, and never will again. A finalizer callback
+ * has been queued, but not yet executed.
+ *
+ * FINALIZED: The JS engine has run the finalizer callback. After this point,
+ * the object is thoroughly dead and unremembered, and no longer exists in
+ * one of these four states.
+ *
+ * The transition from REACHABLE to UNREACHABLE always happens as a result of
+ * a message delivery or resolution notification (e.g when userspace
+ * overwrites a variable, deletes a Map entry, or a callback on the promise
+ * queue which closed over some objects is retired and deleted).
+ *
+ * The transition from UNREACHABLE to COLLECTED can happen spontaneously, as
+ * the JS engine decides it wants to perform GC. It will also happen
+ * deliberately if we provoke a GC call with a magic function like `gc()`
+ * (when Node.js imports `engine-gc`, which is morally-equivalent to
+ * running with `--expose-gc`, or when XS is configured to provide it as a
+ * C-level callback). We can force GC, but we cannot prevent it from happening
+ * at other times.
+ *
+ * FinalizationRegistry callbacks are defined to run on their own turn, so
+ * the transition from COLLECTED to FINALIZED occurs at a turn boundary.
+ * Node.js appears to schedule these finalizers on the timer/IO queue, not
+ * the promise/microtask queue. So under Node.js, you need a `setImmediate()`
+ * or two to ensure that finalizers have had a chance to run. XS is different
+ * but responds well to similar techniques.
+ */
+
+/*
+ * `gcAndFinalize` must be defined in the start compartment. It uses
+ * platform-specific features to provide a function which provokes a full GC
+ * operation: all "UNREACHABLE" objects should transition to "COLLECTED"
+ * before it returns. In addition, `gcAndFinalize()` returns a Promise. This
+ * Promise will resolve (with `undefined`) after all FinalizationRegistry
+ * callbacks have executed, causing all COLLECTED objects to transition to
+ * FINALIZED. If the caller can manage call gcAndFinalize with an empty
+ * promise queue, then their .then callback will also start with an empty
+ * promise queue, and there will be minimal uncollected unreachable objects
+ * in the heap when it begins.
+ *
+ * `gcAndFinalize` depends upon platform-specific tools to provoke a GC sweep
+ * and wait for finalizers to run: a `gc()` function, and `setImmediate`. If
+ * these tools do not exist, this function will do nothing, and return a
+ * dummy pre-resolved Promise.
+ */
+
+export async function makeGcAndFinalize(gcPowerP) {
+  const gcPower = await gcPowerP;
+  if (typeof gcPower !== 'function') {
+    if (gcPower !== false) {
+      // We weren't explicitly disabled, so warn.
+      console.warn(
+        Error(`no gcPower() function; skipping finalizer provocation`),
+      );
+    }
+  }
+  return async function gcAndFinalize() {
+    if (typeof gcPower !== 'function') {
+      return;
+    }
+
+    // on Node.js, GC seems to work better if the promise queue is empty first
+    await new Promise(setImmediate);
+    // on xsnap, we must do it twice for some reason
+    await new Promise(setImmediate);
+    gcPower();
+    // this gives finalizers a chance to run
+    await new Promise(setImmediate);
+    // Node.js seems to need another for promises to get cleared out
+    await new Promise(setImmediate);
+  };
+}