@seriousme/opifex 1.6.1 → 1.6.3

package/dist/server/handlers/handlePubrel.js

@@ -1,7 +1,16 @@
 import { PacketType } from "../deps.js";
-// qos 2 only
-// Method A, Initiate onward delivery of the Application Message1  then discard message
-// Send PUBCOMP <Packet Identifier>
+/**
+ * Handles PUBREL (QoS 2 publish release) packets
+ *
+ * @param ctx - The connection context
+ * @param packet - The PUBREL packet received from the client
+ * @returns Promise that resolves when handling is complete
+ * @description
+ * For QoS 2 message delivery:
+ * 1. Initiates onward delivery of the Application Message
+ * 2. Discards the stored message
+ * 3. Sends PUBCOMP packet with the Packet Identifier
+ */
 export async function handlePubrel(ctx, packet) {
     const id = packet.id;
     if (ctx.store?.pendingIncoming.has(id)) {

package/dist/server/handlers/handleSubscribe.js

@@ -1,14 +1,35 @@
 import { PacketType, } from "../deps.js";
+/**
+ * @constant {number} SubscriptionFailure
+ * @description Code indicating a failed subscription attempt
+ */
 const SubscriptionFailure = 0x80;
+/**
+ * Checks if a client is authorized to subscribe to a topic
+ * @param  ctx - The connection context
+ * @param  topicFilter - The topic filter to check authorization for
+ * @returns True if authorized, false otherwise
+ */
 function authorizedToSubscribe(ctx, topicFilter) {
     if (ctx.handlers.isAuthorizedToSubscribe) {
         return ctx.handlers.isAuthorizedToSubscribe(ctx, topicFilter);
     }
     return true;
 }
+/**
+ * @function handleSubscribe
+ * @description Processes an MQTT SUBSCRIBE packet
+ * @param {Context} ctx - The connection context
+ * @param {SubscribePacket} packet - The SUBSCRIBE packet received from the client
+ * @returns {Promise<void>}
+ * @throws {Error} If subscription processing fails
+ * @remarks The order of return codes in the SUBACK Packet MUST match the order of Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1]
+ */
 export async function handleSubscribe(ctx, packet) {
-    //  The order of return codes in the SUBACK Packet MUST match the order of
-    //  Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1].
+    /*
+     * The order of return codes in the SUBACK Packet MUST match the order of
+     * Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1].
+     */
     const validSubscriptions = [];
     const returnCodes = packet.subscriptions.map((sub) => {
         if (ctx.store) {
@@ -19,14 +40,16 @@ export async function handleSubscribe(ctx, packet) {
             validSubscriptions.push(sub);
             return sub.qos;
         }
-        return SubscriptionFailure; // failure
+        return SubscriptionFailure;
     });
     await ctx.send({
         type: PacketType.suback,
         id: packet.id,
         returnCodes: returnCodes,
     });
-    // send any retained messages that match these subscriptions
+    /*
+     * send any retained messages that match these subscriptions
+     */
     if (ctx.store) {
         ctx.persistence.handleRetained(ctx.store.clientId);
     }

package/dist/server/handlers/handleUnsubscribe.js

@@ -1,4 +1,10 @@
 import { PacketType } from "../deps.js";
+/**
+ * Handles MQTT unsubscribe packets by removing subscriptions and sending acknowledgement
+ * @param ctx - The connection context containing client information and methods
+ * @param packet - The MQTT unsubscribe packet containing topics to unsubscribe from
+ * @returns Promise that resolves when unsubscribe is complete and acknowledged
+ */
 export async function handleUnsubscribe(ctx, packet) {
     for (const topic of packet.topicFilters) {
         if (ctx.store) {

package/dist/utils/args.js

@@ -32,6 +32,20 @@ function parseKeyValue(arg, alias) {
     }
     return ["_", arg];
 }
+/**
+ *  a parser for command line arguments
+ * @param args the arguments to parse
+ * @param opts the options for the parser
+ * @returns the parsed arguments
+ *
+ * @example
+ * const args = parseArgs(args, {
+ *  alias: { h: "help" },
+ *  boolean: ["help"],
+ *  string: ["port"],
+ *  default: { port: 3000 },
+ * });
+ */
 export function parseArgs(args, opts = {}) {
     const { alias = {}, boolean = [], string = [], default: defaults = {} } = opts;
     const result = { ...defaults };

package/dist/utils/assert.js

@@ -5,6 +5,7 @@ export class AssertionError extends Error {
         this.name = "AssertionError";
     }
 }
+/** assert(expr, msg) throws AssertionError if expr is falsy. */
 export function assert(expr, msg = "") {
     if (!expr) {
         throw new AssertionError(msg);

package/dist/utils/asyncQueue.js

@@ -1,4 +1,17 @@
 import { nextTick } from "./nextTick.js";
+/**
+ * An Async Queue is a queue that can be used to push items to it and then wait
+ * for them to be consumed.
+ *
+ * @example
+ * ```ts
+ * const queue = new AsyncQueue<string>();
+ * queue.push("hello");
+ * for await (const item of queue) {
+ *   console.log(item); // "hello"
+ * }
+ * ```
+ */
 export class AsyncQueue {
     queue = [];
     maxQueueLength = Infinity;

package/dist/utils/deferred.js

@@ -1,3 +1,6 @@
+/**
+ * Create a promise that can be resolved/rejected later
+ */
 export class Deferred {
     promise;
     resolve;

package/dist/utils/logger.js

@@ -1,3 +1,6 @@
+/**
+ * The available log levels
+ */
 export const LogLevel = {
     error: 0,
     warn: 1,
@@ -5,6 +8,19 @@ export const LogLevel = {
     verbose: 3,
     debug: 4,
 };
+/**
+ * Simple logger class
+ * @example
+ * ```ts
+ * const logger = new Logger();
+ * logger.level(LogLevel.debug);
+ * logger.debug("debug message");
+ * logger.verbose("verbose message");
+ * logger.info("info message");
+ * logger.warn("warn message");
+ * logger.error("error message");
+ * ```
+ */
 export class Logger {
     defaultError = console.error;
     defaultWarn = console.warn;
@@ -26,4 +42,17 @@ export class Logger {
         this.debug = logLevel > 3 ? this.defaultDebug : this.noop;
     }
 }
+/**
+ * logger provides a singleton logger instance
+ * @example
+ * ```ts
+ * import { logger } from "./utils/logger.ts";
+ * logger.level(LogLevel.debug);
+ * logger.debug("debug message");
+ * logger.verbose("verbose message");
+ * logger.info("info message");
+ * logger.warn("warn message");
+ * logger.error("error message");
+ * ```
+ */
 export const logger = new Logger();

package/dist/utils/mod.js

@@ -1,3 +1,7 @@
+/**
+ *  This module provides various utilities
+ *  @module
+ */
 export { assert } from "./assert.js";
 export { Deferred } from "./deferred.js";
 export { Logger, logger, LogLevel } from "./logger.js";

package/dist/utils/nextTick.js

@@ -1,3 +1,18 @@
+/**
+ * Returns a promise that resolves on the next tick of the Node.js event loop.
+ * This is useful for deferring execution of code until after the current call stack is cleared.
+ *
+ * @example
+ * ```ts
+ * async function example() {
+ *   console.log('Before nextTick');
+ *   await nextTick();
+ *   console.log('After nextTick');
+ * }
+ * ```
+ *
+ * @returns {Promise<void>} A promise that resolves on the next tick of the event loop
+ */
 export function nextTick() {
     return new Promise((resolve) => setTimeout(resolve, 0));
 }

package/dist/utils/platform.js

@@ -1,4 +1,7 @@
 import { argv } from "node:process";
+/**
+ * @returns an array of command line arguments
+ */
 export function getArgs() {
     return argv.slice(2);
 }

package/mqttPacket/AuthenticationResult.ts

@@ -1,7 +1,6 @@
 /**
  *  Possible MQTT authentication results
  */
-
 export const AuthenticationResult = {
   ok: 0,
   unacceptableProtocol: 1,
@@ -11,6 +10,9 @@ export const AuthenticationResult = {
   notAuthorized: 5,
 } as const;
 
+/**
+ * Reverse lookup for AuthenticationResult
+ */
 export const AuthenticationResultByNumber: Record<number, string> = Object
   .fromEntries(
     Object.entries(AuthenticationResult).map(([k, v]) => [v, k]),

package/mqttPacket/connack.ts

@@ -4,6 +4,10 @@ import { BitMask } from "./BitMask.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 import { AuthenticationResultByNumber } from "./AuthenticationResult.ts";
 
+/**
+ * ConnackPacket is sent from the server to the client in response to a connect packet.
+ * It indicates that the connect is accepted.
+ */
 export type ConnackPacket = {
   type: TPacketType;
   sessionPresent: boolean;

package/mqttPacket/connect.ts

@@ -9,6 +9,9 @@ import {
   hasEmptyFlags,
 } from "./decoder.ts";
 
+/**
+ * ConnectPacket is sent from the client to the server to initiate a connection.
+ */
 export type ConnectPacket = {
   type: TPacketType;
   protocolName?: string;

package/mqttPacket/disconnect.ts

@@ -2,6 +2,10 @@ import { PacketType } from "./PacketType.ts";
 import { isEmptyBuf } from "./decoder.ts";
 import type { TPacketType } from "./types.ts";
 
+/**
+ * DisconnectPacket is the final control packet sent from the client to the server.
+ * It indicates that the client is disconnecting cleanly.
+ */
 export type DisconnectPacket = {
   type: TPacketType;
 };

package/mqttPacket/mod.ts

@@ -1,3 +1,9 @@
+/**
+ *  This module provides the encoding and decoding of MQTT packets
+ * it is used by the server and client modules
+ *  @module
+ */
+
 import type {
   ClientId,
   Dup,
@@ -33,6 +39,9 @@ import { pingres, type PingresPacket } from "./pingres.ts";
 import { disconnect, type DisconnectPacket } from "./disconnect.ts";
 import { DecoderError } from "./decoder.ts";
 
+/**
+ * this can be any possible MQTT packet
+ */
 export type AnyPacket =
   | ConnectPacket
   | ConnackPacket

package/mqttPacket/pingreq.ts

@@ -2,6 +2,9 @@ import { PacketType } from "./PacketType.ts";
 import { hasEmptyFlags, isEmptyBuf } from "./decoder.ts";
 import type { TPacketType } from "./types.ts";
 
+/**
+ * PingreqPacket is a packet that is sent to the server to keep the connection alive
+ */
 export type PingreqPacket = {
   type: TPacketType;
 };

package/mqttPacket/pingres.ts

@@ -2,6 +2,10 @@ import { PacketType } from "./PacketType.ts";
 import { isEmptyBuf } from "./decoder.ts";
 import type { TPacketType } from "./types.ts";
 
+/**
+ * PingresPacket is  an empty packet that is sent by the server in response to a PingreqPacket.
+ * It is used to indicate that the client is still connected to the server.
+ */
 export type PingresPacket = {
   type: TPacketType;
 };

package/mqttPacket/puback.ts

@@ -3,6 +3,9 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubackPacket is sent to indicate publish complete (QoS 1)
+ */
 export type PubackPacket = {
   type: TPacketType;
   id: PacketId;

package/mqttPacket/pubcomp.ts

@@ -3,6 +3,10 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubcompPacket is sent to indicate publish complete
+ * It is the fourth packet of the QoS 2 protocol exchange.
+ */
 export type PubcompPacket = {
   type: TPacketType;
   id: PacketId;

package/mqttPacket/publish.ts

@@ -4,6 +4,10 @@ import { BitMask } from "./BitMask.ts";
 import { Encoder, EncoderError } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * PublishPacket is used to send data from client to server and
+ * from server to subscribers
+ */
 export type PublishPacket = {
   type: TPacketType;
   topic: Topic;

package/mqttPacket/pubrec.ts

@@ -3,6 +3,10 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubrecPacket indicates publish received
+ * It is the second packet of the QoS 2 protocol exchange.
+ */
 export type PubrecPacket = {
   type: TPacketType;
   id: PacketId;

package/mqttPacket/pubrel.ts

@@ -3,6 +3,10 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * PubrelPacket is the packet sent by the Server to the Client in response to a
+ * PubrecPacket. It is the third packet of the QoS 2 protocol exchange.
+ */
 export type PubrelPacket = {
   type: TPacketType;
   id: PacketId;

package/mqttPacket/suback.ts

@@ -3,6 +3,10 @@ import { PacketType } from "./PacketType.ts";
 import { Encoder } from "./encoder.ts";
 import { Decoder } from "./decoder.ts";
 
+/**
+ * SubackPacket is sent by the server to the client to confirm receipt and
+ * processing of a SubscribePacket.
+ */
 export type SubackPacket = {
   type: TPacketType;
   id: PacketId;

package/mqttPacket/subscribe.ts

@@ -4,12 +4,18 @@ import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * SubscribePacket is sent from client to server to subscribe to topics
+ */
 export type SubscribePacket = {
   type: TPacketType;
   id: PacketId;
   subscriptions: Subscription[];
 };
 
+/**
+ * The topic to subscribe to and the associated QoS
+ */
 export type Subscription = {
   topicFilter: TopicFilter;
   qos: QoS;

package/mqttPacket/types.ts

@@ -2,26 +2,57 @@ import type { BitMask } from "./BitMask.ts";
 import type { PacketType } from "./PacketType.ts";
 import type { AuthenticationResult } from "./AuthenticationResult.ts";
 
+/**
+ * Type to limit bit mask to valid values
+ */
 export type TBitMask = typeof BitMask[keyof typeof BitMask];
+/**
+ * Type to limit packet type to valid values
+ */
 export type TPacketType = typeof PacketType[keyof typeof PacketType];
+
+/**
+ * Type to limit authentication result to valid values
+ */
 export type TAuthenticationResult =
   typeof AuthenticationResult[keyof typeof AuthenticationResult];
 
+/**
+ * Quality of Service level
+ */
 export type QoS = 0 | 1 | 2;
 
+/**
+ * Packet payload
+ */
 export type Payload = Uint8Array;
 
 /**
- * The MQTT topic to publish or subscribe to
+ * The MQTT topic to publish to
  */
 export type Topic = string;
 
+/**
+ * The MQTT topic to subscribe/unsubscribe to
+ */
 export type TopicFilter = string;
 
+/**
+ * Duplicate delivery flag
+ */
 export type Dup = boolean;
 
+/**
+ * Packet identifier, unique per client session
+ */
 export type PacketId = number;
 
+/**
+ * Return codes on to describe result of subscribe operation
+ */
 export type ReturnCodes = number[];
 
+/**
+ * Client identifier that uniquely identifies a client
+ */
 export type ClientId = string;

package/mqttPacket/unsuback.ts

@@ -3,6 +3,10 @@ import { PacketType } from "./PacketType.ts";
 import { Decoder } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
+/**
+ * UnsubackPacket is sent by the server to the client to confirm receipt
+ * of an UnsubscribePacket.
+ */
 export type UnsubackPacket = {
   type: TPacketType;
   id: PacketId;

package/mqttPacket/unsubscribe.ts

@@ -4,6 +4,9 @@ import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * UnsubscribePacket is sent from client to server to unsubscribe from topics
+ */
 export type UnsubscribePacket = {
   type: TPacketType;
   id: PacketId;

package/node/tcpClient.ts

@@ -1,5 +1,8 @@
-// this a NodeJS specific implementation of TCP client sockets
-// it extends the platform agnostic Client class
+/*
+ * this a NodeJS 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 { readFile } from "node:fs/promises";
@@ -8,6 +11,15 @@ import * as tls from "node:tls";
 import type { SockConn } from "../socket/socket.ts";
 import { wrapNodeSocket } from "./wrapNodeSocket.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) {
   if (!filename) {
     return;
@@ -19,6 +31,12 @@ export async function getFileData(filename: string | undefined) {
   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 connectMQTT(hostname: string, port = 1883): Promise<SockConn> {
     logger.debug({ hostname, port });

package/node/tcpServer.test.ts

@@ -9,10 +9,10 @@ logger.level(LogLevel.info);
 export function sleep(ms: number): Promise<unknown> {
   return new Promise((r) => setTimeout(r, ms));
 }
-export async function serverTest() {
+
+test("Test pubSub using client and server", async function () {
   const server = new TcpServer({ port: 0 }, {});
   server.start();
-  await sleep(1000);
 
   assert.deepStrictEqual(
     server.port !== undefined,
@@ -86,9 +86,64 @@ export async function serverTest() {
 
   logger.verbose(`Stop server`);
   server.stop();
-}
+});
 
-test("Test pubSub using client and server", async function () {
-  await serverTest();
-  logger.verbose("End of test");
+test("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/node/tcpServer.ts

@@ -1,5 +1,8 @@
-// This a NodeJS specific implementation of a TCP socket listener
-// it uses the platform agnostic MqttServer class
+/*
+ * This module provides a NodeJS specific implementation of a TCP socket listener
+ * it uses the platform agnostic MqttServer class
+ *  @module
+ */
 import type { Server } from "node:net";
 import { createServer } from "node:net";
 import type { MqttServerOptions } from "../server/mod.ts";
@@ -11,6 +14,9 @@ type ServerOptions = {
   port?: number;
 };
 
+/*
+ * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+ */
 export class TcpServer {
   private mqttServer: MqttServer;
   private server?: Server;
@@ -20,11 +26,18 @@ export class TcpServer {
     this.serverOptions = serverOptions;
   }
 
-  start() {
+  async start() {
     this.server = createServer((sock) =>
       this.mqttServer.serve(wrapNodeSocket(sock))
     );
+    const isListening = new Promise((resolve) => {
+      this.server?.on("listening", () => {
+        resolve(true);
+      });
+    });
     this.server.listen(this.serverOptions.port, this.serverOptions.hostname);
+    await isListening;
+    return;
   }
   stop() {
     this.server?.close();
@@ -32,7 +45,7 @@ export class TcpServer {
 
   get port() {
     const address = this.server?.address();
-    if (typeof address === "object") {
+    if (typeof address === "object" && address !== null) {
       return address?.port;
     }
     return this.serverOptions?.port;