@wirebench/engine 2.1.1

package/dist/rest/body.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Turning a {@link RestBody} into the bytes and `Content-Type` that go on the wire.
+ *
+ * Every kind is encoded here and nowhere else, so what the cURL export shows and what the
+ * transport sends come from one function. Files are never read by the engine itself: a
+ * {@link FileResolver} is injected, exactly as the SOAP attachment path does it, so the host keeps
+ * ownership of the project directory and its cache (ADR-0005).
+ */
+import type { AttachmentSource } from '../project/model.js';
+import type { KeyValueEntry, RawLanguage, RestBody } from './model.js';
+/** Reads the bytes behind one file reference. Rejects when the file cannot be read. */
+export type FileResolver = (source: AttachmentSource) => Promise<Uint8Array>;
+/** Options for {@link encodeRestBody}. */
+export interface EncodeBodyOptions {
+    /** How a `multipart` or `binary` body's files are read. Required for those kinds only. */
+    readonly resolveFile?: FileResolver;
+    /** Charset for a raw or form body. Default `utf-8`; see `soap/charset.ts` for the labels. */
+    readonly charset?: string;
+    /** Fixed multipart boundary; a random one is generated otherwise. Tests inject it. */
+    readonly boundary?: string;
+    readonly signal?: AbortSignal;
+}
+/** What one body contributes to the request: its bytes, and the type that describes them. */
+export interface EncodedBody {
+    /** Absent for `{kind: 'none'}` — not an empty array, which would still send `Content-Length: 0`. */
+    readonly bytes?: Uint8Array;
+    /** Absent when the body does not imply one; a header the request sets itself always wins. */
+    readonly contentType?: string;
+}
+/** The `Content-Type` a raw body implies when neither the body nor a header names one. */
+export declare function rawContentType(language: RawLanguage, declared: string | undefined, charset?: string): string;
+/**
+ * `application/x-www-form-urlencoded`, per the URL-encoded form serialisation every HTML form and
+ * every server that parses one uses: space becomes `+`, everything else percent-encodes, and a
+ * disabled row is simply not there.
+ */
+export declare function encodeFormFields(fields: readonly KeyValueEntry[]): string;
+/**
+ * Encodes one request body.
+ *
+ * `{kind: 'none'}` produces no bytes at all rather than an empty buffer, so a `GET` does not
+ * announce a zero-length body it does not have. Every other kind produces both bytes and the
+ * `Content-Type` that describes them; the caller decides whether a header the request set itself
+ * overrides it (`rest/send.ts` does).
+ *
+ * @throws WirebenchError `rest-file-unresolved` when a file part or binary body has no resolver
+ */
+export declare function encodeRestBody(body: RestBody, options?: EncodeBodyOptions): Promise<EncodedBody>;
+/**
+ * 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;
+/** The language a body's escaping follows, for {@link escapeForLanguage}. */
+export declare function bodyLanguage(body: RestBody): RawLanguage | 'form' | undefined;
+/** The media type of an encoded body, without its parameters; `undefined` when it has none. */
+export declare function encodedMediaType(encoded: EncodedBody): string | undefined;

package/dist/rest/body.js

@@ -0,0 +1,184 @@
+/**
+ * Turning a {@link RestBody} into the bytes and `Content-Type` that go on the wire.
+ *
+ * Every kind is encoded here and nowhere else, so what the cURL export shows and what the
+ * transport sends come from one function. Files are never read by the engine itself: a
+ * {@link FileResolver} is injected, exactly as the SOAP attachment path does it, so the host keeps
+ * ownership of the project directory and its cache (ADR-0005).
+ */
+import { randomBytes } from 'node:crypto';
+import { WirebenchError } from '../errors.js';
+import { encodeBody } from '../soap/charset.js';
+import { mediaTypeOf } from '../soap/mime/multipart.js';
+import { RAW_LANGUAGE_CONTENT_TYPES } from './model.js';
+const CRLF = '\r\n';
+/** A fresh multipart boundary: long, random, and unable to occur in base64 or text. */
+function newBoundary() {
+    return `----WirebenchBoundary${randomBytes(16).toString('hex')}`;
+}
+/** The `Content-Type` a raw body implies when neither the body nor a header names one. */
+export function rawContentType(language, declared, charset) {
+    const base = declared ?? RAW_LANGUAGE_CONTENT_TYPES[language];
+    if (charset === undefined || /charset=/i.test(base)) {
+        return base;
+    }
+    const normalized = charset.toLowerCase();
+    return normalized === 'utf-8' || normalized === 'utf8' ? base : `${base}; charset=${charset}`;
+}
+/**
+ * `application/x-www-form-urlencoded`, per the URL-encoded form serialisation every HTML form and
+ * every server that parses one uses: space becomes `+`, everything else percent-encodes, and a
+ * disabled row is simply not there.
+ */
+export function encodeFormFields(fields) {
+    return fields
+        .filter((field) => field.enabled)
+        .map((field) => `${formEncode(field.name)}=${formEncode(field.value)}`)
+        .join('&');
+}
+function formEncode(value) {
+    return encodeURIComponent(value)
+        .replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)
+        .replace(/%20/g, '+');
+}
+/** Escapes a `filename`/`name` parameter for a `Content-Disposition` header (RFC 7578 §4.2). */
+function quoted(value) {
+    return `"${value.replace(/[\r\n"]/g, '_')}"`;
+}
+/** The file name a part advertises: the one it was given, else the last segment of its path. */
+function partFileName(part) {
+    if (part.fileName !== undefined) {
+        return part.fileName;
+    }
+    return part.source.kind === 'path' ? (part.source.path.split(/[\\/]/).pop() ?? part.name) : part.name;
+}
+/**
+ * Builds a `multipart/form-data` body (RFC 7578).
+ *
+ * Parts are written in author order, text before file only if that is how they were ordered — some
+ * services genuinely require a field before the file it describes, so nothing is reordered here.
+ * A text part gets a `Content-Type` only when it asked for one, since a server that sees none
+ * treats the part as `text/plain`, which is what an unadorned field means.
+ */
+async function encodeMultipart(parts, options) {
+    const boundary = options.boundary ?? newBoundary();
+    const chunks = [];
+    const push = (text) => {
+        chunks.push(new TextEncoder().encode(text));
+    };
+    for (const part of parts) {
+        if (!part.enabled) {
+            continue;
+        }
+        options.signal?.throwIfAborted();
+        if (part.kind === 'text') {
+            push(`--${boundary}${CRLF}Content-Disposition: form-data; name=${quoted(part.name)}${CRLF}`);
+            push(part.contentType !== undefined ? `Content-Type: ${part.contentType}${CRLF}${CRLF}` : CRLF);
+            chunks.push(encodeBody(part.value, options.charset));
+            push(CRLF);
+            continue;
+        }
+        const resolveFile = options.resolveFile;
+        if (resolveFile === undefined) {
+            throw new WirebenchError('rest-file-unresolved', 'A multipart file part needs a file resolver', {
+                details: { part: part.name },
+            });
+        }
+        const bytes = await resolveFile(part.source);
+        push(`--${boundary}${CRLF}Content-Disposition: form-data; name=${quoted(part.name)}; filename=${quoted(partFileName(part))}${CRLF}Content-Type: ${part.contentType ?? 'application/octet-stream'}${CRLF}${CRLF}`);
+        chunks.push(bytes);
+        push(CRLF);
+    }
+    push(`--${boundary}--${CRLF}`);
+    return { bytes: concat(chunks), contentType: `multipart/form-data; boundary=${boundary}` };
+}
+/** Joins byte chunks into one buffer, allocating exactly once. */
+function concat(chunks) {
+    let total = 0;
+    for (const chunk of chunks) {
+        total += chunk.byteLength;
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * Encodes one request body.
+ *
+ * `{kind: 'none'}` produces no bytes at all rather than an empty buffer, so a `GET` does not
+ * announce a zero-length body it does not have. Every other kind produces both bytes and the
+ * `Content-Type` that describes them; the caller decides whether a header the request set itself
+ * overrides it (`rest/send.ts` does).
+ *
+ * @throws WirebenchError `rest-file-unresolved` when a file part or binary body has no resolver
+ */
+export async function encodeRestBody(body, options = {}) {
+    switch (body.kind) {
+        case 'none':
+            return {};
+        case 'raw':
+            return {
+                bytes: encodeBody(body.text, options.charset),
+                contentType: rawContentType(body.language, body.contentType, options.charset),
+            };
+        case 'form':
+            return {
+                bytes: encodeBody(encodeFormFields(body.fields), options.charset),
+                contentType: 'application/x-www-form-urlencoded',
+            };
+        case 'multipart':
+            return encodeMultipart(body.parts, options);
+        case 'binary': {
+            const resolveFile = options.resolveFile;
+            if (resolveFile === undefined) {
+                throw new WirebenchError('rest-file-unresolved', 'A binary body needs a file resolver', {
+                    details: { source: body.source.kind },
+                });
+            }
+            return { bytes: await resolveFile(body.source), contentType: body.contentType };
+        }
+    }
+}
+/**
+ * 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;
+}
+/** The language a body's escaping follows, for {@link escapeForLanguage}. */
+export function bodyLanguage(body) {
+    switch (body.kind) {
+        case 'raw':
+            return body.language;
+        case 'form':
+        case 'multipart':
+            return 'form';
+        default:
+            return undefined;
+    }
+}
+/** The media type of an encoded body, without its parameters; `undefined` when it has none. */
+export function encodedMediaType(encoded) {
+    return encoded.contentType === undefined ? undefined : mediaTypeOf(encoded.contentType);
+}

package/dist/rest/browser.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Browser-safe subpath export (`@wirebench/engine/rest`): the URL helpers the REST editor needs in
+ * the renderer, with no dependency on a Node module.
+ *
+ * The renderer has to split a URL into a path and a query table, put it back together, and find the
+ * `{param}` placeholders in it — and it must do all three *exactly* as the send path does, or the
+ * table and the URL would disagree about what is being sent. Re-exporting the engine's own
+ * implementation is the only way to guarantee that; duplicating it in the renderer would mean two
+ * sets of escaping rules to keep in step.
+ */
+export { composeUrl, encodeValue, joinBase, joinQuery, parseUrlParams, splitQuery, type ComposedUrl, type ComposeUrlOptions, type UrlProblem, } from './url.js';
+export type { KeyValueEntry } from './model.js';

package/dist/rest/browser.js

@@ -0,0 +1,11 @@
+/**
+ * Browser-safe subpath export (`@wirebench/engine/rest`): the URL helpers the REST editor needs in
+ * the renderer, with no dependency on a Node module.
+ *
+ * The renderer has to split a URL into a path and a query table, put it back together, and find the
+ * `{param}` placeholders in it — and it must do all three *exactly* as the send path does, or the
+ * table and the URL would disagree about what is being sent. Re-exporting the engine's own
+ * implementation is the only way to guarantee that; duplicating it in the renderer would mean two
+ * sets of escaping rules to keep in step.
+ */
+export { composeUrl, encodeValue, joinBase, joinQuery, parseUrlParams, splitQuery, } from './url.js';

package/dist/rest/cookies.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which of a response's cookies go back out on the next send of the same request.
+ *
+ * Wirebench keeps no cookie jar: a request remembers what its own last response set, for the
+ * session only, and sends the matching ones when its *send cookies* setting is on. That is a
+ * deliberate limit rather than an unfinished one — a shared jar makes one request's send depend on
+ * another's, which is exactly what makes a saved request stop being reproducible — and nothing here
+ * ever reaches disk.
+ *
+ * Matching follows RFC 6265 §5.1.3 and §5.1.4 (domain-match and path-match) and §5.3 (expiry).
+ */
+import type { Cookie } from './response.js';
+/** True when `host` is `domain` or a subdomain of it (RFC 6265 §5.1.3). */
+export declare function domainMatches(host: string, domain: string): boolean;
+/** The default path of a cookie set by `pathname`: everything up to its last `/` (§5.1.4). */
+export declare function defaultPath(pathname: string): string;
+/** True when a cookie scoped to `cookiePath` applies to `requestPath` (§5.1.4). */
+export declare function pathMatches(requestPath: string, cookiePath: string): boolean;
+/** Whether a cookie has expired at `now`, by `Max-Age` first and then `Expires` (§5.3). */
+export declare function isExpired(cookie: Cookie, now: Date, setAt?: Date): boolean;
+/** Options for {@link cookiesToSend}. */
+export interface CookieMatchOptions {
+    /** When the cookies were received, for a `Max-Age` that is relative to that moment. */
+    readonly setAt?: Date;
+}
+/**
+ * The cookies of `cookies` that a request to `url` should carry at `now`.
+ *
+ * A cookie with no `Domain` is host-only, so it goes back only to the host that set it — which, for
+ * a per-request memory, is the host it was sent from unless the URL changed. `Secure` cookies never
+ * travel over plain HTTP, malformed lines are never sent at all, and an expired cookie is dropped
+ * rather than sent and rejected.
+ */
+export declare function cookiesToSend(cookies: readonly Cookie[], url: string, now?: Date, options?: CookieMatchOptions): Cookie[];
+/**
+ * The `Cookie` header value for `cookies`, or `undefined` when there is nothing to send.
+ *
+ * One header with `; `-separated pairs, which is what RFC 6265 §5.4 asks for; a duplicate name
+ * keeps its last value, since that is the one the server most recently set.
+ */
+export declare function cookieHeader(cookies: readonly Cookie[]): string | undefined;

package/dist/rest/cookies.js

@@ -0,0 +1,102 @@
+/**
+ * Which of a response's cookies go back out on the next send of the same request.
+ *
+ * Wirebench keeps no cookie jar: a request remembers what its own last response set, for the
+ * session only, and sends the matching ones when its *send cookies* setting is on. That is a
+ * deliberate limit rather than an unfinished one — a shared jar makes one request's send depend on
+ * another's, which is exactly what makes a saved request stop being reproducible — and nothing here
+ * ever reaches disk.
+ *
+ * Matching follows RFC 6265 §5.1.3 and §5.1.4 (domain-match and path-match) and §5.3 (expiry).
+ */
+/** True when `host` is `domain` or a subdomain of it (RFC 6265 §5.1.3). */
+export function domainMatches(host, domain) {
+    const lowerHost = host.toLowerCase();
+    const lowerDomain = domain.replace(/^\./, '').toLowerCase();
+    if (lowerHost === lowerDomain) {
+        return true;
+    }
+    return lowerHost.endsWith(`.${lowerDomain}`) && !/^\d+(?:\.\d+){3}$/.test(lowerHost);
+}
+/** The default path of a cookie set by `pathname`: everything up to its last `/` (§5.1.4). */
+export function defaultPath(pathname) {
+    if (!pathname.startsWith('/')) {
+        return '/';
+    }
+    const lastSlash = pathname.lastIndexOf('/');
+    return lastSlash === 0 ? '/' : pathname.slice(0, lastSlash);
+}
+/** True when a cookie scoped to `cookiePath` applies to `requestPath` (§5.1.4). */
+export function pathMatches(requestPath, cookiePath) {
+    const path = requestPath === '' ? '/' : requestPath;
+    if (path === cookiePath) {
+        return true;
+    }
+    if (!path.startsWith(cookiePath)) {
+        return false;
+    }
+    return cookiePath.endsWith('/') || path[cookiePath.length] === '/';
+}
+/** Whether a cookie has expired at `now`, by `Max-Age` first and then `Expires` (§5.3). */
+export function isExpired(cookie, now, setAt) {
+    if (cookie.maxAge !== undefined) {
+        if (cookie.maxAge <= 0) {
+            return true;
+        }
+        const from = setAt ?? now;
+        return now.getTime() > from.getTime() + cookie.maxAge * 1000;
+    }
+    if (cookie.expires === undefined) {
+        return false;
+    }
+    const expires = new Date(cookie.expires);
+    return !Number.isNaN(expires.getTime()) && expires.getTime() <= now.getTime();
+}
+/**
+ * The cookies of `cookies` that a request to `url` should carry at `now`.
+ *
+ * A cookie with no `Domain` is host-only, so it goes back only to the host that set it — which, for
+ * a per-request memory, is the host it was sent from unless the URL changed. `Secure` cookies never
+ * travel over plain HTTP, malformed lines are never sent at all, and an expired cookie is dropped
+ * rather than sent and rejected.
+ */
+export function cookiesToSend(cookies, url, now = new Date(), options = {}) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return [];
+    }
+    const secureContext = target.protocol === 'https:';
+    const requestPath = target.pathname === '' ? '/' : target.pathname;
+    return cookies.filter((cookie) => {
+        if (cookie.malformed === true || cookie.name === '') {
+            return false;
+        }
+        if (cookie.secure === true && !secureContext) {
+            return false;
+        }
+        if (isExpired(cookie, now, options.setAt)) {
+            return false;
+        }
+        if (cookie.domain !== undefined && !domainMatches(target.hostname, cookie.domain)) {
+            return false;
+        }
+        return pathMatches(requestPath, cookie.path ?? defaultPath(requestPath));
+    });
+}
+/**
+ * The `Cookie` header value for `cookies`, or `undefined` when there is nothing to send.
+ *
+ * One header with `; `-separated pairs, which is what RFC 6265 §5.4 asks for; a duplicate name
+ * keeps its last value, since that is the one the server most recently set.
+ */
+export function cookieHeader(cookies) {
+    const pairs = new Map();
+    for (const cookie of cookies) {
+        pairs.set(cookie.name, cookie.value);
+    }
+    const header = [...pairs].map(([name, value]) => `${name}=${value}`).join('; ');
+    return header === '' ? undefined : header;
+}

package/dist/rest/curl.d.ts

@@ -0,0 +1,75 @@
+/**
+ * A REST request as a `curl` command, and a pasted `curl` command as a REST request.
+ *
+ * Both directions are conveniences with a sharp edge: what is exported must be *exactly* what the app
+ * would send, or a user debugging a difference between the two chases a ghost. So the exporter takes
+ * the resolved {@link RestSendInput} — the same value the send path uses, with the URL composed, the
+ * credentials applied and the settings decided — rather than the saved request, which still has
+ * properties to expand and a chain of auth to walk.
+ *
+ * The importer is the looser half by nature: a command in the wild may use flags this client has no
+ * field for. Anything understood becomes a field, everything else becomes a problem the dialog shows,
+ * and nothing is guessed at.
+ */
+import type { ToCurlOptions } from '../http/curl.js';
+import type { KeyValueEntry, RestBody, RestMethod, RestRequestSettings } from './model.js';
+import type { RestSendInput } from './send.js';
+/** What a redacted secret reads as in an exported command. Matches the host's own marker. */
+export declare const CURL_REDACTED = "<redacted>";
+/** Options for {@link restToCurl}. */
+export interface RestToCurlOptions extends ToCurlOptions {
+    /**
+     * Replace every credential value with {@link CURL_REDACTED}. On unless the session's show-secrets
+     * switch is on, so a command copied for a colleague does not carry a token with it.
+     */
+    readonly redactSecrets?: boolean;
+}
+/**
+ * Builds a `curl` command for one resolved REST send.
+ *
+ * Credentials go on as they will go on the wire: a bearer token, an OAuth2 access token and a header
+ * API key as `--header`, a query API key in the URL, and Basic as `--user` — which is what `curl`
+ * users expect, and which also keeps a non-preemptive Basic credential behaving as it does here (curl
+ * waits for the challenge too).
+ */
+export declare function restToCurl(input: RestSendInput, options?: RestToCurlOptions): string;
+/** What a pasted command turned into, and what it could not. */
+export interface FromRestCurlResult {
+    /** The fields a new or edited request should take. Absent fields were not in the command. */
+    readonly request: {
+        readonly method?: RestMethod;
+        readonly url?: string;
+        readonly pathParams?: readonly KeyValueEntry[];
+        readonly query?: readonly KeyValueEntry[];
+        readonly headers?: readonly KeyValueEntry[];
+        readonly body?: RestBody;
+        readonly settings?: RestRequestSettings;
+    };
+    /**
+     * A `-u` password, for the caller to store in the keychain and reference. Never put in `request`:
+     * nothing in the model holds a credential value (ADR-0004).
+     */
+    readonly basic?: {
+        readonly username: string;
+        readonly password?: string;
+    };
+    /** What the command said that this client has no field for, in the order it was met. */
+    readonly problems: readonly string[];
+}
+/** Options for {@link fromRestCurl}. */
+export interface FromRestCurlOptions {
+    /**
+     * The API's base URL. A command whose URL starts with it is split, so the request keeps a relative
+     * path and follows the API's environment overrides like every other request in it.
+     */
+    readonly baseUrl?: string;
+}
+/**
+ * Reads a pasted `curl` command as a REST request.
+ *
+ * The body is decided by the most specific flag present, because a command may carry several: `-F`
+ * means multipart, `--data-urlencode` means a form, and a plain `-d` means raw in whatever the
+ * `Content-Type` says. A `-d` naming a file (`@path`) becomes a binary body pointing at that file,
+ * which is the reading that loses nothing.
+ */
+export declare function fromRestCurl(text: string, options?: FromRestCurlOptions): FromRestCurlResult;