@lostgradient/weft 0.2.0

package/dist/core/weft-error.js

@@ -0,0 +1,43 @@
+export class WeftError extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.code = code;
+    this.name = code;
+  }
+}
+const publicWeftErrorCodeMap = {
+  WorkflowAlreadyExistsError: !0,
+  BulkDeleteRequiresTerminalWorkflowsError: !0,
+  BulkOperationConfirmationError: !0,
+  WorkflowTypeNotRegisteredForRecoveryError: !0,
+  EngineCreateNameMismatchError: !0,
+  EngineDisposedError: !0,
+  WorkflowNotFoundError: !0,
+  WorkflowNotRegisteredError: !0,
+  ActivityResolutionError: !0,
+  PersistedDataIncompatibleError: !0,
+  WorkflowTimeoutError: !0,
+  HttpClientError: !0,
+  WorkerProtocolIncompatibleError: !0,
+  UpdateTimeoutError: !0,
+  UpdateValidationError: !0,
+  WorkflowTerminalError: !0,
+  WorkflowBuilderError: !0,
+  VersionMismatchError: !0,
+  EffectReplayConflictError: !0,
+  ReviewTimeoutError: !0,
+  AtomicStateConflictError: !0,
+  StandardSchemaValidationError: !0,
+  ActivityReconciliationCapabilityError: !0,
+  ActivityReconciliationConflictError: !0,
+  ActivityReconciliationIndeterminateError: !0,
+  AsyncActivityTokenNotFoundError: !0,
+  PayloadSizeExceededError: !0
+}, PUBLIC_WEFT_ERROR_CODES = new Set(Object.keys(publicWeftErrorCodeMap));
+export function isWeftError(value) {
+  return value instanceof WeftError;
+}
+export function isWeftErrorCode(value) {
+  return typeof value === "string" && PUBLIC_WEFT_ERROR_CODES.has(value);
+}

package/dist/core/worker-checkpoint-resume-state.d.ts

@@ -0,0 +1,11 @@
+import type { WorkerOutboundMessage } from './types.ts';
+export declare class WorkerCheckpointResumeState {
+    #private;
+    resetWorkflow(workflowId: string): void;
+    clear(): void;
+    recordResume(workflowId: string): void;
+    beginCheckpointHandling(message: WorkerOutboundMessage): number | null;
+    finishCheckpointHandling(workflowId: string, resumeVersionBeforeCheckpointHandling: number | null, workflowIsClosed: boolean): void;
+    wasResumedDuringCheckpointHandling(workflowId: string, resumeVersionBeforeCheckpointHandling: number | null): boolean;
+    forgetWorkflowIfClosed(workflowId: string, workflowIsClosed: boolean): void;
+}

package/dist/core/worker-checkpoint-resume-state.js

@@ -0,0 +1,40 @@
+export class WorkerCheckpointResumeState {
+  #resumeVersionsByWorkflowId = new Map;
+  #checkpointHandlerCountsByWorkflowId = new Map;
+  resetWorkflow(workflowId) {
+    this.#resumeVersionsByWorkflowId.delete(workflowId);
+    this.#checkpointHandlerCountsByWorkflowId.delete(workflowId);
+  }
+  clear() {
+    this.#resumeVersionsByWorkflowId.clear();
+    this.#checkpointHandlerCountsByWorkflowId.clear();
+  }
+  recordResume(workflowId) {
+    this.#resumeVersionsByWorkflowId.set(workflowId, (this.#resumeVersionsByWorkflowId.get(workflowId) ?? 0) + 1);
+  }
+  beginCheckpointHandling(message) {
+    if (message.type !== "checkpoint")
+      return null;
+    this.#checkpointHandlerCountsByWorkflowId.set(message.workflowId, (this.#checkpointHandlerCountsByWorkflowId.get(message.workflowId) ?? 0) + 1);
+    return this.#resumeVersionsByWorkflowId.get(message.workflowId) ?? 0;
+  }
+  finishCheckpointHandling(workflowId, resumeVersionBeforeCheckpointHandling, workflowIsClosed) {
+    if (resumeVersionBeforeCheckpointHandling === null)
+      return;
+    const remainingHandlerCount = (this.#checkpointHandlerCountsByWorkflowId.get(workflowId) ?? 1) - 1;
+    if (remainingHandlerCount > 0) {
+      this.#checkpointHandlerCountsByWorkflowId.set(workflowId, remainingHandlerCount);
+      return;
+    }
+    this.#checkpointHandlerCountsByWorkflowId.delete(workflowId);
+    this.forgetWorkflowIfClosed(workflowId, workflowIsClosed);
+  }
+  wasResumedDuringCheckpointHandling(workflowId, resumeVersionBeforeCheckpointHandling) {
+    return resumeVersionBeforeCheckpointHandling !== null && (this.#resumeVersionsByWorkflowId.get(workflowId) ?? 0) > resumeVersionBeforeCheckpointHandling;
+  }
+  forgetWorkflowIfClosed(workflowId, workflowIsClosed) {
+    if (!workflowIsClosed || this.#checkpointHandlerCountsByWorkflowId.has(workflowId))
+      return;
+    this.#resumeVersionsByWorkflowId.delete(workflowId);
+  }
+}

package/dist/core/worker-execution-dispatcher.d.ts

@@ -0,0 +1,42 @@
+import type { WorkerPool } from '../workers/pool.ts';
+import type { OperationOutcome, WorkerInboundMessage, WorkerOutboundMessage } from './types.ts';
+import { WorkerExecutionOwnership } from './worker-execution-ownership.ts';
+export interface WorkerExecutionDispatcherDependencies {
+    pool: WorkerPool;
+    ownership: WorkerExecutionOwnership;
+    isDisposed: () => boolean;
+    requireProtocolVersion: () => boolean;
+    validateHostToWorkerMessage: (workflowId: string, message: WorkerInboundMessage, worker?: Worker) => boolean;
+    attachWorkerListeners: (worker: Worker) => void;
+    detachWorkerListenersIfIdle: (worker: Worker) => void;
+    beginTurn: (worker: Worker, workflowId: string, turnId: number, kind: 'run' | 'resume') => void;
+    clearTurn: (worker: Worker) => void;
+    discardWorkerAndFailWorkflows: (worker: Worker, options: {
+        targetWorkflowId?: string;
+        targetCategory?: 'application' | 'timeout' | 'cancellation' | 'resource' | 'system';
+        targetError?: string;
+        skipTarget?: boolean;
+        otherCategory: 'application' | 'timeout' | 'cancellation' | 'resource' | 'system';
+        otherError: string;
+    }) => void;
+    emit: (message: WorkerOutboundMessage) => void;
+}
+export interface WorkerResumeParameters {
+    workflowId: string;
+    checkpoint: ArrayBuffer;
+    operationResult: OperationOutcome;
+}
+export declare class WorkerExecutionDispatcher {
+    #private;
+    constructor(dependencies: WorkerExecutionDispatcherDependencies);
+    acquireAndSend(workflowId: string, message: WorkerInboundMessage & {
+        type: 'run';
+    }): Promise<void>;
+    postResumeMessage(worker: Worker, parameters: WorkerResumeParameters, message: WorkerInboundMessage & {
+        type: 'resume';
+    }): void;
+    resumeParkedWorkflow(parameters: WorkerResumeParameters, parkedWorker: Worker, message: WorkerInboundMessage & {
+        type: 'resume';
+    }): Promise<void>;
+    cancelParkedWorkflow(workflowId: string, parkedWorker: Worker): Promise<void>;
+}

package/dist/core/worker-execution-dispatcher.js

@@ -0,0 +1,95 @@
+import { WorkerExecutionOwnership } from "./worker-execution-ownership.js";
+import { WORKER_PROTOCOL_VERSION } from "./worker-protocol.js";
+
+export class WorkerExecutionDispatcher {
+  #dependencies;
+  constructor(dependencies) {
+    this.#dependencies = dependencies;
+  }
+  async acquireAndSend(workflowId, message) {
+    try {
+      const worker = await this.#dependencies.pool.acquire();
+      this.#dependencies.ownership.setActive(workflowId, worker);
+      this.#dependencies.attachWorkerListeners(worker);
+      this.#sendActiveMessage(worker, workflowId, message, "run");
+    } catch (error) {
+      this.#dependencies.emit({
+        type: "failed",
+        workflowId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  postResumeMessage(worker, parameters, message) {
+    this.#sendActiveMessage(worker, parameters.workflowId, message, "resume");
+  }
+  async resumeParkedWorkflow(parameters, parkedWorker, message) {
+    try {
+      const worker = await this.#dependencies.pool.acquireSpecificWorker(parkedWorker);
+      if (this.#dependencies.isDisposed() || !this.#dependencies.ownership.activateParked(parameters.workflowId, worker)) {
+        this.#dependencies.pool.release(worker);
+        return;
+      }
+      this.#dependencies.attachWorkerListeners(worker);
+      this.postResumeMessage(worker, parameters, message);
+    } catch (error) {
+      if (this.#dependencies.isDisposed() || this.#dependencies.ownership.getParkedWorker(parameters.workflowId) !== parkedWorker)
+        return;
+      this.#dependencies.ownership.deleteParked(parameters.workflowId);
+      this.#dependencies.emit({
+        type: "failed",
+        workflowId: parameters.workflowId,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+  async cancelParkedWorkflow(workflowId, parkedWorker) {
+    try {
+      const worker = await this.#dependencies.pool.acquireSpecificWorker(parkedWorker), message = { type: "cancel", workflowId };
+      if (this.#dependencies.requireProtocolVersion())
+        message.protocolVersion = WORKER_PROTOCOL_VERSION;
+      worker.postMessage(message);
+      this.#dependencies.detachWorkerListenersIfIdle(worker);
+      this.#dependencies.pool.release(worker);
+    } catch {}
+  }
+  #sendActiveMessage(worker, workflowId, message, kind) {
+    if (!this.#dependencies.validateHostToWorkerMessage(workflowId, message, worker))
+      return;
+    try {
+      this.#dependencies.beginTurn(worker, workflowId, message.turnId ?? 0, kind);
+      worker.postMessage(message, [transferableCheckpointBuffer(message.checkpoint)]);
+    } catch (error) {
+      this.#handlePostMessageFailure(worker, workflowId, error, kind);
+    }
+  }
+  #handlePostMessageFailure(worker, workflowId, error, kind) {
+    this.#dependencies.clearTurn(worker);
+    if (kind === "resume") {
+      this.#dependencies.discardWorkerAndFailWorkflows(worker, {
+        targetWorkflowId: workflowId,
+        targetCategory: "system",
+        targetError: error instanceof Error ? error.message : String(error),
+        otherCategory: "system",
+        otherError: "Worker was discarded after resume postMessage failed"
+      });
+      return;
+    }
+    this.#dependencies.ownership.forgetWorkflow(workflowId);
+    this.#dependencies.detachWorkerListenersIfIdle(worker);
+    this.#dependencies.pool.release(worker);
+    this.#dependencies.emit({
+      type: "failed",
+      workflowId,
+      error: error instanceof Error ? error.message : String(error),
+      failureCategory: "system"
+    });
+  }
+}
+function transferableCheckpointBuffer(checkpoint) {
+  if (checkpoint instanceof ArrayBuffer)
+    return checkpoint;
+  if (checkpoint.buffer instanceof ArrayBuffer)
+    return checkpoint.buffer;
+  throw Error("Worker checkpoint must use an ArrayBuffer-backed view");
+}

package/dist/core/worker-execution-ownership.d.ts

@@ -0,0 +1,20 @@
+export declare class WorkerExecutionOwnership {
+    #private;
+    resetWorkflow(workflowId: string): void;
+    markCancelled(workflowId: string): void;
+    consumeCancelled(workflowId: string): boolean;
+    getActiveWorker(workflowId: string): Worker | undefined;
+    getParkedWorker(workflowId: string): Worker | undefined;
+    getTargetWorker(workflowId: string): Worker | undefined;
+    setActive(workflowId: string, worker: Worker): void;
+    releaseActive(workflowId: string): Worker | undefined;
+    parkActive(workflowId: string, worker: Worker): boolean;
+    activateParked(workflowId: string, worker: Worker): boolean;
+    deleteParked(workflowId: string): void;
+    isWorkflowClosed(workflowId: string): boolean;
+    activeWorkflowIds(): string[];
+    workflowIdsForWorker(worker: Worker): string[];
+    forgetWorkflow(workflowId: string): void;
+    clear(): void;
+    workerIsIdle(worker: Worker): boolean;
+}

package/dist/core/worker-execution-ownership.js

@@ -0,0 +1,91 @@
+export class WorkerExecutionOwnership {
+  #activeWorkersByWorkflowId = new Map;
+  #parkedWorkersByWorkflowId = new Map;
+  #activeWorkflowIdByWorker = new Map;
+  #cancelledWorkflowIds = new Set;
+  resetWorkflow(workflowId) {
+    this.#cancelledWorkflowIds.delete(workflowId);
+  }
+  markCancelled(workflowId) {
+    this.#cancelledWorkflowIds.add(workflowId);
+  }
+  consumeCancelled(workflowId) {
+    return this.#cancelledWorkflowIds.delete(workflowId);
+  }
+  getActiveWorker(workflowId) {
+    return this.#activeWorkersByWorkflowId.get(workflowId);
+  }
+  getParkedWorker(workflowId) {
+    return this.#parkedWorkersByWorkflowId.get(workflowId);
+  }
+  getTargetWorker(workflowId) {
+    return this.getActiveWorker(workflowId) ?? this.getParkedWorker(workflowId);
+  }
+  setActive(workflowId, worker) {
+    this.#activeWorkersByWorkflowId.set(workflowId, worker);
+    this.#activeWorkflowIdByWorker.set(worker, workflowId);
+  }
+  releaseActive(workflowId) {
+    const worker = this.#activeWorkersByWorkflowId.get(workflowId);
+    if (!worker)
+      return;
+    this.#activeWorkersByWorkflowId.delete(workflowId);
+    this.#activeWorkflowIdByWorker.delete(worker);
+    return worker;
+  }
+  parkActive(workflowId, worker) {
+    if (this.#activeWorkersByWorkflowId.get(workflowId) !== worker)
+      return !1;
+    this.#activeWorkersByWorkflowId.delete(workflowId);
+    this.#activeWorkflowIdByWorker.delete(worker);
+    this.#parkedWorkersByWorkflowId.set(workflowId, worker);
+    return !0;
+  }
+  activateParked(workflowId, worker) {
+    if (this.#parkedWorkersByWorkflowId.get(workflowId) !== worker)
+      return !1;
+    this.#parkedWorkersByWorkflowId.delete(workflowId);
+    this.setActive(workflowId, worker);
+    return !0;
+  }
+  deleteParked(workflowId) {
+    this.#parkedWorkersByWorkflowId.delete(workflowId);
+  }
+  isWorkflowClosed(workflowId) {
+    return !this.#activeWorkersByWorkflowId.has(workflowId) && !this.#parkedWorkersByWorkflowId.has(workflowId);
+  }
+  activeWorkflowIds() {
+    return [...this.#activeWorkersByWorkflowId.keys()];
+  }
+  workflowIdsForWorker(worker) {
+    const workflowIds = [], activeWorkflowId = this.#activeWorkflowIdByWorker.get(worker);
+    if (activeWorkflowId)
+      workflowIds.push(activeWorkflowId);
+    for (const [workflowId, parkedWorker] of this.#parkedWorkersByWorkflowId)
+      if (parkedWorker === worker)
+        workflowIds.push(workflowId);
+    return workflowIds;
+  }
+  forgetWorkflow(workflowId) {
+    const activeWorker = this.#activeWorkersByWorkflowId.get(workflowId);
+    if (activeWorker)
+      this.#activeWorkflowIdByWorker.delete(activeWorker);
+    this.#activeWorkersByWorkflowId.delete(workflowId);
+    this.#parkedWorkersByWorkflowId.delete(workflowId);
+    this.#cancelledWorkflowIds.delete(workflowId);
+  }
+  clear() {
+    this.#activeWorkersByWorkflowId.clear();
+    this.#parkedWorkersByWorkflowId.clear();
+    this.#activeWorkflowIdByWorker.clear();
+    this.#cancelledWorkflowIds.clear();
+  }
+  workerIsIdle(worker) {
+    if (this.#activeWorkflowIdByWorker.has(worker))
+      return !1;
+    for (const parkedWorker of this.#parkedWorkersByWorkflowId.values())
+      if (parkedWorker === worker)
+        return !1;
+    return !0;
+  }
+}

package/dist/core/worker-execution-strategy-options.d.ts

@@ -0,0 +1,7 @@
+export interface WorkerExecutionStrategyOptions {
+    broadcastEvents?: boolean;
+    workflowTurnTimeoutMs?: number;
+    maxProtocolMessageBytes?: number;
+    requireProtocolVersion?: boolean;
+    discardOnCancel?: boolean;
+}

package/dist/core/worker-execution-strategy.d.ts

@@ -0,0 +1,29 @@
+import type { WorkerPool } from '../workers/pool.ts';
+import type { ExecutionStrategy } from './execution-strategy.ts';
+import type { OperationOutcome, WorkerOutboundMessage } from './types.ts';
+import type { WorkerExecutionStrategyOptions } from './worker-execution-strategy-options.ts';
+export declare class WorkerExecutionStrategy implements ExecutionStrategy {
+    #private;
+    constructor(pool: WorkerPool, options?: WorkerExecutionStrategyOptions);
+    onMessage(handler: (message: WorkerOutboundMessage) => void | Promise<void>): void;
+    startWorkflow(parameters: {
+        workflowId: string;
+        workflowType: string;
+        input: unknown;
+        checkpoint: ArrayBuffer;
+        nestingDepth?: number;
+        executionStateOwnerId?: string;
+        startedAt?: number;
+        sleepReferenceTime?: number;
+        deadline?: number;
+        headers?: [string, string][];
+    }): void;
+    resumeWorkflow(parameters: {
+        workflowId: string;
+        checkpoint: ArrayBuffer;
+        operationResult: OperationOutcome;
+    }): void;
+    cancelWorkflow(workflowId: string): void;
+    [Symbol.dispose](): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}