dflockd-client 1.9.1 → 1.10.0

package/dist/client.js

@@ -211,14 +211,14 @@ function stableHashShard(key, numServers) {
 }
 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 (!Number.isInteger(acquireTimeoutS) || acquireTimeoutS < 0) {
+    throw new LockError("acquireTimeoutS must be an integer >= 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");
+  if (leaseTtlS != null && (!Number.isInteger(leaseTtlS) || leaseTtlS < 1)) {
+    throw new LockError("leaseTtlS must be an integer >= 1");
   }
   const parts = [acquireTimeoutS];
   if (limit != null) parts.push(limit);
@@ -241,8 +241,8 @@ async function protoAcquire(sock, cmd, label, key, acquireTimeoutS, leaseTtlS, l
 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");
+  if (leaseTtlS != null && (!Number.isInteger(leaseTtlS) || leaseTtlS < 1)) {
+    throw new LockError("leaseTtlS must be an integer >= 1");
   }
   const arg = leaseTtlS == null ? token : `${token} ${leaseTtlS}`;
   await writeAll(sock, encodeLines(cmd, key, arg));
@@ -258,8 +258,8 @@ async function protoEnqueue(sock, cmd, label, key, leaseTtlS, limit) {
   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");
+  if (leaseTtlS != null && (!Number.isInteger(leaseTtlS) || leaseTtlS < 1)) {
+    throw new LockError("leaseTtlS must be an integer >= 1");
   }
   const parts = [];
   if (limit != null) parts.push(limit);
@@ -281,8 +281,8 @@ async function protoEnqueue(sock, cmd, label, key, leaseTtlS, limit) {
 }
 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");
+  if (!Number.isInteger(waitTimeoutS) || waitTimeoutS < 0) {
+    throw new LockError("waitTimeoutS must be an integer >= 0");
   }
   await writeAll(sock, encodeLines(cmd, key, String(waitTimeoutS)));
   const resp = await readline(sock);
@@ -389,11 +389,11 @@ var DistributedPrimitive = class {
     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 (!Number.isInteger(this.acquireTimeoutS) || this.acquireTimeoutS < 0) {
+      throw new LockError("acquireTimeoutS must be an integer >= 0");
     }
-    if (this.leaseTtlS != null && (!Number.isFinite(this.leaseTtlS) || this.leaseTtlS <= 0)) {
-      throw new LockError("leaseTtlS must be a finite number > 0");
+    if (this.leaseTtlS != null && (!Number.isInteger(this.leaseTtlS) || this.leaseTtlS < 1)) {
+      throw new LockError("leaseTtlS must be an integer >= 1");
     }
     if (opts.servers) {
       if (opts.servers.length === 0) {
@@ -460,8 +460,8 @@ var DistributedPrimitive = class {
       this.close();
     }
     this.closed = false;
-    this.sock = await this.openConnection();
     try {
+      this.sock = await this.openConnection();
       this.suspendSocketTimeout(this.sock);
       const result = await this.doAcquire(this.sock);
       this.restoreSocketTimeout(this.sock);
@@ -496,7 +496,7 @@ var DistributedPrimitive = class {
       if (this.renewInFlight) {
         await Promise.race([
           this.renewInFlight,
-          new Promise((r) => setTimeout(r, 5e3))
+          new Promise((r) => setTimeout(r, 5e3).unref())
         ]);
         this.stopRenew();
       }
@@ -527,16 +527,16 @@ var DistributedPrimitive = class {
       this.close();
     }
     this.closed = false;
-    this.sock = await this.openConnection();
     try {
+      this.sock = await this.openConnection();
       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.restoreSocketTimeout(this.sock);
         this.startRenew();
       }
-      this.restoreSocketTimeout(this.sock);
       return result.status;
     } catch (err) {
       this.close();
@@ -714,14 +714,318 @@ var DistributedSemaphore = class extends DistributedPrimitive {
     return semRenew(sock, this.key, token, this.leaseTtlS);
   }
 };
+function validatePayload(payload) {
+  if (payload === "") {
+    throw new LockError("payload must not be empty");
+  }
+  if (/[\0\n\r]/.test(payload)) {
+    throw new LockError(
+      "payload must not contain NUL, newline, or carriage return characters"
+    );
+  }
+}
+async function publish(sock, channel, payload) {
+  validateKey(channel);
+  validatePayload(payload);
+  await writeAll(sock, encodeLines("signal", channel, payload));
+  const resp = await readline(sock);
+  if (!resp.startsWith("ok ")) {
+    throw new LockError(`signal failed: '${resp}'`);
+  }
+  const n = parseInt(resp.split(" ")[1], 10);
+  if (!Number.isFinite(n)) {
+    throw new LockError(`signal: bad delivery count: '${resp}'`);
+  }
+  return n;
+}
+var SignalConnection = class _SignalConnection {
+  sock;
+  buf = "";
+  responseResolve = null;
+  responseReject = null;
+  cmdQueue = [];
+  cmdBusy = false;
+  signalListeners = [];
+  _closed = false;
+  /**
+   * Wrap an existing socket as a SignalConnection.
+   *
+   * The socket should already be connected (and authenticated, if needed).
+   * Prefer `SignalConnection.connect()` for convenience.
+   */
+  constructor(sock) {
+    this.sock = sock;
+    const leftover = _readlineBuf.get(sock);
+    if (leftover) {
+      this.buf = leftover;
+      _readlineBuf.delete(sock);
+    }
+    sock.on("data", (chunk) => this.onData(chunk));
+    sock.on("error", (err) => this.onSocketError(err));
+    sock.on("close", () => this.onSocketEnd());
+    sock.on("end", () => this.onSocketEnd());
+    this.drainLines();
+  }
+  /** Connect to a dflockd server and return a SignalConnection. */
+  static async connect(opts) {
+    const host = opts?.host ?? DEFAULT_HOST;
+    const port = opts?.port ?? DEFAULT_PORT;
+    const sock = await connect2(
+      host,
+      port,
+      opts?.tls,
+      opts?.auth,
+      opts?.connectTimeoutMs
+    );
+    return new _SignalConnection(sock);
+  }
+  /**
+   * Subscribe to signals matching `pattern`.
+   *
+   * Patterns support NATS-style wildcards:
+   * - `*` matches exactly one dot-separated token
+   * - `>` matches one or more trailing tokens
+   *
+   * If `group` is provided, the subscription joins a queue group where
+   * signals are load-balanced (round-robin) among group members.
+   */
+  async listen(pattern, group) {
+    validateKey(pattern);
+    if (group != null && /[\0\n\r]/.test(group)) {
+      throw new LockError(
+        "group must not contain NUL, newline, or carriage return characters"
+      );
+    }
+    const resp = await this.sendCmd("listen", pattern, group ?? "");
+    if (resp !== "ok") {
+      throw new LockError(`listen failed: '${resp}'`);
+    }
+  }
+  /**
+   * Unsubscribe from signals matching `pattern`.
+   * The `pattern` and `group` must match a previous `listen()` call.
+   */
+  async unlisten(pattern, group) {
+    validateKey(pattern);
+    if (group != null && /[\0\n\r]/.test(group)) {
+      throw new LockError(
+        "group must not contain NUL, newline, or carriage return characters"
+      );
+    }
+    const resp = await this.sendCmd("unlisten", pattern, group ?? "");
+    if (resp !== "ok") {
+      throw new LockError(`unlisten failed: '${resp}'`);
+    }
+  }
+  /**
+   * Publish a signal on a literal channel (no wildcards).
+   * Returns the number of listeners that received the signal.
+   */
+  async emit(channel, payload) {
+    validateKey(channel);
+    validatePayload(payload);
+    const resp = await this.sendCmd("signal", channel, payload);
+    if (!resp.startsWith("ok ")) {
+      throw new LockError(`signal failed: '${resp}'`);
+    }
+    const n = parseInt(resp.split(" ")[1], 10);
+    if (!Number.isFinite(n)) {
+      throw new LockError(`signal: bad delivery count: '${resp}'`);
+    }
+    return n;
+  }
+  /** Register a listener for incoming signals. */
+  onSignal(listener) {
+    this.signalListeners.push(listener);
+  }
+  /** Remove a previously registered signal listener. */
+  offSignal(listener) {
+    const idx = this.signalListeners.indexOf(listener);
+    if (idx >= 0) this.signalListeners.splice(idx, 1);
+  }
+  /**
+   * Async iterator that yields signals as they arrive.
+   * Terminates when the connection closes.
+   *
+   * ```ts
+   * for await (const sig of conn) {
+   *   console.log(sig.channel, sig.payload);
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator]() {
+    const buffer = [];
+    let waiter = null;
+    const listener = (sig) => {
+      buffer.push(sig);
+      if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w();
+      }
+    };
+    const onEnd = () => {
+      if (waiter) {
+        const w = waiter;
+        waiter = null;
+        w();
+      }
+    };
+    this.onSignal(listener);
+    this.sock.once("close", onEnd);
+    try {
+      while (true) {
+        if (buffer.length > 0) {
+          yield buffer.shift();
+          continue;
+        }
+        if (this._closed) break;
+        await new Promise((resolve) => {
+          waiter = resolve;
+        });
+      }
+      while (buffer.length > 0) {
+        yield buffer.shift();
+      }
+    } finally {
+      this.offSignal(listener);
+      this.sock.removeListener("close", onEnd);
+    }
+  }
+  /** Close the connection (idempotent). */
+  close() {
+    if (this._closed) return;
+    this._closed = true;
+    this.sock.destroy();
+    this.rejectPending(new LockError("connection closed"));
+  }
+  /** Whether the connection is closed. */
+  get isClosed() {
+    return this._closed;
+  }
+  // ---- internals ----
+  onData(chunk) {
+    this.buf += chunk.toString("utf-8");
+    if (this.buf.length > MAX_LINE_LENGTH * 2) {
+      this.buf = "";
+      this._closed = true;
+      this.sock.destroy();
+      this.rejectPending(
+        new LockError("server response exceeded maximum buffer size")
+      );
+      return;
+    }
+    this.drainLines();
+  }
+  drainLines() {
+    let idx;
+    while ((idx = this.buf.indexOf("\n")) !== -1) {
+      const line = this.buf.slice(0, idx).replace(/\r$/, "");
+      this.buf = this.buf.slice(idx + 1);
+      this.handleLine(line);
+    }
+  }
+  handleLine(line) {
+    if (line.startsWith("sig ")) {
+      const rest = line.slice(4);
+      const spaceIdx = rest.indexOf(" ");
+      if (spaceIdx < 0) return;
+      const sig = {
+        channel: rest.slice(0, spaceIdx),
+        payload: rest.slice(spaceIdx + 1)
+      };
+      for (const listener of [...this.signalListeners]) {
+        try {
+          listener(sig);
+        } catch {
+        }
+      }
+      return;
+    }
+    if (this.responseResolve) {
+      const resolve = this.responseResolve;
+      this.responseResolve = null;
+      this.responseReject = null;
+      resolve(line);
+    }
+  }
+  onSocketError(err) {
+    this._closed = true;
+    this.rejectPending(err);
+  }
+  onSocketEnd() {
+    this._closed = true;
+    this.rejectPending(new LockError("server closed connection"));
+  }
+  rejectPending(err) {
+    if (this.responseReject) {
+      const reject = this.responseReject;
+      this.responseResolve = null;
+      this.responseReject = null;
+      reject(err);
+    }
+  }
+  sendCmd(cmd, key, arg) {
+    return new Promise((outerResolve, outerReject) => {
+      const execute = () => {
+        if (this._closed) {
+          this.cmdBusy = false;
+          this.dequeueNext();
+          outerReject(new LockError("connection closed"));
+          return;
+        }
+        let settled = false;
+        this.responseResolve = (line) => {
+          if (settled) return;
+          settled = true;
+          this.cmdBusy = false;
+          this.dequeueNext();
+          outerResolve(line);
+        };
+        this.responseReject = (err) => {
+          if (settled) return;
+          settled = true;
+          this.cmdBusy = false;
+          this.dequeueNext();
+          outerReject(err);
+        };
+        this.sock.write(encodeLines(cmd, key, arg), (err) => {
+          if (err && !settled) {
+            settled = true;
+            this.responseResolve = null;
+            this.responseReject = null;
+            this.cmdBusy = false;
+            this.dequeueNext();
+            outerReject(err);
+          }
+        });
+      };
+      if (this.cmdBusy) {
+        this.cmdQueue.push(execute);
+      } else {
+        this.cmdBusy = true;
+        execute();
+      }
+    });
+  }
+  dequeueNext() {
+    const next = this.cmdQueue.shift();
+    if (next) {
+      this.cmdBusy = true;
+      next();
+    }
+  }
+};
 export {
   AcquireTimeoutError,
   AuthError,
   DistributedLock,
   DistributedSemaphore,
   LockError,
+  SignalConnection,
   acquire,
   enqueue,
+  publish,
   release,
   renew,
   semAcquire,