@seriousme/opifex 1.6.1 → 1.6.3

package/client/handlers/handlePubrel.ts

@@ -1,12 +1,22 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PubrelPacket } from "../deps.ts";
 
-// A PUBREL Packet is the response to a PUBREC Packet.
-// It is the third packet of the QoS 2 protocol exchange.
-
-// Method A, Initiate onward delivery of the Application Message then discard message
-// Send PUBCOMP <Packet Identifier>
-
+/**
+ * Handles a PUBREL packet in the MQTT QoS 2 flow
+ * It is the third packet of the QoS 2 protocol exchange
+ * and a response to the PUBREC packet
+ *
+ * It uses Method A from the MQTT specification
+ * @param ctx - The MQTT client context
+ * @param packet - The PUBREL packet received
+ * @description
+ * When a PUBREL packet is received:
+ * 1. If there is a matching pending incoming message:
+ *    - Delivers the stored message to the application
+ *    - Removes the message from pending incoming store
+ *    - Sends PUBCOMP packet as acknowledgement
+ * 2. If no matching message found, silently ignores
+ */
 export async function handlePubrel(
   ctx: Context,
   packet: PubrelPacket,

package/client/handlers/handleSuback.ts

@@ -1,12 +1,15 @@
 import type { Context } from "../context.ts";
 import type { SubackPacket } from "../deps.ts";
 
-// A SUBACK Packet is sent by the Server to the Client to confirm receipt
-// and processing of a SUBSCRIBE Packet.
-
-// A SUBACK Packet contains a list of return codes, that specify the maximum QoS level
-// that was granted in each Subscription that was requested by the SUBSCRIBE.
-
+/**
+ * Handles SUBACK packets received from the server
+ * @param ctx - The MQTT client context
+ * @param packet - The SUBACK packet containing subscription confirmations
+ * @description
+ * - Processes SUBACK packets sent by server to confirm SUBSCRIBE requests
+ * - Removes the packet ID from pending outgoing messages
+ * - Notifies the client about granted QoS levels for each subscription
+ */
 export function handleSuback(ctx: Context, packet: SubackPacket): void {
   const id = packet.id;
   ctx.store.pendingOutgoing.delete(id);

package/client/handlers/handleUnsuback.ts

@@ -1,9 +1,16 @@
 import type { Context } from "../context.ts";
 import type { UnsubackPacket } from "../deps.ts";
 
-// The UNSUBACK Packet is sent by the Server to the Client to confirm receipt
-// of an UNSUBSCRIBE Packet.
-
+/**
+ * Handles the UNSUBACK packet received from the server
+ * @param ctx - The MQTT client context
+ * @param packet - The UNSUBACK packet received from the server
+ * @description
+ * The UNSUBACK Packet is sent by the Server to the Client to confirm receipt of
+ * an UNSUBSCRIBE Packet.
+ * When received, it removes the pending outgoing request and completes the corresponding
+ * unsubscribe operation.
+ */
 export function handleUnsuback(ctx: Context, packet: UnsubackPacket): void {
   const id = packet.id;
   ctx.store.pendingOutgoing.delete(id);

package/client/store/memoryStore.ts

@@ -1,3 +1,7 @@
+/**
+ * @module memoryStore
+ */
+
 import { assert, type PacketId } from "./deps.ts";
 
 import {
@@ -10,13 +14,25 @@ import {
   type PendingOutgoingPackets,
 } from "./store.ts";
 
+/**
+ * In-memory implementation of the IStore interface for managing MQTT packet storage
+ */
 export class MemoryStore implements IStore {
+  /** Current packet ID counter */
   private packetId: PacketId;
 
+  /** Map of pending incoming packets */
   pendingIncoming: PacketStore<pendingIncoming>;
+
+  /** Map of pending outgoing packets */
   pendingOutgoing: PacketStore<PendingOutgoing>;
+
+  /** Map of pending acknowledgment outgoing packets */
   pendingAckOutgoing: PacketStore<PendingAckOutgoing>;
 
+  /**
+   * Creates a new MemoryStore instance
+   */
   constructor() {
     this.packetId = 0;
     this.pendingIncoming = new Map();
@@ -24,6 +40,11 @@ export class MemoryStore implements IStore {
     this.pendingAckOutgoing = new Map();
   }
 
+  /**
+   * Generates the next available packet ID
+   * @returns {PacketId} The next available packet ID
+   * @throws {Error} If no unused packet ID is available
+   */
   nextId(): PacketId {
     const currentId = this.packetId;
     do {
@@ -41,6 +62,10 @@ export class MemoryStore implements IStore {
     return this.packetId;
   }
 
+  /**
+   * Asynchronously yields all pending outgoing packets
+   * @yields {PendingOutgoingPackets} Pending outgoing packets
+   */
   async *pendingOutgoingPackets(): AsyncGenerator<
     PendingOutgoingPackets,
     void,

package/client/store/store.ts

@@ -1,3 +1,6 @@
+/**
+ * @module MQTT Store Types
+ */
 import type {
   PacketId,
   PublishPacket,
@@ -5,22 +8,58 @@ import type {
   SubscribePacket,
   UnsubscribePacket,
 } from "./deps.ts";
+
+/**
+ * Maximum value for MQTT packet IDs (65535)
+ */
 export const maxPacketId = 0xffff;
 
+/**
+ * Generic type for storing MQTT packets by their packet ID
+ * @template T The packet type to store
+ */
 export type PacketStore<T> = Map<PacketId, T>;
 
+/**
+ * Type for incoming PUBLISH packets that are pending processing
+ */
 export type pendingIncoming = PublishPacket;
+
+/**
+ * Type for outgoing packets (PUBLISH, SUBSCRIBE, UNSUBSCRIBE) that are pending sending
+ */
 export type PendingOutgoing =
   | PublishPacket
   | SubscribePacket
   | UnsubscribePacket;
+
+/**
+ * Type for outgoing PUBREL packets that are pending acknowledgement
+ */
 export type PendingAckOutgoing = PubrelPacket;
+
+/**
+ * Union type of all pending outgoing packet types
+ */
 export type PendingOutgoingPackets = PendingAckOutgoing | PendingOutgoing;
 
+/**
+ * Interface defining the storage requirements for MQTT packet state management
+ */
 export interface IStore {
+  /** Store for incoming packets pending processing */
   pendingIncoming: PacketStore<pendingIncoming>;
+
+  /** Store for outgoing packets pending sending */
   pendingOutgoing: PacketStore<PendingOutgoing>;
+
+  /** Store for outgoing packets pending acknowledgement */
   pendingAckOutgoing: PacketStore<PendingAckOutgoing>;
+
+  /**
+   * Generator that yields pending outgoing packets
+   * @returns AsyncGenerator that yields PendingOutgoing or PubrelPacket packets
+   */
   pendingOutgoingPackets(): AsyncGenerator<
     PendingOutgoing | PubrelPacket,
     void,

package/deno/tcpClient.ts

@@ -1,9 +1,21 @@
-// This a Deno specific implementation of TCP client sockets
-// it extends the platform agnostic Client class
+/**
+ * This a Deno specific implementation of TCP client sockets
+ * 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";
 
+/**
+ * @function getFileData
+ * @param filename
+ * @returns Promise
+ *
+ * Fetches data from a file and returns it as a string
+ * @example
+ * const data = await getFileData("data.txt");
+ */
 export async function getFileData(
   filename: string | undefined,
 ): Promise<string | undefined> {
@@ -17,6 +29,11 @@ export async function getFileData(
   return data;
 }
 
+/*
+ * 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 {
   protected async connectMQTT(
     hostname: string,

package/deno/tcpServer.test.ts

@@ -1,14 +1,149 @@
-import assert from "node:assert/strict";
 import { test } from "node:test";
+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";
 
-test("Deno testServer", () => {
+logger.level(LogLevel.info);
+export function sleep(ms: number): Promise<unknown> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+test("Deno Test pubSub using client and server", async function () {
   const server = new TcpServer({ port: 0 }, {});
   server.start();
+
   assert.deepStrictEqual(
     server.port !== undefined,
     true,
     "server runs a a random port",
   );
+  logger.verbose({ port: server.port, address: server.address });
+
+  const params = {
+    url: new URL(`mqtt://${server.address}:${server.port}`),
+    numberOfRetries: 0,
+  };
+
+  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 function () {
+    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 sleep(100);
+  logger.verbose(`Disconnect client`);
+  //client.closeMessages();
+  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();
+});
+
+test("Deno Test subscription persistence after reconnect", async function () {
+  // Start server
+  const server = new TcpServer({ port: 0 }, {});
+  server.start();
+
+  const params = {
+    url: new URL(`mqtt://${server.address}:${server.port}`),
+    numberOfRetries: 0,
+  };
+
+  const client = new TcpClient();
+  const testTopic = "test/topic";
+  const received: PublishPacket[] = [];
+
+  // First connection and subscription
+  await client.connect(params);
+  await client.subscribe({
+    subscriptions: [{
+      topicFilter: testTopic,
+      qos: 0,
+    }],
+  });
+
+  // Start receiving messages
+  (async function () {
+    for await (const item of client.messages()) {
+      received.push(item);
+    }
+  })();
+
+  // Disconnect client
+  await client.disconnect();
+  await sleep(100);
+
+  // Reconnect client
+  await client.connect(params);
+  await sleep(100);
+
+  // Publish test message
+  await client.publish({
+    topic: testTopic,
+    qos: 0,
+    payload: new Uint8Array([0x01]),
+  });
+
+  await sleep(100);
+  logger.verbose(`Disconnect client`);
+  await client.disconnect();
+
+  // Verify message was received
+  assert.equal(received.length, 1, "Should receive one message");
+  assert.equal(
+    received[0].topic,
+    testTopic,
+    "Should receive message on subscribed topic",
+  );
+
   server.stop();
 });

package/deno/tcpServer.ts

@@ -1,8 +1,15 @@
-// This a Deno specific implementation of a TCP socket listener
-// it uses the platform agnostic MqttServer class
+/**
+ * This module provides a Deno specific implementation of a TCP socket listener
+ * it uses the platform agnostic MqttServer class
+ *  @module
+ */
+
 import { MqttServer } from "../server/mod.ts";
 import type { MqttServerOptions } from "../server/mod.ts";
 
+/*
+ * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+ */
 export class TcpServer {
   private listener: Deno.Listener<Deno.Conn>;
   private mqttServer: MqttServer;

package/deno.json

@@ -1,6 +1,7 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.6.1",
+  "version": "1.6.3",
+  "license": "MIT",
   "exports": {
     "./server": "./server/mod.ts",
     "./client": "./client/mod.ts",

package/dist/bin/conformanceServer.js

@@ -1,45 +1,91 @@
 #!/usr/bin/env -S node --experimental-strip-types
 // this server is intended to be used with https://github.com/eclipse/iottestware
+/**
+ * MQTT Server implementation with authentication and authorization
+ * @module mqttServer
+ */
+import { TcpServer } from "../node/tcpServer.js";
 import { AuthenticationResult } from "../server/mod.js";
 import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
-import { TcpServer } from "../node/tcpServer.js";
+/**
+ * UTF-8 decoder for parsing passwords
+ */
 const utf8Decoder = new TextDecoder();
+/**
+ * Map storing valid username/password combinations
+ */
 const userTable = new Map();
 userTable.set("IoTester_1", "strong_password");
 userTable.set("IoTester_2", "strong_password");
+/**
+ * Regular expression for validating usernames
+ * Allows alphanumeric characters up to 23 chars long
+ */
 const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
-const notAuthorizedTable = new Set();
-notAuthorizedTable.add(["123-456-789", "eclipse/iot/tesware/0data"]);
+/**
+ * Flag to enable/disable username checking
+ * If false, all users are allowed access
+ * If true, only users in userTable are allowed access
+ */
+const checkUsername = true;
+/**
+ * Authenticates MQTT clients
+ * @param {Context} _ctx - Connection context
+ * @param {string} clientId - Client identifier
+ * @param {string} username - Username to authenticate
+ * @param {Uint8Array} password - Password as byte array
+ * @returns {TAuthenticationResult} Authentication result
+ */
 function isAuthenticated(_ctx, clientId, username, password) {
     const pwd = utf8Decoder.decode(password);
-    logger.debug(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
-    if (!userTable.has(username)) {
-        if (!strictUsername.test(username)) {
-            return AuthenticationResult.badUsernameOrPassword;
-        }
-    }
-    const pass = userTable.get(username);
-    if (pwd === pass) {
+    logger.info(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
+    if (!checkUsername) {
+        // allow all users access
         return AuthenticationResult.ok;
     }
+    // is the username valid according to MQTT specification
+    if (!strictUsername.test(username)) {
+        return AuthenticationResult.badUsernameOrPassword;
+    }
+    // Does user and password match an entry in userTable
+    if (userTable.has(username)) {
+        const pass = userTable.get(username);
+        if (pwd === pass) {
+            return AuthenticationResult.ok;
+        }
+    }
     return AuthenticationResult.notAuthorized;
 }
+/**
+ * Checks if client is authorized to publish to a topic
+ * @param {Context} ctx - Connection context
+ * @param {Topic} topic - Topic to publish to
+ * @returns {boolean} True if authorized
+ */
 function isAuthorizedToPublish(ctx, topic) {
     logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`);
-    // if (notAuthorizedTable.has([ctx.client,topic])){
-    //   return false;
-    // }
     return true;
 }
+/**
+ * Checks if client is authorized to subscribe to a topic
+ * @param {Context} ctx - Connection context
+ * @param {Topic} topic - Topic to subscribe to
+ * @returns {boolean} True if authorized
+ */
 function isAuthorizedToSubscribe(ctx, topic) {
     logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`);
     return true;
 }
-/** start the server **/
+/**
+ * Parse command line arguments and start server
+ */
 const { _: [portNum] } = parseArgs(getArgs());
 const port = Number(portNum ?? 1883);
 const hostname = "::";
 logger.level(LogLevel.info);
+/**
+ * TCP Server instance with authentication and authorization handlers
+ */
 const tcpServer = new TcpServer({ port, hostname }, {
     handlers: {
         isAuthenticated,

package/dist/bin/demoServer.js

@@ -1,40 +1,90 @@
 #!/usr/bin/env -S node --experimental-strip-types
+/**
+ * MQTT Server implementation with authentication and authorization
+ * @module mqttServer
+ */
 import { TcpServer } from "../node/tcpServer.js";
 import { AuthenticationResult } from "../server/mod.js";
 import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
+/**
+ * UTF-8 decoder for parsing passwords
+ */
 const utf8Decoder = new TextDecoder();
+/**
+ * Map storing valid username/password combinations
+ */
 const userTable = new Map();
 userTable.set("IoTester_1", "strong_password");
 userTable.set("IoTester_2", "strong_password");
-// const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
+/**
+ * Regular expression for validating usernames
+ * Allows alphanumeric characters up to 23 chars long
+ */
+const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
+/**
+ * Flag to enable/disable username checking
+ * If false, all users are allowed access
+ * If true, only users in userTable are allowed access
+ */
+const checkUsername = false;
+/**
+ * Authenticates MQTT clients
+ * @param {Context} _ctx - Connection context
+ * @param {string} clientId - Client identifier
+ * @param {string} username - Username to authenticate
+ * @param {Uint8Array} password - Password as byte array
+ * @returns {TAuthenticationResult} Authentication result
+ */
 function isAuthenticated(_ctx, clientId, username, password) {
     const pwd = utf8Decoder.decode(password);
     logger.info(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
-    return AuthenticationResult.ok;
-    // if (!userTable.has(username)) {
-    //   if (!strictUsername.test(username)) {
-    //     return AuthenticationResult.badUsernameOrPassword;
-    //   }
-    // }
-    // const pass = userTable.get(username);
-    // if (pwd === pass) {
-    //   return AuthenticationResult.ok;
-    // }
-    // return AuthenticationResult.badUsernameOrPassword;
+    if (!checkUsername) {
+        // allow all users access
+        return AuthenticationResult.ok;
+    }
+    // is the username valid according to MQTT specification
+    if (!strictUsername.test(username)) {
+        return AuthenticationResult.badUsernameOrPassword;
+    }
+    // Does user and password match an entry in userTable
+    if (userTable.has(username)) {
+        const pass = userTable.get(username);
+        if (pwd === pass) {
+            return AuthenticationResult.ok;
+        }
+    }
+    return AuthenticationResult.notAuthorized;
 }
+/**
+ * Checks if client is authorized to publish to a topic
+ * @param {Context} ctx - Connection context
+ * @param {Topic} topic - Topic to publish to
+ * @returns {boolean} True if authorized
+ */
 function isAuthorizedToPublish(ctx, topic) {
     logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`);
     return true;
 }
+/**
+ * Checks if client is authorized to subscribe to a topic
+ * @param {Context} ctx - Connection context
+ * @param {Topic} topic - Topic to subscribe to
+ * @returns {boolean} True if authorized
+ */
 function isAuthorizedToSubscribe(ctx, topic) {
     logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`);
     return true;
 }
-/** start the server **/
+/**
+ * Parse command line arguments and start server
+ */
 const { _: [portNum] } = parseArgs(getArgs());
 const port = Number(portNum ?? 1883);
 const hostname = "::";
 logger.level(LogLevel.info);
+/**
+ * TCP Server instance with authentication and authorization handlers
+ */
 const tcpServer = new TcpServer({ port, hostname }, {
     handlers: {
         isAuthenticated,

package/dist/bin/mqtt.js

@@ -1,4 +1,33 @@
 #!/usr/bin/env -S node --experimental-strip-types
+/**
+ * @fileoverview MQTT command line interface that provides publish and subscribe functionality
+ * @module mqtt-cli
+ *
+ * @description
+ * This module implements a command line interface for MQTT operations:
+ * - Publish messages to an MQTT broker
+ * - Subscribe to topics on an MQTT broker
+ *
+ * Features:
+ * - TLS support with custom certificates
+ * - Authentication with username/password
+ * - Configurable QoS levels (0-2)
+ * - Message retention
+ * - Session persistence
+ * - Custom client IDs
+ *
+ * @example
+ * # Publish a message
+ * mqtt publish -t topic -m message
+ *
+ * # Subscribe to a topic
+ * mqtt subscribe -t topic
+ *
+ * @requires node
+ * @requires ../client/mod.ts
+ * @requires ../node/tcpClient.ts
+ * @requires ../utils/mod.ts
+ */
 import { DEFAULT_URL } from "../client/mod.js";
 import { getFileData, TcpClient } from "../node/tcpClient.js";
 import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";

package/dist/client/ConnectionState.js

@@ -1,7 +1,16 @@
+/**
+ * @description Object representing possible connection states
+ * @readonly
+ */
 export const ConnectionState = {
+    /** System is offline and not attempting connection */
     offline: "offline",
+    /** System is in the process of establishing a connection */
     connecting: "connecting",
+    /** System has an active connection */
     connected: "connected",
+    /** System is in the process of disconnecting */
     disconnecting: "disconnecting",
+    /** System has been disconnected */
     disconnected: "disconnected",
 };