@rome-os/node-core 0.1.1 → 0.1.3

package/README.md

@@ -27,6 +27,18 @@ const result = await client.run("device-id", "exec", {
   args: ["status"],
   cwd: "/workspace",
 });
+const { response, body } = await client.runBinary(
+  "device-id",
+  "exec",
+  { command: "gzip", args: ["-c"] },
+  input,
+);
+const copied = await client.copy({
+  direction: "push",
+  localPath: "/data/video.mp4",
+  deviceId: "device-id",
+  remotePath: "/tmp/video.mp4",
+});
 client.disconnect();
 ```
 
@@ -36,6 +48,27 @@ Gateway connection. `connection` describes the caller connection to Gateway,
 not the online state of remote devices. `listDevices()` returns authorized
 devices without asserting that they are online.
 
+`runBinary(deviceId, action, args?, body?)` resolves to `{ response, body }`.
+It sends `body` as input bytes in a binary frame. For `exec`, the input is the
+program's stdin and the reply `body` is its raw stdout. Neither side is JSON or
+base64 encoded. `response` is the same `ActionResponse` as `run()`, and the exec
+result has no `stdout` field. Failures have an empty `body`. The device ID must
+be a UUID. The request must fit in one 32 MiB Gateway frame, header and meta
+included. Larger input fails with `message_too_large` before anything is sent.
+Output that cannot fit fails with `output_too_large` after the program ran.
+A host version without binary frame support
+does not reply, and the call returns `unknown_outcome` after the wait limit.
+See [binary frames](../../docs/rome-node.md#binary-frames).
+
+`copy({ direction, localPath, deviceId, remotePath }, { onProgress? })` copies
+one file between the daemon's computer and a device. `direction` is `push` or
+`pull`, and `localPath` must be absolute. It resolves to `{ bytes, ms, sha256 }`
+after both sides verified the size and checksum. It throws `DeviceActionError`
+otherwise, and the destination stays unchanged. `onProgress` receives
+`{ bytes, total }` about four times per second. The copy has no total time limit
+and aborts after 60 seconds without progress or when the client disconnects.
+See [copying files](../../docs/rome-node.md#copying-files).
+
 `getDevicesStatus()` checks device reachability through read-only `system.info`
 requests through an existing daemon and returns `{ connection, checkedAt, devices }`.
 It returns `null` when no daemon runs and never starts or restarts one. Each device has
@@ -88,6 +121,30 @@ same environment to `nodeConfigFromEnvironment()` as the CLI to honor
 `ROME_NODE_CONFIG_DIR`, `ROME_NODE_DAEMON_PORT`, and platform defaults.
 The library does not select an environment implicitly.
 
+## Activity console
+
+The daemon records the actions it sends in `observe.db`. Read them with
+`node.status`, `log.query`, `log.stats`, and the `node` event topic of the
+[local protocol](../../docs/rome-node.md#activity-log).
+
+A backend that serves a browser console puts `openConsoleBridge` between the
+browser socket and the daemon:
+
+```ts
+import { nodeConfigFromEnvironment, openConsoleBridge } from "@rome-os/node-core/client";
+
+const bridge = openConsoleBridge(nodeConfigFromEnvironment(process.env), {
+  send: (text) => socket.send(text),
+  close: () => socket.close(),
+});
+socket.on("message", (data) => bridge.receive(data.toString()));
+socket.on("close", () => bridge.close());
+```
+
+The bridge never starts the daemon. It forwards only the observation methods.
+When no daemon answers, it sends `console.daemon` with state `not_configured`,
+`not_running`, `incompatible`, or `disconnected`, then closes.
+
 ## Caller authorization
 
 ```ts
@@ -144,7 +201,8 @@ where `expiresIn` is in seconds. It returns a `DeviceSession` after approval and
 rejects on denial, expiry, cancellation, or a terminal error. It opens no browser
 or callback listener. The callback receives neither the device code nor the access token.
 
-The host exposes `system.info` and `exec`. Programs run as the application's OS
+The host exposes `system.info` and `exec`, in text envelopes and in binary frames.
+It also accepts the internal file transfers that `copy()` uses. Programs run as the application's OS
 user. Connection loss terminates direct child processes on a best-effort basis.
 A local caller timeout does not cancel remote execution.
 

package/dist/actions.d.ts

@@ -15,6 +15,10 @@ export type ActionResponse = {
         message: string;
     };
 };
+export interface BinaryActionResult {
+    response: ActionResponse;
+    body: Uint8Array;
+}
 export declare function actionError(code: string, message: string): ActionResponse;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function parseResponse(value: unknown): ActionResponse | null;

package/dist/client.d.ts

@@ -1,7 +1,8 @@
+import { type Frame } from "./frame.js";
 import { type GatewayMessage, type OutboundEnvelope } from "./protocol.js";
 export interface ClientSocket {
     readyState: number;
-    send(data: string): void;
+    send(data: string | Uint8Array): void;
     close(code?: number, reason?: string): void;
     addEventListener(type: "open", listener: () => void): void;
     addEventListener(type: "message", listener: (event: {
@@ -18,11 +19,13 @@ export interface GatewayClientOptions {
     deviceToken: string;
     createSocket(url: string, authorization: string): ClientSocket;
     onMessage(message: GatewayMessage): void;
+    onFrame?(frame: Frame): void;
     onStatus?(status: ConnectionStatus): void;
     random?(): number;
     beforeConnect?(): Promise<string | null>;
 }
 export declare function connectGateway(options: GatewayClientOptions): {
     send(envelope: OutboundEnvelope): boolean;
+    sendFrame(frame: Frame): boolean;
     stop(): void;
 };

package/dist/client.js

@@ -1,3 +1,4 @@
+import { encodeFrame, FRAME_TYPE, frameFits, isUuid, parseFrame } from "./frame.js";
 import { parseGatewayUrl } from "./gateway-url.js";
 import { CLOSE, gatewayMessage, outboundEnvelope, } from "./protocol.js";
 export function connectGateway(options) {
@@ -76,8 +77,19 @@ export function connectGateway(options) {
             status("online");
         });
         current.addEventListener("message", ({ data }) => {
-            if (stopped || socket !== current || typeof data !== "string")
+            if (stopped || socket !== current)
                 return;
+            if (typeof data !== "string") {
+                const bytes = data instanceof Uint8Array
+                    ? data
+                    : data instanceof ArrayBuffer
+                        ? new Uint8Array(data)
+                        : null;
+                const frame = bytes && parseFrame(bytes);
+                if (frame)
+                    options.onFrame?.(frame);
+                return;
+            }
             let message;
             try {
                 message = gatewayMessage(JSON.parse(data));
@@ -116,6 +128,23 @@ export function connectGateway(options) {
                 return false;
             }
         },
+        sendFrame(frame) {
+            if (stopped || !socket || socket.readyState !== 1)
+                return false;
+            if (!frameFits(frame.meta.byteLength, frame.body.byteLength))
+                return false;
+            if (frame.type !== FRAME_TYPE.request && frame.type !== FRAME_TYPE.response)
+                return false;
+            if (!isUuid(frame.id) || !isUuid(frame.peer))
+                return false;
+            try {
+                socket.send(encodeFrame(frame));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
         stop() {
             stopped = true;
             clearTimeout(timer);

package/dist/connect.js

@@ -59,9 +59,7 @@ export async function connectHost(options) {
     const active = session;
     options.onEvent?.({ type: "device", name: active.name, deviceId: active.deviceId });
     await new Promise((resolve, reject) => {
-        const executor = createExecutor(active.name, (message) => connection.send(message), [
-            active.token,
-        ]);
+        const executor = createExecutor(active.name, (message) => connection.send(message), [active.token], (frame) => connection.sendFrame(frame));
         let finished = false;
         const finish = (error) => {
             if (finished)
@@ -94,6 +92,7 @@ export async function connectHost(options) {
                 if ("from" in message)
                     void executor.receive(message);
             },
+            onFrame: (frame) => void executor.receiveFrame(frame),
             onStatus: (status) => {
                 options.onEvent?.({ type: "connection", status });
                 if (status !== "online" && status !== "connecting")

package/dist/connector.d.ts

@@ -1,6 +1,7 @@
-import { type ActionResponse } from "./actions.js";
+import { type ActionResponse, type BinaryActionResult } from "./actions.js";
 import { connectGateway, type ConnectionStatus } from "./client.js";
 import type { CallerCredential } from "./local.js";
+import type { ChannelEvents, TransferChannel } from "./transfer.js";
 export interface DeviceConnectorOptions {
     credential: CallerCredential;
     connect?: typeof connectGateway;
@@ -15,12 +16,20 @@ export declare class DeviceConnector {
     private stopped;
     private pending;
     private ready;
+    private channels;
     constructor(options: DeviceConnectorOptions);
     getStatus(): ConnectionStatus;
     private ensure;
     private initialize;
     list(): Promise<unknown>;
     private receive;
+    private receiveFrame;
+    private admit;
+    private full;
     run(target: string, action: string, args: unknown, waitMs?: number): Promise<ActionResponse>;
+    runBinary(target: string, action: string, args: unknown, body: Uint8Array, waitMs?: number): Promise<BinaryActionResult>;
+    openChannel(target: string, events: ChannelEvents): Promise<(TransferChannel & {
+        id: string;
+    }) | ActionResponse>;
     stop(): void;
 }

package/dist/connector.js

@@ -2,8 +2,10 @@ 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 { decodeMeta, encodeMeta, FRAME_TYPE, frameFits, isUuid, MAX_FRAME_BYTES, } from "./frame.js";
 import { validId } from "./protocol.js";
 import { createNodeSocket } from "./socket.js";
+const MAX_PENDING = 128;
 export class DeviceConnector {
     options;
     connection;
@@ -12,6 +14,7 @@ export class DeviceConnector {
     stopped = false;
     pending = new Map();
     ready = new Set();
+    channels = new Map();
     constructor(options) {
         this.options = options;
     }
@@ -53,12 +56,15 @@ export class DeviceConnector {
                 }
             },
             onMessage: (message) => this.receive(message),
+            onFrame: (frame) => this.receiveFrame(frame),
             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 channel of [...this.channels.values()])
+                        channel.events.lost();
                 }
                 for (const wake of this.ready)
                     wake();
@@ -76,7 +82,7 @@ export class DeviceConnector {
     }
     receive(message) {
         const pending = this.pending.get(message.id);
-        if (!pending)
+        if (!pending || pending.binary)
             return;
         if ("type" in message) {
             pending.finish(actionError(message.code, "The Gateway could not forward the request."));
@@ -88,9 +94,34 @@ export class DeviceConnector {
         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.");
+    receiveFrame(frame) {
+        const channel = this.channels.get(frame.id);
+        if (channel) {
+            if (frame.peer !== channel.target)
+                return;
+            if (frame.type === FRAME_TYPE.response)
+                channel.events.frame(decodeMeta(frame.meta), frame.body);
+            else if (frame.type === FRAME_TYPE.routeError) {
+                const meta = decodeMeta(frame.meta);
+                channel.events.frame(actionError(isRecord(meta) && typeof meta.code === "string" ? meta.code : "target_unavailable", "The Gateway could not forward the request."), new Uint8Array());
+            }
+            return;
+        }
+        const pending = this.pending.get(frame.id);
+        if (!pending?.binary || frame.peer !== pending.target)
+            return;
+        if (frame.type === FRAME_TYPE.routeError) {
+            const meta = decodeMeta(frame.meta);
+            pending.finish(actionError(isRecord(meta) && typeof meta.code === "string" ? meta.code : "target_unavailable", "The Gateway could not forward the request."));
+            return;
+        }
+        if (frame.type !== FRAME_TYPE.response)
+            return;
+        const response = parseResponse(decodeMeta(frame.meta));
+        if (response)
+            pending.finish(response, frame.body);
+    }
+    async admit() {
         try {
             await this.ensure();
         }
@@ -114,8 +145,19 @@ export class DeviceConnector {
             });
         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.");
+        return null;
+    }
+    full() {
+        return this.pending.size + this.channels.size >= MAX_PENDING
+            ? actionError("busy", "Too many device requests are pending.")
+            : null;
+    }
+    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.");
+        const refused = await this.admit();
+        if (refused)
+            return refused;
         const id = randomUUID();
         const envelope = {
             id,
@@ -128,6 +170,9 @@ export class DeviceConnector {
         catch {
             return actionError("invalid_request", "Action arguments must be JSON.");
         }
+        const busy = this.full();
+        if (busy)
+            return busy;
         return new Promise((resolve) => {
             const finish = (response) => {
                 clearTimeout(timer);
@@ -135,11 +180,88 @@ export class DeviceConnector {
                 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 });
+            this.pending.set(id, { target, binary: false, finish });
             if (!this.connection?.send(envelope))
                 finish(actionError("unknown_outcome", "The request could not be submitted reliably. Do not automatically retry."));
         });
     }
+    async runBinary(target, action, args, body, waitMs = this.options.waitMs ?? 60_000) {
+        const empty = new Uint8Array();
+        if (!isUuid(target) || !action || action.length > 128)
+            return {
+                response: actionError("invalid_request", "A device UUID and action are required."),
+                body: empty,
+            };
+        let meta;
+        try {
+            meta = encodeMeta({ type: "request", action, args });
+        }
+        catch {
+            return {
+                response: actionError("invalid_request", "Action arguments must be JSON."),
+                body: empty,
+            };
+        }
+        if (!frameFits(meta.byteLength, body.byteLength))
+            return {
+                response: actionError("message_too_large", `The input does not fit in one ${MAX_FRAME_BYTES / 1024 / 1024} MiB frame. Nothing was sent. Use rome-node cp for large files.`),
+                body: empty,
+            };
+        const refused = await this.admit();
+        if (refused)
+            return { response: refused, body: empty };
+        const busy = this.full();
+        if (busy)
+            return { response: busy, body: empty };
+        const id = randomUUID();
+        const peer = target.toLowerCase();
+        return new Promise((resolve) => {
+            const finish = (response, output = empty) => {
+                clearTimeout(timer);
+                this.pending.delete(id);
+                resolve({ response, body: response.ok ? output : empty });
+            };
+            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: peer, binary: true, finish });
+            if (!this.connection?.sendFrame({ type: FRAME_TYPE.request, id, peer, meta, body }))
+                finish(actionError("unknown_outcome", "The request could not be submitted reliably. Do not automatically retry."));
+        });
+    }
+    async openChannel(target, events) {
+        if (!isUuid(target))
+            return actionError("invalid_request", "A device UUID is required.");
+        const refused = await this.admit();
+        if (refused)
+            return refused;
+        const busy = this.full();
+        if (busy)
+            return busy;
+        const id = randomUUID();
+        const peer = target.toLowerCase();
+        this.channels.set(id, { target: peer, events });
+        return {
+            id,
+            send: (meta, body = new Uint8Array()) => {
+                if (!this.channels.has(id))
+                    return false;
+                try {
+                    return (this.connection?.sendFrame({
+                        type: FRAME_TYPE.request,
+                        id,
+                        peer,
+                        meta: encodeMeta(meta),
+                        body,
+                    }) ?? false);
+                }
+                catch {
+                    return false;
+                }
+            },
+            close: () => {
+                this.channels.delete(id);
+            },
+        };
+    }
     stop() {
         this.stopped = true;
         this.status = "stopped";

package/dist/console.d.ts

@@ -0,0 +1,12 @@
+import { type NodeConfig } from "./local.js";
+export declare const MAX_CONSOLE_MESSAGE_BYTES: number;
+export type ConsoleDaemonState = "not_configured" | "not_running" | "incompatible" | "disconnected";
+export interface ConsoleTransport {
+    send(text: string): void;
+    close(): void;
+}
+export interface ConsoleBridge {
+    receive(text: string): void;
+    close(): void;
+}
+export declare function openConsoleBridge(config: NodeConfig, transport: ConsoleTransport): ConsoleBridge;

package/dist/console.js

@@ -0,0 +1,101 @@
+import { isRecord } from "./actions.js";
+import { findDaemon } from "./daemon-control.js";
+import { DaemonVersionError, RpcError } from "./daemon-rpc.js";
+import { readOptionalCallerCredential } from "./local.js";
+export const MAX_CONSOLE_MESSAGE_BYTES = 64 * 1024;
+const READ_METHODS = new Set(["node.status", "log.query", "log.stats"]);
+export function openConsoleBridge(config, transport) {
+    let closed = false;
+    let rpc;
+    const queued = [];
+    const lifetime = new AbortController();
+    const finish = (state) => {
+        if (closed)
+            return;
+        closed = true;
+        lifetime.abort();
+        if (state)
+            transport.send(JSON.stringify({ jsonrpc: "2.0", method: "console.daemon", params: { state } }));
+        rpc?.close();
+        transport.close();
+    };
+    const reply = (id, body) => {
+        if (!closed)
+            transport.send(JSON.stringify({ jsonrpc: "2.0", id, ...body }));
+    };
+    function forward(text) {
+        let message;
+        try {
+            message = JSON.parse(text);
+        }
+        catch {
+            reply(null, { error: { code: -32700, message: "Parse error" } });
+            return;
+        }
+        if (!isRecord(message) ||
+            message.jsonrpc !== "2.0" ||
+            typeof message.method !== "string" ||
+            (typeof message.id !== "string" && typeof message.id !== "number")) {
+            reply(null, { error: { code: -32600, message: "Invalid Request" } });
+            return;
+        }
+        const { id, method } = message;
+        const params = message.params ?? {};
+        const allowed = READ_METHODS.has(method) ||
+            ((method === "events.subscribe" || method === "events.unsubscribe") &&
+                isRecord(params) &&
+                params.topic === "node");
+        if (!allowed) {
+            reply(id, { error: { code: -32601, message: "Method not found" } });
+            return;
+        }
+        rpc.request(method, params, 15_000).then((result) => reply(id, { result }), (error) => reply(id, {
+            error: error instanceof RpcError
+                ? { code: error.code, message: error.message }
+                : { code: -32000, message: "The rome-node daemon did not answer." },
+        }));
+    }
+    void (async () => {
+        try {
+            const found = await findDaemon(config, lifetime.signal);
+            if (closed) {
+                found?.rpc.close();
+                return;
+            }
+            if (!found) {
+                finish((await readOptionalCallerCredential(config)) ? "not_running" : "not_configured");
+                return;
+            }
+            rpc = found.rpc;
+            rpc.onNotification = (method, params) => {
+                if (method === "events.node" && !closed)
+                    transport.send(JSON.stringify({ jsonrpc: "2.0", method, params }));
+            };
+            rpc.onClose = () => finish("disconnected");
+            for (const text of queued.splice(0))
+                forward(text);
+        }
+        catch (error) {
+            if (closed)
+                return;
+            finish(error instanceof DaemonVersionError ? "incompatible" : "not_running");
+        }
+    })();
+    return {
+        receive(text) {
+            if (closed)
+                return;
+            if (Buffer.byteLength(text) > MAX_CONSOLE_MESSAGE_BYTES) {
+                finish();
+                return;
+            }
+            if (rpc)
+                forward(text);
+            else if (queued.length < 16)
+                queued.push(text);
+            else
+                finish();
+        },
+        close: () => finish(),
+    };
+}

package/dist/daemon-client.d.ts

@@ -1,13 +1,15 @@
 import type { DevicesStatus } from "./devices-status.js";
-import { type ActionResponse } from "./actions.js";
-import { type DaemonStatus, type ConnectionEvent } from "./daemon-protocol.js";
+import { type ActionResponse, type BinaryActionResult } from "./actions.js";
+import { type DaemonStatus, type ConnectionEvent, type CopyProgress, type CopyRequest, type CopySummary } 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 { DaemonStatus, ConnectionEvent, CopyProgress, CopyRequest, CopySummary, } from "./daemon-protocol.js";
 export type { DevicesStatus, DeviceStatus } from "./devices-status.js";
-export type { ActionResponse } from "./actions.js";
+export { openConsoleBridge, MAX_CONSOLE_MESSAGE_BYTES, type ConsoleBridge, type ConsoleDaemonState, type ConsoleTransport, } from "./console.js";
+export type { ActionRow, LogQuery, LogResult, NodeEvent, NodeStatus, Outcome, RoleStatus, } from "./observe-protocol.js";
+export type { ActionResponse, BinaryActionResult } from "./actions.js";
 export declare class DeviceActionError extends Error {
     readonly response: Extract<ActionResponse, {
         ok: false;
@@ -31,6 +33,10 @@ export declare function createNodeClient(config: NodeConfig, options?: NodeClien
     getDevicesStatus(): Promise<DevicesStatus | null>;
     listDevices(): Promise<DeviceList>;
     run: (deviceId: string, action: string, args?: unknown) => Promise<ActionResponse>;
+    runBinary: (deviceId: string, action: string, args?: unknown, body?: Uint8Array) => Promise<BinaryActionResult>;
+    copy: (request: CopyRequest, options?: {
+        onProgress?(progress: CopyProgress): void;
+    }) => Promise<CopySummary>;
     describe: (deviceId: string) => Promise<ActionResponse>;
     subscribe(topic: "connection", listener: (event: ConnectionEvent) => void): Promise<() => Promise<void>>;
     disconnect(): void;