@wirebench/engine 2.1.1

package/dist/ws/session.js

@@ -0,0 +1,333 @@
+/**
+ * One WebSocket connection from handshake to close, and the only file that touches undici's
+ * WebSocket. It knows nothing about projects or containers: a saved WebSocket request opens one
+ * through `call.ts`, and anything else that needs a socket — a subscription protocol layered on a
+ * subprotocol, a contract check wrapped around `onFrame` — opens one the same way.
+ *
+ * Whatever the server does is a result. `done` never rejects: a refused handshake, a dropped
+ * socket and a clean close all resolve with the exchange that records them. A bad *option* is
+ * different — it never reaches the server, so it throws synchronously instead, and cleans up
+ * whatever it had already built (subscriptions, an owned dispatcher) before doing so.
+ */
+import diagnosticsChannel from 'node:diagnostics_channel';
+import { ProxyAgent, WebSocket } from 'undici';
+import { WsError } from '../errors.js';
+import { createDispatcher, proxyAgentOptionsFor } from '../http/client.js';
+import { sslInfoForSocket } from '../http/tls.js';
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 30_000;
+/** RFC 6455 §7.4, as the WHATWG API enforces it: 1000, or the 3000–4999 range. */
+function assertCloseCode(code) {
+    if (code !== 1000 && !(code >= 3000 && code <= 4999)) {
+        throw new WsError('ws-bad-close', `${code} is not a close code an application may send (1000, or 3000–4999)`, {
+            details: { code },
+        });
+    }
+}
+// undici's WebSocket API reports a plain refusal (e.g. a 401) and a completed-but-mismatched
+// handshake (a 101 whose Sec-WebSocket-Protocol selects none of what we offered) identically: an
+// empty `error.message`. So this default text names the offered subprotocols whenever there were
+// any, since that ambiguous case is the one where the extra detail actually helps the reader. It
+// is only ever used before a handshake has happened — see the `error` listener below.
+function defaultHandshakeError(subprotocols) {
+    if (subprotocols !== undefined && subprotocols.length > 0) {
+        return `The server refused the WebSocket handshake, or selected none of the offered subprotocols (${subprotocols.join(', ')})`;
+    }
+    return 'The server refused the WebSocket handshake';
+}
+/** A message naming what was wrong with `options`, for the `ws-bad-options` error below. */
+function describeBadOptions(options, err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return `The WebSocket options for "${options.url}" are invalid: ${reason}`;
+}
+/**
+ * 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 function isUpgradeHeadFor(message, httpOrigin, pathAndSearch) {
+    const m = message;
+    if (typeof m.headers !== 'string')
+        return false;
+    const origin = typeof m.request?.origin === 'string'
+        ? m.request.origin
+        : m.request?.origin instanceof URL
+            ? m.request.origin.origin
+            : undefined;
+    if (origin !== httpOrigin || m.request?.path !== pathAndSearch)
+        return false;
+    return /sec-websocket-key/i.test(m.headers);
+}
+export function openWsSession(options, hooks = {}) {
+    const startedMs = performance.now();
+    const startedAt = new Date().toISOString();
+    const timeoutMs = options.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+    // Parsed before anything is built: a bad URL means there is nothing yet to clean up.
+    let target;
+    try {
+        target = new URL(options.url);
+    }
+    catch (err) {
+        throw new WsError('ws-bad-options', `"${options.url}" is not a valid URL`, {
+            cause: err,
+            details: { url: options.url },
+        });
+    }
+    // `createDispatcher({ proxy })` does not CONNECT-tunnel a WebSocket handshake: undici rewrites
+    // `ws:`/`wss:` to `http:`/`https:` before dispatching, and `ProxyAgent` only tunnels `http:`
+    // when built with `proxyTunnel: true`. So a proxied session always owns its own `ProxyAgent`;
+    // an unproxied one owns a dispatcher only when it asked for TLS/bind-address options that
+    // `createDispatcher` would otherwise hand back the shared keep-alive agent for.
+    const ownsDispatcher = options.proxy !== undefined || options.tls !== undefined || options.localAddress !== undefined;
+    const httpOrigin = `${target.protocol === 'wss:' ? 'https:' : 'http:'}//${target.host}`;
+    const frames = [];
+    const counts = { sent: 0, received: 0, bytesSent: 0, bytesReceived: 0 };
+    let handshake;
+    let rawRequestHead;
+    let tls;
+    let closedBy;
+    let failure;
+    let settled = false;
+    const record = (direction, opcode, payload, close) => {
+        const bytes = typeof payload === 'string' ? Buffer.from(payload, 'utf8') : Buffer.from(payload);
+        const binaryish = opcode === 'binary' || ((opcode === 'ping' || opcode === 'pong') && bytes.length > 0);
+        const frame = {
+            index: frames.length,
+            direction,
+            opcode,
+            at: Math.round(performance.now() - startedMs),
+            size: bytes.length,
+            ...(opcode === 'text' ? { text: bytes.toString('utf8') } : {}),
+            ...(binaryish ? { base64: bytes.toString('base64') } : {}),
+            ...(close !== undefined ? { close } : {}),
+        };
+        frames.push(frame);
+        if (opcode === 'text' || opcode === 'binary') {
+            if (direction === 'sent') {
+                counts.sent += 1;
+                counts.bytesSent += bytes.length;
+            }
+            else {
+                counts.received += 1;
+                counts.bytesReceived += bytes.length;
+            }
+        }
+        hooks.onFrame?.(frame);
+        return frame;
+    };
+    const buildHandshake = (extra) => ({
+        url: options.url,
+        requestHeaders: { ...(options.headers ?? {}) },
+        requestedSubprotocols: [...(options.subprotocols ?? [])],
+        ...(rawRequestHead !== undefined ? { rawRequestHead } : {}),
+        startedAt,
+        durationMs: Math.round(performance.now() - startedMs),
+        ...(tls !== undefined ? { tls } : {}),
+        // The filter drops every `undefined`/empty-string entry at runtime, which is what makes this
+        // safe under `exactOptionalPropertyTypes`; the cast says so, since `Object.fromEntries` can't
+        // carry that through its own type.
+        ...Object.fromEntries(Object.entries(extra).filter(([, v]) => v !== undefined && v !== '')),
+    });
+    // Subscribed before the socket exists: undici starts the handshake inside the constructor.
+    // The request head and the TLS session come from the channel `TimingTracker` reads.
+    const onSendHeaders = (message) => {
+        if (rawRequestHead !== undefined)
+            return;
+        if (!isUpgradeHeadFor(message, httpOrigin, `${target.pathname}${target.search}`))
+            return;
+        rawRequestHead = message.headers;
+        if (message.socket?.encrypted === true)
+            tls = sslInfoForSocket(message.socket);
+    };
+    // Subscribed (and `socket` declared) before `new WebSocket(...)` runs: if a diagnostics channel
+    // ever delivered its payload before the assignment below completed, this ordering is what keeps
+    // the `m.websocket !== socket` identity checks below safe rather than comparing against `undefined`.
+    // `let`, not `const`: it is assigned exactly once, below (inside the try block that builds the
+    // socket), but declared here so those handlers' identity comparisons stay safe even if a
+    // diagnostics channel delivered its payload early.
+    let socket;
+    const onOpenChannel = (message) => {
+        const m = message;
+        if (m.websocket !== socket)
+            return;
+        handshake = buildHandshake({
+            status: m.handshakeResponse?.status,
+            statusText: m.handshakeResponse?.statusText,
+            responseHeaders: m.handshakeResponse?.headers,
+            protocol: m.protocol,
+            extensions: m.extensions,
+            remoteAddress: m.address?.address !== undefined ? `${m.address.address}:${m.address.port ?? ''}` : undefined,
+        });
+        // The handshake succeeded: there is no longer a timeout to guard against.
+        clearTimeout(timer);
+        hooks.onHandshake?.(handshake);
+    };
+    const onPing = (message) => {
+        const m = message;
+        if (m.websocket !== socket)
+            return;
+        const payload = m.payload ?? new Uint8Array();
+        record('received', 'ping', payload);
+        record('sent', 'pong', payload); // undici answers a ping itself, with the same payload
+    };
+    const onPong = (message) => {
+        const m = message;
+        if (m.websocket === socket)
+            record('received', 'pong', m.payload ?? new Uint8Array());
+    };
+    const unsubscribeAll = () => {
+        diagnosticsChannel.unsubscribe('undici:client:sendHeaders', onSendHeaders);
+        diagnosticsChannel.unsubscribe('undici:websocket:open', onOpenChannel);
+        diagnosticsChannel.unsubscribe('undici:websocket:ping', onPing);
+        diagnosticsChannel.unsubscribe('undici:websocket:pong', onPong);
+    };
+    // Everything that can throw synchronously for a bad *option* (a malformed proxy target, a
+    // subprotocol list the WHATWG API itself rejects — a duplicate entry or one with whitespace)
+    // happens in here, so a throw can unwind cleanly: unsubscribe whatever got subscribed, close an
+    // owned dispatcher if one got built, then report `ws-bad-options` instead of leaking either.
+    let dispatcher;
+    try {
+        dispatcher =
+            options.proxy !== undefined
+                ? new ProxyAgent(proxyAgentOptionsFor(options.proxy, {
+                    ...(options.tls !== undefined ? { tls: options.tls } : {}),
+                    ...(options.localAddress !== undefined ? { localAddress: options.localAddress } : {}),
+                }, false, { proxyTunnel: true }))
+                : createDispatcher({
+                    ...(options.tls !== undefined ? { tls: options.tls } : {}),
+                    ...(options.localAddress !== undefined ? { localAddress: options.localAddress } : {}),
+                });
+        diagnosticsChannel.subscribe('undici:client:sendHeaders', onSendHeaders);
+        diagnosticsChannel.subscribe('undici:websocket:open', onOpenChannel);
+        diagnosticsChannel.subscribe('undici:websocket:ping', onPing);
+        diagnosticsChannel.subscribe('undici:websocket:pong', onPong);
+        socket = new WebSocket(options.url, {
+            dispatcher,
+            ...(options.headers !== undefined ? { headers: { ...options.headers } } : {}),
+            ...(options.subprotocols !== undefined && options.subprotocols.length > 0
+                ? { protocols: [...options.subprotocols] }
+                : {}),
+        });
+    }
+    catch (err) {
+        unsubscribeAll();
+        if (ownsDispatcher)
+            void dispatcher?.close().catch(() => undefined);
+        throw new WsError('ws-bad-options', describeBadOptions(options, err), {
+            cause: err,
+            details: {
+                url: options.url,
+                ...(options.subprotocols !== undefined ? { subprotocols: options.subprotocols } : {}),
+            },
+        });
+    }
+    socket.binaryType = 'arraybuffer';
+    const ws = socket;
+    let resolveDone;
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    /** Settles the session exactly once, from whichever path gets there first. */
+    const settle = (code, reason, wasClean) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        options.signal?.removeEventListener('abort', onAbort);
+        unsubscribeAll();
+        const clean = wasClean && handshake !== undefined;
+        const by = closedBy ?? (clean ? 'server' : 'error');
+        if (clean)
+            record('received', 'close', reason, { code, reason });
+        // A handshake that already succeeded keeps no `error` on it, ever: the handshake is not what
+        // failed. A later break in the connection (a drop, a timeout that can't happen post-handshake,
+        // an abort) is expressed entirely by `closed: { by: 'error', ... }` below.
+        const settledHandshake = handshake ?? buildHandshake({ error: failure ?? defaultHandshakeError(options.subprotocols) });
+        const exchange = {
+            kind: 'websocket',
+            url: options.url,
+            handshake: settledHandshake,
+            frames,
+            closed: { code, reason, by },
+            counts: { ...counts },
+            durationMs: Math.round(performance.now() - startedMs),
+        };
+        // A failed close of an already-finished session tells the caller nothing useful — the
+        // exchange is done either way — so it is swallowed rather than surfaced.
+        if (ownsDispatcher)
+            void dispatcher?.close().catch(() => undefined);
+        hooks.onClosed?.(exchange);
+        resolveDone(exchange);
+    };
+    /** Ends a session the server never ended: a timeout, or an abort. */
+    const fail = (message) => {
+        failure ??= message;
+        closedBy ??= 'error';
+        // There is no abort for a connecting socket; close() on one fails the handshake, which is the point.
+        ws.close();
+    };
+    const timer = setTimeout(() => {
+        if (handshake === undefined)
+            fail(`The server did not answer the handshake within ${timeoutMs} ms`);
+    }, timeoutMs);
+    const onAbort = () => fail('The connection was cancelled');
+    if (options.signal?.aborted === true)
+        queueMicrotask(onAbort);
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    ws.addEventListener('message', (event) => {
+        const data = event.data;
+        const frame = typeof data === 'string' ? record('received', 'text', data) : record('received', 'binary', new Uint8Array(data));
+        if (options.maxMessageBytes !== undefined && frame.size > options.maxMessageBytes && closedBy === undefined) {
+            // 1009 is the code for this, and an application may not send it; 1000 with the reason is what it can say.
+            closedBy = 'client';
+            record('sent', 'close', 'message too big', { code: 1000, reason: 'message too big' });
+            ws.close(1000, 'message too big');
+        }
+    });
+    ws.addEventListener('error', (event) => {
+        const eventMessage = event.message;
+        const message = typeof eventMessage === 'string' ? eventMessage : '';
+        if (handshake === undefined) {
+            // Nothing has succeeded yet: this is a refusal (or an undici-internal empty-message variant
+            // of one — see `defaultHandshakeError`). A refused handshake may never fire `close` when the
+            // origin's connection is pooled, so `error` alone is authoritative for it. Settle on the next
+            // macrotask so a `close` that does arrive (as it does when this is the first connection to
+            // the origin) wins and carries its own code.
+            failure ??= message || defaultHandshakeError(options.subprotocols);
+            setTimeout(() => settle(1006, '', false), 0);
+        }
+        else {
+            // The handshake already succeeded; this describes the connection breaking afterward (e.g.
+            // the socket was dropped), not a refusal — it must never land in `handshake.error`. `settle`
+            // reports it via `closed: { by: 'error', ... }` instead.
+            failure ??= message || 'The connection was lost';
+        }
+    });
+    ws.addEventListener('close', (event) => {
+        settle(event.code, event.reason, event.wasClean);
+    });
+    return {
+        get isOpen() {
+            return ws.readyState === WebSocket.OPEN;
+        },
+        done,
+        send(data) {
+            if (ws.readyState !== WebSocket.OPEN)
+                throw new WsError('ws-session-closed', 'The connection is closed');
+            ws.send(data);
+            return record('sent', typeof data === 'string' ? 'text' : 'binary', data);
+        },
+        close(code = 1000, reason = '') {
+            if (ws.readyState === WebSocket.CLOSING || ws.readyState === WebSocket.CLOSED)
+                return;
+            assertCloseCode(code);
+            closedBy ??= 'client';
+            if (ws.readyState === WebSocket.OPEN)
+                record('sent', 'close', reason, { code, reason });
+            ws.close(code, reason);
+        },
+    };
+}

package/dist/ws/shape.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The pure tree and naming rules of a WebSocket API: walking its folders, and naming a saved
+ * message's file.
+ *
+ * A leaf on purpose. `model.ts` needs `project/paths.js` for its slugs, and that reaches
+ * `node:path`, which a renderer bundle cannot have — so the handful of rules the editor also needs
+ * live here, with no runtime imports but `pretty.ts` (itself browser-safe), and `model.ts`
+ * re-exports them so nothing else moved.
+ */
+import type { WsApi, WsFolder, WsRequestDef, WsSavedMessage } from './model.js';
+/** Every request in `folder` and, depth-first, in the folders below it. */
+export declare function wsFolderRequests(folder: Pick<WsFolder, 'folders' | 'requests'>): WsRequestDef[];
+/** Every request in `api`, its root requests first and then each folder depth-first. */
+export declare function wsApiRequests(api: WsApi): WsRequestDef[];
+/** Every folder in `api`, depth-first. */
+export declare function wsApiFolders(api: WsApi): WsFolder[];
+/** The file name a saved message is stored under, named by what it holds. */
+export declare function wsMessageFileName(requestSlug: string, message: Pick<WsSavedMessage, 'slug' | 'format' | 'content'>): string;

package/dist/ws/shape.js

@@ -0,0 +1,28 @@
+/**
+ * The pure tree and naming rules of a WebSocket API: walking its folders, and naming a saved
+ * message's file.
+ *
+ * A leaf on purpose. `model.ts` needs `project/paths.js` for its slugs, and that reaches
+ * `node:path`, which a renderer bundle cannot have — so the handful of rules the editor also needs
+ * live here, with no runtime imports but `pretty.ts` (itself browser-safe), and `model.ts`
+ * re-exports them so nothing else moved.
+ */
+import { prettyFrameText } from './pretty.js';
+/** Every request in `folder` and, depth-first, in the folders below it. */
+export function wsFolderRequests(folder) {
+    return [...folder.requests, ...folder.folders.flatMap((child) => wsFolderRequests(child))];
+}
+/** Every request in `api`, its root requests first and then each folder depth-first. */
+export function wsApiRequests(api) {
+    return wsFolderRequests(api);
+}
+/** Every folder in `api`, depth-first. */
+export function wsApiFolders(api) {
+    const walk = (folders) => folders.flatMap((folder) => [folder, ...walk(folder.folders)]);
+    return walk(api.folders);
+}
+/** The file name a saved message is stored under, named by what it holds. */
+export function wsMessageFileName(requestSlug, message) {
+    const language = message.format === 'binary' ? 'b64' : prettyFrameText(message.content).language;
+    return `${requestSlug}.msg-${message.slug}.${language === 'text' ? 'txt' : language}`;
+}

package/dist/ws/transcript.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What History keeps of a session. Both ends, because the end — the last messages before an
+ * unexpected close — is what a person comes back for, and a first-N cap loses exactly that.
+ */
+import type { WsFrame } from './model.js';
+export declare const WS_HISTORY_HEAD = 400;
+export declare const WS_HISTORY_TAIL = 100;
+export declare const WS_HISTORY_MAX_BYTES = 1048576;
+export interface WsTranscript {
+    readonly frames: readonly WsFrame[];
+    readonly truncated: boolean;
+    readonly omittedFrames: number;
+}
+export declare function capFrames(frames: readonly WsFrame[]): WsTranscript;

package/dist/ws/transcript.js

@@ -0,0 +1,29 @@
+export const WS_HISTORY_HEAD = 400;
+export const WS_HISTORY_TAIL = 100;
+export const WS_HISTORY_MAX_BYTES = 1_048_576;
+export function capFrames(frames) {
+    const limit = WS_HISTORY_HEAD + WS_HISTORY_TAIL;
+    const kept = frames.length <= limit ? [...frames] : [...frames.slice(0, WS_HISTORY_HEAD), ...frames.slice(-WS_HISTORY_TAIL)];
+    const omittedFrames = frames.length - kept.length;
+    let budget = WS_HISTORY_MAX_BYTES;
+    let stripped = false;
+    const capped = kept.map((frame) => {
+        if (frame.size <= budget) {
+            budget -= frame.size;
+            return frame;
+        }
+        if (frame.text === undefined && frame.base64 === undefined)
+            return frame;
+        stripped = true;
+        return {
+            index: frame.index,
+            direction: frame.direction,
+            opcode: frame.opcode,
+            at: frame.at,
+            size: frame.size,
+            ...(frame.close !== undefined ? { close: frame.close } : {}),
+            payloadTruncated: true,
+        };
+    });
+    return { frames: capped, truncated: omittedFrames > 0 || stripped, omittedFrames };
+}

package/dist/ws/url.d.ts

@@ -0,0 +1,3 @@
+import type { KeyValueEntry } from '../rest/model.js';
+/** The URL a session dials: the request's own when absolute, else its path under the server URL. */
+export declare function resolveWsUrl(serverUrl: string, requestUrl: string, query: readonly KeyValueEntry[]): string;

package/dist/ws/url.js

@@ -0,0 +1,44 @@
+import { WsError } from '../errors.js';
+const SCHEME = { 'ws:': 'ws:', 'wss:': 'wss:', 'http:': 'ws:', 'https:': 'wss:' };
+// Trimmed by hand rather than by regex: `/\/+$/` has to retry from every position in a string of
+// many slashes, which costs time in the square of its length.
+function trimTrailingSlashes(text) {
+    let end = text.length;
+    while (end > 0 && text[end - 1] === '/')
+        end -= 1;
+    return text.slice(0, end);
+}
+function trimLeadingSlashes(text) {
+    let start = 0;
+    while (start < text.length && text[start] === '/')
+        start += 1;
+    return text.slice(start);
+}
+/** The URL a session dials: the request's own when absolute, else its path under the server URL. */
+export function resolveWsUrl(serverUrl, requestUrl, query) {
+    const absolute = /^[a-z][a-z0-9+.-]*:\/\//i.test(requestUrl);
+    const joined = absolute
+        ? requestUrl
+        : requestUrl === ''
+            ? serverUrl
+            : `${trimTrailingSlashes(serverUrl)}/${trimLeadingSlashes(requestUrl)}`;
+    let url;
+    try {
+        url = new URL(joined);
+    }
+    catch {
+        throw new WsError('ws-bad-url', `"${joined}" is not a URL`, { details: { url: joined } });
+    }
+    const scheme = SCHEME[url.protocol];
+    if (scheme === undefined) {
+        throw new WsError('ws-bad-url', `A WebSocket URL starts with ws:// or wss://, not ${url.protocol}//`, {
+            details: { url: joined },
+        });
+    }
+    url.protocol = scheme;
+    for (const row of query) {
+        if (row.enabled && row.name !== '')
+            url.searchParams.append(row.name, row.value);
+    }
+    return url.toString();
+}

package/dist/wsa/headers.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Builds, applies and strips the WS-Addressing header block of an outgoing SOAP envelope,
+ * for both the 2005/08 (W3C Recommendation) and the 2004/08 (Member Submission) versions.
+ *
+ * Header construction is deterministic: every non-deterministic input — the MessageID's UUID —
+ * is injected, so a golden test can pin the exact bytes.
+ */
+import type { Element } from '@xmldom/xmldom';
+import type { SoapEnvelopeVersion } from '../soap/envelope.js';
+import type { WsaConfig, WsaVersion } from './model.js';
+/** The prefix every generated WS-Addressing header binds its namespace to. */
+export declare const WSA_PREFIX = "wsa";
+/** The addressing namespace URI for `version`. */
+export declare function wsaNamespace(version: WsaVersion): string;
+/** The "anonymous" endpoint-reference address for `version`. */
+export declare function anonymousAddress(version: WsaVersion): string;
+/** The default `RelationshipType` of a `wsa:RelatesTo` for `version`. */
+export declare function defaultRelationshipType(version: WsaVersion): string;
+/** Everything a header block needs that the configuration itself does not carry. */
+export interface WsaHeaderContext {
+    /** The URL the request is about to be sent to; the default `wsa:To`. */
+    readonly endpoint: string;
+    /** The request's SOAPAction, used as the `wsa:Action` when the configuration names none. */
+    readonly soapAction?: string;
+    /** The WSDL-derived default action, used when neither the configuration nor SOAPAction says. */
+    readonly defaultAction: string;
+    /** Mints the MessageID's UUID; injected so golden tests are deterministic. */
+    readonly uuid: () => string;
+    readonly envelopeVersion: SoapEnvelopeVersion;
+    /**
+     * The prefix the target envelope binds its SOAP namespace to, used for the `mustUnderstand`
+     * attribute so it matches the envelope being addressed (`soap:mustUnderstand` for an envelope
+     * that uses `soap:`, not always `soapenv:`). Defaults to `soapenv`, the common case, when a
+     * caller builds headers without a real envelope in hand (e.g. a preview).
+     */
+    readonly envelopePrefix?: string;
+}
+/** The `wsa:Action` a send will carry, or `undefined` when it carries none. */
+export declare function effectiveAction(config: WsaConfig, ctx: Pick<WsaHeaderContext, 'soapAction' | 'defaultAction'>): string | undefined;
+/** The `wsa:To` a send will carry, or `undefined` when it carries none. */
+export declare function effectiveTo(config: WsaConfig, endpoint: string): string | undefined;
+/** The `wsa:MessageID` a send will carry, or `undefined` when it carries none. */
+export declare function effectiveMessageId(config: WsaConfig, uuid: () => string): string | undefined;
+/**
+ * Builds the `wsa:*` header elements for `config`, in WS-Addressing's own order:
+ * `Action`, `To`, `MessageID`, `ReplyTo`, `From`, `FaultTo`, `RelatesTo`.
+ *
+ * The elements belong to a scratch document; a caller inserting them into an envelope must
+ * `importNode` them first (as {@link applyWsaHeaders} does).
+ *
+ * @param config the effective configuration for this send
+ * @param ctx the endpoint, SOAPAction, WSDL default action, UUID source and SOAP version
+ * @returns the header elements, empty when the configuration produces none
+ */
+export declare function buildWsaHeaders(config: WsaConfig, ctx: WsaHeaderContext): readonly Element[];
+/**
+ * Writes `config`'s WS-Addressing headers into `envelopeXml`.
+ *
+ * Any `wsa:*` header already present — of *either* version — is removed first, so applying
+ * twice (or switching version) never leaves two contradicting `wsa:Action`s behind. The new
+ * block is inserted before every other header, which is where a reader looks for it.
+ *
+ * @param envelopeXml the envelope to address
+ * @param config the effective configuration for this send
+ * @param ctx the endpoint, SOAPAction, default action, UUID source and SOAP version
+ * @returns the serialized, addressed envelope
+ * @throws WirebenchError `wsa-not-an-envelope` when `envelopeXml` is not a SOAP envelope
+ */
+export declare function applyWsaHeaders(envelopeXml: string, config: WsaConfig, ctx: WsaHeaderContext): string;
+/**
+ * Removes every WS-Addressing header (either version) from `envelopeXml`.
+ *
+ * A document that is not a SOAP envelope — or that carries no addressing at all — is returned
+ * byte for byte, so "Remove" on an untouched envelope is a genuine no-op.
+ *
+ * @param envelopeXml the envelope to clean
+ */
+export declare function stripWsaHeaders(envelopeXml: string): string;