@seriousme/opifex 1.11.3 → 2.0.3

package/mqttPacket/publish.ts

@@ -2,11 +2,11 @@ import type {
   CodecOpts,
   Dup,
   Payload,
-  ProtocolLevelNoV5,
   QoS,
   Topic,
   TPacketType,
 } from "./types.ts";
+import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { PublishProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
 import { BitMask } from "./BitMask.ts";
@@ -38,92 +38,73 @@ export type PublishPacketV5 = {
   id?: number | undefined;
   properties?: PublishProperties | undefined;
 };
-
+/** Publish packet (v4|v5). */
 export type PublishPacket = PublishPacketV4 | PublishPacketV5;
 
-export const publish: {
-  encode(packet: PublishPacket, _codecOpts: CodecOpts): Uint8Array;
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): PublishPacket;
-} = {
-  encode(packet: PublishPacket, codecOpts: CodecOpts): Uint8Array {
-    const qos = packet.qos || 0;
+export function encode(
+  packet: PublishPacket,
+  codecOpts: CodecOpts,
+): Uint8Array {
+  const qos = packet.qos || 0;
 
-    const flags = (packet.dup ? BitMask.bit3 : 0) +
-      (qos & 2 ? BitMask.bit2 : 0) +
-      (qos & 1 ? BitMask.bit1 : 0) +
-      (packet.retain ? BitMask.bit0 : 0);
+  const flags = (packet.dup ? BitMask.bit3 : 0) +
+    (qos & 2 ? BitMask.bit2 : 0) +
+    (qos & 1 ? BitMask.bit1 : 0) +
+    (packet.retain ? BitMask.bit0 : 0);
 
-    const encoder = new Encoder(packet.type);
-    encoder.setTopic(packet.topic);
+  const encoder = new Encoder(packet.type);
+  encoder.setUtf8String(packet.topic);
 
-    if (qos === 1 || qos === 2) {
-      if (typeof packet.id !== "number" || packet.id < 1) {
-        throw new EncoderError("when qos is 1 or 2, packet must have id");
-      }
-      encoder.setInt16(packet.id);
+  if (qos === 1 || qos === 2) {
+    if (typeof packet.id !== "number" || packet.id < 1) {
+      throw new EncoderError("when qos is 1 or 2, packet must have id");
     }
+    encoder.setInt16(packet.id);
+  }
 
-    if (packet.protocolLevel === 5) {
-      encoder.setProperties(
-        packet.properties || {},
-        PacketType.publish,
-        codecOpts.maxOutgoingPacketSize,
-      );
-    }
-    encoder.setRemainder(packet.payload);
-    return encoder.done(flags);
-  },
+  if (packet.protocolLevel === 5) {
+    encoder.setProperties(
+      packet.properties || {},
+      PacketType.publish,
+      codecOpts.maxOutgoingPacketSize,
+    );
+  }
+  encoder.setRemainder(packet.payload);
+  return encoder.done(flags);
+}
 
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): PublishPacket {
-    const dup = booleanFlag(flags, BitMask.bit3);
-    const qos = (flags & 6) >> 1;
-    const retain = booleanFlag(flags, BitMask.bit0);
+export function decode(
+  buffer: Uint8Array,
+  flags: number,
+  codecOpts: CodecOpts,
+  packetType: TPacketType,
+): PublishPacket {
+  const dup = booleanFlag(flags, BitMask.bit3);
+  const qos = (flags & 6) >> 1;
+  const retain = booleanFlag(flags, BitMask.bit0);
 
-    if (qos !== 0 && qos !== 1 && qos !== 2) {
-      throw new DecoderError("Invalid qos");
-    }
+  if (qos !== 0 && qos !== 1 && qos !== 2) {
+    throw new DecoderError("Invalid qos");
+  }
 
-    if (dup && qos === 0) {
-      throw new DecoderError("Invalid qos for possible duplicate");
-    }
+  if (dup && qos === 0) {
+    throw new DecoderError("Invalid qos for possible duplicate");
+  }
 
-    const decoder = new Decoder(packetType, buffer);
-    const topic = decoder.getTopic();
+  const decoder = new Decoder(packetType, buffer);
+  const topic = decoder.getUTF8String();
 
-    let id = undefined;
-    if (qos > 0) {
-      id = decoder.getInt16();
-    }
-    if (codecOpts.protocolLevel === 5) {
-      const properties = decoder.getProperties(PacketType.publish);
-      const payload = decoder.getRemainder();
-      return {
-        type: PacketType.publish,
-        protocolLevel: 5,
-        properties,
-        topic,
-        payload,
-        dup,
-        retain,
-        qos,
-        id,
-      };
-    }
-    // no decoder.done() required because of getRemainder
+  let id = undefined;
+  if (qos > 0) {
+    id = decoder.getInt16();
+  }
+  if (codecOpts.protocolLevel === 5) {
+    const properties = decoder.getProperties(PacketType.publish);
     const payload = decoder.getRemainder();
     return {
       type: PacketType.publish,
-      protocolLevel: codecOpts.protocolLevel,
+      protocolLevel: 5,
+      properties,
       topic,
       payload,
       dup,
@@ -131,5 +112,17 @@ export const publish: {
       qos,
       id,
     };
-  },
-};
+  }
+  // no decoder.done() required because of getRemainder
+  const payload = decoder.getRemainder();
+  return {
+    type: PacketType.publish,
+    protocolLevel: codecOpts.protocolLevel,
+    topic,
+    payload,
+    dup,
+    retain,
+    qos,
+    id,
+  };
+}

package/mqttPacket/suback.ts

@@ -1,11 +1,11 @@
 import type {
   CodecOpts,
   PacketId,
-  ProtocolLevelNoV5,
   ReturnCodes,
   TPacketType,
   TReasonCode,
 } from "./types.ts";
+import type { ProtocolLevelNoV5 } from "./protocolLevels.ts";
 import type { SubackProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
 import { Encoder } from "./encoder.ts";
@@ -33,68 +33,58 @@ export type SubackPacketV5 = {
  */
 export type SubackPacket = SubackPacketV4 | SubackPacketV5;
 
-export const suback: {
-  encode(packet: SubackPacket, _codecOpts: CodecOpts): Uint8Array;
-  decode(
-    buffer: Uint8Array,
-    flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): SubackPacket;
-} = {
-  encode(packet: SubackPacket, codecOpts: CodecOpts): Uint8Array {
-    const flags = 0;
-    const encoder = new Encoder(packet.type);
-    encoder.setInt16(packet.id);
-    if (packet.protocolLevel !== 5) {
-      for (const code of packet.returnCodes) {
-        if (!validReturnCodes.includes(code)) {
-          throw new Error("Invalid return code");
-        }
+export function encode(packet: SubackPacket, codecOpts: CodecOpts): Uint8Array {
+  const flags = 0;
+  const encoder = new Encoder(packet.type);
+  encoder.setInt16(packet.id);
+  if (packet.protocolLevel !== 5) {
+    for (const code of packet.returnCodes) {
+      if (!validReturnCodes.includes(code)) {
+        throw new Error("Invalid return code");
       }
-      encoder.setRemainder(packet.returnCodes);
-      return encoder.done(flags);
-    }
-    encoder.setProperties(
-      packet.properties || {},
-      packet.type,
-      codecOpts.maxOutgoingPacketSize,
-    );
-    for (const code of packet.reasonCodes) {
-      encoder.setReasonCode(code);
     }
+    encoder.setRemainder(packet.returnCodes);
     return encoder.done(flags);
-  },
+  }
+  encoder.setProperties(
+    packet.properties || {},
+    packet.type,
+    codecOpts.maxOutgoingPacketSize,
+  );
+  for (const code of packet.reasonCodes) {
+    encoder.setReasonCode(code);
+  }
+  return encoder.done(flags);
+}
 
-  decode(
-    buffer: Uint8Array,
-    _flags: number,
-    codecOpts: CodecOpts,
-    packetType: TPacketType,
-  ): SubackPacket {
-    const packet = {} as SubackPacket;
-    const decoder = new Decoder(packetType, buffer);
-    packet.type = PacketType.suback;
-    packet.id = decoder.getInt16();
-    packet.protocolLevel = codecOpts.protocolLevel;
+export function decode(
+  buffer: Uint8Array,
+  _flags: number,
+  codecOpts: CodecOpts,
+  packetType: TPacketType,
+): SubackPacket {
+  const packet = {} as SubackPacket;
+  const decoder = new Decoder(packetType, buffer);
+  packet.type = PacketType.suback;
+  packet.id = decoder.getInt16();
+  packet.protocolLevel = codecOpts.protocolLevel;
 
-    if (packet.protocolLevel !== 5) {
-      const payload = decoder.getRemainder();
-      packet.returnCodes = [];
-      for (const code of payload) {
-        if (!validReturnCodes.includes(code)) {
-          throw new DecoderError("Invalid return code");
-        }
-        packet.returnCodes.push(code);
+  if (packet.protocolLevel !== 5) {
+    const payload = decoder.getRemainder();
+    packet.returnCodes = [];
+    for (const code of payload) {
+      if (!validReturnCodes.includes(code)) {
+        throw new DecoderError("Invalid return code");
       }
-      return packet;
-    }
-    packet.properties = decoder.getProperties(PacketType.suback);
-    packet.reasonCodes = [];
-    while (!decoder.atEnd()) {
-      const code = decoder.getReasonCode();
-      packet.reasonCodes.push(code);
+      packet.returnCodes.push(code);
     }
     return packet;
-  },
-};
+  }
+  packet.properties = decoder.getProperties(PacketType.suback);
+  packet.reasonCodes = [];
+  while (!decoder.atEnd()) {
+    const code = decoder.getReasonCode();
+    packet.reasonCodes.push(code);
+  }
+  return packet;
+}

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
  */