velocious 1.0.562 → 1.0.563

package/README.md

@@ -1568,7 +1568,9 @@ database: {
 
 Velocious includes a lightweight websocket entry point for API-style calls and server-side events.
 
-Inbound frames remain ordered when TCP splits a frame across reads. Velocious limits a single final client data frame and a reassembled fragmented message to 16 MiB; larger payloads close the connection. See [WebSocket connections](docs/websocket-connections.md) for wire-protocol details.
+Inbound frames remain ordered when TCP splits a frame across reads. Velocious limits a single final client data frame and a reassembled fragmented message to 16 MiB; larger payloads close the connection.
+
+Server-to-client WebSocket delivery is bounded independently per client. The defaults retain at most 256 queued/in-flight completed frames or 16 MiB of serialized frame output; the HTTP 101 upgrade response and ordinary HTTP/file output remain outside that budget, while exact FIFO is preserved. A slow client that exceeds either limit is reported through the framework error events and deterministically closed without affecting other clients. V2 channel broadcast delivery and persistence remain isolated to the originating configuration when several applications share a process. Configure positive safe integers with `httpServer.websocketOutboundQueue.maxPendingFrames` and `maxPendingBytes`. See [WebSocket connections](docs/websocket-connections.md) for configuration and wire-protocol details.
 
 ## Connect and call a controller
 

package/build/configuration-types.js

@@ -255,6 +255,7 @@
  * @property {boolean} [inProcess] - Run HTTP handlers in the main thread instead of worker threads.
  * @property {number} [maxWorkers] - Backward-compatible alias for workers.
  * @property {number} [port] - Port to bind the HTTP server to.
+ * @property {{maxPendingBytes?: number, maxPendingFrames?: number}} [websocketOutboundQueue] - Per-client retained outbound WebSocket frame limits.
  * @property {number} [workers] - Worker handlers to start for the HTTP server.
  */
 

package/build/configuration.js

@@ -114,6 +114,25 @@ function resolveBeaconUnreachableReportMs(value) {
   return 30_000
 }
 
+const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
+const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_FRAMES = 256
+
+/**
+ * Validates a positive safe integer configuration value.
+ * @param {?} value - Configured positive safe integer.
+ * @param {string} name - Configuration key.
+ * @param {number} defaultValue - Default value.
+ * @returns {number} - Validated configured or default value.
+ */
+function positiveSafeInteger(value, name, defaultValue) {
+  if (value === undefined) return defaultValue
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`)
+  }
+
+  return value
+}
+
 export default class VelociousConfiguration {
   /**
    * Close database connections promise.
@@ -209,7 +228,15 @@ export default class VelociousConfiguration {
      * @type {Promise<void> | undefined}
      */
     this._initializePromise = undefined
-    this.httpServer = httpServer || {}
+    const websocketOutboundQueue = httpServer?.websocketOutboundQueue
+
+    this.httpServer = {
+      ...(httpServer || {}),
+      websocketOutboundQueue: {
+        maxPendingBytes: positiveSafeInteger(websocketOutboundQueue?.maxPendingBytes, "httpServer.websocketOutboundQueue.maxPendingBytes", DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES),
+        maxPendingFrames: positiveSafeInteger(websocketOutboundQueue?.maxPendingFrames, "httpServer.websocketOutboundQueue.maxPendingFrames", DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_FRAMES)
+      }
+    }
     /**
      * Stores the http server instance value.
      * @type {{getDebugSnapshot: () => Promise<Record<string, ?>>} | undefined} */
@@ -1693,7 +1720,8 @@ export default class VelociousConfiguration {
       websocketEvents.broadcastV2({
         channel: message.channel,
         broadcastParams: message.broadcastParams,
-        body: message.body
+        body: message.body,
+        configuration: this
       })
       return
     }
@@ -2342,6 +2370,19 @@ export default class VelociousConfiguration {
    */
   getWebsocketSessionHeartbeatSeconds() { return this._websocketSessionHeartbeatSeconds }
 
+  /**
+   * Gets per-client WebSocket outbound queue limits.
+   * @returns {{maxBytes: number, maxFrames: number}} - Per-client outbound queue high-water marks.
+   */
+  getWebsocketOutboundQueueLimits() {
+    const queue = this.httpServer.websocketOutboundQueue
+
+    return {
+      maxBytes: queue.maxPendingBytes,
+      maxFrames: queue.maxPendingFrames
+    }
+  }
+
   /**
    * Registers a wrapper invoked around every WS-borne request /
    * connection message / channel dispatch. The wrapper receives the
@@ -2537,7 +2578,7 @@ export default class VelociousConfiguration {
     const websocketEvents = this._websocketEvents
 
     if (websocketEvents && typeof websocketEvents.broadcastV2 === "function") {
-      websocketEvents.broadcastV2({channel: name, broadcastParams, body})
+      websocketEvents.broadcastV2({channel: name, broadcastParams, body, configuration: this})
       return
     }
 

package/build/http-server/client/websocket-session.js

@@ -423,7 +423,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   sendGoodbye(client) {
     const frame = Buffer.from([WEBSOCKET_FINAL_FRAME | WEBSOCKET_OPCODE_CLOSE, 0x00])
 
-    client.events.emit("output", frame)
+    client.events.emit("output", frame, {websocketFrame: true})
   }
 
   /**
@@ -967,7 +967,7 @@ export default class VelociousHttpServerClientWebsocketSession {
     header[0] = WEBSOCKET_FINAL_FRAME | opcode
     header[1] = payload.length
 
-    this.client.events.emit("output", Buffer.concat([header, payload]))
+    this.client.events.emit("output", Buffer.concat([header, payload]), {websocketFrame: true})
   }
 
   /**
@@ -1012,7 +1012,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
     header[0] = WEBSOCKET_FINAL_FRAME | WEBSOCKET_OPCODE_TEXT
 
-    this.client.events.emit("output", Buffer.concat([header, payload]))
+    this.client.events.emit("output", Buffer.concat([header, payload]), {websocketFrame: true})
   }
 
   /**

package/build/http-server/client-delivery-queue.js

@@ -0,0 +1,168 @@
+// @ts-check
+
+export class ClientDeliveryQueueOverflowError extends Error {
+  /**
+   * Builds an outbound queue overflow error.
+   * @param {object} args - Overflow details.
+   * @param {number} args.clientCount - Client identifier.
+   * @param {number} args.maxBytes - Configured byte high-water mark.
+   * @param {number} args.maxFrames - Configured frame high-water mark.
+   * @param {number} args.pendingBytes - Bytes retained before rejecting the frame.
+   * @param {number} args.pendingFrames - Frames retained before rejecting the frame.
+   * @param {number} args.rejectedBytes - Rejected frame size.
+   */
+  constructor({clientCount, maxBytes, maxFrames, pendingBytes, pendingFrames, rejectedBytes}) {
+    super(`WebSocket client ${clientCount} exceeded its outbound queue limit (${pendingFrames}/${maxFrames} frames, ${pendingBytes}/${maxBytes} bytes; rejected ${rejectedBytes} bytes)`)
+    this.name = "ClientDeliveryQueueOverflowError"
+  }
+}
+
+/**
+ * @typedef {object} DeliveryTask
+ * @property {number} byteLength - Retained complete-buffer bytes.
+ * @property {boolean} countedFrame - Whether this task is an outbound frame.
+ * @property {() => Promise<void>} delivery - Delivery operation.
+ * @property {(error?: Error) => void} settle - Settles the enqueue promise.
+ */
+
+export default class ClientDeliveryQueue {
+  /**
+   * Builds a per-client delivery queue.
+   * @param {object} args - Queue options.
+   * @param {number} args.clientCount - Client identifier.
+   * @param {number} args.maxBytes - Byte high-water mark.
+   * @param {number} args.maxFrames - Frame high-water mark.
+   * @param {(error: ClientDeliveryQueueOverflowError) => void} args.onOverflow - Overflow handler.
+   */
+  constructor({clientCount, maxBytes, maxFrames, onOverflow}) {
+    this.clientCount = clientCount
+    this.maxBytes = maxBytes
+    this.maxFrames = maxFrames
+    this.onOverflow = onOverflow
+    /** @type {DeliveryTask[]} */
+    this.tasks = []
+    /** @type {DeliveryTask | undefined} */
+    this.activeTask = undefined
+    this.pendingBytes = 0
+    this.pendingFrames = 0
+    this.destroyed = false
+  }
+
+  /**
+   * Enqueues one complete output buffer.
+   * @param {object} args - Delivery details.
+   * @param {number} args.byteLength - Exact buffer byte length.
+   * @param {() => Promise<void>} args.delivery - Delivery operation.
+   * @returns {Promise<void>} - Settles after delivery or teardown.
+   */
+  enqueueFrame({byteLength, delivery}) {
+    if (this.destroyed) return Promise.resolve()
+
+    if (this.pendingFrames + 1 > this.maxFrames || this.pendingBytes + byteLength > this.maxBytes) {
+      const error = new ClientDeliveryQueueOverflowError({
+        clientCount: this.clientCount,
+        maxBytes: this.maxBytes,
+        maxFrames: this.maxFrames,
+        pendingBytes: this.pendingBytes,
+        pendingFrames: this.pendingFrames,
+        rejectedBytes: byteLength
+      })
+
+      this.onOverflow(error)
+      return Promise.reject(error)
+    }
+
+    this.pendingFrames += 1
+    this.pendingBytes += byteLength
+    return this._enqueue({byteLength, countedFrame: true, delivery})
+  }
+
+  /**
+   * Enqueues an ordering-only operation that retains no complete output frame.
+   * @param {() => Promise<void>} delivery - Delivery operation.
+   * @returns {Promise<void>} - Settles after delivery or teardown.
+   */
+  enqueueControl(delivery) {
+    if (this.destroyed) return Promise.resolve()
+
+    return this._enqueue({byteLength: 0, countedFrame: false, delivery})
+  }
+
+  /**
+   * Releases queued and active accounting during explicit client teardown.
+   * @returns {void}
+   */
+  destroy() {
+    if (this.destroyed) return
+
+    this.destroyed = true
+    const tasks = this.activeTask ? [this.activeTask, ...this.tasks] : this.tasks
+
+    this.activeTask = undefined
+    this.tasks = []
+    this.pendingBytes = 0
+    this.pendingFrames = 0
+
+    for (const task of tasks) task.settle()
+  }
+
+  /**
+   * Gets current retained-buffer accounting.
+   * @returns {{pendingBytes: number, pendingFrames: number}} - Current retained-buffer accounting.
+   */
+  snapshot() {
+    return {pendingBytes: this.pendingBytes, pendingFrames: this.pendingFrames}
+  }
+
+  /**
+   * Enqueues a delivery task.
+   * @param {Omit<DeliveryTask, "settle">} task - Task to enqueue.
+   * @returns {Promise<void>} - Task completion.
+   */
+  _enqueue(task) {
+    const promise = new Promise((resolve, reject) => {
+      this.tasks.push({
+        ...task,
+        settle: (error) => error ? reject(error) : resolve(undefined)
+      })
+    })
+
+    this._drain()
+    return promise
+  }
+
+  /**
+   * Starts the next task when idle.
+   * @returns {void} - No return value.
+   */
+  _drain() {
+    if (this.destroyed || this.activeTask) return
+
+    const task = this.tasks.shift()
+    if (!task) return
+
+    this.activeTask = task
+    void task.delivery().then(
+      () => this._finish(task),
+      (error) => this._finish(task, error)
+    )
+  }
+
+  /**
+   * Finishes the active delivery task.
+   * @param {DeliveryTask} task - Completed task.
+   * @param {Error} [error] - Delivery error.
+   * @returns {void}
+   */
+  _finish(task, error) {
+    if (this.destroyed || this.activeTask !== task) return
+
+    this.activeTask = undefined
+    if (task.countedFrame) {
+      this.pendingBytes -= task.byteLength
+      this.pendingFrames -= 1
+    }
+    task.settle(error)
+    this._drain()
+  }
+}

package/build/http-server/server-client.js

@@ -76,6 +76,15 @@ export default class ServerClient {
     })
   }
 
+  /**
+   * Immediately destroys the socket and all transport-owned write buffers.
+   * @param {Error} error - Destruction reason.
+   * @returns {void}
+   */
+  destroy(error) {
+    if (!this.socket.destroyed) this.socket.destroy(error)
+  }
+
   /**
    * On socket data.
    * @param {Buffer} chunk - Chunk.

package/build/http-server/websocket-events-host.js

@@ -8,6 +8,10 @@ export class VelociousHttpServerWebsocketEventsHost {
      * Narrows the runtime value to the documented type.
      * @type {Set<import("./worker-handler/index.js").default>} */
     this.handlers = new Set()
+    /**
+     * Broadcast handlers grouped by the configuration that owns them.
+     * @type {Map<import("../configuration.js").default, Set<import("./worker-handler/index.js").default>>} */
+    this.broadcastHandlersByConfiguration = new Map()
     this.publishQueue = Promise.resolve()
   }
 
@@ -30,8 +34,23 @@ export class VelociousHttpServerWebsocketEventsHost {
    */
   register(handler) {
     this.handlers.add(handler)
+    let configurationHandlers = this.broadcastHandlersByConfiguration.get(handler.configuration)
+
+    if (!configurationHandlers) {
+      configurationHandlers = new Set()
+      this.broadcastHandlersByConfiguration.set(handler.configuration, configurationHandlers)
+    }
+
+    configurationHandlers.add(handler)
+
+    return () => {
+      this.handlers.delete(handler)
+      configurationHandlers.delete(handler)
 
-    return () => this.handlers.delete(handler)
+      if (configurationHandlers.size === 0) {
+        this.broadcastHandlersByConfiguration.delete(handler.configuration)
+      }
+    }
   }
 
   /**
@@ -69,17 +88,24 @@ export class VelociousHttpServerWebsocketEventsHost {
    * @param {string} args.channel - Channel name.
    * @param {Record<string, ?>} args.broadcastParams - Routing filter params.
    * @param {?} args.body - Message body.
+   * @param {import("../configuration.js").default} args.configuration - Originating configuration.
    * @returns {void}
    */
-  broadcastV2({body, broadcastParams, channel}) {
+  broadcastV2({body, broadcastParams, channel, configuration}) {
     // Chain onto publishQueue so persistence completes before
     // the next broadcast — without this, a subscriber that connects
     // immediately after a broadcast could miss the just-persisted
     // event when replaying from lastEventId on a slow DB.
     this._queuePublish(async () => {
-      const persistedEvent = await this._persistV2EventIfNeeded({body, channel})
+      const persistedEvent = await this._persistV2EventIfNeeded({body, channel, configuration})
+      const dispatchedTargets = new Set()
 
-      for (const handler of this.handlers) {
+      for (const handler of this.broadcastHandlersByConfiguration.get(configuration) || []) {
+        const dispatchKey = handler.websocketV2BroadcastDispatchKey()
+
+        if (dispatchedTargets.has(dispatchKey)) continue
+
+        dispatchedTargets.add(dispatchKey)
         handler.dispatchWebsocketV2Broadcast({
           body,
           broadcastParams,
@@ -88,18 +114,19 @@ export class VelociousHttpServerWebsocketEventsHost {
           createdAt: persistedEvent?.createdAt
         })
       }
-    }, "Failed to persist/broadcast V2 event")
+    }, "Failed to persist/broadcast V2 event", configuration)
   }
 
   /**
    * Runs queue publish.
    * @param {() => Promise<void>} callback - Publish work to run in order.
    * @param {string} errorMessage - Message logged when publish work fails.
+   * @param {import("../configuration.js").default} [originatingConfiguration] - Configuration whose context owns the work.
    * @returns {void}
    */
-  _queuePublish(callback, errorMessage) {
+  _queuePublish(callback, errorMessage, originatingConfiguration) {
     const handler = this.handlers.values().next().value
-    const configuration = handler?.configuration
+    const configuration = originatingConfiguration || handler?.configuration
 
     this.publishQueue = this.publishQueue
       .then(async () => {
@@ -120,10 +147,11 @@ export class VelociousHttpServerWebsocketEventsHost {
    * @param {object} args - Options.
    * @param {?} args.body - Event body.
    * @param {string} args.channel - Channel name.
+   * @param {import("../configuration.js").default} args.configuration - Originating configuration.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata when storage is enabled.
    */
-  async _persistV2EventIfNeeded({body, channel}) {
-    return await this._persistChannelEventIfNeeded({channel, payload: body})
+  async _persistV2EventIfNeeded({body, channel, configuration}) {
+    return await this._persistChannelEventIfNeeded({channel, payload: body, configuration})
   }
 
   /**
@@ -142,14 +170,16 @@ export class VelociousHttpServerWebsocketEventsHost {
    * @param {object} args - Options object.
    * @param {string} args.channel - Channel name.
    * @param {?} args.payload - Payload data.
+   * @param {import("../configuration.js").default} [args.configuration] - Configuration owning the event store.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata.
    */
-  async _persistChannelEventIfNeeded({channel, payload}) {
+  async _persistChannelEventIfNeeded({channel, payload, configuration}) {
     const handler = this.handlers.values().next().value
+    const eventConfiguration = configuration || handler?.configuration
 
-    if (!handler?.configuration) return null
+    if (!eventConfiguration) return null
 
-    const websocketEventLogStore = websocketEventLogStoreForConfiguration(handler.configuration)
+    const websocketEventLogStore = websocketEventLogStoreForConfiguration(eventConfiguration)
     const shouldPersist = await websocketEventLogStore.shouldPersistChannel(channel)
 
     if (!shouldPersist) return null

package/build/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.