@agoric/swingset-vat 0.32.3-upgrade-18-dev-6ddbef0.0 → 0.32.3-upgrade-19-dev-2a71f04.0

package/tools/run-utils.js

@@ -2,12 +2,18 @@ import { Fail, q } from '@endo/errors';
 import { kunser } from '@agoric/kmarshal';
 import { makeQueue } from '@endo/stream';
 
-/** @import { ERef } from '@endo/far' */
+/**
+ * @import { ERef } from '@endo/far'
+ * @import { RunPolicy } from '../src/types-external.js'
+ */
+
+/** @typedef {{ provideRunPolicy: () => RunPolicy | undefined }} RunHarness */
 
 /**
  * @param {import('../src/controller/controller.js').SwingsetController} controller
+ * @param {RunHarness} [harness]
  */
-export const makeRunUtils = controller => {
+export const makeRunUtils = (controller, harness) => {
   const mutex = makeQueue();
   const logRunFailure = reason =>
     console.log('controller.run() failure', reason);
@@ -17,7 +23,7 @@ export const makeRunUtils = controller => {
    * Wait for exclusive access to the controller, then before relinquishing that access,
    * enqueue and process a delivery and return the result.
    *
-   * @param {() => ERef<void | ReturnType<controller['queueToVatObject']>>} deliveryThunk
+   * @param {() => ERef<void | ReturnType<typeof controller['queueToVatObject']>>} deliveryThunk
    * function for enqueueing a delivery and returning the result kpid (if any)
    * @param {boolean} [voidResult] whether to ignore the result
    * @returns {Promise<any>}
@@ -25,7 +31,8 @@ export const makeRunUtils = controller => {
   const queueAndRun = async (deliveryThunk, voidResult = false) => {
     await mutex.get();
     const kpid = await deliveryThunk();
-    const runResultP = controller.run();
+    const runPolicy = harness && harness.provideRunPolicy();
+    const runResultP = controller.run(runPolicy);
     mutex.put(runResultP.catch(logRunFailure));
     await runResultP;
 
@@ -46,10 +53,25 @@ export const makeRunUtils = controller => {
   };
 
   /**
-   * @typedef {import('@endo/eventual-send').EProxy & {
-   *  sendOnly: (presence: unknown) => Record<string, (...args: any) => void>;
-   *  vat: (name: string) => Record<string, (...args: any) => Promise<any>>;
-   * }} EVProxy
+   * @typedef EVProxyMethods
+   * @property {(presence: unknown) => Record<string, (...args: any) => Promise<void>>} sendOnly
+   *   Returns a "methods proxy" for the presence that ignores the results of
+   *   each method invocation.
+   * @property {(name: string) => Record<string, (...args: any) => Promise<any>>} vat
+   *   Returns a "methods proxy" for the root object of the specified vat.
+   *   So e.g. `EV.vat('foo').m(0)` becomes
+   *   `controller.queueToVatRoot('foo', 'm', [0])`.
+   * @property {(presence: unknown) => Record<string, Promise<any>>} get
+   *   Returns a "values proxy" for the presence for which each requested
+   *   property manifests as a promise.
+   */
+  /**
+   * @typedef {import('@endo/eventual-send').EProxy & EVProxyMethods} EVProxy
+   *   Given a presence, return a "methods proxy" for which each requested
+   *   property manifests as a method that forwards its invocation through the
+   *   controller to the presence as an invocation of an identically-named method
+   *   with identical arguments (modulo passable translation).
+   *   So e.g. `EV(x).m(0)` becomes `controller.queueToVatObject(x, 'm', [0])`.
    */
 
   // IMPORTANT WARNING TO USERS OF `EV`
@@ -96,52 +118,39 @@ export const makeRunUtils = controller => {
   // promise that can remain pending indefinitely, possibly to be settled by a
   // future message delivery.
 
-  /** @type {EVProxy} */
-  // @ts-expect-error cast, approximate
-  const EV = Object.assign(
-    presence =>
-      new Proxy(harden({}), {
-        get: (_t, method, _rx) => {
-          const boundMethod = (...args) =>
-            queueAndRun(() =>
-              controller.queueToVatObject(presence, method, args),
-            );
-          return harden(boundMethod);
-        },
-      }),
-    {
-      vat: vatName =>
-        new Proxy(harden({}), {
-          get: (_t, method, _rx) => {
-            const boundMethod = (...args) =>
-              queueAndRun(() =>
-                controller.queueToVatRoot(vatName, method, args),
-              );
-            return harden(boundMethod);
-          },
-        }),
-      sendOnly: presence =>
-        new Proxy(harden({}), {
-          get: (_t, method, _rx) => {
-            const boundMethod = (...args) =>
-              queueAndRun(
-                () => controller.queueToVatObject(presence, method, args),
-                true,
-              );
-            return harden(boundMethod);
-          },
-        }),
-      get: presence =>
-        new Proxy(harden({}), {
-          get: (_t, pathElement, _rx) =>
-            queueAndRun(() =>
-              controller.queueToVatRoot('bootstrap', 'awaitVatObject', [
-                presence,
-                [pathElement],
-              ]),
-            ),
-        }),
-    },
+  /**
+   * @template {(typeof controller.queueToVatObject) | (typeof controller.queueToVatRoot)} T
+   * @param {T} invoker
+   * @param {Parameters<T>[0]} target
+   * @param {boolean} [voidResult]
+   */
+  const makeMethodsProxy = (invoker, target, voidResult = false) =>
+    new Proxy(harden({}), {
+      get: (_t, method, _rx) => {
+        const resultPolicy = voidResult ? 'none' : undefined;
+        const boundMethod = (...args) =>
+          queueAndRun(
+            () => invoker(target, method, args, resultPolicy),
+            voidResult,
+          );
+        return harden(boundMethod);
+      },
+    });
+
+  const EV = /** @type {EVProxy} */ (
+    Object.assign(
+      presence => makeMethodsProxy(controller.queueToVatObject, presence),
+      {
+        vat: vatName => makeMethodsProxy(controller.queueToVatRoot, vatName),
+        sendOnly: presence =>
+          makeMethodsProxy(controller.queueToVatObject, presence, true),
+        get: presence =>
+          new Proxy(harden({}), {
+            get: (_t, key, _rx) =>
+              EV.vat('bootstrap').awaitVatObject(presence, [key]),
+          }),
+      },
+    )
   );
   return harden({ queueAndRun, EV });
 };

package/tools/vat-puppet.js

@@ -0,0 +1,111 @@
+/**
+ * @file Source code for a vat that exposes reflective methods for use in
+ *   testing.
+ */
+
+import { Fail, q } from '@endo/errors';
+import { Far, E } from '@endo/far';
+import { makePromiseKit } from '@endo/promise-kit';
+import { objectMap } from '@agoric/internal';
+
+/**
+ * @callback Die
+ * @param {unknown} completion
+ * @param {[target: unknown, method: string, ...args: unknown[]]} [finalSend]
+ */
+
+/**
+ * @typedef {Array<[name: string, ...args: unknown[]]>} CallLog
+ */
+
+/**
+ * @param {import('@agoric/swingset-vat').VatPowers} vatPowers
+ * @param {import('@agoric/vat-data').Baggage} baggage
+ */
+export const makeReflectionMethods = (vatPowers, baggage) => {
+  let baggageHoldCount = 0;
+  /** @type {Map<object, CallLog>} */
+  const callLogsByRemotable = new Map();
+  const heldInHeap = [];
+  const send = (target, method, ...args) => E(target)[method](...args);
+  const makeSpy = (value, name, callLog) => {
+    const spyName = `get ${name}`;
+    const spy = {
+      [spyName](...args) {
+        callLog.push([name, ...args]);
+        return value;
+      },
+    }[spyName];
+    return spy;
+  };
+
+  return {
+    /** @type {Die} */
+    dieHappy: (completion, finalSend) => {
+      vatPowers.exitVat(completion);
+      if (finalSend) send(...finalSend);
+    },
+
+    /** @type {Die} */
+    dieSad: (reason, finalSend) => {
+      vatPowers.exitVatWithFailure(/** @type {Error} */ (reason));
+      if (finalSend) send(...finalSend);
+    },
+
+    holdInBaggage: (...values) => {
+      for (const value of values) {
+        baggage.init(`held-${baggageHoldCount}`, value);
+        baggageHoldCount += 1;
+      }
+      return baggageHoldCount;
+    },
+
+    holdInHeap: (...values) => heldInHeap.push(...values),
+
+    makePromiseKit: () => {
+      const { promise, ...resolverMethods } = makePromiseKit();
+      void promise.catch(() => {});
+      const resolver = Far('resolver', resolverMethods);
+      return harden({ promise, resolver });
+    },
+
+    makeUnsettledPromise() {
+      const { promise } = makePromiseKit();
+      void promise.catch(() => {});
+      return promise;
+    },
+
+    /**
+     * Returns a remotable with methods that return provided values. Invocations
+     * of those methods and their arguments are captured for later retrieval by
+     * `getCallLogForRemotable`.
+     *
+     * @param {string} [label]
+     * @param {Record<string, any>} [fields]
+     */
+    makeRemotable: (label = 'Remotable', fields = {}) => {
+      /** @type {CallLog} */
+      const callLog = [];
+      const methods = objectMap(fields, (value, name) =>
+        makeSpy(value, name, callLog),
+      );
+      const remotable = Far(label, { ...methods });
+      callLogsByRemotable.set(remotable, callLog);
+      return remotable;
+    },
+
+    /**
+     * @param {object} remotable
+     * @returns {CallLog}
+     */
+    getCallLogForRemotable: remotable =>
+      callLogsByRemotable.get(remotable) ||
+      Fail`unknown remotable ${q(remotable)}`,
+  };
+};
+harden(makeReflectionMethods);
+
+export function buildRootObject(vatPowers, _vatParameters, baggage) {
+  const methods = makeReflectionMethods(vatPowers, baggage);
+  return Far('root', methods);
+}