velocious 1.0.709 → 1.0.710

package/build/src/database/advisory-lock-errors.d.ts

@@ -0,0 +1,54 @@
+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 declare class AdvisoryLockServiceUnavailableError extends Error {
+    lockName: string;
+    reason: string;
+    /**
+     * Runs constructor.
+     * @param {string} message - Error message.
+     * @param {{lockName: string, reason: string}} args - Lock name and failure reason.
+     */
+    constructor(message: string, { lockName, reason }: {
+        lockName: string;
+        reason: string;
+    });
+}
+/**
+ * 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 declare class AdvisoryLockLostError extends Error {
+    lockName: string;
+    epoch: number | null;
+    currentEpoch: number | null;
+    cause: Error | undefined;
+    /**
+     * Runs constructor.
+     * @param {string} message - Error message.
+     * @param {{cause?: Error, currentEpoch: number | null, epoch: number | null, lockName: string}} args - Fencing details.
+     */
+    constructor(message: string, { cause, currentEpoch, epoch, lockName }: {
+        cause?: Error;
+        currentEpoch: number | null;
+        epoch: number | null;
+        lockName: string;
+    });
+}
+/**
+ * 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 declare function advisoryLockBackendUnavailable(args: {
+    lockName: string;
+    minTier: import("./advisory-lock-backend-policy.js").AdvisoryLockTier;
+    reasons: string[];
+}): AdvisoryLockBackendUnavailableError;
+//# sourceMappingURL=advisory-lock-errors.d.ts.map

package/build/src/database/advisory-lock-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisory-lock-errors.d.ts","sourceRoot":"","sources":["../../../src/database/advisory-lock-errors.js"],"names":[],"mappings":"AAEA,OAAO,EAAC,mCAAmC,EAAC,MAAM,mCAAmC,CAAA;AAErF;;;;;GAKG;AACH,qBAAa,mCAAoC,SAAQ,KAAK;IASrD,QAAQ;IACR,MAAM;IATb;;;;OAIG;IACH,YAAY,OAAO,EAHR,MAGQ,EAAE,EAAC,QAAQ,EAAE,MAAM,EAAC,EAF5B;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAEL,EAKtC;CACF;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IASvC,QAAQ;IACR,KAAK;IACL,YAAY;IACZ,KAAK;IAXZ;;;;OAIG;IACH,YAAY,OAAO,EAHR,MAGQ,EAAE,EAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAC,EAFhD;QAAC,KAAK,CAAC,EAAE,KAAK,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAEnC,EAO1D;CACF;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAHxC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,mCAAmC,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAGnE,GAFtC,mCAAmC,CAS/C"}

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

@@ -0,0 +1,52 @@
+// @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 });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWR2aXNvcnktbG9jay1lcnJvcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvZGF0YWJhc2UvYWR2aXNvcnktbG9jay1lcnJvcnMuanMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsWUFBWTtBQUVaLE9BQU8sRUFBQyxtQ0FBbUMsRUFBQyxNQUFNLG1DQUFtQyxDQUFBO0FBRXJGOzs7OztHQUtHO0FBQ0gsTUFBTSxPQUFPLG1DQUFvQyxTQUFRLEtBQUs7SUFDNUQ7Ozs7T0FJRztJQUNILFlBQVksT0FBTyxFQUFFLEVBQUMsUUFBUSxFQUFFLE1BQU0sRUFBQztRQUNyQyxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUE7UUFDZCxJQUFJLENBQUMsSUFBSSxHQUFHLHFDQUFxQyxDQUFBO1FBQ2pELElBQUksQ0FBQyxRQUFRLEdBQUcsUUFBUSxDQUFBO1FBQ3hCLElBQUksQ0FBQyxNQUFNLEdBQUcsTUFBTSxDQUFBO0lBQ3RCLENBQUM7Q0FDRjtBQUVEOzs7O0dBSUc7QUFDSCxNQUFNLE9BQU8scUJBQXNCLFNBQVEsS0FBSztJQUM5Qzs7OztPQUlHO0lBQ0gsWUFBWSxPQUFPLEVBQUUsRUFBQyxLQUFLLEVBQUUsWUFBWSxFQUFFLEtBQUssRUFBRSxRQUFRLEVBQUM7UUFDekQsS0FBSyxDQUFDLE9BQU8sQ0FBQyxDQUFBO1FBQ2QsSUFBSSxDQUFDLElBQUksR0FBRyx1QkFBdUIsQ0FBQTtRQUNuQyxJQUFJLENBQUMsUUFBUSxHQUFHLFFBQVEsQ0FBQTtRQUN4QixJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQTtRQUNsQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQTtRQUNoQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQTtJQUNwQixDQUFDO0NBQ0Y7QUFFRDs7Ozs7R0FLRztBQUNILE1BQU0sVUFBVSw4QkFBOEIsQ0FBQyxJQUFJO0lBQ2pELE1BQU0sRUFBQyxRQUFRLEVBQUUsT0FBTyxFQUFFLE9BQU8sRUFBQyxHQUFHLElBQUksQ0FBQTtJQUV6QyxPQUFPLElBQUksbUNBQW1DLENBQzVDLHNEQUFzRCxJQUFJLENBQUMsU0FBUyxDQUFDLFFBQVEsQ0FBQyxrQkFBa0IsSUFBSSxDQUFDLFNBQVMsQ0FBQyxPQUFPLENBQUMsTUFBTSxPQUFPLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxFQUFFLEVBQ2pKLEVBQUMsUUFBUSxFQUFFLE9BQU8sRUFBRSxPQUFPLEVBQUMsQ0FDN0IsQ0FBQTtBQUNILENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBAdHMtY2hlY2tcblxuaW1wb3J0IHtBZHZpc29yeUxvY2tCYWNrZW5kVW5hdmFpbGFibGVFcnJvcn0gZnJvbSBcIi4vYWR2aXNvcnktbG9jay1iYWNrZW5kLXBvbGljeS5qc1wiXG5cbi8qKlxuICogVGhyb3duIHdoZW4gYSBsb2NrLXNlcnZlciBhY3F1aXNpdGlvbiBjb3VsZCBub3QgYmUgYXR0ZW1wdGVkIGJlY2F1c2UgdGhlXG4gKiBsb2NrIHNlcnZlciBpcyB1bnJlYWNoYWJsZS4gRGlzdGluY3QgZnJvbSBgQWR2aXNvcnlMb2NrVGltZW91dEVycm9yYCAoXCJ0aGVcbiAqIHNlcnZlciB3YXMgcmVhY2hhYmxlLCB0aGUgaG9sZGVyIG5ldmVyIHJlbGVhc2VkXCIpIHNvIGEgY2FsbGVyIGNhbiByZWFjdCB0b1xuICogYW4gaW5mcmFzdHJ1Y3R1cmUgb3V0YWdlIHdpdGhvdXQgZ3Vlc3NpbmcuXG4gKi9cbmV4cG9ydCBjbGFzcyBBZHZpc29yeUxvY2tTZXJ2aWNlVW5hdmFpbGFibGVFcnJvciBleHRlbmRzIEVycm9yIHtcbiAgLyoqXG4gICAqIFJ1bnMgY29uc3RydWN0b3IuXG4gICAqIEBwYXJhbSB7c3RyaW5nfSBtZXNzYWdlIC0gRXJyb3IgbWVzc2FnZS5cbiAgICogQHBhcmFtIHt7bG9ja05hbWU6IHN0cmluZywgcmVhc29uOiBzdHJpbmd9fSBhcmdzIC0gTG9jayBuYW1lIGFuZCBmYWlsdXJlIHJlYXNvbi5cbiAgICovXG4gIGNvbnN0cnVjdG9yKG1lc3NhZ2UsIHtsb2NrTmFtZSwgcmVhc29ufSkge1xuICAgIHN1cGVyKG1lc3NhZ2UpXG4gICAgdGhpcy5uYW1lID0gXCJBZHZpc29yeUxvY2tTZXJ2aWNlVW5hdmFpbGFibGVFcnJvclwiXG4gICAgdGhpcy5sb2NrTmFtZSA9IGxvY2tOYW1lXG4gICAgdGhpcy5yZWFzb24gPSByZWFzb25cbiAgfVxufVxuXG4vKipcbiAqIFRocm93biBhZnRlciBhIGNyaXRpY2FsIHNlY3Rpb24gcmFuIG9uIHRoZSBsb2NrLXNlcnZlciB0aWVyIHdoaWxlIGl0cyBsZWFzZVxuICogd2FzIGZlbmNlZCBvciBsb3N0IChkZXNpZ24gwqc3L8KnOCk6IHRoZSBzZWN0aW9uIG1heSBoYXZlIG92ZXJsYXBwZWQgYW5vdGhlclxuICogaG9sZGVyLCBzbyBpdHMgcmVzdWx0IG11c3Qgbm90IGJlIHRydXN0ZWQgYXMgZXhjbHVzaXZlLlxuICovXG5leHBvcnQgY2xhc3MgQWR2aXNvcnlMb2NrTG9zdEVycm9yIGV4dGVuZHMgRXJyb3Ige1xuICAvKipcbiAgICogUnVucyBjb25zdHJ1Y3Rvci5cbiAgICogQHBhcmFtIHtzdHJpbmd9IG1lc3NhZ2UgLSBFcnJvciBtZXNzYWdlLlxuICAgKiBAcGFyYW0ge3tjYXVzZT86IEVycm9yLCBjdXJyZW50RXBvY2g6IG51bWJlciB8IG51bGwsIGVwb2NoOiBudW1iZXIgfCBudWxsLCBsb2NrTmFtZTogc3RyaW5nfX0gYXJncyAtIEZlbmNpbmcgZGV0YWlscy5cbiAgICovXG4gIGNvbnN0cnVjdG9yKG1lc3NhZ2UsIHtjYXVzZSwgY3VycmVudEVwb2NoLCBlcG9jaCwgbG9ja05hbWV9KSB7XG4gICAgc3VwZXIobWVzc2FnZSlcbiAgICB0aGlzLm5hbWUgPSBcIkFkdmlzb3J5TG9ja0xvc3RFcnJvclwiXG4gICAgdGhpcy5sb2NrTmFtZSA9IGxvY2tOYW1lXG4gICAgdGhpcy5lcG9jaCA9IGVwb2NoXG4gICAgdGhpcy5jdXJyZW50RXBvY2ggPSBjdXJyZW50RXBvY2hcbiAgICB0aGlzLmNhdXNlID0gY2F1c2VcbiAgfVxufVxuXG4vKipcbiAqIEJ1aWxkcyB0aGUgZXJyb3IgdGhyb3duIHdoZW4gYSBsb2NrIG5hbWUncyBtaW5pbXVtIHRpZXIgY2Fubm90IGJlIHNlcnZlZCBhbmRcbiAqIG5vIGVsaWdpYmxlIHRpZXIgaXMgYXZhaWxhYmxlIChkZXNpZ24gwqc5LCBmYWlsLWNsb3NlZCkuXG4gKiBAcGFyYW0ge3tsb2NrTmFtZTogc3RyaW5nLCBtaW5UaWVyOiBpbXBvcnQoXCIuL2Fkdmlzb3J5LWxvY2stYmFja2VuZC1wb2xpY3kuanNcIikuQWR2aXNvcnlMb2NrVGllciwgcmVhc29uczogc3RyaW5nW119fSBhcmdzIC0gVW5hdmFpbGFiaWxpdHkgZGV0YWlscy5cbiAqIEByZXR1cm5zIHtBZHZpc29yeUxvY2tCYWNrZW5kVW5hdmFpbGFibGVFcnJvcn0gLSBFcnJvciB0byB0aHJvdy5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGFkdmlzb3J5TG9ja0JhY2tlbmRVbmF2YWlsYWJsZShhcmdzKSB7XG4gIGNvbnN0IHtsb2NrTmFtZSwgbWluVGllciwgcmVhc29uc30gPSBhcmdzXG5cbiAgcmV0dXJuIG5ldyBBZHZpc29yeUxvY2tCYWNrZW5kVW5hdmFpbGFibGVFcnJvcihcbiAgICBgTm8gZWxpZ2libGUgYWR2aXNvcnktbG9jayBiYWNrZW5kIGlzIGF2YWlsYWJsZSBmb3IgJHtKU09OLnN0cmluZ2lmeShsb2NrTmFtZSl9IChtaW5pbXVtIHRpZXIgJHtKU09OLnN0cmluZ2lmeShtaW5UaWVyKX0pOiAke3JlYXNvbnMuam9pbihcIjsgXCIpfWAsXG4gICAge2xvY2tOYW1lLCBtaW5UaWVyLCByZWFzb25zfVxuICApXG59XG4iXX0=

package/build/src/database/advisory-lock-lock-server-backend.d.ts

@@ -0,0 +1,279 @@
+export type LockServerConnectionLike = {
+    /**
+     * - Resolves when the server accepted the 1:1 connection.
+     */
+    ready: Promise<void>;
+    /**
+     * - Sends one connection message.
+     */
+    sendMessage: (body: Record<string, unknown>) => void;
+    /**
+     * - Closes the connection.
+     */
+    close?: () => void;
+};
+export type LockServerClientLike = {
+    /**
+     * - Opens the transport.
+     */
+    connect: () => Promise<void>;
+    /**
+     * - Opens the 1:1 connection.
+     */
+    openConnection: (type: string, args: {
+        onMessage: (body: Record<string, unknown>) => void;
+        params: Record<string, unknown>;
+        timeoutMs: number;
+    }) => LockServerConnectionLike;
+    /**
+     * - Closes the transport.
+     */
+    close?: () => Promise<void> | void;
+};
+export type LockServerHold = {
+    epoch: number;
+    name: string;
+    timer: ReturnType<typeof setInterval>;
+    leaseExpiresAt: number;
+};
+export type LockServerAcquireResult = {
+    status: "acquired";
+    epoch: number;
+    leaseExpiresAt: number;
+} | {
+    status: "busy";
+} | {
+    status: "timeout";
+};
+/**
+ * @typedef {object} LockServerConnectionLike
+ * @property {Promise<void>} ready - Resolves when the server accepted the 1:1 connection.
+ * @property {(body: Record<string, unknown>) => void} sendMessage - Sends one connection message.
+ * @property {() => void} [close] - Closes the connection.
+ * @typedef {object} LockServerClientLike
+ * @property {() => Promise<void>} connect - Opens the transport.
+ * @property {(type: string, args: {onMessage: (body: Record<string, unknown>) => void, params: Record<string, unknown>, timeoutMs: number}) => LockServerConnectionLike} openConnection - Opens the 1:1 connection.
+ * @property {() => Promise<void> | void} [close] - Closes the transport.
+ * @typedef {{epoch: number, name: string, timer: ReturnType<typeof setInterval>, leaseExpiresAt: number}} LockServerHold
+ * @typedef {{status: "acquired", epoch: number, leaseExpiresAt: number} | {status: "busy"} | {status: "timeout"}} LockServerAcquireResult
+ */
+/** Protocol version spoken by the centralized lock server (consens-lock v2). */
+export declare const LOCK_SERVER_PROTOCOL_VERSION = 2;
+/**
+ * Tier (b) backend: the centralized lock server (`consens-lock`, protocol v2).
+ *
+ * The server holds every lock in its own process memory, so a held lock never
+ * pins a database connection — that is the whole point of this tier. Ownership
+ * is bound to this process's connection: the server mints the `holderId`, so a
+ * client can only renew or release its own leases, and a dropped connection
+ * releases all of them immediately.
+ *
+ * Holds are leases renewed every third of the lease window. A fenced lease
+ * (the server granted the name to another holder after an expiry or partition)
+ * is recorded per lock name and surfaced by the runner as
+ * `AdvisoryLockLostError` after the critical section settles.
+ *
+ * Unavailability is cached for `reprobeCooldownMs` so a flapping server cannot
+ * turn every waiting caller into a connection attempt (design §2).
+ */
+export default class AdvisoryLockLockServerBackend {
+    url: string;
+    authToken: string;
+    clientFactory: (args: {
+        authToken: string;
+        url: string;
+    }) => LockServerClientLike;
+    connectTimeoutMs: number;
+    leaseMs: number;
+    onError: ((error: Error) => void) | undefined;
+    reprobeCooldownMs: number;
+    /** @type {LockServerClientLike | null} */
+    client: LockServerClientLike | null;
+    /** @type {LockServerConnectionLike | null} */
+    connection: LockServerConnectionLike | null;
+    /** @type {Promise<void> | null} */
+    connectPromise: Promise<void> | null;
+    /** @type {{reject: (error: Error) => void, resolve: () => void, timer: ReturnType<typeof setTimeout> | null} | null} */
+    helloWaiter: {
+        reject: (error: Error) => void;
+        resolve: () => void;
+        timer: ReturnType<typeof setTimeout> | null;
+    } | null;
+    /** @type {Map<string, {epoch: number, name: string, timer: ReturnType<typeof setInterval>, leaseExpiresAt: number}>} */
+    holds: Map<string, {
+        epoch: number;
+        name: string;
+        timer: ReturnType<typeof setInterval>;
+        leaseExpiresAt: number;
+    }>;
+    /** @type {Map<string, {currentEpoch: number | null, epoch: number | null}>} */
+    fencedHolds: Map<string, {
+        currentEpoch: number | null;
+        epoch: number | null;
+    }>;
+    /** @type {Map<string, {reject: (error: Error) => void, resolve: (message: Record<string, unknown>) => void, timer: ReturnType<typeof setTimeout> | null}>} */
+    pending: Map<string, {
+        reject: (error: Error) => void;
+        resolve: (message: Record<string, unknown>) => void;
+        timer: ReturnType<typeof setTimeout> | null;
+    }>;
+    /** @type {{lastError: string | null, lastProbeAt: string | null, unavailableUntil: number}} */
+    status: {
+        lastError: string | null;
+        lastProbeAt: string | null;
+        unavailableUntil: number;
+    };
+    requestCounter: number;
+    closed: boolean;
+    /**
+     * Creates the lock-server backend. The transport is created on first use, so
+     * constructing this object never performs I/O.
+     * @param {object} args - Backend options.
+     * @param {string} [args.authToken] - Shared secret; the server fails closed without a matching token.
+     * @param {(args: {authToken: string, url: string}) => LockServerClientLike} [args.clientFactory] - Transport factory (tests inject a fake).
+     * @param {number} [args.connectTimeoutMs] - Handshake timeout.
+     * @param {number} [args.leaseMs] - Lease duration used until the server advertises its own.
+     * @param {(error: Error) => void} [args.onError] - Async error reporter.
+     * @param {number} [args.reprobeCooldownMs] - How long an unavailable server is not re-probed.
+     * @param {string} args.url - Lock-server websocket URL.
+     */
+    constructor({ authToken, clientFactory, connectTimeoutMs, leaseMs, onError, reprobeCooldownMs, url }: {
+        authToken?: string;
+        clientFactory?: (args: {
+            authToken: string;
+            url: string;
+        }) => LockServerClientLike;
+        connectTimeoutMs?: number;
+        leaseMs?: number;
+        onError?: (error: Error) => void;
+        reprobeCooldownMs?: number;
+        url: string;
+    });
+    /**
+     * Opens the connection if needed, honoring the re-probe cooldown.
+     * @param {string} lockName - Lock name, for error messages.
+     * @returns {Promise<void>} - Resolves when connected.
+     */
+    ensureConnected(lockName: string): Promise<void>;
+    /**
+     * Opens the transport and completes the hello handshake.
+     * @param {string} lockName - Lock name, for error messages.
+     * @returns {Promise<void>} - Resolves when the handshake completed.
+     */
+    openConnection(lockName: string): Promise<void>;
+    /**
+     * Waits for a lock through the server's FIFO queue.
+     * @param {string} name - Lock name.
+     * @param {{timeoutMs?: number | null}} [args] - Bounded wait; the server defaults to 30s.
+     * @returns {Promise<boolean>} - True when the lease was granted, false on timeout.
+     */
+    acquire(name: string, { timeoutMs }?: {
+        timeoutMs?: number | null;
+    }): Promise<boolean>;
+    /**
+     * Takes a lock only if the server grants it immediately.
+     * @param {string} name - Lock name.
+     * @returns {Promise<boolean>} - True when granted.
+     */
+    tryAcquire(name: string): Promise<boolean>;
+    /**
+     * Releases a held lease and stops its renewal.
+     * @param {string} name - Lock name.
+     * @returns {Promise<void>} - Resolves when released (or when the transport is gone).
+     */
+    release(name: string): Promise<void>;
+    /**
+     * Releases every lease this process holds (shutdown path).
+     * @returns {Promise<void>} - Resolves when every lease was released.
+     */
+    releaseAllHeld(): Promise<void>;
+    /**
+     * Runs the server's live holder list (diagnostics).
+     * @returns {Promise<Record<string, unknown>[]>} - Live holders.
+     */
+    list(): Promise<Record<string, unknown>[]>;
+    /**
+     * Runs who-holds for one name (diagnostics).
+     * @param {string} name - Lock name.
+     * @returns {Promise<Record<string, unknown> | null>} - Holder, or null.
+     */
+    whoHolds(name: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Runs the fencing epoch granted for one held lease.
+     * @param {string} name - Lock name.
+     * @returns {number | null} - Granted epoch, or null when the lease is not (or no longer) held.
+     */
+    getHoldEpoch(name: string): number | null;
+    /**
+     * Whether this hold was fenced or lost during its critical section.
+     * @param {string} name - Lock name.
+     * @param {number | null} epoch - Epoch the hold was granted.
+     * @returns {{currentEpoch: number | null, epoch: number | null} | null} - Fencing details when lost.
+     */
+    takeLoss(name: string, epoch: number | null): {
+        currentEpoch: number | null;
+        epoch: number | null;
+    } | null;
+    /**
+     * Reports connection state and the names currently leased through this
+     * process, for `getAdvisoryLockBackendStatus()`.
+     * @returns {{connected: boolean, lastError: string | null, lastProbeAt: string | null, leasedNames: string[]}} - Backend status for diagnostics.
+     */
+    getStatus(): {
+        connected: boolean;
+        lastError: string | null;
+        lastProbeAt: string | null;
+        leasedNames: string[];
+    };
+    /**
+     * Closes the backend: explicit release first, then the transport.
+     * @returns {Promise<void>} - Resolves when closed.
+     */
+    close(): Promise<void>;
+    /**
+     * Dispatches one server message.
+     * @param {Record<string, unknown>} body - Server message.
+     * @returns {void}
+     */
+    handleMessage(body: Record<string, unknown>): void;
+    /**
+     * Sends one request and awaits its correlated response.
+     * @param {string} type - Request type.
+     * @param {Record<string, unknown>} payload - Request fields.
+     * @param {number | null} [timeoutMs] - Response timeout; null waits for the server.
+     * @returns {Promise<Record<string, unknown>>} - Response body.
+     */
+    request(type: string, payload: Record<string, unknown>, timeoutMs?: number | null): Promise<Record<string, unknown>>;
+    /**
+     * Starts lease renewal for a granted lock.
+     * @param {string} name - Lock name.
+     * @param {number} epoch - Granted epoch.
+     * @returns {void}
+     */
+    startRenewal(name: string, epoch: number): void;
+    /**
+     * Renews one lease; a fenced lease is recorded for the runner to surface.
+     * @param {string} name - Lock name.
+     * @param {number} epoch - Epoch the hold believes it owns.
+     * @returns {Promise<void>} - Resolves after the renewal round-trip.
+     */
+    renew(name: string, epoch: number): Promise<void>;
+    /**
+     * Records that the lock server is unreachable and starts the re-probe cooldown.
+     * @param {Error} error - Failure.
+     * @returns {void}
+     */
+    markUnavailable(error: Error): void;
+    /**
+     * Drops transport state and marks every outstanding hold lost.
+     * @returns {void}
+     */
+    teardown(): void;
+    /**
+     * Reports a transport-side failure without breaking lock handling.
+     * @param {unknown} error - Failure to report.
+     * @returns {void}
+     */
+    reportError(error: unknown): void;
+}
+//# sourceMappingURL=advisory-lock-lock-server-backend.d.ts.map

package/build/src/database/advisory-lock-lock-server-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advisory-lock-lock-server-backend.d.ts","sourceRoot":"","sources":["../../../src/database/advisory-lock-lock-server-backend.js"],"names":[],"mappings":"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"}