@temelj/workflow 0.0.0-alpha.1

package/dist/worker.mjs

@@ -0,0 +1,427 @@
+import { WorkflowStateError } from "./errors/base.mjs";
+import { WorkflowRunNotFoundError } from "./errors/run.mjs";
+import { createDefaultWorkerId, isPositiveSafeInteger, resolvePositiveSafeIntegerOption } from "./utility.mjs";
+import { WorkflowCapabilityError } from "./errors/capability.mjs";
+import { durationBetween } from "./temporal.mjs";
+import { MAX_TIMER_DELAY, nonNegativeTimerDelay, positiveTimerDelay } from "./timer.mjs";
+import { resolveMissingImplementationRetryConfig } from "./engine/retry.mjs";
+import { patchRunIfCurrent, transitionRunToFailed, transitionRunToMissingImplementationWait, wakeParentRunForTerminalChild, wakeParentRunForWaitingChild } from "./engine/state.mjs";
+import { requireWorkflowStoreCapabilities } from "./store/capabilities.mjs";
+import { DEFAULT_MISSING_IMPLEMENTATION_RETRY_INTERVAL, makeMissingImplementationDeadlineErrorRecord, makeMissingImplementationNotFoundErrorRecord, missingImplementationRetryDelay, toWorkflowWorkerErrorRecord } from "./worker/error.mjs";
+//#region src/worker.ts
+const DEFAULT_WORKER_LEASE_DURATION = Temporal.Duration.from({ seconds: 30 });
+const DEFAULT_WORKER_POLL_INTERVAL = Temporal.Duration.from({ milliseconds: 100 });
+const DEFAULT_WORKER_STOP_DRAIN_TIMEOUT = Temporal.Duration.from({ seconds: 30 });
+/** Storage-backed workflow worker implementation. */
+var WorkflowWorker = class {
+	#engine;
+	#store;
+	#registry;
+	#workerId;
+	#leaseDuration;
+	#heartbeatInterval;
+	#stopDrainTimeout;
+	#defaultPollInterval;
+	#missingImplementationRetry;
+	#now;
+	#stopRequested = false;
+	#pollWakeups = /* @__PURE__ */ new Set();
+	#activeExecutionAborts = /* @__PURE__ */ new Set();
+	#activeExecutions = /* @__PURE__ */ new Set();
+	#activeExecutionRuns = /* @__PURE__ */ new Map();
+	constructor(options) {
+		const store = options.engine.store;
+		requireWorkflowStoreCapabilities(store, {
+			conditionalRunClaims: "workflow worker conditional run claims",
+			conditionalRunUpdates: "workflow worker conditional run updates",
+			conditionalRunLeaseExtensions: "workflow worker conditional lease extensions",
+			conditionalRunLeaseReleases: "workflow worker conditional lease releases",
+			conditionalEventAppends: "workflow worker conditional event appends",
+			reconcilesStepAttemptsFromEvents: "workflow worker step-attempt reconciliation"
+		});
+		this.#engine = options.engine;
+		this.#store = store;
+		this.#registry = options.registry;
+		this.#workerId = options.workerId ?? createDefaultWorkerId();
+		this.#leaseDuration = options.leaseDuration ?? DEFAULT_WORKER_LEASE_DURATION;
+		const resolvedLeaseDelay = positiveTimerDelay(this.#leaseDuration, "Workflow worker leaseDuration");
+		this.#heartbeatInterval = options.heartbeatInterval === void 0 ? Math.min(MAX_TIMER_DELAY, Math.max(1, Math.floor(resolvedLeaseDelay.clampedDelay / 2))) : nonNegativeTimerDelay(options.heartbeatInterval, "Workflow worker heartbeatInterval").clampedDelay;
+		this.#stopDrainTimeout = nonNegativeTimerDelay(options.stopDrainTimeout ?? DEFAULT_WORKER_STOP_DRAIN_TIMEOUT, "Workflow worker stopDrainTimeout").clampedDelay;
+		this.#defaultPollInterval = nonNegativeTimerDelay(options.pollInterval ?? DEFAULT_WORKER_POLL_INTERVAL, "Workflow worker pollInterval").clampedDelay;
+		this.#missingImplementationRetry = resolveMissingImplementationRetryConfig(options.missingImplementationRetry, {
+			initialInterval: DEFAULT_MISSING_IMPLEMENTATION_RETRY_INTERVAL,
+			backoffCoefficient: 2,
+			maximumAttempts: 0
+		}, "Workflow missing implementation retry options");
+		this.#now = options.now ?? Temporal.Now.instant;
+	}
+	async processRun(runId) {
+		this.#stopRequested = false;
+		const run = await this.#claimRun({ runId });
+		if (run === void 0) WorkflowStateError.runNotClaimable(runId);
+		if (this.#stopRequested) {
+			await this.#releaseLease(run.id, run.attempts);
+			WorkflowStateError.workerStoppedBeforeRun(runId);
+		}
+		return await this.#executeClaimedRun(run);
+	}
+	async processNextRun(options) {
+		this.#stopRequested = false;
+		return await this.#processNextRun(options);
+	}
+	async extendLease(runId, options) {
+		return await this.#extendLease(runId, options?.attempts);
+	}
+	async releaseLease(runId, options) {
+		return await this.#releaseLease(runId, options?.attempts);
+	}
+	async run(options) {
+		this.#stopRequested = false;
+		let processedRuns = 0;
+		const activeRuns = /* @__PURE__ */ new Set();
+		const pollInterval = options?.pollInterval === void 0 ? this.#defaultPollInterval : nonNegativeTimerDelay(options.pollInterval, "Workflow worker pollInterval").clampedDelay;
+		const maxRuns = resolvePositiveSafeIntegerOption(options?.maxRuns, "Workflow worker maxRuns");
+		const concurrency = resolvePositiveSafeIntegerOption(options?.concurrency, "Workflow worker concurrency") ?? 1;
+		const tickSchedules = options?.tickSchedules ?? false;
+		while (!this.#stopRequested && options?.signal?.aborted !== true) {
+			if (maxRuns !== void 0 && processedRuns >= maxRuns) break;
+			if (tickSchedules) await this.#tickDueSchedules();
+			while (!this.#stopRequested && activeRuns.size < concurrency && (maxRuns === void 0 || processedRuns + activeRuns.size < maxRuns)) {
+				let execution;
+				execution = this.#processNextRun(options ?? {}, options?.signal).then((result) => ({
+					execution,
+					result
+				}), (error) => ({
+					error,
+					execution
+				}));
+				activeRuns.add(execution);
+			}
+			if (activeRuns.size > 0) {
+				const settled = await Promise.race(activeRuns);
+				activeRuns.delete(settled.execution);
+				if (settled.error !== void 0) {
+					await this.#abortActiveWorkerExecutions(activeRuns);
+					throw settled.error;
+				}
+				if (settled.result !== void 0) {
+					processedRuns++;
+					continue;
+				}
+				if (activeRuns.size > 0) {
+					await this.#sleep(await this.#idlePollDelay(options ?? {}, pollInterval, tickSchedules), options?.signal);
+					continue;
+				}
+			}
+			if (this.#stopRequested || options?.signal?.aborted) break;
+			await this.#sleep(await this.#idlePollDelay(options ?? {}, pollInterval, tickSchedules), options?.signal);
+		}
+		if (activeRuns.size > 0) for (const settled of await Promise.all(activeRuns)) {
+			activeRuns.delete(settled.execution);
+			if (settled.error !== void 0) throw settled.error;
+			if (settled.result !== void 0) processedRuns++;
+		}
+		return { processedRuns };
+	}
+	async stop() {
+		this.#stopRequested = true;
+		const activeExecutions = [...this.#activeExecutions];
+		const releaseRuns = [...this.#activeExecutionRuns];
+		for (const controller of this.#activeExecutionAborts) controller.abort();
+		for (const wakeup of this.#pollWakeups) wakeup();
+		if (!await this.#waitForActiveExecutions(activeExecutions)) return;
+		await Promise.all(releaseRuns.map(async ([runId, attempts]) => await this.#releaseLease(runId, attempts)));
+	}
+	async #waitForActiveExecutions(activeExecutions) {
+		if (activeExecutions.length === 0) return true;
+		if (this.#stopDrainTimeout === 0) return false;
+		let timer;
+		const timeout = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				resolve(false);
+			}, this.#stopDrainTimeout);
+		});
+		const drained = Promise.allSettled(activeExecutions).then(() => true);
+		const result = await Promise.race([drained, timeout]);
+		if (timer !== void 0) clearTimeout(timer);
+		return result;
+	}
+	async #abortActiveWorkerExecutions(activeRuns) {
+		for (const controller of this.#activeExecutionAborts) controller.abort();
+		await Promise.all(activeRuns);
+	}
+	async #claimRun(options) {
+		const timestamp = this.#now();
+		const run = await this.#store.claimRun({
+			...options,
+			workerId: this.#workerId,
+			leaseDuration: this.#leaseDuration,
+			now: timestamp
+		});
+		if (run === void 0 && options?.runId !== void 0) this.#observeWorkerOperation({
+			operation: "claim",
+			status: "failure",
+			timestamp,
+			runId: options.runId
+		});
+		return run;
+	}
+	async #processNextRun(options, signal) {
+		const timestamp = this.#now();
+		const run = await this.#claimRun(options);
+		this.#observeWorkerOperation({
+			operation: "poll",
+			status: run === void 0 ? "empty" : "claimed",
+			timestamp,
+			...run === void 0 ? {} : {
+				runId: run.id,
+				run
+			}
+		});
+		if (run === void 0) return;
+		if (this.#stopRequested || signal?.aborted === true) {
+			await this.#releaseLease(run.id, run.attempts);
+			return;
+		}
+		return await this.#executeClaimedRun(run, signal);
+	}
+	async #tickDueSchedules() {
+		if (this.#engine.tickSchedules === void 0) WorkflowCapabilityError.unsupported("workflow schedule ticking");
+		await this.#engine.tickSchedules({ now: this.#now() });
+	}
+	async #executeClaimedRun(run, signal) {
+		const definition = this.#registry.getByName(run.workflowName, run.workflowVersion);
+		if (definition === void 0) return await this.#rescheduleMissingImplementation(run);
+		const attempts = run.attempts !== void 0 && isPositiveSafeInteger(run.attempts) ? run.attempts : void 0;
+		return await this.#withHeartbeat(run.id, attempts, signal, async (executionSignal) => await this.#engine.resumeWorkflow(definition, run.id, { signal: executionSignal }));
+	}
+	async #rescheduleMissingImplementation(run) {
+		const timestamp = this.#now();
+		const retryAttempt = run.attempts ?? (run.retryAttempt ?? 0) + 1;
+		const errorRecord = makeMissingImplementationNotFoundErrorRecord(run);
+		const deadlineAt = run.deadlineAt;
+		if (deadlineAt !== void 0 && Temporal.Instant.compare(deadlineAt, timestamp) <= 0) return await this.#failMissingImplementationForDeadline(run, deadlineAt, timestamp);
+		if (this.#missingImplementationRetry.maximumAttempts > 0 && retryAttempt >= this.#missingImplementationRetry.maximumAttempts) return await this.#failMissingImplementationRun(run, errorRecord, timestamp);
+		let availableAt;
+		try {
+			availableAt = timestamp.add(Temporal.Duration.from({ milliseconds: nonNegativeTimerDelay(missingImplementationRetryDelay(this.#missingImplementationRetry, retryAttempt), "Workflow missing implementation retry delay").clampedDelay }));
+		} catch (retryError) {
+			return await this.#failMissingImplementationRun(run, toWorkflowWorkerErrorRecord(retryError), timestamp);
+		}
+		if (deadlineAt !== void 0 && Temporal.Instant.compare(deadlineAt, availableAt) <= 0) return await this.#failMissingImplementationForDeadline(run, deadlineAt, timestamp);
+		const waitingRun = await patchRunIfCurrent(this.#store, run, transitionRunToMissingImplementationWait(run, errorRecord, timestamp, availableAt, retryAttempt));
+		if (waitingRun === void 0) return await this.#readRunExecutionResult(run.id);
+		await wakeParentRunForWaitingChild(this.#store, waitingRun, availableAt);
+		return {
+			kind: "waiting",
+			run: waitingRun,
+			availableAt
+		};
+	}
+	async #failMissingImplementationRun(run, errorRecord, timestamp) {
+		return await this.#failClaimedMissingImplementationRun(run, errorRecord, timestamp, "failed");
+	}
+	async #failMissingImplementationForDeadline(run, deadlineAt, timestamp) {
+		return await this.#failClaimedMissingImplementationRun(run, makeMissingImplementationDeadlineErrorRecord(run, deadlineAt), timestamp, "deadline", deadlineAt);
+	}
+	async #failClaimedMissingImplementationRun(run, errorRecord, timestamp, reason, deadlineAt) {
+		const failedRun = await patchRunIfCurrent(this.#store, run, transitionRunToFailed(run, errorRecord, timestamp, reason, deadlineAt));
+		if (failedRun === void 0) return await this.#readRunExecutionResult(run.id);
+		if (await this.#store.appendEventIfRunCurrent(failedRun, {
+			kind: "workflow_failed",
+			timestamp
+		}) === void 0) return await this.#readRunExecutionResult(run.id);
+		await wakeParentRunForTerminalChild(this.#store, failedRun, timestamp);
+		return {
+			kind: "failed",
+			run: failedRun,
+			error: errorRecord
+		};
+	}
+	async #readRunExecutionResult(runId) {
+		const current = await this.#engine.getRun(runId);
+		if (current === void 0) WorkflowRunNotFoundError.notFound(runId);
+		if (current.status === "completed") return {
+			kind: "completed",
+			run: current,
+			output: current.output
+		};
+		if (current.status === "failed") return {
+			kind: "failed",
+			run: current,
+			error: current.error ?? {
+				name: "WorkflowError",
+				message: `Workflow run failed: ${runId}`
+			}
+		};
+		if (current.status === "canceled") return {
+			kind: "failed",
+			run: current,
+			error: current.error ?? {
+				name: "WorkflowRunCanceledError",
+				message: `Workflow run was canceled: ${runId}`
+			}
+		};
+		return {
+			kind: "waiting",
+			run: current,
+			availableAt: current.availableAt ?? this.#now()
+		};
+	}
+	async #extendLease(runId, attempts) {
+		const timestamp = this.#now();
+		const run = await this.#store.extendRunLease({
+			runId,
+			workerId: this.#workerId,
+			attempts,
+			leaseDuration: this.#leaseDuration,
+			now: timestamp
+		});
+		this.#observeWorkerOperation({
+			operation: "lease_extension",
+			status: run === void 0 ? "failure" : "success",
+			timestamp,
+			runId,
+			...run === void 0 ? {} : { run }
+		});
+		return run;
+	}
+	async #releaseLease(runId, attempts) {
+		const timestamp = this.#now();
+		const run = await this.#store.releaseRunLease({
+			runId,
+			workerId: this.#workerId,
+			attempts,
+			now: timestamp
+		});
+		this.#observeWorkerOperation({
+			operation: "lease_release",
+			status: run === void 0 ? "failure" : "success",
+			timestamp,
+			runId,
+			...run === void 0 ? {} : { run }
+		});
+		return run;
+	}
+	async #withHeartbeat(runId, attempts, signal, callback) {
+		const executionAbort = new AbortController();
+		this.#activeExecutionAborts.add(executionAbort);
+		if (attempts !== void 0) this.#activeExecutionRuns.set(runId, attempts);
+		let timer;
+		let heartbeatPending = false;
+		let heartbeat;
+		let heartbeatError;
+		let abortRelease;
+		const abortExecution = () => {
+			executionAbort.abort();
+			abortRelease = this.#releaseLease(runId, attempts);
+		};
+		if (this.#stopRequested || signal?.aborted === true) executionAbort.abort();
+		else signal?.addEventListener("abort", abortExecution, { once: true });
+		if (this.#heartbeatInterval > 0) timer = setInterval(() => {
+			if (heartbeatPending || executionAbort.signal.aborted) return;
+			heartbeatPending = true;
+			heartbeat = this.#extendLease(runId, attempts).then((run) => {
+				if (run === void 0) {
+					this.#observeWorkerOperation({
+						operation: "heartbeat",
+						status: "failure",
+						timestamp: this.#now(),
+						runId
+					});
+					executionAbort.abort();
+				}
+			}).catch((error) => {
+				executionAbort.abort();
+				heartbeatError ??= error;
+				this.#observeWorkerOperation({
+					operation: "heartbeat",
+					status: "failure",
+					timestamp: this.#now(),
+					runId,
+					error
+				});
+			}).finally(() => {
+				heartbeatPending = false;
+			});
+		}, this.#heartbeatInterval);
+		const execution = (async () => await callback(executionAbort.signal))();
+		this.#activeExecutions.add(execution);
+		let executionOutcome;
+		try {
+			executionOutcome = {
+				status: "fulfilled",
+				value: await execution
+			};
+		} catch (error) {
+			executionOutcome = {
+				status: "rejected",
+				reason: error
+			};
+		} finally {
+			if (timer !== void 0) clearInterval(timer);
+			this.#activeExecutions.delete(execution);
+			this.#activeExecutionAborts.delete(executionAbort);
+			this.#activeExecutionRuns.delete(runId);
+			signal?.removeEventListener("abort", abortExecution);
+			await heartbeat;
+			await abortRelease;
+		}
+		if (heartbeatError !== void 0) throw heartbeatError;
+		if (executionOutcome.status === "rejected") throw executionOutcome.reason;
+		return executionOutcome.value;
+	}
+	#observeWorkerOperation(event) {
+		try {
+			this.#engine.observeWorkerOperation?.({
+				workerId: this.#workerId,
+				...event
+			});
+		} catch {
+			return;
+		}
+	}
+	async #sleep(duration, signal) {
+		if (duration <= 0 || this.#stopRequested || signal?.aborted === true) {
+			await Promise.resolve();
+			return;
+		}
+		await new Promise((resolve) => {
+			let timer;
+			const finish = () => {
+				if (timer !== void 0) clearTimeout(timer);
+				this.#pollWakeups.delete(finish);
+				signal?.removeEventListener("abort", finish);
+				resolve();
+			};
+			this.#pollWakeups.add(finish);
+			signal?.addEventListener("abort", finish, { once: true });
+			timer = setTimeout(finish, duration);
+		});
+	}
+	async #idlePollDelay(options, pollInterval, tickSchedules) {
+		if (pollInterval <= 0 || this.#engine.getRunSummary === void 0) return pollInterval;
+		const timestamp = this.#now();
+		const summaryWakeAt = earliestSummaryWakeAt(await this.#engine.getRunSummary(options), timestamp);
+		const scheduleWakeAt = tickSchedules ? await this.#nextScheduleWakeAt() : void 0;
+		const nextWakeAt = summaryWakeAt === void 0 ? scheduleWakeAt : scheduleWakeAt === void 0 || Temporal.Instant.compare(summaryWakeAt, scheduleWakeAt) <= 0 ? summaryWakeAt : scheduleWakeAt;
+		if (nextWakeAt === void 0) return pollInterval;
+		return Math.min(pollInterval, nonNegativeTimerDelay(durationBetween(timestamp, nextWakeAt), "Workflow idle poll delay").clampedDelay);
+	}
+	async #nextScheduleWakeAt() {
+		if (this.#engine.listSchedules === void 0) return;
+		return (await this.#engine.listSchedules({
+			status: "active",
+			limit: 1
+		}))[0]?.nextFireAt;
+	}
+};
+function earliestSummaryWakeAt(summary, timestamp) {
+	if (summary.lease.expired > 0) return timestamp;
+	const nextAt = summary.nextAvailableAt === void 0 ? summary.retry.nextRetryAt : summary.retry.nextRetryAt === void 0 || Temporal.Instant.compare(summary.nextAvailableAt, summary.retry.nextRetryAt) <= 0 ? summary.nextAvailableAt : summary.retry.nextRetryAt;
+	if (nextAt === void 0) return summary.lease.nextExpiresAt;
+	if (summary.lease.nextExpiresAt === void 0) return nextAt;
+	return Temporal.Instant.compare(summary.lease.nextExpiresAt, nextAt) < 0 ? summary.lease.nextExpiresAt : nextAt;
+}
+//#endregion
+export { WorkflowWorker };

package/package.json

@@ -0,0 +1,144 @@
+{
+  "name": "@temelj/workflow",
+  "version": "0.0.0-alpha.1",
+  "description": "Durable, vendor-agnostic, extendible workflows.",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/tinrab/temelj"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/mod.mjs",
+  "types": "./dist/mod.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/mod.d.mts",
+      "import": "./dist/mod.mjs"
+    },
+    "./engine": {
+      "types": "./dist/engine/mod.d.mts",
+      "import": "./dist/engine/mod.mjs"
+    },
+    "./esbuild": {
+      "types": "./dist/esbuild.d.mts",
+      "import": "./dist/esbuild.mjs"
+    },
+    "./events": {
+      "types": "./dist/events/mod.d.mts",
+      "import": "./dist/events/mod.mjs"
+    },
+    "./inspection": {
+      "types": "./dist/inspection/mod.d.mts",
+      "import": "./dist/inspection/mod.mjs"
+    },
+    "./otel": {
+      "types": "./dist/otel.d.mts",
+      "import": "./dist/otel.mjs"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.mts",
+      "import": "./dist/registry.mjs"
+    },
+    "./rolldown": {
+      "types": "./dist/rolldown.d.mts",
+      "import": "./dist/rolldown.mjs"
+    },
+    "./rollup": {
+      "types": "./dist/rollup.d.mts",
+      "import": "./dist/rollup.mjs"
+    },
+    "./rspack": {
+      "types": "./dist/rspack.d.mts",
+      "import": "./dist/rspack.mjs"
+    },
+    "./telemetry": {
+      "types": "./dist/telemetry.d.mts",
+      "import": "./dist/telemetry.mjs"
+    },
+    "./store": {
+      "types": "./dist/store/mod.d.mts",
+      "import": "./dist/store/mod.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs"
+    },
+    "./webpack": {
+      "types": "./dist/webpack.d.mts",
+      "import": "./dist/webpack.mjs"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.mts",
+      "import": "./dist/worker.mjs"
+    }
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "oxc-parser": "0.141.0",
+    "unplugin": "^3.3.0",
+    "zod": "^4.4.3",
+    "@temelj/event": "0.1.0",
+    "@temelj/standard-schema": "0.1.0",
+    "@temelj/storage": "0.4.0",
+    "@temelj/string": "0.14.0",
+    "@temelj/value": "0.14.0",
+    "@temelj/log": "0.1.0"
+  },
+  "devDependencies": {
+    "@opentelemetry/sdk-metrics": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@rspack/core": "^2.1.5",
+    "@types/node": "26.1.1",
+    "esbuild": "^0.28.1",
+    "rolldown": "^1.2.0",
+    "rollup": "^4.62.2",
+    "shx": "^0.4.0",
+    "tsdown": "^0.22.14",
+    "typedoc": "^0.28.20",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10",
+    "webpack": "^5.109.0"
+  },
+  "peerDependencies": {
+    "@rspack/core": "^2.0.0",
+    "esbuild": "^0.28.0",
+    "rolldown": "^1.0.0",
+    "rollup": "^4.0.0",
+    "typescript": "^6.0.0",
+    "vite": "^8.0.0",
+    "webpack": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@rspack/core": {
+      "optional": true
+    },
+    "esbuild": {
+      "optional": true
+    },
+    "rolldown": {
+      "optional": true
+    },
+    "rollup": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "webpack": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "shx rm -rf dist",
+    "docs": "shx rm -rf docs && typedoc"
+  }
+}