dflockd-client 1.8.3 → 1.9.0

package/dist/client.d.ts

@@ -85,8 +85,9 @@ declare function stats(options?: {
     port?: number;
     tls?: tls.ConnectionOptions;
     auth?: string;
+    connectTimeoutMs?: number;
 }): Promise<Stats>;
-interface DistributedLockOptions {
+interface BaseOptions {
     key: string;
     acquireTimeoutS?: number;
     leaseTtlS?: number;
@@ -100,83 +101,22 @@ interface DistributedLockOptions {
     tls?: tls.ConnectionOptions;
     auth?: string;
     onLockLost?: (key: string, token: string) => void;
-}
-declare class DistributedLock {
-    readonly key: string;
-    readonly acquireTimeoutS: number;
-    readonly leaseTtlS: number | undefined;
-    readonly servers: Array<[string, number]>;
-    readonly shardingStrategy: ShardingStrategy;
-    readonly renewRatio: number;
-    readonly tls: tls.ConnectionOptions | undefined;
-    readonly auth: string | undefined;
-    readonly onLockLost: ((key: string, token: string) => void) | undefined;
-    token: string | null;
-    lease: number;
-    private sock;
-    private renewTimer;
-    private closed;
-    constructor(opts: DistributedLockOptions);
-    private pickServer;
-    /**
-     * Acquire the lock. Returns `true` on success, `false` on timeout.
-     * @param opts.force - If `true`, silently close any existing connection before acquiring. Defaults to `false`, which throws if already connected.
-     */
-    acquire(opts?: {
-        force?: boolean;
-    }): Promise<boolean>;
-    /** Release the lock and close the connection. */
-    release(): Promise<void>;
-    /**
-     * Two-phase step 1: connect and join the FIFO queue.
-     * Returns `"acquired"` (fast-path, lock is already held) or `"queued"`.
-     * If acquired immediately, the renew loop starts automatically.
-     * @param opts.force - If `true`, silently close any existing connection before enqueuing. Defaults to `false`, which throws if already connected.
-     */
-    enqueue(opts?: {
-        force?: boolean;
-    }): Promise<"acquired" | "queued">;
-    /**
-     * Two-phase step 2: block until the lock is granted.
-     * Returns `true` if granted, `false` on timeout.
-     * If already acquired during `enqueue()`, returns `true` immediately.
-     */
-    wait(timeoutS?: number): Promise<boolean>;
+    /** TCP connect timeout in milliseconds. Undefined means no timeout. */
+    connectTimeoutMs?: number;
     /**
-     * Run `fn` while holding the lock, then release automatically.
-     *
-     * ```ts
-     * const lock = new DistributedLock({ key: "my-resource" });
-     * await lock.withLock(async () => {
-     *   // critical section
-     * });
-     * ```
+     * Socket idle timeout in milliseconds. If no data is received within this
+     * period, the socket emits a 'timeout' event and is destroyed, causing any
+     * pending `readline` to reject. Undefined means no timeout.
      */
-    withLock<T>(fn: () => T | Promise<T>): Promise<T>;
-    /** Close the underlying socket (idempotent). */
-    close(): void;
-    private startRenew;
-    private stopRenew;
+    socketTimeoutMs?: number;
 }
-interface DistributedSemaphoreOptions {
-    key: string;
+interface DistributedLockOptions extends BaseOptions {
+}
+interface DistributedSemaphoreOptions extends BaseOptions {
     limit: number;
-    acquireTimeoutS?: number;
-    leaseTtlS?: number;
-    /** @deprecated Use `servers` instead. */
-    host?: string;
-    /** @deprecated Use `servers` instead. */
-    port?: number;
-    servers?: Array<[host: string, port: number]>;
-    shardingStrategy?: ShardingStrategy;
-    renewRatio?: number;
-    tls?: tls.ConnectionOptions;
-    auth?: string;
-    onLockLost?: (key: string, token: string) => void;
 }
-declare class DistributedSemaphore {
+declare abstract class DistributedPrimitive {
     readonly key: string;
-    readonly limit: number;
     readonly acquireTimeoutS: number;
     readonly leaseTtlS: number | undefined;
     readonly servers: Array<[string, number]>;
@@ -185,46 +125,80 @@ declare class DistributedSemaphore {
     readonly tls: tls.ConnectionOptions | undefined;
     readonly auth: string | undefined;
     readonly onLockLost: ((key: string, token: string) => void) | undefined;
+    readonly connectTimeoutMs: number | undefined;
+    readonly socketTimeoutMs: number | undefined;
     token: string | null;
     lease: number;
     private sock;
     private renewTimer;
+    private renewInFlight;
     private closed;
-    constructor(opts: DistributedSemaphoreOptions);
+    constructor(opts: BaseOptions);
+    protected abstract doAcquire(sock: net.Socket): Promise<{
+        token: string;
+        lease: number;
+    }>;
+    protected abstract doEnqueue(sock: net.Socket): Promise<{
+        status: "acquired" | "queued";
+        token: string | null;
+        lease: number | null;
+    }>;
+    protected abstract doWait(sock: net.Socket, timeoutS: number): Promise<{
+        token: string;
+        lease: number;
+    }>;
+    protected abstract doRelease(sock: net.Socket, token: string): Promise<void>;
+    protected abstract doRenew(sock: net.Socket, token: string): Promise<number>;
+    private openConnection;
+    /**
+     * Suspend or restore the socket idle timeout.  Only has effect when
+     * `socketTimeoutMs` was set at construction time and a listener was
+     * registered in `openConnection`.
+     */
+    private suspendSocketTimeout;
+    private restoreSocketTimeout;
     private pickServer;
     /**
-     * Acquire a semaphore slot. Returns `true` on success, `false` on timeout.
-     * @param opts.force - If `true`, silently close any existing connection before acquiring. Defaults to `false`, which throws if already connected.
+     * Acquire the lock / semaphore slot.
+     * Returns `true` on success, `false` on timeout.
+     * @param opts.force - If `true`, silently close any existing connection
+     *   before acquiring. Defaults to `false`, which throws if already connected.
      */
     acquire(opts?: {
         force?: boolean;
     }): Promise<boolean>;
-    /** Release the semaphore slot and close the connection. */
+    /**
+     * Release the lock / semaphore slot and close the connection.
+     *
+     * Throws `LockError` if the instance is already closed (e.g. after a
+     * previous `release()` or `close()` call).
+     *
+     * The server-side release itself is best-effort: if the underlying
+     * connection is already dead the protocol-level release error is silently
+     * ignored so that the method doesn't throw on transient network failures.
+     */
     release(): Promise<void>;
     /**
      * Two-phase step 1: connect and join the FIFO queue.
-     * Returns `"acquired"` (fast-path, slot granted immediately) or `"queued"`.
+     * Returns `"acquired"` (fast-path) or `"queued"`.
      * If acquired immediately, the renew loop starts automatically.
-     * @param opts.force - If `true`, silently close any existing connection before enqueuing. Defaults to `false`, which throws if already connected.
+     * @param opts.force - If `true`, silently close any existing connection
+     *   before enqueuing. Defaults to `false`, which throws if already connected.
      */
     enqueue(opts?: {
         force?: boolean;
     }): Promise<"acquired" | "queued">;
     /**
-     * Two-phase step 2: block until a semaphore slot is granted.
+     * Two-phase step 2: block until the lock / slot is granted.
      * Returns `true` if granted, `false` on timeout.
      * If already acquired during `enqueue()`, returns `true` immediately.
      */
     wait(timeoutS?: number): Promise<boolean>;
     /**
-     * Run `fn` while holding a semaphore slot, then release automatically.
+     * Run `fn` while holding the lock / slot, then release automatically.
      *
-     * ```ts
-     * const sem = new DistributedSemaphore({ key: "my-resource", limit: 5 });
-     * await sem.withLock(async () => {
-     *   // critical section (up to 5 concurrent holders)
-     * });
-     * ```
+     * If `fn()` throws, its error is always preserved — a concurrent
+     * release failure will not mask it.
      */
     withLock<T>(fn: () => T | Promise<T>): Promise<T>;
     /** Close the underlying socket (idempotent). */
@@ -232,5 +206,42 @@ declare class DistributedSemaphore {
     private startRenew;
     private stopRenew;
 }
+declare class DistributedLock extends DistributedPrimitive {
+    constructor(opts: DistributedLockOptions);
+    protected doAcquire(sock: net.Socket): Promise<{
+        token: string;
+        lease: number;
+    }>;
+    protected doEnqueue(sock: net.Socket): Promise<{
+        status: "acquired" | "queued";
+        token: string | null;
+        lease: number | null;
+    }>;
+    protected doWait(sock: net.Socket, timeoutS: number): Promise<{
+        token: string;
+        lease: number;
+    }>;
+    protected doRelease(sock: net.Socket, token: string): Promise<void>;
+    protected doRenew(sock: net.Socket, token: string): Promise<number>;
+}
+declare class DistributedSemaphore extends DistributedPrimitive {
+    readonly limit: number;
+    constructor(opts: DistributedSemaphoreOptions);
+    protected doAcquire(sock: net.Socket): Promise<{
+        token: string;
+        lease: number;
+    }>;
+    protected doEnqueue(sock: net.Socket): Promise<{
+        status: "acquired" | "queued";
+        token: string | null;
+        lease: number | null;
+    }>;
+    protected doWait(sock: net.Socket, timeoutS: number): Promise<{
+        token: string;
+        lease: number;
+    }>;
+    protected doRelease(sock: net.Socket, token: string): Promise<void>;
+    protected doRenew(sock: net.Socket, token: string): Promise<number>;
+}
 
 export { AcquireTimeoutError, AuthError, DistributedLock, type DistributedLockOptions, DistributedSemaphore, type DistributedSemaphoreOptions, LockError, type ShardingStrategy, type Stats, type StatsIdleLock, type StatsIdleSemaphore, type StatsLock, type StatsSemaphore, acquire, enqueue, release, renew, semAcquire, semEnqueue, semRelease, semRenew, semWaitForLock, stableHashShard, stats, waitForLock };