@seriousme/opifex 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## [Unreleased]
+
+### 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
+
+- added support for NodeJS < 22.0.6 by adding transpiled Javascript in `/dist`
+
+## [v1.1.0] 01-11-2024
+
+### Changed
+
+- added support for NodeJS >= 22.0.6 using --experimental-strip-types
+
+## [v1.0.0] 09-10-2022
+
+Initial version

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

@@ -96,7 +96,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`);
@@ -117,7 +117,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 +129,7 @@ export class Client {
     }
 
     if (isReconnect === false) {
-      this.ctx.unresolvedConnect?.reject(Error(lastMessage));
+      this.ctx.unresolvedConnect?.reject(lastMessage);
     }
   }
 

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,7 +18,7 @@ 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(
@@ -26,7 +27,7 @@ export class TcpClient extends Client {
     caCerts?: string[],
   ) {
     logger.debug({ hostname, port, caCerts });
-    return wrapDenoConn(await Deno.connectTls({ hostname, port, caCerts }));
+    return await Deno.connectTls({ hostname, port, caCerts });
   }
 
   protected override createConn(

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,9 +1,11 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "exports": {
     "./server": "./server/mod.ts",
     "./client": "./client/mod.ts"
   },
-  "exclude": ["dist"]
+  "exclude": [
+    "dist"
+  ]
 }

package/deno.lock

@@ -1,22 +1,9 @@
 {
   "version": "4",
   "specifiers": {
-    "jsr:@std/assert@1.0.2": "1.0.2",
-    "jsr:@std/internal@^1.0.1": "1.0.1",
     "npm:@types/node@*": "22.5.4",
     "npm:@types/node@^22.8.6": "22.8.6"
   },
-  "jsr": {
-    "@std/assert@1.0.2": {
-      "integrity": "ccacec332958126deaceb5c63ff8b4eaf9f5ed0eac9feccf124110435e59e49c",
-      "dependencies": [
-        "jsr:@std/internal"
-      ]
-    },
-    "@std/internal@1.0.1": {
-      "integrity": "6f8c7544d06a11dd256c8d6ba54b11ed870aac6c5aeafff499892662c57673e6"
-    }
-  },
   "npm": {
     "@types/node@22.5.4": {
       "integrity": "sha512-FDuKUJQm/ju9fT/SeX/6+gBzoPzlVCzfzmGkwKvRHQVxi4BntVbyIwf6a4Xn62mrvndLiml6z/UBXIdEVjQLXg==",
@@ -35,9 +22,6 @@
     }
   },
   "workspace": {
-    "dependencies": [
-      "jsr:@std/assert@1.0.2"
-    ],
     "packageJson": {
       "dependencies": [
         "npm:@types/node@^22.8.6"

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}`);