velocious 1.0.557 → 1.0.558

package/README.md

@@ -10,7 +10,7 @@
 * Migrations for schema changes and UTC datetime storage (see [docs/database-migrations.md](docs/database-migrations.md))
 * External packages (engines) that contribute data models, frontend-model resources and migrations to a consuming app (see [docs/packages.md](docs/packages.md))
 * Controllers and views for HTTP endpoints
-* Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses (see [docs/frontend-models.md](docs/frontend-models.md))
+* Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses and one-budget WebSocket startup controls (see [docs/frontend-models.md](docs/frontend-models.md) and [docs/websocket-channels.md](docs/websocket-channels.md))
 * Client-side offline sync mutation logs and frontend-model optimistic queueing primitives (see [docs/offline-sync.md](docs/offline-sync.md))
 * Declarative client sync scopes with per-scope cursors, automatic mutation tracking, realtime delivery, and `sync`/`pull` progress reporting for "X of Y" import screens (see [docs/sync-client.md](docs/sync-client.md))
 * Reactive `useLiveQuery(Model.where(...))` queries that stay current from committed local model changes across local writes, pulls, and realtime (see [docs/live-queries.md](docs/live-queries.md))
@@ -75,6 +75,11 @@ Baselines are generated against a fresh checkout (no generated dummy `configurat
 
 # Testing
 
+The dummy database configurations require `MSSQL_SA_PASSWORD` whenever they include
+the shared MSSQL test database. Set it in the local process environment rather than
+writing the password into `spec/dummy/src/config/configuration*.js`. TensorBuzz CI
+provides one shared test value to both the build and MSSQL service environments.
+
 Tag tests to filter runs.
 
 ```js
@@ -2139,6 +2144,15 @@ Inline jobs share the worker process and run concurrently up to `maxConcurrentIn
 new BackgroundJobsWorker({configuration, maxConcurrentInlineJobs: 8})
 ```
 
+Standalone background-jobs main and worker processes close their configuration's
+database pools during `stop()`. Embedded/test callers that share externally owned
+pools can pass `closeDatabaseConnectionsOnStop: false` to `BackgroundJobsMain` or
+`BackgroundJobsWorker`; sockets and Beacon still shut down normally. An async
+`onStopped` constructor hook can coordinate externally owned cleanup after that
+shutdown without wrapping the service's `stop()` method. Repeated `stop()` calls
+share one lifecycle and invoke the hook once; dual shutdown/hook failures reject
+with an `AggregateError` ordered with the shutdown failure first.
+
 ## Scheduled jobs
 
 Velocious can enqueue recurring jobs from the `background-jobs-main` process. Configure them with `scheduledBackgroundJobs` using Sidekiq Scheduler-style `every` arrays:
@@ -2383,7 +2397,7 @@ Tenant lifecycle commands print start and final counts, report each completed te
 
 `afterMigrateTenant` hooks run inside the active default and tenant database connection scope for the tenant being migrated.
 
-At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a tenant context, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. `Tenant.with` and `Tenant.each` run their callbacks inside `ensureConnections`, so switching into a tenant establishes its database connections (global + tenant) and passes them to the callback — the tenant is immediately queryable without the caller wiring up connections (already-open connections are reused, so nesting does not double-connect). `Tenant.with` is generic over its callback's return type, so a value returned from inside the tenant context comes back to the caller with its type preserved (no cast needed). `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
+At runtime, the apartment-style `Tenant` façade (`velocious/build/src/tenants/tenant.js`) is the single entry point: `Tenant.with(tenant, callback)` / `Tenant.current()` to switch into and read a tenant context, `Tenant.each({identifier, callback, parallel?, filter?})` to run a callback within every provider-listed tenant, and `Tenant.drop({identifier, tenant})` (plus the `db:tenants:drop` CLI command) to drop a tenant's database through the provider's `dropDatabase` hook. `Tenant.with` and `Tenant.each` run their callbacks inside `ensureConnections`, so switching into a tenant establishes its database connections (global + tenant), initializes registered tenant-switched models whose tables exist, and passes the connections to the callback — the tenant is immediately queryable without caller-owned connection or model initialization (already-open connections and in-progress model initialization promises are reused). Models for absent optional tables stay deferred. `Tenant.with` is generic over its callback's return type, so a value returned from inside the tenant context comes back to the caller with its type preserved (no cast needed). `Tenant.aggregateAcross({identifier, aggregates, keyColumns, subquery, tenants?, filter?})` runs one aggregate over the same table across many tenant databases and returns the merged result — grouping tenants by server and using a single cross-database `UNION ALL` where the driver supports two-part `` `database`.`table` `` references (MySQL/MariaDB) or one query per tenant otherwise (PostgreSQL/SQLite/MSSQL).
 
 `SchemaCloner` adds a missing auto-increment column and its separate source unique index in one schema alteration, including on MySQL/MariaDB where an auto-increment column must be keyed when it is created.
 

package/build/background-jobs/main.js

@@ -7,6 +7,7 @@ import BackgroundJobsStore from "./store.js"
 import Logger from "../logger.js"
 import PruneTerminalBackgroundJobsJob from "../jobs/prune-terminal-background-jobs.js"
 import VelociousError from "../velocious-error.js"
+import shutdownLifecycle from "../utils/shutdown-lifecycle.js"
 
 /**
  * Channel used by `background-jobs-main` to coordinate dispatch wake-ups
@@ -60,9 +61,13 @@ export default class BackgroundJobsMain {
    * @param {number} [args.port] - Port.
    * @param {number} [args.workerStaleTimeoutMs] - Override how long a silent worker may go before being dropped (default 60000ms).
    * @param {number} [args.workerLivenessSweepMs] - Override how often stale workers are swept for (default 15000ms).
+   * @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 main process finishes stopping.
    */
-  constructor({configuration, host, port, workerStaleTimeoutMs, workerLivenessSweepMs}) {
+  constructor({configuration, host, port, workerStaleTimeoutMs, workerLivenessSweepMs, closeDatabaseConnectionsOnStop = true, onStopped}) {
     this.configuration = configuration
+    this.closeDatabaseConnectionsOnStop = closeDatabaseConnectionsOnStop
+    this.onStopped = onStopped
     const config = configuration.getBackgroundJobsConfig()
     this.host = host || config.host
     this.port = typeof port === "number" ? port : config.port
@@ -123,6 +128,8 @@ export default class BackgroundJobsMain {
     this._draining = false
     this._redrainQueued = false
     this._stopped = false
+    /** @type {Promise<void> | undefined} */
+    this.stopPromise = undefined
     /**
      * Narrows the runtime value to the documented type.
      * @type {(() => void) | undefined} */
@@ -143,6 +150,7 @@ export default class BackgroundJobsMain {
    */
   async start() {
     this._stopped = false
+    this.stopPromise = undefined
     this.configuration.setCurrent()
     await this.configuration.initialize({type: "background-jobs-main"})
     await this.configuration.connectBeacon({peerType: "background-jobs-main"})
@@ -214,18 +222,33 @@ export default class BackgroundJobsMain {
    * Runs stop.
    * @returns {Promise<void>} - Resolves when closed.
    */
-  async stop() {
+  stop() {
+    if (!this.stopPromise) this.stopPromise = this._stop()
+
+    return this.stopPromise
+  }
+
+  /**
+   * Runs the main-process shutdown lifecycle once.
+   * @returns {Promise<void>} - Resolves when closed.
+   */
+  async _stop() {
     this._stopped = true
 
-    this._closeWorkers()
-    this._clearTimers()
-    this._disconnectBeaconHandlers()
-    await this.scheduler?.stop()
-    try {
-      await this._drainWorkerHandoffAdoptions()
-    } finally {
-      await this._stopBeaconAndServer()
-    }
+    await shutdownLifecycle({
+      onStopped: this.onStopped,
+      shutdown: async () => {
+        this._closeWorkers()
+        this._clearTimers()
+        this._disconnectBeaconHandlers()
+        await this.scheduler?.stop()
+        try {
+          await this._drainWorkerHandoffAdoptions()
+        } finally {
+          await this._stopBeaconAndServer()
+        }
+      }
+    })
   }
 
   /**
@@ -287,7 +310,7 @@ export default class BackgroundJobsMain {
     try {
       await this._closeServer()
     } finally {
-      await this.configuration.closeDatabaseConnections()
+      if (this.closeDatabaseConnectionsOnStop) await this.configuration.closeDatabaseConnections()
     }
   }
 

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