repositories / pi-ext
pi-ext
bugabingas pi extensions
owned by admin
extensions/voice/src/speak-client.ts
Rawimport { 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;
}