velocious 1.0.626 → 1.0.628

package/src/database/pool/base.js

@@ -40,10 +40,13 @@ import sha256Hex from "../../utils/sha256-hex.js"
  * @property {Array<Record<string, ReturnType<typeof JSON.parse>>>} connections - Live connection snapshots.
  * @property {number} connectionsBeingSpawned - Number of in-progress connection spawns.
  * @property {number} idleCount - Number of idle connections.
+ * @property {number} [idleMatchingPendingCheckoutCount] - Idle connections that can satisfy at least one pending checkout.
  * @property {string} identifier - Database identifier.
  * @property {number} inUseCount - Number of checked-out connections.
  * @property {Array<DatabasePoolPendingCheckoutDebugSnapshot>} [pendingCheckouts] - Waiting checkout snapshots.
  * @property {number} pendingCheckoutCount - Number of queued checkout requests.
+ * @property {boolean} [pendingCheckoutDrainActive] - Whether a checkout drain pass is active.
+ * @property {boolean} [pendingCheckoutDrainRequested] - Whether another checkout drain pass was requested.
  * @property {string} poolClass - Pool class name.
  * @property {{connectionCreationCount: number, connectionCreationFailureCount: number, connectionCreationMaxMs: number, connectionCreationTotalMs: number, checkoutTimeoutCount: number, checkoutWaitCount: number, checkoutWaitMaxMs: number, checkoutWaitTotalMs: number, idleReapCount: number, idleReapDisposalCount: number, idleReapFailureCount: number, idleReapMaxMs: number, idleReapTotalMs: number, peakLiveConnections: number}} [telemetry] - Cumulative pool lifecycle telemetry.
  */

package/src/database/pool/checkout-timeout-error.js

@@ -0,0 +1,16 @@
+// @ts-check
+
+/** Stable framework error for a database pool checkout that exceeded its wait limit. */
+export default class DatabasePoolCheckoutTimeoutError extends Error {
+  /**
+   * Builds a database pool checkout timeout error.
+   * @param {string} message - Detailed sanitized pool timeout message.
+   * @param {{cause?: unknown}} [args] - Error options.
+   */
+  constructor(message, {cause} = {}) {
+    super(message, cause === undefined ? undefined : {cause})
+
+    this.name = "DatabasePoolCheckoutTimeoutError"
+    this.code = "VELOCIOUS_DATABASE_POOL_CHECKOUT_TIMEOUT"
+  }
+}

package/src/http-client/websocket-client.js

@@ -4,6 +4,7 @@ import SnapReqWebSocketClient from "snapreq/websocket"
 import {deserializeFrontendModelTransportValue} from "../frontend-models/transport-serialization.js"
 
 const DEFAULT_URL = "ws://127.0.0.1:3006/websocket"
+const SESSION_ROUTING_PARAMETER = "velociousSessionId"
 
 /**
  * Velocious's WebSocket client. The cross-platform connection/session/channel
@@ -28,6 +29,57 @@ export default class VelociousWebsocketClient extends SnapReqWebSocketClient {
     this.runningReconnectTasks = new Set()
     /** @type {Promise<void> | null} */
     this.gracefulClosePromise = null
+    this.routingBaseUrl = this.url
+  }
+
+  /**
+   * Restores a persisted session before opening the socket so the host can route
+   * the HTTP upgrade to the worker that owns its paused state.
+   * @returns {Promise<void>}
+   */
+  async _restoreSessionIdForRouting() {
+    // SnapReq initializes these internal session fields in its constructor, but
+    // its declaration does not expose that definite-assignment lifecycle here.
+    const routingState = /** @type {{_sessionId: string | null, _sessionStore: {get: () => string | null | undefined | Promise<string | null | undefined>} | undefined, _sessionStoreRestored: boolean}} */ (/** @type {unknown} */ (this))
+
+    if (routingState._sessionId || routingState._sessionStoreRestored || !routingState._sessionStore) return
+
+    routingState._sessionStoreRestored = true
+
+    try {
+      const storedId = await routingState._sessionStore.get()
+
+      if (typeof storedId === "string" && storedId.length > 0) routingState._sessionId = storedId
+    } catch (error) {
+      this._debug("sessionStore.get failed", error)
+    }
+  }
+
+  /**
+   * Builds the WebSocket URL carrying only the current resumable session routing hint.
+   * @returns {string} - WebSocket URL.
+   */
+  _sessionRoutingUrl() {
+    const url = new URL(this.routingBaseUrl)
+
+    if (this._sessionId) {
+      url.searchParams.set(SESSION_ROUTING_PARAMETER, this._sessionId)
+    } else {
+      url.searchParams.delete(SESSION_ROUTING_PARAMETER)
+    }
+
+    return url.toString()
+  }
+
+  /**
+   * Restores routing state before delegating socket creation to SnapReq.
+   * @param {Parameters<SnapReqWebSocketClient["_connect"]>[0]} [options] - Connect options.
+   * @returns {Promise<void>} - Resolves when the session is ready.
+   */
+  async _connect(options) {
+    await this._restoreSessionIdForRouting()
+    this.url = this._sessionRoutingUrl()
+    await super._connect(options)
   }
 
   /**

package/src/http-server/client/index.js

@@ -314,6 +314,12 @@ export default class VeoliciousHttpServerClient {
       this.websocketSession = undefined
       this.events.emit("close")
     })
+    this.websocketSession.events.on("ownershipClaimed", ({sessionId}) => {
+      this.events.emit("websocketSessionOwned", {sessionId})
+    })
+    this.websocketSession.events.on("ownershipReleased", ({sessionId}) => {
+      this.events.emit("websocketSessionReleased", {sessionId})
+    })
     this.state = "websocket"
     this.events.emit("output", response)
     void this.websocketSession.initializeChannel()

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

@@ -215,6 +215,9 @@ export default class VelociousHttpServerClientWebsocketSession {
      */
     this._resumeIdentityPromise = undefined
 
+    /** @type {string | null} */
+    this._claimedSessionId = null
+
     /**
      * Accumulates payloads for a fragmented websocket message per
      * RFC 6455. Non-null while mid-fragment; cleared when the frame
@@ -266,6 +269,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    * @returns {void}
    */
   sendSessionEstablished() {
+    this._claimOwnership()
     this.sendJson({
       type: "session-established",
       sessionId: this.sessionId,
@@ -313,6 +317,7 @@ export default class VelociousHttpServerClientWebsocketSession {
   }
 
   destroy() {
+    this._releaseOwnership()
     this._stopHeartbeat()
     this._resetFragmentBuffer()
     this._clearBufferedFrameChunks()
@@ -325,6 +330,25 @@ export default class VelociousHttpServerClientWebsocketSession {
     this.events.removeAllListeners()
   }
 
+  /** Claims this session id for host-side reconnect routing. */
+  _claimOwnership() {
+    if (this._claimedSessionId === this.sessionId) return
+    if (this._claimedSessionId) this._releaseOwnership()
+
+    this._claimedSessionId = this.sessionId
+    this.events.emit("ownershipClaimed", {sessionId: this.sessionId})
+  }
+
+  /** Releases the currently claimed session id exactly once. */
+  _releaseOwnership() {
+    const sessionId = this._claimedSessionId
+
+    if (!sessionId) return
+
+    this._claimedSessionId = null
+    this.events.emit("ownershipReleased", {sessionId})
+  }
+
   /**
    * Runs has subscription.
    * @param {string} channel - Channel name.
@@ -1339,6 +1363,7 @@ export default class VelociousHttpServerClientWebsocketSession {
     }
 
     this._stopHeartbeat()
+    this._releaseOwnership()
     this.configuration._websocketSessions.delete(this)
     void this._runMessageHandlerClose()
     void this._teardownChannel()
@@ -1355,6 +1380,7 @@ export default class VelociousHttpServerClientWebsocketSession {
    */
   _finalizeGraceExpiry() {
     this._stopHeartbeat()
+    this._releaseOwnership()
     this._resetFragmentBuffer()
     this._clearBufferedFrameChunks()
     this._abandonInboundMessages()
@@ -1499,6 +1525,9 @@ export default class VelociousHttpServerClientWebsocketSession {
 
     this.configuration._clearPausedWebsocketSession(resumeSessionId)
 
+    this._releaseOwnership()
+    paused._releaseOwnership()
+
     // Transfer resumable state onto this (live) session. The paused
     // session shell is discarded after the transfer.
     for (const [connectionId, connection] of paused._connections) {
@@ -1526,6 +1555,7 @@ export default class VelociousHttpServerClientWebsocketSession {
     paused._paused = false
     paused.destroy()
 
+    this._claimOwnership()
     this.sendJson({type: "session-resumed", sessionId: resumeSessionId})
     for (const body of queued) this.sendJson(body)
     await this._fireOnResume()

package/src/http-server/index.js

@@ -6,6 +6,7 @@ import EventEmitter from "../utils/event-emitter.js"
 import InProcessHandler from "./worker-handler/in-process.js"
 import Logger from "../logger.js"
 import Net from "net"
+import os from "node:os"
 import ServerClient from "./server-client.js"
 import WorkerHandler from "./worker-handler/index.js"
 
@@ -14,17 +15,18 @@ import WorkerHandler from "./worker-handler/index.js"
  * @typedef {{start: () => Promise<void>, stop: () => Promise<void>}} DevelopmentReloaderLike */
 /**
  * Defines this typedef.
- * @typedef {(args: {configuration: import("../configuration.js").default, workerCount: number}) => (WorkerHandler | InProcessHandler)} WorkerHandlerFactory */
+ * @typedef {(args: {configuration: import("../configuration.js").default, onWebsocketSessionOwned: (args: {sessionId: string, workerHandler: WorkerHandler}) => void, onWebsocketSessionReleased: (args: {sessionId: string, workerHandler: WorkerHandler}) => void, onWorkerStopped: (args: {workerHandler: WorkerHandler}) => void, workerCount: number}) => (WorkerHandler | InProcessHandler)} WorkerHandlerFactory */
 
 /**
  * Runs normalize worker count.
  * @param {object} args - Options object.
  * @param {number} [args.maxWorkers] - Backward-compatible worker count alias.
  * @param {number} [args.workers] - Configured worker count.
+ * @param {number} args.defaultWorkerCount - Process-available CPU count.
  * @returns {number} - Normalized worker count.
  */
-function normalizeWorkerCount({maxWorkers, workers}) {
-  const workerCount = workers ?? maxWorkers ?? 1
+function normalizeWorkerCount({defaultWorkerCount, maxWorkers, workers}) {
+  const workerCount = workers ?? maxWorkers ?? defaultWorkerCount
 
   if (!Number.isInteger(workerCount) || workerCount < 1) {
     throw new Error("HTTP server workers must be a positive integer")
@@ -33,6 +35,9 @@ function normalizeWorkerCount({maxWorkers, workers}) {
   return workerCount
 }
 
+const MAX_INITIAL_REQUEST_HEADER_BYTES = 64 * 1024
+const WEBSOCKET_SESSION_ROUTING_PARAMETER = "velociousSessionId"
+
 export default class VelociousHttpServer {
   clientCount = 0
   _starting = false
@@ -70,10 +75,8 @@ export default class VelociousHttpServer {
    * @type {Array<WorkerHandler | InProcessHandler>} */
   workerHandlers = []
   nextWorkerHandlerIndex = 0
-  /**
-   * Sticky worker handlers.
-   * @type {Map<string, WorkerHandler | InProcessHandler>} */
-  stickyWorkerHandlers = new Map()
+  /** Worker ownership for live or grace-paused resumable WebSocket sessions. */
+  websocketSessionOwners = new Map()
 
   /**
    * Runs constructor.
@@ -84,10 +87,11 @@ export default class VelociousHttpServer {
    * @param {number} [args.port] - Port.
    * @param {number} [args.maxWorkers] - Max workers.
    * @param {number} [args.workers] - Worker handlers to start.
+   * @param {() => number} [args.availableParallelism] - CPU availability owner seam.
    * @param {(args: {configuration: import("../configuration.js").default, onReload: (args: {changedPath: string}) => Promise<void>}) => {start: () => Promise<void>, stop: () => Promise<void>}} [args.developmentReloaderFactory] - Development reloader factory.
    * @param {WorkerHandlerFactory} [args.workerHandlerFactory] - Worker handler factory.
    */
-  constructor({configuration, developmentReloaderFactory, host, inProcess, maxWorkers, port, workerHandlerFactory, workers}) {
+  constructor({availableParallelism = os.availableParallelism, configuration, developmentReloaderFactory, host, inProcess, maxWorkers, port, workerHandlerFactory, workers}) {
     this.configuration = configuration
     this.developmentReloaderFactory = developmentReloaderFactory
     this.workerHandlerFactory = workerHandlerFactory
@@ -95,7 +99,8 @@ export default class VelociousHttpServer {
     this.logger = new Logger(this)
     this.host = host ?? "0.0.0.0"
     this.port = port ?? 3006
-    this.workers = normalizeWorkerCount({maxWorkers, workers})
+    this.workers = normalizeWorkerCount({defaultWorkerCount: availableParallelism(), maxWorkers, workers})
+    this.effectiveWorkers = this.inProcess && workers === undefined && maxWorkers === undefined ? 1 : this.workers
   }
 
   /**
@@ -167,7 +172,7 @@ export default class VelociousHttpServer {
     this.developmentReloader = startupState.developmentReloader
     this.netServer = startupState.netServer
     this.workerHandlers = startupState.workerHandlers
-    this.stickyWorkerHandlers.clear()
+    this.websocketSessionOwners.clear()
   }
 
   /**
@@ -205,7 +210,7 @@ export default class VelociousHttpServer {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async _ensureWorkers() {
-    while (this.workerHandlers.length < this.workers) {
+    while (this.workerHandlers.length < this.effectiveWorkers) {
       await this.spawnWorker()
     }
   }
@@ -232,6 +237,7 @@ export default class VelociousHttpServer {
       activeSocketCount: this._activeSockets.size,
       clientCount: Object.keys(this.clients).length,
       configuredWorkerCount: this.workers,
+      effectiveWorkerCount: this.effectiveWorkers,
       inProcess: this.inProcess,
       workerCount: this.workerHandlers.length,
       workers: await Promise.all(this.workerHandlers.map((handler) => this.workerDebugSnapshot(handler)))
@@ -327,7 +333,7 @@ export default class VelociousHttpServer {
     const stopTasks = this.workerHandlers.map((handler) => handler.stop())
     await Promise.all(stopTasks)
     this.workerHandlers = []
-    this.stickyWorkerHandlers.clear()
+    this.websocketSessionOwners.clear()
   }
 
   /**
@@ -367,9 +373,6 @@ export default class VelociousHttpServer {
     this.clientCount++
 
     try {
-      // Paused WebSocket sessions are worker-local, so reconnects from
-      // the same client address must return to the same worker.
-      const workerHandler = this.workerHandlerToUse({stickyKey: socket.remoteAddress})
       const client = new ServerClient({
         clientCount,
         configuration: this.configuration,
@@ -377,16 +380,184 @@ export default class VelociousHttpServer {
       })
 
       client.events.on("close", this.onClientClose)
-
-      this.logger.debug(`Gave client ${clientCount} to worker ${workerHandler.workerCount}`)
-      workerHandler.addSocketConnection(client)
       this.clients[clientCount] = client
+      this.routeClientAfterInitialRoutingData(client)
     } catch (error) {
       this.logger.error(`Failed to initialize client ${clientCount} on new connection`, error)
       socket.destroy()
     }
   }
 
+  /**
+   * Buffers only the bounded initial request data needed to recognize a
+   * WebSocket resume routing hint, then replays it to the selected worker.
+   * @param {ServerClient} client - Unassigned socket client.
+   * @returns {void}
+   */
+  routeClientAfterInitialRoutingData(client) {
+    const {socket} = client
+    /** @type {Buffer[]} */
+    const chunks = []
+    let byteLength = 0
+    const cleanup = () => {
+      socket.off("data", onData)
+      socket.off("close", cleanup)
+    }
+    const onData = (/** @type {Buffer} */ chunk) => {
+      chunks.push(chunk)
+      byteLength += chunk.length
+      const initialRequest = Buffer.concat(chunks, byteLength)
+
+      if (this.initialRequestNeedsMoreRoutingData(initialRequest) && byteLength < MAX_INITIAL_REQUEST_HEADER_BYTES) return
+
+      cleanup()
+      this.assignClientToWorker(client, initialRequest)
+    }
+
+    socket.on("data", onData)
+    socket.once("close", cleanup)
+  }
+
+  /**
+   * Checks whether the buffered initial HTTP headers are complete.
+   * @param {Buffer} initialRequest - Buffered initial request bytes.
+   * @returns {boolean} - Whether a header terminator is present.
+   */
+  initialRequestHeadersComplete(initialRequest) {
+    return initialRequest.includes("\r\n\r\n") || initialRequest.includes("\n\n")
+  }
+
+  /**
+   * Checks whether a possible resumable WebSocket request still needs headers.
+   * Ordinary and malformed requests can reach the existing request parser as
+   * soon as their first line is complete.
+   * @param {Buffer} initialRequest - Buffered initial request bytes.
+   * @returns {boolean} - Whether more routing data is required.
+   */
+  initialRequestNeedsMoreRoutingData(initialRequest) {
+    if (this.initialRequestHeadersComplete(initialRequest)) return false
+
+    const lineEnd = initialRequest.indexOf("\n")
+
+    if (lineEnd === -1) return true
+
+    const requestLine = initialRequest.subarray(0, lineEnd).toString("latin1").replace(/\r$/, "")
+    const requestLineMatch = requestLine.match(/^GET ([^ ]+) HTTP\/[^ ]+$/)
+
+    if (!requestLineMatch) return false
+
+    try {
+      const requestUrl = new URL(requestLineMatch[1], "http://velocious.invalid")
+
+      return requestUrl.searchParams.has(WEBSOCKET_SESSION_ROUTING_PARAMETER)
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Assigns a buffered client and replays the exact bytes into its worker.
+   * @param {ServerClient} client - Client awaiting assignment.
+   * @param {Buffer} initialRequest - Initial request bytes.
+   * @returns {void}
+   */
+  assignClientToWorker(client, initialRequest) {
+    if (client.socket.destroyed) return
+
+    try {
+      const workerHandler = this.workerHandlerForInitialRequest(initialRequest)
+
+      this.logger.debug(`Gave client ${client.clientCount} to worker ${workerHandler.workerCount}`)
+      workerHandler.addSocketConnection(client)
+      client.onSocketData(initialRequest)
+    } catch (error) {
+      this.logger.error(`Failed to assign client ${client.clientCount} to a worker`, error)
+      client.destroy(error instanceof Error ? error : new Error("Failed to assign HTTP client to worker", {cause: error}))
+    }
+  }
+
+  /**
+   * Selects the owner of a resumable WebSocket session or the next ordinary worker.
+   * @param {Buffer} initialRequest - Initial HTTP request headers.
+   * @returns {WorkerHandler | InProcessHandler} - Selected worker.
+   */
+  workerHandlerForInitialRequest(initialRequest) {
+    const sessionId = this.websocketResumeSessionId(initialRequest)
+
+    if (sessionId) {
+      const owner = this.websocketSessionOwners.get(sessionId)
+
+      if (owner && this.workerHandlers.includes(owner)) return owner
+      if (owner) this.websocketSessionOwners.delete(sessionId)
+    }
+
+    return this.workerHandlerToUse()
+  }
+
+  /**
+   * Reads the resumable WebSocket session routing hint from an upgrade request.
+   * @param {Buffer} initialRequest - Initial HTTP request headers.
+   * @returns {string | undefined} - Session identity, if present on a WebSocket upgrade.
+   */
+  websocketResumeSessionId(initialRequest) {
+    const headerEnd = initialRequest.indexOf("\r\n\r\n")
+    const fallbackHeaderEnd = headerEnd === -1 ? initialRequest.indexOf("\n\n") : headerEnd
+
+    if (fallbackHeaderEnd === -1) return
+
+    const lines = initialRequest.subarray(0, fallbackHeaderEnd).toString("latin1").split(/\r?\n/)
+    const [method, requestTarget] = lines[0]?.split(" ") || []
+
+    if (method !== "GET" || !requestTarget) return
+
+    /** @type {Map<string, string>} */
+    const headers = new Map()
+
+    for (const line of lines.slice(1)) {
+      const separatorIndex = line.indexOf(":")
+
+      if (separatorIndex === -1) continue
+
+      headers.set(line.slice(0, separatorIndex).trim().toLowerCase(), line.slice(separatorIndex + 1).trim().toLowerCase())
+    }
+
+    if (headers.get("upgrade") !== "websocket" || !headers.get("connection")?.split(",").map((value) => value.trim()).includes("upgrade")) return
+
+    const sessionId = new URL(requestTarget, "http://velocious.invalid").searchParams.get(WEBSOCKET_SESSION_ROUTING_PARAMETER)
+
+    return sessionId || undefined
+  }
+
+  /**
+   * Records the live worker owner for a resumable session.
+   * @param {{sessionId: string, workerHandler: WorkerHandler | InProcessHandler}} args - Ownership claim.
+   * @returns {void}
+   */
+  claimWebsocketSession({sessionId, workerHandler}) {
+    if (!this.workerHandlers.includes(workerHandler)) return
+    this.websocketSessionOwners.set(sessionId, workerHandler)
+  }
+
+  /**
+   * Releases a session only when the releasing worker still owns it.
+   * @param {{sessionId: string, workerHandler: WorkerHandler | InProcessHandler}} args - Ownership release.
+   * @returns {void}
+   */
+  releaseWebsocketSession({sessionId, workerHandler}) {
+    if (this.websocketSessionOwners.get(sessionId) === workerHandler) this.websocketSessionOwners.delete(sessionId)
+  }
+
+  /**
+   * Releases every session owned by a worker leaving service.
+   * @param {WorkerHandler | InProcessHandler} workerHandler - Worker leaving service.
+   * @returns {void}
+   */
+  releaseWebsocketSessionsForWorker(workerHandler) {
+    for (const [sessionId, owner] of this.websocketSessionOwners) {
+      if (owner === workerHandler) this.websocketSessionOwners.delete(sessionId)
+    }
+  }
+
   /**
    * On client close.
    * @param {ServerClient} client - Client instance.
@@ -425,7 +596,7 @@ export default class VelociousHttpServer {
      * @type {Array<WorkerHandler | InProcessHandler>} */
     const workerHandlers = []
 
-    for (let index = 0; index < this.workers; index += 1) {
+    for (let index = 0; index < this.effectiveWorkers; index += 1) {
       workerHandlers.push(await this._buildWorkerHandler())
     }
 
@@ -443,9 +614,18 @@ export default class VelociousHttpServer {
 
     const Handler = this.inProcess ? InProcessHandler : WorkerHandler
     const workerHandler = this.workerHandlerFactory
-      ? this.workerHandlerFactory({configuration: this.configuration, workerCount})
+      ? this.workerHandlerFactory({
+        configuration: this.configuration,
+        onWebsocketSessionOwned: ({sessionId, workerHandler}) => this.claimWebsocketSession({sessionId, workerHandler}),
+        onWebsocketSessionReleased: ({sessionId, workerHandler}) => this.releaseWebsocketSession({sessionId, workerHandler}),
+        onWorkerStopped: ({workerHandler}) => this.releaseWebsocketSessionsForWorker(workerHandler),
+        workerCount
+      })
       : new Handler({
         configuration: this.configuration,
+        onWebsocketSessionOwned: ({sessionId, workerHandler}) => this.claimWebsocketSession({sessionId, workerHandler}),
+        onWebsocketSessionReleased: ({sessionId, workerHandler}) => this.releaseWebsocketSession({sessionId, workerHandler}),
+        onWorkerStopped: ({workerHandler}) => this.releaseWebsocketSessionsForWorker(workerHandler),
         workerCount
       })
 
@@ -456,25 +636,9 @@ export default class VelociousHttpServer {
 
   /**
    * Runs worker handler to use.
-   * @param {object} [args] - Options object.
-   * @param {string} [args.stickyKey] - Stable key that must keep routing to the same worker.
    * @returns {WorkerHandler | InProcessHandler} - The worker handler to use.
    */
-  workerHandlerToUse({stickyKey} = {}) {
-    if (stickyKey) {
-      const stickyWorkerHandler = this.stickyWorkerHandlers.get(stickyKey)
-
-      if (stickyWorkerHandler && this.workerHandlers.includes(stickyWorkerHandler)) {
-        return stickyWorkerHandler
-      }
-
-      const workerHandler = this._nextRoundRobinWorkerHandler()
-
-      this.stickyWorkerHandlers.set(stickyKey, workerHandler)
-
-      return workerHandler
-    }
-
+  workerHandlerToUse() {
     return this._nextRoundRobinWorkerHandler()
   }
 
@@ -550,7 +714,7 @@ export default class VelociousHttpServer {
 
         this.workerHandlers = newWorkerHandlers
         this.nextWorkerHandlerIndex = 0
-        this.stickyWorkerHandlers.clear()
+        for (const workerHandler of oldWorkerHandlers) this.releaseWebsocketSessionsForWorker(workerHandler)
 
         await Promise.all(oldWorkerHandlers.map((workerHandler) => workerHandler.stop()))
       } while (this._reloadWorkersForDevelopmentQueued && !this._stopping)

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

@@ -41,8 +41,11 @@ export default class VelociousHttpServerWorker {
    * @param {object} args - Options object.
    * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
    * @param {number} args.workerCount - Worker count.
+   * @param {(args: {sessionId: string, workerHandler: VelociousHttpServerWorker}) => void} [args.onWebsocketSessionOwned] - Session ownership callback.
+   * @param {(args: {sessionId: string, workerHandler: VelociousHttpServerWorker}) => void} [args.onWebsocketSessionReleased] - Session ownership release callback.
+   * @param {(args: {workerHandler: VelociousHttpServerWorker}) => void} [args.onWorkerStopped] - Worker lifecycle callback.
    */
-  constructor({configuration, workerCount}) {
+  constructor({configuration, onWebsocketSessionOwned, onWebsocketSessionReleased, onWorkerStopped, workerCount}) {
     this.configuration = configuration
 
     /**
@@ -52,6 +55,9 @@ export default class VelociousHttpServerWorker {
 
     this.logger = new Logger(this)
     this.workerCount = workerCount
+    this.onWebsocketSessionOwned = onWebsocketSessionOwned
+    this.onWebsocketSessionReleased = onWebsocketSessionReleased
+    this.onWorkerStopped = onWorkerStopped
     this.workerStarted = false
     this._stopping = false
     this._debugRequestId = 0
@@ -152,6 +158,7 @@ export default class VelociousHttpServerWorker {
     }
 
     this.unregisterFromEventsHostIfNeeded()
+    if (this.onWorkerStopped) this.onWorkerStopped({workerHandler: this})
     if (this._stopResolve) {
       this._stopResolve()
     }
@@ -190,6 +197,7 @@ export default class VelociousHttpServerWorker {
    * @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 {string} [data.sessionId] - WebSocket session identity.
    * @param {number} [data.requestId] - Debug request id.
    * @param {Record<string, ReturnType<typeof JSON.parse>>} [data.snapshot] - Worker debug snapshot.
    * @param {ReturnType<typeof JSON.parse>} [data.payload] - Payload data.
@@ -306,6 +314,12 @@ export default class VelociousHttpServerWorker {
         channel,
         configuration: this.configuration
       })
+    } else if (command == "websocketSessionOwned") {
+      if (typeof data.sessionId !== "string") throw new Error("Worker websocket session id must be a string")
+      if (this.onWebsocketSessionOwned) this.onWebsocketSessionOwned({sessionId: data.sessionId, workerHandler: this})
+    } else if (command == "websocketSessionReleased") {
+      if (typeof data.sessionId !== "string") throw new Error("Worker websocket session id must be a string")
+      if (this.onWebsocketSessionReleased) this.onWebsocketSessionReleased({sessionId: data.sessionId, workerHandler: this})
     } else {
       throw new Error(`Unknown command: ${command}`)
     }

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

@@ -170,6 +170,14 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
       this.parentPort.postMessage({command: "clientClose", clientCount, output})
     })
 
+    client.events.on("websocketSessionOwned", ({sessionId}) => {
+      this.parentPort.postMessage({command: "websocketSessionOwned", sessionId})
+    })
+
+    client.events.on("websocketSessionReleased", ({sessionId}) => {
+      this.parentPort.postMessage({command: "websocketSessionReleased", sessionId})
+    })
+
     this.clients[clientCount] = client
   }