@seriousme/opifex 1.11.2 → 2.0.3

package/mqttPacket/validators.ts

@@ -1,35 +1,9 @@
-import type { Topic, TopicFilter } from "./types.ts";
-
-// deno-lint-ignore no-control-regex
-const invalidUTF8regEx = new RegExp(/\x00|\uFFFD/);
-// deno-lint-ignore no-control-regex
-const invalidTopicRegEx = new RegExp(/^$|\+|#|\x00|\uFFFD/);
-// deno-lint-ignore no-control-regex
-const invalidTopicFilterRegEx = new RegExp(/^$|#.|[^\/]\+|\+[^\/]|\x00|\uFFFD/);
-
 /**
- * check for invalid UTF-8 characters
- * @param value string to test
- * @returns true if the string contains invalid UTF-8 characters
+ * Checks for invalid UTF-8 characters or null bytes.
+ *
+ * @param value - The string to validate.
+ * @returns `true` if the string contains invalid UTF-8 sequences or a null byte, otherwise `false`.
  */
 export function invalidUTF8(value: string): boolean {
-  return invalidUTF8regEx.test(value);
-}
-
-/**
- * check for invalid topic characters
- * @param value
- * @returns true if the topic is invalid
- */
-export function invalidTopic(value: Topic): boolean {
-  return invalidTopicRegEx.test(value);
-}
-
-/**
- * check for invalid topic filter characters
- * @param value topic filter to test
- * @returns true if the topic filter is invalid
- */
-export function invalidTopicFilter(value: TopicFilter): boolean {
-  return invalidTopicFilterRegEx.test(value);
+  return value.includes("\x00") || !value.isWellFormed();
 }

package/node/socket-node-stream.test.ts

@@ -0,0 +1,322 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { PassThrough } from "node:stream";
+import { Conn, type SockConn } from "./socket-node-stream.ts";
+
+// Helper to create a mock SockConn using a PassThrough duplex stream
+function createMockConn(): {
+  conn: Conn;
+  stream: PassThrough;
+  closeCalled: { count: number };
+} {
+  const stream = new PassThrough();
+  const closeCalled = { count: 0 };
+
+  const sockConn: SockConn = {
+    stream,
+    close: () => {
+      closeCalled.count++;
+    },
+    remoteAddr: {
+      transport: "tcp",
+      hostname: "127.0.0.1",
+      port: 1883,
+    },
+  };
+
+  const conn = new Conn(sockConn);
+  return { conn, stream, closeCalled };
+}
+
+test("Conn.write - successfully writes data", async () => {
+  const { conn, stream } = createMockConn();
+  const data = new Uint8Array([0x01, 0x02, 0x03]);
+
+  const bytesWritten = await conn.write(data);
+  assert.equal(bytesWritten, data.length, "Number of written bytes matches");
+
+  const chunk = stream.read();
+  assert.deepStrictEqual(
+    new Uint8Array(chunk),
+    data,
+    "The stream received the correct data",
+  );
+
+  conn.close();
+});
+
+test("Conn.write - respects backpressure and waits for drain event", async () => {
+  const { conn, stream } = createMockConn();
+  const data = new Uint8Array([0x01, 0x02, 0x03]);
+
+  // Force stream.write to return false to simulate a full internal buffer (backpressure)
+  stream.write = () => false;
+
+  let writeResolved = false;
+  const writePromise = conn.write(data).then((bytes) => {
+    writeResolved = true;
+    return bytes;
+  });
+
+  // Yield execution shortly to ensure the promise hasn't resolved prematurely
+  await new Promise((resolve) => setImmediate(resolve));
+  assert.equal(
+    writeResolved,
+    false,
+    "Write promise should pend while backpressure is active",
+  );
+
+  // Emit the drain event to signal the buffer has cleared
+  stream.emit("drain");
+
+  const bytesWritten = await writePromise;
+  assert.equal(bytesWritten, data.length, "Resolves after drain event fires");
+  assert.equal(writeResolved, true);
+
+  conn.close();
+});
+
+test("Conn.read - reads exact number of bytes", async () => {
+  const { conn, stream } = createMockConn();
+  const data = new Uint8Array([10, 20, 30, 40, 50]);
+
+  stream.write(data);
+
+  const result = await conn.read(3);
+  assert.deepStrictEqual(
+    result,
+    new Uint8Array([10, 20, 30]),
+    "First 3 bytes match",
+  );
+
+  const restResult = await conn.read(2);
+  assert.deepStrictEqual(
+    restResult,
+    new Uint8Array([40, 50]),
+    "Remaining bytes match via the leftover buffer",
+  );
+
+  conn.close();
+});
+
+test("Conn.read - waits for async data (readable event)", async () => {
+  const { conn, stream } = createMockConn();
+
+  const readPromise = conn.read(2);
+
+  // Simulate network latency using setImmediate or setTimeout
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  stream.write(new Uint8Array([0xAA, 0xBB]));
+
+  const result = await readPromise;
+  assert.deepStrictEqual(
+    result,
+    new Uint8Array([0xAA, 0xBB]),
+    "Data correctly received after async wait",
+  );
+
+  conn.close();
+});
+
+test("Conn.close - gracefully closes the connection and streams", async () => {
+  const { conn, stream, closeCalled } = createMockConn();
+
+  assert.equal(closeCalled.count, 0, "Closer has not been called yet");
+
+  conn.close();
+
+  assert.equal(closeCalled.count, 1, "Closer is called exactly once");
+  assert.equal(stream.destroyed, true, "The underlying stream is destroyed");
+
+  await assert.rejects(
+    conn.write(new Uint8Array([1])),
+    /Stream is closed or not writable/,
+    "Writing to a closed connection throws an error",
+  );
+
+  const readResult = await conn.read(1);
+  assert.equal(
+    readResult,
+    null,
+    "Reading from a closed connection returns null",
+  );
+});
+
+test("Conn.read - length less than 0 returns null", async () => {
+  const { conn } = createMockConn();
+
+  const result = await conn.read(-5);
+  assert.equal(result, null, "Reading with a negative length returns null");
+
+  conn.close();
+});
+
+test("Conn.read - length equal to 0 returns empty Uint8Array", async () => {
+  const { conn } = createMockConn();
+
+  const result = await conn.read(0);
+  assert.deepStrictEqual(
+    result,
+    new Uint8Array(0),
+    "Reading 0 bytes returns an empty Uint8Array",
+  );
+
+  conn.close();
+});
+
+test("Conn.read - stream errors while waiting for data (returns null)", async () => {
+  const { conn, stream } = createMockConn();
+
+  // Prevent Node.js from crashing due to an unhandled stream error during test execution
+  stream.on("error", () => {});
+
+  const readPromise = conn.read(5);
+
+  // Emit error event to invoke internal error tracking state
+  stream.emit("error", new Error("Network failure"));
+
+  const result = await readPromise;
+  assert.equal(
+    result,
+    null,
+    "Returns null when the stream errors out during an active read",
+  );
+
+  conn.close();
+});
+
+test("Conn.read - chunk is larger than requested (populates leftover)", async () => {
+  const { conn, stream } = createMockConn();
+  const largeChunk = new Uint8Array([1, 2, 3, 4, 5]);
+
+  stream.write(largeChunk);
+
+  const result1 = await conn.read(2);
+  assert.deepStrictEqual(
+    result1,
+    new Uint8Array([1, 2]),
+    "Returns the exact requested chunk size",
+  );
+
+  const result2 = await conn.read(2);
+  assert.deepStrictEqual(
+    result2,
+    new Uint8Array([3, 4]),
+    "Returns the next bytes from the leftover buffer",
+  );
+
+  const result3 = await conn.read(1);
+  assert.deepStrictEqual(
+    result3,
+    new Uint8Array([5]),
+    "Returns the last remaining byte from leftover",
+  );
+
+  conn.close();
+});
+
+test("Conn.read - partial leftover is not enough (combines leftover and new stream chunk)", async () => {
+  const { conn, stream } = createMockConn();
+
+  // 1. Write 3 bytes and read 2 (leaving 1 byte [0x03] in leftover)
+  stream.write(new Uint8Array([0x01, 0x02, 0x03]));
+  await conn.read(2);
+
+  // 2. Write new data to the stream
+  stream.write(new Uint8Array([0x04, 0x05]));
+
+  // 3. Request 3 bytes (needs 1 from leftover + 2 from stream)
+  const result = await conn.read(3);
+  assert.deepStrictEqual(
+    result,
+    new Uint8Array([0x03, 0x04, 0x05]),
+    "Combines leftover data with newly arrived stream data",
+  );
+
+  conn.close();
+});
+
+test("Conn.write - rejects immediately if stream.writable is false", async () => {
+  const { conn, stream } = createMockConn();
+
+  Object.defineProperty(stream, "writable", { value: false });
+
+  await assert.rejects(
+    conn.write(new Uint8Array([1, 2, 3])),
+    /Stream is closed or not writable/,
+    "Rejects immediately when stream.writable is false",
+  );
+
+  conn.close();
+});
+
+test("Conn.read - fulfilled entirely from leftover buffer (skips while loop)", async () => {
+  const { conn, stream } = createMockConn();
+  const data = new Uint8Array([10, 20, 30, 40, 50]);
+
+  // 1. Populate the leftover buffer by reading less than what was written
+  stream.write(data);
+  await conn.read(2); // Leaves [30, 40, 50] in leftover
+
+  // 2. Request an amount that can be fully satisfied by the leftover buffer
+  const result = await conn.read(2);
+  assert.deepStrictEqual(
+    result,
+    new Uint8Array([30, 40]),
+    "Successfully fulfilled entirely from the leftover buffer",
+  );
+
+  // 3. Verify the remaining byte is still preserved
+  const finalResult = await conn.read(1);
+  assert.deepStrictEqual(
+    finalResult,
+    new Uint8Array([50]),
+    "The remaining byte in leftover is still accessible",
+  );
+
+  conn.close();
+});
+
+test("Conn - handles unexpected stream close event from underlying resource", () => {
+  const { conn, stream } = createMockConn();
+
+  // Initially, the connection should not be marked as closed
+  assert.equal(conn["closed"], false, "Connection is open initially");
+
+  // Simulate the underlying socket/stream closing unexpectedly from the remote side
+  stream.emit("close");
+
+  // Verify that the permanent 'close' listener was triggered and updated the internal state
+  assert.equal(
+    conn["closed"],
+    true,
+    "Connection internally updates to closed when stream emits close",
+  );
+
+  // Clean up to ensure resources are disposed
+  conn.close();
+});
+
+test("Conn.write - rejects the promise if stream.write invokes the callback with an error", async () => {
+  const { conn, stream } = createMockConn();
+  const data = new Uint8Array([1, 2, 3]);
+
+  // Simulate a write error by overriding stream.write
+  // It forces the callback to be invoked with an Error object
+  stream.write = (_chunk, callback) => {
+    if (typeof callback === "function") {
+      // Execute the callback with an error asynchronously, mimicking Node.js behavior
+      setImmediate(() => callback(new Error("Write pipeline failure")));
+    }
+    return false;
+  };
+
+  // Verify that the conn.write Promise rejects with the exact error
+  await assert.rejects(
+    conn.write(data),
+    /Write pipeline failure/,
+    "The write promise should reject when the stream callback receives an error",
+  );
+
+  conn.close();
+});

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

@@ -65,9 +65,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 +83,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
+  // overload createConn from 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);