@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/assert/schema.js

@@ -1,6 +1,14 @@
 import { z } from 'zod';
+import { GRPC_STATUS_NAMES } from './status-names.js';
+import { CALLBACK_LIMITS } from './model.js';
 const name = z.string().min(1).optional();
-const statusValue = z.union([z.number().int().min(100).max(599), z.string().regex(/^[1-5]xx$/)]);
+const grpcStatusNames = Object.values(GRPC_STATUS_NAMES);
+const statusValue = z.union([
+    z.number().int().min(100).max(599),
+    z.number().int().min(0).max(16),
+    z.string().regex(/^[1-5]xx$/),
+    z.enum(grpcStatusNames),
+]);
 const statusSchema = z.looseObject({
     type: z.literal('status'),
     equals: z.union([statusValue, z.array(statusValue).min(1)]),
@@ -23,24 +31,158 @@ const matchSchema = z.looseObject({
 });
 const schemaSchema = z.looseObject({ type: z.literal('schema'), name });
 const slaSchema = z.looseObject({ type: z.literal('sla'), maxMs: z.number().int().positive(), name });
-const assertionSchema = z
-    .discriminatedUnion('type', [statusSchema, soapFaultSchema, matchSchema, schemaSchema, slaSchema])
-    .superRefine((value, ctx) => {
-    if (value.type !== 'match') {
-        return;
+const headerSchema = z.looseObject({
+    type: z.literal('header'),
+    header: z.string().min(1),
+    equals: z.string().optional(),
+    matches: z.string().optional(),
+    exists: z.boolean().optional(),
+    name,
+});
+function compiles(pattern, path, ctx) {
+    try {
+        // Compiling is linear in the pattern's length; only matching can run away, and that happens on
+        // the evaluation worker (`matchRegexWithTimeout`).
+        new RegExp(pattern);
     }
+    catch {
+        ctx.addIssue({ code: 'custom', path: [...path], message: 'not a valid regular expression' });
+    }
+}
+/** Exactly one of `equals`, `matches` or `exists`, and a `matches:` that compiles. */
+function refineOneCheck(value, ctx) {
     const given = [value.equals, value.matches, value.exists].filter((v) => v !== undefined).length;
     if (given !== 1) {
         ctx.addIssue({ code: 'custom', message: 'exactly one of equals, matches or exists is required' });
     }
     if (value.matches !== undefined) {
-        try {
-            new RegExp(value.matches);
-        }
-        catch {
-            ctx.addIssue({ code: 'custom', path: ['matches'], message: 'not a valid regular expression' });
-        }
+        compiles(value.matches, ['matches'], ctx);
+    }
+}
+/** A `match` or `header` assertion names exactly one check, and a `matches:` must compile. */
+function refineCheck(value, ctx) {
+    if (value.type === 'match' || value.type === 'header') {
+        refineOneCheck(value, ctx);
+    }
+}
+const oneCheck = {
+    equals: z.string().optional(),
+    matches: z.string().optional(),
+    exists: z.boolean().optional(),
+};
+const callbackHeaderSchema = z.looseObject({ name: z.string().min(1), ...oneCheck }).superRefine(refineOneCheck);
+const callbackBodySchema = z
+    .looseObject({ language: z.enum(['jsonpath', 'xpath']), path: z.string().min(1), ...oneCheck })
+    .superRefine(refineOneCheck);
+const callbackMatchSchema = z
+    .looseObject({
+    method: z.string().min(1).optional(),
+    path: z.string().startsWith('/').optional(),
+    pathMatches: z.string().min(1).optional(),
+    headers: z.array(callbackHeaderSchema).max(CALLBACK_LIMITS.maxHeaderChecks).optional(),
+    body: callbackBodySchema.optional(),
+})
+    .superRefine((value, ctx) => {
+    if (value.path !== undefined && value.pathMatches !== undefined) {
+        ctx.addIssue({ code: 'custom', message: 'at most one of path and pathMatches' });
+    }
+    if (value.pathMatches !== undefined) {
+        compiles(value.pathMatches, ['pathMatches'], ctx);
+    }
+});
+const callbackCheckSchema = z
+    .looseObject({
+    body: callbackBodySchema.optional(),
+    header: callbackHeaderSchema.optional(),
+    signature: z.literal('verified').optional(),
+})
+    .superRefine((value, ctx) => {
+    const given = [value.body, value.header, value.signature].filter((v) => v !== undefined).length;
+    if (given !== 1) {
+        ctx.addIssue({ code: 'custom', message: 'each expect entry is exactly one of body, header or signature' });
     }
 });
+/** `type: callback` (spec §2.1): the same shape on a request file and on a sequence step. */
+export const callbackAssertionSchema = z.looseObject({
+    type: z.literal('callback'),
+    catchUrl: z.string().min(1).max(CALLBACK_LIMITS.maxCatchUrlLength),
+    withinMs: z
+        .number()
+        .int()
+        .min(CALLBACK_LIMITS.minWithinMs)
+        .max(CALLBACK_LIMITS.maxWithinMs)
+        .default(CALLBACK_LIMITS.defaultWithinMs),
+    match: callbackMatchSchema.default({}),
+    expect: z.array(callbackCheckSchema).max(CALLBACK_LIMITS.maxExpectChecks).default([]),
+    name,
+});
+function checkOf(raw) {
+    return {
+        ...(raw.equals !== undefined ? { equals: raw.equals } : {}),
+        ...(raw.matches !== undefined ? { matches: raw.matches } : {}),
+        ...(raw.exists !== undefined ? { exists: raw.exists } : {}),
+    };
+}
+const toHeader = (raw) => ({
+    name: raw.name,
+    ...checkOf(raw),
+});
+const toBody = (raw) => ({
+    language: raw.language,
+    path: raw.path,
+    ...checkOf(raw),
+});
+function toCheck(check) {
+    if ('body' in check && check.body !== undefined)
+        return { body: toBody(check.body) };
+    if ('header' in check && check.header !== undefined)
+        return { header: toHeader(check.header) };
+    return { signature: 'verified' };
+}
+/**
+ * Only the fields a callback assertion defines, at every level. `looseObject` keeps unknown keys on
+ * the parsed value; dropping them here keeps them from being written back.
+ */
+export function toCallbackAssertion(raw) {
+    const match = raw.match;
+    return {
+        type: 'callback',
+        catchUrl: raw.catchUrl,
+        withinMs: raw.withinMs,
+        match: {
+            ...(match.method !== undefined ? { method: match.method } : {}),
+            ...(match.path !== undefined ? { path: match.path } : {}),
+            ...(match.pathMatches !== undefined ? { pathMatches: match.pathMatches } : {}),
+            ...(match.headers !== undefined ? { headers: match.headers.map(toHeader) } : {}),
+            ...(match.body !== undefined ? { body: toBody(match.body) } : {}),
+        },
+        expect: raw.expect.map(toCheck),
+        ...(raw.name !== undefined ? { name: raw.name } : {}),
+    };
+}
+const assertionSchema = z
+    .discriminatedUnion('type', [
+    statusSchema,
+    soapFaultSchema,
+    matchSchema,
+    schemaSchema,
+    slaSchema,
+    callbackAssertionSchema,
+])
+    .superRefine(refineCheck);
 /** The `assertions:` list of a request file. `looseObject` like every project schema; see `project/schema.ts`. */
 export const assertionsSchema = z.array(assertionSchema);
+/**
+ * The `assertions:` list of a sequence step: the request catalogue plus `header`.
+ */
+export const stepAssertionsSchema = z.array(z
+    .discriminatedUnion('type', [
+    statusSchema,
+    soapFaultSchema,
+    matchSchema,
+    schemaSchema,
+    slaSchema,
+    headerSchema,
+    callbackAssertionSchema,
+])
+    .superRefine(refineCheck));

package/dist/assert/status-names.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The status names a request file's `status` assertion may be written with.
+ *
+ * In `assert/` because the assertion file schema (`schema.ts`) lists them, and core imports no
+ * protocol folder (protocol modules spec §7.2). They are gRPC's; `grpc/status.ts` re-exports the
+ * table and keeps everything else about a status.
+ */
+/** The seventeen status codes. `0` is the only success. */
+export declare const GRPC_STATUS_NAMES: Readonly<Record<number, string>>;

package/dist/assert/status-names.js

@@ -0,0 +1,27 @@
+/**
+ * The status names a request file's `status` assertion may be written with.
+ *
+ * In `assert/` because the assertion file schema (`schema.ts`) lists them, and core imports no
+ * protocol folder (protocol modules spec §7.2). They are gRPC's; `grpc/status.ts` re-exports the
+ * table and keeps everything else about a status.
+ */
+/** The seventeen status codes. `0` is the only success. */
+export const GRPC_STATUS_NAMES = Object.freeze({
+    0: 'OK',
+    1: 'CANCELLED',
+    2: 'UNKNOWN',
+    3: 'INVALID_ARGUMENT',
+    4: 'DEADLINE_EXCEEDED',
+    5: 'NOT_FOUND',
+    6: 'ALREADY_EXISTS',
+    7: 'PERMISSION_DENIED',
+    8: 'RESOURCE_EXHAUSTED',
+    9: 'FAILED_PRECONDITION',
+    10: 'ABORTED',
+    11: 'OUT_OF_RANGE',
+    12: 'UNIMPLEMENTED',
+    13: 'INTERNAL',
+    14: 'UNAVAILABLE',
+    15: 'DATA_LOSS',
+    16: 'UNAUTHENTICATED',
+});

package/dist/assert/status.d.ts

@@ -1,3 +1,6 @@
 import type { AssertionResult, AssertionSubject, StatusAssertion } from './model.js';
-/** Checks the response status code against one or more expected values or `Nxx` classes. */
+/**
+ * Checks the response status against one or more expected values. A subject that carries
+ * `statusNames` is compared by exact code or by name; any other by HTTP code or `Nxx` class.
+ */
 export declare function evaluateStatus(subject: AssertionSubject, assertion: StatusAssertion): AssertionResult;

package/dist/assert/status.js

@@ -1,14 +1,38 @@
-function holds(expected, status) {
+/** The shape of a status name (`NOT_FOUND`), as opposed to an `Nxx` class. */
+const STATUS_NAME = /^[A-Z][A-Z_]*$/;
+function holdsHttp(expected, status) {
     return typeof expected === 'number' ? expected === status : Number(expected[0]) === Math.floor(status / 100);
 }
-/** Checks the response status code against one or more expected values or `Nxx` classes. */
+/**
+ * Checks the response status against one or more expected values. A subject that carries
+ * `statusNames` is compared by exact code or by name; any other by HTTP code or `Nxx` class.
+ */
 export function evaluateStatus(subject, assertion) {
     const expected = typeof assertion.equals === 'number' || typeof assertion.equals === 'string'
         ? [assertion.equals]
         : assertion.equals;
     const text = expected.join(' or ');
     const base = { type: 'status', label: assertion.name ?? `status is ${text}` };
-    return expected.some((value) => holds(value, subject.status))
+    const names = subject.statusNames;
+    if (names !== undefined) {
+        const unknownName = expected.find((value) => typeof value === 'string' && !names.byName.has(value));
+        if (unknownName !== undefined) {
+            return { ...base, outcome: 'errored', message: `${String(unknownName)} is not a gRPC status name` };
+        }
+        const matched = expected.some((value) => typeof value === 'number' ? value === subject.status : names.byName.get(value) === subject.status);
+        return matched
+            ? { ...base, outcome: 'passed' }
+            : { ...base, outcome: 'failed', expected: text, actual: names.nameOf(subject.status) };
+    }
+    const statusName = expected.find((value) => typeof value === 'string' && STATUS_NAME.test(value));
+    if (statusName !== undefined) {
+        return { ...base, outcome: 'errored', message: `${String(statusName)} is a gRPC status name, not an HTTP one` };
+    }
+    const notHttp = expected.find((value) => typeof value === 'number' && value < 100);
+    if (notHttp !== undefined) {
+        return { ...base, outcome: 'errored', message: `${String(notHttp)} is not an HTTP status` };
+    }
+    return expected.some((value) => holdsHttp(value, subject.status))
         ? { ...base, outcome: 'passed' }
         : { ...base, outcome: 'failed', expected: text, actual: String(subject.status) };
 }

package/dist/asyncapi/browser.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The browser-safe face of `asyncapi/`: the model's types, with no Node dependency, reachable from
+ * the renderer as `@wirebench/engine/asyncapi`. Parsing stays engine-side, because the reference
+ * policy it resolves under reads the file system.
+ */
+export type { AsyncApiChannel, AsyncApiChannelParameter, AsyncApiDocument, AsyncApiMessage, AsyncApiOperation, AsyncApiSecurityScheme, AsyncApiServer, AsyncApiSkip, AsyncApiVersion, } from './model.js';
+export type { AsyncApiImportSummary } from './map.js';

package/dist/asyncapi/browser.js

@@ -0,0 +1,6 @@
+/**
+ * The browser-safe face of `asyncapi/`: the model's types, with no Node dependency, reachable from
+ * the renderer as `@wirebench/engine/asyncapi`. Parsing stays engine-side, because the reference
+ * policy it resolves under reads the file system.
+ */
+export {};

package/dist/asyncapi/frame-check-worker-host.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Live frame checking off the calling thread.
+ *
+ * {@link checkFrame} is synchronous and a contract's `pattern` is untrusted: its own time budget
+ * stops a check between messages, but one regex call that runs away cannot be interrupted from the
+ * thread it runs on. So the checks run in a `worker_threads` Worker, one frame at a time, each under
+ * a hard deadline: a worker that has not answered by then is terminated, the frame is reported
+ * `not-checked`, and a fresh worker is started for the next frame. The caller's thread (Electron's
+ * main process) never runs a check itself.
+ */
+import type { WsFrame, WsFrameContract } from '../ws/model.js';
+import { type ChannelMessages } from './frame-check.js';
+/** How long one frame's check may take, worker round trip included, before the worker is replaced. */
+export declare const DEFAULT_FRAME_CHECK_DEADLINE_MS = 1000;
+/** How many frames may wait behind the one being checked before new ones are not checked at all. */
+export declare const DEFAULT_FRAME_CHECK_QUEUE = 1000;
+/** Payload bytes that may wait to be checked; a frame that would pass it is not checked at all. */
+export declare const DEFAULT_FRAME_CHECK_QUEUE_BYTES: number;
+export interface WorkerFrameCheckerOptions {
+    /** Milliseconds one frame's check may take before the worker is terminated and replaced. */
+    readonly deadlineMs?: number;
+    /** The in-check budget passed to {@link checkFrame}; below the deadline, it ends a slow check cleanly. */
+    readonly budgetMs?: number;
+    /** Frames that may wait behind the one being checked. */
+    readonly maxQueued?: number;
+    /** Payload bytes that may wait behind the frame being checked. */
+    readonly maxQueuedBytes?: number;
+    /** The worker script; tests substitute one. Defaults to the compiled `frame-check-worker.js`. */
+    readonly workerUrl?: URL;
+}
+export interface WorkerFrameChecker {
+    /**
+     * The frame's contract result. `undefined` for a frame no contract speaks to (binary, control)
+     * and for any frame after {@link dispose}. Never rejects.
+     */
+    check(frame: WsFrame): Promise<WsFrameContract | undefined>;
+    /** Terminates the worker; a check still waiting resolves `not-checked`. */
+    dispose(): Promise<void>;
+    /** Workers started so far (a replaced one counts again). */
+    readonly spawned: number;
+    /** Whether a worker is currently alive. */
+    readonly running: boolean;
+}
+export declare function createWorkerFrameChecker(messages: ChannelMessages, options?: WorkerFrameCheckerOptions): WorkerFrameChecker;

package/dist/asyncapi/frame-check-worker-host.js

@@ -0,0 +1,175 @@
+/**
+ * Live frame checking off the calling thread.
+ *
+ * {@link checkFrame} is synchronous and a contract's `pattern` is untrusted: its own time budget
+ * stops a check between messages, but one regex call that runs away cannot be interrupted from the
+ * thread it runs on. So the checks run in a `worker_threads` Worker, one frame at a time, each under
+ * a hard deadline: a worker that has not answered by then is terminated, the frame is reported
+ * `not-checked`, and a fresh worker is started for the next frame. The caller's thread (Electron's
+ * main process) never runs a check itself.
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { MAX_CHECKED_FRAME_BYTES } from './frame-check.js';
+/** How long one frame's check may take, worker round trip included, before the worker is replaced. */
+export const DEFAULT_FRAME_CHECK_DEADLINE_MS = 1_000;
+/** How many frames may wait behind the one being checked before new ones are not checked at all. */
+export const DEFAULT_FRAME_CHECK_QUEUE = 1_000;
+/** Payload bytes that may wait to be checked; a frame that would pass it is not checked at all. */
+export const DEFAULT_FRAME_CHECK_QUEUE_BYTES = 8 * 1024 * 1024;
+/**
+ * The compiled worker script: the sibling `.js` when running from `dist`, else — running from `src`
+ * under vitest — the package's `dist/asyncapi/frame-check-worker.js`, as `xpath/evaluate-async.ts`
+ * resolves its own worker.
+ */
+function defaultWorkerUrl() {
+    const sibling = new URL('./frame-check-worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(sibling))) {
+        return sibling;
+    }
+    const fallback = import.meta.url.replace(/\/src\/asyncapi\/frame-check-worker-host\.ts$/, '/dist/asyncapi/frame-check-worker.js');
+    /* v8 ignore next 3 -- only reachable when the engine package has never been built */
+    if (fallback === import.meta.url) {
+        throw new Error('frame-check worker not found: build the engine package first');
+    }
+    return new URL(fallback);
+}
+const notChecked = (reason) => ({ status: 'not-checked', reason });
+export function createWorkerFrameChecker(messages, options = {}) {
+    const deadlineMs = options.deadlineMs ?? DEFAULT_FRAME_CHECK_DEADLINE_MS;
+    const maxQueued = options.maxQueued ?? DEFAULT_FRAME_CHECK_QUEUE;
+    const maxQueuedBytes = options.maxQueuedBytes ?? DEFAULT_FRAME_CHECK_QUEUE_BYTES;
+    let queuedBytes = 0;
+    const data = {
+        messages,
+        ...(options.budgetMs !== undefined ? { budgetMs: options.budgetMs } : {}),
+    };
+    let url = options.workerUrl;
+    let worker;
+    let spawned = 0;
+    let disposed = false;
+    let nextId = 0;
+    let current;
+    let timer;
+    const queue = [];
+    const finish = (contract) => {
+        const job = current;
+        if (job === undefined)
+            return;
+        current = undefined;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        job.resolve(contract);
+        pump();
+    };
+    /** Drops the current worker without waiting for it; its late answer or exit is then ignored. */
+    const discard = () => {
+        const dead = worker;
+        worker = undefined;
+        if (dead !== undefined) {
+            dead.removeAllListeners();
+            // An 'error' after the listeners are gone would otherwise be an uncaught exception.
+            dead.on('error', () => undefined);
+            void dead.terminate();
+        }
+    };
+    const spawn = () => {
+        url ??= defaultWorkerUrl();
+        const next = new Worker(url, { workerData: data });
+        spawned += 1;
+        // A session's checker must never be what keeps the process alive.
+        next.unref();
+        next.on('message', (answer) => {
+            if (current?.id === answer.id)
+                finish(answer.contract ?? undefined);
+        });
+        const failed = (why) => {
+            if (worker !== next)
+                return;
+            discard();
+            finish(notChecked(why));
+        };
+        next.on('error', (error) => {
+            failed(`the check failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        next.on('exit', () => {
+            failed('the check stopped unexpectedly');
+        });
+        return next;
+    };
+    function pump() {
+        if (current !== undefined || disposed)
+            return;
+        const job = queue.shift();
+        if (job === undefined)
+            return;
+        queuedBytes -= job.frame.size;
+        current = job;
+        try {
+            worker ??= spawn();
+            worker.postMessage({ id: job.id, frame: job.frame });
+        }
+        catch (error) {
+            discard();
+            finish(notChecked(`the check could not start: ${error instanceof Error ? error.message : String(error)}`));
+            return;
+        }
+        // The deadline starts when this frame reaches the worker, not when it was queued, so one stuck
+        // frame never costs the frames behind it their check.
+        timer = setTimeout(() => {
+            discard();
+            finish(notChecked(`the check took longer than ${String(deadlineMs)} ms`));
+        }, deadlineMs);
+        timer.unref?.();
+    }
+    return {
+        check(frame) {
+            if (disposed || frame.opcode !== 'text' || frame.text === undefined)
+                return Promise.resolve(undefined);
+            // Answered here, as the worker would: a frame this large is never walked, so it must not wait
+            // behind others or count against the queued-bytes bound.
+            if (frame.size > MAX_CHECKED_FRAME_BYTES) {
+                return Promise.resolve({ status: 'skipped', reason: 'frame too large to check' });
+            }
+            if (queue.length >= maxQueued)
+                return Promise.resolve(notChecked('too many frames waiting to be checked'));
+            if (queue.length > 0 && queuedBytes + frame.size > maxQueuedBytes) {
+                return Promise.resolve(notChecked('too much data waiting to be checked'));
+            }
+            return new Promise((resolve) => {
+                nextId += 1;
+                queue.push({ id: nextId, frame, resolve });
+                queuedBytes += frame.size;
+                pump();
+            });
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const dead = worker;
+            worker = undefined;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+            const waiting = [...(current !== undefined ? [current] : []), ...queue.splice(0)];
+            queuedBytes = 0;
+            current = undefined;
+            for (const job of waiting)
+                job.resolve(notChecked('the session ended'));
+            if (dead !== undefined) {
+                dead.removeAllListeners();
+                dead.on('error', () => undefined);
+                await dead.terminate();
+            }
+        },
+        get spawned() {
+            return spawned;
+        },
+        get running() {
+            return worker !== undefined;
+        },
+    };
+}

package/dist/asyncapi/frame-check-worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link createWorkerFrameChecker}. Its
+ * `workerData` is the channel's messages and the in-check time budget; each message in is one frame
+ * (`{ id, frame }`) and each message out its result (`{ id, contract }`, `null` for a frame no
+ * contract speaks to). Frames are checked one at a time, in the order they arrive.
+ */
+import { type ChannelMessages } from './frame-check.js';
+/** What the host passes as `workerData`. */
+export interface FrameCheckWorkerData {
+    readonly messages: ChannelMessages;
+    readonly budgetMs?: number;
+}

package/dist/asyncapi/frame-check-worker.js

@@ -0,0 +1,25 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link createWorkerFrameChecker}. Its
+ * `workerData` is the channel's messages and the in-check time budget; each message in is one frame
+ * (`{ id, frame }`) and each message out its result (`{ id, contract }`, `null` for a frame no
+ * contract speaks to). Frames are checked one at a time, in the order they arrive.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import { checkFrame } from './frame-check.js';
+/* v8 ignore start -- runs only inside a real worker thread; covered end to end by
+   frame-check-worker.test.ts, which coverage instrumentation does not follow across the thread. */
+if (parentPort !== null) {
+    const port = parentPort;
+    const data = workerData;
+    port.on('message', ({ id, frame }) => {
+        let contract;
+        try {
+            contract = checkFrame(frame, data.messages[frame.direction], data.budgetMs !== undefined ? { budgetMs: data.budgetMs } : {});
+        }
+        catch (error) {
+            contract = { status: 'not-checked', reason: error instanceof Error ? error.message : String(error) };
+        }
+        port.postMessage({ id, contract: contract ?? null });
+    });
+}
+/* v8 ignore stop */

package/dist/asyncapi/frame-check.d.ts

@@ -0,0 +1,25 @@
+import type { WsFrame, WsFrameContract } from '../ws/model.js';
+import type { AsyncApiDocument, AsyncApiMessage } from './model.js';
+/** A text frame bigger than this is not parsed or validated: it is reported `skipped`. */
+export declare const MAX_CHECKED_FRAME_BYTES = 262144;
+/** The default time one frame's check may take before it gives up as `not-checked`. */
+export declare const DEFAULT_FRAME_CHECK_BUDGET_MS = 50;
+export type FrameChecker = (frame: WsFrame) => WsFrameContract | undefined;
+export interface FrameCheckOptions {
+    /** Milliseconds one frame's check may take; past it the result is `not-checked`. */
+    readonly budgetMs?: number;
+    /** The clock, injectable for tests; defaults to `performance.now`. */
+    readonly now?: () => number;
+}
+/** The messages a channel declares for each of Wirebench's directions — plain data, serialisable. */
+export interface ChannelMessages {
+    readonly sent: readonly AsyncApiMessage[];
+    readonly received: readonly AsyncApiMessage[];
+}
+export declare function channelMessages(document: AsyncApiDocument, channel: string): ChannelMessages;
+export declare function createFrameChecker(document: AsyncApiDocument, channel: string, options?: FrameCheckOptions): FrameChecker;
+/**
+ * Checks one frame against `messages` (the ones declared for the frame's direction). Returns
+ * `undefined` for a frame no contract speaks to (binary and control frames).
+ */
+export declare function checkFrame(frame: WsFrame, messages: readonly AsyncApiMessage[], options?: FrameCheckOptions): WsFrameContract | undefined;

package/dist/asyncapi/frame-check.js

@@ -0,0 +1,78 @@
+/**
+ * Checks each live WebSocket frame against the messages its channel's contract declares for that
+ * direction.
+ *
+ * Everything here is pure and synchronous, and {@link checkFrame} takes and returns plain data, so a
+ * caller can run it in a worker. That matters because a contract's `pattern` is untrusted: the
+ * validator refuses the regex shapes known to backtrack badly, but that scan is a heuristic, and a
+ * single regex call cannot be interrupted from the same thread. The time budget here stops the
+ * check between messages and reports `not-checked` — neither a pass nor a failure — and the worker
+ * is what bounds a single call that runs away.
+ */
+import { validateJsonSchema } from '../json/schema-validate.js';
+/** A text frame bigger than this is not parsed or validated: it is reported `skipped`. */
+export const MAX_CHECKED_FRAME_BYTES = 262_144;
+/** The default time one frame's check may take before it gives up as `not-checked`. */
+export const DEFAULT_FRAME_CHECK_BUDGET_MS = 50;
+export function channelMessages(document, channel) {
+    const pick = (direction) => document.operations.filter((o) => o.channel === channel && o.direction === direction).flatMap((o) => o.messages);
+    return { sent: pick('sent'), received: pick('received') };
+}
+export function createFrameChecker(document, channel, options) {
+    const messages = channelMessages(document, channel);
+    return (frame) => checkFrame(frame, messages[frame.direction], options);
+}
+function isJsonContentType(contentType) {
+    const base = contentType.split(';')[0].trim().toLowerCase();
+    return base === '' || base === 'application/json' || base.endsWith('+json') || base === 'text/json';
+}
+/**
+ * Checks one frame against `messages` (the ones declared for the frame's direction). Returns
+ * `undefined` for a frame no contract speaks to (binary and control frames).
+ */
+export function checkFrame(frame, messages, options) {
+    if (frame.opcode !== 'text' || frame.text === undefined)
+        return undefined;
+    if (frame.size > MAX_CHECKED_FRAME_BYTES)
+        return { status: 'skipped', reason: 'frame too large to check' };
+    if (messages.length === 0)
+        return { status: 'unmatched', reason: `no ${frame.direction} messages in the contract` };
+    const json = messages.filter((m) => isJsonContentType(m.contentType));
+    if (json.length === 0)
+        return { status: 'skipped', reason: 'no JSON message to check against' };
+    let value;
+    try {
+        value = JSON.parse(frame.text);
+    }
+    catch {
+        return { status: 'violation', message: json[0].name, reason: 'not JSON' };
+    }
+    const now = options?.now ?? (() => performance.now());
+    const budgetMs = options?.budgetMs ?? DEFAULT_FRAME_CHECK_BUDGET_MS;
+    const start = now();
+    let closest;
+    // A message whose check stopped on the node or depth cap with nothing wrong found so far: the
+    // frame may well be that message, so it is neither the closest violation nor a match.
+    let undecided;
+    for (const message of json) {
+        if (now() - start > budgetMs)
+            return { status: 'not-checked', reason: 'time budget exceeded' };
+        const problems = message.payload === undefined ? [] : validateJsonSchema(value, message.payload);
+        if (problems.length > 0 && problems.every((p) => p.keyword === 'budget')) {
+            undecided ??= problems[0].message;
+            continue;
+        }
+        if (problems.length === 0) {
+            if (now() - start > budgetMs)
+                return { status: 'not-checked', reason: 'time budget exceeded' };
+            return { status: 'ok', message: message.name };
+        }
+        if (closest === undefined || problems.length < closest.problems.length)
+            closest = { name: message.name, problems };
+    }
+    if (now() - start > budgetMs)
+        return { status: 'not-checked', reason: 'time budget exceeded' };
+    if (undecided !== undefined)
+        return { status: 'not-checked', reason: undecided };
+    return { status: 'violation', message: closest.name, problems: closest.problems };
+}