velocious 1.0.708 → 1.0.710

package/README.md

@@ -4,7 +4,7 @@
 * Database framework with familiar MVC concepts
 * Database models with migrations and validations
 * Database models that work almost the same in frontend and backend, including online CRUD for [composite primary keys](docs/composite-primary-keys.md)
-* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed, a non-throwing `withAdvisoryLockOrDefer` result for contended hot paths, event-driven slow acquire/hold duration telemetry with holder attribution, and an explicitly opt-in file-lock fallback tier with per-lock-name minimum-tier enforcement and acquisition provenance (see [docs/advisory-locks.md](docs/advisory-locks.md) and [docs/advisory-lock-backends.md](docs/advisory-lock-backends.md))* Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
+* Connection-scoped advisory locks with automatic cleanup before pooled connections are reused or closed, a non-throwing `withAdvisoryLockOrDefer` result for contended hot paths, event-driven slow acquire/hold duration telemetry with holder attribution, and an explicitly opt-in file-lock fallback tier with per-lock-name minimum-tier enforcement and acquisition provenance, and a policy-selected centralized lock-server tier that holds leases in a separate process instead of pinning database connections (see [docs/advisory-locks.md](docs/advisory-locks.md) and [docs/advisory-lock-backends.md](docs/advisory-lock-backends.md))* Built-in record auditing for model lifecycle changes (see [docs/auditing.md](docs/auditing.md))
 * Declarative state machines for models, with typed event methods generated into the base model (see [docs/state-machine.md](docs/state-machine.md))
 * Migrations for schema changes and UTC datetime storage, including caller-selected `pre-runtime` and `post-publication` execution sets and recorded `changeTable` batches that combine operations into one `ALTER` on bulk-capable drivers (see [docs/database-migrations.md](docs/database-migrations.md), [docs/migration-execution-phases.md](docs/migration-execution-phases.md), and [docs/change-table.md](docs/change-table.md))
 * Tenant-selected base-model and structure generation with one immutable, fail-closed physical database context; tenant-only model metadata initializes only after that context is active (see [docs/tenant-selected-database-generation.md](docs/tenant-selected-database-generation.md))

package/build/configuration-types.js

@@ -1,11 +1,27 @@
 // @ts-check
 
+/**
+ * Resolved lock-service configuration after environment and Beacon defaults.
+ * @typedef {object} LockServiceResolvedConfigType
+ * @property {string} [authToken] - Shared secret enforced by the host, when configured.
+ * @property {number} connectBackoffMs - Base backoff between connection retries.
+ * @property {number} connectRetries - Bounded connection retries before giving up.
+ * @property {number} connectTimeoutMs - Handshake timeout.
+ * @property {"database" | "none"} fallback - What to do when the service is unreachable.
+ * @property {string} host - Lock-service host.
+ * @property {number} leaseMs - Lease duration advertised to clients.
+ * @property {"beacon" | "in-process" | "off"} mode - Where the authority lives.
+ * @property {string} namespace - Prefix applied to every lock name.
+ * @property {number} port - Lock-service port.
+ * @property {string | null} statePath - Durable mirror for epochs and holders.
+ */
+
 /**
  * @module types
  */
 
 /**
- * Immutable identity shared by application initializers for one process lifecycle.
+ * Immutable identity shared by application hooks and initializers for one process lifecycle.
  * @typedef {object} ApplicationProcessContext
  * @property {string} type - Generic process type supplied to `configuration.initialize()`.
  * @property {string} instanceId - Opaque identity unique to this lifecycle.
@@ -866,7 +882,7 @@
  * behavior; the file backend is disabled by default and only selectable by
  * explicit configuration.
  * @typedef {object} AdvisoryLocksConfiguration
- * @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration.
+ * @property {{file?: {directory?: string, enabled?: boolean, leaseMs?: number, renewIntervalMs?: number}, lockServer?: {authToken?: string, connectTimeoutMs?: number, enabled?: boolean, host?: string, leaseMs?: number, port?: number, reprobeCooldownMs?: number, url?: string}}} [backends] - Backend enablement. `file.enabled` defaults to false; enabling it is the deployment's explicit single-host declaration. `lockServer` defaults to enabled when a host/port/url or the `VELOCIOUS_LOCK_SERVER_HOST`/`_PORT` env pair is configured.
  * @property {import("./database/advisory-lock-backend-policy.js").AdvisoryLockBackendPolicyEntry[]} [policy] - Per-lock-name minimum/allowed/preferred tier rules (design §5).
  */
 
@@ -899,7 +915,7 @@
  * @property {BeaconConfiguration} [beacon] - Beacon broadcast bus configuration.
  * @property {ScheduledBackgroundJobsConfiguration | ScheduledBackgroundJobsLoaderType} [scheduledBackgroundJobs] - Scheduled background jobs configuration.
  * @property {MailerBackend} [mailerBackend] - Mail delivery backend.
- * @property {(args: {configuration: import("./configuration.js").default, type: string}) => void} initializeModels - Hook to register models for a given initialization type.
+ * @property {(args: {configuration: import("./configuration.js").default, processContext: ApplicationProcessContext | undefined, type: string}) => void} initializeModels - Hook to register models for a given initialization type.
  * @property {InitializersType} [initializers] - Initializer loader for environment bootstrapping.
  * @property {string | (() => string)} locale - Default locale or locale resolver.
  * @property {string[]} locales - Supported locales.

package/build/configuration.js

@@ -261,6 +261,12 @@ export default class VelociousConfiguration {
    * (browser/Expo, no `fs`) cannot create one at all.
    * @type {import("./database/advisory-lock-file-backend.js").default | undefined} */
   _advisoryLockFileBackend = undefined
+  /**
+   * Lazily created lock-server (tier (b)) backend; undefined when the tier is
+   * not configured.
+   * @type {import("./database/advisory-lock-lock-server-backend.js").default | undefined}
+   */
+  _advisoryLockLockServerBackend = undefined
 
   /**
    * Most recent advisory-lock acquisition per lock name — the "which backend
@@ -2641,6 +2647,16 @@ export default class VelociousConfiguration {
    */
   isInitialized() { return this._isInitialized }
 
+  /**
+   * Returns the framework-owned process context for this configuration's
+   * lifecycle. It is undefined until `initialize()` starts, and it carries the
+   * process `type` (`server`, `worker-handler`, background-jobs types, or an
+   * application-defined string) so hooks and framework services can tell which
+   * process they are running in.
+   * @returns {import("./configuration-types.js").ApplicationProcessContext | undefined} - Process context, when initialization has started.
+   */
+  getApplicationProcessContext() { return this._applicationProcessContext }
+
   /**
    * Runs initialize models.
    * @param {object} args - Options object.
@@ -2674,7 +2690,7 @@ export default class VelociousConfiguration {
 
       if (!shouldSkipDummyModelInitialization) {
         if (this._initializeModels) {
-          await this._initializeModels({configuration: this, type: args.type})
+          await this._initializeModels({configuration: this, processContext: this.getApplicationProcessContext(), type: args.type})
         }
 
         await this.getEnvironmentHandler().initializePackageModels(this)
@@ -4195,11 +4211,21 @@ export default class VelociousConfiguration {
    * 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.
+   * @returns {{backends: {file: {directory?: string, enabled: boolean, leaseMs: number, renewIntervalMs: number}, lockServer: {authToken: string, connectTimeoutMs: number, enabled: boolean, leaseMs: number, reprobeCooldownMs: number, url: string}}, 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 || {}
+    const lockServerConfigured = configured.backends?.lockServer || {}
+    const envHost = process.env.VELOCIOUS_LOCK_SERVER_HOST
+    const envPortRaw = process.env.VELOCIOUS_LOCK_SERVER_PORT
+    const envPort = envPortRaw ? Number(envPortRaw) : undefined
+    const lockServerHost = lockServerConfigured.host || envHost
+    const lockServerPort = typeof lockServerConfigured.port === "number"
+      ? lockServerConfigured.port
+      : (typeof envPort === "number" && Number.isFinite(envPort) ? envPort : 3006)
+    const lockServerUrl = lockServerConfigured.url
+      || `ws://${lockServerHost || "127.0.0.1"}:${lockServerPort}/websocket`
 
     return {
       backends: {
@@ -4208,6 +4234,18 @@ export default class VelociousConfiguration {
           enabled: fileConfigured.enabled === true,
           leaseMs: typeof fileConfigured.leaseMs === "number" ? fileConfigured.leaseMs : 30_000,
           renewIntervalMs: typeof fileConfigured.renewIntervalMs === "number" ? fileConfigured.renewIntervalMs : 10_000
+        },
+        lockServer: {
+          // Enabled only by explicit configuration or an explicit env pair, so
+          // an app that configures nothing keeps today's driver-native behavior.
+          authToken: typeof lockServerConfigured.authToken === "string" ? lockServerConfigured.authToken : "",
+          connectTimeoutMs: typeof lockServerConfigured.connectTimeoutMs === "number" ? lockServerConfigured.connectTimeoutMs : 3000,
+          enabled: typeof lockServerConfigured.enabled === "boolean"
+            ? lockServerConfigured.enabled
+            : Boolean(lockServerConfigured.url || lockServerConfigured.host || envHost || typeof lockServerConfigured.port === "number" || envPortRaw),
+          leaseMs: typeof lockServerConfigured.leaseMs === "number" ? lockServerConfigured.leaseMs : 30_000,
+          reprobeCooldownMs: typeof lockServerConfigured.reprobeCooldownMs === "number" ? lockServerConfigured.reprobeCooldownMs : 5000,
+          url: lockServerUrl
         }
       },
       policy: Array.isArray(configured.policy) ? configured.policy : []
@@ -4257,6 +4295,39 @@ export default class VelociousConfiguration {
     return this._advisoryLockFileBackend
   }
 
+  /**
+   * Returns the lock-server advisory-lock backend (tier (b)) when this
+   * deployment configured one, creating it on first use. Returns `undefined`
+   * when the tier is not configured — callers must never invent one.
+   *
+   * The backend keeps a single socket per process; it holds no database
+   * connection while waiting for or holding a lease.
+   * @returns {Promise<import("./database/advisory-lock-lock-server-backend.js").default | undefined>} - Resolves with the configured backend, or undefined.
+   */
+  async getAdvisoryLockLockServerBackend() {
+    const config = this.getAdvisoryLockConfig()
+
+    if (!config.backends.lockServer.enabled) return undefined
+    if (this._advisoryLockLockServerBackend) return this._advisoryLockLockServerBackend
+
+    const {default: AdvisoryLockLockServerBackend} = await import("./database/advisory-lock-lock-server-backend.js")
+    const backend = new AdvisoryLockLockServerBackend({
+      authToken: config.backends.lockServer.authToken,
+      connectTimeoutMs: config.backends.lockServer.connectTimeoutMs,
+      leaseMs: config.backends.lockServer.leaseMs,
+      onError: (error) => {
+        this.getErrorEvents().emit("framework-error", {context: "advisory-lock-lock-server", error})
+        this.getErrorEvents().emit("all-error", {context: "advisory-lock-lock-server", error, errorType: "framework-error"})
+      },
+      reprobeCooldownMs: config.backends.lockServer.reprobeCooldownMs,
+      url: config.backends.lockServer.url
+    })
+
+    this._advisoryLockLockServerBackend = backend
+
+    return backend
+  }
+
   /**
    * Records which backend tier served one advisory-lock acquisition so
    * `getAdvisoryLockBackendStatus()` can answer "which backend served this
@@ -4277,11 +4348,12 @@ export default class VelociousConfiguration {
    * 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.
+   * @returns {{acquisition: {backend: import("./database/advisory-lock-backend-policy.js").AdvisoryLockTier, fencingSupported: boolean, servedAt: string} | null, lockServer: {connected: boolean, lastError: string | null, lastProbeAt: string | null, leasedNames: 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,
+      lockServer: this._advisoryLockLockServerBackend?.getStatus() ?? null,
       policy: this.resolveAdvisoryLockPolicy(lockName)
     }
   }
@@ -4374,6 +4446,16 @@ export default class VelociousConfiguration {
             closeErrors.push(error instanceof Error ? error : new Error(String(error)))
           }
 
+          try {
+            // Release lock-server leases explicitly first, then drop the socket:
+            // the server reclaims a closed connection anyway, but an explicit
+            // release hands the name to the next waiter without waiting for the
+            // transport teardown.
+            await this._advisoryLockLockServerBackend?.close()
+          } catch (error) {
+            closeErrors.push(error instanceof Error ? error : new Error(String(error)))
+          }
+
           for (const pool of Object.values(this.databasePools)) {
             if (!pool) continue
 

package/build/database/advisory-lock-errors.js

@@ -0,0 +1,59 @@
+// @ts-check
+
+import {AdvisoryLockBackendUnavailableError} from "./advisory-lock-backend-policy.js"
+
+/**
+ * Thrown when a lock-server acquisition could not be attempted because the
+ * lock server is unreachable. Distinct from `AdvisoryLockTimeoutError` ("the
+ * server was reachable, the holder never released") so a caller can react to
+ * an infrastructure outage without guessing.
+ */
+export class AdvisoryLockServiceUnavailableError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{lockName: string, reason: string}} args - Lock name and failure reason.
+   */
+  constructor(message, {lockName, reason}) {
+    super(message)
+    this.name = "AdvisoryLockServiceUnavailableError"
+    this.lockName = lockName
+    this.reason = reason
+  }
+}
+
+/**
+ * Thrown after a critical section ran on the lock-server tier while its lease
+ * was fenced or lost (design §7/§8): the section may have overlapped another
+ * holder, so its result must not be trusted as exclusive.
+ */
+export class AdvisoryLockLostError extends Error {
+  /**
+   * Runs constructor.
+   * @param {string} message - Error message.
+   * @param {{cause?: Error, currentEpoch: number | null, epoch: number | null, lockName: string}} args - Fencing details.
+   */
+  constructor(message, {cause, currentEpoch, epoch, lockName}) {
+    super(message)
+    this.name = "AdvisoryLockLostError"
+    this.lockName = lockName
+    this.epoch = epoch
+    this.currentEpoch = currentEpoch
+    this.cause = cause
+  }
+}
+
+/**
+ * Builds the error thrown when a lock name's minimum tier cannot be served and
+ * no eligible tier is available (design §9, fail-closed).
+ * @param {{lockName: string, minTier: import("./advisory-lock-backend-policy.js").AdvisoryLockTier, reasons: string[]}} args - Unavailability details.
+ * @returns {AdvisoryLockBackendUnavailableError} - Error to throw.
+ */
+export function advisoryLockBackendUnavailable(args) {
+  const {lockName, minTier, reasons} = args
+
+  return new AdvisoryLockBackendUnavailableError(
+    `No eligible advisory-lock backend is available for ${JSON.stringify(lockName)} (minimum tier ${JSON.stringify(minTier)}): ${reasons.join("; ")}`,
+    {lockName, minTier, reasons}
+  )
+}