@seriousme/opifex 1.11.2 → 2.0.3

package/mqttPacket/subscribe.ts

@@ -1,181 +1,205 @@
 import type {
   CodecOpts,
   PacketId,
-  ProtocolLevelNoV5,
   QoS,
   TopicFilter,
   TPacketType,
   TRetainHandling,
 } from "./types.ts";
+import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { SubscribeProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
 import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
 import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * Represents an MQTT SUBSCRIBE packet conforming to MQTT version 3.1.1 (Protocol Level 4) or lower.
+ */
 export type SubscribePacketV4 = {
+  /** The type of the MQTT control packet. */
   type: TPacketType;
+  /** The protocol version level, restricted to non-v5 variants. */
   protocolLevel: ProtocolLevelNoV5;
+  /** The unique 16-bit packet identifier. */
   id: PacketId;
+  /** The list of topic subscriptions associated with this packet. */
   subscriptions: Array<SubscriptionV4>;
 };
 
+/**
+ * Represents an MQTT SUBSCRIBE packet conforming to MQTT version 5.0.
+ */
 export type SubscribePacketV5 = {
+  /** The type of the MQTT control packet. */
   type: TPacketType;
+  /** The protocol version level, strictly set to 5. */
   protocolLevel: 5;
+  /** The unique 16-bit packet identifier. */
   id: PacketId;
+  /** Optional user and protocol properties introduced in MQTT v5. */
   properties?: SubscribeProperties;
+  /** The list of topic subscriptions including v5 option flags. */
   subscriptions: Array<SubscriptionV5>;
 };
 
 /**
- * SubscribePacket is sent from client to server to subscribe to topics
+ * Represents a union of available MQTT SUBSCRIBE packets (v4 or v5) sent from client to server.
  */
 export type SubscribePacket = SubscribePacketV4 | SubscribePacketV5;
+
 /**
- * The topic to subscribe to and the associated QoS
+ * Describes a topic subscription requirement for MQTT version 3.1.1.
  */
 export type SubscriptionV4 = {
+  /** The topic filter expression the client intends to subscribe to. */
   topicFilter: TopicFilter;
+  /** The maximum Quality of Service level authorized for this topic filter. */
   qos: QoS;
 };
 
+/**
+ * Describes a topic subscription requirement for MQTT version 5.0, including extended flags.
+ */
 export type SubscriptionV5 = {
+  /** The topic filter expression the client intends to subscribe to. */
   topicFilter: TopicFilter;
+  /** The maximum Quality of Service level authorized for this topic filter. */
   qos: QoS;
+  /** Optional flag indicating whether messages should not be forwarded back to the client that published them. */
   noLocal?: boolean;
+  /** Optional flag indicating whether messages forwarded under this subscription keep their original retain flag. */
   retainAsPublished?: boolean;
+  /** Optional setting declaring how retained messages are handled when the subscription is created. */
   retainHandling?: TRetainHandling;
 };
 
+/** * Represents a generic union of MQTT subscription configurations (v4 or v5).
+ */
 export type Subscription = SubscriptionV4 | SubscriptionV5;
 
-export const subscribe: {
-  encode(packet: SubscribePacket, codecOpts: CodecOpts): Uint8Array;
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): SubscribePacket;
-} = {
-  encode(packet: SubscribePacket, codecOpts: CodecOpts): Uint8Array {
-    // Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and
-    // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
-    // malformed and close the Network Connection [MQTT-3.8.1-1].
-    const flags = 0b0010;
+/**
+ * Codec utility object responsible for encoding and decoding MQTT SUBSCRIBE control packets.
+ */
+export function encode(
+  packet: SubscribePacket,
+  codecOpts: CodecOpts,
+): Uint8Array {
+  // Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and
+  // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
+  // malformed and close the Network Connection [MQTT-3.8.1-1].
+  const flags = 0b0010;
 
-    const encoder = new Encoder(packet.type);
-    encoder.setInt16(packet.id);
+  const encoder = new Encoder(packet.type);
+  encoder.setInt16(packet.id);
+  if (packet.protocolLevel === 5) {
+    encoder.setProperties(
+      packet.properties || {},
+      packet.type,
+      codecOpts.maxOutgoingPacketSize,
+    );
+  }
+  for (const sub of packet.subscriptions) {
+    encoder.setUtf8String(sub.topicFilter);
     if (packet.protocolLevel === 5) {
-      encoder.setProperties(
-        packet.properties || {},
-        packet.type,
-        codecOpts.maxOutgoingPacketSize,
-      );
-    }
-    for (const sub of packet.subscriptions) {
-      encoder.setTopicFilter(sub.topicFilter);
-      if (packet.protocolLevel === 5) {
-        const {
-          qos,
-          noLocal = false,
-          retainAsPublished = false,
-          retainHandling = 0,
-        } = sub as SubscriptionV5;
-        const option = (qos & 1 ? BitMask.bit0 : 0) +
-          (qos & 2 ? BitMask.bit1 : 0) +
-          (noLocal ? BitMask.bit2 : 0) +
-          (retainAsPublished ? BitMask.bit3 : 0) +
-          ((retainHandling as number) & 1 ? BitMask.bit4 : 0) +
-          ((retainHandling as number) & 2 ? BitMask.bit5 : 0);
-        encoder.setByte(option);
-      } else {
-        encoder.setByte(sub.qos);
-      }
+      const {
+        qos,
+        noLocal = false,
+        retainAsPublished = false,
+        retainHandling = 0,
+      } = sub as SubscriptionV5;
+      const option = (qos & 1 ? BitMask.bit0 : 0) +
+        (qos & 2 ? BitMask.bit1 : 0) +
+        (noLocal ? BitMask.bit2 : 0) +
+        (retainAsPublished ? BitMask.bit3 : 0) +
+        ((retainHandling as number) & 1 ? BitMask.bit4 : 0) +
+        ((retainHandling as number) & 2 ? BitMask.bit5 : 0);
+      encoder.setByte(option);
+    } else {
+      encoder.setByte(sub.qos);
     }
-    return encoder.done(flags);
-  },
+  }
+  return encoder.done(flags);
+}
+
+export function decode(
+  buffer: Uint8Array,
+  flags: number,
+  codecOpts: CodecOpts,
+  packetType: TPacketType,
+): SubscribePacket {
+  // Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and
+  // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
+  // malformed and close the Network Connection [MQTT-3.8.1-1].
+  if (flags !== 0b0010) {
+    throw new DecoderError("Invalid header");
+  }
+  const decoder = new Decoder(packetType, buffer);
+  const id = decoder.getInt16();
+  let properties = {};
+  if (codecOpts.protocolLevel === 5) {
+    properties = decoder.getProperties(PacketType.subscribe);
+  }
 
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): SubscribePacket {
-    // Bits 3,2,1 and 0 of the fixed header of the SUBSCRIBE Control Packet are reserved and
-    // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
-    // malformed and close the Network Connection [MQTT-3.8.1-1].
-    if (flags !== 0b0010) {
-      throw new DecoderError("Invalid header");
+  const subscriptions: Subscription[] = [];
+  // The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / Option pair.
+  // A SUBSCRIBE packet with no payload is a protocol violation [MQTT-3.8.3-3].
+  do {
+    const topicFilter = decoder.getUTF8String();
+    const option = decoder.getByte();
+    const qos = option & 0b11;
+    if (qos !== 0 && qos !== 1 && qos !== 2) {
+      throw new DecoderError("Invalid qos");
     }
-    const decoder = new Decoder(packetType, buffer);
-    const id = decoder.getInt16();
-    let properties = {};
-    if (codecOpts.protocolLevel === 5) {
-      properties = decoder.getProperties(PacketType.subscribe);
+    if (qos > 0 && id === 0) {
+      throw new DecoderError("Invalid packet identifier");
     }
-
-    const subscriptions: Subscription[] = [];
-    // The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / Option pair.
-    // A SUBSCRIBE packet with no payload is a protocol violation [MQTT-3.8.3-3].
-    do {
-      const topicFilter = decoder.getTopicFilter();
-      const option = decoder.getByte();
-      const qos = option & 0b11;
-      if (qos !== 0 && qos !== 1 && qos !== 2) {
+    if (codecOpts.protocolLevel !== 5) {
+      if (option !== qos) {
         throw new DecoderError("Invalid qos");
       }
-      if (qos > 0 && id === 0) {
-        throw new DecoderError("Invalid packet identifier");
+      subscriptions.push({
+        topicFilter: topicFilter,
+        qos,
+      } as SubscriptionV4);
+    } else {
+      // Bits 6 and 7 of the Subscription Options byte are reserved for future use.
+      // The Server MUST treat a SUBSCRIBE packet as malformed if any of
+      // Reserved bits in the Payload are non-zero [MQTT-3.8.3-5].
+      if (option > 0b111111) {
+        throw new DecoderError("Invalid subscription options");
       }
-      if (codecOpts.protocolLevel !== 5) {
-        if (option !== qos) {
-          throw new DecoderError("Invalid qos");
-        }
-        subscriptions.push({
-          topicFilter: topicFilter,
-          qos,
-        } as SubscriptionV4);
-      } else {
-        // Bits 6 and 7 of the Subscription Options byte are reserved for future use.
-        // The Server MUST treat a SUBSCRIBE packet as malformed if any of
-        // Reserved bits in the Payload are non-zero [MQTT-3.8.3-5].
-        if (option > 0b111111) {
-          throw new DecoderError("Invalid subscription options");
-        }
-        const noLocal = booleanFlag(option, BitMask.bit2);
-        const retainAsPublished = booleanFlag(option, BitMask.bit3);
-        const retainHandling = (option & 0b110000) >> 4;
-        if (
-          retainHandling !== 0 && retainHandling !== 1 && retainHandling !== 2
-        ) {
-          throw new DecoderError("Invalid retain handling");
-        }
-        subscriptions.push({
-          topicFilter: topicFilter,
-          qos,
-          noLocal,
-          retainAsPublished,
-          retainHandling,
-        } as SubscriptionV5);
+      const noLocal = booleanFlag(option, BitMask.bit2);
+      const retainAsPublished = booleanFlag(option, BitMask.bit3);
+      const retainHandling = (option & 0b110000) >> 4;
+      if (
+        retainHandling !== 0 && retainHandling !== 1 && retainHandling !== 2
+      ) {
+        throw new DecoderError("Invalid retain handling");
       }
-    } while (!decoder.atEnd());
-    decoder.done();
-    if (codecOpts.protocolLevel !== 5) {
-      return {
-        type: PacketType.subscribe,
-        protocolLevel: codecOpts.protocolLevel,
-        id,
-        subscriptions: subscriptions as Array<SubscriptionV4>,
-      };
+      subscriptions.push({
+        topicFilter: topicFilter,
+        qos,
+        noLocal,
+        retainAsPublished,
+        retainHandling,
+      } as SubscriptionV5);
     }
+  } while (!decoder.atEnd());
+  decoder.done();
+  if (codecOpts.protocolLevel !== 5) {
     return {
       type: PacketType.subscribe,
-      protocolLevel: 5,
+      protocolLevel: codecOpts.protocolLevel,
       id,
-      properties,
-      subscriptions: subscriptions as Array<SubscriptionV5>,
+      subscriptions: subscriptions as Array<SubscriptionV4>,
     };
-  },
-};
+  }
+  return {
+    type: PacketType.subscribe,
+    protocolLevel: 5,
+    id,
+    properties,
+    subscriptions: subscriptions as Array<SubscriptionV5>,
+  };
+}

package/mqttPacket/types.ts

@@ -3,6 +3,7 @@ import type { PacketType } from "./PacketType.ts";
 import type { RetainHandling } from "./RetainHandling.ts";
 import type { AuthenticationResult } from "./AuthenticationResult.ts";
 import type { ReasonCode } from "./ReasonCode.ts";
+import type { ProtocolLevel } from "./protocolLevels.ts";
 
 /**
  * Type to limit bit mask to valid values
@@ -24,15 +25,6 @@ export type TAuthenticationResult =
  */
 export type TReasonCode = typeof ReasonCode[keyof typeof ReasonCode];
 
-/**
- * Protocol version
- * 3.1 = 3
- * 3.1.1 = 4
- * 5.0 = 5
- */
-export type ProtocolLevel = 3 | 4 | 5 | undefined;
-export type ProtocolLevelNoV5 = Exclude<ProtocolLevel, 5>;
-
 /**
  * Quality of Service level
  */

package/mqttPacket/unsuback.ts

@@ -1,10 +1,5 @@
-import type {
-  CodecOpts,
-  PacketId,
-  ProtocolLevelNoV5,
-  TPacketType,
-  TReasonCode,
-} from "./types.ts";
+import type { CodecOpts, PacketId, TPacketType, TReasonCode } from "./types.ts";
+import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { UnsubackProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
 import { Decoder, hasEmptyFlags } from "./decoder.ts";
@@ -30,61 +25,54 @@ export type UnsubackPacketV5 = {
  */
 export type UnsubackPacket = UnsubackPacketV4 | UnsubackPacketV5;
 
-export const unsuback: {
-  encode(packet: UnsubackPacket, codecOpts: CodecOpts): Uint8Array;
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): UnsubackPacket;
-} = {
-  encode(packet: UnsubackPacket, codecOpts: CodecOpts): Uint8Array {
-    const flags = 0;
-    const encoder = new Encoder(packet.type);
-    encoder.setInt16(packet.id);
-    if (packet.protocolLevel === 5) {
-      encoder.setProperties(
-        packet.properties || {},
-        PacketType.unsuback,
-        codecOpts.maxOutgoingPacketSize,
-      );
-      for (const reasonCode of packet.reasonCodes) {
-        encoder.setByte(reasonCode);
-      }
+export function encode(
+  packet: UnsubackPacket,
+  codecOpts: CodecOpts,
+): Uint8Array {
+  const flags = 0;
+  const encoder = new Encoder(packet.type);
+  encoder.setInt16(packet.id);
+  if (packet.protocolLevel === 5) {
+    encoder.setProperties(
+      packet.properties || {},
+      PacketType.unsuback,
+      codecOpts.maxOutgoingPacketSize,
+    );
+    for (const reasonCode of packet.reasonCodes) {
+      encoder.setByte(reasonCode);
     }
-    return encoder.done(flags);
-  },
+  }
+  return encoder.done(flags);
+}
 
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): UnsubackPacket {
-    hasEmptyFlags(flags);
-    const decoder = new Decoder(packetType, buffer);
-    const id = decoder.getInt16();
-    if (codecOpts.protocolLevel === 5) {
-      const properties = decoder.getProperties(PacketType.unsuback);
-      const reasonCodes = [];
-      while (!decoder.atEnd()) {
-        const reasonCode = decoder.getReasonCode();
-        reasonCodes.push(reasonCode);
-      }
-      return {
-        type: PacketType.unsuback,
-        protocolLevel: 5,
-        id,
-        properties,
-        reasonCodes: reasonCodes as Array<TReasonCode>,
-      };
+export function decode(
+  buffer: Uint8Array,
+  flags: number,
+  codecOpts: CodecOpts,
+  packetType: TPacketType,
+): UnsubackPacket {
+  hasEmptyFlags(flags);
+  const decoder = new Decoder(packetType, buffer);
+  const id = decoder.getInt16();
+  if (codecOpts.protocolLevel === 5) {
+    const properties = decoder.getProperties(PacketType.unsuback);
+    const reasonCodes = [];
+    while (!decoder.atEnd()) {
+      const reasonCode = decoder.getReasonCode();
+      reasonCodes.push(reasonCode);
     }
-    decoder.done();
     return {
       type: PacketType.unsuback,
-      protocolLevel: codecOpts.protocolLevel,
+      protocolLevel: 5,
       id,
+      properties,
+      reasonCodes: reasonCodes as Array<TReasonCode>,
     };
-  },
-};
+  }
+  decoder.done();
+  return {
+    type: PacketType.unsuback,
+    protocolLevel: codecOpts.protocolLevel,
+    id,
+  };
+}

package/mqttPacket/unsubscribe.ts

@@ -1,101 +1,112 @@
 import type {
   CodecOpts,
   PacketId,
-  ProtocolLevelNoV5,
   Topic,
   TopicFilter,
   TPacketType,
 } from "./types.ts";
+import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { UnsubscribeProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
 import { Encoder } from "./encoder.ts";
 import { Decoder, DecoderError } from "./decoder.ts";
 
+/**
+ * Represents an MQTT UNSUBSCRIBE packet conforming to MQTT version 3.1.1 (Protocol Level 4) or lower.
+ */
 export type UnsubscribePacketV4 = {
+  /** The type of the MQTT control packet. */
   type: TPacketType;
+  /** The protocol version level, restricted to non-v5 variants. */
   protocolLevel: ProtocolLevelNoV5;
+  /** The unique 16-bit packet identifier. */
   id: PacketId;
+  /** The list of topic filters from which the client intends to unsubscribe. */
   topicFilters: TopicFilter[];
 };
 
+/**
+ * Represents an MQTT UNSUBSCRIBE packet conforming to MQTT version 5.0.
+ */
 export type UnsubscribePacketV5 = {
+  /** The type of the MQTT control packet. */
   type: TPacketType;
+  /** The protocol version level, strictly set to 5. */
   protocolLevel: 5;
+  /** The unique 16-bit packet identifier. */
   id: PacketId;
+  /** Optional user and protocol properties introduced in MQTT v5. */
   properties?: UnsubscribeProperties;
+  /** The list of topic filters from which the client intends to unsubscribe. */
   topicFilters: TopicFilter[];
 };
 
 /**
- * UnsubscribePacket is sent from client to server to unsubscribe from topics
+ * Represents a union of available MQTT UNSUBSCRIBE packets (v4 or v5) sent from client to server.
  */
 export type UnsubscribePacket = UnsubscribePacketV4 | UnsubscribePacketV5;
 
-export const unsubscribe: {
-  encode(packet: UnsubscribePacket, codecOpts: CodecOpts): Uint8Array;
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): UnsubscribePacket;
-} = {
-  encode(packet: UnsubscribePacket, codecOpts: CodecOpts): Uint8Array {
-    // Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are reserved and
-    // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
-    // malformed and close the Network Connection [MQTT-3.10.1-1].
-    const flags = 0b0010;
+/**
+ * Codec utility object responsible for encoding and decoding MQTT UNSUBSCRIBE control packets.
+ */
+export function encode(
+  packet: UnsubscribePacket,
+  codecOpts: CodecOpts,
+): Uint8Array {
+  // Bits 3,2,1 and 0 of the fixed header of the UNSUBSCRIBE Control Packet are reserved and
+  // MUST be set to 0,0,1 and 0 respectively. The Server MUST treat any other value as
+  // malformed and close the Network Connection [MQTT-3.10.1-1].
+  const flags = 0b0010;
 
-    const encoder = new Encoder(packet.type);
-    encoder.setInt16(packet.id);
-    if (packet.protocolLevel === 5) {
-      encoder.setProperties(
-        packet.properties || {},
-        PacketType.unsubscribe,
-        codecOpts.maxOutgoingPacketSize,
-      );
-    }
-    for (const topicFilter of packet.topicFilters) {
-      encoder.setTopicFilter(topicFilter);
-    }
-    return encoder.done(flags);
-  },
+  const encoder = new Encoder(packet.type);
+  encoder.setInt16(packet.id);
+  if (packet.protocolLevel === 5) {
+    encoder.setProperties(
+      packet.properties || {},
+      PacketType.unsubscribe,
+      codecOpts.maxOutgoingPacketSize,
+    );
+  }
+  for (const topicFilter of packet.topicFilters) {
+    encoder.setUtf8String(topicFilter);
+  }
+  return encoder.done(flags);
+}
 
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): UnsubscribePacket {
-    if (flags !== 0b0010) {
-      throw new DecoderError("Invalid header");
-    }
-    const decoder = new Decoder(packetType, buffer);
-    const id = decoder.getInt16();
-    let properties = {};
-    if (codecOpts.protocolLevel === 5) {
-      properties = decoder.getProperties(PacketType.unsubscribe);
-    }
-    const topicFilters: Topic[] = [];
-    do {
-      const topicFilter = decoder.getTopicFilter();
-      topicFilters.push(topicFilter);
-    } while (!decoder.atEnd());
-    decoder.done();
-    if (codecOpts.protocolLevel !== 5) {
-      return {
-        type: PacketType.unsubscribe,
-        protocolLevel: codecOpts.protocolLevel,
-        id,
-        topicFilters,
-      };
-    }
+export function decode(
+  buffer: Uint8Array,
+  flags: number,
+  codecOpts: CodecOpts,
+  packetType: TPacketType,
+): UnsubscribePacket {
+  if (flags !== 0b0010) {
+    throw new DecoderError("Invalid header");
+  }
+  const decoder = new Decoder(packetType, buffer);
+  const id = decoder.getInt16();
+  let properties = {};
+  if (codecOpts.protocolLevel === 5) {
+    properties = decoder.getProperties(PacketType.unsubscribe);
+  }
+  const topicFilters: Topic[] = [];
+  do {
+    const topicFilter = decoder.getUTF8String();
+    topicFilters.push(topicFilter);
+  } while (!decoder.atEnd());
+  decoder.done();
+  if (codecOpts.protocolLevel !== 5) {
     return {
       type: PacketType.unsubscribe,
-      protocolLevel: 5,
+      protocolLevel: codecOpts.protocolLevel,
       id,
-      properties,
       topicFilters,
     };
-  },
-};
+  }
+  return {
+    type: PacketType.unsubscribe,
+    protocolLevel: 5,
+    id,
+    properties,
+    topicFilters,
+  };
+}