@seriousme/opifex 1.6.2 → 1.6.3

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/asyncQueue.js

@@ -4,11 +4,13 @@ import { nextTick } from "./nextTick.js";
  * 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 = [];

package/dist/utils/nextTick.js

@@ -1,5 +1,17 @@
 /**
- * @returns a promise that resolves on the nextTick of the event loop
+ * 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/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

@@ -26,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();
@@ -38,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;

package/node/wrapNodeSocket.ts

@@ -1,13 +1,24 @@
+/**
+ * Utility functions for wrapping Node.js sockets into standard web streams.
+ */
 import type { Socket } from "node:net";
 import { Writable } from "node:stream";
 import type { SockConn } from "../socket/socket.ts";
-
-function closer(sock: Socket) {
+/**
+ * Closes a Node.js socket if it is not already closed
+ * @param sock - The Node.js socket to close
+ */
+function closer(sock: Socket): void {
   if (!sock.closed) {
     sock.end();
   }
 }
 
+/**
+ * Wraps a Node.js socket into a standard web streams-based socket connection
+ * @param socket - The Node.js socket to wrap
+ * @returns A socket connection object with readable/writable streams and close method
+ */
 export function wrapNodeSocket(socket: Socket): SockConn {
   const readable = new ReadableStream(
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "description": "MQTT client & server for Deno & NodeJS",
   "type": "module",
   "scripts": {
@@ -10,7 +10,7 @@
     "postbuild": "deno fmt",
     "preversion": "npm run test",
     "version": "npm run build",
-    "postversion": "jq '( { name:.name , version:.version} + .deno)' package.json > deno.json"
+    "postversion": "jq '( { name:.name , version:.version, license:.license } + .deno)' package.json > deno.json"
   },
   "keywords": [
     "MQTT",

package/persistence/memory/memoryPersistence.test.ts

@@ -21,7 +21,7 @@ test("new should create new Persistence object", () => {
 });
 
 test(
-  "Registring a client should register the client and return a Store Object",
+  "Registering a client should register the client and return a Store Object",
   () => {
     const persistence = new Persistence();
     const clientId = "myClient";
@@ -29,6 +29,7 @@ test(
     assert.deepStrictEqual(persistence.clientList.has(clientId), true);
     assert.deepStrictEqual(typeof client, "object");
     assert.deepStrictEqual(client instanceof Store, true);
+    assert.deepStrictEqual(client.existingSession, false);
   },
 );
 

package/persistence/memory/memoryPersistence.ts

@@ -26,6 +26,7 @@ type ClientSubscription = {
 };
 
 export class MemoryStore implements IStore {
+  existingSession: boolean = false;
   clientId: ClientId;
   private packetId: PacketId;
   pendingIncoming: PacketStore;

package/persistence/store.ts

@@ -5,6 +5,7 @@ export type PacketStore = Map<PacketId, PublishPacket>;
 export type SubscriptionStore = Map<Topic, QoS>;
 
 export interface IStore {
+  existingSession: boolean;
   clientId: ClientId;
   pendingIncoming: PacketStore;
   pendingOutgoing: PacketStore;

package/server/handlers/handleConnect.ts

@@ -8,6 +8,12 @@ import {
   Timer,
 } from "../deps.ts";
 
+/**
+ * Checks if the client is authenticated based on the provided credentials
+ * @param ctx - The connection context
+ * @param packet - The MQTT CONNECT packet
+ * @returns Authentication result indicating if the client is authenticated
+ */
 function isAuthenticated(
   ctx: Context,
   packet: ConnectPacket,
@@ -23,6 +29,12 @@ function isAuthenticated(
   return AuthenticationResult.ok;
 }
 
+/**
+ * Validates the CONNECT packet
+ * @param ctx - The connection context
+ * @param packet - The MQTT CONNECT packet to validate
+ * @returns Authentication result indicating if the CONNECT packet is valid
+ */
 function validateConnect(
   ctx: Context,
   packet: ConnectPacket,
@@ -33,10 +45,18 @@ function validateConnect(
   return isAuthenticated(ctx, packet);
 }
 
-export function handleConnect(ctx: Context, packet: ConnectPacket): void {
-  const clientId = packet.clientId || `Opifex-${crypto.randomUUID()}`;
-  const returnCode = validateConnect(ctx, packet);
-  // connect is ok
+/**
+ * Processes the validated CONNECT packet
+ * @param packet - The MQTT CONNECT packet
+ * @param ctx - The connection context
+ * @param clientId - The client ID
+ */
+function processValidatedConnect(
+  returnCode: TAuthenticationResult,
+  packet: ConnectPacket,
+  ctx: Context,
+  clientId: string,
+): boolean {
   if (returnCode === AuthenticationResult.ok) {
     if (packet.will) {
       ctx.will = {
@@ -57,10 +77,33 @@ export function handleConnect(ctx: Context, packet: ConnectPacket): void {
         ctx.close();
       }, Math.floor(keepAlive * 1500));
     }
+    // is this a new session?
+    // either because its the first time for the client
+    // or it specifically asked for a clean one
+    const previousSession = ctx.store?.existingSession;
+    // client now has a history
+    if (!previousSession && ctx.store) {
+      ctx.store.existingSession = true;
+    }
+    return previousSession || false;
   }
+  return false;
+}
 
-  const sessionPresent = false;
-
+/**
+ * Handles the MQTT CONNECT packet
+ * @param ctx - The connection context
+ * @param packet - The MQTT CONNECT packet to handle
+ */
+export function handleConnect(ctx: Context, packet: ConnectPacket): void {
+  const clientId = packet.clientId || `Opifex-${crypto.randomUUID()}`;
+  const returnCode = validateConnect(ctx, packet);
+  const sessionPresent = processValidatedConnect(
+    returnCode,
+    packet,
+    ctx,
+    clientId,
+  );
   ctx.send({
     type: PacketType.connack,
     sessionPresent,

package/server/handlers/handleDisconnect.ts

@@ -1,5 +1,10 @@
 import type { Context } from "../context.ts";
 
+/**
+ * Handles client disconnection by clearing the will message and closing the connection
+ * @param {Context} ctx - The connection context object
+ * @returns {void}
+ */
 export function handleDisconnect(ctx: Context): void {
   ctx.will = undefined;
   ctx.close();

package/server/handlers/handlePacket.ts

@@ -23,6 +23,13 @@ import { handleUnsubscribe } from "./handleUnsubscribe.ts";
 import { handleDisconnect } from "./handleDisconnect.ts";
 import { logger } from "../deps.ts";
 
+/**
+ * Handles incoming MQTT packets based on their type and connection state
+ * @param ctx - The connection context containing client state and configuration
+ * @param packet - The MQTT packet to handle
+ * @throws Error if receiving unexpected packet types or packets before connect
+ * @returns Promise that resolves when packet handling is complete
+ */
 export async function handlePacket(
   ctx: Context,
   packet: AnyPacket,

package/server/handlers/handlePingreq.ts

@@ -1,6 +1,12 @@
 import type { Context } from "../context.ts";
 import { PacketType } from "../deps.ts";
 
+/**
+ * Handles PINGREQ packet by responding with a PINGRESP packet
+ * @param ctx - The connection context containing send method
+ * @returns Promise that resolves when PINGRESP is sent
+ */
+
 export async function handlePingreq(ctx: Context): Promise<void> {
   await ctx.send({
     type: PacketType.pingres,

package/server/handlers/handlePuback.ts

@@ -1,8 +1,15 @@
 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 (Publish Acknowledgment) packets in MQTT protocol
+ * @param ctx - The connection context containing the client's state and configuration
+ * @param packet - The PUBACK packet received from the client
+ * @description
+ * PUBACK packets are sent in response to PUBLISH packets with QoS level 1.
+ * This function removes the original PUBLISH packet from the pending outgoing messages store
+ * once acknowledgment is received.
+ */
 export function handlePuback(ctx: Context, packet: PubackPacket) {
   // qos 1 only
   const id = packet.id;

package/server/handlers/handlePubcomp.ts

@@ -1,9 +1,14 @@
 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 configuration
+ * @param packet - The PUBCOMP packet received from the client
+ * @description
+ * This is the fourth and final packet of the QoS 2 protocol exchange.
+ * When received, it removes the message from the pendingAckOutgoing store.
+ */
 export function handlePubcomp(ctx: Context, packet: PubcompPacket): void {
   const id = packet.id;
   if (ctx.store?.pendingAckOutgoing.has(id)) {

package/server/handlers/handlePublish.ts

@@ -1,6 +1,12 @@
 import { type Context, SysPrefix } from "../context.ts";
 import { PacketType, type PublishPacket, type Topic } from "../deps.ts";
 
+/**
+ * Checks if a client is authorized to publish to a given topic
+ * @param ctx - The connection context
+ * @param topic - The topic to check authorization for
+ * @returns boolean indicating if client is authorized to publish
+ */
 function authorizedToPublish(ctx: Context, topic: Topic) {
   if (topic.startsWith(SysPrefix)) {
     return false;
@@ -11,6 +17,13 @@ function authorizedToPublish(ctx: Context, topic: Topic) {
   return true;
 }
 
+/**
+ * Handles MQTT PUBLISH packets
+ * @param ctx - The connection context
+ * @param packet - The PUBLISH packet to process
+ * @returns Promise that resolves when packet is processed
+ * @throws Error if packet processing fails
+ */
 export async function handlePublish(
   ctx: Context,
   packet: PublishPacket,

package/server/handlers/handlePubrec.ts

@@ -1,9 +1,17 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PubrecPacket } from "../deps.ts";
 
-// qos 2
-// Discard message, Store PUBREC received <Packet Identifier>
-// send PUBREL <Packet Identifier>
+/**
+ * Handles PUBREC (QoS 2 Publish Received) packets
+ * @param ctx - The connection context
+ * @param packet - The PUBREC packet received from the client
+ * @returns Promise that resolves when handling is complete
+ * @description
+ * For QoS 2 message flow:
+ * 1. Discards the original publish message
+ * 2. Stores that PUBREC was received for the packet ID
+ * 3. Sends PUBREL packet in response
+ */
 export async function handlePubrec(
   ctx: Context,
   packet: PubrecPacket,

package/server/handlers/handlePubrel.ts

@@ -1,10 +1,18 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PubrelPacket } from "../deps.ts";
 
-// 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: Context,
   packet: PubrelPacket,

package/server/handlers/handleSubscribe.ts

@@ -6,7 +6,18 @@ import {
   type Topic,
 } from "../deps.ts";
 
+/**
+ * @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: Context, topicFilter: Topic) {
   if (ctx.handlers.isAuthorizedToSubscribe) {
     return ctx.handlers.isAuthorizedToSubscribe(ctx, topicFilter);
@@ -14,13 +25,23 @@ function authorizedToSubscribe(ctx: Context, topicFilter: Topic) {
   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: Context,
   packet: SubscribePacket,
 ): Promise<void> {
-  //  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: Subscription[] = [];
   const returnCodes = packet.subscriptions.map((sub) => {
     if (ctx.store) {
@@ -31,7 +52,7 @@ export async function handleSubscribe(
       validSubscriptions.push(sub);
       return sub.qos;
     }
-    return SubscriptionFailure; // failure
+    return SubscriptionFailure;
   });
 
   await ctx.send({
@@ -40,7 +61,9 @@ export async function handleSubscribe(
     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/server/handlers/handleUnsubscribe.ts

@@ -1,6 +1,12 @@
 import type { Context } from "../context.ts";
 import { PacketType, type UnsubscribePacket } from "../deps.ts";
 
+/**
+ * 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: Context,
   packet: UnsubscribePacket,

package/utils/asyncQueue.ts

@@ -1,15 +1,16 @@
 import { nextTick } from "./nextTick.ts";
-
 /**
  * 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<T> {
   private queue: T[] = [];

package/utils/nextTick.ts

@@ -1,5 +1,17 @@
 /**
- * @returns a promise that resolves on the nextTick of the event loop
+ * 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(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));