@seriousme/opifex 1.1.0

package/client/client.ts

@@ -0,0 +1,181 @@
+import {
+  type ConnectPacket,
+  Deferred,
+  logger,
+  MemoryStore,
+  PacketType,
+  type PublishPacket,
+  type SockConn,
+  type SubscribePacket,
+  type TAuthenticationResult,
+} from "./deps.ts";
+
+import { Context } from "./context.ts";
+
+function generateClientId(prefix: string): string {
+  return `${prefix}-${Math.random().toString().slice(-10)}`;
+}
+
+type ConnectOptions = Omit<
+  ConnectPacket,
+  "type" | "protocolName" | "protocolLevel"
+>;
+
+/** ConnectParameters define how to connect */
+export type ConnectParameters = {
+  url?: URL;
+  caCerts?: string[];
+  numberOfRetries?: number;
+  options?: ConnectOptions;
+};
+
+/** PublishParameters define how a message should be published */
+export type PublishParameters = Omit<PublishPacket, "type" | "id">;
+/** SubscribeParameters define how to subscribe to a topic */
+export type SubscribeParameters = Omit<SubscribePacket, "type" | "id">;
+
+function backOffSleep(random: boolean, attempt: number): Promise<void> {
+  // based on https://dthain.blogspot.com/2009/02/exponential-backoff-in-distributed.html
+  const factor = 1.5;
+  const min = 1000;
+  const max = 5000;
+  const randomness = 1 + (random ? Math.random() : 0);
+  const delay = Math.floor(
+    Math.min(randomness * min * (factor ** attempt), max),
+  );
+  logger.debug({ delay });
+  return new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+/**  the default MQTT URL to connect to */
+export const DEFAULT_URL = "mqtt://localhost:1883/";
+const DEFAULT_KEEPALIVE = 60; // 60 seconds
+const DEFAULT_RETRIES = 3; // on first connect
+const CLIENTID_PREFIX = "opifex"; // on first connect
+
+/**
+ * The Client class provides an MQTT Client that can be used to connect to
+ * a MQTT broker and publish/subscribe messages.
+ *
+ * The Client class is not meant to be used directly, but
+ * instead should be subclassed and the subclass should
+ * override the createConn() method to provide a
+ * connection type that is supported by the subclass.
+ */
+
+export class Client {
+  protected clientIdPrefix = CLIENTID_PREFIX;
+  protected numberOfRetries = DEFAULT_RETRIES;
+  protected url: URL = new URL(DEFAULT_URL);
+  protected keepAlive = DEFAULT_KEEPALIVE;
+  protected autoReconnect = true;
+  private caCerts?: string[];
+  private clientId: string;
+  private ctx = new Context(new MemoryStore());
+  private connectPacket?: ConnectPacket;
+
+  constructor() {
+    this.clientId = generateClientId(this.clientIdPrefix);
+    this.numberOfRetries = DEFAULT_RETRIES;
+  }
+
+  protected createConn(
+    protocol: string,
+    _hostname: string,
+    _port?: number,
+    _caCerts?: string[],
+  ): Promise<SockConn> {
+    // if you need to support alternative connection types just
+    // overload this method in your subclass
+    throw `Unsupported protocol: ${protocol}`;
+  }
+
+  private async doConnect(): Promise<void> {
+    if (!this.connectPacket) {
+      return;
+    }
+    let isReconnect = false;
+    let attempt = 1;
+    let lastMessage = "";
+    let tryConnect = true;
+    while (tryConnect) {
+      logger.debug(`${isReconnect ? "re" : ""}connecting`);
+      try {
+        const conn = await this.createConn(
+          this.url.protocol,
+          this.url.hostname,
+          Number(this.url.port) ?? undefined,
+          this.caCerts,
+        );
+        // if we get this far we have a connection
+        tryConnect =
+          (await this.ctx.handleConnection(conn, this.connectPacket)) &&
+          this.autoReconnect;
+        logger.debug({ tryConnect });
+        isReconnect = true;
+        this.connectPacket.clean = false;
+        this.ctx.close();
+      } catch (err) {
+        if (err instanceof Error) {
+          lastMessage = `Connection failed: ${err.message}`;
+        }
+        logger.debug(lastMessage);
+        if (!isReconnect && attempt > this.numberOfRetries) {
+          tryConnect = false;
+        } else {
+          await backOffSleep(true, attempt++);
+        }
+      }
+    }
+
+    if (isReconnect === false) {
+      this.ctx.unresolvedConnect?.reject(Error(lastMessage));
+    }
+  }
+
+  connect(params: ConnectParameters = {}): Promise<TAuthenticationResult> {
+    this.url = params?.url || this.url;
+    this.numberOfRetries = params.numberOfRetries || this.numberOfRetries;
+    this.caCerts = params?.caCerts;
+    const options = Object.assign(
+      {
+        keepAlive: this.keepAlive,
+        clientId: this.clientId,
+      },
+      params?.options,
+    );
+    this.connectPacket = {
+      type: PacketType.connect,
+      ...options,
+    };
+    const deferred = new Deferred<TAuthenticationResult>();
+    this.ctx.unresolvedConnect = deferred;
+    this.doConnect();
+    return deferred.promise;
+  }
+
+  async disconnect(): Promise<void> {
+    await this.ctx.disconnect();
+  }
+
+  async publish(params: PublishParameters): Promise<void> {
+    const packet: PublishPacket = {
+      type: PacketType.publish,
+      ...params,
+    };
+    await this.ctx.send(packet);
+  }
+
+  async subscribe(params: SubscribeParameters): Promise<void> {
+    const packet: SubscribePacket = {
+      type: PacketType.subscribe,
+      id: this.ctx.store.nextId(),
+      ...params,
+    };
+    await this.ctx.send(packet);
+  }
+
+  async *messages(): AsyncGenerator<PublishPacket, void, unknown> {
+    yield* this.ctx.incoming;
+  }
+}

package/client/context.ts

@@ -0,0 +1,197 @@
+import {
+  type AnyPacket,
+  AsyncQueue,
+  type ConnectPacket,
+  Deferred,
+  logger,
+  type MemoryStore,
+  MqttConn,
+  type PacketId,
+  PacketType,
+  type PublishPacket,
+  type ReturnCodes,
+  type SockConn,
+  type SubscribePacket,
+  type TAuthenticationResult,
+  Timer,
+  type UnsubscribePacket,
+} from "./deps.ts";
+
+import { handlePacket } from "./handlers/handlePacket.ts";
+
+export const ConnectionState = {
+  offline: "offline",
+  connecting: "connecting",
+  connected: "connected",
+  disconnecting: "disconnecting",
+  disconnected: "disconnected",
+} as const;
+
+export type TConnectionState =
+  typeof ConnectionState[keyof typeof ConnectionState];
+
+export class Context {
+  mqttConn?: MqttConn;
+  connectionState: TConnectionState;
+  pingTimer?: Timer;
+  unresolvedConnect?: Deferred<TAuthenticationResult>;
+  unresolvedPublish: Map<PacketId, Deferred<void>>;
+  unresolvedSubscribe: Map<PacketId, Deferred<ReturnCodes>>;
+  unresolvedUnSubscribe: Map<PacketId, Deferred<void>>;
+  store: MemoryStore;
+  incoming: AsyncQueue<PublishPacket>;
+
+  constructor(store: MemoryStore) {
+    this.store = store;
+    this.connectionState = ConnectionState.offline;
+    this.incoming = new AsyncQueue();
+    this.unresolvedPublish = new Map();
+    this.unresolvedSubscribe = new Map();
+    this.unresolvedUnSubscribe = new Map();
+  }
+
+  async connect(packet: ConnectPacket) {
+    this.connectionState = ConnectionState.connecting;
+    await this.mqttConn?.send(packet);
+    const keepAlive = packet.keepAlive || 0;
+    if (keepAlive > 0) {
+      this.pingTimer = new Timer(
+        this.sendPing.bind(this),
+        keepAlive * 1000,
+        true,
+      );
+    }
+  }
+
+  async disconnect() {
+    if (this.connectionState !== ConnectionState.connected) {
+      throw "Not connected";
+    }
+    if (this.mqttConn) {
+      this.connectionState = ConnectionState.disconnecting;
+      await this.mqttConn.send({ type: PacketType.disconnect });
+      this.mqttConn.close();
+    }
+  }
+
+  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("not connected");
+    this.pingTimer?.clear();
+  }
+
+  sendPing() {
+    this.send({ type: PacketType.pingreq });
+  }
+
+  async handleConnection(
+    conn: SockConn,
+    connectPacket: ConnectPacket,
+  ): Promise<boolean> {
+    this.mqttConn = new MqttConn({ conn });
+    if (this.mqttConn === undefined) {
+      return true;
+    }
+    await this.connect(connectPacket);
+    try {
+      for await (const packet of this.mqttConn) {
+        handlePacket(this, packet);
+      }
+      logger.debug("No more packets");
+    } catch (err) {
+      logger.debug(err);
+      if (this.mqttConn.isClosed) {
+        this.mqttConn.close();
+      }
+    }
+    if (this.connectionState === ConnectionState.disconnecting) {
+      return false;
+    }
+    return true;
+  }
+
+  close() {
+    logger.debug("closing connection");
+    this.connectionState = ConnectionState.disconnected;
+    this.pingTimer?.clear();
+  }
+
+  receivePublish(packet: PublishPacket) {
+    this.incoming.push(packet);
+  }
+
+  publish(packet: PublishPacket): Promise<void> {
+    const qos = packet.qos || 0;
+    if (qos === 0) {
+      packet.id = 0;
+      this.send(packet);
+      // return empty promise
+      return Promise.resolve();
+    }
+    packet.id = this.store.nextId();
+    this.store.pendingOutgoing.set(packet.id, packet);
+    const deferred = new Deferred<void>();
+    this.unresolvedPublish.set(packet.id, deferred);
+    this.send(packet);
+    return deferred.promise;
+  }
+
+  subscribe(packet: SubscribePacket): Promise<ReturnCodes> {
+    packet.id = this.store.nextId();
+    this.store.pendingOutgoing.set(packet.id, packet);
+    const deferred = new Deferred<ReturnCodes>();
+    this.unresolvedSubscribe.set(packet.id, deferred);
+    this.send(packet);
+    return deferred.promise;
+  }
+
+  unsubscribe(packet: UnsubscribePacket): Promise<void> {
+    packet.id = this.store.nextId();
+    this.store.pendingOutgoing.set(packet.id, packet);
+    const deferred = new Deferred<void>();
+    this.unresolvedUnSubscribe.set(packet.id, deferred);
+    this.send(packet);
+    return deferred.promise;
+  }
+
+  receivePuback(id: PacketId): boolean {
+    const unresolvedMap = this.unresolvedPublish;
+    if (unresolvedMap.has(id)) {
+      const deferred = unresolvedMap.get(id);
+      unresolvedMap.delete(id);
+      deferred?.resolve();
+      return true;
+    }
+    return false;
+  }
+
+  receiveSuback(id: PacketId, returnCodes: ReturnCodes): boolean {
+    const unresolvedMap = this.unresolvedSubscribe;
+    if (unresolvedMap.has(id)) {
+      const deferred = unresolvedMap.get(id);
+      unresolvedMap.delete(id);
+      deferred?.resolve(returnCodes);
+      return true;
+    }
+    return false;
+  }
+
+  receiveUnsuback(id: PacketId): boolean {
+    const unresolvedMap = this.unresolvedUnSubscribe;
+    if (unresolvedMap.has(id)) {
+      const deferred = unresolvedMap.get(id);
+      unresolvedMap.delete(id);
+      deferred?.resolve();
+      return true;
+    }
+    return false;
+  }
+}

package/client/deps.ts

@@ -0,0 +1,36 @@
+export type {
+  AnyPacket,
+  ConnackPacket,
+  ConnectPacket,
+  DisconnectPacket,
+  Dup,
+  PacketId,
+  Payload,
+  PubackPacket,
+  PubcompPacket,
+  PublishPacket,
+  PubrecPacket,
+  PubrelPacket,
+  ReturnCodes,
+  SubackPacket,
+  SubscribePacket,
+  TAuthenticationResult,
+  Topic,
+  UnsubackPacket,
+  UnsubscribePacket,
+} from "../mqttPacket/mod.ts";
+
+export {
+  AuthenticationResult,
+  AuthenticationResultByNumber,
+  decodePayload,
+  encode,
+  PacketNameByType,
+  PacketType,
+} from "../mqttPacket/mod.ts";
+
+export { MqttConn } from "../mqttConn/mqttConn.ts";
+export type { SockConn } from "../socket/socket.ts";
+export { Timer } from "../timer/timer.ts";
+export { AsyncQueue, Deferred, logger } from "../utils/mod.ts";
+export { MemoryStore } from "./store/memoryStore.ts";

package/client/handlers/handleConnack.ts

@@ -0,0 +1,21 @@
+import { ConnectionState, type Context } from "../context.ts";
+import { AuthenticationResultByNumber, type ConnackPacket } from "../deps.ts";
+
+export async function handleConnack(packet: ConnackPacket, ctx: Context) {
+  if (packet.returnCode === 0) {
+    ctx.connectionState = ConnectionState.connected;
+    ctx.pingTimer?.reset();
+    ctx.unresolvedConnect?.resolve(packet.returnCode);
+    // start transmitting packets that were queued before
+    for await (const packet of ctx.store.pendingOutgoingPackets()) {
+      ctx.send(packet);
+    }
+    return;
+  }
+  const err = new Error(
+    `Connect failed: ${AuthenticationResultByNumber[packet.returnCode]}`,
+  );
+  ctx.connectionState = ConnectionState.disconnecting;
+  ctx.pingTimer?.clear();
+  ctx.unresolvedConnect?.reject(err);
+}

package/client/handlers/handlePacket.ts

@@ -0,0 +1,70 @@
+import { ConnectionState, type Context } from "../context.ts";
+import { handleConnack } from "./handleConnack.ts";
+import { handlePublish } from "./handlePublish.ts";
+import { handlePuback } from "./handlePuback.ts";
+import { handlePubrec } from "./handlePubrec.ts";
+import { handlePubrel } from "./handlePubrel.ts";
+import { handlePubcomp } from "./handlePubcomp.ts";
+import { handleSuback } from "./handleSuback.ts";
+import { handleUnsuback } from "./handleUnsuback.ts";
+import { logger, PacketNameByType, PacketType } from "../deps.ts";
+import type {
+  AnyPacket,
+  ConnackPacket,
+  PubackPacket,
+  PubcompPacket,
+  PublishPacket,
+  PubrecPacket,
+  PubrelPacket,
+  SubackPacket,
+  UnsubackPacket,
+} from "../deps.ts";
+
+export async function handlePacket(
+  ctx: Context,
+  packet: AnyPacket,
+): Promise<void> {
+  logger.debug({ received: JSON.stringify(packet, null, 2) });
+  if (ctx.connectionState !== ConnectionState.connected) {
+    if (packet.type === PacketType.connack) {
+      handleConnack(packet as ConnackPacket, ctx);
+    } else {
+      throw new Error(
+        `Received ${PacketNameByType[packet.type]} packet before connect`,
+      );
+    }
+  } else {
+    switch (packet.type) {
+      case PacketType.pingres:
+        break;
+      case PacketType.publish:
+        await handlePublish(ctx, packet as PublishPacket);
+        break;
+      case PacketType.puback:
+        await handlePuback(ctx, packet as PubackPacket);
+        break;
+      case PacketType.pubrel:
+        await handlePubrel(ctx, packet as PubrelPacket);
+        break;
+      case PacketType.pubrec:
+        await handlePubrec(ctx, packet as PubrecPacket);
+        break;
+      case PacketType.pubcomp:
+        await handlePubcomp(ctx, packet as PubcompPacket);
+        break;
+      case PacketType.suback:
+        await handleSuback(ctx, packet as SubackPacket);
+        break;
+      case PacketType.unsuback:
+        handleUnsuback(ctx, packet as UnsubackPacket);
+        break;
+
+      default:
+        throw new Error(
+          `Received unexpected ${
+            PacketNameByType[packet.type]
+          } packet after connect`,
+        );
+    }
+  }
+}

package/client/handlers/handlePuback.ts

@@ -0,0 +1,10 @@
+import type { Context } from "../context.ts";
+import type { PubackPacket } from "../deps.ts";
+
+// A PUBACK Packet is the response to a PUBLISH Packet with QoS level 1.
+
+export function handlePuback(ctx: Context, packet: PubackPacket): void {
+  const id = packet.id;
+  ctx.store.pendingOutgoing.delete(id);
+  ctx.receivePuback(id);
+}

package/client/handlers/handlePubcomp.ts

@@ -0,0 +1,13 @@
+import type { Context } from "../context.ts";
+import type { PubcompPacket } from "../deps.ts";
+
+// The PUBCOMP Packet is the response to a PUBREL Packet.
+// It is the fourth and final packet of the QoS 2 protocol exchange.
+
+export function handlePubcomp(ctx: Context, packet: PubcompPacket): void {
+  const id = packet.id;
+  if (ctx.store.pendingAckOutgoing.has(id)) {
+    ctx.store.pendingAckOutgoing.delete(id);
+    ctx.receivePuback(id);
+  }
+}

package/client/handlers/handlePublish.ts

@@ -0,0 +1,32 @@
+import type { Context } from "../context.ts";
+import { PacketType, type PublishPacket } from "../deps.ts";
+
+// Incoming publish
+
+export async function handlePublish(ctx: Context, packet: PublishPacket) {
+  const qos = packet.qos || 0;
+  if (qos === 0) {
+    ctx.receivePublish(packet);
+    return;
+  }
+
+  if (packet.id !== undefined) {
+    // qos 1
+    if (qos === 1) {
+      ctx.receivePublish(packet);
+      await ctx.send({
+        type: PacketType.puback,
+        id: packet.id,
+      });
+      return;
+    }
+    // qos 2
+    if (ctx.store) {
+      ctx.store.pendingIncoming.set(packet.id, packet);
+      await ctx.send({
+        type: PacketType.pubrec,
+        id: packet.id,
+      });
+    }
+  }
+}

package/client/handlers/handlePubrec.ts

@@ -0,0 +1,24 @@
+import type { Context } from "../context.ts";
+import { PacketType, type PubrecPacket, type PubrelPacket } from "../deps.ts";
+
+// A PUBREC Packet is the response to a PUBLISH Packet with QoS 2.
+// It is the second packet of the QoS 2 protocol exchange.
+
+// Discard message, Store PUBREC received <Packet Identifier>
+// send PUBREL <Packet Identifier>
+
+export async function handlePubrec(
+  ctx: Context,
+  packet: PubrecPacket,
+): Promise<void> {
+  const id = packet.id;
+  const ack: PubrelPacket = {
+    type: PacketType.pubrel,
+    id,
+  };
+  if (ctx.store.pendingOutgoing.has(id)) {
+    ctx.store.pendingAckOutgoing.set(id, ack);
+    ctx.store.pendingOutgoing.delete(id);
+    await ctx.send(ack);
+  }
+}

package/client/handlers/handlePubrel.ts

@@ -0,0 +1,26 @@
+import type { Context } from "../context.ts";
+import { PacketType, type PubrelPacket } from "../deps.ts";
+
+// A PUBREL Packet is the response to a PUBREC Packet.
+// It is the third packet of the QoS 2 protocol exchange.
+
+// Method A, Initiate onward delivery of the Application Message then discard message
+// Send PUBCOMP <Packet Identifier>
+
+export async function handlePubrel(
+  ctx: Context,
+  packet: PubrelPacket,
+): Promise<void> {
+  const id = packet.id;
+  if (ctx.store.pendingIncoming.has(id)) {
+    const storedPacket = ctx.store.pendingIncoming.get(id);
+    if (storedPacket) {
+      ctx.receivePublish(storedPacket);
+      ctx.store.pendingIncoming.delete(id);
+      await ctx.send({
+        type: PacketType.pubcomp,
+        id,
+      });
+    }
+  }
+}

package/client/handlers/handleSuback.ts

@@ -0,0 +1,14 @@
+import type { Context } from "../context.ts";
+import type { SubackPacket } from "../deps.ts";
+
+// A SUBACK Packet is sent by the Server to the Client to confirm receipt
+// and processing of a SUBSCRIBE Packet.
+
+// A SUBACK Packet contains a list of return codes, that specify the maximum QoS level
+// that was granted in each Subscription that was requested by the SUBSCRIBE.
+
+export function handleSuback(ctx: Context, packet: SubackPacket): void {
+  const id = packet.id;
+  ctx.store.pendingOutgoing.delete(id);
+  ctx.receiveSuback(id, packet.returnCodes);
+}

package/client/handlers/handleUnsuback.ts

@@ -0,0 +1,11 @@
+import type { Context } from "../context.ts";
+import type { UnsubackPacket } from "../deps.ts";
+
+// The UNSUBACK Packet is sent by the Server to the Client to confirm receipt
+// of an UNSUBSCRIBE Packet.
+
+export function handleUnsuback(ctx: Context, packet: UnsubackPacket): void {
+  const id = packet.id;
+  ctx.store.pendingOutgoing.delete(id);
+  ctx.receiveUnsuback(id);
+}

package/client/mod.ts

@@ -0,0 +1,11 @@
+/**
+ *  This module provides an MQTT Client interface
+ *  see the /bin folder for examples
+ *  @module
+ */
+export { Client, DEFAULT_URL } from "./client.ts";
+export type {
+  ConnectParameters,
+  PublishParameters,
+  SubscribeParameters,
+} from "./client.ts";

package/client/store/deps.ts

@@ -0,0 +1,22 @@
+export type {
+  AnyPacket,
+  ConnackPacket,
+  ConnectPacket,
+  DisconnectPacket,
+  Dup,
+  PacketId,
+  Payload,
+  PubackPacket,
+  PubcompPacket,
+  PublishPacket,
+  PubrecPacket,
+  PubrelPacket,
+  ReturnCodes,
+  SubackPacket,
+  SubscribePacket,
+  Topic,
+  UnsubackPacket,
+  UnsubscribePacket,
+} from "../../mqttPacket/mod.ts";
+
+export { assert } from "../../utils/mod.ts";