@h-ai/serv 0.1.0-alpha.34 → 0.1.0-alpha.36

package/dist/index.js

@@ -1,12 +1,14 @@
 import { WILDCARD_PERMISSION, requirePermission } from './chunk-YQV2OMQK.js';
 import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody } from './chunk-4QBF4PUG.js';
 import { implement } from '@orpc/server';
-import process from 'process';
+import process2 from 'process';
 import { serve } from '@hono/node-server';
-import { core, err, HaiCommonError, ok } from '@h-ai/core';
+import { core, ok, err, HaiCommonError } from '@h-ai/core';
+import { createNodeWebSocket } from '@hono/node-ws';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
 import { RPCHandler } from '@orpc/server/fetch';
 import { Hono } from 'hono';
+import { Buffer } from 'buffer';
 import { z } from 'zod';
 import { IAM_AUTH_ROUTES } from '@h-ai/api-contract';
 import { getCookie } from 'hono/cookie';
@@ -23,55 +25,343 @@ function toFetch(app) {
   };
   return handler;
 }
-var DEFAULT_SERV_HOST = "127.0.0.1";
-var DEFAULT_SERV_PORT = 3e3;
-function listen(app, options = {}) {
-  const host = options.host ?? process.env.HOST ?? DEFAULT_SERV_HOST;
-  const port = options.port ?? (process.env.PORT ? Number(process.env.PORT) : DEFAULT_SERV_PORT);
-  const server = serve(
-    { fetch: app.fetch, hostname: host, port },
-    options.onListening
-  );
-  const handle = {
-    server,
-    address: { host, port },
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error)
-          reject(error);
-        else resolve();
+var logger = core.logger.child({ module: "serv", scope: "audio-ws" });
+var DEFAULT_MAX_MESSAGE_BYTES = 1048576;
+var DEFAULT_MAX_BUFFERED_BYTES = 10 * 1024 * 1024;
+var DEFAULT_MAX_TEXT_BYTES = 1 * 1024 * 1024;
+var DEFAULT_MAX_SESSION_MS = 5 * 60 * 1e3;
+function registerAudioWsRoute(app, path, upgradeWebSocket, deps) {
+  const maxMessageBytes = deps.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
+  const maxBufferedBytes = deps.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  const maxTextBytes = deps.maxTextBytes ?? DEFAULT_MAX_TEXT_BYTES;
+  const maxSessionMs = deps.maxSessionMs ?? DEFAULT_MAX_SESSION_MS;
+  app.get(path, upgradeWebSocket((c) => {
+    const ticket = c.req.query("ticket");
+    const conn = new AudioConnection(deps, ticket, maxMessageBytes, maxBufferedBytes, maxTextBytes);
+    let sessionTimer;
+    return {
+      onOpen(_evt, ws) {
+        sessionTimer = setTimeout(() => {
+          conn.fail(ws, "hai:ai:057", "audio session timeout");
+        }, maxSessionMs);
+      },
+      onMessage(evt, ws) {
+        conn.enqueue(ws, evt.data);
+      },
+      onClose() {
+        if (sessionTimer)
+          clearTimeout(sessionTimer);
+        conn.dispose();
+      },
+      onError() {
+        if (sessionTimer)
+          clearTimeout(sessionTimer);
+        conn.dispose();
+      }
+    };
+  }));
+}
+var AsyncQueue = class {
+  items = [];
+  waiting = null;
+  ended = false;
+  push(item) {
+    if (this.ended)
+      return;
+    if (this.waiting) {
+      const w = this.waiting;
+      this.waiting = null;
+      w({ value: item, done: false });
+    } else {
+      this.items.push(item);
+    }
+  }
+  end() {
+    if (this.ended)
+      return;
+    this.ended = true;
+    if (this.waiting) {
+      const w = this.waiting;
+      this.waiting = null;
+      w({ value: void 0, done: true });
+    }
+  }
+  async *iterate() {
+    while (true) {
+      if (this.items.length > 0) {
+        yield this.items.shift();
+        continue;
+      }
+      if (this.ended)
+        return;
+      const next = await new Promise((res) => {
+        this.waiting = res;
       });
-    })
-  };
-  if (options.onClose) {
-    const onClose = options.onClose;
-    let shuttingDown = false;
-    const shutdown = async () => {
-      if (shuttingDown)
+      if (next.done)
+        return;
+      yield next.value;
+    }
+  }
+};
+var AudioConnection = class {
+  constructor(deps, ticket, maxMessageBytes, maxBufferedBytes, maxTextBytes) {
+    this.deps = deps;
+    this.ticket = ticket;
+    this.maxMessageBytes = maxMessageBytes;
+    this.maxBufferedBytes = maxBufferedBytes;
+    this.maxTextBytes = maxTextBytes;
+  }
+  started = false;
+  start;
+  session;
+  authorizedRequest;
+  audioQueue = new AsyncQueue();
+  textQueue = new AsyncQueue();
+  audioBuffer = [];
+  receivedBytes = 0;
+  receivedTextBytes = 0;
+  controller = new AbortController();
+  closed = false;
+  /** 消息串行处理链：确保同一连接的消息按到达顺序处理，鉴权完成前不处理业务帧。 */
+  queue = Promise.resolve();
+  /** 将消息追加到串行处理链，保证按序处理（start 的鉴权完成前不会处理后续业务帧）。 */
+  enqueue(ws, data) {
+    this.queue = this.queue.then(() => this.handleMessage(ws, data)).catch((error) => {
+      logger.debug("audio ws message handling failed", { error: error instanceof Error ? error.message : String(error) });
+      if (!this.closed)
+        this.failFromError(ws, error);
+    });
+  }
+  async handleMessage(ws, data) {
+    if (this.closed)
+      return;
+    const bytes = toBytes(data);
+    if (bytes) {
+      if (!this.started) {
+        this.fail(ws, "hai:ai:050", "audio frame before start");
         return;
-      shuttingDown = true;
-      try {
-        await handle.close();
-      } catch {
       }
-      try {
-        await onClose();
-      } catch {
+      if (bytes.length > this.maxMessageBytes) {
+        this.fail(ws, "hai:ai:058", "audio frame too large");
+        return;
+      }
+      this.receivedBytes += bytes.length;
+      if (this.receivedBytes > this.maxBufferedBytes) {
+        this.fail(ws, "hai:ai:058", "buffered audio exceeds limit");
+        return;
+      }
+      if (this.start?.stream)
+        this.audioQueue.push(bytes);
+      else
+        this.audioBuffer.push(bytes);
+      return;
+    }
+    if (typeof data !== "string")
+      return;
+    if (data.length > this.maxMessageBytes) {
+      this.fail(ws, "hai:ai:058", "message too large");
+      return;
+    }
+    let message;
+    try {
+      message = JSON.parse(data);
+    } catch {
+      this.fail(ws, "hai:ai:050", "invalid json message");
+      return;
+    }
+    if (message.type === "start") {
+      await this.onStart(ws, message);
+    } else if (!this.started) {
+      this.fail(ws, "hai:ai:050", "message before start");
+    } else if (message.type === "text") {
+      this.receivedTextBytes += Buffer.byteLength(message.text, "utf8");
+      if (this.receivedTextBytes > this.maxTextBytes) {
+        this.fail(ws, "hai:ai:058", "buffered text exceeds limit");
+        return;
       }
+      this.textQueue.push({ id: message.segmentId, text: message.text });
+    } else if (message.type === "done") {
+      this.audioQueue.end();
+      this.textQueue.end();
+      if (this.start && !this.start.stream && this.start.operation === "transcribe")
+        await this.runBufferedTranscribe(ws);
+    }
+  }
+  async onStart(ws, message) {
+    if (this.started) {
+      this.fail(ws, "hai:ai:050", "session already started");
+      return;
+    }
+    if (!this.ticket) {
+      this.fail(ws, "hai:ai:054", "missing audio ticket");
+      return;
+    }
+    const verified = await this.deps.verifyTicket(this.ticket);
+    if (!verified.success) {
+      this.fail(ws, String(verified.error.code), verified.error.message);
+      return;
+    }
+    this.session = verified.data;
+    const authorized = this.deps.authorize ? await this.deps.authorize(verified.data, message) : { success: true, data: { operation: message.operation, format: message.format } };
+    if (!authorized.success) {
+      this.fail(ws, String(authorized.error.code), authorized.error.message);
+      return;
+    }
+    const confirmed = {
+      ...message,
+      operation: authorized.data.operation,
+      model: authorized.data.model,
+      voice: authorized.data.voice,
+      instruction: authorized.data.instruction,
+      format: authorized.data.format,
+      sampleRate: authorized.data.sampleRate
     };
-    process.once("SIGINT", () => void shutdown());
-    process.once("SIGTERM", () => void shutdown());
+    this.started = true;
+    this.start = confirmed;
+    this.authorizedRequest = authorized.data;
+    if (confirmed.operation === "synthesize")
+      void this.runSynthesize(ws, confirmed);
+    else if (confirmed.operation === "transcribe" && confirmed.stream)
+      void this.runStreamTranscribe(ws, confirmed);
   }
-  return handle;
+  /** 流式识别：桥接持续音频输入，流式返回临时/最终结果与语音起止事件 */
+  async runStreamTranscribe(ws, start) {
+    try {
+      const stream = this.deps.ai.audio.transcribeStream({
+        audio: {
+          chunks: this.audioQueue.iterate(),
+          format: start.format ?? "pcm16",
+          sampleRate: start.sampleRate ?? 16e3,
+          channels: start.channels
+        },
+        language: start.language,
+        contextHints: start.contextHints,
+        model: start.model,
+        signal: this.controller.signal
+      });
+      for await (const event of stream) {
+        if (event.type === "transcript")
+          this.send(ws, { type: "transcript", text: event.text, final: event.final });
+        else if (event.type === "speech_started")
+          this.send(ws, { type: "speech_started" });
+        else if (event.type === "speech_stopped")
+          this.send(ws, { type: "speech_stopped" });
+      }
+      this.end(ws);
+    } catch (error) {
+      this.failFromError(ws, error);
+    }
+  }
+  /** 非流式识别：缓冲完整音频后返回单条最终结果 */
+  async runBufferedTranscribe(ws) {
+    const start = this.start;
+    if (!start)
+      return;
+    try {
+      const result = await this.deps.ai.audio.transcribe({
+        audio: {
+          data: concat(this.audioBuffer),
+          format: start.format ?? "wav",
+          sampleRate: start.sampleRate,
+          channels: start.channels
+        },
+        language: start.language,
+        contextHints: start.contextHints,
+        model: start.model,
+        signal: this.controller.signal
+      });
+      if (!result.success) {
+        this.fail(ws, String(result.error.code), result.error.message);
+        return;
+      }
+      this.send(ws, { type: "transcript", text: result.data.text, final: true });
+      this.end(ws);
+    } catch (error) {
+      this.failFromError(ws, error);
+    }
+  }
+  /** 语音合成：桥接文本输入，流式返回音频二进制帧 */
+  async runSynthesize(ws, start) {
+    try {
+      const stream = this.deps.ai.audio.synthesizeStream({
+        text: this.textQueue.iterate(),
+        voice: start.voice,
+        instruction: start.instruction,
+        format: start.format,
+        sampleRate: start.sampleRate,
+        model: start.model,
+        signal: this.controller.signal
+      });
+      for await (const event of stream) {
+        if (event.type === "audio")
+          ws.send(toArrayBuffer(event.data));
+        else
+          this.send(ws, event);
+      }
+      this.end(ws);
+    } catch (error) {
+      this.failFromError(ws, error);
+    }
+  }
+  fail(ws, code, message) {
+    this.send(ws, { type: "error", code, message });
+    this.dispose();
+    ws.close();
+  }
+  failFromError(ws, error) {
+    const hai = error;
+    const code = typeof hai?.code === "string" ? hai.code : "hai:ai:054";
+    const message = error instanceof Error ? error.message : String(error);
+    this.fail(ws, code, message);
+  }
+  end(ws) {
+    this.send(ws, { type: "end" });
+    this.dispose();
+    ws.close();
+  }
+  send(ws, message) {
+    if (!this.closed)
+      ws.send(JSON.stringify(message));
+  }
+  dispose() {
+    if (this.closed)
+      return;
+    this.closed = true;
+    this.audioQueue.end();
+    this.textQueue.end();
+    this.controller.abort();
+    if (this.session && this.authorizedRequest && this.deps.onSessionEnd) {
+      void Promise.resolve(this.deps.onSessionEnd(this.session, this.authorizedRequest)).catch((error) => {
+        logger.warn("audio ws session end hook failed", { error: error instanceof Error ? error.message : String(error) });
+      });
+    }
+  }
+};
+function toBytes(data) {
+  if (typeof data === "string")
+    return void 0;
+  if (data instanceof ArrayBuffer)
+    return new Uint8Array(data);
+  if (ArrayBuffer.isView(data))
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+  if (Buffer.isBuffer(data))
+    return new Uint8Array(data);
+  return void 0;
 }
-var WILDCARD_ROLE = "*";
-function requireRole(role, handler) {
-  return requireAuth(async (options) => {
-    const roles = options.context.session?.roles ?? [];
-    if (!roles.includes(role) && !roles.includes(WILDCARD_ROLE))
-      return err(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale: options.context.locale }));
-    return handler(options);
-  });
+function concat(chunks) {
+  const total = chunks.reduce((sum, c) => sum + c.length, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+function toArrayBuffer(data) {
+  const buffer = new ArrayBuffer(data.length);
+  new Uint8Array(buffer).set(data);
+  return buffer;
 }
 var DEFAULT_LOCALE = "zh-CN";
 function resolveRequestLocale(headers) {
@@ -293,7 +583,7 @@ function resolveRefreshCookieConfig(apiPrefix, config, iam) {
   return {
     cookieName: config.cookieName ?? "hai_refresh_token",
     maxAge: config.maxAge ?? 30 * 24 * 3600,
-    isSecure: config.secure ?? process.env.NODE_ENV === "production",
+    isSecure: config.secure ?? process2.env.NODE_ENV === "production",
     refreshCookiePath: `${apiPrefix}${IAM_AUTH_ROUTES.refresh}`,
     onRefresh
   };
@@ -479,7 +769,7 @@ function readScalarBrowserEntry(packageInfo) {
   const browser = packageInfo.browser;
   return typeof browser === "string" ? browser : void 0;
 }
-var logger = core.logger.child({ module: "serv", scope: "transport" });
+var logger2 = core.logger.child({ module: "serv", scope: "transport" });
 var MAX_ENCRYPTED_BODY = 1048576;
 var ENCRYPTABLE_RESPONSE_CONTENT_TYPES = ["application/json"];
 function createTransportMiddleware(manager, keyExchangePath, excludePaths = []) {
@@ -520,7 +810,7 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [])
     try {
       bodyText = await response.clone().text();
     } catch (cause) {
-      logger.warn("Failed to read response body for encryption", { error: cause });
+      logger2.warn("Failed to read response body for encryption", { error: cause });
       c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
       return;
     }
@@ -532,7 +822,7 @@ function createTransportMiddleware(manager, keyExchangePath, excludePaths = [])
     }
     const encResult = await manager.encryptResponse(clientId, bodyText);
     if (!encResult.success) {
-      logger.warn("Failed to encrypt response", { error: encResult.error });
+      logger2.warn("Failed to encrypt response", { error: encResult.error });
       c.res = jsonError(servM("serv_transportEncryptFailed"), 500);
       return;
     }
@@ -564,7 +854,7 @@ async function handleKeyExchange(request, manager) {
       headers: { "Content-Type": "application/json; charset=utf-8" }
     });
   } catch (cause) {
-    logger.error("Key exchange failed", { error: cause });
+    logger2.error("Key exchange failed", { error: cause });
     return jsonError(servM("serv_transportKeyExchangeFailed"), 500);
   }
 }
@@ -582,7 +872,7 @@ async function decryptRequestInPlace(c, manager) {
     return jsonError(servM("serv_transportInvalidPayload"), 400);
   const decResult = manager.decryptRequest(payload);
   if (!decResult.success) {
-    logger.warn("Failed to decrypt request", { error: decResult.error });
+    logger2.warn("Failed to decrypt request", { error: decResult.error });
     return jsonError(servM("serv_transportDecryptFailed"), 400);
   }
   const original = c.req.raw;
@@ -638,7 +928,9 @@ function isEncryptedPayloadShape(value) {
 }
 
 // src/serv-app.ts
+var DEFAULT_AUDIO_WS_PATH = "/ai/audio";
 var API_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"];
+var audioWsInjectors = /* @__PURE__ */ new WeakMap();
 function createApp(options) {
   const http = resolveServHttpConfig(options.http);
   const app = new Hono();
@@ -672,6 +964,21 @@ function createApp(options) {
     mountHealthRoutes(app, http.health);
   if (options.refreshCookie)
     mountRefreshCookieRoutes(app, http.apiPrefix, options.refreshCookie, options.iam);
+  if (options.audio) {
+    const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
+    const audioPath = `${http.apiPrefix}${options.audio.path ?? DEFAULT_AUDIO_WS_PATH}`;
+    registerAudioWsRoute(app, audioPath, upgradeWebSocket, {
+      ai: options.audio.ai,
+      verifyTicket: options.audio.verifyTicket,
+      authorize: options.audio.authorize,
+      onSessionEnd: options.audio.onSessionEnd,
+      maxMessageBytes: options.audio.maxMessageBytes,
+      maxBufferedBytes: options.audio.maxBufferedBytes,
+      maxTextBytes: options.audio.maxTextBytes,
+      maxSessionMs: options.audio.maxSessionMs
+    });
+    audioWsInjectors.set(app, injectWebSocket);
+  }
   mountOpenAPIRoutes(app, options.procedures, http.apiPrefix, createContext);
   if (http.rpc !== false)
     mountRPCRoutes(app, options.procedures, http.rpc, createContext);
@@ -779,6 +1086,61 @@ function isOrpcValidationErrorPayload(value) {
   return Array.isArray(issues);
 }
 
+// src/adapters/serv-adapter-node.ts
+var DEFAULT_SERV_HOST = "127.0.0.1";
+var DEFAULT_SERV_PORT = 3e3;
+function listen(app, options = {}) {
+  const host = options.host ?? process2.env.HOST ?? DEFAULT_SERV_HOST;
+  const port = options.port ?? (process2.env.PORT ? Number(process2.env.PORT) : DEFAULT_SERV_PORT);
+  const server = serve(
+    { fetch: app.fetch, hostname: host, port },
+    options.onListening
+  );
+  const injectWebSocket = audioWsInjectors.get(app);
+  if (injectWebSocket)
+    injectWebSocket(server);
+  const handle = {
+    server,
+    address: { host, port },
+    close: () => new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error)
+          reject(error);
+        else resolve();
+      });
+    })
+  };
+  if (options.onClose) {
+    const onClose = options.onClose;
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown)
+        return;
+      shuttingDown = true;
+      try {
+        await handle.close();
+      } catch {
+      }
+      try {
+        await onClose();
+      } catch {
+      }
+    };
+    process2.once("SIGINT", () => void shutdown());
+    process2.once("SIGTERM", () => void shutdown());
+  }
+  return handle;
+}
+var WILDCARD_ROLE = "*";
+function requireRole(role, handler) {
+  return requireAuth(async (options) => {
+    const roles = options.context.session?.roles ?? [];
+    if (!roles.includes(role) && !roles.includes(WILDCARD_ROLE))
+      return err(HaiCommonError.FORBIDDEN, servM("serv_errorForbidden", { locale: options.context.locale }));
+    return handler(options);
+  });
+}
+
 // src/serv-cors.ts
 var DEFAULT_CORS_METHODS = ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE", "OPTIONS"];
 var DEFAULT_CORS_ALLOWED_HEADERS = ["Authorization", "Content-Type", "X-Requested-With"];