@fnndsc/porter 0.2.0

package/dist/host/processHost.js

@@ -0,0 +1,261 @@
+/**
+ * @file Sessions as child processes on this host, one per identity, each in
+ * four directories of its own.
+ *
+ * A session is `chell --daemon <user>@<url> --auth-token-stdin`: the token
+ * on stdin, one line, never argv; the config, runtime, cache and tmp
+ * directories under the porter's state, keyed by the identity's berth key,
+ * because a daemon that shares any of them with another identity's has cost
+ * real sessions their working directory. The child's berth lands in its own
+ * runtime directory, and that is where the host reads it back.
+ *
+ * The boot's stdout and stderr are kept, line by line, for as long as the
+ * child lives: a greeter that attaches late replays them, one that is there
+ * follows them, and the terminal boot and the browser boot are the same
+ * text.
+ *
+ * @module
+ */
+import { spawn as childSpawn } from 'node:child_process';
+import { mkdirSync, readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { berthKey_compute, berth_pathIn, berthUrl_isAlive } from '@fnndsc/calypso/berth';
+/** How many boot lines a session keeps for late followers. */
+export const BOOT_LINES_KEPT = 2_000;
+/** Default spawner: a real child with piped streams. */
+const spawn_real = (command, args, options) => {
+    const child = childSpawn(command, args, { env: options.env, stdio: options.stdio });
+    return child;
+};
+/**
+ * Splits a stream's chunks into lines, handing over each complete one.
+ *
+ * @param stream - The stream to read.
+ * @param onLine - Told each line without its ending.
+ */
+function stream_lines(stream, onLine) {
+    if (stream === null)
+        return;
+    let buffered = '';
+    stream.on('data', (chunk) => {
+        buffered += chunk.toString();
+        let cut = buffered.indexOf('\n');
+        while (cut !== -1) {
+            onLine(buffered.slice(0, cut).replace(/\r$/, ''));
+            buffered = buffered.slice(cut + 1);
+            cut = buffered.indexOf('\n');
+        }
+    });
+    stream.on('end', () => {
+        if (buffered.length > 0)
+            onLine(buffered);
+        buffered = '';
+    });
+}
+/** Sessions as child processes on this host. */
+export class ProcessHost {
+    stateDir;
+    chellEntry;
+    spawner;
+    alive;
+    bootTimeoutMs;
+    pollMs;
+    kill;
+    sessions = new Map();
+    constructor(options) {
+        this.stateDir = options.stateDir;
+        this.chellEntry = options.chellEntry;
+        this.spawner = options.spawn ?? spawn_real;
+        this.alive = options.alive ?? ((url) => berthUrl_isAlive(url));
+        this.bootTimeoutMs = options.bootTimeoutMs ?? 120_000;
+        this.pollMs = options.pollMs ?? 250;
+        this.kill = options.kill ?? ((pid, signal) => { process.kill(pid, signal); });
+    }
+    /**
+     * The four directories an identity's session owns, under the state dir.
+     *
+     * @param identity - The normalised identity.
+     * @returns The directories; not necessarily existing yet.
+     */
+    dirs_of(identity) {
+        const root = join(this.stateDir, berthKey_compute(identity));
+        return {
+            config: join(root, 'config'),
+            runtime: join(root, 'run'),
+            cache: join(root, 'cache'),
+            tmp: join(root, 'tmp'),
+        };
+    }
+    /** Reads a berth file, if well formed. */
+    berthFile_read(path) {
+        if (!existsSync(path))
+            return null;
+        try {
+            const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+            if (typeof parsed.url === 'string' && typeof parsed.token === 'string' && typeof parsed.identity === 'string') {
+                return { identity: parsed.identity, url: parsed.url, token: parsed.token, ...(typeof parsed.pid === 'number' ? { pid: parsed.pid } : {}) };
+            }
+        }
+        catch {
+            // A half-written berth reads as none; the next poll reads it whole.
+        }
+        return null;
+    }
+    /** Reads an identity's berth from its own runtime directory, if written. */
+    berth_read(identity) {
+        return this.berthFile_read(berth_pathIn(this.dirs_of(identity).runtime, identity));
+    }
+    /** @inheritdoc */
+    async sessions_adopt() {
+        const sightings = [];
+        if (!existsSync(this.stateDir))
+            return sightings;
+        for (const entry of readdirSync(this.stateDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const berthDir = join(this.stateDir, entry.name, 'run', 'calypso');
+            if (!existsSync(berthDir))
+                continue;
+            for (const name of readdirSync(berthDir)) {
+                if (!name.startsWith('berth-') || !name.endsWith('.json'))
+                    continue;
+                const berth = this.berthFile_read(join(berthDir, name));
+                if (berth === null)
+                    continue;
+                const alive = await this.alive(berth.url);
+                sightings.push({ identity: berth.identity, berth, alive });
+                if (alive && !this.sessions.has(berth.identity)) {
+                    this.sessions.set(berth.identity, {
+                        identity: berth.identity,
+                        child: null,
+                        adoptedPid: berth.pid ?? null,
+                        lines: [],
+                        state: 'ready',
+                        listeners: new Set(),
+                        starting: null,
+                    });
+                }
+            }
+        }
+        return sightings;
+    }
+    /** @inheritdoc */
+    async find(identity) {
+        const berth = this.berth_read(identity);
+        if (berth === null)
+            return null;
+        return (await this.alive(berth.url)) ? berth : null;
+    }
+    /** @inheritdoc */
+    async spawn(identity, user, cubeUrl, token) {
+        const existing = this.sessions.get(identity);
+        if (existing?.starting)
+            return existing.starting;
+        const record = {
+            identity,
+            child: null,
+            adoptedPid: null,
+            lines: [],
+            state: 'booting',
+            listeners: new Set(),
+            starting: null,
+        };
+        this.sessions.set(identity, record);
+        record.starting = this.boot_run(record, user, cubeUrl, token).finally(() => { record.starting = null; });
+        return record.starting;
+    }
+    /** @inheritdoc */
+    spawn_begin(identity, user, cubeUrl, token) {
+        // The failure is already on the boot record for whoever follows it; the
+        // promise's own rejection has nobody left to reach.
+        void this.spawn(identity, user, cubeUrl, token).catch(() => undefined);
+    }
+    /** Starts the child and waits for its berth to answer. */
+    async boot_run(record, user, cubeUrl, token) {
+        const dirs = this.dirs_of(record.identity);
+        for (const dir of Object.values(dirs))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const env = {
+            ...process.env,
+            XDG_CONFIG_HOME: dirs.config,
+            XDG_RUNTIME_DIR: dirs.runtime,
+            XDG_CACHE_HOME: dirs.cache,
+            TMPDIR: dirs.tmp,
+            // The boot rows are for a greeter that renders them as a terminal
+            // would; chalk sees no TTY here and would strip the colour.
+            FORCE_COLOR: '3',
+        };
+        // The greeter draws the brain itself, from the same frames; the boot's
+        // own copy on stdout would stand a second, still brain under the rows.
+        const child = this.spawner(process.execPath, [this.chellEntry, `${user}@${cubeUrl}`, '--daemon', '--auth-token-stdin', '--no-logo'], { env, stdio: ['pipe', 'pipe', 'pipe'] });
+        record.child = child;
+        const line_note = (channel, text) => {
+            const line = { channel, text };
+            record.lines.push(line);
+            // A daemon writes for as long as it lives; a follower wants the boot,
+            // not the year. The earliest lines go first.
+            if (record.lines.length > BOOT_LINES_KEPT)
+                record.lines.splice(0, record.lines.length - BOOT_LINES_KEPT);
+            for (const listener of record.listeners)
+                listener.line(line);
+        };
+        stream_lines(child.stdout, (text) => line_note('out', text));
+        stream_lines(child.stderr, (text) => line_note('err', text));
+        child.stdin?.end(`${token}\n`);
+        let exited = null;
+        child.once('exit', (code) => { exited = code ?? 0; });
+        const deadline = Date.now() + this.bootTimeoutMs;
+        while (Date.now() < deadline) {
+            if (exited !== null) {
+                return this.boot_end(record, 'failed', `the session exited during boot (code ${exited})`);
+            }
+            const berth = this.berth_read(record.identity);
+            if (berth !== null && (await this.alive(berth.url))) {
+                this.boot_end(record, 'ready');
+                return berth;
+            }
+            await new Promise((resolve) => { setTimeout(resolve, this.pollMs); });
+        }
+        child.kill('SIGTERM');
+        return this.boot_end(record, 'failed', `the session did not answer within ${Math.round(this.bootTimeoutMs / 1000)} s`);
+    }
+    boot_end(record, state, reason) {
+        record.state = state;
+        record.reason = reason;
+        for (const listener of record.listeners)
+            listener.done(state, reason);
+        record.listeners.clear();
+        if (state === 'failed')
+            throw new Error(reason);
+    }
+    /** @inheritdoc */
+    boot_follow(identity, listener) {
+        const record = this.sessions.get(identity);
+        if (record === undefined)
+            return null;
+        const report = { lines: [...record.lines], state: record.state, ...(record.reason !== undefined ? { reason: record.reason } : {}) };
+        if (record.state === 'booting')
+            record.listeners.add(listener);
+        return { report, release: () => { record.listeners.delete(listener); } };
+    }
+    /** @inheritdoc */
+    async evict(identity) {
+        const record = this.sessions.get(identity);
+        this.sessions.delete(identity);
+        if (record?.child && record.child.exitCode === null) {
+            record.child.kill('SIGTERM');
+            return true;
+        }
+        // A session an earlier porter started is known by its berth, and the
+        // berth carries the pid. It is signalled only while the berth answers:
+        // a pid whose daemon is gone may be somebody else's by now.
+        const berth = this.berth_read(identity);
+        const pid = record?.adoptedPid ?? berth?.pid ?? null;
+        if (berth !== null && pid !== null && (await this.alive(berth.url))) {
+            this.kill(pid, 'SIGTERM');
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=processHost.js.map

package/dist/host/processHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processHost.js","sourceRoot":"","sources":["../../src/host/processHost.ts"],"names":[],"mappings":"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"}

package/dist/host/sessionHost.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @file The seam between the door and wherever sessions run.
+ *
+ * On one host a session is a child process in four directories of its own;
+ * on a cluster it is a pod with a volume. The porter never knows which: it
+ * asks the host to find an identity's session, to start one with a token,
+ * and to end one, and it gets back a berth — an address and an attach
+ * token — either way. This is the `BerthResolver` seam of tier 1 walked
+ * through: the surface's attach path did not change for identity-keyed
+ * daemons, and the door's does not change for pods.
+ *
+ * @module
+ */
+import type { Berth } from '@fnndsc/calypso/berth';
+export type { Berth };
+/** One line of a session's boot, as the host saw it. */
+export interface BootLine {
+    /** Which stream it came off. */
+    channel: 'out' | 'err';
+    /** The line, ANSI and all: the greeter renders it as the terminal would. */
+    text: string;
+}
+/** A boot in progress, or finished, as a host reports it. */
+export interface BootReport {
+    /** Every line so far, in order. */
+    lines: BootLine[];
+    /** Whether the session is up (berth answering), still booting, or gone. */
+    state: 'booting' | 'ready' | 'failed';
+    /** What went wrong, when the state is `failed`. */
+    reason?: string;
+}
+/** Who to tell as a boot proceeds. */
+export interface BootListener {
+    line(line: BootLine): void;
+    done(state: 'ready' | 'failed', reason?: string): void;
+}
+/** One session a host knows of, for a listing. */
+export interface SessionSighting {
+    identity: string;
+    berth: Berth;
+    alive: boolean;
+}
+/** Where sessions run. */
+export interface SessionHost {
+    /**
+     * Finds every session this host holds a berth for, alive or not, and
+     * takes the live ones under its wing — a porter restarted adopts the
+     * fleet its predecessor started rather than starting rivals.
+     *
+     * @returns Every berth found, with whether its daemon answers.
+     */
+    sessions_adopt(): Promise<SessionSighting[]>;
+    /**
+     * Finds an identity's live session.
+     *
+     * @param identity - The normalised `<user>@<url>`.
+     * @returns Its berth, or null when no session of theirs answers.
+     */
+    find(identity: string): Promise<Berth | null>;
+    /**
+     * Starts an identity's session with a CUBE token, or joins one already
+     * starting; resolves once its berth answers.
+     *
+     * @param identity - The normalised `<user>@<url>`.
+     * @param user - The CUBE username.
+     * @param cubeUrl - The CUBE API base.
+     * @param token - The CUBE token the door minted; the session's only credential.
+     * @returns The berth.
+     * @throws {Error} When the session does not come up.
+     */
+    spawn(identity: string, user: string, cubeUrl: string, token: string): Promise<Berth>;
+    /**
+     * Starts an identity's session and returns at once: the boot is followed
+     * through {@link boot_follow}, and its end — ready, or failed with a
+     * reason — is recorded there rather than thrown to anyone.
+     *
+     * @param identity - The normalised `<user>@<url>`.
+     * @param user - The CUBE username.
+     * @param cubeUrl - The CUBE API base.
+     * @param token - The CUBE token the door minted.
+     */
+    spawn_begin(identity: string, user: string, cubeUrl: string, token: string): void;
+    /**
+     * Reads what a session's boot has said so far, and follows it.
+     *
+     * @param identity - The normalised `<user>@<url>`.
+     * @param listener - Told each line from now on, and the end.
+     * @returns The lines so far and the state now, or null when the host has
+     *   no boot on record for this identity. The listener is released when
+     *   the boot ends or when the returned function is called.
+     */
+    boot_follow(identity: string, listener: BootListener): {
+        report: BootReport;
+        release: () => void;
+    } | null;
+    /**
+     * Ends an identity's session.
+     *
+     * @param identity - The normalised `<user>@<url>`.
+     * @returns Whether there was one to end.
+     */
+    evict(identity: string): Promise<boolean>;
+}

package/dist/host/sessionHost.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sessionHost.js.map

package/dist/host/sessionHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionHost.js","sourceRoot":"","sources":["../../src/host/sessionHost.ts"],"names":[],"mappings":""}

package/dist/porter.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/porter.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * @file The `porter` entry: the mise display manager.
+ *
+ * Reads its configuration from the environment, stands a process host on
+ * this machine, and listens. `porter --status` lists the sessions a running
+ * porter's state directory holds.
+ *
+ * @module
+ */
+import { porterConfig_resolve } from './config.js';
+import { ProcessHost } from './host/processHost.js';
+import { porterApp_build } from './app.js';
+import { berthKey_compute } from '@fnndsc/calypso/berth';
+/**
+ * Lists the sessions the state directory holds, without starting anything.
+ *
+ * @param config - Where the state directory is.
+ */
+async function status_print(config) {
+    const host = new ProcessHost({ stateDir: config.stateDir, chellEntry: config.chellEntry });
+    const sightings = await host.sessions_adopt();
+    console.log(`state: ${config.stateDir}`);
+    if (sightings.length === 0) {
+        console.log('no sessions');
+        return;
+    }
+    for (const sighting of sightings) {
+        const state = sighting.alive ? 'answering' : 'gone';
+        console.log(`${berthKey_compute(sighting.identity)}  ${state.padEnd(9)}  ${sighting.berth.url.padEnd(24)}  ${sighting.identity}${sighting.berth.pid !== undefined ? `  pid ${sighting.berth.pid}` : ''}`);
+    }
+}
+async function porter_start() {
+    let config;
+    try {
+        config = porterConfig_resolve(process.env);
+    }
+    catch (error) {
+        console.error(`[!] ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+    if (process.argv.includes('--status')) {
+        await status_print(config);
+        return;
+    }
+    const host = new ProcessHost({ stateDir: config.stateDir, chellEntry: config.chellEntry });
+    const sweepText = process.env['PORTER_SWEEP_SECONDS'];
+    const built = await porterApp_build({
+        config,
+        host,
+        logger: false,
+        log: (line) => { console.log(`[+] ${line}`); },
+        // Not documented: the sweep's cadence only matters to a test of it.
+        ...(sweepText !== undefined && Number(sweepText) > 0 ? { sweepMs: Number(sweepText) * 1000 } : {}),
+    });
+    await built.app.listen({ host: config.host, port: config.port });
+    console.log(`[+] PORTER at http://${config.host}:${config.port}/ for ${config.cubeUrl}`);
+    console.log(`    state:  ${config.stateDir}`);
+    console.log(`    chell:  ${config.chellEntry}`);
+    console.log(`    idle:   sessions end after ${config.idleHours} h with nobody on them; their state directories stay`);
+    if (config.secretGenerated) {
+        console.log('    secret: made up for this run — set PORTER_SECRET so a restart does not ask every browser again');
+    }
+    const stop = async () => {
+        await built.app.close();
+        process.exit(0);
+    };
+    process.once('SIGINT', () => { void stop(); });
+    process.once('SIGTERM', () => { void stop(); });
+}
+void porter_start();
+//# sourceMappingURL=porter.js.map

package/dist/porter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"porter.js","sourceRoot":"","sources":["../src/porter.ts"],"names":[],"mappings":"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"}

package/dist/registry.d.ts

@@ -0,0 +1,58 @@
+import type { Berth, SessionHost } from './host/sessionHost.js';
+/** One identity the door has let through. */
+export interface SessionEntry {
+    key: string;
+    identity: string;
+    user: string;
+    berth: Berth;
+    /** When something last reached the session through the door, epoch ms. */
+    activeAt: number;
+    /** How many wires — relayed WebSockets — stand open on it right now. */
+    wires: number;
+}
+/** The sessions the door knows, by key. */
+export declare class SessionRegistry {
+    private readonly byKey;
+    private readonly pending;
+    private readonly clock;
+    constructor(clock?: () => number);
+    /**
+     * The key an identity is addressed by.
+     *
+     * @param identity - The normalised identity.
+     * @returns Sixteen hex characters, stable for the identity.
+     */
+    key_of(identity: string): string;
+    /** Records an identity and the berth it answers at; a known one keeps its wires. */
+    note(identity: string, user: string, berth: Berth): SessionEntry;
+    /** Something reached the session through the door just now. */
+    activity_note(key: string): void;
+    /** A wire opened on the session, or closed. */
+    wire_count(key: string, delta: 1 | -1): void;
+    /**
+     * The sessions nobody has touched for longer than the span: no wire open,
+     * nothing through the door since.
+     *
+     * @param idleMs - The span.
+     * @returns The idle entries.
+     */
+    idle_list(idleMs: number): SessionEntry[];
+    /** Records an identity whose session is booting; the berth comes later. */
+    pending_note(identity: string, user: string): void;
+    /** The identity behind a key, admitted or still booting. */
+    identity_of(key: string): string | null;
+    /**
+     * Moves a booting identity into the registry once its berth answers.
+     *
+     * @param identity - The identity whose boot ended.
+     * @param host - Where to read the berth from.
+     * @returns The entry, or null when the boot ended without a berth.
+     */
+    settle(identity: string, host: Pick<SessionHost, 'find'>): Promise<SessionEntry | null>;
+    /** Looks a key up. */
+    get(key: string): SessionEntry | null;
+    /** Forgets a key. */
+    forget(key: string): void;
+    /** Every entry, for a status listing. */
+    all(): SessionEntry[];
+}

package/dist/registry.js

@@ -0,0 +1,107 @@
+/**
+ * @file Who is behind which door.
+ *
+ * A browser names its session by a short key in the path — `/s/<key>/` —
+ * never by the identity, which carries a URL with slashes in it and is the
+ * operator's business, not the URL bar's. The key is the berth key calypso
+ * already computes for the identity, so a porter restarted finds the same
+ * key for the same operator. The registry maps key to identity and to the
+ * berth the door last saw.
+ *
+ * @module
+ */
+import { berthKey_compute } from '@fnndsc/calypso/berth';
+/** The sessions the door knows, by key. */
+export class SessionRegistry {
+    byKey = new Map();
+    pending = new Map();
+    clock;
+    constructor(clock = () => Date.now()) {
+        this.clock = clock;
+    }
+    /**
+     * The key an identity is addressed by.
+     *
+     * @param identity - The normalised identity.
+     * @returns Sixteen hex characters, stable for the identity.
+     */
+    key_of(identity) {
+        return berthKey_compute(identity);
+    }
+    /** Records an identity and the berth it answers at; a known one keeps its wires. */
+    note(identity, user, berth) {
+        const key = this.key_of(identity);
+        const known = this.byKey.get(key);
+        const entry = { key, identity, user, berth, activeAt: this.clock(), wires: known?.wires ?? 0 };
+        this.byKey.set(key, entry);
+        return entry;
+    }
+    /** Something reached the session through the door just now. */
+    activity_note(key) {
+        const entry = this.byKey.get(key);
+        if (entry !== undefined)
+            entry.activeAt = this.clock();
+    }
+    /** A wire opened on the session, or closed. */
+    wire_count(key, delta) {
+        const entry = this.byKey.get(key);
+        if (entry === undefined)
+            return;
+        entry.wires = Math.max(0, entry.wires + delta);
+        entry.activeAt = this.clock();
+    }
+    /**
+     * The sessions nobody has touched for longer than the span: no wire open,
+     * nothing through the door since.
+     *
+     * @param idleMs - The span.
+     * @returns The idle entries.
+     */
+    idle_list(idleMs) {
+        const now = this.clock();
+        return [...this.byKey.values()].filter((entry) => entry.wires === 0 && now - entry.activeAt > idleMs);
+    }
+    /** Records an identity whose session is booting; the berth comes later. */
+    pending_note(identity, user) {
+        const key = this.key_of(identity);
+        if (this.byKey.has(key))
+            return;
+        this.pending.set(key, { key, identity, user });
+    }
+    /** The identity behind a key, admitted or still booting. */
+    identity_of(key) {
+        return this.byKey.get(key)?.identity ?? this.pending.get(key)?.identity ?? null;
+    }
+    /**
+     * Moves a booting identity into the registry once its berth answers.
+     *
+     * @param identity - The identity whose boot ended.
+     * @param host - Where to read the berth from.
+     * @returns The entry, or null when the boot ended without a berth.
+     */
+    async settle(identity, host) {
+        const key = this.key_of(identity);
+        const waiting = this.pending.get(key);
+        if (waiting === undefined)
+            return this.byKey.get(key) ?? null;
+        const berth = await host.find(identity);
+        if (berth === null)
+            return null;
+        this.pending.delete(key);
+        return this.note(identity, waiting.user, berth);
+    }
+    /** Looks a key up. */
+    get(key) {
+        return this.byKey.get(key) ?? null;
+    }
+    /** Forgets a key. */
+    forget(key) {
+        this.byKey.delete(key);
+        this.pending.delete(key);
+    }
+    /** Every entry, for a status listing. */
+    all() {
+        return [...this.byKey.values()];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"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"}