@seriousme/opifex 2.1.0 → 2.3.0

package/examples/mqtt.test.ts

@@ -30,7 +30,7 @@ test("Test pubSub using TCP client and server using memoryPersistence", async fu
 
   const client = new TcpClient();
   await client.connect(params);
-  logger.info("Client connected to server at", client.url);
+  logger.info("Client connected to server at", client.url.toString());
 
   const publishSet: { topic: string; qos: QoS }[] = [
     { topic: "t0@q0", qos: 0 },
@@ -85,5 +85,5 @@ test("Test pubSub using TCP client and server using memoryPersistence", async fu
   }
 
   logger.info("Stop server");
-  server.stop();
+  await server.stop();
 });

package/examples/mqtts.test.ts

@@ -41,7 +41,7 @@ test("Test pubSub using TLS client and server and sqlitePersistence", async func
 
   const client = new TcpClient();
   await client.connect(params);
-  logger.info("Client connected to server at", client.url);
+  logger.info("Client connected to server at", client.url.toString());
 
   const publishSet: { topic: string; qos: QoS }[] = [
     { topic: "t0@q0", qos: 0 },
@@ -96,5 +96,5 @@ test("Test pubSub using TLS client and server and sqlitePersistence", async func
   }
 
   logger.info("Stop server");
-  server.stop();
+  await server.stop();
 });

package/examples/webSocket.test.ts

@@ -1,8 +1,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { delay, logger, LogLevel } from "@seriousme/opifex/utils";
-
-import type { PublishPacket, QoS } from "@seriousme/opifex/mqttPacket";
+import { logger, LogLevel } from "@seriousme/opifex/utils";
+import { runTest } from "./public/testRunner.js";
 
 logger.level(LogLevel.info);
 
@@ -27,68 +26,15 @@ test("Deno: Test pubSub using WebSocket client and server and memoryPersistence"
       ? "127.0.0.1"
       : server.address;
 
-    const params = {
-      url: new URL(`ws://${hostname}:${server.port}`),
-      numberOfRetries: 0,
-    };
-
-    const client = new WsClient();
-    await client.connect(params);
-    logger.info("Client connected to server at", client.url);
-
-    const publishSet: { topic: string; qos: QoS }[] = [
-      { topic: "t0@q0", qos: 0 },
-      { topic: "t1@q0", qos: 0 },
-      { topic: "t2@q0", qos: 0 },
-      { topic: "t0@q1", qos: 1 },
-      { topic: "t1@q1", qos: 1 },
-      { topic: "t2@q1", qos: 1 },
-      { topic: "t0@q2", qos: 2 },
-      { topic: "t1@q2", qos: 2 },
-      { topic: "t2@q2", qos: 2 },
-    ];
-
-    const subscriptions = publishSet.map((item) => ({
-      topicFilter: item.topic,
-      qos: item.qos,
-    }));
-    await client.subscribe({
-      subscriptions,
+    await runTest({
+      WsClient,
+      protocol: "ws",
+      hostname,
+      port: server.port,
+      logger: logger.verbose,
+      assert,
     });
-
-    // the IIFE ensures message reception runs in parallel
-    logger.info("Start receiving");
-    const received: PublishPacket[] = [];
-    (async function () {
-      for await (const item of client.messages()) {
-        logger.verbose("Receiving:", item.topic, "--", item.qos);
-        received.push(item);
-      }
-    })();
-    // end of IIFE
-    for (const item of publishSet) {
-      logger.verbose("Publishing:", item.topic, "--", item.qos);
-      await client.publish({
-        topic: item.topic,
-        qos: item.qos,
-        payload: new Uint8Array([0x01]),
-      });
-    }
-
-    await delay(100);
-    logger.info("Disconnect client");
-    await client.disconnect();
-
-    logger.info("Check completeness");
-    for (const item of publishSet) {
-      const found = received.find((f) =>
-        f.topic == item.topic && f.qos === item.qos
-      );
-      logger.verbose("Found:", item.topic, "--", item.qos);
-      assert(found, `${item.topic} -- ${item.qos}`);
-    }
-
     logger.info("Stop server");
-    server.stop();
+    await server.stop();
   }
 });

package/examples/webSocketServer.ts

@@ -0,0 +1,98 @@
+/**
+ * a simple websocket server to verify browser compatibility
+ */
+import { extname, join, resolve } from "node:path";
+import { logger } from "@seriousme/opifex/utils";
+import { MqttServer } from "@seriousme/opifex/server";
+import { mqttOverWS } from "@seriousme/opifex/wsServer";
+import { LogLevel } from "@seriousme/opifex/utils";
+import type { RequestHandler } from "@seriousme/opifex/wsServer";
+
+logger.level(LogLevel.info);
+
+// Nodejs does not natively support WebSockets so we only continue running Deno
+if (typeof Deno === "undefined") {
+  logger.error("Native WebSocket server only supported on Deno");
+  process.exit(1);
+}
+const currentDir = import.meta.dirname || "./";
+const PUBLIC_DIR = resolve(join(currentDir, "/public"));
+const listenOptions = { port: 8080 };
+const mqttOptions = {};
+const mqttServer = new MqttServer(mqttOptions);
+
+const mimeTypes = new Map<string, string>([
+  [".html", "text/html; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+]);
+
+function w3cLogger(handler: RequestHandler): RequestHandler {
+  return async (req, info) => {
+    const res = await handler(req, info);
+    const hostname = res.headers.get("upgrade")
+      ? "unknown"
+      : info.remoteAddr.hostname;
+    logger.info(W3CLogLine(req, res, hostname));
+    return res;
+  };
+}
+
+function W3CLogLine(req: Request, res: Response, hostname: string): string {
+  const now = new Date();
+
+  // format date to UTC (YYYY-MM-DD en HH:MM:SS)
+  const date = now.toISOString().split("T")[0];
+  const time = now.toISOString().split("T")[1]?.substring(0, 8);
+
+  const url = new URL(req.url);
+  const clientIp = hostname ?? "127.0.0.1";
+  const method = req.method;
+  const uriStem = url.pathname;
+  const uriQuery = url.search ? url.search : "-";
+  const status = res.status;
+  const bytesSent = res.headers.get("content-length") ?? "-";
+
+  return `${date} ${time} ${clientIp} ${method} ${uriStem} ${uriQuery} ${status} ${bytesSent}`;
+}
+
+const requestHandler: RequestHandler = async (req) => {
+  const url = new URL(req.url);
+
+  const pathname = url.pathname.endsWith("/")
+    ? url.pathname + "index.html"
+    : url.pathname;
+
+  const ext = extname(pathname);
+  const mimeType = mimeTypes.get(ext) ?? "application/octet-stream";
+
+  const targetPath = resolve(join(PUBLIC_DIR, pathname));
+  logger.debug({ targetPath });
+
+  try {
+    if (!targetPath.startsWith(PUBLIC_DIR)) {
+      // someone is trying to escape the public folder
+      return new Response("403 Forbidden", { status: 403 });
+    }
+
+    const file = await Deno.readFile(targetPath);
+    return new Response(file, {
+      status: 200,
+      headers: {
+        "content-type": mimeType,
+      },
+    });
+  } catch (err) {
+    if (err instanceof Deno.errors.NotFound) {
+      return new Response("404 Not Found", { status: 404 });
+    }
+    return new Response("500 Internal Server Error", { status: 500 });
+  }
+};
+
+const server = Deno.serve(
+  listenOptions,
+  w3cLogger(mqttOverWS(mqttServer, "/mqtt", requestHandler)),
+);
+
+await server.finished;

package/mqttConn/mqttConn.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { createMockSockConn } from "../dev_utils/mod.ts";
+import { createMockConn } from "../dev_utils/mod.ts";
 import { encode, MQTTLevel, PacketType } from "../mqttPacket/mod.ts";
 import { MqttConn, MqttConnError } from "./mqttConn.ts";
 import type { AnyPacket, CodecOpts } from "../mqttPacket/mod.ts";
@@ -50,7 +50,7 @@ test("MqttConn should act as asyncIterator", async () => {
   const publish = encode(publishPacket, codecOptsV4);
   const disconnect = encode(disconnectPacket, codecOptsV4);
 
-  const conn = createMockSockConn(
+  const conn = createMockConn(
     [connect, publish, disconnect],
     new Uint8Array(),
   );
@@ -68,7 +68,7 @@ test("MqttConn should act as asyncIterator", async () => {
 });
 
 test("MqttConn should close on malformed length", async () => {
-  const conn = createMockSockConn([new Uint8Array([1, 175])], new Uint8Array());
+  const conn = createMockConn([new Uint8Array([1, 175])], new Uint8Array());
   const mqttConn = new MqttConn({ conn });
 
   const packets: AnyPacket[] = [];
@@ -86,7 +86,7 @@ test("MqttConn should close on failed packets", async () => {
   const publish = encode(publishPacket, codecOptsV4);
   const brokenPublish = publish.slice(0, 7);
 
-  const conn = createMockSockConn([connect, brokenPublish], new Uint8Array());
+  const conn = createMockConn([connect, brokenPublish], new Uint8Array());
   const mqttConn = new MqttConn({ conn });
 
   const packets: AnyPacket[] = [];
@@ -103,7 +103,7 @@ test("MqttConn should close on failed packets", async () => {
 test("MqttConn should close on packets too large", async () => {
   const connect = encode(connectPacket, codecOptsV4);
 
-  const conn = createMockSockConn([connect], new Uint8Array());
+  const conn = createMockConn([connect], new Uint8Array());
   const mqttConn = new MqttConn({ conn, maxIncomingPacketSize: 20 });
 
   const packets: AnyPacket[] = [];
@@ -119,7 +119,7 @@ test("MqttConn should close on packets too large", async () => {
 test("MqttConn should be writable", async () => {
   const connect = encode(connectPacket, codecOptsV4);
   const writer = new Uint8Array(24);
-  const conn = createMockSockConn([connect], writer);
+  const conn = createMockConn([connect], writer);
   const mqttConn = new MqttConn({ conn });
   await mqttConn.send(connectPacket);
   assert.deepStrictEqual(writer, connect);

package/mqttConn/mqttConn.ts

@@ -16,8 +16,7 @@ import {
 } from "../mqttPacket/mod.ts";
 
 import { assert } from "../utils/mod.ts";
-import type { SockConn } from "../socket/socket.ts";
-import { Conn } from "../socket/socket.ts";
+import type { ConnNext } from "../connNext/connNext.ts";
 
 /**
  * Common MQTT connection error messages
@@ -45,7 +44,7 @@ export type SendResult =
  * @returns Single byte as number
  * @throws Error if EOF reached unexpectedly
  */
-async function readByte(conn: Conn): Promise<number> {
+async function readByte(conn: ConnNext): Promise<number> {
   const buff = await conn.read(1);
   assert(buff !== null, MqttConnError.UnexpectedEof);
   assert(buff !== undefined, MqttConnError.UnexpectedEof);
@@ -59,7 +58,7 @@ async function readByte(conn: Conn): Promise<number> {
  * @param buf Buffer to read into
  * @throws Error if EOF reached unexpectedly
  */
-async function readFull(conn: Conn, length: number): Promise<Uint8Array> {
+async function readFull(conn: ConnNext, length: number): Promise<Uint8Array> {
   const buff = await conn.read(length);
   assert(buff !== null, MqttConnError.UnexpectedEof);
   assert(buff.byteLength === length, MqttConnError.UnexpectedEof);
@@ -74,7 +73,7 @@ async function readFull(conn: Conn, length: number): Promise<Uint8Array> {
  * @throws Error if packet is invalid or too large
  */
 export async function readPacket(
-  conn: Conn,
+  conn: ConnNext,
   codecOpts: CodecOpts,
   maxConnectPacketSize: number,
 ): Promise<AnyPacket> {
@@ -113,7 +112,7 @@ export async function readPacket(
  */
 export class MqttConn {
   /** Underlying connection */
-  readonly conn: Conn;
+  readonly conn: ConnNext;
   /** Maximum Connect packet size */
   readonly maxConnectPacketSize: number;
   /** codecOpts */
@@ -134,10 +133,10 @@ export class MqttConn {
    */
   constructor(
     options:
-      & { conn: SockConn; maxConnectPacketSize?: number }
+      & { conn: ConnNext; maxConnectPacketSize?: number }
       & Partial<CodecOpts>,
   ) {
-    this.conn = new Conn(options.conn);
+    this.conn = options.conn;
     this.maxConnectPacketSize = options.maxConnectPacketSize ??
       DEFAULT_MAX_PACKETSIZE;
     this.codecOpts = {
@@ -154,7 +153,7 @@ export class MqttConn {
     return this._reason;
   }
 
-  /** Get remoteAdress */
+  /** Get remoteAddress */
   get remoteAddress(): string {
     if (this.conn.remoteAddr?.transport === "tcp") {
       return this.conn.remoteAddr.hostname;

package/mqttPacket/protocolLevels.ts

@@ -14,5 +14,7 @@ export const MQTTLevel = {
   v5: 5,
 } as const;
 
+/** the MQTT protocol level: 3, 4, 5 or undefined */
 export type ProtocolLevel = (typeof MQTTLevel)[keyof typeof MQTTLevel];
+/** all MQTT protocol levels except 5 */
 export type ProtocolLevelNoV5 = Exclude<ProtocolLevel, 5>;

package/node/README.md

@@ -1,6 +1,6 @@
 # Running Opifex server/client on NodeJS
 
-These instructions specifify how to run [Opifex](README.md) on NodeJS. To run
+These instructions specifify how to run [Opifex](../README.md) on NodeJS. To run
 Opifex on Deno see the [instructions](../deno/README.md)
 
 ## Playing around

package/node/mod.ts

@@ -0,0 +1,7 @@
+/**
+ * Opifex default exports for NodeJS
+ * @module
+ */
+
+export * from "../client/mod.ts";
+export * from "../server/mod.ts";

package/node/{socket-node-stream.ts → nodeSocketToNext.ts}

@@ -1,59 +1,42 @@
-import type { Duplex } from "node:stream";
+import type { Socket } from "node:net";
+import type { ConnAddr, ConnNext } from "../connNext/connNext.ts"; // Custom types
 
-export type SockAddr = NetAddr | UnixAddr | VsockAddr;
-export interface NetAddr {
-  transport: "tcp" | "udp";
-  hostname: string;
-  port: number;
-}
-export interface UnixAddr {
-  transport: "unix" | "unixpacket";
-  path: string;
-}
-export interface VsockAddr {
-  transport: "vsock";
-  cid: number;
-  port: number;
-}
-
-export type SockConn = {
-  stream: Duplex;
-  close: () => void;
-  localAddr?: SockAddr;
-  remoteAddr?: SockAddr;
-};
-
-export class Conn {
-  private stream: Duplex;
+/** wrapper class */
+export class NodeSocketConnNextWrapper {
+  private endPoint: Socket;
   private closed: boolean;
-  private closer: () => void;
-  public remoteAddr: SockAddr | undefined;
   private leftover: Uint8Array = new Uint8Array(0);
 
   // Store bound event listeners so we can cleanly remove them later
-  private onStreamClose = () => {
+  private onClose = () => {
     this.closed = true;
   };
-  private onStreamError = () => {
+  private onError = () => {
     this.closed = true;
   };
 
-  constructor(sockConn: SockConn) {
-    this.stream = sockConn.stream;
+  /** Create a new ConnNext object from a Webstream */
+  constructor(endPoint: Socket) {
+    this.endPoint = endPoint;
     this.closed = false;
-    this.closer = sockConn.close;
-    this.remoteAddr = sockConn.remoteAddr;
-
-    // Attach listeners to update internal state on stream termination
-    this.stream.on("close", this.onStreamClose);
-    this.stream.on("error", this.onStreamError);
+    this.endPoint;
   }
 
-  async read(length: number): Promise<Uint8Array | null> {
-    if (this.closed || length < 0) {
+  async read(length?: number): Promise<Uint8Array | null> {
+    if (this.closed || (length ?? 0) < 0) {
       return null;
     }
 
+    // If no specific byte length is requested, read whatever is available
+    if (length === undefined) {
+      const chunk = this.endPoint.read();
+      return chunk
+        ? Promise.resolve(
+          new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength),
+        )
+        : Promise.resolve(null);
+    }
+
     if (length === 0) {
       return new Uint8Array(0);
     }
@@ -71,28 +54,28 @@ export class Conn {
 
     // 2. Loop until the requested number of bytes is accumulated
     while (bytesAccumulated < length) {
-      if (this.closed || !this.stream.readable) {
+      if (this.closed || !this.endPoint.readable) {
         break;
       }
 
-      const chunk = this.stream.read();
+      const chunk = this.endPoint.read();
       if (chunk === null) {
         await new Promise<void>((resolve) => {
           const cleanup = () => {
-            this.stream.off("readable", onEvent);
-            this.stream.off("end", onEvent);
-            this.stream.off("error", onEvent);
-            this.stream.off("close", onEvent);
+            this.endPoint.off("readable", onEvent);
+            this.endPoint.off("end", onEvent);
+            this.endPoint.off("error", onEvent);
+            this.endPoint.off("close", onEvent);
           };
           const onEvent = () => {
             cleanup();
             resolve();
           };
 
-          this.stream.on("readable", onEvent);
-          this.stream.on("end", onEvent);
-          this.stream.on("error", onEvent);
-          this.stream.on("close", onEvent);
+          this.endPoint.on("readable", onEvent);
+          this.endPoint.on("end", onEvent);
+          this.endPoint.on("error", onEvent);
+          this.endPoint.on("close", onEvent);
         });
 
         continue;
@@ -119,14 +102,14 @@ export class Conn {
     return result;
   }
 
-  write(data: Uint8Array): Promise<number> {
-    if (this.closed || !this.stream.writable) {
+  write(data: Uint8Array): Promise<void> {
+    if (this.closed || !this.endPoint.writable) {
       return Promise.reject(new Error("Stream is closed or not writable"));
     }
 
     return new Promise((resolve, reject) => {
       // 1. Fire the write command and catch any immediate/async errors via the callback
-      const canWriteMore = this.stream.write(data, (err) => {
+      const canWriteMore = this.endPoint.write(data, (err) => {
         if (err) {
           reject(err);
         }
@@ -135,11 +118,11 @@ export class Conn {
       // 2. Determine when to resolve based on the return value of write()
       if (canWriteMore) {
         // If the buffer is not full, we can resolve immediately
-        resolve(data.length);
+        resolve();
       } else {
         // If backpressure is triggered, we must wait for the 'drain' event
-        this.stream.once("drain", () => {
-          resolve(data.length);
+        this.endPoint.once("drain", () => {
+          resolve();
         });
       }
     });
@@ -150,25 +133,55 @@ export class Conn {
       this.closed = true;
 
       // Clean up permanent event listeners to prevent memory leaks
-      this.stream.off("close", this.onStreamClose);
-      this.stream.off("error", this.onStreamError);
+      this.endPoint.off("close", this.onClose);
+      this.endPoint.off("error", this.onError);
 
       // Safely destroy the stream first, then trigger the closer callback
       try {
-        this.stream.destroy();
+        this.endPoint.destroy();
         // deno-coverage-ignore
       } catch (_) {
         // Suppress stream destruction errors
         // deno-coverage-ignore
       }
+    }
+  }
 
-      try {
-        this.closer();
-        // deno-coverage-ignore
-      } catch (_) {
-        // Prevent closer failures from crashing the thread
-        // deno-coverage-ignore
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      const chunk = await this.read();
+      if (chunk === null) {
+        break;
       }
+      yield chunk;
+    }
+  }
+
+  // Convert addresses to custom ConnAddr format
+  get localAddr(): ConnAddr | undefined {
+    if (this.endPoint.localAddress) {
+      return {
+        transport: "tcp",
+        hostname: this.endPoint.localAddress,
+        port: this.endPoint.localPort ?? 0,
+      };
+    }
+    return undefined;
+  }
+
+  get remoteAddr(): ConnAddr | undefined {
+    if (this.endPoint.remoteAddress) {
+      return {
+        transport: "tcp",
+        hostname: this.endPoint.remoteAddress,
+        port: this.endPoint.remotePort ?? 0,
+      };
     }
+    return undefined;
   }
 }
+
+export function nodeSocketToNext(socket: Socket): ConnNext {
+  const connNext = new NodeSocketConnNextWrapper(socket);
+  return connNext;
+}

package/node/tcpClient.ts

@@ -7,9 +7,9 @@ import { Client } from "../client/client.ts";
 import { logger } from "../client/deps.ts";
 import { readFile } from "node:fs/promises";
 import { createConnection } from "node:net";
-import * as tls from "node:tls";
-import type { SockConn } from "../socket/socket.ts";
-import { wrapNodeSocket } from "./wrapNodeSocket.ts";
+import { connect } from "node:tls";
+import type { ConnNext } from "../client/mod.ts";
+import { nodeSocketToNext } from "./nodeSocketToNext.ts";
 
 /**
  * Fetches data from a file and returns it as a string
@@ -44,14 +44,17 @@ export class TcpClient extends Client {
    * @param hostname the name of the host to connect to
    * @param port the port number
    */
-  protected connectMQTT(hostname: string, port = 1883): Promise<SockConn> {
+  protected override connectMQTT(
+    hostname: string,
+    port = 1883,
+  ): Promise<ConnNext> {
     logger.debug({ hostname, port });
     return new Promise((resolve, reject) => {
       const socket = createConnection(
         { port, host: hostname },
         () => {
           logger.debug("Connected to server");
-          resolve(wrapNodeSocket(socket));
+          resolve(nodeSocketToNext(socket));
         },
       );
       socket.once("error", (err) => {
@@ -68,15 +71,15 @@ export class TcpClient extends Client {
    * @param caCerts the CA certificates to trust
    * @param cert the clients certificate
    * @param key the clients private key
-   * @returns a SockConn object
+   * @returns a ConnNext object
    */
-  protected connectMQTTS(
+  protected override connectMQTTS(
     hostname: string,
     port = 8883,
     ca?: string[],
     cert?: string,
     key?: string,
-  ): Promise<SockConn> {
+  ): Promise<ConnNext> {
     const opts = {
       host: hostname,
       port,
@@ -87,9 +90,9 @@ export class TcpClient extends Client {
     };
     logger.debug({ hostname, port, ca, cert });
     return new Promise((resolve, reject) => {
-      const socket = tls.connect(opts, () => {
+      const socket = connect(opts, () => {
         logger.debug("Connected to server");
-        resolve(wrapNodeSocket(socket));
+        resolve(nodeSocketToNext(socket));
       });
       socket.once("error", (err) => {
         logger.debug("Connection failed", err);
@@ -97,21 +100,4 @@ export class TcpClient extends Client {
       });
     });
   }
-
-  /** createConn is used by the base client class */
-  protected override createConn(): Promise<SockConn> {
-    const { protocol, hostname, port: portStr } = this.connectUrl;
-    const port = Number(portStr);
-    const caCerts = this.caCerts;
-    const cert = this.cert;
-    const key = this.key;
-
-    if (protocol === "mqtts:") {
-      return this.connectMQTTS(hostname, port, caCerts, cert, key);
-    }
-    if (protocol === "mqtt:") {
-      return this.connectMQTT(hostname, port);
-    }
-    throw new Error(`Unsupported protocol: ${protocol}`);
-  }
 }