@seriousme/opifex 1.6.1 → 1.6.3

package/dist/client/client.js

@@ -1,10 +1,21 @@
 import { Deferred, logger, MemoryStore, PacketType, } from "./deps.js";
 import { Context } from "./context.js";
+/**
+ * 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) {
     return `${prefix}-${Math.random().toString().slice(-10)}`;
 }
+/**
+ * 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, attempt) {
-    // based on https://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html
     const factor = 1.5;
     const min = 1000;
     const max = 5000;
@@ -39,15 +50,32 @@ export class Client {
     clientId;
     ctx = new Context(new MemoryStore());
     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
+     */
     createConn(protocol, _hostname, _port, _caCerts, _cert, _key) {
         // if you need to support alternative connection types just
         // overload this method in your subclass
         throw `Unsupported protocol: ${protocol}`;
     }
+    /**
+     * Handles the connection process including retries and reconnection
+     * @returns Promise that resolves when connection is established or fails
+     */
     async doConnect() {
         if (!this.connectPacket) {
             return;
@@ -86,6 +114,11 @@ export class Client {
             this.ctx.unresolvedConnect?.reject(lastMessage);
         }
     }
+    /**
+     * Connects to the MQTT broker
+     * @param params - Connection parameters
+     * @returns Promise resolving to authentication result
+     */
     connect(params = {}) {
         this.url = params?.url || this.url;
         this.numberOfRetries = params.numberOfRetries || this.numberOfRetries;
@@ -105,9 +138,18 @@ export class Client {
         this.doConnect();
         return deferred.promise;
     }
+    /**
+     * Disconnects from the MQTT broker
+     * @returns Promise that resolves when disconnected
+     */
     async disconnect() {
         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) {
         const packet = {
             type: PacketType.publish,
@@ -115,6 +157,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) {
         const packet = {
             type: PacketType.subscribe,
@@ -123,9 +170,17 @@ export class Client {
         };
         await this.ctx.subscribe(packet);
     }
+    /**
+     * Gets an async iterator for received messages
+     * @returns AsyncGenerator yielding received publish packets
+     */
     async *messages() {
         yield* this.ctx.incoming;
     }
+    /**
+     * Closes the message stream
+     * @param reason - Optional reason for closing
+     */
     closeMessages(reason) {
         this.ctx.incoming.close(reason);
     }

package/dist/client/context.js

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

package/dist/client/handlers/handleConnack.js

@@ -1,5 +1,11 @@
 import { ConnectionState } from "../ConnectionState.js";
 import { AuthenticationResultByNumber } from "../deps.js";
+/**
+ * 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, ctx) {
     if (packet.returnCode === 0) {
         ctx.connectionState = ConnectionState.connected;

package/dist/client/handlers/handlePacket.js

@@ -8,6 +8,13 @@ import { handlePubcomp } from "./handlePubcomp.js";
 import { handleSuback } from "./handleSuback.js";
 import { handleUnsuback } from "./handleUnsuback.js";
 import { logger, PacketNameByType, PacketType } from "../deps.js";
+/**
+ * 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, packet) {
     logger.debug({ received: PacketNameByType[packet.type], packet });
     if (ctx.connectionState !== ConnectionState.connected) {

package/dist/client/handlers/handlePuback.js

@@ -1,4 +1,11 @@
-// 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, packet) {
     const id = packet.id;
     ctx.store.pendingOutgoing.delete(id);

package/dist/client/handlers/handlePubcomp.js

@@ -1,9 +1,16 @@
-// 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, packet) {
     const id = packet.id;
     if (ctx.store.pendingAckOutgoing.has(id)) {
         ctx.store.pendingAckOutgoing.delete(id);
-        ctx.receivePuback(id);
+        ctx.receivePubcomp(id);
     }
 }

package/dist/client/handlers/handlePublish.js

@@ -1,5 +1,10 @@
 import { PacketType } from "../deps.js";
-// 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, packet) {
     const qos = packet.qos || 0;
     if (qos === 0) {

package/dist/client/handlers/handlePubrec.js

@@ -1,8 +1,17 @@
 import { PacketType } from "../deps.js";
-// 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, packet) {
     const id = packet.id;
     const ack = {

package/dist/client/handlers/handlePubrel.js

@@ -1,8 +1,20 @@
 import { PacketType } from "../deps.js";
-// 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, packet) {
     const id = packet.id;
     if (ctx.store.pendingIncoming.has(id)) {

package/dist/client/handlers/handleSuback.js

@@ -1,7 +1,12 @@
-// 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, packet) {
     const id = packet.id;
     ctx.store.pendingOutgoing.delete(id);

package/dist/client/handlers/handleUnsuback.js

@@ -1,5 +1,13 @@
-// 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, packet) {
     const id = packet.id;
     ctx.store.pendingOutgoing.delete(id);

package/dist/client/store/memoryStore.js

@@ -1,16 +1,34 @@
+/**
+ * @module memoryStore
+ */
 import { assert } from "./deps.js";
 import { maxPacketId, } from "./store.js";
+/**
+ * In-memory implementation of the IStore interface for managing MQTT packet storage
+ */
 export class MemoryStore {
+    /** Current packet ID counter */
     packetId;
+    /** Map of pending incoming packets */
     pendingIncoming;
+    /** Map of pending outgoing packets */
     pendingOutgoing;
+    /** Map of pending acknowledgment outgoing packets */
     pendingAckOutgoing;
+    /**
+     * Creates a new MemoryStore instance
+     */
     constructor() {
         this.packetId = 0;
         this.pendingIncoming = new Map();
         this.pendingOutgoing = new Map();
         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() {
         const currentId = this.packetId;
         do {
@@ -25,6 +43,10 @@ export class MemoryStore {
         assert(this.packetId !== currentId, "No unused packetId available");
         return this.packetId;
     }
+    /**
+     * Asynchronously yields all pending outgoing packets
+     * @yields {PendingOutgoingPackets} Pending outgoing packets
+     */
     async *pendingOutgoingPackets() {
         for (const [_id, packet] of this.pendingAckOutgoing) {
             yield packet;

package/dist/client/store/store.js

@@ -1 +1,4 @@
+/**
+ * Maximum value for MQTT packet IDs (65535)
+ */
 export const maxPacketId = 0xffff;

package/dist/mqttPacket/AuthenticationResult.js

@@ -9,5 +9,8 @@ export const AuthenticationResult = {
     badUsernameOrPassword: 4,
     notAuthorized: 5,
 };
+/**
+ * Reverse lookup for AuthenticationResult
+ */
 export const AuthenticationResultByNumber = Object
     .fromEntries(Object.entries(AuthenticationResult).map(([k, v]) => [v, k]));

package/dist/mqttPacket/mod.js

@@ -1,3 +1,8 @@
+/**
+ *  This module provides the encoding and decoding of MQTT packets
+ * it is used by the server and client modules
+ *  @module
+ */
 import { PacketNameByType, PacketType } from "./PacketType.js";
 import { invalidTopic, invalidTopicFilter, invalidUTF8 } from "./validators.js";
 import { decodeLength, encodeLength } from "./length.js";

package/dist/node/tcpClient.js

@@ -1,11 +1,23 @@
-// 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.js";
 import { logger } from "../client/deps.js";
 import { readFile } from "node:fs/promises";
 import { createConnection } from "node:net";
 import * as tls from "node:tls";
 import { wrapNodeSocket } from "./wrapNodeSocket.js";
+/**
+ * @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) {
     if (!filename) {
         return;
@@ -16,6 +28,11 @@ export async function getFileData(filename) {
     }
     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 {
     connectMQTT(hostname, port = 1883) {
         logger.debug({ hostname, port });

package/dist/node/tcpServer.js

@@ -1,6 +1,9 @@
 import { createServer } from "node:net";
 import { MqttServer } from "../server/mod.js";
 import { wrapNodeSocket } from "./wrapNodeSocket.js";
+/*
+ * TCP server that wraps a MqttServer, see demoServer.ts in the /bin folder
+ */
 export class TcpServer {
     mqttServer;
     server;
@@ -9,16 +12,23 @@ export class TcpServer {
         this.mqttServer = new MqttServer(mqttOptions);
         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();
     }
     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/dist/node/wrapNodeSocket.js

@@ -1,9 +1,18 @@
 import { Writable } from "node:stream";
+/**
+ * Closes a Node.js socket if it is not already closed
+ * @param sock - The Node.js socket to close
+ */
 function closer(sock) {
     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) {
     const readable = new ReadableStream({
         type: "bytes",

package/dist/persistence/memory/memoryPersistence.js

@@ -2,6 +2,7 @@ import { Trie, } from "../deps.js";
 import { assert } from "../../utils/mod.js";
 const maxPacketId = 0xffff;
 export class MemoryStore {
+    existingSession = false;
     clientId;
     packetId;
     pendingIncoming;

package/dist/server/handlers/handleConnect.js

@@ -1,20 +1,35 @@
 import { AuthenticationResult, logger, PacketType, Timer, } from "../deps.js";
+/**
+ * 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, packet) {
     if (ctx.handlers.isAuthenticated) {
         return ctx.handlers.isAuthenticated(ctx, packet.clientId || "", packet.username || "", packet.password || new Uint8Array(0));
     }
     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, packet) {
     if (packet.protocolLevel !== 4) {
         return AuthenticationResult.unacceptableProtocol;
     }
     return isAuthenticated(ctx, packet);
 }
-export function handleConnect(ctx, packet) {
-    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, packet, ctx, clientId) {
     if (returnCode === AuthenticationResult.ok) {
         if (packet.will) {
             ctx.will = {
@@ -33,8 +48,27 @@ export function handleConnect(ctx, packet) {
                 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;
     }
-    const sessionPresent = false;
+    return false;
+}
+/**
+ * Handles the MQTT CONNECT packet
+ * @param ctx - The connection context
+ * @param packet - The MQTT CONNECT packet to handle
+ */
+export function handleConnect(ctx, packet) {
+    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/dist/server/handlers/handleDisconnect.js

@@ -1,3 +1,8 @@
+/**
+ * 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) {
     ctx.will = undefined;
     ctx.close();

package/dist/server/handlers/handlePacket.js

@@ -10,6 +10,13 @@ import { handleSubscribe } from "./handleSubscribe.js";
 import { handleUnsubscribe } from "./handleUnsubscribe.js";
 import { handleDisconnect } from "./handleDisconnect.js";
 import { logger } from "../deps.js";
+/**
+ * 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, packet) {
     logger.debug("handling", PacketNameByType[packet.type]);
     logger.debug(JSON.stringify(packet, null, 2));

package/dist/server/handlers/handlePingreq.js

@@ -1,4 +1,9 @@
 import { PacketType } from "../deps.js";
+/**
+ * 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) {
     await ctx.send({
         type: PacketType.pingres,

package/dist/server/handlers/handlePuback.js

@@ -1,4 +1,12 @@
-// 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, packet) {
     // qos 1 only
     const id = packet.id;

package/dist/server/handlers/handlePubcomp.js

@@ -1,5 +1,11 @@
-// 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, packet) {
     const id = packet.id;
     if (ctx.store?.pendingAckOutgoing.has(id)) {

package/dist/server/handlers/handlePublish.js

@@ -1,5 +1,11 @@
 import { SysPrefix } from "../context.js";
 import { PacketType } from "../deps.js";
+/**
+ * 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, topic) {
     if (topic.startsWith(SysPrefix)) {
         return false;
@@ -9,6 +15,13 @@ function authorizedToPublish(ctx, 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, packet) {
     if (!authorizedToPublish(ctx, packet.topic)) {
         return;

package/dist/server/handlers/handlePubrec.js

@@ -1,7 +1,15 @@
 import { PacketType } from "../deps.js";
-// 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, packet) {
     const id = packet.id;
     if (ctx.store?.pendingOutgoing.has(id)) {