@wirebench/engine 2.1.1

package/dist/ws/model.d.ts

@@ -0,0 +1,191 @@
+/**
+ * The WebSocket fourth of the project model: a *WebSocket API* — a target, a set of saved
+ * messages, and a tree of folders and requests, one request per socket connection the user wants
+ * to keep.
+ *
+ * A WebSocket API is the fourth sibling container beside a SOAP interface, a REST API and a gRPC
+ * API (ADR-0007). It identifies itself with `kind: websocket` at the top of every file it writes,
+ * so a file says what it is without anyone having to know which directory implies which protocol.
+ * In memory it is kept in its own list on the project so the compiler points at every surface that
+ * needs a fourth branch rather than letting a WebSocket API fall through a REST- or gRPC-shaped
+ * `if`.
+ *
+ * The same rules as the other models apply: every field is `readonly`, ids are ULIDs so an entity
+ * 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 { SslInfo } from '../http/tls.js';
+export { wsApiFolders, wsApiRequests, wsFolderRequests, wsMessageFileName } from './shape.js';
+/**
+ * Per-request transport settings. Every field is optional and an absent one means *inherit*, not
+ * *off*: the send resolves request → API → project → preference, exactly as a REST request does.
+ */
+export interface WsRequestSettings {
+    readonly handshakeTimeoutMs?: number;
+    readonly trustInvalid?: boolean;
+    readonly sslKeystoreRef?: string;
+    readonly bindAddress?: string;
+    /** Close the session when a received message is larger than this. */
+    readonly maxMessageBytes?: number;
+    readonly escapeProperties?: boolean;
+}
+/** A message saved under a request, ready to send without retyping it. */
+export interface WsSavedMessage {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly format: 'text' | 'binary';
+    /** The text as edited; for `binary`, base64. Stored in `<request-slug>.msg-<slug>.<ext>`. */
+    readonly content: string;
+}
+/** A saved WebSocket request: a URL to dial, headers and query to send, and saved messages. */
+export interface WsRequestDef {
+    readonly kind: 'websocket';
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    /** A path joined to the API's server URL, or an absolute `ws(s)://` / `http(s)://` URL. */
+    readonly url: string;
+    readonly query: readonly KeyValueEntry[];
+    readonly headers: readonly KeyValueEntry[];
+    readonly subprotocols: readonly string[];
+    readonly auth: AuthConfig;
+    readonly settings: WsRequestSettings;
+    readonly messages: readonly WsSavedMessage[];
+}
+/** A named node in a WebSocket API's tree. */
+export interface WsFolder {
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    /** Default credentials for everything inside, unless a child says otherwise. */
+    readonly auth?: AuthConfig;
+    readonly folders: readonly WsFolder[];
+    readonly requests: readonly WsRequestDef[];
+}
+/** Reserved for the contract import (#100); nothing in this plan reads it. */
+export interface WsDefinitionRef {
+    readonly kind: 'asyncapi';
+    readonly source: string;
+    readonly cache: boolean;
+}
+/** A WebSocket API: a server URL and a tree of folders and requests. */
+export interface WsApi {
+    readonly kind: 'websocket';
+    readonly id: string;
+    readonly name: string;
+    readonly slug: string;
+    readonly order: number;
+    readonly description?: string;
+    /** The server URL; may hold `${…}`; an environment overrides it under the API's slug. */
+    readonly url: string;
+    readonly headers: readonly KeyValueEntry[];
+    readonly auth?: AuthConfig;
+    readonly definition?: WsDefinitionRef;
+    readonly folders: readonly WsFolder[];
+    readonly requests: readonly WsRequestDef[];
+}
+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 {
+    readonly index: number;
+    readonly direction: 'sent' | 'received';
+    readonly opcode: WsOpcode;
+    /** Milliseconds since the session started. */
+    readonly at: number;
+    /** Payload bytes. */
+    readonly size: number;
+    readonly text?: string;
+    readonly base64?: string;
+    readonly close?: {
+        readonly code: number;
+        readonly reason: string;
+    };
+    readonly payloadTruncated?: boolean;
+}
+/** The handshake that opened (or failed to open) a WebSocket session. */
+export interface WsHandshake {
+    readonly url: string;
+    readonly requestHeaders: Readonly<Record<string, string>>;
+    readonly requestedSubprotocols: readonly string[];
+    readonly rawRequestHead?: string;
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly responseHeaders?: Readonly<Record<string, string>>;
+    readonly protocol?: string;
+    readonly extensions?: string;
+    readonly remoteAddress?: string;
+    readonly startedAt: string;
+    readonly durationMs: number;
+    readonly tls?: SslInfo;
+    readonly error?: string;
+}
+/** A completed (or in-progress) WebSocket session: the handshake, its frames, and how it closed. */
+export interface WsExchange {
+    readonly kind: 'websocket';
+    readonly url: string;
+    readonly handshake: WsHandshake;
+    readonly frames: readonly WsFrame[];
+    readonly closed: {
+        readonly code: number;
+        readonly reason: string;
+        readonly by: 'client' | 'server' | 'error';
+    };
+    readonly counts: {
+        readonly sent: number;
+        readonly received: number;
+        readonly bytesSent: number;
+        readonly bytesReceived: number;
+    };
+    readonly durationMs: number;
+}
+/** Input to {@link createWsApi} beyond the name. */
+export interface CreateWsApiInput extends CreateOptions {
+    readonly url?: string;
+    readonly slug?: string;
+    readonly description?: string;
+    readonly headers?: readonly KeyValueEntry[];
+    readonly auth?: AuthConfig;
+    readonly definition?: WsDefinitionRef;
+    readonly folders?: readonly WsFolder[];
+    readonly requests?: readonly WsRequestDef[];
+}
+/** Creates an empty WebSocket API. */
+export declare function createWsApi(name: string, input?: CreateWsApiInput): WsApi;
+/** Input to {@link createWsFolder} beyond the name. */
+export interface CreateWsFolderInput extends CreateOptions {
+    readonly slug?: string;
+    readonly description?: string;
+    readonly auth?: AuthConfig;
+    readonly folders?: readonly WsFolder[];
+    readonly requests?: readonly WsRequestDef[];
+}
+/** Creates an empty folder. */
+export declare function createWsFolder(name: string, input?: CreateWsFolderInput): WsFolder;
+/** Input to {@link createWsRequest} beyond the name. */
+export interface CreateWsRequestInput extends CreateOptions {
+    readonly slug?: string;
+    readonly description?: string;
+    readonly url?: string;
+    readonly query?: readonly KeyValueEntry[];
+    readonly headers?: readonly KeyValueEntry[];
+    readonly subprotocols?: readonly string[];
+    readonly auth?: AuthConfig;
+    readonly settings?: WsRequestSettings;
+    readonly messages?: readonly WsSavedMessage[];
+}
+/** Creates a request with an empty URL and inherited credentials, and nothing saved. */
+export declare function createWsRequest(name: string, input?: CreateWsRequestInput): WsRequestDef;
+/** Creates a saved message, text and empty by default. */
+export declare function createWsSavedMessage(name: string, input?: CreateOptions & {
+    readonly slug?: string;
+    readonly format?: 'text' | 'binary';
+    readonly content?: string;
+}): WsSavedMessage;
+export type { IdGenerator };

package/dist/ws/model.js

@@ -0,0 +1,83 @@
+/**
+ * The WebSocket fourth of the project model: a *WebSocket API* — a target, a set of saved
+ * messages, and a tree of folders and requests, one request per socket connection the user wants
+ * to keep.
+ *
+ * A WebSocket API is the fourth sibling container beside a SOAP interface, a REST API and a gRPC
+ * API (ADR-0007). It identifies itself with `kind: websocket` at the top of every file it writes,
+ * so a file says what it is without anyone having to know which directory implies which protocol.
+ * In memory it is kept in its own list on the project so the compiler points at every surface that
+ * needs a fourth branch rather than letting a WebSocket API fall through a REST- or gRPC-shaped
+ * `if`.
+ *
+ * The same rules as the other models apply: every field is `readonly`, ids are ULIDs so an entity
+ * 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 { generateId } from '../project/model.js';
+import { slugify } from '../project/paths.js';
+// The pure tree and naming rules live in `shape.ts`, which imports nothing but `pretty.ts`, so the
+// renderer can have them without `node:path` coming along; they are re-exported here because this
+// is where callers expect a ws model rule to be.
+export { wsApiFolders, wsApiRequests, wsFolderRequests, wsMessageFileName } from './shape.js';
+function idOf(options) {
+    return options?.id ?? (options?.newId ?? generateId)();
+}
+/** Creates an empty WebSocket API. */
+export function createWsApi(name, input = {}) {
+    return {
+        kind: 'websocket',
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        url: input.url ?? '',
+        headers: input.headers ?? [],
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        ...(input.definition !== undefined ? { definition: input.definition } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates an empty folder. */
+export function createWsFolder(name, input = {}) {
+    return {
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        ...(input.auth !== undefined ? { auth: input.auth } : {}),
+        folders: input.folders ?? [],
+        requests: input.requests ?? [],
+    };
+}
+/** Creates a request with an empty URL and inherited credentials, and nothing saved. */
+export function createWsRequest(name, input = {}) {
+    return {
+        kind: 'websocket',
+        id: idOf(input),
+        name,
+        slug: input.slug ?? slugify(name),
+        order: input.order ?? 0,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+        url: input.url ?? '',
+        query: input.query ?? [],
+        headers: input.headers ?? [],
+        subprotocols: input.subprotocols ?? [],
+        auth: input.auth ?? { type: 'inherit' },
+        settings: input.settings ?? {},
+        messages: input.messages ?? [],
+    };
+}
+/** Creates a saved message, text and empty by default. */
+export function createWsSavedMessage(name, input) {
+    return {
+        id: idOf(input),
+        name,
+        slug: input?.slug ?? slugify(name),
+        format: input?.format ?? 'text',
+        content: input?.content ?? '',
+    };
+}

package/dist/ws/pretty.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Frame text pretty-printing for the WebSocket log: JSON is reformatted with `JSON.stringify`, XML
+ * with the engine's tolerant formatter, and anything else is left as-is. Browser-safe: `formatXml`
+ * (from `xml/pretty.ts`) never throws and pulls no `node:` import.
+ */
+/** The result of {@link prettyFrameText}: the detected language and the text to display. */
+export interface PrettyFrameResult {
+    readonly language: 'json' | 'xml' | 'text';
+    readonly pretty: string;
+}
+/** Reformats a WebSocket frame's text for display, detecting JSON or XML, else leaving it as text. */
+export declare function prettyFrameText(text: string): PrettyFrameResult;

package/dist/ws/pretty.js

@@ -0,0 +1,25 @@
+/**
+ * Frame text pretty-printing for the WebSocket log: JSON is reformatted with `JSON.stringify`, XML
+ * with the engine's tolerant formatter, and anything else is left as-is. Browser-safe: `formatXml`
+ * (from `xml/pretty.ts`) never throws and pulls no `node:` import.
+ */
+import { formatXml } from '../xml/pretty.js';
+/** Reformats a WebSocket frame's text for display, detecting JSON or XML, else leaving it as text. */
+export function prettyFrameText(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            return { language: 'json', pretty: JSON.stringify(JSON.parse(text), null, 2) };
+        }
+        catch {
+            // Not valid JSON despite the leading bracket; fall through to the other checks.
+        }
+    }
+    if (trimmed.startsWith('<')) {
+        const formatted = formatXml(text);
+        if (formatted.problem === undefined) {
+            return { language: 'xml', pretty: formatted.text };
+        }
+    }
+    return { language: 'text', pretty: text };
+}

package/dist/ws/session.d.ts

@@ -0,0 +1,50 @@
+import type { ProxyOptions, TlsOptions } from '../http/types.js';
+import { type TlsSocketLike } from '../http/tls.js';
+import type { WsExchange, WsFrame, WsHandshake } from './model.js';
+/** Options for {@link openWsSession}. */
+export interface WsSessionOptions {
+    readonly url: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** The connection fails if the server's response selects none of these. */
+    readonly subprotocols?: readonly string[];
+    readonly tls?: TlsOptions;
+    readonly proxy?: ProxyOptions;
+    readonly localAddress?: string;
+    /** Default 30 000. */
+    readonly handshakeTimeoutMs?: number;
+    /** Default unlimited. A larger received message ends the session from this side. */
+    readonly maxMessageBytes?: number;
+    readonly signal?: AbortSignal;
+}
+/** Hooks {@link openWsSession} calls as the session runs, in addition to `done`. */
+export interface WsSessionHooks {
+    onHandshake?(handshake: WsHandshake): void;
+    onFrame?(frame: WsFrame): void;
+    onClosed?(exchange: WsExchange): void;
+}
+/** A live WebSocket session, as returned by {@link openWsSession}. */
+export interface WsSessionHandle {
+    /** @throws WsError `ws-session-closed` */
+    send(data: string | Uint8Array): WsFrame;
+    /** Idempotent. @throws WsError `ws-bad-close` for a code an application may not send. */
+    close(code?: number, reason?: string): void;
+    readonly isOpen: boolean;
+    /** Never rejects. */
+    readonly done: Promise<WsExchange>;
+}
+/**
+ * True when `message` (an `undici:client:sendHeaders` payload) is this session's own WebSocket
+ * upgrade request. Matched by origin and path *and* required to carry `Sec-WebSocket-Key`
+ * (case-insensitively, in the raw head), so a concurrent plain HTTP request to the same URL —
+ * same origin, same path, no upgrade — can never donate its head or TLS info to this session.
+ *
+ * Exported only for its own unit test (ordering a diagnostics-channel race reliably isn't
+ * possible); not part of the package's public surface — `index.ts` does not re-export it.
+ */
+export declare function isUpgradeHeadFor(message: unknown, httpOrigin: string, pathAndSearch: string): message is {
+    headers: string;
+    socket?: TlsSocketLike & {
+        encrypted?: boolean;
+    };
+};
+export declare function openWsSession(options: WsSessionOptions, hooks?: WsSessionHooks): WsSessionHandle;