sideby 0.0.0-stage → 0.1.0

package/dist/src/panel/background.js

@@ -0,0 +1,274 @@
+// `sideby ui --background` and `--stop`: one detached Panel per state directory, found again through a pid file.
+// The detached process runs `sideby ui --serve-detached`; that flag is internal. `--stop` signals a pid only when
+// the process, its start time and the Panel answering on the recorded port all match the pid file.
+import { execFile, spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { loginShellPath } from '../core/login-path.js';
+import { buildId } from '../core/version.js';
+import { DEFAULT_PANEL_PORT, isSidebyPanel, panelIdentity, startPanelServer, } from './server.js';
+export const DETACHED_FLAG = 'serve-detached';
+const START_TIMEOUT_MS = 20_000;
+const LOCK_STALE_MS = 30_000;
+const STOP_TIMEOUT_MS = 5000;
+const LOG_MAX_BYTES = 1_000_000;
+export const pidFilePath = (p) => join(p.stateDir, 'panel.json');
+export const logFilePath = (p) => join(p.stateDir, 'panel.log');
+const lockPath = (p) => join(p.stateDir, 'panel.lock');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function readPidFile(p) {
+    try {
+        const d = JSON.parse(await readFile(pidFilePath(p), 'utf8'));
+        if (Number.isInteger(d.pid) && Number.isInteger(d.port) && typeof d.url === 'string')
+            return { ...d, instance: typeof d.instance === 'string' ? d.instance : '' };
+    }
+    catch { }
+    return undefined;
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** Output of `ps -o <field>= -p <pid>`, or undefined when the process is gone or `ps` is unavailable. */
+function psField(pid, field) {
+    return new Promise((resolve) => {
+        execFile('ps', ['-ww', '-o', `${field}=`, '-p', String(pid)], { timeout: 3000, env: { ...process.env, LC_ALL: 'C' } }, (err, stdout) => resolve(err ? undefined : stdout.trim() || undefined));
+    });
+}
+/** When `pid` started, as `ps` prints it; with the pid it names one process, which a reused pid does not match. */
+export const processStartTime = (pid) => psField(pid, 'lstart');
+/**
+ * Checks that the pid file names a live detached Panel: the process is alive, started when the pid file says,
+ * runs `ui --serve-detached`, and the Panel on the recorded port answers with the same instance id and pid.
+ */
+async function checkPanel(rec) {
+    const stale = (reason) => ({ status: 'stale', reason });
+    if (!rec.instance)
+        return stale('it names no panel instance');
+    if (!alive(rec.pid))
+        return stale(`process ${rec.pid} is not running`);
+    if (rec.processStart && (await processStartTime(rec.pid)) !== rec.processStart)
+        return stale(`process ${rec.pid} is not the one that wrote it`);
+    const cmd = await psField(rec.pid, 'command');
+    if (!(cmd && / ui( |$)/.test(cmd) && cmd.includes(`--${DETACHED_FLAG}`)))
+        return stale(`process ${rec.pid} is not a sideby panel`);
+    const id = await panelIdentity(rec.port);
+    if (!id)
+        return {
+            status: 'unconfirmed',
+            reason: `process ${rec.pid} does not answer as a sideby panel on port ${rec.port}; if it is one, stop it with \`kill ${rec.pid}\``,
+        };
+    if (id.instance !== rec.instance || id.pid !== rec.pid)
+        return stale(`the panel on port ${rec.port} is not the one it names`);
+    return { status: 'ours', ...(id.build ? { build: id.build } : {}) };
+}
+/** URL of a running background Panel, or of any sideby Panel on `port`; removes a stale pid file. */
+export async function findRunningPanel(p, port) {
+    const rec = await readPidFile(p);
+    if (rec) {
+        const check = await checkPanel(rec);
+        if (check.status === 'ours')
+            return rec.url;
+        if (check.status === 'stale')
+            await rm(pidFilePath(p), { force: true });
+    }
+    return (await isSidebyPanel(port)) ? `http://127.0.0.1:${port}/` : undefined;
+}
+/**
+ * Stops this state directory's background Panel when it runs another build than `build` (or is older than build
+ * ids). Only a Panel the pid file names and that answers as itself is stopped; true when one was.
+ */
+async function stopOutdated(p, build) {
+    const rec = await readPidFile(p);
+    if (!rec)
+        return false;
+    const check = await checkPanel(rec);
+    if (check.status !== 'ours' || check.build === build)
+        return false;
+    return (await stopBackgroundPanel(p)).status === 'stopped';
+}
+/** Takes the start lock, waiting while another launch holds it; a lock older than 30 s is taken over. */
+async function withStartLock(p, fn) {
+    const lock = lockPath(p);
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    for (;;) {
+        try {
+            const fh = await open(lock, 'wx', 0o600);
+            await fh.writeFile(String(process.pid));
+            await fh.close();
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            const age = await stat(lock).then((s) => Date.now() - s.mtimeMs, () => 0);
+            if (age > LOCK_STALE_MS || Date.now() > deadline)
+                await rm(lock, { force: true });
+            else
+                await sleep(200);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        await rm(lock, { force: true });
+    }
+}
+async function openLog(p) {
+    const log = logFilePath(p);
+    const size = await stat(log).then((s) => s.size, () => 0);
+    if (size > LOG_MAX_BYTES)
+        await rename(log, `${log}.1`).catch(() => { });
+    return open(log, 'a', 0o600);
+}
+/**
+ * Makes sure one background Panel runs and returns its URL. Reuses a running one; otherwise starts
+ * `sideby ui --serve-detached` in its own session, logging to the state directory, and waits until it listens.
+ */
+export async function startBackgroundPanel(opts) {
+    const { paths } = opts;
+    const port = opts.port ?? DEFAULT_PANEL_PORT;
+    // After an upgrade or reinstall the old background Panel still runs the old code: replace it.
+    const replaced = await stopOutdated(paths, buildId(opts.env));
+    const running = await findRunningPanel(paths, port);
+    if (running)
+        return { url: running, reused: true };
+    await mkdir(paths.stateDir, { recursive: true, mode: 0o700 });
+    return withStartLock(paths, async () => {
+        // Another launch may have started one while this one waited for the lock.
+        const again = await findRunningPanel(paths, port);
+        if (again)
+            return { url: again, reused: true };
+        const log = await openLog(paths);
+        try {
+            await log.write(`\n[${new Date().toISOString()}] starting background panel on port ${port}\n`);
+            const child = spawn(process.execPath, [opts.entry, 'ui', `--${DETACHED_FLAG}`, '--no-open', '--port', String(port)], {
+                env: opts.env,
+                detached: true,
+                stdio: ['ignore', log.fd, log.fd, 'ipc'],
+            });
+            const msg = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    child.kill('SIGTERM');
+                    reject(new Error(`the background panel did not start; see ${logFilePath(paths)}`));
+                }, START_TIMEOUT_MS);
+                child.once('message', (m) => {
+                    clearTimeout(timer);
+                    resolve(m);
+                });
+                child.once('error', (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                });
+                child.once('exit', (code) => {
+                    clearTimeout(timer);
+                    reject(new Error(`the background panel exited (code ${code}); see ${logFilePath(paths)}`));
+                });
+            });
+            child.removeAllListeners();
+            if (child.connected)
+                child.disconnect();
+            child.unref();
+            if (msg.reused)
+                return { url: msg.url, reused: true };
+            return { url: msg.url, reused: false, pid: child.pid, ...(replaced ? { replaced } : {}) };
+        }
+        finally {
+            await log.close();
+        }
+    });
+}
+/**
+ * Body of the detached process: serve the Panel with Hosts found through the login shell's PATH, tell the
+ * launching process the URL over IPC, keep the pid file while running, and remove it on SIGTERM or SIGINT.
+ */
+export async function serveDetached(opts) {
+    const { paths, log } = opts;
+    // Started now, awaited by the first request: the server listens without waiting for the shell.
+    const envReady = loginShellPath(opts.env).then((r) => {
+        log(r.source === 'login-shell'
+            ? 'host PATH: from the login shell'
+            : `host PATH: login shell unusable (${r.reason}); using the inherited PATH`);
+        return { ...opts.env, PATH: r.path };
+    });
+    const instance = randomBytes(16).toString('hex');
+    const srv = await startPanelServer({
+        runtimeFactory: async () => opts.runtimeFactory(await envReady),
+        instance,
+        ...(opts.port ? { port: opts.port } : {}),
+        open: false,
+        log,
+    });
+    const send = (m) => {
+        if (process.send)
+            process.send(m);
+        if (process.connected)
+            process.disconnect();
+    };
+    if (srv.reused) {
+        send({ url: srv.url, reused: true });
+        return 0;
+    }
+    const rec = {
+        pid: process.pid,
+        port: Number(new URL(srv.url).port),
+        url: srv.url,
+        startedAt: new Date().toISOString(),
+        instance,
+    };
+    const processStart = await processStartTime(process.pid);
+    if (processStart)
+        rec.processStart = processStart;
+    await writeFile(pidFilePath(paths), `${JSON.stringify(rec, null, 2)}\n`, { mode: 0o600 });
+    send({ url: srv.url, reused: false });
+    await new Promise((resolve) => {
+        const stop = (sig) => {
+            log(`[${new Date().toISOString()}] ${sig}: stopping`);
+            void srv.close().finally(resolve);
+        };
+        process.once('SIGTERM', () => stop('SIGTERM'));
+        process.once('SIGINT', () => stop('SIGINT'));
+        process.on('SIGHUP', () => { });
+    });
+    const now = await readPidFile(paths);
+    if (now?.pid === process.pid)
+        await rm(pidFilePath(paths), { force: true });
+    return 0;
+}
+/** Stops the background Panel named in the pid file, signalling it only when checkPanel confirms it. */
+export async function stopBackgroundPanel(paths) {
+    const rec = await readPidFile(paths);
+    if (!rec)
+        return { status: 'not-running' };
+    const check = await checkPanel(rec);
+    if (check.status === 'stale') {
+        await rm(pidFilePath(paths), { force: true });
+        return { status: 'not-running', detail: `removed a stale pid file (${check.reason})` };
+    }
+    if (check.status === 'unconfirmed')
+        return { status: 'failed', pid: rec.pid, detail: check.reason };
+    try {
+        process.kill(rec.pid, 'SIGTERM');
+    }
+    catch (err) {
+        return { status: 'failed', pid: rec.pid, detail: err.message };
+    }
+    const deadline = Date.now() + STOP_TIMEOUT_MS;
+    while (alive(rec.pid) && Date.now() < deadline)
+        await sleep(100);
+    if (alive(rec.pid))
+        return {
+            status: 'failed',
+            pid: rec.pid,
+            detail: `process ${rec.pid} did not exit within ${STOP_TIMEOUT_MS / 1000} s; stop it with \`kill ${rec.pid}\``,
+        };
+    await rm(pidFilePath(paths), { force: true });
+    return { status: 'stopped', pid: rec.pid, url: rec.url };
+}

package/dist/src/panel/handler.d.ts

@@ -0,0 +1,93 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { AccountStatus, DoctorHistory, FamilyInfo, Runtime } from '../runtime.ts';
+import type { Account, FamilyLogo, QuotaResult, QuotaSetupPlan, UsageResult } from '../types.ts';
+import { type PanelTheme } from './theme.ts';
+export declare const PANEL_VERSION: string;
+export declare const MAX_BODY_BYTES: number;
+/** Write requests allowed to wait behind the running one; more get 409. */
+export declare const MAX_QUEUED_WRITES = 4;
+export interface PanelHandlerOptions {
+    /** A Runtime, or a factory called per request so every response reflects the disk. */
+    runtime: Runtime | (() => Promise<Runtime>);
+    /** Mount point such as `/accounts`; empty or `/` for the root. */
+    basePath?: string;
+    /** Accepted `Host` header values, for example `127.0.0.1:17420`. */
+    allowedHosts: string[];
+    /** Rejects changes (fix, create, quota setup apply and teardown) with 403. */
+    readOnly?: boolean;
+    version?: string;
+    /**
+     * Design tokens that make the page match the embedding page. Checked when the handler is created: an unknown
+     * token or a value that could leave its CSS declaration throws a TypeError.
+     */
+    theme?: PanelTheme;
+    /**
+     * The Panel's language. `en` or `zh` wins over what the viewer saved and hides the Panel's own switch; `auto`
+     * (the default) uses the viewer's saved choice, then the browser language. Checked when the handler is created:
+     * any other value throws a TypeError. A Portal that changes language creates the handler again.
+     */
+    lang?: 'auto' | 'en' | 'zh';
+}
+export type PanelHandler = ((req: IncomingMessage, res: ServerResponse) => Promise<boolean>) & {
+    /** Per-instance secret the page sends as `x-sideby-token`. */
+    readonly token: string;
+};
+export type PanelAccount = (AccountStatus | (Account & Partial<AccountStatus>)) & {
+    quota?: QuotaResult;
+    usage?: UsageResult;
+    error?: string;
+    /** Latest Doctor result for this Account; absent when it was never checked. */
+    health?: {
+        at: string;
+        fail: number;
+        warn: number;
+    };
+    /** Config `aliases` that point at this Account, sorted; absent when none do. */
+    aliases?: string[];
+    /** Host arguments of those aliases that add any (alias → arguments); absent when none do. */
+    aliasArgs?: Record<string, string[]>;
+};
+export type { DoctorHistory };
+/** Counts of failing and warning Findings per checked Account, from the Doctor history. */
+export declare function healthByAccount(history: DoctorHistory | undefined): Map<string, {
+    at: string;
+    fail: number;
+    warn: number;
+}>;
+/** Alias names per Account ref, sorted. An alias whose target matches no Account is left out. */
+export declare function aliasesByAccount(aliases: Readonly<Record<string, string>> | undefined, accounts: readonly Account[]): Map<string, string[]>;
+/** A Family as the page sees it: FamilyInfo plus the mark from its FamilyDef. */
+export type PanelFamily = FamilyInfo & {
+    logo?: FamilyLogo;
+};
+export interface PanelState {
+    schemaVersion: 1;
+    version: string;
+    /** buildId() of the process serving the Panel: a page from another build reloads itself. */
+    build: string;
+    readOnly: boolean;
+    generatedAt: string;
+    families: PanelFamily[];
+    accounts: PanelAccount[];
+    pluginErrors: {
+        where: string;
+        message: string;
+    }[];
+    quotaSetups: {
+        family: string;
+        summary: string;
+        plan: QuotaSetupPlan;
+    }[];
+    /** Latest Doctor result per Account and per Family. */
+    history?: DoctorHistory;
+    /** The config `aliases` as alias → Account ref (arguments left out), so the page can tell which names are taken. */
+    configAliases?: Record<string, string>;
+    /**
+     * Family → the Account `sideby next <family>` would pick (spec §3.13). Only Families with a Quota source,
+     * at least two subscription Accounts, some Quota data and a pick; API Accounts are left out as in the CLI default.
+     */
+    handoff?: Record<string, string>;
+}
+/** The `handoff` map of the Panel state, from the statuses and Quota already read for the page. */
+export declare function handoffByFamily(rt: Runtime, accounts: readonly PanelAccount[], now: Date): Record<string, string>;
+export declare function createPanelHandler(opts: PanelHandlerOptions): PanelHandler;