@agoric/swingset-liveslots 0.10.3-other-dev-8f8782b.0 → 0.10.3-other-dev-3eb1a1d.0

package/tools/fakeVirtualObjectManager.js

@@ -0,0 +1,62 @@
+import { makeVirtualObjectManager } from '../src/virtualObjectManager.js';
+
+// Note: `fakeVirtualObjectManager` is something of a misnomer here.  The
+// virtual object manager being used to implement this realized by the actual
+// virtual object manager code.  What's being faked is everything else the
+// virtual object manager is embedded in, i.e., the kernel and the rest of
+// liveslots.  In particular, this module can be (and is, and is intended to be)
+// used for unit tests for the virtual object manager itself.  What you get back
+// from `makeFakeVirtualObjectManager` can't be used to program as if you were
+// running in a vat because the rest of the vat environment is not present, but
+// it *will* execute virtual object manager operations in the same way that the
+// real one will because underneath it *is* the real one.
+
+export function makeFakeVirtualObjectManager(vrm, fakeStuff) {
+  const {
+    initializeKindHandleKind,
+    defineKind,
+    defineKindMulti,
+    defineDurableKind,
+    defineDurableKindMulti,
+    makeKindHandle,
+    VirtualObjectAwareWeakMap,
+    VirtualObjectAwareWeakSet,
+    flushStateCache,
+    canBeDurable,
+    insistAllDurableKindsReconnected,
+  } = makeVirtualObjectManager(
+    fakeStuff.syscall,
+    vrm,
+    fakeStuff.allocateExportID,
+    fakeStuff.getSlotForVal,
+    fakeStuff.requiredValForSlot,
+    fakeStuff.registerEntry,
+    fakeStuff.marshal.serialize,
+    fakeStuff.marshal.unserialize,
+    fakeStuff.assertAcceptableSyscallCapdataSize,
+  );
+
+  const normalVOM = {
+    initializeKindHandleKind,
+    defineKind,
+    defineKindMulti,
+    defineDurableKind,
+    defineDurableKindMulti,
+    makeKindHandle,
+    canBeDurable,
+    insistAllDurableKindsReconnected,
+    VirtualObjectAwareWeakMap,
+    VirtualObjectAwareWeakSet,
+  };
+
+  const debugTools = {
+    getValForSlot: fakeStuff.getValForSlot,
+    setValForSlot: fakeStuff.setValForSlot,
+    registerEntry: fakeStuff.registerEntry,
+    deleteEntry: fakeStuff.deleteEntry,
+    flushStateCache,
+    dumpStore: fakeStuff.dumpStore,
+  };
+
+  return harden({ ...normalVOM, ...debugTools });
+}

package/tools/fakeVirtualSupport.js

@@ -0,0 +1,389 @@
+/* global globalThis */
+/* eslint-disable max-classes-per-file */
+import { assert, Fail } from '@endo/errors';
+import { makeMarshal } from '@endo/marshal';
+import { isPromise } from '@endo/promise-kit';
+
+import { parseVatSlot } from '../src/parseVatSlots.js';
+import { makeVirtualReferenceManager } from '../src/virtualReferences.js';
+import { makeWatchedPromiseManager } from '../src/watchedPromises.js';
+import { makeFakeVirtualObjectManager } from './fakeVirtualObjectManager.js';
+import { makeFakeCollectionManager } from './fakeCollectionManager.js';
+
+const {
+  WeakRef: RealWeakRef,
+  WeakMap: RealWeakMap,
+  WeakSet: RealWeakSet,
+} = globalThis;
+
+class FakeFinalizationRegistry {
+  // eslint-disable-next-line no-useless-constructor, no-empty-function
+  constructor() {}
+
+  // eslint-disable-next-line class-methods-use-this
+  register(_target, _heldValue, _unregisterToken) {}
+
+  // eslint-disable-next-line class-methods-use-this
+  unregister(_unregisterToken) {}
+}
+
+class FakeWeakRef {
+  #target;
+
+  constructor(target) {
+    this.#target = target;
+  }
+
+  deref() {
+    return this.#target; // strong ref
+  }
+}
+
+export function makeFakeLiveSlotsStuff(options = {}) {
+  let vrm;
+  function setVrm(vrmToUse) {
+    assert(!vrm, 'vrm already configured');
+    vrmToUse.initializeIDCounters();
+    vrm = vrmToUse;
+  }
+
+  const {
+    fakeStore = new Map(),
+    weak = false,
+    log,
+    FinalizationRegistry = FakeFinalizationRegistry,
+    WeakRef = FakeWeakRef, // VRM uses this
+    WeakMap = RealWeakMap,
+    WeakSet = RealWeakSet,
+    addToPossiblyDeadSet = () => {},
+    addToPossiblyRetiredSet = () => {},
+  } = options;
+
+  let sortedKeys;
+  let priorKeyReturned;
+  let priorKeyIndex;
+
+  function s(v) {
+    switch (typeof v) {
+      case 'symbol':
+        return v.toString();
+      case 'bigint':
+        return `${v}n`;
+      default:
+        return `${v}`;
+    }
+  }
+
+  function ensureSorted() {
+    if (!sortedKeys) {
+      sortedKeys = [];
+      for (const key of fakeStore.keys()) {
+        sortedKeys.push(key);
+      }
+      sortedKeys.sort((k1, k2) => k1.localeCompare(k2));
+    }
+  }
+
+  function clearGetNextKeyCache() {
+    priorKeyReturned = undefined;
+    priorKeyIndex = -1;
+  }
+  clearGetNextKeyCache();
+
+  function clearSorted() {
+    sortedKeys = undefined;
+    clearGetNextKeyCache();
+  }
+
+  function dumpStore() {
+    ensureSorted();
+    const result = [];
+    for (const key of sortedKeys) {
+      result.push([key, fakeStore.get(key)]);
+    }
+    return result;
+  }
+
+  const syscall = {
+    vatstoreGet(key) {
+      const result = fakeStore.get(key);
+      if (log) {
+        log.push(`get ${s(key)} => ${s(result)}`);
+      }
+      return result;
+    },
+    vatstoreGetNextKey(priorKey) {
+      assert.typeof(priorKey, 'string');
+      ensureSorted();
+      // TODO: binary search for priorKey (maybe missing), then get
+      // the one after that. For now we go simple and slow. But cache
+      // a starting point, because the main use case is a full
+      // iteration. OTOH, the main use case also deletes everything,
+      // which will clobber the cache on each deletion, so it might
+      // not help.
+      const start = priorKeyReturned === priorKey ? priorKeyIndex : 0;
+      let result;
+      for (let i = start; i < sortedKeys.length; i += 1) {
+        const key = sortedKeys[i];
+        if (key > priorKey) {
+          priorKeyReturned = key;
+          priorKeyIndex = i;
+          result = key;
+          break;
+        }
+      }
+      if (!result) {
+        // reached end without finding the key, so clear our cache
+        clearGetNextKeyCache();
+      }
+      if (log) {
+        log.push(`getNextKey ${s(priorKey)} => ${s(result)}`);
+      }
+      return result;
+    },
+    vatstoreSet(key, value) {
+      if (log) {
+        log.push(`set ${s(key)} ${s(value)}`);
+      }
+      if (!fakeStore.has(key)) {
+        clearSorted();
+      }
+      fakeStore.set(key, value);
+    },
+    vatstoreDelete(key) {
+      if (log) {
+        log.push(`delete ${s(key)}`);
+      }
+      if (fakeStore.has(key)) {
+        clearSorted();
+      }
+      fakeStore.delete(key);
+    },
+  };
+
+  function allocateExportID() {
+    return vrm.allocateNextID('exportID');
+  }
+
+  function allocatePromiseID() {
+    return vrm.allocateNextID('promiseID');
+  }
+
+  function allocateCollectionID() {
+    return vrm.allocateNextID('collectionID');
+  }
+
+  // note: The real liveslots slotToVal() maps slots (vrefs) to a WeakRef,
+  // and the WeakRef may or may not contain the target value. Use
+  // options={weak:true} to match that behavior, or the default weak:false to
+  // keep strong references.
+  const WeakRefForSlot = weak ? RealWeakRef : FakeWeakRef;
+  const valToSlot = new WeakMap();
+  const slotToVal = new Map();
+
+  function getSlotForVal(val) {
+    return valToSlot.get(val);
+  }
+
+  function getValForSlot(slot) {
+    const d = slotToVal.get(slot);
+    return d && d.deref();
+  }
+
+  function requiredValForSlot(slot) {
+    const val = getValForSlot(slot);
+    assert(val, `${slot} must have a value`);
+    return val;
+  }
+
+  function setValForSlot(slot, val) {
+    slotToVal.set(slot, new WeakRefForSlot(val));
+  }
+
+  function convertValToSlot(val) {
+    if (!valToSlot.has(val)) {
+      const slot = isPromise(val)
+        ? `p+${allocatePromiseID()}`
+        : `o+${allocateExportID()}`;
+      valToSlot.set(val, slot);
+      setValForSlot(slot, val);
+    }
+    return valToSlot.get(val);
+  }
+
+  function convertSlotToVal(slot) {
+    const { type, id, virtual, durable, facet, baseRef } = parseVatSlot(slot);
+    assert.equal(type, 'object');
+    let val = getValForSlot(baseRef);
+    if (val) {
+      if (virtual || durable) {
+        if (facet !== undefined) {
+          return vrm.getFacet(id, val, facet);
+        }
+      }
+      return val;
+    }
+    let result;
+    if (virtual || durable) {
+      if (vrm) {
+        val = vrm.reanimate(slot);
+        if (facet !== undefined) {
+          result = vrm.getFacet(id, val, facet);
+        }
+      } else {
+        assert.fail('fake liveSlots stuff configured without vrm');
+      }
+    }
+    registerEntry(baseRef, val, facet !== undefined);
+    if (!result) {
+      result = val;
+    }
+    return result;
+  }
+
+  const marshal = makeMarshal(convertValToSlot, convertSlotToVal, {
+    serializeBodyFormat: 'smallcaps',
+    marshalName: 'fakeLiveSlots',
+    errorIdNum: 80_000,
+    marshalSaveError: _err => {},
+  });
+
+  function registerEntry(baseRef, val, valIsCohort) {
+    const { facet } = parseVatSlot(baseRef);
+    !facet ||
+      Fail`registerEntry(${baseRef} should not receive individual facets`;
+    setValForSlot(baseRef, val);
+    if (valIsCohort) {
+      const { id } = parseVatSlot(baseRef);
+      for (const [index, name] of vrm.getFacetNames(id).entries()) {
+        valToSlot.set(val[name], `${baseRef}:${index}`);
+      }
+    } else {
+      valToSlot.set(val, baseRef);
+    }
+  }
+
+  function deleteEntry(slot, val) {
+    if (!val) {
+      val = getValForSlot(slot);
+    }
+    slotToVal.delete(slot);
+    valToSlot.delete(val);
+  }
+
+  function assertAcceptableSyscallCapdataSize(_capdatas) {}
+
+  const maybeExportPromise = _vref => false;
+
+  return {
+    syscall,
+    allocateExportID,
+    allocatePromiseID,
+    allocateCollectionID,
+    getSlotForVal,
+    requiredValForSlot,
+    getValForSlot,
+    setValForSlot,
+    registerEntry,
+    valToSlot,
+    slotToVal,
+    convertValToSlot,
+    convertSlotToVal,
+    marshal,
+    deleteEntry,
+    FinalizationRegistry,
+    WeakRef,
+    WeakMap,
+    WeakSet,
+    addToPossiblyDeadSet,
+    addToPossiblyRetiredSet,
+    dumpStore,
+    setVrm,
+    assertAcceptableSyscallCapdataSize,
+    maybeExportPromise,
+  };
+}
+
+export function makeFakeVirtualReferenceManager(
+  fakeStuff,
+  relaxDurabilityRules = true,
+) {
+  return makeVirtualReferenceManager(
+    fakeStuff.syscall,
+    fakeStuff.getSlotForVal,
+    fakeStuff.getValForSlot,
+    fakeStuff.FinalizationRegistry,
+    fakeStuff.WeakRef,
+    fakeStuff.addToPossiblyDeadSet,
+    fakeStuff.addToPossiblyRetiredSet,
+    relaxDurabilityRules,
+  );
+}
+
+export function makeFakeWatchedPromiseManager(
+  vrm,
+  vom,
+  collectionManager,
+  fakeStuff,
+) {
+  return makeWatchedPromiseManager({
+    syscall: fakeStuff.syscall,
+    vrm,
+    vom,
+    collectionManager,
+    convertValToSlot: fakeStuff.convertValToSlot,
+    convertSlotToVal: fakeStuff.convertSlotToVal,
+    maybeExportPromise: fakeStuff.maybeExportPromise,
+  });
+}
+
+/**
+ * Configure virtual stuff with relaxed durability rules and fake liveslots
+ *
+ * @param {object} [options]
+ * @param {number} [options.cacheSize]
+ * @param {boolean} [options.relaxDurabilityRules]
+ * @param {Map<string, string>} [options.fakeStore]
+ * @param {WeakMapConstructor} [options.WeakMap]
+ * @param {WeakSetConstructor} [options.WeakSet]
+ * @param {boolean} [options.weak]
+ */
+export function makeFakeVirtualStuff(options = {}) {
+  const actualOptions = {
+    relaxDurabilityRules: true,
+    ...options,
+  };
+  const { relaxDurabilityRules } = actualOptions;
+  const fakeStuff = makeFakeLiveSlotsStuff(actualOptions);
+  const vrm = makeFakeVirtualReferenceManager(fakeStuff, relaxDurabilityRules);
+  fakeStuff.setVrm(vrm);
+  const vom = makeFakeVirtualObjectManager(vrm, fakeStuff);
+  vom.initializeKindHandleKind();
+  const cm = makeFakeCollectionManager(vrm, fakeStuff, actualOptions);
+  const wpm = makeFakeWatchedPromiseManager(vrm, vom, cm, fakeStuff);
+  wpm.preparePromiseWatcherTables();
+  return { fakeStuff, vrm, vom, cm, wpm };
+}
+
+export function makeStandaloneFakeVirtualObjectManager(options = {}) {
+  const fakeStuff = makeFakeLiveSlotsStuff(options);
+  const { relaxDurabilityRules = true } = options;
+  const vrm = makeFakeVirtualReferenceManager(fakeStuff, relaxDurabilityRules);
+  fakeStuff.setVrm(vrm);
+  const vom = makeFakeVirtualObjectManager(vrm, fakeStuff);
+  vom.initializeKindHandleKind();
+  return vom;
+}
+
+export function makeStandaloneFakeCollectionManager(options = {}) {
+  const fakeStuff = makeFakeLiveSlotsStuff(options);
+  const { relaxDurabilityRules = true } = options;
+  const vrm = makeFakeVirtualReferenceManager(fakeStuff, relaxDurabilityRules);
+  fakeStuff.setVrm(vrm);
+  return makeFakeCollectionManager(vrm, fakeStuff, options);
+}
+
+export {
+  makeStandaloneFakeVirtualObjectManager as makeFakeVirtualObjectManager,
+  makeStandaloneFakeCollectionManager as makeFakeCollectionManager,
+};

package/tools/prepare-strict-test-env.js

@@ -0,0 +1,124 @@
+/**
+ * Prepare Agoric SwingSet vat global strict environment for testing.
+ *
+ * Installs Hardened JS (and does lockdown), plus adds mocks for virtual objects
+ * and stores.
+ *
+ * Exports tools for simulating upgrades.
+ */
+
+import '@agoric/internal/src/install-ses-debug.js';
+
+// eslint-disable-next-line import/order
+import { reincarnate, flushIncarnation } from './setup-vat-data.js';
+
+import { makePromiseKit } from '@endo/promise-kit';
+import { Fail } from '@endo/errors';
+import { eventLoopIteration } from '@agoric/internal/src/testing-utils.js';
+import { makeUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
+
+export { flushIncarnation };
+export { eventLoopIteration as nextCrank };
+
+/**
+ * @import { PromiseKit } from '@endo/promise-kit'
+ * @import { Baggage } from '@agoric/swingset-liveslots'
+ * @import { ReincarnateOptions } from './setup-vat-data.js'
+ */
+
+/** @type {ReincarnateOptions} */
+let incarnation;
+let incarnationNumber = 0;
+
+/** @param {Omit<ReincarnateOptions, 'fakeVomKit' | 'fakeStore'>} [options] */
+export const annihilate = (options = {}) => {
+  // @ts-expect-error fakeStore and fakeVomKit don't exist on type, but drop them if they do at runtime
+  const { fakeStore: _fs, fakeVomKit: _fvk, ...opts } = options;
+  incarnation = reincarnate({ relaxDurabilityRules: false, ...opts });
+  incarnationNumber = 0;
+  return incarnation;
+};
+
+/** @returns {Baggage} */
+export const getBaggage = () => {
+  return incarnation.fakeVomKit.cm.provideBaggage();
+};
+
+/**
+ * @param {ReincarnateOptions} [fromIncarnation]
+ */
+export const nextLife = (fromIncarnation = incarnation) => {
+  incarnation = reincarnate(fromIncarnation);
+  incarnationNumber += 1;
+  return incarnation;
+};
+
+/**
+ * @template {(baggage: Baggage) => Promise<any> | any} B
+ * @param {B} build
+ * @param {(tools: Awaited<ReturnType<B>>) => Promise<void> | void} [run]
+ * @param {object} [options]
+ * @param {ReincarnateOptions} [options.fromIncarnation]
+ * @param {boolean} [options.cleanStart]
+ */
+export const startLife = async (
+  build,
+  run,
+  { fromIncarnation, cleanStart } = {},
+) => {
+  await eventLoopIteration();
+  if (cleanStart) annihilate();
+  const oldIncarnationNumber = incarnationNumber;
+  const oldIncarnation = incarnation;
+  const disconnectionObject = makeUpgradeDisconnection(
+    'vat upgraded',
+    oldIncarnationNumber,
+  );
+  const { fakeVomKit } = nextLife(fromIncarnation);
+  /** @type {Map<string, PromiseKit<any>>} */
+  const previouslyWatchedPromises = new Map();
+  let buildTools;
+  try {
+    buildTools = await build(getBaggage());
+    fakeVomKit.wpm.loadWatchedPromiseTable(vref => {
+      // See revivePromise in liveslots.js
+      const { getValForSlot, valToSlot, setValForSlot } = fakeVomKit.fakeStuff;
+      // Assume all promises were decided by the previous incarnation
+      !getValForSlot(vref) || Fail`Attempting to revive known promise ${vref}`;
+      const pk = makePromiseKit();
+      previouslyWatchedPromises.set(vref, pk);
+      const val = pk.promise;
+      valToSlot.set(val, vref);
+      setValForSlot(vref, val);
+      return val;
+    });
+
+    fakeVomKit.vom.insistAllDurableKindsReconnected();
+
+    await eventLoopIteration();
+    // End of start crank
+  } catch (err) {
+    // Rollback upgrade
+    incarnation = oldIncarnation;
+    incarnationNumber = oldIncarnationNumber;
+    throw err;
+  }
+
+  // Simulate a dispatch of previously decided promise rejections
+  // In real swingset this could happen after some deliveries
+  for (const { reject } of previouslyWatchedPromises.values()) {
+    reject(disconnectionObject);
+  }
+  await eventLoopIteration();
+  // End of resolution dispatch crank
+
+  if (run) {
+    await run(buildTools);
+    await eventLoopIteration();
+  }
+
+  return incarnation;
+};
+
+// Setup the initial incarnation
+annihilate();

package/tools/prepare-test-env.js

@@ -0,0 +1,13 @@
+/**
+ * Prepare Agoric SwingSet vat global environment for testing.
+ *
+ * Installs Hardened JS (and does lockdown), plus adds mocks for virtual objects
+ * and stores.
+ */
+
+import '@agoric/internal/src/install-ses-debug.js';
+
+import { reincarnate } from './setup-vat-data.js';
+
+// Install the VatData globals.
+reincarnate();

package/tools/setup-vat-data.js

@@ -0,0 +1,96 @@
+// @ts-check
+/* global globalThis */
+
+// This file produces the globalThis.VatData property outside of a
+// running SwingSet so that it can be used by '@agoric/vat-data'
+// (which only *consumes* `globalThis.VatData`) in code under test. It
+// also populates the passStyleOf symbol-named property.
+
+import { passStyleOf } from '@endo/pass-style';
+import { PassStyleOfEndowmentSymbol } from '@endo/pass-style/endow.js';
+import { makeFakeVirtualStuff } from './fakeVirtualSupport.js';
+
+const { WeakMap, WeakSet } = globalThis;
+
+/** @typedef {ReturnType<typeof makeFakeVirtualStuff>} FakeVomKit */
+
+/** @type {FakeVomKit} */
+let fakeVomKit;
+
+globalThis.VatData = harden({
+  // @ts-expect-error spread argument for non-rest parameter
+  defineKind: (...args) => fakeVomKit.vom.defineKind(...args),
+  // @ts-expect-error spread argument for non-rest parameter
+  defineKindMulti: (...args) => fakeVomKit.vom.defineKindMulti(...args),
+  // @ts-expect-error spread argument for non-rest parameter
+  defineDurableKind: (...args) => fakeVomKit.vom.defineDurableKind(...args),
+  defineDurableKindMulti: (...args) =>
+    // @ts-expect-error spread argument for non-rest parameter
+    fakeVomKit.vom.defineDurableKindMulti(...args),
+  makeKindHandle: tag => fakeVomKit.vom.makeKindHandle(tag),
+  canBeDurable: (...args) => fakeVomKit.vom.canBeDurable(...args),
+  providePromiseWatcher: (...args) =>
+    // @ts-expect-error spread argument for non-rest parameter
+    fakeVomKit.wpm.providePromiseWatcher(...args),
+  watchPromise: (p, watcher, ...args) =>
+    fakeVomKit.wpm.watchPromise(p, watcher, ...args),
+  makeScalarBigMapStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigMapStore(...args),
+  makeScalarBigWeakMapStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigWeakMapStore(...args),
+  makeScalarBigSetStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigSetStore(...args),
+  makeScalarBigWeakSetStore: (...args) =>
+    fakeVomKit.cm.makeScalarBigWeakSetStore(...args),
+});
+
+globalThis[PassStyleOfEndowmentSymbol] = passStyleOf;
+
+/**
+ * @typedef {import("@agoric/internal").Simplify<
+ *   Omit<NonNullable<Parameters<typeof makeFakeVirtualStuff>[0]>, 'WeakMap' | 'WeakSet'> &
+ *   { fakeVomKit: FakeVomKit; fakeStore: Map<string, string> }
+ * >} ReincarnateOptions
+ */
+
+/**
+ *
+ * @param {Partial<ReincarnateOptions>} options
+ * @returns {Omit<ReincarnateOptions, 'fakeVomKit'>}
+ */
+export const flushIncarnation = (options = {}) => {
+  const { fakeVomKit: fvk = fakeVomKit, ...fakeStuffOptions } = options;
+
+  if (fvk) {
+    fvk.vom.flushStateCache();
+    fvk.cm.flushSchemaCache();
+    fvk.vrm.flushIDCounters();
+  }
+
+  // Clone previous fakeStore (if any) to avoid mutations from previous incarnation
+  const fakeStore = new Map(options.fakeStore);
+
+  return { ...fakeStuffOptions, fakeStore };
+};
+
+/**
+ *
+ * @param {Partial<ReincarnateOptions>} options
+ * @returns {ReincarnateOptions}
+ */
+export const reincarnate = (options = {}) => {
+  const clonedIncarnation = flushIncarnation(options);
+
+  fakeVomKit = makeFakeVirtualStuff({
+    ...clonedIncarnation,
+    WeakMap,
+    WeakSet,
+  });
+
+  // @ts-expect-error toStringTag set imperatively so it doesn't show up in the type
+  globalThis.WeakMap = fakeVomKit.vom.VirtualObjectAwareWeakMap;
+  // @ts-expect-error ditto
+  globalThis.WeakSet = fakeVomKit.vom.VirtualObjectAwareWeakSet;
+
+  return { ...clonedIncarnation, fakeVomKit };
+};