@agoric/vow 0.1.1-calypso-dev-84eb287.0

package/src/watch-utils.js

@@ -0,0 +1,220 @@
+// @ts-check
+
+import { M } from '@endo/patterns';
+import { PromiseWatcherI } from '@agoric/base-zone';
+
+const { Fail, bare, details: X } = assert;
+
+/**
+ * @import {MapStore} from '@agoric/store/src/types.js';
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {Watch} from './watch.js';
+ * @import {When} from './when.js';
+ * @import {VowKit, AsPromiseFunction, IsRetryableReason, EVow} from './types.js';
+ */
+
+const VowShape = M.tagged(
+  'Vow',
+  harden({
+    vowV0: M.remotable('VowV0'),
+  }),
+);
+
+/**
+ * Like `provideLazy`, but accepts non-Passable values.
+ *
+ * @param {WeakMap} map
+ * @param {any} key
+ * @param {(key: any) => any} makeValue
+ */
+const provideLazyMap = (map, key, makeValue) => {
+  if (!map.has(key)) {
+    map.set(key, makeValue(key));
+  }
+  return map.get(key);
+};
+
+/**
+ * @param {Zone} zone
+ * @param {object} powers
+ * @param {Watch} powers.watch
+ * @param {When} powers.when
+ * @param {() => VowKit<any>} powers.makeVowKit
+ * @param {IsRetryableReason} powers.isRetryableReason
+ */
+export const prepareWatchUtils = (
+  zone,
+  { watch, when, makeVowKit, isRetryableReason },
+) => {
+  const detached = zone.detached();
+  const utilsToNonStorableResults = new WeakMap();
+
+  const makeWatchUtilsKit = zone.exoClassKit(
+    'WatchUtils',
+    {
+      utils: M.interface('Utils', {
+        all: M.call(M.arrayOf(M.any())).returns(VowShape),
+        asPromise: M.call(M.raw()).rest(M.raw()).returns(M.promise()),
+      }),
+      watcher: M.interface('Watcher', {
+        onFulfilled: M.call(M.any()).rest(M.any()).returns(M.any()),
+        onRejected: M.call(M.any()).rest(M.any()).returns(M.any()),
+      }),
+      retryRejectionPromiseWatcher: PromiseWatcherI,
+    },
+    () => {
+      /**
+       * @typedef {object} VowState
+       * @property {number} remaining
+       * @property {MapStore<number, any>} resultsMap
+       * @property {VowKit['resolver']} resolver
+       */
+      /** @type {MapStore<bigint, VowState>} */
+      const idToVowState = detached.mapStore('idToVowState');
+
+      return {
+        nextId: 0n,
+        idToVowState,
+      };
+    },
+    {
+      utils: {
+        /**
+         * @param {EVow<unknown>[]} vows
+         */
+        all(vows) {
+          const { nextId: id, idToVowState } = this.state;
+          /** @type {VowKit<any[]>} */
+          const kit = makeVowKit();
+
+          // Preserve the order of the vow results.
+          for (let index = 0; index < vows.length; index += 1) {
+            watch(vows[index], this.facets.watcher, {
+              id,
+              index,
+              numResults: vows.length,
+            });
+          }
+
+          if (vows.length > 0) {
+            // Save the state until rejection or all fulfilled.
+            this.state.nextId += 1n;
+            idToVowState.init(
+              id,
+              harden({
+                resolver: kit.resolver,
+                remaining: vows.length,
+                resultsMap: detached.mapStore('resultsMap'),
+              }),
+            );
+            const idToNonStorableResults = provideLazyMap(
+              utilsToNonStorableResults,
+              this.facets.utils,
+              () => new Map(),
+            );
+            idToNonStorableResults.set(id, new Map());
+          } else {
+            // Base case: nothing to wait for.
+            kit.resolver.resolve(harden([]));
+          }
+          return kit.vow;
+        },
+        /** @type {AsPromiseFunction} */
+        asPromise(specimenP, ...watcherArgs) {
+          // Watch the specimen in case it is an ephemeral promise.
+          const vow = watch(specimenP, ...watcherArgs);
+          const promise = when(vow);
+          // Watch the ephemeral result promise to ensure that if its settlement is
+          // lost due to upgrade of this incarnation, we will at least cause an
+          // unhandled rejection in the new incarnation.
+          zone.watchPromise(promise, this.facets.retryRejectionPromiseWatcher);
+
+          return promise;
+        },
+      },
+      watcher: {
+        onFulfilled(value, { id, index, numResults }) {
+          const { idToVowState } = this.state;
+          if (!idToVowState.has(id)) {
+            // Resolution of the returned vow happened already.
+            return;
+          }
+          const { remaining, resultsMap, resolver } = idToVowState.get(id);
+          const idToNonStorableResults = provideLazyMap(
+            utilsToNonStorableResults,
+            this.facets.utils,
+            () => new Map(),
+          );
+          const nonStorableResults = provideLazyMap(
+            idToNonStorableResults,
+            id,
+            () => new Map(),
+          );
+
+          // Capture the fulfilled value.
+          if (zone.isStorable(value)) {
+            resultsMap.init(index, value);
+          } else {
+            nonStorableResults.set(index, value);
+          }
+          const vowState = harden({
+            remaining: remaining - 1,
+            resultsMap,
+            resolver,
+          });
+          if (vowState.remaining > 0) {
+            idToVowState.set(id, vowState);
+            return;
+          }
+          // We're done!  Extract the array.
+          idToVowState.delete(id);
+          const results = new Array(numResults);
+          let numLost = 0;
+          for (let i = 0; i < numResults; i += 1) {
+            if (nonStorableResults.has(i)) {
+              results[i] = nonStorableResults.get(i);
+            } else if (resultsMap.has(i)) {
+              results[i] = resultsMap.get(i);
+            } else {
+              numLost += 1;
+            }
+          }
+          if (numLost > 0) {
+            resolver.reject(
+              assert.error(X`${numLost} unstorable results were lost`),
+            );
+          } else {
+            resolver.resolve(harden(results));
+          }
+        },
+        onRejected(value, { id, index: _index, numResults: _numResults }) {
+          const { idToVowState } = this.state;
+          if (!idToVowState.has(id)) {
+            // First rejection wins.
+            return;
+          }
+          const { resolver } = idToVowState.get(id);
+          idToVowState.delete(id);
+          resolver.reject(value);
+        },
+      },
+      retryRejectionPromiseWatcher: {
+        onFulfilled(_result) {},
+        onRejected(reason, failedOp) {
+          if (isRetryableReason(reason, undefined)) {
+            Fail`Pending ${bare(failedOp)} could not retry; ${reason}`;
+          }
+        },
+      },
+    },
+  );
+
+  const makeWatchUtil = () => {
+    const { utils } = makeWatchUtilsKit();
+    return harden(utils);
+  };
+
+  return makeWatchUtil;
+};
+
+harden(prepareWatchUtils);

package/src/watch.d.ts

@@ -0,0 +1,8 @@
+export function prepareWatch(zone: Zone, makeVowKit: () => VowKit<any>, isRetryableReason?: ((reason: any, lastValue: any) => any) | undefined): <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
+export type Watch = ReturnType<typeof prepareWatch>;
+import type { Zone } from '@agoric/base-zone';
+import type { VowKit } from './types.js';
+import type { EVow } from './types.js';
+import type { Watcher } from './types.js';
+import type { Vow } from './types.js';
+//# sourceMappingURL=watch.d.ts.map

package/src/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["watch.js"],"names":[],"mappings":"AA2JO,mCAJI,IAAI,cACJ,MAAM,OAAO,GAAG,CAAC,gCACR,GAAG,aAAa,GAAG,KAAK,GAAG,iBAe/B,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG,qBACT,KAAK,CAAC,CAAC,2EAEP,CAAC,yIAoBb;oBAIa,UAAU,CAAC,OAAO,YAAY,CAAC;0BA/LJ,mBAAmB;4BACyB,YAAY;0BAAZ,YAAY;6BAAZ,YAAY;yBAAZ,YAAY"}

package/src/watch.js

@@ -0,0 +1,199 @@
+// @ts-check
+import { PromiseWatcherI } from '@agoric/base-zone';
+import { getVowPayload, basicE } from './vow-utils.js';
+
+const { apply } = Reflect;
+
+/**
+ * @import { PromiseWatcher, Zone } from '@agoric/base-zone';
+ * @import { ERef, EVow, IsRetryableReason, Vow, VowKit, VowResolver, Watcher } from './types.js';
+ */
+
+/**
+ * @param {Zone} zone
+ */
+const makeWatchNextStep =
+  zone =>
+  /**
+   * If the specimen is a vow, obtain a fresh shortened promise from it,
+   * otherwise coerce the non-vow specimen to a promise.  Then, associate a
+   * (usually durable) watcher object with the promise.
+   *
+   * @param {any} specimen
+   * @param {PromiseWatcher} promiseWatcher
+   */
+  (specimen, promiseWatcher) => {
+    let promise;
+    const payload = getVowPayload(specimen);
+    if (payload) {
+      promise = basicE(payload.vowV0).shorten();
+    } else {
+      promise = basicE.resolve(specimen);
+    }
+    zone.watchPromise(promise, promiseWatcher);
+  };
+
+/**
+ * @param {VowResolver | undefined} resolver
+ * @param {Watcher<unknown, unknown, unknown> | undefined} watcher
+ * @param {keyof Required<Watcher>} wcb
+ * @param {unknown} value
+ * @param {unknown[]} [watcherArgs]
+ */
+const settle = (resolver, watcher, wcb, value, watcherArgs = []) => {
+  try {
+    let chainedValue = value;
+    const w = watcher && watcher[wcb];
+    if (w) {
+      chainedValue = apply(w, watcher, [value, ...watcherArgs]);
+    } else if (wcb === 'onRejected') {
+      throw value;
+    }
+    resolver && resolver.resolve(chainedValue);
+  } catch (e) {
+    if (resolver) {
+      resolver.reject(e);
+    } else {
+      // for host's unhandled rejection handler to catch
+      throw e;
+    }
+  }
+};
+
+/**
+ * @param {Zone} zone
+ * @param {IsRetryableReason} isRetryableReason
+ * @param {ReturnType<typeof makeWatchNextStep>} watchNextStep
+ */
+const preparePromiseWatcher = (zone, isRetryableReason, watchNextStep) => {
+  // We use an ephemeral WeakSet for the previously seen vows in a watch operation
+  // While watch is durable, it suffices to detect the cycle in a single incarnation
+  /** @type {WeakMap<PromiseWatcher, WeakSet<any>>} */
+  const watcherSeenPayloads = new WeakMap();
+
+  /** @param {PromiseWatcher} watcher */
+  const getSeenPayloads = watcher => {
+    let seenPayloads = watcherSeenPayloads.get(watcher);
+    if (!seenPayloads) {
+      seenPayloads = new WeakSet();
+      watcherSeenPayloads.set(watcher, seenPayloads);
+    }
+    return seenPayloads;
+  };
+
+  return zone.exoClass(
+    'PromiseWatcher',
+    PromiseWatcherI,
+    /**
+     * @template [T=any]
+     * @template [TResult1=T]
+     * @template [TResult2=never]
+     * @param {VowResolver<TResult1 | TResult2>} resolver
+     * @param {Watcher<T, TResult1, TResult2>} [watcher]
+     * @param {unknown[]} [watcherArgs]
+     */
+    (resolver, watcher, watcherArgs) => {
+      const state = {
+        vow: /** @type {unknown} */ (undefined),
+        priorRetryValue: /** @type {any} */ (undefined),
+        resolver,
+        watcher,
+        watcherArgs: harden(watcherArgs),
+      };
+      return /** @type {Partial<typeof state>} */ (state);
+    },
+    {
+      /** @type {Required<PromiseWatcher>['onFulfilled']} */
+      onFulfilled(value) {
+        const { watcher, watcherArgs, resolver } = this.state;
+        const payload = getVowPayload(value);
+        if (payload) {
+          const seenPayloads = getSeenPayloads(this.self);
+          // TODO: rely on endowed helper to get storable cap from payload
+          if (seenPayloads.has(payload.vowV0)) {
+            return this.self.onRejected(Error('Vow resolution cycle detected'));
+          }
+          seenPayloads.add(payload.vowV0);
+          // We've been shortened, so reflect our state accordingly, and go again.
+          this.state.vow = value;
+          watchNextStep(value, this.self);
+          return;
+        }
+        watcherSeenPayloads.delete(this.self);
+        this.state.priorRetryValue = undefined;
+        this.state.watcher = undefined;
+        this.state.resolver = undefined;
+        settle(resolver, watcher, 'onFulfilled', value, watcherArgs);
+      },
+      /** @type {Required<PromiseWatcher>['onRejected']} */
+      onRejected(reason) {
+        const { vow, watcher, watcherArgs, resolver, priorRetryValue } =
+          this.state;
+        if (vow) {
+          const retryValue = isRetryableReason(reason, priorRetryValue);
+          if (retryValue) {
+            // Retry the same specimen.
+            this.state.priorRetryValue = retryValue;
+            watchNextStep(vow, this.self);
+            return;
+          }
+        }
+        watcherSeenPayloads.delete(this.self);
+        this.state.priorRetryValue = undefined;
+        this.state.resolver = undefined;
+        this.state.watcher = undefined;
+        settle(resolver, watcher, 'onRejected', reason, watcherArgs);
+      },
+    },
+  );
+};
+
+/**
+ * @param {Zone} zone
+ * @param {() => VowKit<any>} makeVowKit
+ * @param {(reason: any, lastValue: any) => any} [isRetryableReason]
+ */
+export const prepareWatch = (
+  zone,
+  makeVowKit,
+  isRetryableReason = (_reason, _lastValue) => undefined,
+) => {
+  const watchNextStep = makeWatchNextStep(zone);
+  const makePromiseWatcher = preparePromiseWatcher(
+    zone,
+    isRetryableReason,
+    watchNextStep,
+  );
+
+  /**
+   * @template [T=any]
+   * @template [TResult1=T]
+   * @template [TResult2=never]
+   * @template {any[]} [C=any[]] watcher args
+   * @param {EVow<T>} specimenP
+   * @param {Watcher<T, TResult1, TResult2, C>} [watcher]
+   * @param {C} watcherArgs
+   */
+  const watch = (specimenP, watcher, ...watcherArgs) => {
+    /** @typedef {Exclude<TResult1, void> | Exclude<TResult2, void>} Voidless */
+    /** @typedef {Voidless extends never ? TResult1 : Voidless} Narrowest */
+    /** @type {VowKit<Narrowest>} */
+    const { resolver, vow } = makeVowKit();
+
+    // Create a promise watcher to track vows, retrying upon rejection as
+    // controlled by `isRetryableReason`.
+    const promiseWatcher = makePromiseWatcher(resolver, watcher, watcherArgs);
+
+    // Coerce the specimen to a promise, and start the watcher cycle.
+    zone.watchPromise(basicE.resolve(specimenP), promiseWatcher);
+
+    return vow;
+  };
+  harden(watch);
+
+  return watch;
+};
+
+harden(prepareWatch);
+
+/** @typedef {ReturnType<typeof prepareWatch>} Watch */

package/src/when.d.ts

@@ -0,0 +1,5 @@
+export function makeWhen(isRetryableReason?: IsRetryableReason | undefined): <T, TResult1 = EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
+export type When = ReturnType<typeof makeWhen>;
+import type { IsRetryableReason } from './types.js';
+import type { EUnwrap } from './types.js';
+//# sourceMappingURL=when.d.ts.map

package/src/when.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["when.js"],"names":[],"mappings":"AAQO,8EAMQ,CAAC,EACA,QAAQ,eACR,QAAQ,qBACX,CAAC,yBACO,QAAQ,CAAC,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,sCAC9C,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,kBAC/C,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAmD1C;mBAIa,UAAU,CAAC,OAAO,QAAQ,CAAC;uCAxEO,YAAY;6BAAZ,YAAY"}

package/src/when.js

@@ -0,0 +1,76 @@
+// @ts-check
+import { getVowPayload, basicE } from './vow-utils.js';
+
+/** @import { IsRetryableReason, EUnwrap } from './types.js' */
+
+/**
+ * @param {IsRetryableReason} [isRetryableReason]
+ */
+export const makeWhen = (
+  isRetryableReason = /** @type {IsRetryableReason} */ (() => false),
+) => {
+  /**
+   * Shorten `specimenP` until we achieve a final result.
+   *
+   * @template T
+   * @template [TResult1=EUnwrap<T>]
+   * @template [TResult2=never]
+   * @param {T} specimenP value to unwrap
+   * @param {(value: EUnwrap<T>) => TResult1 | PromiseLike<TResult1>} [onFulfilled]
+   * @param {(reason: any) => TResult2 | PromiseLike<TResult2>} [onRejected]
+   * @returns {Promise<TResult1 | TResult2>}
+   */
+  const when = async (specimenP, onFulfilled, onRejected) => {
+    // Ensure we don't run until a subsequent turn.
+    await null;
+
+    // Ensure we have a presence that won't be disconnected later.
+    let result = await specimenP;
+    let payload = getVowPayload(result);
+    let priorRetryValue;
+    const seenPayloads = new WeakSet();
+    while (payload) {
+      // TODO: rely on endowed helpers for getting storable cap and performing
+      // shorten "next step"
+      const { vowV0 } = payload;
+      if (seenPayloads.has(vowV0)) {
+        throw Error('Vow resolution cycle detected');
+      }
+      result = await basicE(vowV0)
+        .shorten()
+        .then(
+          res => {
+            seenPayloads.add(vowV0);
+            priorRetryValue = undefined;
+            return res;
+          },
+          e => {
+            const nextValue = isRetryableReason(e, priorRetryValue);
+            if (nextValue) {
+              // Shorten the same specimen to try again.
+              priorRetryValue = nextValue;
+              return result;
+            }
+            throw e;
+          },
+        );
+      // Advance to the next vow.
+      payload = getVowPayload(result);
+    }
+
+    const unwrapped = /** @type {EUnwrap<T>} */ (result);
+
+    // We've extracted the final result.
+    if (onFulfilled == null && onRejected == null) {
+      return /** @type {TResult1} */ (unwrapped);
+    }
+    return basicE.resolve(unwrapped).then(onFulfilled, onRejected);
+  };
+  harden(when);
+
+  return when;
+};
+
+harden(makeWhen);
+
+/** @typedef {ReturnType<typeof makeWhen>} When */

package/vat.js

@@ -0,0 +1,43 @@
+/**
+ * @file specialization of the `@agoric/vow` package for the vat disconnection rejections produced by
+ * the SwingSet kernel.
+ */
+
+// @ts-check
+import { isUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
+import { makeHeapZone } from '@agoric/base-zone/heap.js';
+import { prepareVowTools as rawPrepareVowTools } from './src/index.js';
+
+export { EVow$, OrVow$ } from './src/index.js';
+
+/** @type {import('./src/types.js').IsRetryableReason} */
+const isRetryableReason = (reason, priorRetryValue) => {
+  if (
+    isUpgradeDisconnection(reason) &&
+    (!priorRetryValue ||
+      reason.incarnationNumber > priorRetryValue.incarnationNumber)
+  ) {
+    return reason;
+  }
+  return undefined;
+};
+
+export const defaultPowers = harden({
+  isRetryableReason,
+});
+
+/**
+ * Produce SwingSet-compatible vowTools, with an arbitrary Zone type
+ *
+ * @type {typeof rawPrepareVowTools}
+ */
+export const prepareVowTools = (zone, powers = {}) =>
+  rawPrepareVowTools(zone, { ...defaultPowers, ...powers });
+
+/**
+ * `vowTools` that are not durable, but are useful in non-durable clients that
+ * need to consume vows from other SwingSet vats.
+ */
+export const heapVowTools = prepareVowTools(makeHeapZone());
+
+export const { E: heapVowE } = heapVowTools;