@wirebench/engine 2.1.1

package/dist/rest/curl.js

@@ -0,0 +1,417 @@
+/**
+ * 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 { toCurl } from '../http/curl.js';
+import { entry, RAW_LANGUAGE_CONTENT_TYPES } from './model.js';
+import { applyAuth } from './auth.js';
+import { findHeredoc, findHereString } from '../http/heredoc.js';
+import { expandBundles, takesNoValue } from '../http/curl-flags.js';
+import { composeUrl, splitQuery, trimTrailingSlashes } from './url.js';
+/** What a redacted secret reads as in an exported command. Matches the host's own marker. */
+export const CURL_REDACTED = '<redacted>';
+/** A stand-in that survives URL encoding untouched, swapped for {@link CURL_REDACTED} afterwards. */
+const QUERY_STAND_IN = 'wirebenchRedactedValue';
+/** The body of an exported command, per kind. */
+function curlBody(body) {
+    switch (body.kind) {
+        case 'raw':
+            return { kind: 'raw', text: body.text };
+        case 'form':
+            return {
+                kind: 'form',
+                fields: body.fields.filter((field) => field.enabled).map((field) => ({ name: field.name, value: field.value })),
+            };
+        case 'multipart':
+            return {
+                kind: 'multipart',
+                parts: body.parts
+                    .filter((part) => part.enabled)
+                    .map((part) => part.kind === 'file'
+                    ? {
+                        kind: 'file',
+                        name: part.name,
+                        path: part.source.kind === 'path' ? part.source.path : '',
+                        ...(part.contentType !== undefined ? { contentType: part.contentType } : {}),
+                    }
+                    : {
+                        kind: 'text',
+                        name: part.name,
+                        value: part.value,
+                        ...(part.contentType !== undefined ? { contentType: part.contentType } : {}),
+                    }),
+            };
+        case 'binary':
+            return { kind: 'binary', path: body.source.kind === 'path' ? body.source.path : '' };
+        default:
+            return { kind: 'none' };
+    }
+}
+/**
+ * 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 function restToCurl(input, options = {}) {
+    const redact = options.redactSecrets !== false;
+    const applied = applyAuth(input.auth);
+    // A credential in the query is composed under an encoding-safe stand-in and swapped afterwards:
+    // `composeUrl` would otherwise percent-encode the marker's own angle brackets, leaving the user
+    // reading `%3Credacted%3E` where the point was to be legible.
+    const composed = composeUrl(input.baseUrl, input.request.url, input.request.pathParams, [...input.request.query, ...applied.query.map((row) => (redact ? { ...row, value: QUERY_STAND_IN } : row))], { encode: input.settings.encodeUrl ?? true });
+    const url = redact ? composed.url.split(QUERY_STAND_IN).join(CURL_REDACTED) : composed.url;
+    const headers = [];
+    for (const row of input.request.headers) {
+        if (row.enabled) {
+            headers.push({ name: row.name, value: row.value });
+        }
+    }
+    for (const [name, value] of Object.entries(applied.headers)) {
+        headers.push({ name, value: redact ? CURL_REDACTED : value });
+    }
+    const transport = applied.transportAuth;
+    const basic = transport?.type === 'basic'
+        ? { username: transport.username, password: redact ? CURL_REDACTED : transport.password }
+        : undefined;
+    const command = {
+        method: input.request.method,
+        url,
+        headers,
+        body: curlBody(input.request.body),
+        ...(basic !== undefined ? { basic } : {}),
+        ...(input.tls?.rejectUnauthorized === false ? { insecure: true } : {}),
+        ...(input.settings.followRedirects ? { followRedirects: true } : {}),
+        ...(input.settings.followRedirects && input.settings.maxRedirects !== undefined
+            ? { maxRedirects: input.settings.maxRedirects }
+            : {}),
+    };
+    return toCurl(command, options.shell !== undefined ? { shell: options.shell } : {});
+}
+/** The raw-body language a content type implies. */
+function languageOf(contentType) {
+    if (contentType === undefined) {
+        return 'text';
+    }
+    const type = contentType.split(';')[0]?.trim().toLowerCase() ?? '';
+    if (type === 'application/json' || type.endsWith('+json')) {
+        return 'json';
+    }
+    if (type === 'application/xml' || type === 'text/xml' || type.endsWith('+xml')) {
+        return 'xml';
+    }
+    if (type === 'text/html') {
+        return 'html';
+    }
+    if (type === 'application/javascript' || type === 'text/javascript') {
+        return 'javascript';
+    }
+    return 'text';
+}
+/** One `name=value` argument, as `-F` and `--data-urlencode` both spell a field. */
+function splitField(argument) {
+    const equals = argument.indexOf('=');
+    return equals === -1
+        ? { name: argument, value: '' }
+        : { name: argument.slice(0, equals), value: argument.slice(equals + 1) };
+}
+/**
+ * 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 function fromRestCurl(text, options = {}) {
+    const problems = [];
+    const tokenized = tokenizeCommand(text);
+    const tokens = expandBundles(tokenized.tokens);
+    const { heredoc } = tokenized;
+    let method;
+    let url;
+    const headers = [];
+    const formFields = [];
+    const parts = [];
+    let rawData;
+    let binaryPath;
+    let basic;
+    const settings = {};
+    // `-G` sends the `-d` data as the query of a GET; `-I` asks for HEAD. Both are read after the loop,
+    // because the flag may come before or after the data it changes.
+    let dataInQuery = false;
+    let head = false;
+    let index = tokens[0] === 'curl' || tokens[0] === 'curl.exe' ? 1 : 0;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        const next = tokens[index + 1] ?? '';
+        if (token === '-X' || token === '--request') {
+            method = next.toUpperCase();
+            index += 2;
+            continue;
+        }
+        if (token === '-H' || token === '--header') {
+            const colon = next.indexOf(':');
+            if (colon !== -1) {
+                headers.push(entry(next.slice(0, colon).trim(), next.slice(colon + 1).trim()));
+            }
+            index += 2;
+            continue;
+        }
+        if (token === '--url') {
+            url = next;
+            index += 2;
+            continue;
+        }
+        if (token === '-u' || token === '--user') {
+            const colon = next.indexOf(':');
+            basic = colon === -1 ? { username: next } : { username: next.slice(0, colon), password: next.slice(colon + 1) };
+            index += 2;
+            continue;
+        }
+        if (token === '-F' || token === '--form') {
+            const field = splitField(next);
+            if (field.value.startsWith('@') || field.value.startsWith('<')) {
+                parts.push({
+                    kind: 'file',
+                    name: field.name,
+                    source: { kind: 'path', path: field.value.slice(1) },
+                    enabled: true,
+                });
+            }
+            else {
+                parts.push({ kind: 'text', name: field.name, value: field.value, enabled: true });
+            }
+            index += 2;
+            continue;
+        }
+        if (token === '--data-urlencode') {
+            const field = splitField(next);
+            formFields.push(entry(field.name, field.value));
+            index += 2;
+            continue;
+        }
+        if (token === '-d' || token === '--data' || token === '--data-raw' || token === '--data-binary') {
+            if ((next === '@-' || next === '') && heredoc !== undefined) {
+                rawData = heredoc;
+            }
+            else if (next.startsWith('@')) {
+                binaryPath = next.slice(1);
+            }
+            else {
+                rawData = next;
+            }
+            index += 2;
+            continue;
+        }
+        if (token === '--json') {
+            // curl's shorthand for a JSON body: `-d` plus the two headers, unless the command sets its own.
+            rawData = next;
+            for (const [name, value] of [
+                ['Content-Type', 'application/json'],
+                ['Accept', 'application/json'],
+            ]) {
+                if (!headers.some((row) => row.name.toLowerCase() === name.toLowerCase())) {
+                    headers.push(entry(name, value));
+                }
+            }
+            index += 2;
+            continue;
+        }
+        if (token === '-G' || token === '--get') {
+            dataInQuery = true;
+            index += 1;
+            continue;
+        }
+        if (token === '-I' || token === '--head') {
+            head = true;
+            index += 1;
+            continue;
+        }
+        if (token === '-k' || token === '--insecure') {
+            settings.trustInvalid = true;
+            index += 1;
+            continue;
+        }
+        if (token === '-L' || token === '--location') {
+            settings.followRedirects = true;
+            index += 1;
+            continue;
+        }
+        if (token === '--max-redirs') {
+            const limit = Number.parseInt(next, 10);
+            if (!Number.isNaN(limit)) {
+                settings.maxRedirects = limit;
+            }
+            index += 2;
+            continue;
+        }
+        if (token.startsWith('-')) {
+            // A flag with no field here. Boolean ones are simply dropped; one that takes a value must also
+            // consume it, or its argument would be read as the URL.
+            problems.push(`Ignored ${token}`);
+            index += takesNoValue(token) ? 1 : 2;
+            continue;
+        }
+        if (url === undefined) {
+            url = token;
+        }
+        index += 1;
+    }
+    if (url === undefined) {
+        problems.push('No URL in the command');
+    }
+    // Rows, not text appended to the URL: `--data-urlencode` values are unencoded, as the table holds
+    // them, and the `-d` text is read the way a URL's own query string is.
+    const dataQuery = [];
+    if (dataInQuery) {
+        if (rawData !== undefined) {
+            dataQuery.push(...splitQuery(`?${rawData}`).query);
+        }
+        dataQuery.push(...formFields);
+        rawData = undefined;
+        formFields.length = 0;
+        method ??= 'GET';
+    }
+    if (head) {
+        method ??= 'HEAD';
+    }
+    const body = bodyFrom({ parts, formFields, rawData, binaryPath, headers });
+    const split = url === undefined ? undefined : splitAgainstBase(url, options.baseUrl);
+    const pathParams = split === undefined ? [] : paramRows(split.path);
+    return {
+        request: {
+            // A command with no `-X` sends a GET, unless it carries a body, which makes it a POST — the
+            // same rule curl itself applies.
+            method: method ?? (body.kind === 'none' ? 'GET' : 'POST'),
+            ...(split !== undefined ? { url: split.path, query: [...split.query, ...dataQuery] } : {}),
+            ...(pathParams.length > 0 ? { pathParams } : {}),
+            ...(headers.length > 0 ? { headers } : {}),
+            body,
+            ...(Object.keys(settings).length > 0 ? { settings } : {}),
+        },
+        ...(basic !== undefined ? { basic } : {}),
+        problems,
+    };
+}
+/** The body the flags add up to, most specific first. */
+function bodyFrom(input) {
+    if (input.parts.length > 0) {
+        return { kind: 'multipart', parts: input.parts };
+    }
+    if (input.formFields.length > 0) {
+        return { kind: 'form', fields: input.formFields };
+    }
+    if (input.binaryPath !== undefined) {
+        const declared = input.headers.find((row) => row.name.toLowerCase() === 'content-type')?.value;
+        return {
+            kind: 'binary',
+            source: { kind: 'path', path: input.binaryPath },
+            contentType: declared ?? 'application/octet-stream',
+        };
+    }
+    if (input.rawData !== undefined) {
+        const declared = input.headers.find((row) => row.name.toLowerCase() === 'content-type')?.value;
+        const language = languageOf(declared);
+        return {
+            kind: 'raw',
+            language,
+            // A declared type that the language's own default does not cover has to be kept, or the
+            // request would go out as something the server was never offered.
+            ...(declared !== undefined && declared !== RAW_LANGUAGE_CONTENT_TYPES[language] ? { contentType: declared } : {}),
+            text: input.rawData,
+        };
+    }
+    return { kind: 'none' };
+}
+/** A URL split into a path (relative to `baseUrl` when it matches) and its query rows. */
+function splitAgainstBase(url, baseUrl) {
+    const { path, query } = splitQuery(url);
+    if (baseUrl === undefined || baseUrl === '') {
+        return { path, query };
+    }
+    const base = trimTrailingSlashes(baseUrl);
+    if (path === base) {
+        return { path: '/', query };
+    }
+    if (path.startsWith(`${base}/`)) {
+        return { path: path.slice(base.length), query };
+    }
+    return { path, query };
+}
+/** One row per `{param}` the path names, so the table is filled in as the editor expects. */
+function paramRows(path) {
+    const rows = [];
+    for (const match of path.matchAll(/\{([^{}/?#]+)\}/g)) {
+        const name = match[1];
+        if (!rows.some((row) => row.name === name)) {
+            rows.push(entry(name, ''));
+        }
+    }
+    return rows;
+}
+/**
+ * Splits a command into tokens, pulling out a heredoc or here-string body first.
+ *
+ * Shared shape with the SOAP parser in `http/curl.ts`, but its own implementation: that one folds a
+ * heredoc into `envelopeXml`, and the two would drift into one function with a mode flag.
+ */
+function tokenizeCommand(text) {
+    let heredoc;
+    let remainder = text;
+    const embedded = findHeredoc(text) ?? findHereString(text);
+    if (embedded !== undefined) {
+        heredoc = embedded.body;
+        remainder = text.slice(0, embedded.start) + text.slice(embedded.end);
+    }
+    const normalized = remainder
+        .replace(/\\\r?\n/g, ' ')
+        .replace(/`\r?\n/g, ' ')
+        .trim();
+    const tokens = [];
+    let index = 0;
+    while (index < normalized.length) {
+        while (index < normalized.length && /\s/.test(normalized[index])) {
+            index += 1;
+        }
+        if (index >= normalized.length) {
+            break;
+        }
+        let token = '';
+        while (index < normalized.length && !/\s/.test(normalized[index])) {
+            const character = normalized[index];
+            if (character === "'" || character === '"') {
+                index += 1;
+                const start = index;
+                while (index < normalized.length && normalized[index] !== character) {
+                    index += 1;
+                }
+                token += normalized.slice(start, index);
+                index += 1;
+            }
+            else if (character === '\\' && index + 1 < normalized.length) {
+                token += normalized[index + 1];
+                index += 2;
+            }
+            else {
+                token += character;
+                index += 1;
+            }
+        }
+        if (token.length > 0) {
+            tokens.push(token);
+        }
+    }
+    return { tokens, heredoc };
+}

package/dist/rest/expand.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Property expansion for a REST send: every `${…}` reference in the base URL, the URL, the tables
+ * and the body, resolved against the same scopes a SOAP send uses.
+ *
+ * Separate from `project/properties.ts`'s `expandSendInput` because the two inputs share no fields,
+ * but the rules are deliberately the same ones: names as well as values are expanded, an
+ * unresolved reference is reported rather than guessed at, and escaping is applied to the body
+ * alone — escaping a header value or a URL would corrupt it.
+ */
+import type { PropertyScopes, UnresolvedRef } from '../project/properties.js';
+import type { RestSendInput } from './send.js';
+/** Options for {@link expandRestSendInput}. */
+export interface ExpandRestOptions {
+    /**
+     * Escape substituted values for the body's own language — JSON string escaping, or the five XML
+     * entities — which is the request's *escape properties* setting. Off by default.
+     */
+    readonly escape?: boolean;
+}
+/**
+ * Expands every property reference in a REST send input.
+ *
+ * What is expanded: the base URL, the URL (including its `{param}` names' values), every path,
+ * query and header row's name and value, a raw body's text, form field and multipart text values,
+ * and a file part's path — the two places a property can reasonably appear in a file reference, as
+ * for a SOAP attachment. What is not: a file's cache hash, which is content-addressed rather than
+ * authored.
+ *
+ * Escaping is applied only to values substituted *into the body*, and only when asked. A header or
+ * a URL is never escaped: `&` in a query string is a different request.
+ */
+export declare function expandRestSendInput(input: RestSendInput, scopes: PropertyScopes, options?: ExpandRestOptions): {
+    readonly input: RestSendInput;
+    readonly unresolved: UnresolvedRef[];
+};

package/dist/rest/expand.js

@@ -0,0 +1,104 @@
+/**
+ * Property expansion for a REST send: every `${…}` reference in the base URL, the URL, the tables
+ * and the body, resolved against the same scopes a SOAP send uses.
+ *
+ * Separate from `project/properties.ts`'s `expandSendInput` because the two inputs share no fields,
+ * but the rules are deliberately the same ones: names as well as values are expanded, an
+ * unresolved reference is reported rather than guessed at, and escaping is applied to the body
+ * alone — escaping a header value or a URL would corrupt it.
+ */
+import { expand } from '../project/properties.js';
+import { escapeForLanguage } from './body.js';
+/**
+ * Expands every property reference in a REST send input.
+ *
+ * What is expanded: the base URL, the URL (including its `{param}` names' values), every path,
+ * query and header row's name and value, a raw body's text, form field and multipart text values,
+ * and a file part's path — the two places a property can reasonably appear in a file reference, as
+ * for a SOAP attachment. What is not: a file's cache hash, which is content-addressed rather than
+ * authored.
+ *
+ * Escaping is applied only to values substituted *into the body*, and only when asked. A header or
+ * a URL is never escaped: `&` in a query string is a different request.
+ */
+export function expandRestSendInput(input, scopes, options = {}) {
+    const unresolved = [];
+    const run = (text) => {
+        const result = expand(text, scopes);
+        unresolved.push(...result.unresolved);
+        return result.text;
+    };
+    /** A body value: expanded, then escaped for the body's language when the request asks for it. */
+    const runBody = (text, language) => {
+        const result = expand(text, scopes);
+        unresolved.push(...result.unresolved);
+        if (options.escape !== true || language === undefined) {
+            return result.text;
+        }
+        // Escaping has to happen per substituted value, not over the finished text, or the body's own
+        // punctuation would be escaped too. `expand` reports which references it replaced, so the
+        // cheapest correct thing is to re-expand with an escaping substitution.
+        return expand(text, escapedScopes(scopes, language)).text;
+    };
+    const rows = (entries) => entries.map((entry) => ({ ...entry, name: run(entry.name), value: run(entry.value) }));
+    const request = {
+        method: input.request.method,
+        url: run(input.request.url),
+        pathParams: rows(input.request.pathParams),
+        query: rows(input.request.query),
+        headers: rows(input.request.headers),
+        body: expandBody(input.request.body, run, runBody),
+    };
+    return {
+        input: { ...input, baseUrl: run(input.baseUrl), request },
+        unresolved,
+    };
+}
+/** The same scopes with every value escaped for `language`, so substitution escapes as it goes. */
+function escapedScopes(scopes, language) {
+    const escapeMap = (map) => {
+        const out = {};
+        for (const [name, value] of Object.entries(map ?? {})) {
+            if (value !== undefined) {
+                out[name] = escapeForLanguage(value, language);
+            }
+        }
+        return out;
+    };
+    return {
+        ...scopes,
+        project: escapeMap(scopes.project),
+        global: escapeMap(scopes.global),
+        system: escapeMap(scopes.system),
+        ...(scopes.env !== undefined ? { env: escapeMap(scopes.env) } : {}),
+        ...(scopes.workspace !== undefined ? { workspace: escapeMap(scopes.workspace) } : {}),
+    };
+}
+function expandBody(body, run, runBody) {
+    switch (body.kind) {
+        case 'raw':
+            return { ...body, text: runBody(body.text, body.language) };
+        case 'form':
+            return {
+                kind: 'form',
+                fields: body.fields.map((field) => ({ ...field, name: run(field.name), value: runBody(field.value, 'form') })),
+            };
+        case 'multipart':
+            return { kind: 'multipart', parts: body.parts.map((part) => expandPart(part, run)) };
+        case 'binary':
+            return body.source.kind === 'path' ? { ...body, source: { kind: 'path', path: run(body.source.path) } } : body;
+        default:
+            return body;
+    }
+}
+function expandPart(part, run) {
+    if (part.kind === 'text') {
+        return { ...part, name: run(part.name), value: run(part.value) };
+    }
+    return {
+        ...part,
+        name: run(part.name),
+        ...(part.fileName !== undefined ? { fileName: run(part.fileName) } : {}),
+        source: part.source.kind === 'path' ? { kind: 'path', path: run(part.source.path) } : part.source,
+    };
+}