@jskit-ai/assistant-voice 0.0.0-stage → 0.1.2

package/src/server/voiceProxy.js

@@ -0,0 +1,199 @@
+import { WebSocket } from "ws";
+
+import {
+  VOICE_MAX_AUDIO_FRAME_BYTES,
+  VOICE_MAX_CONTROL_BYTES,
+  assertVoiceAudioFrame,
+  parseVoiceClientControl
+} from "../shared/protocol.js";
+import { normalizeVoiceCloseMetadata } from "./voiceSocketClose.js";
+
+const WEBSOCKET_CONNECTING = 0;
+const WEBSOCKET_OPEN = 1;
+
+async function readVoiceCatalogue(config, { fetchImpl = fetch } = {}) {
+  try {
+    if (!config?.available) throw new Error("Voice is not configured.");
+    const url = new URL("/voices", config.endpoint);
+    url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+    const response = await fetchImpl(url, {
+      headers: { authorization: `Bearer ${config.token}` }, signal: AbortSignal.timeout(5000)
+    });
+    if (!response.ok) throw new Error("Voice service refused the catalogue request.");
+    const catalogue = await response.json();
+    if (!Array.isArray(catalogue.voices) || typeof catalogue.defaultVoice !== "string") throw new Error("Invalid voice catalogue.");
+    return catalogue;
+  } catch (cause) {
+    throw Object.assign(new Error("Speaking voices could not load. Check the speech service and retry."), {
+      code: "voice_unavailable", statusCode: 503, cause
+    });
+  }
+}
+
+function closeSocket(socket, code, reason) {
+  if ([WEBSOCKET_CONNECTING, WEBSOCKET_OPEN].includes(socket?.readyState)) {
+    const metadata = normalizeVoiceCloseMetadata(code, reason);
+    socket.close(metadata.code, metadata.reason);
+  }
+}
+
+function sendSocketError(socket, code, message) {
+  if (socket?.readyState === WEBSOCKET_OPEN) {
+    socket.send(JSON.stringify({ code, message, type: "error" }));
+  }
+}
+
+function registerVoiceProxyRoute(fastify, {
+  proxyConfig,
+  route,
+  authorize = null,
+  WebSocketCtor = WebSocket
+} = {}) {
+  if (!fastify || typeof fastify.get !== "function") {
+    throw new TypeError("registerVoiceProxyRoute requires Fastify get().");
+  }
+  if (typeof authorize !== "function" || typeof route !== "string" || !route.startsWith("/")) {
+    throw new TypeError("registerVoiceProxyRoute requires an application route and authorization function.");
+  }
+  const config = proxyConfig || { available: false, endpoint: "", token: "" };
+
+  fastify.get(route, { websocket: true }, (browserSocket, request) => {
+    let serviceSocket = null;
+    let closed = false;
+
+    const closeBoth = (code = 1000, reason = "Voice connection closed") => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      closeSocket(browserSocket, code, reason);
+      closeSocket(serviceSocket, code, reason);
+    };
+    browserSocket.once("close", (code, reason) => {
+      closeBoth(code || 1000, reason?.toString() || "Browser closed voice");
+    });
+    browserSocket.once("error", () => closeBoth(1011, "Browser voice connection failed"));
+
+    if (!config.available) {
+      sendSocketError(browserSocket, "voice_unavailable", "Voice is not installed on this server.");
+      closeBoth(1013, "Voice service unavailable");
+      return;
+    }
+
+    void (async () => {
+      const authorized = await authorize(request);
+      if (authorized === false) {
+        sendSocketError(browserSocket, "voice_auth_required", "Voice access was denied.");
+        closeBoth(1008, "Voice access denied");
+        return;
+      }
+      if (closed) {
+        return;
+      }
+
+      serviceSocket = new WebSocketCtor(config.endpoint, {
+        headers: {
+          authorization: `Bearer ${config.token}`
+        },
+        maxPayload: Math.max(VOICE_MAX_AUDIO_FRAME_BYTES, VOICE_MAX_CONTROL_BYTES),
+        perMessageDeflate: false
+      });
+
+      const pendingFrames = [];
+      let pendingBytes = 0;
+      const forwardToService = (raw, isBinary) => {
+        if (closed) {
+          return;
+        }
+        const frame = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+        const limit = isBinary ? VOICE_MAX_AUDIO_FRAME_BYTES : VOICE_MAX_CONTROL_BYTES;
+        if (frame.byteLength > limit) {
+          sendSocketError(browserSocket, "voice_frame_too_large", "Voice message is too large.");
+          closeBoth(1009, "Voice message too large");
+          return;
+        }
+        try {
+          if (isBinary) {
+            assertVoiceAudioFrame(frame);
+          } else {
+            parseVoiceClientControl(frame);
+          }
+        } catch (error) {
+          sendSocketError(
+            browserSocket,
+            String(error?.code || "voice_control_invalid"),
+            String(error?.message || error)
+          );
+          return;
+        }
+        if (serviceSocket.readyState === WEBSOCKET_OPEN) {
+          serviceSocket.send(frame, { binary: isBinary });
+          return;
+        }
+        if (serviceSocket.readyState !== WEBSOCKET_CONNECTING || pendingBytes + frame.byteLength > 128 * 1024) {
+          sendSocketError(browserSocket, "voice_connecting", "Voice is still connecting. Try again.");
+          return;
+        }
+        pendingFrames.push({ frame, isBinary });
+        pendingBytes += frame.byteLength;
+      };
+
+      browserSocket.on("message", forwardToService);
+
+      serviceSocket.once("open", () => {
+        for (const entry of pendingFrames.splice(0)) {
+          if (serviceSocket.readyState !== WEBSOCKET_OPEN) {
+            break;
+          }
+          serviceSocket.send(entry.frame, { binary: entry.isBinary });
+        }
+        pendingBytes = 0;
+      });
+      serviceSocket.on("message", (raw, isBinary) => {
+        if (browserSocket.readyState !== WEBSOCKET_OPEN) {
+          return;
+        }
+        const frame = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+        const limit = isBinary ? VOICE_MAX_AUDIO_FRAME_BYTES : VOICE_MAX_CONTROL_BYTES;
+        if (frame.byteLength > limit) {
+          closeBoth(1009, "Voice service message too large");
+          return;
+        }
+        browserSocket.send(frame, { binary: isBinary });
+      });
+      serviceSocket.once("unexpected-response", (_request, response) => {
+        const code = Number(response?.statusCode) === 429 ? "voice_busy" : "voice_unavailable";
+        const message = code === "voice_busy"
+          ? "Voice is busy. Try again shortly."
+          : "Voice service could not be reached.";
+        sendSocketError(browserSocket, code, message);
+        closeBoth(1013, message);
+      });
+      serviceSocket.once("close", (code, reason) => {
+        closeBoth(code || 1012, reason?.toString() || "Voice service closed");
+      });
+      serviceSocket.once("error", () => {
+        sendSocketError(browserSocket, "voice_unavailable", "Voice service could not be reached.");
+        closeBoth(1013, "Voice service unavailable");
+      });
+    })().catch((error) => {
+      sendSocketError(
+        browserSocket,
+        String(error?.code || "voice_session_failed"),
+        "Voice could not open for this conversation."
+      );
+      closeBoth([401, 403].includes(error?.statusCode) ? 1008 : 1011, "Voice session failed");
+    });
+  });
+
+  return Object.freeze({
+    available: config.available,
+    route
+  });
+}
+
+export {
+  closeSocket,
+  readVoiceCatalogue,
+  registerVoiceProxyRoute
+};

package/src/server/voiceProxyConfig.js

@@ -0,0 +1,70 @@
+import { readFileSync, statSync } from "node:fs";
+import { VOICE_ACCESS_TOKEN_VERSION, voiceTenant } from "./voiceAccessToken.js";
+
+function voiceEndpoint(value = "") {
+  const endpoint = String(value || "").trim();
+  if (!endpoint) {
+    return "";
+  }
+  let parsed;
+  try {
+    parsed = new URL(endpoint);
+  } catch {
+    throw new Error("Voice endpoint must be a valid ws:// or wss:// URL.");
+  }
+  if (!["ws:", "wss:"].includes(parsed.protocol) || parsed.username || parsed.password || parsed.hash) {
+    throw new Error("Voice endpoint must use ws:// or wss:// without embedded credentials or fragments.");
+  }
+  return parsed.toString();
+}
+
+function readVoiceAccessToken(filePath = "") {
+  const pathname = String(filePath || "").trim();
+  if (!pathname) {
+    return "";
+  }
+  const metadata = statSync(pathname);
+  if (!metadata.isFile() || metadata.size < 16 || metadata.size > 4_096) {
+    throw new Error("The voice credential file is invalid.");
+  }
+  const token = readFileSync(pathname, "utf8").trim();
+  let valid;
+  try {
+    const [version, tenant = "", signature = "", ...extra] = token.split(".");
+    valid = version === VOICE_ACCESS_TOKEN_VERSION &&
+      extra.length === 0 &&
+      voiceTenant(tenant) === tenant &&
+      /^[A-Za-z0-9_-]{43}$/u.test(signature) &&
+      Buffer.from(signature, "base64url").toString("base64url") === signature;
+  } catch {
+    valid = false;
+  }
+  if (!valid) {
+    throw new Error("The voice credential is malformed.");
+  }
+  return token;
+}
+
+function resolveVoiceProxyConfig({ endpoint: value = "", accessTokenFile = "" } = {}) {
+  const endpoint = voiceEndpoint(value);
+  const tokenFile = String(accessTokenFile || "").trim();
+  if (!endpoint && !tokenFile) {
+    return Object.freeze({ available: false, endpoint: "", token: "" });
+  }
+  if (!endpoint || !tokenFile) {
+    throw new Error(
+      "Voice endpoint and accessTokenFile must be configured together."
+    );
+  }
+  return Object.freeze({
+    available: true,
+    endpoint,
+    token: readVoiceAccessToken(tokenFile)
+  });
+}
+
+export {
+  readVoiceAccessToken,
+  resolveVoiceProxyConfig,
+  voiceEndpoint
+};

package/src/server/voiceSocketClose.js

@@ -0,0 +1,31 @@
+const RESERVED_CLOSE_CODES = new Set([1004, 1005, 1006, 1015]);
+
+function proxyCloseCode(code) {
+  const numericCode = Number(code);
+  const isStandardCode = Number.isInteger(numericCode)
+    && numericCode >= 1000
+    && numericCode <= 1014
+    && !RESERVED_CLOSE_CODES.has(numericCode);
+  const isApplicationCode = Number.isInteger(numericCode)
+    && numericCode >= 3000
+    && numericCode <= 4999;
+  return isStandardCode || isApplicationCode ? numericCode : 1000;
+}
+
+function proxyCloseReason(reason) {
+  const encoded = Buffer.from(String(reason || ""), "utf8");
+  return encoded.byteLength <= 123
+    ? encoded.toString("utf8")
+    : encoded.subarray(0, 120).toString("utf8");
+}
+
+function normalizeVoiceCloseMetadata(code, reason) {
+  return Object.freeze({
+    code: proxyCloseCode(code),
+    reason: proxyCloseReason(reason)
+  });
+}
+
+export {
+  normalizeVoiceCloseMetadata
+};