sfbench 0.1.0

package/dist/server/sf/apiRequest.js

@@ -0,0 +1,138 @@
+// `sf api request rest`, the fallback transport. One of the documented
+// exceptions to "depend only on sf's JSON output": with --include, sf prints a
+// status line, headers and the body as plain text. All of that parsing lives
+// here, tested against recorded output in __fixtures__.
+import { randomBytes } from 'node:crypto';
+import { rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { OrgAuthError, SfCliError, isAuthErrorMessage } from "./errors.js";
+import { lastErrorLine, runSf } from "./run.js";
+/** Salesforce says the session (the access token) is invalid: a 401 with INVALID_SESSION_ID. */
+export function isInvalidSession(res) {
+    if (res.status !== 401)
+        return false;
+    // XML when the request asked for it (Accept: application/xml).
+    if (/<errorCode>\s*INVALID_SESSION_ID\s*<\/errorCode>/.test(res.body))
+        return true;
+    try {
+        const body = JSON.parse(res.body);
+        return Array.isArray(body) && body.some((e) => e?.errorCode === 'INVALID_SESSION_ID');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A body that `sf api request rest` cannot send as it is: sf reads the request
+ * file as JSON and sends JSON.stringify of it, so only JSON goes through, and a
+ * number with more digits than a double holds would arrive rounded.
+ */
+export class NotJsonBodyError extends Error {
+    constructor(reason) {
+        super(reason === 'notJson'
+            ? 'Only a JSON body can be sent while sfbench uses sf api request rest. Try again once Salesforce can be reached directly.'
+            : 'A number in the body would change (it has more digits than a double holds, or is out of its range) while sfbench uses sf api request rest, so the request was not sent. Write it as text, or try again once Salesforce can be reached directly.');
+        this.name = 'NotJsonBodyError';
+    }
+}
+/** A JSON number as its significant digits and exponent, so that 1.50 and 1.5e0 compare equal. */
+function decimal(text) {
+    const m = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(text);
+    if (!m)
+        return text;
+    const fraction = m[3] ?? '';
+    let digits = (m[2] + fraction).replace(/^0+/, '');
+    let exponent = Number(m[4] ?? 0) - fraction.length;
+    while (digits.endsWith('0')) {
+        digits = digits.slice(0, -1);
+        exponent++;
+    }
+    return digits ? `${m[1]}${digits}e${exponent}` : '0';
+}
+/** Whether sf would send the number as written: it parses it into a double and writes that back. */
+function survivesSf(source, value) {
+    return Number.isFinite(value) && decimal(source) === decimal(JSON.stringify(value));
+}
+/** The body as sf will send it, or an error when sf would change it. */
+function bodyForSf(body) {
+    let long = false;
+    let parsed;
+    try {
+        // The reviver's third argument (the source text) tells the number as written.
+        parsed = JSON.parse(body, function (_key, value, context) {
+            if (typeof value === 'number' && context?.source && !survivesSf(context.source, value))
+                long = true;
+            return value;
+        });
+    }
+    catch {
+        throw new NotJsonBodyError('notJson');
+    }
+    if (long)
+        throw new NotJsonBodyError('longNumber');
+    return parsed;
+}
+const HEADER_LINE = /^([!#$%&'*+.^_`|~0-9A-Za-z-]+):[ \t]?(.*)$/;
+/**
+ * Parses the output of `sf api request rest --include`. sf prints no blank
+ * line between the headers and the body, so the body starts at the first line
+ * that is not a header. A plain-text body whose first line looks like a header
+ * would be misread; Salesforce REST responses are JSON, so this does not occur.
+ */
+export function parseIncludedResponse(stdout) {
+    // Strip ANSI color codes in case sf colors its output despite NO_COLOR.
+    // oxlint-disable-next-line no-control-regex
+    const lines = stdout.replace(/\x1b\[[0-9;]*m/g, '').split(/\r?\n/);
+    const statusMatch = /^HTTP\/[\d.]+ (\d{3})\b/.exec(lines[0] ?? '');
+    if (!statusMatch)
+        return undefined;
+    const headers = {};
+    let i = 1;
+    for (; i < lines.length; i++) {
+        const m = HEADER_LINE.exec(lines[i]);
+        if (!m)
+            break;
+        headers[m[1].toLowerCase()] = m[2].trim();
+    }
+    // Skip a blank separator line in case a future sf version prints one.
+    if (lines[i] === '')
+        i++;
+    return { status: Number(statusMatch[1]), headers, body: lines.slice(i).join('\n').trimEnd() };
+}
+/** Sends a REST request through `sf api request rest`. Throws OrgAuthError when the org's auth is no longer valid. */
+export async function apiRequest(username, request, tmpDir, timeoutMs) {
+    // The request goes in a file so that user input never appears on the command line.
+    const fileName = `req-${randomBytes(8).toString('hex')}.json`;
+    const filePath = join(tmpDir, fileName);
+    // sf sends JSON.stringify(raw), so the body goes in parsed: a string here
+    // would arrive quoted. Without a body, raw is left out and nothing is sent.
+    const raw = request.body !== undefined ? bodyForSf(request.body) : undefined;
+    const fileBody = {
+        url: request.path,
+        method: request.method,
+        header: Object.entries(request.headers).map(([key, value]) => ({ key, value })),
+        body: { mode: 'raw', raw },
+    };
+    writeFileSync(filePath, JSON.stringify(fileBody), { mode: 0o600 });
+    try {
+        const { stdout, stderr } = await runSf(['api', 'request', 'rest', '--file', fileName, '--include'], {
+            targetOrg: username,
+            cwd: tmpDir,
+            timeoutMs,
+        });
+        const response = parseIncludedResponse(stdout);
+        if (response) {
+            // sf refreshes the token itself, so an invalid session here needs a new login.
+            if (isInvalidSession(response))
+                throw new OrgAuthError(username, 'Salesforce rejected the session (401).');
+            return response;
+        }
+        const message = lastErrorLine(stderr) ?? 'sf api request rest returned no response';
+        if (isAuthErrorMessage(message))
+            throw new OrgAuthError(username, message);
+        throw new SfCliError(message);
+    }
+    finally {
+        rmSync(filePath, { force: true });
+    }
+}

package/dist/server/sf/commands.js

@@ -0,0 +1,143 @@
+import { OrgAuthError, SfCliError, isAuthErrorMessage } from "./errors.js";
+import { lastErrorLine, runSf, runSfJson } from "./run.js";
+function kindOf(o) {
+    if (o.isScratch)
+        return 'scratch';
+    if (o.isSandbox)
+        return 'sandbox';
+    if (o.isDevHub)
+        return 'devhub';
+    return 'production';
+}
+/**
+ * Converts `sf org list --json` output to Org objects. Only the fields the UI
+ * needs are copied: sf's output also contains each org's access token, which
+ * must never reach the browser.
+ */
+export function toOrgs(result) {
+    const seen = new Set();
+    const orgs = [];
+    for (const o of [...(result.nonScratchOrgs ?? []), ...(result.scratchOrgs ?? [])]) {
+        if (!o.username || !o.instanceUrl || seen.has(o.username))
+            continue;
+        seen.add(o.username);
+        orgs.push({
+            username: o.username,
+            alias: o.alias || undefined,
+            instanceUrl: o.instanceUrl,
+            kind: kindOf(o),
+            edition: o.orgEdition || o.edition || undefined,
+            expirationDate: o.isScratch ? o.expirationDate : undefined,
+            isExpired: Boolean(o.isExpired),
+            availability: scratchAvailability(o),
+        });
+    }
+    // Orgs with an alias first (by alias), then the rest (by username): orgs
+    // without an alias are usually leftovers such as test users.
+    return orgs.sort((a, b) => a.alias && b.alias ? a.alias.localeCompare(b.alias) : a.alias ? -1 : b.alias ? 1 : a.username.localeCompare(b.username));
+}
+/**
+ * Scratch orgs carry their state, recorded by the Dev Hub, even in the fast
+ * list. The sf CLI does not check their connection, so an active scratch org
+ * within its expiration date is treated as usable. Other orgs need the
+ * connection check.
+ */
+function scratchAvailability(o) {
+    if (!o.isScratch)
+        return 'unknown';
+    if (o.isExpired || (o.status !== undefined && o.status !== 'Active'))
+        return 'unavailable';
+    return o.status === 'Active' ? 'ok' : 'unknown';
+}
+/** The command that logs in to an org again. */
+export function reloginCommand(org) {
+    return `sf org login web --instance-url ${org.instanceUrl}${org.alias ? ` -a ${org.alias}` : ''}`;
+}
+// `sf org list` reports a deleted org or an expired trial as an HTML response with HTTP 420.
+const GONE_PATTERNS = [/HTTP status code: 420/, /HTTP response contains html content/i];
+/**
+ * Reads `connectedStatus`. Only clear signals hide an org: a network problem
+ * while checking (for example, being offline) must not hide every org.
+ */
+export function availabilityFromStatus(connectedStatus) {
+    if (!connectedStatus)
+        return 'unknown';
+    if (connectedStatus === 'Connected')
+        return 'ok';
+    if (isAuthErrorMessage(connectedStatus))
+        return 'authError';
+    if (GONE_PATTERNS.some((p) => p.test(connectedStatus)))
+        return 'unavailable';
+    return 'unknown';
+}
+/** Maps username → availability from `sf org list --json` with connection status. */
+export function toAvailability(result) {
+    const map = new Map();
+    for (const o of result.nonScratchOrgs ?? []) {
+        if (o.username)
+            map.set(o.username, availabilityFromStatus(o.connectedStatus));
+    }
+    return map;
+}
+/**
+ * Checks every org's connection. Slow (about 12 seconds with 50 orgs) and
+ * calls each org's API, so it runs once at startup and when the user asks.
+ */
+export async function checkOrgConnections(cwd) {
+    const result = await runSfJson(['org', 'list'], { cwd, timeoutMs: 300_000 });
+    return toAvailability(result);
+}
+export async function listOrgs(cwd) {
+    // --skip-connection-status: checking every org's connection takes far too long.
+    const result = await runSfJson(['org', 'list', '--skip-connection-status'], {
+        cwd,
+        timeoutMs: 120_000,
+    });
+    return toOrgs(result);
+}
+/**
+ * The default org (alias or username) as configured for `cwd`. The CLI entry
+ * point runs this in the user's working directory, because projects can set
+ * their own default org.
+ */
+export async function getDefaultOrg(cwd) {
+    return parseDefaultOrg(await runSfJson(['config', 'get', 'target-org'], { cwd }));
+}
+/** Reads the `result` of `sf config get target-org --json`. There is no `value` when no default org is set. */
+export function parseDefaultOrg(result) {
+    const value = Array.isArray(result) ? result[0]?.value : undefined;
+    return typeof value === 'string' && value ? value : undefined;
+}
+/**
+ * The org's access token. sf refreshes an expired access token before returning
+ * it. When the refresh token itself is no longer valid, sf returns the stale
+ * access token without an error; the caller notices through a 401.
+ */
+export async function getAccessToken(username, cwd) {
+    const result = await runSfJson(['org', 'auth', 'show-access-token', '--no-prompt'], {
+        targetOrg: username,
+        cwd,
+    });
+    return parseAccessToken(result);
+}
+/** Reads the `result` of `sf org auth show-access-token --json`. */
+export function parseAccessToken(result) {
+    const token = result?.accessToken;
+    // A real token has the form "<org id>!<secret>"; anything else means sf masked it.
+    if (typeof token !== 'string' || !token.includes('!')) {
+        throw new SfCliError('sf did not return a usable access token');
+    }
+    return token;
+}
+/** Opens the org's home page in the default browser, logged in, with `sf org open`. */
+export async function openOrg(username, cwd) {
+    // stdout contains the frontdoor URL, which carries a session: it is never read or logged.
+    const { exitCode, stderr } = await runSf(['org', 'open'], { targetOrg: username, cwd });
+    // stderr can contain the frontdoor URL, which carries a session; lastErrorLine removes URLs.
+    if (exitCode !== 0) {
+        const message = lastErrorLine(stderr) ?? 'unknown error';
+        if (isAuthErrorMessage(message))
+            throw new OrgAuthError(username, message);
+        throw new SfCliError(`sf org open failed: ${message}`);
+    }
+}

package/dist/server/sf/errors.js

@@ -0,0 +1,38 @@
+/** The sf CLI is not installed or not on PATH. */
+export class SfNotFoundError extends Error {
+    constructor() {
+        super('The Salesforce CLI (sf) was not found. Install it from https://developer.salesforce.com/tools/salesforcecli');
+        this.name = 'SfNotFoundError';
+    }
+}
+/** An sf command failed. `sfName` is the `name` from sf's JSON error, when there was one. */
+export class SfCliError extends Error {
+    sfName;
+    constructor(message, sfName) {
+        super(message);
+        this.name = 'SfCliError';
+        this.sfName = sfName;
+    }
+}
+/** An sf command did not finish in time and was stopped. */
+export class SfTimeoutError extends SfCliError {
+    constructor(message) {
+        super(message);
+        this.name = 'SfTimeoutError';
+    }
+}
+/** The org's auth is no longer valid (for example, the refresh token expired). */
+export class OrgAuthError extends Error {
+    username;
+    constructor(username, message) {
+        super(message);
+        this.name = 'OrgAuthError';
+        this.username = username;
+    }
+}
+// sf reports an expired refresh token with a generic error name, so the
+// message is the only reliable signal. See docs/design.md.
+const AUTH_ERROR_PATTERNS = [/unable to refresh session/i, /expired access\/refresh token/i, /invalid_grant/i];
+export function isAuthErrorMessage(message) {
+    return AUTH_ERROR_PATTERNS.some((p) => p.test(message));
+}

package/dist/server/sf/run.js

@@ -0,0 +1,163 @@
+// Runs the sf CLI as a child process. See docs/design.md ("sf CLI の呼び出し方").
+//
+// - sf is started by its absolute path, resolved from PATH without the current
+//   directory, so that an untrusted `sf.cmd` in the working directory is never run.
+// - Arguments are fixed strings only. The org goes in SF_TARGET_ORG and user
+//   input goes in files, because on Windows `sf.cmd` needs a shell and the shell
+//   would interpret symbols in the arguments.
+// - At most MAX_CONCURRENT sf processes run at once; the rest wait in a queue.
+import { execFile } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { SfCliError, SfNotFoundError, SfTimeoutError } from "./errors.js";
+const isWindows = process.platform === 'win32';
+const MAX_CONCURRENT = 4;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_OUTPUT_BYTES = 512 * 1024 * 1024;
+let sfPath;
+/** Finds sf on PATH. Relative PATH entries (including ".") are ignored. */
+export function resolveSfPath(env = process.env) {
+    if (sfPath)
+        return sfPath;
+    const names = isWindows ? ['sf.cmd', 'sf.exe', 'sf.bat'] : ['sf'];
+    const dirs = (env.PATH ?? env.Path ?? '').split(delimiter).filter((d) => d && isAbsolute(d));
+    for (const dir of dirs) {
+        for (const name of names) {
+            const candidate = join(dir, name);
+            try {
+                accessSync(candidate, isWindows ? constants.F_OK : constants.X_OK);
+                sfPath = candidate;
+                return candidate;
+            }
+            catch {
+                // Try the next one.
+            }
+        }
+    }
+    throw new SfNotFoundError();
+}
+let running = 0;
+const waiting = [];
+async function acquire() {
+    if (running < MAX_CONCURRENT) {
+        running++;
+        return;
+    }
+    await new Promise((resolve) => waiting.push(resolve));
+}
+function release() {
+    const next = waiting.shift();
+    if (next)
+        next();
+    else
+        running--;
+}
+/** Runs `sf <args>` and returns its output. Resolves even when sf exits with a non-zero code. */
+export async function runSf(args, options) {
+    const file = resolveSfPath();
+    const env = {
+        ...process.env,
+        SF_JSON_TO_STDOUT: 'true',
+        SF_DISABLE_AUTOUPDATE: 'true',
+        SF_AUTOUPDATE_DISABLE: 'true',
+        NO_COLOR: '1',
+        FORCE_COLOR: '0',
+    };
+    delete env.SF_TARGET_ORG;
+    if (options.targetOrg)
+        env.SF_TARGET_ORG = options.targetOrg;
+    if (isWindows)
+        env.NoDefaultCurrentDirectoryInExePath = '1';
+    const label = `sf ${args.slice(0, 2).join(' ')}`;
+    await acquire();
+    try {
+        return await new Promise((resolve, reject) => {
+            let timedOut = false;
+            const child = execFile(
+            // With a shell, Node joins the command line without quoting, so quote the path.
+            isWindows ? `"${file}"` : file, args, {
+                cwd: options.cwd,
+                env,
+                shell: isWindows,
+                windowsHide: true,
+                maxBuffer: MAX_OUTPUT_BYTES,
+                encoding: 'utf8',
+            }, (error, stdout, stderr) => {
+                clearTimeout(timer);
+                const code = error?.code;
+                if (code === 'ENOENT')
+                    reject(new SfNotFoundError());
+                else if (timedOut)
+                    reject(new SfTimeoutError(`${label} timed out`));
+                else if (code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER')
+                    reject(new SfCliError(`${label} printed too much output`));
+                else
+                    resolve({ stdout, stderr, exitCode: typeof error?.code === 'number' ? error.code : error ? 1 : 0 });
+            });
+            const timer = setTimeout(() => {
+                timedOut = true;
+                killTree(child.pid, () => child.kill('SIGKILL'));
+            }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        });
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * On Windows, sf runs under cmd.exe, so killing the child only stops cmd.exe
+ * and leaves sf running. taskkill /T stops the whole process tree.
+ */
+function killTree(pid, fallback) {
+    if (!isWindows || pid === undefined) {
+        fallback();
+        return;
+    }
+    const taskkill = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'taskkill.exe');
+    execFile(taskkill, ['/T', '/F', '/PID', String(pid)], { windowsHide: true }, (error) => {
+        if (error)
+            fallback();
+    });
+}
+/** Runs an sf command with --json and returns `result`. Throws SfCliError when sf reports an error. */
+export async function runSfJson(args, options) {
+    const output = await runSf([...args, '--json'], options);
+    return parseSfJsonOutput(output, `sf ${args.slice(0, 2).join(' ')}`);
+}
+/** Reads sf's --json output: `result` on success, SfCliError with sf's `name` and `message` on failure. */
+export function parseSfJsonOutput({ stdout, stderr, exitCode }, label) {
+    let json;
+    try {
+        json = JSON.parse(stdout);
+    }
+    catch {
+        json = undefined;
+    }
+    if (json && json.status === 0 && exitCode === 0 && json.result !== undefined)
+        return json.result;
+    if (json?.message)
+        throw new SfCliError(redactUrls(json.message), json.name);
+    throw new SfCliError(lastErrorLine(stderr) ?? `${label} failed with exit code ${exitCode}`);
+}
+/**
+ * Extracts the error message from sf's human-readable stderr ("Error (Name): message").
+ * URLs are removed: sf can print URLs that carry a session (such as frontdoor
+ * URLs), and these messages reach the log and the browser.
+ */
+export function lastErrorLine(stderr) {
+    const lines = stderr.split(/\r?\n/).map((l) => l.trim());
+    const errorLine = lines.find((l) => /^Error \(.+?\): /.test(l));
+    if (errorLine)
+        return redactUrls(errorLine.replace(/^Error \(.+?\): /, ''));
+    const meaningful = lines.filter((l) => l && !l.startsWith('›'));
+    const last = meaningful.at(-1);
+    return last === undefined ? undefined : redactUrls(last);
+}
+/**
+ * Removes URLs and Salesforce paths from text that goes to the log or the
+ * browser: absolute URLs can carry a session, and /services/ paths can carry
+ * SOQL in the query string.
+ */
+export function redactUrls(text) {
+    return text.replace(/https?:\/\/\S+/g, '<URL>').replace(/\/services\/\S+/g, '<PATH>');
+}

package/dist/server/state.js

@@ -0,0 +1,103 @@
+// server.json and server.lock. Their format is part of the contract that must
+// not change between versions: a newer CLI entry point has to find, use or
+// stop an older server. See docs/design.md ("バージョンをまたいで変えない契約").
+import { randomBytes } from 'node:crypto';
+import { closeSync, openSync, readFileSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { readJson, writeFileAtomic } from "./fsutil.js";
+export function readServerInfo(file) {
+    const v = readJson(file);
+    if (v &&
+        typeof v.port === 'number' &&
+        typeof v.adminToken === 'string' &&
+        typeof v.pid === 'number' &&
+        typeof v.version === 'string') {
+        return { port: v.port, adminToken: v.adminToken, pid: v.pid, version: v.version };
+    }
+    return undefined;
+}
+export function writeServerInfo(file, info) {
+    writeFileAtomic(file, JSON.stringify(info, null, 2));
+}
+/** Removes server.json if it still describes this process. */
+export function removeServerInfo(file, pid) {
+    if (readServerInfo(file)?.pid === pid)
+        rmSync(file, { force: true });
+}
+/** Compares "x.y.z" versions. Pre-release suffixes are ignored. */
+export function compareVersions(a, b) {
+    const parse = (v) => v.split('-')[0].split('.').map((n) => Number.parseInt(n, 10) || 0);
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return Math.sign(d);
+    }
+    return 0;
+}
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: the process exists but belongs to someone else.
+        return e.code === 'EPERM';
+    }
+}
+const LOCK_WAIT_MS = 20_000;
+const LOCK_STALE_MS = 60_000;
+const LOCK_POLL_MS = 200;
+export class LockTimeoutError extends Error {
+    constructor() {
+        super('Another sfbench is starting. Try again in a moment.');
+        this.name = 'LockTimeoutError';
+    }
+}
+function isStale(file, now) {
+    let content;
+    try {
+        content = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        // Unreadable: either being written right now or corrupt. Judge by age.
+        const mtime = statSync(file, { throwIfNoEntry: false })?.mtimeMs;
+        return mtime === undefined || now - mtime > LOCK_STALE_MS;
+    }
+    return now - content.createdAt > LOCK_STALE_MS || !isProcessAlive(content.pid);
+}
+/**
+ * Takes server.lock, waiting up to 20 seconds. Returns a function that releases it.
+ * A lock whose process is gone, or that is older than 60 seconds, is stale.
+ */
+export async function acquireLock(file) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const fd = openSync(file, 'wx', 0o600);
+            writeSync(fd, JSON.stringify({ pid: process.pid, createdAt: Date.now() }));
+            closeSync(fd);
+            return () => rmSync(file, { force: true });
+        }
+        catch (e) {
+            if (e.code !== 'EEXIST')
+                throw e;
+        }
+        if (isStale(file, Date.now())) {
+            // Rename before deleting: if two processes find the same stale lock, only
+            // one rename succeeds, so neither deletes a lock the other just created.
+            const aside = `${file}.stale-${randomBytes(6).toString('hex')}`;
+            try {
+                renameSync(file, aside);
+                rmSync(aside, { force: true });
+            }
+            catch {
+                // Someone else handled it.
+            }
+            continue;
+        }
+        if (Date.now() > deadline)
+            throw new LockTimeoutError();
+        await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+    }
+}