velocious 1.0.626 → 1.0.628

package/README.md

@@ -1827,7 +1827,7 @@ database: {
 }
 ```
 
-`pool.max` caps live async-tracked connections for that pool and defaults to `10` when omitted. When the cap is reached, new checkouts wait until a matching checked-in connection can be handed over or capacity is freed. Set `pool.max` to `null` only when a process is deliberately allowed to open an unbounded number of database connections. The built-in debug endpoint reports each in-use connection's `checkedOutForMs`, each idle connection's `idleForMs`, and queued `pendingCheckouts[].waitingForMs` so production diagnostics can distinguish long-held checkouts from pool-capacity waits.
+`pool.max` caps live async-tracked connections for that pool and defaults to `10` when omitted. When the cap is reached, new checkouts wait until a matching checked-in connection can be handed over or capacity is freed. Set `pool.max` to `null` only when a process is deliberately allowed to open an unbounded number of database connections. The built-in debug endpoint reports each in-use connection's `checkedOutForMs`, each idle connection's `idleForMs`, queued `pendingCheckouts[].waitingForMs`, and matching idle capacity plus checkout-drain state so production diagnostics can distinguish long-held checkouts, pool-capacity waits, and an invariant violation where compatible capacity is unexpectedly idle.
 
 Debug snapshots also expose cumulative connection-creation, checkout-wait and
 timeout, idle-reap, and peak-live-connection telemetry. Opt-in test profiles can
@@ -2028,7 +2028,7 @@ await client.close()
 
 For long-lived Node clients, the constructor also accepts opt-in liveness options (all default off, so browser/Expo usage is unchanged): `webSocketImplementation` (inject Node's `ws`, since the global/undici WebSocket exposes neither protocol ping nor an unref-able socket), `heartbeatIntervalMs` (a ping heartbeat that drops a socket whose peer stops ponging, so a client notices a vanished server), and `unref` (unref the underlying socket so an idle connection can't keep the process alive on its own). See [docs/websocket-channels.md](docs/websocket-channels.md).
 
-`await client.close()` is a final graceful shutdown that releases resumable server-session state; unexpected transport drops first attempt to resume that state. A successful resume retains the existing server-side connection and channel instances. If the server instead rejects the old session with `session-gone`, SnapReq promotes the already-established fresh session, reopens still-live one-to-one connection handles, and re-subscribes still-live channel handles. Those public handles remain usable and channel readiness resolves on the fresh session; explicitly closed handles stay closed. See [the WebSocket channel lifecycle guarantees](docs/websocket-channels.md#lifecycle-guarantees-phase-1b).
+`await client.close()` is a final graceful shutdown that releases resumable server-session state; unexpected transport drops first attempt to resume that state. On a multi-worker server, the client automatically puts the prior session identity in the reconnect upgrade URL so the host can route it to its owning worker; routing is session-based and never source-IP-based. A successful resume retains the existing server-side connection and channel instances. If the server instead rejects the old session with `session-gone`, SnapReq promotes the already-established fresh session, reopens still-live one-to-one connection handles, and re-subscribes still-live channel handles. Those public handles remain usable and channel readiness resolves on the fresh session; explicitly closed handles stay closed. See [the WebSocket channel lifecycle guarantees](docs/websocket-channels.md#lifecycle-guarantees-phase-1b).
 
 ## Subscribe to events
 
@@ -2310,7 +2310,7 @@ Create the file `src/routes/testing/another-action.ejs` and so something like th
 
 Velocious includes a simple background jobs system inspired by Sidekiq.
 
-Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
+Jobs can opt into cross-worker durable concurrency limits by pairing a non-empty `concurrencyKey` with a positive-integer `maxConcurrency` in their background-job options, or by deriving the key in a hydrated job instance's non-static `concurrencyKey()` method. Explicit enqueue options win. The first cap registered for a key is stable; conflicting caps are rejected. See [durable concurrency limits](docs/background-jobs.md#durable-concurrency-limits).
 
 Production apps can listen for `background-job-failed` (or its `all-error` mirror) to report accepted failed attempts, including retry and terminal-state metadata, and for `background-job-orphaned` to react to a specific job the main process reclaimed after its worker died mid-run — e.g. enqueue a targeted recovery for the work it left behind, instead of only polling for the aftermath. Orphan handlers run before the sweep waits for reclaimed jobs to be dispatched, so a stalled dispatcher does not delay application recovery. See [docs/background-jobs.md](docs/background-jobs.md#failure-events).
 
@@ -2701,6 +2701,18 @@ It exposes `GET /api/stats`, `/api/jobs`, `/api/jobs/:id`, `/api/schedule` and `
 npx velocious server --host 0.0.0.0 --port 8082
 ```
 
+Threaded servers default to `os.availableParallelism()` HTTP workers. Pass
+`--workers` or configure `httpServer.workers` to override that count. Ordinary
+connections are distributed round-robin even behind a loopback reverse proxy,
+while resumable WebSockets return to their session's worker. Each worker owns a
+separate configuration and database pools, so per-worker limits multiply across
+the effective worker count (for example, four workers with `pool.max: 10` can
+open 40 connections for that pool). The debug snapshot exposes the configured
+and effective counts; default in-process mode uses one effective handler.
+Only requests carrying a resumable-session query wait for upgrade headers before
+worker assignment; ordinary and malformed requests continue directly to the
+request parser.
+
 When the server runs in the `development` environment, Velocious watches application `src/` trees and hot-reloads by recycling HTTP workers after `.js`/`.mjs`/`.cjs`/`.json`/`.ejs` changes. That picks up edited controllers, models, resources, routes, and views without a manual server restart while keeping production/test behavior unchanged.
 
 Starting the HTTP server creates `tmp/server.lock` under the configured application directory before Beacon, workers, or the TCP listener start. A second server for the same app fails fast with the lock owner details instead of partially starting. Normal shutdown removes the lock; stale locks with a dead local PID are reclaimed automatically, while locks from another host or unreadable metadata should be removed manually only after confirming no server is running. See [docs/http-server.md](docs/http-server.md#server-lock).

package/build/background-jobs/job-runner.js

@@ -93,6 +93,14 @@ export default async function runJobPayload(payload, {closeConnections = true, m
   await registry.load()
   const JobClass = registry.getJobByName(payload.jobName)
   const jobInstance = new JobClass()
+  const jobArgs = payload.args || []
+  jobInstance._setBackgroundJobContext({
+    args: jobArgs,
+    jobClass: JobClass,
+    jobName: payload.jobName,
+    options: payload.options || {},
+    payload
+  })
   /**
    * Perform.
    * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>} */
@@ -107,7 +115,7 @@ export default async function runJobPayload(payload, {closeConnections = true, m
   try {
     try {
       await configuration.withConnections({databaseIdentifiers: JobClass.databaseIdentifiers, name: `Background job runner: ${payload.jobName}`}, async () => {
-        await perform.apply(jobInstance, payload.args || [])
+        await perform.apply(jobInstance, jobArgs)
       })
     } catch (error) {
       if (error instanceof BackgroundJobRescheduleSignal) {

package/build/background-jobs/local-dispatcher.js

@@ -184,7 +184,29 @@ export default class LocalBackgroundJobsDispatcher {
         configuration: this.configuration,
         JobClass,
         jobArgs: job.args,
-        name: `Local background job: ${job.jobName}`
+        jobOptions: {
+          concurrencyKey: job.concurrencyKey || undefined,
+          executionMode: job.executionMode,
+          maxConcurrency: job.maxConcurrency ?? undefined,
+          maxRetries: job.maxRetries ?? undefined,
+          queue: job.queue,
+          scheduledAtMs: job.scheduledAtMs ?? undefined,
+          timeoutMs: job.timeoutMs ?? undefined
+        },
+        name: `Local background job: ${job.jobName}`,
+        payload: {
+          args: job.args,
+          handedOffAtMs: handoff.handedOffAtMs,
+          handoffId: handoff.handoffId,
+          id: job.id,
+          jobName: job.jobName,
+          options: {
+            concurrencyKey: job.concurrencyKey || undefined,
+            executionMode: job.executionMode,
+            maxConcurrency: job.maxConcurrency ?? undefined,
+            queue: job.queue
+          }
+        }
       })
     } catch (error) {
       if (error instanceof BackgroundJobRescheduleSignal) {

package/build/background-jobs/main.js

@@ -223,10 +223,7 @@ export default class BackgroundJobsMain {
           await this.store.enqueue({
             jobName: jobClass.jobName(),
             args,
-            // Fold in the job class's static `queue` (as performLater* do) so a
-            // scheduled job with `static queue = "..."` lands on its queue and
-            // honors the configured cap without every schedule repeating it.
-            options: jobClass._withQueue(options)
+            options: jobClass._withJobContext({jobArgs: args, jobOptions: options})
           })
           this._notifyEnqueued()
           // Persistence is the scheduler enqueue boundary. Dispatch remains
@@ -1400,7 +1397,12 @@ export default class BackgroundJobsMain {
             workerId: worker.workerId,
             handedOffAtMs: handoff.handedOffAtMs,
             options: {
+              concurrencyKey: job.concurrencyKey || undefined,
               executionMode: job.executionMode,
+              maxConcurrency: job.maxConcurrency ?? undefined,
+              maxRetries: job.maxRetries ?? undefined,
+              queue: job.queue,
+              scheduledAtMs: job.scheduledAtMs ?? undefined,
               ...(job.timeoutMs === null ? {} : {timeoutMs: job.timeoutMs})
             }
           }

package/build/background-jobs/perform-job.js

@@ -6,11 +6,20 @@
  * @param {import("../configuration.js").default} args.configuration - Active configuration.
  * @param {typeof import("./platform-job.js").default} args.JobClass - Job class.
  * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+ * @param {import("./types.js").BackgroundJobOptions} [args.jobOptions] - Resolved runtime options.
  * @param {string} args.name - Connection-scope label.
+ * @param {import("./types.js").BackgroundJobPayload} [args.payload] - Persisted runner payload.
  * @returns {Promise<void>} - Resolves after performance.
  */
-export default async function performBackgroundJob({configuration, JobClass, jobArgs, name}) {
+export default async function performBackgroundJob({configuration, JobClass, jobArgs, jobOptions = {}, name, payload}) {
   const jobInstance = new JobClass()
+  jobInstance._setBackgroundJobContext({
+    args: jobArgs,
+    jobClass: JobClass,
+    jobName: JobClass.jobName(),
+    options: jobOptions,
+    ...(payload ? {payload} : {})
+  })
   /**
    * Narrows the generic subclass's runtime method to serialized job arguments.
    * @type {(...args: Array<ReturnType<typeof JSON.parse>>) => Promise<void>}

package/build/background-jobs/platform-job.js

@@ -14,6 +14,11 @@ import {cancelScheduledBackgroundJob, enqueueBackgroundJob, replaceScheduledBack
  * @template {Array<ReturnType<typeof JSON.parse>>} [TArgs=[]]
  */
 export default class VelociousJob {
+  constructor() {
+    /** @type {import("./types.js").BackgroundJobContext | undefined} */
+    this._backgroundJobContext = undefined
+  }
+
   /**
    * Database identifiers checked out while this job performs. Set an explicit
    * list to avoid holding unrelated configured database connections, or `[]`
@@ -82,6 +87,63 @@ export default class VelociousJob {
     return merged
   }
 
+  /**
+   * Resolves class-derived enqueue options on a hydrated job instance. Explicit
+   * per-enqueue options take precedence over the instance concurrency key.
+   * @param {object} args - Job context.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args.jobArgs - Job arguments.
+   * @param {import("./types.js").BackgroundJobOptions | undefined} args.jobOptions - Job options.
+   * @returns {import("./types.js").BackgroundJobOptions} - Resolved job options.
+   */
+  static _withJobContext({jobArgs, jobOptions}) {
+    const options = this._withQueue(jobOptions)
+
+    if (options.concurrencyKey !== undefined) return options
+
+    const jobInstance = new this()
+    jobInstance._setBackgroundJobContext({
+      args: jobArgs,
+      jobClass: this,
+      jobName: this.jobName(),
+      options
+    })
+    const concurrencyKey = jobInstance.concurrencyKey()
+
+    if (concurrencyKey !== undefined) options.concurrencyKey = concurrencyKey
+
+    return options
+  }
+
+  /**
+   * Sets the complete context available to this hydrated job instance.
+   * Framework enqueue/runner boundaries own this method.
+   * @param {import("./types.js").BackgroundJobContext} context - Job context.
+   * @returns {void}
+   */
+  _setBackgroundJobContext(context) {
+    this._backgroundJobContext = context
+  }
+
+  /**
+   * Returns this hydrated job's complete enqueue or runner context.
+   * @returns {import("./types.js").BackgroundJobContext} - Job context.
+   */
+  backgroundJobContext() {
+    if (!this._backgroundJobContext) throw new Error("Background job context is not hydrated")
+
+    return this._backgroundJobContext
+  }
+
+  /**
+   * Override to derive a durable concurrency key from `backgroundJobContext()`.
+   * Pair the derived key with `maxConcurrency` in enqueue options. An explicit
+   * per-enqueue `concurrencyKey` takes precedence and skips this method.
+   * @returns {string | undefined} - Derived concurrency key, or undefined for none.
+   */
+  concurrencyKey() {
+    return undefined
+  }
+
   /**
    * Runs perform later.
    * @param {...ReturnType<typeof JSON.parse>} args - Job args.

package/build/background-jobs/runtime.js

@@ -52,9 +52,10 @@ export async function enqueueBackgroundJob({JobClass, jobArgs, jobOptions}) {
  * @returns {Promise<string>} - Durable job id or ephemeral inline performance id.
  */
 export async function enqueueBackgroundJobForConfiguration({configuration, JobClass, jobArgs, jobOptions}) {
+  const resolvedJobOptions = JobClass._withJobContext({jobArgs, jobOptions})
 
   if (configuration.getBackgroundJobsConfig().mode === "inline") {
-    validateInlineOptions(jobOptions)
+    validateInlineOptions(resolvedJobOptions)
     configuration.setCurrent()
     await configuration.initialize({type: "background-jobs-inline"})
 
@@ -63,6 +64,7 @@ export async function enqueueBackgroundJobForConfiguration({configuration, JobCl
         configuration,
         JobClass,
         jobArgs,
+        jobOptions: resolvedJobOptions,
         name: `Background job inline mode: ${JobClass.jobName()}`
       })
     } catch (error) {
@@ -81,7 +83,7 @@ export async function enqueueBackgroundJobForConfiguration({configuration, JobCl
   return await client.enqueue({
     jobName: JobClass.jobName(),
     args: jobArgs,
-    options: JobClass._withQueue(jobOptions)
+    options: resolvedJobOptions
   })
 }
 
@@ -117,12 +119,13 @@ export async function replaceScheduledBackgroundJobForConfiguration({configurati
   }
 
   const client = configuration.getEnvironmentHandler().backgroundJobsClient({configuration})
+  const resolvedJobOptions = JobClass._withJobContext({jobArgs, jobOptions})
 
   return await client.replaceScheduled({
     scheduleKey,
     jobName: JobClass.jobName(),
     args: jobArgs,
-    options: JobClass._withQueue(jobOptions)
+    options: resolvedJobOptions
   })
 }
 

package/build/background-jobs/types.js

@@ -71,6 +71,14 @@
  * @property {number} [handedOffAtMs] - Time handed to a worker in ms.
  * @property {BackgroundJobOptions} [options] - Runtime options.
  */
+/**
+ * @typedef {object} BackgroundJobContext
+ * @property {typeof import("./platform-job.js").default} jobClass - Concrete job class.
+ * @property {string} jobName - Registered job name.
+ * @property {Array<ReturnType<typeof JSON.parse>>} args - Serialized job arguments.
+ * @property {BackgroundJobOptions} options - Resolved enqueue/runtime options.
+ * @property {BackgroundJobPayload} [payload] - Complete persisted runner payload when the job is performing.
+ */
 /**
  * @typedef {object} BackgroundJobRow
  * @property {string} id - Job id.

package/build/background-jobs/worker.js

@@ -1054,7 +1054,9 @@ export default class BackgroundJobsWorker {
       configuration,
       JobClass,
       jobArgs: payload.args || [],
-      name: `Background job worker inline: ${payload.jobName}`
+      jobOptions: payload.options || {},
+      name: `Background job worker inline: ${payload.jobName}`,
+      payload
     })
   }
 

package/build/database/pool/async-tracked-multi-connection.js

@@ -2,6 +2,7 @@
 
 import { AsyncLocalStorage } from "async_hooks"
 import BasePool, { POOL_CONFIGURATION_KEY } from "./base.js"
+import DatabasePoolCheckoutTimeoutError from "./checkout-timeout-error.js"
 import { currentTestProfileContext } from "../../testing/test-profile-context.js"
 
 /**
@@ -101,6 +102,9 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @type {Promise<void> | undefined} */
   pendingCheckoutDrainPromise = undefined
 
+  /** Whether a caller requested another pass through the pending checkout queue. */
+  pendingCheckoutDrainRequested = false
+
   /**
    * Idle connection reaper timer.
    * @type {ReturnType<typeof setTimeout> | undefined} */
@@ -602,18 +606,45 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {Promise<void>} - Resolves when pending checkouts have been drained as far as possible.
    */
   async drainPendingCheckouts() {
-    if (this.pendingCheckoutDrainPromise) {
-      await this.pendingCheckoutDrainPromise
-      return
-    }
+    this.pendingCheckoutDrainRequested = true
 
-    this.pendingCheckoutDrainPromise = this.drainPendingCheckoutsActual()
+    if (!this.pendingCheckoutDrainPromise) this.startPendingCheckoutDrain()
+    await this.pendingCheckoutDrainPromise
+  }
 
+  /**
+   * Starts the single checkout-drain owner. The shared promise is cleared before
+   * it settles, closing the resolved-promise/stale-field interval in which a new
+   * request could otherwise be lost.
+   * @returns {void}
+   */
+  startPendingCheckoutDrain() {
+    const {promise, reject, resolve} = Promise.withResolvers()
+
+    this.pendingCheckoutDrainPromise = promise
+    void this.runRequestedPendingCheckoutDrains({reject, resolve})
+  }
+
+  /**
+   * Runs drain passes until every request observed during the active pass has
+   * received a later pass.
+   * @param {{reject: (reason?: ReturnType<typeof JSON.parse>) => void, resolve: (value?: void) => void}} deferred - Shared drain settlement.
+   * @returns {Promise<void>}
+   */
+  async runRequestedPendingCheckoutDrains({reject, resolve}) {
     try {
-      await this.pendingCheckoutDrainPromise
-    } finally {
+      while (this.pendingCheckoutDrainRequested) {
+        this.pendingCheckoutDrainRequested = false
+        await this.drainPendingCheckoutsActual()
+      }
+    } catch (error) {
       this.pendingCheckoutDrainPromise = undefined
+      reject(error)
+      return
     }
+
+    this.pendingCheckoutDrainPromise = undefined
+    resolve()
   }
 
   /**
@@ -726,13 +757,13 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
   /**
    * Runs pending checkout timeout error.
    * @param {PendingCheckout} checkout - Timed-out checkout.
-   * @returns {Error} - Timeout error.
+   * @returns {DatabasePoolCheckoutTimeoutError} - Timeout error.
    */
   pendingCheckoutTimeoutError(checkout) {
     const checkoutName = checkout.options.name ? ` Checkout name: ${JSON.stringify(checkout.options.name)}.` : ""
     const diagnostics = this.pendingCheckoutTimeoutDiagnostics(checkout)
 
-    return new Error(`Timed out after ${checkout.timeoutMillis}ms waiting for database connection checkout from pool "${this.identifier}".${checkoutName} ${diagnostics}`)
+    return new DatabasePoolCheckoutTimeoutError(`Timed out after ${checkout.timeoutMillis}ms waiting for database connection checkout from pool "${this.identifier}".${checkoutName} ${diagnostics}`)
   }
 
   /**
@@ -1255,7 +1286,13 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
       connections,
       connectionsBeingSpawned: this.connectionsBeingSpawned,
       idleCount: this.connections.length + [...this.lifecycleRetainedConnections.values()].filter((connection) => connection.getIdSeq() === undefined).length,
+      idleMatchingPendingCheckoutCount: this.connections.filter((connection) => {
+        return !this.connectionHasOpenTransaction(connection)
+          && this.pendingCheckouts.some((checkout) => this.connectionMatchesReuseKey(connection, checkout.reuseKey))
+      }).length,
       inUseCount: Object.keys(this.connectionsInUse).length,
+      pendingCheckoutDrainActive: Boolean(this.pendingCheckoutDrainPromise),
+      pendingCheckoutDrainRequested: this.pendingCheckoutDrainRequested,
       pendingCheckouts: this.pendingCheckoutDebugSnapshots(now),
       pendingCheckoutCount: this.pendingCheckouts.length,
       telemetry: {...this.telemetry}

package/build/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/build/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/build/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/build/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/build/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()