velocious 1.0.565 → 1.0.567

package/README.md

@@ -1180,6 +1180,8 @@ Evaluate inline JavaScript (Rails-style runner) with initialized app/database co
 npx velocious runner "const users = await db.query('SELECT COUNT(*) AS count FROM users'); console.log(users[0].count)"
 ```
 
+Successful CLI commands exit with status `0`. If command execution rejects, Velocious marks the process failed and always runs final database cleanup. Successful cleanup preserves and rethrows the original command error unchanged; if cleanup also fails, an `AggregateError` retains the command error first and as its `cause`, followed by the cleanup error. Cleanup-only failures also exit nonzero. These failures therefore remain nonzero even when application code installs an `uncaughtException` listener that reports and consumes the error. See [CLI process exit behavior](docs/cli.md#process-exit-behavior).
+
 By default, migrations write `db/structure-<identifier>.sql` files for each database in non-test environments. Test skips these automatic writes unless you explicitly opt in. Configure allow/deny lists in your configuration:
 
 ```js
@@ -1568,7 +1570,7 @@ 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.
+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. Decoded inbound work is bounded independently per session before authorization or request handling: the defaults retain at most 256 active/queued messages or 16 MiB of raw UTF-8 payload bytes. Exact FIFO is preserved within the limits. A next message exceeding either limit is rejected before decoding and permanently closes that session with status `1008` and reason `Inbound message backlog exceeded`. Configure positive safe integers with `httpServer.websocketInboundQueue.maxPendingMessages` and `maxPendingBytes`.
 
 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.
 
@@ -1712,6 +1714,8 @@ configuration.getErrorEvents().on("all-error", ({error, errorType}) => {
 
 Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `Request failed.` response, but it also emits them as `framework-error`/`all-error` (with `context.frontendModelEndpoint === true`) so they are reported instead of being silently swallowed. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`), invalid client query descriptors are returned as frontend-model query errors, and `error.velocious`-annotated / `safeToExpose` / `errorType`-marked errors keep their expected-error status — none of these reach the error bus.
 
+Unexpected inbound decoded WebSocket dispatch failures emit one `framework-error` and one matching `all-error`. Established expected client-flow errors remain excluded from both events.
+
 ## Use the Websocket client API (HTTP-like)
 
 ```js

package/bin/velocious.js

@@ -39,10 +39,37 @@ const cli = new Cli({
   processArgs
 })
 
+let commandError
+let commandFailed = false
+
 try {
   await cli.execute()
-} finally {
+} catch (error) {
+  commandError = error
+  commandFailed = true
+  process.exitCode = 1
+}
+
+let cleanupError
+let cleanupFailed = false
+
+try {
   await configuration.closeDatabaseConnections()
+} catch (error) {
+  cleanupError = error
+  cleanupFailed = true
+  process.exitCode = 1
+}
+
+if (commandFailed && cleanupFailed) {
+  throw new AggregateError(
+    [commandError, cleanupError],
+    "Velocious CLI command execution and database cleanup both failed",
+    {cause: commandError}
+  )
 }
 
+if (commandFailed) throw commandError
+if (cleanupFailed) throw cleanupError
+
 process.exit(0)

package/build/bin/velocious.js

@@ -39,10 +39,37 @@ const cli = new Cli({
   processArgs
 })
 
+let commandError
+let commandFailed = false
+
 try {
   await cli.execute()
-} finally {
+} catch (error) {
+  commandError = error
+  commandFailed = true
+  process.exitCode = 1
+}
+
+let cleanupError
+let cleanupFailed = false
+
+try {
   await configuration.closeDatabaseConnections()
+} catch (error) {
+  cleanupError = error
+  cleanupFailed = true
+  process.exitCode = 1
+}
+
+if (commandFailed && cleanupFailed) {
+  throw new AggregateError(
+    [commandError, cleanupError],
+    "Velocious CLI command execution and database cleanup both failed",
+    {cause: commandError}
+  )
 }
 
+if (commandFailed) throw commandError
+if (cleanupFailed) throw cleanupError
+
 process.exit(0)

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, maxPendingMessages?: number}} [websocketInboundQueue] - Per-session retained inbound WebSocket message limits.
  * @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,8 @@ function resolveBeaconUnreachableReportMs(value) {
   return 30_000
 }
 
+const DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
+const DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_MESSAGES = 256
 const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_BYTES = 16 * 1024 * 1024
 const DEFAULT_WEBSOCKET_OUTBOUND_MAX_PENDING_FRAMES = 256
 
@@ -228,10 +230,15 @@ export default class VelociousConfiguration {
      * @type {Promise<void> | undefined}
      */
     this._initializePromise = undefined
+    const websocketInboundQueue = httpServer?.websocketInboundQueue
     const websocketOutboundQueue = httpServer?.websocketOutboundQueue
 
     this.httpServer = {
       ...(httpServer || {}),
+      websocketInboundQueue: {
+        maxPendingBytes: positiveSafeInteger(websocketInboundQueue?.maxPendingBytes, "httpServer.websocketInboundQueue.maxPendingBytes", DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_BYTES),
+        maxPendingMessages: positiveSafeInteger(websocketInboundQueue?.maxPendingMessages, "httpServer.websocketInboundQueue.maxPendingMessages", DEFAULT_WEBSOCKET_INBOUND_MAX_PENDING_MESSAGES)
+      },
       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)
@@ -2370,6 +2377,19 @@ export default class VelociousConfiguration {
    */
   getWebsocketSessionHeartbeatSeconds() { return this._websocketSessionHeartbeatSeconds }
 
+  /**
+   * Gets per-session WebSocket inbound message queue limits.
+   * @returns {{maxBytes: number, maxMessages: number}} - Per-session inbound queue high-water marks.
+   */
+  getWebsocketInboundQueueLimits() {
+    const queue = this.httpServer.websocketInboundQueue
+
+    return {
+      maxBytes: queue.maxPendingBytes,
+      maxMessages: queue.maxPendingMessages
+    }
+  }
+
   /**
    * Gets per-client WebSocket outbound queue limits.
    * @returns {{maxBytes: number, maxFrames: number}} - Per-client outbound queue high-water marks.