@x-tech-laboratories/x-libs 0.14.0 → 0.14.1

package/dist/log.js

@@ -1,79 +0,0 @@
-// Logging by scope and level, such as "warn,play:debug", where a mistake in the setting never silences logging.
-const level_order = { critical: 0, error: 1, warn: 2, info: 3, debug: 4 };
-export const levels = Object.keys(level_order);
-const level_aliases = {
-    crit: "critical", critical: "critical",
-    err: "error", error: "error",
-    warn: "warn", warning: "warn",
-    info: "info",
-    debug: "debug", verbose: "debug", trace: "debug",
-};
-export const default_level = "info";
-// ── Parsing ──────────────────────────────────────────────────────────────────
-// A bare level sets the default and "scope:level" one scope; entries it cannot read are skipped.
-export function parse_level_spec(spec, fallback = default_level) {
-    const parsed = { default: fallback, scopes: {} };
-    if (!spec)
-        return parsed;
-    for (const raw_part of spec.split(",")) {
-        const part = raw_part.trim().toLowerCase();
-        if (part === "")
-            continue;
-        // Scopes hold colons of their own, so the level follows the last one.
-        const colon = part.lastIndexOf(":");
-        if (colon === -1) {
-            const level = level_aliases[part];
-            if (level)
-                parsed.default = level;
-            continue;
-        }
-        const scope = part.slice(0, colon).trim();
-        const level = level_aliases[part.slice(colon + 1).trim()];
-        if (!level || scope === "")
-            continue;
-        if (scope === "*")
-            parsed.default = level;
-        else
-            parsed.scopes[scope] = level;
-    }
-    return parsed;
-}
-export function level_for(spec, scope) {
-    return spec.scopes[scope] ?? spec.default;
-}
-export function is_enabled(spec, scope, level) {
-    return level_order[level] <= level_order[level_for(spec, scope)];
-}
-const two_digits = (count) => String(count).padStart(2, "0");
-// A line in fixed columns, such as "10:33:35.123 WARN     play      message {"detail":1}".
-export function format_record(record) {
-    const date = new Date(record.at);
-    const time = `${two_digits(date.getHours())}:${two_digits(date.getMinutes())}:${two_digits(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}`;
-    let line = `${time} ${record.level.toUpperCase().padEnd(8)} ${record.scope.padEnd(9)} ${record.message}`;
-    if (record.data !== undefined) {
-        try {
-            line += ` ${JSON.stringify(record.data)}`;
-        }
-        catch {
-            line += " [unserializable]";
-        }
-    }
-    return line;
-}
-const resolve_spec = (source) => typeof source === "function" ? source() : source;
-export function create_logger(scope, spec, sink) {
-    const emit = (level, message, data) => {
-        if (!is_enabled(resolve_spec(spec), scope, level))
-            return;
-        sink({ at: Date.now(), level, scope, message, data });
-    };
-    return {
-        critical: (message, data) => emit("critical", message, data),
-        error: (message, data) => emit("error", message, data),
-        warn: (message, data) => emit("warn", message, data),
-        info: (message, data) => emit("info", message, data),
-        debug: (message, data) => emit("debug", message, data),
-        enabled: (level) => is_enabled(resolve_spec(spec), scope, level),
-        child: (child_scope) => create_logger(`${scope}:${child_scope}`, spec, sink),
-    };
-}

package/dist/server/agents/agent.d.ts

@@ -1,27 +0,0 @@
-import type { CommandStream } from "../../agent/commands.ts";
-import type { LongRun, LongRunPoll, RunResult } from "../../agent/protocol.ts";
-export type { CommandStream } from "../../agent/commands.ts";
-export type { LongRun, LongRunPoll, LongRunState, RunResult } from "../../agent/protocol.ts";
-export interface AgentRunOptions {
-    timeout_in_seconds: number;
-    stdin?: string | null;
-}
-export interface AgentStreamOptions {
-    stdin?: string | null;
-}
-export declare class AgentError extends Error {
-    readonly unreachable: boolean;
-    constructor(message: string, unreachable?: boolean);
-}
-export declare function ended_stream(stderr: string): CommandStream;
-export interface Agent<Task> {
-    run(task: Task, options: AgentRunOptions): Promise<RunResult>;
-    stream(task: Task, options?: AgentStreamOptions): CommandStream;
-    start(run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
-    poll(run_id: string, offset: number): Promise<LongRunPoll>;
-    attach(run_id: string, offset: number): CommandStream;
-    stop(run_id: string): Promise<LongRun>;
-    forget(run_id: string): Promise<void>;
-    runs(): Promise<LongRun[]>;
-    request(type: string, body?: Record<string, unknown>): Promise<unknown>;
-}

package/dist/server/agents/agent.js

@@ -1,16 +0,0 @@
-// What the server can ask of one host's agent, whether it is connected over a WebSocket or built into the server.
-// ── Imports ──────────────────────────────────────────────────────────────────
-import { Readable } from "node:stream";
-export class AgentError extends Error {
-    // Whether the host never answered, so trying again later may work, rather than answering that it failed.
-    unreachable;
-    constructor(message, unreachable = false) {
-        super(message);
-        this.name = "AgentError";
-        this.unreachable = unreachable;
-    }
-}
-// A stream that has already ended with an error, for a host with no agent or a run that cannot be followed.
-export function ended_stream(stderr) {
-    return { stdout: Readable.from([]), done: Promise.resolve({ exit_code: -1, stderr }), stop: () => { } };
-}

package/dist/server/agents/connection.d.ts

@@ -1,51 +0,0 @@
-import { type AgentApp, type AgentMessage, type AppMessage, type LongRun, type LongRunPoll, type RunResult, type ServerMessage } from "../../agent/protocol.ts";
-import { type Agent, type AgentRunOptions, type AgentStreamOptions, type CommandStream } from "./agent.ts";
-export interface ServerSocket {
-    readonly readyState: number;
-    send(data: string): void;
-    close(code?: number, reason?: string): void;
-    on(event: "message", listener: (data: Buffer | ArrayBuffer | Buffer[], is_binary: boolean) => void): unknown;
-    on(event: "close", listener: () => void): unknown;
-    on(event: "error", listener: (error: Error) => void): unknown;
-}
-export interface ConnectionOptions {
-    window_in_bytes: number;
-    request_timeout_in_milliseconds: number;
-    heartbeat_in_milliseconds: number;
-}
-export type Hello = Omit<Extract<AgentMessage, {
-    type: "hello";
-}>, "signature">;
-export declare class AgentConnection<Task> implements Agent<Task> {
-    readonly host: string;
-    readonly hello: Hello;
-    readonly connected_epoch: number;
-    on_message: ((message: AppMessage) => void) | null;
-    private readonly socket;
-    private readonly app;
-    private readonly options;
-    private readonly pending;
-    private readonly streams;
-    private next_id;
-    private last_heard;
-    private readonly heartbeat;
-    private closed_reason;
-    constructor(socket: ServerSocket, app: AgentApp<Task>, host: string, hello: Hello, options: ConnectionOptions);
-    get is_open(): boolean;
-    run(task: Task, options: AgentRunOptions): Promise<RunResult>;
-    stream(task: Task, options?: AgentStreamOptions): CommandStream;
-    start(run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
-    poll(run_id: string, offset: number): Promise<LongRunPoll>;
-    attach(run_id: string, offset: number): CommandStream;
-    stop(run_id: string): Promise<LongRun>;
-    forget(run_id: string): Promise<void>;
-    runs(): Promise<LongRun[]>;
-    request(type: string, body?: Record<string, unknown>): Promise<unknown>;
-    send(message: ServerMessage<Task> | AppMessage): void;
-    receive(data: Buffer, is_binary: boolean): void;
-    closed(reason: string): void;
-    close(code: number, reason: string): void;
-    private send_request;
-    private open_stream;
-    private beat;
-}

package/dist/server/agents/connection.js

@@ -1,239 +0,0 @@
-// One connected agent, as the server sees it: sends it requests and matches each reply by id, and turns its streamed
-// output back into a readable stream, granting the agent more credit only as the reader takes what has come.
-// ── Imports ──────────────────────────────────────────────────────────────────
-import { Readable } from "node:stream";
-import { decode_chunk, encode_message, is_agent_message, parse_agent_message, } from "../../agent/protocol.js";
-import { AgentError } from "./agent.js";
-const socket_open = 1;
-// A run's reply may come this long after its own timeout, which the agent enforces, before the server gives up.
-const run_reply_slack_in_milliseconds = 30_000;
-// ── Incoming streams ─────────────────────────────────────────────────────────
-// A stream's output arriving from the agent, readable as it comes.
-class IncomingStream {
-    stdout;
-    done;
-    id;
-    connection;
-    window;
-    // Credit the agent still holds: bytes it may send before it hears from us again.
-    outstanding;
-    reader_full = false;
-    result = null;
-    stdout_closed = false;
-    settle;
-    constructor(id, connection, window) {
-        this.id = id;
-        this.connection = connection;
-        this.window = window;
-        this.outstanding = window;
-        this.done = new Promise((resolve) => (this.settle = resolve));
-        this.stdout = new Readable({
-            read: () => {
-                this.reader_full = false;
-                this.grant();
-            },
-            destroy: (error, callback) => {
-                if (this.result === null)
-                    this.connection.send({ type: "cancel", id: this.id });
-                callback(error);
-            },
-        });
-        this.stdout.on("close", () => {
-            this.stdout_closed = true;
-            this.settle_when_done();
-        });
-    }
-    receive(data) {
-        this.outstanding -= data.length;
-        if (this.result !== null || this.stdout.destroyed)
-            return;
-        if (!this.stdout.push(data))
-            this.reader_full = true;
-        this.grant();
-    }
-    end(result) {
-        if (this.result !== null)
-            return;
-        this.result = result;
-        if (!this.stdout.destroyed)
-            this.stdout.push(null);
-        this.settle_when_done();
-    }
-    stop() {
-        this.stdout.destroy();
-    }
-    // Tops the agent's credit back up once half of it has been read.
-    grant() {
-        if (this.reader_full || this.result !== null || this.outstanding > this.window / 2)
-            return;
-        this.connection.send({ type: "credit", id: this.id, bytes: this.window - this.outstanding });
-        this.outstanding = this.window;
-    }
-    settle_when_done() {
-        if (this.result !== null && this.stdout_closed)
-            this.settle(this.result);
-    }
-}
-// ── Connection ───────────────────────────────────────────────────────────────
-export class AgentConnection {
-    host;
-    hello;
-    connected_epoch = Math.floor(Date.now() / 1000);
-    // Takes the app's own messages from the agent that are not replies.
-    on_message = null;
-    socket;
-    app;
-    options;
-    pending = new Map();
-    streams = new Map();
-    next_id = 1;
-    last_heard = Date.now();
-    heartbeat;
-    closed_reason = null;
-    constructor(socket, app, host, hello, options) {
-        this.socket = socket;
-        this.app = app;
-        this.host = host;
-        this.hello = hello;
-        this.options = options;
-        this.heartbeat = setInterval(() => this.beat(), options.heartbeat_in_milliseconds);
-        this.heartbeat.unref();
-    }
-    get is_open() {
-        return this.closed_reason === null;
-    }
-    // ── Agent ────────────────────────────────────────────────────────────────
-    async run(task, options) {
-        try {
-            const timeout = options.timeout_in_seconds * 1000 + run_reply_slack_in_milliseconds;
-            return await this.send_request("run", { task, stdin: options.stdin ?? null, timeout_in_seconds: options.timeout_in_seconds }, timeout);
-        }
-        catch (error) {
-            return { exit_code: -1, stdout: "", stderr: error.message };
-        }
-    }
-    stream(task, options = {}) {
-        return this.open_stream((id, window) => ({ type: "stream", id, task, stdin: options.stdin ?? null, window }));
-    }
-    start(run_id, task, options = {}) {
-        return this.send_request("start", { run_id, task, stdin: options.stdin ?? null });
-    }
-    poll(run_id, offset) {
-        return this.send_request("poll", { run_id, offset });
-    }
-    attach(run_id, offset) {
-        return this.open_stream((id, window) => ({ type: "attach", id, run_id, offset, window }));
-    }
-    stop(run_id) {
-        return this.send_request("stop", { run_id });
-    }
-    async forget(run_id) {
-        await this.send_request("forget", { run_id });
-    }
-    runs() {
-        return this.send_request("runs", {});
-    }
-    request(type, body = {}) {
-        return this.send_request(type, body);
-    }
-    // ── Socket ───────────────────────────────────────────────────────────────
-    send(message) {
-        if (this.is_open && this.socket.readyState === socket_open)
-            this.socket.send(encode_message(message, this.app));
-    }
-    // Handles one frame from the agent after its hello.
-    receive(data, is_binary) {
-        this.last_heard = Date.now();
-        if (is_binary) {
-            const chunk = decode_chunk(data);
-            if (chunk !== null)
-                this.streams.get(chunk.id)?.receive(chunk.data);
-            return;
-        }
-        const message = parse_agent_message(data.toString("utf8"), this.app);
-        if (message === null)
-            return;
-        if (!is_agent_message(message)) {
-            this.on_message?.(message);
-            return;
-        }
-        switch (message.type) {
-            case "ping":
-                this.send({ type: "pong", epoch_ms: message.epoch_ms });
-                return;
-            case "reply":
-            case "failed": {
-                const pending = this.pending.get(message.id);
-                if (pending === undefined)
-                    return;
-                this.pending.delete(message.id);
-                clearTimeout(pending.timer);
-                // The agent answered that the request failed, which is not the host being out of reach.
-                if (message.type === "reply")
-                    pending.resolve(message.value);
-                else
-                    pending.reject(new AgentError(message.error));
-                return;
-            }
-            case "stream_end":
-                this.streams.get(message.id)?.end({ exit_code: message.exit_code, stderr: message.stderr });
-                this.streams.delete(message.id);
-                return;
-            default:
-                return;
-        }
-    }
-    // Fails what was waiting and ends each stream; the agent's long runs carry on.
-    closed(reason) {
-        if (this.closed_reason !== null)
-            return;
-        this.closed_reason = reason;
-        clearInterval(this.heartbeat);
-        for (const pending of this.pending.values()) {
-            clearTimeout(pending.timer);
-            pending.reject(new AgentError(reason, true));
-        }
-        this.pending.clear();
-        for (const stream of this.streams.values())
-            stream.end({ exit_code: -1, stderr: reason });
-        this.streams.clear();
-    }
-    close(code, reason) {
-        this.socket.close(code, reason);
-        this.closed(reason);
-    }
-    // ── Helpers ──────────────────────────────────────────────────────────────
-    send_request(type, body, timeout = this.options.request_timeout_in_milliseconds) {
-        if (!this.is_open)
-            return Promise.reject(new AgentError(this.closed_reason, true));
-        const id = `r${this.next_id++}`;
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                this.pending.delete(id);
-                reject(new AgentError(`The agent on ${this.host} did not answer within ${Math.round(timeout / 1000)}s.`, true));
-            }, timeout);
-            this.pending.set(id, { resolve: resolve, reject, timer });
-            this.send({ ...body, type, id });
-        });
-    }
-    open_stream(message) {
-        const id = `s${this.next_id++}`;
-        const stream = new IncomingStream(id, this, this.options.window_in_bytes);
-        if (!this.is_open) {
-            stream.end({ exit_code: -1, stderr: this.closed_reason });
-        }
-        else {
-            this.streams.set(id, stream);
-            this.send(message(id, this.options.window_in_bytes));
-        }
-        return { stdout: stream.stdout, done: stream.done, stop: () => stream.stop() };
-    }
-    // Pings the agent, or drops one that has been silent for three beats.
-    beat() {
-        if (Date.now() - this.last_heard > 3 * this.options.heartbeat_in_milliseconds) {
-            this.close(4008, `The agent on ${this.host} stopped answering.`);
-            return;
-        }
-        this.send({ type: "ping", epoch_ms: Date.now() });
-    }
-}

package/dist/server/agents/hub.d.ts

@@ -1,86 +0,0 @@
-import { EventEmitter } from "node:events";
-import type { IncomingHttpHeaders } from "node:http";
-import { type AgentApp, type AppMessage, type LongRun, type LongRunPoll, type RunResult } from "../../agent/protocol.ts";
-import { type Agent, type AgentRunOptions, type AgentStreamOptions, type CommandStream } from "./agent.ts";
-import { AgentConnection, type ConnectionOptions, type ServerSocket } from "./connection.ts";
-export interface AgentTokenLookup {
-    host_for(token: string): string | null;
-    seen?(host: string): void;
-}
-export interface HubOptions<Task> {
-    app: AgentApp<Task>;
-    local?: {
-        host: string;
-        agent: Agent<Task>;
-    };
-    tokens?: AgentTokenLookup;
-    on_message?: (host: string, message: AppMessage, connection: AgentConnection<Task>) => void;
-    hello_timeout_in_milliseconds?: number;
-    connection?: Partial<ConnectionOptions>;
-}
-export interface AgentStatus {
-    host: string;
-    reported_host: string;
-    agent_version: string;
-    connected_epoch: number;
-    built_in: boolean;
-    login: AgentLogin | null;
-    runs: LongRun[];
-}
-export type AgentLogin = "token" | "key";
-export type Admission = {
-    host: string;
-    login: AgentLogin;
-} | {
-    error: string;
-};
-interface HubEvents {
-    connect: [status: AgentStatus];
-    disconnect: [host: string];
-}
-export declare const close_codes: {
-    readonly protocol: 4002;
-    readonly replaced: 4003;
-    readonly revoked: 4004;
-    readonly no_hello: 4005;
-    readonly bad_key: 4006;
-};
-export declare class AgentHub<Task> extends EventEmitter<HubEvents> {
-    readonly app: AgentApp<Task>;
-    private readonly local;
-    private readonly tokens;
-    private readonly on_message;
-    private readonly hello_timeout;
-    private readonly connection_options;
-    private readonly connections;
-    private readonly logins;
-    private agent_keys;
-    constructor(options: HubOptions<Task>);
-    set_local_host(host: string): void;
-    set_agent_keys(lines: Map<string, string>): void;
-    has_agent_key(host: string): boolean;
-    declared_hosts(): string[];
-    disconnect_token_login(host: string, reason: string): void;
-    authenticate(authorization: string | undefined): string | null;
-    admit(headers: IncomingHttpHeaders): Admission;
-    accept(socket: ServerSocket, host: string, login: AgentLogin): void;
-    private proves_key;
-    disconnect(host: string, code?: number, reason?: string): void;
-    close(): void;
-    is_connected(host: string): boolean;
-    status(host: string): AgentStatus | null;
-    statuses(): AgentStatus[];
-    agent(host: string): Agent<Task> | null;
-    run(host: string, task: Task, options: AgentRunOptions): Promise<RunResult>;
-    stream(host: string, task: Task, options?: AgentStreamOptions): CommandStream;
-    start(host: string, run_id: string, task: Task, options?: AgentStreamOptions): Promise<LongRun>;
-    poll(host: string, run_id: string, offset: number): Promise<LongRunPoll>;
-    attach(host: string, run_id: string, offset: number): CommandStream;
-    stop(host: string, run_id: string): Promise<LongRun>;
-    forget(host: string, run_id: string): Promise<void>;
-    runs(host: string): Promise<LongRun[]>;
-    request(host: string, type: string, body?: Record<string, unknown>): Promise<unknown>;
-    private require;
-    private status_of;
-}
-export {};