@seriousme/opifex 1.2.1 → 1.4.0

package/.github/workflows/update-license-year.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+
+license='LICENSE.txt'
+prefix='2016-'
+current_year=$(date +%Y)
+sed -i -e "s/$prefix\([0-9\]\+\)/$prefix$current_year/" $license
+
+if [ "$(git diff $license)" ]; then
+  git add $license
+  git commit -m "Update license year to $current_year"
+  git push
+else
+  echo "No changes detected in $license"
+fi

package/.github/workflows/update-license-year.yml

@@ -0,0 +1,13 @@
+name: Update License Year
+
+on:
+  schedule:
+    - cron: "5 12 1 1 *"
+
+jobs:
+  update_license:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Update license year
+        run: ./update_license.sh

package/CHANGELOG.md

@@ -4,6 +4,22 @@
 
 ### Changed
 
+## [v1.3.0] 19-11-2024
+
+### Changed
+
+- update: added architectural description of Opifex to documentation
+- update: added comments to platform specific code to explain boundary between
+  platform agnostic and platform specific.
+- update: set default clientId in client
+- fix: improve handling of errors if client connect fails
+
+## [v1.2.1] 01-11-2024
+
+### Changed
+
+- fix: unlock last BYOB request using respond(0)
+
 ## [v1.2.0] 01-11-2024
 
 ### Changed

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Hans Klunder
+Copyright (c) 2023-2025 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

@@ -10,14 +10,82 @@ 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.
 
-There are separate usage instructions for:
+## Example
+
+A simple server example using Deno, for more elaborate examples see the Usage
+section below.
+
+```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);
+}
+```
+
+## Architecture
+
+1. The basis of Opifex is the MQTT packet module
+   ([mqttPacket/mod.ts](mqttPacket/mod.ts)) which contains al the logic to
+   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.
+
+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
+   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
+   ([socket](socket)) to be able to work.
+
+4. As the server needs to be able to serve multiple clients at the same time, it
+   maintains a context ([server/context.ts](server/context.ts)) per client to
+   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.
+
+6. 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
+   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)
 
-The client and server libs should also work on Bun as they are engine
-independent, but the demo server and client currently do not work on Bun because
-of some socket incompatibilities between Bun and the rest.
+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 (e.g. Bun) then the platform specific code in `/node` or `/deno` might
+serve as inspiration.
+
+The platform independent client and server libs should also work on Bun as they
+are engine independent, but the demo server and client currently do not work on
+Bun because of some socket incompatibilities between Bun and the rest.
 
 ## Naming
 

package/bin/conformanceServer.ts

@@ -5,7 +5,7 @@ import { AuthenticationResult } from "../server/mod.ts";
 import type { Context, TAuthenticationResult, Topic } from "../server/mod.ts";
 import { logger, LogLevel } from "../utils/mod.ts";
 import { getArgs, parseArgs } from "../utils/mod.ts";
-import { TcpServer } from "../deno/server.ts";
+import { TcpServer } from "../node/server.ts";
 
 const utf8Decoder = new TextDecoder();
 const userTable = new Map();

package/bin/mqtt.ts

@@ -40,6 +40,7 @@ const connectOpts = {
   boolean: ["noClean", "help"],
   default: {
     noClean: false,
+    clientId: `Opifex-${crypto.randomUUID()}`,
   },
 };
 
@@ -120,7 +121,8 @@ async function subscribe() {
     }
   } catch (err) {
     if (err instanceof Error) {
-      logger.info(err.message);
+      // @ts-ignore the type spec of err is missing err.code
+      logger.info(`Error: ${err.message || err.code}`);
     }
   }
 }
@@ -188,7 +190,8 @@ async function publish() {
     logger.debug("Disconnected !");
   } catch (err) {
     if (err instanceof Error) {
-      logger.info(err.message);
+      // @ts-ignore the type spec of err is missing err.code
+      logger.info(`Error: ${err.message || err.code}`);
     }
   }
 }

package/client/client.ts

@@ -25,6 +25,8 @@ type ConnectOptions = Omit<
 export type ConnectParameters = {
   url?: URL;
   caCerts?: string[];
+  cert?: string;
+  key?: string;
   numberOfRetries?: number;
   options?: ConnectOptions;
 };
@@ -70,6 +72,8 @@ export class Client {
   protected keepAlive = DEFAULT_KEEPALIVE;
   protected autoReconnect = true;
   private caCerts?: string[];
+  private cert?: string;
+  private key?: string;
   private clientId: string;
   private ctx = new Context(new MemoryStore());
   private connectPacket?: ConnectPacket;
@@ -84,6 +88,8 @@ export class Client {
     _hostname: string,
     _port?: number,
     _caCerts?: string[],
+    _cert?: string,
+    _key?: string,
   ): Promise<SockConn> {
     // if you need to support alternative connection types just
     // overload this method in your subclass
@@ -96,7 +102,7 @@ export class Client {
     }
     let isReconnect = false;
     let attempt = 1;
-    let lastMessage = "";
+    let lastMessage = new Error();
     let tryConnect = true;
     while (tryConnect) {
       logger.debug(`${isReconnect ? "re" : ""}connecting`);
@@ -106,6 +112,8 @@ export class Client {
           this.url.hostname,
           Number(this.url.port) ?? undefined,
           this.caCerts,
+          this.cert,
+          this.key,
         );
         // if we get this far we have a connection
         tryConnect =
@@ -117,7 +125,7 @@ export class Client {
         this.ctx.close();
       } catch (err) {
         if (err instanceof Error) {
-          lastMessage = `Connection failed: ${err.message}`;
+          lastMessage = err;
         }
         logger.debug(lastMessage);
         if (!isReconnect && attempt > this.numberOfRetries) {
@@ -129,7 +137,7 @@ export class Client {
     }
 
     if (isReconnect === false) {
-      this.ctx.unresolvedConnect?.reject(Error(lastMessage));
+      this.ctx.unresolvedConnect?.reject(lastMessage);
     }
   }
 
@@ -137,6 +145,8 @@ export class Client {
     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,

package/client/context.ts

@@ -91,8 +91,10 @@ export class Context {
     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);
       }

package/client/mod.ts

@@ -1,6 +1,5 @@
 /**
- *  This module provides an MQTT Client interface
- *  see the /bin folder for examples
+ *  This module provides an MQTT Client interface see the /bin folder for examples
  *  @module
  */
 export { Client, DEFAULT_URL } from "./client.ts";

package/deno/client.ts

@@ -1,6 +1,7 @@
+// This a Deno specific implementation of TCP client sockets
+// it extends the platform agnostic Client class
 import { Client } from "../client/client.ts";
 import { logger } from "../client/deps.ts";
-import { wrapDenoConn } from "./wrapDenoConn.ts";
 import type { SockConn } from "../client/deps.ts";
 
 export async function getCaCerts(filename: string | undefined) {
@@ -17,16 +18,18 @@ export async function getCaCerts(filename: string | undefined) {
 export class TcpClient extends Client {
   protected async connectMQTT(hostname: string, port = 1883) {
     logger.debug({ hostname, port });
-    return wrapDenoConn(await Deno.connect({ hostname, port }));
+    return await Deno.connect({ hostname, port });
   }
 
   protected async connectMQTTS(
     hostname: string,
     port = 8883,
     caCerts?: string[],
+    cert?: string,
+    key?: string,
   ) {
-    logger.debug({ hostname, port, caCerts });
-    return wrapDenoConn(await Deno.connectTls({ hostname, port, caCerts }));
+    logger.debug({ hostname, port, caCerts, cert });
+    return await Deno.connectTls({ hostname, port, caCerts, cert, key });
   }
 
   protected override createConn(
@@ -34,11 +37,13 @@ export class TcpClient extends Client {
     hostname: string,
     port?: number,
     caCerts?: string[],
+    cert?: string,
+    key?: string,
   ): Promise<SockConn> {
     // if you need to support alternative connection types just
     // overload this method in your subclass
     if (protocol === "mqtts:") {
-      return this.connectMQTTS(hostname, port, caCerts);
+      return this.connectMQTTS(hostname, port, caCerts, cert, key);
     }
     if (protocol === "mqtt:") {
       return this.connectMQTT(hostname, port);

package/deno/server.ts

@@ -1,6 +1,7 @@
+// This a Deno specific implementation of a TCP socket listener
+// it uses the platform agnostic MqttServer class
 import { MqttServer } from "../server/mod.ts";
 import type { MqttServerOptions } from "../server/mod.ts";
-import { wrapDenoConn } from "./wrapDenoConn.ts";
 
 export class TcpServer {
   private listener: Deno.Listener<Deno.Conn>;
@@ -15,7 +16,7 @@ export class TcpServer {
 
   async start() {
     for await (const conn of this.listener) {
-      this.mqttServer.serve(wrapDenoConn(conn));
+      this.mqttServer.serve(conn);
     }
   }
   stop() {

package/deno.json

@@ -1,8 +1,11 @@
 {
   "name": "@seriousme/opifex",
+  "version": "1.4.0",
   "exports": {
     "./server": "./server/mod.ts",
     "./client": "./client/mod.ts"
   },
-  "exclude": ["dist"]
+  "exclude": [
+    "dist"
+  ]
 }

package/deno.lock

@@ -2,29 +2,32 @@
   "version": "4",
   "specifiers": {
     "npm:@types/node@*": "22.5.4",
-    "npm:@types/node@^22.8.6": "22.8.6"
+    "npm:@types/node@^22.10.0": "22.10.0"
   },
   "npm": {
-    "@types/node@22.5.4": {
-      "integrity": "sha512-FDuKUJQm/ju9fT/SeX/6+gBzoPzlVCzfzmGkwKvRHQVxi4BntVbyIwf6a4Xn62mrvndLiml6z/UBXIdEVjQLXg==",
+    "@types/node@22.10.0": {
+      "integrity": "sha512-XC70cRZVElFHfIUB40FgZOBbgJYFKKMa5nb9lxcwYstFG/Mi+/Y0bGS+rs6Dmhmkpq4pnNiLiuZAbc02YCOnmA==",
       "dependencies": [
-        "undici-types"
+        "undici-types@6.20.0"
       ]
     },
-    "@types/node@22.8.6": {
-      "integrity": "sha512-tosuJYKrIqjQIlVCM4PEGxOmyg3FCPa/fViuJChnGeEIhjA46oy8FMVoF9su1/v8PNs2a8Q0iFNyOx0uOF91nw==",
+    "@types/node@22.5.4": {
+      "integrity": "sha512-FDuKUJQm/ju9fT/SeX/6+gBzoPzlVCzfzmGkwKvRHQVxi4BntVbyIwf6a4Xn62mrvndLiml6z/UBXIdEVjQLXg==",
       "dependencies": [
-        "undici-types"
+        "undici-types@6.19.8"
       ]
     },
     "undici-types@6.19.8": {
       "integrity": "sha512-ve2KP6f/JnbPBFyobGHuerC9g1FYGn/F8n1LWTwNxCEzd6IfqTwUQcNXgEtmmQ6DlRrC1hrSrBnCZPokRrDHjw=="
+    },
+    "undici-types@6.20.0": {
+      "integrity": "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="
     }
   },
   "workspace": {
     "packageJson": {
       "dependencies": [
-        "npm:@types/node@^22.8.6"
+        "npm:@types/node@^22.10.0"
       ]
     }
   }

package/dev_utils/dummyConn.ts

@@ -68,7 +68,7 @@ function ReadableStreamFrom(
 export function makeDummySockConn(
   readerBuffs: Uint8Array[],
   writerBuf: Uint8Array,
-  closer = () => {},
+  close = () => {},
 ) {
   const readBlob = new Blob(readerBuffs);
   const readable = readBlob.stream();
@@ -76,20 +76,20 @@ export function makeDummySockConn(
   return {
     readable,
     writable,
-    closer,
+    close,
   };
 }
 
 export function makeDummyQueueSockConn(
   r: AsyncQueue<Uint8Array>,
   w: AsyncQueue<Uint8Array>,
-  closer = () => {},
+  close = () => {},
 ) {
   const readable = ReadableStreamFrom(r);
   const writable = new WritableStream(new Uint8QueuedWriter(w));
   return {
     readable,
     writable,
-    closer,
+    close,
   };
 }

package/dist/bin/conformanceServer.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env -S node --experimental-strip-types
+// this server is intended to be used with https://github.com/eclipse/iottestware
+import { AuthenticationResult } from "../server/mod.js";
+import { logger, LogLevel } from "../utils/mod.js";
+import { getArgs, parseArgs } from "../utils/mod.js";
+import { TcpServer } from "../node/server.js";
+const utf8Decoder = new TextDecoder();
+const userTable = new Map();
+userTable.set("IoTester_1", "strong_password");
+userTable.set("IoTester_2", "strong_password");
+const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
+const notAuthorizedTable = new Set();
+notAuthorizedTable.add(["123-456-789", "eclipse/iot/tesware/0data"]);
+function isAuthenticated(_ctx, clientId, username, password) {
+    const pwd = utf8Decoder.decode(password);
+    logger.debug(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
+    if (!userTable.has(username)) {
+        if (!strictUsername.test(username)) {
+            return AuthenticationResult.badUsernameOrPassword;
+        }
+    }
+    const pass = userTable.get(username);
+    if (pwd === pass) {
+        return AuthenticationResult.ok;
+    }
+    return AuthenticationResult.notAuthorized;
+}
+function isAuthorizedToPublish(ctx, topic) {
+    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`);
+    // if (notAuthorizedTable.has([ctx.client,topic])){
+    //   return false;
+    // }
+    return true;
+}
+function isAuthorizedToSubscribe(ctx, topic) {
+    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`);
+    return true;
+}
+/** start the server **/
+const { _: [portNum] } = parseArgs(getArgs());
+const port = Number(portNum ?? 1883);
+const hostname = "::";
+logger.level(LogLevel.info);
+const tcpServer = new TcpServer({ port, hostname }, {
+    handlers: {
+        isAuthenticated,
+        isAuthorizedToPublish,
+        isAuthorizedToSubscribe,
+    },
+});
+tcpServer.start();
+logger.info(`Server started on port ${tcpServer.port}`);

package/dist/bin/demoServer.js

@@ -1,74 +1,46 @@
-#!/usr/bin/env node
-import { createServer } from "node:net";
-import {
-  A as AuthenticationResult,
-  L as LogLevel,
-  l as logger,
-} from "../timer-DDWVNsyG.js";
-import "node:process";
-import { MqttServer } from "../server/mod.js";
-import {
-  g as getArgs,
-  p as parseArgs,
-  w as wrapNodeSocket,
-} from "../wrapNodeSocket-BAJm059T.js";
-import "node:stream";
-
-class TcpServer {
-  mqttServer;
-  server;
-  serverOptions;
-  constructor(serverOptions, mqttOptions) {
-    this.mqttServer = new MqttServer(mqttOptions);
-    this.serverOptions = serverOptions;
-  }
-  start() {
-    this.server = createServer(
-      (sock) => this.mqttServer.serve(wrapNodeSocket(sock)),
-    );
-    this.server.listen(this.serverOptions.port, this.serverOptions.hostname);
-  }
-  stop() {
-    this.server?.close();
-  }
-  get port() {
-    return this.serverOptions.port;
-  }
-}
-
+#!/usr/bin/env -S node --experimental-strip-types
+import { TcpServer } from "../node/server.js";
+import { AuthenticationResult } from "../server/mod.js";
+import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
 const utf8Decoder = new TextDecoder();
-const userTable = /* @__PURE__ */ new Map();
+const userTable = new Map();
 userTable.set("IoTester_1", "strong_password");
 userTable.set("IoTester_2", "strong_password");
+// const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
 function isAuthenticated(_ctx, clientId, username, password) {
-  const pwd = utf8Decoder.decode(password);
-  logger.info(
-    `Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`,
-  );
-  return AuthenticationResult.ok;
+    const pwd = utf8Decoder.decode(password);
+    logger.info(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
+    return AuthenticationResult.ok;
+    // if (!userTable.has(username)) {
+    //   if (!strictUsername.test(username)) {
+    //     return AuthenticationResult.badUsernameOrPassword;
+    //   }
+    // }
+    // const pass = userTable.get(username);
+    // if (pwd === pass) {
+    //   return AuthenticationResult.ok;
+    // }
+    // return AuthenticationResult.badUsernameOrPassword;
 }
 function isAuthorizedToPublish(ctx, topic) {
-  logger.debug(
-    `Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`,
-  );
-  return true;
+    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`);
+    return true;
 }
 function isAuthorizedToSubscribe(ctx, topic) {
-  logger.debug(
-    `Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`,
-  );
-  return true;
+    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`);
+    return true;
 }
+/** start the server **/
 const { _: [portNum] } = parseArgs(getArgs());
 const port = Number(portNum ?? 1883);
 const hostname = "::";
 logger.level(LogLevel.info);
 const tcpServer = new TcpServer({ port, hostname }, {
-  handlers: {
-    isAuthenticated,
-    isAuthorizedToPublish,
-    isAuthorizedToSubscribe,
-  },
+    handlers: {
+        isAuthenticated,
+        isAuthorizedToPublish,
+        isAuthorizedToSubscribe,
+    },
 });
 tcpServer.start();
 logger.info(`Server started on port ${tcpServer.port}`);