@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/sequence/run.js

@@ -0,0 +1,191 @@
+/**
+ * Running a sequence: the loop, the transfers and the assertions, with the same semantics wherever it
+ * runs. Sending stays with the host (the CLI through `createRunSender`, the desktop through its own send
+ * paths and History), because the two send with different secrets, auth flows and cookie jars.
+ *
+ * Values lifted from responses reach the next step only through the `sequence` scope the host passes to
+ * its expanders, where ADR-0015's rules apply: literal, explicit, escaped, never the origin.
+ */
+import { isCallbackAssertion, sendAwaitingCallbacks } from '../assert/callback.js';
+import { evaluateAssertions } from '../assert/index.js';
+import { isWirebenchError } from '../errors.js';
+import { findStepRequest } from '../run/select.js';
+import { extractTransfer } from './transfer.js';
+import { mergeScriptValues, scriptAssertions } from '../run/script-support.js';
+/** Carries a step the host could not send out of `sendAwaitingCallbacks`, so no wait follows it. */
+class NotSent extends Error {
+    failure;
+    constructor(failure) {
+        super(failure.error.message);
+        this.failure = failure;
+    }
+}
+const RANK = { skipped: 0, passed: 1, failed: 2, errored: 3 };
+function worst(outcomes) {
+    return outcomes.reduce((a, b) => (RANK[b] > RANK[a] ? b : a), 'skipped');
+}
+function stepName(step, selected) {
+    return step.name ?? selected?.request.name ?? step.requestId;
+}
+function requestAssertionsOf(selected) {
+    return ('assertions' in selected.request ? selected.request.assertions : undefined) ?? [];
+}
+/**
+ * Runs `sequence` against `project`, sending each step through `send`. Never throws: every failure,
+ * a throwing sender included, is an errored step. A step after an abort, after a failure under
+ * `stopOnFailure`, or disabled, is `skipped` and never sent.
+ */
+export async function runSequence(sequence, project, send, options = {}) {
+    const startedAt = (options.now ?? (() => new Date()))().toISOString();
+    const signal = options.signal ?? new AbortController().signal;
+    // A Map, not an object: a transfer may legitimately be named `__proto__` or `constructor`.
+    const values = new Map();
+    const steps = [];
+    let stopped = false;
+    const finish = (result) => {
+        steps.push(result);
+        options.onStepDone?.(result);
+        if (sequence.settings.stopOnFailure && (result.outcome === 'failed' || result.outcome === 'errored')) {
+            stopped = true;
+        }
+    };
+    for (const [index, step] of sequence.steps.entries()) {
+        const target = findStepRequest(project, step.requestId, options.registry);
+        const selected = target.kind === 'found' ? target.selected : undefined;
+        const base = {
+            index,
+            stepId: step.id,
+            requestId: step.requestId,
+            name: stepName(step, selected),
+            ...(selected !== undefined ? { protocol: selected.kind } : {}),
+            assertions: [],
+            transfers: [],
+        };
+        const skip = signal.aborted ? 'cancelled' : stopped ? 'after-failure' : !step.enabled ? 'disabled' : undefined;
+        if (skip !== undefined) {
+            // A skipped step never ends the run early by itself; only a failure does.
+            steps.push({ ...base, outcome: 'skipped', skipped: skip });
+            options.onStepDone?.(steps[steps.length - 1]);
+            continue;
+        }
+        if (target.kind === 'missing') {
+            finish({
+                ...base,
+                outcome: 'errored',
+                error: { code: 'sequence-step-missing-request', message: `The request ${step.requestId} no longer exists` },
+            });
+            continue;
+        }
+        if (target.kind === 'unsupported') {
+            finish({ ...base, outcome: 'errored', error: { code: 'sequence-step-unsupported', message: target.reason } });
+            continue;
+        }
+        const resolved = {
+            index,
+            step,
+            selected: target.selected,
+            ...(sequence.settings.stepTimeoutMs !== undefined ? { timeoutMs: sequence.settings.stepTimeoutMs } : {}),
+        };
+        const sequenceScope = Object.fromEntries(values);
+        const stepAssertions = [
+            ...(step.requestAssertions ? requestAssertionsOf(target.selected) : []),
+            ...step.assertions,
+        ];
+        let sent;
+        let callbacks = [];
+        try {
+            // The cursor is taken inside this helper, before the send (§2.3 step 1).
+            const awaited = await sendAwaitingCallbacks(stepAssertions, () => options.callbackScopes?.(resolved, sequenceScope) ?? {
+                project: {},
+                global: {},
+                system: {},
+                sequence: sequenceScope,
+            }, async () => {
+                const result = await send(resolved, sequenceScope, signal);
+                if ('error' in result)
+                    throw new NotSent(result);
+                return result;
+            }, {
+                ...(options.captures !== undefined ? { captures: options.captures } : {}),
+                ...(options.callbackClock !== undefined ? { clock: options.callbackClock } : {}),
+                ...(options.callbackPollMs !== undefined ? { pollIntervalMs: options.callbackPollMs } : {}),
+                signal,
+                onWaiting: (waiting) => options.onCallbackWaiting?.({ index, stepId: step.id, name: base.name }, waiting),
+            });
+            sent = awaited.sent;
+            callbacks = awaited.callbacks;
+        }
+        catch (error) {
+            sent =
+                error instanceof NotSent
+                    ? error.failure
+                    : {
+                        error: {
+                            code: isWirebenchError(error) ? error.code : 'internal-error',
+                            message: error instanceof Error ? error.message : String(error),
+                        },
+                    };
+        }
+        if ('error' in sent) {
+            finish({ ...base, outcome: 'errored', error: sent.error });
+            continue;
+        }
+        const { subject, script } = sent;
+        // A script's values join the run's before the step's own transfers, which win on a clash (#63).
+        mergeScriptValues(values, script?.values ?? [], options.onSecretValue, options.containsKnownSecret);
+        const transfers = [];
+        let transferError;
+        for (const transfer of step.transfers) {
+            const found = await extractTransfer(subject, transfer);
+            if (found.kind === 'value') {
+                const secret = transfer.secret === true || options.containsKnownSecret?.(found.value) === true;
+                if (secret) {
+                    options.onSecretValue?.(found.value);
+                }
+                values.set(transfer.name, found.value);
+                transfers.push({ name: transfer.name, outcome: 'set', secret, ...(secret ? {} : { value: found.value }) });
+                continue;
+            }
+            const secret = transfer.secret === true;
+            if (found.kind === 'missing') {
+                transfers.push({ name: transfer.name, outcome: 'missing', secret });
+                if (transfer.optional !== true) {
+                    transferError ??= {
+                        code: 'sequence-transfer-missing',
+                        message: `${transfer.name}: the response had nothing there`,
+                    };
+                }
+                continue;
+            }
+            transfers.push({ name: transfer.name, outcome: 'errored', secret, message: found.message });
+            transferError ??= { code: found.code, message: `${transfer.name}: ${found.message}` };
+        }
+        const immediate = await evaluateAssertions(subject, stepAssertions.filter((assertion) => !isCallbackAssertion(assertion)));
+        const assertions = [...immediate, ...callbacks, ...scriptAssertions(script?.tests ?? [])];
+        transferError ??= script?.error;
+        const outcome = transferError !== undefined || assertions.some((a) => a.outcome === 'errored')
+            ? 'errored'
+            : assertions.some((a) => a.outcome === 'failed')
+                ? 'failed'
+                : 'passed';
+        finish({
+            ...base,
+            outcome,
+            status: subject.status,
+            durationMs: subject.durationMs,
+            ...(sent.origin !== undefined ? { origin: sent.origin } : {}),
+            assertions,
+            transfers,
+            ...(transferError !== undefined ? { error: transferError } : {}),
+            ...(script !== undefined && script.log.lines.length > 0 ? { scriptLog: script.log.lines } : {}),
+            ...(sent.scriptsOff === true ? { scriptsOff: true } : {}),
+        });
+    }
+    return {
+        sequenceId: sequence.id,
+        name: sequence.name,
+        startedAt,
+        outcome: worst(steps.map((s) => s.outcome)),
+        steps,
+    };
+}

package/dist/sequence/transfer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lifting one value out of a step's response. Body expressions go through the same hardened path as
+ * assertions (`fontoxpath`, `jsonpath-plus` in its safe mode, both on a worker with a time budget), so
+ * nothing in a sequence file is evaluated any other way (ADR-0015, spec Rule 7).
+ */
+import type { AssertionSubject } from '../assert/model.js';
+import type { Transfer } from './model.js';
+/** What one transfer found. */
+export type ExtractedValue = {
+    readonly kind: 'value';
+    readonly value: string;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'error';
+    readonly code: string;
+    readonly message: string;
+};
+/**
+ * Evaluates one transfer against a response. Never throws. A value over
+ * {@link SEQUENCE_LIMITS.valueBytes} is an error rather than a value, so a server cannot make a run
+ * hold (or send onward) more than that per name.
+ */
+export declare function extractTransfer(subject: AssertionSubject, transfer: Transfer): Promise<ExtractedValue>;

package/dist/sequence/transfer.js

@@ -0,0 +1,75 @@
+/**
+ * Lifting one value out of a step's response. Body expressions go through the same hardened path as
+ * assertions (`fontoxpath`, `jsonpath-plus` in its safe mode, both on a worker with a time budget), so
+ * nothing in a sequence file is evaluated any other way (ADR-0015, spec Rule 7).
+ */
+import { firstHeaderValue } from '../assert/header.js';
+import { firstText } from '../assert/match.js';
+import { parseSetCookie } from '../http/cookies.js';
+import { evaluateWithTimeout } from '../xpath/evaluate-async.js';
+import { collectNamespaces } from '../xpath/namespaces.js';
+import { SEQUENCE_LIMITS } from './model.js';
+/** The response's own prefix bindings, or none when the body is not XML that parses. */
+function defaultNamespaces(bodyText) {
+    try {
+        return collectNamespaces(bodyText);
+    }
+    catch {
+        return {};
+    }
+}
+async function fromBody(subject, transfer) {
+    const wantsJson = transfer.language === 'jsonpath';
+    if (wantsJson && subject.bodyKind !== 'json') {
+        return { kind: 'error', code: 'sequence-transfer-failed', message: 'jsonpath needs a JSON response body' };
+    }
+    if (!wantsJson && subject.bodyKind === 'other') {
+        return {
+            kind: 'error',
+            code: 'sequence-transfer-failed',
+            message: `${transfer.language} needs an XML or JSON response body`,
+        };
+    }
+    const namespaces = transfer.namespaces ?? (subject.bodyKind === 'xml' && !wantsJson ? defaultNamespaces(subject.bodyText) : undefined);
+    const result = await evaluateWithTimeout(subject.bodyText, transfer.expression, { language: transfer.language, ...(namespaces !== undefined ? { namespaces } : {}) }, { kind: subject.bodyKind === 'json' ? 'json' : 'xml' });
+    if (result.kind === 'error') {
+        return { kind: 'error', code: 'sequence-transfer-failed', message: result.message };
+    }
+    const text = firstText(result);
+    return text === undefined ? { kind: 'missing' } : { kind: 'value', value: text };
+}
+/**
+ * Evaluates one transfer against a response. Never throws. A value over
+ * {@link SEQUENCE_LIMITS.valueBytes} is an error rather than a value, so a server cannot make a run
+ * hold (or send onward) more than that per name.
+ */
+export async function extractTransfer(subject, transfer) {
+    let found;
+    switch (transfer.from) {
+        case 'body':
+            found = await fromBody(subject, transfer);
+            break;
+        case 'header': {
+            const value = firstHeaderValue(subject.headers, transfer.header);
+            found = value === undefined ? { kind: 'missing' } : { kind: 'value', value };
+            break;
+        }
+        case 'status':
+            found = { kind: 'value', value: String(subject.status) };
+            break;
+        case 'cookie': {
+            const set = parseSetCookie(subject.headers ?? []).filter((cookie) => cookie.malformed !== true && cookie.name === transfer.cookie);
+            const last = set[set.length - 1];
+            found = last === undefined ? { kind: 'missing' } : { kind: 'value', value: last.value };
+            break;
+        }
+    }
+    if (found.kind === 'value' && Buffer.byteLength(found.value, 'utf8') > SEQUENCE_LIMITS.valueBytes) {
+        return {
+            kind: 'error',
+            code: 'sequence-value-too-large',
+            message: `${transfer.name} is larger than ${SEQUENCE_LIMITS.valueBytes} bytes`,
+        };
+    }
+    return found;
+}