@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/http/curl.js

@@ -4,12 +4,9 @@
  *
  * {@link toCurl} describes a request in `curl`'s own terms — a method, a URL, headers and one of the
  * body shapes `curl` has a flag for — and knows nothing about SOAP or REST. Each protocol builds that
- * description from its own send input ({@link soapToCurl} here, `restToCurl` in `rest/curl.ts`), so the
+ * description from its own send input (`soapToCurl` in `soap/curl.ts`, `restToCurl` in `rest/curl.ts`), so the
  * quoting, the line continuations and the two shells have one implementation rather than two.
  */
-import { soapActionHeaders } from '../soap/soap-action.js';
-import { findHeredoc, findHereString } from './heredoc.js';
-import { expandBundles, takesNoValue } from './curl-flags.js';
 /** Escapes a value for a POSIX single-quoted shell string. */
 function posixQuote(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
@@ -52,6 +49,9 @@ export function toCurl(command, options = {}) {
     if (command.insecure === true) {
         args.push('--insecure');
     }
+    if (command.noBuffer === true) {
+        args.push('-N');
+    }
     if (command.followRedirects === true) {
         args.push('--location');
         if (command.maxRedirects !== undefined) {
@@ -93,153 +93,3 @@ export function toCurl(command, options = {}) {
     }
     return lines.join('\n');
 }
-/** Builds a `curl` command reproducing a SOAP send — headers, envelope and all. */
-export function soapToCurl(input, options = {}) {
-    const actionHeaders = soapActionHeaders(input.soapVersion, input.soapAction, input.skipSoapAction !== undefined ? { skipSoapAction: input.skipSoapAction } : {});
-    const contentType = input.contentType ?? input.headers?.['Content-Type'] ?? actionHeaders.contentType;
-    const headers = [{ name: 'Content-Type', value: contentType }];
-    if (input.soapVersion === '1.1' && input.headers?.['SOAPAction'] === undefined) {
-        headers.push({ name: 'SOAPAction', value: `"${input.soapAction ?? ''}"` });
-    }
-    for (const [name, value] of Object.entries(input.headers ?? {})) {
-        if (name === 'Content-Type')
-            continue;
-        headers.push({ name, value });
-    }
-    return toCurl({ method: 'POST', url: input.endpoint, headers, body: { kind: 'raw', text: input.envelopeXml } }, options);
-}
-/** Splits a command line into tokens, respecting single/double quoted spans (no `$'…'` support). */
-function tokenize(text) {
-    const tokens = [];
-    let i = 0;
-    const len = text.length;
-    while (i < len) {
-        while (i < len && /\s/.test(text[i]))
-            i += 1;
-        if (i >= len)
-            break;
-        let token = '';
-        while (i < len && !/\s/.test(text[i])) {
-            const ch = text[i];
-            if (ch === "'" || ch === '"') {
-                const quote = ch;
-                i += 1;
-                const start = i;
-                while (i < len && text[i] !== quote)
-                    i += 1;
-                token += text.slice(start, i);
-                i += 1;
-            }
-            else if (ch === '\\' && i + 1 < len) {
-                token += text[i + 1];
-                i += 2;
-            }
-            else if (ch === '`' || (ch === '\\' && text[i + 1] === '\n')) {
-                // line continuation markers; skip
-                i += 1;
-            }
-            else {
-                token += ch;
-                i += 1;
-            }
-        }
-        if (token.length > 0)
-            tokens.push(token);
-    }
-    return tokens;
-}
-/** Parses a pasted `curl` command back into a partial {@link SoapSendInput}. */
-export function fromCurl(text) {
-    const problems = [];
-    // Pull out a heredoc/here-string body (`<<'EOF' ... EOF` or `@'...'@`) before line-splicing and
-    // tokenizing the rest — its content is verbatim and may contain anything, including newlines.
-    let heredocData;
-    let withoutHeredoc = text;
-    const embedded = findHeredoc(text) ?? findHereString(text);
-    if (embedded !== undefined) {
-        heredocData = embedded.body;
-        withoutHeredoc = text.slice(0, embedded.start) + text.slice(embedded.end);
-    }
-    const normalized = withoutHeredoc
-        .replace(/\\\r?\n/g, ' ')
-        .replace(/`\r?\n/g, ' ')
-        .trim();
-    const tokens = expandBundles(tokenize(normalized));
-    let endpoint;
-    let envelopeXml;
-    const headers = {};
-    let i = 0;
-    if (tokens[0] === 'curl' || tokens[0] === 'curl.exe')
-        i += 1;
-    while (i < tokens.length) {
-        const tok = tokens[i];
-        if (tok === '-X' || tok === '--request') {
-            i += 2;
-            continue;
-        }
-        if (tok === '-H' || tok === '--header') {
-            const header = tokens[i + 1] ?? '';
-            const colon = header.indexOf(':');
-            if (colon !== -1) {
-                const key = header.slice(0, colon).trim();
-                const value = header.slice(colon + 1).trim();
-                headers[key] = value;
-            }
-            i += 2;
-            continue;
-        }
-        if (tok === '-d' || tok === '--data' || tok === '--data-binary' || tok === '--data-raw') {
-            const data = tokens[i + 1] ?? '';
-            if ((data === '@-' || data === '') && heredocData !== undefined) {
-                envelopeXml = heredocData;
-            }
-            else if (data.startsWith('@')) {
-                problems.push('data-from-file-unsupported');
-            }
-            else {
-                envelopeXml = data;
-            }
-            i += 2;
-            continue;
-        }
-        if (tok === '--url') {
-            endpoint = tokens[i + 1];
-            i += 2;
-            continue;
-        }
-        if (tok === '-u' || tok === '--user') {
-            problems.push('basic-auth-ignored');
-            i += 2;
-            continue;
-        }
-        if (tok.startsWith('-')) {
-            // A flag with no field here: skip its value too, unless it is one that takes none.
-            problems.push(`ignored-flag:${tok}`);
-            i += takesNoValue(tok) ? 1 : 2;
-            continue;
-        }
-        // bare token: the URL
-        if (endpoint === undefined) {
-            endpoint = tok;
-        }
-        i += 1;
-    }
-    const soapActionHeader = headers['SOAPAction'];
-    let soapAction;
-    if (soapActionHeader !== undefined) {
-        soapAction = soapActionHeader.replace(/^"|"$/g, '');
-    }
-    const contentType = headers['Content-Type'];
-    const soapVersion = contentType?.includes('application/soap+xml') === true ? '1.2' : '1.1';
-    const extraHeaders = { ...headers };
-    delete extraHeaders['SOAPAction'];
-    delete extraHeaders['Content-Type'];
-    const input = {
-        ...(endpoint !== undefined ? { endpoint } : {}),
-        ...(envelopeXml !== undefined ? { envelopeXml } : {}),
-        soapVersion,
-        ...(soapAction !== undefined ? { soapAction } : {}),
-        ...(Object.keys(extraHeaders).length > 0 ? { headers: extraHeaders } : {}),
-    };
-    return { input, problems };
-}

package/dist/http/decompress.d.ts

@@ -1,3 +1,4 @@
+import type { Transform } from 'node:stream';
 /**
  * Decompresses `data` according to the response's `content-encoding` header
  * (`gzip`, `x-gzip`, `deflate`, or `br`). Returns `data` unchanged for any
@@ -5,3 +6,9 @@
  * to the caller.
  */
 export declare function decompressBody(data: Uint8Array, contentEncoding: string | undefined): Promise<Uint8Array>;
+/**
+ * An incremental decoder for a streamed body with the given `content-encoding`, or `undefined` when
+ * the encoding needs none. Sync-flushes, so each chunk's decoded bytes come out as soon as they can
+ * rather than waiting for more input, and a stream cut short still yields what it decoded.
+ */
+export declare function createDecompressStream(contentEncoding: string | undefined): Transform | undefined;

package/dist/http/decompress.js

@@ -1,4 +1,4 @@
-import { brotliDecompress, gunzip, inflate } from 'node:zlib';
+import { brotliDecompress, constants, createBrotliDecompress, createGunzip, createInflate, gunzip, inflate, } from 'node:zlib';
 /**
  * Decompresses `data` according to the response's `content-encoding` header
  * (`gzip`, `x-gzip`, `deflate`, or `br`). Returns `data` unchanged for any
@@ -20,3 +20,25 @@ export async function decompressBody(data, contentEncoding) {
             return data;
     }
 }
+/**
+ * An incremental decoder for a streamed body with the given `content-encoding`, or `undefined` when
+ * the encoding needs none. Sync-flushes, so each chunk's decoded bytes come out as soon as they can
+ * rather than waiting for more input, and a stream cut short still yields what it decoded.
+ */
+export function createDecompressStream(contentEncoding) {
+    const zlibFlush = { flush: constants.Z_SYNC_FLUSH, finishFlush: constants.Z_SYNC_FLUSH };
+    switch (contentEncoding?.trim().toLowerCase()) {
+        case 'gzip':
+        case 'x-gzip':
+            return createGunzip(zlibFlush);
+        case 'deflate':
+            return createInflate(zlibFlush);
+        case 'br':
+            return createBrotliDecompress({
+                flush: constants.BROTLI_OPERATION_FLUSH,
+                finishFlush: constants.BROTLI_OPERATION_FLUSH,
+            });
+        default:
+            return undefined;
+    }
+}

package/dist/http/document-fetch.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The fetcher every OpenAPI and AsyncAPI read goes through.
+ *
+ * It sends through the engine's own HTTP client rather than the global `fetch`, so the proxy and CA
+ * bundle the host resolves apply to a definition as they do to a request. It follows redirects
+ * itself: `sendHttp` scopes only the three standard credential headers to an origin, and a
+ * definition's credentials may also be a custom API-key header or a query key. On every hop, and for
+ * every `$ref` document, credentials go only to the origin of the document the user named.
+ */
+import type { SendAuth } from './auth/send-auth.js';
+import type { FetchDocument } from './fetch-document.js';
+import type { ProxyOptions, TlsOptions } from './types.js';
+/** How {@link createHttpFetchDocument} reaches the network, and with what credentials. */
+export interface DocumentFetchOptions {
+    /** Resolved credentials: values, not references. Sent only to `authOrigin`. */
+    readonly auth?: SendAuth;
+    /**
+     * Origin of the document the user named; absent means no auth is ever attached. Normalised as a URL
+     * origin (a trailing slash, the host's case and a default port do not matter); it must be `http(s)`.
+     */
+    readonly authOrigin?: string;
+    /** TLS and proxy for one URL, as the host resolves them. */
+    readonly network?: (url: string) => Promise<{
+        readonly tls?: TlsOptions;
+        readonly proxy?: ProxyOptions;
+    }>;
+}
+/**
+ * Creates the {@link FetchDocument} for OpenAPI and AsyncAPI reads: `file:` (and any other non-HTTP
+ * location) as {@link createDefaultFetchDocument} reads it, and `http(s):` through `sendHttp` with
+ * the host's TLS and proxy, following up to 10 redirects, with `options.auth` sent only to
+ * `options.authOrigin`.
+ *
+ * The returned `location` never carries a query key this fetcher added, so `$ref` resolution,
+ * progress messages, errors and a recorded source never do either.
+ *
+ * @throws HttpError `definition-auth-required` for a 401 or 403 (`details.authSent` says whether
+ * credentials went with it), `fetch-failed` for any other non-2xx or a redirect off `http(s)`,
+ * `too-many-redirects`, or a transport error from `sendHttp` (without `details.request`)
+ * @throws HttpError `invalid-url`, at once, when `options.authOrigin` is not an `http(s)` URL
+ */
+export declare function createHttpFetchDocument(options?: DocumentFetchOptions): FetchDocument;

package/dist/http/document-fetch.js

@@ -0,0 +1,207 @@
+/**
+ * The fetcher every OpenAPI and AsyncAPI read goes through.
+ *
+ * It sends through the engine's own HTTP client rather than the global `fetch`, so the proxy and CA
+ * bundle the host resolves apply to a definition as they do to a request. It follows redirects
+ * itself: `sendHttp` scopes only the three standard credential headers to an origin, and a
+ * definition's credentials may also be a custom API-key header or a query key. On every hop, and for
+ * every `$ref` document, credentials go only to the origin of the document the user named.
+ */
+import { HttpError, WirebenchError } from '../errors.js';
+import { redactUrl } from '../redact/index.js';
+import { applyAuth } from './auth/apply-auth.js';
+import { decodeXmlBytes } from '../xml/decode.js';
+import { createDefaultFetchDocument } from './fetch-document.js';
+import { basicAuthorization } from './auth/basic.js';
+import { sendHttp } from './client.js';
+const TIMEOUT_MS = 20_000;
+const USER_AGENT = 'wirebench/0.1';
+const MAX_REDIRECTS = 10;
+/** A definition is JSON or YAML; anything else is still read, at a lower preference. */
+const ACCEPT = 'application/json, application/yaml, text/yaml, */*;q=0.8';
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const WEB_PROTOCOLS = new Set(['http:', 'https:']);
+/** `url` without the query parameter `name`; `url` itself, unparsed and unchanged, when it has none. */
+function withoutParam(url, name) {
+    const parsed = new URL(url);
+    if (!parsed.searchParams.has(name)) {
+        return url;
+    }
+    parsed.searchParams.delete(name);
+    return parsed.toString();
+}
+/**
+ * `authOrigin` as `URL.origin` writes it, so it compares equal to a hop's origin however the caller
+ * spelled it.
+ *
+ * @throws HttpError `invalid-url` when it is not an `http(s)` URL: an opaque origin (`null`, from
+ * `file:` or `data:`) must never match anything
+ */
+function normaliseAuthOrigin(authOrigin) {
+    let parsed;
+    try {
+        parsed = new URL(authOrigin);
+    }
+    catch {
+        throw new HttpError('invalid-url', `The origin credentials go to is not a URL: ${authOrigin}`, {
+            details: { authOrigin },
+        });
+    }
+    if (!WEB_PROTOCOLS.has(parsed.protocol)) {
+        throw new HttpError('invalid-url', `The origin credentials go to is not http(s): ${authOrigin}`, {
+            details: { authOrigin },
+        });
+    }
+    return parsed.origin;
+}
+/** What one hop sends: its URL (with a query key, on the auth origin) and its credential headers. */
+function credentialsFor(url, options) {
+    const { auth, authOrigin } = options;
+    if (auth === undefined || authOrigin === undefined) {
+        return { url, headers: {} };
+    }
+    const hop = new URL(url);
+    if (!WEB_PROTOCOLS.has(hop.protocol) || hop.origin !== authOrigin) {
+        return { url, headers: {} };
+    }
+    if (auth.type === 'basic') {
+        // Always preemptive: a definition endpoint that answers 401 is refused, not challenged through.
+        return { url, headers: { Authorization: basicAuthorization(auth.username, auth.password) } };
+    }
+    if (auth.type === 'api-key' && auth.in === 'query') {
+        const keyed = new URL(url);
+        keyed.searchParams.append(auth.name, auth.value);
+        return { url: keyed.toString(), headers: {} };
+    }
+    return { url, headers: applyAuth(auth).headers };
+}
+/**
+ * A transport failure from `sendHttp`, told without the credentials this hop carried.
+ *
+ * `details.request` always goes: it records the headers as sent, `Authorization` or an API-key header
+ * included. Every other detail stays, and `details.location` names the hop without a query key. When
+ * the hop carried a query key (`sent` differs from `bare`), the URL in the message is masked, any
+ * detail that repeats it is replaced by `bare`, and the `cause` goes too, since its text may hold it.
+ */
+function sanitisedFailure(error, sent, bare, keyName) {
+    if (!(error instanceof WirebenchError)) {
+        return error;
+    }
+    const keyed = keyName !== undefined && sent !== bare;
+    const details = {};
+    for (const [name, value] of Object.entries(error.details ?? {})) {
+        if (name !== 'request') {
+            details[name] = keyed && value === sent ? bare : value;
+        }
+    }
+    details['location'] = bare;
+    const message = keyed ? error.message.split(sent).join(redactUrl(sent, { extraParams: [keyName] })) : error.message;
+    const rebuilt = new HttpError(error.code, message, {
+        details,
+        ...(!keyed && error.cause !== undefined ? { cause: error.cause } : {}),
+    });
+    if (!keyed && error.stack !== undefined) {
+        rebuilt.stack = error.stack;
+    }
+    return rebuilt;
+}
+/**
+ * Where a redirect from `bare` to `target` leads.
+ *
+ * @throws HttpError `fetch-failed` when `target` is not a URL or not `http(s)`: a server must not
+ * steer a definition read onto the local disk or anywhere else outside the web
+ */
+function redirectTarget(target, bare, status) {
+    let next;
+    try {
+        next = new URL(target, bare);
+    }
+    catch {
+        throw new HttpError('fetch-failed', `GET ${bare} redirected to a location that is not a URL`, {
+            details: { location: bare, status },
+        });
+    }
+    if (!WEB_PROTOCOLS.has(next.protocol)) {
+        throw new HttpError('fetch-failed', `GET ${bare} redirected to a ${next.protocol} location; a definition read follows http(s) redirects only`, { details: { location: bare, status } });
+    }
+    return next.toString();
+}
+async function fetchHttp(location, signal, options) {
+    const keyName = options.auth?.type === 'api-key' && options.auth.in === 'query' ? options.auth.name : undefined;
+    // `bare` is the hop's URL as the resolver may see it: never with the key this fetcher adds, even
+    // when a server echoed it into a redirect's `Location`.
+    const start = keyName === undefined ? location : withoutParam(location, keyName);
+    let bare = start;
+    for (let hops = 0;; hops += 1) {
+        const { url, headers } = credentialsFor(bare, options);
+        const credentialsSent = url !== bare || Object.keys(headers).length > 0;
+        let exchange;
+        try {
+            // Inside the try: a cancel while the host resolves the proxy is a cancel too.
+            const network = (await options.network?.(bare)) ?? {};
+            signal?.throwIfAborted();
+            exchange = await sendHttp({
+                url,
+                method: 'GET',
+                headers: { 'user-agent': USER_AGENT, accept: ACCEPT, ...headers },
+                timeoutMs: TIMEOUT_MS,
+                followRedirects: false,
+                ...(signal !== undefined ? { signal } : {}),
+                ...(network.tls !== undefined ? { tls: network.tls } : {}),
+                ...(network.proxy !== undefined ? { proxy: network.proxy } : {}),
+            });
+        }
+        catch (error) {
+            // A cancel stays a cancel: the resolver tells an `AbortError` from a document that failed.
+            signal?.throwIfAborted();
+            throw sanitisedFailure(error, url, bare, keyName);
+        }
+        const target = exchange.headers['location'];
+        if (REDIRECT_STATUSES.has(exchange.status) && target !== undefined) {
+            if (hops >= MAX_REDIRECTS) {
+                throw new HttpError('too-many-redirects', `GET ${start} redirected more than ${String(MAX_REDIRECTS)} times`, {
+                    details: { location: start },
+                });
+            }
+            const next = redirectTarget(target, bare, exchange.status);
+            bare = keyName === undefined ? next : withoutParam(next, keyName);
+            continue;
+        }
+        if (exchange.status === 401 || exchange.status === 403) {
+            const status = String(exchange.status);
+            throw new HttpError('definition-auth-required', credentialsSent
+                ? `The definition at ${bare} refused the credentials given (HTTP ${status}).`
+                : `The definition at ${bare} needs authentication (HTTP ${status}).`, { details: { location: bare, status: exchange.status, authSent: credentialsSent } });
+        }
+        if (exchange.status < 200 || exchange.status >= 300) {
+            throw new HttpError('fetch-failed', `GET ${bare} failed with status ${String(exchange.status)}`, {
+                details: { location: bare, status: exchange.status },
+            });
+        }
+        return { location: bare, bytes: exchange.body, text: decodeXmlBytes(exchange.body) };
+    }
+}
+/**
+ * Creates the {@link FetchDocument} for OpenAPI and AsyncAPI reads: `file:` (and any other non-HTTP
+ * location) as {@link createDefaultFetchDocument} reads it, and `http(s):` through `sendHttp` with
+ * the host's TLS and proxy, following up to 10 redirects, with `options.auth` sent only to
+ * `options.authOrigin`.
+ *
+ * The returned `location` never carries a query key this fetcher added, so `$ref` resolution,
+ * progress messages, errors and a recorded source never do either.
+ *
+ * @throws HttpError `definition-auth-required` for a 401 or 403 (`details.authSent` says whether
+ * credentials went with it), `fetch-failed` for any other non-2xx or a redirect off `http(s)`,
+ * `too-many-redirects`, or a transport error from `sendHttp` (without `details.request`)
+ * @throws HttpError `invalid-url`, at once, when `options.authOrigin` is not an `http(s)` URL
+ */
+export function createHttpFetchDocument(options = {}) {
+    const resolved = options.authOrigin === undefined ? options : { ...options, authOrigin: normaliseAuthOrigin(options.authOrigin) };
+    const fallback = createDefaultFetchDocument();
+    return async (location, signal) => {
+        if (!/^https?:\/\//i.test(location)) {
+            return fallback(location, signal);
+        }
+        return fetchHttp(location, signal, resolved);
+    };
+}

package/dist/http/entries.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A row of a name/value table: a path or query parameter, a header, a form field, a metadata entry.
+ *
+ * In `http/` because REST, gRPC and WebSocket requests all keep such rows, and a protocol folder
+ * imports core and itself, never another protocol (protocol modules spec §7.2). `rest/model.ts`
+ * re-exports both names, so REST code and the public exports read them where they always did.
+ */
+/**
+ * One row of a params, query, headers or form table: a name, a value, and whether it takes part
+ * in the next send. Rows keep author order and may repeat a name — two `X-Trace` headers and two
+ * `tag=` parameters are both legal on the wire, so neither is deduplicated here.
+ *
+ * `enabled` is always present in memory and written to disk only when `false`, so a file stays
+ * quiet about the common case (see `project/serialize.ts`).
+ */
+export interface KeyValueEntry {
+    readonly name: string;
+    readonly value: string;
+    readonly enabled: boolean;
+    /** Free-form note, carried over from an imported definition's parameter description. */
+    readonly description?: string;
+}
+/** Creates an enabled {@link KeyValueEntry}. */
+export declare function entry(name: string, value: string, options?: {
+    readonly enabled?: boolean;
+    readonly description?: string;
+}): KeyValueEntry;

package/dist/http/entries.js

@@ -0,0 +1,16 @@
+/**
+ * A row of a name/value table: a path or query parameter, a header, a form field, a metadata entry.
+ *
+ * In `http/` because REST, gRPC and WebSocket requests all keep such rows, and a protocol folder
+ * imports core and itself, never another protocol (protocol modules spec §7.2). `rest/model.ts`
+ * re-exports both names, so REST code and the public exports read them where they always did.
+ */
+/** Creates an enabled {@link KeyValueEntry}. */
+export function entry(name, value, options) {
+    return {
+        name,
+        value,
+        enabled: options?.enabled ?? true,
+        ...(options?.description !== undefined ? { description: options.description } : {}),
+    };
+}

package/dist/http/escape.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Escaping a value that is substituted into a body, by the language the body is written in.
+ *
+ * In `http/` because the REST, gRPC and WebSocket expansions all apply it, and a protocol folder
+ * imports core and itself, never another protocol (protocol modules spec §7.2). `rest/model.ts`
+ * re-exports {@link RawLanguage} and `rest/body.ts` re-exports {@link escapeForLanguage}.
+ */
+/** The languages a raw body can be edited and sent as. Picks the editor mode and a default type. */
+export type RawLanguage = 'json' | 'xml' | 'text' | 'html' | 'javascript';
+/**
+ * XML- or JSON-escapes a value being substituted into a body, for the *escape properties* setting.
+ *
+ * Only the characters that would otherwise change the document's structure are touched. A JSON
+ * body gets JSON string escaping (without the surrounding quotes, since the value is substituted
+ * inside them); an XML body gets the five predefined entities; anything else is left alone,
+ * because there is no general escape for `text/plain`.
+ */
+export declare function escapeForLanguage(value: string, language: RawLanguage | 'form'): string;

package/dist/http/escape.js

@@ -0,0 +1,30 @@
+/**
+ * Escaping a value that is substituted into a body, by the language the body is written in.
+ *
+ * In `http/` because the REST, gRPC and WebSocket expansions all apply it, and a protocol folder
+ * imports core and itself, never another protocol (protocol modules spec §7.2). `rest/model.ts`
+ * re-exports {@link RawLanguage} and `rest/body.ts` re-exports {@link escapeForLanguage}.
+ */
+/**
+ * XML- or JSON-escapes a value being substituted into a body, for the *escape properties* setting.
+ *
+ * Only the characters that would otherwise change the document's structure are touched. A JSON
+ * body gets JSON string escaping (without the surrounding quotes, since the value is substituted
+ * inside them); an XML body gets the five predefined entities; anything else is left alone,
+ * because there is no general escape for `text/plain`.
+ */
+export function escapeForLanguage(value, language) {
+    if (language === 'json') {
+        const json = JSON.stringify(value);
+        return json.slice(1, -1);
+    }
+    if (language === 'xml' || language === 'html') {
+        return value
+            .replace(/&/g, '&')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')
+            .replace(/"/g, '&quot;')
+            .replace(/'/g, '&apos;');
+    }
+    return value;
+}

package/dist/http/fetch-document.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Fetching one document by its location: what a fetcher is, and the default one.
+ *
+ * In `http/` because the WSDL, OpenAPI and AsyncAPI imports all take a {@link FetchDocument}, and a
+ * protocol folder imports core and itself, never another protocol (protocol modules spec §7.2).
+ * `wsdl/resolver.ts` re-exports the two types.
+ */
+/** A fetched document's canonical location (post-redirect) and raw content. */
+export interface FetchedDocument {
+    /** The final absolute location after following any redirects. */
+    readonly location: string;
+    readonly bytes: Uint8Array;
+    readonly text: string;
+}
+/** Fetches a single document by absolute location, honouring an optional abort signal. */
+export type FetchDocument = (location: string, signal?: AbortSignal) => Promise<FetchedDocument>;
+/**
+ * Creates the default {@link FetchDocument} implementation: `file:` URLs are
+ * read from disk via `node:fs/promises`, and `http(s):` URLs are fetched via
+ * the global `fetch` (following redirects, with a 20s timeout combined with
+ * the caller's `AbortSignal`, and a `wirebench/0.1` User-Agent).
+ *
+ * Text is decoded as UTF-8 by default, honouring an `iso-8859-1` `encoding`
+ * in the document's XML declaration when present (see {@link decodeXmlBytes}
+ * for why `utf-16` isn't sniffed the same way). Other declared encodings
+ * fall back to UTF-8.
+ */
+export declare function createDefaultFetchDocument(): FetchDocument;

package/dist/{wsdl/fetch.js → http/fetch-document.js}

@@ -1,24 +1,16 @@
+/**
+ * Fetching one document by its location: what a fetcher is, and the default one.
+ *
+ * In `http/` because the WSDL, OpenAPI and AsyncAPI imports all take a {@link FetchDocument}, and a
+ * protocol folder imports core and itself, never another protocol (protocol modules spec §7.2).
+ * `wsdl/resolver.ts` re-exports the two types.
+ */
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { HttpError } from '../errors.js';
+import { decodeXmlBytes } from '../xml/decode.js';
 const DEFAULT_TIMEOUT_MS = 20_000;
 const USER_AGENT = 'wirebench/0.1';
-/**
- * Decodes bytes as UTF-8, honouring an `<?xml ... encoding="iso-8859-1" ?>`
- * declaration when present (single-byte, so it is safely sniffable by
- * decoding the head as UTF-8 first). A `utf-16` declaration would require a
- * BOM/byte-order sniff before the declaration itself is even legible, which
- * does not fit a small helper like this — such documents fall back to (and
- * garble under) UTF-8; use a pre-fetched `text` in that case instead.
- */
-function decodeXmlBytes(bytes) {
-    const head = new TextDecoder('utf-8').decode(bytes.subarray(0, 200));
-    const match = /^\s*<\?xml[^>]*\bencoding=["']([^"']+)["']/i.exec(head);
-    if (match?.[1]?.toLowerCase() === 'iso-8859-1') {
-        return new TextDecoder('iso-8859-1').decode(bytes);
-    }
-    return new TextDecoder('utf-8').decode(bytes);
-}
 async function fetchFile(location) {
     const bytes = await readFile(fileURLToPath(location));
     return { location, bytes: new Uint8Array(bytes), text: decodeXmlBytes(bytes) };

package/dist/http/media-type.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reading a `Content-Type` header value.
+ *
+ * In `http/` because the SOAP multipart code and the REST body and response code both need the bare
+ * media type, and a protocol folder imports core and itself, never another protocol (protocol
+ * modules spec §7.2). `soap/mime/multipart.ts` re-exports the name.
+ */
+/** The media type of a `Content-Type` header value, without its parameters. */
+export declare function mediaTypeOf(contentType: string): string;

package/dist/http/media-type.js

@@ -0,0 +1,12 @@
+/**
+ * Reading a `Content-Type` header value.
+ *
+ * In `http/` because the SOAP multipart code and the REST body and response code both need the bare
+ * media type, and a protocol folder imports core and itself, never another protocol (protocol
+ * modules spec §7.2). `soap/mime/multipart.ts` re-exports the name.
+ */
+/** The media type of a `Content-Type` header value, without its parameters. */
+export function mediaTypeOf(contentType) {
+    const semicolon = contentType.indexOf(';');
+    return (semicolon === -1 ? contentType : contentType.slice(0, semicolon)).trim();
+}