velocious 1.0.698 → 1.0.700

package/src/http-server/server-lock.js

@@ -1,11 +1,15 @@
 // @ts-check
 
-import fs from "node:fs/promises"
-import os from "node:os"
+import AdvisoryLockFileBackend from "../database/advisory-lock-file-backend.js"
 import path from "node:path"
 
 /**
- * Directory-based lock that allows only one HTTP server process per app directory.
+ * Directory-based lock that allows only one HTTP server process per app
+ * directory. Thin wrapper over the shared file-lock backend
+ * (`src/database/advisory-lock-file-backend.js` — the STC-210 `file` tier
+ * primitive generalized from this lock's original hand-rolled directory
+ * protocol), so the server lock and the advisory-lock file tier share one
+ * acquisition, owner-metadata, lease-renewal, and staleness implementation.
  */
 export default class VelociousHttpServerLock {
   /**
@@ -20,53 +24,26 @@ export default class VelociousHttpServerLock {
     this.host = host
     this.port = port
     this.lockPath = path.join(configuration.getDirectory(), "tmp", "server.lock")
+    this.backend = new AdvisoryLockFileBackend({
+      directory: path.join(configuration.getDirectory(), "tmp"),
+      extraOwnerFields: {host: this.host, port: this.port},
+      pathStyle: "plain"
+    })
     this.acquired = false
   }
 
   /**
-   * Acquires the app-directory HTTP server lock before startup side effects run.
+   * Acquires the app-directory HTTP server lock before startup side effects
+   * run. A stale lock (dead local owner or expired lease) is reclaimed by the
+   * backend; a live foreign owner fails loudly with the owner details.
    * @returns {Promise<void>} - Resolves after the lock has been acquired.
    */
   async acquire() {
-    await fs.mkdir(path.dirname(this.lockPath), {recursive: true})
+    const acquired = await this.backend.acquire("server", {timeoutMs: 0})
 
-    while (true) {
-      const acquired = await this.tryAcquire()
+    if (!acquired) throw new Error(await this.lockHeldMessage())
 
-      if (acquired) {
-        return
-      }
-
-      if (await this.isStale()) {
-        await fs.rm(this.lockPath, {recursive: true, force: true})
-        continue
-      }
-
-      throw new Error(await this.lockHeldMessage())
-    }
-  }
-
-  /**
-   * Tries to create the lock directory and write owner metadata.
-   * @returns {Promise<boolean>} - Whether the lock was acquired.
-   */
-  async tryAcquire() {
-    try {
-      await fs.mkdir(this.lockPath)
-    } catch (error) {
-      if (/** @type {{code?: string}} */ (error).code === "EEXIST") return false
-      throw error
-    }
-
-    try {
-      await this.writeOwnerMetadata()
-      this.acquired = true
-
-      return true
-    } catch (error) {
-      await fs.rm(this.lockPath, {recursive: true, force: true})
-      throw error
-    }
+    this.acquired = true
   }
 
   /**
@@ -77,86 +54,15 @@ export default class VelociousHttpServerLock {
     if (!this.acquired) return
 
     this.acquired = false
-    await fs.rm(this.lockPath, {recursive: true, force: true})
-  }
-
-  /**
-   * Writes metadata used to explain or reclaim an existing server lock.
-   * @returns {Promise<void>} - Resolves after owner metadata has been written.
-   */
-  async writeOwnerMetadata() {
-    await fs.writeFile(path.join(this.lockPath, "owner.json"), JSON.stringify({
-      acquiredAt: new Date().toISOString(),
-      host: this.host,
-      hostname: os.hostname(),
-      pid: process.pid,
-      port: this.port
-    }))
-  }
-
-  /**
-   * Checks whether the current lock owner is a dead process on this host.
-   * @returns {Promise<boolean>} - Whether the existing lock belongs to a dead process.
-   */
-  async isStale() {
-    const owner = await this.readOwnerMetadata()
-
-    if (!this.isLocalProcessOwner(owner)) return false
-
-    return this.processIsDead(/** @type {{pid: number}} */ (owner).pid)
-  }
-
-  /**
-   * Runs is local process owner.
-   * @param {Record<string, ReturnType<typeof JSON.parse>> | null} owner - Existing lock owner metadata.
-   * @returns {boolean} - Whether owner metadata names a local process.
-   */
-  isLocalProcessOwner(owner) {
-    if (!owner) return false
-    if (typeof owner.pid !== "number") return false
-
-    return this.ownerHostnameMatches(owner)
-  }
-
-  /**
-   * Runs owner hostname matches.
-   * @param {Record<string, ReturnType<typeof JSON.parse>>} owner - Existing lock owner metadata.
-   * @returns {boolean} - Whether the owner hostname is local or absent.
-   */
-  ownerHostnameMatches(owner) {
-    if (!owner.hostname) return true
-    if (owner.hostname === os.hostname()) return true
-
-    return false
-  }
-
-  /**
-   * Runs process is dead.
-   * @param {number} pid - Process id.
-   * @returns {boolean} - Whether the process no longer exists.
-   */
-  processIsDead(pid) {
-    try {
-      process.kill(pid, 0)
-
-      return false
-    } catch (error) {
-      return /** @type {{code?: string}} */ (error).code === "ESRCH"
-    }
+    await this.backend.release("server")
   }
 
   /**
    * Reads owner metadata from an existing server lock directory.
-   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>> | null>} - Parsed owner metadata, when readable.
+   * @returns {Promise<import("../database/advisory-lock-file-backend.js").AdvisoryLockFileOwner | null>} - Parsed owner metadata, when readable.
    */
   async readOwnerMetadata() {
-    try {
-      const rawOwner = await fs.readFile(path.join(this.lockPath, "owner.json"), "utf8")
-
-      return /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (JSON.parse(rawOwner))
-    } catch {
-      return null
-    }
+    return await this.backend.holderInfo("server")
   }
 
   /**

package/src/testing/test-runner.js

@@ -8,6 +8,7 @@ import { slowestTestResults } from "@velocious/testing/reporters"
 import { TestRunner as PackageTestRunner } from "@velocious/testing/runner"
 import Application from "../../src/application.js"
 import RequestClient from "./request-client.js"
+import Tenant from "../tenants/tenant.js"
 import picocolors from "picocolors"
 import restArgsError from "../utils/rest-args-error.js"
 import { testConfig } from "./test.js"
@@ -17,6 +18,7 @@ import { SHARED_TRANSACTION_BROKER_ENV } from "./shared-transaction-proxy-driver
 import VelociousAttemptExecutor from "./velocious-attempt-executor.js"
 import VelociousRunnerReporter, { AbortRemainingTestsError } from "./velocious-runner-reporter.js"
 import VelociousSuiteHookExecutor from "./velocious-suite-hook-executor.js"
+import TestTenantDatabasePool from "./test-tenant-database-pool.js"
 import VelociousTestArguments from "./velocious-test-arguments.js"
 
 /** @typedef {typeof defaultTestContext} PackageTestContext */
@@ -48,6 +50,18 @@ import VelociousTestArguments from "./velocious-test-arguments.js"
  * @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.
+ * @property {(args?: {databaseIdentifier?: string, tenant?: object}) => Promise<TestTenantPoolLease>} [acquireTestTenant] - Leases one member of the configured test tenant database pool for this attempt (opt-in `testTenantPools` configuration).
+ * @property {(args: {databaseIdentifier: string, tenant: object}) => void} [registerTenantForCleanup] - Registers one active tenant database for the framework-owned end-of-attempt cleanup (drop + provider hooks) without hand-rolled afterEach bookkeeping.
+ */
+/**
+ * TestTenantPoolLease type (re-exported from the pool for TestArgs consumers).
+ * @typedef {import("./test-tenant-database-pool.js").TestTenantPoolLease} TestTenantPoolLease
+ */
+/**
+ * TenantCleanupRegistration type.
+ * @typedef {object} TenantCleanupRegistration
+ * @property {string} databaseIdentifier - Tenant database identifier to drop at attempt end.
+ * @property {ReturnType<typeof JSON.parse>} tenant - Tenant descriptor whose database must be dropped.
  */
 /**
  * BrowserDummyConnectionRegistration type.
@@ -201,6 +215,10 @@ export default class TestRunner {
     this._setupFiles = setupFiles || []
     this._timeoutMs = timeoutMs
     this._abortRemainingTests = false
+    /** @type {Map<string, TestTenantDatabasePool>} */
+    this._testTenantPools = new Map()
+    /** @type {Promise<void> | undefined} */
+    this._testTenantPoolTeardownPromise = undefined
 
     this._failedTests = 0
     this._successfulTests = 0
@@ -632,6 +650,81 @@ export default class TestRunner {
     return this._application
   }
 
+  /**
+   * Resolves the pool identifier when exactly one `testTenantPools` entry is
+   * configured, so `acquireTestTenant()` can omit it. Ambiguous or missing
+   * configuration fails loudly instead of guessing.
+   * @returns {string} - The single configured pool identifier.
+   */
+  singleTestTenantPoolIdentifier() {
+    const identifiers = Object.keys(this.getConfiguration().getTestTenantPools() || {})
+
+    if (identifiers.length === 0) {
+      throw new Error("acquireTestTenant requires a databaseIdentifier when no testTenantPools configuration is present")
+    }
+    if (identifiers.length > 1) {
+      throw new Error(`acquireTestTenant requires a databaseIdentifier when multiple testTenantPools are configured: ${identifiers.join(", ")}`)
+    }
+
+    return identifiers[0]
+  }
+
+  /**
+   * Returns the test tenant database pool for one configured `testTenantPools`
+   * identifier, creating it on first use. Throws when the identifier has no pool
+   * configuration — the pool stays strictly opt-in.
+   * @param {string} databaseIdentifier - Tenant database identifier.
+   * @returns {TestTenantDatabasePool} - The runner-owned pool.
+   */
+  getTestTenantPool(databaseIdentifier) {
+    const existingPool = this._testTenantPools.get(databaseIdentifier)
+
+    if (existingPool) return existingPool
+
+    const poolConfiguration = this.getConfiguration().getTestTenantPools()?.[databaseIdentifier]
+
+    if (!poolConfiguration) {
+      throw new Error(`No testTenantPools configuration for database identifier: ${databaseIdentifier}`)
+    }
+
+    const pool = new TestTenantDatabasePool({
+      configuration: this.getConfiguration(),
+      databaseIdentifier,
+      poolConfiguration
+    })
+    this._testTenantPools.set(databaseIdentifier, pool)
+
+    return pool
+  }
+
+  /**
+   * Tears down every test tenant database pool created during this run, exactly once.
+   * Safe to call from afterAll-style teardown and from the runner's own cleanup; the
+   * same promise is shared by concurrent callers.
+   * @returns {Promise<void>} - Resolves after all pools dropped their databases.
+   */
+  teardownTestTenantPools() {
+    this._testTenantPoolTeardownPromise ??= (async () => {
+      const pools = [...this._testTenantPools.values()]
+      this._testTenantPools.clear()
+
+      const errors = []
+
+      for (const pool of pools) {
+        try {
+          await pool.teardown()
+        } catch (error) {
+          errors.push(error)
+        }
+      }
+
+      if (errors.length === 1) throw errors[0]
+      if (errors.length > 1) throw new AggregateError(errors, "Failed to tear down test tenant database pools")
+    })()
+
+    return this._testTenantPoolTeardownPromise
+  }
+
   /**
    * Registers each non-tenant per-test connection as a dynamic candidate for in-process
    * request sharing. The pool evaluates transaction state when each request is dispatched,
@@ -822,6 +915,52 @@ export default class TestRunner {
     if (errors.length > 1) throw new AggregateError(errors, "Failed to clean up a transactional tenant test connection")
   }
 
+  /**
+   * Registers one tenant database for framework-owned end-of-attempt cleanup. The
+   * registration drops the tenant's database through the provider's `dropDatabase`
+   * hook (or the framework default) after the attempt's afterEach hooks and
+   * transactional tenant rollbacks finished, so consuming apps do not hand-roll a
+   * Map/afterEach bookkeeping layer for DDL that a test transaction cannot roll back.
+   * @param {{databaseIdentifier: string, tenant: object}} args - Tenant database identifier and tenant descriptor to drop at attempt end.
+   * @param {TenantCleanupRegistration[]} registrations - Current attempt registrations.
+   * @returns {void} - No return value.
+   */
+  registerTenantForCleanup({databaseIdentifier, tenant, ...restArgs}, registrations) {
+    restArgsError(restArgs)
+    if (!databaseIdentifier) throw new Error("registerTenantForCleanup requires a databaseIdentifier")
+    if (!tenant) throw new Error("registerTenantForCleanup requires a tenant")
+
+    const databaseConfiguration = this.getConfiguration().resolveDatabaseConfiguration(databaseIdentifier, tenant)
+
+    if (!databaseConfiguration.tenantOnly) {
+      throw new Error(`registerTenantForCleanup requires a tenantOnly database: ${databaseIdentifier}`)
+    }
+
+    registrations.push({databaseIdentifier, tenant})
+  }
+
+  /**
+   * Drops every tenant database registered for this attempt, in registration order.
+   * Each drop is attempted even when an earlier one failed; failures are surfaced
+   * (single error or AggregateError), never swallowed.
+   * @param {TenantCleanupRegistration[]} registrations - Attempt-owned registrations.
+   * @returns {Promise<void>} - Resolves after all registered tenants were dropped.
+   */
+  async cleanupTenantRegistrations(registrations) {
+    const errors = []
+
+    for (const {databaseIdentifier, tenant} of registrations) {
+      try {
+        await Tenant.drop({identifier: databaseIdentifier, tenant, configuration: this.getConfiguration()})
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to drop tenant databases registered for cleanup")
+  }
+
   /**
    * Selects the current non-tenant connections eligible for shared transaction work.
    * @param {{transactionsOnly: boolean}} args - Selection options.
@@ -1374,6 +1513,12 @@ export default class TestRunner {
     } finally {
       process.off("unhandledRejection", onUnhandledRejection)
       process.off("uncaughtException", onUncaughtException)
+
+      try {
+        await this.teardownTestTenantPools()
+      } catch (error) {
+        this.recordTimeoutCleanupFailure(error, "test tenant pool teardown")
+      }
     }
   }
 
@@ -1385,6 +1530,13 @@ export default class TestRunner {
     const failureStart = this._suiteHookFailures.length
 
     await this._packageRunner?.cleanupActiveSuites()
+
+    try {
+      await this.teardownTestTenantPools()
+    } catch (error) {
+      this.recordTimeoutCleanupFailure(error, "test tenant pool teardown")
+    }
+
     this.throwAfterAllFailures(this._suiteHookFailures.slice(failureStart))
   }