@seriousme/opifex 1.6.1 → 1.6.3

package/.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"

package/.github/workflows/closeStale.yml

@@ -7,7 +7,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@v3
+      - uses: actions/stale@v9
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           days-before-stale: 30

package/.github/workflows/codeql-analysis.yml

@@ -39,11 +39,11 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v1
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -54,7 +54,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v1
+        uses: github/codeql-action/autobuild@v3
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -68,4 +68,4 @@ jobs:
       #   make release
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v1
+        uses: github/codeql-action/analyze@v3

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ### Changed
 
+## [v1.6.3] 31-01-2025
+
+### Changed
+
+- fix: improve memory persistence backend on reconnects
+
+## [v1.6.2] 19-01-2025
+
+### Changed
+
+- fix: added more JSdoc comments
+
 ## [v1.6.1] 18-01-2025
 
 ### Changed

package/README.md

@@ -4,8 +4,9 @@
 # Opifex
 
 Opifex aims to provide a MQTT server and MQTT client in Typescript to be used
-with [Deno](https://deno.land) or [NodeJS](https://nodejs.org) It has _no_ third
-party dependencies, it only relies on built in modules.
+with [Deno](https://deno.land), [NodeJS](https://nodejs.org) or
+[Bun](https://bun.sh) It has _no_ third party dependencies, it only relies on
+built in modules.
 
 Its a work in progress, only does MQTT 3.1.1 and currently only has memory based
 persistence.
@@ -80,12 +81,10 @@ types of transport (e.g. Unix sockets or websocketstream) then its recommended
 to clone and modify the platform specific code in `/node` or `/deno` as well.
 
 If you want to port the platform independent client and server libs to another
-platform (e.g. Bun) then the platform specific code in `/node` or `/deno` might
-serve as inspiration.
+platform then the platform specific code in `/node` or `/deno` might serve as
+inspiration.
 
-The platform independent client and server libs should also work on Bun as they
-are engine independent, but the demo server and client currently do not work on
-Bun because of some socket incompatibilities between Bun and the rest.
+Bun (as of version 1.2) is capable of running the NodeJS version.
 
 ## Naming
 

package/bin/conformanceServer.ts

@@ -1,19 +1,48 @@
 #!/usr/bin/env -S node --experimental-strip-types
 // this server is intended to be used with https://github.com/eclipse/iottestware
 
-import { AuthenticationResult } from "../server/mod.ts";
+/**
+ * MQTT Server implementation with authentication and authorization
+ * @module mqttServer
+ */
+import { TcpServer } from "../node/tcpServer.ts";
 import type { Context, TAuthenticationResult, Topic } from "../server/mod.ts";
+import { AuthenticationResult } from "../server/mod.ts";
 import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
-import { TcpServer } from "../node/tcpServer.ts";
 
+/**
+ * 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: Context,
   clientId: string,
@@ -21,31 +50,47 @@ function isAuthenticated(
   password: Uint8Array,
 ): TAuthenticationResult {
   const pwd = utf8Decoder.decode(password);
-  logger.debug(
+  logger.info(
     `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) {
+  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: Context, topic: Topic): boolean {
   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: Context, topic: Topic): boolean {
   logger.debug(
     `Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`,
@@ -53,11 +98,17 @@ function isAuthorizedToSubscribe(ctx: Context, topic: Topic): boolean {
   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/bin/demoServer.ts

@@ -1,15 +1,47 @@
 #!/usr/bin/env -S node --experimental-strip-types
+
+/**
+ * MQTT Server implementation with authentication and authorization
+ * @module mqttServer
+ */
 import { TcpServer } from "../node/tcpServer.ts";
 import type { Context, TAuthenticationResult, Topic } from "../server/mod.ts";
 import { AuthenticationResult } from "../server/mod.ts";
 import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
 
+/**
+ * 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: Context,
   clientId: string,
@@ -21,26 +53,43 @@ function isAuthenticated(
     `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: Context, topic: Topic): boolean {
   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: Context, topic: Topic): boolean {
   logger.debug(
     `Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`,
@@ -48,11 +97,17 @@ function isAuthorizedToSubscribe(ctx: Context, topic: Topic): boolean {
   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/bin/mqtt.ts

@@ -1,4 +1,34 @@
 #!/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.ts";
 import { getFileData, TcpClient } from "../node/tcpClient.ts";
 import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";

package/client/ConnectionState.ts

@@ -1,10 +1,22 @@
+/**
+ * @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",
 } as const;
 
+/**
+ * @description Type representing the possible values of ConnectionState
+ */
 export type TConnectionState =
   (typeof ConnectionState)[keyof typeof ConnectionState];

package/client/client.ts

@@ -12,6 +12,11 @@ import {
 
 import { Context } from "./context.ts";
 
+/**
+ * Generates a random client ID with the given prefix
+ * @param prefix - The prefix to use for the client ID
+ * @returns A string containing the prefix followed by a random number
+ */
 function generateClientId(prefix: string): string {
   return `${prefix}-${Math.random().toString().slice(-10)}`;
 }
@@ -36,8 +41,14 @@ export type PublishParameters = Omit<PublishPacket, "type" | "id">;
 /** SubscribeParameters define how to subscribe to a topic */
 export type SubscribeParameters = Omit<SubscribePacket, "type" | "id">;
 
+/**
+ * Implements exponential backoff sleep with optional randomization
+ * based on https://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html
+ * @param random - Whether to add randomization to the delay
+ * @param attempt - The attempt number (used to calculate delay)
+ * @returns Promise that resolves after the calculated delay
+ */
 function backOffSleep(random: boolean, attempt: number): Promise<void> {
-  // based on https://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html
   const factor = 1.5;
   const min = 1000;
   const max = 5000;
@@ -64,7 +75,6 @@ const CLIENTID_PREFIX = "opifex"; // on first connect
  * override the createConn() method to provide a
  * connection type that is supported by the subclass.
  */
-
 export class Client {
   protected clientIdPrefix = CLIENTID_PREFIX;
   protected numberOfRetries = DEFAULT_RETRIES;
@@ -78,11 +88,24 @@ export class Client {
   private ctx = new Context(new MemoryStore());
   private connectPacket?: ConnectPacket;
 
+  /**
+   * Creates a new MQTT client instance
+   */
   constructor() {
     this.clientId = generateClientId(this.clientIdPrefix);
     this.numberOfRetries = DEFAULT_RETRIES;
   }
 
+  /**
+   * Creates a new connection to the MQTT broker
+   * @param protocol - The protocol to use (mqtt, mqtts, etc)
+   * @param _hostname - The hostname to connect to
+   * @param _port - The port to connect to
+   * @param _caCerts - Optional CA certificates
+   * @param _cert - Optional client certificate
+   * @param _key - Optional client key
+   * @returns Promise resolving to a SockConn connection
+   */
   protected createConn(
     protocol: string,
     _hostname: string,
@@ -96,6 +119,10 @@ export class Client {
     throw `Unsupported protocol: ${protocol}`;
   }
 
+  /**
+   * Handles the connection process including retries and reconnection
+   * @returns Promise that resolves when connection is established or fails
+   */
   private async doConnect(): Promise<void> {
     if (!this.connectPacket) {
       return;
@@ -141,6 +168,11 @@ export class Client {
     }
   }
 
+  /**
+   * Connects to the MQTT broker
+   * @param params - Connection parameters
+   * @returns Promise resolving to authentication result
+   */
   connect(params: ConnectParameters = {}): Promise<TAuthenticationResult> {
     this.url = params?.url || this.url;
     this.numberOfRetries = params.numberOfRetries || this.numberOfRetries;
@@ -164,10 +196,19 @@ export class Client {
     return deferred.promise;
   }
 
+  /**
+   * Disconnects from the MQTT broker
+   * @returns Promise that resolves when disconnected
+   */
   async disconnect(): Promise<void> {
     await this.ctx.disconnect();
   }
 
+  /**
+   * Publishes a message to the MQTT broker
+   * @param params - Publish parameters including topic and payload
+   * @returns Promise that resolves when published
+   */
   async publish(params: PublishParameters): Promise<void> {
     const packet: PublishPacket = {
       type: PacketType.publish,
@@ -176,6 +217,11 @@ export class Client {
     await this.ctx.publish(packet);
   }
 
+  /**
+   * Subscribes to topics on the MQTT broker
+   * @param params - Subscribe parameters including topics
+   * @returns Promise that resolves when subscribed
+   */
   async subscribe(params: SubscribeParameters): Promise<void> {
     const packet: SubscribePacket = {
       type: PacketType.subscribe,
@@ -185,10 +231,18 @@ export class Client {
     await this.ctx.subscribe(packet);
   }
 
+  /**
+   * Gets an async iterator for received messages
+   * @returns AsyncGenerator yielding received publish packets
+   */
   async *messages(): AsyncGenerator<PublishPacket, void, unknown> {
     yield* this.ctx.incoming;
   }
 
+  /**
+   * Closes the message stream
+   * @param reason - Optional reason for closing
+   */
   closeMessages(reason?: string) {
     this.ctx.incoming.close(reason);
   }

package/client/context.ts

@@ -166,6 +166,11 @@ export class Context {
     return false;
   }
 
+  // just an alias to clarify protocol flow
+  receivePubcomp(id: PacketId): boolean {
+    return this.receivePuback(id);
+  }
+
   receiveSuback(id: PacketId, returnCodes: ReturnCodes): boolean {
     const unresolvedMap = this.unresolvedSubscribe;
     if (unresolvedMap.has(id)) {

package/client/handlers/handleConnack.ts

@@ -2,6 +2,12 @@ import type { Context } from "../context.ts";
 import { ConnectionState } from "../ConnectionState.ts";
 import { AuthenticationResultByNumber, type ConnackPacket } from "../deps.ts";
 
+/**
+ * Handles the CONNACK packet received from the MQTT broker
+ * @param packet - The CONNACK packet containing the connection acknowledgment
+ * @param ctx - The connection context
+ * @returns Promise that resolves when handling is complete
+ */
 export async function handleConnack(packet: ConnackPacket, ctx: Context) {
   if (packet.returnCode === 0) {
     ctx.connectionState = ConnectionState.connected;

package/client/handlers/handlePacket.ts

@@ -21,6 +21,13 @@ import type {
   UnsubackPacket,
 } from "../deps.ts";
 
+/**
+ * Handles incoming MQTT packets based on the connection state and packet type
+ * @param ctx - The MQTT client context containing connection state and other information
+ * @param packet - The MQTT packet to handle
+ * @throws Error if an unexpected packet is received before connection is established
+ * @throws Error if an unexpected packet type is received after connection
+ */
 export async function handlePacket(
   ctx: Context,
   packet: AnyPacket,

package/client/handlers/handlePuback.ts

@@ -1,8 +1,14 @@
 import type { Context } from "../context.ts";
 import type { PubackPacket } from "../deps.ts";
 
-// A PUBACK Packet is the response to a PUBLISH Packet with QoS level 1.
-
+/**
+ * Handles PUBACK packet processing for QoS level 1 PUBLISH responses
+ * @param ctx - The MQTT client context
+ * @param packet - The PUBACK packet received from the broker
+ * @description
+ * - Removes the packet ID from the list of pending outgoing messages
+ * - Completes the corresponding publish operation
+ */
 export function handlePuback(ctx: Context, packet: PubackPacket): void {
   const id = packet.id;
   ctx.store.pendingOutgoing.delete(id);

package/client/handlers/handlePubcomp.ts

@@ -1,13 +1,19 @@
 import type { Context } from "../context.ts";
 import type { PubcompPacket } from "../deps.ts";
 
-// The PUBCOMP Packet is the response to a PUBREL Packet.
-// It is the fourth and final packet of the QoS 2 protocol exchange.
-
+/**
+ * Handles PUBCOMP packets which are the response to PUBREL packets in QoS 2 flow
+ * @param ctx - The connection context containing the client state and store
+ * @param packet - The PUBCOMP packet received from the broker
+ * @description
+ * This function processes PUBCOMP packets which are the fourth and final packet
+ * in the QoS 2 protocol exchange. It removes the message from pendingAckOutgoing queue
+ * Completes the corresponding publish operation
+ */
 export function handlePubcomp(ctx: Context, packet: PubcompPacket): void {
   const id = packet.id;
   if (ctx.store.pendingAckOutgoing.has(id)) {
     ctx.store.pendingAckOutgoing.delete(id);
-    ctx.receivePuback(id);
+    ctx.receivePubcomp(id);
   }
 }

package/client/handlers/handlePublish.ts

@@ -1,8 +1,12 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PublishPacket } from "../deps.ts";
 
-// Incoming publish
-
+/**
+ * Handles incoming MQTT publish packets based on their QoS level
+ * @param ctx - The MQTT connection context
+ * @param packet - The incoming publish packet to handle
+ * @returns Promise that resolves when packet is handled
+ */
 export async function handlePublish(ctx: Context, packet: PublishPacket) {
   const qos = packet.qos || 0;
   if (qos === 0) {

package/client/handlers/handlePubrec.ts

@@ -1,12 +1,19 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PubrecPacket, type PubrelPacket } from "../deps.ts";
 
-// A PUBREC Packet is the response to a PUBLISH Packet with QoS 2.
-// It is the second packet of the QoS 2 protocol exchange.
-
-// Discard message, Store PUBREC received <Packet Identifier>
-// send PUBREL <Packet Identifier>
-
+/**
+ * Handles PUBREC (Publish Received) packets for QoS 2 message flow
+ * It is the second packet of the QoS 2 protocol exchange.
+ * @param ctx - The connection context containing message stores and send function
+ * @param packet - The received PUBREC packet
+ * @description
+ * When a PUBREC packet is received:
+ * 1. Checks if there is a pending outgoing message with matching packet ID
+ * 2. Creates a PUBREL packet to acknowledge the PUBREC
+ * 3. Add the packet ID to pendingAckOutgoing store
+ * 4. Removes the message from pendingOutgoing store
+ * 5. Sends the PUBREL packet
+ */
 export async function handlePubrec(
   ctx: Context,
   packet: PubrecPacket,