sfbench 0.1.0

package/dist/server/salesforce.js

@@ -0,0 +1,348 @@
+// Calls the Salesforce REST API for one org. See docs/design.md
+// ("呼び出しの手順", "代わりの経路への切り替え").
+//
+// The usual transport is fetch with the access token from the sf CLI. The
+// fallback transport is `sf api request rest`, which is slow (about 3 seconds
+// per call) but needs no token.
+import { isServicesPath } from "../shared/api.js";
+import { log } from "./log.js";
+import { apiRequest, isInvalidSession } from "./sf/apiRequest.js";
+import { getAccessToken } from "./sf/commands.js";
+import { OrgAuthError, SfCliError, SfNotFoundError, SfTimeoutError, isAuthErrorMessage } from "./sf/errors.js";
+/** Salesforce answered with an HTTP error. `body` is its parsed JSON when possible. */
+export class SalesforceError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(salesforceMessage(status, body));
+        this.name = 'SalesforceError';
+        this.status = status;
+        this.body = body;
+    }
+}
+function salesforceMessage(status, body) {
+    if (Array.isArray(body) && body[0] && typeof body[0] === 'object' && 'message' in body[0]) {
+        return String(body[0].message);
+    }
+    return `Salesforce returned HTTP ${status}`;
+}
+/** Whether a request may change data: decided here only (docs/design.md "経路の選択"). */
+export function mayChangeData(req) {
+    return req.changesData === true || (req.method !== 'GET' && req.method !== 'HEAD');
+}
+/** Salesforce did not answer in time. */
+export class SalesforceTimeoutError extends Error {
+    constructor() {
+        super('Salesforce did not respond in time.');
+        this.name = 'SalesforceTimeoutError';
+    }
+}
+/**
+ * The connection broke while a request that changes data was in flight.
+ * Salesforce may have processed it, so it is not sent again.
+ */
+export class SalesforceUnreachableError extends Error {
+    constructor() {
+        super('The connection to Salesforce broke while sending the request. Salesforce may already have processed it, so sfbench did not send it again. Check the result in Salesforce.');
+        this.name = 'SalesforceUnreachableError';
+    }
+}
+/** The screen asked for an API version the org does not support: nothing was sent. */
+export class UnsupportedVersionError extends Error {
+    constructor(version) {
+        super(`The org does not support API version ${version}.`);
+        this.name = 'UnsupportedVersionError';
+    }
+}
+/** The fetch transport failed before or while talking to Salesforce. */
+class FetchFailure extends Error {
+    /** False when the request was never sent (for example, no access token). */
+    mayHaveReachedSalesforce;
+    constructor(message, mayHaveReachedSalesforce) {
+        super(message);
+        this.name = 'FetchFailure';
+        this.mayHaveReachedSalesforce = mayHaveReachedSalesforce;
+    }
+}
+const RETRY_FETCH_AFTER_MS = 10 * 60 * 1000;
+export class OrgClient {
+    username;
+    instanceUrl;
+    apiUsage;
+    tmpDir;
+    forceCli;
+    timeoutMs;
+    transport = 'fetch';
+    switchedToCliAt = 0;
+    token;
+    /** The value `token` resolved to, once it has. */
+    tokenValue;
+    /** The rejected token that the pending `token` run is replacing. */
+    replacing;
+    apiVersions;
+    constructor(options) {
+        this.username = options.username;
+        this.instanceUrl = options.instanceUrl;
+        this.tmpDir = options.tmpDir;
+        this.forceCli = options.forceCli;
+        this.timeoutMs = options.timeoutMs;
+    }
+    /**
+     * The API versions the org supports, oldest first, such as "66.0" last. An
+     * org can list a version twice (seen around a release), so each is kept once.
+     */
+    versions() {
+        this.apiVersions ??= this.request({ method: 'GET', path: '/services/data/' }).then((res) => [...new Set(res.body.map((v) => v.version))].sort((a, b) => Number(a) - Number(b)));
+        this.apiVersions.catch(() => (this.apiVersions = undefined));
+        return this.apiVersions;
+    }
+    /**
+     * The API version to use: `requested` if the org supports it, else the latest
+     * when none is requested. A version the org does not support is refused
+     * (UnsupportedVersionError), never replaced by another.
+     */
+    async version(requested) {
+        const versions = await this.versions();
+        if (requested === undefined)
+            return versions[versions.length - 1];
+        if (!versions.includes(requested))
+            throw new UnsupportedVersionError(requested);
+        return requested;
+    }
+    /** Sends a request. Throws SalesforceError for HTTP errors and OrgAuthError when the org needs a new login. */
+    async request(req) {
+        const raw = await this.requestRaw(req);
+        const body = parseBody(raw.body);
+        if (raw.status >= 400)
+            throw new SalesforceError(raw.status, body);
+        return { status: raw.status, headers: raw.headers, body };
+    }
+    /**
+     * Sends a request and returns what Salesforce answered, whatever its status
+     * (the REST API screen shows a 4xx as a response, docs/rest.md). Throws
+     * OrgAuthError only when Salesforce says the session is invalid even with a
+     * new token. With `maxBodyBytes`, a longer body is cut off while it is read.
+     */
+    async requestRaw(req, options = {}) {
+        // What was checked is what is sent, on either transport.
+        const checked = { ...req, path: salesforcePath(req.path, this.instanceUrl) };
+        const raw = await this.send(checked, options.maxBodyBytes);
+        this.recordApiUsage(raw.headers['sforce-limit-info']);
+        return raw;
+    }
+    async send(req, maxBodyBytes) {
+        if (this.forceCli)
+            return this.sendWithCli(req, maxBodyBytes);
+        const readOnly = !mayChangeData(req);
+        // After switching to sf, fetch is tried again after a while, but only with
+        // a read-only request: a request that changes data must not be the one
+        // that discovers fetch still fails, because it could not be sent again.
+        if (this.transport === 'cli' && (!readOnly || Date.now() - this.switchedToCliAt < RETRY_FETCH_AFTER_MS)) {
+            return this.sendWithCli(req, maxBodyBytes);
+        }
+        try {
+            const res = await this.sendWithFetch(req, maxBodyBytes);
+            this.transport = 'fetch';
+            return res;
+        }
+        catch (e) {
+            if (!(e instanceof FetchFailure))
+                throw e;
+            // A request that changes data is sent again only if nothing reached
+            // Salesforce yet (the token could not be obtained). After a network
+            // error, Salesforce may already have processed it.
+            if (e.mayHaveReachedSalesforce && !readOnly)
+                throw new SalesforceUnreachableError();
+            // Switch only if sf succeeds: when the network is down, sf fails too.
+            log.warn(`${this.username}: ${e.message}; trying sf api request rest`);
+            const res = await this.sendWithCli(req, maxBodyBytes);
+            if (this.transport !== 'cli')
+                log.info(`${this.username}: switched to sf api request rest`);
+            this.transport = 'cli';
+            this.switchedToCliAt = Date.now();
+            return res;
+        }
+    }
+    async sendWithFetch(req, maxBodyBytes) {
+        let token = await this.getTokenForFetch();
+        let res = await this.fetchOnce(req, token, maxBodyBytes);
+        // Only Salesforce saying the session is invalid sends the request again: any
+        // other 401 (such as one from the user's Apex REST, which may have changed
+        // data first) is the answer (docs/rest.md "Salesforce が返した 4xx と 5xx").
+        if (isInvalidSession(res)) {
+            // The access token expired. sf refreshes it; if the refresh token is no
+            // longer valid, sf returns the same stale token and the retry fails too.
+            token = await this.getTokenForFetch(token);
+            res = await this.fetchOnce(req, token, maxBodyBytes);
+            if (isInvalidSession(res)) {
+                this.token = undefined;
+                throw new OrgAuthError(this.username, 'Salesforce rejected the session (401).');
+            }
+        }
+        return res;
+    }
+    async getTokenForFetch(stale) {
+        try {
+            return await this.getToken(stale);
+        }
+        catch (e) {
+            if (e instanceof OrgAuthError || e instanceof SfNotFoundError)
+                throw e;
+            if (e instanceof SfCliError && isAuthErrorMessage(e.message))
+                throw new OrgAuthError(this.username, e.message);
+            throw new FetchFailure(`could not get an access token (${e.message})`, false);
+        }
+    }
+    async sendWithCli(req, maxBodyBytes) {
+        try {
+            const res = await apiRequest(this.username, { method: req.method, path: req.path, headers: requestHeaders(req), body: req.body }, this.tmpDir, this.timeoutMs());
+            return maxBodyBytes !== undefined ? cutBody(res, maxBodyBytes) : res;
+        }
+        catch (e) {
+            // The same answer as fetch's timeout: Salesforce may have processed the request.
+            throw e instanceof SfTimeoutError ? new SalesforceTimeoutError() : e;
+        }
+    }
+    /**
+     * The access token. Concurrent callers share one `sf org auth
+     * show-access-token` run. `stale` is the token Salesforce just rejected: a
+     * new one is fetched only if no other caller has already replaced it.
+     */
+    getToken(stale) {
+        // All checks are synchronous, so that concurrent callers see each other's run.
+        if (this.token) {
+            if (stale === undefined)
+                return this.token;
+            const alreadyReplaced = this.tokenValue !== undefined && this.tokenValue !== stale;
+            if (stale === this.replacing || alreadyReplaced)
+                return this.token;
+        }
+        const pending = getAccessToken(this.username, this.tmpDir);
+        this.token = pending;
+        this.tokenValue = undefined;
+        this.replacing = stale;
+        pending.then((value) => {
+            if (this.token === pending) {
+                this.tokenValue = value;
+                this.replacing = undefined;
+            }
+        }, () => {
+            if (this.token === pending) {
+                this.token = undefined;
+                this.replacing = undefined;
+            }
+        });
+        return pending;
+    }
+    async fetchOnce(req, token, maxBodyBytes) {
+        try {
+            const res = await fetch(new URL(req.path, this.instanceUrl), {
+                method: req.method,
+                // The token goes last, so that no header of the request can replace it.
+                headers: { ...requestHeaders(req), authorization: `Bearer ${token}` },
+                body: req.body,
+                redirect: 'manual',
+                signal: AbortSignal.timeout(this.timeoutMs()),
+            });
+            const headers = {};
+            res.headers.forEach((value, key) => (headers[key] = value));
+            return { status: res.status, headers, ...(await readBody(res, maxBodyBytes)) };
+        }
+        catch (e) {
+            if (e.name === 'TimeoutError')
+                throw new SalesforceTimeoutError();
+            throw new FetchFailure(`fetch failed (${e.message})`, true);
+        }
+    }
+    recordApiUsage(header) {
+        const m = header ? /api-usage=(\d+)\/(\d+)/.exec(header) : null;
+        if (m)
+            this.apiUsage = { used: Number(m[1]), max: Number(m[2]) };
+    }
+}
+/**
+ * The headers to send: the defaults, then the request's own, all with names in
+ * lower case, so that `content-type` from the request replaces the default
+ * rather than adding a second value to it (docs/rest.md "要求").
+ */
+function requestHeaders(req) {
+    const headers = { accept: 'application/json' };
+    if (req.body !== undefined)
+        headers['content-type'] = 'application/json';
+    for (const [name, value] of Object.entries(req.headers ?? {}))
+        headers[name.toLowerCase()] = value;
+    return headers;
+}
+/**
+ * Reads the body, stopping once it is longer than `maxBodyBytes`. With a
+ * limit (the REST API screen), a body that stops arriving still returns the
+ * status, so that a processed request is not taken for one of unknown outcome.
+ */
+async function readBody(res, maxBodyBytes) {
+    if (maxBodyBytes === undefined || !res.body) {
+        const body = await res.text();
+        return { body, size: Buffer.byteLength(body) };
+    }
+    const chunks = [];
+    let size = 0;
+    const reader = res.body.getReader();
+    for (;;) {
+        let next;
+        try {
+            next = await reader.read();
+        }
+        catch {
+            // Salesforce answered (the status is known) but the body stopped
+            // arriving, such as when time ran out: the request was processed.
+            return { body: '', size, incomplete: true };
+        }
+        const { done, value } = next;
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > maxBodyBytes) {
+            await reader.cancel();
+            return { body: '', size, truncated: true };
+        }
+        chunks.push(value);
+    }
+    return { body: Buffer.concat(chunks).toString('utf8'), size };
+}
+function cutBody(res, maxBodyBytes) {
+    const size = Buffer.byteLength(res.body);
+    return size > maxBodyBytes ? { ...res, body: '', size, truncated: true } : { ...res, size };
+}
+function parseBody(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * The path to send, as checked: only paths under /services/ on the org's own
+ * instance may be requested, so that the server can never be used to send the
+ * token anywhere else. An absolute URL of the instance becomes its path.
+ */
+export function salesforcePath(path, instanceUrl) {
+    let url;
+    try {
+        url = new URL(path, instanceUrl);
+    }
+    catch {
+        throw new InvalidPathError(path);
+    }
+    if (url.origin !== new URL(instanceUrl).origin || !isServicesPath(url.pathname)) {
+        throw new InvalidPathError(path);
+    }
+    return url.pathname + url.search;
+}
+export class InvalidPathError extends Error {
+    constructor(path) {
+        super(`Only paths under /services/ on the org's instance are allowed: ${path}`);
+        this.name = 'InvalidPathError';
+    }
+}

package/dist/server/serve.js

@@ -0,0 +1,121 @@
+// The server process. In normal use the CLI entry point starts it detached in
+// the background; `npm run dev:server` runs it in the foreground.
+import { randomBytes } from 'node:crypto';
+import { readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJson, writeFileAtomic } from "./fsutil.js";
+import { App } from "./http/server.js";
+import { initLog, log } from "./log.js";
+import { OrgRegistry } from "./orgs.js";
+import { ensureDirs, resolvePaths, webRoot } from "./paths.js";
+import { removeServerInfo, writeServerInfo } from "./state.js";
+import { SettingsStore } from "./store.js";
+import { packageVersion } from "./version.js";
+export const DEFAULT_PORT = 7717;
+const LAST_PORT = 7736;
+export const DEV_PORT = 17717;
+const DEV_WEB_URL = 'http://localhost:5173/launch/dev';
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (e) => {
+            server.off('listening', onListening);
+            if (e.code === 'EADDRINUSE')
+                resolve(false);
+            else
+                reject(e);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve(true);
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, '127.0.0.1');
+    });
+}
+/** In dev mode, a session token that survives restarts, so that `node --watch` restarts do not log the UI out. */
+function devSessionToken(paths) {
+    const file = join(paths.home, 'dev-session.json');
+    const stored = readJson(file);
+    if (typeof stored?.token === 'string')
+        return stored.token;
+    const token = randomBytes(32).toString('base64url');
+    writeFileAtomic(file, JSON.stringify({ token }));
+    return token;
+}
+const TMP_MAX_AGE_MS = 60 * 60 * 1000;
+/**
+ * Removes leftovers older than an hour. Newer files may belong to an older
+ * server that did not stop and is still running next to this one.
+ */
+function cleanTmp(dir) {
+    const now = Date.now();
+    for (const name of readdirSync(dir)) {
+        const file = join(dir, name);
+        const mtime = statSync(file, { throwIfNoEntry: false })?.mtimeMs;
+        if (mtime !== undefined && now - mtime > TMP_MAX_AGE_MS)
+            rmSync(file, { recursive: true, force: true });
+    }
+}
+export async function serve(dev) {
+    const paths = resolvePaths(dev);
+    ensureDirs(paths);
+    initLog(paths.serverLog, dev);
+    cleanTmp(paths.tmpDir);
+    // Child processes inherit this directory. A fixed, private directory keeps
+    // cmd.exe on Windows from finding executables in the user's project.
+    process.chdir(paths.tmpDir);
+    const version = packageVersion();
+    const adminToken = randomBytes(32).toString('base64url');
+    const settings = new SettingsStore(paths.settings);
+    const orgs = new OrgRegistry(paths.tmpDir, process.env.SFBENCH_TRANSPORT === 'cli', () => settings.get().requestTimeoutSeconds * 1000);
+    let server;
+    const shutdown = () => {
+        log.info('shutting down');
+        removeServerInfo(paths.serverJson, process.pid);
+        server?.close();
+        server?.closeAllConnections();
+        setTimeout(() => process.exit(0), 100).unref();
+    };
+    const ports = dev ? [DEV_PORT] : Array.from({ length: LAST_PORT - DEFAULT_PORT + 1 }, (_, i) => DEFAULT_PORT + i);
+    // Created once: it reads the web UI's files into memory.
+    const app = new App({
+        version,
+        dev,
+        port: ports[0],
+        adminToken,
+        paths,
+        orgs,
+        settings,
+        webRoot: dev ? undefined : webRoot,
+        devSessionToken: dev ? devSessionToken(paths) : undefined,
+        onShutdown: shutdown,
+    });
+    for (const port of ports) {
+        app.port = port;
+        const candidate = app.createServer();
+        if (await listen(candidate, port)) {
+            server = candidate;
+            // Written after listening, and atomically, so that the CLI entry point
+            // never sees a server.json for a server that is not ready.
+            writeServerInfo(paths.serverJson, { port, adminToken, pid: process.pid, version });
+            log.info(`sfbench ${version} listening on 127.0.0.1:${port}${dev ? ' (dev)' : ''}`);
+            break;
+        }
+    }
+    if (!server) {
+        const message = dev
+            ? `Port ${DEV_PORT} is in use. Stop the other development server first.`
+            : `No free port between ${DEFAULT_PORT} and ${LAST_PORT}.`;
+        log.error(message);
+        process.exitCode = 1;
+        return;
+    }
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    if (dev)
+        process.stderr.write(`\nOpen ${DEV_WEB_URL} (started by \`npm run dev\`, or by \`npm run dev:web\` alongside \`npm run dev:server\`).\n\n`);
+    // Load the org list in the background: it can take several seconds. Then
+    // check each org's connection, which takes longer still.
+    orgs.list().then(() => void orgs.checkConnections(), (e) => log.warn(`could not load the org list: ${e.message}`));
+}

package/dist/server/sf/apexRun.js

@@ -0,0 +1,112 @@
+// `sf apex run`: runs anonymous Apex and returns the result with its debug
+// log (docs/apex.md "実行の経路"). One of the documented exceptions to "depend
+// only on sf's JSON output" being stable: sf reports compile errors and
+// exceptions as failures whose `data` holds the result as strings. All of that
+// reading 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, isAuthErrorMessage } from "./errors.js";
+import { lastErrorLine, redactUrls, runSf } from "./run.js";
+/**
+ * sf failed before or while running, and it cannot be told whether the code
+ * ran. `sfName` is sf's error name. The message is for the screen only: it is
+ * never logged (docs/apex.md "実行の経路").
+ */
+export class ApexRunError extends Error {
+    sfName;
+    constructor(sfName, message) {
+        super(message);
+        this.name = 'ApexRunError';
+        this.sfName = sfName;
+    }
+}
+/** The code could not be written to its file: sf was not started, so nothing ran. */
+export class ApexFileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApexFileError';
+    }
+}
+export function parseApexOutput(stdout, stderr) {
+    let json;
+    try {
+        json = JSON.parse(stdout);
+    }
+    catch {
+        json = undefined;
+    }
+    // 1. Ran.
+    if (json?.status === 0 && json.result)
+        return { kind: 'ran', run: toRun(json.result) };
+    // 2. Ran, or reached Salesforce and did not compile. Before 3: an exception's
+    // text can hold "invalid_grant" (a failed OAuth callout in the Apex itself).
+    // Decided by the name alone: without `data`, it may have run, so it is unknown, never a login error.
+    const message = redactUrls(json?.message ?? lastErrorLine(stderr) ?? 'sf apex run failed');
+    if (json?.name === 'executeCompileFailure' || json?.name === 'executeRuntimeFailure') {
+        return json.data ? { kind: 'ran', run: toRun(json.data) } : { kind: 'failed', sfName: json.name, message };
+    }
+    // 3. Only now: a login error, before anything ran.
+    if (isAuthErrorMessage(message))
+        return { kind: 'authError', message };
+    // 4. The rest is of unknown outcome.
+    return { kind: 'failed', sfName: json?.name ?? 'unreadable', message };
+}
+/** sf writes true or 'True', 1 or '1', and -1 for no position. */
+function toRun(r) {
+    const yes = (v) => v === true || v === 'True' || v === 'true';
+    const no = (v) => v === false || v === 'False' || v === 'false';
+    const text = (v) => (typeof v === 'string' && v ? v : undefined);
+    const position = (v) => {
+        const n = typeof v === 'number' ? v : typeof v === 'string' ? Number(v) : Number.NaN;
+        return Number.isInteger(n) && n > 0 ? n : undefined;
+    };
+    // Only a stated compile failure says it did not run: anything else may have run.
+    const result = no(r.compiled) ? 'compileError' : yes(r.success) ? 'success' : 'runtimeError';
+    const run = { result, logs: typeof r.logs === 'string' ? r.logs : '' };
+    if (result !== 'success') {
+        const line = position(r.line);
+        const column = position(r.column);
+        if (line !== undefined)
+            run.line = line;
+        if (column !== undefined)
+            run.column = column;
+    }
+    if (result === 'compileError')
+        run.compileProblem = text(r.compileProblem);
+    if (result === 'runtimeError') {
+        run.exceptionMessage = text(r.exceptionMessage);
+        run.exceptionStackTrace = text(r.exceptionStackTrace);
+    }
+    return run;
+}
+/**
+ * Runs anonymous Apex in the org. The code goes in a file so that it never
+ * appears on the command line. Throws OrgAuthError (did not run), SfTimeoutError
+ * (sf was stopped; Salesforce may still run it), ApexFileError (did not run)
+ * or ApexRunError (unknown). `apiVersion` is the only value from the screen on
+ * the command line, and only after it was found among the org's versions.
+ */
+export async function runApex(username, code, tmpDir, timeoutMs, apiVersion) {
+    const fileName = `apex-${randomBytes(8).toString('hex')}.apex`;
+    const filePath = join(tmpDir, fileName);
+    try {
+        try {
+            writeFileSync(filePath, code, { mode: 0o600 });
+        }
+        catch (e) {
+            throw new ApexFileError(e.message);
+        }
+        // An SfTimeoutError from runSf goes to the caller as it is.
+        const { stdout, stderr } = await runSf(['apex', 'run', '-f', fileName, ...(apiVersion ? ['--api-version', apiVersion] : []), '--json'], { targetOrg: username, cwd: tmpDir, timeoutMs });
+        const output = parseApexOutput(stdout, stderr);
+        if (output.kind === 'ran')
+            return output.run;
+        if (output.kind === 'authError')
+            throw new OrgAuthError(username, output.message);
+        throw new ApexRunError(output.sfName, output.message);
+    }
+    finally {
+        rmSync(filePath, { force: true });
+    }
+}