@seriousme/opifex 1.9.4 → 1.11.0

package/README.md

@@ -1,15 +1,49 @@
+[![Nodejs CI](https://github.com/seriousme/opifex/actions/workflows/nodejs-ci.yml/badge.svg)](https://github.com/seriousme/opifex/actions/workflows/nodejs-ci.yml)
 [![Deno CI](https://github.com/seriousme/opifex/actions/workflows/deno-ci.yml/badge.svg)](https://github.com/seriousme/opifex/actions/workflows/deno-ci.yml)
 [![CodeQL](https://github.com/seriousme/opifex/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/seriousme/opifex/actions/workflows/codeql-analysis.yml)
 
 # Opifex
 
 Opifex aims to provide a MQTT server and MQTT client in Typescript to be used
-with [Deno](https://deno.land), [NodeJS](https://nodejs.org) or
+with [NodeJS](https://nodejs.org), [Deno](https://deno.land) or
 [Bun](https://bun.sh) It has _no_ third party dependencies, it only relies on
 built in modules.
 
-Its a work in progress, only does MQTT 3.1.1 and currently only has memory based
-persistence.
+# Compatibility
+
+The following MQTT versions are supported:
+
+|                | MQTT 3.1 (v3) | MQTT 3.11 (v4) | MQTT 5.0 (v5) |
+| -------------- | ------------- | -------------- | ------------- |
+| Packet/encoder | ✅            | ✅             | ✅            |
+| Client         | ✅            | ✅             | ✅ partially  |
+| Server         | ❌            | ✅             | ❌            |
+
+Client and server currently only have memory based persistence, but one can
+provide its own persistence. (see [#Architecture] )
+
+## Usage
+
+The most easy way to use this project is to just use the demo server
+(demoServer) and/or the demo client (mqtt).
+
+- [NodeJS/Bun](node/README.md)
+- [Deno](deno/README.md)
+
+If you want to change the behaviour of the server and/or the client beyond what
+can be done with CLI options then the next step is to clone the demo server
+and/or the client scripts and modify them to your liking.
+
+If you want to port the platform independent client and server libs to other
+types of transport (e.g. Unix sockets or websocketstream) then its recommended
+to clone and modify the platform specific code in `/node` or `/deno` as well.
+
+If you want to port the platform independent client and server libs to another
+platform then the platform specific code in `/node` or `/deno` might serve as
+inspiration.
+
+Bun (as of version 1.2) and Deno are both capable of running the NodeJS version,
+but for historic reasons `/deno` still exists.
 
 ## Example
 
@@ -65,29 +99,6 @@ A more elaborate example including client and server can be found in the
 7. The demo client opens a platform specific socket and passes the resulting
    platform independent streams to the client module.
 
-## Usage
-
-The most easy way to use this project is to just use the demo server
-(demoServer) and/or the demo client (mqtt). There are separate usage
-instructions for:
-
-- [Deno](deno/README.md)
-- [NodeJS](node/README.md)
-
-If you want to change the behaviour of the server and/or the client beyond what
-can be done with CLI options then the next step is to clone the demo server
-and/or the client scripts and modify them to your liking.
-
-If you want to port the platform independent client and server libs to other
-types of transport (e.g. Unix sockets or websocketstream) then its recommended
-to clone and modify the platform specific code in `/node` or `/deno` as well.
-
-If you want to port the platform independent client and server libs to another
-platform then the platform specific code in `/node` or `/deno` might serve as
-inspiration.
-
-Bun (as of version 1.2) is capable of running the NodeJS version.
-
 ## Exports
 
 | Export                        | Description                                             |

package/bin/conformanceServer.ts

@@ -5,10 +5,11 @@
  * MQTT Server implementation with authentication and authorization
  * @module mqttServer
  */
+import { parseArgs } from "node:util";
 import { TcpServer } from "../node/tcpServer.ts";
 import type { Context, TAuthenticationResult, Topic } from "../server/mod.ts";
 import { AuthenticationResult } from "../server/mod.ts";
-import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
+import { logger, LogLevel } from "../utils/mod.ts";
 
 /**
  * UTF-8 decoder for parsing passwords
@@ -101,7 +102,7 @@ function isAuthorizedToSubscribe(ctx: Context, topic: Topic): boolean {
 /**
  * Parse command line arguments and start server
  */
-const { _: [portNum] } = parseArgs(getArgs());
+const { positionals: [portNum] } = parseArgs({ allowPositionals: true });
 const port = Number(portNum ?? 1883);
 const hostname = "::";
 logger.level(LogLevel.info);

package/bin/demoServer.ts

@@ -4,10 +4,11 @@
  * MQTT Server implementation with authentication and authorization
  * @module mqttServer
  */
+import { parseArgs } from "node:util";
 import { TcpServer } from "../node/tcpServer.ts";
 import type { Context, TAuthenticationResult, Topic } from "../server/mod.ts";
 import { AuthenticationResult } from "../server/mod.ts";
-import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
+import { logger, LogLevel } from "../utils/mod.ts";
 
 /**
  * UTF-8 decoder for parsing passwords
@@ -100,7 +101,7 @@ function isAuthorizedToSubscribe(ctx: Context, topic: Topic): boolean {
 /**
  * Parse command line arguments and start server
  */
-const { _: [portNum] } = parseArgs(getArgs());
+const { positionals: [portNum] } = parseArgs({ allowPositionals: true });
 const port = Number(portNum ?? 1883);
 const hostname = "::";
 logger.level(LogLevel.info);

package/bin/mqtt.ts

@@ -24,16 +24,24 @@
  * # Subscribe to a topic
  * mqtt subscribe -t topic
  *
- * @requires node
+ * @requires node:util
  * @requires ../client/mod.ts
  * @requires ../node/tcpClient.ts
  * @requires ../utils/mod.ts
  */
-import { DEFAULT_URL } from "../client/mod.ts";
+
+import { parseArgs } from "node:util";
+import type { ParseArgsConfig } from "node:util";
+import {
+  DEFAULT_KEEPALIVE,
+  DEFAULT_PROTOCOLLEVEL,
+  DEFAULT_URL,
+} from "../client/mod.ts";
+import type { ProtocolLevel } from "../client/mod.ts";
 import { getFileData, TcpClient } from "../node/tcpClient.ts";
-import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.ts";
-import type { Args } from "../utils/mod.ts";
+import { logger, LogLevel } from "../utils/mod.ts";
 
+type Args = Record<string, string | boolean>;
 const client = new TcpClient();
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
@@ -52,59 +60,64 @@ const ConnectHelp = `
   -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
+  -V/--mqttVersion the MQTT version to use (3,4 or 5): default is ${DEFAULT_PROTOCOLLEVEL}
   -c/--certFile   the path to a certificate file
   -k/--keyFile    the path to a key file
+  -K/--keepAlive  the keep alive of the client (in seconds): default is ${DEFAULT_KEEPALIVE}
   -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()}`,
+  url: { type: "string", short: "u", default: DEFAULT_URL },
+  username: { type: "string", short: "U" },
+  password: { type: "string", short: "P" },
+  caFile: { type: "string", short: "C" },
+  certFile: { type: "string", short: "c" },
+  keyFile: { type: "string", short: "k" },
+  keepAlive: {
+    type: "string",
+    short: "K",
+    default: DEFAULT_KEEPALIVE.toString(),
   },
-};
-
-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",
+  clientId: {
+    type: "string",
+    short: "i",
+    default: `Opifex-${crypto.randomUUID()}`,
   },
-  default: {
-    qos: 0,
-    topic: "",
+  noClean: { type: "boolean", short: "n", default: false },
+  mqttVersion: {
+    type: "string",
+    short: "V",
+    default: DEFAULT_PROTOCOLLEVEL?.toString(),
   },
-};
+  help: { type: "boolean", short: "h", default: false },
+} as const;
+
+async function connect(connectArgs: Args) {
+  const {
+    caCerts,
+    cert,
+    key,
+  } = await getTLSdata(connectArgs);
+  await client.connect({
+    url: new URL(connectArgs.url as string),
+    caCerts,
+    cert,
+    key,
+    options: {
+      username: connectArgs.username as string,
+      password: encodePwd(connectArgs.password as string),
+      clientId: connectArgs.clientId as string,
+      clean: !connectArgs.noClean,
+      keepAlive: Number(connectArgs.keepAlive),
+      protocolLevel: parseInt(
+        connectArgs.mqttVersion as string,
+      ) as ProtocolLevel,
+    },
+  });
+  logger.debug("Connected !");
+}
 
 function parseQos(qosArg: string | number) {
   const qos = Number(qosArg);
@@ -122,11 +135,21 @@ function parseQos(qosArg: string | number) {
   return 0;
 }
 
+function safeParseArgs(config: ParseArgsConfig) {
+  try {
+    return parseArgs(config);
+  } catch (err: unknown) {
+    if (err instanceof Error) {
+      console.error(err.message);
+    }
+  }
+}
+
 async function getTLSdata(connectArgs: Args) {
-  const caFileData = await getFileData(connectArgs.caFile);
+  const caFileData = await getFileData(connectArgs.caFile as string);
   const caCerts = caFileData ? [caFileData] : undefined;
-  const cert = await getFileData(connectArgs.certFile);
-  const key = await getFileData(connectArgs.keyFile);
+  const cert = await getFileData(connectArgs.certFile as string);
+  const key = await getFileData(connectArgs.keyFile as string);
   return {
     caCerts,
     cert,
@@ -134,43 +157,48 @@ async function getTLSdata(connectArgs: Args) {
   };
 }
 
+function encodePwd(password: string | undefined) {
+  if (typeof password === "string") {
+    return encoder.encode(password);
+  }
+  return undefined;
+}
+
+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 = {
+  topic: { type: "string", short: "t" },
+  qos: { type: "string", short: "q", default: "0" },
+} as const;
+
 async function subscribe() {
-  const connectArgs = parseArgs(getArgs(), connectOpts);
-  const {
-    caCerts,
-    cert,
-    key,
-  } = await getTLSdata(connectArgs);
-  const subscribeArgs = parseArgs(getArgs(), subscribeOpts);
-  if (connectArgs.help) {
+  const res = safeParseArgs({
+    options: { ...connectOpts, ...subscribeOpts },
+    allowPositionals: true,
+  });
+  if (!res) return;
+  const subscribeArgs = res.values as Record<string, string | boolean>;
+  if (subscribeArgs.help) {
     console.log(SubscribeHelp);
     return;
   }
-  if (subscribeArgs.topic === undefined) {
+  if (typeof subscribeArgs.topic !== "string") {
     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({
+    await connect(subscribeArgs);
+    await client.subscribe({
       subscriptions: [
         {
           topicFilter: subscribeArgs.topic,
-          qos: parseQos(subscribeArgs.qos),
+          qos: parseQos(subscribeArgs.qos as string),
         },
       ],
     });
@@ -198,58 +226,34 @@ ${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: "",
-  },
-};
+  topic: { type: "string", short: "t" },
+  message: { type: "string", short: "m" },
+  qos: { type: "string", short: "q", default: "0" },
+  retain: { type: "boolean", short: "r", default: false },
+} as const;
 
 async function publish() {
-  const connectArgs = parseArgs(getArgs(), connectOpts);
-  const {
-    caCerts,
-    cert,
-    key,
-  } = await getTLSdata(connectArgs);
-  const publishArgs = parseArgs(getArgs(), publishOpts);
-  if (connectArgs.help) {
+  const res = safeParseArgs({
+    options: { ...connectOpts, ...publishOpts },
+    allowPositionals: true,
+  });
+  if (!res) return;
+  const publishArgs = res.values as Record<string, string | boolean>;
+  if (publishArgs.help) {
     console.log(PublishHelp);
     return;
   }
-  if (publishArgs.topic === undefined) {
+  if (typeof publishArgs.topic !== "string") {
     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 connect(publishArgs);
     await client.publish({
       topic: publishArgs.topic,
-      payload: encoder.encode(publishArgs.message),
-      retain: publishArgs.retain,
-      qos: parseQos(publishArgs.qos),
+      payload: encoder.encode(publishArgs.message as string),
+      retain: publishArgs.retain as boolean,
+      qos: parseQos(publishArgs.qos as string),
     });
     logger.debug("Published!");
     client.disconnect();
@@ -263,7 +267,12 @@ async function publish() {
 }
 
 function processArgs() {
-  const { _: [cmd] } = parseArgs(getArgs());
+  const res = safeParseArgs({
+    strict: false,
+    allowPositionals: true,
+  });
+  const positionals = res !== undefined ? res.positionals : [];
+  const cmd = positionals[0];
   switch (cmd) {
     case "publish":
       publish();

package/client/client.ts

@@ -1,16 +1,24 @@
 import {
-  type ConnectPacket,
   Deferred,
   logger,
   MemoryStore,
+  MQTTLevel,
   PacketType,
-  type PublishPacket,
-  type SockConn,
-  type SubscribePacket,
-  type TAuthenticationResult,
 } from "./deps.ts";
 
+import type {
+  ConnectPacket,
+  PublishPacket,
+  SockConn,
+  SubscribePacket,
+  TAuthenticationResult,
+} from "./deps.ts";
+
+import { noop } from "../utils/utils.ts";
+
 import { Context } from "./context.ts";
+import type { TConnectionState } from "./ConnectionState.ts";
+import { assert } from "../utils/assert.ts";
 
 /**
  * Generates a random client ID with the given prefix
@@ -23,7 +31,7 @@ function generateClientId(prefix: string): string {
 
 type ConnectOptions = Omit<
   ConnectPacket,
-  "type" | "protocolName" | "protocolLevel"
+  "type" | "protocolName"
 >;
 
 /** ConnectParameters define how to connect */
@@ -37,9 +45,15 @@ export type ConnectParameters = {
 };
 
 /** PublishParameters define how a message should be published */
-export type PublishParameters = Omit<PublishPacket, "type" | "id">;
+export type PublishParameters = Omit<
+  PublishPacket,
+  "type" | "id" | "protocolLevel"
+>;
 /** SubscribeParameters define how to subscribe to a topic */
-export type SubscribeParameters = Omit<SubscribePacket, "type" | "id">;
+export type SubscribeParameters = Omit<
+  SubscribePacket,
+  "type" | "id" | "protocolLevel"
+>;
 
 /**
  * Implements exponential backoff sleep with optional randomization
@@ -60,9 +74,12 @@ function backOffSleep(random: boolean, attempt: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, delay));
 }
 
-/**  the default MQTT URL to connect to */
+/** the default MQTT URL to connect to */
 export const DEFAULT_URL = "mqtt://localhost:1883/";
-const DEFAULT_KEEPALIVE = 60; // 60 seconds
+/** the default protocol level to connect with*/
+export const DEFAULT_PROTOCOLLEVEL = MQTTLevel.v4;
+/** the default keepalive time */
+export const DEFAULT_KEEPALIVE = 60; // 60 seconds
 const DEFAULT_RETRIES = 3; // on first connect
 const CLIENTID_PREFIX = "opifex"; // on first connect
 
@@ -76,26 +93,37 @@ const CLIENTID_PREFIX = "opifex"; // on first connect
  * connection type that is supported by the subclass.
  */
 export class Client {
+  public onError: (err: Error) => void = noop;
+  public onConnected: () => void = noop;
+  public onDisconnected: () => void = noop;
+  public onReconnecting: () => void = noop;
+
   protected clientIdPrefix = CLIENTID_PREFIX;
   protected numberOfRetries = DEFAULT_RETRIES;
   protected url: URL = new URL(DEFAULT_URL);
   protected keepAlive = DEFAULT_KEEPALIVE;
+  protected protocolLevel = DEFAULT_PROTOCOLLEVEL;
   protected autoReconnect = true;
   private caCerts?: string[];
   private cert?: string;
   private key?: string;
   private clientId: string;
-  private ctx = new Context(new MemoryStore());
+  private ctx: Context;
   private connectPacket?: ConnectPacket;
 
   /**
    * Creates a new MQTT client instance
    */
   constructor() {
+    this.ctx = new Context(new MemoryStore(), this);
     this.clientId = generateClientId(this.clientIdPrefix);
     this.numberOfRetries = DEFAULT_RETRIES;
   }
 
+  get connectionState(): TConnectionState {
+    return this.ctx.connectionState;
+  }
+
   /**
    * Creates a new connection to the MQTT broker
    * @param protocol - The protocol to use (mqtt, mqtts, etc)
@@ -116,7 +144,7 @@ export class Client {
   ): Promise<SockConn> {
     // if you need to support alternative connection types just
     // overload this method in your subclass
-    throw `Unsupported protocol: ${protocol}`;
+    throw new Error(`Unsupported protocol: ${protocol}`);
   }
 
   /**
@@ -127,12 +155,13 @@ export class Client {
     if (!this.connectPacket) {
       return;
     }
+
     let isReconnect = false;
     let attempt = 1;
     let lastMessage = new Error();
     let tryConnect = true;
     while (tryConnect) {
-      logger.debug(`${isReconnect ? "re" : ""}connecting`);
+      logger.debug(`${isReconnect ? "re" : ""}connecting, attempt ${attempt}`);
       try {
         const conn = await this.createConn(
           this.url.protocol,
@@ -151,15 +180,23 @@ export class Client {
         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++);
+        assert(
+          err instanceof Error,
+          `Caught something that is not an instance of Error: ${err}`,
+        );
+        queueMicrotask(() => this.onError(err));
+        lastMessage = err;
+        logger.debug({ lastMessage });
+      }
+
+      if (tryConnect && (isReconnect || attempt < this.numberOfRetries)) {
+        await backOffSleep(true, attempt);
+        if (!isReconnect) {
+          attempt++;
         }
+        queueMicrotask(this.onReconnecting);
+      } else {
+        tryConnect = false;
       }
     }
 
@@ -183,6 +220,7 @@ export class Client {
       {
         keepAlive: this.keepAlive,
         clientId: this.clientId,
+        protocolLevel: this.protocolLevel,
       },
       params?.options,
     );
@@ -212,6 +250,7 @@ export class Client {
   async publish(params: PublishParameters): Promise<void> {
     const packet: PublishPacket = {
       type: PacketType.publish,
+      protocolLevel: this.ctx.protocolLevel,
       ...params,
     };
     await this.ctx.publish(packet);
@@ -226,6 +265,7 @@ export class Client {
     const packet: SubscribePacket = {
       type: PacketType.subscribe,
       id: 0, //placeholder
+      protocolLevel: this.ctx.protocolLevel,
       ...params,
     };
     await this.ctx.subscribe(packet);