@seriousme/opifex 1.11.2 → 2.0.3

package/client/client.ts

@@ -4,21 +4,23 @@ import {
   MemoryStore,
   MQTTLevel,
   PacketType,
+  ReasonCode,
 } from "./deps.ts";
 
 import type {
   ConnectPacket,
+  IStore,
   PublishPacket,
   SockConn,
   SubscribePacket,
   TAuthenticationResult,
 } from "./deps.ts";
 
-import { noop } from "../utils/utils.ts";
+import { noop } from "../utils/mod.ts";
 
 import { Context } from "./context.ts";
+import type { AuthenticatedResult } from "./context.ts";
 import type { TConnectionState } from "./ConnectionState.ts";
-import { assert } from "../utils/assert.ts";
 import { BufferedAsyncIterable } from "./deps.ts";
 
 /**
@@ -37,12 +39,12 @@ type ConnectOptions = Omit<
 
 /** ConnectParameters define how to connect */
 export type ConnectParameters = {
-  url?: URL;
-  caCerts?: string[];
-  cert?: string;
-  key?: string;
-  numberOfRetries?: number;
-  options?: ConnectOptions;
+  url?: URL | undefined;
+  caCerts?: string[] | undefined;
+  cert?: string | undefined;
+  key?: string | undefined;
+  numberOfRetries?: number | undefined;
+  options?: ConnectOptions | undefined;
 };
 
 /** PublishParameters define how a message should be published */
@@ -84,6 +86,20 @@ export const DEFAULT_KEEPALIVE = 60; // 60 seconds
 const DEFAULT_RETRIES = 3; // on first connect
 const CLIENTID_PREFIX = "opifex"; // on first connect
 
+// convert an ErrorEvent into an Error
+// NodeJS does not know ErrorEvent
+function normalizeError(err: unknown): Error {
+  if (typeof ErrorEvent !== "undefined" && err instanceof ErrorEvent) {
+    return new Error(err.message);
+  }
+
+  if (err instanceof Error) {
+    return err;
+  }
+
+  throw err;
+}
+
 /**
  * The Client class provides an MQTT Client that can be used to connect to
  * a MQTT broker and publish/subscribe messages.
@@ -94,6 +110,15 @@ const CLIENTID_PREFIX = "opifex"; // on first connect
  * connection type that is supported by the subclass.
  */
 export class Client {
+  public onAuth: (
+    authMethod: string,
+    authData: Uint8Array,
+  ) => AuthenticatedResult = () => {
+    return {
+      reasonCode: ReasonCode.badAuthenticationMethod,
+      reasonString: "No authentication method configured",
+    };
+  };
   public onError: (err: Error) => void = noop;
   public onPacket: (pkt: PublishPacket) => void | Promise<void> = noop;
   public onConnected: () => void = noop;
@@ -102,51 +127,43 @@ export class Client {
 
   protected clientIdPrefix = CLIENTID_PREFIX;
   protected numberOfRetries = DEFAULT_RETRIES;
-  protected url: URL = new URL(DEFAULT_URL);
+  protected connectUrl: URL = new URL(DEFAULT_URL);
   protected keepAlive = DEFAULT_KEEPALIVE;
   protected protocolLevel = DEFAULT_PROTOCOLLEVEL;
   protected autoReconnect = true;
-  private caCerts?: string[];
-  private cert?: string;
-  private key?: string;
-  private clientId: string;
+  protected caCerts?: string[] | undefined;
+  protected cert?: string | undefined;
+  protected key?: string | undefined;
+  protected clientId: string;
   private ctx: Context;
   private connectPacket?: ConnectPacket;
 
   /**
    * Creates a new MQTT client instance
    */
-  constructor() {
-    this.ctx = new Context(new MemoryStore(), this);
+  constructor(store?: IStore) {
+    const cStore = store ? store : new MemoryStore();
+    this.ctx = new Context(cStore, this);
     this.clientId = generateClientId(this.clientIdPrefix);
     this.numberOfRetries = DEFAULT_RETRIES;
   }
 
-  get connectionState(): TConnectionState {
+  public get connectionState(): TConnectionState {
     return this.ctx.connectionState;
   }
 
+  public get url(): URL {
+    return this.connectUrl;
+  }
+
   /**
    * Creates a new connection to the MQTT broker
-   * @param protocol - The protocol to use (mqtt, mqtts, etc)
-   * @param _hostname - The hostname to connect to
-   * @param _port - The port to connect to
-   * @param _caCerts - Optional CA certificates
-   * @param _cert - Optional client certificate
-   * @param _key - Optional client key
    * @returns Promise resolving to a SockConn connection
    */
-  protected createConn(
-    protocol: string,
-    _hostname: string,
-    _port?: number,
-    _caCerts?: string[],
-    _cert?: string,
-    _key?: string,
-  ): Promise<SockConn> {
+  protected createConn(): Promise<SockConn> {
     // if you need to support alternative connection types just
     // overload this method in your subclass
-    throw new Error(`Unsupported protocol: ${protocol}`);
+    throw new Error(`Unsupported protocol: ${this.url.protocol}`);
   }
 
   /**
@@ -163,16 +180,12 @@ export class Client {
     let lastMessage = new Error();
     let tryConnect = true;
     while (tryConnect) {
-      logger.debug(`${isReconnect ? "re" : ""}connecting, attempt ${attempt}`);
+      logger.debug(
+        isReconnect ? "reconnecting, attempt" : "connecting, attempt",
+        attempt,
+      );
       try {
-        const conn = await this.createConn(
-          this.url.protocol,
-          this.url.hostname,
-          Number(this.url.port) ?? undefined,
-          this.caCerts,
-          this.cert,
-          this.key,
-        );
+        const conn = await this.createConn();
         // if we get this far we have a connection
         tryConnect =
           (await this.ctx.handleConnection(conn, this.connectPacket)) &&
@@ -182,12 +195,9 @@ export class Client {
         this.connectPacket.clean = false;
         this.ctx.close();
       } catch (err) {
-        assert(
-          err instanceof Error,
-          `Caught something that is not an instance of Error: ${err}`,
-        );
-        queueMicrotask(() => this.onError(err));
-        lastMessage = err;
+        const normalizedErr = normalizeError(err);
+        queueMicrotask(() => this.onError(normalizedErr));
+        lastMessage = normalizedErr;
         logger.debug({ lastMessage });
       }
 
@@ -213,7 +223,7 @@ export class Client {
    * @returns Promise resolving to authentication result
    */
   connect(params: ConnectParameters = {}): Promise<TAuthenticationResult> {
-    this.url = params?.url || this.url;
+    this.connectUrl = params?.url || this.connectUrl;
     this.numberOfRetries = params.numberOfRetries || this.numberOfRetries;
     this.caCerts = params?.caCerts;
     this.cert = params?.cert;

package/client/context.ts

@@ -9,7 +9,7 @@ import {
 import type {
   AnyPacket,
   ConnectPacket,
-  MemoryStore,
+  IStore,
   PacketId,
   ProtocolLevel,
   PublishPacket,
@@ -17,6 +17,8 @@ import type {
   SockConn,
   SubscribePacket,
   TAuthenticationResult,
+  TPacketType,
+  TReasonCode,
   UnsubscribePacket,
 } from "./deps.ts";
 
@@ -26,6 +28,24 @@ import { ConnectionState } from "./ConnectionState.ts";
 import type { Client } from "./client.ts";
 import { assert } from "../utils/assert.ts";
 
+/**
+ * packets not allowed during authentication
+ */
+function blockedDuringAuthentication(pktType: TPacketType) {
+  return (
+    pktType === PacketType.publish ||
+    pktType === PacketType.subscribe ||
+    pktType === PacketType.unsubscribe
+  );
+}
+
+/** Possible results from authHandler */
+export type AuthenticatedResult = {
+  reasonCode: TReasonCode;
+  reasonString?: string;
+  authData?: Uint8Array;
+};
+
 export class Context {
   mqttConn?: MqttConn;
   #connectionState: TConnectionState;
@@ -35,10 +55,10 @@ export class Context {
   unresolvedPublish: Map<PacketId, Deferred<void>>;
   unresolvedSubscribe: Map<PacketId, Deferred<ReturnCodes>>;
   unresolvedUnSubscribe: Map<PacketId, Deferred<void>>;
-  store: MemoryStore;
+  store: IStore;
   #client: Client;
 
-  constructor(store: MemoryStore, client: Client) {
+  constructor(store: IStore, client: Client) {
     this.#client = client;
     this.store = store;
     this.#connectionState = ConnectionState.offline;
@@ -64,6 +84,25 @@ export class Context {
     }
   }
 
+  authHandler(
+    _ctx: Context,
+    authMethod: string,
+    authData: Uint8Array,
+  ): AuthenticatedResult | Promise<AuthenticatedResult> {
+    return this.#client.onAuth(authMethod, authData);
+  }
+
+  setPingTimer(interval: number) {
+    if (this.pingTimer) {
+      this.pingTimer.clear();
+    }
+    this.pingTimer = new Timer(
+      this.sendPing.bind(this),
+      interval * 1000,
+      true,
+    );
+  }
+
   async connect(packet: ConnectPacket) {
     this.connectionState = ConnectionState.connecting;
     if (packet.protocolLevel === MQTTLevel.unknown) {
@@ -73,16 +112,15 @@ export class Context {
     await this.mqttConn?.send(packet);
     const keepAlive = packet.keepAlive || 0;
     if (keepAlive > 0) {
-      this.pingTimer = new Timer(
-        this.sendPing.bind(this),
-        keepAlive * 1000,
-        true,
-      );
+      this.setPingTimer(keepAlive);
     }
   }
 
   async disconnect() {
-    if (this.connectionState !== ConnectionState.connected) {
+    if (
+      this.connectionState !== ConnectionState.connected &&
+      this.connectionState !== ConnectionState.authenticating
+    ) {
       throw "Not connected";
     }
     if (this.mqttConn) {
@@ -97,14 +135,29 @@ export class Context {
   }
 
   async send(packet: AnyPacket) {
-    logger.debug({ send: packet });
-    if (
-      this.connectionState === ConnectionState.connected &&
-      !this.mqttConn?.isClosed
-    ) {
-      await this.mqttConn?.send(packet);
-      this.pingTimer?.reset();
-      return;
+    logger.debug("client.ctx.send", this.#connectionState, { packet });
+    if (!this.mqttConn?.isClosed) {
+      if (this.connectionState === ConnectionState.connected) {
+        await this.mqttConn?.send(packet);
+        this.pingTimer?.reset();
+        return;
+      }
+      if (
+        this.connectionState === ConnectionState.connecting &&
+        packet.type === PacketType.auth
+      ) {
+        await this.mqttConn?.send(packet);
+        this.pingTimer?.reset();
+        return;
+      }
+      if (
+        this.connectionState === ConnectionState.authenticating &&
+        !blockedDuringAuthentication(packet.type)
+      ) {
+        await this.mqttConn?.send(packet);
+        this.pingTimer?.reset();
+        return;
+      }
     }
     logger.debug("not connected");
     this.pingTimer?.clear();
@@ -122,6 +175,7 @@ export class Context {
     connectPacket: ConnectPacket,
   ): Promise<boolean> {
     this.mqttConn = new MqttConn({ conn });
+    this.mqttConn.codecOpts.protocolLevel = connectPacket.protocolLevel;
     try {
       logger.debug("Send connect packet", connectPacket);
       await this.connect(connectPacket);
@@ -136,7 +190,7 @@ export class Context {
         `Caught something that is not an instance of Error: ${err}`,
       );
       queueMicrotask(() => this.#client.onError(err));
-      logger.debug(`error ${err}`);
+      logger.debug("error", err);
       if (!this.mqttConn.isClosed) {
         this.mqttConn.close();
       }
@@ -164,7 +218,7 @@ export class Context {
       await this.send(packet);
       return;
     }
-    packet.id = this.store.nextId();
+    packet.id = await this.store.nextId();
     this.store.pendingOutgoing.set(packet.id, packet);
     const deferred = new Deferred<void>();
     this.unresolvedPublish.set(packet.id, deferred);
@@ -173,7 +227,7 @@ export class Context {
   }
 
   async subscribe(packet: SubscribePacket): Promise<ReturnCodes> {
-    packet.id = this.store.nextId();
+    packet.id = await this.store.nextId();
     this.store.pendingOutgoing.set(packet.id, packet);
     const deferred = new Deferred<ReturnCodes>();
     this.unresolvedSubscribe.set(packet.id, deferred);
@@ -182,7 +236,7 @@ export class Context {
   }
 
   async unsubscribe(packet: UnsubscribePacket): Promise<void> {
-    packet.id = this.store.nextId();
+    packet.id = await this.store.nextId();
     this.store.pendingOutgoing.set(packet.id, packet);
     const deferred = new Deferred<void>();
     this.unresolvedUnSubscribe.set(packet.id, deferred);

package/client/deps.ts

@@ -1,5 +1,6 @@
 export type {
   AnyPacket,
+  AuthPacket,
   ConnackPacket,
   ConnectPacket,
   DisconnectPacket,
@@ -12,11 +13,13 @@ export type {
   PublishPacket,
   PubrecPacket,
   PubrelPacket,
+  QoS,
   ReturnCodes,
   SubackPacket,
   SubscribePacket,
   TAuthenticationResult,
   Topic,
+  TPacketType,
   TReasonCode,
   UnsubackPacket,
   UnsubscribePacket,
@@ -30,6 +33,7 @@ export {
   MQTTLevel,
   PacketNameByType,
   PacketType,
+  ReasonCode,
   ReasonCodeByNumber,
 } from "../mqttPacket/mod.ts";
 
@@ -38,3 +42,4 @@ export type { SockConn } from "../socket/socket.ts";
 export { Timer } from "../timer/timer.ts";
 export { BufferedAsyncIterable, Deferred, logger } from "../utils/mod.ts";
 export { MemoryStore } from "./store/memoryStore.ts";
+export type { IStore } from "./store/store.ts";

package/client/handlers/handleAuth.test.ts

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { handleAuth } from "./handleAuth.ts";
+import { ConnectionState } from "../ConnectionState.ts";
+import { PacketType, ReasonCode } from "../deps.ts";
+import type { AuthPacket } from "../deps.ts";
+import type { AuthenticatedResult } from "../context.ts";
+import { Deferred } from "../../utils/mod.ts";
+
+function createMockContext() {
+  const sentPackets: unknown[] = [];
+  return {
+    connectionState: ConnectionState.connecting as string,
+    pingTimer: { clear: () => {} },
+    unresolvedConnect: new Deferred<number>(),
+    authHandler: (
+      _ctx: unknown,
+      _authMethod: string,
+      _authData: Uint8Array,
+    ): Promise<AuthenticatedResult> => {
+      return Promise.resolve({
+        reasonCode: ReasonCode.continueAuthentication,
+        authData: new Uint8Array([1, 2, 3]),
+      });
+    },
+    send: (packet: unknown) => {
+      sentPackets.push(packet);
+    },
+    sentPackets,
+  };
+}
+
+test("handleAuth sets connected state on ReasonCode.success", async () => {
+  const ctx = createMockContext();
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.success,
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.connected,
+    "Should set connection state to connected when reasonCode is success",
+  );
+});
+
+test("handleAuth handles authentication failure when connecting", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connecting;
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.badAuthenticationMethod,
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.disconnecting,
+    "Should transition state to disconnecting on failure during connect",
+  );
+
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed/,
+    "Should reject unresolvedConnect with connect failed error",
+  );
+});
+
+test("handleAuth throws error on authentication failure when connected", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connected;
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.badAuthenticationMethod,
+  };
+
+  await assert.rejects(
+    async () => {
+      await handleAuth(ctx as never, packet);
+    },
+    Error,
+    "Should throw an error if reasonCode indicates failure after already connected",
+  );
+});
+
+test("handleAuth throws error if authMethod or authData is missing", async () => {
+  const ctx = createMockContext();
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      // authenticationData missing
+    },
+  };
+
+  await assert.rejects(
+    async () => {
+      await handleAuth(ctx as never, packet);
+    },
+    /Auth method and\/or Auth data missing/,
+    "Should throw when missing required auth properties",
+  );
+});
+
+test("handleAuth transitions state and sends response packet on continueAuthentication success", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connected;
+
+  ctx.authHandler = () =>
+    Promise.resolve({
+      reasonCode: ReasonCode.continueAuthentication,
+      authData: new Uint8Array([4, 5, 6]),
+      reasonString: "Continue",
+    });
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([1, 2, 3]),
+    },
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.authenticating,
+    "Should transition connection state to authenticating",
+  );
+  assert.deepStrictEqual(
+    ctx.sentPackets.length,
+    1,
+    "Should send a response auth packet",
+  );
+  assert.deepStrictEqual(ctx.sentPackets[0], {
+    type: PacketType.auth,
+    protocolLevel: 5,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([4, 5, 6]),
+      reasonString: "Continue",
+    },
+  });
+});
+
+test("handleAuth handles failure result from authHandler", async () => {
+  const ctx = createMockContext();
+  ctx.connectionState = ConnectionState.connecting;
+
+  ctx.authHandler = () =>
+    Promise.resolve({
+      reasonCode: ReasonCode.notAuthorized,
+      reasonString: "Not authorized to proceed",
+    });
+
+  const packet: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5 as const,
+    reasonCode: ReasonCode.continueAuthentication,
+    properties: {
+      authenticationMethod: "SCRAM-SHA-256",
+      authenticationData: new Uint8Array([1, 2, 3]),
+    },
+  };
+
+  await handleAuth(ctx as never, packet);
+
+  assert.deepStrictEqual(
+    ctx.connectionState,
+    ConnectionState.disconnecting,
+    "Should set state to disconnecting on authHandler failure",
+  );
+
+  await assert.rejects(
+    ctx.unresolvedConnect.promise,
+    /Connect failed: Not authorized to proceed/,
+    "Should reject unresolvedConnect with the reasonString provided by authHandler",
+  );
+});

package/client/handlers/handleAuth.ts

@@ -0,0 +1,89 @@
+import type { AuthenticatedResult, Context } from "../context.ts";
+import { ConnectionState } from "../ConnectionState.ts";
+import { PacketType, ReasonCode, ReasonCodeByNumber } from "../deps.ts";
+import type { AuthPacket } from "../deps.ts";
+
+/**
+ * Handle error
+ */
+
+function handleError(ctx: Context, errMsg: string) {
+  if (ctx.connectionState === ConnectionState.connecting) {
+    const err = new Error(
+      `Connect failed: ${errMsg}`,
+    );
+    ctx.connectionState = ConnectionState.disconnecting;
+    ctx.pingTimer?.clear();
+    ctx.unresolvedConnect?.reject(err);
+    return;
+  }
+  throw new Error(errMsg);
+}
+
+/**
+ * Handle success
+ */
+
+async function handleResult(
+  ctx: Context,
+  authMethod: string,
+  result: AuthenticatedResult,
+) {
+  await ctx.send({
+    type: PacketType.auth,
+    protocolLevel: 5,
+    reasonCode: result.reasonCode,
+    properties: result.authData
+      ? {
+        authenticationMethod: authMethod,
+        authenticationData: result.authData,
+        reasonString: result.reasonString,
+      }
+      : {},
+  });
+}
+
+/**
+ * Handles v5 Auth packet
+ * @param ctx - The connection context containing send method
+ * @returns Promise that resolves
+ */
+
+export async function handleAuth(
+  ctx: Context,
+  authPacket: AuthPacket,
+): Promise<void> {
+  const reasonCode = authPacket.reasonCode;
+  if (reasonCode === ReasonCode.success) {
+    // we are connected again
+    ctx.connectionState = ConnectionState.connected;
+    return;
+  }
+
+  if (reasonCode !== ReasonCode.continueAuthentication) {
+    // something went wrong
+    handleError(ctx, ReasonCodeByNumber[reasonCode]);
+    return;
+  }
+
+  // we need to send something back
+  if (ctx.connectionState === ConnectionState.connected) {
+    // pauze auther activities
+    ctx.connectionState = ConnectionState.authenticating;
+  }
+
+  const authMethod = authPacket.properties?.authenticationMethod;
+  const authData = authPacket.properties?.authenticationData;
+  if (!(authMethod && authData)) {
+    throw new Error("Auth method and/or Auth data missing");
+  }
+  const result = await ctx.authHandler(
+    ctx,
+    authMethod,
+    authData,
+  );
+  if (result.reasonCode === ReasonCode.continueAuthentication) {
+    return handleResult(ctx, authMethod, result);
+  }
+  return handleError(ctx, result.reasonString || "Error during authentication");
+}