@seriousme/opifex 1.11.2 → 2.0.3

package/server/handlers/will.delivery.test.ts

@@ -0,0 +1,221 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { PacketType } from "../deps.ts";
+import {
+  addMockClient,
+  connect,
+  disconnect,
+  ping,
+  startMockServer,
+  subscribe,
+} from "../../dev_utils/mod.ts";
+
+const txtEncoder = new TextEncoder();
+
+test("MQTT-3.1.2.5: will message delivered on ungraceful disconnect", async () => {
+  const willTopic = "will/topic";
+  const payload = txtEncoder.encode("goodbye");
+  const { mqttConn: subscriber, mqttServer } = startMockServer();
+
+  // Subscriber connects
+  await connect(subscriber, { clientId: "subscriber1" });
+  await subscribe(subscriber, [{ topicFilter: willTopic, qos: 0 }]);
+
+  const publisher = addMockClient(mqttServer);
+  // Publisher connects
+  await connect(publisher, {
+    clientId: "publisher1",
+    will: {
+      topic: willTopic,
+      payload,
+      qos: 0,
+      retain: false,
+    },
+  });
+
+  // Force close the publisher connection without sending DISCONNECT
+  // This simulates an ungraceful disconnect
+  publisher.close();
+  assert.deepStrictEqual(publisher.isClosed, true, "publisher is closed");
+
+  // Subscriber should receive the will message
+  const { value: willMessage } = await subscriber.next();
+
+  assert.deepStrictEqual(
+    willMessage.type,
+    PacketType.publish,
+    "Expecting a Publish packet",
+  );
+  assert.deepStrictEqual(
+    willMessage.topic,
+    willTopic,
+    "Expecting correct topic",
+  );
+  assert.deepStrictEqual(
+    willMessage.payload,
+    payload,
+    "Expecting correct payload",
+  );
+
+  // Clean up
+  await disconnect(subscriber);
+});
+
+test("MQTT-3.1.2.5: will message NOT delivered on graceful DISCONNECT", async () => {
+  const willTopic = "will/topic2";
+  const payload = txtEncoder.encode("goodbye");
+  const { mqttConn: subscriber, mqttServer } = startMockServer();
+
+  // Subscriber connects
+  await connect(subscriber, { clientId: "subscriber2" });
+  await subscribe(subscriber, [{ topicFilter: willTopic, qos: 0 }]);
+
+  const publisher = addMockClient(mqttServer);
+  // Publisher connects
+  await connect(publisher, {
+    clientId: "publisher2",
+    will: {
+      topic: willTopic,
+      payload,
+      qos: 0,
+      retain: false,
+    },
+  });
+  // Publisher gracefully disconnects
+  await disconnect(publisher);
+
+  // Send PINGREQ to verify no will message was queued before it
+  await ping(subscriber);
+
+  // Clean up
+  await disconnect(subscriber);
+});
+
+test("MQTT-3.1.2.5: will message delivered with correct QoS", async () => {
+  const willTopic = "will/qos";
+  const payload = txtEncoder.encode("goodbye");
+  const { mqttConn: subscriber, mqttServer } = startMockServer();
+
+  // Subscriber connects
+  await connect(subscriber, { clientId: "subscriber3" });
+  await subscribe(subscriber, [{ topicFilter: willTopic, qos: 1 }]);
+
+  // Publisher connects with will message QoS 1
+  const publisher = addMockClient(mqttServer);
+  await connect(publisher, {
+    clientId: "publisher3",
+    will: {
+      topic: willTopic,
+      payload,
+      qos: 1,
+      retain: false,
+    },
+  });
+
+  // Force close the publisher connection
+  publisher.close();
+
+  // Subscriber should receive the will message with QoS 1
+  const { value: willMessage } = await subscriber.next();
+  assert.deepStrictEqual(willMessage.type, PacketType.publish);
+
+  assert.deepStrictEqual(
+    willMessage.type,
+    PacketType.publish,
+    "Expecting a Publish packet",
+  );
+  assert.deepStrictEqual(
+    willMessage.topic,
+    willTopic,
+    "Expecting correct topic",
+  );
+  assert.deepStrictEqual(
+    willMessage.qos,
+    1,
+    "Expecting correct QoS",
+  );
+
+  // Clean up
+  await disconnect(subscriber);
+});
+
+test("MQTT-3.1.2.5: will message stored as retained when retain=true", async () => {
+  const willTopic = "will/retained";
+  const payload = txtEncoder.encode("Retained message");
+
+  const { mqttConn: subscriber, mqttServer } = startMockServer();
+
+  // Subscriber connects
+  await connect(subscriber, { clientId: "subscriber4" });
+
+  // Publisher connects with will retain true
+  const publisher = addMockClient(mqttServer);
+  await connect(publisher, {
+    clientId: "publisher4",
+    will: {
+      topic: willTopic,
+      payload,
+      qos: 0,
+      retain: true,
+    },
+  });
+
+  // Force close the publisher connection
+  publisher.close();
+
+  // Now subscribe to the topic - should receive the retained message
+  await subscribe(subscriber, [{ topicFilter: willTopic, qos: 0 }]);
+
+  // Should receive the retained will message
+  const { value: willMessage } = await subscriber.next();
+  assert.deepStrictEqual(
+    willMessage.type,
+    PacketType.publish,
+    "Expecting PUBLISH packet",
+  );
+  assert.deepStrictEqual(
+    willMessage.topic,
+    willTopic,
+    "Expecting correct topic",
+  );
+  assert.deepStrictEqual(willMessage.retain, true, "Expecting retain true");
+  assert.deepStrictEqual(
+    willMessage.payload,
+    payload,
+    "Expecting correct payload",
+  );
+
+  // Clean up
+  await disconnect(subscriber);
+});
+
+test("MQTT-3.1.2.5: will message to $ topic is rejected", async () => {
+  const willTopic = "$SYS/will";
+  const payload = txtEncoder.encode("System Will");
+  const { mqttConn: subscriber, mqttServer } = startMockServer();
+
+  // Subscriber connects
+  await connect(subscriber, { clientId: "subscriber5" });
+  await subscribe(subscriber, [{ topicFilter: willTopic, qos: 0 }]);
+
+  // Publisher connects with will message to system topic
+  const publisher = addMockClient(mqttServer);
+  await connect(publisher, {
+    clientId: "publisher5",
+    will: {
+      topic: willTopic,
+      payload,
+      qos: 0,
+      retain: false,
+    },
+  });
+
+  // Force close the publisher connection
+  publisher.close();
+
+  // Send PINGREQ to verify no will message was queued
+  await ping(subscriber);
+
+  // Clean up
+  await disconnect(subscriber);
+});

package/server/mod.ts

@@ -2,14 +2,15 @@
  *  This module provides an MQTT Server interface see the /bin folder for examples
  *  @module
  */
-export { AuthenticationResult } from "./deps.ts";
+export { ReasonCode } from "./deps.ts";
 export type {
+  ConnectPacket,
   IPersistence,
+  ShareName,
   SockConn,
-  TAuthenticationResult,
   Topic,
 } from "./deps.ts";
 export { MqttServer } from "./server.ts";
 export type { MqttServerOptions } from "./server.ts";
 export { Context } from "./context.ts";
-export type { Handlers } from "./context.ts";
+export type { AuthenticatedResult, Handlers } from "./context.ts";

package/server/preconnect.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  connect,
+  delay,
+  disconnect,
+  startMockServer,
+} from "../dev_utils/mod.ts";
+import type { AnyPacket } from "./deps.ts";
+import { MQTTLevel } from "./deps.ts";
+import { PacketType } from "../mqttPacket/mod.ts";
+
+test(
+  "Preconnect timer: connection closes if CONNECT not received within timeout",
+  { concurrency: false },
+  async () => {
+    const { mqttConn } = startMockServer({
+      configuration: { context: { preconnectTimeoutMs: 500 } },
+    });
+
+    // Wait 750 ms without sending CONNECT packet
+    await delay(750);
+
+    // Try to get next packet (should timeout/close)
+    await mqttConn.next();
+
+    // Connection should be closed
+    assert.deepStrictEqual(
+      mqttConn.isClosed,
+      true,
+      "Connection should be closed after preconnect timeout",
+    );
+  },
+);
+
+test(
+  "Preconnect timer: connection succeeds if CONNECT received before timeout",
+  { concurrency: false },
+  async () => {
+    const { mqttConn } = startMockServer({
+      configuration: { context: { preconnectTimeoutMs: 500 } },
+    });
+
+    // Wait 200 ms (before timeout)
+    await delay(200);
+
+    // Send CONNECT packet
+    await connect(mqttConn, { clientId: "preconnectTestClient" });
+
+    // Connection should still be open
+    assert.deepStrictEqual(
+      mqttConn.isClosed,
+      false,
+      "Connection should remain open after successful CONNECT",
+    );
+
+    // Cleanup
+    await disconnect(mqttConn);
+  },
+);
+
+test(
+  "Preconnect timer: connection succeeds with immediate CONNECT",
+  { concurrency: false },
+  async () => {
+    const { mqttConn } = startMockServer({
+      configuration: { context: { preconnectTimeoutMs: 500 } },
+    });
+
+    // Send CONNECT immediately
+    await connect(mqttConn, { clientId: "preconnectTestImmediate" });
+    await delay(750);
+
+    // Connection should be open
+    assert.deepStrictEqual(
+      mqttConn.isClosed,
+      false,
+      "Connection should remain open after immediate CONNECT",
+    );
+
+    // Cleanup
+    await disconnect(mqttConn);
+  },
+);
+
+test(
+  "Preconnect timer: closes connection at exact time",
+  { concurrency: false },
+  async () => {
+    const { mqttConn } = startMockServer({
+      configuration: { context: { preconnectTimeoutMs: 500 } },
+    });
+
+    // Wait just under 500 ms - should still be connected
+    await delay(400);
+
+    // Connection should still be open
+    assert.deepStrictEqual(
+      mqttConn.isClosed,
+      false,
+      "Connection should be open at 2.9 seconds",
+    );
+
+    // Wait additional 200ms to cross the 500 ms boundary
+    await delay(200);
+
+    // Try to interact with connection
+    await mqttConn.next();
+
+    // Connection should now be closed
+    assert.deepStrictEqual(
+      mqttConn.isClosed,
+      true,
+      "Connection should be closed now",
+    );
+  },
+);
+
+test("Preconnect handler: handler disconnects session", async () => {
+  const txtEncoder = new TextEncoder();
+
+  const connectPacket: AnyPacket = {
+    type: PacketType.connect,
+    protocolName: "MQTT",
+    protocolLevel: MQTTLevel.v4,
+    clientId: "testClient",
+    clean: true,
+    keepAlive: 0,
+    username: "IoTester_1",
+    password: txtEncoder.encode("strong_password"),
+    will: undefined,
+  };
+
+  const { mqttConn } = startMockServer({
+    handlers: {
+      preconnect: () => false,
+    },
+  });
+  await mqttConn.send(connectPacket);
+  const { value } = await mqttConn.next();
+  assert.deepStrictEqual(
+    value,
+    undefined,
+    "No connack received",
+  );
+  assert.deepStrictEqual(
+    mqttConn.isClosed,
+    true,
+    "Connection should be closed by the preconnect handler",
+  );
+});

package/server/server.ts

@@ -1,69 +1,167 @@
-import { AuthenticationResult, logger, MemoryPersistence } from "./deps.ts";
+import { logger, MemoryPersistence, ReasonCode } from "./deps.ts";
 import { Context } from "./context.ts";
 import type { Handlers } from "./context.ts";
-import type { IPersistence, SockConn, Topic } from "./deps.ts";
+import type { IPersistence, ShareName, SockConn, Topic } from "./deps.ts";
 import { handlePacket } from "./handlers/handlePacket.ts";
+import { createConfiguration } from "./config.ts";
+import type { Configuration, ConfigurationInput } from "./config.ts";
 
+/**
+ * Default preconnect handler that unconditionally permits all connections.
+ * @param {SockConn} _conn - The connection.
+ * @returns {boolean} Always returns true
+ */
+const defaultPreconnect = (
+  _conn: SockConn,
+) => (true) as const;
+
+/**
+ * Default authentication handler that unconditionally permits all connections.
+ * @param {Context} _ctx - The connection context.
+ * @param {string} _clientId - The client identifier.
+ * @param {string} _username - The username provided by the client.
+ * @param {Uint8Array} _password - The password provided by the client.
+ * @returns {IsAuthenticatedResult} Always returns ReasonCode.success.
+ */
 const defaultIsAuthenticated = (
   _ctx: Context,
   _clientId: string,
   _username: string,
   _password: Uint8Array,
-) => AuthenticationResult.ok;
+) => ({ reasonCode: ReasonCode.success }) as const;
+
+const defaultProcessAuth = (
+  _ctx: Context,
+  _clientId: string,
+  _authMethod: string,
+  _authData: Uint8Array,
+) =>
+  ({
+    reasonCode: ReasonCode.badAuthenticationMethod,
+    reasonString: "Authentication method not supported",
+  }) as const;
+
+/**
+ * Default authorization handler that unconditionally permits all publish operations.
+ * @param {Context} _ctx - The connection context.
+ * @param {Topic} _topic - The topic being accessed.
+ * @returns {boolean} Always returns true.
+ */
+const defaultIsAuthorizedToPublish = (_ctx: Context, _topic: Topic) =>
+  (true) as const;
 
-const defaultIsAuthorized = (_ctx: Context, _topic: Topic) => true;
+/**
+ * Default authorization handler that unconditionally permits all subscribe operations.
+ * @param {Context} _ctx - The connection context.
+ * @param {Topic} _topic - The topic being accessed.
+ * @param {ShareName} _shareName - The share name being accessed when using shared subscriptions
+ * @returns {boolean} Always returns true.
+ */
+
+const defaultIsAuthorizedToSubscribe = (
+  _ctx: Context,
+  _topic: Topic,
+  _shareName: ShareName,
+) => (true) as const;
 
 /**
- * The options to configure the MqttServer
+ * Configuration options for creating an MqttServer instance.
  */
 export type MqttServerOptions = {
+  /** Optional persistence layer implementation. Defaults to MemoryPersistence. */
   persistence?: IPersistence;
+  /** Optional custom handlers for authentication and authorization. */
   handlers?: Handlers;
+  /** Optional configuration data */
+  configuration?: ConfigurationInput;
 };
 
-/** The MqttServer class provides a MQTT server with configurable persistence and
+/** * The MqttServer class provides an MQTT server with configurable persistence and
  * authentication/authorization handlers.
  *
  * The default handlers are:
- *  - isAuthenticated: always returns ok
- *  - isAuthorizedToPublish: always returns true
- *  - isAuthorizedToSubscribe: always returns true
+ * - isAuthenticated: always returns ok
+ * - isAuthorizedToPublish: always returns true
+ * - isAuthorizedToSubscribe: always returns true
  *
  * To customize the handlers, pass in a Handlers object.
  * To customize the persistence, pass in a Persistence object.
  */
-
 export class MqttServer {
+  /** The registered authentication and authorization handlers. */
   handlers: Handlers;
+  /** The persistence layer used for storing sessions and messages. */
   persistence: IPersistence;
+  /** The persistence layer used for storing sessions and messages. */
+  configuration: Configuration;
+
+  /**
+   * Initializes a new instance of the MqttServer.
+   * * @param {MqttServerOptions} options - The configuration options for the server.
+   */
   constructor({
     persistence,
     handlers,
+    configuration,
   }: MqttServerOptions) {
     this.persistence = persistence || new MemoryPersistence();
     this.handlers = {
+      preconnect: handlers?.preconnect || defaultPreconnect,
       isAuthenticated: handlers?.isAuthenticated || defaultIsAuthenticated,
+      processAuth: handlers?.processAuth || defaultProcessAuth,
       isAuthorizedToPublish: handlers?.isAuthorizedToPublish ||
-        defaultIsAuthorized,
+        defaultIsAuthorizedToPublish,
       isAuthorizedToSubscribe: handlers?.isAuthorizedToSubscribe ||
-        defaultIsAuthorized,
+        defaultIsAuthorizedToSubscribe,
     };
+    this.configuration = createConfiguration(configuration);
   }
 
+  /**
+   * Serve a new client connection.
+   * @param {SockConn} conn - The socket connection to serve.
+   * @returns {Promise<void>} A promise that resolves when the connection is closed.
+   */
   async serve(conn: SockConn): Promise<void> {
-    const ctx = new Context(this.persistence, conn, this.handlers);
+    if (this.handlers.preconnect) {
+      if (!await this.handlers.preconnect(conn)) {
+        conn.close();
+        return;
+      }
+    }
+    const ctx = new Context(
+      this.configuration,
+      this.persistence,
+      conn,
+      this.handlers,
+    );
     if (conn.remoteAddr?.transport === "tcp") {
-      logger.debug(`socket connected from ${conn.remoteAddr.hostname}`);
+      logger.debug("socket connected from", conn.remoteAddr.hostname);
     }
     try {
       for await (const packet of ctx.mqttConn) {
+        logger.debug("next packet");
         await handlePacket(ctx, packet);
       }
     } catch (err) {
-      logger.debug(`Error while serving:${err}`);
+      logger.debug("Error while serving:", err);
     } finally {
-      if (!ctx.mqttConn.isClosed) {
-        ctx.close();
+      logger.debug("done serving for", ctx.clientId);
+      await ctx.close();
+    }
+  }
+
+  /**
+   * Close the server and all active client connections.
+   * @param {boolean} cleanUp - If true, clean up client sessions on close.
+   */
+  async close(cleanUp: boolean = false): Promise<void> {
+    logger.debug("stopping mqttServer");
+    for (const [clientid, ctx] of Context.clientList) {
+      logger.debug("closing session for clientid:", clientid);
+      await ctx.close();
+      if (cleanUp) {
+        await ctx.clean();
       }
     }
   }

package/socket/socket.test.ts

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { Conn } from "./socket.ts";
+import { createMockSockConn } from "../dev_utils/mod.ts";
+
+test("Conn.read peaks and buffers partial data correctly", async () => {
+  const chunk1 = new Uint8Array([1, 2, 3]);
+  const chunk2 = new Uint8Array([4, 5, 6, 7]);
+  const chunk3 = new Uint8Array([8, 9]);
+
+  const mockTarget = new Uint8Array();
+  const sockConn = createMockSockConn([chunk1, chunk2, chunk3], mockTarget);
+  const conn = new Conn(sockConn);
+
+  const res1 = await conn.read(2);
+  assert.deepStrictEqual(res1, new Uint8Array([1, 2]));
+
+  const res2 = await conn.read(3);
+  assert.deepStrictEqual(res2, new Uint8Array([3, 4, 5]));
+
+  const res3 = await conn.read(4);
+  assert.deepStrictEqual(res3, new Uint8Array([6, 7, 8, 9]));
+});
+
+test("Conn.read returns null when stream ends before length is met", async () => {
+  const chunk = new Uint8Array([1, 2, 3]);
+  const mockTarget = new Uint8Array(0);
+  const sockConn = createMockSockConn([chunk], mockTarget);
+  const conn = new Conn(sockConn);
+
+  // asking for5 bytes, but only 3 are available in the stream
+  const res = await conn.read(5);
+  assert.deepStrictEqual(res, null);
+});
+
+test("Conn.read returns null when length <= 0", async () => {
+  const chunk = new Uint8Array([1, 2, 3]);
+  const mockTarget = new Uint8Array(0);
+  const sockConn = createMockSockConn([chunk], mockTarget);
+  const conn = new Conn(sockConn);
+
+  const res = await conn.read(-1);
+  assert.deepStrictEqual(res, null);
+});
+
+test("Conn.read returns empty array when length = 0", async () => {
+  const chunk = new Uint8Array([1, 2, 3]);
+  const mockTarget = new Uint8Array(0);
+  const sockConn = createMockSockConn([chunk], mockTarget);
+  const conn = new Conn(sockConn);
+
+  const res = await conn.read(0);
+  assert.deepStrictEqual(res?.length, 0);
+});
+
+test("Conn.write successfully forwards data to writable stream", async () => {
+  const dataToWrite = new Uint8Array([10, 20, 30, 40]);
+  const mockTarget = new Uint8Array(4);
+  const sockConn = createMockSockConn([], mockTarget);
+  const conn = new Conn(sockConn);
+
+  const bytesWritten = await conn.write(dataToWrite);
+
+  assert.deepStrictEqual(bytesWritten, 4);
+  assert.deepStrictEqual(mockTarget, dataToWrite);
+});
+
+test("Conn.write rejects when connection is closed", async () => {
+  const mockTarget = new Uint8Array(4);
+  const sockConn = createMockSockConn([], mockTarget);
+  const conn = new Conn(sockConn);
+
+  conn.close();
+
+  await assert.rejects(
+    conn.write(new Uint8Array([1, 2])),
+    /Connection closed/,
+  );
+});
+
+test("Conn.close closes writer, releases reader lock and sets closed flag", () => {
+  const mockTarget = new Uint8Array(0);
+  const sockConn = createMockSockConn([], mockTarget);
+  const conn = new Conn(sockConn);
+
+  assert.deepStrictEqual(conn.closed, false);
+
+  conn.close();
+
+  assert.deepStrictEqual(conn.closed, true);
+});