@seriousme/opifex 1.11.3 → 2.1.0

package/utils/outboundTopicAliasManager.ts

@@ -0,0 +1,100 @@
+/**
+ * Represents the result of processing an outbound topic name,
+ * containing either the original topic name, a topic alias integer, or both.
+ */
+export interface OutboundTopicAlias {
+  /**
+   * The topic name.
+   * Will be empty (`""`) when a valid alias mapping has already been established.
+   */
+  topicName: string;
+
+  /**
+   * The numeric alias assigned to the topic, if aliases are enabled.
+   */
+  topicAlias?: number;
+}
+
+/**
+ * Manages outbound MQTT topic aliases using a Least Recently Used (LRU) caching strategy.
+ */
+export class OutboundTopicAliasManager {
+  /**
+   * The maximum number of topic aliases supported by the broker/client.
+   */
+  private readonly maxAliases: number;
+
+  /**
+   * Internal mapping from topic names to assigned aliases.
+   * Leverages JavaScript's Map insertion-order behavior to act as an LRU cache.
+   */
+  private readonly topicToAlias: Map<string, number>;
+
+  /**
+   * Creates an instance of `OutboundTopicAliasManager`.
+   *
+   * @param clientTopicAliasMaximum - The maximum number of topic aliases allowed (defaults to `0`, meaning disabled).
+   */
+  constructor(clientTopicAliasMaximum: number = 0) {
+    this.maxAliases = clientTopicAliasMaximum;
+    this.topicToAlias = new Map();
+  }
+
+  /**
+   * Processes an outbound topic name and returns the appropriate payload metadata
+   * (`OutboundTopcAlias`) based on alias availability and caching state.
+   *
+   * - If aliases are disabled (`maxAliases === 0`), returns only the original `topicName`.
+   * - If the topic is already cached (cache hit), refreshes its LRU position and returns the `topicAlias` with an empty `topicName`.
+   * - If the topic is not cached (cache miss), assigns a new alias or evicts the least recently used topic alias mapping.
+   *
+   * @param topic - The outbound MQTT topic name to process.
+   * @returns An object containing the formatted `topicName` and optional `topicAlias`.
+   */
+  public processTopic(topic: string): OutboundTopicAlias {
+    if (this.maxAliases === 0) {
+      return { topicName: topic };
+    }
+
+    // Cache Hit -> Refresh LRU-position in Map
+    if (this.topicToAlias.has(topic)) {
+      const alias = this.topicToAlias.get(topic)!;
+      this.topicToAlias.delete(topic);
+      this.topicToAlias.set(topic, alias);
+
+      return {
+        topicName: "",
+        topicAlias: alias,
+      };
+    }
+
+    // Cache Miss
+    let assignedAlias: number;
+
+    if (this.topicToAlias.size < this.maxAliases) {
+      // While there is space, simply assign the next alias (1, 2, 3...)
+      assignedAlias = this.topicToAlias.size + 1;
+    } else {
+      // Cache full: reuse the alias of the least used topic (first key in the Map)
+      const lruTopic = this.topicToAlias.keys().next().value;
+      assignedAlias = this.topicToAlias.get(lruTopic!)!;
+
+      this.topicToAlias.delete(lruTopic!);
+    }
+
+    // Store the new topic
+    this.topicToAlias.set(topic, assignedAlias);
+
+    return {
+      topicName: topic,
+      topicAlias: assignedAlias,
+    };
+  }
+
+  /**
+   * Clears all internal topic alias mappings and releases cached resources.
+   */
+  public destroy(): void {
+    this.topicToAlias.clear();
+  }
+}

package/utils/queue.test.ts

@@ -0,0 +1,61 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { ArrayQueue } from "./queue.ts";
+
+test("should initialize as an empty queue", () => {
+  const queue = new ArrayQueue<number>();
+  assert.strictEqual(queue.isEmpty(), true);
+  assert.strictEqual(queue.size(), 0);
+});
+
+test("should enqueue elements and update size correctly", () => {
+  const queue = new ArrayQueue<string>();
+
+  queue.enqueue("A");
+  assert.strictEqual(queue.isEmpty(), false);
+  assert.strictEqual(queue.size(), 1);
+
+  queue.enqueue("B");
+  assert.strictEqual(queue.size(), 2);
+});
+
+test("should dequeue elements in First-In, First-Out (FIFO) order", () => {
+  const queue = new ArrayQueue<number>();
+  queue.enqueue(10);
+  queue.enqueue(20);
+  queue.enqueue(30);
+
+  assert.strictEqual(queue.dequeue(), 10);
+  assert.strictEqual(queue.size(), 2);
+
+  assert.strictEqual(queue.dequeue(), 20);
+  assert.strictEqual(queue.size(), 1);
+
+  assert.strictEqual(queue.dequeue(), 30);
+  assert.strictEqual(queue.isEmpty(), true);
+});
+
+test("should return undefined when dequeuing an empty queue", () => {
+  const queue = new ArrayQueue<unknown>();
+  assert.strictEqual(queue.dequeue(), undefined);
+});
+
+test("should trigger internal cleanup (slice optimization) correctly", () => {
+  const queue = new ArrayQueue<number>();
+
+  // 1. Fill the queue with enough elements to exceed the threshold of 2000
+  const testSize = 2500;
+  for (let i = 0; i < testSize; i++) {
+    queue.enqueue(i);
+  }
+
+  // 2. Dequeue more than 1/4 of the total length to trigger the optimization (> 625 times)
+  // Dequeuing 2100 times satisfies the condition: headIndex > 2000 && headIndex > items.length / 4
+  for (let i = 0; i < 2100; i++) {
+    assert.strictEqual(queue.dequeue(), i);
+  }
+
+  // 3. Verify that the queue still functions correctly after internal cleanup
+  assert.strictEqual(queue.size(), testSize - 2100); // 400 remaining
+  assert.strictEqual(queue.dequeue(), 2100); // Next in line
+});

package/utils/topicFilter.test.ts

@@ -0,0 +1,63 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { topicFilterToRegExp } from "./topicFilter.ts";
+
+test("should convert an exact topic filter without wildcards to a valid regex string", () => {
+  const filter = "home/livingroom/temperature";
+  const regex = topicFilterToRegExp(filter);
+
+  assert.strictEqual(regex.test("home/livingroom/temperature"), true);
+  assert.strictEqual(regex.test("home/kitchen/temperature"), false);
+});
+
+test("should handle the single-level wildcard (+) correctly", () => {
+  const filter = "home/+/temperature";
+  const regex = topicFilterToRegExp(filter);
+
+  // Should match exactly one arbitrary level
+  assert.strictEqual(regex.test("home/livingroom/temperature"), true);
+  assert.strictEqual(regex.test("home/kitchen/temperature"), true);
+
+  // Should not match if the level is missing or contains sub-levels
+  assert.strictEqual(regex.test("home/temperature"), false);
+  assert.strictEqual(regex.test("home/livingroom/closet/temperature"), false);
+});
+
+test("should handle the multi-level wildcard (#) correctly", () => {
+  const filter = "home/#";
+  const regex = topicFilterToRegExp(filter);
+
+  // Should match anything that follows the prefix (including nothing)
+  assert.strictEqual(regex.test("home"), true);
+  assert.strictEqual(regex.test("home/livingroom"), true);
+  assert.strictEqual(regex.test("home/livingroom/temperature"), true);
+  assert.strictEqual(regex.test("home/kitchen/lights/status"), true);
+  // should not match extensions
+  assert.strictEqual(regex.test("homeo/livingroom"), false);
+});
+
+test("should escape special regex characters safely", () => {
+  // Characters like '.' and '$' have special meanings in regex, but are literal in MQTT
+  const filter = "device/v1.0$/+";
+  const regex = topicFilterToRegExp(filter);
+
+  // Should match the exact literal characters including the dot and dollar sign
+  assert.strictEqual(regex.test("device/v1.0$/sensor"), true);
+
+  // Should fail if the '.' is treated as a regex wildcard (matching any character)
+  assert.strictEqual(regex.test("device/v1X0$/sensor"), false);
+});
+
+test("should combine both single-level (+) and multi-level (#) wildcards correctly", () => {
+  const filter = "clients/+/status/#";
+  const regex = topicFilterToRegExp(filter);
+
+  assert.strictEqual(regex.test("clients/user123/status"), true);
+  assert.strictEqual(regex.test("clients/user456/status/online"), true);
+  assert.strictEqual(
+    regex.test("clients/device789/status/connection/errors"),
+    true,
+  );
+
+  assert.strictEqual(regex.test("clients/status/online"), false);
+});

package/utils/topicFilter.ts

@@ -0,0 +1,61 @@
+/**
+ * Converts an MQTT topic filter into a regular expression according to the MQTT specification.
+ *
+ * This utility escapes standard regex characters to prevent injection or unexpected behavior,
+ * and then converts the native MQTT wildcards into their regex equivalents:
+ * - `+` (single-level wildcard) becomes `[^/]+` (matches one or more characters except a forward slash)
+ * - `#` (multi-level wildcard) becomes an optional matching group `(?:/.*)?` to correctly handle parent levels.
+ *
+ * @param topicFilter - The MQTT topic filter string to convert (e.g., "home/+/temperature" or "clients/#").
+ * @returns A `RegExp` object configured to match topics corresponding to the filter.
+ *
+ * @example
+ * ```typescript
+ * const regex = topicFilterToRegExp("home/+/temperature");
+ * regex.test("home/livingroom/temperature"); // true
+ * regex.test("home/kitchen/lights");        // false
+ * ```
+ */
+export function topicFilterToRegExp(topicFilter: string): RegExp {
+  // RegExp.escape (ES2024+) safely escapes special characters, forcing punctuation into hex formats (\xHH)
+  const escaped = RegExp.escape(topicFilter);
+
+  const regexStr = escaped
+    .replace(/\\\+/g, "[^/]+") // Replace '+' wildcard globally
+    .replace(/(?:\\\/)?\\x23/g, "(?:/.*)?"); // Replace '#' and its optional preceding slash (\/) globally
+
+  return new RegExp(`^${regexStr}$`);
+}
+
+/**
+ * Parses a Topic filter for a "shared subscription" into the share name and the regular Topic Filter
+ *
+ * @param topicFilter - The MQTT topic filter string to parse (e.g. "$share/sharename/rest/of/topic/filter")).
+ * @returns an object that contains the regular topicFilter and he share name (if present)
+ */
+export function parseTopicFilter(topicFilter: string): {
+  topicFilter: string;
+  shareName: string;
+} {
+  if (topicFilter.startsWith("$share/")) {
+    const nextSlashIndex = topicFilter.indexOf("/", 7);
+    if (nextSlashIndex !== -1) {
+      return {
+        topicFilter: topicFilter.slice(nextSlashIndex + 1),
+        shareName: topicFilter.slice(7, nextSlashIndex),
+      };
+    }
+  }
+  return { topicFilter, shareName: "" };
+}
+
+/** the inverse of parseTopicFilter */
+export function joinTopicFilter(
+  topicFilter: string,
+  shareName: string,
+): string {
+  if (shareName !== "") {
+    return `$share/${shareName}/${topicFilter}`;
+  }
+  return topicFilter;
+}

package/utils/utils.ts

@@ -3,4 +3,7 @@
  * deserve their own dedicated files.
  */
 
+import { setTimeout as delay } from "node:timers/promises";
+export { delay };
+
 export const noop = () => {};

package/utils/validators.ts

@@ -0,0 +1,67 @@
+/**
+ * Checks for too many topic levels to reduce the risk of Denial of Service
+ *
+ * @param value - The string to validate.
+ * @returns `true` if the string contains more / signs than allowed`.
+ */
+export function invalidmaxTopicLevels(
+  value: string,
+  maxTopicLevels: number,
+): boolean {
+  let slashCount = 0;
+  for (const char of value) {
+    if (char === "/") {
+      slashCount++;
+      if (slashCount >= maxTopicLevels) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Checks for invalid characters in an MQTT topic name.
+ * It cannot contain wildcards (+, #)
+ *
+ * @param value - The topic name to validate.
+ * @returns `true` if the topic is invalid, otherwise `false`.
+ */
+export function invalidTopic(value: string): boolean {
+  return hasWildcards(value);
+}
+
+/**
+ * Checks for MQTT wildcards in a string.
+ *
+ * @param value - The topic name to validate.
+ * @returns `true` if the topic is invalid, otherwise `false`.
+ */
+export function hasWildcards(value: string): boolean {
+  // Native .includes() is significantly faster than regular expressions for basic character checks
+  return value.includes("+") || value.includes("#");
+}
+
+/**
+ * Checks for invalid characters and malformed wildcards in an MQTT topic filter.
+ *
+ * Wildcard rules according to the MQTT specification:
+ * - '+' must occupy an entire level (e.g., 'a/+/b' is valid, 'a+/b' is invalid)
+ * - '#' must only appear at the very end of the string (e.g., 'a/#' is valid, 'a/#/b' is invalid)
+ *
+ * @param value - The topic filter to validate.
+ * @returns `true` if the topic filter is invalid, otherwise `false`.
+ */
+export function invalidTopicFilter(value: string): boolean {
+  // Rule 1: A '#' wildcard must NEVER be followed by any other character
+  if (/#./.test(value)) {
+    return true;
+  }
+
+  // Rule 2: A '+' wildcard must be isolated by slashes (or string boundaries).
+  // Modern lookbehind (?<=) and lookahead (?=) make this highly readable.
+  const malformedPlus = /(?<=[^\/])\+|\+(?=[^\/])/.test(value);
+  if (malformedPlus) {
+    return true;
+  }
+
+  return false;
+}

package/web/webSocketStream.ts

@@ -0,0 +1,97 @@
+/**
+ * Utility functions for wrapping standard WebSockets into standard web streams.
+ */
+
+export interface WebSocketConnection<
+  T extends Uint8Array | string = Uint8Array | string,
+> {
+  readable: ReadableStream<T>;
+  writable: WritableStream<T>;
+  protocol: string;
+  extensions: string;
+}
+
+export interface WebSocketCloseInfo {
+  closeCode?: number;
+  reason?: string;
+}
+
+export interface WebSocketStreamOptions {
+  protocols?: string[];
+  signal?: AbortSignal;
+}
+
+/**
+ * [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) with [Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)
+ *
+ * @see https://web.dev/websocketstream/
+ */
+export class WebSocketStream<
+  T extends Uint8Array | string = Uint8Array | string,
+> {
+  readonly opened: Promise<WebSocketConnection<T>>;
+
+  readonly closed: Promise<WebSocketCloseInfo>;
+
+  readonly close: (closeInfo?: WebSocketCloseInfo) => void;
+
+  constructor(ws: WebSocket, options: WebSocketStreamOptions = {}) {
+    if (options.signal?.aborted) {
+      throw new DOMException("This operation was aborted", "AbortError");
+    }
+    const closeWithInfo = (
+      { closeCode: code, reason }: WebSocketCloseInfo = {},
+    ) => ws.close(code, reason);
+
+    this.opened = new Promise((resolve, reject) => {
+      ws.onopen = () => {
+        resolve({
+          readable: new ReadableStream<T>({
+            start(controller) {
+              ws.onmessage = ({ data }) => {
+                if (data instanceof ArrayBuffer) {
+                  controller.enqueue(new Uint8Array(data) as T);
+                } else {
+                  controller.enqueue(data as T);
+                }
+              };
+              ws.onerror = (e) => controller.error(e);
+            },
+            cancel: closeWithInfo,
+          }),
+          writable: new WritableStream<T>({
+            write(chunk) {
+              if (chunk instanceof Uint8Array) {
+                ws.send(chunk.buffer as ArrayBuffer);
+              } else {
+                ws.send(chunk);
+              }
+            },
+            abort() {
+              ws.close();
+            },
+            close: closeWithInfo,
+          }),
+          protocol: ws.protocol,
+          extensions: ws.extensions,
+        });
+        ws.removeEventListener("error", reject);
+      };
+      ws.addEventListener("error", reject);
+    });
+
+    this.closed = new Promise<WebSocketCloseInfo>((resolve, reject) => {
+      ws.onclose = ({ code, reason }) => {
+        resolve({ closeCode: code, reason });
+        ws.removeEventListener("error", reject);
+      };
+      ws.addEventListener("error", reject);
+    });
+
+    if (options.signal) {
+      options.signal.onabort = () => ws.close();
+    }
+
+    this.close = closeWithInfo;
+  }
+}

package/web/wrapWebSocket.ts

@@ -0,0 +1,52 @@
+/**
+ * Utility functions for wrapping WebSocketStream sockets into standard web streams.
+ */
+import { WebSocketStream } from "./webSocketStream.ts";
+import type { SockConn } from "../socket/socket.ts";
+import { logger } from "../utils/logger.ts";
+
+export type HostnamePort = {
+  hostname?: string;
+  port?: string | number;
+};
+
+/**
+ * Closes a WebSocketStream socket if it is not already closed
+ * @param sock - The WebSocketStream socket to close
+ */
+async function closer(stream: WebSocketStream) {
+  if (!await stream.closed) {
+    stream.close();
+  }
+}
+
+/**
+ * Wraps a WebSocketStream socket into a standard web streams-based socket connection
+ * @param ws - The WebSocket to wrap
+ * @returns A SockConn object
+ */
+export async function wrapWebSocket(
+  ws: WebSocket,
+  remoteAddr?: HostnamePort,
+): Promise<SockConn> {
+  ws.binaryType = "arraybuffer";
+  const wsstream = new WebSocketStream<Uint8Array>(ws);
+  logger.debug("created wsstream");
+  const stream = await wsstream.opened;
+  logger.debug("wsstream is opened");
+  const readable = stream.readable;
+  const writable = stream.writable;
+  const { hostname = "localhost", port = 0 } = remoteAddr || {};
+
+  const conn: SockConn = {
+    readable: readable as ReadableStream<Uint8Array>,
+    writable: writable as WritableStream<Uint8Array>,
+    close: () => closer(wsstream),
+    remoteAddr: {
+      hostname,
+      port: Number(port),
+      transport: "tcp",
+    },
+  };
+  return conn;
+}

package/web/wsClient.test.ts

@@ -0,0 +1,26 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { WsClient } from "./wsClient.ts";
+
+// most client testing is already done in wsServer.test.ts
+test("Web: Test createConn - unsupported protocol", async () => {
+  const client = new WsClient();
+
+  // Use an unsupported protocol like 'ftp://' to trigger the throw in createConn
+  const invalidParams = {
+    url: new URL("ftp://localhost:1883"),
+    numberOfRetries: 0,
+  };
+
+  // Assert that connect rejects with the specific "Unsupported protocol" error
+  await assert.rejects(
+    async () => {
+      await client.connect(invalidParams);
+    },
+    {
+      name: "Error",
+      message: "Unsupported protocol: ftp:",
+    },
+    "Should throw an error when an unsupported protocol is provided",
+  );
+});

package/web/wsClient.ts

@@ -0,0 +1,37 @@
+/*
+ * this is a WebSockets specific client
+ * it extends the platform agnostic Client class
+ *  @module
+ */
+
+import { Client } from "../client/client.ts";
+import { logger } from "../client/deps.ts";
+import type { SockConn } from "../client/deps.ts";
+import { wrapWebSocket } from "./wrapWebSocket.ts";
+
+/**
+ * WsClient extends the Client class to provide WebSocket based clients
+ * it is used by the MQTTclient to connect to the broker
+ * see the /examples folder for an example
+ */
+export class WsClient extends Client {
+  /** create a websocket and wrap it in a SockConn */
+  private async establishSocket(url: string): Promise<SockConn> {
+    const ws = new WebSocket(url);
+    const conn = await wrapWebSocket(ws);
+    return conn;
+  }
+
+  /** createConn provides support for both "ws:" and "wss:" URLs */
+  protected override createConn(): Promise<SockConn> {
+    const { protocol, hostname, port: portStr, pathname } = this.connectUrl;
+    const port = portStr ? Number(portStr) : (protocol === "wss:" ? 443 : 80);
+    const path = pathname || "/mqtt";
+
+    logger.debug({ hostname, port, path });
+    if (protocol === "ws:" || protocol === "wss:") {
+      return this.establishSocket(`${protocol}//${hostname}:${port}${path}`);
+    }
+    throw new Error(`Unsupported protocol: ${protocol}`);
+  }
+}

package/benchmarks/receiver.ts

@@ -1,35 +0,0 @@
-import { exit } from "node:process";
-import { importClientClass } from "./utils.ts";
-
-const { TcpClient } = await importClientClass();
-const client = new TcpClient();
-client.onError = (err) => {
-  console.log("client error", err);
-  exit(1);
-};
-
-await client.connect({
-  url: new URL("mqtt://localhost:1883"),
-});
-
-await client.subscribe({ subscriptions: [{ topicFilter: "test", qos: 0 }] });
-
-let counter = 0;
-const interval = 5000;
-
-function count() {
-  console.log("received/s", (counter / interval) * 1000);
-  counter = 0;
-}
-
-setInterval(count, interval);
-
-// // Consume using a callback
-// client.onPacket = async (packet) => {
-//   counter++;
-// };
-
-// Consume using an AsyncIterator
-for await (const _ of client.messages()) {
-  counter++;
-}

package/benchmarks/sender.ts

@@ -1,32 +0,0 @@
-import { exit } from "node:process";
-import { runAsap } from "../dev_utils/timers.ts";
-import { importClientClass } from "./utils.ts";
-
-const { TcpClient } = await importClientClass();
-const client = new TcpClient();
-client.onError = (err) => {
-  console.log("client error", err);
-  exit(1);
-};
-
-await client.connect({
-  url: new URL("mqtt://localhost:1883"),
-});
-
-const payload = new TextEncoder().encode("payload");
-let sent = 0;
-const interval = 5000;
-
-const loop = () => {
-  sent++;
-  client.publish({ topic: "test", payload })
-    .then(() => runAsap(loop));
-};
-
-function count() {
-  console.log("sent/s", (sent / interval) * 1000);
-  sent = 0;
-}
-
-setInterval(count, interval);
-loop();

package/benchmarks/utils.ts

@@ -1,9 +0,0 @@
-export async function importClientClass() {
-  // @ts-ignore: the Deno global variable is not defined in @types/node,
-  //             therefore we need to ignore this error because this file
-  //             is meant to be used in both environments.
-  const isDeno = typeof Deno !== "undefined";
-  return isDeno
-    ? (await import("../deno/tcpClient.ts"))
-    : (await import("../node/tcpClient.ts"));
-}