@wirebench/engine 2.1.1

package/dist/http/curl.js

@@ -0,0 +1,245 @@
+/**
+ * Interoperability convenience: export a send as a `curl` command, and parse a pasted `curl` command
+ * back into a partial send input.
+ *
+ * {@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
+ * 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, "'\\''")}'`;
+}
+/** Escapes a value for a PowerShell single-quoted string. */
+function powershellQuote(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}
+/** Quotes one argument for `shell`; shared with the gRPC command renderer so both quote alike. */
+export function quoteForShell(value, shell) {
+    return shell === 'powershell' ? powershellQuote(value) : posixQuote(value);
+}
+/** The path a `@file` argument names, or a placeholder when no file has been chosen yet. */
+function filePath(path) {
+    return path.length > 0 ? path : '/path/to/file';
+}
+/**
+ * Builds a `curl` command from {@link CurlCommand}.
+ *
+ * A raw body travels as a heredoc (POSIX) or a here-string (PowerShell) rather than as a quoted
+ * argument: it may contain newlines, quotes and anything else, and a heredoc is the one form that
+ * carries all of it unchanged — which is also what {@link fromCurl} reads back.
+ */
+export function toCurl(command, options = {}) {
+    const shell = options.shell ?? 'posix';
+    const powershell = shell === 'powershell';
+    const quote = powershell ? powershellQuote : posixQuote;
+    const continuation = powershell ? '`' : '\\';
+    const program = powershell ? 'curl.exe' : 'curl';
+    const body = command.body ?? { kind: 'none' };
+    // The method and the URL stay on the first line together: that is the shape everyone recognises,
+    // and it is what makes the rest of the command read as a list of options rather than of arguments.
+    const args = [`--request ${command.method} ${quote(command.url)}`];
+    for (const header of command.headers) {
+        args.push(`--header ${quote(`${header.name}: ${header.value}`)}`);
+    }
+    if (command.basic !== undefined) {
+        args.push(`--user ${quote(`${command.basic.username}:${command.basic.password}`)}`);
+    }
+    if (command.insecure === true) {
+        args.push('--insecure');
+    }
+    if (command.followRedirects === true) {
+        args.push('--location');
+        if (command.maxRedirects !== undefined) {
+            args.push(`--max-redirs ${String(command.maxRedirects)}`);
+        }
+    }
+    switch (body.kind) {
+        case 'form':
+            for (const field of body.fields) {
+                args.push(`--data-urlencode ${quote(`${field.name}=${field.value}`)}`);
+            }
+            break;
+        case 'multipart':
+            for (const part of body.parts) {
+                const value = part.kind === 'file' ? `${part.name}=@${filePath(part.path)}` : `${part.name}=${part.value}`;
+                const typed = part.contentType !== undefined ? `${value};type=${part.contentType}` : value;
+                args.push(`--form ${quote(typed)}`);
+            }
+            break;
+        case 'binary':
+            args.push(`--data-binary ${quote(`@${filePath(body.path)}`)}`);
+            break;
+        case 'raw':
+            args.push(powershell ? `--data-binary @'` : `--data-binary @- <<'EOF'`);
+            break;
+        default:
+            break;
+    }
+    const lines = [];
+    const last = args.length - 1;
+    args.forEach((argument, index) => {
+        const prefix = index === 0 ? `${program} ` : '  ';
+        // The heredoc opener must be the last argument, and takes no continuation: its body follows.
+        const tail = index === last ? '' : ` ${continuation}`;
+        lines.push(`${prefix}${argument}${tail}`);
+    });
+    if (body.kind === 'raw') {
+        lines.push(body.text, powershell ? `'@` : 'EOF');
+    }
+    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

@@ -0,0 +1,7 @@
+/**
+ * Decompresses `data` according to the response's `content-encoding` header
+ * (`gzip`, `x-gzip`, `deflate`, or `br`). Returns `data` unchanged for any
+ * other/absent encoding. Errors from a malformed compressed body propagate
+ * to the caller.
+ */
+export declare function decompressBody(data: Uint8Array, contentEncoding: string | undefined): Promise<Uint8Array>;

package/dist/http/decompress.js

@@ -0,0 +1,22 @@
+import { brotliDecompress, 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
+ * other/absent encoding. Errors from a malformed compressed body propagate
+ * to the caller.
+ */
+export async function decompressBody(data, contentEncoding) {
+    const encoding = contentEncoding?.trim().toLowerCase();
+    const buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    switch (encoding) {
+        case 'gzip':
+        case 'x-gzip':
+            return new Uint8Array(await new Promise((resolve, reject) => gunzip(buf, (err, out) => (err ? reject(err) : resolve(out)))));
+        case 'deflate':
+            return new Uint8Array(await new Promise((resolve, reject) => inflate(buf, (err, out) => (err ? reject(err) : resolve(out)))));
+        case 'br':
+            return new Uint8Array(await new Promise((resolve, reject) => brotliDecompress(buf, (err, out) => (err ? reject(err) : resolve(out)))));
+        default:
+            return data;
+    }
+}

package/dist/http/errors.d.ts

@@ -0,0 +1,22 @@
+import { HttpError } from '../errors.js';
+/**
+ * Maps a raw error thrown by undici/Node's networking stack (or our own deadline
+ * timer) into a stable {@link HttpError} with an {@link HttpErrorCode}. `userAborted`
+ * distinguishes a caller-triggered abort from the deadline timer firing so we can
+ * report `aborted` vs `timeout` correctly even though both surface as AbortError.
+ * `hadProxy` (the request had `proxy` set) is used to route connection-level
+ * failures and undici's proxy errors to the `proxy` code instead of `connection-refused`/`network`.
+ * `host` names the peer in a `tls-untrusted` message when Node did not attach the offending
+ * certificate to the error (undici's connector usually does not), so the user is always told
+ * *which* server they are being asked to trust.
+ */
+export declare function toHttpError(err: unknown, options: {
+    readonly userAborted: boolean;
+    readonly deadlineHit: boolean;
+    readonly hadProxy?: boolean;
+    readonly host?: string;
+}): HttpError;
+/** Builds the `HttpError('invalid-url')` thrown when `req.url` cannot be parsed. */
+export declare function invalidUrlError(url: string, cause: unknown): HttpError;
+/** Builds the `HttpError('too-many-redirects')` thrown when the redirect cap is exceeded. */
+export declare function tooManyRedirectsError(maxRedirects: number): HttpError;

package/dist/http/errors.js

@@ -0,0 +1,144 @@
+import { HttpError } from '../errors.js';
+/**
+ * The verification failures that mean "the chain did not lead to a trusted root" — as opposed
+ * to a protocol or handshake failure. These are the ones a CA bundle (or the endpoint's
+ * "Trust invalid certificates" flag) actually fixes, so they get their own code and their own
+ * remedy-shaped message.
+ */
+const UNTRUSTED_CODES = new Set([
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'UNABLE_TO_GET_ISSUER_CERT',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+    'CERT_UNTRUSTED',
+]);
+/** Node/undici error codes recognized as TLS/certificate failures. */
+const TLS_CODE_PATTERNS = [
+    /^CERT_/,
+    /^ERR_TLS_/,
+    /^ERR_SSL_/,
+    /^DEPTH_ZERO_SELF_SIGNED_CERT$/,
+    /^UNABLE_TO_VERIFY_LEAF_SIGNATURE$/,
+    /^SELF_SIGNED_CERT_IN_CHAIN$/,
+];
+/**
+ * The peer's subject DN, when Node attached the offending certificate to the error (it does,
+ * for every verification failure raised by `tls.connect`). Rendered `CN=x, O=y` in the
+ * certificate's own attribute order, matching `PeerCert.subject`, so the problem row and the
+ * SSL inspector name the same thing. `undefined` when the error carries no certificate.
+ */
+function peerSubjectOf(err) {
+    const chain = [err];
+    for (let depth = 0; depth < 4 && chain.length > 0; depth += 1) {
+        const current = chain.shift();
+        if (current === null || typeof current !== 'object')
+            continue;
+        const cert = current.cert;
+        if (cert !== null && typeof cert === 'object') {
+            const subject = cert.subject;
+            if (subject !== null && typeof subject === 'object') {
+                const parts = [];
+                for (const [key, value] of Object.entries(subject)) {
+                    if (Array.isArray(value)) {
+                        for (const item of value)
+                            parts.push(`${key}=${String(item)}`);
+                    }
+                    else {
+                        parts.push(`${key}=${String(value)}`);
+                    }
+                }
+                if (parts.length > 0)
+                    return parts.join(', ');
+            }
+        }
+        chain.push(current.cause);
+    }
+    return undefined;
+}
+/** Extracts a Node-style `code` (e.g. `ECONNREFUSED`) from an arbitrary thrown value, if any. */
+function nodeErrorCode(err) {
+    if (err !== null && typeof err === 'object' && 'code' in err) {
+        const code = err.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    return undefined;
+}
+/** True if `err` (or its cause chain) was raised because of an AbortSignal firing. */
+function isAbortError(err) {
+    if (err instanceof Error && err.name === 'AbortError')
+        return true;
+    if (err !== null && typeof err === 'object' && 'code' in err) {
+        return err.code === 'ABORT_ERR';
+    }
+    return false;
+}
+/** Builds `HttpError` constructor options, omitting `details` entirely when there's no code. */
+function optionsFor(cause, code) {
+    return code !== undefined ? { cause, details: { code } } : { cause };
+}
+/** Node error codes that indicate a connection-level failure (occur during connect, before any bytes flow). */
+const CONNECT_FAILURE_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'ECONNRESET']);
+/** True if `err`'s name or message mentions "Proxy" (undici's proxy-related errors do this). */
+function looksLikeProxyError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return /proxy/i.test(err.name) || /proxy/i.test(err.message);
+}
+/**
+ * Maps a raw error thrown by undici/Node's networking stack (or our own deadline
+ * timer) into a stable {@link HttpError} with an {@link HttpErrorCode}. `userAborted`
+ * distinguishes a caller-triggered abort from the deadline timer firing so we can
+ * report `aborted` vs `timeout` correctly even though both surface as AbortError.
+ * `hadProxy` (the request had `proxy` set) is used to route connection-level
+ * failures and undici's proxy errors to the `proxy` code instead of `connection-refused`/`network`.
+ * `host` names the peer in a `tls-untrusted` message when Node did not attach the offending
+ * certificate to the error (undici's connector usually does not), so the user is always told
+ * *which* server they are being asked to trust.
+ */
+export function toHttpError(err, options) {
+    const code = nodeErrorCode(err);
+    if (options.deadlineHit) {
+        return new HttpError('timeout', 'The request timed out.', optionsFor(err, code));
+    }
+    if (options.userAborted || isAbortError(err)) {
+        return new HttpError('aborted', 'The request was aborted.', optionsFor(err, code));
+    }
+    if (options.hadProxy === true &&
+        ((code !== undefined && CONNECT_FAILURE_CODES.has(code)) || looksLikeProxyError(err))) {
+        return new HttpError('proxy', 'Proxy connection failed.', optionsFor(err, code));
+    }
+    if (code === 'ECONNREFUSED') {
+        return new HttpError('connection-refused', 'Connection refused.', optionsFor(err, code));
+    }
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+        return new HttpError('dns', 'DNS lookup failed.', optionsFor(err, code));
+    }
+    if (code !== undefined && UNTRUSTED_CODES.has(code)) {
+        const peerSubject = peerSubjectOf(err);
+        const peer = peerSubject ?? options.host;
+        return new HttpError('tls-untrusted', `The server certificate${peer === undefined ? '' : ` for ${peer}`} is not trusted. Add its CA to the CA bundle, or turn on "Trust invalid certificates" for this endpoint.`, {
+            cause: err,
+            details: {
+                code,
+                ...(peerSubject !== undefined ? { peerSubject } : {}),
+                ...(options.host !== undefined ? { host: options.host } : {}),
+            },
+        });
+    }
+    if (code !== undefined && TLS_CODE_PATTERNS.some((pattern) => pattern.test(code))) {
+        return new HttpError('tls', 'TLS/certificate error.', optionsFor(err, code));
+    }
+    return new HttpError('network', err instanceof Error ? err.message : 'Network error.', optionsFor(err, code));
+}
+/** Builds the `HttpError('invalid-url')` thrown when `req.url` cannot be parsed. */
+export function invalidUrlError(url, cause) {
+    return new HttpError('invalid-url', `Invalid URL: ${url}`, { cause, details: { url } });
+}
+/** Builds the `HttpError('too-many-redirects')` thrown when the redirect cap is exceeded. */
+export function tooManyRedirectsError(maxRedirects) {
+    return new HttpError('too-many-redirects', `Exceeded maximum of ${maxRedirects} redirects.`, {
+        details: { maxRedirects },
+    });
+}

package/dist/http/failed-request.d.ts

@@ -0,0 +1,27 @@
+/** The most body bytes a transport error carries: enough to debug a send, small enough to log. */
+export declare const FAILED_REQUEST_BODY_CAP_BYTES: number;
+/**
+ * The request a transport error was raised for, as it was about to go on the wire: the last
+ * attempt's URL and method (after any redirects), its final headers (credentials applied, plus the
+ * `host` and `content-length` the transport adds) and at most {@link FAILED_REQUEST_BODY_CAP_BYTES}
+ * of its body. Unredacted — whoever shows it must redact it.
+ */
+export interface FailedRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    /** Absent when the attempt had no body. */
+    readonly bodyBase64?: string;
+    /** True when the body was longer than the cap and `bodyBase64` holds only its start. */
+    readonly bodyTruncated: boolean;
+}
+/** Builds the {@link FailedRequest} for one attempt, capping its body. */
+export declare function failedRequestFor(url: string, method: string, headers: Readonly<Record<string, string>>, body: Uint8Array | undefined): FailedRequest;
+/**
+ * Returns an `HttpError` with `details.request` set to `request` — a new one with the same code,
+ * message and cause, since `details` is read-only. Anything that is not an `HttpError` is
+ * returned as is.
+ */
+export declare function withFailedRequest(error: unknown, request: FailedRequest): unknown;
+/** The request a transport error was raised for, or `undefined` when it carries none (e.g. `invalid-url`). */
+export declare function failedRequestOf(error: unknown): FailedRequest | undefined;

package/dist/http/failed-request.js

@@ -0,0 +1,48 @@
+import { HttpError, isWirebenchError } from '../errors.js';
+/** The most body bytes a transport error carries: enough to debug a send, small enough to log. */
+export const FAILED_REQUEST_BODY_CAP_BYTES = 64 * 1024;
+/** Builds the {@link FailedRequest} for one attempt, capping its body. */
+export function failedRequestFor(url, method, headers, body) {
+    if (body === undefined || body.length === 0) {
+        return { url, method, headers: { ...headers }, bodyTruncated: false };
+    }
+    const truncated = body.length > FAILED_REQUEST_BODY_CAP_BYTES;
+    const kept = truncated ? body.subarray(0, FAILED_REQUEST_BODY_CAP_BYTES) : body;
+    return {
+        url,
+        method,
+        headers: { ...headers },
+        bodyBase64: Buffer.from(kept.buffer, kept.byteOffset, kept.byteLength).toString('base64'),
+        bodyTruncated: truncated,
+    };
+}
+/**
+ * Returns an `HttpError` with `details.request` set to `request` — a new one with the same code,
+ * message and cause, since `details` is read-only. Anything that is not an `HttpError` is
+ * returned as is.
+ */
+export function withFailedRequest(error, request) {
+    if (!(error instanceof HttpError) || error.details?.['request'] !== undefined) {
+        return error;
+    }
+    const rebuilt = new HttpError(error.code, error.message, {
+        ...(error.cause !== undefined ? { cause: error.cause } : {}),
+        details: { ...error.details, request },
+    });
+    if (error.stack !== undefined)
+        rebuilt.stack = error.stack;
+    return rebuilt;
+}
+/** The request a transport error was raised for, or `undefined` when it carries none (e.g. `invalid-url`). */
+export function failedRequestOf(error) {
+    if (!isWirebenchError(error))
+        return undefined;
+    const candidate = error.details?.['request'];
+    if (candidate === null || typeof candidate !== 'object')
+        return undefined;
+    const { url, method, headers } = candidate;
+    if (typeof url !== 'string' || typeof method !== 'string' || headers === null || typeof headers !== 'object') {
+        return undefined;
+    }
+    return candidate;
+}

package/dist/http/headers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Case-insensitive helpers for the header maps the transport passes around.
+ *
+ * HTTP header names are case-insensitive but the maps here are plain objects, so every
+ * lookup and every override has to compare case-folded names or a caller-supplied
+ * `Content-Type` would silently sit next to a computed `content-type`.
+ */
+/** Case-insensitively merges `override` onto `base`, letting `override`'s casing win for shared keys. */
+export declare function mergeHeaders(base: Readonly<Record<string, string>>, override: Readonly<Record<string, string>>): Record<string, string>;
+/** Sets a header, replacing any differently-cased entry of the same name. */
+export declare function setHeader(headers: Record<string, string>, name: string, value: string): void;
+/** Returns a copy of `headers` with `name` removed, case-insensitively. */
+export declare function withoutHeader(headers: Readonly<Record<string, string>>, name: string): Record<string, string>;
+/** Looks up a header case-insensitively. */
+export declare function headerValue(headers: Readonly<Record<string, string>>, name: string): string | undefined;

package/dist/http/headers.js

@@ -0,0 +1,50 @@
+/**
+ * Case-insensitive helpers for the header maps the transport passes around.
+ *
+ * HTTP header names are case-insensitive but the maps here are plain objects, so every
+ * lookup and every override has to compare case-folded names or a caller-supplied
+ * `Content-Type` would silently sit next to a computed `content-type`.
+ */
+/** Case-insensitively merges `override` onto `base`, letting `override`'s casing win for shared keys. */
+export function mergeHeaders(base, override) {
+    const merged = { ...base };
+    const lowerToKey = new Map(Object.keys(merged).map((key) => [key.toLowerCase(), key]));
+    for (const [key, value] of Object.entries(override)) {
+        const existingKey = lowerToKey.get(key.toLowerCase());
+        if (existingKey !== undefined && existingKey !== key) {
+            delete merged[existingKey];
+        }
+        merged[key] = value;
+        lowerToKey.set(key.toLowerCase(), key);
+    }
+    return merged;
+}
+/** Sets a header, replacing any differently-cased entry of the same name. */
+export function setHeader(headers, name, value) {
+    for (const key of Object.keys(headers)) {
+        if (key.toLowerCase() === name.toLowerCase() && key !== name) {
+            delete headers[key];
+        }
+    }
+    headers[name] = value;
+}
+/** Returns a copy of `headers` with `name` removed, case-insensitively. */
+export function withoutHeader(headers, name) {
+    const lower = name.toLowerCase();
+    const result = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== lower)
+            result[key] = value;
+    }
+    return result;
+}
+/** Looks up a header case-insensitively. */
+export function headerValue(headers, name) {
+    const lower = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lower) {
+            return value;
+        }
+    }
+    return undefined;
+}

package/dist/http/heredoc.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Finds the heredoc or here-string body embedded in a pasted `curl` command.
+ *
+ * Both cURL parsers (`http/curl.ts` for SOAP, `rest/curl.ts` for REST) need this and nothing else
+ * in common, so it lives here rather than in either. It scans instead of matching a regex: the
+ * pattern this replaces, `/<<\\s*'?(\\w+)'?\\r?\\n([\\s\\S]*?)\\r?\\n\\1/`, backtracks its lazy body against a
+ * backreference for every candidate `<<`, which is O(n²) on a command that a user pastes and can
+ * therefore be anything.
+ */
+/** A body found by {@link findHeredoc} or {@link findHereString}: what to keep, and where it sat. */
+export interface EmbeddedBody {
+    readonly body: string;
+    /** Offset of the opener (`<<` or `@'`) in the source text. */
+    readonly start: number;
+    /** Offset just past the closing delimiter line. */
+    readonly end: number;
+}
+/**
+ * Locates a POSIX heredoc: `<<EOF` or `<<'EOF'`, a newline, the body, a newline and `EOF` on a line
+ * of its own. The body is everything between the opening line and the first line that is exactly
+ * the delimiter; an opener with no such closing line is not a heredoc.
+ */
+export declare function findHeredoc(text: string): EmbeddedBody | undefined;
+/** Locates a PowerShell here-string: `@'`, a newline, the body, a newline and `'@`. */
+export declare function findHereString(text: string): EmbeddedBody | undefined;