velocious 1.0.708 → 1.0.710

package/package.json

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

package/src/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/src/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/src/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}
+  )
+}