sfbench 0.1.0

package/dist/server/launcher.js

@@ -0,0 +1,170 @@
+// The CLI entry point's work: find or start the background server, then open
+// a new browser tab. See docs/design.md ("起動").
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { openBrowser } from "./browser.js";
+import { ensureDirs, resolvePaths } from "./paths.js";
+import { getDefaultOrg } from "./sf/commands.js";
+import { SfNotFoundError } from "./sf/errors.js";
+import { acquireLock, compareVersions, readServerInfo } from "./state.js";
+import { packageVersion } from "./version.js";
+const START_TIMEOUT_MS = 15_000;
+const STOP_TIMEOUT_MS = 5_000;
+const HEALTH_TIMEOUT_MS = 2_000;
+export class UserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UserError';
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Calls an admin endpoint. Node's fetch sends no Origin header, which the server requires for admin calls. */
+async function admin(info, method, path, body, timeoutMs = HEALTH_TIMEOUT_MS) {
+    return fetch(`http://127.0.0.1:${info.port}${path}`, {
+        method,
+        headers: { 'X-Sfbench-Admin': info.adminToken, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+}
+/** The version of the server described by `info`, or undefined if it does not answer. */
+async function health(info) {
+    try {
+        const res = await admin(info, 'GET', '/api/health');
+        if (!res.ok)
+            return undefined;
+        return (await res.json()).version;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Asks a server to stop and waits until it no longer answers. */
+async function stopServer(info) {
+    try {
+        await admin(info, 'POST', '/api/shutdown');
+    }
+    catch {
+        // It may already be gone.
+    }
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if ((await health(info)) === undefined)
+            return true;
+        await sleep(200);
+    }
+    return false;
+}
+function startServer(paths) {
+    // cli.js next to this file when installed; cli.ts when run from the sources.
+    const cli = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? './cli.ts' : './cli.js', import.meta.url));
+    const child = spawn(process.execPath, ['--use-env-proxy', cli, 'serve'], {
+        cwd: paths.tmpDir,
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    child.unref();
+    if (child.pid === undefined)
+        throw new UserError('Could not start the sfbench server.');
+    return child.pid;
+}
+/** Returns a running server of this version or newer, starting one if needed. Call with server.lock held. */
+async function ensureServer(paths) {
+    const mine = packageVersion();
+    const existing = readServerInfo(paths.serverJson);
+    if (existing) {
+        const running = await health(existing);
+        if (running !== undefined) {
+            // A newer server is used as is, so that two sfbench versions on one
+            // computer do not keep stopping each other's server.
+            if (compareVersions(running, mine) >= 0)
+                return existing;
+            if (!(await stopServer(existing))) {
+                process.stderr.write(`An older sfbench server (${running}) did not stop. Starting another one.\n`);
+            }
+        }
+    }
+    const pid = startServer(paths);
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await sleep(200);
+        const info = readServerInfo(paths.serverJson);
+        if (info?.pid === pid && (await health(info)) !== undefined)
+            return info;
+    }
+    throw new UserError(`The sfbench server did not start. See ${paths.serverLog}.`);
+}
+async function resolveOrg(options) {
+    if (options.targetOrg)
+        return options.targetOrg;
+    try {
+        // In the user's working directory: a project can set its own default org.
+        return await getDefaultOrg(process.cwd());
+    }
+    catch (e) {
+        if (e instanceof SfNotFoundError)
+            throw new UserError(e.message);
+        return undefined;
+    }
+}
+export async function openSfbench(options) {
+    if (options.run && !options.query)
+        throw new UserError('--run needs --query.');
+    if (options.rest && (options.query || options.run))
+        throw new UserError('--rest cannot be used with --query or --run.');
+    if (options.apex && (options.query || options.run || options.rest))
+        throw new UserError('--apex cannot be used with --query, --run or --rest.');
+    const org = await resolveOrg(options);
+    if (options.run && !org) {
+        throw new UserError('No org to run the query in. Pass -o <alias>, or set a default org with `sf config set target-org <alias>`.');
+    }
+    // A request that may change data goes only into the org it was meant for.
+    if (options.rest && !org) {
+        throw new UserError('No org for the REST request. Pass -o <alias>, or set a default org with `sf config set target-org <alias>`.');
+    }
+    if (options.apex && !org) {
+        throw new UserError('No org for the Apex. Pass -o <alias>, or set a default org with `sf config set target-org <alias>`.');
+    }
+    const paths = resolvePaths(false);
+    ensureDirs(paths);
+    const release = await acquireLock(paths.serverLock);
+    let info;
+    try {
+        info = await ensureServer(paths);
+    }
+    finally {
+        release();
+    }
+    const res = await admin(info, 'POST', '/api/launch', { org, query: options.query, run: options.run, rest: options.rest, apex: options.apex, noOpen: !options.open });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => undefined));
+        throw new UserError(body?.error?.message ?? `sfbench could not open (HTTP ${res.status}).`);
+    }
+    const { code } = (await res.json());
+    const url = `http://127.0.0.1:${info.port}/launch/${code}`;
+    const opened = options.open ? await openBrowser(url) : false;
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ url, opened, port: info.port, org: org ?? null })}\n`);
+    }
+    else if (opened) {
+        process.stdout.write(`Opened sfbench in your browser.\n`);
+    }
+    else {
+        process.stdout.write(`Open this URL in your browser within ${options.open ? 'a minute' : '10 minutes'}:\n${url}\n`);
+    }
+}
+export async function stopSfbench() {
+    const paths = resolvePaths(false);
+    const info = readServerInfo(paths.serverJson);
+    if (!info || (await health(info)) === undefined) {
+        process.stdout.write('sfbench is not running.\n');
+        return;
+    }
+    if (await stopServer(info))
+        process.stdout.write('Stopped sfbench.\n');
+    else
+        throw new UserError('sfbench did not stop.');
+}

package/dist/server/log.js

@@ -0,0 +1,33 @@
+// Server log. The server writes it itself, opening and closing the file on
+// every write so that the file can be rotated while the server runs (also on
+// Windows). Never pass tokens, API keys, `sf org open` URLs, SOQL or request
+// bodies to these functions.
+import { appendFileSync, renameSync, statSync } from 'node:fs';
+const MAX_BYTES = 1024 * 1024;
+let logFile;
+let alsoConsole = false;
+export function initLog(file, toConsole) {
+    logFile = file;
+    alsoConsole = toConsole;
+}
+function write(level, message) {
+    const line = `${new Date().toISOString()} ${level} ${message}\n`;
+    if (alsoConsole)
+        process.stderr.write(line);
+    if (!logFile)
+        return;
+    try {
+        if ((statSync(logFile, { throwIfNoEntry: false })?.size ?? 0) > MAX_BYTES) {
+            renameSync(logFile, `${logFile}.1`);
+        }
+        appendFileSync(logFile, line, { mode: 0o600 });
+    }
+    catch {
+        // Logging must never break the server.
+    }
+}
+export const log = {
+    info: (message) => write('INFO', message),
+    warn: (message) => write('WARN', message),
+    error: (message) => write('ERROR', message),
+};

package/dist/server/orgs.js

@@ -0,0 +1,143 @@
+import { log } from "./log.js";
+import { OrgClient } from "./salesforce.js";
+import { checkOrgConnections, listOrgs, reloginCommand } from "./sf/commands.js";
+/** A version the screen chose is cached apart from the latest (docs/web.md "API バージョン"). */
+function keyPrefix(at) {
+    return at.version ? `v${at.version}:` : '';
+}
+export class OrgRegistry {
+    tmpDir;
+    forceCli;
+    timeoutMs;
+    orgs;
+    clients = new Map();
+    summaries = new Map();
+    sobjects = new Map();
+    connections;
+    check;
+    checkState = 'pending';
+    constructor(tmpDir, forceCli, timeoutMs) {
+        this.tmpDir = tmpDir;
+        this.forceCli = forceCli;
+        this.timeoutMs = timeoutMs;
+    }
+    /** The org list. `sf org list` can take several seconds, so the result is cached until refresh. */
+    list(refresh = false) {
+        if (refresh || !this.orgs) {
+            const pending = listOrgs(this.tmpDir);
+            this.orgs = pending;
+            pending.catch(() => {
+                if (this.orgs === pending)
+                    this.orgs = undefined;
+            });
+        }
+        return this.orgs;
+    }
+    /**
+     * Checks every org's connection in the background (docs/screens.md
+     * "組織の切り替え"). Resolves when the check ends, successfully or not.
+     */
+    checkConnections() {
+        this.checkState = 'pending';
+        const run = checkOrgConnections(this.tmpDir).then((map) => {
+            if (this.check === run) {
+                this.connections = map;
+                this.checkState = 'done';
+            }
+        }, (e) => {
+            log.warn(`could not check the org connections: ${e.message}`);
+            if (this.check === run)
+                this.checkState = 'failed';
+        });
+        this.check = run;
+        return run;
+    }
+    /** Waits for the connection check that is running, if any. */
+    waitForCheck() {
+        return this.check ?? Promise.resolve();
+    }
+    /** The org list with each org's availability from the latest connection check. */
+    async listWithAvailability(refresh = false) {
+        const orgs = (await this.list(refresh)).map((org) => {
+            const availability = org.availability !== 'unknown' ? org.availability : (this.connections?.get(org.username) ?? 'unknown');
+            return availability === 'authError'
+                ? { ...org, availability, reloginCommand: reloginCommand(org) }
+                : { ...org, availability };
+        });
+        return { orgs, connectionCheck: this.checkState };
+    }
+    /** The client for a username from the list. Returns undefined for anything else. */
+    async client(username) {
+        const org = (await this.list()).find((o) => o.username === username);
+        if (!org)
+            return undefined;
+        let client = this.clients.get(username);
+        if (!client || client.instanceUrl !== org.instanceUrl) {
+            client = new OrgClient({
+                username,
+                instanceUrl: org.instanceUrl,
+                tmpDir: this.tmpDir,
+                forceCli: this.forceCli,
+                timeoutMs: this.timeoutMs,
+            });
+            this.clients.set(username, client);
+        }
+        return client;
+    }
+    /** Organization type and namespace, fetched once per org. */
+    summary(client) {
+        let pending = this.summaries.get(client.username);
+        if (!pending) {
+            pending = fetchSummary(client);
+            this.summaries.set(client.username, pending);
+            pending.catch(() => this.summaries.delete(client.username));
+        }
+        return pending;
+    }
+    /**
+     * The org's object list (describeGlobal), cached. The screen's list and the
+     * AI's tools read the same entry (docs/ai-agent.md "SOQL のときのツール").
+     */
+    describeGlobal(client, at, refresh = false) {
+        return this.cachedDescribe(client, `${keyPrefix(at)}${at.tooling ? 'tooling:global' : 'global'}`, refresh, async () => {
+            const version = await client.version(at.version);
+            return (await client.request({ method: 'GET', path: `/services/data/v${version}/${at.tooling ? 'tooling/' : ''}sobjects/` })).body;
+        });
+    }
+    /** One object's describe, cached. Throws SalesforceError (404) when the org has no such object. */
+    describeObject(client, name, at, refresh = false) {
+        // "object:": an object named like the list's key ("global") is never taken for the list.
+        return this.cachedDescribe(client, `${keyPrefix(at)}${at.tooling ? 'tooling:' : ''}object:${name}`, refresh, async () => {
+            const version = await client.version(at.version);
+            return (await client.request({ method: 'GET', path: `/services/data/v${version}/${at.tooling ? 'tooling/' : ''}sobjects/${name}/describe/` })).body;
+        });
+    }
+    /** A cached describe result with the time it was fetched. */
+    cachedDescribe(client, key, refresh, load) {
+        const cacheKey = `${client.username}\n${key}`;
+        let pending = this.sobjects.get(cacheKey);
+        if (refresh || !pending) {
+            pending = load().then((body) => ({ body, fetchedAt: new Date().toISOString() }));
+            this.sobjects.set(cacheKey, pending);
+            const stored = pending;
+            pending.catch(() => {
+                if (this.sobjects.get(cacheKey) === stored)
+                    this.sobjects.delete(cacheKey);
+            });
+        }
+        return pending;
+    }
+}
+async function fetchSummary(client) {
+    const version = await client.version();
+    const soql = 'SELECT OrganizationType, IsSandbox, NamespacePrefix FROM Organization';
+    const res = await client.request({ method: 'GET', path: `/services/data/v${version}/query?q=${encodeURIComponent(soql)}` });
+    const record = res.body?.records?.[0];
+    if (!record)
+        throw new Error('The Organization query returned no record');
+    return {
+        organizationType: String(record.OrganizationType ?? ''),
+        isSandbox: Boolean(record.IsSandbox),
+        namespacePrefix: typeof record.NamespacePrefix === 'string' && record.NamespacePrefix ? record.NamespacePrefix : null,
+    };
+}

package/dist/server/paths.js

@@ -0,0 +1,35 @@
+// Locations of sfbench's state. See docs/design.md ("データの保存").
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+/** Root of the installed package (or of the repository during development). */
+export const packageRoot = resolve(here, '..', '..');
+/** Built web UI. Present only after `npm run build`. */
+export const webRoot = join(packageRoot, 'dist', 'web');
+/**
+ * State lives in ~/.sfbench, or in SFBENCH_HOME. `npm run dev:server` uses
+ * .sfbench-dev in the repository so that it never touches the sfbench the
+ * developer uses day to day.
+ */
+export function resolvePaths(dev) {
+    const home = process.env.SFBENCH_HOME ?? (dev ? join(packageRoot, '.sfbench-dev') : join(homedir(), '.sfbench'));
+    return {
+        home,
+        serverJson: join(home, 'server.json'),
+        serverLock: join(home, 'server.lock'),
+        serverLog: join(home, 'server.log'),
+        settings: join(home, 'settings.json'),
+        historyDir: join(home, 'history'),
+        restHistoryDir: join(home, 'rest-history'),
+        apexHistoryDir: join(home, 'apex-history'),
+        tmpDir: join(home, 'tmp'),
+    };
+}
+/** Creates the state directories, readable only by the user (no effect on Windows). */
+export function ensureDirs(paths) {
+    for (const dir of [paths.home, paths.historyDir, paths.restHistoryDir, paths.apexHistoryDir, paths.tmpDir]) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}

package/dist/server/records.js

@@ -0,0 +1,118 @@
+// Saving and deleting records from the result table (docs/edit.md "サーバー"):
+// what is accepted, and how sObject Collections' answer is passed back. Pure,
+// so that it is tested without Salesforce.
+import { MAX_RECORDS_PER_CALL } from "../shared/api.js";
+export class RecordsRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecordsRequestError';
+    }
+}
+const NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
+const ID = /^[a-zA-Z0-9]{15}([a-zA-Z0-9]{3})?$/;
+function checkAllOrNone(value) {
+    if (typeof value !== 'boolean')
+        throw new RecordsRequestError('allOrNone must be true or false.');
+    return value;
+}
+/** The same record twice (also as its 15 and 18 character Ids) would leave which value wins to Salesforce. */
+function checkUnique(ids) {
+    const seen = new Set();
+    for (const id of ids) {
+        const key = id.slice(0, 15);
+        if (seen.has(key))
+            throw new RecordsRequestError(`The record ${id} is given twice.`);
+        seen.add(key);
+    }
+}
+function checkCount(n) {
+    if (n === 0)
+        throw new RecordsRequestError('No records were given.');
+    if (n > MAX_RECORDS_PER_CALL)
+        throw new RecordsRequestError(`At most ${MAX_RECORDS_PER_CALL} records can be sent at once.`);
+}
+function checkId(id) {
+    if (typeof id !== 'string' || !ID.test(id))
+        throw new RecordsRequestError('Each record needs a 15 or 18 character Id.');
+    return id;
+}
+function isFieldValue(value) {
+    return value === null || typeof value === 'string' || typeof value === 'boolean';
+}
+/** Checks a save from the screen; nothing is sent when it fails. */
+export function checkUpdate(input) {
+    const { object, records, allOrNone } = input;
+    if (typeof object !== 'string' || !NAME.test(object))
+        throw new RecordsRequestError('object must be an object API name.');
+    if (!Array.isArray(records))
+        throw new RecordsRequestError('records must be a list.');
+    checkCount(records.length);
+    const checked = records.map((record) => {
+        if (!record || typeof record !== 'object')
+            throw new RecordsRequestError('Each record must be an object.');
+        const { id, fields } = record;
+        if (!fields || typeof fields !== 'object' || Array.isArray(fields))
+            throw new RecordsRequestError('Each record needs its fields.');
+        const entries = Object.entries(fields);
+        if (entries.length === 0)
+            throw new RecordsRequestError('Each record needs at least one field.');
+        for (const [name, value] of entries) {
+            if (!NAME.test(name) || name.toLowerCase() === 'id' || name === 'attributes')
+                throw new RecordsRequestError(`Invalid field name: ${name}`);
+            if (!isFieldValue(value))
+                throw new RecordsRequestError(`The value of ${name} must be text, true, false or null.`);
+        }
+        return { id: checkId(id), fields: fields };
+    });
+    checkUnique(checked.map((r) => r.id));
+    return { object, records: checked, allOrNone: checkAllOrNone(allOrNone) };
+}
+/** Checks a delete from the screen; nothing is sent when it fails. */
+export function checkDelete(input) {
+    const { ids, allOrNone } = input;
+    if (!Array.isArray(ids))
+        throw new RecordsRequestError('ids must be a list.');
+    checkCount(ids.length);
+    const checked = ids.map(checkId);
+    checkUnique(checked);
+    return { ids: checked, allOrNone: checkAllOrNone(allOrNone) };
+}
+/** The body of the sObject Collections update. */
+export function updateBody(request) {
+    return JSON.stringify({
+        allOrNone: request.allOrNone,
+        records: request.records.map((r) => ({ attributes: { type: request.object }, ...r.fields, id: r.id })),
+    });
+}
+function errorsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((e) => {
+        const error = (e ?? {});
+        return {
+            statusCode: typeof error.statusCode === 'string' ? error.statusCode : 'UNKNOWN',
+            message: typeof error.message === 'string' ? error.message : '',
+            fields: Array.isArray(error.fields) ? error.fields.filter((f) => typeof f === 'string') : [],
+        };
+    });
+}
+/**
+ * Salesforce's answers, one per record sent and in the same order. A failed
+ * record has no id in the answer: the id sent is put in. An answer of another
+ * shape is not guessed at: Salesforce took the call, so what it did is not
+ * known, and the screen says so (an internal error is of unknown outcome).
+ */
+export function recordResults(ids, body) {
+    const unexpected = () => new Error('sObject Collections answered in an unexpected form');
+    if (!Array.isArray(body) || body.length !== ids.length)
+        throw unexpected();
+    return ids.map((id, i) => {
+        const answer = body[i];
+        if (!answer || typeof answer !== 'object' || typeof answer.success !== 'boolean')
+            throw unexpected();
+        // A saved row names its record: one out of order is not taken for another.
+        if (answer.success && typeof answer.id === 'string' && answer.id.slice(0, 15) !== id.slice(0, 15))
+            throw unexpected();
+        return { id, success: answer.success, errors: errorsOf(answer.errors) };
+    });
+}

package/dist/server/rest.js

@@ -0,0 +1,120 @@
+// The REST API screen's requests (docs/rest.md "サーバーの `/rest`"): what is
+// accepted, and how Salesforce's answer is passed back. The only place that
+// decides which headers may be sent.
+import { validateHeaderName, validateHeaderValue } from 'node:http';
+import { isServicesPath, methodTakesBody, REST_METHODS } from "../shared/api.js";
+export class RestRequestError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RestRequestError';
+    }
+}
+const MAX_PATH = 16 * 1024;
+const MAX_HEADERS = 50;
+const MAX_HEADER_BYTES = 16 * 1024;
+/** A longer response body is not passed back (bodyOmitted: 'tooLarge'). */
+export const MAX_REST_RESPONSE_BYTES = 20 * 1024 * 1024;
+/** Names the request may not set: the token, the connection, and what fetch decides itself. */
+const FORBIDDEN = new Set(['authorization', 'cookie', 'host', 'content-length', 'connection', 'transfer-encoding', 'te', 'trailer', 'upgrade', 'keep-alive', 'expect']);
+/** Checks a request from the screen. Header names come back in lower case. */
+export function checkRestRequest(input) {
+    if (!input || typeof input !== 'object')
+        throw new RestRequestError('The body must be an object.');
+    const { method, path, headers, body } = input;
+    if (typeof method !== 'string' || !REST_METHODS.includes(method)) {
+        throw new RestRequestError(`method must be one of ${REST_METHODS.join(', ')}.`);
+    }
+    const m = method;
+    if (typeof path !== 'string' || !path)
+        throw new RestRequestError('path is required.');
+    if (path.length > MAX_PATH)
+        throw new RestRequestError('path is too long.');
+    if (body !== undefined && typeof body !== 'string')
+        throw new RestRequestError('body must be a string.');
+    // An empty body is no body, the same on either transport.
+    const sent = body === '' ? undefined : body;
+    // fetch cannot send a GET with a body, and would take that for a network error (docs/rest.md "前提にする事実").
+    if (sent !== undefined && !methodTakesBody(m))
+        throw new RestRequestError(`A ${m} request has no body.`);
+    return { method: m, path, headers: checkHeaders(headers), body: sent };
+}
+function checkHeaders(input) {
+    if (input === undefined)
+        return {};
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new RestRequestError('headers must be an object.');
+    const entries = Object.entries(input);
+    if (entries.length > MAX_HEADERS)
+        throw new RestRequestError(`At most ${MAX_HEADERS} headers can be sent.`);
+    let bytes = 0;
+    const headers = {};
+    for (const [rawName, value] of entries) {
+        if (typeof value !== 'string')
+            throw new RestRequestError(`The value of ${rawName} must be a string.`);
+        try {
+            validateHeaderName(rawName);
+            validateHeaderValue(rawName, value);
+        }
+        catch {
+            throw new RestRequestError(`Invalid header: ${rawName}`);
+        }
+        const name = rawName.toLowerCase();
+        if (FORBIDDEN.has(name) || name.startsWith('proxy-'))
+            throw new RestRequestError(`The ${rawName} header cannot be set.`);
+        // Two that differ only in case would be one, and one value would be dropped unseen.
+        if (Object.hasOwn(headers, name))
+            throw new RestRequestError(`The ${rawName} header is given twice.`);
+        bytes += name.length + value.length;
+        headers[name] = value;
+    }
+    if (bytes > MAX_HEADER_BYTES)
+        throw new RestRequestError('The headers are too long.');
+    return headers;
+}
+const TEXT_TYPE = /^(application\/(json|xml|[\w.+-]*\+(json|xml)|x-www-form-urlencoded|javascript)|text\/)/i;
+/** Salesforce's answer as the screen gets it: no set-cookie, and no body that is binary or too long. */
+export function restResponseBody(raw) {
+    const { 'set-cookie': _, ...headers } = raw.headers;
+    const size = raw.size ?? Buffer.byteLength(raw.body);
+    if (raw.incomplete)
+        return { headers, body: '', bodyOmitted: 'incomplete', size };
+    if (raw.truncated)
+        return { headers, body: '', bodyOmitted: 'tooLarge', size };
+    const type = headers['content-type'];
+    if (raw.body && type && !TEXT_TYPE.test(type))
+        return { headers, body: '', bodyOmitted: 'binary', size };
+    return { headers, body: raw.body, size };
+}
+/** The longest REST body the command line may give (docs/rest.md "`--rest` の起動時の指定"). */
+const MAX_LAUNCH_BODY = 1024 * 1024;
+/**
+ * The REST request given on the command line (`--rest <path> --method <method>
+ * --body <json>`), checked. Used by the CLI and by /api/launch, which both
+ * refuse what this refuses.
+ */
+export function restLaunch(input) {
+    const method = typeof input.method === 'string' ? input.method.toUpperCase() : input.method === undefined ? 'GET' : undefined;
+    if (!method || !REST_METHODS.includes(method))
+        throw new RestRequestError(`--method must be one of ${REST_METHODS.join(', ')}.`);
+    const m = method;
+    if (typeof input.path !== 'string' || !isServicesPath(input.path))
+        throw new RestRequestError('--rest needs a path that starts with /services/.');
+    if (input.path.length > MAX_PATH)
+        throw new RestRequestError('The --rest path is too long.');
+    // An empty body is no body, as on the screen (checkRestRequest).
+    if (input.body === undefined || input.body === '')
+        return { method: m, path: input.path };
+    if (typeof input.body !== 'string')
+        throw new RestRequestError('--body must be text.');
+    if (!methodTakesBody(m))
+        throw new RestRequestError(`A ${m} request has no body.`);
+    if (Buffer.byteLength(input.body) > MAX_LAUNCH_BODY)
+        throw new RestRequestError('The --body is too long.');
+    try {
+        JSON.parse(input.body);
+    }
+    catch {
+        throw new RestRequestError('--body must be JSON.');
+    }
+    return { method: m, path: input.path, body: input.body };
+}