velocious 1.0.557 → 1.0.559

package/build/background-jobs/web/counts-channel.js

@@ -0,0 +1,79 @@
+// @ts-check
+
+import {BACKGROUND_JOB_COUNTS_CHANNEL} from "../store.js"
+import VelociousWebsocketChannel from "../../http-server/websocket-channel.js"
+import {authorizeJobsRequest} from "./authorization.js"
+import {getJobsMount} from "./registry.js"
+import {normalizeMountPrefix} from "./path-matcher.js"
+
+/**
+ * Authorized dashboard count-delta channel. Clients subscribe with the mount
+ * path and their normal bearer token as `authenticationToken`.
+ */
+export default class BackgroundJobCountsChannel extends VelociousWebsocketChannel {
+  /**
+   * Authorizes the subscription.
+   * @returns {Promise<boolean>} Whether the mount's normal dashboard authorization allows the subscription.
+   */
+  async canSubscribe() {
+    if (typeof this.params.mountAt !== "string") return false
+
+    const mountAt = normalizeMountPrefix(this.params.mountAt)
+    const options = getJobsMount(this.session.configuration, mountAt)
+
+    if (!options || !this.session.upgradeRequest) return false
+
+    const token = typeof this.params.authenticationToken === "string"
+      ? this.params.authenticationToken
+      : null
+    const ability = await this.session.configuration.resolveAbility({
+      params: this.params,
+      request: this.session.upgradeRequest
+    })
+    const authorized = await authorizeJobsRequest({
+      ability,
+      configuration: this.session.configuration,
+      options,
+      request: this.session.upgradeRequest,
+      token
+    })
+
+    if (!authorized) return false
+
+    this.databaseIdentifier = options.databaseIdentifier
+      || this.session.configuration.getBackgroundJobsConfig().databaseIdentifier
+      || "default"
+
+    return true
+  }
+
+  /**
+   * Matches only events from the database selected by the authorized mount.
+   * @param {import("../../http-server/websocket-channel.js").WebsocketJsonValue} broadcastParams - Publisher scope.
+   * @returns {boolean} Whether this subscription should receive the event.
+   */
+  matches(broadcastParams) {
+    if (!broadcastParams || typeof broadcastParams !== "object" || Array.isArray(broadcastParams)) return false
+
+    return String(/** @type {Record<string, ?>} */ (broadcastParams).databaseIdentifier) === this.databaseIdentifier
+  }
+
+  /**
+   * Builds diagnostics.
+   * @returns {Record<string, string>} Non-sensitive diagnostics.
+   */
+  debugSnapshot() {
+    return {databaseIdentifier: this.databaseIdentifier}
+  }
+
+  /** @type {string} */
+  databaseIdentifier = ""
+
+  /**
+   * Registers the framework channel used by mounted jobs dashboards.
+   * @param {import("../../configuration.js").default} configuration - Configuration.
+   */
+  static register(configuration) {
+    configuration.registerWebsocketChannel(BACKGROUND_JOB_COUNTS_CHANNEL, this)
+  }
+}

package/build/background-jobs/web/index.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import VelociousBackgroundJobsWebController from "./controller.js"
+import BackgroundJobCountsChannel from "./counts-channel.js"
 import {matchJobsApiPath, normalizeMountPrefix} from "./path-matcher.js"
 import {registerJobsMount} from "./registry.js"
 
@@ -40,6 +41,7 @@ export default class VelociousBackgroundJobsApi {
     const prefix = normalizeMountPrefix(at)
 
     registerJobsMount(configuration, prefix, {accessTokens, allowedOrigins, authorize, databaseIdentifier, redactArgs})
+    BackgroundJobCountsChannel.register(configuration)
 
     configuration.addRouteResolverHook(({currentPath, request}) => {
       const match = matchJobsApiPath({method: request.httpMethod(), path: currentPath, prefix})

package/build/background-jobs/web/registry.js

@@ -3,7 +3,7 @@
 /**
  * JobsMountOptions type.
  * @typedef {object} JobsMountOptions
- * @property {(args: {request: import("../../http-server/client/request.js").default, ability: (import("../../authorization/ability.js").default | undefined), token: (string | null), configuration: import("../../configuration.js").default}) => (boolean | void | Promise<boolean | void>)} [authorize] - Authorization callback. Return true to allow the request.
+ * @property {(args: {request: import("../../http-server/client/request.js").default | import("../../http-server/client/websocket-request.js").default, ability: (import("../../authorization/ability.js").default | undefined), token: (string | null), configuration: import("../../configuration.js").default}) => (boolean | void | Promise<boolean | void>)} [authorize] - Authorization callback. Return true to allow the request.
  * @property {string[]} [accessTokens] - Bearer tokens accepted for cross-origin/native access.
  * @property {string[]} [allowedOrigins] - Origins allowed for cross-origin browser access.
  * @property {boolean} [redactArgs] - When true, job arguments are omitted from API responses.

package/build/background-jobs/worker.js

@@ -8,6 +8,7 @@ import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobsStatusReporter from "./status-reporter.js"
 import {randomUUID} from "crypto"
 import {fileURLToPath} from "node:url"
+import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
 
 /** Grace period after SIGTERM before a lingering process runner is SIGKILLed. */
 const FORKED_CHILD_SIGKILL_GRACE_MS = 5000
@@ -73,8 +74,10 @@ export default class BackgroundJobsWorker {
    * @param {number} [args.forkedChildSigkillGraceMs] - Override the grace period between SIGTERM and SIGKILL when reaping lingering process runners on stop.
    * @param {number} [args.heartbeatIntervalMs] - Override the liveness heartbeat interval (default 15000ms).
    * @param {number} [args.jobTimeoutMs] - Override the wall-clock timeout for forked and pooled jobs from `configuration.getBackgroundJobsConfig()`. `0` disables it.
+   * @param {boolean} [args.closeDatabaseConnectionsOnStop] - Whether stop owns closing the configuration's database pools (default true).
+   * @param {() => void | Promise<void>} [args.onStopped] - Lifecycle hook invoked after the worker finishes stopping.
    */
-  constructor({configuration, host, port, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, forkedChildSigkillGraceMs, heartbeatIntervalMs, jobTimeoutMs} = {}) {
+  constructor({configuration, host, port, maxConcurrentForkedJobs, maxConcurrentInlineJobs, pooledRunnerCount, pooledRunnerConcurrency, pooledRunnerMaxJobs, pooledRunnerMaxRssBytes, pooledRunnerMaxLifetimeMs, forkedChildSigkillGraceMs, heartbeatIntervalMs, jobTimeoutMs, closeDatabaseConnectionsOnStop = true, onStopped} = {}) {
     /**
      * Narrows the runtime value to the documented type.
      * @type {Promise<import("../configuration.js").default>} */
@@ -85,6 +88,8 @@ export default class BackgroundJobsWorker {
     this.configuration = undefined
     this.host = host
     this.port = port
+    this.closeDatabaseConnectionsOnStop = closeDatabaseConnectionsOnStop
+    this.onStopped = onStopped
     /**
      * Constructor override for the inline-job concurrency cap. When unset
      * the cap is read from `configuration.getBackgroundJobsConfig()` in
@@ -136,6 +141,8 @@ export default class BackgroundJobsWorker {
      */
     this.jobTimeoutMsOverride = typeof jobTimeoutMs === "number" ? jobTimeoutMs : undefined
     this.shouldStop = false
+    /** @type {Promise<void> | undefined} */
+    this.stopPromise = undefined
     this.workerId = randomUUID()
     this.heartbeatIntervalMs = typeof heartbeatIntervalMs === "number" && heartbeatIntervalMs >= 1
       ? heartbeatIntervalMs
@@ -195,6 +202,8 @@ export default class BackgroundJobsWorker {
    * @returns {Promise<void>} - Resolves when connected.
    */
   async start() {
+    this.shouldStop = false
+    this.stopPromise = undefined
     this.configuration = await this.configurationPromise
     this.configuration.setCurrent()
     await this.configuration.initialize({type: "background-jobs-worker"})
@@ -241,37 +250,53 @@ export default class BackgroundJobsWorker {
    * @param {number} [args.timeoutMs] - Max wait for in-flight jobs (per phase) in ms.
    * @returns {Promise<void>} - Resolves when stopped.
    */
-  async stop({timeoutMs} = {}) {
-    if (this.shouldStop) return
-    this.shouldStop = true
-    this._stopHeartbeat()
+  stop({timeoutMs} = {}) {
+    if (!this.stopPromise) this.stopPromise = this._stop({timeoutMs})
 
-    // Announce drain so main stops dispatching but keeps the connection
-    // open until we close it ourselves below.
-    if (this.jsonSocket) {
-      try {
-        this.jsonSocket.send({type: "draining"})
-      } catch {
-        // Socket may already be closing; nothing to do.
-      }
-    }
+    return this.stopPromise
+  }
 
-    await this._drainInflight(this.inflightInlineJobs, timeoutMs)
-    await this._drainInflight(this.inflightPooledJobs, timeoutMs)
-    await this._drainInflight(this.inflightProcessJobs, timeoutMs)
-    await this._terminateProcessChildren()
-    // Give in-flight result reports (now decoupled from job slots) a bounded
-    // chance to land before the socket closes.
-    await this._drainInflight(this.inflightReports, timeoutMs)
+  /**
+   * Runs the worker shutdown lifecycle once.
+   * @param {object} [args] - Options.
+   * @param {number} [args.timeoutMs] - Max wait for in-flight jobs (per phase) in ms.
+   * @returns {Promise<void>} - Resolves when stopped.
+   */
+  async _stop({timeoutMs} = {}) {
+    this.shouldStop = true
+    this._stopHeartbeat()
 
-    if (this.jsonSocket) this.jsonSocket.close()
-    if (this.configuration) {
-      try {
-        await this.configuration.disconnectBeacon()
-      } finally {
-        await this.configuration.closeDatabaseConnections()
+    await shutdownLifecycle({
+      onStopped: this.onStopped,
+      shutdown: async () => {
+        // Announce drain so main stops dispatching but keeps the connection
+        // open until we close it ourselves below.
+        if (this.jsonSocket) {
+          try {
+            this.jsonSocket.send({type: "draining"})
+          } catch {
+            // Socket may already be closing; nothing to do.
+          }
+        }
+
+        await this._drainInflight(this.inflightInlineJobs, timeoutMs)
+        await this._drainInflight(this.inflightPooledJobs, timeoutMs)
+        await this._drainInflight(this.inflightProcessJobs, timeoutMs)
+        await this._terminateProcessChildren()
+        // Give in-flight result reports (now decoupled from job slots) a bounded
+        // chance to land before the socket closes.
+        await this._drainInflight(this.inflightReports, timeoutMs)
+
+        if (this.jsonSocket) this.jsonSocket.close()
+        if (!this.configuration) return
+
+        try {
+          await this.configuration.disconnectBeacon()
+        } finally {
+          if (this.closeDatabaseConnectionsOnStop) await this.configuration.closeDatabaseConnections()
+        }
       }
-    }
+    })
   }
 
   /**

package/build/database/record/index.js

@@ -1710,6 +1710,12 @@ class VelociousDatabaseRecord {
    */
   static switchesTenantDatabase(databaseIdentifierOrResolver) {
     this._tenantDatabaseIdentifierResolver = databaseIdentifierOrResolver
+
+    if (this._translationClass) {
+      const translatedModelClass = this
+
+      this._translationClass.switchesTenantDatabase(({tenant}) => translatedModelClass.getTenantDatabaseIdentifier(tenant))
+    }
   }
 
   /**
@@ -2814,6 +2820,12 @@ class VelociousDatabaseRecord {
     TranslationClass.setTableName(this.getTranslationsTableName())
     TranslationClass.belongsTo(belongsTo)
 
+    if (this.hasTenantDatabaseIdentifierResolver()) {
+      const translatedModelClass = this
+
+      TranslationClass.switchesTenantDatabase(({tenant}) => translatedModelClass.getTenantDatabaseIdentifier(tenant))
+    }
+
     this._translationClass = TranslationClass
 
     return this._translationClass

package/build/frontend-models/base.js

@@ -12,7 +12,7 @@ import {deserializeFrontendModelTransportValue, serializeFrontendModelTransportV
 import runWithTransportDeadline from "./transport-deadline.js"
 import {REQUEST_TIME_ZONE_HEADER, validateTimeZone} from "../time-zone.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
-import {bufferOutgoingEvent, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
+import {bufferOutgoingEvent, clearBufferedOutgoingEvents, drainBufferedOutgoingEvents} from "./outgoing-event-buffer.js"
 import {defineModelScope} from "../utils/model-scope.js"
 import isPlainObject from "../utils/plain-object.js"
 import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQueryData, setPayloadAssociationCount, setPayloadComputedAbility, setPayloadQueryData} from "../record-payload-values.js"
@@ -154,6 +154,64 @@ let frontendModelIdleResolvers = []
  * Internal websocket client.
  * @type {VelociousWebsocketClient | null} */
 let internalWebsocketClient = null
+/** @type {AbortSignal | null} */
+let internalWebsocketClientSignal = null
+/** @type {(() => void) | null} */
+let internalWebsocketClientSignalCleanup = null
+
+/**
+ * Detaches an owned WebSocket client from the shared cache if it is still current.
+ * @param {VelociousWebsocketClient} client - Client whose ownership is ending.
+ * @returns {void}
+ */
+function detachInternalWebsocketClient(client) {
+  if (internalWebsocketClient !== client) return
+
+  internalWebsocketClient = null
+  internalWebsocketClientSignalCleanup?.()
+  internalWebsocketClientSignal = null
+  internalWebsocketClientSignalCleanup = null
+}
+
+/**
+ * Disposes the owned WebSocket client before transport/session configuration changes.
+ * @returns {void}
+ */
+function resetInternalWebsocketClient() {
+  const client = internalWebsocketClient
+
+  if (!client) return
+
+  detachInternalWebsocketClient(client)
+  void client.disconnectAndStopReconnect()
+}
+
+/**
+ * Binds the owned WebSocket client lifetime to the current session signal.
+ * @param {AbortSignal | undefined} sessionSignal - Current session signal.
+ * @returns {void}
+ */
+function bindInternalWebsocketClientSignal(sessionSignal) {
+  if (internalWebsocketClientSignal === sessionSignal) return
+
+  internalWebsocketClientSignalCleanup?.()
+  internalWebsocketClientSignal = sessionSignal || null
+  internalWebsocketClientSignalCleanup = null
+
+  if (!sessionSignal || !internalWebsocketClient) return
+
+  const client = internalWebsocketClient
+  const onSessionAbort = () => {
+    detachInternalWebsocketClient(client)
+    clearBufferedOutgoingEvents()
+    void client.disconnectAndStopReconnect()
+  }
+
+  sessionSignal.addEventListener("abort", onSessionAbort, {once: true})
+  internalWebsocketClientSignalCleanup = () => sessionSignal.removeEventListener("abort", onSessionAbort)
+
+  if (sessionSignal.aborted) onSessionAbort()
+}
 
 /**
  * Runs frontend model transport is idle.
@@ -237,7 +295,13 @@ async function trackFrontendModelTransportRequest(callback) {
  * @returns {VelociousWebsocketClient | null} Websocket client or null.
  */
 function resolveInternalWebsocketClient() {
-  if (internalWebsocketClient) return internalWebsocketClient
+  if (internalWebsocketClient) {
+    const client = internalWebsocketClient
+
+    bindInternalWebsocketClientSignal(frontendModelTransportSignal())
+
+    return client
+  }
 
   const websocketUrl = frontendModelTransportConfig.websocketUrl
 
@@ -248,41 +312,68 @@ function resolveInternalWebsocketClient() {
 
   if (!resolvedUrl) return null
 
-  internalWebsocketClient = new VelociousWebsocketClient({
+  const client = new VelociousWebsocketClient({
     autoReconnect: true,
     sessionStore: frontendModelTransportConfig.sessionStore,
     url: resolvedUrl
   })
-  internalWebsocketClient.onReconnect = flushBufferedOutgoingEventsAfterReconnect
+  internalWebsocketClient = client
+  client.onReconnect = async () => await flushBufferedOutgoingEventsAfterReconnect(client)
 
-  return internalWebsocketClient
+  bindInternalWebsocketClientSignal(frontendModelTransportSignal())
+
+  return client
 }
 
 /**
  * Runs flush buffered outgoing events after reconnect.
+ * @param {VelociousWebsocketClient} client - Reconnected client that owns this flush.
  * @returns {Promise<void>} */
-async function flushBufferedOutgoingEventsAfterReconnect() {
-  if (!internalWebsocketClient) return
+async function flushBufferedOutgoingEventsAfterReconnect(client) {
+  if (internalWebsocketClient !== client) return
 
   const events = drainBufferedOutgoingEvents()
+  const sessionSignal = frontendModelTransportSignal()
 
-  for (let index = 0; index < events.length; index += 1) {
-    try {
-      await internalWebsocketClient.post(events[index].customPath, events[index].payload)
-    } catch {
-      const socketOpen = internalWebsocketClient.socket?.readyState === internalWebsocketClient.socket?.OPEN
+  await runWithTransportDeadline(
+    {
+      errorMessage: "Buffered frontend-model WebSocket flush timed out",
+      signal: sessionSignal,
+      timeoutMs: frontendModelTransportTimeoutMs()
+    },
+    async (signal) => {
+      for (let index = 0; index < events.length; index += 1) {
+        if (internalWebsocketClient !== client) return
 
-      if (socketOpen) {
-        continue
-      }
+        try {
+          await client.post(events[index].customPath, events[index].payload, {signal})
 
-      for (let remaining = index; remaining < events.length; remaining += 1) {
-        bufferOutgoingEvent(events[remaining])
-      }
+          if (internalWebsocketClient !== client) return
+        } catch {
+          if (internalWebsocketClient !== client) return
+          if (sessionSignal?.aborted) return
 
-      return
+          if (signal.aborted) {
+            for (let remaining = index; remaining < events.length; remaining += 1) {
+              bufferOutgoingEvent(events[remaining])
+            }
+
+            return
+          }
+
+          const socketOpen = client.socket?.readyState === client.socket?.OPEN
+
+          if (socketOpen) continue
+
+          for (let remaining = index; remaining < events.length; remaining += 1) {
+            bufferOutgoingEvent(events[remaining])
+          }
+
+          return
+        }
+      }
     }
-  }
+  )
 }
 
 /**
@@ -1784,6 +1875,29 @@ function frontendModelTransportSignal() {
   return configuredSignal || undefined
 }
 
+/**
+ * Resolves per-startup controls with the configured session cancellation.
+ * @param {{timeoutMs?: number, signal?: AbortSignal}} controls - Call controls.
+ * @returns {{timeoutMs?: number, signal?: AbortSignal}} - Effective startup controls.
+ */
+function frontendModelWebsocketStartupControls(controls) {
+  const sessionSignal = frontendModelTransportSignal()
+  let signal = controls.signal || sessionSignal
+
+  if (controls.signal && sessionSignal && controls.signal !== sessionSignal) {
+    signal = AbortSignal.any([controls.signal, sessionSignal])
+  }
+
+  const configuredTimeoutMs = frontendModelTransportTimeoutMs()
+  const timeoutMs = controls.timeoutMs === undefined
+    ? configuredTimeoutMs
+    : configuredTimeoutMs === undefined
+      ? controls.timeoutMs
+      : Math.min(controls.timeoutMs, configuredTimeoutMs)
+
+  return {signal, timeoutMs}
+}
+
 /**
  * Runs perform shared frontend model api request.
  * @param {Record<string, ?>} requestPayload - Shared request payload.
@@ -2897,7 +3011,7 @@ export default class FrontendModelBase {
     if (Object.prototype.hasOwnProperty.call(config, "websocketUrl")) {
       frontendModelTransportConfig.websocketUrl = config.websocketUrl
       // Reset cached internal client so the new URL takes effect on next subscribe
-      internalWebsocketClient = null
+      resetInternalWebsocketClient()
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "requestHeaders")) {
@@ -2909,7 +3023,10 @@ export default class FrontendModelBase {
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "signal")) {
-      frontendModelTransportConfig.signal = config.signal
+      if (frontendModelTransportConfig.signal !== config.signal) {
+        frontendModelTransportConfig.signal = config.signal
+        resetInternalWebsocketClient()
+      }
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "timeZone")) {
@@ -2923,7 +3040,7 @@ export default class FrontendModelBase {
     if (Object.prototype.hasOwnProperty.call(config, "sessionStore")) {
       frontendModelTransportConfig.sessionStore = config.sessionStore
       // Reset cached internal client so the new sessionStore is picked up.
-      internalWebsocketClient = null
+      resetInternalWebsocketClient()
     }
 
     if (Object.prototype.hasOwnProperty.call(config, "offlineSync")) {
@@ -2933,16 +3050,17 @@ export default class FrontendModelBase {
 
   /**
    * Connect the internal WebSocket and enable auto-reconnect.
+   * @param {{timeoutMs?: number, signal?: AbortSignal}} [options] - Startup controls composed with the configured transport controls.
    * @returns {Promise<void>} - Resolves when connected.
    */
-  static async connectWebsocket() {
+  static async connectWebsocket(options = {}) {
     const client = resolveInternalWebsocketClient()
 
     if (!client) {
       throw new Error("connectWebsocket requires configureTransport({websocketUrl})")
     }
 
-    await client.connect()
+    await client.connect(frontendModelWebsocketStartupControls(options))
   }
 
   /**
@@ -2952,7 +3070,10 @@ export default class FrontendModelBase {
   static async disconnectWebsocket() {
     if (!internalWebsocketClient) return
 
-    await internalWebsocketClient.disconnectAndStopReconnect()
+    const client = internalWebsocketClient
+
+    detachInternalWebsocketClient(client)
+    await client.disconnectAndStopReconnect()
   }
 
   /**
@@ -3026,7 +3147,7 @@ export default class FrontendModelBase {
    * functions change (e.g. current-user sign-in/out). The handle
    * retries when the WS client isn't ready and reopens on close.
    * @param {string} connectionType - Connection class name registered on the server.
-   * @param {{shouldConnect: () => boolean, params: () => Record<string, ?>, onMessage?: (body: ?) => void}} options - Connection lifecycle and payload callbacks.
+   * @param {{shouldConnect: () => boolean, params: () => Record<string, ?>, signal?: AbortSignal, onMessage?: (body: ?) => void}} options - Connection lifecycle, cancellation, and payload callbacks.
    * @returns {{sync: () => void, close: () => void}} - Handle used to resync or close the managed connection.
    */
   static openManagedConnection(connectionType, options) {
@@ -3040,11 +3161,29 @@ export default class FrontendModelBase {
      * @type {ReturnType<typeof setTimeout> | null} */
     let retryTimer = null
     let lastParamsJson = ""
+    const controls = frontendModelWebsocketStartupControls({signal: options.signal})
+    const clearRetryTimer = () => {
+      if (retryTimer === null) return
+
+      globalThis.clearTimeout(retryTimer)
+      retryTimer = null
+    }
+
+    const close = () => {
+      if (closed) return
+
+      closed = true
+      clearRetryTimer()
+      controls.signal?.removeEventListener("abort", close)
+      if (connection && !connection.isClosed()) connection.close()
+      connection = null
+    }
 
     const sync = () => {
       if (closed) return
 
       if (!options.shouldConnect()) {
+        clearRetryTimer()
         if (connection && !connection.isClosed()) connection.close()
         connection = null
         lastParamsJson = ""
@@ -3087,7 +3226,7 @@ export default class FrontendModelBase {
       }
 
       lastParamsJson = nextParamsJson
-      connection = FrontendModelBase.openWebsocketConnection(connectionType, {
+      connection = client.openConnection(connectionType, {
         params: nextParams,
         onMessage: options.onMessage,
         onClose: () => {
@@ -3100,14 +3239,13 @@ export default class FrontendModelBase {
       })
     }
 
-    const close = () => {
-      closed = true
-      if (retryTimer !== null) globalThis.clearTimeout(retryTimer)
-      if (connection && !connection.isClosed()) connection.close()
-      connection = null
-    }
+    controls.signal?.addEventListener("abort", close, {once: true})
 
-    sync()
+    if (controls.signal?.aborted) {
+      close()
+    } else {
+      sync()
+    }
 
     return {sync, close}
   }
@@ -3118,34 +3256,47 @@ export default class FrontendModelBase {
    * `openConnection`. Apps use this for per-session state/messaging
    * that doesn't fit the pub/sub Channel model (locale, presence).
    * @param {string} connectionType - Name the server registered the class under.
-   * @param {{params?: Record<string, ?>, onConnect?: () => void, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options and event handlers.
+   * @param {{params?: Record<string, ?>, timeoutMs?: number, signal?: AbortSignal, onConnect?: () => void, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Connection options, readiness controls, and event handlers. Connect the client first; the timeout covers server-confirmed readiness and the signal cancels readiness without entering the wire payload.
    * @returns {{ready: Promise<void>, close: () => void}} - Websocket connection handle.
    */
-  static openWebsocketConnection(connectionType, options) {
+  static openWebsocketConnection(connectionType, options = {}) {
     const client = /** @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.openConnection !== "function") {
       throw new Error("openWebsocketConnection requires configureTransport({websocketUrl})")
     }
 
-    return client.openConnection(connectionType, options || {})
+    const {signal, timeoutMs, ...connectionOptions} = options
+
+    return client.openConnection(connectionType, {
+      ...connectionOptions,
+      ...frontendModelWebsocketStartupControls({signal, timeoutMs})
+    })
   }
 
   /**
    * Subscribes to a pub/sub `WebsocketChannel`. Thin wrapper around
    * the internal client's `subscribeChannel`.
    * @param {string} channelType - Channel class name registered on the server.
-   * @param {{params?: Record<string, ?>, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel subscription options and event handlers.
+   * @param {{params?: Record<string, ?>, timeoutMs?: number, signal?: AbortSignal, onMessage?: (body: Record<string, unknown>) => void, onDisconnect?: () => void, onResume?: () => void, onClose?: (reason: string) => void}} [options] - Channel options, startup controls, and event handlers. The timeout covers connect and server-confirmed readiness only; the signal cancels startup without entering the wire payload.
    * @returns {{ready: Promise<void>, close: () => void}} - Websocket channel handle from the configured client.
    */
-  static subscribeWebsocketChannel(channelType, options) {
+  static subscribeWebsocketChannel(channelType, options = {}) {
     const client = /** @type {?} */ (frontendModelTransportConfig.websocketClient || resolveInternalWebsocketClient())
 
     if (!client || typeof client.subscribeChannel !== "function") {
       throw new Error("subscribeWebsocketChannel requires configureTransport({websocketUrl})")
     }
 
-    return client.subscribeChannel(channelType, options || {})
+    const {signal, timeoutMs, ...channelOptions} = options
+    const startupControls = frontendModelWebsocketStartupControls({signal, timeoutMs})
+    const handle = client.subscribeChannel(channelType, {...channelOptions, ...startupControls})
+
+    if (typeof client.connect === "function") {
+      void client.connect(startupControls).catch(() => handle.close())
+    }
+
+    return handle
   }
 
   /**