@rome-os/node-core 0.1.0

package/dist/connector.d.ts

@@ -0,0 +1,26 @@
+import { type ActionResponse } from "./actions.js";
+import { connectGateway, type ConnectionStatus } from "./client.js";
+import type { CallerCredential } from "./local.js";
+export interface DeviceConnectorOptions {
+    credential: CallerCredential;
+    connect?: typeof connectGateway;
+    waitMs?: number;
+    onStatus?(status: ConnectionStatus): void;
+}
+export declare class DeviceConnector {
+    private options;
+    private connection?;
+    private initializing?;
+    private status;
+    private stopped;
+    private pending;
+    private ready;
+    constructor(options: DeviceConnectorOptions);
+    getStatus(): ConnectionStatus;
+    private ensure;
+    private initialize;
+    list(): Promise<unknown>;
+    private receive;
+    run(target: string, action: string, args: unknown, waitMs?: number): Promise<ActionResponse>;
+    stop(): void;
+}

package/dist/connector.js

@@ -0,0 +1,155 @@
+import { randomUUID } from "node:crypto";
+import { actionError, isRecord, parseResponse, } from "./actions.js";
+import { connectGateway } from "./client.js";
+import { cloudRequest, CloudError, gatewayConfig } from "./cloud.js";
+import { validId } from "./protocol.js";
+import { createNodeSocket } from "./socket.js";
+export class DeviceConnector {
+    options;
+    connection;
+    initializing;
+    status = "stopped";
+    stopped = false;
+    pending = new Map();
+    ready = new Set();
+    constructor(options) {
+        this.options = options;
+    }
+    getStatus() {
+        return this.status;
+    }
+    async ensure() {
+        if (this.stopped || this.status === "superseded" || this.status === "revoked")
+            throw new Error("connector_stopped");
+        if (this.connection)
+            return;
+        if (this.initializing)
+            return this.initializing;
+        this.initializing = this.initialize();
+        try {
+            await this.initializing;
+        }
+        finally {
+            this.initializing = undefined;
+        }
+    }
+    async initialize() {
+        const { cloudUrl, token } = this.options.credential;
+        const gatewayUrl = await gatewayConfig(cloudUrl, token);
+        if (this.stopped)
+            throw new Error("connector_stopped");
+        this.connection = (this.options.connect ?? connectGateway)({
+            gatewayUrl,
+            deviceToken: token,
+            createSocket: createNodeSocket,
+            beforeConnect: async () => {
+                try {
+                    return await gatewayConfig(cloudUrl, token);
+                }
+                catch (error) {
+                    if (error instanceof CloudError && error.code === "invalid_device_session")
+                        return null;
+                    throw error;
+                }
+            },
+            onMessage: (message) => this.receive(message),
+            onStatus: (status) => {
+                this.status = status;
+                this.options.onStatus?.(status);
+                if (status !== "online") {
+                    for (const pending of this.pending.values())
+                        pending.finish(actionError("unknown_outcome", "The connection was lost. Execution may have occurred. Do not automatically retry."));
+                }
+                for (const wake of this.ready)
+                    wake();
+            },
+        });
+    }
+    async list() {
+        if (this.stopped)
+            throw new Error("connector_stopped");
+        const { cloudUrl, token } = this.options.credential;
+        const body = await cloudRequest(cloudUrl, "/api/account/devices", token);
+        if (!isRecord(body) || !Array.isArray(body.items))
+            throw new CloudError("invalid_response");
+        return { items: body.items };
+    }
+    receive(message) {
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        if ("type" in message) {
+            pending.finish(actionError(message.code, "The Gateway could not forward the request."));
+            return;
+        }
+        if (message.from !== pending.target)
+            return;
+        const response = parseResponse(message.payload);
+        if (response)
+            pending.finish(response);
+    }
+    async run(target, action, args, waitMs = this.options.waitMs ?? 60_000) {
+        if (!validId(target) || !action || action.length > 128)
+            return actionError("invalid_request", "A device ID and action are required.");
+        try {
+            await this.ensure();
+        }
+        catch {
+            return actionError("gateway_unavailable", "The device connection is unavailable.");
+        }
+        if (this.status !== "online")
+            await new Promise((resolve) => {
+                const finish = () => {
+                    clearTimeout(timer);
+                    this.ready.delete(wake);
+                    resolve();
+                };
+                const wake = () => {
+                    if (["online", "revoked", "superseded", "stopped"].includes(this.status))
+                        finish();
+                };
+                const timer = setTimeout(finish, 10_000);
+                this.ready.add(wake);
+                wake();
+            });
+        if (this.status !== "online")
+            return actionError("gateway_unavailable", "The device connection is offline. No operation was sent.");
+        if (this.pending.size >= 128)
+            return actionError("busy", "Too many device requests are pending.");
+        const id = randomUUID();
+        const envelope = {
+            id,
+            to: target,
+            payload: { type: "request", action, args },
+        };
+        try {
+            JSON.stringify(envelope);
+        }
+        catch {
+            return actionError("invalid_request", "Action arguments must be JSON.");
+        }
+        return new Promise((resolve) => {
+            const finish = (response) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve(response);
+            };
+            const timer = setTimeout(() => finish(actionError("unknown_outcome", "The local wait limit was reached. The remote program was not canceled. Do not automatically retry.")), waitMs);
+            this.pending.set(id, { target, finish });
+            if (!this.connection?.send(envelope))
+                finish(actionError("unknown_outcome", "The request could not be submitted reliably. Do not automatically retry."));
+        });
+    }
+    stop() {
+        this.stopped = true;
+        this.status = "stopped";
+        if (this.connection)
+            this.connection.stop();
+        else
+            this.options.onStatus?.("stopped");
+        for (const pending of this.pending.values())
+            pending.finish(actionError("unknown_outcome", "The caller is shutting down. Execution may have occurred."));
+        for (const wake of this.ready)
+            wake();
+    }
+}

package/dist/daemon-client.d.ts

@@ -0,0 +1,37 @@
+import type { DevicesStatus } from "./devices-status.js";
+import { type ActionResponse } from "./actions.js";
+import { type DaemonStatus, type ConnectionEvent } from "./daemon-protocol.js";
+import type { NodeConfig } from "./local.js";
+export { createNodeConfig, nodeConfigFromEnvironment, readOptionalCallerCredential, CallerConfigurationError, type NodeConfig, type CallerCredential, } from "./local.js";
+export { daemonStatus, startDaemon, stopDaemon } from "./daemon-control.js";
+export { DaemonRequestError, DaemonVersionError } from "./daemon-rpc.js";
+export type { DaemonStatus, ConnectionEvent } from "./daemon-protocol.js";
+export type { DevicesStatus, DeviceStatus } from "./devices-status.js";
+export type { ActionResponse } from "./actions.js";
+export declare class DeviceActionError extends Error {
+    readonly response: Extract<ActionResponse, {
+        ok: false;
+    }>;
+    readonly code: string;
+    constructor(response: Extract<ActionResponse, {
+        ok: false;
+    }>);
+}
+export interface DeviceList {
+    items: Array<{
+        id: string;
+        [key: string]: unknown;
+    }>;
+}
+export interface NodeClientOptions {
+    onListenerError?(error: unknown): void;
+}
+export declare function createNodeClient(config: NodeConfig, options?: NodeClientOptions): {
+    getConnectionStatus(): Promise<DaemonStatus | null>;
+    getDevicesStatus(): Promise<DevicesStatus | null>;
+    listDevices(): Promise<DeviceList>;
+    run: (deviceId: string, action: string, args?: unknown) => Promise<ActionResponse>;
+    describe: (deviceId: string) => Promise<ActionResponse>;
+    subscribe(topic: "connection", listener: (event: ConnectionEvent) => void): Promise<() => Promise<void>>;
+    disconnect(): void;
+};

package/dist/daemon-client.js

@@ -0,0 +1,244 @@
+import { actionError, isRecord, parseResponse } from "./actions.js";
+import { validId } from "./protocol.js";
+import { parseDaemonStatus } from "./daemon-protocol.js";
+import { DaemonRequestError, DaemonVersionError, RpcError, } from "./daemon-rpc.js";
+import { ensureDaemon, findDaemon } from "./daemon-control.js";
+export { createNodeConfig, nodeConfigFromEnvironment, readOptionalCallerCredential, CallerConfigurationError, } from "./local.js";
+export { daemonStatus, startDaemon, stopDaemon } from "./daemon-control.js";
+export { DaemonRequestError, DaemonVersionError } from "./daemon-rpc.js";
+export class DeviceActionError extends Error {
+    response;
+    code;
+    constructor(response) {
+        super(response.error.message);
+        this.response = response;
+        this.code = response.error.code;
+    }
+}
+export function createNodeClient(config, options = {}) {
+    let closed = false;
+    let incompatible = false;
+    let connection;
+    let connecting;
+    const lifetime = new AbortController();
+    const observers = new Set();
+    let retry;
+    let attempt = 0;
+    const assertOpen = () => {
+        if (closed)
+            throw new Error("The caller client is closed.");
+    };
+    function emit(event, rpc) {
+        for (const observer of observers) {
+            observer.seen = rpc;
+            try {
+                observer.listener(event);
+            }
+            catch (error) {
+                options.onListenerError?.(error);
+            }
+        }
+    }
+    function scheduleReconnect() {
+        if (closed || incompatible || !observers.size || retry || connection)
+            return;
+        retry = setTimeout(() => {
+            retry = undefined;
+            void connect(false)
+                .catch(() => { })
+                .finally(scheduleReconnect);
+        }, Math.min(5000, 250 * 2 ** Math.min(attempt++, 5)));
+    }
+    async function initialize(start) {
+        let owned;
+        try {
+            const found = await (start
+                ? ensureDaemon(config, lifetime.signal)
+                : findDaemon(config, lifetime.signal));
+            if (!found)
+                return null;
+            const { rpc } = found;
+            owned = rpc;
+            if (closed || !rpc.open) {
+                rpc.close();
+                throw new DaemonRequestError();
+            }
+            connection = rpc;
+            rpc.onNotification = (method, params) => {
+                if (connection !== rpc || closed || method !== "events.connection")
+                    return;
+                const status = parseDaemonStatus(params);
+                if (!status) {
+                    rpc.close();
+                    return;
+                }
+                emit({ transport: "connected", daemon: status }, rpc);
+            };
+            rpc.onClose = () => {
+                if (connection !== rpc)
+                    return;
+                connection = undefined;
+                if (!closed) {
+                    emit({ transport: "disconnected", daemon: null, reason: "connection_lost" });
+                    scheduleReconnect();
+                }
+            };
+            if (observers.size)
+                await rpc.request("events.subscribe", { topic: "connection" }, 5000);
+            attempt = 0;
+            return rpc;
+        }
+        catch (error) {
+            owned?.close();
+            if (error instanceof DaemonVersionError && !closed) {
+                incompatible = true;
+                emit({ transport: "disconnected", daemon: null, reason: "incompatible" });
+            }
+            throw error;
+        }
+    }
+    async function connect(start) {
+        assertOpen();
+        if (incompatible)
+            throw new DaemonVersionError();
+        if (connection?.open && !connecting)
+            return connection;
+        if (connecting) {
+            const result = await connecting;
+            return result || !start ? result : connect(true);
+        }
+        connecting = initialize(start).finally(() => {
+            connecting = undefined;
+        });
+        return connecting;
+    }
+    async function call(method, params) {
+        const rpc = await connect(true);
+        assertOpen();
+        if (!rpc)
+            throw new DaemonRequestError();
+        return rpc.request(method, params);
+    }
+    async function run(deviceId, action, args = {}) {
+        assertOpen();
+        if (!validId(deviceId) || typeof action !== "string" || !action || action.length > 128)
+            return actionError("invalid_request", "A device ID and action are required.");
+        let body;
+        try {
+            body = JSON.parse(JSON.stringify({ deviceId, action, args }));
+        }
+        catch {
+            return actionError("invalid_request", "Action arguments must be JSON.");
+        }
+        try {
+            const response = parseResponse(await call("devices.run", body));
+            return (response ??
+                actionError("unknown_outcome", "The action response was invalid. Do not automatically retry."));
+        }
+        catch (error) {
+            if (error instanceof DaemonRequestError)
+                return actionError(error.code, error.message);
+            if (error instanceof RpcError)
+                return actionError(error.code === -32602 ? "invalid_request" : "gateway_unavailable", error.message);
+            throw error;
+        }
+    }
+    return {
+        async getConnectionStatus() {
+            const rpc = await connect(false);
+            if (!rpc)
+                return null;
+            const status = parseDaemonStatus(await rpc.request("daemon.status", {}, 5000));
+            if (!status)
+                throw new Error("Invalid caller daemon status.");
+            return status;
+        },
+        async getDevicesStatus() {
+            let body;
+            try {
+                const rpc = await connect(false);
+                if (!rpc)
+                    return null;
+                body = await rpc.request("devices.status");
+            }
+            catch (error) {
+                if (error instanceof RpcError && error.code === -32601)
+                    throw new DaemonVersionError();
+                throw error;
+            }
+            if (!isRecord(body) ||
+                !Array.isArray(body.devices) ||
+                typeof body.checkedAt !== "string" ||
+                !["stopped", "connecting", "online", "retrying", "revoked", "superseded"].includes(String(body.connection)) ||
+                !body.devices.every((device) => isRecord(device) &&
+                    typeof device.id === "string" &&
+                    typeof device.name === "string" &&
+                    (device.platform === null || typeof device.platform === "string") &&
+                    ["connected", "not_connected", "unknown", "revoked"].includes(String(device.status))))
+                throw new Error("Invalid devices status response.");
+            return body;
+        },
+        async listDevices() {
+            let body;
+            try {
+                body = await call("devices.list");
+            }
+            catch (error) {
+                if (error instanceof RpcError)
+                    throw new DeviceActionError({
+                        type: "response",
+                        ok: false,
+                        error: { code: "gateway_unavailable", message: error.message },
+                    });
+                throw error;
+            }
+            if (!isRecord(body) ||
+                !Array.isArray(body.items) ||
+                !body.items.every((item) => isRecord(item) && typeof item.id === "string"))
+                throw new Error("Invalid device list response.");
+            return body;
+        },
+        run,
+        describe: (deviceId) => run(deviceId, "system.info"),
+        async subscribe(topic, listener) {
+            assertOpen();
+            if (topic !== "connection")
+                throw new Error("Unknown event topic.");
+            const observer = { listener };
+            observers.add(observer);
+            try {
+                const rpc = await connect(true);
+                if (!rpc)
+                    throw new DaemonRequestError();
+                if (observer.seen !== rpc)
+                    await rpc.request("events.subscribe", { topic }, 5000);
+            }
+            catch (error) {
+                observers.delete(observer);
+                if (!observers.size) {
+                    clearTimeout(retry);
+                    retry = undefined;
+                }
+                throw error;
+            }
+            return async () => {
+                if (!observers.delete(observer) || observers.size)
+                    return;
+                clearTimeout(retry);
+                retry = undefined;
+                if (connection?.open)
+                    await connection.request("events.unsubscribe", { topic }, 5000);
+            };
+        },
+        disconnect() {
+            if (closed)
+                return;
+            closed = true;
+            clearTimeout(retry);
+            observers.clear();
+            lifetime.abort();
+            connection?.close();
+            connection = undefined;
+        },
+    };
+}

package/dist/daemon-control.d.ts

@@ -0,0 +1,13 @@
+import { type DaemonStatus } from "./daemon-protocol.js";
+import { type NodeConfig } from "./local.js";
+export declare function findDaemon(config: NodeConfig, signal?: AbortSignal): Promise<{
+    rpc: import("./daemon-rpc.js").RpcConnection;
+    status: DaemonStatus;
+} | null>;
+export declare function daemonStatus(config: NodeConfig): Promise<DaemonStatus | null>;
+export declare function ensureDaemon(config: NodeConfig, signal?: AbortSignal): Promise<{
+    rpc: import("./daemon-rpc.js").RpcConnection;
+    status: DaemonStatus;
+}>;
+export declare function startDaemon(config: NodeConfig): Promise<DaemonStatus>;
+export declare function stopDaemon(config: NodeConfig): Promise<void>;

package/dist/daemon-control.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { isRecord } from "./actions.js";
+import { DAEMON_PROTOCOL_VERSION } from "./daemon-protocol.js";
+import { connectRpc, DaemonVersionError } from "./daemon-rpc.js";
+import { daemonStatePath, readCallerCredential } from "./local.js";
+import { readPrivateJson } from "./storage.js";
+async function readDaemonState(config) {
+    const value = await readPrivateJson(daemonStatePath(config));
+    if (!isRecord(value) ||
+        typeof value.token !== "string" ||
+        !/^romenode_[A-Za-z0-9_-]{43}$/.test(value.token) ||
+        value.port !== config.port ||
+        typeof value.pid !== "number" ||
+        !Number.isSafeInteger(value.pid) ||
+        value.pid <= 0)
+        return null;
+    return {
+        token: value.token,
+        port: config.port,
+        pid: value.pid,
+        ...(typeof value.protocolVersion === "number"
+            ? { protocolVersion: value.protocolVersion }
+            : {}),
+    };
+}
+async function legacyRequest(state, path) {
+    const response = await fetch(`http://127.0.0.1:${state.port}${path}`, {
+        method: path === "/stop" ? "POST" : "GET",
+        headers: { authorization: `Bearer ${state.token}` },
+        redirect: "error",
+        signal: AbortSignal.timeout(1000),
+    });
+    const value = await response.json();
+    return response.ok && isRecord(value) ? value : null;
+}
+export async function findDaemon(config, signal) {
+    signal?.throwIfAborted();
+    const state = await readDaemonState(config);
+    if (!state)
+        return null;
+    if (state.protocolVersion !== DAEMON_PROTOCOL_VERSION) {
+        const legacy = await legacyRequest(state, "/status").catch(() => null);
+        if (legacy?.pid === state.pid)
+            throw new DaemonVersionError();
+    }
+    try {
+        return await connectRpc(state, signal);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        if (error instanceof DaemonVersionError)
+            throw error;
+        return null;
+    }
+}
+export async function daemonStatus(config) {
+    const found = await findDaemon(config);
+    if (!found)
+        return null;
+    found.rpc.close();
+    return found.status;
+}
+export async function ensureDaemon(config, signal) {
+    const current = await findDaemon(config, signal);
+    if (current)
+        return current;
+    await readCallerCredential(config);
+    signal?.throwIfAborted();
+    let child;
+    let failed = false;
+    let nextLaunch = 0;
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline && !failed) {
+        const current = await findDaemon(config, signal);
+        if (current)
+            return current;
+        signal?.throwIfAborted();
+        if (!child && Date.now() >= nextLaunch && Date.now() < deadline) {
+            const launched = spawn(process.execPath, [fileURLToPath(new URL("../bin/daemon.js", import.meta.url))], {
+                detached: true,
+                stdio: "ignore",
+                windowsHide: true,
+                env: {
+                    ...process.env,
+                    ROME_NODE_CONFIG_DIR: config.directory,
+                    ROME_NODE_DAEMON_PORT: String(config.port),
+                },
+            });
+            child = launched;
+            nextLaunch = Date.now() + 250;
+            launched.once("error", () => {
+                failed = true;
+            });
+            launched.once("exit", () => {
+                if (child === launched)
+                    child = undefined;
+            });
+            launched.unref();
+        }
+        await delay(50, undefined, { signal });
+    }
+    throw new Error("Could not start the caller daemon. Check the configuration directory and daemon port.");
+}
+export async function startDaemon(config) {
+    const { rpc, status } = await ensureDaemon(config);
+    rpc.close();
+    return status;
+}
+export async function stopDaemon(config) {
+    const state = await readDaemonState(config);
+    if (!state)
+        return;
+    if (state.protocolVersion !== DAEMON_PROTOCOL_VERSION) {
+        const legacy = await legacyRequest(state, "/status").catch(() => null);
+        if (legacy?.pid === state.pid) {
+            await legacyRequest(state, "/stop");
+        }
+        else
+            return;
+    }
+    else {
+        const found = await findDaemon(config);
+        if (!found)
+            return;
+        try {
+            await found.rpc.request("daemon.stop", {}, 5000);
+        }
+        finally {
+            found.rpc.close();
+        }
+    }
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
+        const found = await findDaemon(config).catch((error) => {
+            if (error instanceof DaemonVersionError)
+                return "legacy";
+            throw error;
+        });
+        if (!found)
+            return;
+        if (found !== "legacy") {
+            found.rpc.close();
+            if (found.status.pid !== state.pid)
+                return;
+        }
+        await delay(50);
+    }
+    throw new Error("The caller daemon has not stopped yet.");
+}

package/dist/daemon-entry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/daemon-entry.js

@@ -0,0 +1,16 @@
+import { serveDaemon } from "./daemon.js";
+import { nodeConfigFromEnvironment } from "./local.js";
+const controller = new AbortController();
+const stop = () => controller.abort();
+process.once("SIGINT", stop);
+process.once("SIGTERM", stop);
+try {
+    await serveDaemon(nodeConfigFromEnvironment(process.env), controller.signal);
+}
+catch {
+    process.exitCode = 1;
+}
+finally {
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+}

package/dist/daemon-protocol.d.ts

@@ -0,0 +1,16 @@
+import type { ConnectionStatus } from "./client.js";
+export declare const DAEMON_PROTOCOL_VERSION = 2;
+export interface DaemonStatus {
+    pid: number;
+    protocolVersion: number;
+    connection: ConnectionStatus;
+}
+export declare function parseDaemonStatus(value: unknown): DaemonStatus | null;
+export type ConnectionEvent = {
+    transport: "connected";
+    daemon: DaemonStatus;
+} | {
+    transport: "disconnected";
+    daemon: null;
+    reason: "connection_lost" | "incompatible";
+};

package/dist/daemon-protocol.js

@@ -0,0 +1,15 @@
+import { isRecord } from "./actions.js";
+export const DAEMON_PROTOCOL_VERSION = 2;
+export function parseDaemonStatus(value) {
+    if (!isRecord(value) ||
+        !Number.isSafeInteger(value.pid) ||
+        Number(value.pid) <= 0 ||
+        typeof value.protocolVersion !== "number" ||
+        !["stopped", "connecting", "online", "retrying", "revoked", "superseded"].includes(String(value.connection)))
+        return null;
+    return {
+        pid: value.pid,
+        protocolVersion: value.protocolVersion,
+        connection: value.connection,
+    };
+}