@seriousme/opifex 1.11.2 → 2.0.3

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-2025 Hans Klunder
+Copyright (c) 2023-2026 Hans Klunder
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,21 +6,58 @@
 
 Opifex aims to provide a MQTT server and MQTT client in Typescript to be used
 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.
+[Bun](https://bun.sh). It has _no_ third-party dependencies, it only relies on
+built-in modules.
 
 # Compatibility
 
 The following MQTT versions are supported:
 
-|                | MQTT 3.1 (v3) | MQTT 3.11 (v4) | MQTT 5.0 (v5) |
-| -------------- | ------------- | -------------- | ------------- |
-| Packet/encoder | ✅            | ✅             | ✅            |
-| Client         | ✅            | ✅             | ✅ partially  |
-| Server         | ❌            | ✅             | ❌            |
+|                | MQTT 3.1 (v3) | MQTT 3.1.1 (v4) | MQTT 5.0 (v5)   |
+| -------------- | ------------- | --------------- | --------------- |
+| Packet/encoder | ✅            | ✅              | ✅              |
+| Client         | ✅            | ✅              | ✅ <sup>1</sup> |
+| Server         | ❌            | ✅              | ✅              |
 
-Client and server currently only have memory based persistence, but one can
-provide its own persistence. (see [Architecture](#architecture))
+<sup>1</sup> The client API fully supports MQTTv5, the CLI only supports a
+subset
+
+Version 5 support includes:
+
+- Client Topic Alias ✅
+- Server Topic Alias ✅
+- Subscription Identifiers ✅
+- Subscription options (NoLocal, RetainAsPublished, RetainHandling) ✅
+- Message expiry interval ✅
+- Will delay ✅
+- Assigned Client Identifier ✅
+- Client receive maximum ✅
+- Server receive maximum ✅
+- Shared Subscriptions ✅
+
+# Transports
+
+The following transports are currently supported:
+
+- plain TCP ✅
+- TLS ✅
+- WebSockets ✅ <sup>2</sup>
+
+<sup>2</sup> Deno + Browser only, NodeJS has no native websocket support.
+
+You can add your own transports.
+
+# Persistence
+
+Opifex offers pluggable persistence, but one can provide its own persistence.
+(see [Architecture](#architecture))
+
+The following types are currently provided:
+
+|        | Plugable | Memory | Sqlite |
+| ------ | -------- | ------ | ------ |
+| Client | ✅       | ✅     | ❌     |
+| Server | ✅       | ✅     | ✅     |
 
 ## Usage
 
@@ -35,8 +72,8 @@ 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 transports (e.g. Unix sockets or websocketstream) then it's recommended
-to clone and modify the platform specific code in `/node` or `/deno` as well.
+types of transports (e.g. Unix sockets) then it's recommended to clone and
+modify the platform specific code in `/node` , `/deno` or `/web` 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
@@ -47,20 +84,25 @@ but for historic reasons `/deno` still exists.
 
 ## Example
 
-A simple server example using Deno.
+A simple server example:
 
 ```typescript
-import { MqttServer } from "./server/mod.ts";
-
-const listener = Deno.listen();
-const mqttServer = new MqttServer(mqttOptions);
-for await (const conn of this.listener) {
-  mqttServer.serve(conn);
-}
+import { TcpServer } from "@seriousme/opifex/tcpServer";
+
+const server = new TcpServer({ port: 1883 }, {
+  // just an example of how to configure the server
+  configuration: {
+    context: { maximumConnectPacketSize: 3000 },
+  },
+});
+server.start();
+console.log(
+  `MQTT server running on port: ${server.port}, address: ${server.address}`,
+);
 ```
 
-A more elaborate example including client and server can be found in the
-[examples](/examples/) folder.
+More elaborate examples including client and server, TLS, Websockets and sqlite
+can be found in the [examples](/examples/) folder.
 
 ## Architecture
 
@@ -69,18 +111,18 @@ A more elaborate example including client and server can be found in the
    encode and decode packets.
 
 2. On top of mqttPacket sits the MQTT connection module
-   ([mqttConn/mod.ts](mqttConn/mod.ts)) module that reads packets from a
-   Readable stream and writes them to Writable stream. It will take care of
-   incomplete and/or malformed packets. mqttConn provides an async iterable that
-   can be awaited for new packets.
+   ([mqttConn/mod.ts](mqttConn/mod.ts)) that reads packets from a Readable
+   stream and writes them to Writable stream. It will take care of incomplete
+   and/or malformed packets. mqttConn provides an async iterable that can be
+   awaited for new packets.
 
 3. On top of mqttConn live the MQTT server ([server/mod.ts](server/mod.ts)) and
    MQTT client ([client/mod.ts](client/mod.ts)) that take care of the MQTT
-   protocol handling like requiring an authentication to be successfull before
+   protocol handling like requiring an authentication to be successful before
    another type of packet will be accepted. Both follow a similar model of
    implementation where for each packet that is received a handler is invoked
-   which then triggers the next step. Server and client are totally independ of
-   the technical implementation of the connection and only need a socketConn
+   which then triggers the next step. Server and client are totally independent
+   of the technical implementation of the connection and only need a socketConn
    ([socket](socket)) to be able to work.
 
 4. As the server needs to be able to serve multiple clients at the same time, it
@@ -88,29 +130,46 @@ A more elaborate example including client and server can be found in the
    keep track of its state and associated timers.
 
 5. Persistence of data is handled by a pluggable persistence module
-   ([persistence](persistence)) which currently only offers memory persistence
-   ([persistence/memory](persistence/memory)) but can be extended with database
-   backed persistence supported by third party modules.
+   ([persistence](persistence)) which currently offers single process
+   persistence which you can replace by something more scalable (e.g. redis
+   based clusters etc) This is backed by two storage providers:
+   - [memory](persistence/memory)
+   - [sqlite](persistence/sqlite), based on node:sqlite
+
+   but can be extended with other database backend persistence supported by
+   third-party modules.
+
+6. Server behavior can be customized by passing a
+   [ConfigurationInput object](server/config.ts) via
+   `MqttServerOptions.configuration`, see the example above.
 
-6. The demo server listens to a platform specific socket and runs the `serve()`
+7. The demo server listens to a platform specific socket and runs the `serve()`
    method from the server module on the platform independent streams of every
    connection.
 
-7. The demo client opens a platform specific socket and passes the resulting
+8. The demo client opens a platform specific socket and passes the resulting
    platform independent streams to the client module.
 
 ## Exports
 
-| Export                        | Description                                             |
-| ----------------------------- | ------------------------------------------------------- |
-| @seriousme/opifex/tcpClient   | Exports a MQTT over TCP client                          |
-| @seriousme/opifex/tcpServer   | Exports a MQTT over TCP server                          |
-| @seriousme/opifex/server      | Exports a transport agnostic MQTT server                |
-| @seriousme/opifex/client      | Exports a transport agnostic MQTT client                |
-| @seriousme/opifex/persistence | Exports an Typescript interface for storage persistence |
-| @seriousme/opifex/mqttConn    | Exports MQTT connection handling                        |
-| @seriousme/opifex/mqttPacket  | Exports MQTT packet handling                            |
-| @seriousme/opifex/utils       | Exports various utilities                               |
+| Export                        | Description                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
+| @seriousme/opifex/tcpClient   | Exports a MQTT over TCP/TLS client                           |
+| @seriousme/opifex/tcpServer   | Exports a MQTT over TCP server                               |
+| @seriousme/opifex/tlsServer   | Exports a MQTT over TLS server                               |
+| @seriousme/opifex/wsClient    | Exports a MQTT over Websocket client (deno and browser only) |
+| @seriousme/opifex/wsServer    | Exports a MQTT over Websocket server (deno only)             |
+| @seriousme/opifex/server      | Exports a transport agnostic MQTT server                     |
+| @seriousme/opifex/client      | Exports a transport agnostic MQTT client                     |
+| @seriousme/opifex/persistence | Exports a Typescript interface for storage persistence       |
+| @seriousme/opifex/mqttConn    | Exports MQTT connection handling                             |
+| @seriousme/opifex/mqttPacket  | Exports MQTT packet handling                                 |
+| @seriousme/opifex/utils       | Exports various utilities                                    |
+
+## API docs
+
+The latest API documentation can be found at:
+https://jsr.io/@seriousme/opifex@latest/doc
 
 ## Naming
 

package/bin/conformanceServer.ts

@@ -7,8 +7,14 @@
  */
 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 type {
+  AuthenticatedResult,
+  ConnectPacket,
+  Context,
+  ShareName,
+  Topic,
+} from "../server/mod.ts";
+import { ReasonCode } from "../server/mod.ts";
 import { logger, LogLevel } from "../utils/mod.ts";
 
 /**
@@ -42,35 +48,49 @@ const checkUsername = true;
  * @param {string} clientId - Client identifier
  * @param {string} username - Username to authenticate
  * @param {Uint8Array} password - Password as byte array
- * @returns {TAuthenticationResult} Authentication result
+ * @param {ConnectPacket} connectPacket - The raw connect packet
+ * @returns {IsAuthenticationResult} Authentication result
  */
 function isAuthenticated(
   _ctx: Context,
   clientId: string,
   username: string,
   password: Uint8Array,
-): TAuthenticationResult {
+  connectPacket: ConnectPacket,
+): AuthenticatedResult {
   const pwd = utf8Decoder.decode(password);
   logger.info(
-    `Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`,
+    "Verifying authentication of client",
+    clientId,
+    "with username",
+    username,
+  );
+  logger.debug(
+    "Client",
+    clientId,
+    "connecting with protocol level",
+    connectPacket.protocolLevel,
   );
 
   if (!checkUsername) {
     // allow all users access
-    return AuthenticationResult.ok;
+    return { reasonCode: ReasonCode.success };
   }
   // is the username valid according to MQTT specification
   if (!strictUsername.test(username)) {
-    return AuthenticationResult.badUsernameOrPassword;
+    return { reasonCode: ReasonCode.badUserNameOrPassword };
   }
   // Does user and password match an entry in userTable
   if (userTable.has(username)) {
     const pass = userTable.get(username);
     if (pwd === pass) {
-      return AuthenticationResult.ok;
+      return { reasonCode: ReasonCode.success };
     }
   }
-  return AuthenticationResult.notAuthorized;
+  return {
+    reasonCode: ReasonCode.notAuthorized,
+    reasonString: "Authentication failed",
+  };
 }
 
 /**
@@ -81,7 +101,10 @@ function isAuthenticated(
  */
 function isAuthorizedToPublish(ctx: Context, topic: Topic): boolean {
   logger.debug(
-    `Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`,
+    "Checking authorization of client",
+    ctx.clientId,
+    "to publish on topic",
+    topic,
   );
   return true;
 }
@@ -92,9 +115,18 @@ function isAuthorizedToPublish(ctx: Context, topic: Topic): boolean {
  * @param {Topic} topic - Topic to subscribe to
  * @returns {boolean} True if authorized
  */
-function isAuthorizedToSubscribe(ctx: Context, topic: Topic): boolean {
+function isAuthorizedToSubscribe(
+  ctx: Context,
+  topic: Topic,
+  shareName: ShareName,
+): boolean {
   logger.debug(
-    `Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`,
+    "Checking authorization of client",
+    ctx.clientId,
+    "to subscribe to topic",
+    topic,
+    "using shareName",
+    shareName,
   );
   return true;
 }
@@ -118,4 +150,4 @@ const tcpServer = new TcpServer({ port, hostname }, {
   },
 });
 tcpServer.start();
-logger.info(`Server started on port ${tcpServer.port}`);
+logger.info("Server started on port", tcpServer.port);

package/bin/demoServer.ts

@@ -6,8 +6,14 @@
  */
 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 type {
+  AuthenticatedResult,
+  ConnectPacket,
+  Context,
+  ShareName,
+  Topic,
+} from "../server/mod.ts";
+import { ReasonCode } from "../server/mod.ts";
 import { logger, LogLevel } from "../utils/mod.ts";
 
 /**
@@ -41,35 +47,42 @@ const checkUsername = false;
  * @param {string} clientId - Client identifier
  * @param {string} username - Username to authenticate
  * @param {Uint8Array} password - Password as byte array
- * @returns {TAuthenticationResult} Authentication result
+ * @returns {IsAuthenticationResult} Authentication result
  */
 function isAuthenticated(
   _ctx: Context,
   clientId: string,
   username: string,
   password: Uint8Array,
-): TAuthenticationResult {
+  connectPacket: ConnectPacket,
+): AuthenticatedResult {
   const pwd = utf8Decoder.decode(password);
   logger.info(
-    `Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`,
+    `Verifying authentication of client '${clientId}' with username '${username}'`,
+  );
+  logger.debug(
+    `Client '${clientId}' connecting with protocol level ${connectPacket.protocolLevel}`,
   );
 
   if (!checkUsername) {
     // allow all users access
-    return AuthenticationResult.ok;
+    return { reasonCode: ReasonCode.success };
   }
   // is the username valid according to MQTT specification
   if (!strictUsername.test(username)) {
-    return AuthenticationResult.badUsernameOrPassword;
+    return { reasonCode: ReasonCode.badUserNameOrPassword };
   }
   // Does user and password match an entry in userTable
   if (userTable.has(username)) {
     const pass = userTable.get(username);
     if (pwd === pass) {
-      return AuthenticationResult.ok;
+      return { reasonCode: ReasonCode.success };
     }
   }
-  return AuthenticationResult.notAuthorized;
+  return {
+    reasonCode: ReasonCode.notAuthorized,
+    reasonString: "Authentication failed",
+  };
 }
 
 /**
@@ -80,7 +93,10 @@ function isAuthenticated(
  */
 function isAuthorizedToPublish(ctx: Context, topic: Topic): boolean {
   logger.debug(
-    `Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`,
+    "Checking authorization of client",
+    ctx.clientId,
+    "to publish on topic",
+    topic,
   );
   return true;
 }
@@ -91,9 +107,18 @@ function isAuthorizedToPublish(ctx: Context, topic: Topic): boolean {
  * @param {Topic} topic - Topic to subscribe to
  * @returns {boolean} True if authorized
  */
-function isAuthorizedToSubscribe(ctx: Context, topic: Topic): boolean {
+function isAuthorizedToSubscribe(
+  ctx: Context,
+  topic: Topic,
+  shareName: ShareName,
+): boolean {
   logger.debug(
-    `Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`,
+    "Checking authorization of client",
+    ctx.clientId,
+    "to subscribe to topic",
+    topic,
+    "using shareName",
+    shareName,
   );
   return true;
 }
@@ -117,4 +142,4 @@ const tcpServer = new TcpServer({ port, hostname }, {
   },
 });
 tcpServer.start();
-logger.info(`Server started on port ${tcpServer.port}`);
+logger.info("Server started on port", tcpServer.port);

package/bin/mqtt.ts

@@ -37,16 +37,26 @@ import {
   DEFAULT_PROTOCOLLEVEL,
   DEFAULT_URL,
 } from "../client/mod.ts";
-import type { ProtocolLevel } from "../client/mod.ts";
+import type { ProtocolLevel, QoS } from "../client/mod.ts";
 import { getFileData, TcpClient } from "../node/tcpClient.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();
 logger.level(LogLevel.info);
 
+// --- TypeScript Utility Types to Derive Args Natively ---
+type MapOptType<T> = T extends { type: "string" } ? string | undefined
+  : T extends { type: "boolean" } ? boolean
+  : never;
+
+type ParsedArgsFromOpts<
+  T extends Record<string, { type: "string" | "boolean" }>,
+> = {
+  [K in keyof T]: MapOptType<T[K]>;
+};
+
 const MQTTHelp = `MQTT command line interface, available commands are:
 
     * publish     publish a message to the broker
@@ -94,7 +104,9 @@ const connectOpts = {
   help: { type: "boolean", short: "h", default: false },
 } as const;
 
-async function connect(connectArgs: Args) {
+type ConnectArgs = ParsedArgsFromOpts<typeof connectOpts>;
+
+async function connect(connectArgs: ConnectArgs) {
   const {
     caCerts,
     cert,
@@ -111,25 +123,24 @@ async function connect(connectArgs: Args) {
       clientId: connectArgs.clientId as string,
       clean: !connectArgs.noClean,
       keepAlive: Number(connectArgs.keepAlive),
-      protocolLevel: parseInt(
-        connectArgs.mqttVersion as string,
-      ) as ProtocolLevel,
+      protocolLevel: parseProtocolLevel(connectArgs.mqttVersion),
     },
   });
   logger.debug("Connected !");
 }
 
-function parseQos(qosArg: string | number) {
+function parseProtocolLevel(mqttVersion: string | undefined): ProtocolLevel {
+  const result = parseInt(mqttVersion ?? "");
+  if (result >= 3 && result <= 5) {
+    return result as ProtocolLevel;
+  }
+  return DEFAULT_PROTOCOLLEVEL;
+}
+
+function parseQos(qosArg: string | number | undefined): QoS {
   const qos = Number(qosArg);
-  switch (qos) {
-    case 0:
-      return 0;
-    case 1:
-      return 1;
-    case 2:
-      return 2;
-    default:
-      break;
+  if (qos === 0 || qos === 1 || qos === 2) {
+    return qos;
   }
   console.log("QoS must be between 0 and 2");
   return 0;
@@ -142,14 +153,17 @@ function safeParseArgs(config: ParseArgsConfig) {
     if (err instanceof Error) {
       console.error(err.message);
     }
+    return undefined;
   }
 }
 
-async function getTLSdata(connectArgs: Args) {
-  const caFileData = await getFileData(connectArgs.caFile as string);
+async function getTLSdata(connectArgs: Partial<ConnectArgs>) {
+  const caFileData = connectArgs.caFile
+    ? await getFileData(connectArgs.caFile)
+    : undefined;
   const caCerts = caFileData ? [caFileData] : undefined;
-  const cert = await getFileData(connectArgs.certFile as string);
-  const key = await getFileData(connectArgs.keyFile as string);
+  const cert = await getFileData(connectArgs.certFile);
+  const key = await getFileData(connectArgs.keyFile);
   return {
     caCerts,
     cert,
@@ -177,13 +191,18 @@ const subscribeOpts = {
   qos: { type: "string", short: "q", default: "0" },
 } as const;
 
+type SubscribeArgs = ParsedArgsFromOpts<
+  typeof connectOpts & typeof subscribeOpts
+>;
+
 async function subscribe() {
   const res = safeParseArgs({
     options: { ...connectOpts, ...subscribeOpts },
     allowPositionals: true,
   });
   if (!res) return;
-  const subscribeArgs = res.values as Record<string, string | boolean>;
+
+  const subscribeArgs = res.values as unknown as SubscribeArgs;
   if (subscribeArgs.help) {
     console.log(SubscribeHelp);
     return;
@@ -198,7 +217,7 @@ async function subscribe() {
       subscriptions: [
         {
           topicFilter: subscribeArgs.topic,
-          qos: parseQos(subscribeArgs.qos as string),
+          qos: parseQos(subscribeArgs.qos),
         },
       ],
     });
@@ -209,8 +228,8 @@ async function subscribe() {
     }
   } 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 errorWithCode = err as Error & { code?: string };
+      logger.info("Error:", errorWithCode.message || errorWithCode.code);
     }
   }
 }
@@ -232,13 +251,16 @@ const publishOpts = {
   retain: { type: "boolean", short: "r", default: false },
 } as const;
 
+type PublishArgs = ParsedArgsFromOpts<typeof connectOpts & typeof publishOpts>;
+
 async function publish() {
   const res = safeParseArgs({
     options: { ...connectOpts, ...publishOpts },
     allowPositionals: true,
   });
   if (!res) return;
-  const publishArgs = res.values as Record<string, string | boolean>;
+
+  const publishArgs = res.values as unknown as PublishArgs;
   if (publishArgs.help) {
     console.log(PublishHelp);
     return;
@@ -251,17 +273,17 @@ async function publish() {
     await connect(publishArgs);
     await client.publish({
       topic: publishArgs.topic,
-      payload: encoder.encode(publishArgs.message as string),
-      retain: publishArgs.retain as boolean,
-      qos: parseQos(publishArgs.qos as string),
+      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}`);
+      const errorWithCode = err as Error & { code?: string };
+      logger.info("Error:", errorWithCode.message || errorWithCode.code);
     }
   }
 }

package/client/ConnectionState.ts

@@ -13,6 +13,8 @@ export const ConnectionState = {
   disconnecting: "disconnecting",
   /** System has been disconnected */
   disconnected: "disconnected",
+  /** System is authenticating mid session */
+  authenticating: "authenticating",
 } as const;
 
 /**