velocious 1.0.562 → 1.0.563

package/src/http-server/worker-handler/in-process.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import Client from "../client/index.js"
+import ClientDeliveryQueue from "../client-delivery-queue.js"
 import dispatchChannelSubscribers from "./channel-subscriber-dispatch.js"
 import Logger from "../../logger.js"
 import websocketEventsHost from "../websocket-events-host.js"
@@ -23,7 +24,7 @@ export default class VelociousHttpServerInProcessHandler {
 
     /**
      * Narrows the runtime value to the documented type.
-     * @type {Record<number, {httpClient: Client, serverClient: import("../server-client.js").default}>} */
+     * @type {Record<number, {deliveryQueue: ClientDeliveryQueue, httpClient: Client, serverClient: import("../server-client.js").default}>} */
     this.clients = {}
 
     /** @type {Set<Promise<void>>} */
@@ -56,25 +57,36 @@ export default class VelociousHttpServerInProcessHandler {
       remoteAddress: serverClient.remoteAddress
     })
 
-    let deliveryQueue = Promise.resolve()
-    const enqueueDelivery = (/** @type {() => Promise<void>} */ delivery) => {
-      deliveryQueue = deliveryQueue
-        .catch(() => {})
-        .then(delivery)
-
-      return deliveryQueue
-    }
+    const {maxBytes, maxFrames} = this.configuration.getWebsocketOutboundQueueLimits()
+    const deliveryQueue = new ClientDeliveryQueue({
+      clientCount,
+      maxBytes,
+      maxFrames,
+      onOverflow: (error) => {
+        deliveryQueue.destroy()
+        serverClient.destroy(error)
+        this._reportOutboundQueueOverflow({clientCount, error})
+      }
+    })
 
-    httpClient.events.on("output", (output) => {
+    httpClient.events.on("output", (output, {websocketFrame = false} = {}) => {
       if (output !== null && output !== undefined) {
-        void enqueueDelivery(() => serverClient.send(output)).catch((error) => {
+        const delivery = () => serverClient.send(output)
+        const queued = websocketFrame
+          ? deliveryQueue.enqueueFrame({
+            byteLength: typeof output === "string" ? Buffer.byteLength(output) : output.byteLength,
+            delivery
+          })
+          : deliveryQueue.enqueueControl(delivery)
+
+        void queued.catch((error) => {
           this.logger.error(() => ["Failed to deliver client output", {clientCount}, error])
         })
       }
     })
 
     httpClient.events.on("file", ({filePath, sendBody, settle}) => {
-      void enqueueDelivery(async () => {
+      void deliveryQueue.enqueueControl(async () => {
         await settle(await serverClient.sendFile(filePath, sendBody))
       }).catch((error) => {
         this.logger.error(() => ["Failed to deliver file response", {clientCount, filePath}, error])
@@ -83,11 +95,12 @@ export default class VelociousHttpServerInProcessHandler {
     })
 
     httpClient.events.on("close", () => {
-      void enqueueDelivery(() => serverClient.end())
+      void deliveryQueue.enqueueControl(() => serverClient.end())
         .finally(() => delete this.clients[clientCount])
     })
 
     serverClient.events.on("close", () => {
+      deliveryQueue.destroy()
       const cleanup = httpClient.abortPendingFileResponses()
         .catch((error) => {
           this.logger.warn("Failed to abort file responses after client close", error)
@@ -100,7 +113,7 @@ export default class VelociousHttpServerInProcessHandler {
       this.pendingClientCloseCleanups.add(cleanup)
     })
 
-    this.clients[clientCount] = {httpClient, serverClient}
+    this.clients[clientCount] = {deliveryQueue, httpClient, serverClient}
 
     // Create a message-port shim so ServerClient.onSocketData can route data
     // to the in-process HTTP Client without needing a real worker thread.
@@ -118,6 +131,24 @@ export default class VelociousHttpServerInProcessHandler {
     serverClient.listen()
   }
 
+  /**
+   * Reports a per-client outbound queue overflow.
+   * @param {object} args - Overflow details.
+   * @param {number} args.clientCount - Affected client.
+   * @param {Error} args.error - Overflow error.
+   * @returns {void}
+   */
+  _reportOutboundQueueOverflow({clientCount, error}) {
+    const errorPayload = {
+      context: {clientCount, websocketOutboundQueueOverflow: true, workerCount: this.workerCount},
+      error
+    }
+    const errorEvents = this.configuration.getErrorEvents()
+
+    errorEvents.emit("framework-error", errorPayload)
+    errorEvents.emit("all-error", {...errorPayload, errorType: "framework-error"})
+  }
+
   /**
    * Runs stop.
    * @returns {Promise<void>} */
@@ -158,6 +189,14 @@ export default class VelociousHttpServerInProcessHandler {
     return this.configuration._broadcastToChannelLocal(channel, broadcastParams, body, {eventId})
   }
 
+  /**
+   * Gets the configuration-wide V2 broadcast target shared by in-process handlers.
+   * @returns {import("../../configuration.js").default} - Shared configuration target.
+   */
+  websocketV2BroadcastDispatchKey() {
+    return this.configuration
+  }
+
   /**
    * Runs dispatch websocket event.
    * @param {object} args - Options object.

package/src/http-server/worker-handler/index.js

@@ -2,6 +2,7 @@
 
 import {ensureError} from "typanic"
 import Logger from "../../logger.js"
+import ClientDeliveryQueue from "../client-delivery-queue.js"
 import {Worker} from "worker_threads"
 import websocketEventsHost from "../websocket-events-host.js"
 
@@ -59,7 +60,7 @@ export default class VelociousHttpServerWorker {
      * @type {Map<number, {resolve: (snapshot: Record<string, ?>) => void}>} */
     this._debugSnapshotRequests = new Map()
 
-    /** @type {Map<number, Promise<void>>} */
+    /** @type {Map<number, ClientDeliveryQueue>} */
     this._clientDeliveryQueues = new Map()
   }
 
@@ -117,6 +118,7 @@ export default class VelociousHttpServerWorker {
     if (!this.clients[clientCount] && !this._clientDeliveryQueues.has(clientCount)) return
 
     delete this.clients[clientCount]
+    this._clientDeliveryQueues.get(clientCount)?.destroy()
     this._clientDeliveryQueues.delete(clientCount)
     this.worker?.postMessage({command: "clientAbort", clientCount})
   }
@@ -163,6 +165,10 @@ export default class VelociousHttpServerWorker {
   _closeAllClients() {
     const clients = Object.values(this.clients)
     this.clients = {}
+    const deliveryQueues = this._clientDeliveryQueues
+    this._clientDeliveryQueues = new Map()
+
+    for (const queue of deliveryQueues.values()) queue.destroy()
 
     for (const client of clients) {
       try {
@@ -182,6 +188,7 @@ export default class VelociousHttpServerWorker {
    * @param {string} [data.filePath] - File path.
    * @param {boolean} [data.sendBody] - Whether to send the file body.
    * @param {number} [data.transferId] - File transfer id.
+   * @param {boolean} [data.websocketFrame] - Whether output is a completed WebSocket frame.
    * @param {string} [data.channel] - Channel name.
    * @param {number} [data.requestId] - Debug request id.
    * @param {Record<string, ?>} [data.snapshot] - Worker debug snapshot.
@@ -219,7 +226,11 @@ export default class VelociousHttpServerWorker {
       if (output !== null && output !== undefined) {
         const outputLength = typeof output === "string" ? output.length : output.byteLength
 
-        void this.enqueueClientDelivery(client.clientCount, () => client.send(output)).then(() => {
+        const delivery = data.websocketFrame === true
+          ? this.enqueueClientFrame(client, output)
+          : this.enqueueClientControl(client, () => client.send(output))
+
+        void delivery.then(() => {
           this.logger.debug(() => ["Client output delivered", {
             clientCount,
             outputLength,
@@ -243,7 +254,7 @@ export default class VelociousHttpServerWorker {
         return
       }
 
-      void this.enqueueClientDelivery(client.clientCount, async () => {
+      void this.enqueueClientControl(client, async () => {
         const result = await client.sendFile(filePath, sendBody !== false)
 
         this.worker?.postMessage({command: "clientFileResult", result, transferId})
@@ -260,7 +271,7 @@ export default class VelociousHttpServerWorker {
         return
       }
 
-      void this.enqueueClientDelivery(client.clientCount, () => client.end())
+      void this.enqueueClientControl(client, () => client.end())
         .finally(() => delete this.clients[client.clientCount])
     } else if (command == "debugSnapshot") {
       const {requestId, snapshot} = data
@@ -289,7 +300,12 @@ export default class VelociousHttpServerWorker {
         throw new Error("Worker websocket v2-broadcast channel must be a string")
       }
 
-      websocketEventsHost.broadcastV2({body, broadcastParams: broadcastParams || {}, channel})
+      websocketEventsHost.broadcastV2({
+        body,
+        broadcastParams: broadcastParams || {},
+        channel,
+        configuration: this.configuration
+      })
     } else {
       throw new Error(`Unknown command: ${command}`)
     }
@@ -297,24 +313,70 @@ export default class VelociousHttpServerWorker {
 
   /**
    * Preserves socket output ordering for one client.
-   * @param {number} clientCount - Client count.
+   * @param {import("../server-client.js").default} client - Client instance.
+   * @param {string | Uint8Array} output - Complete output buffer.
+   * @returns {Promise<void>} - Queued delivery.
+   */
+  enqueueClientFrame(client, output) {
+    const byteLength = typeof output === "string" ? Buffer.byteLength(output) : output.byteLength
+
+    return this._deliveryQueueFor(client).enqueueFrame({
+      byteLength,
+      delivery: () => client.send(output)
+    })
+  }
+
+  /**
+   * Preserves ordering for a delivery that retains no complete output frame.
+   * @param {import("../server-client.js").default} client - Client instance.
    * @param {() => Promise<void>} delivery - Delivery operation.
    * @returns {Promise<void>} - Queued delivery.
    */
-  enqueueClientDelivery(clientCount, delivery) {
-    const previous = this._clientDeliveryQueues.get(clientCount) || Promise.resolve()
-    const queued = previous
-      .catch(() => {})
-      .then(delivery)
-
-    this._clientDeliveryQueues.set(clientCount, queued)
-    const clearQueue = () => {
-      if (this._clientDeliveryQueues.get(clientCount) === queued) this._clientDeliveryQueues.delete(clientCount)
-    }
+  enqueueClientControl(client, delivery) {
+    return this._deliveryQueueFor(client).enqueueControl(delivery)
+  }
 
-    void queued.then(clearQueue, clearQueue)
+  /**
+   * Gets or creates one client's delivery queue.
+   * @param {import("../server-client.js").default} client - Client instance.
+   * @returns {ClientDeliveryQueue} - Client-owned delivery queue.
+   */
+  _deliveryQueueFor(client) {
+    const existing = this._clientDeliveryQueues.get(client.clientCount)
+    if (existing) return existing
+
+    const {maxBytes, maxFrames} = this.configuration.getWebsocketOutboundQueueLimits()
+    const queue = new ClientDeliveryQueue({
+      clientCount: client.clientCount,
+      maxBytes,
+      maxFrames,
+      onOverflow: (error) => {
+        queue.destroy()
+        client.destroy(error)
+        this._reportOutboundQueueOverflow({clientCount: client.clientCount, error})
+      }
+    })
+
+    this._clientDeliveryQueues.set(client.clientCount, queue)
+    return queue
+  }
+
+  /**
+   * Reports a per-client outbound queue overflow.
+   * @param {object} args - Overflow details.
+   * @param {number} args.clientCount - Affected client.
+   * @param {Error} args.error - Overflow error.
+   * @returns {void}
+   */
+  _reportOutboundQueueOverflow({clientCount, error}) {
+    const errorPayload = {
+      context: {clientCount, websocketOutboundQueueOverflow: true, workerCount: this.workerCount},
+      error
+    }
+    const errorEvents = this.configuration.getErrorEvents()
 
-    return queued
+    errorEvents.emit("framework-error", errorPayload)
+    errorEvents.emit("all-error", {...errorPayload, errorType: "framework-error"})
   }
 
   /**
@@ -410,6 +472,14 @@ export default class VelociousHttpServerWorker {
     this.worker.postMessage({body, broadcastParams, channel, command: "websocketV2Broadcast", eventId, createdAt})
   }
 
+  /**
+   * Gets this worker's isolated V2 broadcast target.
+   * @returns {VelociousHttpServerWorker} - This worker handler.
+   */
+  websocketV2BroadcastDispatchKey() {
+    return this
+  }
+
   /**
    * Runs register with events host.
    * @returns {void} */

package/src/http-server/worker-handler/worker-thread.js

@@ -154,8 +154,8 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
       remoteAddress
     })
 
-    client.events.on("output", (output) => {
-      this.parentPort.postMessage({command: "clientOutput", clientCount, output})
+    client.events.on("output", (output, {websocketFrame = false} = {}) => {
+      this.parentPort.postMessage({command: "clientOutput", clientCount, output, websocketFrame})
     })
 
     client.events.on("file", ({filePath, sendBody, settle}) => {