@wirebench/engine 2.1.1

package/dist/wsa/headers.js

@@ -0,0 +1,244 @@
+/**
+ * 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 { WsaError } from '../errors.js';
+import { detectEnvelopeVersion, envelopeNamespace } from '../soap/envelope.js';
+import { NS } from '../xml/namespaces.js';
+import { parseXml } from '../xml/parse.js';
+import { serializeXml } from '../xml/serialize.js';
+/** The prefix every generated WS-Addressing header binds its namespace to. */
+export const WSA_PREFIX = 'wsa';
+/** The addressing namespace URI for `version`. */
+export function wsaNamespace(version) {
+    return version === '2004/08' ? NS.WSA_200408 : NS.WSA_200508;
+}
+/** The "anonymous" endpoint-reference address for `version`. */
+export function anonymousAddress(version) {
+    return version === '2004/08'
+        ? 'http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous'
+        : 'http://www.w3.org/2005/08/addressing/anonymous';
+}
+/** The default `RelationshipType` of a `wsa:RelatesTo` for `version`. */
+export function defaultRelationshipType(version) {
+    return version === '2004/08' ? 'wsa:Reply' : 'http://www.w3.org/2005/08/addressing/reply';
+}
+/** The `soap:mustUnderstand` attribute value meaning `true` for `version`. */
+function mustUnderstandLiteral(version, value) {
+    if (version === '1.2') {
+        return value;
+    }
+    return value === 'true' ? '1' : '0';
+}
+/** The `wsa:Action` a send will carry, or `undefined` when it carries none. */
+export function effectiveAction(config, ctx) {
+    if (config.action !== undefined && config.action.length > 0) {
+        return config.action;
+    }
+    if (!config.addDefaultAction) {
+        return undefined;
+    }
+    if (ctx.soapAction !== undefined && ctx.soapAction.length > 0) {
+        return ctx.soapAction;
+    }
+    return ctx.defaultAction.length > 0 ? ctx.defaultAction : undefined;
+}
+/** The `wsa:To` a send will carry, or `undefined` when it carries none. */
+export function effectiveTo(config, endpoint) {
+    if (config.to !== undefined && config.to.length > 0) {
+        return config.to;
+    }
+    if (!config.addDefaultTo) {
+        return undefined;
+    }
+    return endpoint.length > 0 ? endpoint : undefined;
+}
+/** The `wsa:MessageID` a send will carry, or `undefined` when it carries none. */
+export function effectiveMessageId(config, uuid) {
+    const configured = config.messageId;
+    if (configured !== undefined && configured.length > 0 && configured !== 'auto') {
+        return configured;
+    }
+    if (configured === 'auto' || config.generateMessageId) {
+        return `urn:uuid:${uuid()}`;
+    }
+    return undefined;
+}
+/** Resolves an endpoint-reference address, mapping the literal `anonymous` to the version's URI. */
+function addressOf(value, version) {
+    return value === 'anonymous' ? anonymousAddress(version) : value;
+}
+/**
+ * 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 function buildWsaHeaders(config, ctx) {
+    const ns = wsaNamespace(config.version);
+    const doc = parseXml(`<wsa:headers xmlns:wsa="${ns}"/>`, { location: 'wsa-headers' });
+    const owner = doc.documentElement;
+    /* v8 ignore next 3 */
+    if (owner === null) {
+        return [];
+    }
+    const envelopeNs = envelopeNamespace(ctx.envelopeVersion);
+    const envelopePrefix = ctx.envelopePrefix !== undefined && ctx.envelopePrefix.length > 0 ? ctx.envelopePrefix : 'soapenv';
+    const headers = [];
+    const create = (localName) => {
+        const element = doc.createElementNS(ns, `${WSA_PREFIX}:${localName}`);
+        if (config.mustUnderstand !== 'none') {
+            element.setAttributeNS(envelopeNs, `${envelopePrefix}:mustUnderstand`, mustUnderstandLiteral(ctx.envelopeVersion, config.mustUnderstand));
+        }
+        headers.push(element);
+        return element;
+    };
+    const text = (localName, value) => {
+        const element = create(localName);
+        element.appendChild(doc.createTextNode(value));
+        return element;
+    };
+    const epr = (localName, value) => {
+        const element = create(localName);
+        const address = doc.createElementNS(ns, `${WSA_PREFIX}:Address`);
+        address.appendChild(doc.createTextNode(addressOf(value, config.version)));
+        element.appendChild(address);
+    };
+    const action = effectiveAction(config, ctx);
+    if (action !== undefined) {
+        text('Action', action);
+    }
+    const to = effectiveTo(config, ctx.endpoint);
+    if (to !== undefined) {
+        text('To', to);
+    }
+    const messageId = effectiveMessageId(config, ctx.uuid);
+    if (messageId !== undefined) {
+        text('MessageID', messageId);
+    }
+    for (const [field, localName] of [
+        ['replyTo', 'ReplyTo'],
+        ['from', 'From'],
+        ['faultTo', 'FaultTo'],
+    ]) {
+        const value = config[field];
+        if (value !== undefined && value.length > 0) {
+            epr(localName, value);
+        }
+    }
+    if (config.relatesTo !== undefined && config.relatesTo.length > 0) {
+        const element = text('RelatesTo', config.relatesTo);
+        const relationship = config.relationshipType;
+        element.setAttribute('RelationshipType', relationship !== undefined && relationship.length > 0 ? relationship : defaultRelationshipType(config.version));
+    }
+    return headers;
+}
+/** Parses `envelopeXml`, rejecting anything that is not a SOAP envelope. */
+function parseEnvelope(envelopeXml) {
+    const doc = parseXml(envelopeXml, { location: 'envelope' });
+    const version = detectEnvelopeVersion(doc);
+    const root = doc.documentElement;
+    if (version === undefined || root === null) {
+        throw new WsaError('wsa-not-an-envelope', 'WS-Addressing can only be applied to a SOAP envelope.');
+    }
+    return { doc, root, version };
+}
+/** The direct child element of `parent` in `namespaceUri` with `localName`, if any. */
+function childElement(parent, namespaceUri, localName) {
+    for (let node = parent.firstChild; node !== null; node = node.nextSibling) {
+        if (node.nodeType === 1) {
+            const element = node;
+            if (element.namespaceURI === namespaceUri && element.localName === localName) {
+                return element;
+            }
+        }
+    }
+    return undefined;
+}
+/** The prefix the envelope binds its SOAP namespace to (`soapenv` when it uses a default one). */
+function envelopePrefix(root) {
+    const prefix = root.prefix;
+    return prefix === null || prefix === '' ? 'soapenv' : prefix;
+}
+/** Finds or creates the `soap:Header`, always placing a new one before the `Body`. */
+function ensureHeader(doc, root, version) {
+    const namespace = envelopeNamespace(version);
+    const existing = childElement(root, namespace, 'Header');
+    if (existing !== undefined) {
+        return existing;
+    }
+    const header = doc.createElementNS(namespace, `${envelopePrefix(root)}:Header`);
+    root.insertBefore(header, childElement(root, namespace, 'Body') ?? null);
+    return header;
+}
+/** Removes every `wsa:*` header of either version from `header`; returns how many went. */
+function removeExisting(header) {
+    const doomed = [];
+    for (let node = header.firstChild; node !== null; node = node.nextSibling) {
+        if (node.nodeType === 1) {
+            const element = node;
+            if (element.namespaceURI === NS.WSA_200508 || element.namespaceURI === NS.WSA_200408) {
+                doomed.push(element);
+            }
+        }
+    }
+    for (const element of doomed) {
+        header.removeChild(element);
+    }
+    return doomed.length;
+}
+/**
+ * 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 function applyWsaHeaders(envelopeXml, config, ctx) {
+    const { doc, root, version } = parseEnvelope(envelopeXml);
+    const header = ensureHeader(doc, root, version);
+    removeExisting(header);
+    const built = buildWsaHeaders(config, { ...ctx, envelopeVersion: version, envelopePrefix: envelopePrefix(root) });
+    const first = header.firstChild;
+    for (const element of built) {
+        header.insertBefore(doc.importNode(element, true), first);
+    }
+    return serializeXml(doc);
+}
+/**
+ * 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 function stripWsaHeaders(envelopeXml) {
+    let parsed;
+    try {
+        parsed = parseEnvelope(envelopeXml);
+    }
+    catch {
+        return envelopeXml;
+    }
+    const { doc, root, version } = parsed;
+    const header = childElement(root, envelopeNamespace(version), 'Header');
+    if (header === undefined) {
+        return envelopeXml;
+    }
+    return removeExisting(header) === 0 ? envelopeXml : serializeXml(doc);
+}

package/dist/wsa/model.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The WS-Addressing configuration model: what a request (or its interface) says about the
+ * `wsa:*` headers a send should carry, and how the two levels combine.
+ *
+ * Both levels hold the same shape. A request that defines no `wsa` at all inherits its
+ * interface's configuration wholesale; a request that defines one overrides the interface
+ * field by field, so a request can change only the `Action` and still follow the interface
+ * for everything else.
+ */
+/** The WS-Addressing specification version a header block is written in. */
+export type WsaVersion = '2005/08' | '2004/08';
+/**
+ * Whether (and how) a `soap:mustUnderstand` attribute is put on every `wsa:*` header:
+ * `'none'` writes no attribute at all, and is the default.
+ */
+export type WsaMustUnderstand = 'none' | 'true' | 'false';
+/** One level's WS-Addressing settings. */
+export interface WsaConfig {
+    readonly enabled: boolean;
+    readonly version: WsaVersion;
+    readonly mustUnderstand: WsaMustUnderstand;
+    /** Explicit `wsa:Action`; falls back to the SOAPAction and then the WSDL default action. */
+    readonly action?: string;
+    /** Explicit `wsa:To`; falls back to the endpoint URL when {@link addDefaultTo}. */
+    readonly to?: string;
+    /**
+     * The literal `'auto'` (or any empty value with {@link generateMessageId}) mints a fresh
+     * `urn:uuid:`; anything else is sent verbatim, so two sends share one MessageID.
+     */
+    readonly messageId?: string;
+    readonly replyTo?: string;
+    readonly from?: string;
+    readonly faultTo?: string;
+    readonly relatesTo?: string;
+    readonly relationshipType?: string;
+    readonly addDefaultAction: boolean;
+    readonly addDefaultTo: boolean;
+    readonly generateMessageId: boolean;
+}
+/**
+ * A partial configuration, as a project file written by an older build may hold. Every key is
+ * explicitly `| undefined` so a value parsed by zod (where an absent optional is present as
+ * `undefined`) is assignable under `exactOptionalPropertyTypes`.
+ */
+export type WsaConfigPatch = {
+    readonly [K in keyof WsaConfig]?: WsaConfig[K] | undefined;
+};
+/**
+ * The v1 defaults. They match what a project file from before the WS-Addressing task holds
+ * once the missing fields are filled in, so an old `{ enabled, version }` keeps working.
+ */
+export declare const DEFAULT_WSA_CONFIG: WsaConfig;
+/**
+ * Fills a (possibly partial) configuration out with {@link DEFAULT_WSA_CONFIG}.
+ *
+ * @param patch the stored configuration, or `undefined`
+ */
+export declare function normalizeWsa(patch: WsaConfigPatch | undefined): WsaConfig;
+/**
+ * The configuration one send actually runs with: the defaults, then the interface's settings,
+ * then the request's own — each level overriding the previous field by field.
+ *
+ * @param interfaceWsa the interface-level defaults
+ * @param requestWsa the request's own overrides, absent when the request inherits
+ */
+export declare function effectiveWsa(interfaceWsa: WsaConfigPatch | undefined, requestWsa: WsaConfigPatch | undefined): WsaConfig;

package/dist/wsa/model.js

@@ -0,0 +1,52 @@
+/**
+ * The WS-Addressing configuration model: what a request (or its interface) says about the
+ * `wsa:*` headers a send should carry, and how the two levels combine.
+ *
+ * Both levels hold the same shape. A request that defines no `wsa` at all inherits its
+ * interface's configuration wholesale; a request that defines one overrides the interface
+ * field by field, so a request can change only the `Action` and still follow the interface
+ * for everything else.
+ */
+/**
+ * The v1 defaults. They match what a project file from before the WS-Addressing task holds
+ * once the missing fields are filled in, so an old `{ enabled, version }` keeps working.
+ */
+export const DEFAULT_WSA_CONFIG = {
+    enabled: false,
+    version: '2005/08',
+    mustUnderstand: 'none',
+    addDefaultAction: true,
+    addDefaultTo: true,
+    generateMessageId: true,
+};
+/** Copies the keys of `patch` that are actually set onto `base`. */
+function merge(base, patch) {
+    if (patch === undefined) {
+        return base;
+    }
+    const next = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined) {
+            next[key] = value;
+        }
+    }
+    return next;
+}
+/**
+ * Fills a (possibly partial) configuration out with {@link DEFAULT_WSA_CONFIG}.
+ *
+ * @param patch the stored configuration, or `undefined`
+ */
+export function normalizeWsa(patch) {
+    return merge(DEFAULT_WSA_CONFIG, patch);
+}
+/**
+ * The configuration one send actually runs with: the defaults, then the interface's settings,
+ * then the request's own — each level overriding the previous field by field.
+ *
+ * @param interfaceWsa the interface-level defaults
+ * @param requestWsa the request's own overrides, absent when the request inherits
+ */
+export function effectiveWsa(interfaceWsa, requestWsa) {
+    return merge(merge(DEFAULT_WSA_CONFIG, interfaceWsa), requestWsa);
+}

package/dist/wsa/policy-detect.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Reads what a WSDL says about WS-Addressing, so an imported interface can turn addressing on
+ * by itself instead of making the user discover the requirement from a runtime fault.
+ *
+ * Three shapes are recognised, all of which real services use:
+ * - `wsaw:UsingAddressing` (or the 2004 `wsap:UsingAddressing`) on the binding or the port;
+ * - a `wsp:Policy` — attached inline or through a `wsp:PolicyReference` to a `#id` — that
+ *   contains `wsam:Addressing` or one of the `UsingAddressing` assertions;
+ * - `wsam:Action` (or `wsaw:Action`) on a `portType` operation's `wsdl:input`, which also
+ *   supplies that operation's default `wsa:Action`.
+ */
+import type { Binding, BindingOperation, Operation, PortType, WsdlDefinition } from '../wsdl/model.js';
+import type { QName } from '../wsdl/qname.js';
+import type { WsaVersion } from './model.js';
+/** What a WSDL says about WS-Addressing for one binding operation. */
+export interface WsaDetection {
+    /** True when the definition asks for WS-Addressing at all. */
+    readonly usingAddressing: boolean;
+    /** The addressing version the definition's markers imply. */
+    readonly version: WsaVersion;
+    /** The operation's default `wsa:Action`, when the WSDL declares one. */
+    readonly action?: string;
+    /**
+     * True when the only addressing markers found are `wsp:Optional="true"` and there is no
+     * declared `wsa:Action` to force it on anyway — the WSDL merely *offers* addressing, so it
+     * must not auto-enable (`usingAddressing` is `false` in this case).
+     */
+    readonly optional?: boolean;
+}
+/**
+ * The default `wsa:Action` for one operation, following the WS-Addressing 1.0 WSDL binding's
+ * precedence: an explicit `wsam:Action`, then a non-empty `soapAction`, then the default
+ * pattern `<targetNamespace>/<portType>/<operation>Request`.
+ *
+ * @param definition the definition the operation belongs to
+ * @param portType the operation's `wsdl:portType`
+ * @param operation the abstract `wsdl:operation`
+ * @param options `soapAction` from the binding operation, when it has one
+ */
+export declare function defaultAction(definition: WsdlDefinition, portType: PortType, operation: Operation, options?: {
+    readonly soapAction?: string;
+}): string;
+/**
+ * What `definition` says about WS-Addressing for one binding operation.
+ *
+ * `version` is `'2004/08'` only when *every* marker found is a 2004 one; a definition that
+ * mixes the two (or declares none at all) is treated as 2005/08, the version a modern stack
+ * speaks.
+ *
+ * @param definition the imported definition
+ * @param binding the binding the operation belongs to
+ * @param operation the binding operation, for its `soapAction` and abstract counterpart
+ */
+export declare function detectWsaDefaults(definition: WsdlDefinition, binding: Binding, operation: BindingOperation): WsaDetection;
+/** What an import records about WS-Addressing for a whole interface. */
+export interface WsaSummary {
+    /** True when any binding of the definition asks for WS-Addressing. */
+    readonly enabled: boolean;
+    /**
+     * True when no binding requires addressing but at least one only *offers* it
+     * (`wsp:Optional="true"`) — the inspector shows "WSDL offers WS-Addressing (optional)"
+     * rather than auto-enabling.
+     */
+    readonly optional: boolean;
+    readonly version: WsaVersion;
+    /**
+     * Each binding operation's default `wsa:Action`, keyed by Clark-notation binding QName and
+     * operation name (`{namespace}Binding|Operation`) so two bindings that happen to share an
+     * operation name do not overwrite each other's default action.
+     */
+    readonly defaultActionByOperation: Readonly<Record<string, string>>;
+}
+/** The `defaultActionByOperation` key for one binding operation: `{ns}Binding|Operation`. */
+export declare function wsaActionKey(bindingName: QName, operationName: string): string;
+/**
+ * Folds {@link detectWsaDefaults} and {@link defaultAction} over every binding operation, for
+ * the interface summary an import produces.
+ *
+ * @param definition the imported definition
+ */
+export declare function summarizeWsa(definition: WsdlDefinition): WsaSummary;