@platless/axom-cli 0.3.13 → 0.5.9

package/dist/workstation/keepers/terminal/client.js

@@ -0,0 +1,213 @@
+// Daemon-side: a typed `pty.*` client for keeper-terminal (launch through KeeperLauncher, one long-lived KeeperClient per
+// generation). Exempt from the keeper-side import guard.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { readKeeperManifest } from '../kit/bundle.js';
+import { KeeperClient } from '../kit/client.js';
+import { keeperGen } from '../kit/identity.js';
+import { defaultDistDir } from '../kit/launcher.js';
+import { protocolWindow } from '../kit/protocol.js';
+import { PTY_CAPABILITY, PTY_UNAVAILABLE_ERROR, TERMINAL_PROTOCOL_VERSION, execStream, } from './protocol.js';
+/** keeper-terminal could not be reached (launch, connect or hello failed): the request was never sent. */
+export class KeeperLaunchError extends Error {
+    cause;
+    code = 'launch_failed';
+    // The cause's message unchanged: terminal.* callers surface it as before.
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause));
+        this.cause = cause;
+        this.name = 'KeeperLaunchError';
+    }
+}
+/** The terminal fields a keeper-terminal hello implies: `pty` capability, or today's unavailable wording. */
+export function terminalStatusOf(hello) {
+    return hello.capabilities.includes(PTY_CAPABILITY) ? { terminal: true } : { terminal: false, terminalError: PTY_UNAVAILABLE_ERROR };
+}
+/** Records how long a "nothing is running" answer stays valid, so a high-frequency probe does not knock on a missing socket each time. */
+const NOT_RUNNING_TTL_MS = 5000;
+/** The default bound of {@link TerminalKeeperClient.probe}: a real connect and hello, not a quick peek. */
+export const KEEPER_PROBE_TIMEOUT_MS = 3000;
+const errnoOf = (error) => typeof error === 'object' && error !== null && typeof error.code === 'string' ? error.code : undefined;
+/** Connect errors that prove nothing listens: the socket file is gone, or a stale one with no listener behind it. */
+const ABSENT_ERRNOS = new Set(['ENOENT', 'ECONNREFUSED']);
+const messageOf = (error) => (error instanceof Error ? error.message : String(error));
+export class TerminalKeeperClient {
+    options;
+    client;
+    clientGen;
+    /** The generation of the build the launcher last ensured (the daemon's current keeper-terminal build). */
+    currentGen;
+    /** Until when a proven absence is remembered (only `absent` is cached for this long). */
+    notRunningUntil = 0;
+    /** Until when `runningHello` answers null after an undecided probe without probing again (never used by `probe`). */
+    undecidedUntil = 0;
+    /** Probes in flight, by bound: a caller joins one with its own bound (a 300 ms peek never answers a 3 s probe). */
+    probing = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    get daemonProtocol() { return this.options.daemonProtocol ?? protocolWindow(TERMINAL_PROTOCOL_VERSION); }
+    clientFor(paths) {
+        if (this.client && this.clientGen === paths.gen)
+            return this.client;
+        this.client?.close();
+        this.client = new KeeperClient({
+            kind: 'terminal', socket: paths.socket, tokenFile: paths.tokenFile, gen: paths.gen, daemonProtocol: this.daemonProtocol,
+            requestTimeoutMs: this.options.requestTimeoutMs, connectTimeoutMs: this.options.connectTimeoutMs,
+        });
+        this.client.on('error', () => { }); // state changes are observed through `state`; never crash the daemon on an emitter error
+        this.clientGen = paths.gen;
+        return this.client;
+    }
+    /** The hello of the connected keeper, if this client currently holds a ready connection. Never does IO. */
+    get hello() { return this.client?.state === 'ready' ? this.client.hello : undefined; }
+    /** The generation this client is bound to (`gen`), or `undefined` for the current build's. */
+    get gen() { return this.options.gen; }
+    /**
+     * The connected client of the current build, launching it only when needed. A ready connection to the current build's
+     * generation is returned as is (no manifest read, no probe), so per-request calls such as `pty.poll` cost one round trip.
+     * Anything else (no client yet, reconnecting, keeper gone, another generation) goes through the launcher, which starts at
+     * most one keeper per kind at a time. A `gen`-bound client only connects to its generation.
+     */
+    async ensure() {
+        const current = this.client;
+        if (this.options.gen !== undefined) {
+            if (current && current.state === 'ready')
+                return current;
+            const client = this.clientFor(this.options.launcher.pathsFor('terminal', this.options.gen));
+            await client.connect();
+            return client;
+        }
+        if (current && current.state === 'ready' && this.clientGen !== undefined && this.clientGen === this.currentGen)
+            return current;
+        const handle = await this.options.launcher.launch('terminal');
+        this.currentGen = handle.paths.gen;
+        const client = this.clientFor(handle.paths);
+        await client.connect();
+        this.notRunningUntil = 0;
+        this.undecidedUntil = 0;
+        return client;
+    }
+    /**
+     * The hello of keeper-terminal (current build) if it is already running, else null. Connects to a running keeper but
+     * NEVER starts one (spec §7: answering tools.info starts no keeper). A "not running" answer is remembered briefly. Null also when
+     * the keeper could not be told within `timeoutMs` (see {@link probe} for callers that must not read that as "not running").
+     */
+    async runningHello(timeoutMs = 300) {
+        const ready = this.hello;
+        if (ready)
+            return ready;
+        const now = Date.now();
+        if (now < this.notRunningUntil || now < this.undecidedUntil)
+            return null;
+        const presence = await this.probe(timeoutMs);
+        if (presence.state === 'unknown')
+            this.undecidedUntil = Date.now() + NOT_RUNNING_TTL_MS;
+        return presence.state === 'running' ? presence.hello : null;
+    }
+    /**
+     * Whether keeper-terminal (this client's generation) runs — `absent` only when that is proven (see {@link KeeperPresence}). Never
+     * starts one. Waits for a real connect and hello up to `timeoutMs`; an answer it could not get in time is `unknown`.
+     */
+    probe(timeoutMs = KEEPER_PROBE_TIMEOUT_MS) {
+        const ready = this.hello;
+        if (ready)
+            return Promise.resolve({ state: 'running', hello: ready });
+        if (Date.now() < this.notRunningUntil)
+            return Promise.resolve({ state: 'absent' });
+        let probing = this.probing.get(timeoutMs);
+        if (!probing) {
+            probing = this.probeOnce(timeoutMs).finally(() => { this.probing.delete(timeoutMs); });
+            this.probing.set(timeoutMs, probing);
+        }
+        return probing;
+    }
+    async probeOnce(timeoutMs) {
+        const absent = () => { this.notRunningUntil = Date.now() + NOT_RUNNING_TTL_MS; return { state: 'absent' }; };
+        let gen;
+        try {
+            gen = this.options.gen
+                ?? keeperGen((await readKeeperManifest(path.join(this.options.distDir ?? defaultDistDir(), 'terminal'))).buildVersion);
+        }
+        catch {
+            return absent();
+        } // no build of the current generation: nothing of it can run
+        const paths = this.options.launcher.pathsFor('terminal', gen);
+        if (this.options.gen === undefined)
+            this.currentGen = paths.gen;
+        try {
+            await fs.access(paths.tokenFile);
+            await fs.access(paths.socket);
+        }
+        catch (error) {
+            return ABSENT_ERRNOS.has(errnoOf(error) ?? '') ? absent() : { state: 'unknown', reason: messageOf(error) };
+        }
+        const client = this.clientFor(paths);
+        let timer;
+        try {
+            const result = await Promise.race([
+                client.connect(),
+                new Promise((resolve) => { timer = setTimeout(() => resolve(null), timeoutMs); timer.unref(); }),
+            ]);
+            if (result === null)
+                return { state: 'unknown', reason: `no answer within ${timeoutMs} ms` };
+            if (result.status === 'ready') {
+                this.notRunningUntil = 0;
+                this.undecidedUntil = 0;
+                return { state: 'running', hello: result.hello };
+            }
+            return { state: 'unknown', reason: `protocol ${result.hello.protocolVersion} is outside the daemon's window` };
+        }
+        catch (error) {
+            // The token or the socket went away meanwhile, or nothing listens behind a stale socket file: the keeper is gone.
+            return ABSENT_ERRNOS.has(errnoOf(error) ?? '') ? absent() : { state: 'unknown', reason: messageOf(error) };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** `tools.info` terminal fields from a running keeper's hello, else from `fallback` (a cached node-pty check). Starts nothing. */
+    async terminalStatus(fallback) {
+        const hello = await this.runningHello();
+        return hello ? terminalStatusOf(hello) : fallback();
+    }
+    /** A failure to reach the keeper (launch, connect, hello) surfaces as {@link KeeperLaunchError}: nothing was sent. */
+    async call(method, params, options = {}) {
+        let client;
+        try {
+            client = await this.ensure();
+        }
+        catch (error) {
+            throw new KeeperLaunchError(error);
+        }
+        return client.request(method, params, options);
+    }
+    create(params) { return this.call('pty.create', params); }
+    attach(params) { return this.call('pty.attach', params); }
+    poll(params) { return this.call('pty.poll', params); }
+    write(params) { return this.call('pty.write', params); }
+    resize(params) { return this.call('pty.resize', params); }
+    takeover(params) { return this.call('pty.takeover', params); }
+    detach(params) { return this.call('pty.detach', params); }
+    close(params) { return this.call('pty.close', params); }
+    list() { return this.call('pty.list', {}); }
+    activity() { return this.call('keeper.activity', {}); }
+    // exec.* (spec §4.2). The daemon decides argv/env/deadline/quotas; the keeper only executes them.
+    execStart(params, options = {}) { return this.call('exec.start', params, options); }
+    execList() { return this.call('exec.list', {}); }
+    /** Descriptor plus the latest checkpoint (blob as given to `execCheckpoint`). */
+    execStatus(execId, options = {}) { return this.call('exec.status', { execId }, options); }
+    execRead(params) { return this.call('exec.read', params); }
+    execKill(params) { return this.call('exec.kill', params); }
+    execCommit(params) { return this.call('exec.commit', params); }
+    execCheckpoint(params) { return this.call('exec.checkpoint', params); }
+    /**
+     * Streams an exec's records from `from` with credit backpressure (kit stream `exec/<execId>`); after a reconnect the kit client
+     * resumes after the last record delivered.
+     */
+    async execSubscribe(execId, handler, options) {
+        return (await this.ensure()).subscribe(execStream(execId), handler, options);
+    }
+    /** Drops the connection (the keeper and its PTYs keep running). */
+    disconnect() { this.client?.close(); this.client = undefined; this.clientGen = undefined; }
+}