dflockd-client 1.8.3 → 1.9.1

package/dist/client.js

@@ -21,6 +21,33 @@ var AuthError = class extends LockError {
     this.name = "AuthError";
   }
 };
+function validateKey(key) {
+  if (key === "") {
+    throw new LockError("key must not be empty");
+  }
+  if (/[\0\n\r]/.test(key)) {
+    throw new LockError(
+      "key must not contain NUL, newline, or carriage return characters"
+    );
+  }
+}
+function validateAuth(auth) {
+  if (/[\0\n\r]/.test(auth)) {
+    throw new LockError(
+      "auth token must not contain NUL, newline, or carriage return characters"
+    );
+  }
+}
+function validateToken(token) {
+  if (token === "") {
+    throw new LockError("token must not be empty");
+  }
+  if (/[\0\n\r]/.test(token)) {
+    throw new LockError(
+      "token must not contain NUL, newline, or carriage return characters"
+    );
+  }
+}
 function encodeLines(...lines) {
   return Buffer.from(lines.map((l) => l + "\n").join(""), "utf-8");
 }
@@ -32,7 +59,13 @@ function writeAll(sock, data) {
     });
   });
 }
+function parseLease(value, fallback = 30) {
+  if (value == null || value === "") return fallback;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : fallback;
+}
 var _readlineBuf = /* @__PURE__ */ new WeakMap();
+var MAX_LINE_LENGTH = 1024 * 1024;
 function readline(sock) {
   return new Promise((resolve, reject) => {
     let buf = _readlineBuf.get(sock) ?? "";
@@ -51,6 +84,10 @@ function readline(sock) {
         const line = buf.slice(0, idx).replace(/\r$/, "");
         _readlineBuf.set(sock, buf.slice(idx + 1));
         resolve(line);
+      } else if (buf.length > MAX_LINE_LENGTH) {
+        cleanup();
+        _readlineBuf.delete(sock);
+        reject(new LockError("server response exceeded maximum line length"));
       }
     };
     const onError = (err) => {
@@ -63,38 +100,83 @@ function readline(sock) {
       _readlineBuf.delete(sock);
       reject(new LockError("server closed connection"));
     };
+    const onEnd = () => {
+      cleanup();
+      _readlineBuf.delete(sock);
+      reject(new LockError("server closed connection"));
+    };
     const cleanup = () => {
       sock.removeListener("data", onData);
       sock.removeListener("error", onError);
       sock.removeListener("close", onClose);
+      sock.removeListener("end", onEnd);
     };
+    if (sock.readableEnded || sock.destroyed) {
+      _readlineBuf.delete(sock);
+      reject(new LockError("server closed connection"));
+      return;
+    }
     sock.on("data", onData);
     sock.on("error", onError);
     sock.on("close", onClose);
+    sock.on("end", onEnd);
   });
 }
-async function connect2(host, port, tlsOptions, auth) {
+async function connect2(host, port, tlsOptions, auth, connectTimeoutMs) {
   const sock = await new Promise((resolve, reject) => {
+    let timer = null;
+    let settled = false;
+    const connectEvent = tlsOptions ? "secureConnect" : "connect";
+    const onConnect = () => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      s.removeListener("error", onError);
+      resolve(s);
+    };
+    const onError = (err) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      s.removeListener(connectEvent, onConnect);
+      s.destroy();
+      reject(err);
+    };
+    let s;
     if (tlsOptions) {
-      const s = tls.connect({ host, port, ...tlsOptions }, () => {
-        s.removeListener("error", reject);
-        resolve(s);
-      });
-      s.on("error", reject);
+      s = tls.connect({ ...tlsOptions, host, port }, onConnect);
     } else {
-      const s = net.createConnection({ host, port }, () => {
-        s.removeListener("error", reject);
-        resolve(s);
-      });
-      s.on("error", reject);
+      s = net.createConnection({ host, port }, onConnect);
+    }
+    s.on("error", onError);
+    if (connectTimeoutMs != null && connectTimeoutMs > 0) {
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        s.removeListener("error", onError);
+        s.removeListener(connectEvent, onConnect);
+        s.destroy();
+        reject(
+          new LockError(
+            `connect timed out after ${connectTimeoutMs}ms to ${host}:${port}`
+          )
+        );
+      }, connectTimeoutMs);
     }
   });
   sock.setNoDelay(true);
   sock.on("error", () => {
   });
   if (auth != null && auth !== "") {
-    await writeAll(sock, encodeLines("auth", "_", auth));
-    const resp = await readline(sock);
+    validateAuth(auth);
+    let resp;
+    try {
+      await writeAll(sock, encodeLines("auth", "_", auth));
+      resp = await readline(sock);
+    } catch (err) {
+      sock.destroy();
+      throw err;
+    }
     if (resp === "ok") {
       return sock;
     }
@@ -122,135 +204,139 @@ function crc32(buf) {
   return (crc ^ 4294967295) >>> 0;
 }
 function stableHashShard(key, numServers) {
-  return (crc32(Buffer.from(key, "utf-8")) >>> 0) % numServers;
+  if (numServers <= 0) {
+    throw new LockError("numServers must be greater than 0");
+  }
+  return crc32(Buffer.from(key, "utf-8")) % numServers;
 }
-async function acquire(sock, key, acquireTimeoutS, leaseTtlS) {
-  const arg = leaseTtlS == null ? String(acquireTimeoutS) : `${acquireTimeoutS} ${leaseTtlS}`;
-  await writeAll(sock, encodeLines("l", key, arg));
+async function protoAcquire(sock, cmd, label, key, acquireTimeoutS, leaseTtlS, limit) {
+  validateKey(key);
+  if (!Number.isFinite(acquireTimeoutS) || acquireTimeoutS < 0) {
+    throw new LockError("acquireTimeoutS must be a finite number >= 0");
+  }
+  if (limit != null && (!Number.isInteger(limit) || limit < 1)) {
+    throw new LockError("limit must be an integer >= 1");
+  }
+  if (leaseTtlS != null && (!Number.isFinite(leaseTtlS) || leaseTtlS <= 0)) {
+    throw new LockError("leaseTtlS must be a finite number > 0");
+  }
+  const parts = [acquireTimeoutS];
+  if (limit != null) parts.push(limit);
+  if (leaseTtlS != null) parts.push(leaseTtlS);
+  await writeAll(sock, encodeLines(cmd, key, parts.join(" ")));
   const resp = await readline(sock);
   if (resp === "timeout") {
     throw new AcquireTimeoutError(key);
   }
   if (!resp.startsWith("ok ")) {
-    throw new LockError(`acquire failed: '${resp}'`);
+    throw new LockError(`${label} failed: '${resp}'`);
+  }
+  const respParts = resp.split(" ");
+  const token = respParts[1];
+  if (!token) {
+    throw new LockError(`${label}: server returned no token: '${resp}'`);
   }
-  const parts = resp.split(" ");
-  const token = parts[1];
-  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;
-  return { token, lease };
+  return { token, lease: parseLease(respParts[2]) };
 }
-async function renew(sock, key, token, leaseTtlS) {
+async function protoRenew(sock, cmd, label, key, token, leaseTtlS) {
+  validateKey(key);
+  validateToken(token);
+  if (leaseTtlS != null && (!Number.isFinite(leaseTtlS) || leaseTtlS <= 0)) {
+    throw new LockError("leaseTtlS must be a finite number > 0");
+  }
   const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;
-  await writeAll(sock, encodeLines("n", key, arg));
+  await writeAll(sock, encodeLines(cmd, key, arg));
   const resp = await readline(sock);
   if (resp !== "ok" && !resp.startsWith("ok ")) {
-    throw new LockError(`renew failed: '${resp}'`);
-  }
-  const parts = resp.split(" ");
-  if (parts.length >= 2 && /^\d+$/.test(parts[1])) {
-    return parseInt(parts[1], 10);
+    throw new LockError(`${label} failed: '${resp}'`);
   }
-  throw new LockError(`renew: malformed response: '${resp}'`);
+  if (resp === "ok") return leaseTtlS ?? 30;
+  return parseLease(resp.split(" ")[1]);
 }
-async function enqueue(sock, key, leaseTtlS) {
-  const arg = leaseTtlS == null ? "" : String(leaseTtlS);
-  await writeAll(sock, encodeLines("e", key, arg));
+async function protoEnqueue(sock, cmd, label, key, leaseTtlS, limit) {
+  validateKey(key);
+  if (limit != null && (!Number.isInteger(limit) || limit < 1)) {
+    throw new LockError("limit must be an integer >= 1");
+  }
+  if (leaseTtlS != null && (!Number.isFinite(leaseTtlS) || leaseTtlS <= 0)) {
+    throw new LockError("leaseTtlS must be a finite number > 0");
+  }
+  const parts = [];
+  if (limit != null) parts.push(limit);
+  if (leaseTtlS != null) parts.push(leaseTtlS);
+  await writeAll(sock, encodeLines(cmd, key, parts.join(" ")));
   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 };
+    const respParts = resp.split(" ");
+    const token = respParts[1];
+    if (!token) {
+      throw new LockError(`${label}: server returned no token: '${resp}'`);
+    }
+    return { status: "acquired", token, lease: parseLease(respParts[2]) };
   }
   if (resp === "queued") {
     return { status: "queued", token: null, lease: null };
   }
-  throw new LockError(`enqueue failed: '${resp}'`);
+  throw new LockError(`${label} failed: '${resp}'`);
 }
-async function waitForLock(sock, key, waitTimeoutS) {
-  await writeAll(sock, encodeLines("w", key, String(waitTimeoutS)));
+async function protoWait(sock, cmd, label, key, waitTimeoutS) {
+  validateKey(key);
+  if (!Number.isFinite(waitTimeoutS) || waitTimeoutS < 0) {
+    throw new LockError("waitTimeoutS must be a finite number >= 0");
+  }
+  await writeAll(sock, encodeLines(cmd, key, String(waitTimeoutS)));
   const resp = await readline(sock);
   if (resp === "timeout") {
     throw new AcquireTimeoutError(key);
   }
   if (!resp.startsWith("ok ")) {
-    throw new LockError(`wait failed: '${resp}'`);
+    throw new LockError(`${label} failed: '${resp}'`);
   }
-  const parts = resp.split(" ");
-  const token = parts[1];
-  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;
-  return { token, lease };
+  const respParts = resp.split(" ");
+  const token = respParts[1];
+  if (!token) {
+    throw new LockError(`${label}: server returned no token: '${resp}'`);
+  }
+  return { token, lease: parseLease(respParts[2]) };
 }
-async function release(sock, key, token) {
-  await writeAll(sock, encodeLines("r", key, token));
+async function protoRelease(sock, cmd, label, key, token) {
+  validateKey(key);
+  validateToken(token);
+  await writeAll(sock, encodeLines(cmd, key, token));
   const resp = await readline(sock);
   if (resp !== "ok") {
-    throw new LockError(`release failed: '${resp}'`);
+    throw new LockError(`${label} failed: '${resp}'`);
   }
 }
+async function acquire(sock, key, acquireTimeoutS, leaseTtlS) {
+  return protoAcquire(sock, "l", "acquire", key, acquireTimeoutS, leaseTtlS);
+}
+async function renew(sock, key, token, leaseTtlS) {
+  return protoRenew(sock, "n", "renew", key, token, leaseTtlS);
+}
+async function enqueue(sock, key, leaseTtlS) {
+  return protoEnqueue(sock, "e", "enqueue", key, leaseTtlS);
+}
+async function waitForLock(sock, key, waitTimeoutS) {
+  return protoWait(sock, "w", "wait", key, waitTimeoutS);
+}
+async function release(sock, key, token) {
+  return protoRelease(sock, "r", "release", key, token);
+}
 async function semAcquire(sock, key, acquireTimeoutS, limit, leaseTtlS) {
-  const arg = leaseTtlS == null ? `${acquireTimeoutS} ${limit}` : `${acquireTimeoutS} ${limit} ${leaseTtlS}`;
-  await writeAll(sock, 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(" ");
-  const token = parts[1];
-  const lease = parts.length >= 3 ? parseInt(parts[2], 10) : 30;
-  return { token, lease };
+  return protoAcquire(sock, "sl", "sem_acquire", key, acquireTimeoutS, leaseTtlS, limit);
 }
 async function semRenew(sock, key, token, leaseTtlS) {
-  const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;
-  await writeAll(sock, encodeLines("sn", key, arg));
-  const resp = await readline(sock);
-  if (resp !== "ok" && !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);
-  }
-  throw new LockError(`sem_renew: malformed response: '${resp}'`);
+  return protoRenew(sock, "sn", "sem_renew", key, token, leaseTtlS);
 }
 async function semEnqueue(sock, key, limit, leaseTtlS) {
-  const arg = leaseTtlS == null ? String(limit) : `${limit} ${leaseTtlS}`;
-  await writeAll(sock, 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}'`);
+  return protoEnqueue(sock, "se", "sem_enqueue", key, leaseTtlS, limit);
 }
 async function semWaitForLock(sock, key, waitTimeoutS) {
-  await writeAll(sock, 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 };
+  return protoWait(sock, "sw", "sem_wait", key, waitTimeoutS);
 }
 async function semRelease(sock, key, token) {
-  await writeAll(sock, encodeLines("sr", key, token));
-  const resp = await readline(sock);
-  if (resp !== "ok") {
-    throw new LockError(`sem_release failed: '${resp}'`);
-  }
+  return protoRelease(sock, "sr", "sem_release", key, token);
 }
 async function statsProto(sock) {
   await writeAll(sock, encodeLines("stats", "_", ""));
@@ -268,14 +354,14 @@ async function statsProto(sock) {
 async function stats(options) {
   const host = options?.host ?? DEFAULT_HOST;
   const port = options?.port ?? DEFAULT_PORT;
-  const sock = await connect2(host, port, options?.tls, options?.auth);
+  const sock = await connect2(host, port, options?.tls, options?.auth, options?.connectTimeoutMs);
   try {
     return await statsProto(sock);
   } finally {
     sock.destroy();
   }
 }
-var DistributedLock = class {
+var DistributedPrimitive = class {
   key;
   acquireTimeoutS;
   leaseTtlS;
@@ -285,18 +371,30 @@ var DistributedLock = class {
   tls;
   auth;
   onLockLost;
+  connectTimeoutMs;
+  socketTimeoutMs;
   token = null;
   lease = 0;
   sock = null;
   renewTimer = null;
+  renewInFlight = null;
   closed = false;
   constructor(opts) {
+    validateKey(opts.key);
     this.key = opts.key;
     this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;
     this.leaseTtlS = opts.leaseTtlS;
     this.tls = opts.tls;
     this.auth = opts.auth;
     this.onLockLost = opts.onLockLost;
+    this.connectTimeoutMs = opts.connectTimeoutMs;
+    this.socketTimeoutMs = opts.socketTimeoutMs;
+    if (!Number.isFinite(this.acquireTimeoutS) || this.acquireTimeoutS < 0) {
+      throw new LockError("acquireTimeoutS must be a finite number >= 0");
+    }
+    if (this.leaseTtlS != null && (!Number.isFinite(this.leaseTtlS) || this.leaseTtlS <= 0)) {
+      throw new LockError("leaseTtlS must be a finite number > 0");
+    }
     if (opts.servers) {
       if (opts.servers.length === 0) {
         throw new LockError("servers list must not be empty");
@@ -306,7 +404,36 @@ var DistributedLock = class {
       this.servers = [[opts.host ?? DEFAULT_HOST, opts.port ?? DEFAULT_PORT]];
     }
     this.shardingStrategy = opts.shardingStrategy ?? stableHashShard;
-    this.renewRatio = opts.renewRatio ?? 0.5;
+    const renewRatio = opts.renewRatio ?? 0.5;
+    if (!Number.isFinite(renewRatio) || renewRatio <= 0 || renewRatio >= 1) {
+      throw new LockError("renewRatio must be a finite number between 0 and 1 (exclusive)");
+    }
+    this.renewRatio = renewRatio;
+  }
+  // -- public API --
+  async openConnection() {
+    const [host, port] = this.pickServer();
+    const sock = await connect2(host, port, this.tls, this.auth, this.connectTimeoutMs);
+    if (this.socketTimeoutMs != null && this.socketTimeoutMs > 0) {
+      sock.on("timeout", () => {
+        sock.destroy(new LockError("socket idle timeout"));
+      });
+      sock.setTimeout(this.socketTimeoutMs);
+    }
+    return sock;
+  }
+  /**
+   * Suspend or restore the socket idle timeout.  Only has effect when
+   * `socketTimeoutMs` was set at construction time and a listener was
+   * registered in `openConnection`.
+   */
+  suspendSocketTimeout(sock) {
+    sock.setTimeout(0);
+  }
+  restoreSocketTimeout(sock) {
+    if (this.socketTimeoutMs != null && this.socketTimeoutMs > 0) {
+      sock.setTimeout(this.socketTimeoutMs);
+    }
   }
   pickServer() {
     const idx = this.shardingStrategy(this.key, this.servers.length);
@@ -318,26 +445,26 @@ var DistributedLock = class {
     return this.servers[idx];
   }
   /**
-   * 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 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.
    */
   async acquire(opts) {
     if (this.sock && !this.closed) {
       if (!opts?.force) {
-        throw new LockError("already connected; call release() or close() first, or pass { force: true }");
+        throw new LockError(
+          "already connected; call release() or close() first, or pass { force: true }"
+        );
       }
       this.close();
     }
     this.closed = false;
-    const [host, port] = this.pickServer();
-    this.sock = await connect2(host, port, this.tls, this.auth);
+    this.sock = await this.openConnection();
     try {
-      const result = await acquire(
-        this.sock,
-        this.key,
-        this.acquireTimeoutS,
-        this.leaseTtlS
-      );
+      this.suspendSocketTimeout(this.sock);
+      const result = await this.doAcquire(this.sock);
+      this.restoreSocketTimeout(this.sock);
       this.token = result.token;
       this.lease = result.lease;
     } catch (err) {
@@ -348,12 +475,36 @@ var DistributedLock = class {
     this.startRenew();
     return true;
   }
-  /** Release the lock 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.
+   */
   async release() {
+    if (this.closed) {
+      throw new LockError("not connected; nothing to release");
+    }
+    const tokenToRelease = this.token;
+    const sockToRelease = this.sock;
     try {
       this.stopRenew();
-      if (this.sock && this.token) {
-        await release(this.sock, this.key, this.token);
+      if (this.renewInFlight) {
+        await Promise.race([
+          this.renewInFlight,
+          new Promise((r) => setTimeout(r, 5e3))
+        ]);
+        this.stopRenew();
+      }
+      if (sockToRelease != null && tokenToRelease != null) {
+        try {
+          await this.doRelease(sockToRelease, tokenToRelease);
+        } catch {
+        }
       }
     } finally {
       this.close();
@@ -361,27 +512,31 @@ var DistributedLock = class {
   }
   /**
    * Two-phase step 1: connect and join the FIFO queue.
-   * Returns `"acquired"` (fast-path, lock is already held) 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.
    */
   async enqueue(opts) {
     if (this.sock && !this.closed) {
       if (!opts?.force) {
-        throw new LockError("already connected; call release() or close() first, or pass { force: true }");
+        throw new LockError(
+          "already connected; call release() or close() first, or pass { force: true }"
+        );
       }
       this.close();
     }
     this.closed = false;
-    const [host, port] = this.pickServer();
-    this.sock = await connect2(host, port, this.tls, this.auth);
+    this.sock = await this.openConnection();
     try {
-      const result = await enqueue(this.sock, this.key, this.leaseTtlS);
+      this.suspendSocketTimeout(this.sock);
+      const result = await this.doEnqueue(this.sock);
       if (result.status === "acquired") {
         this.token = result.token;
         this.lease = result.lease ?? 0;
         this.startRenew();
       }
+      this.restoreSocketTimeout(this.sock);
       return result.status;
     } catch (err) {
       this.close();
@@ -389,7 +544,7 @@ var DistributedLock = class {
     }
   }
   /**
-   * Two-phase step 2: block until the lock 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.
    */
@@ -397,12 +552,17 @@ var DistributedLock = class {
     if (this.token !== null) {
       return true;
     }
+    if (this.closed) {
+      throw new LockError("connection closed; call enqueue() again");
+    }
     if (!this.sock) {
       throw new LockError("not connected; call enqueue() first");
     }
     const timeout = timeoutS ?? this.acquireTimeoutS;
     try {
-      const result = await waitForLock(this.sock, this.key, timeout);
+      this.suspendSocketTimeout(this.sock);
+      const result = await this.doWait(this.sock, timeout);
+      this.restoreSocketTimeout(this.sock);
       this.token = result.token;
       this.lease = result.lease;
     } catch (err) {
@@ -414,24 +574,28 @@ var DistributedLock = class {
     return true;
   }
   /**
-   * Run `fn` while holding the lock, then release automatically.
+   * Run `fn` while holding the lock / slot, then release automatically.
    *
-   * ```ts
-   * const lock = new DistributedLock({ key: "my-resource" });
-   * await lock.withLock(async () => {
-   *   // critical section
-   * });
-   * ```
+   * If `fn()` throws, its error is always preserved — a concurrent
+   * release failure will not mask it.
    */
   async withLock(fn) {
     const ok = await this.acquire();
     if (!ok) {
       throw new AcquireTimeoutError(this.key);
     }
+    let threw = false;
     try {
       return await fn();
+    } catch (err) {
+      threw = true;
+      throw err;
     } finally {
-      await this.release();
+      try {
+        await this.release();
+      } catch (releaseErr) {
+        if (!threw) throw releaseErr;
+      }
     }
   }
   /** Close the underlying socket (idempotent). */
@@ -439,29 +603,50 @@ var DistributedLock = class {
     if (this.closed) return;
     this.closed = true;
     this.stopRenew();
+    this.renewInFlight = null;
     if (this.sock) {
       this.sock.destroy();
       this.sock = null;
     }
     this.token = null;
+    this.lease = 0;
   }
   // -- internals --
   startRenew() {
+    this.stopRenew();
     const loop = async () => {
       const savedToken = this.token;
-      if (!this.sock || !savedToken) return;
+      const sock = this.sock;
+      if (!sock || !savedToken) return;
       const start = Date.now();
-      try {
-        this.lease = await renew(this.sock, this.key, savedToken, this.leaseTtlS);
-      } catch {
-        if (this.token === savedToken) {
-          this.token = null;
-          if (this.onLockLost) {
-            this.onLockLost(this.key, savedToken);
+      const p = (async () => {
+        try {
+          const newLease = await this.doRenew(sock, savedToken);
+          if (this.token === savedToken && !this.closed) {
+            this.lease = newLease;
+          }
+        } catch {
+          if (this.token === savedToken) {
+            this.token = null;
+            if (this.onLockLost) {
+              try {
+                const result = this.onLockLost(this.key, savedToken);
+                if (result instanceof Promise) {
+                  result.catch(() => {
+                  });
+                }
+              } catch {
+              }
+            }
+            this.close();
           }
+          return;
         }
-        return;
-      }
+      })();
+      this.renewInFlight = p;
+      await p;
+      this.renewInFlight = null;
+      if (this.closed || this.token !== savedToken) return;
       const elapsed = Date.now() - start;
       const interval2 = Math.max(1, this.lease * this.renewRatio) * 1e3;
       this.renewTimer = setTimeout(loop, Math.max(0, interval2 - elapsed));
@@ -478,210 +663,55 @@ var DistributedLock = class {
     }
   }
 };
-var DistributedSemaphore = class {
-  key;
-  limit;
-  acquireTimeoutS;
-  leaseTtlS;
-  servers;
-  shardingStrategy;
-  renewRatio;
-  tls;
-  auth;
-  onLockLost;
-  token = null;
-  lease = 0;
-  sock = null;
-  renewTimer = null;
-  closed = false;
+var DistributedLock = class extends DistributedPrimitive {
   constructor(opts) {
-    this.key = opts.key;
-    this.limit = opts.limit;
-    this.acquireTimeoutS = opts.acquireTimeoutS ?? 10;
-    this.leaseTtlS = opts.leaseTtlS;
-    this.tls = opts.tls;
-    this.auth = opts.auth;
-    this.onLockLost = opts.onLockLost;
-    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;
+    super(opts);
   }
-  pickServer() {
-    const idx = this.shardingStrategy(this.key, this.servers.length);
-    if (!Number.isInteger(idx) || idx < 0 || idx >= this.servers.length) {
-      throw new LockError(
-        `shardingStrategy returned invalid index ${idx} for ${this.servers.length} server(s)`
-      );
-    }
-    return this.servers[idx];
+  doAcquire(sock) {
+    return acquire(sock, this.key, this.acquireTimeoutS, this.leaseTtlS);
   }
-  /**
-   * 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.
-   */
-  async acquire(opts) {
-    if (this.sock && !this.closed) {
-      if (!opts?.force) {
-        throw new LockError("already connected; call release() or close() first, or pass { force: true }");
-      }
-      this.close();
-    }
-    this.closed = false;
-    const [host, port] = this.pickServer();
-    this.sock = await connect2(host, port, this.tls, this.auth);
-    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) {
-      this.close();
-      if (err instanceof AcquireTimeoutError) return false;
-      throw err;
-    }
-    this.startRenew();
-    return true;
+  doEnqueue(sock) {
+    return enqueue(sock, this.key, this.leaseTtlS);
   }
-  /** 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 {
-      this.close();
-    }
+  doWait(sock, timeoutS) {
+    return waitForLock(sock, this.key, timeoutS);
   }
-  /**
-   * 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.
-   * @param opts.force - If `true`, silently close any existing connection before enqueuing. Defaults to `false`, which throws if already connected.
-   */
-  async enqueue(opts) {
-    if (this.sock && !this.closed) {
-      if (!opts?.force) {
-        throw new LockError("already connected; call release() or close() first, or pass { force: true }");
-      }
-      this.close();
-    }
-    this.closed = false;
-    const [host, port] = this.pickServer();
-    this.sock = await connect2(host, port, this.tls, this.auth);
-    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) {
-      this.close();
-      throw err;
-    }
+  doRelease(sock, token) {
+    return release(sock, this.key, token);
   }
-  /**
-   * 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) {
-      this.close();
-      if (err instanceof AcquireTimeoutError) return false;
-      throw err;
-    }
-    this.startRenew();
-    return true;
+  doRenew(sock, token) {
+    return renew(sock, this.key, token, this.leaseTtlS);
   }
-  /**
-   * 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();
+};
+var DistributedSemaphore = class extends DistributedPrimitive {
+  limit;
+  constructor(opts) {
+    super(opts);
+    if (!Number.isInteger(opts.limit) || opts.limit < 1) {
+      throw new LockError("limit must be an integer >= 1");
     }
+    this.limit = opts.limit;
   }
-  /** Close the underlying socket (idempotent). */
-  close() {
-    if (this.closed) return;
-    this.closed = true;
-    this.stopRenew();
-    if (this.sock) {
-      this.sock.destroy();
-      this.sock = null;
-    }
-    this.token = null;
+  doAcquire(sock) {
+    return semAcquire(
+      sock,
+      this.key,
+      this.acquireTimeoutS,
+      this.limit,
+      this.leaseTtlS
+    );
   }
-  // -- internals --
-  startRenew() {
-    const loop = async () => {
-      const savedToken = this.token;
-      if (!this.sock || !savedToken) return;
-      const start = Date.now();
-      try {
-        this.lease = await semRenew(this.sock, this.key, savedToken, this.leaseTtlS);
-      } catch {
-        if (this.token === savedToken) {
-          this.token = null;
-          if (this.onLockLost) {
-            this.onLockLost(this.key, savedToken);
-          }
-        }
-        return;
-      }
-      const elapsed = Date.now() - start;
-      const interval2 = Math.max(1, this.lease * this.renewRatio) * 1e3;
-      this.renewTimer = setTimeout(loop, Math.max(0, interval2 - elapsed));
-      this.renewTimer.unref();
-    };
-    const interval = Math.max(1, this.lease * this.renewRatio) * 1e3;
-    this.renewTimer = setTimeout(loop, interval);
-    this.renewTimer.unref();
+  doEnqueue(sock) {
+    return semEnqueue(sock, this.key, this.limit, this.leaseTtlS);
   }
-  stopRenew() {
-    if (this.renewTimer != null) {
-      clearTimeout(this.renewTimer);
-      this.renewTimer = null;
-    }
+  doWait(sock, timeoutS) {
+    return semWaitForLock(sock, this.key, timeoutS);
+  }
+  doRelease(sock, token) {
+    return semRelease(sock, this.key, token);
+  }
+  doRenew(sock, token) {
+    return semRenew(sock, this.key, token, this.leaseTtlS);
   }
 };
 export {