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

package/dist/index.js

@@ -3,6 +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, 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';
@@ -10,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';
@@ -30,19 +30,33 @@ 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 maxTextBytes = deps.maxTextBytes ?? DEFAULT_MAX_TEXT_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 ticket = c.req.query("ticket");
-    const conn = new AudioConnection(deps, ticket, maxMessageBytes, maxBufferedBytes, maxTextBytes);
+    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) {
@@ -62,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)
@@ -104,105 +125,194 @@ var AsyncQueue = class {
   }
 };
 var AudioConnection = class {
-  constructor(deps, ticket, maxMessageBytes, maxBufferedBytes, maxTextBytes) {
+  constructor(deps, ticket, limits) {
     this.deps = deps;
     this.ticket = ticket;
-    this.maxMessageBytes = maxMessageBytes;
-    this.maxBufferedBytes = maxBufferedBytes;
-    this.maxTextBytes = maxTextBytes;
+    this.limits = limits;
+    this.audioQueue = new AsyncQueue(MAX_QUEUE_ITEMS);
+    this.textQueue = new AsyncQueue(MAX_QUEUE_ITEMS);
   }
-  started = false;
+  state = "connecting";
   start;
   session;
+  grant;
   authorizedRequest;
-  audioQueue = new AsyncQueue();
-  textQueue = new AsyncQueue();
+  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();
-  /** 将消息追加到串行处理链，保证按序处理（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) });
+  /** 连接建立：立即鉴权（串行链首个任务）并启动预鉴权超时。 */
+  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.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);
+      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;
     }
-    if (!this.ticket) {
-      this.fail(ws, "hai:ai:054", "missing audio ticket");
+    if (this.state !== "awaiting_start") {
+      this.fail(ws, CODE_PROTOCOL, "session already started");
       return;
     }
-    const verified = await this.deps.verifyTicket(this.ticket);
-    if (!verified.success) {
-      this.fail(ws, String(verified.error.code), verified.error.message);
+    const session = this.session;
+    if (!session) {
+      this.fail(ws, CODE_TICKET, "not authenticated");
       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 } };
+    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;
@@ -216,14 +326,30 @@ var AudioConnection = class {
       format: authorized.data.format,
       sampleRate: authorized.data.sampleRate
     };
-    this.started = true;
     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 (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) {
     try {
@@ -240,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")
@@ -270,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;
@@ -280,7 +410,7 @@ var AudioConnection = class {
       this.failFromError(ws, error);
     }
   }
-  /** 语音合成：桥接文本输入，流式返回音频二进制帧 */
+  /** 语音合成：桥接文本输入，流式返回音频二进制帧（带发送缓冲背压） */
   async runSynthesize(ws, start) {
     try {
       const stream = this.deps.ai.audio.synthesizeStream({
@@ -293,10 +423,17 @@ var AudioConnection = class {
         signal: this.controller.signal
       });
       for await (const event of stream) {
-        if (event.type === "audio")
+        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
+        } else {
           this.send(ws, event);
+        }
       }
       this.end(ws);
     } catch (error) {
@@ -304,17 +441,25 @@ var AudioConnection = class {
     }
   }
   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();
@@ -327,6 +472,12 @@ 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();
@@ -337,6 +488,10 @@ var AudioConnection = class {
     }
   }
 };
+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;
@@ -928,7 +1083,6 @@ 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) {
@@ -966,7 +1120,7 @@ function createApp(options) {
     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}`;
+    const audioPath = `${http.apiPrefix}${options.audio.path ?? AUDIO_WS_PATH}`;
     registerAudioWsRoute(app, audioPath, upgradeWebSocket, {
       ai: options.audio.ai,
       verifyTicket: options.audio.verifyTicket,
@@ -975,7 +1129,10 @@ function createApp(options) {
       maxMessageBytes: options.audio.maxMessageBytes,
       maxBufferedBytes: options.audio.maxBufferedBytes,
       maxTextBytes: options.audio.maxTextBytes,
-      maxSessionMs: options.audio.maxSessionMs
+      maxSessionMs: options.audio.maxSessionMs,
+      preAuthTimeoutMs: options.audio.preAuthTimeoutMs,
+      maxPendingMessages: options.audio.maxPendingMessages,
+      maxSendBufferBytes: options.audio.maxSendBufferBytes
     });
     audioWsInjectors.set(app, injectWebSocket);
   }