@agoric/base-zone 0.1.1-calypso-dev-84eb287.0

package/src/prepare-revocable.js

@@ -0,0 +1,175 @@
+import { M } from '@endo/patterns';
+import { fromUniqueEntries } from '@endo/common/from-unique-entries.js';
+
+const { Fail, quote: q } = assert;
+
+/** @import {Amplify} from '@endo/exo'; */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableMakerKit
+ * @property {(revocable: U) => boolean} revoke
+ * @property {(underlying: U) => U} makeRevocable
+ *   Forwards to the underlying exo object, until revoked
+ */
+
+/**
+ * @typedef {object} RevokerFacet
+ * @property {() => boolean} revoke
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableKit
+ * @property {RevokerFacet} revoker
+ * @property {U} revocable
+ *   Forwards to the underlying exo object, until revoked
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableKitThis
+ * @property {RevocableKit<U>} facets
+ * @property {{ underlying: U }} state
+ */
+
+/**
+ * @template [U=any]
+ * @typedef {object} RevocableKitOptions
+ * @property {string} [uInterfaceName]
+ *   The `interfaceName` of the underlying interface guard.
+ *   Defaults to the `uKindName`.
+ * @property {Record<
+ *   string|symbol,
+ *   import('@endo/patterns').MethodGuard
+ * >} [extraMethodGuards]
+ * For guarding the `extraMethods`, if you include them below. These appear
+ * only on the synthesized interface guard for the revocable caretaker, and
+ * do not necessarily correspond to any method of the underlying.
+ * @property {Record<
+ *   string|symbol,
+ *   (this: RevocableKitThis<U>, ...args: any[]) => any
+ * >} [extraMethods]
+ * Extra methods adding behavior only to the revocable caretaker, and
+ * do not necessarily correspond to any methods of the underlying.
+ */
+
+/**
+ * Make an exo class kit for wrapping an underlying exo class,
+ * where the wrapper is a revocable forwarder.
+ *
+ * @template [U=any]
+ * @param {import('@agoric/base-zone').Zone} zone
+ * @param {string} uKindName
+ *   The `kindName` of the underlying exo class
+ * @param {(string|symbol)[]} uMethodNames
+ *   The method names of the underlying exo class that should be represented
+ *   by transparently-forwarding methods of the revocable caretaker.
+ * @param {RevocableKitOptions} [options]
+ * @returns {RevocableMakerKit<U>}
+ */
+export const prepareRevocableMakerKit = (
+  zone,
+  uKindName,
+  uMethodNames,
+  options = {},
+) => {
+  const {
+    uInterfaceName = uKindName,
+    extraMethodGuards = undefined,
+    extraMethods = undefined,
+  } = options;
+  const RevocableIKit = harden({
+    revoker: M.interface(`${uInterfaceName}_revoker`, {
+      revoke: M.call().returns(M.boolean()),
+    }),
+    revocable: M.interface(
+      `${uInterfaceName}_revocable`,
+      {
+        ...extraMethodGuards,
+      },
+      {
+        defaultGuards: 'raw',
+      },
+    ),
+  });
+
+  const revocableKindName = `${uKindName}_caretaker`;
+
+  /** @type {Amplify<any>} */
+  let amplifier;
+
+  const makeRevocableKit = zone.exoClassKit(
+    revocableKindName,
+    RevocableIKit,
+    underlying => ({
+      underlying,
+    }),
+    {
+      revoker: {
+        revoke() {
+          const { state } = this;
+          if (state.underlying === undefined) {
+            return false;
+          }
+          state.underlying = undefined;
+          return true;
+        },
+      },
+      revocable: {
+        ...fromUniqueEntries(
+          uMethodNames.map(name => [
+            name,
+            {
+              // Use concise method syntax for exo methods
+              [name](...args) {
+                // @ts-expect-error normal exo-this typing confusion
+                const { underlying } = this.state;
+                underlying !== undefined ||
+                  Fail`${q(revocableKindName)} revoked`;
+                return underlying[name](...args);
+              },
+              // @ts-expect-error using possible symbol as index type
+            }[name],
+          ]),
+        ),
+        ...extraMethods,
+      },
+    },
+    {
+      stateShape: {
+        underlying: M.opt(M.remotable('underlying')),
+      },
+      receiveAmplifier: amp => {
+        amplifier = amp;
+      },
+    },
+  );
+
+  /**
+   * @param {U} underlying
+   * @returns {U}
+   */
+  const makeRevocable = underlying =>
+    // @ts-expect-error some confusion about UU vs Guarded<U> I think
+    makeRevocableKit(underlying).revocable;
+
+  /**
+   * @param {U} revocable
+   * @returns {boolean}
+   */
+  const revoke = revocable => {
+    /** @type {RevocableKit<U>} */
+    const facets = amplifier(revocable);
+    if (facets === undefined) {
+      return false;
+    }
+    return facets.revoker.revoke();
+  };
+
+  return harden({
+    revoke,
+    makeRevocable,
+  });
+};
+harden(prepareRevocableMakerKit);

package/src/types.d.ts

@@ -0,0 +1,64 @@
+export type KeyCategories = "exoClass" | "exoClassKit" | "exo" | "store" | "zone";
+export type KeyMakers = Record<KeyCategories, (label: string) => string[]>;
+/**
+ * A bag of methods for creating defensible objects and
+ * collections with the same allocation semantics (ephemeral, persistent, etc)
+ */
+export type Zone = ExoZone & Stores;
+export type ExoZone = {
+    /**
+     * create a singleton exo-object instance bound to this zone
+     */
+    exo: typeof makeExo;
+    /**
+     * create a maker function that can be used to create exo-objects bound to this zone
+     */
+    exoClass: typeof defineExoClass;
+    /**
+     * create a "kit" maker function that can be used to create a record of exo-objects sharing the same state
+     */
+    exoClassKit: typeof defineExoClassKit;
+    /**
+     * create or retrieve a singleton object bound to this zone
+     */
+    makeOnce: <T>(key: string, maker: (key: string) => T) => T;
+    /**
+     * create a new Zone that can be passed to untrusted consumers without exposing the storage of the parent zone
+     */
+    subZone: (label: string, options?: StoreOptions) => Zone;
+    /**
+     * register a promise watcher created by this zone
+     */
+    watchPromise: typeof watchPromise;
+};
+export type Stores = {
+    /**
+     * obtain store providers which are detached (the stores are anonymous rather than bound to `label` in the zone)
+     */
+    detached: () => Stores;
+    /**
+     * return true if the specimen can be stored in the zone, whether as exo-object state or in a store
+     */
+    isStorable: (specimen: unknown) => boolean;
+    /**
+     * provide a Map-like store named `label` in the zone
+     */
+    mapStore: (label: string, options?: StoreOptions) => MapStore<any, any>;
+    /**
+     * provide a Set-like store named `label` in the zone
+     */
+    setStore: <K>(label: string, options?: StoreOptions) => SetStore<K>;
+    /**
+     * provide a WeakMap-like store named `label` in the zone
+     */
+    weakMapStore: <K, V>(label: string, options?: StoreOptions) => WeakMapStore<K, V>;
+    /**
+     * provide a WeakSet-like store named `label` in the zone
+     */
+    weakSetStore: <K>(label: string, options?: StoreOptions) => WeakSetStore<K>;
+};
+import { makeExo } from '@endo/exo';
+import { defineExoClass } from '@endo/exo';
+import { defineExoClassKit } from '@endo/exo';
+import { watchPromise } from './watch-promise.js';
+//# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":"4BAac,UAAU,GAAG,aAAa,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM;wBACrD,MAAM,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;;;;;mBAGnD,OAAO,GAAG,MAAM;;;;;SAMf,OAAO,OAAO;;;;cACd,OAAO,cAAc;;;;iBACrB,OAAO,iBAAiB;;;;cACxB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,KAAK,CAAC;;;;aAChD,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,IAAI;;;;kBAC/C,OAAO,YAAY;;;;;;cAKnB,MAAM,MAAM;;;;gBACZ,CAAC,QAAQ,EAAE,OAAO,KAAK,OAAO;;;;cAC9B,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;;;;cAC7D,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC;;;;kBACzD,CAAC,CAAC,EAAE,CAAC,EAClB,KAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC;;;;kBAEnD,CAAC,CAAC,EACf,KAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,KAAK,YAAY,CAAC,CAAC,CAAC;;wBAxCH,WAAW;+BAAX,WAAW;kCAAX,WAAW;6BAEzC,oBAAoB"}

package/src/types.js

@@ -0,0 +1,44 @@
+// eslint-disable-next-line no-unused-vars
+import { makeExo, defineExoClass, defineExoClassKit } from '@endo/exo';
+// eslint-disable-next-line no-unused-vars
+import { watchPromise } from './watch-promise.js';
+
+// Ensure this is a module.
+export {};
+
+/**
+ * @import {Key} from '@endo/patterns';
+ * @import {Passable} from '@endo/pass-style';
+ */
+
+/** @typedef {'exoClass' | 'exoClassKit' | 'exo' | 'store' | 'zone'} KeyCategories */
+/** @typedef {Record<KeyCategories, (label: string) => string[]>} KeyMakers */
+
+/**
+ * @typedef {ExoZone & Stores} Zone A bag of methods for creating defensible objects and
+ * collections with the same allocation semantics (ephemeral, persistent, etc)
+ */
+
+/**
+ * @typedef {object} ExoZone
+ * @property {typeof makeExo} exo create a singleton exo-object instance bound to this zone
+ * @property {typeof defineExoClass} exoClass create a maker function that can be used to create exo-objects bound to this zone
+ * @property {typeof defineExoClassKit} exoClassKit create a "kit" maker function that can be used to create a record of exo-objects sharing the same state
+ * @property {<T>(key: string, maker: (key: string) => T) => T} makeOnce create or retrieve a singleton object bound to this zone
+ * @property {(label: string, options?: StoreOptions) => Zone} subZone create a new Zone that can be passed to untrusted consumers without exposing the storage of the parent zone
+ * @property {typeof watchPromise} watchPromise register a promise watcher created by this zone
+ */
+
+/**
+ * @typedef {object} Stores
+ * @property {() => Stores} detached obtain store providers which are detached (the stores are anonymous rather than bound to `label` in the zone)
+ * @property {(specimen: unknown) => boolean} isStorable return true if the specimen can be stored in the zone, whether as exo-object state or in a store
+ * @property {(label: string, options?: StoreOptions) => MapStore<any, any>} mapStore provide a Map-like store named `label` in the zone
+ * @property {<K>(label: string, options?: StoreOptions) => SetStore<K>} setStore provide a Set-like store named `label` in the zone
+ * @property {<K, V>(
+ *   label: string, options?: StoreOptions) => WeakMapStore<K, V>
+ * } weakMapStore provide a WeakMap-like store named `label` in the zone
+ * @property {<K>(
+ *   label: string, options?: StoreOptions) => WeakSetStore<K>
+ * } weakSetStore provide a WeakSet-like store named `label` in the zone
+ */

package/src/watch-promise.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A PromiseWatcher method guard callable with one or more arguments, returning void.
+ */
+export const PromiseWatcherHandler: import("@endo/patterns").MethodGuard;
+/**
+ * A PromiseWatcher interface that has both onFulfilled and onRejected handlers.
+ */
+export const PromiseWatcherI: import("@endo/patterns").InterfaceGuard<{
+    onFulfilled: import("@endo/patterns").MethodGuard;
+    onRejected: import("@endo/patterns").MethodGuard;
+}>;
+/**
+ * A PromiseWatcher interface that has only an onFulfilled handler.
+ */
+export const PromiseWatcherFulfilledI: import("@endo/patterns").InterfaceGuard<{
+    onFulfilled: import("@endo/patterns").MethodGuard;
+}>;
+/**
+ * A PromiseWatcher interface that has only an onRejected handler.
+ */
+export const PromiseWatcherRejectedI: import("@endo/patterns").InterfaceGuard<{
+    onRejected: import("@endo/patterns").MethodGuard;
+}>;
+export function watchPromise(p: Promise<any>, watcher: PromiseWatcher, ...watcherArgs: unknown[]): void;
+export type PromiseWatcher = {
+    onFulfilled?: ((fulfilment: unknown, ...args: unknown[]) => void) | undefined;
+    onRejected?: ((reason: unknown, ...args: unknown[]) => void) | undefined;
+};
+//# sourceMappingURL=watch-promise.d.ts.map

package/src/watch-promise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-promise.d.ts","sourceRoot":"","sources":["watch-promise.js"],"names":[],"mappings":"AAQA;;GAEG;AACH,yEAA6E;AAE7E;;GAEG;AACH;;;GAGG;AAEH;;GAEG;AACH;;GAEG;AAEH;;GAEG;AACH;;GAEG;AAuCI,gCALI,OAAO,CAAC,GAAG,CAAC,WACZ,cAAc,kBACX,OAAO,EAAA,GACR,IAAI,CAUhB;;gCA3C0B,OAAO,WAAW,OAAO,EAAE,KAAK,IAAI;2BACxC,OAAO,WAAW,OAAO,EAAE,KAAK,IAAI"}

package/src/watch-promise.js

@@ -0,0 +1,82 @@
+// @ts-check
+import { M } from '@endo/patterns';
+import { E } from '@endo/far';
+
+const { Fail } = assert;
+
+const { apply } = Reflect;
+
+/**
+ * A PromiseWatcher method guard callable with one or more arguments, returning void.
+ */
+export const PromiseWatcherHandler = M.call(M.raw()).rest(M.raw()).returns();
+
+/**
+ * A PromiseWatcher interface that has both onFulfilled and onRejected handlers.
+ */
+export const PromiseWatcherI = M.interface('PromiseWatcher', {
+  onFulfilled: PromiseWatcherHandler,
+  onRejected: PromiseWatcherHandler,
+});
+
+/**
+ * A PromiseWatcher interface that has only an onFulfilled handler.
+ */
+export const PromiseWatcherFulfilledI = M.interface('PromiseWatcherFulfilled', {
+  onFulfilled: PromiseWatcherHandler,
+});
+
+/**
+ * A PromiseWatcher interface that has only an onRejected handler.
+ */
+export const PromiseWatcherRejectedI = M.interface('PromiseWatcherRejected', {
+  onRejected: PromiseWatcherHandler,
+});
+
+/**
+ * @typedef {object} PromiseWatcher
+ * @property {(fulfilment: unknown, ...args: unknown[]) => void} [onFulfilled]
+ * @property {(reason: unknown, ...args: unknown[]) => void} [onRejected]
+ */
+
+/**
+ * Adapt a promise watcher method to E.when.
+ * @param {Record<PropertyKey, (...args: unknown[]) => unknown>} that
+ * @param {PropertyKey} prop
+ * @param {unknown[]} postArgs
+ */
+const callMeMaybe = (that, prop, postArgs) => {
+  const fn = that[prop];
+  if (!fn) {
+    return undefined;
+  }
+  assert.typeof(fn, 'function');
+  /**
+   * @param {unknown} arg value or reason
+   */
+  const wrapped = arg => {
+    // Don't return a value, to prevent E.when from subscribing to a resulting
+    // promise.
+    apply(fn, that, [arg, ...postArgs]);
+  };
+  return wrapped;
+};
+
+/**
+ * Shim the promise watcher behaviour when VatData.watchPromise is not available.
+ *
+ * @param {Promise<any>} p
+ * @param {PromiseWatcher} watcher
+ * @param {...unknown} watcherArgs
+ * @returns {void}
+ */
+export const watchPromise = (p, watcher, ...watcherArgs) => {
+  Promise.resolve(p) === p || Fail`watchPromise only watches promises`;
+  const onFulfilled = callMeMaybe(watcher, 'onFulfilled', watcherArgs);
+  const onRejected = callMeMaybe(watcher, 'onRejected', watcherArgs);
+  onFulfilled ||
+    onRejected ||
+    Fail`promise watcher must implement at least one handler method`;
+  void E.when(p, onFulfilled, onRejected);
+};
+harden(watchPromise);

package/test/exos.test.js

@@ -0,0 +1,9 @@
+import { test } from './prepare-test-env-ava.js';
+
+import { makeHeapZone } from '../heap.js';
+import { testFirstZoneIncarnation } from '../tools/testers.js';
+
+test('heapZone', t => {
+  const zone = makeHeapZone();
+  testFirstZoneIncarnation(t, zone);
+});

package/test/make-once.test.js

@@ -0,0 +1,8 @@
+import { test } from './prepare-test-env-ava.js';
+
+import { makeHeapZone } from '../heap.js';
+import { testMakeOnce } from '../tools/testers.js';
+
+test('heapZone', t => {
+  testMakeOnce(t, makeHeapZone());
+});

package/test/prepare-revocable.test.js

@@ -0,0 +1,121 @@
+// Modeled on test-heap-classes.js
+
+import { test } from './prepare-test-env-ava.js';
+
+// eslint-disable-next-line import/order
+import { M } from '@endo/patterns';
+import { makeHeapZone } from '../src/heap.js';
+import { prepareRevocableMakerKit } from '../src/prepare-revocable.js';
+
+const UpCounterI = M.interface('UpCounter', {
+  incr: M.call()
+    // TODO M.number() should not be needed to get a better error message
+    .optional(M.and(M.number(), M.gte(0)))
+    .returns(M.number()),
+});
+
+const DownCounterI = M.interface('DownCounter', {
+  decr: M.call()
+    // TODO M.number() should not be needed to get a better error message
+    .optional(M.and(M.number(), M.gte(0)))
+    .returns(M.number()),
+});
+
+test('test revoke defineVirtualExoClass', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingUpCounter = zone.exoClass(
+    'UpCounter',
+    UpCounterI,
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      incr(y = 1) {
+        const { state } = this;
+        state.x += y;
+        return state.x;
+      },
+    },
+  );
+
+  const { revoke, makeRevocable } = prepareRevocableMakerKit(
+    zone,
+    'UpCounter',
+    ['incr'],
+  );
+
+  const makeUpCounter = x => makeRevocable(makeUnderlyingUpCounter(x));
+
+  const upCounter = makeUpCounter(3);
+  t.is(upCounter.incr(5), 8);
+  t.is(revoke(upCounter), true);
+  t.throws(() => upCounter.incr(1), {
+    message: '"UpCounter_caretaker" revoked',
+  });
+});
+
+test('test revoke defineVirtualExoClassKit', t => {
+  const zone = makeHeapZone('rootZone');
+
+  const makeUnderlyingCounterKit = zone.exoClassKit(
+    'Counter',
+    { up: UpCounterI, down: DownCounterI },
+    /** @param {number} [x] */
+    (x = 0) => ({ x }),
+    {
+      up: {
+        incr(y = 1) {
+          const { state } = this;
+          state.x += y;
+          return state.x;
+        },
+      },
+      down: {
+        decr(y = 1) {
+          const { state } = this;
+          state.x -= y;
+          return state.x;
+        },
+      },
+    },
+  );
+
+  const { revoke, makeRevocable } = prepareRevocableMakerKit(
+    zone,
+    'UpCounter',
+    ['incr'],
+    {
+      extraMethodGuards: {
+        selfRevoke: M.call().returns(M.boolean()),
+      },
+      extraMethods: {
+        selfRevoke() {
+          // Could directly use the revoker facet instead, but this
+          // should now be considered more of an internal detail that
+          // we should deemphasize. This tests the code pattern we wish
+          // to encourage.
+          const { revocable } = this.facets;
+          return revoke(revocable);
+        },
+      },
+    },
+  );
+
+  const makeCounterKit = x => {
+    const { up: upCounter, down: downCounter } = makeUnderlyingCounterKit(x);
+    const revocableUpCounter = makeRevocable(upCounter);
+    return harden({
+      up: revocableUpCounter,
+      down: downCounter,
+    });
+  };
+
+  const { up: upCounter, down: downCounter } = makeCounterKit(3);
+  t.is(upCounter.incr(5), 8);
+  t.is(downCounter.decr(), 7);
+  t.is(upCounter.selfRevoke(), true);
+  t.throws(() => upCounter.incr(3), {
+    message: '"UpCounter_caretaker" revoked',
+  });
+  t.is(downCounter.decr(), 6);
+});

package/test/prepare-test-env-ava.js

@@ -0,0 +1,4 @@
+import { wrapTest } from '@endo/ses-ava';
+import rawTest from 'ava';
+
+export const test = wrapTest(rawTest);

package/tools/greeter.js

@@ -0,0 +1,74 @@
+import { M, getInterfaceGuardPayload } from '@endo/patterns';
+
+/**
+ * @template {{}} T
+ * @param {T} obj
+ * @param {unknown} that
+ * @returns {T}
+ */
+export const bindAllMethodsTo = (obj, that = obj) =>
+  /** @type {T} */
+  (
+    Object.fromEntries(
+      Object.entries(obj).map(([name, fn]) => [name, fn.bind(that)]),
+    )
+  );
+
+export const GreeterI = M.interface('Greeter', {
+  greet: M.call().optional(M.string()).returns(M.string()),
+});
+export const greetFacet = {
+  greet(greeting = 'Hello') {
+    return `${greeting}, ${this.state.nick}`;
+  },
+};
+
+export const GreeterAdminI = M.interface('GreeterAdmin', {
+  setNick: M.call(M.string()).returns(),
+});
+export const adminFacet = {
+  setNick(nick) {
+    this.state.nick = nick;
+  },
+};
+
+export const GreeterWithAdminI = M.interface('GreeterWithAdmin', {
+  ...getInterfaceGuardPayload(GreeterI).methodGuards,
+  ...getInterfaceGuardPayload(GreeterAdminI).methodGuards,
+});
+
+/**
+ * @param {import('../src/types.js').Zone} zone
+ * @param {string} label
+ * @param {string} nick
+ */
+export const prepareGreeterSingleton = (zone, label, nick) => {
+  const myThis = Object.freeze({ state: { nick } });
+  return zone.exo(label, GreeterWithAdminI, {
+    ...bindAllMethodsTo(greetFacet, myThis),
+    ...bindAllMethodsTo(adminFacet, myThis),
+  });
+};
+
+/**
+ * @param {import('../src/types.js').Zone} zone
+ */
+export const prepareGreeter = zone =>
+  zone.exoClass('Greeter', GreeterWithAdminI, nick => ({ nick }), {
+    ...greetFacet,
+    ...adminFacet,
+  });
+
+/**
+ * @param {import('../src/types.js').Zone} zone
+ */
+export const prepareGreeterKit = zone =>
+  zone.exoClassKit(
+    'GreeterKit',
+    { greeter: GreeterI, admin: GreeterAdminI },
+    nick => ({ nick }),
+    {
+      greeter: greetFacet,
+      admin: adminFacet,
+    },
+  );