@temelj/workflow 0.0.0-alpha.1

package/dist/engine/task.mjs

@@ -0,0 +1,207 @@
+import { WorkflowDurationError, WorkflowNonRetryableError } from "../errors/failures.mjs";
+import { isAbortError, safeDuration } from "../utility.mjs";
+import { WorkflowStepExecutionError, WorkflowStepRetryLimitError, WorkflowStepTimeoutError } from "../errors/step.mjs";
+import "../errors/mod.mjs";
+import { WORKFLOW_ATTRIBUTES, withStepTelemetry } from "../telemetry.mjs";
+import { serializeError, toOptionalPersistedValue } from "./serialization.mjs";
+import { nextRetryAt, resolveWorkflowRetryConfig, retryClassificationRetryAt } from "./retry.mjs";
+import { WorkflowSuspended } from "./state.mjs";
+import { resolveWorkflowCommandIdentityFromCandidates } from "./command-identity.mjs";
+import { appendDurableStepStartedEvent, appendDurableStepTerminalEvent } from "./durable-command.mjs";
+import { isRunStepTerminalForStartedAttempt, recordedStepCompletionTimestamp, requireRecordedDurableStepStarted, requireRunStepReplayTimeoutMatches, sleepUntil } from "./replay.mjs";
+//#region src/engine/task.ts
+function createWorkflowStepTaskApi(environment, executionSignal) {
+	const { runId, history, now, limits, executionOwner, telemetry } = environment;
+	const run = async (config, callback) => {
+		const identity = resolveWorkflowCommandIdentityFromCandidates(history, "run", [config.commandId, config.name], "Workflow step name or commandId");
+		const timeout = config.timeout === void 0 ? void 0 : (() => {
+			const value = safeDuration(config.timeout.total({ unit: "millisecond" }), "Workflow step timeout");
+			if (value <= 0) WorkflowDurationError.stepTimeoutPositive();
+			return value;
+		})();
+		const started = history.startedStep(identity.id);
+		const completed = history.completedStep(identity.id);
+		if (completed !== void 0 && (started === void 0 || isRunStepTerminalForStartedAttempt(completed, started))) {
+			requireRecordedDurableStepStarted(identity, history.hasStartedEventBeforeTerminalEvent(completed));
+			requireRunStepReplayTimeoutMatches(identity, started, config);
+			recordedStepCompletionTimestamp(identity, completed.timestamp);
+			return completed.result;
+		}
+		if (history.unstartedFailedStep(identity.id) !== void 0) requireRecordedDurableStepStarted(identity, false);
+		const retry = resolveWorkflowRetryConfig(config.retry, {
+			maximumAttempts: 10,
+			backoffCoefficient: 2
+		}, "Workflow step retry");
+		let attempt = history.nextStepAttempt(identity.id);
+		while (retry.maximumAttempts === 0 || attempt <= retry.maximumAttempts) {
+			const startedAt = now();
+			const timestamp = startedAt;
+			const timeoutAt = timeout === void 0 ? void 0 : startedAt.add(Temporal.Duration.from({ milliseconds: timeout }));
+			await appendDurableStepStartedEvent(environment, {
+				kind: "step_started",
+				timestamp,
+				stepId: identity.id,
+				stepName: identity.name,
+				count: identity.count,
+				attempt,
+				...timeoutAt === void 0 ? {} : { timeoutAt }
+			});
+			try {
+				const telemetryContext = {
+					run: executionOwner,
+					step: {
+						id: identity.id,
+						name: identity.name,
+						count: identity.count,
+						kind: "run"
+					},
+					attempt,
+					retry,
+					...timeoutAt === void 0 ? {} : { timeoutAt }
+				};
+				const result = await withStepTelemetry(telemetry, telemetryContext, async () => {
+					return await runStepCallbackWithTimeout(callback, createStepContext(identity, attempt, retry, executionSignal, environment.logger.child({
+						[WORKFLOW_ATTRIBUTES.stepId]: identity.id,
+						[WORKFLOW_ATTRIBUTES.stepName]: identity.name,
+						[WORKFLOW_ATTRIBUTES.stepKind]: identity.kind,
+						[WORKFLOW_ATTRIBUTES.stepAttempt]: attempt,
+						[WORKFLOW_ATTRIBUTES.replay]: false
+					})), {
+						runId,
+						stepId: identity.id,
+						stepName: identity.name,
+						attempt,
+						timeoutAt,
+						timeout
+					});
+				});
+				try {
+					telemetry?.recordStepExecution?.(telemetryContext);
+				} catch {}
+				const persistedResult = toOptionalPersistedValue(result, "step result", limits);
+				await appendDurableStepTerminalEvent(environment, {
+					kind: "step_completed",
+					timestamp: now(),
+					stepId: identity.id,
+					stepName: identity.name,
+					attempt,
+					...persistedResult === void 0 ? {} : { result: persistedResult }
+				});
+				return result;
+			} catch (error) {
+				if (executionSignal.aborted && isAbortError(error)) throw error;
+				try {
+					telemetry?.recordStepExecution?.({
+						run: executionOwner,
+						step: {
+							id: identity.id,
+							name: identity.name,
+							count: identity.count,
+							kind: "run"
+						},
+						attempt,
+						retry,
+						...timeoutAt === void 0 ? {} : { timeoutAt },
+						error
+					});
+				} catch {}
+				const failedAt = now();
+				await appendDurableStepTerminalEvent(environment, {
+					kind: "step_failed",
+					timestamp: failedAt,
+					stepId: identity.id,
+					stepName: identity.name,
+					attempt,
+					error: serializeError(error)
+				});
+				if (error instanceof WorkflowNonRetryableError || retry.maximumAttempts !== 0 && attempt >= retry.maximumAttempts) WorkflowStepExecutionError.failed({
+					stepId: identity.id,
+					stepName: identity.name,
+					attempt,
+					cause: error
+				});
+				const retryAt = retryClassificationRetryAt(failedAt, error, "Workflow step retry classification") ?? nextRetryAt(failedAt, retry, attempt, "Workflow step retry delay");
+				if (retryAt !== void 0) WorkflowSuspended.forStepRetry(retryAt, identity, attempt + 1);
+				attempt++;
+			}
+		}
+		WorkflowStepExecutionError.failed({
+			stepId: identity.id,
+			stepName: identity.name,
+			attempt,
+			cause: WorkflowStepRetryLimitError.create({
+				stepId: identity.id,
+				stepName: identity.name,
+				attempt
+			})
+		});
+	};
+	return {
+		run,
+		async call(definition, ...args) {
+			return await run(definition.config, async (context) => {
+				return await definition.handler(...args, context);
+			});
+		},
+		async sleep(commandId, duration) {
+			const resolvedDuration = duration.total({ unit: "millisecond" });
+			safeDuration(resolvedDuration, "Workflow sleep duration");
+			await sleepUntil(environment, commandId, now().add(Temporal.Duration.from({ milliseconds: resolvedDuration })), { duration });
+		},
+		async sleepUntil(commandId, timestamp) {
+			await sleepUntil(environment, commandId, timestamp, {});
+		}
+	};
+}
+function createStepContext(identity, attempt, config, signal, log) {
+	return new WorkflowStepContext(identity, attempt, config, signal, log);
+}
+var WorkflowStepContext = class {
+	step;
+	attempt;
+	config;
+	signal;
+	log;
+	constructor(step, attempt, config, signal, log) {
+		this.step = step;
+		this.attempt = attempt;
+		this.config = config;
+		this.signal = signal;
+		this.log = log;
+	}
+};
+async function runStepCallbackWithTimeout(callback, context, timeout) {
+	if (timeout.timeoutAt === void 0 || timeout.timeout === void 0) return await callback(context);
+	const timeoutAt = timeout.timeoutAt;
+	const timeoutAbort = new AbortController();
+	const abortFromParent = () => {
+		timeoutAbort.abort(context.signal.reason);
+	};
+	if (context.signal.aborted) timeoutAbort.abort(context.signal.reason);
+	else context.signal.addEventListener("abort", abortFromParent, { once: true });
+	let timeoutHandle;
+	const timeoutPromise = new Promise((_resolve, reject) => {
+		timeoutHandle = setTimeout(() => {
+			const error = WorkflowStepTimeoutError.create({
+				runId: timeout.runId,
+				stepId: timeout.stepId,
+				stepName: timeout.stepName,
+				attempt: timeout.attempt,
+				timeoutAt
+			});
+			timeoutAbort.abort(error);
+			reject(error);
+		}, timeout.timeout);
+	});
+	try {
+		return await Promise.race([callback({
+			...context,
+			signal: timeoutAbort.signal
+		}), timeoutPromise]);
+	} finally {
+		if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+		context.signal.removeEventListener("abort", abortFromParent);
+	}
+}
+//#endregion
+export { createWorkflowStepTaskApi };

package/dist/errors/base.d.mts

@@ -0,0 +1,99 @@
+import { WorkflowErrorCode } from "../types/error-code.mjs";
+import { RunId } from "../types/run-id.mjs";
+import { StepId } from "../types/step-id.mjs";
+import "../types/step.mjs";
+import { WorkflowTerminalRunStatus } from "../types/run.mjs";
+import { WorkflowErrorDetails, WorkflowErrorOptions } from "../types/error.mjs";
+import { EventKind } from "../types/events.mjs";
+//#region src/errors/base.d.ts
+/** Base error for workflow failures that carry optional structured details. */
+declare class WorkflowError extends Error {
+  readonly code: WorkflowErrorCode;
+  readonly cause: unknown;
+  readonly details: WorkflowErrorDetails | undefined;
+  constructor(message: string, options?: WorkflowErrorOptions, context?: Function);
+  static fromMessage(this: void, message: string, options?: WorkflowErrorOptions): WorkflowError;
+}
+/** Error thrown for options failures. */
+declare class WorkflowOptionsError extends WorkflowError {
+  constructor(message: string, context?: Function, options?: WorkflowErrorOptions);
+  static create(this: void, message: string): WorkflowOptionsError;
+  static object(this: void, label: string): never;
+  static array(this: void, label: string): never;
+  static function(this: void, label: string): never;
+  static string(this: void, label: string): never;
+  static nonEmpty(this: void, label: string): never;
+  static nonBlank(this: void, label: string): never;
+  static number(this: void, label: string): never;
+  static boolean(this: void, label: string): never;
+  static required(this: void, label: string): never;
+  static positiveSafeInteger(this: void, label: string): never;
+  static nonNegativeSafeInteger(this: void, label: string): never;
+  static positiveDuration(this: void, label: string): never;
+  static nonNegativeDuration(this: void, label: string): never;
+  static safeDuration(this: void, label: string): never;
+  static positiveSafeIntegerDuration(this: void, label: string): never;
+  static temporalInstant(this: void, label: string): never;
+  static abortSignal(this: void, label: string): never;
+  static childCancellationPolicy(this: void): never;
+  static cursorInvalid(this: void, label: string): never;
+  static retryMaximumIntervalTooSmall(this: void, label: string): never;
+  static retryableErrorDelayConflict(this: void): never;
+  static engineStoreAndStorageConflict(this: void): never;
+  static missingImplementationRetryAttemptPositiveSafeInteger(this: void): never;
+}
+/** Error thrown for state failures. */
+declare class WorkflowStateError extends WorkflowError {
+  constructor(message: string, context?: Function, options?: WorkflowErrorOptions);
+  static create(this: void, message: string): WorkflowStateError;
+  static runNamespaceMismatch(this: void, actual: string, expected: string): never;
+  static runIdMismatch(this: void, actual: string, expected: string): never;
+  static runIdAlreadyExists(this: void, runId: RunId): never;
+  static eventHistoryAlreadyExists(this: void, runId: RunId): never;
+  static eventNotTerminalStep(this: void, kind: EventKind): never;
+  static unsupportedRecordedStepEventType(this: void, kind: EventKind): never;
+  static stepAttemptFieldMismatch(this: void, stepId: StepId, field: string): never;
+  static failedRunMissingError(this: void, runId: RunId): never;
+  static runNotClaimable(this: void, runId: RunId): never;
+  static workerStoppedBeforeRun(this: void, runId: RunId): never;
+  static storeRunIdInvalid(this: void): never;
+  static invalid(this: void, label: string, issues: string): never;
+  static idempotencyKeyClaimedWithoutRun(this: void, runId: RunId): never;
+  static runMissingIdempotencyKey(this: void, runId: RunId): never;
+  static failedRunMetadataUpdate(this: void, runId: RunId): never;
+  static failedRunAttributesUpdate(this: void, runId: RunId): never;
+  static runCannotBeRescheduled(this: void, runId: RunId): never;
+  static failedRunReschedule(this: void, runId: RunId): never;
+  static staleLeaseReleaseRequiresRunning(this: void, runId: RunId): never;
+  static runLeaseStillActive(this: void, runId: RunId): never;
+  static failedStaleRunLeaseRelease(this: void, runId: RunId): never;
+  static runRetryRequiresFailed(this: void, runId: RunId): never;
+  static runRetryRequiresForceAfterPermanentFailure(this: void, runId: RunId): never;
+  static failedRunRetryRequiresForce(this: void, runId: RunId): never;
+  static failedRunRetry(this: void, runId: RunId): never;
+  static failedPermanentRunFailure(this: void, runId: RunId): never;
+  static permanentFailureInvalidStatus(this: void, runId: RunId, status: WorkflowTerminalRunStatus): never;
+  static failedMessageAppend(this: void, runId: RunId): never;
+  static cleanupSelectedNonTerminalRun(this: void, runId: RunId): never;
+  static cleanupRunMissingFinishedAt(this: void, runId: RunId): never;
+  static failedWorkflowEventAppend(this: void, runId: RunId, attempts: number): never;
+  static failedStepAttemptMaterialization(this: void, runId: RunId, attempts: number): never;
+  static appendProjectionPipelineMissing(this: void): never;
+}
+/** Error thrown for run failures. */
+declare class WorkflowRunError extends WorkflowError {
+  constructor(message: string, options: WorkflowErrorOptions, context?: Function);
+  static fromMessage(this: void, message: string, options: WorkflowErrorOptions): WorkflowRunError;
+}
+/** Error thrown for step failures. */
+declare class WorkflowStepError extends WorkflowError {
+  constructor(message: string, options: WorkflowErrorOptions, context?: Function);
+  static fromMessage(this: void, message: string, options: WorkflowErrorOptions): WorkflowStepError;
+}
+/** Error thrown for message failures. */
+declare class WorkflowMessageError extends WorkflowError {
+  constructor(message: string, options: WorkflowErrorOptions, context?: Function);
+  static fromMessage(this: void, message: string, options: WorkflowErrorOptions): WorkflowMessageError;
+}
+//#endregion
+export { WorkflowError, type WorkflowErrorOptions, WorkflowMessageError, WorkflowOptionsError, WorkflowRunError, WorkflowStateError, WorkflowStepError };