@seriousme/opifex 1.11.3 → 2.1.0

package/client/client.ts

@@ -4,21 +4,24 @@ import {
   MemoryStore,
   MQTTLevel,
   PacketType,
+  ReasonCode,
 } from "./deps.ts";
 
 import type {
+  AuthenticationResult,
   ConnectPacket,
+  ProtocolLevel,
   PublishPacket,
   SockConn,
+  Store,
   SubscribePacket,
-  TAuthenticationResult,
 } from "./deps.ts";
 
-import { noop } from "../utils/utils.ts";
+import { noop } from "../utils/mod.ts";
 
 import { Context } from "./context.ts";
-import type { TConnectionState } from "./ConnectionState.ts";
-import { assert } from "../utils/assert.ts";
+import type { AuthenticatedResult } from "./context.ts";
+import type { ConnectionState } from "./ConnectionState.ts";
 import { BufferedAsyncIterable } from "./deps.ts";
 
 /**
@@ -30,18 +33,25 @@ function generateClientId(prefix: string): string {
   return `${prefix}-${Math.random().toString().slice(-10)}`;
 }
 
-type ConnectOptions = Omit<
+/** All properties of a connect packet, except for type and protocol name */
+export type ConnectOptions = Omit<
   ConnectPacket,
   "type" | "protocolName"
 >;
 
 /** ConnectParameters define how to connect */
 export type ConnectParameters = {
+  /** the URL to connect to */
   url?: URL | undefined;
+  /** any CA Certs to trust */
   caCerts?: string[] | undefined;
+  /** the clients certificate */
   cert?: string | undefined;
+  /** the clients private key*/
   key?: string | undefined;
+  /** number of retries before stopping connection attempts */
   numberOfRetries?: number | undefined;
+  /** connect options */
   options?: ConnectOptions | undefined;
 };
 
@@ -78,12 +88,26 @@ function backOffSleep(random: boolean, attempt: number): Promise<void> {
 /** the default MQTT URL to connect to */
 export const DEFAULT_URL = "mqtt://localhost:1883/";
 /** the default protocol level to connect with*/
-export const DEFAULT_PROTOCOLLEVEL = MQTTLevel.v4;
+export const DEFAULT_PROTOCOLLEVEL = MQTTLevel.v4 as ProtocolLevel;
 /** the default keepalive time */
 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,59 +118,83 @@ 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",
+    };
+  };
+  /** callback for errors */
   public onError: (err: Error) => void = noop;
+  /** callback for publish packets */
   public onPacket: (pkt: PublishPacket) => void | Promise<void> = noop;
+  /** callback once connected */
   public onConnected: () => void = noop;
+  /** callback once disconnected */
   public onDisconnected: () => void = noop;
+  /** callback when reconnecting */
   public onReconnecting: () => void = noop;
 
+  /** clientId prefix used when automatically generating a client Id */
   protected clientIdPrefix = CLIENTID_PREFIX;
+  /** number of times to retry connect */
   protected numberOfRetries = DEFAULT_RETRIES;
-  protected url: URL = new URL(DEFAULT_URL);
+  /** the URL to connect to */
+  protected connectUrl: URL = new URL(DEFAULT_URL);
+  /** the keepAlive value in number of seconds */
   protected keepAlive = DEFAULT_KEEPALIVE;
+  /** the requested protocol level */
   protected protocolLevel = DEFAULT_PROTOCOLLEVEL;
+  /** try auto reconnect if connection is lost */
   protected autoReconnect = true;
-  private caCerts?: string[] | undefined;
-  private cert?: string | undefined;
-  private key?: string | undefined;
-  private clientId: string;
+  /** any CA Certs to trust */
+  protected caCerts?: string[] | undefined;
+  /** the clients certificate */
+  protected cert?: string | undefined;
+  /** the clients private key*/
+  protected key?: string | undefined;
+  /** the MQTT clientId */
+  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?: Store) {
+    const cStore = store ? store : new MemoryStore();
+    this.ctx = new Context(cStore, this);
     this.clientId = generateClientId(this.clientIdPrefix);
     this.numberOfRetries = DEFAULT_RETRIES;
   }
 
-  get connectionState(): TConnectionState {
+  /**
+   * Current connection state
+   * @returns connectionState as ConnectionState
+   */
+  public get connectionState(): ConnectionState {
     return this.ctx.connectionState;
   }
 
+  /**
+   * Current configured connection URL
+   * @returns URL object
+   */
+  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 +211,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 +226,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 });
       }
 
@@ -212,8 +253,8 @@ export class Client {
    * @param params - Connection parameters
    * @returns Promise resolving to authentication result
    */
-  connect(params: ConnectParameters = {}): Promise<TAuthenticationResult> {
-    this.url = params?.url || this.url;
+  connect(params: ConnectParameters = {}): Promise<AuthenticationResult> {
+    this.connectUrl = params?.url || this.connectUrl;
     this.numberOfRetries = params.numberOfRetries || this.numberOfRetries;
     this.caCerts = params?.caCerts;
     this.cert = params?.cert;
@@ -230,7 +271,7 @@ export class Client {
       type: PacketType.connect,
       ...options,
     };
-    const deferred = new Deferred<TAuthenticationResult>();
+    const deferred = new Deferred<AuthenticationResult>();
     this.ctx.unresolvedConnect = deferred;
     this.doConnect();
     return deferred.promise;

package/client/context.ts

@@ -8,37 +8,55 @@ import {
 } from "./deps.ts";
 import type {
   AnyPacket,
+  AuthenticationResult,
   ConnectPacket,
-  MemoryStore,
   PacketId,
   ProtocolLevel,
   PublishPacket,
+  ReasonCode,
   ReturnCodes,
   SockConn,
+  Store,
   SubscribePacket,
-  TAuthenticationResult,
   UnsubscribePacket,
 } from "./deps.ts";
 
 import { handlePacket } from "./handlers/handlePacket.ts";
-import type { TConnectionState } from "./ConnectionState.ts";
 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: PacketType) {
+  return (
+    pktType === PacketType.publish ||
+    pktType === PacketType.subscribe ||
+    pktType === PacketType.unsubscribe
+  );
+}
+
+/** Possible results from authHandler */
+export type AuthenticatedResult = {
+  reasonCode: ReasonCode;
+  reasonString?: string;
+  authData?: Uint8Array;
+};
+
 export class Context {
   mqttConn?: MqttConn;
-  #connectionState: TConnectionState;
+  #connectionState: ConnectionState;
   protocolLevel: ProtocolLevel;
   pingTimer?: Timer;
-  unresolvedConnect?: Deferred<TAuthenticationResult>;
+  unresolvedConnect?: Deferred<AuthenticationResult>;
   unresolvedPublish: Map<PacketId, Deferred<void>>;
   unresolvedSubscribe: Map<PacketId, Deferred<ReturnCodes>>;
   unresolvedUnSubscribe: Map<PacketId, Deferred<void>>;
-  store: MemoryStore;
+  store: Store;
   #client: Client;
 
-  constructor(store: MemoryStore, client: Client) {
+  constructor(store: Store, client: Client) {
     this.#client = client;
     this.store = store;
     this.#connectionState = ConnectionState.offline;
@@ -48,11 +66,11 @@ export class Context {
     this.unresolvedUnSubscribe = new Map();
   }
 
-  get connectionState(): TConnectionState {
+  get connectionState(): ConnectionState {
     return this.#connectionState;
   }
 
-  set connectionState(state: TConnectionState) {
+  set connectionState(state: ConnectionState) {
     this.#connectionState = state;
     switch (state) {
       case "connected":
@@ -64,6 +82,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 +110,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 +133,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 +173,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 +188,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 +216,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 +225,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 +234,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,
@@ -16,9 +17,7 @@ export type {
   ReturnCodes,
   SubackPacket,
   SubscribePacket,
-  TAuthenticationResult,
   Topic,
-  TReasonCode,
   UnsubackPacket,
   UnsubscribePacket,
 } from "../mqttPacket/mod.ts";
@@ -31,11 +30,19 @@ export {
   MQTTLevel,
   PacketNameByType,
   PacketType,
+  ReasonCode,
   ReasonCodeByNumber,
 } from "../mqttPacket/mod.ts";
 
 export { MqttConn } from "../mqttConn/mqttConn.ts";
-export type { SockConn } from "../socket/socket.ts";
+export type {
+  NetAddr,
+  SockAddr,
+  SockConn,
+  UnixAddr,
+  VsockAddr,
+} 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 { Store } 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",
+  );
+});