velocious 1.0.698 → 1.0.700

package/src/configuration.js

@@ -45,6 +45,7 @@ import VelociousPackage from "./packages/velocious-package.js"
 import FrontendTenantSqliteLifecycle from "./tenants/frontend-tenant-sqlite-lifecycle.js"
 import { resolveGenerationId, resolveInitialGenerationState, resolveLifecycleSocketPath } from "./background-jobs/generation-identity.js"
 import { runShutdownSteps } from "./utils/shutdown-lifecycle.js"
+import { resolveAdvisoryLockBackendPolicy } from "./database/advisory-lock-backend-policy.js"
 
 export { CurrentConfigurationNotSetError }
 
@@ -245,6 +246,20 @@ export default class VelociousConfiguration {
    * @type {Set<import("./database/drivers/base.js").default>} */
   _advisoryLockConnections = new Set()
 
+  /**
+   * Lazily created file-tier advisory-lock backend (STC-213). Stays `undefined`
+   * unless `advisoryLocks.backends.file.enabled: true` is explicitly configured —
+   * the file tier is never auto-enabled, and a non-Node environment handler
+   * (browser/Expo, no `fs`) cannot create one at all.
+   * @type {import("./database/advisory-lock-file-backend.js").default | undefined} */
+  _advisoryLockFileBackend = undefined
+
+  /**
+   * Most recent advisory-lock acquisition per lock name — the "which backend
+   * served this lock" surface (design §3).
+   * @type {Map<string, {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string}>} */
+  _advisoryLockAcquisitions = new Map()
+
   /** @type {Map<string, number>} */
   _schemaCacheGenerationsByReuseKey = new Map()
 
@@ -260,11 +275,12 @@ export default class VelociousConfiguration {
    * Runs constructor.
    * @param {import("./configuration-types.js").ConfigurationArgsType} args - Configuration arguments.
    */
-  constructor({abilityResolver, abilityResources, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, mcp = false, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
+  constructor({abilityResolver, abilityResources, advisoryLocks, attachments, autoload = true, backgroundJobs, backendProjects, beacon, cookieSecret, cors, database, debug = false, debugEndpoint = false, apiManifest = false, directory, enforceTenantDatabaseScopes = true, environment, environmentHandler, exposeInternalErrorsToClients, frontendTenantSqlite, httpServer, initializeModels, initializers, locale, localeFallbacks, locales, logging, mailerBackend, mcp = false, packages, requestTimeoutMs, routeResolverHooks, scheduledBackgroundJobs, secureFrontendModelErrors, structureSql, sync, tenantDatabaseProviders, tenantDatabaseResolver, tenantResolver, testTenantPools, testing, timeZone, timezoneOffsetMinutes, trustedProxies, websocketChannelResolver, websocketMessageHandlerResolver, ...restArgs}) {
     restArgsError(restArgs)
 
     this._abilityResolver = abilityResolver
     this._abilityResources = abilityResources || []
+    this._advisoryLocks = advisoryLocks
     this._autoload = autoload
     this._backgroundJobs = backgroundJobs
     this._beacon = beacon
@@ -399,6 +415,7 @@ export default class VelociousConfiguration {
     this._tenantDatabaseProviders = tenantDatabaseProviders || {}
     this._tenantDatabaseResolver = tenantDatabaseResolver
     this._tenantResolver = tenantResolver
+    this._testTenantPools = testTenantPools
     this._websocketEvents = undefined
     /**
      * Stores the websocket channel subscribers value.
@@ -1445,6 +1462,12 @@ export default class VelociousConfiguration {
    */
   getTenantDatabaseResolver() { return this._tenantDatabaseResolver }
 
+  /**
+   * Runs get test tenant pool configurations.
+   * @returns {import("./configuration-types.js").TestTenantPoolsConfiguration | undefined} - Opt-in test tenant database pools keyed by database identifier.
+   */
+  getTestTenantPools() { return this._testTenantPools }
+
   /**
    * Runs get enforce tenant database scopes.
    * @returns {boolean} - Whether tenant-switched models require a resolved tenant database identifier.
@@ -1514,6 +1537,13 @@ export default class VelociousConfiguration {
    */
   setTenantDatabaseResolver(resolver) { this._tenantDatabaseResolver = resolver }
 
+  /**
+   * Runs set test tenant pool configurations.
+   * @param {import("./configuration-types.js").TestTenantPoolsConfiguration | undefined} pools - Opt-in test tenant database pools.
+   * @returns {void} - No return value.
+   */
+  setTestTenantPools(pools) { this._testTenantPools = pools }
+
   /**
    * Runs set enforce tenant database scopes.
    * @param {boolean} newValue - Whether tenant-switched models require a resolved tenant database identifier.
@@ -4062,6 +4092,102 @@ export default class VelociousConfiguration {
     })
   }
 
+  /**
+   * Resolves the `advisoryLocks` configuration block (STC-210 design §10).
+   * Full backward compatibility: an app that configures nothing gets today's
+   * driver-native-only behavior — the file backend is **disabled by default**
+   * and only ever selectable by explicit configuration.
+   * @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}}, policy: import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]}} - Advisory-lock configuration with defaults applied.
+   */
+  getAdvisoryLockConfig() {
+    const configured = this._advisoryLocks || {}
+    const fileConfigured = configured.backends?.file || {}
+
+    return {
+      backends: {
+        file: {
+          directory: fileConfigured.directory,
+          enabled: fileConfigured.enabled === true,
+          leaseMs: typeof fileConfigured.leaseMs === "number" ? fileConfigured.leaseMs : 30_000,
+          renewIntervalMs: typeof fileConfigured.renewIntervalMs === "number" ? fileConfigured.renewIntervalMs : 10_000
+        }
+      },
+      policy: Array.isArray(configured.policy) ? configured.policy : []
+    }
+  }
+
+  /**
+   * Runs get advisory lock policy.
+   * @returns {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} - Per-lock-name backend policy entries.
+   */
+  getAdvisoryLockPolicy() {
+    return this.getAdvisoryLockConfig().policy
+  }
+
+  /**
+   * Resolves the effective backend policy for one lock name (design §5).
+   * @param {string} lockName - Concrete lock name.
+   * @returns {import("./database/advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy} - Resolved policy.
+   */
+  resolveAdvisoryLockPolicy(lockName) {
+    return resolveAdvisoryLockBackendPolicy(lockName, this.getAdvisoryLockPolicy())
+  }
+
+  /**
+   * Returns the file-tier advisory-lock backend when this deployment has
+   * explicitly enabled it (`advisoryLocks.backends.file.enabled: true`),
+   * creating it on first use. Returns `undefined` when the tier is disabled
+   * (the default) — callers must never fall back to it implicitly. Creation
+   * goes through the environment handler so browser/Expo configurations
+   * without `fs` fail loudly instead of half-working.
+   * @returns {Promise<import("./database/advisory-lock-file-backend.js").default | undefined>} - Resolves with the enabled file backend, or undefined.
+   */
+  async getAdvisoryLockFileBackend() {
+    const config = this.getAdvisoryLockConfig()
+
+    if (!config.backends.file.enabled) return undefined
+    if (this._advisoryLockFileBackend) return this._advisoryLockFileBackend
+
+    const directory = config.backends.file.directory || `${this.getDirectory()}/tmp/advisory-locks`
+
+    this._advisoryLockFileBackend = await this.getEnvironmentHandler().createAdvisoryLockFileBackend({
+      directory,
+      leaseMs: config.backends.file.leaseMs,
+      renewIntervalMs: config.backends.file.renewIntervalMs
+    })
+
+    return this._advisoryLockFileBackend
+  }
+
+  /**
+   * Records which backend tier served one advisory-lock acquisition so
+   * `getAdvisoryLockBackendStatus()` can answer "which backend served this
+   * lock" (design §3).
+   * @param {object} args - Acquisition record.
+   * @param {string} args.lockName - Lock name.
+   * @param {import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier} args.backend - Tier that served the acquisition.
+   * @param {boolean} args.fencingSupported - Whether the serving tier carries fencing tokens.
+   * @returns {void}
+   */
+  recordAdvisoryLockAcquisition({lockName, backend, fencingSupported}) {
+    this._advisoryLockAcquisitions.set(lockName, {backend, fencingSupported, servedAt: new Date().toISOString()})
+  }
+
+  /**
+   * The "which backend served this lock" diagnostics surface (design §3):
+   * per lock name, the tier of the most recent acquisition, whether that tier
+   * carries fencing tokens, and the resolved policy (minimum/allowed/preferred
+   * tiers) for the name.
+   * @param {string} lockName - Lock name.
+   * @returns {{acquisition: {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string} | null, policy: import("./database/advisory-lock-backend-policy.js").ResolvedAdvisoryLockBackendPolicy}} - Backend status for the name.
+   */
+  getAdvisoryLockBackendStatus(lockName) {
+    return {
+      acquisition: this._advisoryLockAcquisitions.get(lockName) ?? null,
+      policy: this.resolveAdvisoryLockPolicy(lockName)
+    }
+  }
+
   /**
    * Registers a dedicated connection that currently holds an advisory lock, so a
    * shutdown can close it and release the lock. See `_advisoryLockConnections`.
@@ -4141,6 +4267,15 @@ export default class VelociousConfiguration {
           // leave the rest of the connections open.
           await this._closeAdvisoryLockConnections()
         } finally {
+          try {
+            // Release file-tier advisory-lock holds explicitly (STC-213): the
+            // lease would make them reclaimable anyway, but a clean shutdown
+            // should not leave lock directories behind for the staleness path.
+            await this._advisoryLockFileBackend?.releaseAllHeld()
+          } catch (error) {
+            closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+          }
+
           for (const pool of Object.values(this.databasePools)) {
             if (!pool) continue
 

package/src/database/advisory-lock-backend-policy.js

@@ -0,0 +1,204 @@
+// @ts-check
+
+/**
+ * Advisory-lock backend tiers (STC-210 design, `docs/advisory-lock-backends.md` §1/§9).
+ * `process-local` and `file` are host-local; `driver-native` and `lock-server` are
+ * cross-host. Tier strength order (strongest first):
+ * `lock-server` ≡ `driver-native` > `file` > `process-local`.
+ * @typedef {"process-local" | "file" | "driver-native" | "lock-server"} AdvisoryLockTier
+ */
+/**
+ * One per-lock-name backend policy entry as declared in configuration (§5).
+ * @typedef {object} AdvisoryLockBackendPolicyEntry
+ * @property {string} name - Lock name or `*`-suffixed glob pattern (e.g. `background_jobs:*`).
+ * @property {AdvisoryLockTier} [minTier] - Weakest tier this name may ever be served by. Defaults to `driver-native` (default-deny).
+ * @property {AdvisoryLockTier[]} [allowedTiers] - Explicit whitelist of servable tiers. Defaults to every tier at or above `minTier`.
+ * @property {AdvisoryLockTier} [preferredTier] - Tier used when available; falling below it triggers the fallback report (§3). Defaults to `driver-native`.
+ */
+/**
+ * Policy resolved for one concrete lock name, with tier gaps already closed:
+ * `allowedTiers` always contains every tier at or above `minTier`, so a
+ * cross-host-minimum name can never be served by `file` or `process-local`.
+ * @typedef {object} ResolvedAdvisoryLockBackendPolicy
+ * @property {AdvisoryLockTier} minTier - Weakest tier this name may be served by.
+ * @property {AdvisoryLockTier[]} allowedTiers - Tiers that may serve this name (minimum-closed).
+ * @property {AdvisoryLockTier} preferredTier - Tier preferred when available.
+ * @property {AdvisoryLockBackendPolicyEntry | null} entry - The matched configuration entry, or null for the default policy.
+ */
+
+/**
+ * Thrown when an acquisition would have to be served by a tier below the
+ * lock name's declared minimum tier. Fail-closed refusal (§9): the name is
+ * never served by the weaker tier, and the refusal is reported on the
+ * framework-error channel as `advisory-lock-min-tier-refused`.
+ */
+export class AdvisoryLockMinTierRefusedError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{lockName: string, requestedBackend: AdvisoryLockTier, minTier: AdvisoryLockTier}} args - Refusal details.
+   */
+  constructor(message, {lockName, requestedBackend, minTier}) {
+    super(message)
+    this.name = "AdvisoryLockMinTierRefusedError"
+    this.lockName = lockName
+    this.requestedBackend = requestedBackend
+    this.minTier = minTier
+  }
+}
+
+/**
+ * Thrown when no enabled backend that satisfies the lock name's minimum tier
+ * is available (§9). Distinct from `AdvisoryLockTimeoutError` (a backend
+ * served the wait but the holder never released).
+ */
+export class AdvisoryLockBackendUnavailableError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{lockName: string, minTier: AdvisoryLockTier, reasons: string[]}} args - Unavailability details.
+   */
+  constructor(message, {lockName, minTier, reasons}) {
+    super(message)
+    this.name = "AdvisoryLockBackendUnavailableError"
+    this.lockName = lockName
+    this.minTier = minTier
+    this.reasons = reasons
+  }
+}
+
+/**
+ * Tier strength ranks (§9): higher rank is stronger. `lock-server` and
+ * `driver-native` are both cross-host and rank equal.
+ * @type {Record<AdvisoryLockTier, number>} */
+const TIER_RANKS = {
+  "driver-native": 2,
+  file: 1,
+  "lock-server": 3,
+  "process-local": 0
+}
+
+/** All tiers ordered strongest-first. */
+const TIERS_STRONGEST_FIRST = /** @type {AdvisoryLockTier[]} */ (["lock-server", "driver-native", "file", "process-local"])
+
+/**
+ * Runs tier rank.
+ * @param {AdvisoryLockTier} tier - Tier to rank.
+ * @returns {number} - Strength rank (higher is stronger).
+ */
+export function advisoryLockTierRank(tier) {
+  const rank = TIER_RANKS[tier]
+
+  if (rank === undefined) throw new Error(`Unknown advisory-lock tier ${JSON.stringify(String(tier))}`)
+
+  return rank
+}
+
+/**
+ * Runs tier is at least as strong as.
+ * @param {AdvisoryLockTier} tier - Candidate serving tier.
+ * @param {AdvisoryLockTier} minimum - Required minimum tier.
+ * @returns {boolean} - Whether `tier` satisfies the minimum.
+ */
+export function advisoryLockTierSatisfies(tier, minimum) {
+  return advisoryLockTierRank(tier) >= advisoryLockTierRank(minimum)
+}
+
+/**
+ * Resolves the effective backend policy for one concrete lock name:
+ * longest-prefix glob match over the configured entries (exact names win),
+ * default-deny for undeclared names (`minTier: driver-native`,
+ * `preferredTier: driver-native`), and `allowedTiers` closed upward so a
+ * cross-host minimum can never be served by a host-local tier.
+ * @param {string} lockName - Concrete lock name.
+ * @param {AdvisoryLockBackendPolicyEntry[] | undefined} policy - Configured policy entries.
+ * @returns {ResolvedAdvisoryLockBackendPolicy} - Resolved policy.
+ */
+export function resolveAdvisoryLockBackendPolicy(lockName, policy) {
+  const entry = matchAdvisoryLockPolicyEntry(lockName, policy)
+  const minTier = entry?.minTier ?? "driver-native"
+  const preferredTier = entry?.preferredTier ?? "driver-native"
+
+  // §9: eligibility filters to tier strength >= minTier even when a weaker
+  // tier was declared in `allowedTiers` — a cross-host minimum can never be
+  // served by `file` or `process-local`. A `preferredTier` below the minimum
+  // stays visible here so the runner can refuse it loudly before contacting
+  // the weaker backend.
+  const declaredAllowed = entry?.allowedTiers
+  const allowedTiers = TIERS_STRONGEST_FIRST.filter((tier) => {
+    if (!advisoryLockTierSatisfies(tier, minTier)) return false
+
+    if (!Array.isArray(declaredAllowed)) return true
+
+    return declaredAllowed.includes(tier)
+  })
+
+  return {allowedTiers, entry: entry ?? null, minTier, preferredTier}
+}
+
+/**
+ * Matches one policy entry for a lock name: exact `name` matches win;
+ * otherwise the longest `*`-suffixed prefix pattern wins.
+ * @param {string} lockName - Concrete lock name.
+ * @param {AdvisoryLockBackendPolicyEntry[] | undefined} policy - Configured policy entries.
+ * @returns {AdvisoryLockBackendPolicyEntry | null} - Matched entry or null.
+ */
+function matchAdvisoryLockPolicyEntry(lockName, policy) {
+  if (!Array.isArray(policy)) return null
+
+  let bestPrefixMatch = null
+  let bestPrefixLength = -1
+
+  for (const entry of policy) {
+    if (typeof entry?.name !== "string") continue
+
+    if (entry.name === lockName) return entry
+
+    if (entry.name.endsWith("*")) {
+      const prefix = entry.name.slice(0, -1)
+
+      if (lockName.startsWith(prefix) && prefix.length > bestPrefixLength) {
+        bestPrefixMatch = entry
+        bestPrefixLength = prefix.length
+      }
+    }
+  }
+
+  return bestPrefixMatch
+}
+
+/**
+ * Refuses a downgrade below the lock name's minimum tier before any contact
+ * with the weaker backend (§9), reporting the refusal on the framework-error
+ * channel so a silent downgrade is impossible to hide.
+ * @param {object} args - Refusal args.
+ * @param {import("../configuration.js").default} args.configuration - Configuration owning the error channel.
+ * @param {string} args.lockName - Lock name.
+ * @param {AdvisoryLockTier} args.requestedBackend - Tier the acquisition would fall to.
+ * @param {AdvisoryLockTier} args.minTier - Declared minimum tier.
+ * @returns {never} - Always throws.
+ */
+export function refuseAdvisoryLockTierBelowMinimum({configuration, lockName, requestedBackend, minTier}) {
+  const error = new AdvisoryLockMinTierRefusedError(
+    `Advisory lock ${JSON.stringify(lockName)} requires minimum tier ${JSON.stringify(minTier)}; the ${JSON.stringify(requestedBackend)} tier is refused. Enable a cross-host backend or declare minTier: "file" for this lock name (single-host deployments only).`,
+    {lockName, minTier, requestedBackend}
+  )
+
+  configuration.getErrorEvents().emit("framework-error", {
+    context: "advisory-lock-min-tier-refused",
+    error,
+    lockName,
+    minTier,
+    requestedBackend
+  })
+  configuration.getErrorEvents().emit("all-error", {
+    context: "advisory-lock-min-tier-refused",
+    error,
+    errorType: "framework-error",
+    lockName,
+    minTier,
+    requestedBackend
+  })
+
+  throw error
+}