import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process"; import { TextDecoder } from "node:util"; import { isRecord, type OperationOutcome, parseEvent, type ServiceInfo, type SpeakEvent, } from "./speak-protocol.ts"; export * from "./speak-protocol.ts"; const lineLimit = 65_536; const writeLimit = 262_144; const pendingLimit = 32; const ordinaryPendingLimit = 28; const cacheLimit = 512; const requestTimeout = 5_000; const controlMethods = new Set([ "service.ping", "operation.cancel", "resource.set_muted", "resource.close", "service.shutdown", ]); type Pending = { resolve: (value: object) => void; reject: (reason: Error) => void; timer: ReturnType; abort?: () => void; onResult?: (result: object) => void; }; type Waiter = { resolve: (value: OperationOutcome) => void; reject: (reason: Error) => void; timer: ReturnType; abort?: () => void; }; export class SpeakClientError extends Error { readonly data: unknown; constructor(message: string, data?: unknown) { super(message); this.name = "SpeakClientError"; this.data = data; } } export class SpeakClient { readonly #command: readonly string[]; readonly #env: NodeJS.ProcessEnv | undefined; #child: ChildProcessWithoutNullStreams | undefined; #starting: Promise | undefined; #closing: Promise | undefined; #info: ServiceInfo | undefined; #buffer = Buffer.alloc(0); #decoder = new TextDecoder("utf-8", { fatal: true }); #id = 0; #pending = new Map(); #retired = new Set(); #events = new Set<(event: SpeakEvent) => void>(); #failures = new Set<(error: Error) => void>(); #terminals = new Map(); #waiters = new Map>(); #writeQueue: Array<{ id: string; line: string }> = []; #queuedBytes = 0; #waitingDrain = false; #lastSeq = 0; #failure: Error | undefined; #closed = false; #exit: Promise | undefined; constructor( command: readonly string[], options: { env?: NodeJS.ProcessEnv } = {}, ) { if (command.length === 0 || command.some((part) => part.length === 0)) throw new SpeakClientError( "command must contain executable and nonempty prefix arguments", ); this.#command = command; this.#env = options.env; } get serviceInfo(): ServiceInfo | undefined { return this.#info; } async start(): Promise { if (this.#info && !this.#closed && !this.#failure) return this.#info; if (this.#starting) return this.#starting; if (this.#closed || this.#failure) throw this.#failure ?? new SpeakClientError("client is closed"); const [file, ...args] = this.#command; if (!file) throw new SpeakClientError("command requires executable"); try { const child = spawn( file, args.includes("serve") ? args : [...args, "serve"], { shell: false, stdio: "pipe", env: this.#env, }, ); this.#child = child; this.#exit = new Promise((resolve) => child.once("close", resolve)); child.stdout.on("data", (chunk: Buffer) => this.#receive(chunk)); child.stderr.on("data", () => undefined); child.stdin.on("error", (error) => this.#fail( new SpeakClientError(`native stdin error: ${error.message}`), ), ); child.on("error", (error) => this.#fail( new SpeakClientError(`native process error: ${error.message}`), ), ); child.once("close", (code, signal) => { if (!this.#closed) this.#fail( new SpeakClientError( `native process exited (${code ?? signal ?? "unknown"})`, ), ); }); const starting = this.request( "service.info", {}, { timeoutMs: requestTimeout, onResult: (result) => { this.#info = validateInfo(result); }, }, ).then(() => this.#info as ServiceInfo); this.#starting = starting; try { return await starting; } finally { if (this.#starting === starting) this.#starting = undefined; } } catch (error) { const failure = error instanceof Error ? error : new SpeakClientError("native launch failed"); this.#fail(failure); throw failure; } } onEvent(listener: (event: SpeakEvent) => void): () => void { this.#events.add(listener); return () => this.#events.delete(listener); } onFailure(listener: (error: Error) => void): () => void { this.#failures.add(listener); return () => this.#failures.delete(listener); } request( method: string, params: Record = {}, options: { signal?: AbortSignal; timeoutMs?: number; onResult?: (result: T) => void; } = {}, ): Promise { if (!/^[\x21-\x7e]{1,64}$/.test(method)) return Promise.reject(new SpeakClientError("invalid method")); if (!isRecord(params)) return Promise.reject(new SpeakClientError("params must be object")); if (this.#failure) return Promise.reject(this.#failure); if (!this.#child || this.#closed) return Promise.reject(new SpeakClientError("client is not running")); if (options.signal?.aborted) return Promise.reject(new SpeakClientError(`request aborted: ${method}`)); const ordinary = !controlMethods.has(method); if ( this.#pending.size >= pendingLimit || (ordinary && this.#pending.size >= ordinaryPendingLimit) ) return Promise.reject( new SpeakClientError("pending request limit exceeded"), ); const timeout = checkedTimeout(options.timeoutMs ?? requestTimeout); const id = `c${++this.#id}`; const line = `${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`; if (Buffer.byteLength(line) > lineLimit) return Promise.reject( new SpeakClientError("outgoing frame exceeds limit"), ); if (this.#queuedBytes + Buffer.byteLength(line) > writeLimit) return Promise.reject( new SpeakClientError("outgoing queue exceeds limit"), ); return new Promise((resolve, reject) => { const retire = (error: Error, fail = false) => { if (!this.#pending.delete(id)) return; this.#rememberRetired(id); this.#dropQueued(id); clearTimeout(pending.timer); pending.abort?.(); reject(error); if (fail) this.#fail(error); }; const pending: Pending = { resolve: (result) => resolve(result as T), reject, timer: setTimeout( () => retire(new SpeakClientError(`request timed out: ${method}`), true), timeout, ), ...(options.onResult ? { onResult: options.onResult as (result: object) => void } : {}), }; if (options.signal) { const abort = () => retire(new SpeakClientError(`request aborted: ${method}`)); options.signal.addEventListener("abort", abort, { once: true }); pending.abort = () => options.signal?.removeEventListener("abort", abort); } this.#pending.set(id, pending); this.#writeQueue.push({ id, line }); this.#queuedBytes += Buffer.byteLength(line); this.#flush(); }); } waitForOperation( operation: string, options: { signal?: AbortSignal; timeoutMs?: number } = {}, ): Promise { const terminal = this.#terminals.get(operation); if (terminal) return Promise.resolve(terminal); if (this.#failure) return Promise.reject(this.#failure); if (options.signal?.aborted) return Promise.reject( new SpeakClientError(`operation aborted: ${operation}`), ); const timeout = checkedTimeout(options.timeoutMs ?? requestTimeout); return new Promise((resolve, reject) => { const remove = () => this.#waiters.get(operation)?.delete(waiter); const waiter: Waiter = { resolve, reject, timer: setTimeout(() => { remove(); reject(new SpeakClientError(`operation timed out: ${operation}`)); }, timeout), }; if (options.signal) { const abort = () => { remove(); clearTimeout(waiter.timer); reject(new SpeakClientError(`operation aborted: ${operation}`)); }; options.signal.addEventListener("abort", abort, { once: true }); waiter.abort = () => options.signal?.removeEventListener("abort", abort); } const waiters = this.#waiters.get(operation) ?? new Set(); waiters.add(waiter); this.#waiters.set(operation, waiters); }); } close(): Promise { if (this.#closing) return this.#closing; this.#closing = this.#close(); return this.#closing; } async #close(): Promise { const child = this.#child; if (!child) { this.#closed = true; return; } try { await this.request("service.shutdown", {}, { timeoutMs: requestTimeout }); } catch { // A shutdown response cannot prove shutdown after any transport fault. } this.#closed = true; await Promise.race([ this.#exit ?? Promise.resolve(), sleep(requestTimeout), ]); if (child.exitCode === null) child.kill("SIGTERM"); await Promise.race([this.#exit ?? Promise.resolve(), sleep(1_000)]); if (child.exitCode === null) child.kill("SIGKILL"); await this.#exit; this.#settle(new SpeakClientError("client closed")); } #flush(): void { const child = this.#child; if (!child || this.#failure || this.#closed || this.#waitingDrain) return; while (this.#writeQueue.length > 0) { const entry = this.#writeQueue.shift(); if (!entry) return; const { line } = entry; this.#queuedBytes -= Buffer.byteLength(line); if (!child.stdin.writable) { this.#fail(new SpeakClientError("native stdin closed")); return; } try { if (!child.stdin.write(line)) { this.#waitingDrain = true; child.stdin.once("drain", () => { this.#waitingDrain = false; this.#flush(); }); return; } } catch (error) { this.#fail( new SpeakClientError( `native stdin write failed: ${error instanceof Error ? error.message : "unknown error"}`, ), ); return; } } } #receive(chunk: Buffer): void { if (this.#failure) return; this.#buffer = Buffer.concat([this.#buffer, chunk]); for (;;) { const end = this.#buffer.indexOf(10); if (end < 0) break; let line = this.#buffer.subarray(0, end); this.#buffer = this.#buffer.subarray(end + 1); if (line.at(-1) === 13) line = line.subarray(0, -1); if (line.length === 0 || line.length > lineLimit) { this.#fail(new SpeakClientError("invalid native stdout frame")); return; } try { this.#message(JSON.parse(this.#decoder.decode(line))); } catch { this.#fail(new SpeakClientError("invalid native JSON-RPC frame")); return; } } if (this.#buffer.length > lineLimit) this.#fail(new SpeakClientError("native stdout line exceeds limit")); } #message(message: unknown): void { if (!isRecord(message) || message["jsonrpc"] !== "2.0") throw new SpeakClientError("invalid JSON-RPC envelope"); if (typeof message["method"] === "string") { const event = parseEvent(message["method"], message["params"]); const params = message["params"] as SpeakEvent["params"]; if ( !this.#info || params.instance !== this.#info.instance || params.seq !== this.#lastSeq + 1 ) throw new SpeakClientError("invalid event instance or sequence"); this.#lastSeq = params.seq; if (!event) return; if (event.method === "operation.ended") this.#terminal( event.params.operation as string, event.params.data as unknown as OperationOutcome, ); for (const listener of this.#events) { try { listener(event); } catch { /* consumer failure cannot corrupt wire state */ } } return; } if ( typeof message["id"] !== "string" || "result" in message === "error" in message ) throw new SpeakClientError("invalid JSON-RPC response"); const pending = this.#pending.get(message["id"]); if (!pending) { if (this.#retired.delete(message["id"])) return; throw new SpeakClientError("response for unknown request"); } if ("error" in message) { if (!validResponseError(message.error)) throw new SpeakClientError("invalid JSON-RPC error"); this.#pending.delete(message["id"]); clearTimeout(pending.timer); pending.abort?.(); pending.reject( new SpeakClientError(message["error"].message, message["error"].data), ); return; } if (!isRecord(message["result"])) throw new SpeakClientError("invalid JSON-RPC result"); this.#pending.delete(message["id"]); clearTimeout(pending.timer); pending.abort?.(); try { pending.onResult?.(message["result"]); pending.resolve(message["result"]); } catch (error) { const failure = error instanceof Error ? error : new SpeakClientError("invalid result"); pending.reject(failure); this.#fail(failure); } } #terminal(operation: string, outcome: OperationOutcome): void { if (this.#terminals.has(operation)) throw new SpeakClientError("duplicate operation terminal"); this.#terminals.set(operation, outcome); if (this.#terminals.size > cacheLimit) this.#terminals.delete(this.#terminals.keys().next().value as string); for (const waiter of this.#waiters.get(operation) ?? []) { clearTimeout(waiter.timer); waiter.abort?.(); waiter.resolve(outcome); } this.#waiters.delete(operation); } #dropQueued(id: string): void { const index = this.#writeQueue.findIndex((entry) => entry.id === id); if (index < 0) return; const [entry] = this.#writeQueue.splice(index, 1); if (entry) this.#queuedBytes -= Buffer.byteLength(entry.line); } #rememberRetired(id: string): void { this.#retired.add(id); if (this.#retired.size > cacheLimit) this.#retired.delete(this.#retired.values().next().value as string); } #settle(error: Error): void { for (const pending of this.#pending.values()) { clearTimeout(pending.timer); pending.abort?.(); pending.reject(error); } this.#pending.clear(); this.#writeQueue = []; this.#queuedBytes = 0; for (const waiters of this.#waiters.values()) for (const waiter of waiters) { clearTimeout(waiter.timer); waiter.abort?.(); waiter.reject(error); } this.#waiters.clear(); } #fail(error: Error): void { if (this.#failure || this.#closed) return; this.#failure = error; this.#info = undefined; this.#settle(error); for (const listener of this.#failures) { try { listener(error); } catch { /* failure reporting is isolated */ } } if (this.#child && this.#child.exitCode === null) this.#child.kill("SIGTERM"); } } function checkedTimeout(value: number): number { if (!Number.isSafeInteger(value) || value < 1 || value > 1_800_000) throw new SpeakClientError("invalid timeout"); return value; } function sleep(ms: number): Promise { return new Promise((resolve) => setTimeout(resolve, ms)); } function key(value: unknown): boolean { return typeof value === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(value); } function text(value: unknown, limit: number): boolean { return typeof value === "string" && [...value].length <= limit; } function integer(value: unknown): boolean { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0; } function capabilities(value: unknown): boolean { return ( isRecord(value) && [ "capture", "render", "aec", "recognition", "preview", "hotwords", "synthesis", "sounds", "test_io", ].every((name) => typeof value[name] === "boolean") ); } function validResponseError( value: unknown, ): value is { code: number; message: string; data?: unknown } { return ( isRecord(value) && Number.isSafeInteger(value["code"]) && text(value["message"], 512) ); } function validateInfo(value: object): ServiceInfo { if ( !isRecord(value) || !key(value["instance"]) || !["device", "fixture", "fake"].includes(value["io_mode"] as string) || !Array.isArray(value["profiles"]) || !Array.isArray(value["devices"]) || !Array.isArray(value["sounds"]) || !capabilities(value["capabilities"]) || !isRecord(value["limits"]) ) throw new SpeakClientError("invalid service.info result"); const limits = value["limits"]; const limitNames = [ "line_bytes", "pending_requests", "active_operations", "resources", "text_chars", "queued_text_chars", "unacked_segments", "hotwords", "hotword_chars", "waveform_bins", "output_queue_bytes", "instance_requests", "instance_operations", ]; if ( !limitNames.every((name) => integer(limits[name])) || limits["line_bytes"] !== lineLimit || limits["pending_requests"] !== pendingLimit || limits["output_queue_bytes"] !== writeLimit ) throw new SpeakClientError("invalid service.info limits"); if ( value["profiles"].length > 16 || value["devices"].length > 32 || value["sounds"].length > 16 ) throw new SpeakClientError("service.info choices exceed limits"); if ( !value["profiles"].every( (profile) => isRecord(profile) && key(profile["id"]) && text(profile["label"], 256) && text(profile["description"], 256) && typeof profile["installed"] === "boolean" && capabilities(profile["capabilities"]), ) ) throw new SpeakClientError("invalid service.info profile"); if ( !value["devices"].every( (device) => isRecord(device) && key(device["id"]) && text(device["label"], 256) && (device["direction"] === "capture" || device["direction"] === "render") && typeof device["available"] === "boolean", ) ) throw new SpeakClientError("invalid service.info device"); if ( !value["sounds"].every( (sound) => isRecord(sound) && key(sound["id"]) && text(sound["label"], 256) && typeof sound["installed"] === "boolean" && typeof sound["sha256"] === "string" && /^[0-9a-f]{64}$/.test(sound["sha256"]), ) ) throw new SpeakClientError("invalid service.info sound"); return value as ServiceInfo; }