@classytic/arc 2.41.1 → 2.44.0

package/dist/integrations/streamline.mjs

@@ -1,17 +1,38 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { f as createError, i as NotFoundError, r as ForbiddenError } from "../errors-BH7YU_9O.mjs";
-import { a as promoteStreamTokenToHeader, n as forwardedStreamHeaders } from "../streaming-IcRFjWQU.mjs";
+/*! @classytic/arc v2.44.0 | MIT | https://classytic.com */
+import { f as createError, i as NotFoundError, r as ForbiddenError } from "../errors-CW4anJBy.mjs";
+import { a as promoteStreamTokenToHeader, n as forwardedStreamHeaders } from "../streaming-JzB5CAga.mjs";
+import { ARC_ERROR_CODES } from "@classytic/repo-core/errors";
 import fp from "fastify-plugin";
 //#region src/integrations/streamline.ts
 /**
-* Streamline >= 2.3.3 dead-letter discriminator. The run.status stays
-* `'failed'`; the discrimination is `error.code`:
+* Streamline integration — wires `@classytic/streamline` workflows into arc.
+*
+* REST endpoints for workflow management, auto-connected to arc's event bus,
+* honouring arc auth/permissions and surfacing streamline's repo-core-aligned
+* `HttpError`s with their real status codes rather than a blanket 500.
+*
+* A separate subpath, loaded only when used:
+* `@classytic/arc/integrations/streamline`. Peer: `@classytic/streamline`.
+*
+* Routes mounted under `prefix`: `POST /:workflow/start`,
+* `GET /:workflow/runs[/:runId]`, `POST /:workflow/runs/:runId/{resume,cancel}`,
+* and `POST /hooks/:token` when `enableHookEndpoint` is set.
+*
+* @example
+* ```typescript
+* await fastify.register(streamlinePlugin, {
+*   workflows: [orderWorkflow],
+*   prefix: '/api/workflows',
+*   tenantResolver: (req) => req.user?.organizationId,
+* });
+* ```
+*/
+/**
+* Dead-letter discriminator: `run.status` stays `'failed'`; `error.code` says why:
 *   - `'stale_heartbeat'` — sweeper terminated; transient crash signal.
 *   - `'dead_lettered'`   — exceeded `maxStaleRecoveries`; permanent.
 *   - `'VERSION_MISMATCH'` — engine deployed a step graph the run can't
 *     resume against; admin must rewind / migrate / cancel.
-*
-* Hosts switch on `error.code` for dashboards / alerting.
 */
 const STREAMLINE_FAILURE_CODES = {
 	STALE_HEARTBEAT: "stale_heartbeat",
@@ -19,15 +40,9 @@ const STREAMLINE_FAILURE_CODES = {
 	VERSION_MISMATCH: "VERSION_MISMATCH"
 };
 /**
-* Full event list published on a streamline workflow's internal `eventBus`
-* (tracks streamline 2.3's `EventPayloadMap` in
-* `@classytic/streamline/src/core/events.ts`).
-*
-* Hardcoded here by design — arc subscribes via structural
-* `eventBus.on(name, handler)`, which is a no-op for events the running
-* streamline version doesn't emit. New events a future streamline release
-* adds can be bridged by updating this list; arc never breaks just
-* because streamline extended its bus.
+* Events published on a streamline workflow's internal `eventBus`. Subscribing
+* to one the running version doesn't emit is a no-op. Pinned against
+* streamline's `ALL_WORKFLOW_EVENT_NAMES` by `tests/integrations/streamline-drift.test.ts`.
 */
 const STREAMLINE_BUS_EVENTS = [
 	"step:started",
@@ -47,48 +62,63 @@ const STREAMLINE_BUS_EVENTS = [
 	"workflow:retry",
 	"workflow:compensating",
 	"workflow:paused",
+	"workflow:compensated",
+	"workflow:compensation_failed",
 	"engine:error",
 	"scheduler:error",
 	"scheduler:circuit-open"
 ];
 /**
-* Non-durable streaming frames from streamline >= 2.6's `ctx.stream(frame)`
-* (LLM tokens, percent-complete, live previews).
-*
-* Delivered on the SSE endpoint ONLY — deliberately excluded from
-* `STREAMLINE_BUS_EVENTS` / `bridgeBusEvents` because frames are
-* high-frequency, at-most-once UI traffic, not domain events: republishing
-* every token onto arc's Redis/Kafka transport would flood it. Subscribers
-* that genuinely want frames on the transport can bridge
-* `streamline:step.stream` from streamline's own arc-shape transport.
-*
-* On streamline < 2.6 the subscription is a structural no-op (the bus never
-* emits the event) — no version gate needed.
+* Non-durable `ctx.stream(frame)` frames (LLM tokens, progress). SSE ONLY —
+* excluded from `bridgeBusEvents` because high-frequency at-most-once UI
+* traffic would flood arc's event transport.
 */
 const STREAMLINE_STREAM_EVENTS = ["step:stream"];
 /**
-* Workflow events that should auto-close an SSE stream when observed.
-* Recovered / waiting / resumed / retry / compensating are NOT terminal —
-* the run is still active after them.
+* Workflow events that end a run and auto-close an SSE stream.
+*
+* `workflow:failed` is terminal ONLY without compensation handlers: a saga
+* emits `failed` THEN rolls back, so closing there would hide the rollback.
+* See {@link isStreamTerminal}.
 */
 const STREAMLINE_TERMINAL_EVENTS = [
 	"workflow:completed",
 	"workflow:failed",
-	"workflow:cancelled"
+	"workflow:cancelled",
+	"workflow:compensated",
+	"workflow:compensation_failed"
 ];
 /**
-* Terminal run STATUSES (distinct from the terminal EVENT names above).
-* Mirrors streamline's `isTerminalState()` — a run in one of these will
-* emit no further bus events, so the SSE handler sends its snapshot and
-* closes immediately rather than holding a connection open on a dead run.
+* Terminal run STATUSES (vs. the event names above). A run in one emits no
+* further events, so SSE sends its snapshot and closes. Pinned against
+* streamline's own list by `tests/integrations/streamline-drift.test.ts`.
 */
 const TERMINAL_RUN_STATUSES = /* @__PURE__ */ new Set([
 	"done",
 	"failed",
-	"cancelled"
+	"cancelled",
+	"compensated",
+	"compensation_failed"
 ]);
+/** Whether a workflow rolls back on failure (has any `onCompensate` step). */
+function hasCompensation(wf) {
+	const handlers = wf.engine.options?.compensationHandlers;
+	return !!handlers && typeof handlers === "object" && Object.keys(handlers).length > 0;
+}
+/**
+* Whether a run has ended, for the purpose of closing its stream — by event
+* name or by status. `failed` ends a run only when nothing will compensate it.
+*/
+function isStreamTerminal(eventOrStatus, compensates, kind) {
+	if (kind === "event") {
+		if (eventOrStatus === "workflow:failed") return !compensates;
+		return STREAMLINE_TERMINAL_EVENTS.includes(eventOrStatus);
+	}
+	if (eventOrStatus === "failed") return !compensates;
+	return TERMINAL_RUN_STATUSES.has(eventOrStatus);
+}
 const streamlinePluginImpl = async (fastify, options) => {
-	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms } = options;
+	const { workflows, prefix = "/workflows", auth = true, bridgeEvents = true, enableStreaming = false, enableHookEndpoint = false, tenantResolver, bypassTenantResolver, permissions: perms, idempotency } = options;
 	const routeScope = prefix;
 	const bridgeBus = options.bridgeBusEvents ?? false;
 	const registry = /* @__PURE__ */ new Map();
@@ -110,11 +140,38 @@ const streamlinePluginImpl = async (fastify, options) => {
 		if (tenantId !== void 0) opts.tenantId = tenantId;
 		return opts;
 	};
+	const PERM_FALLBACK = {
+		execute: "start",
+		pause: "cancel",
+		rewind: "cancel"
+	};
 	const checkPerm = async (op, request) => {
-		const check = perms?.[op];
+		const fallback = PERM_FALLBACK[op];
+		const check = perms?.[op] ?? (fallback ? perms?.[fallback] : void 0);
 		if (!check) return true;
 		return check(request);
 	};
+	const fencedOps = new Set(idempotency?.required ?? []);
+	if (fencedOps.size > 0 && !fastify.hasDecorator("idempotency")) throw new Error("[Arc/Streamline] `idempotency.required` is declared, but idempotencyPlugin is not registered — register it (enabled) before streamlinePlugin, or drop the declaration.");
+	for (const wfId of idempotency?.workflows ?? []) if (!workflows.some((wf) => wf.definition.id === wfId)) throw new Error(`[Arc/Streamline] idempotency.workflows names unknown workflow '${wfId}'.`);
+	/**
+	* Route options for a mutating op: a fenced op gets `config.idempotency.required` and
+	* runs auth → permission → idempotency, so a refused caller never reaches the key check.
+	*/
+	const routeOpts = (wfId, op, permOp = op) => {
+		if (!(fencedOps.has(op) && (!idempotency?.workflows || idempotency.workflows.includes(wfId)))) return { preHandler: authPreHandler };
+		const permGate = async (request) => {
+			if (!await checkPerm(permOp, request)) throw new ForbiddenError();
+		};
+		return {
+			config: { idempotency: { required: true } },
+			preHandler: [
+				...authPreHandler,
+				permGate,
+				fastify.idempotency.middleware
+			]
+		};
+	};
 	for (const [id, wf] of registry) {
 		const routePrefix = `${routeScope}/${id}`;
 		const visibilityRepo = wf.container?.repository;
@@ -125,7 +182,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			if (tenantOpts.bypassTenant || tenantOpts.tenantId === void 0) return;
 			if (!await visibilityGetById(runId, { tenantId: tenantOpts.tenantId })) throw new NotFoundError("Workflow run", runId);
 		};
-		fastify.post(`${routePrefix}/start`, { preHandler: authPreHandler }, async (request, reply) => {
+		fastify.post(`${routePrefix}/start`, routeOpts(id, "start"), async (request, reply) => {
 			if (!await checkPerm("start", request)) throw new ForbiddenError();
 			const body = request.body;
 			if (body !== null && body !== void 0 && typeof body !== "object") throw createError(422, `[Arc/Streamline] '/${id}/start' body must be a JSON object.`, {
@@ -152,7 +209,13 @@ const streamlinePluginImpl = async (fastify, options) => {
 				workflowId: id,
 				unknown: unknownKeys
 			});
-			const { input, meta, idempotencyKey, priority } = bodyRecord;
+			const { input, meta, idempotencyKey: bodyKey, priority } = bodyRecord;
+			const headerKey = request.idempotencyKey;
+			if (headerKey !== void 0 && bodyKey !== void 0 && bodyKey !== headerKey) throw createError(422, `[Arc/Streamline] '/${id}/start' got an idempotency-key header and a different body \`idempotencyKey\` — send one key, or the same key in both.`, {
+				code: ARC_ERROR_CODES.IDEMPOTENCY_KEY_REUSED,
+				workflowId: id
+			});
+			const idempotencyKey = bodyKey ?? headerKey;
 			const tenantOpts = resolveTenantOpts(request);
 			const run = await wf.start(input, {
 				meta,
@@ -201,7 +264,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			if (!run) throw new NotFoundError("Workflow run", runId);
 			return run;
 		});
-		fastify.post(`${routePrefix}/runs/:runId/resume`, { preHandler: authPreHandler }, async (request, _reply) => {
+		fastify.post(`${routePrefix}/runs/:runId/resume`, routeOpts(id, "resume"), async (request, _reply) => {
 			if (!await checkPerm("resume", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
@@ -241,7 +304,8 @@ const streamlinePluginImpl = async (fastify, options) => {
 			}
 			return run;
 		});
-		fastify.post(`${routePrefix}/runs/:runId/execute`, { preHandler: authPreHandler }, async (request, _reply) => {
+		fastify.post(`${routePrefix}/runs/:runId/execute`, routeOpts(id, "execute"), async (request, _reply) => {
+			if (!await checkPerm("execute", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
 			return await wf.engine.execute(runId);
@@ -273,12 +337,14 @@ const streamlinePluginImpl = async (fastify, options) => {
 			return await wf.engine.waitFor?.(runId, { timeout: Math.min(timeoutMs, 12e4) });
 		});
 		if (wf.engine.pause) fastify.post(`${routePrefix}/runs/:runId/pause`, { preHandler: authPreHandler }, async (request, _reply) => {
+			if (!await checkPerm("pause", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
 			const { reason: pauseReason } = request.body ?? {};
 			return await wf.engine.pause?.(runId, pauseReason !== void 0 ? { reason: pauseReason } : void 0);
 		});
-		if (wf.engine.rewindTo) fastify.post(`${routePrefix}/runs/:runId/rewind`, { preHandler: authPreHandler }, async (request, _reply) => {
+		if (wf.engine.rewindTo) fastify.post(`${routePrefix}/runs/:runId/rewind`, routeOpts(id, "rewind"), async (request, _reply) => {
+			if (!await checkPerm("rewind", request)) throw new ForbiddenError();
 			const { runId } = request.params;
 			await assertRunVisible(request, runId);
 			const { stepId } = request.body ?? {};
@@ -315,7 +381,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 				...forwardedStreamHeaders(reply)
 			});
 			reply.raw.flushHeaders();
-			const terminalEvents = new Set(STREAMLINE_TERMINAL_EVENTS);
+			const compensates = hasCompensation(wf);
 			const listeners = [];
 			let closed = false;
 			let heartbeat;
@@ -339,7 +405,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 			};
 			send("workflow:snapshot", run);
 			const runStatus = run.status;
-			if (runStatus && TERMINAL_RUN_STATUSES.has(runStatus)) {
+			if (runStatus && isStreamTerminal(runStatus, compensates, "status")) {
 				cleanup();
 				return;
 			}
@@ -357,7 +423,7 @@ const streamlinePluginImpl = async (fastify, options) => {
 					const p = payload;
 					if (typeof p?.runId === "string" && p.runId !== runId) return;
 					send(eventName, p);
-					if (terminalEvents.has(eventName) && p?.runId === runId) cleanup();
+					if (p?.runId === runId && isStreamTerminal(eventName, compensates, "event")) cleanup();
 				};
 				wf.container?.eventBus.on(eventName, fn);
 				listeners.push({
@@ -370,10 +436,24 @@ const streamlinePluginImpl = async (fastify, options) => {
 	}
 	if (enableHookEndpoint) {
 		let resumeHookFn;
+		/**
+		* The container the token's run lives in. Streamline's DB-fallback resume writes through the DEFAULT
+		* connection's repository and strict-concurrency counter unless it is handed the run's container —
+		* wrong for a streamline bound to another connection. One distinct container is the common case;
+		* several are told apart by which one holds the run.
+		*/
+		const containerForRun = async (runId) => {
+			const containers = [...new Set([...registry.values()].map((wf) => wf.container).filter((c) => c !== void 0))];
+			if (containers.length <= 1) return containers[0];
+			for (const container of containers) try {
+				if (await container.repository?.getById?.(runId)) return container;
+			} catch {}
+		};
 		fastify.post(`${routeScope}/hooks/:token`, { preHandler: authPreHandler }, async (request, _reply) => {
 			if (!resumeHookFn) resumeHookFn = (await import("@classytic/streamline")).resumeHook;
 			const { token } = request.params;
-			const result = await resumeHookFn(token, request.body);
+			const container = await containerForRun(token.split(":")[0] ?? token);
+			const result = await resumeHookFn(token, request.body, container ? { container } : void 0);
 			return {
 				runId: result.runId,
 				run: result.run
@@ -395,16 +475,12 @@ const streamlinePluginImpl = async (fastify, options) => {
 	});
 };
 /**
-* Pluggable streamline integration for Arc.
-*
-* Wrapped in `fastify-plugin` so Fastify treats `options.prefix` as a
-* plain plugin option (NOT an encapsulation prefix). Without the wrapper,
-* Fastify would prepend `options.prefix` to every route, then the plugin
-* code would prepend it again — the duplicate-prefix bug.
+* Streamline integration for Arc. Wrapped in `fastify-plugin` so `prefix` is
+* a plain option, not an encapsulation prefix (which would apply it twice).
 */
 const streamlinePlugin = fp(streamlinePluginImpl, {
 	name: "streamline-routes",
 	fastify: "5.x"
 });
 //#endregion
-export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_STREAM_EVENTS, STREAMLINE_TERMINAL_EVENTS, TERMINAL_RUN_STATUSES, streamlinePlugin };
+export { STREAMLINE_BUS_EVENTS, STREAMLINE_FAILURE_CODES, STREAMLINE_STREAM_EVENTS, STREAMLINE_TERMINAL_EVENTS, TERMINAL_RUN_STATUSES, isStreamTerminal, streamlinePlugin };