callman-core 1.17.0 → 1.19.0

package/dist-cjs/scenario-runner/runScenario.js

@@ -5,6 +5,7 @@ const condition_js_1 = require("./condition.js");
 const extraction_js_1 = require("./extraction.js");
 const assertion_js_1 = require("./assertion.js");
 const graphTraversal_js_1 = require("./graphTraversal.js");
+const websocket_js_1 = require("./websocket.js");
 const executionPolicyRunner_js_1 = require("./executionPolicyRunner.js");
 const nodePolicy_js_1 = require("./nodePolicy.js");
 const templateResolver_js_1 = require("./templateResolver.js");
@@ -36,9 +37,19 @@ const buildTitle = (node) => {
     return `${node.type[0]?.toUpperCase() ?? ""}${node.type.slice(1)}`;
 };
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-// `loop`/`loops` are the loop-iteration template roots (see the loop-frame
+// `loop`/`loops` are the loop-iteration template roots and `item`/`each`/
+// `eaches` the foreach-iteration ones (see the loop-frame and foreach
 // machinery in runScenario) — node labels must not shadow them.
-const RESERVED_WORKFLOW_ROOT_LABELS = new Set(["workflow", "__meta", "loop", "loops"]);
+const RESERVED_WORKFLOW_ROOT_LABELS = new Set([
+    "workflow",
+    "__meta",
+    "loop",
+    "loops",
+    "item",
+    "each",
+    "eaches",
+    "ws",
+]);
 const cloneNodeExecutionMeta = (meta) => ({
     ...meta,
     ...(meta.error ? { error: { ...meta.error } } : {}),
@@ -416,6 +427,18 @@ const updateRecordFromEvent = (records, event) => {
         });
         return;
     }
+    if (event.type === "step:iteration") {
+        // Iteration progress marker only — the terminal success/fail event owns
+        // the record. Without this early return the generic fallback below would
+        // stamp status:"failed" on the foreach step.
+        records.set(event.stepId, {
+            ...current,
+            stepType: event.stepType,
+            title: event.title,
+            startedAt: current.startedAt ?? event.at,
+        });
+        return;
+    }
     if (event.type === "step:condition") {
         records.set(event.stepId, {
             ...current,
@@ -511,6 +534,9 @@ const callHandler = async (handlers, event) => {
         case "step:poll":
             await handlers?.onPollTick?.(event);
             return;
+        case "step:iteration":
+            await handlers?.onForeachIteration?.(event);
+            return;
         case "step:success":
             await handlers?.onNodeSuccess?.(event);
             return;
@@ -824,10 +850,10 @@ const runScenario = async ({ scenario, environment = {}, globals = {}, runtimeAd
         let executionPolicy = (0, nodePolicy_js_1.supportsScenarioNodeExecutionPolicy)(node)
             ? withNotificationFailurePolicyOverride(node, (0, nodePolicy_js_1.getScenarioNodeExecutionPolicy)(node))
             : (0, nodePolicy_js_1.getLegacyScenarioNodeExecutionPolicy)();
-        if (node.type === "poll") {
-            // The poll loop REPLACES per-node retry (nested retry loops would be
-            // unexplainable). onFailure — incl. error edges — still governs the
-            // timeout outcome.
+        if (node.type === "poll" || node.type === "foreach") {
+            // The poll/item loop REPLACES per-node retry (nested retry loops would
+            // be unexplainable). onFailure — incl. error edges — still governs the
+            // final outcome.
             executionPolicy = {
                 ...executionPolicy,
                 retry: { enabled: false, maxAttempts: 0, delayMs: 0 },
@@ -1424,6 +1450,163 @@ const runScenario = async ({ scenario, environment = {}, globals = {}, runtimeAd
                         outputData = runtimeContext.kafkaEvent;
                     }
                 }
+                if (node.type === "websocket") {
+                    const wsConfig = node.data.config;
+                    const resolvedUrl = (0, templateResolver_js_1.resolveScenarioTemplateString)(wsConfig.url ?? "", templateValues).trim();
+                    if (!resolvedUrl) {
+                        throw new ScenarioNodeFailureError("WebSocket URL is required.");
+                    }
+                    const configuredSteps = wsConfig.steps ?? [];
+                    if (configuredSteps.length > graphTraversal_js_1.MAX_WS_STEPS) {
+                        throw new ScenarioNodeFailureError(`WebSocket conversations are capped at ${graphTraversal_js_1.MAX_WS_STEPS} steps.`);
+                    }
+                    for (const [stepIndex, step] of configuredSteps.entries()) {
+                        if (step.kind === "expect" && (!step.rules || step.rules.length === 0)) {
+                            throw new ScenarioNodeFailureError(`WebSocket expect step ${stepIndex + 1} has no rules.`);
+                        }
+                    }
+                    const resolvedHeaders = (wsConfig.headers ?? [])
+                        .filter((header) => header.enabled !== false && header.key.trim())
+                        .map((header) => ({
+                        key: (0, templateResolver_js_1.resolveScenarioTemplateString)(header.key, templateValues).trim(),
+                        value: (0, templateResolver_js_1.resolveScenarioTemplateString)(header.value ?? "", templateValues),
+                    }));
+                    const resolvedSubprotocols = (wsConfig.subprotocols ?? [])
+                        .map((protocol) => (0, templateResolver_js_1.resolveScenarioTemplateString)(protocol, templateValues).trim())
+                        .filter((protocol) => protocol.length > 0);
+                    const connectTimeoutMs = Math.min(graphTraversal_js_1.MAX_WS_CONNECT_TIMEOUT_MS, Math.max(100, Math.round(wsConfig.connectTimeoutMs ?? graphTraversal_js_1.DEFAULT_WS_CONNECT_TIMEOUT_MS)));
+                    const resolvedSteps = configuredSteps.map((step) => {
+                        if (step.kind === "send") {
+                            return {
+                                id: step.id,
+                                kind: "send",
+                                payload: (0, templateResolver_js_1.resolveScenarioJsonTemplateString)(step.payload ?? "", templateValues),
+                            };
+                        }
+                        if (step.kind === "wait") {
+                            return {
+                                id: step.id,
+                                kind: "wait",
+                                durationMs: Math.min(graphTraversal_js_1.MAX_WS_WAIT_DURATION_MS, Math.max(0, Math.round(step.durationMs ?? 0))),
+                            };
+                        }
+                        return {
+                            id: step.id,
+                            kind: "expect",
+                            timeoutMs: Math.min(graphTraversal_js_1.MAX_WS_EXPECT_TIMEOUT_MS, Math.max(100, Math.round(step.timeoutMs ?? graphTraversal_js_1.DEFAULT_WS_EXPECT_TIMEOUT_MS))),
+                            matchMode: step.matchMode === "any" ? "any" : "all",
+                            rules: step.rules,
+                        };
+                    });
+                    const wsExecution = await runtimeAdapters.websocketExecutor({
+                        runId,
+                        stepId,
+                        node,
+                        resolvedUrl,
+                        resolvedHeaders,
+                        subprotocols: resolvedSubprotocols,
+                        connectTimeoutMs,
+                        steps: resolvedSteps,
+                        closeCode: wsConfig.closeCode ?? graphTraversal_js_1.DEFAULT_WS_CLOSE_CODE,
+                        rejectUnauthorized: wsConfig.rejectUnauthorized !== false,
+                        environment: { ...runtimeContext.environment },
+                        globals: { ...runtimeContext.globals },
+                        signal,
+                    });
+                    throwIfStopped(signal);
+                    // Authoritative expect evaluation over the recorded frames — the
+                    // host's early-stop is advisory only (kafka consume precedent).
+                    const evaluationScope = {
+                        environment: runtimeContext.environment,
+                        globals: runtimeContext.globals,
+                        workflowContext: runtimeContext.workflowContext,
+                        nodeMetaByLabel: runtimeContext.nodeMetaByLabel,
+                        responseRoot: runtimeContext.responseRoot,
+                        dbResult: runtimeContext.dbResult,
+                        kafkaEvent: runtimeContext.kafkaEvent,
+                        redisResult: runtimeContext.redisResult,
+                    };
+                    const outcomesByIndex = new Map(wsExecution.stepOutcomes.map((outcome) => [outcome.index, outcome]));
+                    let conversationBroken = !wsExecution.connected;
+                    const stepResults = resolvedSteps.map((step, index) => {
+                        const outcome = outcomesByIndex.get(index);
+                        const durationMs = outcome && outcome.startedAt && outcome.endedAt
+                            ? Math.max(0, new Date(outcome.endedAt).getTime() - new Date(outcome.startedAt).getTime())
+                            : 0;
+                        if (!outcome) {
+                            return {
+                                index,
+                                kind: step.kind,
+                                status: "failed",
+                                durationMs: 0,
+                                error: conversationBroken
+                                    ? "Step not reached — the conversation ended early."
+                                    : "Step was not executed by the host.",
+                                matchedMessageIndex: null,
+                            };
+                        }
+                        if (step.kind !== "expect") {
+                            const failed = Boolean(outcome.error);
+                            if (failed)
+                                conversationBroken = true;
+                            return {
+                                index,
+                                kind: step.kind,
+                                status: failed ? "failed" : "passed",
+                                durationMs,
+                                error: outcome.error ?? null,
+                                matchedMessageIndex: null,
+                            };
+                        }
+                        const candidates = wsExecution.messages.filter((message) => message.direction === "received" && message.stepIndex === index);
+                        let matchedMessageIndex = null;
+                        for (const candidate of candidates) {
+                            const evaluation = (0, websocket_js_1.evaluateWebsocketExpect)(step.rules ?? [], step.matchMode ?? "all", evaluationScope, candidate);
+                            if (evaluation.passed) {
+                                matchedMessageIndex = candidate.index;
+                                break;
+                            }
+                        }
+                        const failed = matchedMessageIndex === null;
+                        if (failed)
+                            conversationBroken = true;
+                        return {
+                            index,
+                            kind: step.kind,
+                            status: failed ? "failed" : "passed",
+                            durationMs,
+                            error: failed
+                                ? (outcome.error ??
+                                    `No message matched within ${step.timeoutMs}ms (${candidates.length} received).`)
+                                : null,
+                            matchedMessageIndex,
+                        };
+                    });
+                    const failedSteps = stepResults.filter((entry) => entry.status === "failed").length;
+                    const wsErrorMessage = !wsExecution.connected
+                        ? (wsExecution.connectError ?? "WebSocket connection failed.")
+                        : failedSteps > 0
+                            ? (() => {
+                                const firstFailed = stepResults.find((entry) => entry.status === "failed");
+                                return `WebSocket step ${(firstFailed?.index ?? 0) + 1} (${firstFailed?.kind}) failed: ${firstFailed?.error}`;
+                            })()
+                            : null;
+                    outputData = {
+                        url: resolvedUrl,
+                        connected: wsExecution.connected,
+                        closeCode: wsExecution.closeCode,
+                        closeReason: wsExecution.closeReason ?? null,
+                        durationMs: wsExecution.durationMs,
+                        messageCount: wsExecution.messages.length,
+                        messages: wsExecution.messages,
+                        steps: stepResults,
+                        failedSteps,
+                        errorMessage: wsErrorMessage,
+                    };
+                    if (wsErrorMessage) {
+                        throw new ScenarioNodeFailureError(wsErrorMessage);
+                    }
+                }
                 if (node.type === "condition") {
                     const conditionIssues = (0, condition_js_1.validateConditionConfig)(node.data.config);
                     const blockingConditionIssue = conditionIssues.find((issue) => issue.severity === "error");
@@ -1536,6 +1719,228 @@ const runScenario = async ({ scenario, environment = {}, globals = {}, runtimeAd
                     shouldMarkPartialSuccess = degradedStepIds.size > degradedCountBefore;
                     outputData = groupedOutput;
                 }
+                if (node.type === "foreach") {
+                    const foreachConfig = node.data.config;
+                    // ── Resolve the items array ──────────────────────────────────────
+                    let items;
+                    if (foreachConfig.sourceMode === "inline") {
+                        const rawInline = (foreachConfig.itemsInline ?? "").trim();
+                        if (!rawInline) {
+                            throw new ScenarioNodeFailureError("Foreach inline items are empty.");
+                        }
+                        const resolvedInline = (0, templateResolver_js_1.resolveScenarioJsonTemplateString)(rawInline, templateValues);
+                        let parsedInline;
+                        try {
+                            parsedInline = JSON.parse(resolvedInline);
+                        }
+                        catch {
+                            throw new ScenarioNodeFailureError("Foreach inline items are not valid JSON after template resolution.");
+                        }
+                        if (!Array.isArray(parsedInline)) {
+                            throw new ScenarioNodeFailureError("Foreach inline items must be a JSON array.");
+                        }
+                        items = parsedInline;
+                    }
+                    else {
+                        const itemsPath = (foreachConfig.itemsPath ?? "").trim();
+                        if (!itemsPath) {
+                            throw new ScenarioNodeFailureError("Foreach items path is required.");
+                        }
+                        const resolved = (0, condition_js_1.resolveConditionRuntimeValue)({
+                            environment: runtimeContext.environment,
+                            globals: runtimeContext.globals,
+                            workflowContext: runtimeContext.workflowContext,
+                            nodeMetaByLabel: runtimeContext.nodeMetaByLabel,
+                            responseRoot: runtimeContext.responseRoot,
+                            dbResult: runtimeContext.dbResult,
+                            kafkaEvent: runtimeContext.kafkaEvent,
+                            redisResult: runtimeContext.redisResult,
+                        }, itemsPath);
+                        if (!resolved.exists || typeof resolved.value === "undefined") {
+                            throw new ScenarioNodeFailureError(`Foreach items path "${itemsPath}" resolved to nothing.`);
+                        }
+                        if (!Array.isArray(resolved.value)) {
+                            throw new ScenarioNodeFailureError(`Foreach items path "${itemsPath}" must resolve to an array (got ${typeof resolved.value}).`);
+                        }
+                        items = resolved.value;
+                    }
+                    const itemAlias = (foreachConfig.itemAlias ?? "").trim();
+                    if (itemAlias && RESERVED_WORKFLOW_ROOT_LABELS.has(itemAlias)) {
+                        throw new ScenarioNodeFailureError(`Foreach item alias "${itemAlias}" is a reserved name.`);
+                    }
+                    const maxIterations = Math.min(graphTraversal_js_1.MAX_FOREACH_ITERATIONS, Math.max(1, Math.round(foreachConfig.maxIterations ?? graphTraversal_js_1.DEFAULT_FOREACH_MAX_ITERATIONS)));
+                    const processLimit = Math.min(items.length, maxIterations);
+                    const iterationDelayMs = Math.max(0, Math.round(foreachConfig.delayMs ?? 0));
+                    const onItemFailure = foreachConfig.onItemFailure ?? "stop";
+                    const collectResults = foreachConfig.collectResults !== false;
+                    // Thinned emission keeps stored events bounded (~100 iteration markers).
+                    const iterationEmitStride = Math.max(1, Math.ceil(processLimit / 100));
+                    const internalGraph = (0, templateResolver_js_1.buildScenarioExecutionGraph)(foreachConfig.nodes, foreachConfig.edges);
+                    const internalScope = {
+                        graph: internalGraph,
+                        stepIdForNode: (childNodeId) => (0, graphTraversal_js_1.createSubScenarioStepId)(stepId, childNodeId),
+                        stepIdForEdge: (edgeId) => (0, graphTraversal_js_1.createSubScenarioStepId)(stepId, edgeId),
+                    };
+                    // ALL descendant step ids (nested containers included) — reset
+                    // targets between iterations.
+                    const internalStepIds = (0, graphTraversal_js_1.buildRuntimeStepDescriptors)(foreachConfig.nodes, stepId).map((descriptor) => descriptor.stepId);
+                    const childLabels = (0, graphTraversal_js_1.flattenScenarioNodesForContext)(foreachConfig.nodes)
+                        .map((childNode) => childNode.data.label.trim())
+                        .filter((childLabel) => childLabel.length > 0);
+                    const workflowRoots = runtimeContext.workflowContext;
+                    // Save the enclosing iteration roots so a NESTED foreach restores
+                    // its parent's {{item}}/{{each}} when it finishes mid-iteration.
+                    const hadItemRoot = Object.prototype.hasOwnProperty.call(workflowRoots, "item");
+                    const previousItemRoot = workflowRoots.item;
+                    const hadEachRoot = Object.prototype.hasOwnProperty.call(workflowRoots, "each");
+                    const previousEachRoot = workflowRoots.each;
+                    const hadAliasRoot = itemAlias
+                        ? Object.prototype.hasOwnProperty.call(workflowRoots, itemAlias)
+                        : false;
+                    const previousAliasRoot = itemAlias ? workflowRoots[itemAlias] : undefined;
+                    const nodeLabelKey = nodeLabel;
+                    const previousEaches = workflowRoots.eaches;
+                    const degradedCountBefore = degradedStepIds.size;
+                    const results = [];
+                    let failedItems = 0;
+                    try {
+                        for (let index = 0; index < processLimit; index += 1) {
+                            throwIfStopped(signal);
+                            if (index > 0) {
+                                // Fresh pass: every internal step back to idle (including the
+                                // "skipped" stamped on unreached nodes last pass), degraded
+                                // marks cleared, records reset via the bulk step:reset event.
+                                for (const internalStepId of internalStepIds) {
+                                    localStatuses.set(internalStepId, "idle");
+                                    degradedStepIds.delete(internalStepId);
+                                }
+                                await emit({
+                                    type: "step:reset",
+                                    runId,
+                                    scenarioId: scenario.id,
+                                    stepIds: internalStepIds,
+                                    at: new Date().toISOString(),
+                                    reason: `Item ${index + 1}/${processLimit}: reset foreach body`,
+                                });
+                                if (iterationDelayMs > 0) {
+                                    await waitForDuration(iterationDelayMs);
+                                }
+                            }
+                            // Fresh-pass isolation: a failed/short-circuited item must not
+                            // inherit the previous iteration's child outputs in its results
+                            // snapshot. The final iteration's children stay published after
+                            // the loop (last-iteration-wins for downstream reads).
+                            for (const childLabel of childLabels) {
+                                delete workflowRoots[childLabel];
+                            }
+                            const item = items[index];
+                            const frame = {
+                                index,
+                                iteration: index + 1,
+                                total: processLimit,
+                                remaining: processLimit - (index + 1),
+                            };
+                            workflowRoots.item = item;
+                            if (itemAlias) {
+                                workflowRoots[itemAlias] = item;
+                            }
+                            workflowRoots.each = frame;
+                            if (nodeLabelKey) {
+                                const eachesRoot = workflowRoots.eaches && typeof workflowRoots.eaches === "object"
+                                    ? workflowRoots.eaches
+                                    : {};
+                                workflowRoots.eaches = { ...eachesRoot, [nodeLabelKey]: frame };
+                            }
+                            if (index === 0 ||
+                                index === processLimit - 1 ||
+                                (index + 1) % iterationEmitStride === 0) {
+                                const itemPreview = (() => {
+                                    try {
+                                        const serialized = JSON.stringify(item);
+                                        if (typeof serialized !== "string")
+                                            return String(item);
+                                        return serialized.length > 2048 ? `${serialized.slice(0, 2048)}…` : serialized;
+                                    }
+                                    catch {
+                                        return null;
+                                    }
+                                })();
+                                await emit({
+                                    type: "step:iteration",
+                                    runId,
+                                    scenarioId: scenario.id,
+                                    stepId,
+                                    stepType: node.type,
+                                    title,
+                                    at: new Date().toISOString(),
+                                    index,
+                                    iteration: index + 1,
+                                    total: processLimit,
+                                    itemPreview,
+                                });
+                            }
+                            try {
+                                for (const startNodeId of internalGraph.startNodeIds) {
+                                    throwIfStopped(signal);
+                                    await executeNode(startNodeId, null, {}, internalScope);
+                                }
+                                await markScopeRemainingNodesSkipped(internalScope, `Internal node was not reached inside ${title} (item ${index + 1}).`);
+                            }
+                            catch (error) {
+                                if (error instanceof ScenarioStopError) {
+                                    throw error;
+                                }
+                                failedItems += 1;
+                                if (onItemFailure === "stop") {
+                                    const message = error instanceof Error ? error.message : String(error);
+                                    throw new ScenarioNodeFailureError(`Foreach item ${index + 1}/${processLimit} failed: ${message}`);
+                                }
+                                // continue: unreached internal nodes stay consistent for the
+                                // report, the run degrades to partial success below.
+                                await markScopeRemainingNodesSkipped(internalScope, `Internal node was not reached inside ${title} (item ${index + 1} failed).`);
+                            }
+                            if (collectResults) {
+                                const iterationOutput = {};
+                                for (const childLabel of childLabels) {
+                                    if (Object.prototype.hasOwnProperty.call(workflowRoots, childLabel)) {
+                                        iterationOutput[childLabel] = workflowRoots[childLabel];
+                                    }
+                                }
+                                results.push(iterationOutput);
+                            }
+                        }
+                    }
+                    finally {
+                        // Restore the enclosing iteration roots (or clear ours).
+                        if (hadItemRoot)
+                            workflowRoots.item = previousItemRoot;
+                        else
+                            delete workflowRoots.item;
+                        if (hadEachRoot)
+                            workflowRoots.each = previousEachRoot;
+                        else
+                            delete workflowRoots.each;
+                        if (itemAlias) {
+                            if (hadAliasRoot)
+                                workflowRoots[itemAlias] = previousAliasRoot;
+                            else
+                                delete workflowRoots[itemAlias];
+                        }
+                        if (typeof previousEaches === "undefined")
+                            delete workflowRoots.eaches;
+                        else
+                            workflowRoots.eaches = previousEaches;
+                    }
+                    shouldMarkPartialSuccess =
+                        degradedStepIds.size > degradedCountBefore || failedItems > 0;
+                    outputData = {
+                        ...(collectResults ? { results } : {}),
+                        itemCount: items.length,
+                        processedCount: processLimit,
+                        truncated: items.length > processLimit,
+                        failedItems,
+                    };
+                }
                 if (node.type === "end") {
                     if (node.data.config.loop && node.data.config.loopTargetNodeId) {
                         const loopTargetNode = scope.graph.nodeMap.get(node.data.config.loopTargetNodeId);