velocious 1.0.617 → 1.0.618

package/src/database/pool/single-multi-use.js

@@ -45,6 +45,8 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
   /** @type {Set<() => boolean>} */
   capacityWaiters = new Set()
   closeGeneration = 0
+  /** @type {Map<string, {connection: import("../drivers/base.js").default, registration: import("./base.js").TestSharedConnectionRegistration}>} */
+  testSharedConnectionsByReuseKey = new Map()
 
   /**
    * Checks a connection back into its keyed physical entry.
@@ -80,6 +82,24 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
     if (!entry.lifecycleRetained && (!entry.retained || this.capacityWaiters.size > 0)) await this.removeAndCloseEntry(entry)
   }
 
+  /**
+   * 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 entry = this.entryForConnection(connection)
+
+    if (entry) {
+      this.activeCheckoutCount -= entry.activeCheckoutCount
+      entry.activeCheckoutCount = 0
+      entry.checkoutNames = []
+      await this.removeAndCloseEntry(entry)
+      return
+    }
+
+    await connection.close()
+  }
+
   /**
    * Checks out the ambient configuration and retains it as the single mutable
    * browser fallback connection.
@@ -93,11 +113,11 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
   /**
    * Checks out an explicitly captured physical configuration.
    * @param {import("../../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Captured configuration.
-   * @param {import("./base.js").ConnectionCheckoutOptions} options - Checkout options.
-   * @param {{retain: boolean}} args - Whether this becomes the ambient retained connection.
+   * @param {import("./base.js").ConnectionCheckoutOptions} [options] - Checkout options.
+   * @param {{retain: boolean}} [args] - Whether this becomes the ambient retained connection.
    * @returns {Promise<import("../drivers/base.js").default>} - Checked-out connection.
    */
-  async checkoutForConfiguration(databaseConfiguration, options, {retain}) {
+  async checkoutForConfiguration(databaseConfiguration, options = {}, {retain} = {retain: false}) {
     const reuseKey = this.getConfigurationReuseKey(databaseConfiguration)
     let entry = this.connectionEntries.get(reuseKey)
 
@@ -460,6 +480,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
 
     this.connectionEntries.clear()
     this.connectionEntrySpawnPromises.clear()
+    this.testSharedConnectionsByReuseKey.clear()
     this.connection = undefined
     this.activeCheckoutCount = 0
 
@@ -476,6 +497,46 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
     return this.connection
   }
 
+  /**
+   * 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 an attempt-owned shared physical connection without revoking a newer owner.
+   * @param {import("./base.js").TestSharedConnectionRegistration} [registration] - Registration to clear conditionally.
+   */
+  clearTestSharedConnection(registration) {
+    if (!registration) {
+      this.testSharedConnectionsByReuseKey.clear()
+      return
+    }
+
+    for (const [reuseKey, entry] of this.testSharedConnectionsByReuseKey) {
+      if (entry.registration !== registration) continue
+      this.testSharedConnectionsByReuseKey.delete(reuseKey)
+      return
+    }
+  }
+
+  /**
+   * Resolves the attempt-owned connection for the current physical configuration.
+   * @returns {import("../drivers/base.js").default | undefined} - Shared connection.
+   */
+  testSharedConnection() {
+    const reuseKey = this.getConfigurationReuseKey()
+
+    return this.testSharedConnectionsByReuseKey.get(reuseKey)?.connection
+  }
+
   /**
    * Returns the current context fallback connection when it is not suppressed.
    * @returns {import("../drivers/base.js").default | undefined} - Current fallback connection.
@@ -483,7 +544,7 @@ export default class VelociousDatabasePoolSingleMultiUser extends BasePool {
   getCurrentContextConnection() {
     if (this.suppressedConnectionContextCount > 0) return undefined
 
-    return this.connection
+    return this.testSharedConnection() || this.connection
   }
 
   /**

package/src/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/src/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