@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/project/tsx-module-loader.d.ts

@@ -0,0 +1,7 @@
+import type { TsxModuleLoader } from '@zhin.js/runtime';
+/**
+ * Creates a lazy, namespaced TSX loader for the CLI composition root.
+ * It does not replace Node's native `.ts` handling and is registered only
+ * after the active process loader reports that it cannot load a `.tsx` file.
+ */
+export declare function createTsxModuleLoader(projectRoot: string): TsxModuleLoader;

package/lib/project/tsx-module-loader.js

@@ -0,0 +1,29 @@
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Creates a lazy, namespaced TSX loader for the CLI composition root.
+ * It does not replace Node's native `.ts` handling and is registered only
+ * after the active process loader reports that it cannot load a `.tsx` file.
+ */
+export function createTsxModuleLoader(projectRoot) {
+    const root = resolve(projectRoot);
+    const tsconfigFile = join(root, 'tsconfig.json');
+    let registration;
+    const acquire = () => {
+        registration ??= import('tsx/esm/api').then(({ register }) => register({
+            namespace: `zhin-runtime:${pathToFileURL(root).href}`,
+            tsconfig: existsSync(tsconfigFile) ? tsconfigFile : false,
+        }));
+        return registration;
+    };
+    return Object.freeze({
+        async load(source, parentURL) {
+            return (await acquire()).import(source, parentURL);
+        },
+        async close() {
+            if (registration)
+                await (await registration).unregister();
+        },
+    });
+}

package/lib/project.d.ts

@@ -0,0 +1,7 @@
+/** `@zhin.js/gateway/project` — project files: config file selection, dotenv layers, TSX loading, migrations, Node requirements. */
+export * from './project/config-file.js';
+export * from './project/environment.js';
+export * from './project/instance-declarations.js';
+export * from './project/legacy-config.js';
+export * from './project/node-requirements.js';
+export * from './project/tsx-module-loader.js';

package/lib/project.js

@@ -0,0 +1,7 @@
+/** `@zhin.js/gateway/project` — project files: config file selection, dotenv layers, TSX loading, migrations, Node requirements. */
+export * from './project/config-file.js';
+export * from './project/environment.js';
+export * from './project/instance-declarations.js';
+export * from './project/legacy-config.js';
+export * from './project/node-requirements.js';
+export * from './project/tsx-module-loader.js';

package/lib/server.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@zhin.js/gateway/server` — the gateway HTTP server (ADR 0054 §2 / §3), its composition with
+ * the instance supervisor (`startGateway`), the CLI entry (`runGateway`) and the gateway-owned
+ * Console RPC route. Loads the Node HTTP stack: never import it from the instance.
+ */
+export * from './http/gateway-http-server.js';
+export * from './http/console-rpc.js';
+export * from './http/start-gateway.js';
+export * from './http/gateway-console.js';
+export * from './http/gateway-events.js';
+export * from './http/run-gateway.js';

package/lib/server.js

@@ -0,0 +1,11 @@
+/**
+ * `@zhin.js/gateway/server` — the gateway HTTP server (ADR 0054 §2 / §3), its composition with
+ * the instance supervisor (`startGateway`), the CLI entry (`runGateway`) and the gateway-owned
+ * Console RPC route. Loads the Node HTTP stack: never import it from the instance.
+ */
+export * from './http/gateway-http-server.js';
+export * from './http/console-rpc.js';
+export * from './http/start-gateway.js';
+export * from './http/gateway-console.js';
+export * from './http/gateway-events.js';
+export * from './http/run-gateway.js';

package/lib/supervisor/instance-logs.d.ts

@@ -0,0 +1,39 @@
+import type { Readable } from 'node:stream';
+export type InstanceLogStream = 'stdout' | 'stderr';
+export interface InstanceLogLine {
+    /** Monotonic sequence number, unique per collector. */
+    readonly seq: number;
+    /** Epoch milliseconds when the line was captured. */
+    readonly time: number;
+    readonly stream: InstanceLogStream;
+    readonly line: string;
+}
+export interface InstanceLogOptions {
+    /** Log file path; `false` keeps the ring buffer only. */
+    readonly file?: string | false;
+    /** Rotate once the file would exceed this many bytes. Default 10 MiB. */
+    readonly maxBytes?: number;
+    /** Rotated files kept besides the active one (`.1` … `.N`). Default 5. */
+    readonly maxFiles?: number;
+    /** Ring buffer capacity in lines. Default 1000. */
+    readonly capacity?: number;
+}
+export declare const DEFAULT_INSTANCE_LOG_MAX_BYTES: number;
+export declare const DEFAULT_INSTANCE_LOG_MAX_FILES = 5;
+export declare const DEFAULT_INSTANCE_LOG_CAPACITY = 1000;
+export declare class InstanceLogCollector {
+    #private;
+    constructor(options?: InstanceLogOptions);
+    get file(): string | undefined;
+    /** Captures a child stream until it ends. */
+    attach(stream: Readable, kind: InstanceLogStream): void;
+    /** Appends raw text; complete lines are recorded, the remainder waits for its newline. */
+    write(kind: InstanceLogStream, text: string): void;
+    /** Records an unterminated trailing line (e.g. when the child exits). */
+    flush(kind?: InstanceLogStream): void;
+    /** The newest `limit` lines (all buffered lines by default), oldest first. */
+    tail(limit?: number): readonly InstanceLogLine[];
+    /** Live lines; returns an unsubscribe function. */
+    subscribe(listener: (line: InstanceLogLine) => void): () => void;
+    close(): void;
+}

package/lib/supervisor/instance-logs.js

@@ -0,0 +1,152 @@
+/**
+ * Instance log capture (ADR 0054 §3): the gateway collects the instance's stdout / stderr into an
+ * in-memory ring buffer (for `gateway.instance.logs` and offline viewing) and a size-rotated file
+ * (`.zhin/logs/instance.log`, `.1`, `.2`, …).
+ */
+import { closeSync, existsSync, mkdirSync, openSync, renameSync, rmSync, statSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+export const DEFAULT_INSTANCE_LOG_MAX_BYTES = 10 * 1024 * 1024;
+export const DEFAULT_INSTANCE_LOG_MAX_FILES = 5;
+export const DEFAULT_INSTANCE_LOG_CAPACITY = 1_000;
+/** A line longer than this is split, so a child that never prints a newline cannot grow memory. */
+const MAX_PENDING_LINE = 64 * 1024;
+export class InstanceLogCollector {
+    #file;
+    #maxBytes;
+    #maxFiles;
+    #capacity;
+    #ring = [];
+    #listeners = new Set();
+    #pending = { stdout: '', stderr: '' };
+    #seq = 0;
+    #fd;
+    #size = 0;
+    #closed = false;
+    constructor(options = {}) {
+        this.#file = options.file === false ? undefined : options.file;
+        this.#maxBytes = Math.max(1, options.maxBytes ?? DEFAULT_INSTANCE_LOG_MAX_BYTES);
+        this.#maxFiles = Math.max(0, Math.floor(options.maxFiles ?? DEFAULT_INSTANCE_LOG_MAX_FILES));
+        this.#capacity = Math.max(1, Math.floor(options.capacity ?? DEFAULT_INSTANCE_LOG_CAPACITY));
+    }
+    get file() { return this.#file; }
+    /** Captures a child stream until it ends. */
+    attach(stream, kind) {
+        const decoder = new StringDecoder('utf8');
+        stream.on('data', (chunk) => {
+            this.write(kind, typeof chunk === 'string' ? chunk : decoder.write(chunk));
+        });
+        stream.once('end', () => {
+            const rest = decoder.end();
+            if (rest)
+                this.write(kind, rest);
+            this.flush(kind);
+        });
+    }
+    /** Appends raw text; complete lines are recorded, the remainder waits for its newline. */
+    write(kind, text) {
+        if (this.#closed || text.length === 0)
+            return;
+        let buffer = this.#pending[kind] + text;
+        for (;;) {
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            this.#record(kind, buffer.slice(0, newline).replace(/\r$/u, ''));
+            buffer = buffer.slice(newline + 1);
+        }
+        while (buffer.length > MAX_PENDING_LINE) {
+            this.#record(kind, buffer.slice(0, MAX_PENDING_LINE));
+            buffer = buffer.slice(MAX_PENDING_LINE);
+        }
+        this.#pending[kind] = buffer;
+    }
+    /** Records an unterminated trailing line (e.g. when the child exits). */
+    flush(kind) {
+        for (const stream of kind ? [kind] : ['stdout', 'stderr']) {
+            const rest = this.#pending[stream];
+            this.#pending[stream] = '';
+            if (rest)
+                this.#record(stream, rest);
+        }
+    }
+    /** The newest `limit` lines (all buffered lines by default), oldest first. */
+    tail(limit = this.#capacity) {
+        const count = Math.max(0, Math.min(limit, this.#ring.length));
+        return Object.freeze(this.#ring.slice(this.#ring.length - count));
+    }
+    /** Live lines; returns an unsubscribe function. */
+    subscribe(listener) {
+        this.#listeners.add(listener);
+        return () => { this.#listeners.delete(listener); };
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.flush();
+        this.#closed = true;
+        this.#listeners.clear();
+        this.#closeFile();
+    }
+    #record(stream, line) {
+        const entry = Object.freeze({ seq: ++this.#seq, time: Date.now(), stream, line });
+        this.#ring.push(entry);
+        if (this.#ring.length > this.#capacity)
+            this.#ring.splice(0, this.#ring.length - this.#capacity);
+        this.#append(`${line}\n`);
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(entry);
+            }
+            catch { /* a faulty subscriber must not stop capture */ }
+        }
+    }
+    #append(text) {
+        if (!this.#file)
+            return;
+        try {
+            const bytes = Buffer.byteLength(text);
+            this.#open();
+            if (this.#size > 0 && this.#size + bytes > this.#maxBytes)
+                this.#rotate();
+            this.#open();
+            writeSync(this.#fd, text);
+            this.#size += bytes;
+        }
+        catch {
+            // Disk errors must not take the supervisor down; the ring buffer still has the line.
+            this.#closeFile();
+        }
+    }
+    #open() {
+        if (this.#fd !== undefined || !this.#file)
+            return;
+        mkdirSync(dirname(this.#file), { recursive: true });
+        this.#fd = openSync(this.#file, 'a');
+        this.#size = statSync(this.#file).size;
+    }
+    #rotate() {
+        const file = this.#file;
+        this.#closeFile();
+        if (this.#maxFiles === 0) {
+            rmSync(file, { force: true });
+            return;
+        }
+        rmSync(`${file}.${this.#maxFiles}`, { force: true });
+        for (let index = this.#maxFiles - 1; index >= 1; index -= 1) {
+            if (existsSync(`${file}.${index}`))
+                renameSync(`${file}.${index}`, `${file}.${index + 1}`);
+        }
+        renameSync(file, `${file}.1`);
+    }
+    #closeFile() {
+        if (this.#fd === undefined)
+            return;
+        try {
+            closeSync(this.#fd);
+        }
+        catch { /* already closed */ }
+        this.#fd = undefined;
+        this.#size = 0;
+    }
+}

package/lib/supervisor/instance-supervisor.d.ts

@@ -0,0 +1,140 @@
+import { EventEmitter } from 'node:events';
+import { IpcInstanceTransport, type IpcInstanceTransportOptions, type InstanceReadyPayload, type InstanceRestartRequestPayload } from '@zhin.js/host-http/bridge';
+import { InstanceLogCollector, type InstanceLogLine, type InstanceLogOptions } from './instance-logs.js';
+export type InstanceState = 'stopped' | 'starting' | 'running' | 'stopping' | 'backoff' | 'crashed';
+export type InstanceFailureReason = 'exit' | 'spawn-error' | 'ready-timeout' | 'protocol-mismatch' | 'restart-storm';
+export interface InstanceFailure {
+    readonly reason: InstanceFailureReason;
+    readonly message: string;
+    readonly at: number;
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    /** Last captured log lines before the failure (empty with inherited output). */
+    readonly logTail: readonly string[];
+}
+export interface InstanceStatus {
+    readonly state: InstanceState;
+    readonly pid?: number;
+    /** Epoch ms of the current child's `ready`. */
+    readonly startedAt?: number;
+    /** Runtime generation reported by the instance in `ready`. */
+    readonly generation?: number;
+    /** Protocol version reported by the instance in `ready`. */
+    readonly protocolVersion?: number;
+    readonly lastExitCode: number | null;
+    readonly lastExitSignal: NodeJS.Signals | null;
+    readonly lastFailure?: InstanceFailure;
+    /** Automatic restarts (crash or requested) inside the current storm window. */
+    readonly recentRestarts: number;
+}
+export interface InstanceSpawnSpec {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string;
+    /** Child environment; defaults to `process.env`. {@link INSTANCE_CHILD_ENV} is always set. */
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export interface InstanceRestartPolicy {
+    /** Restart crashed instances automatically. Default true. */
+    readonly onCrash?: boolean;
+    /** Honour `restart-request` from the instance. Default true. */
+    readonly onRequest?: boolean;
+    /** Automatic restarts allowed per window before the instance stays `crashed`. Default 10. */
+    readonly maxRestarts?: number;
+    /** Storm window. Default 60 s. */
+    readonly windowMs?: number;
+    /** Delay before an automatic restart (`backoff` state). Default 3 s. */
+    readonly delayMs?: number;
+}
+export interface InstanceSupervisorOptions {
+    readonly spawn: InstanceSpawnSpec;
+    /** `pipe` captures stdout / stderr into {@link InstanceSupervisor.logs}; `inherit` shares the terminal. */
+    readonly output?: 'pipe' | 'inherit';
+    /**
+     * The child's stdin. `inherit` hands it the supervisor's own stdin (a foreground gateway on a
+     * TTY, so terminal adapters can read input); default `ignore` (background gateways).
+     */
+    readonly input?: 'ignore' | 'inherit';
+    readonly logs?: InstanceLogOptions;
+    /** Time a spawned instance gets to report `ready`; see {@link InstanceSupervisor.setReadyTimeout}. */
+    readonly readyTimeoutMs?: number;
+    /** Budget announced in `shutdown`; SIGTERM follows when the child has not exited after it. */
+    readonly shutdownBudgetMs?: number;
+    /** Time between SIGTERM and SIGKILL. */
+    readonly killGraceMs?: number;
+    readonly restart?: InstanceRestartPolicy;
+    /** Protocol versions this supervisor accepts. Default: only {@link INSTANCE_BRIDGE_PROTOCOL_VERSION}. */
+    readonly acceptedProtocolVersions?: readonly number[];
+    /** HTTP bridge settings of {@link InstanceSupervisor.transport}. */
+    readonly transport?: IpcInstanceTransportOptions;
+}
+export interface InstanceStopOptions {
+    /** Time to wait after `shutdown` before SIGTERM. Default: shutdown budget + 1 s. */
+    readonly timeoutMs?: number;
+    readonly reason?: string;
+    /** Kill immediately with SIGKILL (also escalates a stop already in progress). */
+    readonly force?: boolean;
+}
+export interface InstanceExit {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    /** The exit was requested by the supervisor (stop / restart). */
+    readonly expected: boolean;
+}
+export interface InstanceSupervisorEvents {
+    state: [InstanceStatus];
+    ready: [InstanceReadyPayload];
+    exit: [InstanceExit];
+    'restart-request': [InstanceRestartRequestPayload];
+    failure: [InstanceFailure];
+    log: [InstanceLogLine];
+}
+export declare const DEFAULT_INSTANCE_READY_TIMEOUT_MS = 60000;
+export declare const DEFAULT_INSTANCE_KILL_GRACE_MS = 2000;
+/** Storm guard: 10 automatic restarts per minute, 3 s apart (ADR 0054 §5). */
+export declare const MAX_RESTARTS_PER_WINDOW = 10;
+export declare const RESTART_WINDOW_MS = 60000;
+export declare const RESTART_DELAY_MS = 3000;
+export declare class InstanceProtocolMismatchError extends Error {
+    readonly instanceVersion: number;
+    readonly accepted: readonly number[];
+    readonly code = "ZHIN_INSTANCE_PROTOCOL_MISMATCH";
+    constructor(instanceVersion: number, accepted: readonly number[]);
+}
+export declare class InstanceStartError extends Error {
+    readonly failure: InstanceFailure;
+    readonly code = "ZHIN_INSTANCE_START_FAILED";
+    constructor(failure: InstanceFailure);
+}
+export declare class InstanceSupervisor extends EventEmitter<InstanceSupervisorEvents> {
+    #private;
+    readonly logs: InstanceLogCollector;
+    /**
+     * HTTP / WebSocket bridge to the current instance child (ADR 0054 §2). Stable across
+     * restarts: the gateway's HTTP server forwards through it; it is `ready` while a child that
+     * announced its route table runs.
+     */
+    readonly transport: IpcInstanceTransport;
+    constructor(options: InstanceSupervisorOptions);
+    get state(): InstanceState;
+    status(): InstanceStatus;
+    /**
+     * Starts the instance and resolves on its `ready`. A manual start resets the storm window.
+     * Rejects with {@link InstanceStartError} / {@link InstanceProtocolMismatchError} when this
+     * attempt fails; automatic restarts after a crash still follow the restart policy.
+     */
+    start(): Promise<void>;
+    /** Graceful `shutdown`, then SIGTERM after `timeoutMs`, then SIGKILL after the kill grace. */
+    stop(options?: InstanceStopOptions): Promise<void>;
+    /**
+     * Ready timeout for the next spawns (`gateway.readyTimeout`, re-read by the gateway before each
+     * start, restart and transaction); `undefined` goes back to the constructor option.
+     */
+    setReadyTimeout(ms: number | undefined): void;
+    /** Ready timeout the next spawn uses. */
+    get readyTimeoutMs(): number;
+    /** Manual restart: stop gracefully, then start (not counted by the storm guard). */
+    restart(options?: Omit<InstanceStopOptions, 'force'>): Promise<void>;
+    /** Releases timers and the log file; kills a child that is still running. */
+    dispose(): void;
+}