dflockd-client 1.9.1 → 1.10.0

package/README.md

@@ -103,8 +103,8 @@ without blocking. If the lock is contended, `enqueue()` returns `"queued"` and
 | Option             | Type                          | Default                  | Description                                      |
 |--------------------|-------------------------------|--------------------------|--------------------------------------------------|
 | `key`              | `string`                      | *(required)*             | Lock name                                        |
-| `acquireTimeoutS`  | `number`                      | `10`                     | Seconds to wait for the lock before giving up    |
-| `leaseTtlS`        | `number`                      | server default           | Server-side lease duration in seconds             |
+| `acquireTimeoutS`  | `number`                      | `10`                     | Seconds to wait for the lock before giving up (integer ≥ 0) |
+| `leaseTtlS`        | `number`                      | server default           | Server-side lease duration in seconds (integer ≥ 1) |
 | `servers`          | `Array<[string, number]>`     | `[["127.0.0.1", 6388]]` | List of `[host, port]` pairs                     |
 | `shardingStrategy` | `ShardingStrategy`            | `stableHashShard`        | Function mapping `(key, numServers)` to a server index |
 | `host`             | `string`                      | `127.0.0.1`              | Server host *(deprecated — use `servers`)*       |
@@ -233,9 +233,9 @@ try {
 | Option             | Type                          | Default                  | Description                                      |
 |--------------------|-------------------------------|--------------------------|--------------------------------------------------|
 | `key`              | `string`                      | *(required)*             | Semaphore name                                   |
-| `limit`            | `number`                      | *(required)*             | Max concurrent holders                           |
-| `acquireTimeoutS`  | `number`                      | `10`                     | Seconds to wait before giving up                 |
-| `leaseTtlS`        | `number`                      | server default           | Server-side lease duration in seconds             |
+| `limit`            | `number`                      | *(required)*             | Max concurrent holders (integer ≥ 1)             |
+| `acquireTimeoutS`  | `number`                      | `10`                     | Seconds to wait before giving up (integer ≥ 0)   |
+| `leaseTtlS`        | `number`                      | server default           | Server-side lease duration in seconds (integer ≥ 1) |
 | `servers`          | `Array<[string, number]>`     | `[["127.0.0.1", 6388]]` | List of `[host, port]` pairs                     |
 | `shardingStrategy` | `ShardingStrategy`            | `stableHashShard`        | Function mapping `(key, numServers)` to a server index |
 | `host`             | `string`                      | `127.0.0.1`              | Server host *(deprecated — use `servers`)*       |
@@ -356,7 +356,7 @@ import * as net from "net";
 import {
   acquire, enqueue, waitForLock, renew, release,
   semAcquire, semEnqueue, semWaitForLock, semRenew, semRelease,
-  stats,
+  publish, stats,
 } from "dflockd-client";
 
 const sock = net.createConnection({ host: "127.0.0.1", port: 6388 });
@@ -383,9 +383,97 @@ if (semResult.status === "queued") {
   const semGranted = await semWaitForLock(sock, "sem-key", 10); // { token, lease }
 }
 
+// Signal — publish only (no subscription on raw sockets)
+const delivered = await publish(sock, "events.user.login", '{"user":"alice"}');
+
 sock.destroy();
 ```
 
+## Signals
+
+Publish/subscribe messaging with NATS-style pattern matching and optional
+queue groups for load-balanced consumption.
+
+### `SignalConnection` (recommended)
+
+```ts
+import { SignalConnection } from "dflockd-client";
+
+const conn = await SignalConnection.connect();
+
+// Subscribe to signals
+conn.onSignal((sig) => {
+  console.log(`${sig.channel}: ${sig.payload}`);
+});
+
+await conn.listen("events.>");
+
+// ... later
+await conn.unlisten("events.>");
+conn.close();
+```
+
+### Publish a signal
+
+```ts
+import { SignalConnection } from "dflockd-client";
+
+const conn = await SignalConnection.connect();
+const delivered = await conn.emit("events.user.login", '{"user":"alice"}');
+console.log(`delivered to ${delivered} listener(s)`);
+conn.close();
+```
+
+### Pattern matching
+
+Subscription patterns support NATS-style wildcards:
+
+- `*` matches exactly one dot-separated token (`events.*.login` matches
+  `events.user.login` but not `events.user.admin.login`)
+- `>` matches one or more trailing tokens (`events.>` matches
+  `events.user.login` and `events.order.created`)
+
+Publishing always uses literal channel names (no wildcards).
+
+### Queue groups
+
+Listeners can join a named queue group. Within a group, each signal is
+delivered to exactly one member (round-robin), enabling load-balanced
+processing. Non-grouped listeners always receive every matching signal.
+
+```ts
+// Worker 1
+await conn.listen("tasks.>", "workers");
+
+// Worker 2 (same group — only one receives each signal)
+await conn2.listen("tasks.>", "workers");
+```
+
+### Async iterator
+
+`SignalConnection` implements `Symbol.asyncIterator`, so you can consume
+signals with a `for-await-of` loop:
+
+```ts
+const conn = await SignalConnection.connect();
+await conn.listen("events.>");
+
+for await (const sig of conn) {
+  console.log(sig.channel, sig.payload);
+}
+// Loop ends when conn.close() is called
+```
+
+### Signal connection options
+
+| Option             | Type                    | Default        | Description                         |
+|--------------------|-------------------------|----------------|-------------------------------------|
+| `host`             | `string`                | `127.0.0.1`    | Server host                         |
+| `port`             | `number`                | `6388`         | Server port                         |
+| `tls`              | `tls.ConnectionOptions` | `undefined`    | TLS options; pass `{}` for system CA|
+| `auth`             | `string`                | `undefined`    | Auth token                          |
+| `connectTimeoutMs` | `number`                | `undefined`    | TCP connect timeout in milliseconds |
+
 ## License
 
 MIT

package/dist/client.cjs

@@ -35,8 +35,10 @@ __export(client_exports, {
   DistributedLock: () => DistributedLock,
   DistributedSemaphore: () => DistributedSemaphore,
   LockError: () => LockError,
+  SignalConnection: () => SignalConnection,
   acquire: () => acquire,
   enqueue: () => enqueue,
+  publish: () => publish,
   release: () => release,
   renew: () => renew,
   semAcquire: () => semAcquire,
@@ -261,14 +263,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);
@@ -291,8 +293,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));
@@ -308,8 +310,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);
@@ -331,8 +333,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);
@@ -439,11 +441,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) {
@@ -510,8 +512,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);
@@ -546,7 +548,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();
       }
@@ -577,16 +579,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();
@@ -764,6 +766,308 @@ 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();
+    }
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AcquireTimeoutError,
@@ -771,8 +1075,10 @@ var DistributedSemaphore = class extends DistributedPrimitive {
   DistributedLock,
   DistributedSemaphore,
   LockError,
+  SignalConnection,
   acquire,
   enqueue,
+  publish,
   release,
   renew,
   semAcquire,