@agoric/internal 0.2.2-dev-3fa74c5.0 → 0.2.2-dev-acc2db2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/internal",
-  "version": "0.2.2-dev-3fa74c5.0+3fa74c5",
+  "version": "0.2.2-dev-acc2db2.0+acc2db2",
   "description": "Externally unsupported utilities internal to agoric-sdk",
   "type": "module",
   "main": "src/index.js",
@@ -20,7 +20,7 @@
     "lint:types": "tsc -p jsconfig.json"
   },
   "dependencies": {
-    "@agoric/zone": "0.1.1-dev-3fa74c5.0+3fa74c5",
+    "@agoric/zone": "0.1.1-dev-acc2db2.0+acc2db2",
     "@endo/far": "^0.2.18",
     "@endo/marshal": "^0.8.5",
     "@endo/patterns": "^0.2.2",
@@ -42,5 +42,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3fa74c5bb9675c4ed967cd9c7961ab4692a49cf7"
+  "gitHead": "acc2db25a2c6e50b45848ba9a848c4a71145033e"
 }

package/src/callback.d.ts

@@ -4,7 +4,32 @@ export function makeSyncFunctionCallback<I extends (...args: unknown[]) => any,
 export function makeFunctionCallback<I extends (...args: unknown[]) => any, T extends import("@endo/far").ERef<(...args: [...B, ...Parameters<I>]) => ReturnType<I>> = import("@endo/far").ERef<I>, B extends unknown[] = []>(target: T, ...bound: B): import("./types").Callback<I>;
 export function makeSyncMethodCallback<I extends (...args: unknown[]) => any, P extends PropertyKey, T extends { [x in P]: (...args: [...B, ...Parameters<I>]) => ReturnType<I>; } = { [x_1 in P]: I; }, B extends unknown[] = []>(target: T, methodName: P, ...bound: B): import("./types").SyncCallback<I>;
 export function makeMethodCallback<I extends (...args: unknown[]) => any, P extends PropertyKey, T extends import("@endo/far").ERef<{ [x in P]: (...args: [...B, ...Parameters<I>]) => ReturnType<I>; }> = import("@endo/far").ERef<{ [x_1 in P]: I; }>, B extends unknown[] = []>(target: T, methodName: P, ...bound: B): import("./types").Callback<I>;
-export function isCallback(callback: any): callback is any;
+export function isCallback(callback: any): callback is import("./types").Callback<any>;
+export function prepareAttenuator<M extends PropertyKey>(zone: import('@agoric/zone').Zone, methodNames: M[], { interfaceGuard, tag }?: {
+    interfaceGuard?: InterfaceGuard | undefined;
+    tag?: string | undefined;
+}): (args_0: {
+    target?: any;
+    isSync?: boolean | undefined;
+    overrides?: { [K in M]?: import("./types").Callback<any> | null | undefined; } | undefined;
+}) => { [K_1 in M]: (this: any, ...args: unknown[]) => any; } & import("@endo/eventual-send").RemotableBrand<{}, { [K_1 in M]: (this: any, ...args: unknown[]) => any; }>;
+export function prepareGuardedAttenuator(zone: import('@agoric/zone').Zone, interfaceGuard: InterfaceGuard, opts?: {
+    tag?: string | undefined;
+} | undefined): (args_0: {
+    target?: any;
+    isSync?: boolean | undefined;
+    overrides?: {
+        [x: string]: import("./types").Callback<any> | null | undefined;
+        [x: symbol]: import("./types").Callback<any> | null | undefined;
+    } | undefined;
+}) => {
+    [x: string]: (this: any, ...args: unknown[]) => any;
+    [x: symbol]: (this: any, ...args: unknown[]) => any;
+} & import("@endo/eventual-send").RemotableBrand<{}, {
+    [x: string]: (this: any, ...args: unknown[]) => any;
+    [x: symbol]: (this: any, ...args: unknown[]) => any;
+}>;
 export type Callback<I extends (...args: unknown[]) => any> = import('./types').Callback<I>;
 export type SyncCallback<I extends (...args: unknown[]) => any> = import('./types').SyncCallback<I>;
+export type Farable<T> = import('@endo/eventual-send').RemotableBrand<{}, T> & T;
 //# sourceMappingURL=callback.d.ts.map

package/src/callback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callback.d.ts","sourceRoot":"","sources":["callback.js"],"names":[],"mappings":"AAwBO,6CALiB,OAAO,EAAE,KAAK,GAAG,sFAWxC;AAUM,0CALiB,OAAO,EAAE,KAAK,GAAG,oGAWxC;AAYM,6DAPiB,OAAO,EAAE,KAAK,GAAG,2JAaxC;AAeM,yDATiB,OAAO,EAAE,KAAK,GAAG,2MAexC;AAiBM,2DAXiB,OAAO,EAAE,KAAK,GAAG,iOAoBxC;AAiBM,uDAXiB,OAAO,EAAE,KAAK,GAAG,iRAmBxC;AAOM,qCAHI,GAAG,mBAeb;yCApJuB,OAAO,EAAE,KAAK,GAAG,IAC5B,OAAO,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;6CAIlB,OAAO,EAAE,KAAK,GAAG,IAC5B,OAAO,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC"}
+{"version":3,"file":"callback.d.ts","sourceRoot":"","sources":["callback.js"],"names":[],"mappings":"AAkDO,6CALiB,OAAO,EAAE,KAAK,GAAG,sFAWxC;AAWM,0CALiB,OAAO,EAAE,KAAK,GAAG,oGAWxC;AAaM,6DAPiB,OAAO,EAAE,KAAK,GAAG,2JAaxC;AAeM,yDATiB,OAAO,EAAE,KAAK,GAAG,2MAexC;AAiBM,2DAXiB,OAAO,EAAE,KAAK,GAAG,iOAoBxC;AAiBM,uDAXiB,OAAO,EAAE,KAAK,GAAG,iRAmBxC;AAOM,qCAHI,GAAG,+CAeb;AAcM,+DAPI,OAAO,cAAc,EAAE,IAAI;IAGL,cAAc;IAEtB,GAAG;;aAkEb,GAAG;;;2BA1DI,GAAG,WAAW,OAAO,EAAE,KAAK,GAAG,4EAA/B,GAAG,WAAW,OAAO,EAAE,KAAK,GAAG,KA8FpD;AAWM,+CALI,OAAO,cAAc,EAAE,IAAI,kBAC3B,cAAc;;;aA3CV,GAAG;;;;;;;wBA1DI,GAAG,WAAW,OAAO,EAAE,KAAK,GAAG;wBAA/B,GAAG,WAAW,OAAO,EAAE,KAAK,GAAG;;wBAA/B,GAAG,WAAW,OAAO,EAAE,KAAK,GAAG;wBAA/B,GAAG,WAAW,OAAO,EAAE,KAAK,GAAG;GA6GpD;yCAzSuB,OAAO,EAAE,KAAK,GAAG,IAC5B,OAAO,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;6CAIlB,OAAO,EAAE,KAAK,GAAG,IAC5B,OAAO,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;yBAGpB,OAAO,qBAAqB,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC"}

package/src/callback.js

@@ -2,7 +2,15 @@
 import { E } from '@endo/far';
 import { isObject, isPassableSymbol } from '@endo/marshal';
 
-const { Fail } = assert;
+const { Fail, quote: q } = assert;
+
+const { fromEntries } = Object;
+
+const { ownKeys: rawOwnKeys } = Reflect;
+const ownKeys =
+  /** @type {<T extends PropertyKey>(obj: {[K in T]?: unknown}) => T[]} */ (
+    rawOwnKeys
+  );
 
 /**
  * @template {(...args: unknown[]) => any} I
@@ -14,6 +22,24 @@ const { Fail } = assert;
  * @typedef {import('./types').SyncCallback<I>} SyncCallback
  */
 
+/** @template T @typedef {import('@endo/eventual-send').RemotableBrand<{}, T> & T} Farable */
+
+/**
+ * @param {unknown} key
+ * @returns {key is PropertyKey} FIXME: should be just `PropertyKey` but TS
+ * complains it can't be used as an index type.
+ */
+const isPropertyKey = key => {
+  switch (typeof key) {
+    case 'string':
+    case 'number':
+    case 'symbol':
+      return true;
+    default:
+      return false;
+  }
+};
+
 /**
  * Synchronously call a callback.
  *
@@ -29,6 +55,7 @@ export const callSync = (callback, ...args) => {
   }
   return target[methodName](...bound, ...args);
 };
+harden(callSync);
 
 /**
  * Eventual send to a callback.
@@ -45,6 +72,7 @@ export const callE = (callback, ...args) => {
   }
   return E(target)[methodName](...bound, ...args);
 };
+harden(callE);
 
 /**
  * Create a callback from a near function.
@@ -60,7 +88,7 @@ export const makeSyncFunctionCallback = (target, ...bound) => {
   typeof target === 'function' ||
     Fail`sync function callback target must be a function: ${target}`;
   /** @type {unknown} */
-  const cb = harden({ target, bound });
+  const cb = harden({ target, bound, isSync: true });
   return /** @type {SyncCallback<I>} */ (cb);
 };
 harden(makeSyncFunctionCallback);
@@ -107,7 +135,7 @@ export const makeSyncMethodCallback = (target, methodName, ...bound) => {
     isPassableSymbol(methodName) ||
     Fail`method name must be a string or passable symbol: ${methodName}`;
   /** @type {unknown} */
-  const cb = harden({ target, methodName, bound });
+  const cb = harden({ target, methodName, bound, isSync: true });
   return /** @type {SyncCallback<I>} */ (cb);
 };
 harden(makeSyncMethodCallback);
@@ -139,7 +167,7 @@ harden(makeMethodCallback);
 
 /**
  * @param {any} callback
- * @returns {callback is Callback}
+ * @returns {callback is Callback<any>}
  */
 export const isCallback = callback => {
   if (!isObject(callback)) {
@@ -155,3 +183,132 @@ export const isCallback = callback => {
   );
 };
 harden(isCallback);
+
+/**
+ * Prepare an attenuator class whose methods can be redirected via callbacks.
+ *
+ * @template {PropertyKey} M
+ * @param {import('@agoric/zone').Zone} zone The zone in which to allocate attenuators.
+ * @param {M[]} methodNames Methods to forward.
+ * @param {object} opts
+ * @param {InterfaceGuard} [opts.interfaceGuard] An interface guard for the
+ * new attenuator.
+ * @param {string} [opts.tag] A tag for the new attenuator exoClass.
+ */
+export const prepareAttenuator = (
+  zone,
+  methodNames,
+  { interfaceGuard, tag = 'Attenuator' } = {},
+) => {
+  /**
+   * @typedef {(this: any, ...args: unknown[]) => any} Method
+   * @typedef {{ [K in M]: Method }} Methods
+   * @typedef {{ [K in M]?: Callback<any> | null}} Overrides
+   */
+  const methods = fromEntries(
+    methodNames.map(key => {
+      // Only allow the `PropertyKey` type for the target method key.
+      if (!isPropertyKey(key)) {
+        throw Fail`key ${q(key)} is not a PropertyKey`;
+      }
+
+      const m = /** @type {Methods} */ ({
+        // Explicitly use concise method syntax to preserve `this` but prevent
+        // constructor behavior.
+        /** @type {Method} */
+        [key](...args) {
+          // Support both synchronous and async callbacks.
+          const cb = this.state.cbs[key];
+          if (!cb) {
+            const err = assert.error(
+              `unimplemented ${q(tag)} method ${q(key)}`,
+            );
+            if (this.state.isSync) {
+              throw err;
+            }
+            return Promise.reject(err);
+          }
+          if (cb.isSync) {
+            return callSync(cb, ...args);
+          }
+          return callE(cb, ...args);
+        },
+      })[key];
+      return /** @type {const} */ ([key, m]);
+    }),
+  );
+
+  const methodKeys = /** @type {M[]} */ (ownKeys(methods));
+
+  /**
+   * Create an exo object whose behavior is composed from a default target
+   * and/or individual method override callbacks.
+   *
+   * @param {object} opts
+   * @param {unknown} [opts.target] The target for any methods that
+   * weren't specified in `opts.overrides`.
+   * @param {boolean} [opts.isSync=false] Whether the target should be treated
+   * as synchronously available.
+   * @param {Overrides} [opts.overrides] Set individual
+   * callbacks for methods (whose names must be defined in the
+   * `prepareAttenuator` or `prepareGuardedAttenuator` call).  Nullish overrides
+   * mean to throw.
+   */
+  const makeAttenuator = zone.exoClass(
+    tag,
+    interfaceGuard,
+    /**
+     * @param {object} opts
+     * @param {any} [opts.target]
+     * @param {boolean} [opts.isSync=false]
+     * @param {Overrides} [opts.overrides]
+     */
+    ({
+      target = null,
+      isSync = false,
+      overrides = /** @type {Overrides} */ ({}),
+    }) => {
+      const cbs = /** @type {Overrides} */ ({});
+
+      const remaining = new Set(methodKeys);
+      for (const key of ownKeys(overrides)) {
+        remaining.has(key) ||
+          Fail`${q(tag)} overrides[${q(key)}] not allowed by methodNames`;
+
+        remaining.delete(key);
+        const cb = overrides[key];
+        if (cb != null) {
+          isCallback(cb) ||
+            Fail`${q(tag)} overrides[${q(key)}] is not a callback; got ${cb}`;
+        }
+        cbs[key] = cb;
+      }
+      for (const key of remaining) {
+        if (isSync) {
+          cbs[key] = makeSyncMethodCallback(target, key);
+        } else {
+          cbs[key] = makeMethodCallback(target, key);
+        }
+      }
+      return harden({ cbs, isSync });
+    },
+    /** @type {Methods} */ (methods),
+  );
+  return makeAttenuator;
+};
+harden(prepareAttenuator);
+
+/**
+ * Prepare an attenuator whose methodNames are derived from the interfaceGuard.
+ *
+ * @param {import('@agoric/zone').Zone} zone
+ * @param {InterfaceGuard} interfaceGuard
+ * @param {object} [opts]
+ * @param {string} [opts.tag]
+ */
+export const prepareGuardedAttenuator = (zone, interfaceGuard, opts = {}) => {
+  const { methodGuards } = interfaceGuard;
+  const methodNames = ownKeys(methodGuards);
+  return prepareAttenuator(zone, methodNames, { ...opts, interfaceGuard });
+};
+harden(prepareGuardedAttenuator);

package/src/storage-test-utils.d.ts

@@ -37,7 +37,10 @@ export function makeFakeStorageKit(rootPath: string, rootOptions?: [handleStorag
 };
 export function makeMockChainStorageRoot(): {
     /**
-     * Defaults to deserializing pass-by-presence objects into Remotable objects.
+     * Defaults to deserializing slot references into plain Remotable
+     * objects, but if supplied with a different marshaller, it could
+     * produce Remotables with e.g. the slog string embedded in the
+     * iface.
      *
      * @param {string} path
      * @param {import('./lib-chainStorage.js').Marshaller} marshaller
@@ -53,7 +56,10 @@ export function makeMockChainStorageRoot(): {
     setValue(value: string): Promise<void>;
 } & import("@endo/eventual-send").RemotableBrand<{}, {
     /**
-     * Defaults to deserializing pass-by-presence objects into Remotable objects.
+     * Defaults to deserializing slot references into plain Remotable
+     * objects, but if supplied with a different marshaller, it could
+     * produce Remotables with e.g. the slog string embedded in the
+     * iface.
      *
      * @param {string} path
      * @param {import('./lib-chainStorage.js').Marshaller} marshaller

package/src/storage-test-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AAcO,yCAHI,MAAM,UACN,MAAM,wDAGC;AAElB;;;GAGG;AACH;;;;;EAEG;AAiBW,+CAAU,GAAG,GAAK,GAAG,CAAA;AA+B5B,6CAHI,MAAM,gBACN;;eAAwC,CAAC,CAAC;;;;;;;;;;;;;;;;;;yBAOvC,OAAO,4BAA4B,EAAE,cAAc;;;;EAkDhE;AAIM;IAIH;;;;;;OAMG;oBAHQ,MAAM,eACN,OAAO,uBAAuB,EAAE,UAAU,KACxC,OAAO;;;;;;;;;IALpB;;;;;;OAMG;oBAHQ,MAAM,eACN,OAAO,uBAAuB,EAAE,UAAU,KACxC,OAAO;;;;;;;;GAevB;6BA1Ba,WAAY,yBAAyB,CAAC;mCA2BtC,WAAW,+BAA+B,CAAC"}
+{"version":3,"file":"storage-test-utils.d.ts","sourceRoot":"","sources":["storage-test-utils.js"],"names":[],"mappings":"AAeO,yCAHI,MAAM,UACN,MAAM,wDAGC;AAElB;;;GAGG;AACH;;;;;EAEG;AAsBW,+CAAU,GAAG,GAAK,GAAG,CAAA;AA+B5B,6CAHI,MAAM,gBACN;;eAAwC,CAAC,CAAC;;;;;;;;;;;;;;;;;;yBAOvC,OAAO,4BAA4B,EAAE,cAAc;;;;EAkDhE;AAIM;IAIH;;;;;;;;;OASG;oBAHQ,MAAM,eACN,OAAO,uBAAuB,EAAE,UAAU,KACxC,OAAO;;;;;;;;;IARpB;;;;;;;;;OASG;oBAHQ,MAAM,eACN,OAAO,uBAAuB,EAAE,UAAU,KACxC,OAAO;;;;;;;;GAevB;6BA7Ba,WAAY,yBAAyB,CAAC;mCA8BtC,WAAW,+BAA+B,CAAC"}

package/src/storage-test-utils.js

@@ -7,12 +7,13 @@ import { bindAllMethods } from './method-tools.js';
 const { Fail, quote: q } = assert;
 
 /**
- * A convertSlotToVal function that produces basic Remotables
+ * A convertSlotToVal function that produces basic Remotables. Assumes
+ * that all slots are Remotables (i.e. none are Promises).
  *
  * @param {string} _slotId
  * @param {string} iface
  */
-export const slotToRemotable = (_slotId, iface = 'Alleged: Remotable') =>
+export const slotToRemotable = (_slotId, iface = 'Remotable') =>
   Remotable(iface);
 
 /**
@@ -31,8 +32,13 @@ export const defaultMarshaller = makeMarshal(undefined, slotToRemotable, {
  *
  * This may be useful for display purposes.
  *
- * One limitation: serialized data that contains a particular unusual
- * string will be unserialized into a BigInt.
+ * Limitations:
+ *  * it cannot handle Symbols (registered or well-known)
+ *  * it can handle BigInts, but serialized data that contains a
+ *     particular unusual string will be unserialized into a BigInt by
+ *     mistake
+ *  * it cannot handle Promises, NaN, +/- Infinity, undefined, or
+ *    other non-JSONable JavaScript values
  */
 const makeSlotStringUnserialize = () => {
   /** @type { (slot: string, iface: string) => any } */
@@ -133,7 +139,10 @@ export const makeMockChainStorageRoot = () => {
   return Far('mockChainStorage', {
     ...bindAllMethods(rootNode),
     /**
-     * Defaults to deserializing pass-by-presence objects into Remotable objects.
+     * Defaults to deserializing slot references into plain Remotable
+     * objects, but if supplied with a different marshaller, it could
+     * produce Remotables with e.g. the slog string embedded in the
+     * iface.
      *
      * @param {string} path
      * @param {import('./lib-chainStorage.js').Marshaller} marshaller
@@ -148,7 +157,7 @@ export const makeMockChainStorageRoot = () => {
       }
       assert.typeof(dataStr, 'string');
       const datum = JSON.parse(dataStr);
-      return marshaller.unserialize(datum);
+      return marshaller.fromCapData(datum);
     },
     keys: () => [...data.keys()],
   });

package/src/types.d.ts

@@ -7,10 +7,14 @@ export declare class Callback<I extends (...args: unknown[]) => any> {
   public methodName?: PropertyKey;
 
   public bound: unknown[];
+
+  public isSync: boolean;
 }
 
 export declare class SyncCallback<
   I extends (...args: unknown[]) => any,
 > extends Callback<I> {
   private syncIface: I;
+
+  public isSync: true;
 }