@yieldstar/core 0.5.0 → 0.6.0

package/src/base/errors.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, test } from "vitest";
+import { durableValueCodec, encodeThrownValue } from "./durable-value";
+import { WorkflowStartError } from "./execution";
+import { WorkflowValueError, registerErrorClass } from "./errors";
+
+function encode(value: unknown) {
+  const encoding = durableValueCodec.encode(value);
+  if (encoding.status !== "encoded") {
+    throw new Error(`expected encoded, got: ${encoding.message}`);
+  }
+  return encoding.canonical;
+}
+
+function decode(canonical: string) {
+  const decoding = durableValueCodec.decode(canonical);
+  if (decoding.status !== "decoded") {
+    throw new Error(`expected decoded, got: ${decoding.message}`);
+  }
+  return decoding.value;
+}
+
+function roundTrip<T>(value: T) {
+  return decode(encode(value)) as T;
+}
+
+class CourierError extends Error {
+  code = "COURIER_DOWN";
+  courier: string;
+  constructor(courier: string, options?: ErrorOptions) {
+    if (typeof courier !== "string") throw new Error("courier is required");
+    super(`${courier} is down`, options);
+    this.name = "CourierError";
+    this.courier = courier;
+  }
+  describe() {
+    return `${this.courier}: ${this.message}`;
+  }
+}
+registerErrorClass("CourierError", CourierError);
+
+class UnregisteredError extends Error {
+  code = "NOPE";
+  attempts = 3;
+  constructor(message: string) {
+    super(message);
+    this.name = "UnregisteredError";
+  }
+}
+
+describe("error encoding", () => {
+  test("is tagged and canonical", () => {
+    const error = new Error("boom");
+    error.stack = "stack";
+    expect(encode(error)).toBe(
+      '{"$type":"error","message":"boom","name":"Error","stack":"stack"}'
+    );
+  });
+
+  test("keeps name, message, stack, a string code, cause and durable fields", () => {
+    const error = new CourierError("dhl", { cause: new TypeError("socket") });
+    const revived = roundTrip(error);
+    expect(revived).toBeInstanceOf(CourierError);
+    expect(revived.name).toBe("CourierError");
+    expect(revived.message).toBe("dhl is down");
+    expect(revived.stack).toBe(error.stack);
+    expect(revived.code).toBe("COURIER_DOWN");
+    expect(revived.courier).toBe("dhl");
+    expect(revived.describe()).toBe("dhl: dhl is down");
+    expect(revived.cause).toBeInstanceOf(TypeError);
+    expect((revived.cause as Error).message).toBe("socket");
+  });
+
+  test("revives without calling the constructor", () => {
+    const revived = roundTrip(new CourierError("ups"));
+    expect(revived).toBeInstanceOf(CourierError);
+  });
+
+  test("matches the original's own property layout", () => {
+    const error = new CourierError("dhl", { cause: "flaky" });
+    const revived = roundTrip(error);
+    expect(Object.keys(revived).sort()).toEqual(Object.keys(error).sort());
+    expect(Object.getOwnPropertyDescriptor(revived, "message")?.enumerable).toBe(false);
+    expect(Object.getOwnPropertyDescriptor(revived, "cause")?.enumerable).toBe(false);
+    expect(revived).toEqual(error);
+  });
+
+  test("revives native errors", () => {
+    const revived = roundTrip(new CourierError("dhl"));
+    expect(Object.prototype.toString.call(revived)).toBe("[object Error]");
+  });
+
+  test("revives an error without a stack without one", () => {
+    const error = new Error("boom");
+    delete error.stack;
+    expect(roundTrip(error).stack).toBeUndefined();
+  });
+
+  test("omits non-durable properties", () => {
+    const error = Object.assign(new Error("boom"), {
+      at: new Date(0),
+      handler: () => {},
+      ok: 1,
+    });
+    const revived = roundTrip(error);
+    expect(Object.keys(revived)).toEqual(["ok"]);
+  });
+
+  test("ignores a non-string code", () => {
+    const revived = roundTrip(Object.assign(new Error("boom"), { code: 42 }));
+    expect(revived).not.toHaveProperty("code");
+  });
+
+  test("keeps a cause of undefined distinct from no cause", () => {
+    expect(Object.hasOwn(roundTrip(new Error("a", { cause: undefined })), "cause")).toBe(
+      true
+    );
+    expect(Object.hasOwn(roundTrip(new Error("a")), "cause")).toBe(false);
+  });
+
+  test("omits a cause that cycles back to the error", () => {
+    const error = new Error("loop");
+    error.cause = error;
+    expect(Object.hasOwn(roundTrip(error), "cause")).toBe(false);
+  });
+
+  test("wraps fields with a $type key", () => {
+    const revived = roundTrip(Object.assign(new Error("boom"), { $type: "undefined" }));
+    expect((revived as unknown as { $type: string }).$type).toBe("undefined");
+  });
+
+  test("keeps AggregateError's errors", () => {
+    const revived = roundTrip(new AggregateError([new RangeError("r"), "two"], "all"));
+    expect(revived).toBeInstanceOf(AggregateError);
+    expect(revived.errors).toHaveLength(2);
+    expect(revived.errors[0]).toBeInstanceOf(RangeError);
+    expect(revived.errors[1]).toBe("two");
+    expect(Object.getOwnPropertyDescriptor(revived, "errors")?.enumerable).toBe(false);
+  });
+
+  test("works anywhere a value can appear", () => {
+    const revived = roundTrip({ ok: false, errors: [new TypeError("t")] });
+    expect(revived.errors[0]).toBeInstanceOf(TypeError);
+  });
+});
+
+describe("error revival", () => {
+  test("revives an unregistered class as an Error with the same name, message, code and fields", () => {
+    const revived = roundTrip(new UnregisteredError("nope"));
+    expect(Object.getPrototypeOf(revived)).toBe(Error.prototype);
+    expect(revived.name).toBe("UnregisteredError");
+    expect(revived.message).toBe("nope");
+    expect(revived.code).toBe("NOPE");
+    expect(revived.attempts).toBe(3);
+  });
+
+  test.each([
+    TypeError,
+    RangeError,
+    SyntaxError,
+    ReferenceError,
+    EvalError,
+    URIError,
+  ])("revives %o by default", (errorClass) => {
+    const revived = roundTrip(new errorClass("m"));
+    expect(Object.getPrototypeOf(revived)).toBe(errorClass.prototype);
+    expect(revived.name).toBe(errorClass.name);
+    expect(Object.hasOwn(revived, "name")).toBe(false);
+  });
+
+  test("revives the Yieldstar error classes by default", () => {
+    const start = roundTrip(new WorkflowStartError("START_REQUEST_MISMATCH", "m"));
+    expect(start).toBeInstanceOf(WorkflowStartError);
+    expect(start.code).toBe("START_REQUEST_MISMATCH");
+
+    const value = roundTrip(new WorkflowValueError("INVALID_STEP_VALUE", "now", "m"));
+    expect(value).toBeInstanceOf(WorkflowValueError);
+    expect(value.code).toBe("INVALID_STEP_VALUE");
+    expect(value.stepKey).toBe("now");
+  });
+
+  test("registration replaces the class for a name", () => {
+    class First extends Error {}
+    class Second extends Error {}
+    registerErrorClass("ReplacedError", First);
+    registerErrorClass("ReplacedError", Second);
+    const error = new First("m");
+    error.name = "ReplacedError";
+    expect(roundTrip(error)).toBeInstanceOf(Second);
+  });
+
+  test("rejects invalid registrations", () => {
+    expect(() => registerErrorClass("", Error)).toThrow(TypeError);
+    expect(() => registerErrorClass("Point", class Point {} as never)).toThrow(TypeError);
+  });
+});
+
+describe("encodeThrownValue", () => {
+  test("keeps a durable thrown value as thrown", () => {
+    expect(decode(encodeThrownValue("boom"))).toBe("boom");
+    expect(decode(encodeThrownValue({ code: 1 }))).toEqual({ code: 1 });
+    expect(decode(encodeThrownValue(new RangeError("r")))).toBeInstanceOf(RangeError);
+  });
+
+  test("records a non-durable thrown value as Error(String(value))", () => {
+    const revived = decode(encodeThrownValue(new Date(0))) as Error;
+    expect(Object.getPrototypeOf(revived)).toBe(Error.prototype);
+    expect(revived.message).toBe(String(new Date(0)));
+    expect((decode(encodeThrownValue(10n)) as Error).message).toBe("10");
+  });
+});

package/src/base/errors.ts

@@ -0,0 +1,72 @@
+import {
+  EffectClientInvariantError,
+  EffectDeliveryError,
+  WorkflowEffectError,
+} from "./effect";
+import { WorkflowStartError } from "./execution";
+
+export type WorkflowValueErrorCode = "INVALID_STEP_VALUE" | "STEP_SCHEMA_INVALID";
+
+/** The `stepKey` of a `WorkflowValueError` raised by an invalid workflow result. */
+export const WORKFLOW_RESULT_STEP_KEY = "$$workflow-result$$";
+
+/**
+ * Thrown to workflow code when a step produces a value the durable value codec
+ * rejects, or a step's schema rejects its decoded value. It is recorded as the
+ * step's error, so replay throws it again.
+ */
+export class WorkflowValueError extends Error {
+  readonly code: WorkflowValueErrorCode;
+  readonly stepKey: string;
+
+  constructor(code: WorkflowValueErrorCode, stepKey: string, message: string) {
+    super(message);
+    this.name = "WorkflowValueError";
+    this.code = code;
+    this.stepKey = stepKey;
+  }
+}
+
+export type ErrorClass = abstract new (...args: any[]) => Error;
+
+const errorClasses = new Map<string, ErrorClass>();
+
+/**
+ * Registers the class that decoding revives errors named `name` as, replacing
+ * any class registered under that name. Registration is per process: a worker
+ * that has not registered a class revives its errors as plain `Error`s with
+ * the same name, message, code, cause and fields.
+ */
+export function registerErrorClass(name: string, errorClass: ErrorClass): void {
+  if (typeof name !== "string" || name === "") {
+    throw new TypeError("Error class name must be a non-empty string");
+  }
+  if (
+    typeof errorClass !== "function" ||
+    !(errorClass.prototype instanceof Error || errorClass === Error)
+  ) {
+    throw new TypeError(`Error class "${name}" must extend Error`);
+  }
+  errorClasses.set(name, errorClass);
+}
+
+export function registeredErrorClass(name: string): ErrorClass | undefined {
+  return errorClasses.get(name);
+}
+
+// Names are spelled out so a minifying bundler cannot change them.
+const defaults: [string, ErrorClass][] = [
+  ["TypeError", TypeError],
+  ["RangeError", RangeError],
+  ["SyntaxError", SyntaxError],
+  ["ReferenceError", ReferenceError],
+  ["EvalError", EvalError],
+  ["URIError", URIError],
+  ["AggregateError", AggregateError],
+  ["WorkflowStartError", WorkflowStartError],
+  ["WorkflowValueError", WorkflowValueError],
+  ["WorkflowEffectError", WorkflowEffectError],
+  ["EffectClientInvariantError", EffectClientInvariantError],
+  ["EffectDeliveryError", EffectDeliveryError],
+];
+for (const [name, errorClass] of defaults) registerErrorClass(name, errorClass);

package/src/base/event.ts

@@ -38,9 +38,14 @@ export type WorkflowEvent<
   context: Context;
 };
 
+/**
+ * The event a trigger route passes through middleware before admission.
+ * `executionId` is absent when the caller lets the runtime choose one.
+ */
 export type MiddlewareEvent<
   Params extends EventParams = EventParams,
   Context extends MiddlewareEventContext = MiddlewareEventContext
-> = ExecutionEvent<Params> & {
+> = Omit<ExecutionEvent<Params>, "executionId" | "context"> & {
+  executionId?: string;
   context: Context;
 };

package/src/base/execution.ts

@@ -0,0 +1,303 @@
+import type { DurableObject } from "./durable-value";
+import type { EventContext, EventParams } from "./event";
+
+export type ExecutionStatus =
+  | "admitted"
+  | "running"
+  | "suspended"
+  | "completed"
+  | "failed";
+
+export type ExecutionOutcome =
+  | { status: "completed"; result: unknown }
+  | { status: "failed"; error: Error };
+
+/** The execution and step that started an execution with `step.start`. */
+export type ExecutionParent = { executionId: string; stepKey: string };
+
+/**
+ * The durable record of one workflow execution. Admission creates it and
+ * stores the event once; every delivery reads the event from here.
+ *
+ * - `admitted`: no delivery has been acknowledged yet.
+ * - `running`: the execution has a live lease. When the lease ends without a
+ *   terminal acknowledgement, the status returns to `suspended` if any
+ *   earlier delivery was acknowledged as suspended, and to `admitted`
+ *   otherwise.
+ * - `suspended`: the latest acknowledged delivery suspended the workflow.
+ * - `completed` and `failed` are terminal. `outcome` is present only in these
+ *   states.
+ *
+ * `parent` is present, and immutable, only on executions admitted by `start`.
+ */
+export interface ExecutionRecord {
+  executionId: string;
+  workflowId: string;
+  params: EventParams;
+  context: EventContext;
+  status: ExecutionStatus;
+  outcome?: ExecutionOutcome;
+  admittedAt: number;
+  updatedAt: number;
+  /** Consecutive deliveries that ended without an acknowledgement. */
+  unacknowledgedDeliveryCount: number;
+  parent?: ExecutionParent;
+}
+
+export type ExecutionAdmissionErrorCode =
+  | "EXECUTION_ID_CONFLICT"
+  | "INVALID_EXECUTION_EVENT";
+
+/**
+ * A lease on one execution, granted by `claimDue`. `token` is a fencing token:
+ * every claim of the execution issues a token greater than every earlier one,
+ * and only the current token's fenced writes are accepted. It also identifies
+ * the wakes the delivery covers. `expiresAt` is read from the runtime clock;
+ * clocks decide only when the execution becomes claimable again, never whose
+ * writes count.
+ */
+export type ExecutionLease = {
+  executionId: string;
+  token: number;
+  expiresAt: number;
+};
+
+/**
+ * Returned by a fenced write whose lease is no longer current: a higher token
+ * has been issued, or the lease has ended. The write changed nothing, and its
+ * holder must stop.
+ */
+export type LeaseLost = { status: "lost" };
+
+export function isLeaseLost(value: unknown): value is LeaseLost {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { status?: unknown }).status === "lost"
+  );
+}
+
+/**
+ * What a delivery reports once its durable work is finished:
+ * - `completed`: the workflow returned a result;
+ * - `suspended`: the unfinished step is recorded, and `wakeAt`, when present,
+ *   is the earliest time a paused step needs the execution to run again;
+ * - `failed`: workflow code threw an uncaught error.
+ *
+ * Infrastructure errors are never outcomes: the delivery rejects instead.
+ */
+export type WorkflowRunOutcome =
+  | { status: "completed"; result: unknown }
+  | { status: "suspended"; wakeAt?: number }
+  | { status: "failed"; error: Error };
+
+export type ExecutionAdmissionRequest = {
+  executionId?: string;
+  workflowId: string;
+  params: EventParams;
+  context: EventContext;
+};
+
+export type ExecutionAdmissionResult =
+  | { status: "accepted"; executionId: string }
+  | {
+      status: "rejected";
+      code: ExecutionAdmissionErrorCode;
+      message: string;
+    };
+
+export type WorkflowStartErrorCode =
+  | "INVALID_START_PARAMETERS"
+  | "START_REQUEST_MISMATCH";
+
+export type ExecutionStartRequest = {
+  /** Identifies the request: the calling execution and its step key. */
+  requestId: { executionId: string; stepKey: string };
+  workflowId: string;
+  params?: DurableObject;
+};
+
+export type ExecutionStartResult =
+  | { status: "accepted"; executionId: string }
+  | {
+      status: "rejected";
+      code: WorkflowStartErrorCode;
+      message: string;
+    };
+
+export type ExecutionWakeResult =
+  | { status: "requested" }
+  | { status: "ignored" }
+  | {
+      status: "rejected";
+      code: "EXECUTION_NOT_FOUND";
+      message: string;
+    };
+
+export type ExecutionAcknowledgeResult =
+  | { status: "suspended" }
+  | ExecutionOutcome
+  | LeaseLost;
+
+export type ExecutionRenewResult =
+  | { status: "renewed"; lease: ExecutionLease }
+  | LeaseLost;
+
+export type ExecutionReleaseResult = { status: "released" } | LeaseLost;
+
+export interface ExecutionClient {
+  /**
+   * Creates the execution record with status `admitted` and makes it due
+   * immediately, all-or-nothing. Execution IDs are never reused.
+   */
+  admit(request: ExecutionAdmissionRequest): Promise<ExecutionAdmissionResult>;
+
+  get(executionId: string): Promise<ExecutionRecord | undefined>;
+
+  /**
+   * Starts a workflow on behalf of the execution and step named by
+   * `requestId`, idempotently by that ID. A new start admits the target with
+   * the caller's context and a parent link to the caller, and records the
+   * start request, all-or-nothing. A repeated request returns the first
+   * target's ID if its workflow ID and canonical params match, and
+   * `START_REQUEST_MISMATCH` otherwise, whatever the target's status. Invalid
+   * params return `INVALID_START_PARAMETERS` and admit nothing. Not fenced.
+   */
+  start(request: ExecutionStartRequest): Promise<ExecutionStartResult>;
+
+  /**
+   * Requests a wake from outside a delivery, such as a store commit. Wakes not
+   * covered by a claimed delivery merge into one due time: the earliest.
+   */
+  requestWake(request: {
+    executionId: string;
+    wakeAt: number;
+  }): Promise<ExecutionWakeResult>;
+
+  /**
+   * Leases up to `limit` executions whose due time is at or before the runtime
+   * clock and that have no live lease, earliest due first. Each lease lasts
+   * `duration` milliseconds and carries a token greater than every earlier
+   * token for its execution. An execution has at most one live lease at a
+   * time, across every client sharing the backend.
+   */
+  claimDue(request: {
+    limit: number;
+    duration: number;
+  }): Promise<ExecutionLease[]>;
+
+  /**
+   * Extends a lease to `duration` milliseconds from now. Returns `lost` if a
+   * higher token has been issued or the lease has ended. An expired lease
+   * that has not been claimed again is still current.
+   */
+  renew(request: {
+    lease: ExecutionLease;
+    duration: number;
+  }): Promise<ExecutionRenewResult>;
+
+  /**
+   * Ends a lease without acknowledging an outcome. The delivery counts as
+   * unacknowledged, so the execution becomes claimable again only after the
+   * redelivery delay. Returns `lost` for a stale lease.
+   */
+  release(request: { lease: ExecutionLease }): Promise<ExecutionReleaseResult>;
+
+  /**
+   * Records a delivery's outcome and ends its lease, all-or-nothing. A
+   * `suspended` outcome clears the wakes the lease covered, leaving the
+   * execution due at the earliest of `wakeAt` and any wake requested since the
+   * claim. A stale lease returns `lost` and changes nothing.
+   */
+  acknowledge(request: {
+    lease: ExecutionLease;
+    outcome: WorkflowRunOutcome;
+  }): Promise<ExecutionAcknowledgeResult>;
+}
+
+/**
+ * Thrown by the driver when a fenced write returns `lost`: another claim has
+ * taken over the execution, so this delivery must stop without acknowledging.
+ */
+export class LeaseLostError extends Error {
+  readonly executionId: string;
+
+  constructor(executionId: string) {
+    super(`Lease on execution "${executionId}" was lost`);
+    this.name = "LeaseLostError";
+    this.executionId = executionId;
+  }
+}
+
+/**
+ * Thrown by the driver when the current holder writes a step record that
+ * already exists with a different value. The recorded value stands: the
+ * delivery ends as a retry, and the next delivery replays the recorded value.
+ */
+export class StepConflictError extends Error {
+  readonly executionId: string;
+  readonly stepKey: string;
+
+  constructor(executionId: string, stepKey: string) {
+    super(
+      `Step "${stepKey}" of execution "${executionId}" is already recorded with a different value`
+    );
+    this.name = "StepConflictError";
+    this.executionId = executionId;
+    this.stepKey = stepKey;
+  }
+}
+
+export class ExecutionAdmissionError extends Error {
+  readonly code: ExecutionAdmissionErrorCode;
+
+  constructor(code: ExecutionAdmissionErrorCode, message: string) {
+    super(message);
+    this.name = "ExecutionAdmissionError";
+    this.code = code;
+  }
+}
+
+/**
+ * Thrown to workflow code by `step.start` when the runtime rejects the start.
+ * The rejection is recorded as the step's result, so replay throws it again.
+ */
+export class WorkflowStartError extends Error {
+  readonly code: WorkflowStartErrorCode;
+
+  constructor(code: WorkflowStartErrorCode, message: string) {
+    super(message);
+    this.name = "WorkflowStartError";
+    this.code = code;
+  }
+}
+
+const INFRASTRUCTURE_ERROR = Symbol.for("yieldstar.infrastructureError");
+
+/**
+ * Wraps a failure of the runtime rather than of workflow code, such as a heap
+ * or store client rejecting. A delivery that hits one rejects without
+ * resuming workflow code, and is not acknowledged.
+ */
+export class InfrastructureError extends Error {
+  readonly [INFRASTRUCTURE_ERROR] = true;
+
+  constructor(cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.name = "InfrastructureError";
+  }
+
+  static is(value: unknown): value is InfrastructureError {
+    return (
+      typeof value === "object" &&
+      value !== null &&
+      (value as Record<symbol, unknown>)[INFRASTRUCTURE_ERROR] === true
+    );
+  }
+}
+
+export function isTerminalExecutionStatus(
+  status: ExecutionStatus
+): status is "completed" | "failed" {
+  return status === "completed" || status === "failed";
+}

package/src/base/heap.ts

@@ -1,3 +1,5 @@
+import type { ExecutionLease, LeaseLost } from "./execution";
+
 export type HeapRecord = {
   stepResponseJson: string;
   meta: { attempt: number; done: boolean };
@@ -8,11 +10,23 @@ export abstract class HeapClient {
     executionId: string;
     stepKey: string;
   }): Promise<HeapRecord | null>;
+
+  /**
+   * Records one attempt of a step, fenced by `lease`. The token check and the
+   * write are atomic: if the lease is not current, nothing changes and the
+   * write returns `lost`. A `done` record also deletes the step's store
+   * and effect waiters in the same write.
+   *
+   * Records are keyed by execution, step key and attempt, and never change
+   * once written. Rewriting an existing record succeeds without changing it,
+   * and resolves with the record as stored, which may hold a different value
+   * from the one written: callers compare it to detect a conflicting write.
+   */
   abstract writeStep(params: {
-    executionId: string;
+    lease: ExecutionLease;
     stepKey: string;
     stepAttempt: number;
-    stepDone: boolean;
+    done: boolean;
     stepResponseJson: string;
-  }): Promise<void>;
+  }): Promise<HeapRecord | LeaseLost>;
 }