velocious 1.0.709 → 1.0.711

package/package.json

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

package/src/configuration-types.js

@@ -1,5 +1,21 @@
 // @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
  */
@@ -69,7 +85,7 @@
 /**
  * @typedef {object} DatabaseConfigurationType
  * @property {number | null} [advisoryLockAcquireTimeoutMs] - Bound (ms) a blocking advisory-lock acquisition waits for a contended lock before reporting failure. Default: `900000` (15 minutes). `null` opts out and restores the driver's indefinite wait. A per-call `timeoutMs` argument always overrides this.
- * @property {{slowAcquireMs?: number | null, slowHoldMs?: number | null}} [advisoryLockTelemetry] - Event-driven advisory-lock duration telemetry thresholds. `slowAcquireMs` (default `5000`) reports an acquire wait that completed slower than the threshold, including the eventual outcome; `advisory-lock-acquire-timeout` always fires when a wait exceeds its bound and carries the holder identity available on the tier at that moment. `slowHoldMs` (default `60000`) reports a hold that outlives the threshold at release. `null` disables that report. Reports fire on the events themselves — no periodic scanner — on `getErrorEvents()` as `framework-error` with `context: "advisory-lock-telemetry"`. See [docs/advisory-locks.md](../docs/advisory-locks.md).
+ * @property {{slowAcquireMs?: number | null, slowHoldMs?: number | null}} [advisoryLockTelemetry] - Event-driven advisory-lock duration telemetry thresholds. `slowAcquireMs` (default `5000`) reports an acquire wait that completed slower than the threshold, including the eventual outcome; `advisory-lock-acquire-timeout` always fires when a wait exceeds its bound and carries the holder identity available on the tier at that moment. `slowHoldMs` (default `60000`) reports a hold that outlives the threshold at release. `null` disables that report. Reports fire on the events themselves — no periodic scanner — on `getTelemetryEvents()` as `telemetry` with `context: "advisory-lock-telemetry"`. See [docs/advisory-locks.md](../docs/advisory-locks.md).
  * @property {string} [databaseCharset] - Default character set applied by `db:create` via mysql/mariadb `CREATE DATABASE ... CHARACTER SET`. Distinct from `charset`, which is the client connection charset forwarded to the mysql2 driver.
  * @property {string} [databaseCollation] - Default collation applied by `db:create` via mysql/mariadb `CREATE DATABASE ... COLLATE`.
  * @property {string} [database] - Database name for this connection.
@@ -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).
  */
 

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
@@ -519,6 +525,7 @@ export default class VelociousConfiguration {
      * @type {WeakSet<object>} */
     this._appliedRouteMounts = new WeakSet()
     this._errorEvents = new EventEmitter()
+    this._telemetryEvents = new EventEmitter()
 
     /**
      * Stores the database pools value.
@@ -3859,6 +3866,19 @@ export default class VelociousConfiguration {
     return this._errorEvents
   }
 
+  /**
+   * Framework telemetry emitter. Telemetry reports measurements — lock contention,
+   * slow queries, queue depth — that are worth observing but are not failures. It is
+   * deliberately separate from `getErrorEvents()`: a bug reporter subscribes to the
+   * error channel on the promise that every payload there carries a thrown value, and
+   * a contention measurement emitted as `framework-error` turns into a bug report on
+   * every occurrence instead of a metric.
+   * @returns {import("eventemitter3").EventEmitter} - Framework telemetry events emitter.
+   */
+  getTelemetryEvents() {
+    return this._telemetryEvents
+  }
+
   /**
    * Registers a reporter that can add client-safe metadata to frontend-model error payloads.
    * @param {import("./configuration-types.js").ClientErrorPayloadReporterType} reporter - Reporter callback.
@@ -4205,11 +4225,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: {
@@ -4218,6 +4248,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 : []
@@ -4267,6 +4309,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
@@ -4287,11 +4362,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)
     }
   }
@@ -4384,6 +4460,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}
+  )
+}