@h-ai/serv 0.1.0-alpha.35 → 0.1.0-alpha.37

package/dist/index.js

@@ -3,7 +3,7 @@ import { servM, mapHaiError, requireAuth, normalizeServLocale, buildHaiErrorBody
 import { implement } from '@orpc/server';
 import process2 from 'process';
 import { serve } from '@hono/node-server';
-import { AUDIO_WS_PATH } from '@h-ai/ai';
+import { AUDIO_WS_PATH, IAM_AUTH_ROUTES, AudioWsClientMessageSchema } from '@h-ai/api-contract';
 import { core, ok, err, HaiCommonError } from '@h-ai/core';
 import { createNodeWebSocket } from '@hono/node-ws';
 import { OpenAPIHandler } from '@orpc/openapi/fetch';
@@ -11,7 +11,6 @@ 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';
 import { readFile } from 'fs/promises';
 import { OpenAPIGenerator } from '@orpc/openapi';
@@ -29,25 +28,39 @@ function toFetch(app) {
 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;
+var DEFAULT_PRE_AUTH_TIMEOUT_MS = 5e3;
+var DEFAULT_MAX_PENDING_MESSAGES = 256;
+var DEFAULT_MAX_SEND_BUFFER_BYTES = 8 * 1024 * 1024;
+var MAX_QUEUE_ITEMS = 4096;
+var CODE_PROTOCOL = "hai:ai:050";
+var CODE_TICKET = "hai:ai:054";
+var CODE_TOO_LARGE = "hai:ai:058";
+var CODE_TIMEOUT = "hai:ai:057";
 function registerAudioWsRoute(app, path, upgradeWebSocket, deps) {
-  const maxMessageBytes = deps.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
-  const maxBufferedBytes = deps.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+  const limits = {
+    maxMessageBytes: deps.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES,
+    maxBufferedBytes: deps.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES,
+    maxTextBytes: deps.maxTextBytes ?? DEFAULT_MAX_TEXT_BYTES,
+    maxPendingMessages: deps.maxPendingMessages ?? DEFAULT_MAX_PENDING_MESSAGES,
+    maxSendBufferBytes: deps.maxSendBufferBytes ?? DEFAULT_MAX_SEND_BUFFER_BYTES
+  };
   const maxSessionMs = deps.maxSessionMs ?? DEFAULT_MAX_SESSION_MS;
+  const preAuthTimeoutMs = deps.preAuthTimeoutMs ?? DEFAULT_PRE_AUTH_TIMEOUT_MS;
   app.get(path, upgradeWebSocket((c) => {
-    const token = c.req.query("access_token") ?? c.req.header("authorization")?.replace(/^Bearer\s+/i, "");
-    const conn = new AudioConnection(deps, token, maxMessageBytes, maxBufferedBytes);
+    const ticket = c.req.query("ticket");
+    const conn = new AudioConnection(deps, ticket, limits);
     let sessionTimer;
     return {
       onOpen(_evt, ws) {
+        conn.begin(ws, preAuthTimeoutMs);
         sessionTimer = setTimeout(() => {
-          conn.fail(ws, "hai:ai:057", "audio session timeout");
+          conn.fail(ws, CODE_TIMEOUT, "audio session timeout");
         }, maxSessionMs);
       },
       onMessage(evt, ws) {
-        conn.handleMessage(ws, evt.data).catch((error) => {
-          logger.debug("audio ws message handling failed", { error: error instanceof Error ? error.message : String(error) });
-        });
+        conn.enqueue(ws, evt.data);
       },
       onClose() {
         if (sessionTimer)
@@ -63,19 +76,26 @@ function registerAudioWsRoute(app, path, upgradeWebSocket, deps) {
   }));
 }
 var AsyncQueue = class {
+  constructor(maxItems) {
+    this.maxItems = maxItems;
+  }
   items = [];
   waiting = null;
   ended = false;
+  /** 入队；超过上限返回 false（背压信号，调用方据此关闭连接）。 */
   push(item) {
     if (this.ended)
-      return;
+      return true;
     if (this.waiting) {
       const w = this.waiting;
       this.waiting = null;
       w({ value: item, done: false });
-    } else {
-      this.items.push(item);
+      return true;
     }
+    if (this.items.length >= this.maxItems)
+      return false;
+    this.items.push(item);
+    return true;
   }
   end() {
     if (this.ended)
@@ -105,92 +125,230 @@ var AsyncQueue = class {
   }
 };
 var AudioConnection = class {
-  constructor(deps, token, maxMessageBytes, maxBufferedBytes) {
+  constructor(deps, ticket, limits) {
     this.deps = deps;
-    this.token = token;
-    this.maxMessageBytes = maxMessageBytes;
-    this.maxBufferedBytes = maxBufferedBytes;
+    this.ticket = ticket;
+    this.limits = limits;
+    this.audioQueue = new AsyncQueue(MAX_QUEUE_ITEMS);
+    this.textQueue = new AsyncQueue(MAX_QUEUE_ITEMS);
   }
-  started = false;
+  state = "connecting";
   start;
-  audioQueue = new AsyncQueue();
-  textQueue = new AsyncQueue();
+  session;
+  grant;
+  authorizedRequest;
+  doneReceived = false;
+  audioQueue;
+  textQueue;
   audioBuffer = [];
   receivedBytes = 0;
+  receivedTextBytes = 0;
+  /** 合成文本段 ID 去重（同一会话内唯一）。 */
+  seenSegmentIds = /* @__PURE__ */ new Set();
   controller = new AbortController();
   closed = false;
+  preAuthTimer;
+  /** 待处理消息数（含鉴权任务）：积压过多即关闭。 */
+  pending = 0;
+  /** 消息串行处理链：确保同一连接的消息按到达顺序处理，鉴权完成前不处理业务帧。 */
+  queue = Promise.resolve();
+  /** 连接建立：立即鉴权（串行链首个任务）并启动预鉴权超时。 */
+  begin(ws, preAuthTimeoutMs) {
+    this.preAuthTimer = setTimeout(() => {
+      if (this.state === "connecting" || this.state === "authenticated" || this.state === "awaiting_start")
+        this.fail(ws, CODE_TIMEOUT, "pre-auth timeout: authenticate and send start in time");
+    }, preAuthTimeoutMs);
+    this.chain(ws, () => this.authenticate(ws));
+  }
+  /** 将任务追加到串行处理链（含积压上限保护）。 */
+  chain(ws, task) {
+    if (this.closed)
+      return;
+    this.pending++;
+    if (this.pending > this.limits.maxPendingMessages) {
+      this.pending--;
+      this.fail(ws, CODE_TOO_LARGE, "too many pending messages");
+      return;
+    }
+    this.queue = this.queue.then(() => task()).catch((error) => {
+      logger.debug("audio ws task failed", { error: error instanceof Error ? error.message : String(error) });
+      if (!this.closed)
+        this.failFromError(ws, error);
+    }).finally(() => {
+      this.pending--;
+    });
+  }
+  /** 将消息追加到串行处理链，保证按序处理（鉴权完成前不处理业务帧）。 */
+  enqueue(ws, data) {
+    this.chain(ws, () => this.handleMessage(ws, data));
+  }
+  /** 连接建立即执行：校验并原子消费 ticket，成功后进入 awaiting_start。 */
+  async authenticate(ws) {
+    if (this.closed)
+      return;
+    if (!this.ticket) {
+      this.fail(ws, CODE_TICKET, "missing audio ticket");
+      return;
+    }
+    const verified = await this.deps.verifyTicket(this.ticket);
+    if (this.closed)
+      return;
+    if (!verified.success) {
+      this.fail(ws, String(verified.error.code), verified.error.message);
+      return;
+    }
+    this.session = verified.data.session;
+    this.grant = verified.data.grant;
+    this.state = "awaiting_start";
+  }
   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;
-      }
-      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);
+      this.handleAudioFrame(ws, bytes);
       return;
     }
     if (typeof data !== "string")
       return;
-    if (data.length > this.maxMessageBytes) {
-      this.fail(ws, "hai:ai:058", "message too large");
+    if (Buffer.byteLength(data, "utf8") > this.limits.maxMessageBytes) {
+      this.fail(ws, CODE_TOO_LARGE, "message too large");
       return;
     }
-    let message;
+    let raw;
     try {
-      message = JSON.parse(data);
+      raw = JSON.parse(data);
     } catch {
-      this.fail(ws, "hai:ai:050", "invalid json message");
+      this.fail(ws, CODE_PROTOCOL, "invalid json message");
+      return;
+    }
+    const parsed = AudioWsClientMessageSchema.safeParse(raw);
+    if (!parsed.success) {
+      this.fail(ws, CODE_PROTOCOL, `invalid message: ${parsed.error.issues[0]?.message ?? "schema validation failed"}`);
       return;
     }
+    const message = parsed.data;
     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.textQueue.push(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);
+      return;
+    }
+    if (this.state === "connecting" || this.state === "authenticated" || this.state === "awaiting_start") {
+      this.fail(ws, CODE_PROTOCOL, "message before start");
+      return;
+    }
+    if (message.type === "text")
+      this.handleTextFrame(ws, message);
+    else if (message.type === "done")
+      this.handleDone(ws);
+  }
+  /** 处理音频二进制帧（仅识别操作、输入未结束时接受）。 */
+  handleAudioFrame(ws, bytes) {
+    if (this.state !== "transcribing") {
+      this.fail(ws, CODE_PROTOCOL, "unexpected audio frame");
+      return;
+    }
+    if (bytes.length > this.limits.maxMessageBytes) {
+      this.fail(ws, CODE_TOO_LARGE, "audio frame too large");
+      return;
+    }
+    this.receivedBytes += bytes.length;
+    if (this.receivedBytes > this.limits.maxBufferedBytes) {
+      this.fail(ws, CODE_TOO_LARGE, "buffered audio exceeds limit");
+      return;
+    }
+    if (this.start?.stream) {
+      if (!this.audioQueue.push(bytes))
+        this.fail(ws, CODE_TOO_LARGE, "audio backpressure limit exceeded");
+    } else {
+      this.audioBuffer.push(bytes);
     }
   }
+  /** 处理文本控制帧（仅合成操作、输入未结束时接受；segmentId 唯一）。 */
+  handleTextFrame(ws, message) {
+    if (this.state !== "synthesizing") {
+      this.fail(ws, CODE_PROTOCOL, "unexpected text frame");
+      return;
+    }
+    if (this.seenSegmentIds.has(message.segmentId)) {
+      this.fail(ws, CODE_PROTOCOL, `duplicate segmentId: ${message.segmentId}`);
+      return;
+    }
+    this.receivedTextBytes += Buffer.byteLength(message.text, "utf8");
+    if (this.receivedTextBytes > this.limits.maxTextBytes) {
+      this.fail(ws, CODE_TOO_LARGE, "buffered text exceeds limit");
+      return;
+    }
+    this.seenSegmentIds.add(message.segmentId);
+    if (!this.textQueue.push({ id: message.segmentId, text: message.text }))
+      this.fail(ws, CODE_TOO_LARGE, "text backpressure limit exceeded");
+  }
+  /** 处理输入结束帧（只允许一次）。 */
+  handleDone(ws) {
+    if (this.doneReceived) {
+      this.fail(ws, CODE_PROTOCOL, "duplicate done");
+      return;
+    }
+    this.doneReceived = true;
+    this.audioQueue.end();
+    this.textQueue.end();
+    if (this.state === "transcribing" || this.state === "synthesizing")
+      this.state = "input_completed";
+    if (this.start && !this.start.stream && this.start.operation === "transcribe")
+      void this.runBufferedTranscribe(ws);
+  }
   async onStart(ws, message) {
-    if (this.started) {
-      this.fail(ws, "hai:ai:050", "session already started");
+    if (this.state === "connecting" || this.state === "authenticated") {
+      this.fail(ws, CODE_TICKET, "not authenticated");
       return;
     }
-    this.started = true;
-    this.start = message;
-    if (this.deps.verifyToken) {
-      if (!this.token) {
-        this.fail(ws, "hai:ai:054", "missing access token");
-        return;
-      }
-      const auth = await this.deps.verifyToken(this.token);
-      if (!auth.success) {
-        this.fail(ws, "hai:ai:054", "unauthorized");
-        return;
-      }
+    if (this.state !== "awaiting_start") {
+      this.fail(ws, CODE_PROTOCOL, "session already started");
+      return;
+    }
+    const session = this.session;
+    if (!session) {
+      this.fail(ws, CODE_TICKET, "not authenticated");
+      return;
+    }
+    const authorized = this.deps.authorize ? await this.deps.authorize(session, message, this.grant) : this.defaultAuthorize(message);
+    if (this.closed)
+      return;
+    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
+    };
+    this.start = confirmed;
+    this.authorizedRequest = authorized.data;
+    this.state = confirmed.operation === "synthesize" ? "synthesizing" : "transcribing";
+    if (this.preAuthTimer) {
+      clearTimeout(this.preAuthTimer);
+      this.preAuthTimer = void 0;
     }
-    if (message.operation === "synthesize")
-      void this.runSynthesize(ws, message);
-    else if (message.operation === "transcribe" && message.stream)
-      void this.runStreamTranscribe(ws, message);
+    if (confirmed.operation === "synthesize")
+      void this.runSynthesize(ws, confirmed);
+    else if (confirmed.operation === "transcribe" && confirmed.stream)
+      void this.runStreamTranscribe(ws, confirmed);
+  }
+  /** 无 authorize 回调时的默认授权：仅保留操作与格式，并交叉校验票据 grant。 */
+  defaultAuthorize(message) {
+    if (this.grant?.operation && this.grant.operation !== message.operation) {
+      return err(HaiCommonError.FORBIDDEN, "operation not permitted by ticket");
+    }
+    return ok({
+      operation: message.operation,
+      // 无 authorize 回调时不透传客户端 model/voice/instruction；仅采用票据 grant 绑定的 model
+      model: this.grant?.model,
+      format: message.format
+    });
   }
   /** 流式识别：桥接持续音频输入，流式返回临时/最终结果与语音起止事件 */
   async runStreamTranscribe(ws, start) {
@@ -208,6 +366,8 @@ var AudioConnection = class {
         signal: this.controller.signal
       });
       for await (const event of stream) {
+        if (this.closed)
+          return;
         if (event.type === "transcript")
           this.send(ws, { type: "transcript", text: event.text, final: event.final });
         else if (event.type === "speech_started")
@@ -238,6 +398,8 @@ var AudioConnection = class {
         model: start.model,
         signal: this.controller.signal
       });
+      if (this.closed)
+        return;
       if (!result.success) {
         this.fail(ws, String(result.error.code), result.error.message);
         return;
@@ -248,7 +410,7 @@ var AudioConnection = class {
       this.failFromError(ws, error);
     }
   }
-  /** 语音合成：桥接文本输入，流式返回音频二进制帧 */
+  /** 语音合成：桥接文本输入，流式返回音频二进制帧（带发送缓冲背压） */
   async runSynthesize(ws, start) {
     try {
       const stream = this.deps.ai.audio.synthesizeStream({
@@ -260,25 +422,44 @@ var AudioConnection = class {
         model: start.model,
         signal: this.controller.signal
       });
-      for await (const audio of stream)
-        ws.send(toArrayBuffer(audio));
+      for await (const event of stream) {
+        if (this.closed)
+          return;
+        if (event.type === "audio") {
+          if (sendBufferedAmount(ws) > this.limits.maxSendBufferBytes) {
+            this.fail(ws, CODE_TOO_LARGE, "client send buffer exceeded high-water mark");
+            return;
+          }
+          ws.send(toArrayBuffer(event.data));
+        } else {
+          this.send(ws, event);
+        }
+      }
       this.end(ws);
     } catch (error) {
       this.failFromError(ws, error);
     }
   }
   fail(ws, code, message) {
+    if (this.closed)
+      return;
+    this.state = "failed";
     this.send(ws, { type: "error", code, message });
     this.dispose();
     ws.close();
   }
   failFromError(ws, error) {
+    if (this.closed)
+      return;
     const hai = error;
-    const code = typeof hai?.code === "string" ? hai.code : "hai:ai:054";
+    const code = typeof hai?.code === "string" ? hai.code : CODE_TICKET;
     const message = error instanceof Error ? error.message : String(error);
     this.fail(ws, code, message);
   }
   end(ws) {
+    if (this.closed)
+      return;
+    this.state = "completed";
     this.send(ws, { type: "end" });
     this.dispose();
     ws.close();
@@ -291,11 +472,26 @@ var AudioConnection = class {
     if (this.closed)
       return;
     this.closed = true;
+    if (this.state !== "completed" && this.state !== "failed")
+      this.state = "cancelled";
+    if (this.preAuthTimer) {
+      clearTimeout(this.preAuthTimer);
+      this.preAuthTimer = void 0;
+    }
     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 sendBufferedAmount(ws) {
+  const raw = ws.raw;
+  return typeof raw?.bufferedAmount === "number" ? raw.bufferedAmount : 0;
+}
 function toBytes(data) {
   if (typeof data === "string")
     return void 0;
@@ -927,10 +1123,16 @@ function createApp(options) {
     const audioPath = `${http.apiPrefix}${options.audio.path ?? AUDIO_WS_PATH}`;
     registerAudioWsRoute(app, audioPath, upgradeWebSocket, {
       ai: options.audio.ai,
-      verifyToken,
+      verifyTicket: options.audio.verifyTicket,
+      authorize: options.audio.authorize,
+      onSessionEnd: options.audio.onSessionEnd,
       maxMessageBytes: options.audio.maxMessageBytes,
       maxBufferedBytes: options.audio.maxBufferedBytes,
-      maxSessionMs: options.audio.maxSessionMs
+      maxTextBytes: options.audio.maxTextBytes,
+      maxSessionMs: options.audio.maxSessionMs,
+      preAuthTimeoutMs: options.audio.preAuthTimeoutMs,
+      maxPendingMessages: options.audio.maxPendingMessages,
+      maxSendBufferBytes: options.audio.maxSendBufferBytes
     });
     audioWsInjectors.set(app, injectWebSocket);
   }