@rivetkit/workflow-engine 2.1.0-rc.1

package/src/driver.ts

@@ -0,0 +1,103 @@
+import type { WorkflowMessageDriver } from "./types.js";
+
+/**
+ * A key-value entry returned from list operations.
+ */
+export interface KVEntry {
+	key: Uint8Array;
+	value: Uint8Array;
+}
+
+/**
+ * A write operation for batch writes.
+ */
+export interface KVWrite {
+	key: Uint8Array;
+	value: Uint8Array;
+}
+
+/**
+ * The engine driver provides the KV and scheduling interface.
+ * Implementations must provide these methods to integrate with different backends.
+ *
+ * IMPORTANT: Each workflow instance must have its own isolated driver/KV namespace.
+ * The workflow engine is the sole reader/writer of its KV during execution.
+ * KV operations do not include workflow IDs because isolation is provided externally
+ * by the host system (e.g., Cloudflare Durable Objects, dedicated actor processes).
+ *
+ * External systems may only enqueue messages through the configured message driver
+ * (via WorkflowHandle.message()).
+ * See architecture.md "Isolation Model" for details.
+ */
+export interface EngineDriver {
+	// === KV Operations ===
+
+	/**
+	 * Get a value by key.
+	 * Returns null if the key doesn't exist.
+	 */
+	get(key: Uint8Array): Promise<Uint8Array | null>;
+
+	/**
+	 * Set a value by key.
+	 */
+	set(key: Uint8Array, value: Uint8Array): Promise<void>;
+
+	/**
+	 * Delete a key.
+	 */
+	delete(key: Uint8Array): Promise<void>;
+
+	/**
+	 * Delete all keys with a given prefix.
+	 */
+	deletePrefix(prefix: Uint8Array): Promise<void>;
+
+	/**
+	 * List all key-value pairs with a given prefix.
+	 *
+	 * IMPORTANT: Results MUST be sorted by key in lexicographic byte order.
+	 * The workflow engine relies on this ordering for deterministic history
+	 * replay and name registry reconstruction. Failing to sort will cause
+	 * non-deterministic replay behavior.
+	 */
+	list(prefix: Uint8Array): Promise<KVEntry[]>;
+
+	/**
+	 * Batch write multiple key-value pairs.
+	 * Should be atomic if possible.
+	 */
+	batch(writes: KVWrite[]): Promise<void>;
+
+	// === Scheduling ===
+
+	/**
+	 * Set an alarm to wake the workflow at a specific time.
+	 * @param workflowId The workflow to wake
+	 * @param wakeAt Timestamp in milliseconds when to wake
+	 */
+	setAlarm(workflowId: string, wakeAt: number): Promise<void>;
+
+	/**
+	 * Clear any pending alarm for a workflow.
+	 */
+	clearAlarm(workflowId: string): Promise<void>;
+
+	/**
+	 * How often the worker polls for work (in milliseconds).
+	 * Affects the threshold for in-memory vs scheduled sleeps.
+	 */
+	readonly workerPollInterval: number;
+
+	/** Queue-backed message driver used for workflow messaging. */
+	readonly messageDriver: WorkflowMessageDriver;
+
+	/**
+	 * Wait for incoming messages when running in live mode.
+	 * Implementations should resolve when any of the specified message names are available.
+	 */
+	waitForMessages(
+		messageNames: string[],
+		abortSignal: AbortSignal,
+	): Promise<void>;
+}

package/src/errors.ts

@@ -0,0 +1,170 @@
+/**
+ * Thrown from steps to prevent retry.
+ * Use this when an error is unrecoverable and retrying would be pointless.
+ */
+export class CriticalError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "CriticalError";
+	}
+}
+
+/**
+ * Thrown from steps to force rollback without retry.
+ */
+export class RollbackError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "RollbackError";
+	}
+}
+
+/**
+ * Thrown when rollback is used without a checkpoint.
+ */
+export class RollbackCheckpointError extends Error {
+	constructor() {
+		super("Rollback requires a checkpoint before any rollback step");
+		this.name = "RollbackCheckpointError";
+	}
+}
+
+/**
+ * Internal: Workflow should sleep until deadline.
+ * This is thrown to yield control back to the scheduler.
+ * Optionally, the workflow can also wake early if certain messages arrive.
+ */
+export class SleepError extends Error {
+	constructor(
+		public readonly deadline: number,
+		public readonly messageNames?: string[],
+	) {
+		super(
+			messageNames && messageNames.length > 0
+				? `Sleeping until ${deadline} or messages: ${messageNames.join(", ")}`
+				: `Sleeping until ${deadline}`,
+		);
+		this.name = "SleepError";
+	}
+}
+
+/**
+ * Internal: Workflow is waiting for messages.
+ * This is thrown to yield control back to the scheduler.
+ */
+export class MessageWaitError extends Error {
+	constructor(public readonly messageNames: string[]) {
+		super(`Waiting for messages: ${messageNames.join(", ")}`);
+		this.name = "MessageWaitError";
+	}
+}
+
+/**
+ * Internal: Workflow was evicted.
+ * This is thrown when the workflow is being gracefully stopped.
+ */
+export class EvictedError extends Error {
+	constructor() {
+		super("Workflow evicted");
+		this.name = "EvictedError";
+	}
+}
+
+/**
+ * Internal: Stop rollback traversal.
+ */
+export class RollbackStopError extends Error {
+	constructor() {
+		super("Rollback traversal halted");
+		this.name = "RollbackStopError";
+	}
+}
+
+/**
+ * Workflow code changed incompatibly.
+ * Thrown when history doesn't match the current workflow code.
+ */
+export class HistoryDivergedError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "HistoryDivergedError";
+	}
+}
+
+/**
+ * Step exhausted all retries.
+ */
+export class StepExhaustedError extends Error {
+	constructor(
+		public readonly stepName: string,
+		public readonly lastError?: string,
+	) {
+		super(
+			`Step "${stepName}" exhausted retries: ${lastError ?? "unknown error"}`,
+		);
+		this.name = "StepExhaustedError";
+	}
+}
+
+/**
+ * Step failed (will be retried).
+ * Internal error used to trigger retry logic.
+ */
+export class StepFailedError extends Error {
+	constructor(
+		public readonly stepName: string,
+		public readonly originalError: unknown,
+		public readonly attempts: number,
+	) {
+		super(`Step "${stepName}" failed (attempt ${attempts})`);
+		this.name = "StepFailedError";
+		this.cause = originalError;
+	}
+}
+
+/**
+ * Join had branch failures.
+ */
+export class JoinError extends Error {
+	constructor(public readonly errors: Record<string, Error>) {
+		super(`Join failed: ${Object.keys(errors).join(", ")}`);
+		this.name = "JoinError";
+	}
+}
+
+/**
+ * Race had all branches fail.
+ */
+export class RaceError extends Error {
+	constructor(
+		message: string,
+		public readonly errors: Array<{ name: string; error: string }>,
+	) {
+		super(message);
+		this.name = "RaceError";
+	}
+}
+
+/**
+ * Branch was cancelled (used by race).
+ */
+export class CancelledError extends Error {
+	constructor() {
+		super("Branch cancelled");
+		this.name = "CancelledError";
+	}
+}
+
+/**
+ * Entry is currently being processed.
+ * Thrown when user forgets to await a step.
+ */
+export class EntryInProgressError extends Error {
+	constructor() {
+		super(
+			"Cannot start a new workflow entry while another is in progress. " +
+				"Did you forget to await the previous step/loop/sleep?",
+		);
+		this.name = "EntryInProgressError";
+	}
+}