@seriousme/opifex 1.6.3 → 1.7.0

package/dist/bin/mqtt.js

@@ -1,256 +0,0 @@
-#!/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.js";
-import { getFileData, TcpClient } from "../node/tcpClient.js";
-import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
-const client = new TcpClient();
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-logger.level(LogLevel.info);
-const MQTTHelp = `MQTT command line interface, available commands are:
-
-    * publish     publish a message to the broker
-    * subscribe   subscribe for updates from the broker
-
-Run 'mqtt [command] --help' to know more about the commands.`;
-const ConnectHelp = `
-  -u/--url        the URL to connect to: default is ${DEFAULT_URL}
-  -i/--clientId   the clientId to connect to the server
-  -U/--username   the username to connect to the server
-  -P/--password   the password to connect to the server
-  -C/--caFile     the path to a CA certificate file
-  -c/--certFile   the path to a certificate file
-  -k/--keyFile    the path to a key file
-  -n/--noClean    try to resume a previous session
-  -h/--help       this text
-  `;
-const connectOpts = {
-    string: [
-        "url",
-        "username",
-        "password",
-        "caFile",
-        "certFile",
-        "keyFile",
-        "clientId",
-    ],
-    alias: {
-        u: "url",
-        U: "username",
-        P: "password",
-        C: "caFile",
-        c: "certFile",
-        k: "keyFile",
-        i: "clientId",
-        n: "noClean",
-        h: "help",
-    },
-    boolean: ["noClean", "help"],
-    default: {
-        noClean: false,
-        clientId: `Opifex-${crypto.randomUUID()}`,
-    },
-};
-const SubscribeHelp = `Usage: mqtt subscribe <options>
-
-Where options are:
-  -t/--topic      the topic to use
-  -q/--qos        the QoS (0/1/2) to use, default is 0
-${ConnectHelp}
-Example: mqtt subscribe -t hello`;
-const subscribeOpts = {
-    string: ["topic"],
-    alias: {
-        t: "topic",
-        q: "qos",
-    },
-    default: {
-        qos: 0,
-        topic: "",
-    },
-};
-function parseQos(qosArg) {
-    const qos = Number(qosArg);
-    switch (qos) {
-        case 0:
-            return 0;
-        case 1:
-            return 1;
-        case 2:
-            return 2;
-        default:
-            break;
-    }
-    console.log("QoS must be between 0 and 2");
-    return 0;
-}
-async function getTLSdata(connectArgs) {
-    const caFileData = await getFileData(connectArgs.caFile);
-    const caCerts = caFileData ? [caFileData] : undefined;
-    const cert = await getFileData(connectArgs.certFile);
-    const key = await getFileData(connectArgs.keyFile);
-    return {
-        caCerts,
-        cert,
-        key,
-    };
-}
-async function subscribe() {
-    const connectArgs = parseArgs(getArgs(), connectOpts);
-    const { caCerts, cert, key, } = await getTLSdata(connectArgs);
-    const subscribeArgs = parseArgs(getArgs(), subscribeOpts);
-    if (connectArgs.help) {
-        console.log(SubscribeHelp);
-        return;
-    }
-    if (subscribeArgs.topic === undefined) {
-        console.log("Missing `topic`");
-        return;
-    }
-    try {
-        await client.connect({
-            url: connectArgs.url,
-            caCerts,
-            cert,
-            key,
-            options: {
-                username: connectArgs.username,
-                password: encoder.encode(connectArgs.password),
-                clientId: connectArgs.clientId,
-                clean: !connectArgs.noClean,
-                keepAlive: 60,
-            },
-        });
-        logger.debug("Connected !");
-        client.subscribe({
-            subscriptions: [
-                {
-                    topicFilter: subscribeArgs.topic,
-                    qos: parseQos(subscribeArgs.qos),
-                },
-            ],
-        });
-        logger.debug("Subscribed!");
-        for await (const message of client.messages()) {
-            console.log(decoder.decode(message.payload));
-        }
-    }
-    catch (err) {
-        if (err instanceof Error) {
-            // @ts-ignore the type spec of err is missing err.code
-            logger.info(`Error: ${err.message || err.code}`);
-        }
-    }
-}
-const PublishHelp = `Usage: mqtt publish <options>
-
-Where options are:
-  -t/--topic      the topic to use
-  -m/--message    the message to send
-  -q/--qos        the QoS (0/1/2) to use, default is 0
-  -r/--retain     if the message should be retained, default is false
-${ConnectHelp}
-Example: mqtt publish -t hello -m world`;
-const publishOpts = {
-    string: ["topic", "message"],
-    boolean: ["retain"],
-    alias: {
-        t: "topic",
-        m: "message",
-        q: "qos",
-        r: "retain",
-    },
-    default: {
-        qos: 0,
-        dup: false,
-        retain: false,
-        topic: undefined,
-        message: "",
-    },
-};
-async function publish() {
-    const connectArgs = parseArgs(getArgs(), connectOpts);
-    const { caCerts, cert, key, } = await getTLSdata(connectArgs);
-    const publishArgs = parseArgs(getArgs(), publishOpts);
-    if (connectArgs.help) {
-        console.log(PublishHelp);
-        return;
-    }
-    if (publishArgs.topic === undefined) {
-        console.log("Missing `topic`");
-        return;
-    }
-    try {
-        await client.connect({
-            url: connectArgs.url,
-            caCerts,
-            cert,
-            key,
-            options: {
-                username: connectArgs.username,
-                password: encoder.encode(connectArgs.password),
-                clientId: connectArgs.clientId,
-                clean: !connectArgs.noClean,
-            },
-        });
-        logger.debug("Connected !");
-        await client.publish({
-            topic: publishArgs.topic,
-            payload: encoder.encode(publishArgs.message),
-            retain: publishArgs.retain,
-            qos: parseQos(publishArgs.qos),
-        });
-        logger.debug("Published!");
-        client.disconnect();
-        logger.debug("Disconnected !");
-    }
-    catch (err) {
-        if (err instanceof Error) {
-            // @ts-ignore the type spec of err is missing err.code
-            logger.info(`Error: ${err.message || err.code}`);
-        }
-    }
-}
-function processArgs() {
-    const { _: [cmd] } = parseArgs(getArgs());
-    switch (cmd) {
-        case "publish":
-            publish();
-            break;
-        case "subscribe":
-            subscribe();
-            break;
-        default:
-            console.log(MQTTHelp);
-            break;
-    }
-}
-processArgs();

package/dist/client/ConnectionState.js

@@ -1,16 +0,0 @@
-/**
- * @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",
-};

package/dist/client/client.js

@@ -1,187 +0,0 @@
-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) {
-    const factor = 1.5;
-    const min = 1000;
-    const max = 5000;
-    const randomness = 1 + (random ? Math.random() : 0);
-    const delay = Math.floor(Math.min(randomness * min * (factor ** attempt), max));
-    logger.debug({ delay });
-    return new Promise((resolve) => setTimeout(resolve, delay));
-}
-/**  the default MQTT URL to connect to */
-export const DEFAULT_URL = "mqtt://localhost:1883/";
-const DEFAULT_KEEPALIVE = 60; // 60 seconds
-const DEFAULT_RETRIES = 3; // on first connect
-const CLIENTID_PREFIX = "opifex"; // on first connect
-/**
- * The Client class provides an MQTT Client that can be used to connect to
- * a MQTT broker and publish/subscribe messages.
- *
- * The Client class is not meant to be used directly, but
- * instead should be subclassed and the subclass should
- * override the createConn() method to provide a
- * connection type that is supported by the subclass.
- */
-export class Client {
-    clientIdPrefix = CLIENTID_PREFIX;
-    numberOfRetries = DEFAULT_RETRIES;
-    url = new URL(DEFAULT_URL);
-    keepAlive = DEFAULT_KEEPALIVE;
-    autoReconnect = true;
-    caCerts;
-    cert;
-    key;
-    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;
-        }
-        let isReconnect = false;
-        let attempt = 1;
-        let lastMessage = new Error();
-        let tryConnect = true;
-        while (tryConnect) {
-            logger.debug(`${isReconnect ? "re" : ""}connecting`);
-            try {
-                const conn = await this.createConn(this.url.protocol, this.url.hostname, Number(this.url.port) ?? undefined, this.caCerts, this.cert, this.key);
-                // if we get this far we have a connection
-                tryConnect =
-                    (await this.ctx.handleConnection(conn, this.connectPacket)) &&
-                        this.autoReconnect;
-                logger.debug({ tryConnect });
-                isReconnect = true;
-                this.connectPacket.clean = false;
-                this.ctx.close();
-            }
-            catch (err) {
-                if (err instanceof Error) {
-                    lastMessage = err;
-                }
-                logger.debug(lastMessage);
-                if (!isReconnect && attempt > this.numberOfRetries) {
-                    tryConnect = false;
-                }
-                else {
-                    await backOffSleep(true, attempt++);
-                }
-            }
-        }
-        if (isReconnect === false) {
-            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;
-        this.caCerts = params?.caCerts;
-        this.cert = params?.cert;
-        this.key = params?.key;
-        const options = Object.assign({
-            keepAlive: this.keepAlive,
-            clientId: this.clientId,
-        }, params?.options);
-        this.connectPacket = {
-            type: PacketType.connect,
-            ...options,
-        };
-        const deferred = new Deferred();
-        this.ctx.unresolvedConnect = deferred;
-        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,
-            ...params,
-        };
-        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,
-            id: 0, //placeholder
-            ...params,
-        };
-        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

@@ -1,152 +0,0 @@
-import { AsyncQueue, Deferred, logger, MqttConn, PacketType, Timer, } from "./deps.js";
-import { handlePacket } from "./handlers/handlePacket.js";
-import { ConnectionState } from "./ConnectionState.js";
-export class Context {
-    mqttConn;
-    connectionState;
-    pingTimer;
-    unresolvedConnect;
-    unresolvedPublish;
-    unresolvedSubscribe;
-    unresolvedUnSubscribe;
-    store;
-    incoming;
-    constructor(store) {
-        this.store = store;
-        this.connectionState = ConnectionState.offline;
-        this.incoming = new AsyncQueue();
-        this.unresolvedPublish = new Map();
-        this.unresolvedSubscribe = new Map();
-        this.unresolvedUnSubscribe = new Map();
-    }
-    async connect(packet) {
-        this.connectionState = ConnectionState.connecting;
-        await this.mqttConn?.send(packet);
-        const keepAlive = packet.keepAlive || 0;
-        if (keepAlive > 0) {
-            this.pingTimer = new Timer(this.sendPing.bind(this), keepAlive * 1000, true);
-        }
-    }
-    async disconnect() {
-        if (this.connectionState !== ConnectionState.connected) {
-            throw "Not connected";
-        }
-        if (this.mqttConn) {
-            this.connectionState = ConnectionState.disconnecting;
-            await this.mqttConn.send({ type: PacketType.disconnect });
-            this.mqttConn.close();
-        }
-    }
-    async send(packet) {
-        logger.debug({ send: packet });
-        if (this.connectionState === ConnectionState.connected &&
-            !this.mqttConn?.isClosed) {
-            await this.mqttConn?.send(packet);
-            this.pingTimer?.reset();
-            return;
-        }
-        logger.debug("not connected");
-        this.pingTimer?.clear();
-    }
-    sendPing() {
-        this.send({ type: PacketType.pingreq });
-    }
-    async handleConnection(conn, connectPacket) {
-        this.mqttConn = new MqttConn({ conn });
-        if (this.mqttConn === undefined) {
-            return true;
-        }
-        logger.debug("Send connect packet");
-        await this.connect(connectPacket);
-        try {
-            logger.debug("Accepting packets");
-            for await (const packet of this.mqttConn) {
-                handlePacket(this, packet);
-            }
-            logger.debug("No more packets");
-        }
-        catch (err) {
-            logger.debug(err);
-            if (this.mqttConn.isClosed) {
-                this.mqttConn.close();
-            }
-        }
-        if (this.connectionState === ConnectionState.disconnecting) {
-            return false;
-        }
-        return true;
-    }
-    close() {
-        logger.debug("closing connection");
-        this.connectionState = ConnectionState.disconnected;
-        this.pingTimer?.clear();
-    }
-    receivePublish(packet) {
-        this.incoming.push(packet);
-    }
-    publish(packet) {
-        const qos = packet.qos || 0;
-        if (qos === 0) {
-            packet.id = 0;
-            this.send(packet);
-            // return empty promise
-            return Promise.resolve();
-        }
-        packet.id = this.store.nextId();
-        this.store.pendingOutgoing.set(packet.id, packet);
-        const deferred = new Deferred();
-        this.unresolvedPublish.set(packet.id, deferred);
-        this.send(packet);
-        return deferred.promise;
-    }
-    subscribe(packet) {
-        packet.id = this.store.nextId();
-        this.store.pendingOutgoing.set(packet.id, packet);
-        const deferred = new Deferred();
-        this.unresolvedSubscribe.set(packet.id, deferred);
-        this.send(packet);
-        return deferred.promise;
-    }
-    unsubscribe(packet) {
-        packet.id = this.store.nextId();
-        this.store.pendingOutgoing.set(packet.id, packet);
-        const deferred = new Deferred();
-        this.unresolvedUnSubscribe.set(packet.id, deferred);
-        this.send(packet);
-        return deferred.promise;
-    }
-    receivePuback(id) {
-        const unresolvedMap = this.unresolvedPublish;
-        if (unresolvedMap.has(id)) {
-            const deferred = unresolvedMap.get(id);
-            unresolvedMap.delete(id);
-            deferred?.resolve();
-            return true;
-        }
-        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)) {
-            const deferred = unresolvedMap.get(id);
-            unresolvedMap.delete(id);
-            deferred?.resolve(returnCodes);
-            return true;
-        }
-        return false;
-    }
-    receiveUnsuback(id) {
-        const unresolvedMap = this.unresolvedUnSubscribe;
-        if (unresolvedMap.has(id)) {
-            const deferred = unresolvedMap.get(id);
-            unresolvedMap.delete(id);
-            deferred?.resolve();
-            return true;
-        }
-        return false;
-    }
-}

package/dist/client/deps.js

@@ -1,5 +0,0 @@
-export { AuthenticationResult, AuthenticationResultByNumber, decodePayload, encode, PacketNameByType, PacketType, } from "../mqttPacket/mod.js";
-export { MqttConn } from "../mqttConn/mqttConn.js";
-export { Timer } from "../timer/timer.js";
-export { AsyncQueue, Deferred, logger } from "../utils/mod.js";
-export { MemoryStore } from "./store/memoryStore.js";

package/dist/client/handlers/handleConnack.js

@@ -1,24 +0,0 @@
-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;
-        ctx.pingTimer?.reset();
-        ctx.unresolvedConnect?.resolve(packet.returnCode);
-        // start transmitting packets that were queued before
-        for await (const packet of ctx.store.pendingOutgoingPackets()) {
-            ctx.send(packet);
-        }
-        return;
-    }
-    const err = new Error(`Connect failed: ${AuthenticationResultByNumber[packet.returnCode]}`);
-    ctx.connectionState = ConnectionState.disconnecting;
-    ctx.pingTimer?.clear();
-    ctx.unresolvedConnect?.reject(err);
-}

package/dist/client/handlers/handlePacket.js

@@ -1,57 +0,0 @@
-import { ConnectionState } from "../ConnectionState.js";
-import { handleConnack } from "./handleConnack.js";
-import { handlePublish } from "./handlePublish.js";
-import { handlePuback } from "./handlePuback.js";
-import { handlePubrec } from "./handlePubrec.js";
-import { handlePubrel } from "./handlePubrel.js";
-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) {
-        if (packet.type === PacketType.connack) {
-            handleConnack(packet, ctx);
-        }
-        else {
-            throw new Error(`Received ${PacketNameByType[packet.type]} packet before connect`);
-        }
-    }
-    else {
-        switch (packet.type) {
-            case PacketType.pingres:
-                break;
-            case PacketType.publish:
-                await handlePublish(ctx, packet);
-                break;
-            case PacketType.puback:
-                await handlePuback(ctx, packet);
-                break;
-            case PacketType.pubrel:
-                await handlePubrel(ctx, packet);
-                break;
-            case PacketType.pubrec:
-                await handlePubrec(ctx, packet);
-                break;
-            case PacketType.pubcomp:
-                await handlePubcomp(ctx, packet);
-                break;
-            case PacketType.suback:
-                await handleSuback(ctx, packet);
-                break;
-            case PacketType.unsuback:
-                handleUnsuback(ctx, packet);
-                break;
-            default:
-                throw new Error(`Received unexpected ${PacketNameByType[packet.type]} packet after connect`);
-        }
-    }
-}