Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

extensions/voice/src/speak-client.ts

Raw
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<typeof setTimeout>;
	abort?: () => void;
	onResult?: (result: object) => void;
};
type Waiter = {
	resolve: (value: OperationOutcome) => void;
	reject: (reason: Error) => void;
	timer: ReturnType<typeof setTimeout>;
	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<ServiceInfo> | undefined;
	#closing: Promise<void> | undefined;
	#info: ServiceInfo | undefined;
	#buffer = Buffer.alloc(0);
	#decoder = new TextDecoder("utf-8", { fatal: true });
	#id = 0;
	#pending = new Map<string, Pending>();
	#retired = new Set<string>();
	#events = new Set<(event: SpeakEvent) => void>();
	#failures = new Set<(error: Error) => void>();
	#terminals = new Map<string, OperationOutcome>();
	#waiters = new Map<string, Set<Waiter>>();
	#writeQueue: Array<{ id: string; line: string }> = [];
	#queuedBytes = 0;
	#waitingDrain = false;
	#lastSeq = 0;
	#failure: Error | undefined;
	#closed = false;
	#exit: Promise<void> | 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<ServiceInfo> {
		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<ServiceInfo>(
				"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<T extends object>(
		method: string,
		params: Record<string, unknown> = {},
		options: {
			signal?: AbortSignal;
			timeoutMs?: number;
			onResult?: (result: T) => void;
		} = {},
	): Promise<T> {
		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<T>((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<OperationOutcome> {
		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<Waiter>();
			waiters.add(waiter);
			this.#waiters.set(operation, waiters);
		});
	}

	close(): Promise<void> {
		if (this.#closing) return this.#closing;
		this.#closing = this.#close();
		return this.#closing;
	}

	async #close(): Promise<void> {
		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<void> {
	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;
}