@wirebench/engine 2.2.0 → 3.1.0-rc.1

package/dist/ws/files.d.ts

@@ -0,0 +1,284 @@
+/**
+ * The WebSocket files of a project folder: `apis/<slug>/api.yaml` with `kind: websocket`, and each
+ * `*.request.yaml` of its request tree (spec §3.2).
+ */
+import { z } from 'zod';
+/**
+ * `apis/<slug>/requests/[<folder>/…]<name>.request.yaml` for a WebSocket request. Each saved
+ * message's own text lives in its own sibling file, so a JSON message is a JSON file in git.
+ */
+export declare const wsRequestFileSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"websocket">;
+    id: z.ZodString;
+    name: z.ZodString;
+    order: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    query: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    headers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    subprotocols: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    auth: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodEnum<{
+            none: "none";
+            basic: "basic";
+            ntlm: "ntlm";
+        }>;
+        username: z.ZodOptional<z.ZodString>;
+        passwordRef: z.ZodOptional<z.ZodString>;
+        passwordEnv: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        workstation: z.ZodOptional<z.ZodString>;
+        preemptive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"inherit">;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        tokenRef: z.ZodOptional<z.ZodString>;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"api-key">;
+        name: z.ZodString;
+        valueRef: z.ZodOptional<z.ZodString>;
+        valueEnv: z.ZodOptional<z.ZodString>;
+        in: z.ZodEnum<{
+            header: "header";
+            query: "query";
+        }>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        grant: z.ZodEnum<{
+            "client-credentials": "client-credentials";
+            "authorization-code": "authorization-code";
+        }>;
+        tokenUrl: z.ZodString;
+        authorizationUrl: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodString;
+        clientSecretRef: z.ZodOptional<z.ZodString>;
+        clientSecretEnv: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        audience: z.ZodOptional<z.ZodString>;
+        clientAuth: z.ZodDefault<z.ZodEnum<{
+            basic: "basic";
+            body: "body";
+        }>>;
+        pkce: z.ZodDefault<z.ZodBoolean>;
+        refreshTokenRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>;
+    settings: z.ZodDefault<z.ZodObject<{
+        handshakeTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        trustInvalid: z.ZodOptional<z.ZodBoolean>;
+        sslKeystoreRef: z.ZodOptional<z.ZodString>;
+        bindAddress: z.ZodOptional<z.ZodString>;
+        maxMessageBytes: z.ZodOptional<z.ZodNumber>;
+        escapeProperties: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>>;
+    messages: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        format: z.ZodDefault<z.ZodEnum<{
+            binary: "binary";
+            text: "text";
+        }>>;
+        file: z.ZodString;
+        contract: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            generated: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+    assertions: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"status">;
+        equals: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber, z.ZodString, z.ZodEnum<{
+            [x: string]: string;
+        }>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber, z.ZodString, z.ZodEnum<{
+            [x: string]: string;
+        }>]>>]>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"soap-fault">;
+        expect: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            present: "present";
+        }>>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"match">;
+        language: z.ZodEnum<{
+            xpath: "xpath";
+            xquery: "xquery";
+            jsonpath: "jsonpath";
+        }>;
+        expression: z.ZodString;
+        namespaces: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        matches: z.ZodOptional<z.ZodString>;
+        exists: z.ZodOptional<z.ZodBoolean>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"schema">;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"sla">;
+        maxMs: z.ZodNumber;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"callback">;
+        catchUrl: z.ZodString;
+        withinMs: z.ZodDefault<z.ZodNumber>;
+        match: z.ZodDefault<z.ZodObject<{
+            method: z.ZodOptional<z.ZodString>;
+            path: z.ZodOptional<z.ZodString>;
+            pathMatches: z.ZodOptional<z.ZodString>;
+            headers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                name: z.ZodString;
+            }, z.core.$loose>>>;
+            body: z.ZodOptional<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                language: z.ZodEnum<{
+                    xpath: "xpath";
+                    jsonpath: "jsonpath";
+                }>;
+                path: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+        expect: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            body: z.ZodOptional<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                language: z.ZodEnum<{
+                    xpath: "xpath";
+                    jsonpath: "jsonpath";
+                }>;
+                path: z.ZodString;
+            }, z.core.$loose>>;
+            header: z.ZodOptional<z.ZodObject<{
+                equals: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                exists: z.ZodOptional<z.ZodBoolean>;
+                name: z.ZodString;
+            }, z.core.$loose>>;
+            signature: z.ZodOptional<z.ZodLiteral<"verified">>;
+        }, z.core.$loose>>>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], "type">>>;
+    contract: z.ZodOptional<z.ZodObject<{
+        channel: z.ZodString;
+    }, z.core.$loose>>;
+    orphaned: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$loose>;
+/** `apis/<slug>/api.yaml` for a WebSocket API. */
+export declare const wsApiFileSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"websocket">;
+    id: z.ZodString;
+    name: z.ZodString;
+    order: z.ZodNumber;
+    description: z.ZodOptional<z.ZodString>;
+    url: z.ZodString;
+    headers: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodEnum<{
+            none: "none";
+            basic: "basic";
+            ntlm: "ntlm";
+        }>;
+        username: z.ZodOptional<z.ZodString>;
+        passwordRef: z.ZodOptional<z.ZodString>;
+        passwordEnv: z.ZodOptional<z.ZodString>;
+        domain: z.ZodOptional<z.ZodString>;
+        workstation: z.ZodOptional<z.ZodString>;
+        preemptive: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"inherit">;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"bearer">;
+        tokenRef: z.ZodOptional<z.ZodString>;
+        tokenEnv: z.ZodOptional<z.ZodString>;
+        scheme: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"api-key">;
+        name: z.ZodString;
+        valueRef: z.ZodOptional<z.ZodString>;
+        valueEnv: z.ZodOptional<z.ZodString>;
+        in: z.ZodEnum<{
+            header: "header";
+            query: "query";
+        }>;
+    }, z.core.$loose>, z.ZodObject<{
+        type: z.ZodLiteral<"oauth2">;
+        grant: z.ZodEnum<{
+            "client-credentials": "client-credentials";
+            "authorization-code": "authorization-code";
+        }>;
+        tokenUrl: z.ZodString;
+        authorizationUrl: z.ZodOptional<z.ZodString>;
+        clientId: z.ZodString;
+        clientSecretRef: z.ZodOptional<z.ZodString>;
+        clientSecretEnv: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        audience: z.ZodOptional<z.ZodString>;
+        clientAuth: z.ZodDefault<z.ZodEnum<{
+            basic: "basic";
+            body: "body";
+        }>>;
+        pkce: z.ZodDefault<z.ZodBoolean>;
+        refreshTokenRef: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>]>>;
+    definition: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"asyncapi">;
+        source: z.ZodString;
+        cache: z.ZodDefault<z.ZodBoolean>;
+        server: z.ZodOptional<z.ZodString>;
+        auth: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            type: z.ZodEnum<{
+                none: "none";
+                basic: "basic";
+                ntlm: "ntlm";
+            }>;
+            username: z.ZodOptional<z.ZodString>;
+            passwordRef: z.ZodOptional<z.ZodString>;
+            passwordEnv: z.ZodOptional<z.ZodString>;
+            domain: z.ZodOptional<z.ZodString>;
+            workstation: z.ZodOptional<z.ZodString>;
+            preemptive: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"bearer">;
+            tokenRef: z.ZodOptional<z.ZodString>;
+            tokenEnv: z.ZodOptional<z.ZodString>;
+            scheme: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>, z.ZodObject<{
+            type: z.ZodLiteral<"api-key">;
+            name: z.ZodString;
+            valueRef: z.ZodOptional<z.ZodString>;
+            valueEnv: z.ZodOptional<z.ZodString>;
+            in: z.ZodEnum<{
+                header: "header";
+                query: "query";
+            }>;
+        }, z.core.$loose>]>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** A WebSocket `api.yaml` as parsed. */
+export type WsApiFile = z.infer<typeof wsApiFileSchema>;
+/** A WebSocket `*.request.yaml` as parsed. */
+export type WsRequestFile = z.infer<typeof wsRequestFileSchema>;

package/dist/ws/files.js

@@ -0,0 +1,71 @@
+/**
+ * The WebSocket files of a project folder: `apis/<slug>/api.yaml` with `kind: websocket`, and each
+ * `*.request.yaml` of its request tree (spec §3.2).
+ */
+import { z } from 'zod';
+import { assertionsSchema } from '../assert/schema.js';
+import { authConfigSchema, definitionAuthSchema, keyValueEntrySchema, nonEmpty } from '../project/schema-parts.js';
+const wsSettingsSchema = z.looseObject({
+    handshakeTimeoutMs: z.number().int().nonnegative().optional(),
+    trustInvalid: z.boolean().optional(),
+    sslKeystoreRef: z.string().optional(),
+    bindAddress: z.string().optional(),
+    maxMessageBytes: z.number().int().nonnegative().optional(),
+    escapeProperties: z.boolean().optional(),
+});
+/**
+ * One saved message as persisted: its text (or, for `binary`, base64) lives in the sibling file
+ * `file` names, validated as a path segment before it is read (ADR-0005) — the same convention a
+ * gRPC message or a REST raw body follows.
+ */
+const wsSavedMessageSchema = z.looseObject({
+    id: nonEmpty,
+    name: z.string(),
+    format: z.enum(['text', 'binary']).default('text'),
+    file: nonEmpty,
+    /** The contract message this was generated from, and the sample text it was generated as. */
+    contract: z.looseObject({ message: nonEmpty, generated: z.string() }).optional(),
+});
+/**
+ * `apis/<slug>/requests/[<folder>/…]<name>.request.yaml` for a WebSocket request. Each saved
+ * message's own text lives in its own sibling file, so a JSON message is a JSON file in git.
+ */
+export const wsRequestFileSchema = z.looseObject({
+    kind: z.literal('websocket'),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    url: z.string(),
+    query: z.array(keyValueEntrySchema).default([]),
+    headers: z.array(keyValueEntrySchema).default([]),
+    subprotocols: z.array(z.string()).default([]),
+    auth: authConfigSchema.default({ type: 'inherit' }),
+    settings: wsSettingsSchema.default({}),
+    messages: z.array(wsSavedMessageSchema).default([]),
+    assertions: assertionsSchema.default([]),
+    /** The channel of the API's contract this request was imported from. */
+    contract: z.looseObject({ channel: nonEmpty }).optional(),
+    /** The contract no longer has that channel. */
+    orphaned: z.boolean().optional(),
+});
+/** `apis/<slug>/api.yaml` for a WebSocket API. */
+export const wsApiFileSchema = z.looseObject({
+    kind: z.literal('websocket'),
+    id: nonEmpty,
+    name: z.string(),
+    order: z.number().int(),
+    description: z.string().optional(),
+    url: z.string(),
+    headers: z.array(keyValueEntrySchema).default([]),
+    auth: authConfigSchema.optional(),
+    definition: z
+        .looseObject({
+        kind: z.literal('asyncapi'),
+        source: nonEmpty,
+        cache: z.boolean().default(true),
+        server: z.string().optional(),
+        auth: definitionAuthSchema.optional(),
+    })
+        .optional(),
+});

package/dist/ws/history-entry.d.ts

@@ -0,0 +1,44 @@
+import type { HistoryEntry } from '../project/history.js';
+import type { WsExchange } from './model.js';
+/** What {@link buildWsHistoryEntry} needs to build one WebSocket entry. */
+export interface WsHistoryInput {
+    readonly requestId: string;
+    readonly requestName: string;
+    /** The API the request belongs to, in the interface name's slot. */
+    readonly apiName: string;
+    readonly folderPath: string;
+    readonly exchange: WsExchange;
+    /**
+     * Whether the session's handshake actually opened. `ok` follows it rather than
+     * `exchange.handshake.status === 101`: that status is optional (e.g. absent through a proxy
+     * tunnel) and so cannot itself tell an opened session from a refused one.
+     */
+    readonly handshakeOpened: boolean;
+    /** Query parameters an API key travels in, masked in the URL whatever they are called. */
+    readonly keyParams?: readonly string[];
+    /** Where the entry came from, or the run it belongs to: `cli`, `sequence:<id>`. */
+    readonly tags?: readonly string[];
+}
+/** The secret values the host knows of, masked wherever no pattern rule looks. */
+export interface WsHistoryMasks {
+    /** Masks each value in a text: a header, the URL, a frame's text, a close reason. */
+    readonly text: (text: string) => string;
+    /** Masks each value's bytes in a base64 run: a binary frame's payload. */
+    readonly base64: (base64: string) => string;
+}
+/**
+ * A session as History stores it: the headers and the URL redacted by pattern with `show: false`
+ * (an API key's own `keyParams` too), then masked; a frame's text, a binary payload's bytes and a
+ * close reason masked the same way. `size` stays the size on the wire, though a masked payload's own
+ * length can differ from it. A host that shows the session where History's rules apply (the command
+ * line's `send` result) reads it from here too.
+ */
+export declare function redactWsExchange(exchange: WsExchange, masks: WsHistoryMasks, keyParams?: readonly string[]): WsExchange;
+/**
+ * Builds one redacted WebSocket `HistoryEntry` from a finished session, whether it closed cleanly or
+ * the handshake never got past `error`/a non-101 status. The SOAP-shaped fields carry what they can,
+ * as a gRPC entry's do: the API's name as the interface, the folder path as the operation, the
+ * handshake's status as the status; `ws` is the multi-message record ADR-0007 left room for, capped
+ * by {@link historyWsOf}'s own `capFrames`. Redacted by {@link redactWsExchange}.
+ */
+export declare function buildWsHistoryEntry(projectId: string, record: WsHistoryInput, masks: WsHistoryMasks): HistoryEntry;

package/dist/ws/history-entry.js

@@ -0,0 +1,93 @@
+/**
+ * One WebSocket session as History records it, for every host that writes History: the desktop on
+ * a session's close, the command line's `send`. Redaction is History's, whatever was shown live.
+ */
+import { generateHistoryId, historyWsOf } from '../project/history.js';
+import { redactHeaders, redactUrl } from '../redact/index.js';
+/**
+ * A session as History stores it: the headers and the URL redacted by pattern with `show: false`
+ * (an API key's own `keyParams` too), then masked; a frame's text, a binary payload's bytes and a
+ * close reason masked the same way. `size` stays the size on the wire, though a masked payload's own
+ * length can differ from it. A host that shows the session where History's rules apply (the command
+ * line's `send` result) reads it from here too.
+ */
+export function redactWsExchange(exchange, masks, keyParams = []) {
+    const url = (value) => masks.text(redactUrl(value, { show: false, extraParams: keyParams }));
+    const headers = (values) => {
+        const out = redactHeaders(values, { show: false });
+        for (const [name, value] of Object.entries(out)) {
+            out[name] = masks.text(value);
+        }
+        return out;
+    };
+    return {
+        kind: 'websocket',
+        url: url(exchange.url),
+        handshake: {
+            ...exchange.handshake,
+            url: url(exchange.handshake.url),
+            requestHeaders: headers(exchange.handshake.requestHeaders),
+            ...(exchange.handshake.responseHeaders !== undefined
+                ? { responseHeaders: headers(exchange.handshake.responseHeaders) }
+                : {}),
+        },
+        frames: exchange.frames.map((frame) => ({
+            ...frame,
+            ...(frame.text !== undefined ? { text: masks.text(frame.text) } : {}),
+            ...(frame.base64 !== undefined ? { base64: masks.base64(frame.base64) } : {}),
+            ...(frame.close !== undefined
+                ? { close: { code: frame.close.code, reason: masks.text(frame.close.reason) } }
+                : {}),
+        })),
+        // `historyWsOf` copies the reason into the entry's `closeReason`.
+        closed: { ...exchange.closed, reason: masks.text(exchange.closed.reason) },
+        counts: exchange.counts,
+        durationMs: exchange.durationMs,
+    };
+}
+/**
+ * Builds one redacted WebSocket `HistoryEntry` from a finished session, whether it closed cleanly or
+ * the handshake never got past `error`/a non-101 status. The SOAP-shaped fields carry what they can,
+ * as a gRPC entry's do: the API's name as the interface, the folder path as the operation, the
+ * handshake's status as the status; `ws` is the multi-message record ADR-0007 left room for, capped
+ * by {@link historyWsOf}'s own `capFrames`. Redacted by {@link redactWsExchange}.
+ */
+export function buildWsHistoryEntry(projectId, record, masks) {
+    const { exchange } = record;
+    const redacted = redactWsExchange(exchange, masks, record.keyParams);
+    const ws = historyWsOf(redacted);
+    const requestHeaders = Object.entries(redacted.handshake.requestHeaders).map(([name, value]) => ({
+        name,
+        value,
+    }));
+    return {
+        id: generateHistoryId(),
+        kind: 'websocket',
+        at: new Date().toISOString(),
+        projectId,
+        requestId: record.requestId,
+        requestName: record.requestName,
+        interfaceName: record.apiName,
+        operationName: record.folderPath,
+        endpoint: ws.url,
+        soapVersion: 'none',
+        method: 'GET',
+        ...(ws.status !== undefined ? { status: ws.status } : {}),
+        durationMs: exchange.durationMs,
+        ok: record.handshakeOpened && ws.closedBy !== 'error',
+        request: { envelopeXml: '', headers: requestHeaders },
+        ...(ws.status !== undefined
+            ? {
+                response: {
+                    rawHeaders: Object.entries(redacted.handshake.responseHeaders ?? {}),
+                    status: ws.status,
+                    statusText: exchange.handshake.statusText ?? '',
+                },
+            }
+            : {}),
+        ...(ws.error !== undefined ? { error: { code: 'ws-handshake-failed', message: ws.error } } : {}),
+        ws,
+        sizeBytes: exchange.counts.bytesSent + exchange.counts.bytesReceived,
+        ...(record.tags !== undefined ? { tags: record.tags } : {}),
+    };
+}

package/dist/ws/model.d.ts

@@ -14,8 +14,10 @@
  * survives a rename, `slug` is the file-system name derived from `name`, and nothing here ever
  * holds a secret — credentials are `secretRef`s resolved from the OS keychain at send time.
  */
-import type { AuthConfig, CreateOptions, IdGenerator } from '../project/model.js';
-import type { KeyValueEntry } from '../rest/model.js';
+import type { AuthConfig, CreateOptions, DefinitionAuth, IdGenerator } from '../project/model.js';
+import type { JsonSchemaProblem } from '../json/schema-validate.js';
+import type { Assertion } from '../assert/model.js';
+import type { KeyValueEntry } from '../http/entries.js';
 import type { SslInfo } from '../http/tls.js';
 export { wsApiFolders, wsApiRequests, wsFolderRequests, wsMessageFileName } from './shape.js';
 /**
@@ -31,6 +33,16 @@ export interface WsRequestSettings {
     readonly maxMessageBytes?: number;
     readonly escapeProperties?: boolean;
 }
+/** Which channel of the API's contract a request was imported from: the channel key in the document. */
+export interface WsContractLink {
+    readonly channel: string;
+}
+/** Which contract message a saved message was generated from, and the text it was generated as. */
+export interface WsMessageContractLink {
+    readonly message: string;
+    /** The sample as imported — what Update Definition compares against to tell an untouched message. */
+    readonly generated: string;
+}
 /** A message saved under a request, ready to send without retyping it. */
 export interface WsSavedMessage {
     readonly id: string;
@@ -39,6 +51,7 @@ export interface WsSavedMessage {
     readonly format: 'text' | 'binary';
     /** The text as edited; for `binary`, base64. Stored in `<request-slug>.msg-<slug>.<ext>`. */
     readonly content: string;
+    readonly contract?: WsMessageContractLink;
 }
 /** A saved WebSocket request: a URL to dial, headers and query to send, and saved messages. */
 export interface WsRequestDef {
@@ -56,6 +69,12 @@ export interface WsRequestDef {
     readonly auth: AuthConfig;
     readonly settings: WsRequestSettings;
     readonly messages: readonly WsSavedMessage[];
+    /** Checked against the received messages, in order, as a JSON array (request-assertions spec §3). */
+    readonly assertions: readonly Assertion[];
+    /** Set when the request was imported from the API's contract. */
+    readonly contract?: WsContractLink;
+    /** The contract no longer has the channel this request was imported from. */
+    readonly orphaned?: boolean;
 }
 /** A named node in a WebSocket API's tree. */
 export interface WsFolder {
@@ -69,11 +88,16 @@ export interface WsFolder {
     readonly folders: readonly WsFolder[];
     readonly requests: readonly WsRequestDef[];
 }
-/** Reserved for the contract import (#100); nothing in this plan reads it. */
+/** Where an AsyncAPI-imported API's contract came from, and whether a copy is cached under `definition/`. */
 export interface WsDefinitionRef {
     readonly kind: 'asyncapi';
     readonly source: string;
     readonly cache: boolean;
+    /** The server key the API was mapped against, so an update maps the new document against the same one.
+     *  Absent means the first WebSocket server. */
+    readonly server?: string;
+    /** Credentials the document is fetched with, sent to the source's own origin only. */
+    readonly auth?: DefinitionAuth;
 }
 /** A WebSocket API: a server URL and a tree of folders and requests. */
 export interface WsApi {
@@ -91,6 +115,18 @@ export interface WsApi {
     readonly folders: readonly WsFolder[];
     readonly requests: readonly WsRequestDef[];
 }
+/** How a frame fared against its channel's contract. `not-checked` means the check ran out of
+ *  time and stopped: it says nothing either way about the frame. */
+export type WsFrameContractStatus = 'ok' | 'violation' | 'unmatched' | 'skipped' | 'not-checked';
+/** One frame's contract check result: plain data, so it can cross a worker boundary. */
+export interface WsFrameContract {
+    readonly status: WsFrameContractStatus;
+    /** The matched message's name, or the closest one's on a violation. */
+    readonly message?: string;
+    readonly problems?: readonly JsonSchemaProblem[];
+    /** Why a frame is a violation without schema problems, unmatched, skipped or not checked. */
+    readonly reason?: string;
+}
 export type WsOpcode = 'text' | 'binary' | 'ping' | 'pong' | 'close';
 /** One frame sent or received during a WebSocket session, as shown in the log. */
 export interface WsFrame {
@@ -108,6 +144,8 @@ export interface WsFrame {
         readonly reason: string;
     };
     readonly payloadTruncated?: boolean;
+    /** Set when the session's request is linked to a contract channel. */
+    readonly contract?: WsFrameContract;
 }
 /** The handshake that opened (or failed to open) a WebSocket session. */
 export interface WsHandshake {
@@ -179,6 +217,8 @@ export interface CreateWsRequestInput extends CreateOptions {
     readonly auth?: AuthConfig;
     readonly settings?: WsRequestSettings;
     readonly messages?: readonly WsSavedMessage[];
+    readonly assertions?: readonly Assertion[];
+    readonly contract?: WsContractLink;
 }
 /** Creates a request with an empty URL and inherited credentials, and nothing saved. */
 export declare function createWsRequest(name: string, input?: CreateWsRequestInput): WsRequestDef;
@@ -187,5 +227,6 @@ export declare function createWsSavedMessage(name: string, input?: CreateOptions
     readonly slug?: string;
     readonly format?: 'text' | 'binary';
     readonly content?: string;
+    readonly contract?: WsMessageContractLink;
 }): WsSavedMessage;
 export type { IdGenerator };

package/dist/ws/model.js

@@ -69,6 +69,8 @@ export function createWsRequest(name, input = {}) {
         auth: input.auth ?? { type: 'inherit' },
         settings: input.settings ?? {},
         messages: input.messages ?? [],
+        assertions: input.assertions ?? [],
+        ...(input.contract !== undefined ? { contract: input.contract } : {}),
     };
 }
 /** Creates a saved message, text and empty by default. */
@@ -79,5 +81,6 @@ export function createWsSavedMessage(name, input) {
         slug: input?.slug ?? slugify(name),
         format: input?.format ?? 'text',
         content: input?.content ?? '',
+        ...(input?.contract !== undefined ? { contract: input.contract } : {}),
     };
 }

package/dist/ws/module.d.ts

@@ -0,0 +1,2 @@
+/** The WebSocket protocol: APIs, their folders and their saved requests. */
+export declare const wsProtocol: import("../protocol/module.js").ProtocolModule;

package/dist/ws/module.js

@@ -0,0 +1,11 @@
+/** WebSocket as a protocol module (spec §3). */
+import { defineProtocol } from '../protocol/module.js';
+import { wsRun } from './run.js';
+import { wsStorage } from './storage.js';
+/** The WebSocket protocol: APIs, their folders and their saved requests. */
+export const wsProtocol = defineProtocol({
+    kind: 'websocket',
+    feature: { id: 'websocket', title: 'WebSocket', default: true, stage: 'stable', requires: [] },
+    storage: wsStorage,
+    run: wsRun,
+});