@seriousme/opifex 1.6.2 → 1.7.0

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/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/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.7.0",
   "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",
@@ -21,6 +21,16 @@
     "mqtt": "dist/bin/mqtt.js",
     "demoServer": "dist/bin/demoServer.js"
   },
+  "files": [
+    "package.json",
+    "README.md",
+    "LICENSE.txt",
+    "**/*.ts",
+    "dist/**/*.js",
+    "dist/**/*.js.map",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map"
+  ],
   "exports": {
     "./server": "./dist/server/mod.js",
     "./client": "./dist/client/mod.js",
@@ -53,6 +63,6 @@
   },
   "homepage": "https://github.com/seriousme/opifex#readme",
   "devDependencies": {
-    "@types/node": "^22.10.0"
+    "@types/node": "^22.13.1"
   }
 }

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,