@devicerail/client 0.1.0

package/dist/rpc-response-validator.d.ts

@@ -0,0 +1,5 @@
+import type { RpcMethod, RpcResponseFor, RpcResultFor } from "@devicerail/protocol";
+export declare function assertPureJsonValue(value: unknown, location?: string): void;
+export declare function validateRpcResponse<M extends RpcMethod>(method: M, response: unknown): asserts response is RpcResponseFor<M>;
+/** Validates a method result for adapters that inject a client-compatible transport. */
+export declare function validateRpcResult<M extends RpcMethod>(method: M, result: unknown): asserts result is RpcResultFor<M>;

package/dist/rpc-response-validator.js

@@ -0,0 +1,190 @@
+import { types as utilTypes } from "node:util";
+import { Ajv2020, } from "ajv/dist/2020.js";
+import { ProtocolViolationError } from "./errors.js";
+import { RPC_RESPONSE_SCHEMAS } from "./generated/response-schemas.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+const MAX_PUBLIC_JSON_DEPTH = 256;
+const MAX_PUBLIC_JSON_NODES = 100_000;
+const compiler = new Ajv2020({
+    allErrors: false,
+    allowUnionTypes: true,
+    strict: true,
+    validateFormats: true,
+});
+compiler.addFormat("uuid", { type: "string", validate: (value) => UUID_PATTERN.test(value) });
+compiler.addFormat("int32", {
+    type: "number",
+    validate: (value) => Number.isInteger(value) && value >= -2_147_483_648 && value <= 2_147_483_647,
+});
+compiler.addFormat("uint16", {
+    type: "number",
+    validate: (value) => Number.isInteger(value) && value >= 0 && value <= 65_535,
+});
+compiler.addFormat("uint32", {
+    type: "number",
+    validate: (value) => Number.isInteger(value) && value >= 0 && value <= 4_294_967_295,
+});
+compiler.addFormat("uint64", {
+    type: "number",
+    validate: (value) => Number.isSafeInteger(value) && value >= 0,
+});
+compiler.addFormat("double", {
+    type: "number",
+    validate: (value) => Number.isFinite(value),
+});
+const responseValidators = new Map();
+function responseValidator(method) {
+    const cached = responseValidators.get(method);
+    if (cached) {
+        return cached;
+    }
+    if (typeof method !== "string" || !Object.hasOwn(RPC_RESPONSE_SCHEMAS, method)) {
+        throw new ProtocolViolationError("no runtime response Schema is registered for the method");
+    }
+    const schema = RPC_RESPONSE_SCHEMAS[method];
+    try {
+        const validator = compiler.compile(schema);
+        responseValidators.set(method, validator);
+        return validator;
+    }
+    catch (cause) {
+        throw new Error(`failed to compile the packaged ${method} response Schema`, { cause });
+    }
+}
+function boundedDiagnosticLocation(value) {
+    const safe = value.replace(/[^\x20-\x7e]/gu, "?");
+    return safe.length <= 256 ? safe : `${safe.slice(0, 253)}...`;
+}
+export function assertPureJsonValue(value, location = "$") {
+    const pending = [
+        { depth: 0, location, value },
+    ];
+    const seen = new Set();
+    let nodes = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (!current) {
+            continue;
+        }
+        nodes += 1;
+        if (nodes > MAX_PUBLIC_JSON_NODES || current.depth > MAX_PUBLIC_JSON_DEPTH) {
+            throw new ProtocolViolationError("response exceeds the pure-JSON validation budget");
+        }
+        if (current.value === null ||
+            typeof current.value === "string" ||
+            typeof current.value === "boolean") {
+            continue;
+        }
+        if (typeof current.value === "number") {
+            if (!Number.isFinite(current.value) ||
+                (Number.isInteger(current.value) && !Number.isSafeInteger(current.value))) {
+                throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains an unsafe JSON number`);
+            }
+            continue;
+        }
+        if (typeof current.value !== "object") {
+            throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a non-JSON value`);
+        }
+        if (utilTypes.isProxy(current.value)) {
+            throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a non-JSON proxy`);
+        }
+        if (seen.has(current.value)) {
+            throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a repeated or cyclic value`);
+        }
+        seen.add(current.value);
+        if (Array.isArray(current.value)) {
+            const array = current.value;
+            if (Object.getPrototypeOf(array) !== Array.prototype) {
+                throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a non-JSON array`);
+            }
+            const ownKeys = Reflect.ownKeys(array);
+            if (array.length > MAX_PUBLIC_JSON_NODES ||
+                ownKeys.length > MAX_PUBLIC_JSON_NODES + 1) {
+                throw new ProtocolViolationError("response exceeds the pure-JSON validation budget");
+            }
+            if (ownKeys.some((key) => typeof key !== "string" ||
+                (key !== "length" &&
+                    (!/^(0|[1-9][0-9]*)$/u.test(key) ||
+                        !Number.isSafeInteger(Number(key)) ||
+                        Number(key) >= array.length)))) {
+                throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a non-JSON array property`);
+            }
+            const descriptors = Object.getOwnPropertyDescriptors(array);
+            for (let index = array.length - 1; index >= 0; index -= 1) {
+                const descriptor = descriptors[String(index)];
+                if (!descriptor?.enumerable || !("value" in descriptor)) {
+                    throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a sparse or accessor array slot`);
+                }
+                pending.push({
+                    depth: current.depth + 1,
+                    location: boundedDiagnosticLocation(`${current.location}[${index}]`),
+                    value: descriptor.value,
+                });
+            }
+        }
+        else {
+            const prototype = Object.getPrototypeOf(current.value);
+            if (prototype !== Object.prototype && prototype !== null) {
+                throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a non-JSON object`);
+            }
+            const ownKeys = Reflect.ownKeys(current.value);
+            if (ownKeys.length > MAX_PUBLIC_JSON_NODES) {
+                throw new ProtocolViolationError("response exceeds the pure-JSON validation budget");
+            }
+            const descriptors = Object.getOwnPropertyDescriptors(current.value);
+            for (const key of ownKeys) {
+                if (typeof key !== "string") {
+                    throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a symbol property`);
+                }
+                const descriptor = descriptors[key];
+                if (!descriptor?.enumerable || !("value" in descriptor)) {
+                    throw new ProtocolViolationError(`${boundedDiagnosticLocation(current.location)} contains a non-JSON property`);
+                }
+                pending.push({
+                    depth: current.depth + 1,
+                    location: boundedDiagnosticLocation(`${current.location}.*`),
+                    value: descriptor.value,
+                });
+            }
+        }
+    }
+}
+function redactedInstanceLocation(instancePath) {
+    const segments = instancePath.split("/").slice(1);
+    let location = "$";
+    for (const segment of segments) {
+        location += /^(0|[1-9][0-9]{0,11})$/u.test(segment) ? `[${segment}]` : ".*";
+        if (location.length > 256) {
+            return `${location.slice(0, 253)}...`;
+        }
+    }
+    return location;
+}
+function validationError(method, errors) {
+    const candidates = [...(errors ?? [])].sort((left, right) => {
+        const pathDifference = right.instancePath.length - left.instancePath.length;
+        if (pathDifference !== 0) {
+            return pathDifference;
+        }
+        const leftAggregate = left.keyword === "anyOf" || left.keyword === "oneOf";
+        const rightAggregate = right.keyword === "anyOf" || right.keyword === "oneOf";
+        return Number(leftAggregate) - Number(rightAggregate);
+    });
+    const error = candidates[0];
+    if (!error) {
+        return new ProtocolViolationError(`${method} response was rejected by its JSON Schema`);
+    }
+    const location = redactedInstanceLocation(error.instancePath);
+    return new ProtocolViolationError(`${method} response was rejected at ${location}: ${error.message ?? error.keyword}`);
+}
+export function validateRpcResponse(method, response) {
+    const validator = responseValidator(method);
+    assertPureJsonValue(response);
+    if (!validator(response)) {
+        throw validationError(method, validator.errors);
+    }
+}
+/** Validates a method result for adapters that inject a client-compatible transport. */
+export function validateRpcResult(method, result) {
+    validateRpcResponse(method, { id: 0, jsonrpc: "2.0", result });
+}

package/dist/stderr-tail.d.ts

@@ -0,0 +1,10 @@
+import type { Readable } from "node:stream";
+export declare const DEFAULT_STDERR_TAIL_BYTES: number;
+export declare class BoundedStderrTail {
+    #private;
+    readonly maxBytes: number;
+    constructor(stream?: Readable, maxBytes?: number);
+    get byteLength(): number;
+    get text(): string;
+    stop(): void;
+}

package/dist/stderr-tail.js

@@ -0,0 +1,42 @@
+export const DEFAULT_STDERR_TAIL_BYTES = 64 * 1024;
+export class BoundedStderrTail {
+    maxBytes;
+    #bytes = Buffer.alloc(0);
+    #stopped = false;
+    #stream;
+    #onData = (chunk) => {
+        const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+        if (bytes.length >= this.maxBytes) {
+            this.#bytes = Buffer.from(bytes.subarray(bytes.length - this.maxBytes));
+            return;
+        }
+        const overflow = Math.max(0, this.#bytes.length + bytes.length - this.maxBytes);
+        this.#bytes = Buffer.concat([this.#bytes.subarray(overflow), bytes]);
+    };
+    #onError = () => {
+        // stderr is diagnostic only; transport health is determined by stdout/stdin.
+    };
+    constructor(stream, maxBytes = DEFAULT_STDERR_TAIL_BYTES) {
+        if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+            throw new RangeError("maxBytes must be a positive safe integer");
+        }
+        this.maxBytes = maxBytes;
+        this.#stream = stream;
+        stream?.on("data", this.#onData);
+        stream?.on("error", this.#onError);
+    }
+    get byteLength() {
+        return this.#bytes.length;
+    }
+    get text() {
+        return this.#bytes.toString("utf8");
+    }
+    stop() {
+        if (this.#stopped) {
+            return;
+        }
+        this.#stopped = true;
+        this.#stream?.off("data", this.#onData);
+        this.#stream?.off("error", this.#onError);
+    }
+}

package/dist/write-queue.d.ts

@@ -0,0 +1,26 @@
+import type { Writable } from "node:stream";
+export interface NdjsonWriteQueueOptions {
+    readonly maxFrameBytes?: number;
+    readonly maxQueuedBytes?: number;
+    readonly maxQueuedFrames?: number;
+}
+/** Serializes outbound NDJSON writes and makes stream backpressure observable. */
+export declare class NdjsonWriteQueue {
+    #private;
+    readonly maxFrameBytes: number;
+    readonly maxQueuedBytes: number;
+    readonly maxQueuedFrames: number;
+    constructor(writable: Writable, options?: NdjsonWriteQueueOptions);
+    get backpressured(): boolean;
+    /** Resolves exactly once when the underlying stream or queue fails. */
+    get failure(): Promise<Error>;
+    get queuedBytes(): number;
+    get queuedFrames(): number;
+    get progressVersion(): bigint;
+    enqueue(frame: string): Promise<void>;
+    idle(): Promise<void>;
+    /** Resolves after the next admitted frame leaves the bounded queue. */
+    waitForProgress(since?: bigint): Promise<void>;
+    fail(error: Error): void;
+    close(): Promise<void>;
+}

package/dist/write-queue.js

@@ -0,0 +1,273 @@
+import { TransportClosedError, WriteFrameTooLargeError, WriteQueueOverflowError, } from "./errors.js";
+import { DEFAULT_MAX_FRAME_BYTES } from "./ndjson.js";
+const NEWLINE = Buffer.from("\n");
+function positiveSafeInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+    return value;
+}
+/** Serializes outbound NDJSON writes and makes stream backpressure observable. */
+export class NdjsonWriteQueue {
+    maxFrameBytes;
+    maxQueuedBytes;
+    maxQueuedFrames;
+    #backpressured = false;
+    #accepting = true;
+    #activeAbort;
+    #closePromise;
+    #failure;
+    #failurePromise;
+    #resolveFailure;
+    #idleWaiters = [];
+    #progressWaiters = [];
+    #pumping = false;
+    #progressVersion = 0n;
+    #queue = [];
+    #queuedBytes = 0;
+    #streamErrorsGuarded = false;
+    #writable;
+    #ignoreLateStreamError = () => { };
+    #onGuardedStreamClose = () => {
+        this.#writable.off("error", this.#ignoreLateStreamError);
+        this.#writable.off("close", this.#onGuardedStreamClose);
+        this.#streamErrorsGuarded = false;
+    };
+    #onStreamClose = () => {
+        this.fail(new TransportClosedError("outbound stream closed"));
+    };
+    #onStreamError = (cause) => {
+        this.fail(new TransportClosedError("outbound stream failed", { cause }));
+    };
+    #onStreamFinish = () => {
+        this.fail(new TransportClosedError("outbound stream finished"));
+    };
+    constructor(writable, options = {}) {
+        this.#writable = writable;
+        this.maxFrameBytes = positiveSafeInteger(options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, "maxFrameBytes");
+        this.maxQueuedBytes = positiveSafeInteger(options.maxQueuedBytes ?? this.maxFrameBytes * 4, "maxQueuedBytes");
+        this.maxQueuedFrames = positiveSafeInteger(options.maxQueuedFrames ?? 256, "maxQueuedFrames");
+        this.#failurePromise = new Promise((resolve) => {
+            this.#resolveFailure = resolve;
+        });
+        this.#writable.on("close", this.#onStreamClose);
+        this.#writable.on("error", this.#onStreamError);
+        this.#writable.on("finish", this.#onStreamFinish);
+    }
+    get backpressured() {
+        return this.#backpressured;
+    }
+    /** Resolves exactly once when the underlying stream or queue fails. */
+    get failure() {
+        return this.#failurePromise;
+    }
+    get queuedBytes() {
+        return this.#queuedBytes;
+    }
+    get queuedFrames() {
+        return this.#queue.length;
+    }
+    get progressVersion() {
+        return this.#progressVersion;
+    }
+    enqueue(frame) {
+        if (this.#failure) {
+            return Promise.reject(this.#failure);
+        }
+        if (!this.#accepting) {
+            return Promise.reject(new TransportClosedError("outbound queue is closing"));
+        }
+        const payload = Buffer.from(frame, "utf8");
+        if (payload.length > this.maxFrameBytes) {
+            return Promise.reject(new WriteFrameTooLargeError(this.maxFrameBytes, payload.length));
+        }
+        const bytes = Buffer.concat([payload, NEWLINE]);
+        if (this.#queue.length >= this.maxQueuedFrames) {
+            return Promise.reject(new WriteQueueOverflowError(`outbound queue already contains ${this.#queue.length} frames; the limit is ${this.maxQueuedFrames}`));
+        }
+        if (this.#queuedBytes + bytes.length > this.maxQueuedBytes) {
+            return Promise.reject(new WriteQueueOverflowError(`outbound queue would contain ${this.#queuedBytes + bytes.length} bytes; the limit is ${this.maxQueuedBytes}`));
+        }
+        const completion = new Promise((resolve, reject) => {
+            this.#queue.push({ bytes, reject, resolve });
+            this.#queuedBytes += bytes.length;
+        });
+        void this.#pump();
+        return completion;
+    }
+    idle() {
+        if (this.#failure) {
+            return Promise.reject(this.#failure);
+        }
+        if (this.#queue.length === 0) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            this.#idleWaiters.push({ reject, resolve });
+        });
+    }
+    /** Resolves after the next admitted frame leaves the bounded queue. */
+    waitForProgress(since = this.#progressVersion) {
+        if (this.#failure) {
+            return Promise.reject(this.#failure);
+        }
+        if (since !== this.#progressVersion) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            this.#progressWaiters.push({ reject, resolve });
+        });
+    }
+    fail(error) {
+        if (this.#failure) {
+            return;
+        }
+        this.#accepting = false;
+        this.#failure = error;
+        this.#resolveFailure(error);
+        this.#backpressured = false;
+        this.#activeAbort?.(error);
+        const queued = this.#queue.splice(0);
+        this.#queuedBytes = 0;
+        for (const frame of queued) {
+            frame.reject(error);
+        }
+        for (const waiter of this.#idleWaiters.splice(0)) {
+            waiter.reject(error);
+        }
+        for (const waiter of this.#progressWaiters.splice(0)) {
+            waiter.reject(error);
+        }
+        this.#detachStreamListeners();
+    }
+    close() {
+        if (this.#closePromise) {
+            return this.#closePromise;
+        }
+        if (this.#failure) {
+            this.#closePromise = Promise.reject(this.#failure);
+            return this.#closePromise;
+        }
+        this.#accepting = false;
+        this.#closePromise = this.#finishClose();
+        return this.#closePromise;
+    }
+    async #finishClose() {
+        await this.idle();
+        if (this.#failure) {
+            throw this.#failure;
+        }
+        this.#failure = new TransportClosedError();
+        for (const waiter of this.#progressWaiters.splice(0)) {
+            waiter.reject(this.#failure);
+        }
+        this.#detachStreamListeners();
+    }
+    async #pump() {
+        if (this.#pumping || this.#failure) {
+            return;
+        }
+        this.#pumping = true;
+        try {
+            while (!this.#failure) {
+                const frame = this.#queue[0];
+                if (!frame) {
+                    return;
+                }
+                try {
+                    await this.#write(frame.bytes);
+                }
+                catch (cause) {
+                    const error = cause instanceof Error
+                        ? new TransportClosedError("outbound stream failed", { cause })
+                        : new TransportClosedError("outbound stream failed");
+                    this.fail(error);
+                    return;
+                }
+                if (this.#failure) {
+                    return;
+                }
+                this.#queue.shift();
+                this.#queuedBytes -= frame.bytes.length;
+                this.#progressVersion += 1n;
+                for (const waiter of this.#progressWaiters.splice(0)) {
+                    waiter.resolve();
+                }
+                frame.resolve();
+                if (this.#queue.length === 0) {
+                    for (const waiter of this.#idleWaiters.splice(0)) {
+                        waiter.resolve();
+                    }
+                }
+            }
+        }
+        finally {
+            this.#pumping = false;
+        }
+    }
+    #write(bytes) {
+        return new Promise((resolve, reject) => {
+            let callbackComplete = false;
+            let drainComplete = false;
+            let settled = false;
+            let writeReturned = false;
+            const cleanup = () => {
+                this.#writable.off("drain", onDrain);
+                if (this.#activeAbort === abort) {
+                    this.#activeAbort = undefined;
+                }
+            };
+            const abort = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const completeIfReady = () => {
+                if (!settled && writeReturned && callbackComplete && drainComplete) {
+                    settled = true;
+                    cleanup();
+                    this.#backpressured = false;
+                    resolve();
+                }
+            };
+            const onDrain = () => {
+                drainComplete = true;
+                completeIfReady();
+            };
+            this.#activeAbort = abort;
+            try {
+                const accepted = this.#writable.write(bytes, (error) => {
+                    if (error) {
+                        abort(error);
+                        return;
+                    }
+                    callbackComplete = true;
+                    completeIfReady();
+                });
+                writeReturned = true;
+                drainComplete = accepted;
+                this.#backpressured = !accepted;
+                if (!accepted) {
+                    this.#writable.once("drain", onDrain);
+                }
+                completeIfReady();
+            }
+            catch (cause) {
+                abort(cause instanceof Error ? cause : new Error("outbound write threw"));
+            }
+        });
+    }
+    #detachStreamListeners() {
+        this.#writable.off("close", this.#onStreamClose);
+        this.#writable.off("error", this.#onStreamError);
+        this.#writable.off("finish", this.#onStreamFinish);
+        if (!this.#streamErrorsGuarded) {
+            this.#streamErrorsGuarded = true;
+            this.#writable.on("error", this.#ignoreLateStreamError);
+            this.#writable.once("close", this.#onGuardedStreamClose);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@devicerail/client",
+  "version": "0.1.0",
+  "description": "Typed Node.js client for the DeviceRail device automation protocol",
+  "license": "Apache-2.0",
+  "keywords": [
+    "device-automation",
+    "test-automation",
+    "json-rpc",
+    "typescript"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@types/node": "26.1.1",
+    "ajv": "8.20.0",
+    "@devicerail/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wangweiwei/device-rail.git",
+    "directory": "packages/client"
+  },
+  "homepage": "https://github.com/wangweiwei/device-rail#readme",
+  "bugs": {
+    "url": "https://github.com/wangweiwei/device-rail/issues"
+  },
+  "scripts": {
+    "runtime-schemas:generate": "node scripts/generate-response-schemas.mjs",
+    "runtime-schemas:check": "node scripts/generate-response-schemas.mjs --check",
+    "runtime-schemas:test": "node --test scripts/generate-response-schemas.test.mjs",
+    "typecheck": "pnpm run runtime-schemas:check && tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run runtime-schemas:check && node scripts/clean.mjs dist && tsc -p tsconfig.build.json && tsc -p tsconfig.package-exports.json && node scripts/check-package-exports.mjs",
+    "test": "pnpm run runtime-schemas:check && pnpm run runtime-schemas:test && node scripts/clean.mjs .test-dist && tsc -p tsconfig.test.json && node scripts/run-tests.mjs"
+  }
+}