@rome-os/node-core 0.1.0 → 0.1.2

package/dist/transfer.js

@@ -0,0 +1,518 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { open, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { actionError, isRecord, parseResponse } from "./actions.js";
+import { FRAME_HEADER_BYTES, MAX_FRAME_BYTES } from "./frame.js";
+export const TRANSFER_VERSION = 1;
+export const TRANSFER_CHUNK_BYTES = 4 * 1024 * 1024;
+export const TRANSFER_WINDOW_BYTES = 16 * 1024 * 1024;
+export const TRANSFER_IDLE_MS = 60_000;
+export const MAX_HOST_TRANSFERS = 4;
+export const PART_SUFFIX = ".rome-part";
+const isSize = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const isDigest = (value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+export function parseTransferMessage(value) {
+    if (!isRecord(value) || value.type !== "transfer")
+        return null;
+    switch (value.kind) {
+        case "data":
+        case "ack":
+            return isSize(value.offset)
+                ? { type: "transfer", kind: value.kind, offset: value.offset }
+                : null;
+        case "end":
+        case "done":
+            return isSize(value.size) && isDigest(value.sha256)
+                ? { type: "transfer", kind: value.kind, size: value.size, sha256: value.sha256 }
+                : null;
+        case "abort":
+            return typeof value.code === "string" && typeof value.message === "string"
+                ? { type: "transfer", kind: "abort", code: value.code, message: value.message }
+                : null;
+        default:
+            return null;
+    }
+}
+export class TransferError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function fsError(error) {
+    const code = error?.code;
+    return new TransferError(code === "ENOENT"
+        ? "not_found"
+        : code === "EACCES" || code === "EPERM"
+            ? "permission_denied"
+            : code === "EISDIR"
+                ? "is_directory"
+                : "io_error", error instanceof Error ? error.message : "The file operation failed.");
+}
+const closed = (stream) => stream.closed
+    ? Promise.resolve()
+    : new Promise((resolve) => {
+        stream.once("close", () => resolve());
+        stream.destroy();
+    });
+function lifecycle(send, idleMs, cleanup) {
+    let settled = false;
+    let timer;
+    let resolve;
+    let reject;
+    const result = new Promise((done, fail) => {
+        resolve = done;
+        reject = fail;
+    });
+    result.catch(() => { });
+    const abort = (code, message, notify = true) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (notify)
+            send({ type: "transfer", kind: "abort", code, message });
+        void cleanup()
+            .catch(() => { })
+            .finally(() => reject(new TransferError(code, message)));
+    };
+    const touch = () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => abort("timeout", `No transfer progress for ${idleMs / 1000} seconds.`), idleMs);
+        timer.unref();
+    };
+    return {
+        result,
+        abort,
+        touch,
+        finish(summary) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(summary);
+        },
+        get settled() {
+            return settled;
+        },
+    };
+}
+const notAFile = (path) => new TransferError("not_a_file", `${path} is not a regular file.`);
+export async function openSource(path) {
+    const info = await stat(path).catch((error) => {
+        throw fsError(error);
+    });
+    if (!info.isFile())
+        throw notAFile(path);
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    }
+    catch (error) {
+        throw fsError(error);
+    }
+    let size;
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile())
+            throw notAFile(path);
+        size = opened.size;
+    }
+    catch (error) {
+        await handle.close().catch(() => { });
+        throw error instanceof TransferError ? error : fsError(error);
+    }
+    let started = false;
+    return {
+        size,
+        start(send, options) {
+            started = true;
+            return startSender(handle, send, options);
+        },
+        async close() {
+            if (!started)
+                await handle.close().catch(() => { });
+        },
+    };
+}
+function startSender(handle, send, options = {}) {
+    const chunkBytes = options.chunkBytes ?? TRANSFER_CHUNK_BYTES;
+    const windowBytes = options.windowBytes ?? TRANSFER_WINDOW_BYTES;
+    if (windowBytes < chunkBytes)
+        throw new RangeError("The window must hold at least one chunk.");
+    if (chunkBytes > MAX_FRAME_BYTES - FRAME_HEADER_BYTES - 1024)
+        throw new RangeError("A chunk must fit in one frame.");
+    const stream = handle.createReadStream({ highWaterMark: chunkBytes });
+    const hash = createHash("sha256");
+    let sent = 0;
+    let acked = 0;
+    let sha256;
+    const life = lifecycle(send, options.idleMs ?? TRANSFER_IDLE_MS, () => closed(stream));
+    const full = () => sent - acked + chunkBytes > windowBytes;
+    const lost = () => life.abort("connection_lost", "The device connection was lost. Run the copy again.", false);
+    stream.on("data", (chunk) => {
+        if (life.settled)
+            return;
+        const bytes = chunk;
+        hash.update(bytes);
+        if (!send({ type: "transfer", kind: "data", offset: sent }, bytes))
+            return lost();
+        sent += bytes.byteLength;
+        life.touch();
+        if (full())
+            stream.pause();
+    });
+    stream.once("end", () => {
+        if (life.settled)
+            return;
+        sha256 = hash.digest("hex");
+        if (!send({ type: "transfer", kind: "end", size: sent, sha256 }))
+            return lost();
+        life.touch();
+    });
+    stream.once("error", (error) => life.abort("read_failed", error.message));
+    life.touch();
+    return {
+        result: life.result,
+        abort: life.abort,
+        receive(message) {
+            if (life.settled)
+                return;
+            if (message.kind === "ack") {
+                if (message.offset <= acked || message.offset > sent)
+                    return;
+                acked = message.offset;
+                life.touch();
+                options.onProgress?.(acked);
+                if (stream.isPaused() && !full())
+                    stream.resume();
+            }
+            else if (message.kind === "done") {
+                if (sha256 === undefined || message.size !== sent || message.sha256 !== sha256)
+                    life.abort("checksum_mismatch", "The receiver reported a different size or checksum.");
+                else
+                    life.finish({ size: sent, sha256 });
+            }
+            else if (message.kind === "abort")
+                life.abort(message.code, message.message, false);
+        },
+    };
+}
+export async function createPartFile(path, id = randomUUID()) {
+    const name = Buffer.from(basename(path)).subarray(0, 160).toString("utf8");
+    const part = join(dirname(path), `.${name}.${id}${PART_SUFFIX}`);
+    try {
+        return { part, handle: await open(part, "wx", 0o600) };
+    }
+    catch (error) {
+        throw fsError(error);
+    }
+}
+export async function openDestination(path) {
+    const existing = await stat(path).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw fsError(error);
+    });
+    if (existing?.isDirectory())
+        throw new TransferError("is_directory", `${path} is a directory.`);
+    const { part, handle } = await createPartFile(path);
+    let started = false;
+    return {
+        part,
+        start(send, options) {
+            started = true;
+            return startReceiver(handle, path, part, send, options);
+        },
+        async cancel() {
+            if (started)
+                return;
+            await handle.close().catch(() => { });
+            await rm(part, { force: true });
+        },
+    };
+}
+async function finalMode(path) {
+    const current = await stat(path).catch(() => null);
+    if (current)
+        return current.mode & 0o777;
+    const probe = join(dirname(path), `.${randomUUID()}.rome-mode`);
+    const handle = await open(probe, "wx");
+    try {
+        return (await handle.stat()).mode & 0o777;
+    }
+    finally {
+        await handle.close();
+        await rm(probe, { force: true });
+    }
+}
+function startReceiver(handle, path, part, send, options = {}) {
+    const stream = handle.createWriteStream({ flush: true });
+    const hash = createHash("sha256");
+    let expected = options.size;
+    let received = 0;
+    let written = 0;
+    let ending = false;
+    const life = lifecycle(send, options.idleMs ?? TRANSFER_IDLE_MS, async () => {
+        await closed(stream);
+        await rm(part, { force: true });
+    });
+    stream.on("error", (error) => life.abort("write_failed", error.message));
+    async function finish(size, sha256) {
+        const actual = hash.digest("hex");
+        if (process.platform !== "win32")
+            await handle.chmod(await finalMode(path));
+        if (life.settled)
+            return;
+        await new Promise((resolve, reject) => {
+            stream.once("close", resolve);
+            stream.once("error", reject);
+            stream.end();
+        });
+        if (life.settled)
+            return;
+        if (received !== size || (expected !== undefined && expected !== size))
+            return life.abort("size_mismatch", `Received ${received} bytes, expected ${expected ?? size}. ${path} was not changed.`);
+        if (actual !== sha256)
+            return life.abort("checksum_mismatch", `The SHA-256 checksum does not match. ${path} was not changed.`);
+        try {
+            await rename(part, path);
+        }
+        catch (error) {
+            const failure = fsError(error);
+            return life.abort(failure.code, failure.message);
+        }
+        send({ type: "transfer", kind: "done", size, sha256 });
+        life.finish({ size, sha256 });
+    }
+    life.touch();
+    return {
+        result: life.result,
+        abort: life.abort,
+        expect(size) {
+            expected = size;
+        },
+        receive(message, body) {
+            if (life.settled)
+                return;
+            if (message.kind === "data") {
+                if (ending || message.offset !== received)
+                    return life.abort("out_of_order", "Transfer data arrived out of order.");
+                const length = body.byteLength;
+                if (expected !== undefined && received + length > expected)
+                    return life.abort("size_mismatch", `Received more than ${expected} bytes.`);
+                received += length;
+                hash.update(body);
+                life.touch();
+                stream.write(body, (error) => {
+                    if (error || life.settled)
+                        return;
+                    written += length;
+                    options.onProgress?.(written);
+                    if (!send({ type: "transfer", kind: "ack", offset: written }))
+                        life.abort("connection_lost", "The device connection was lost. Run the copy again.", false);
+                });
+            }
+            else if (message.kind === "end") {
+                if (ending)
+                    return;
+                ending = true;
+                life.touch();
+                finish(message.size, message.sha256).catch((error) => life.abort("write_failed", error instanceof Error ? error.message : "Write failed."));
+            }
+            else if (message.kind === "abort")
+                life.abort(message.code, message.message, false);
+        },
+    };
+}
+function parseOpen(args) {
+    if (!isRecord(args) ||
+        (args.direction !== "push" && args.direction !== "pull") ||
+        typeof args.path !== "string" ||
+        !args.path ||
+        args.path.includes("\0") ||
+        (args.direction === "push" && !isSize(args.size)))
+        return null;
+    return {
+        direction: args.direction,
+        path: args.path,
+        ...(args.direction === "push" ? { size: args.size } : {}),
+    };
+}
+export class TransferHost {
+    options;
+    transfers = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async open(id, peer, args, send) {
+        if (this.transfers.has(id))
+            return;
+        const request = parseOpen(args);
+        if (!request) {
+            send(actionError("invalid_args", "transfer.open requires direction push or pull, a path, and a size for push."));
+            return;
+        }
+        if (this.transfers.size >= (this.options.limit ?? MAX_HOST_TRANSFERS)) {
+            send(actionError("busy", "The computer is already running its maximum number of transfers."));
+            return;
+        }
+        const entry = { peer, canceled: false };
+        this.transfers.set(id, entry);
+        try {
+            if (request.direction === "push") {
+                const destination = await openDestination(request.path);
+                if (entry.canceled)
+                    return void (await destination.cancel());
+                entry.endpoint = destination.start(send, { ...this.options, size: request.size });
+                send({ type: "response", ok: true, result: {} });
+            }
+            else {
+                const source = await openSource(request.path);
+                if (entry.canceled)
+                    return void (await source.close());
+                send({
+                    type: "response",
+                    ok: true,
+                    result: { size: source.size },
+                });
+                entry.endpoint = source.start(send, this.options);
+            }
+            await entry.endpoint.result.catch(() => { });
+        }
+        catch (error) {
+            if (!entry.canceled)
+                send(error instanceof TransferError
+                    ? actionError(error.code, error.message)
+                    : actionError("io_error", "The transfer failed."));
+        }
+        finally {
+            this.transfers.delete(id);
+        }
+    }
+    receive(id, peer, message, body) {
+        const entry = this.transfers.get(id);
+        if (!entry || entry.peer !== peer)
+            return;
+        if (entry.endpoint)
+            entry.endpoint.receive(message, body);
+        else if (message.kind === "abort")
+            entry.canceled = true;
+    }
+    abortAll() {
+        for (const entry of this.transfers.values()) {
+            entry.canceled = true;
+            entry.endpoint?.abort("connection_lost", "The host connection was lost.", false);
+        }
+    }
+}
+export async function copyWithDevice(openChannel, request, options = {}) {
+    const started = Date.now();
+    const { signal, onProgress, ...transfer } = options;
+    const canceled = () => new TransferError("canceled", "The copy was canceled.");
+    if (signal?.aborted)
+        throw canceled();
+    const idleMs = transfer.idleMs ?? TRANSFER_IDLE_MS;
+    const source = request.direction === "push" ? await openSource(request.localPath) : undefined;
+    let destination;
+    try {
+        if (request.direction === "pull")
+            destination = await openDestination(request.localPath);
+        if (signal?.aborted)
+            throw canceled();
+    }
+    catch (error) {
+        await source?.close();
+        await destination?.cancel();
+        throw error;
+    }
+    let total = source?.size ?? 0;
+    let endpoint;
+    let receiver;
+    let channel;
+    let opened = false;
+    let settle;
+    const outcome = new Promise((resolve) => {
+        settle = resolve;
+    });
+    const attach = (next) => {
+        endpoint = next;
+        next.result.then(settle, (error) => settle(error instanceof TransferError ? error : new TransferError("io_error", String(error))));
+    };
+    const fail = (error, notify) => {
+        if (endpoint)
+            return endpoint.abort(error.code, error.message, notify);
+        if (notify)
+            channel?.send({ type: "transfer", kind: "abort", code: error.code, message: error.message });
+        void Promise.resolve(source?.close() ?? destination?.cancel()).finally(() => settle(error));
+    };
+    const progress = (bytes) => onProgress?.({ bytes, total });
+    const opening = source
+        ? setTimeout(() => fail(new TransferError("timeout", "The device did not answer the copy."), true), idleMs)
+        : undefined;
+    const result = await openChannel({
+        frame(meta, body) {
+            const response = parseResponse(meta);
+            if (response) {
+                if (!response.ok)
+                    return fail(new TransferError(response.error.code, response.error.message), false);
+                if (opened || !channel)
+                    return;
+                opened = true;
+                clearTimeout(opening);
+                if (source)
+                    return attach(source.start(channel.send, { ...transfer, onProgress: progress }));
+                const size = isRecord(response.result) ? response.result.size : undefined;
+                if (!isSize(size))
+                    return fail(new TransferError("invalid_response", "The device sent no file size."), true);
+                total = size;
+                receiver?.expect(size);
+                return;
+            }
+            const message = parseTransferMessage(meta);
+            if (message && endpoint)
+                endpoint.receive(message, body);
+            else if (message?.kind === "abort")
+                fail(new TransferError(message.code, message.message), false);
+        },
+        lost() {
+            fail(new TransferError("connection_lost", "The device connection was lost. Run the copy again."), false);
+        },
+    });
+    if (!("send" in result)) {
+        clearTimeout(opening);
+        await (source?.close() ?? destination?.cancel());
+        throw result.ok
+            ? new TransferError("invalid_response", "The device channel could not be opened.")
+            : new TransferError(result.error.code, result.error.message);
+    }
+    channel = result;
+    if (signal?.aborted) {
+        clearTimeout(opening);
+        channel.close();
+        await (source?.close() ?? destination?.cancel());
+        throw canceled();
+    }
+    if (destination) {
+        receiver = destination.start(channel.send, { ...transfer, onProgress: progress });
+        attach(receiver);
+    }
+    const cancel = () => fail(canceled(), true);
+    signal?.addEventListener("abort", cancel, { once: true });
+    const args = {
+        direction: request.direction,
+        path: request.remotePath,
+        ...(source ? { size: source.size } : {}),
+    };
+    if (!channel.send({ type: "request", action: "transfer.open", args }))
+        fail(new TransferError("connection_lost", "The copy could not be sent to the device."), false);
+    const value = await outcome;
+    clearTimeout(opening);
+    signal?.removeEventListener("abort", cancel);
+    channel.close();
+    if (value instanceof TransferError)
+        throw value;
+    return { bytes: value.size, sha256: value.sha256, ms: Date.now() - started };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rome-os/node-core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "JavaScript APIs for Rome device hosts and shared caller daemons",
   "license": "MIT",
   "type": "module",