@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/redact/index.js

@@ -13,14 +13,30 @@ export function containsRedaction(text) {
 }
 /** Header names (case-insensitive) whose value is always masked. */
 const SENSITIVE_HEADERS = new Set(['authorization', 'proxy-authorization', 'cookie', 'set-cookie', 'x-api-key']);
-/** Masks the values of sensitive headers in a plain header map, case-insensitively. */
+/** True when a header named `name` (any case) always carries a credential; see {@link redactHeaders}. */
+export function isSensitiveHeaderName(name) {
+    return SENSITIVE_HEADERS.has(name.toLowerCase());
+}
+/**
+ * The test every header redactor applies: a well-known credential header, or one of `extraHeaders`
+ * — the name an API key was configured under, which may be anything (`Ocp-Apim-Subscription-Key`).
+ * Both compared case-insensitively.
+ */
+function headerIsMasked(name, extraHeaders) {
+    const lower = name.toLowerCase();
+    return SENSITIVE_HEADERS.has(lower) || (extraHeaders?.some((extra) => extra.toLowerCase() === lower) ?? false);
+}
+/**
+ * Masks the values of sensitive headers in a plain header map, case-insensitively. `extraHeaders`
+ * names more headers to mask, as `redactUrl`'s `extraParams` does for query parameters.
+ */
 export function redactHeaders(headers, opts) {
     if (opts?.show) {
         return { ...headers };
     }
     const result = {};
     for (const [name, value] of Object.entries(headers)) {
-        result[name] = SENSITIVE_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
+        result[name] = headerIsMasked(name, opts?.extraHeaders) ? REDACTED : value;
     }
     return result;
 }
@@ -31,7 +47,7 @@ export function redactHeaders(headers, opts) {
  */
 export function redactHeaderPairs(pairs, opts) {
     const show = opts?.show ?? false;
-    return pairs.map(([name, value]) => [name, !show && SENSITIVE_HEADERS.has(name.toLowerCase()) ? REDACTED : value]);
+    return pairs.map(([name, value]) => [name, !show && headerIsMasked(name, opts?.extraHeaders) ? REDACTED : value]);
 }
 /**
  * Query-parameter names (case-insensitive) whose value is masked wherever a URL is logged, stored
@@ -50,6 +66,10 @@ const SENSITIVE_QUERY_PARAMS = new Set([
     'signature',
     'sig',
 ]);
+/** True when a query parameter named `name` (any case) carries a credential; see {@link redactUrl}. */
+export function isSensitiveQueryParam(name) {
+    return SENSITIVE_QUERY_PARAMS.has(name.toLowerCase());
+}
 /**
  * Masks the value of every sensitive query parameter in `url`, plus any parameter named in
  * `extraParams` — which is how the send path masks the exact parameter an API key is configured to
@@ -86,6 +106,31 @@ export function redactUrl(url, opts) {
     // untouched URL is returned as it came in rather than as the parser would have written it.
     return changed ? parsed.toString() : url;
 }
+/**
+ * Masks the query of a raw request line (`GET /calc?key=secret HTTP/1.1`) by the same rules as
+ * {@link redactUrl}, `extraParams` included. The target is usually origin-form (a path), so it is
+ * parsed against a placeholder origin and the origin taken off again. Anything that is not a
+ * request line — a response's status line, a header — is returned unchanged.
+ */
+function redactRequestLine(line, extraParams) {
+    // Split rather than matched with one pattern: `\S*\?\S*` backtracks polynomially on a line of `?`s.
+    const parts = line.split(' ');
+    if (parts.length !== 3) {
+        return line;
+    }
+    const [method = '', target = '', version = ''] = parts;
+    if (method === '' || !target.includes('?') || !/^HTTP\/\d(?:\.\d)?$/.test(version)) {
+        return line;
+    }
+    const originForm = target.startsWith('/');
+    const base = 'http://request-line.invalid';
+    const url = originForm ? `${base}${target}` : target;
+    const redacted = redactUrl(url, { extraParams: extraParams ?? [] });
+    if (redacted === url) {
+        return line;
+    }
+    return `${method} ${originForm ? redacted.slice(base.length) : redacted} ${version}`;
+}
 /**
  * The redaction pass for a response's attachment list. Nothing in `{index, contentId,
  * contentType, size, name}` carries a secret today, so this is a copy — it exists as the one
@@ -235,13 +280,12 @@ export function redactStructuredBody(text, contentType, opts) {
     return text;
 }
 /** Masks a single raw `name: value` header line (no terminator), case-insensitively. */
-function redactHeaderLine(line) {
+function redactHeaderLine(line, extraHeaders) {
     const idx = line.indexOf(':');
     if (idx < 0) {
         return line;
     }
-    const name = line.slice(0, idx).trim().toLowerCase();
-    if (!SENSITIVE_HEADERS.has(name)) {
+    if (!headerIsMasked(line.slice(0, idx).trim(), extraHeaders)) {
         return line;
     }
     return `${line.slice(0, idx + 1)} ${REDACTED}`;
@@ -305,7 +349,11 @@ export function redactRawHttp(input, opts) {
     // Split keeping the terminators so `\r\n` and `\n` mixes survive the round trip verbatim.
     const redactedHeaderBlock = headerBlock
         .split(/(\r\n|\n)/)
-        .map((part, index) => (index % 2 === 0 ? redactHeaderLine(part) : part))
+        .map((part, index) => index === 0
+        ? redactRequestLine(part, opts?.extraParams)
+        : index % 2 === 0
+            ? redactHeaderLine(part, opts?.extraHeaders)
+            : part)
         .join('');
     // XML first (a `wsse:Password` element), then JSON and form bodies by key. A compressed body is
     // left alone: its bytes are not the text either pass reads.

package/dist/redact/literal.d.ts

@@ -8,5 +8,15 @@
 /**
  * Builds a function that replaces every occurrence of `values` — and the base64, percent-, form-,
  * XML- and JSON-escaped forms of each — with the redaction marker.
+ *
+ * Every match is found on the original text and overlapping or touching matches are merged before
+ * anything is replaced. Masking one needle first would hide the start of another that overlaps it
+ * (`token` inside a cut `token-abcdef-12…`), leaving the rest of that one in the output.
  */
 export declare function createSecretMasker(values: readonly string[]): (text: string) => string;
+/**
+ * Builds the same masker over a base64 run of raw bytes: each value's UTF-8 bytes are masked
+ * wherever they sit, whatever the bytes around them are (a binary WebSocket frame carrying JSON,
+ * MessagePack or CBOR). A run with nothing to mask comes back as the same string, not a re-encoding.
+ */
+export declare function createSecretBytesMasker(values: readonly string[]): (base64: string) => string;

package/dist/redact/literal.js

@@ -36,6 +36,10 @@ function encodedForms(value) {
 /**
  * Builds a function that replaces every occurrence of `values` — and the base64, percent-, form-,
  * XML- and JSON-escaped forms of each — with the redaction marker.
+ *
+ * Every match is found on the original text and overlapping or touching matches are merged before
+ * anything is replaced. Masking one needle first would hide the start of another that overlaps it
+ * (`token` inside a cut `token-abcdef-12…`), leaving the rest of that one in the output.
  */
 export function createSecretMasker(values) {
     const plain = values.filter((value) => value.length >= MIN_MASKED_LENGTH);
@@ -49,20 +53,114 @@ export function createSecretMasker(values) {
             }
         }
     }
-    // Longest first: a value that is a prefix of another must not leave the other's tail behind.
-    const ordered = [...needles].sort((a, b) => b.length - a.length);
-    return (text) => {
-        let out = maskBasicCredentials(text, plain);
-        for (const needle of ordered) {
-            out = out.split(needle).join(REDACTED_MARKER);
+    return (text) => replaceRanges(text, [
+        ...basicCredentialRanges(text, plain),
+        ...needleRanges(text, needles),
+        ...cutPrefixRanges(text, needles),
+    ]);
+}
+/** Replaces each run of overlapping or touching ranges with one marker. */
+function replaceRanges(text, ranges) {
+    if (ranges.length === 0) {
+        return text;
+    }
+    ranges.sort((a, b) => a.start - b.start);
+    let out = '';
+    let kept = 0;
+    let current = { ...ranges[0] };
+    for (const range of ranges.slice(1)) {
+        if (range.start <= current.end) {
+            current.end = Math.max(current.end, range.end);
         }
-        return out;
-    };
+        else {
+            out += text.slice(kept, current.start) + REDACTED_MARKER;
+            kept = current.end;
+            current = { ...range };
+        }
+    }
+    return out + text.slice(kept, current.start) + REDACTED_MARKER + text.slice(current.end);
+}
+/** Every occurrence of every needle, overlapping ones included. */
+function needleRanges(text, needles) {
+    const ranges = [];
+    for (const needle of needles) {
+        for (let at = text.indexOf(needle); at !== -1; at = text.indexOf(needle, at + 1)) {
+            ranges.push({ start: at, end: at + needle.length });
+        }
+    }
+    return ranges;
+}
+/** The marker every report cap writes where it cut a value. */
+const CUT_MARKER = '\u2026';
+/**
+ * A report cap can cut a value inside a secret, so no whole needle is left to match. Finds the
+ * longest needle prefix that ends where a cut was made: just before each `…`, after stepping back
+ * over the `\n` of `\n… truncated` and any U+FFFD a byte cap left of a split character.
+ */
+function cutPrefixRanges(text, needles) {
+    const ranges = [];
+    let start = 0;
+    for (let at = text.indexOf(CUT_MARKER); at !== -1; at = text.indexOf(CUT_MARKER, at + 1)) {
+        let end = at;
+        if (end > start && text[end - 1] === '\n') {
+            end -= 1;
+        }
+        while (end > start && text[end - 1] === '\uFFFD') {
+            end -= 1;
+        }
+        const length = cutTailLength(text.slice(start, end), needles);
+        if (length > 0) {
+            ranges.push({ start: end - length, end });
+        }
+        start = at + 1;
+    }
+    return ranges;
+}
+/** The length of the cut `Basic` base64 run, else of the longest proper needle prefix `head` ends with. */
+function cutTailLength(head, needles) {
+    // Cut base64 cannot be decoded and checked, and it is a credential either way.
+    const basic = /\bBasic\s+([A-Za-z0-9+/=]+)$/.exec(head);
+    if (basic) {
+        return basic[1].length;
+    }
+    let longest = 0;
+    for (const needle of needles) {
+        for (let length = Math.min(needle.length - 1, head.length); length > longest; length -= 1) {
+            if (head.endsWith(needle.slice(0, length))) {
+                longest = length;
+                break;
+            }
+        }
+    }
+    return longest;
 }
 /** A Basic credential is base64 of `user:password`, so the password never appears literally. */
-function maskBasicCredentials(text, values) {
-    return text.replace(/\bBasic\s+([A-Za-z0-9+/=]{8,})/g, (whole, encoded) => {
+function basicCredentialRanges(text, values) {
+    const ranges = [];
+    for (const match of text.matchAll(/\bBasic\s+([A-Za-z0-9+/=]{8,})/g)) {
+        const encoded = match[1];
         const decoded = Buffer.from(encoded, 'base64').toString('utf8');
-        return values.some((value) => decoded.includes(value)) ? `Basic ${REDACTED_MARKER}` : whole;
-    });
+        if (values.some((value) => decoded.includes(value))) {
+            const end = match.index + match[0].length;
+            ranges.push({ start: end - encoded.length, end });
+        }
+    }
+    return ranges;
+}
+/**
+ * Builds the same masker over a base64 run of raw bytes: each value's UTF-8 bytes are masked
+ * wherever they sit, whatever the bytes around them are (a binary WebSocket frame carrying JSON,
+ * MessagePack or CBOR). A run with nothing to mask comes back as the same string, not a re-encoding.
+ */
+export function createSecretBytesMasker(values) {
+    if (values.length === 0) {
+        return (base64) => base64;
+    }
+    // Read as latin1 so bytes that are not UTF-8 survive the round trip unchanged.
+    const mask = createSecretMasker(values.map((value) => Buffer.from(value, 'utf8').toString('latin1')));
+    return (base64) => {
+        const text = Buffer.from(base64, 'base64').toString('latin1');
+        const masked = mask(text);
+        return masked === text ? base64 : Buffer.from(masked, 'latin1').toString('base64');
+    };
 }

package/dist/rest/body.d.ts

@@ -14,7 +14,7 @@ export type FileResolver = (source: AttachmentSource) => Promise<Uint8Array>;
 export interface EncodeBodyOptions {
     /** How a `multipart` or `binary` body's files are read. Required for those kinds only. */
     readonly resolveFile?: FileResolver;
-    /** Charset for a raw or form body. Default `utf-8`; see `soap/charset.ts` for the labels. */
+    /** Charset for a raw or form body. Default `utf-8`; see `http/charset.ts` for the labels. */
     readonly charset?: string;
     /** Fixed multipart boundary; a random one is generated otherwise. Tests inject it. */
     readonly boundary?: string;
@@ -46,15 +46,7 @@ export declare function encodeFormFields(fields: readonly KeyValueEntry[]): stri
  * @throws WirebenchError `rest-file-unresolved` when a file part or binary body has no resolver
  */
 export declare function encodeRestBody(body: RestBody, options?: EncodeBodyOptions): Promise<EncodedBody>;
-/**
- * XML- or JSON-escapes a value being substituted into a body, for the *escape properties* setting.
- *
- * Only the characters that would otherwise change the document's structure are touched. A JSON
- * body gets JSON string escaping (without the surrounding quotes, since the value is substituted
- * inside them); an XML body gets the five predefined entities; anything else is left alone,
- * because there is no general escape for `text/plain`.
- */
-export declare function escapeForLanguage(value: string, language: RawLanguage | 'form'): string;
+export { escapeForLanguage } from '../http/escape.js';
 /** The language a body's escaping follows, for {@link escapeForLanguage}. */
 export declare function bodyLanguage(body: RestBody): RawLanguage | 'form' | undefined;
 /** The media type of an encoded body, without its parameters; `undefined` when it has none. */

package/dist/rest/body.js

@@ -8,8 +8,8 @@
  */
 import { randomBytes } from 'node:crypto';
 import { WirebenchError } from '../errors.js';
-import { encodeBody } from '../soap/charset.js';
-import { mediaTypeOf } from '../soap/mime/multipart.js';
+import { encodeBody } from '../http/charset.js';
+import { mediaTypeOf } from '../http/media-type.js';
 import { RAW_LANGUAGE_CONTENT_TYPES } from './model.js';
 const CRLF = '\r\n';
 /** A fresh multipart boundary: long, random, and unable to occur in base64 or text. */
@@ -143,29 +143,7 @@ export async function encodeRestBody(body, options = {}) {
         }
     }
 }
-/**
- * XML- or JSON-escapes a value being substituted into a body, for the *escape properties* setting.
- *
- * Only the characters that would otherwise change the document's structure are touched. A JSON
- * body gets JSON string escaping (without the surrounding quotes, since the value is substituted
- * inside them); an XML body gets the five predefined entities; anything else is left alone,
- * because there is no general escape for `text/plain`.
- */
-export function escapeForLanguage(value, language) {
-    if (language === 'json') {
-        const json = JSON.stringify(value);
-        return json.slice(1, -1);
-    }
-    if (language === 'xml' || language === 'html') {
-        return value
-            .replace(/&/g, '&')
-            .replace(/</g, '&lt;')
-            .replace(/>/g, '&gt;')
-            .replace(/"/g, '&quot;')
-            .replace(/'/g, '&apos;');
-    }
-    return value;
-}
+export { escapeForLanguage } from '../http/escape.js';
 /** The language a body's escaping follows, for {@link escapeForLanguage}. */
 export function bodyLanguage(body) {
     switch (body.kind) {

package/dist/rest/browser.d.ts

@@ -10,3 +10,7 @@
  */
 export { composeUrl, encodeValue, joinBase, joinQuery, parseUrlParams, splitQuery, type ComposedUrl, type ComposeUrlOptions, type UrlProblem, } from './url.js';
 export type { KeyValueEntry } from './model.js';
+export { SECRET_NAME_PATTERN } from '../secrets/secret-token.js';
+export { createSseParser, eventStreamDocument, isEventStream, serializeEventStream, type SseParser, type SseRow, } from './sse.js';
+export { applyJsonFormEdit, buildJsonForm, toWireSchema, type JsonFormEdit, type JsonFormKind, type JsonFormNode, type JsonFormOptions, type JsonFormValueType, } from './json-form.js';
+export type { JsonSchema, JsonValue } from './openapi/model.js';

package/dist/rest/browser.js

@@ -9,3 +9,8 @@
  * sets of escaping rules to keep in step.
  */
 export { composeUrl, encodeValue, joinBase, joinQuery, parseUrlParams, splitQuery, } from './url.js';
+// The `${secret:name}` name rule, so the renderer's secret review checks a name typed into it
+// exactly as main's move will — a request's headers, query and body are where those tokens land.
+export { SECRET_NAME_PATTERN } from '../secrets/secret-token.js';
+export { createSseParser, eventStreamDocument, isEventStream, serializeEventStream, } from './sse.js';
+export { applyJsonFormEdit, buildJsonForm, toWireSchema, } from './json-form.js';

package/dist/rest/contract-check-worker-host.d.ts

@@ -0,0 +1,36 @@
+/**
+ * REST response checking off the calling thread.
+ *
+ * {@link checkRestResponse} is synchronous and a contract's `pattern` is untrusted: its own time
+ * budget stops a check between steps, 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 response at a time,
+ * each under a hard deadline: a worker that has not answered by then is terminated, the response is
+ * reported `not-checked`, and a fresh worker is started for the next one. The caller's thread
+ * (Electron's main process) never runs a check itself.
+ *
+ * The input is posted, not serialised: an OpenAPI schema may be shared or refer to itself, which
+ * structured clone carries and JSON cannot. Callers pass only the matched operation's `responses`,
+ * so each send copies that much and no more.
+ */
+import type { RestContractInput, RestContractResult } from './contract-check.js';
+/** How long one response's check may take, worker round trip included, before the worker is replaced. */
+export declare const DEFAULT_REST_CHECK_DEADLINE_MS = 1000;
+/** How many responses may wait behind the one being checked before new ones are not checked at all. */
+export declare const DEFAULT_REST_CHECK_QUEUE = 16;
+export interface RestContractCheckerOptions {
+    /** Milliseconds one response's check may take before the worker is terminated and replaced. */
+    readonly deadlineMs?: number;
+    /** The worker script; tests substitute one. Defaults to the compiled `contract-check-worker.js`. */
+    readonly workerUrl?: URL;
+}
+export interface RestContractChecker {
+    /** The response's contract result; `not-checked` on overrun, overflow, failure or after dispose. Never rejects. */
+    check(input: RestContractInput): Promise<RestContractResult>;
+    /** Terminates the worker; checks still waiting resolve `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 createRestContractChecker(options?: RestContractCheckerOptions): RestContractChecker;

package/dist/rest/contract-check-worker-host.js

@@ -0,0 +1,158 @@
+/**
+ * REST response checking off the calling thread.
+ *
+ * {@link checkRestResponse} is synchronous and a contract's `pattern` is untrusted: its own time
+ * budget stops a check between steps, 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 response at a time,
+ * each under a hard deadline: a worker that has not answered by then is terminated, the response is
+ * reported `not-checked`, and a fresh worker is started for the next one. The caller's thread
+ * (Electron's main process) never runs a check itself.
+ *
+ * The input is posted, not serialised: an OpenAPI schema may be shared or refer to itself, which
+ * structured clone carries and JSON cannot. Callers pass only the matched operation's `responses`,
+ * so each send copies that much and no more.
+ */
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+/** How long one response's check may take, worker round trip included, before the worker is replaced. */
+export const DEFAULT_REST_CHECK_DEADLINE_MS = 1_000;
+/** How many responses may wait behind the one being checked before new ones are not checked at all. */
+export const DEFAULT_REST_CHECK_QUEUE = 16;
+/**
+ * The compiled worker script: the sibling `.js` when running from `dist`, else — running from `src`
+ * under vitest — the package's `dist/rest/contract-check-worker.js`.
+ */
+function defaultWorkerUrl() {
+    const sibling = new URL('./contract-check-worker.js', import.meta.url);
+    if (existsSync(fileURLToPath(sibling))) {
+        return sibling;
+    }
+    const fallback = import.meta.url.replace(/\/src\/rest\/contract-check-worker-host\.ts$/, '/dist/rest/contract-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('contract-check worker not found: build the engine package first');
+    }
+    return new URL(fallback);
+}
+const notChecked = (reason) => ({ status: 'not-checked', problems: [], notes: [reason] });
+export function createRestContractChecker(options = {}) {
+    const deadlineMs = options.deadlineMs ?? DEFAULT_REST_CHECK_DEADLINE_MS;
+    let url = options.workerUrl;
+    let worker;
+    let spawned = 0;
+    let disposed = false;
+    let nextId = 0;
+    let current;
+    let timer;
+    const queue = [];
+    const finish = (result) => {
+        const job = current;
+        if (job === undefined)
+            return;
+        current = undefined;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        job.resolve(result);
+        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);
+        spawned += 1;
+        // The checker must never be what keeps the process alive.
+        next.unref();
+        next.on('message', (answer) => {
+            if (current?.id === answer.id)
+                finish(answer.result);
+        });
+        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;
+        current = job;
+        try {
+            worker ??= spawn();
+            worker.postMessage({ id: job.id, input: job.input });
+        }
+        catch (error) {
+            discard();
+            finish(notChecked(`the check could not start: ${error instanceof Error ? error.message : String(error)}`));
+            return;
+        }
+        // The deadline starts when this response reaches the worker, not when it was queued, so one
+        // stuck check never costs the ones behind it their own.
+        timer = setTimeout(() => {
+            discard();
+            finish(notChecked(`the check took longer than ${String(deadlineMs)} ms`));
+        }, deadlineMs);
+        timer.unref?.();
+    }
+    return {
+        check(input) {
+            if (disposed)
+                return Promise.resolve(notChecked('the checker was stopped'));
+            if (queue.length >= DEFAULT_REST_CHECK_QUEUE) {
+                return Promise.resolve(notChecked('too many responses waiting to be checked'));
+            }
+            return new Promise((resolve) => {
+                nextId += 1;
+                queue.push({ id: nextId, input, resolve });
+                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)];
+            current = undefined;
+            for (const job of waiting)
+                job.resolve(notChecked('the checker was stopped'));
+            if (dead !== undefined) {
+                dead.removeAllListeners();
+                dead.on('error', () => undefined);
+                await dead.terminate();
+            }
+        },
+        get spawned() {
+            return spawned;
+        },
+        get running() {
+            return worker !== undefined;
+        },
+    };
+}

package/dist/rest/contract-check-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link createRestContractChecker}. Each
+ * message in is one response (`{ id, input }`, the input carrying only the selected operation's
+ * responses) and each message out its result (`{ id, result }`). Responses are checked one at a
+ * time, in the order they arrive.
+ */
+export {};

package/dist/rest/contract-check-worker.js

@@ -0,0 +1,28 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link createRestContractChecker}. Each
+ * message in is one response (`{ id, input }`, the input carrying only the selected operation's
+ * responses) and each message out its result (`{ id, result }`). Responses are checked one at a
+ * time, in the order they arrive.
+ */
+import { parentPort } from 'node:worker_threads';
+import { checkRestResponse } from './contract-check.js';
+/* v8 ignore start -- runs only inside a real worker thread; covered end to end by
+   contract-check-worker.test.ts, which coverage instrumentation does not follow across the thread. */
+if (parentPort !== null) {
+    const port = parentPort;
+    port.on('message', ({ id, input }) => {
+        let result;
+        try {
+            result = checkRestResponse(input);
+        }
+        catch (error) {
+            result = {
+                status: 'not-checked',
+                problems: [],
+                notes: [error instanceof Error ? error.message : String(error)],
+            };
+        }
+        port.postMessage({ id, result });
+    });
+}
+/* v8 ignore stop */

package/dist/rest/contract-check.d.ts

@@ -0,0 +1,43 @@
+import type { OpenApiResponses } from './openapi/model.js';
+import type { RestOperationRef } from './openapi/match.js';
+/** A body bigger than this (UTF-8 bytes) is not parsed or validated: it is reported `skipped`. */
+export declare const MAX_CHECKED_BODY_BYTES = 1048576;
+/** The default time one response's check may take before it gives up as `not-checked`. */
+export declare const DEFAULT_REST_CHECK_BUDGET_MS = 200;
+export declare const MAX_CONTRACT_PROBLEMS = 50;
+export declare const MAX_CONTRACT_MESSAGE_LENGTH = 300;
+/**
+ * Schema nodes one check may visit. Generous, since a real response (hundreds of rows of dozens of
+ * properties) must be checkable: the worker's deadline is what bounds the time, and this only stops a
+ * body the deadline would let through yet is still too big to finish.
+ */
+export declare const MAX_REST_CHECK_NODES = 200000;
+export declare const MAX_CONTRACT_PATH_LENGTH = 300;
+export type RestContractStatus = 'ok' | 'violation' | 'unmatched' | 'no-schema' | 'no-contract' | 'skipped' | 'not-checked';
+export interface RestContractProblem {
+    readonly path: string;
+    readonly keyword: string;
+    readonly message: string;
+}
+export interface RestContractResult {
+    readonly status: RestContractStatus;
+    readonly operation?: RestOperationRef;
+    readonly responseKey?: string;
+    readonly mediaType?: string;
+    readonly problems: readonly RestContractProblem[];
+    readonly notes: readonly string[];
+}
+export interface RestContractInput {
+    readonly status: number;
+    readonly contentType?: string | undefined;
+    readonly bodyText: string;
+    readonly language: string;
+    readonly streamed: boolean;
+    readonly operation?: RestOperationRef | undefined;
+    readonly responses?: OpenApiResponses | undefined;
+}
+export interface RestContractCheckOptions {
+    readonly budgetMs?: number;
+    readonly now?: () => number;
+}
+export declare function checkRestResponse(input: RestContractInput, options?: RestContractCheckOptions): RestContractResult;