dflockd-client 1.0.0 → 1.2.0

package/dist/client.d.cts

@@ -6,6 +6,8 @@ declare class AcquireTimeoutError extends Error {
 declare class LockError extends Error {
     constructor(message: string);
 }
+type ShardingStrategy = (key: string, numServers: number) => number;
+declare function stableHashShard(key: string, numServers: number): number;
 declare function acquire(sock: net.Socket, key: string, acquireTimeoutS: number, leaseTtlS?: number): Promise<{
     token: string;
     lease: number;
@@ -21,20 +23,39 @@ declare function waitForLock(sock: net.Socket, key: string, waitTimeoutS: number
     lease: number;
 }>;
 declare function release(sock: net.Socket, key: string, token: string): Promise<void>;
+declare function semAcquire(sock: net.Socket, key: string, acquireTimeoutS: number, limit: number, leaseTtlS?: number): Promise<{
+    token: string;
+    lease: number;
+}>;
+declare function semRenew(sock: net.Socket, key: string, token: string, leaseTtlS?: number): Promise<number>;
+declare function semEnqueue(sock: net.Socket, key: string, limit: number, leaseTtlS?: number): Promise<{
+    status: "acquired" | "queued";
+    token: string | null;
+    lease: number | null;
+}>;
+declare function semWaitForLock(sock: net.Socket, key: string, waitTimeoutS: number): Promise<{
+    token: string;
+    lease: number;
+}>;
+declare function semRelease(sock: net.Socket, key: string, token: string): Promise<void>;
 interface DistributedLockOptions {
     key: string;
     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;
 }
 declare class DistributedLock {
     readonly key: string;
     readonly acquireTimeoutS: number;
     readonly leaseTtlS: number | undefined;
-    readonly host: string;
-    readonly port: number;
+    readonly servers: Array<[string, number]>;
+    readonly shardingStrategy: ShardingStrategy;
     readonly renewRatio: number;
     token: string | null;
     lease: number;
@@ -42,6 +63,7 @@ declare class DistributedLock {
     private renewTimer;
     private closed;
     constructor(opts: DistributedLockOptions);
+    private pickServer;
     /** Acquire the lock. Returns `true` on success, `false` on timeout. */
     acquire(): Promise<boolean>;
     /** Release the lock and close the connection. */
@@ -74,5 +96,65 @@ declare class DistributedLock {
     private startRenew;
     private stopRenew;
 }
+interface DistributedSemaphoreOptions {
+    key: string;
+    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;
+}
+declare class DistributedSemaphore {
+    readonly key: string;
+    readonly limit: number;
+    readonly acquireTimeoutS: number;
+    readonly leaseTtlS: number | undefined;
+    readonly servers: Array<[string, number]>;
+    readonly shardingStrategy: ShardingStrategy;
+    readonly renewRatio: number;
+    token: string | null;
+    lease: number;
+    private sock;
+    private renewTimer;
+    private closed;
+    constructor(opts: DistributedSemaphoreOptions);
+    private pickServer;
+    /** Acquire a semaphore slot. Returns `true` on success, `false` on timeout. */
+    acquire(): Promise<boolean>;
+    /** Release the semaphore slot and close the connection. */
+    release(): Promise<void>;
+    /**
+     * Two-phase step 1: connect and join the FIFO queue.
+     * Returns `"acquired"` (fast-path, slot granted immediately) or `"queued"`.
+     * If acquired immediately, the renew loop starts automatically.
+     */
+    enqueue(): Promise<"acquired" | "queued">;
+    /**
+     * Two-phase step 2: block until a semaphore 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.
+     *
+     * ```ts
+     * const sem = new DistributedSemaphore({ key: "my-resource", limit: 5 });
+     * await sem.withLock(async () => {
+     *   // critical section (up to 5 concurrent holders)
+     * });
+     * ```
+     */
+    withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+    /** Close the underlying socket (idempotent). */
+    close(): Promise<void>;
+    private startRenew;
+    private stopRenew;
+}
 
-export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, LockError, acquire, enqueue, release, renew, waitForLock };
+export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, DistributedSemaphore, type DistributedSemaphoreOptions, LockError, type ShardingStrategy, acquire, enqueue, release, renew, semAcquire, semEnqueue, semRelease, semRenew, semWaitForLock, stableHashShard, waitForLock };

package/dist/client.d.ts

@@ -6,6 +6,8 @@ declare class AcquireTimeoutError extends Error {
 declare class LockError extends Error {
     constructor(message: string);
 }
+type ShardingStrategy = (key: string, numServers: number) => number;
+declare function stableHashShard(key: string, numServers: number): number;
 declare function acquire(sock: net.Socket, key: string, acquireTimeoutS: number, leaseTtlS?: number): Promise<{
     token: string;
     lease: number;
@@ -21,20 +23,39 @@ declare function waitForLock(sock: net.Socket, key: string, waitTimeoutS: number
     lease: number;
 }>;
 declare function release(sock: net.Socket, key: string, token: string): Promise<void>;
+declare function semAcquire(sock: net.Socket, key: string, acquireTimeoutS: number, limit: number, leaseTtlS?: number): Promise<{
+    token: string;
+    lease: number;
+}>;
+declare function semRenew(sock: net.Socket, key: string, token: string, leaseTtlS?: number): Promise<number>;
+declare function semEnqueue(sock: net.Socket, key: string, limit: number, leaseTtlS?: number): Promise<{
+    status: "acquired" | "queued";
+    token: string | null;
+    lease: number | null;
+}>;
+declare function semWaitForLock(sock: net.Socket, key: string, waitTimeoutS: number): Promise<{
+    token: string;
+    lease: number;
+}>;
+declare function semRelease(sock: net.Socket, key: string, token: string): Promise<void>;
 interface DistributedLockOptions {
     key: string;
     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;
 }
 declare class DistributedLock {
     readonly key: string;
     readonly acquireTimeoutS: number;
     readonly leaseTtlS: number | undefined;
-    readonly host: string;
-    readonly port: number;
+    readonly servers: Array<[string, number]>;
+    readonly shardingStrategy: ShardingStrategy;
     readonly renewRatio: number;
     token: string | null;
     lease: number;
@@ -42,6 +63,7 @@ declare class DistributedLock {
     private renewTimer;
     private closed;
     constructor(opts: DistributedLockOptions);
+    private pickServer;
     /** Acquire the lock. Returns `true` on success, `false` on timeout. */
     acquire(): Promise<boolean>;
     /** Release the lock and close the connection. */
@@ -74,5 +96,65 @@ declare class DistributedLock {
     private startRenew;
     private stopRenew;
 }
+interface DistributedSemaphoreOptions {
+    key: string;
+    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;
+}
+declare class DistributedSemaphore {
+    readonly key: string;
+    readonly limit: number;
+    readonly acquireTimeoutS: number;
+    readonly leaseTtlS: number | undefined;
+    readonly servers: Array<[string, number]>;
+    readonly shardingStrategy: ShardingStrategy;
+    readonly renewRatio: number;
+    token: string | null;
+    lease: number;
+    private sock;
+    private renewTimer;
+    private closed;
+    constructor(opts: DistributedSemaphoreOptions);
+    private pickServer;
+    /** Acquire a semaphore slot. Returns `true` on success, `false` on timeout. */
+    acquire(): Promise<boolean>;
+    /** Release the semaphore slot and close the connection. */
+    release(): Promise<void>;
+    /**
+     * Two-phase step 1: connect and join the FIFO queue.
+     * Returns `"acquired"` (fast-path, slot granted immediately) or `"queued"`.
+     * If acquired immediately, the renew loop starts automatically.
+     */
+    enqueue(): Promise<"acquired" | "queued">;
+    /**
+     * Two-phase step 2: block until a semaphore 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.
+     *
+     * ```ts
+     * const sem = new DistributedSemaphore({ key: "my-resource", limit: 5 });
+     * await sem.withLock(async () => {
+     *   // critical section (up to 5 concurrent holders)
+     * });
+     * ```
+     */
+    withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+    /** Close the underlying socket (idempotent). */
+    close(): Promise<void>;
+    private startRenew;
+    private stopRenew;
+}
 
-export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, LockError, acquire, enqueue, release, renew, waitForLock };
+export { AcquireTimeoutError, DistributedLock, type DistributedLockOptions, DistributedSemaphore, type DistributedSemaphoreOptions, LockError, type ShardingStrategy, acquire, enqueue, release, renew, semAcquire, semEnqueue, semRelease, semRenew, semWaitForLock, stableHashShard, waitForLock };

package/dist/client.js

@@ -52,6 +52,24 @@ function connect(host, port) {
     sock.on("error", reject);
   });
 }
+var CRC32_TABLE = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+  let c = i;
+  for (let j = 0; j < 8; j++) {
+    c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  }
+  CRC32_TABLE[i] = c;
+}
+function crc32(buf) {
+  let crc = 4294967295;
+  for (let i = 0; i < buf.length; i++) {
+    crc = CRC32_TABLE[(crc ^ buf[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function stableHashShard(key, numServers) {
+  return (crc32(Buffer.from(key, "utf-8")) >>> 0) % numServers;
+}
 async function acquire(sock, key, acquireTimeoutS, leaseTtlS) {
   const arg = leaseTtlS == null ? String(acquireTimeoutS) : `${acquireTimeoutS} ${leaseTtlS}`;
   sock.write(encodeLines("l", key, arg));
@@ -119,12 +137,79 @@ async function release(sock, key, token) {
     throw new LockError(`release failed: '${resp}'`);
   }
 }
+async function semAcquire(sock, key, acquireTimeoutS, limit, leaseTtlS) {
+  const arg = leaseTtlS == null ? `${acquireTimeoutS} ${limit}` : `${acquireTimeoutS} ${limit} ${leaseTtlS}`;
+  sock.write(encodeLines("sl", key, arg));
+  const resp = await readline(sock);
+  if (resp === "timeout") {
+    throw new AcquireTimeoutError(key);
+  }
+  if (!resp.startsWith("ok ")) {
+    throw new LockError(`sem_acquire failed: '${resp}'`);
+  }
+  const parts = resp.split(" ");
+  if (parts.length < 2) {
+    throw new LockError(`bad ok response: '${resp}'`);
+  }
+  const token = parts[1];
+  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;
+  return { token, lease };
+}
+async function semRenew(sock, key, token, leaseTtlS) {
+  const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;
+  sock.write(encodeLines("sn", key, arg));
+  const resp = await readline(sock);
+  if (!resp.startsWith("ok")) {
+    throw new LockError(`sem_renew failed: '${resp}'`);
+  }
+  const parts = resp.split(" ");
+  if (parts.length >= 2 && /^\d+$/.test(parts[1])) {
+    return parseInt(parts[1], 10);
+  }
+  return -1;
+}
+async function semEnqueue(sock, key, limit, leaseTtlS) {
+  const arg = leaseTtlS == null ? String(limit) : `${limit} ${leaseTtlS}`;
+  sock.write(encodeLines("se", key, arg));
+  const resp = await readline(sock);
+  if (resp.startsWith("acquired ")) {
+    const parts = resp.split(" ");
+    const token = parts[1];
+    const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;
+    return { status: "acquired", token, lease };
+  }
+  if (resp === "queued") {
+    return { status: "queued", token: null, lease: null };
+  }
+  throw new LockError(`sem_enqueue failed: '${resp}'`);
+}
+async function semWaitForLock(sock, key, waitTimeoutS) {
+  sock.write(encodeLines("sw", key, String(waitTimeoutS)));
+  const resp = await readline(sock);
+  if (resp === "timeout") {
+    throw new AcquireTimeoutError(key);
+  }
+  if (!resp.startsWith("ok ")) {
+    throw new LockError(`sem_wait failed: '${resp}'`);
+  }
+  const parts = resp.split(" ");
+  const token = parts[1];
+  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;
+  return { token, lease };
+}
+async function semRelease(sock, key, token) {
+  sock.write(encodeLines("sr", key, token));
+  const resp = await readline(sock);
+  if (resp !== "ok") {
+    throw new LockError(`sem_release failed: '${resp}'`);
+  }
+}
 var DistributedLock = class {
   key;
   acquireTimeoutS;
   leaseTtlS;
-  host;
-  port;
+  servers;
+  shardingStrategy;
   renewRatio;
   token = null;
   lease = 0;
@@ -135,14 +220,26 @@ var DistributedLock = class {
     this.key = opts.key;
     this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;
     this.leaseTtlS = opts.leaseTtlS;
-    this.host = opts.host ?? DEFAULT_HOST;
-    this.port = opts.port ?? DEFAULT_PORT;
+    if (opts.servers) {
+      if (opts.servers.length === 0) {
+        throw new LockError("servers list must not be empty");
+      }
+      this.servers = opts.servers;
+    } else {
+      this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];
+    }
+    this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;
     this.renewRatio = opts.renewRatio ?? 0.5;
   }
+  pickServer() {
+    const idx = this.shardingStrategy(this.key, this.servers.length);
+    return this.servers[idx];
+  }
   /** Acquire the lock. Returns `true` on success, `false` on timeout. */
   async acquire() {
     this.closed = false;
-    this.sock = await connect(this.host, this.port);
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
     try {
       const result = await acquire(
         this.sock,
@@ -178,7 +275,8 @@ var DistributedLock = class {
    */
   async enqueue() {
     this.closed = false;
-    this.sock = await connect(this.host, this.port);
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
     try {
       const result = await enqueue(this.sock, this.key, this.leaseTtlS);
       if (result.status === "acquired") {
@@ -274,14 +372,192 @@ var DistributedLock = class {
     }
   }
 };
+var DistributedSemaphore = class {
+  key;
+  limit;
+  acquireTimeoutS;
+  leaseTtlS;
+  servers;
+  shardingStrategy;
+  renewRatio;
+  token = null;
+  lease = 0;
+  sock = null;
+  renewTimer = null;
+  closed = false;
+  constructor(opts) {
+    this.key = opts.key;
+    this.limit = opts.limit;
+    this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;
+    this.leaseTtlS = opts.leaseTtlS;
+    if (opts.servers) {
+      if (opts.servers.length === 0) {
+        throw new LockError("servers list must not be empty");
+      }
+      this.servers = opts.servers;
+    } else {
+      this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];
+    }
+    this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;
+    this.renewRatio = opts.renewRatio ?? 0.5;
+  }
+  pickServer() {
+    const idx = this.shardingStrategy(this.key, this.servers.length);
+    return this.servers[idx];
+  }
+  /** Acquire a semaphore slot. Returns `true` on success, `false` on timeout. */
+  async acquire() {
+    this.closed = false;
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
+    try {
+      const result = await semAcquire(
+        this.sock,
+        this.key,
+        this.acquireTimeoutS,
+        this.limit,
+        this.leaseTtlS
+      );
+      this.token = result.token;
+      this.lease = result.lease;
+    } catch (err) {
+      await this.close();
+      if (err instanceof AcquireTimeoutError) return false;
+      throw err;
+    }
+    this.startRenew();
+    return true;
+  }
+  /** Release the semaphore slot and close the connection. */
+  async release() {
+    try {
+      this.stopRenew();
+      if (this.sock && this.token) {
+        await semRelease(this.sock, this.key, this.token);
+      }
+    } finally {
+      await this.close();
+    }
+  }
+  /**
+   * Two-phase step 1: connect and join the FIFO queue.
+   * Returns `"acquired"` (fast-path, slot granted immediately) or `"queued"`.
+   * If acquired immediately, the renew loop starts automatically.
+   */
+  async enqueue() {
+    this.closed = false;
+    const [host, port] = this.pickServer();
+    this.sock = await connect(host, port);
+    try {
+      const result = await semEnqueue(this.sock, this.key, this.limit, this.leaseTtlS);
+      if (result.status === "acquired") {
+        this.token = result.token;
+        this.lease = result.lease ?? 0;
+        this.startRenew();
+      }
+      return result.status;
+    } catch (err) {
+      await this.close();
+      throw err;
+    }
+  }
+  /**
+   * Two-phase step 2: block until a semaphore slot is granted.
+   * Returns `true` if granted, `false` on timeout.
+   * If already acquired during `enqueue()`, returns `true` immediately.
+   */
+  async wait(timeoutS) {
+    if (this.token !== null) {
+      return true;
+    }
+    if (!this.sock) {
+      throw new LockError("not connected; call enqueue() first");
+    }
+    const timeout = timeoutS ?? this.acquireTimeoutS;
+    try {
+      const result = await semWaitForLock(this.sock, this.key, timeout);
+      this.token = result.token;
+      this.lease = result.lease;
+    } catch (err) {
+      await this.close();
+      if (err instanceof AcquireTimeoutError) return false;
+      throw err;
+    }
+    this.startRenew();
+    return true;
+  }
+  /**
+   * Run `fn` while holding a semaphore 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)
+   * });
+   * ```
+   */
+  async withLock(fn) {
+    const ok = await this.acquire();
+    if (!ok) {
+      throw new AcquireTimeoutError(this.key);
+    }
+    try {
+      return await fn();
+    } finally {
+      await this.release();
+    }
+  }
+  /** Close the underlying socket (idempotent). */
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.stopRenew();
+    if (this.sock) {
+      this.sock.destroy();
+      this.sock = null;
+    }
+    this.token = null;
+  }
+  // -- internals --
+  startRenew() {
+    const interval = Math.max(1, this.lease * this.renewRatio) * 1e3;
+    const loop = async () => {
+      if (!this.sock || !this.token) return;
+      try {
+        await semRenew(this.sock, this.key, this.token, this.leaseTtlS);
+      } catch {
+        console.error(
+          `semaphore lost (renew failed): key=${this.key} token=${this.token}`
+        );
+        this.token = null;
+        return;
+      }
+      this.renewTimer = setTimeout(loop, interval);
+    };
+    this.renewTimer = setTimeout(loop, interval);
+  }
+  stopRenew() {
+    if (this.renewTimer != null) {
+      clearTimeout(this.renewTimer);
+      this.renewTimer = null;
+    }
+  }
+};
 export {
   AcquireTimeoutError,
   DistributedLock,
+  DistributedSemaphore,
   LockError,
   acquire,
   enqueue,
   release,
   renew,
+  semAcquire,
+  semEnqueue,
+  semRelease,
+  semRenew,
+  semWaitForLock,
+  stableHashShard,
   waitForLock
 };
 //# sourceMappingURL=client.js.map