velocious 1.0.617 → 1.0.618

package/build/testing/shared-transaction-connection-coordinator.js

@@ -1,8 +1,34 @@
 // @ts-check
 
-/** @type {WeakMap<object, {coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, owner: symbol}>} */
+/** @typedef {{coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, ownedQueue: Promise<void>, owner: symbol}} CoordinatorRegistration */
+
+/** @type {WeakMap<object, CoordinatorRegistration>} */
 const coordinators = new WeakMap()
 
+/**
+ * Serializes sibling work that inherited one coordinator owner without re-entering the broker queue.
+ * @template T
+ * @param {CoordinatorRegistration} registration - Physical connection registration.
+ * @param {() => Promise<T>} callback - Owned operation.
+ * @returns {Promise<T>} - Operation result.
+ */
+async function coordinateOwnedSharedTransactionConnection(registration, callback) {
+  const previous = registration.ownedQueue
+  /**
+   * Releases the next owned sibling operation.
+   * @type {() => void}
+   */
+  let release = () => {}
+
+  registration.ownedQueue = new Promise((resolve) => { release = resolve })
+  await previous
+  try {
+    return await callback()
+  } finally {
+    release()
+  }
+}
+
 /**
  * Registers test-only serialization owned by the active broker.
  * @param {object} connection - Parent physical connection.
@@ -12,7 +38,7 @@ const coordinators = new WeakMap()
 export function setSharedTransactionCoordinator(connection, coordinator) {
   const owner = Symbol("shared-transaction-coordinator")
 
-  coordinators.set(connection, {coordinator, owner})
+  coordinators.set(connection, {coordinator, ownedQueue: Promise.resolve(), owner})
   return owner
 }
 
@@ -43,7 +69,7 @@ export async function coordinateSharedTransactionConnection(connection, callback
   const environmentHandler = connection.configuration.getEnvironmentHandler()
 
   if (environmentHandler.getSharedTransactionCoordinatorOwner(connection) === registration.owner) {
-    return await callback()
+    return await coordinateOwnedSharedTransactionConnection(registration, callback)
   }
 
   return /** @type {T} */ (await registration.coordinator(async () => {

package/build/testing/test-runner.js

@@ -39,6 +39,7 @@ import { SHARED_TRANSACTION_BROKER_ENV } from "./shared-transaction-proxy-driver
  * @property {string[] | string} [tags] - Tags for filtering.
  * @property {number} [timeoutSeconds] - Timeout in seconds for the test.
  * @property {string} [type] - Test type identifier.
+ * @property {(args: {databaseIdentifier: string, tenant: object}) => Promise<void>} [registerTransactionalTenant] - Registers one resolved tenant database transaction for this attempt.
  */
 /**
  * TestData type.
@@ -118,6 +119,18 @@ import { SHARED_TRANSACTION_BROKER_ENV } from "./shared-transaction-proxy-driver
  * @property {boolean} environmentPublished - Whether child-process coordinates were published.
  * @property {string | undefined} previousEnvironment - Environment value to restore after publication.
  */
+/**
+ * TransactionalTenantRegistration type.
+ * @typedef {object} TransactionalTenantRegistration
+ * @property {Promise<{connection: import("../database/drivers/base.js").default | undefined, error: Error | undefined}> | undefined} [checkoutPromise] - Attempt-owned physical checkout outcome.
+ * @property {import("../database/drivers/base.js").default | undefined} connection - Attempt-owned physical connection once checkout resolves.
+ * @property {Promise<void> | undefined} [cleanupPromise] - Single cleanup operation shared by emergency and eventual lifecycle cleanup.
+ * @property {boolean | undefined} [discardOnCleanup] - Whether timeout emergency cleanup must quarantine this connection.
+ * @property {import("../database/pool/base.js").default} pool - Owning logical pool.
+ * @property {boolean} revoked - Whether this attempt may still publish the physical registration.
+ * @property {string} reuseKey - Resolved physical configuration identity.
+ * @property {import("../database/pool/base.js").TestSharedConnectionRegistration | undefined} sharedRegistration - Physical-key shared registration once published.
+ */
 
 /**
  * Runs run with timeout.
@@ -641,6 +654,138 @@ export default class TestRunner {
     }
   }
 
+  /**
+   * Checks out and registers one physical tenant transaction for the current attempt.
+   * @param {{databaseIdentifier: string, tenant: object}} args - Logical identifier and tenant descriptor.
+   * @param {TransactionalTenantRegistration[]} registrations - Current attempt registrations.
+   * @returns {Promise<void>}
+   */
+  async registerTransactionalTenant({databaseIdentifier, tenant, ...restArgs}, registrations) {
+    restArgsError(restArgs)
+    if (!databaseIdentifier) throw new Error("registerTransactionalTenant requires a databaseIdentifier")
+    if (!tenant) throw new Error("registerTransactionalTenant requires a tenant")
+
+    const configuration = this.getConfiguration()
+    const pool = configuration.getDatabasePool(databaseIdentifier)
+    const databaseConfiguration = configuration.resolveDatabaseConfiguration(databaseIdentifier, tenant)
+    if (!databaseConfiguration.tenantOnly) {
+      throw new Error(`registerTransactionalTenant requires a tenantOnly database: ${databaseIdentifier}`)
+    }
+    const reuseKey = pool.getConfigurationReuseKey(databaseConfiguration)
+    if (registrations.some((registration) => registration.pool === pool && registration.reuseKey === reuseKey)) return
+
+    /** @type {TransactionalTenantRegistration} */
+    const registration = {
+      connection: undefined,
+      pool,
+      reuseKey,
+      revoked: false,
+      sharedRegistration: undefined
+    }
+
+    registrations.push(registration)
+    registration.checkoutPromise = pool
+      .checkoutForConfiguration(databaseConfiguration, {name: "Transactional tenant test registration"})
+      .then(
+        (connection) => ({connection, error: undefined}),
+        (error) => ({
+          connection: undefined,
+          error: error instanceof Error ? error : new Error("Transactional tenant connection checkout failed", {cause: error})
+        })
+      )
+
+    try {
+      const checkoutOutcome = await registration.checkoutPromise
+
+      if (checkoutOutcome.error) throw checkoutOutcome.error
+      if (!checkoutOutcome.connection) throw new Error("Transactional tenant connection checkout returned no connection")
+      registration.connection = checkoutOutcome.connection
+      if (registration.revoked) throw new Error("Transactional tenant test registration attempt is no longer active")
+
+      await registration.connection.startTransaction()
+      if (registration.revoked) throw new Error("Transactional tenant test registration attempt is no longer active")
+
+      const sharedRegistration = pool.setTestSharedConnectionForConfiguration(registration.connection, reuseKey)
+      if (!sharedRegistration) throw new Error(`Database pool does not support transactional tenant test connections: ${databaseIdentifier}`)
+      registration.sharedRegistration = sharedRegistration
+      if (registration.revoked) {
+        pool.clearTestSharedConnection(sharedRegistration)
+        throw new Error("Transactional tenant test registration attempt is no longer active")
+      }
+    } catch (error) {
+      registration.revoked = true
+      try {
+        await this.cleanupTransactionalTenants([registration], {discard: registration.discardOnCleanup === true})
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "Failed to register and clean up a transactional tenant test connection", {cause: cleanupError})
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Revokes attempt registrations before rolling back and releasing their connections.
+   * @param {TransactionalTenantRegistration[]} registrations - Attempt registrations.
+   * @param {{discard?: boolean}} [options] - Whether connections must be discarded instead of returned to the pool.
+   * @returns {Promise<void>}
+   */
+  async cleanupTransactionalTenants(registrations, {discard = false} = {}) {
+    for (const registration of registrations) {
+      registration.revoked = true
+      if (discard) registration.discardOnCleanup = true
+      if (registration.sharedRegistration) registration.pool.clearTestSharedConnection(registration.sharedRegistration)
+    }
+    const cleanupResults = await Promise.allSettled([...registrations].reverse().map((registration) => {
+      registration.cleanupPromise ??= this.cleanupTransactionalTenantRegistration(registration)
+
+      return registration.cleanupPromise
+    }))
+    const errors = cleanupResults
+      .filter((result) => result.status === "rejected")
+      .map((result) => result.reason)
+
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to clean up transactional tenant test connections")
+  }
+
+  /**
+   * Cleans one attempt registration exactly once, including a checkout that was still pending at revocation.
+   * @param {TransactionalTenantRegistration} registration - Attempt-owned registration.
+   * @returns {Promise<void>} - Resolves after rollback and release or quarantine.
+   */
+  async cleanupTransactionalTenantRegistration(registration) {
+    let connection = registration.connection
+
+    if (!connection && registration.checkoutPromise) {
+      const checkoutOutcome = await registration.checkoutPromise
+
+      if (checkoutOutcome.error) return
+      connection = checkoutOutcome.connection
+      registration.connection = connection
+    }
+    if (!connection) return
+
+    const errors = []
+
+    try {
+      if (connection.insideTransaction()) await connection.rollbackTransaction()
+    } catch (error) {
+      errors.push(error)
+    } finally {
+      try {
+        if (registration.discardOnCleanup) {
+          await registration.pool.discard(connection)
+        } else {
+          await registration.pool.checkin(connection)
+        }
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to clean up a transactional tenant test connection")
+  }
+
   /**
    * Selects the current non-tenant connections eligible for shared transaction work.
    * @param {{transactionsOnly: boolean}} args - Selection options.
@@ -1014,6 +1159,29 @@ export default class TestRunner {
     console.error(error)
   }
 
+  /**
+   * Records a rollback/discard failure that settled after timeout cleanup moved on.
+   * @param {unknown} reason - Detached cleanup rejection.
+   * @returns {void}
+   */
+  recordTransactionalTenantCleanupFailure(reason) {
+    const error = reason instanceof Error ? reason : new Error(`Transactional tenant cleanup failed: ${String(reason)}`)
+    const near = this._lastTestContext
+    const attribution = near ? `, near test: ${near.fullDescription} (${near.filePath}:${near.line})` : ""
+
+    this._failedTests = (this._failedTests || 0) + 1
+    this._failedTestDetails.push({
+      fullDescription: `<transactional tenant emergency cleanup failure${attribution}>`,
+      filePath: near ? near.filePath : "<test runner>",
+      line: near ? near.line : 0,
+      error,
+      consoleOutput: undefined
+    })
+
+    console.error(picocolors.red(`\n[test-runner] transactional tenant emergency cleanup failed after the bounded timeout grace.${attribution}`))
+    console.error(error)
+  }
+
   async run() {
     /**
      * Handles a process-level unhandled rejection during the run.
@@ -1232,6 +1400,11 @@ export default class TestRunner {
           let sharedTransactionBrokerRegistration
           /** @type {SharedTransactionBrokerRegistration | undefined} */
           let sharedTransactionBrokerPreparation
+          /** @type {TransactionalTenantRegistration[]} */
+          const transactionalTenantRegistrations = []
+          testArgs.registerTransactionalTenant = async (args) => {
+            await this.registerTransactionalTenant(args, transactionalTenantRegistrations)
+          }
           const stopConsoleCapture = this.startConsoleCapture({
             passthrough: testConfig.consoleOutput === "live"
           })
@@ -1324,15 +1497,19 @@ export default class TestRunner {
                           sharedTransactionBrokerRegistration = undefined
                           sharedTransactionBrokerPreparation = undefined
                         } finally {
-                          for (const afterEachData of newAfterEaches) {
-                            await this.runProfileSpan({
-                              phase: "afterEach",
-                              declarationIndex: afterEachData.declarationIndex,
-                              declarationScopeId: afterEachData.declarationScopeId,
-                              filePath: afterEachData.ownerFilePath
-                            }, async () => {
-                              await afterEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
-                            })
+                          try {
+                            for (const afterEachData of newAfterEaches) {
+                              await this.runProfileSpan({
+                                phase: "afterEach",
+                                declarationIndex: afterEachData.declarationIndex,
+                                declarationScopeId: afterEachData.declarationScopeId,
+                                filePath: afterEachData.ownerFilePath
+                              }, async () => {
+                                await afterEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
+                              })
+                            }
+                          } finally {
+                            await this.cleanupTransactionalTenants(transactionalTenantRegistrations)
                           }
                         }
                       }
@@ -1401,6 +1578,18 @@ export default class TestRunner {
               await this.stopSharedTransactionBroker(sharedTransactionBrokerRegistration || sharedTransactionBrokerPreparation)
               sharedTransactionBrokerRegistration = undefined
               sharedTransactionBrokerPreparation = undefined
+              const emergencyCleanup = this.cleanupTransactionalTenants(transactionalTenantRegistrations, {discard: true})
+              const emergencyCleanupSettled = await awaitSettledOrGrace(emergencyCleanup, timeoutMs ?? 60000)
+
+              if (emergencyCleanupSettled) {
+                await emergencyCleanup
+              } else {
+                // The timed-out attempt must not block the runner indefinitely, but a
+                // later rollback/discard failure still becomes a visible test failure.
+                void emergencyCleanup.catch((cleanupError) => {
+                  this.recordTransactionalTenantCleanupFailure(cleanupError)
+                })
+              }
             }
 
             willRetry = retriesUsed < retryCount

package/package.json

@@ -3,7 +3,7 @@
     "velocious": "build/bin/velocious.js"
   },
   "name": "velocious",
-  "version": "1.0.617",
+  "version": "1.0.618",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [

package/src/background-jobs/client.js

@@ -1,16 +1,21 @@
 // @ts-check
 
+import timeout from "awaitery/build/timeout.js"
 import configurationResolver from "../configuration-resolver.js"
 import BackgroundJobsSocketRequest from "./socket-request.js"
 
+const DEFAULT_ENQUEUE_TIMEOUT_MS = 5000
+
 export default class BackgroundJobsClient {
   /**
    * Runs constructor.
    * @param {object} [args] - Options.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration.
+   * @param {number} [args.enqueueTimeoutMs] - Maximum time to wait for an enqueue acknowledgement in milliseconds (default: 5000).
    */
-  constructor({configuration} = {}) {
+  constructor({configuration, enqueueTimeoutMs = DEFAULT_ENQUEUE_TIMEOUT_MS} = {}) {
     this.configurationPromise = configuration ? Promise.resolve(configuration) : configurationResolver()
+    this.enqueueTimeoutMs = enqueueTimeoutMs
   }
 
   /**
@@ -35,7 +40,11 @@ export default class BackgroundJobsClient {
   async enqueue({jobName, args, options}) {
     const request = await this._request()
 
-    return await request.run({
+    return await timeout({
+      errorMessage: `Background job enqueue acknowledgement timed out after ${this.enqueueTimeoutMs}ms`,
+      timeout: this.enqueueTimeoutMs
+    }, async ({control}) => await request.run({
+      signal: control.signal,
       onConnect: (jsonSocket) => {
         jsonSocket.send({
           type: "enqueue",
@@ -54,7 +63,7 @@ export default class BackgroundJobsClient {
           reject(new Error(message.error || "Failed to enqueue job"))
         }
       }
-    })
+    }))
   }
 
   /**

package/src/background-jobs/socket-request.js

@@ -89,6 +89,10 @@ export default class BackgroundJobsSocketRequest {
         finish({}, () => reject(error))
       })
 
+      jsonSocket.on("close", () => {
+        finish({destroy: true}, () => reject(new Error("Background jobs socket closed before the request was acknowledged")))
+      })
+
       /**
        * Handles the socket response message.
        * @param {import("./types.js").BackgroundJobSocketMessage} message - Socket message.

package/src/database/migration/index.js

@@ -1,5 +1,6 @@
 // @ts-check
 
+/** @typedef {import("../table-data/table-column.js").TableColumnArgsType} AddColumnArgsType */
 /**
  * CreateTableIdArgsType type.
  * @typedef {object} CreateTableIdArgsType
@@ -109,7 +110,7 @@ export default class VelociousDatabaseMigration {
    * @param {string} tableName - Table name.
    * @param {string} columnName - Column name.
    * @param {string} columnType - Column type.
-   * @param {import("../table-data/table-column.js").TableColumnArgsType} [args] - Options object.
+   * @param {AddColumnArgsType} [args] - Options object.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async addColumn(tableName, columnName, columnType, args) {

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

@@ -55,6 +55,9 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   _testSharedConnectionRegistration = undefined
 
+  /** Attempt-owned shared connections keyed by resolved physical configuration. */
+  _testSharedConnectionsByReuseKey = new Map()
+
   /**
    * Connections.
    * @type {import("../drivers/base.js").default[]} */
@@ -249,6 +252,30 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     if (this.connections.includes(connection)) await this.handleCheckedInIdleConnection()
   }
 
+  /**
+   * Permanently removes and closes a checked-out connection.
+   * @param {import("../drivers/base.js").default} connection - Connection that must not return to the pool.
+   */
+  async discard(connection) {
+    const id = connection.getIdSeq()
+    const errors = []
+
+    this.untrackConnectionInUse(connection, id)
+    try {
+      await this.closeConnection(connection)
+    } catch (error) {
+      errors.push(error)
+    }
+    try {
+      await this.drainPendingCheckouts()
+    } catch (error) {
+      errors.push(error)
+    }
+
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to discard a database connection")
+  }
+
   /**
    * Runs close checked out connection after checkin failure.
    * @param {import("../drivers/base.js").default} connection - Connection that failed check-in cleanup.
@@ -885,6 +912,13 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     if (!actualCallback) throw new Error("withConnection requires a callback")
 
+    const testSharedConnection = this.activeTestSharedConnection()
+    if (testSharedConnection && this.connectionMatchesCurrentConfiguration(testSharedConnection)) {
+      return await this.asyncLocalStorage.run(testSharedConnection.getIdSeq(), async () => {
+        return await actualCallback(testSharedConnection)
+      })
+    }
+
     const connection = await this.checkout(options)
     const id = connection.getIdSeq()
 
@@ -1079,12 +1113,35 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     return registration
   }
 
+  /**
+   * Registers an attempt-owned connection for exactly one physical configuration.
+   * @param {import("../drivers/base.js").default} connection - Attempt-owned connection.
+   * @param {string} reuseKey - Resolved physical configuration identity.
+   * @returns {import("./base.js").TestSharedConnectionRegistration} - Opaque registration handle.
+   */
+  setTestSharedConnectionForConfiguration(connection, reuseKey) {
+    const registration = {owner: Symbol("test-shared-physical-connection")}
+
+    this._testSharedConnectionsByReuseKey.set(reuseKey, {connection, registration})
+    return registration
+  }
+
   /**
    * Clears the current shared connection registration. A supplied stale registration
    * cannot clear a provider installed by a newer lifecycle.
    * @param {import("./base.js").TestSharedConnectionRegistration} [registration] - Opaque registration handle to clear conditionally.
    * @returns {void} */
   clearTestSharedConnection(registration) {
+    if (registration) {
+      for (const [reuseKey, entry] of this._testSharedConnectionsByReuseKey) {
+        if (entry.registration !== registration) continue
+        this._testSharedConnectionsByReuseKey.delete(reuseKey)
+        return
+      }
+    } else {
+      this._testSharedConnectionsByReuseKey.clear()
+    }
+
     if (registration && registration !== this._testSharedConnectionRegistration) return
 
     this._testSharedConnection = undefined
@@ -1103,18 +1160,38 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {T} - Callback result.
    */
   runWithTestSharedConnection(callback) {
-    const connection = this.testSharedConnection()
+    const connection = this.activeTestSharedConnection()
 
     if (!connection) return callback()
 
     return this.asyncLocalStorage.run(connection.getIdSeq(), callback)
   }
 
+  /**
+   * Resolves a test-shared connection only while its checkout ID is still owned by this pool.
+   * Fallback-only registrations have no checkout ID and must enter the normal checkout path.
+   * @returns {import("../drivers/base.js").default | undefined} - Active shared connection.
+   */
+  activeTestSharedConnection() {
+    const connection = this.testSharedConnection()
+    const id = connection?.getIdSeq()
+
+    if (typeof id !== "number") return
+    if (this.connectionsInUse[id] !== connection) return
+
+    return connection
+  }
+
   /**
    * Resolves the connection currently eligible for in-process test request sharing.
    * @returns {import("../drivers/base.js").default | undefined} - Shared connection.
    */
   testSharedConnection() {
+    const reuseKey = this.getConfigurationReuseKey()
+    const physicalRegistration = this._testSharedConnectionsByReuseKey.get(reuseKey)
+
+    if (physicalRegistration) return physicalRegistration.connection
+
     return this._testSharedConnectionProvider
       ? this._testSharedConnectionProvider()
       : this._testSharedConnection

package/src/database/pool/base.js

@@ -126,6 +126,16 @@ class VelociousDatabasePoolBase {
     throw new Error("'checkin' not implemented")
   }
 
+  /**
+   * Permanently discards an attempt-owned checked-out connection.
+   * @abstract
+   * @param {import("../drivers/base.js").default} _connection - Connection that must not return to the pool.
+   * @returns {Promise<void>} - Resolves after the connection is closed and removed from pool ownership.
+   */
+  discard(_connection) {
+    throw new Error("'discard' not implemented")
+  }
+
   /**
    * Runs checkout.
    * @abstract
@@ -175,6 +185,16 @@ class VelociousDatabasePoolBase {
     return undefined
   }
 
+  /**
+   * Registers a test connection for one resolved physical database configuration.
+   * @param {import("../drivers/base.js").default} _connection - Attempt-owned connection.
+   * @param {string} _reuseKey - Resolved physical configuration identity.
+   * @returns {TestSharedConnectionRegistration | undefined} - Opaque registration handle when supported.
+   */
+  setTestSharedConnectionForConfiguration(_connection, _reuseKey) {
+    return undefined
+  }
+
   /**
    * Clears the shared connection or provider set for in-process test requests. No-op by default.
    * When a registration is provided, clears only if it is still the active registration.
@@ -395,6 +415,18 @@ class VelociousDatabasePoolBase {
     return connection
   }
 
+  /**
+   * Checks out a connection for an already-resolved physical configuration.
+   * Multi-configuration pools override this for explicit tenant registrations.
+   * @param {import("../../configuration-types.js").DatabaseConfigurationType} _databaseConfiguration - Captured configuration.
+   * @param {ConnectionCheckoutOptions} [_options] - Checkout options.
+   * @param {{retain: boolean}} [_args] - Pool-specific retention behavior.
+   * @returns {Promise<import("../drivers/base.js").default>} - Checked-out connection.
+   */
+  async checkoutForConfiguration(_databaseConfiguration, _options, _args) {
+    throw new Error("Database pool does not support captured configuration checkout")
+  }
+
   /**
    * Runs close connection after failed connect.
    * @param {import("../drivers/base.js").default} connection - Connection to close.