@devicerail/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./errors.js";
+export { DeviceRailEventStream, type EventStreamItem, type EventStreamOptions, type EventStreamWebSocket, type EventStreamWebSocketEvent, type EventStreamWebSocketEventType, type EventStreamWebSocketFactory, } from "./event-stream.js";
+export * from "./ndjson.js";
+export * from "./rpc-client.js";
+export { validateRpcResult } from "./rpc-response-validator.js";
+export * from "./stderr-tail.js";
+export * from "./write-queue.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./errors.js";
+export { DeviceRailEventStream, } from "./event-stream.js";
+export * from "./ndjson.js";
+export * from "./rpc-client.js";
+export { validateRpcResult } from "./rpc-response-validator.js";
+export * from "./stderr-tail.js";
+export * from "./write-queue.js";

package/dist/ndjson.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_MAX_FRAME_BYTES: number;
+export interface NdjsonDecoderOptions {
+    readonly maxFrameBytes?: number;
+}
+/** A byte-bounded, fatal-UTF-8 NDJSON decoder. */
+export declare class NdjsonDecoder {
+    #private;
+    readonly maxFrameBytes: number;
+    constructor(options?: NdjsonDecoderOptions);
+    get bufferedBytes(): number;
+    push(chunk: Uint8Array): string[];
+    end(): void;
+}

package/dist/ndjson.js

@@ -0,0 +1,134 @@
+import { NdjsonFrameTooLargeError, NdjsonIncompleteFrameError, NdjsonInvalidUtf8Error, } from "./errors.js";
+export const DEFAULT_MAX_FRAME_BYTES = 1024 * 1024;
+function positiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+/** A byte-bounded, fatal-UTF-8 NDJSON decoder. */
+export class NdjsonDecoder {
+    maxFrameBytes;
+    #buffer = Buffer.alloc(0);
+    #bufferedBytes = 0;
+    #ended = false;
+    #failure;
+    constructor(options = {}) {
+        this.maxFrameBytes = positiveSafeInteger(options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, "maxFrameBytes");
+    }
+    get bufferedBytes() {
+        return this.#bufferedBytes;
+    }
+    push(chunk) {
+        this.#assertOpen();
+        if (chunk.byteLength === 0) {
+            return [];
+        }
+        const incoming = Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+        const frames = [];
+        let start = 0;
+        for (let index = 0; index < incoming.length; index += 1) {
+            if (incoming[index] !== 0x0a) {
+                continue;
+            }
+            const segment = incoming.subarray(start, index);
+            this.#checkCompletedBound(segment);
+            const frame = this.#bufferedBytes === 0
+                ? Buffer.from(segment)
+                : this.#appendAndView(segment);
+            frames.push(this.#decodeFrame(frame));
+            this.#bufferedBytes = 0;
+            start = index + 1;
+        }
+        if (start < incoming.length) {
+            const remainder = incoming.subarray(start);
+            this.#checkPendingSegmentBound(remainder);
+            this.#append(remainder);
+        }
+        return frames;
+    }
+    end() {
+        this.#assertOpen();
+        this.#ended = true;
+        if (this.#bufferedBytes !== 0) {
+            const error = new NdjsonIncompleteFrameError(this.#bufferedBytes);
+            this.#failure = error;
+            throw error;
+        }
+    }
+    #decodeFrame(rawFrame) {
+        const frame = rawFrame.at(-1) === 0x0d ? rawFrame.subarray(0, -1) : rawFrame;
+        if (frame.length > this.maxFrameBytes) {
+            return this.#fail(new NdjsonFrameTooLargeError(this.maxFrameBytes, frame.length));
+        }
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(frame);
+        }
+        catch (cause) {
+            return this.#fail(new NdjsonInvalidUtf8Error(cause));
+        }
+    }
+    #checkPendingSegmentBound(segment) {
+        const length = this.#bufferedBytes + segment.length;
+        const finalByte = segment.at(-1) ?? this.#buffer.at(this.#bufferedBytes - 1);
+        const mayBeTerminalCarriageReturn = length === this.maxFrameBytes + 1 && finalByte === 0x0d;
+        if (length > this.maxFrameBytes && !mayBeTerminalCarriageReturn) {
+            this.#fail(new NdjsonFrameTooLargeError(this.maxFrameBytes, length));
+        }
+    }
+    #checkCompletedBound(segment) {
+        const rawLength = this.#bufferedBytes + segment.length;
+        const finalByte = segment.at(-1) ?? this.#buffer.at(this.#bufferedBytes - 1);
+        const frameLength = finalByte === 0x0d ? rawLength - 1 : rawLength;
+        if (frameLength > this.maxFrameBytes) {
+            this.#fail(new NdjsonFrameTooLargeError(this.maxFrameBytes, frameLength));
+        }
+    }
+    #append(segment) {
+        const required = this.#bufferedBytes + segment.length;
+        this.#ensureCapacity(required);
+        segment.copy(this.#buffer, this.#bufferedBytes);
+        this.#bufferedBytes = required;
+    }
+    #appendAndView(segment) {
+        this.#append(segment);
+        return this.#buffer.subarray(0, this.#bufferedBytes);
+    }
+    #ensureCapacity(required) {
+        if (required <= this.#buffer.length) {
+            return;
+        }
+        const maximum = this.maxFrameBytes + 1;
+        let capacity = Math.max(64, this.#buffer.length);
+        while (capacity < required) {
+            capacity = Math.min(maximum, capacity * 2);
+            if (capacity < required && capacity === maximum) {
+                capacity = required;
+                break;
+            }
+        }
+        const next = Buffer.allocUnsafe(capacity);
+        if (this.#bufferedBytes > 0) {
+            this.#buffer.copy(next, 0, 0, this.#bufferedBytes);
+        }
+        this.#buffer = next;
+    }
+    #assertOpen() {
+        if (this.#failure) {
+            throw this.#failure;
+        }
+        if (this.#ended) {
+            throw new TransportClosedDecoderError();
+        }
+    }
+    #fail(error) {
+        this.#failure = error;
+        throw error;
+    }
+}
+class TransportClosedDecoderError extends Error {
+    constructor() {
+        super("NDJSON decoder has already ended");
+        this.name = "TransportClosedDecoderError";
+    }
+}

package/dist/rpc-client.d.ts

@@ -0,0 +1,69 @@
+import type { SpawnOptionsWithoutStdio } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import type { HelloParams, HelloResult, EventsSubscribeParams, RequestCancelResult, RpcId, RpcMethod, RpcParamsFor, RpcResultFor, RpcSupportsTimeout } from "@devicerail/protocol";
+import { DeviceRailEventStream, type EventStreamOptions } from "./event-stream.js";
+export type ClientRpcMethod = Exclude<RpcMethod, "events.subscribe" | "system.hello">;
+export type ClientState = "awaitingHello" | "helloInFlight" | "ready" | "closing" | "closed" | "failed";
+export interface TransportClosure {
+    readonly code: number | null;
+    readonly error?: Error;
+    readonly signal: NodeJS.Signals | null;
+}
+export interface ClientTransport {
+    readonly closed: Promise<TransportClosure>;
+    readonly readable: Readable;
+    readonly stderr?: Readable;
+    readonly writable: Writable;
+    closeInput(): void;
+    terminate?(): void;
+}
+export interface SpawnClientOptions {
+    readonly args?: readonly string[];
+    readonly closeGraceMs?: number;
+    readonly command: string;
+    readonly hello: HelloParams;
+    readonly maxFrameBytes?: number;
+    readonly maxPendingRequests?: number;
+    readonly maxQueuedBytes?: number;
+    readonly maxQueuedFrames?: number;
+    readonly spawn?: Omit<SpawnOptionsWithoutStdio, "shell" | "stdio">;
+    readonly stderrTailBytes?: number;
+}
+export interface AttachedClientOptions {
+    readonly closeGraceMs?: number;
+    readonly maxFrameBytes?: number;
+    readonly maxPendingRequests?: number;
+    readonly maxQueuedBytes?: number;
+    readonly maxQueuedFrames?: number;
+    readonly stderrTailBytes?: number;
+}
+type TimeoutCallOptions<M extends ClientRpcMethod> = RpcSupportsTimeout<M> extends true ? {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+} : {
+    readonly signal?: never;
+    readonly timeoutMs?: never;
+};
+export type CallOptions<M extends ClientRpcMethod> = TimeoutCallOptions<M>;
+export type CallArguments<M extends ClientRpcMethod> = undefined extends RpcParamsFor<M> ? [params?: RpcParamsFor<M>, options?: CallOptions<M>] : [params: RpcParamsFor<M>, options?: CallOptions<M>];
+export interface RequestHandle<Result> {
+    readonly id: RpcId;
+    readonly result: Promise<Result>;
+    cancel(): Promise<RequestCancelResult>;
+}
+export declare class DeviceRailClient {
+    #private;
+    constructor(transport: ClientTransport, options?: AttachedClientOptions);
+    static spawn(options: SpawnClientOptions): Promise<DeviceRailClient>;
+    get enabledFeatures(): ReadonlySet<string>;
+    get pendingRequests(): number;
+    get state(): ClientState;
+    get stderrTail(): string;
+    hello(params: HelloParams): Promise<HelloResult>;
+    call<M extends ClientRpcMethod>(method: M, ...args: CallArguments<M>): Promise<RpcResultFor<M>>;
+    openEventStream(params: EventsSubscribeParams, options?: EventStreamOptions): Promise<DeviceRailEventStream>;
+    beginCall<M extends ClientRpcMethod>(method: M, ...args: CallArguments<M>): RequestHandle<RpcResultFor<M>>;
+    cancel(requestId: RpcId): Promise<RequestCancelResult>;
+    close(): Promise<void>;
+}
+export {};