inngest 4.1.2 → 4.2.0

package/components/execution/engine.js

@@ -5,6 +5,7 @@ import { NonRetriableError } from "../NonRetriableError.js";
 import { ErrCode, deserializeError, serializeError } from "../../helpers/errors.js";
 import { StepMode, StepOpCode, jsonErrorSchema } from "../../types.js";
 import { InngestExecution } from "./InngestExecution.js";
+import { isRecord } from "../../helpers/types.js";
 import { undefinedToNull } from "../../helpers/functions.js";
 import { createDeferredPromise, createDeferredPromiseWithStack, createTimeoutPromise, goIntervalTiming, resolveAfterPending, resolveNextTick, retryWithBackoff, runAsPromise } from "../../helpers/promises.js";
 import { getAsyncCtx, getAsyncLocalStorage } from "./als.js";
@@ -16,6 +17,8 @@ import { internalLoggerSymbol } from "../Inngest.js";
 import { createGroupTools } from "../InngestGroupTools.js";
 import { RetryAfterError } from "../RetryAfterError.js";
 import { StepError } from "../StepError.js";
+import { buildSseMetadataEvent, prependToStream } from "./streaming.js";
+import { Stream } from "../StreamTools.js";
 import { validateEvents } from "../triggers/utils.js";
 import { clientProcessorMap } from "./otel/access.js";
 import { z } from "zod/v3";
@@ -41,10 +44,43 @@ const CHECKPOINT_RETRY_OPTIONS = {
 	maxAttempts: 5,
 	baseDelay: 100
 };
+function errorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (isRecord(error) && typeof error.message === "string") return error.message;
+	return String(error);
+}
+/**
+* Placeholder step ID used when completing a checkpointed run.
+*/
+const RUN_COMPLETE_STEP_ID = "complete";
 const STEP_NOT_FOUND_MAX_FOUND_STEPS = 25;
 const createExecutionEngine = (options) => {
 	return new InngestExecutionEngine(options);
 };
+function extractSseResponse(response, body) {
+	const headers = {};
+	response.headers.forEach((value, key) => {
+		headers[key] = value;
+	});
+	return {
+		body,
+		statusCode: response.status,
+		headers
+	};
+}
+function defaultSseResponse(data) {
+	return {
+		body: JSON.stringify(data),
+		statusCode: 200,
+		headers: { "content-type": "application/json" }
+	};
+}
+function jsonResponse(data, status = 200) {
+	return new Response(JSON.stringify(data), {
+		status,
+		headers: { "Content-Type": "application/json" }
+	});
+}
 var InngestExecutionEngine = class extends InngestExecution {
 	version = ExecutionVersion.V2;
 	state;
@@ -55,6 +91,29 @@ var InngestExecutionEngine = class extends InngestExecution {
 	userFnToRun;
 	middlewareManager;
 	/**
+	* Close the stream via {@link streamCloseSucceeded}, {@link streamCloseFailed},
+	* or {@link streamEnd} — never call `streamTools.close*`/`end` directly, as
+	* the wrappers ensure the redirect event is flushed first.
+	*/
+	streamTools;
+	/**
+	* Resolved when `stream.push()`/`pipe()` is first called in sync mode,
+	* allowing `_start()` to return the SSE Response to the HTTP layer while
+	* the core loop continues executing steps in the background.
+	*/
+	earlyStreamResponse;
+	/**
+	* Whether the `inngest.redirect_info` SSE event has already been sent.
+	* Prevents duplicate redirect events.
+	*/
+	redirectSent = false;
+	/**
+	* Promise that resolves once the redirect event has been written (or the
+	* attempt completes). Stored so that `checkpointAndSwitchToAsync` can
+	* await it before closing the writer.
+	*/
+	redirectPromise = Promise.resolve();
+	/**
 	* If we're supposed to run a particular step via `requestedRunStep`, this
 	* will be a `Promise` that resolves after no steps have been found for
 	* `timeoutDuration` milliseconds.
@@ -89,6 +148,10 @@ var InngestExecutionEngine = class extends InngestExecution {
 			if (!this.options.createResponse) throw new Error("createResponse is required for sync step mode");
 		}
 		this.userFnToRun = this.getUserFnToRun();
+		this.streamTools = new Stream({
+			onActivated: () => this.handleStreamActivated(),
+			onWriteError: (err) => this.devDebug("stream write error (client may have disconnected):", err)
+		});
 		this.state = this.createExecutionState();
 		this.fnArg = this.createFnArg();
 		const mwInstances = this.options.middlewareInstances ?? (this.options.client.middleware || []).map((Cls) => {
@@ -113,7 +176,8 @@ var InngestExecutionEngine = class extends InngestExecution {
 					app: this.options.client,
 					execution: {
 						ctx: this.fnArg,
-						instance: this
+						instance: this,
+						stream: this.streamTools
 					}
 				}, async () => {
 					return tracer.startActiveSpan("inngest.execution", (span) => {
@@ -152,6 +216,21 @@ var InngestExecutionEngine = class extends InngestExecution {
 	* Starts execution of the user's function and the core loop.
 	*/
 	async _start() {
+		if (this.options.stepMode === StepMode.Sync && this.options.acceptsSse) this.earlyStreamResponse = createDeferredPromise();
+		const coreLoop = this.runCoreLoop();
+		if (this.earlyStreamResponse) {
+			coreLoop.catch((err) => {
+				this.options.client[internalLoggerSymbol].error({ err }, "Core loop rejected after early stream response was sent");
+			});
+			return Promise.race([this.earlyStreamResponse.promise, coreLoop]);
+		}
+		return coreLoop;
+	}
+	/**
+	* The core checkpoint loop: processes checkpoints until a handler returns
+	* a result.
+	*/
+	async runCoreLoop() {
 		try {
 			const allCheckpointHandler = this.getCheckpointHandler("");
 			await this.startExecution();
@@ -162,6 +241,12 @@ var InngestExecutionEngine = class extends InngestExecution {
 				if (result) return result;
 			}
 		} catch (error) {
+			if (this.earlyStreamResponse) {
+				await this.streamCloseFailed("Internal execution error");
+				const result = this.transformOutput({ error });
+				this.earlyStreamResponse.resolve(result);
+				return result;
+			}
 			return this.transformOutput({ error });
 		} finally {
 			this.state.loop.return();
@@ -184,8 +269,10 @@ var InngestExecutionEngine = class extends InngestExecution {
 			this.state.checkpointedRun = {
 				appId: res.data.app_id,
 				fnId: res.data.fn_id,
-				token: res.data.token
+				token: res.data.token,
+				realtimeToken: res.data.realtime_token
 			};
+			this.sendRedirectIfReady();
 		} else await retryWithBackoff(() => this.options.client["inngestApi"].checkpointSteps({
 			appId: this.state.checkpointedRun.appId,
 			fnId: this.state.checkpointedRun.fnId,
@@ -193,34 +280,191 @@ var InngestExecutionEngine = class extends InngestExecution {
 			steps
 		}), CHECKPOINT_RETRY_OPTIONS);
 		else if (this.options.stepMode === StepMode.AsyncCheckpointing) {
-			if (!this.options.queueItemId) throw new Error("Missing queueItemId for async checkpointing. This is a bug in the Inngest SDK.");
-			if (!this.options.internalFnId) throw new Error("Missing internalFnId for async checkpointing. This is a bug in the Inngest SDK.");
+			const { internalFnId, queueItemId } = this.options;
+			if (!queueItemId) throw new Error("Missing queueItemId for async checkpointing. This is a bug in the Inngest SDK.");
+			if (!internalFnId) throw new Error("Missing internalFnId for async checkpointing. This is a bug in the Inngest SDK.");
 			await retryWithBackoff(() => this.options.client["inngestApi"].checkpointStepsAsync({
 				runId: this.fnArg.runId,
-				fnId: this.options.internalFnId,
-				queueItemId: this.options.queueItemId,
+				fnId: internalFnId,
+				queueItemId,
 				steps
 			}), CHECKPOINT_RETRY_OPTIONS);
 		} else throw new Error("Checkpointing is only supported in Sync and AsyncCheckpointing step modes. This is a bug in the Inngest SDK.");
 	}
-	async checkpointAndSwitchToAsync(steps) {
+	async checkpointAndSwitchToAsync(steps, stepError) {
 		await this.checkpoint(steps);
 		if (!this.state.checkpointedRun?.token) throw new Error("Failed to checkpoint and switch to async mode");
+		const token = this.state.checkpointedRun.token;
+		if (this.streamTools.activated) if (stepError && !this.retriability(stepError)) await this.streamCloseFailed(errorMessage(stepError));
+		else await this.streamEnd();
+		else if (this.options.acceptsSse) {
+			await this.streamEnd();
+			return {
+				type: "function-resolved",
+				ctx: this.fnArg,
+				ops: this.ops,
+				data: this.buildSyncSseResponse()
+			};
+		}
 		return {
 			type: "change-mode",
 			ctx: this.fnArg,
 			ops: this.ops,
 			to: StepMode.Async,
-			token: this.state.checkpointedRun?.token
+			token
+		};
+	}
+	/**
+	* Prepend the `inngest.metadata` SSE event to the stream's readable side.
+	* The returned stream can be used as a fetch body or Response body.
+	*
+	* NOTE: `this.streamTools.readable` can only be consumed once, so only one
+	* of `buildSyncSseResponse` or `postCheckpointStream` may be called per
+	* execution.
+	*/
+	buildMetadataPrefixedStream() {
+		const metadataEvent = buildSseMetadataEvent(this.fnArg.runId);
+		return prependToStream(new TextEncoder().encode(metadataEvent), this.streamTools.readable);
+	}
+	/**
+	* Build the initial SSE `Response` that marks the start of streaming to the
+	* client. Only used in sync mode. In async mode, the stream is POSTed to the
+	* Inngest Server via {@link postCheckpointStream} instead.
+	*
+	* The response body is the stream's readable side, prefixed with the
+	* `inngest.metadata` SSE event.
+	*/
+	buildSyncSseResponse() {
+		return new Response(this.buildMetadataPrefixedStream(), {
+			status: 200,
+			headers: {
+				"Content-Type": "text/event-stream",
+				"Cache-Control": "no-cache"
+			}
+		});
+	}
+	/**
+	* Wraps a plain return value as an SSE Response.
+	*
+	* Used when the client sent `Accept: text/event-stream` but
+	* `stream.push()`/`pipe()` was NOT called during execution. The
+	* checkpointable data is the function's return value. The SSE events are just
+	* a delivery mechanism.
+	*/
+	async wrapResultAsSse(checkpoint, sseResponse) {
+		const resultData = checkpoint.data;
+		await this.streamCloseSucceeded(sseResponse);
+		const clientResponse = this.buildSyncSseResponse();
+		const streamingResult = {
+			...this.transformOutput({ data: resultData }),
+			data: clientResponse
 		};
+		this.checkpointReturnValue(resultData);
+		return streamingResult;
+	}
+	/**
+	* Called when `stream.push()`/`pipe()` is first invoked during sync
+	* execution. Resolves {@link earlyStreamResponse} so that `_start()` can
+	* return the SSE Response to the HTTP layer immediately, while the core
+	* checkpoint loop keeps running steps in the background.
+	*/
+	handleStreamActivated() {
+		if (this.earlyStreamResponse) {
+			this.earlyStreamResponse.resolve({
+				type: "function-resolved",
+				ctx: this.fnArg,
+				ops: this.ops,
+				data: this.buildSyncSseResponse()
+			});
+			this.sendRedirectIfReady();
+			return;
+		}
+		if (this.options.stepMode !== StepMode.Sync) this.postCheckpointStream();
+		this.sendRedirectIfReady();
+	}
+	/**
+	* Sends the `inngest.redirect_info` SSE event when both conditions are met:
+	* 1. The client accepts SSE (so there's a stream to write the event to)
+	* 2. We have a realtime token (first checkpoint has completed)
+	*
+	* Called after the first checkpoint AND on stream activation, whichever
+	* comes second, so the redirect is sent as early as possible.
+	*/
+	sendRedirectIfReady() {
+		if (this.redirectSent) return;
+		if (!this.options.acceptsSse) return;
+		if (!this.state.checkpointedRun) return;
+		this.redirectSent = true;
+		const { realtimeToken } = this.state.checkpointedRun;
+		this.redirectPromise = (async () => {
+			try {
+				const redirect = await this.options.client["inngestApi"].getRealtimeStreamRedirect(realtimeToken);
+				this.streamTools.sendRedirectInfo({
+					runId: this.fnArg.runId,
+					url: redirect.url
+				});
+			} catch (err) {
+				this.options.client[internalLoggerSymbol].warn({ err }, "Failed to fetch realtime stream redirect URL");
+			}
+		})();
+	}
+	/**
+	* Await the pending redirect-info fetch, then close the stream with a
+	* succeeded result. Awaiting first guarantees the redirect event is
+	* enqueued on the write chain before the close event.
+	*/
+	async streamCloseSucceeded(response) {
+		await this.redirectPromise;
+		this.streamTools.closeSucceeded(response);
+	}
+	/**
+	* Await the pending redirect-info fetch, then close the stream with a
+	* failed result.
+	*/
+	async streamCloseFailed(error) {
+		await this.redirectPromise;
+		this.streamTools.closeFailed(error);
+	}
+	/**
+	* Await the pending redirect-info fetch, then close the stream without
+	* a result event.
+	*/
+	async streamEnd() {
+		await this.redirectPromise;
+		this.streamTools.end();
+	}
+	/**
+	* POST stream data to the checkpoint stream ingest endpoint.
+	*
+	* Called eagerly from handleStreamActivated so chunks flow in
+	* real-time, or after completion if stream.push() was never called.
+	*/
+	postCheckpointStream() {
+		try {
+			this.options.client["inngestApi"].checkpointStream({
+				runId: this.fnArg.runId,
+				body: this.buildMetadataPrefixedStream()
+			}).catch((err) => {
+				this.devDebug("checkpoint stream POST error:", err);
+			});
+		} catch (err) {
+			this.devDebug("checkpoint stream POST error:", err);
+		}
 	}
 	/**
-	* Returns whether we're in the final attempt of execution, or `null` if we
-	* can't determine this in the SDK.
+	* Checkpoints the return value of a function that was delivered via SSE.
+	* Runs in the background so it doesn't block the client stream.
 	*/
-	inFinalAttempt() {
-		if (typeof this.fnArg.maxAttempts !== "number") return null;
-		return this.fnArg.attempt + 1 >= this.fnArg.maxAttempts;
+	async checkpointReturnValue(data) {
+		try {
+			if (this.options.createResponse) await this.checkpoint([{
+				op: StepOpCode.RunComplete,
+				id: hashId(RUN_COMPLETE_STEP_ID),
+				data: await this.options.createResponse(jsonResponse(data))
+			}]);
+		} catch (err) {
+			this.devDebug("error during background checkpoint of SSE result, client stream unaffected:", err);
+		}
 	}
 	/**
 	* Creates a handler for every checkpoint type, defining what to do when we
@@ -311,19 +555,67 @@ var InngestExecutionEngine = class extends InngestExecution {
 		};
 		const syncHandlers = {
 			"": commonCheckpointHandler,
-			"function-resolved": async (checkpoint, i) => {
-				const transformedData = checkpoint.data;
+			"function-resolved": async (checkpoint) => {
+				const usingSseStream = !!this.earlyStreamResponse;
+				if (this.streamTools.activated) {
+					let resultData = checkpoint.data;
+					let sseResponse;
+					if (checkpoint.data instanceof Response) {
+						const body = await (usingSseStream ? checkpoint.data.text() : checkpoint.data.clone().text());
+						sseResponse = extractSseResponse(checkpoint.data, body);
+						resultData = body;
+					} else sseResponse = defaultSseResponse(resultData);
+					await this.streamCloseSucceeded(sseResponse);
+					if (usingSseStream) {
+						this.checkpointReturnValue(resultData);
+						return this.transformOutput({ data: resultData });
+					}
+				}
+				if (this.options.acceptsSse) {
+					let sseResponse;
+					if (checkpoint.data instanceof Response) {
+						const body = await checkpoint.data.text();
+						sseResponse = extractSseResponse(checkpoint.data, body);
+						checkpoint = {
+							...checkpoint,
+							data: body
+						};
+					} else sseResponse = defaultSseResponse(checkpoint.data);
+					return this.wrapResultAsSse(checkpoint, sseResponse);
+				}
+				if (checkpoint.data instanceof Response) {
+					this.checkpointReturnValue(null);
+					return this.transformOutput({ data: checkpoint.data });
+				}
 				await this.checkpoint([{
 					op: StepOpCode.RunComplete,
-					id: _internals.hashId("complete"),
-					data: await this.options.createResponse(transformedData)
+					id: hashId(RUN_COMPLETE_STEP_ID),
+					data: await this.options.createResponse(jsonResponse(checkpoint.data))
 				}]);
-				return await this.transformOutput({ data: checkpoint.data });
+				return this.transformOutput({ data: checkpoint.data });
 			},
 			"function-rejected": async (checkpoint) => {
-				if (this.inFinalAttempt()) return await this.transformOutput({ error: checkpoint.error });
+				const usingSseStream = !!this.earlyStreamResponse;
+				const isFinal = !this.retriability(checkpoint.error);
+				if (this.streamTools.activated && usingSseStream) {
+					(async () => {
+						try {
+							await this.checkpoint([{
+								id: hashId(RUN_COMPLETE_STEP_ID),
+								op: isFinal ? StepOpCode.StepFailed : StepOpCode.StepError,
+								error: checkpoint.error
+							}]);
+						} catch (err) {
+							this.options.client[internalLoggerSymbol].warn({ err }, "Failed to checkpoint function error");
+						}
+						if (isFinal) await this.streamCloseFailed(errorMessage(checkpoint.error));
+						else await this.streamEnd();
+					})();
+					return this.transformOutput({ error: checkpoint.error });
+				}
+				if (isFinal) return this.transformOutput({ error: checkpoint.error });
 				return this.checkpointAndSwitchToAsync([{
-					id: _internals.hashId("complete"),
+					id: hashId(RUN_COMPLETE_STEP_ID),
 					op: StepOpCode.StepError,
 					error: checkpoint.error
 				}]);
@@ -345,7 +637,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 				const result = await this.executeStep(steps[0]);
 				const transformed = await stepRanHandler(result);
 				if (transformed.type !== "step-ran") throw new Error("Unexpected checkpoint handler result type after running step in sync mode");
-				if (result.error) return this.checkpointAndSwitchToAsync([transformed.step]);
+				if (result.error) return this.checkpointAndSwitchToAsync([transformed.step], result.error);
 				const stepToResume = this.resumeStepWithResult(result);
 				delete this.state.executingStep;
 				const stepForCheckpoint = {
@@ -367,13 +659,25 @@ var InngestExecutionEngine = class extends InngestExecution {
 		const asyncHandlers = {
 			"": commonCheckpointHandler,
 			"function-resolved": async ({ data }) => {
+				let resultData = data;
+				let sseResponse;
+				if (data instanceof Response) {
+					const body = await data.text();
+					sseResponse = extractSseResponse(data, body);
+					resultData = body;
+				} else sseResponse = defaultSseResponse(resultData);
 				const newStepsResult = await maybeReturnNewSteps();
 				if (newStepsResult) return newStepsResult;
-				if (this.options.createResponse) data = await this.options.createResponse(data);
-				return await this.transformOutput({ data });
+				await this.streamCloseSucceeded(sseResponse);
+				if (!this.streamTools.activated) this.postCheckpointStream();
+				if (this.options.createResponse) data = await this.options.createResponse(jsonResponse(resultData));
+				return this.transformOutput({ data });
 			},
 			"function-rejected": async (checkpoint) => {
-				return await this.transformOutput({ error: checkpoint.error });
+				if (!this.retriability(checkpoint.error)) await this.streamCloseFailed(errorMessage(checkpoint.error));
+				else await this.streamEnd();
+				if (!this.streamTools.activated) this.postCheckpointStream();
+				return this.transformOutput({ error: checkpoint.error });
 			},
 			"steps-found": async ({ steps }) => {
 				const stepResult = await this.tryExecuteStep(steps);
@@ -405,7 +709,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 				if (output?.type === "function-resolved") {
 					const steps = this.state.checkpointingStepBuffer.concat({
 						op: StepOpCode.RunComplete,
-						id: _internals.hashId("complete"),
+						id: hashId(RUN_COMPLETE_STEP_ID),
 						data: output.data
 					});
 					if (isNonEmpty(steps)) return {
@@ -465,6 +769,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 				}
 			},
 			"checkpointing-runtime-reached": async () => {
+				this.options.client[internalLoggerSymbol].debug("Checkpointing runtime reached; sending discovery request");
 				return {
 					type: "steps-found",
 					ctx: this.fnArg,
@@ -548,7 +853,8 @@ var InngestExecutionEngine = class extends InngestExecution {
 		const store = await getAsyncCtx();
 		if (store?.execution) store.execution.executingStep = {
 			id,
-			name: displayName
+			name: displayName,
+			hashedId
 		};
 		this.devDebug(`executing step "${id}"`);
 		if (this.rootSpanId && this.options.checkpointingConfig) clientProcessorMap.get(this.options.client)?.declareStepExecution(this.rootSpanId, userland.id ?? "", userland.index ?? 0, hashedId, this.options.data?.attempt ?? 0);
@@ -574,6 +880,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 			const metadata = this.state.metadata?.get(id);
 			const serverData = await resultPromise;
 			await this.middlewareManager.onStepComplete(stepInfo, serverData);
+			this.streamTools.commit(hashedId);
 			return {
 				...outgoingOp,
 				data: serverData,
@@ -648,6 +955,7 @@ var InngestExecutionEngine = class extends InngestExecution {
 		const isFinal = !this.retriability(error);
 		const metadata = this.state.metadata?.get(id);
 		await this.middlewareManager.onStepError(stepInfo, error instanceof Error ? error : new Error(String(error)), isFinal);
+		this.streamTools.rollback(outgoingOp.id);
 		const serialized = serializeError(error);
 		return {
 			...outgoingOp,