@seriousme/opifex 1.11.3 → 2.1.0

package/node/socket-node-stream.ts

@@ -0,0 +1,174 @@
+import type { Duplex } from "node:stream";
+
+export type SockAddr = NetAddr | UnixAddr | VsockAddr;
+export interface NetAddr {
+  transport: "tcp" | "udp";
+  hostname: string;
+  port: number;
+}
+export interface UnixAddr {
+  transport: "unix" | "unixpacket";
+  path: string;
+}
+export interface VsockAddr {
+  transport: "vsock";
+  cid: number;
+  port: number;
+}
+
+export type SockConn = {
+  stream: Duplex;
+  close: () => void;
+  localAddr?: SockAddr;
+  remoteAddr?: SockAddr;
+};
+
+export class Conn {
+  private stream: Duplex;
+  private closed: boolean;
+  private closer: () => void;
+  public remoteAddr: SockAddr | undefined;
+  private leftover: Uint8Array = new Uint8Array(0);
+
+  // Store bound event listeners so we can cleanly remove them later
+  private onStreamClose = () => {
+    this.closed = true;
+  };
+  private onStreamError = () => {
+    this.closed = true;
+  };
+
+  constructor(sockConn: SockConn) {
+    this.stream = sockConn.stream;
+    this.closed = false;
+    this.closer = sockConn.close;
+    this.remoteAddr = sockConn.remoteAddr;
+
+    // Attach listeners to update internal state on stream termination
+    this.stream.on("close", this.onStreamClose);
+    this.stream.on("error", this.onStreamError);
+  }
+
+  async read(length: number): Promise<Uint8Array | null> {
+    if (this.closed || length < 0) {
+      return null;
+    }
+
+    if (length === 0) {
+      return new Uint8Array(0);
+    }
+
+    const result = new Uint8Array(length);
+    let bytesAccumulated = 0;
+
+    // 1. Process leftover data from the previous read operation
+    if (this.leftover.byteLength > 0) {
+      const take = Math.min(this.leftover.byteLength, length);
+      result.set(this.leftover.subarray(0, take), bytesAccumulated);
+      bytesAccumulated += take;
+      this.leftover = this.leftover.subarray(take);
+    }
+
+    // 2. Loop until the requested number of bytes is accumulated
+    while (bytesAccumulated < length) {
+      if (this.closed || !this.stream.readable) {
+        break;
+      }
+
+      const chunk = this.stream.read();
+      if (chunk === null) {
+        await new Promise<void>((resolve) => {
+          const cleanup = () => {
+            this.stream.off("readable", onEvent);
+            this.stream.off("end", onEvent);
+            this.stream.off("error", onEvent);
+            this.stream.off("close", onEvent);
+          };
+          const onEvent = () => {
+            cleanup();
+            resolve();
+          };
+
+          this.stream.on("readable", onEvent);
+          this.stream.on("end", onEvent);
+          this.stream.on("error", onEvent);
+          this.stream.on("close", onEvent);
+        });
+
+        continue;
+      }
+
+      // 3. Process the retrieved chunk
+      const chunkLength = chunk.byteLength;
+      const needed = length - bytesAccumulated;
+
+      if (chunkLength <= needed) {
+        result.set(chunk, bytesAccumulated);
+        bytesAccumulated += chunkLength;
+      } else {
+        result.set(chunk.subarray(0, needed), bytesAccumulated);
+        bytesAccumulated += needed;
+        this.leftover = chunk.subarray(needed);
+      }
+    }
+
+    if (bytesAccumulated < length) {
+      return null;
+    }
+
+    return result;
+  }
+
+  write(data: Uint8Array): Promise<number> {
+    if (this.closed || !this.stream.writable) {
+      return Promise.reject(new Error("Stream is closed or not writable"));
+    }
+
+    return new Promise((resolve, reject) => {
+      // 1. Fire the write command and catch any immediate/async errors via the callback
+      const canWriteMore = this.stream.write(data, (err) => {
+        if (err) {
+          reject(err);
+        }
+      });
+
+      // 2. Determine when to resolve based on the return value of write()
+      if (canWriteMore) {
+        // If the buffer is not full, we can resolve immediately
+        resolve(data.length);
+      } else {
+        // If backpressure is triggered, we must wait for the 'drain' event
+        this.stream.once("drain", () => {
+          resolve(data.length);
+        });
+      }
+    });
+  }
+
+  close() {
+    if (!this.closed) {
+      this.closed = true;
+
+      // Clean up permanent event listeners to prevent memory leaks
+      this.stream.off("close", this.onStreamClose);
+      this.stream.off("error", this.onStreamError);
+
+      // Safely destroy the stream first, then trigger the closer callback
+      try {
+        this.stream.destroy();
+        // deno-coverage-ignore
+      } catch (_) {
+        // Suppress stream destruction errors
+        // deno-coverage-ignore
+      }
+
+      try {
+        this.closer();
+        // deno-coverage-ignore
+      } catch (_) {
+        // Prevent closer failures from crashing the thread
+        // deno-coverage-ignore
+      }
+    }
+  }
+}

package/node/tcpClient.test.ts

@@ -0,0 +1,70 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { getFileData, TcpClient } from "./tcpClient.ts";
+
+// most client testing is already done in tcpServer.test.ts
+
+test("Test getFileData - valid file, empty file and undefined", async () => {
+  // Create a unique temporary directory using native NodeJS path/fs utilities
+  const tempDir = await mkdtemp(join(tmpdir(), "mqtt-client-test-"));
+
+  const validFilePath = join(tempDir, "valid.txt");
+  const emptyFilePath = join(tempDir, "empty.txt");
+  const testContent = "Hello MQTT World!";
+
+  try {
+    // 1. Test with a valid file containing data
+    await writeFile(validFilePath, testContent, "utf-8");
+    const result = await getFileData(validFilePath);
+    assert.strictEqual(
+      result,
+      testContent,
+      "Should return the correct content of the file",
+    );
+
+    // 2. Test with an empty file
+    await writeFile(emptyFilePath, "", "utf-8");
+    const emptyResult = await getFileData(emptyFilePath);
+    assert.strictEqual(
+      emptyResult,
+      undefined,
+      "Should return undefined if the file is empty",
+    );
+  } finally {
+    // Clean up the temporary directory and all its contents
+    await rm(tempDir, { recursive: true, force: true });
+  }
+
+  // 3. Test with undefined filename
+  const undefinedResult = await getFileData(undefined);
+  assert.strictEqual(
+    undefinedResult,
+    undefined,
+    "Should return undefined immediately if filename is undefined",
+  );
+});
+
+test("Test createConn - unsupported protocol", async () => {
+  const client = new TcpClient();
+
+  // 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/node/tcpClient.ts

@@ -12,7 +12,8 @@ import type { SockConn } from "../socket/socket.ts";
 import { wrapNodeSocket } from "./wrapNodeSocket.ts";
 
 /**
- * @function getFileData
+ * Fetches data from a file and returns it as a string
+ *
  * @param filename
  * @returns Promise
  *
@@ -20,7 +21,9 @@ import { wrapNodeSocket } from "./wrapNodeSocket.ts";
  * @example
  * const data = await getFileData("data.txt");
  */
-export async function getFileData(filename: string | undefined) {
+export async function getFileData(
+  filename: string | undefined,
+): Promise<string | undefined> {
   if (!filename) {
     return;
   }
@@ -31,13 +34,16 @@ export async function getFileData(filename: string | undefined) {
   return data;
 }
 
-/*
- * TCPclient extends the Client class to provide TCP based clients
+/**
+ * TcpClient extends the Client class to provide TCP based clients
  * it is used by the MQTTclient to connect to the broker
  * see mqtt.ts in the /bin folder as an example
  */
-
 export class TcpClient extends Client {
+  /** Connect using MQTT over TCP
+   * @param hostname the name of the host to connect to
+   * @param port the port number
+   */
   protected connectMQTT(hostname: string, port = 1883): Promise<SockConn> {
     logger.debug({ hostname, port });
     return new Promise((resolve, reject) => {
@@ -55,6 +61,15 @@ export class TcpClient extends Client {
     });
   }
 
+  /**
+   * Connect using MQTT over TLS
+   * @param hostname the name of the host to connect to
+   * @param port the port number
+   * @param caCerts the CA certificates to trust
+   * @param cert the clients certificate
+   * @param key the clients private key
+   * @returns a SockConn object
+   */
   protected connectMQTTS(
     hostname: string,
     port = 8883,
@@ -65,9 +80,10 @@ export class TcpClient extends Client {
     const opts = {
       host: hostname,
       port,
-      secureContext: (ca || key || cert)
-        ? tls.createSecureContext({ ca, cert, key })
-        : undefined,
+      ca,
+      key,
+      cert,
+      minVersion: "TLSv1.3" as const,
     };
     logger.debug({ hostname, port, ca, cert });
     return new Promise((resolve, reject) => {
@@ -82,16 +98,16 @@ export class TcpClient extends Client {
     });
   }
 
-  protected override createConn(
-    protocol: string,
-    hostname: string,
-    port?: number,
-    caCerts?: string[],
-  ): Promise<SockConn> {
-    // if you need to support alternative connection types just
-    // overload this method in your subclass
+  /** createConn is used by the base client class */
+  protected override createConn(): Promise<SockConn> {
+    const { protocol, hostname, port: portStr } = this.connectUrl;
+    const port = Number(portStr);
+    const caCerts = this.caCerts;
+    const cert = this.cert;
+    const key = this.key;
+
     if (protocol === "mqtts:") {
-      return this.connectMQTTS(hostname, port, caCerts);
+      return this.connectMQTTS(hostname, port, caCerts, cert, key);
     }
     if (protocol === "mqtt:") {
       return this.connectMQTT(hostname, port);

package/node/tcpServer.test.ts

@@ -3,14 +3,12 @@ import assert from "node:assert/strict";
 import { TcpClient } from "./tcpClient.ts";
 import { TcpServer } from "./tcpServer.ts";
 import { logger, LogLevel } from "../utils/mod.ts";
-import type { PublishPacket, QoS } from "../mqttPacket/mod.ts";
+import { delay } from "../dev_utils/mod.ts";
+import type { ProtocolLevel, PublishPacket, QoS } from "../mqttPacket/mod.ts";
 
 logger.level(LogLevel.info);
-export function sleep(ms: number): Promise<unknown> {
-  return new Promise((r) => setTimeout(r, ms));
-}
 
-test("Test pubSub using client and server", async function () {
+test("Test pubSub using client and server", async () => {
   const server = new TcpServer({ port: 0 }, {});
   server.start();
 
@@ -52,17 +50,17 @@ test("Test pubSub using client and server", async function () {
   });
 
   // the IIFE ensures message reception runs in parallel
-  logger.verbose(`Start receiving`);
+  logger.verbose("Start receiving");
   const received: PublishPacket[] = [];
-  (async function () {
+  (async () => {
     for await (const item of client.messages()) {
-      logger.verbose(`Receiving: ${item.topic} -- ${item.qos}`);
+      logger.verbose("Receiving:", item.topic, "--", item.qos);
       received.push(item);
     }
   })();
   // end of IIFE
   for (const item of publishSet) {
-    logger.verbose(`Publishing: ${item.topic} -- ${item.qos}`);
+    logger.verbose("Publishing:", item.topic, "--", item.qos);
     await client.publish({
       topic: item.topic,
       qos: item.qos,
@@ -70,24 +68,24 @@ test("Test pubSub using client and server", async function () {
     });
   }
 
-  await sleep(100);
-  logger.verbose(`Disconnect client`);
+  await delay(100);
+  logger.verbose("Disconnect client");
   await client.disconnect();
 
-  logger.verbose(`Check completeness`);
+  logger.verbose("Check completeness");
   for (const item of publishSet) {
     const found = received.find((f) =>
       f.topic == item.topic && f.qos === item.qos
     );
-    logger.verbose(`Found: ${item.topic} -- ${item.qos}`);
+    logger.verbose("Found:", item.topic, "--", item.qos);
     assert(found, `${item.topic} -- ${item.qos}`);
   }
 
-  logger.verbose(`Stop server`);
+  logger.verbose("Stop server");
   server.stop();
 });
 
-test("Test subscription persistence after reconnect", async function () {
+test("Test subscription persistence after reconnect", async () => {
   // Start server
   const server = new TcpServer({ port: 0 }, {});
   server.start();
@@ -95,8 +93,14 @@ test("Test subscription persistence after reconnect", async function () {
   const params = {
     url: new URL(`mqtt://${server.address}:${server.port}`),
     numberOfRetries: 0,
+    options: {
+      protocolLevel: 4 as ProtocolLevel,
+      clean: false,
+    },
   };
 
+  logger.verbose("client parameters: ", params);
+
   const client = new TcpClient();
   const testTopic = "test/topic";
   const received: PublishPacket[] = [];
@@ -111,7 +115,7 @@ test("Test subscription persistence after reconnect", async function () {
   });
 
   // Start receiving messages
-  (async function () {
+  (async () => {
     for await (const item of client.messages()) {
       received.push(item);
     }
@@ -119,11 +123,11 @@ test("Test subscription persistence after reconnect", async function () {
 
   // Disconnect client
   await client.disconnect();
-  await sleep(100);
+  await delay(100);
 
   // Reconnect client
   await client.connect(params);
-  await sleep(100);
+  await delay(100);
 
   // Publish test message
   await client.publish({
@@ -132,8 +136,8 @@ test("Test subscription persistence after reconnect", async function () {
     payload: new Uint8Array([0x01]),
   });
 
-  await sleep(100);
-  logger.verbose(`Disconnect client`);
+  await delay(100);
+  logger.verbose("Disconnect client");
   await client.disconnect();
 
   // Verify message was received

package/node/tcpServer.ts

@@ -14,19 +14,26 @@ type ServerOptions = {
   port?: number;
 };
 
-/*
- * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+/**
+ * TCP server that wraps a MqttServer, see the /examples folder
  */
 export class TcpServer {
   private mqttServer: MqttServer;
   private server?: Server;
   private serverOptions;
+
+  /**
+   * Create a new TCP server
+   */
   constructor(serverOptions: ServerOptions, mqttOptions: MqttServerOptions) {
     this.mqttServer = new MqttServer(mqttOptions);
     this.serverOptions = serverOptions;
   }
 
-  async start() {
+  /**
+   * Start listening
+   */
+  async start(): Promise<void> {
     this.server = createServer((sock) =>
       this.mqttServer.serve(wrapNodeSocket(sock))
     );
@@ -39,22 +46,37 @@ export class TcpServer {
     await isListening;
     return;
   }
-  stop() {
+
+  /**
+   * Stop listening
+   */
+  stop(): void {
+    this.mqttServer.close();
     this.server?.close();
   }
 
-  get port() {
+  /**
+   * The port number the server is listening on
+   */
+  get port(): number | undefined {
     const address = this.server?.address();
+    // deno-coverage-ignore-start
     if (typeof address === "object" && address !== null) {
       return address?.port;
     }
     return this.serverOptions?.port;
+    // deno-coverage-ignore-stop
   }
 
-  get address() {
+  /**
+   * The address the server is listening on
+   */
+  get address(): string | undefined {
     const addressResult = this.server?.address();
+    // deno-coverage-ignore-start
     if (typeof addressResult === "object") {
       const address = addressResult?.address;
+
       if (address === "::") {
         return "localhost";
       }
@@ -65,4 +87,5 @@ export class TcpServer {
     }
     return addressResult;
   }
+  // deno-coverage-ignore-stop
 }

package/node/tlsServer.test.ts

@@ -0,0 +1,94 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { TcpClient } from "./tcpClient.ts";
+import { TlsServer } from "./tlsServer.ts";
+import { logger, LogLevel } from "../utils/mod.ts";
+import type { PublishPacket, QoS } from "../mqttPacket/mod.ts";
+import { delay, generateLocalhostCerts } from "../dev_utils/mod.ts";
+
+logger.level(LogLevel.info);
+
+const { key, cert, caCert } = generateLocalhostCerts();
+
+test("Test pubSub using client and server", async () => {
+  const server = new TlsServer({ port: 0, key, cert }, {});
+  server.start();
+
+  assert.deepStrictEqual(
+    server.port !== undefined,
+    true,
+    "server runs a a random port",
+  );
+  logger.verbose("server running on: ", {
+    port: server.port,
+    address: server.address,
+  });
+
+  const params = {
+    url: new URL(`mqtts://${server.address}:${server.port}`),
+    numberOfRetries: 0,
+    caCerts: [caCert],
+  };
+
+  logger.verbose("client parameters: ", params);
+
+  const client = new TcpClient();
+
+  await client.connect(params);
+  assert(true, "Client connected to server");
+
+  const publishSet: { topic: string; qos: QoS }[] = [
+    { topic: "t0@q0", qos: 0 },
+    { topic: "t1@q0", qos: 0 },
+    { topic: "t2@q0", qos: 0 },
+    { topic: "t0@q1", qos: 1 },
+    { topic: "t1@q1", qos: 1 },
+    { topic: "t2@q1", qos: 1 },
+    { topic: "t0@q2", qos: 2 },
+    { topic: "t1@q2", qos: 2 },
+    { topic: "t2@q2", qos: 2 },
+  ];
+
+  const subscriptions = publishSet.map((item) => ({
+    topicFilter: item.topic,
+    qos: item.qos,
+  }));
+  await client.subscribe({
+    subscriptions,
+  });
+
+  // the IIFE ensures message reception runs in parallel
+  logger.verbose("Start receiving");
+  const received: PublishPacket[] = [];
+  (async () => {
+    for await (const item of client.messages()) {
+      logger.verbose("Receiving:", item.topic, "--", item.qos);
+      received.push(item);
+    }
+  })();
+  // end of IIFE
+  for (const item of publishSet) {
+    logger.verbose("Publishing:", item.topic, "--", item.qos);
+    await client.publish({
+      topic: item.topic,
+      qos: item.qos,
+      payload: new Uint8Array([0x01]),
+    });
+  }
+
+  await delay(100);
+  logger.verbose("Disconnect client");
+  await client.disconnect();
+
+  logger.verbose("Check completeness");
+  for (const item of publishSet) {
+    const found = received.find((f) =>
+      f.topic == item.topic && f.qos === item.qos
+    );
+    logger.verbose("Found:", item.topic, "--", item.qos);
+    assert(found, `${item.topic} -- ${item.qos}`);
+  }
+
+  logger.verbose("Stop server");
+  server.stop();
+});