yieldstar 0.5.0 → 0.6.0

package/src/exports/workflow.ts

@@ -1,17 +1,22 @@
 import type { Logger } from "pino";
 import type {
+  Durable,
   WorkflowEvent,
   WorkflowGenerator,
   EventParams,
   EventContext,
+  IfDurable,
 } from "@yieldstar/core";
 import type { StepRunner } from "../internal/step-runner";
 import { isIterable } from "../internal/utils";
-import {
-  deserializeStepResponse,
-  serializeStepResponse,
-} from "../internal/serialise";
+import { decodeStepRecord, encodeStepRecord } from "../internal/step-record";
 import { createStepRunner } from "../internal/step-runner";
+import {
+  StepRuntimeCall,
+  executeRuntimeCall,
+  infrastructure,
+} from "../internal/runtime-call";
+import { StepEffectCall, executeEffectCall } from "../internal/effect-call";
 import {
   StepResponse,
   StepKey,
@@ -19,9 +24,15 @@ import {
   StepResult,
   StepDelay,
   StepCacheCheck,
+  StepEffectWait,
   StepInvalid,
   StepStoreWait,
   WorkflowResult,
+  InfrastructureError,
+  LeaseLostError,
+  StepConflictError,
+  isLeaseLost,
+  WORKFLOW_RESULT_STEP_KEY,
 } from "@yieldstar/core";
 
 export type WorkflowFn<
@@ -34,51 +45,70 @@ export type WorkflowFn<
   logger: Logger
 ) => AsyncGenerator<any, Result>;
 
+/**
+ * A workflow function whose params and result are durable values. Params are
+ * an input, so a function type cannot check them; a missing property named
+ * for the problem does instead.
+ */
+export type DurableWorkflowFn<Params, Result> = IfDurable<
+  Params,
+  { "Workflow params must be durable values": Durable<Params> }
+> &
+  IfDurable<
+    Result,
+    (step: any, event: any, logger: any) => AsyncGenerator<any, Durable<Result>>
+  >;
+
+/**
+ * Wraps a workflow function in a generator that advances its steps and yields
+ * control to the executor whenever a step needs async work.
+ */
 export function workflow<
   Params extends EventParams,
   Result,
   Context extends EventContext
 >(
-  workflowFn: WorkflowFn<Params, Result, Context>
+  workflowFn: WorkflowFn<Params, Result, Context> &
+    DurableWorkflowFn<Params, Result>
 ): WorkflowGenerator<Params, Result, Context> {
-  /**
-   * @description Advances workflow steps, handling any workflow logic, and
-   * yielding control to a workflow executor to do async work
-   * @yields {StepResponse}
-   */
-  return async function* workflowGenerator({ event, heapClient, storeClient, logger }) {
-    const stepRunner = createStepRunner({ event, storeClient });
+  return async function* workflowGenerator({
+    event,
+    lease,
+    signal,
+    heapClient,
+    storeClient,
+    executionClient,
+    effectClient,
+    clock,
+    logger,
+  }) {
+    const stepRunner = createStepRunner({ event, clock });
     const workflowIterator = workflowFn(stepRunner, event, logger);
     const { executionId } = event;
 
     let iteratorResult: IteratorResult<any> | null = null;
     let nextIteratorResult: IteratorResult<any> | null = null;
+    // A step that produced a result resumes with its decoded record, which
+    // is what it returns to workflow code.
+    let resumeWith: StepResult | undefined;
     const stepKeys = new Set<string>();
 
     while (true) {
       let stepAttempt = 0;
       let stepKey: string;
 
-      /**
-       * If we already have the next iterator result from a previous iteration
-       * (e.g. it threw an error and advanced the workflow), use that, otherwise,
-       * advance the workflow generator
-       */
+      // Throwing a step error into the workflow already advanced it.
       if (nextIteratorResult) {
         iteratorResult = nextIteratorResult;
         nextIteratorResult = null;
       } else {
-        iteratorResult = await workflowIterator.next();
+        stopIfAborted(signal);
+        iteratorResult = await workflowIterator.next(resumeWith);
       }
+      resumeWith = undefined;
 
-      /**
-       * Get the StepKey from the step runner.
-       * If the generator is done, the workflow has returned, so we set a
-       * special key for that.
-       * Finally, check that this call site wasn't reached before.
-       */
       if (iteratorResult.done) {
-        stepKey = "$$workflow-result$$";
+        stepKey = WORKFLOW_RESULT_STEP_KEY;
       } else if (!(iteratorResult.value instanceof StepKey)) {
         throw new Error("Step runners must yield a StepKey object");
       } else {
@@ -89,41 +119,26 @@ export function workflow<
         stepKeys.add(stepKey)
       }
 
-      /**
-       * Using the StepKey, retrieve the previous response for this step from
-       * the cache
-       */
-      let cached = await heapClient.readStep({
-        executionId,
-        stepKey,
-      });
+      let cached = await infrastructure(() =>
+        heapClient.readStep({
+          executionId,
+          stepKey,
+        })
+      );
 
-      /**
-       * Increment attempt counter. We'll save this after execution.
-       */
       if (cached?.meta) {
         stepAttempt = cached.meta.attempt + 1;
       }
 
-      /**
-       * If the step needs to be retried, ignore the cached value
-       */
+      // An unfinished record is a failed attempt: run the step again.
       if (cached?.meta.done === false) {
         cached = null;
       }
 
-      /**
-       * If the workflow generator hasn't returned, advance the step runner
-       */
       if (!iteratorResult.done) {
         iteratorResult = await workflowIterator.next();
       }
 
-      /**
-       * We can now get a StepResponse object from the iterator result.
-       * The step runner generator always yields a StepResponse, whereas
-       * the workflow generator return value needs to be wrapped.
-       */
       let stepResponse: StepResponse;
 
       if (iteratorResult.done) {
@@ -132,26 +147,45 @@ export function workflow<
         stepResponse = iteratorResult.value;
       }
 
-      /**
-       * If the first yielded value is a cache check, advance to actual step,
-       * passing it the cached value
-       */
       if (stepResponse instanceof StepCacheCheck) {
         const cachedResponse = cached
-          ? deserializeStepResponse(cached.stepResponseJson)
+          ? decodeStepRecord(cached.stepResponseJson)
           : null;
+        // Resuming the step runs the step function unless it is cached.
+        stopIfAborted(signal);
         iteratorResult = await workflowIterator.next(cachedResponse);
         stepResponse = iteratorResult.value;
+
+        // A step that needs a runtime client yields a request. Make the call
+        // here, outside workflow code, and resume the step with its result.
+        // An infrastructure error rejects the delivery without resuming it.
+        while (
+          stepResponse instanceof StepRuntimeCall ||
+          stepResponse instanceof StepEffectCall
+        ) {
+          stopIfAborted(signal);
+          const callResult =
+            stepResponse instanceof StepEffectCall
+              ? await executeEffectCall(stepResponse.request, {
+                  effects: effectClient,
+                  executionId,
+                  clock,
+                  assertLease: () => stopIfAborted(signal),
+                  logger,
+                })
+              : await executeRuntimeCall(stepResponse, {
+                  stores: storeClient,
+                  executions: executionClient,
+                });
+          iteratorResult = await workflowIterator.next(callResult);
+          stepResponse = iteratorResult.value;
+        }
       } else if (!(stepResponse instanceof WorkflowResult)) {
         throw new Error("Step runners must yield a CacheCheck object");
       }
 
-      /**
-       * Check for invalid iterators e.g. developer didn't use yield* or didn't
-       * use a step runner
-       * @todo: iterable check should be before StepKey check
-       * @todo: not throwing here causes a critical error – should workflow break?
-       */
+      // TODO: the iterable check should come before the StepKey check.
+      // TODO: not throwing here causes a critical error; should the workflow break?
       if (isIterable(stepResponse)) {
         console.log("[ERR] Steps must be yielded using yield*\n");
         stepResponse = new StepInvalid();
@@ -164,84 +198,106 @@ export function workflow<
         stepResponse = new StepInvalid();
       }
 
-      /**
-       * Determine if step needs to be retried
-       */
+      let stepResponseJson: string | undefined;
+      // The workflow result is encoded on every delivery, so that an invalid
+      // result fails the same way whether or not it is already recorded.
+      if (!cached || stepResponse instanceof WorkflowResult) {
+        const record = encodeStepRecord(stepResponse, stepKey);
+        stepResponseJson = record.json;
+        stepResponse = record.response;
+      }
+
       const needsRetry =
         !cached?.meta.done &&
         stepResponse instanceof StepError &&
         // 1-indexed vs 0-indexed
         stepResponse.maxAttempts > stepAttempt + 1;
+      // A watched effect stays unfinished, so the next delivery begins it
+      // again; its waiter is deleted when the step's result is recorded.
       const needsWake =
-        !cached?.meta.done && stepResponse instanceof StepStoreWait;
+        !cached?.meta.done &&
+        (stepResponse instanceof StepStoreWait ||
+          stepResponse instanceof StepEffectWait);
 
-      /**
-       * If this step attempt is not already cached, cache it
-       */
-      if (!cached) {
-        await heapClient.writeStep({
-          executionId,
-          stepKey,
-          stepAttempt,
-          stepDone: !needsRetry && !needsWake,
-          stepResponseJson: serializeStepResponse(stepResponse),
-        });
+      if (!cached && stepResponseJson !== undefined) {
+        const done = !needsRetry && !needsWake;
+        stopIfAborted(signal);
+        const written = await infrastructure(() =>
+          heapClient.writeStep({
+            lease,
+            stepKey,
+            stepAttempt,
+            done,
+            stepResponseJson: stepResponseJson!,
+          })
+        );
+        // Another claim has taken over: stop without an outcome.
+        if (isLeaseLost(written)) {
+          throw new InfrastructureError(new LeaseLostError(executionId));
+        }
+        // The step was already recorded with a different value. The record
+        // stands, so this delivery must not continue with its own value: end
+        // it as a retry, and the next delivery replays the recorded one.
+        if (
+          written.stepResponseJson !== stepResponseJson ||
+          written.meta.done !== done
+        ) {
+          throw new InfrastructureError(
+            new StepConflictError(executionId, stepKey)
+          );
+        }
       }
 
-      /**
-       * Once the WorkflowResult is cached, return the WorkflowResult to the
-       * upstream consumer e.g the worker
-       */
       if (stepResponse instanceof WorkflowResult) {
         return stepResponse;
       }
 
-      /**
-       * Once invalid iterator steps have been cached, stop execution
-       */
+      // Only an invalid workflow result is recorded as a step error under
+      // the workflow result's key. The workflow has finished, so it fails.
+      if (iteratorResult.done && stepResponse instanceof StepError) {
+        throw stepResponse.err;
+      }
+
       if (stepResponse instanceof StepInvalid) {
         break;
       }
 
-      /**
-       * If step runner yielded a step error, either throw the error back for
-       * user to handle, or yield to worker, if it should be retried.
-       * (Throwing also advances the workflow generator, so, in that case, we
-       * store the next iterator result, and continue to the next step).
-       */
       if (stepResponse instanceof StepError) {
         if (needsRetry) {
-          yield new StepDelay(Date.now() + stepResponse.retryInterval);
+          yield new StepDelay(clock() + stepResponse.retryInterval);
         } else {
+          stopIfAborted(signal);
           nextIteratorResult = await workflowIterator.throw(stepResponse.err);
           continue;
         }
       }
 
-      /**
-       * If the delay has already elapsed, continue straight to next step
-       */
       if (stepResponse instanceof StepDelay) {
-        if (stepResponse.resumeIn <= Date.now()) {
+        if (stepResponse.wakeAt <= clock()) {
           continue;
         }
       }
 
-      /**
-       * Yield control back to the worker if the stepResponse is not a result
-       * i.e. async work is required. (Whenever we receive a StepResult, it's
-       * always possible to continue straight to the next step).
-       */
-      if (!(stepResponse instanceof StepResult)) {
+      if (stepResponse instanceof StepResult) {
+        resumeWith = stepResponse;
+      } else {
         yield stepResponse;
       }
     }
 
-    /**
-     * If we arrive here, something has gone wrong internally
-     */
-    throw new Error("Critical error");
+    throw new Error(
+      "Workflow yielded an invalid step. Steps must be yielded with yield* from a step runner."
+    );
   };
 }
 
 export const createWorkflow = workflow;
+
+/**
+ * Ends the delivery once its signal has aborted, before it runs more workflow
+ * code or makes another fenced write. Like a lost lease found by a fenced
+ * write, it rejects with an infrastructure error, which is not acknowledged.
+ */
+function stopIfAborted(signal: AbortSignal) {
+  if (signal.aborted) throw new InfrastructureError(signal.reason);
+}

package/src/index.ts

@@ -2,10 +2,27 @@ export { createLocalSdk } from "./exports/sdk-local";
 export { createHttpSdkFactory } from "./exports/sdk-http";
 export { createWorkflowRouter } from "./exports/router";
 export { RetryableError } from "./exports/errors";
+export {
+  EffectClientInvariantError,
+  EffectDeliveryError,
+  ExecutionAdmissionError,
+  WORKFLOW_RESULT_STEP_KEY,
+  WorkflowEffectError,
+  WorkflowStartError,
+  WorkflowValueError,
+  registerErrorClass,
+} from "@yieldstar/core";
 export { createWorkflow, workflow } from "./exports/workflow";
-export type { WorkflowFn } from "./exports/workflow";
+export type { DurableWorkflowFn, WorkflowFn } from "./exports/workflow";
 export { defineStore } from "./internal/step-runner";
-export type { WorkflowStore } from "./internal/step-runner";
+export type {
+  DurableStepFn,
+  EffectDescriptor,
+  EffectLookup,
+  StepRunner,
+  StepRunOptions,
+  WorkflowStore,
+} from "./internal/step-runner";
 export type {
   Draft,
   RuntimeStore,
@@ -17,8 +34,23 @@ export type {
   StoreSelector,
   StoreSnapshot,
   StoreState,
+  DurableStoreSchema,
   StoreUpdateFromResult,
   StoreUpdateResult,
   StoreVersion,
   WorkflowEvent,
+  ExecutionAdmissionErrorCode,
+  ExecutionOutcome,
+  ExecutionRecord,
+  ExecutionStatus,
+  ExecutionParent,
+  Durable,
+  DurableObject,
+  DurableValue,
+  ErrorClass,
+  WorkflowValueErrorCode,
+  WorkflowStartErrorCode,
+  EffectDeliveryErrorCode,
+  EffectRecord,
+  WorkflowEffectErrorCode,
 } from "@yieldstar/core";

package/src/internal/effect-call.ts

@@ -0,0 +1,217 @@
+import type { Logger } from "pino";
+import {
+  EffectClientInvariantError,
+  EffectDeliveryError,
+  InfrastructureError,
+  StepResponse,
+  durableValueCodec,
+  type DurableObject,
+  type DurableValue,
+  type EffectClient,
+  type EffectDeliveryErrorCode,
+} from "@yieldstar/core";
+
+/** What `lookup` reports about an effect ID (RFC 005). */
+export type EffectLookup<T> =
+  | { status: "settled"; result: T }
+  | { status: "not-found" }
+  | { status: "unknown" };
+
+/** The effect request a step yields once its descriptor is valid. */
+export type EffectCallRequest = {
+  stepKey: string;
+  effectId: string;
+  operation: string;
+  input: DurableObject;
+  retryIn: number;
+  lookup(effectId: string): Promise<unknown>;
+  perform(effectId: string): Promise<unknown>;
+};
+
+/**
+ * - `settled`: the effect's result, which the step records.
+ * - `rejected`: the effect exists with a different operation or input.
+ * - `suspended`: the step watches the effect and is due again at `wakeAt`.
+ */
+export type EffectCallOutcome =
+  | { status: "settled"; result: DurableValue }
+  | { status: "rejected"; code: "EFFECT_REQUEST_MISMATCH" }
+  | { status: "suspended"; wakeAt: number };
+
+/**
+ * Yielded by `step.effect`. The driver runs the effect with
+ * `executeEffectCall` and resumes the step with its outcome.
+ */
+export class StepEffectCall extends StepResponse {
+  static type = "effect-call";
+  readonly type = "effect-call";
+  readonly request: EffectCallRequest;
+
+  constructor(request: EffectCallRequest) {
+    super();
+    this.request = request;
+  }
+}
+
+/**
+ * Runs an effect step's protocol against the runtime's `EffectClient`. Every
+ * failure that must not be recorded rejects with an `InfrastructureError`
+ * whose cause is an `EffectDeliveryError`, so the delivery is retried.
+ */
+export async function executeEffectCall(
+  request: EffectCallRequest,
+  context: {
+    effects: EffectClient;
+    executionId: string;
+    clock: () => number;
+    /** Checked before every callback, so a lost lease makes no external call. */
+    assertLease: () => void;
+    logger: Logger;
+  }
+): Promise<EffectCallOutcome> {
+  const { effects, executionId, clock, assertLease, logger } = context;
+  const { stepKey, effectId, operation, input, retryIn } = request;
+
+  const fail = (code: EffectDeliveryErrorCode, message: string, cause?: unknown) =>
+    new InfrastructureError(
+      new EffectDeliveryError(
+        code,
+        { effectId, stepKey, message },
+        cause === undefined ? undefined : { cause }
+      )
+    );
+
+  async function client<T>(method: string, call: () => Promise<T>): Promise<T> {
+    try {
+      return await call();
+    } catch (err) {
+      const message = `EffectClient.${method} failed for effect "${effectId}": ${errorMessage(err)}`;
+      if (isInvariantError(err)) throw fail("EFFECT_RUNTIME_INVARIANT", message, err);
+      throw fail("EFFECT_CLIENT_UNAVAILABLE", message, err);
+    }
+  }
+
+  const malformedClient = (method: string) =>
+    fail(
+      "EFFECT_RUNTIME_INVARIANT",
+      `EffectClient.${method} returned a malformed response for effect "${effectId}"`
+    );
+
+  async function suspend(): Promise<EffectCallOutcome> {
+    await client("watch", () => effects.watch({ effectId, executionId, stepKey }));
+    return { status: "suspended", wakeAt: clock() + retryIn };
+  }
+
+  async function settle(result: unknown): Promise<EffectCallOutcome> {
+    const encoding = durableValueCodec.encode(result);
+    if (encoding.status === "invalid") {
+      throw fail(
+        "EFFECT_HANDLER_INVALID",
+        `Effect "${effectId}" result is not a durable value: ${encoding.message}`
+      );
+    }
+    const settled = await client("settle", () =>
+      effects.settle({ operation, effectId, result: result as DurableValue })
+    );
+    if (!isObject(settled) || !("result" in settled)) throw malformedClient("settle");
+    if (settled.status === "conflict") {
+      logger.warn(
+        {
+          executionId,
+          stepKey,
+          effectId,
+          result: settled.result,
+          conflictingResult: settled.conflictingResult,
+        },
+        `Effect "${effectId}" settled with a different result; the first result stands`
+      );
+    } else if (settled.status !== "settled") {
+      throw malformedClient("settle");
+    }
+    return { status: "settled", result: settled.result };
+  }
+
+  const begun = await client("begin", () =>
+    effects.begin({ operation, effectId, input, executionId, stepKey })
+  );
+  if (!isObject(begun)) throw malformedClient("begin");
+
+  let next: "lookup" | "perform";
+  switch (begun.status) {
+    case "settled":
+      if (!("result" in begun)) throw malformedClient("begin");
+      return { status: "settled", result: begun.result };
+    case "rejected":
+      if (begun.code !== "EFFECT_REQUEST_MISMATCH") throw malformedClient("begin");
+      return { status: "rejected", code: begun.code };
+    case "new":
+      next = "perform";
+      break;
+    case "pending":
+      // An earlier attempt may have started the operation, or finished it.
+      next = "lookup";
+      break;
+    default:
+      throw malformedClient("begin");
+  }
+
+  if (next === "lookup") {
+    assertLease();
+    let found: unknown;
+    try {
+      found = await request.lookup(effectId);
+    } catch {
+      return suspend();
+    }
+    if (!isObject(found)) throw malformedLookup(fail, effectId);
+    switch (found.status) {
+      case "settled":
+        if (!("result" in found)) throw malformedLookup(fail, effectId);
+        return settle(found.result);
+      case "unknown":
+        return suspend();
+      case "not-found":
+        break;
+      default:
+        throw malformedLookup(fail, effectId);
+    }
+  }
+
+  assertLease();
+  let performed: unknown;
+  try {
+    performed = await request.perform(effectId);
+  } catch {
+    return suspend();
+  }
+  return settle(performed);
+}
+
+function malformedLookup(
+  fail: (code: EffectDeliveryErrorCode, message: string) => InfrastructureError,
+  effectId: string
+) {
+  return fail(
+    "EFFECT_HANDLER_INVALID",
+    `lookup for effect "${effectId}" returned a malformed response: expected { status: "settled", result }, { status: "not-found" } or { status: "unknown" }`
+  );
+}
+
+// Matches by code too, so an invariant error from another copy of
+// @yieldstar/core, or one revived without its class, is still recognised.
+function isInvariantError(err: unknown) {
+  return (
+    err instanceof EffectClientInvariantError ||
+    (typeof err === "object" &&
+      err !== null &&
+      (err as { code?: unknown }).code === "EFFECT_RUNTIME_INVARIANT")
+  );
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function errorMessage(err: unknown) {
+  return err instanceof Error ? err.message : String(err);
+}