tina4-nodejs 3.13.141 → 3.13.142

package/packages/core/gallery/queue/src/lib/queueDb.ts

@@ -38,3 +38,14 @@ export async function getQueueDb(): Promise<DatabaseAdapter> {
 export function now(): string {
   return new Date().toISOString();
 }
+
+/**
+ * Claim the next pending message for a topic — highest priority first, then
+ * the oldest (lowest id). The `LIMIT 1` bounds the work: without it SQLite
+ * sorts the WHOLE pending backlog on every consume call before `fetchOne`
+ * reads a single row (carbonah E003, an unbounded query on a hot path). One
+ * row asked for, one row returned. Shared by the consume and fail routes so
+ * the claim query lives in exactly one place.
+ */
+export const CLAIM_NEXT_PENDING_SQL =
+  "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC LIMIT 1";

package/packages/core/gallery/queue/src/routes/api/gallery/queue/consume/post.ts

@@ -8,17 +8,14 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 /** Gallery: Queue — consume (complete) the next pending message. */
 import type { Tina4Request, Tina4Response } from "tina4-nodejs";
-import { getQueueDb, now } from "../../../../lib/queueDb.js";
+import { getQueueDb, now, CLAIM_NEXT_PENDING_SQL } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   try {
     const db = await getQueueDb();
     const ts = now();
 
-    const row = db.fetchOne<Record<string, unknown>>(
-      "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC",
-      ["gallery-tasks", ts]
-    );
+    const row = db.fetchOne<Record<string, unknown>>(CLAIM_NEXT_PENDING_SQL, ["gallery-tasks", ts]);
 
     if (!row) {
       return res.json({ consumed: false, message: "No pending messages to consume" });

package/packages/core/gallery/queue/src/routes/api/gallery/queue/fail/post.ts

@@ -8,17 +8,14 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
 
 /** Gallery: Queue — deliberately fail the next pending message. */
 import type { Tina4Request, Tina4Response } from "tina4-nodejs";
-import { getQueueDb, now } from "../../../../lib/queueDb.js";
+import { getQueueDb, now, CLAIM_NEXT_PENDING_SQL } from "../../../../lib/queueDb.js";
 
 export default async function (_req: Tina4Request, res: Tina4Response) {
   try {
     const db = await getQueueDb();
     const ts = now();
 
-    const row = db.fetchOne<Record<string, unknown>>(
-      "SELECT * FROM tina4_queue WHERE topic = ? AND status = 'pending' AND available_at <= ? ORDER BY priority DESC, id ASC",
-      ["gallery-tasks", ts]
-    );
+    const row = db.fetchOne<Record<string, unknown>>(CLAIM_NEXT_PENDING_SQL, ["gallery-tasks", ts]);
 
     if (!row) {
       return res.json({ failed: false, message: "No pending messages to fail" });

package/packages/core/src/devAdmin.ts

@@ -24,6 +24,7 @@ import { fileURLToPath } from "node:url";
 import type { Router } from "./router.js";
 import type { RouteHandler, Tina4Request } from "./types.js";
 import { DevMailbox } from "./devMailbox.js";
+import { relayUpstreamResponse } from "./upstreamResponse.js";
 import { isTruthy } from "./dotenv.js";
 import { fullAnalysis, fileDetail, MetricsEngineError, metricsScanRoot } from "./metrics.js";
 import { registerFeedbackRoutes } from "./feedback.js";
@@ -1682,18 +1683,8 @@ async function proxyToSupervisor(
 
   clearTimeout(timer);
 
-  // JSON / other — drain the body and return as before.
-  const raw = await upstream.text();
-  const status = upstream.status || 200;
-  try {
-    res.json(JSON.parse(raw), status);
-  } catch {
-    // Non-JSON upstream — pass through as text with the same status.
-    res.raw.writeHead(status, {
-      "Content-Type": upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
-    });
-    res.raw.end(raw);
-  }
+  // JSON / other — drain the body and relay with the upstream status.
+  await relayUpstreamResponse(res, upstream);
 }
 
 // -- Framework-grounding (mcp.tina4.com) token config --

package/packages/core/src/dispatchPipeline.ts

@@ -42,6 +42,7 @@ import { createHash } from "node:crypto";
 import type { Tina4Request } from "./types.js";
 import type { Session as SessionInstance } from "./session.js";
 import { Log } from "./logger.js";
+import { etagMatches } from "./etag.js";
 
 /**
  * The prologue, in order. Exported as DATA so the pipeline can be asserted and
@@ -197,23 +198,6 @@ function isCompressibleContentType(contentType: string): boolean {
   return COMPRESSIBLE_PREFIXES.some((prefix) => contentType.includes(prefix));
 }
 
-/**
- * Match an If-None-Match header value against `etag` (RFC 7232 S3.2 weak
- * comparison): an optional W/ prefix is ignored on both sides, the header may
- * carry a comma-separated candidate list, and `*` matches any current
- * representation. Same algorithm as static.ts's own matcher (kept local here
- * rather than imported, since static.ts writes to the raw response directly
- * and never reaches this interceptor).
- */
-function etagMatchesInm(ifNoneMatch: string, etag: string): boolean {
-  const strip = (tag: string) => tag.trim().replace(/^W\//, "");
-  const target = strip(etag);
-  return ifNoneMatch.split(",").some((candidate) => {
-    const trimmed = candidate.trim();
-    return trimmed === "*" || strip(trimmed) === target;
-  });
-}
-
 function maybeCompressResponse(body: Buffer, rawReq: IncomingMessage, rawRes: ServerResponse): Buffer {
   const acceptEncoding = String(rawReq.headers["accept-encoding"] ?? "");
   const contentTypeHeader = rawRes.getHeader("content-type");
@@ -230,7 +214,7 @@ function maybeCompressResponse(body: Buffer, rawReq: IncomingMessage, rawRes: Se
 
 function responseIsNotModified(rawReq: IncomingMessage, rawRes: ServerResponse, etag: string): boolean {
   const ifNoneMatch = String(rawReq.headers["if-none-match"] ?? "");
-  if (ifNoneMatch) return etagMatchesInm(ifNoneMatch, etag);
+  if (ifNoneMatch) return etagMatches(ifNoneMatch, etag);
   const lastModifiedHeader = rawRes.getHeader("last-modified");
   if (typeof lastModifiedHeader !== "string") return false;
   const ifModifiedSince = String(rawReq.headers["if-modified-since"] ?? "");

package/packages/core/src/etag.ts

@@ -0,0 +1,24 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Does an `If-None-Match` header match the response ETag?
+ *
+ * The header may be `*`, a single tag, or a comma-separated list; the `W/`
+ * weak prefix is stripped on both sides before comparing (RFC 7232 §2.3.2
+ * weak comparison). Shared by the static file server and the compression
+ * interceptor so both answer 304 the same way.
+ */
+export function etagMatches(ifNoneMatch: string, etag: string): boolean {
+  const strip = (tag: string) => tag.trim().replace(/^W\//, "");
+  const target = strip(etag);
+  return ifNoneMatch.split(",").some((candidate) => {
+    const trimmed = candidate.trim();
+    return trimmed === "*" || strip(trimmed) === target;
+  });
+}

package/packages/core/src/feedback.ts

@@ -36,6 +36,7 @@ import { fileURLToPath } from "node:url";
 
 import { authenticateRequest } from "./auth.js";
 import { supervisorBaseUrl } from "./devAdmin.js";
+import { relayUpstreamResponse } from "./upstreamResponse.js";
 import type { RouteHandler, Tina4Request } from "./types.js";
 import type { Router } from "./router.js";
 
@@ -221,17 +222,7 @@ export const handleFeedbackTurn: RouteHandler = async (req, res) => {
   }
   clearTimeout(timer);
 
-  const raw = await upstream.text();
-  const status = upstream.status || 200;
-  try {
-    res.json(JSON.parse(raw), status);
-  } catch {
-    res.raw.writeHead(status, {
-      "Content-Type":
-        upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
-    });
-    res.raw.end(raw);
-  }
+  await relayUpstreamResponse(res, upstream);
 };
 
 // Widget bundle lives at packages/core/src/__feedback/widget.js so that

package/packages/core/src/session.ts

@@ -37,7 +37,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, readdir
 import { join } from "node:path";
 import { Log } from "./logger.js";
 import { isTruthy } from "./dotenv.js";
-import { respCommandSync } from "./sessionHandlers/respClient.js";
+import { RespSessionHandler } from "./sessionHandlers/respSessionHandler.js";
 import { ValkeySessionHandler } from "./sessionHandlers/valkeyHandler.js";
 import { MemcachedSessionHandler } from "./sessionHandlers/memcachedHandler.js";
 import { MongoSessionHandler } from "./sessionHandlers/mongoHandler.js";
@@ -304,75 +304,31 @@ export class FileSessionHandler implements SessionHandler {
  *
  * Or pass via SessionConfig.
  */
-export class RedisSessionHandler implements SessionHandler {
-  private host: string;
-  private port: number;
-  private password: string;
-  private prefix: string;
-  private db: number;
-
+export class RedisSessionHandler extends RespSessionHandler {
   constructor(config?: SessionConfig) {
-    this.host = config?.redisHost
-      ?? process.env.TINA4_SESSION_REDIS_HOST
-      ?? "127.0.0.1";
-    this.port = config?.redisPort
-      ?? (process.env.TINA4_SESSION_REDIS_PORT
-        ? parseInt(process.env.TINA4_SESSION_REDIS_PORT, 10)
-        : 6379);
-    this.password = config?.redisPassword
-      ?? process.env.TINA4_SESSION_REDIS_PASSWORD
-      ?? "";
-    this.prefix = config?.redisPrefix
-      ?? process.env.TINA4_SESSION_REDIS_PREFIX
-      ?? "tina4:session:";
-    this.db = config?.redisDb
-      ?? (process.env.TINA4_SESSION_REDIS_DB
-        ? parseInt(process.env.TINA4_SESSION_REDIS_DB, 10)
-        : 0);
-  }
-
-  /**
-   * Execute a Redis command synchronously against the live server.
-   *
-   * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
-   * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
-   * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
-   * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
-   */
-  private execSync(args: string[]): string {
-    return respCommandSync(
-      { host: this.host, port: this.port, password: this.password, db: this.db },
-      args,
+    super(
+      {
+        host: config?.redisHost
+          ?? process.env.TINA4_SESSION_REDIS_HOST
+          ?? "127.0.0.1",
+        port: config?.redisPort
+          ?? (process.env.TINA4_SESSION_REDIS_PORT
+            ? parseInt(process.env.TINA4_SESSION_REDIS_PORT, 10)
+            : 6379),
+        password: config?.redisPassword
+          ?? process.env.TINA4_SESSION_REDIS_PASSWORD
+          ?? "",
+        prefix: config?.redisPrefix
+          ?? process.env.TINA4_SESSION_REDIS_PREFIX
+          ?? "tina4:session:",
+        db: config?.redisDb
+          ?? (process.env.TINA4_SESSION_REDIS_DB
+            ? parseInt(process.env.TINA4_SESSION_REDIS_DB, 10)
+            : 0),
+      },
       "Redis",
     );
   }
-
-  private key(sessionId: string): string {
-    return `${this.prefix}${sessionId}`;
-  }
-
-  read(sessionId: string): SessionData | null {
-    const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
-    try {
-      return JSON.parse(raw) as SessionData;
-    } catch {
-      return null;
-    }
-  }
-
-  write(sessionId: string, data: SessionData, ttl: number = 0): void {
-    const json = JSON.stringify(data);
-    if (ttl > 0) {
-      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
-    } else {
-      this.execSync(["SET", this.key(sessionId), json]);
-    }
-  }
-
-  destroy(sessionId: string): void {
-    this.execSync(["DEL", this.key(sessionId)]);
-  }
 }
 
 // ── Flash data prefix ─────────────────────────────────────────────

package/packages/core/src/sessionHandlers/respSessionHandler.ts

@@ -0,0 +1,94 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+/**
+ * Tina4 RESP Session Handler base — the shared store logic behind Redis and
+ * Valkey, zero dependencies.
+ *
+ * Redis and Valkey speak the same RESP protocol, so the read/write/destroy
+ * transport is byte-for-byte identical between them — only the configuration
+ * variable names and the log label differ. That difference lives entirely in
+ * each subclass constructor; everything the session store actually DOES lives
+ * here, once. A subclass resolves its own host/port/password/prefix/db from
+ * config or environment, then hands a {@link RespConnection} plus a label to
+ * `super()`.
+ */
+import type { SessionHandler } from "../session.js";
+import { respCommandSync } from "./respClient.js";
+
+interface SessionData {
+  _created: number;
+  _accessed: number;
+  [key: string]: unknown;
+}
+
+/** Resolved connection details a RESP session handler needs. */
+export interface RespConnection {
+  host: string;
+  port: number;
+  password: string;
+  prefix: string;
+  db: number;
+}
+
+/**
+ * RESP (Redis/Valkey) session handler using raw TCP — no external client.
+ *
+ * Stores session data as JSON strings with a server-side TTL for automatic
+ * expiry. A genuine key miss yields `null`; a transport/connection FAILURE
+ * (server unreachable, rejected AUTH, timeout) THROWS so the Session boundary
+ * can tell "not found" (silent) from "backend failed" (log-loud + degrade).
+ */
+export abstract class RespSessionHandler implements SessionHandler {
+  protected constructor(
+    private readonly conn: RespConnection,
+    private readonly label: string,
+  ) {}
+
+  /**
+   * Execute a RESP command synchronously against the live server.
+   *
+   * Delegates to the shared {@link respCommandSync} transport: a genuine key
+   * miss yields `""`, and a transport/connection FAILURE THROWS so the caller
+   * can distinguish "not found" from "backend failed". Backend-failure parity.
+   */
+  private execSync(args: string[]): string {
+    return respCommandSync(
+      { host: this.conn.host, port: this.conn.port, password: this.conn.password, db: this.conn.db },
+      args,
+      this.label,
+    );
+  }
+
+  private key(sessionId: string): string {
+    return `${this.conn.prefix}${sessionId}`;
+  }
+
+  read(sessionId: string): SessionData | null {
+    const raw = this.execSync(["GET", this.key(sessionId)]);
+    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
+    try {
+      return JSON.parse(raw) as SessionData;
+    } catch {
+      return null;
+    }
+  }
+
+  write(sessionId: string, data: SessionData, ttl: number = 0): void {
+    const json = JSON.stringify(data);
+    if (ttl > 0) {
+      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
+    } else {
+      this.execSync(["SET", this.key(sessionId), json]);
+    }
+  }
+
+  destroy(sessionId: string): void {
+    this.execSync(["DEL", this.key(sessionId)]);
+  }
+}

package/packages/core/src/sessionHandlers/valkeyHandler.ts

@@ -19,14 +19,7 @@ file, You can obtain one at https://mozilla.org/MPL/2.0/.
  *   TINA4_SESSION_VALKEY_PREFIX   (default: "tina4:session:")
  *   TINA4_SESSION_VALKEY_DB       (default: 0)
  */
-import type { SessionHandler } from "../session.js";
-import { respCommandSync } from "./respClient.js";
-
-interface SessionData {
-  _created: number;
-  _accessed: number;
-  [key: string]: unknown;
-}
+import { RespSessionHandler } from "./respSessionHandler.js";
 
 export interface ValkeySessionConfig {
   host?: string;
@@ -55,73 +48,29 @@ export interface ValkeySessionConfig {
  * Valkey uses the same RESP protocol as Redis, so this handler is functionally
  * identical to RedisSessionHandler but with VALKEY config variable names.
  */
-export class ValkeySessionHandler implements SessionHandler {
-  private host: string;
-  private port: number;
-  private password: string;
-  private prefix: string;
-  private db: number;
-
+export class ValkeySessionHandler extends RespSessionHandler {
   constructor(config?: ValkeySessionConfig) {
-    this.host = config?.host
-      ?? process.env.TINA4_SESSION_VALKEY_HOST
-      ?? "127.0.0.1";
-    this.port = config?.port
-      ?? (process.env.TINA4_SESSION_VALKEY_PORT
-        ? parseInt(process.env.TINA4_SESSION_VALKEY_PORT, 10)
-        : 6379);
-    this.password = config?.password
-      ?? process.env.TINA4_SESSION_VALKEY_PASSWORD
-      ?? "";
-    this.prefix = config?.prefix
-      ?? process.env.TINA4_SESSION_VALKEY_PREFIX
-      ?? "tina4:session:";
-    this.db = config?.db
-      ?? (process.env.TINA4_SESSION_VALKEY_DB
-        ? parseInt(process.env.TINA4_SESSION_VALKEY_DB, 10)
-        : 0);
-  }
-
-  /**
-   * Execute a RESP command synchronously against the live Valkey server.
-   *
-   * Delegates to the shared {@link respCommandSync} transport: a genuine key miss
-   * yields `""`, and a transport/connection FAILURE (server unreachable, rejected
-   * AUTH, timeout) THROWS so the Session boundary can distinguish "not found"
-   * (silent) from "backend failed" (log-loud + degrade). Backend-failure parity.
-   */
-  private execSync(args: string[]): string {
-    return respCommandSync(
-      { host: this.host, port: this.port, password: this.password, db: this.db },
-      args,
+    super(
+      {
+        host: config?.host
+          ?? process.env.TINA4_SESSION_VALKEY_HOST
+          ?? "127.0.0.1",
+        port: config?.port
+          ?? (process.env.TINA4_SESSION_VALKEY_PORT
+            ? parseInt(process.env.TINA4_SESSION_VALKEY_PORT, 10)
+            : 6379),
+        password: config?.password
+          ?? process.env.TINA4_SESSION_VALKEY_PASSWORD
+          ?? "",
+        prefix: config?.prefix
+          ?? process.env.TINA4_SESSION_VALKEY_PREFIX
+          ?? "tina4:session:",
+        db: config?.db
+          ?? (process.env.TINA4_SESSION_VALKEY_DB
+            ? parseInt(process.env.TINA4_SESSION_VALKEY_DB, 10)
+            : 0),
+      },
       "Valkey",
     );
   }
-
-  private key(sessionId: string): string {
-    return `${this.prefix}${sessionId}`;
-  }
-
-  read(sessionId: string): SessionData | null {
-    const raw = this.execSync(["GET", this.key(sessionId)]);
-    if (!raw) return null;     // key miss — normal "no session yet", NOT an error
-    try {
-      return JSON.parse(raw) as SessionData;
-    } catch {
-      return null;
-    }
-  }
-
-  write(sessionId: string, data: SessionData, ttl: number): void {
-    const json = JSON.stringify(data);
-    if (ttl > 0) {
-      this.execSync(["SETEX", this.key(sessionId), String(ttl), json]);
-    } else {
-      this.execSync(["SET", this.key(sessionId), json]);
-    }
-  }
-
-  destroy(sessionId: string): void {
-    this.execSync(["DEL", this.key(sessionId)]);
-  }
 }

package/packages/core/src/static.ts

@@ -10,6 +10,7 @@ import { readFileSync, realpathSync, statSync, type Stats } from "node:fs";
 import { join, extname, sep } from "node:path";
 import { gzipSync } from "node:zlib";
 import type { Tina4Request, Tina4Response } from "./types.js";
+import { etagMatches } from "./etag.js";
 
 /** Content-type prefixes that benefit from gzip. Mirrors the Python master's `_is_compressible`. */
 const COMPRESSIBLE_PREFIXES = [
@@ -200,16 +201,3 @@ function isNotModified(req: Tina4Request, etag: string, stat: Stats): boolean {
   return false;
 }
 
-/**
- * Weak comparison of an `If-None-Match` value against our ETag. The header may
- * be `*`, a single tag, or a comma-separated list; the `W/` weak prefix is
- * stripped on both sides before comparing (RFC 7232 §2.3.2 weak comparison).
- */
-function etagMatches(ifNoneMatch: string, etag: string): boolean {
-  const strip = (tag: string) => tag.trim().replace(/^W\//, "");
-  const target = strip(etag);
-  return ifNoneMatch.split(",").some((candidate) => {
-    const trimmed = candidate.trim();
-    return trimmed === "*" || strip(trimmed) === target;
-  });
-}

package/packages/core/src/upstreamResponse.ts

@@ -0,0 +1,31 @@
+/*
+Copyright (c) 2026 Code Infinity
+SPDX-License-Identifier: MPL-2.0
+This Source Code Form is subject to the terms of the Mozilla Public
+License, v. 2.0. If a copy of the MPL was not distributed with this
+file, You can obtain one at https://mozilla.org/MPL/2.0/.
+*/
+
+import type { Tina4Response } from "./types.js";
+
+/**
+ * Relay a drained upstream (proxied) response to the client.
+ *
+ * The body is read to a string once, then returned as JSON when it parses and
+ * as raw text with the upstream Content-Type otherwise, keeping the upstream
+ * status either way. Shared by the dev-admin supervisor proxy and the feedback
+ * agent proxy so both pass a backend response through identically.
+ */
+export async function relayUpstreamResponse(res: Tina4Response, upstream: Response): Promise<void> {
+  const raw = await upstream.text();
+  const status = upstream.status || 200;
+  try {
+    res.json(JSON.parse(raw), status);
+  } catch {
+    // Non-JSON upstream — pass through as text with the same status.
+    res.raw.writeHead(status, {
+      "Content-Type": upstream.headers.get("content-type") ?? "text/plain; charset=utf-8",
+    });
+    res.raw.end(raw);
+  }
+}

package/packages/core/src/websocket.ts

@@ -321,6 +321,33 @@ export function parseFrame(
   return { fin: !!fin, opcode, payload: Buffer.from(payload), bytesConsumed: offset + payloadLen };
 }
 
+/**
+ * Reassembles fragmented messages (RFC 6455 section 5.4). A browser sends a large message - a pasted image in a chat,
+ * base64 inside JSON - as a TEXT or BINARY frame with FIN clear, then CONTINUATION frames; control frames may arrive
+ * between the pieces. Returns a complete message when one is done, a control frame as it comes, and null while a
+ * message is still arriving. A CONTINUATION with no message started is dropped. Mirrors the Python master
+ * (tina4_python.websocket _handle_frame). One per connection.
+ */
+export class MessageAssembler {
+  private parts: Buffer[] = [];
+  private opcode = 0;
+
+  push(frame: { fin: boolean; opcode: number; payload: Buffer }): { opcode: number; payload: Buffer } | null {
+    if (frame.opcode >= 0x8) return { opcode: frame.opcode, payload: frame.payload }; // control frames are never fragmented
+    if (frame.opcode === OP_CONTINUATION) {
+      if (!this.opcode) return null;
+      this.parts.push(frame.payload);
+      if (!frame.fin) return null;
+      const whole = { opcode: this.opcode, payload: Buffer.concat(this.parts) };
+      this.parts = []; this.opcode = 0;
+      return whole;
+    }
+    if (frame.fin) { this.parts = []; this.opcode = 0; return { opcode: frame.opcode, payload: frame.payload }; }
+    this.opcode = frame.opcode; this.parts = [frame.payload];
+    return null;
+  }
+}
+
 // ── WebSocket Server ─────────────────────────────────────────
 
 export class WebSocketServer {
@@ -854,6 +881,13 @@ export class WebSocketServer {
     });
   }
 
+  private readonly assemblers = new WeakMap<WebSocketClient, MessageAssembler>();
+  private assemblerFor(client: WebSocketClient): MessageAssembler {
+    let a = this.assemblers.get(client);
+    if (!a) { a = new MessageAssembler(); this.assemblers.set(client, a); }
+    return a;
+  }
+
   private processBuffer(
     client: WebSocketClient,
     buffer: Buffer,
@@ -868,17 +902,20 @@ export class WebSocketServer {
       remaining = remaining.subarray(frame.bytesConsumed);
       client.lastActivity = Date.now(); // mark activity for the idle reaper
 
-      switch (frame.opcode) {
+      // a fragmented message is delivered once, whole (MessageAssembler)
+      const whole = this.assemblerFor(client).push(frame);
+      if (!whole) continue;
+      switch (whole.opcode) {
         case OP_TEXT:
-          this.emit("message", client, frame.payload.toString("utf-8"));
+          this.emit("message", client, whole.payload.toString("utf-8"));
           break;
 
         case OP_BINARY:
-          this.emit("message", client, frame.payload);
+          this.emit("message", client, whole.payload);
           break;
 
         case OP_PING: {
-          const pongFrame = buildFrame(OP_PONG, frame.payload);
+          const pongFrame = buildFrame(OP_PONG, whole.payload);
           try {
             client.socket.write(pongFrame);
           } catch {
@@ -1243,15 +1280,19 @@ export function serveWebSocketRoute(req: IncomingMessage, socket: Socket, head:
       .finally(() => wsRouteManager.remove(conn.id));
   };
 
+  const assembler = new MessageAssembler();
   socket.on("data", (chunk: Buffer) => {
     buffer = Buffer.concat([buffer, chunk]);
     while (buffer.length > 0) {
       const frame = parseFrame(buffer);
       if (!frame) break;
       buffer = buffer.subarray(frame.bytesConsumed);
-      switch (frame.opcode) {
+      // a fragmented message is delivered once, whole (MessageAssembler)
+      const whole = assembler.push(frame);
+      if (!whole) continue;
+      switch (whole.opcode) {
         case OP_TEXT: {
-          const text = frame.payload.toString("utf-8");
+          const text = whole.payload.toString("utf-8");
           void Promise.resolve()
             .then(() => (conn._onMessage ? conn._onMessage(text) : handler(conn, "message", text)))
             .catch((e) => Log.error(`WebSocket message handler error: ${(e as Error).message}`));
@@ -1259,7 +1300,7 @@ export function serveWebSocketRoute(req: IncomingMessage, socket: Socket, head:
         }
         case OP_PING:
           try {
-            socket.write(buildFrame(OP_PONG, frame.payload));
+            socket.write(buildFrame(OP_PONG, whole.payload));
           } catch {
             /* client gone */
           }