@seriousme/opifex 1.9.4 → 1.10.1

package/mqttPacket/subscribe.ts

@@ -1,4 +1,13 @@
-import type { PacketId, QoS, TopicFilter, TPacketType } from "./types.ts";
+import type {
+  CodecOpts,
+  PacketId,
+  ProtocolLevelNoV5,
+  QoS,
+  TopicFilter,
+  TPacketType,
+  TRetainHandling,
+} from "./types.ts";
+import type { SubscribeProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
 import { BitMask } from "./BitMask.ts";
 import { Encoder } from "./encoder.ts";
@@ -7,72 +16,166 @@ import { booleanFlag, Decoder, DecoderError } from "./decoder.ts";
 /**
  * SubscribePacket is sent from client to server to subscribe to topics
  */
-export type SubscribePacket = {
+export type SubscribePacketV4 = {
   type: TPacketType;
+  protocolLevel: ProtocolLevelNoV5;
   id: PacketId;
-  subscriptions: Subscription[];
+  subscriptions: Array<SubscriptionV4>;
 };
 
+export type SubscribePacketV5 = {
+  type: TPacketType;
+  protocolLevel: 5;
+  id: PacketId;
+  properties?: SubscribeProperties;
+  subscriptions: Array<SubscriptionV5>;
+};
+
+export type SubscribePacket = SubscribePacketV4 | SubscribePacketV5;
 /**
  * The topic to subscribe to and the associated QoS
  */
-export type Subscription = {
+export type SubscriptionV4 = {
+  topicFilter: TopicFilter;
+  qos: QoS;
+};
+
+export type SubscriptionV5 = {
   topicFilter: TopicFilter;
   qos: QoS;
+  noLocal?: boolean;
+  retainAsPublished?: boolean;
+  retainHandling?: TRetainHandling;
 };
 
+export type Subscription = SubscriptionV4 | SubscriptionV5;
+
 export const subscribe: {
-  encode(packet: SubscribePacket): { flags: number; bytes: number[] };
-  decode(buffer: Uint8Array, flags: number): SubscribePacket;
+  encode(packet: SubscribePacket, codecOpts: CodecOpts): Uint8Array;
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    packetType: TPacketType,
+  ): SubscribePacket;
 } = {
-  encode(packet: SubscribePacket): { flags: number; bytes: number[] } {
+  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();
+    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.setTopic(sub.topicFilter);
-      encoder.setByte(sub.qos);
+      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);
+      }
     }
-    return { flags, bytes: encoder.done() };
+    return encoder.done(flags);
   },
 
-  decode(buffer: Uint8Array, flags: number): SubscribePacket {
+  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 (!booleanFlag(flags, BitMask.bit1)) {
+    if (flags !== 0b0010) {
       throw new DecoderError("Invalid header");
     }
-
-    const decoder = new Decoder(buffer);
+    const decoder = new Decoder(packetType, buffer);
     const id = decoder.getInt16();
+    let properties = {};
+    if (codecOpts.protocolLevel === 5) {
+      properties = decoder.getProperties(PacketType.subscribe);
+    }
 
     const subscriptions: Subscription[] = [];
-    // The payload of a SUBSCRIBE packet MUST contain at least one Topic Filter / QoS pair.
+    // 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 qos = decoder.getByte();
+      const option = decoder.getByte();
+      const qos = option & 0b11;
       if (qos !== 0 && qos !== 1 && qos !== 2) {
         throw new DecoderError("Invalid qos");
       }
       if (qos > 0 && id === 0) {
         throw new DecoderError("Invalid packet identifier");
       }
-      subscriptions.push({
-        topicFilter: topicFilter,
-        qos,
-      });
+      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);
+      }
     } while (!decoder.atEnd());
     decoder.done();
+    if (codecOpts.protocolLevel !== 5) {
+      return {
+        type: PacketType.subscribe,
+        protocolLevel: codecOpts.protocolLevel,
+        id,
+        subscriptions: subscriptions as Array<SubscriptionV4>,
+      };
+    }
     return {
       type: PacketType.subscribe,
+      protocolLevel: 5,
       id,
-      subscriptions,
+      properties,
+      subscriptions: subscriptions as Array<SubscriptionV5>,
     };
   },
 };

package/mqttPacket/types.ts

@@ -1,6 +1,8 @@
 import type { BitMask } from "./BitMask.ts";
 import type { PacketType } from "./PacketType.ts";
+import type { RetainHandling } from "./RetainHandling.ts";
 import type { AuthenticationResult } from "./AuthenticationResult.ts";
+import type { ReasonCode } from "./ReasonCode.ts";
 
 /**
  * Type to limit bit mask to valid values
@@ -17,6 +19,20 @@ export type TPacketType = typeof PacketType[keyof typeof PacketType];
 export type TAuthenticationResult =
   typeof AuthenticationResult[keyof typeof AuthenticationResult];
 
+/**
+ * Type to limit reason code to valid values
+ */
+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
  */
@@ -56,3 +72,27 @@ export type ReturnCodes = number[];
  * Client identifier that uniquely identifies a client
  */
 export type ClientId = string;
+
+export type TRetainHandling =
+  typeof RetainHandling[keyof typeof RetainHandling];
+
+/**
+ * UTF8 string pair (for v5)
+ */
+export type UTF8StringPair = [string, string];
+
+/**
+ * Options for the codec
+ */
+export type CodecOpts = {
+  protocolLevel: ProtocolLevel;
+  maxIncomingPacketSize: number;
+  maxOutgoingPacketSize: number;
+};
+
+/**
+ * Typescript helper to create an inverted record type
+ */
+export type InvertRecord<R extends Record<string, number>> = {
+  [K in keyof R as R[K]]: K;
+};

package/mqttPacket/unsuback.test.ts

@@ -1,15 +1,30 @@
-import { PacketType } from "./PacketType.ts";
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { decode, encode } from "./mod.ts";
+import { decode, encode, MQTTLevel, PacketType, ReasonCode } from "./mod.ts";
+import type { CodecOpts } from "./mod.ts";
 
-test("encode Puback", () => {
+const codecOptsV4: CodecOpts = {
+  protocolLevel: MQTTLevel.v4,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+const codecOptsV5: CodecOpts = {
+  protocolLevel: MQTTLevel.v5,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+test("encode/decode Unsuback V4", () => {
+  const packet = {
+    type: PacketType.unsuback,
+    protocolLevel: MQTTLevel.v4,
+    id: 1337,
+  };
+  const encoded = encode(packet, codecOptsV4);
   assert.deepStrictEqual(
-    encode({
-      type: PacketType.unsuback,
-      id: 1337,
-    }),
+    encoded,
     Uint8Array.from([
       // fixedHeader
       0xb0, // packetType + flags
@@ -19,37 +34,72 @@ test("encode Puback", () => {
       57, // id LSB
     ]),
   );
+  const decoded = decode(encoded, codecOptsV4);
+  assert.deepStrictEqual(decoded, packet);
 });
 
-test("decode Puback ", () => {
-  assert.deepStrictEqual(
-    decode(
-      Uint8Array.from([
-        // fixedHeader
-        0xb0, // packetType + flags
-        2, // remainingLength
-        // variableHeader
-        5, // id MSB
-        57, // id LSB
-      ]),
-    ),
-    {
-      type: PacketType.unsuback,
-      id: 1337,
+test("encode/decode Unsuback V5", () => {
+  const packet = {
+    type: PacketType.unsuback,
+    protocolLevel: MQTTLevel.v5,
+    id: 1337,
+    properties: {
+      reasonString: "reason",
     },
+    reasonCodes: [ReasonCode.success, ReasonCode.unspecifiedError],
+  };
+  const encoded = encode(packet, codecOptsV5);
+  assert.deepStrictEqual(
+    encoded,
+    Uint8Array.from([
+      // fixedHeader
+      176, // packet type + flags
+      14, // remaining length
+      5, // id MSB
+      57, // id LSB
+      9, // property length
+      31, // reasonString reason
+      0, // string lenght MSB
+      6, // string lengtg LSB
+      114, // r
+      101, // e
+      97, // a
+      115, // s
+      111, // o
+      110, // n
+      0, // ReasonCode.success
+      128, // ReasonCode.unspecifiedError
+    ]),
   );
+  const decoded = decode(encoded, codecOptsV5);
+  assert.deepStrictEqual(decoded, packet);
 });
 
-test("decodeShortPubackPackets", () => {
+test("decode short unsuback packets", () => {
+  assert.throws(
+    () => decode(Uint8Array.from([0xb0]), codecOptsV4),
+    /Packet decoding failed/,
+    "single byte",
+  );
   assert.throws(
-    () => decode(Uint8Array.from([0xb0])),
-    Error,
-    "decoding failed",
+    () => decode(Uint8Array.from([0xb0, 2]), codecOptsV4),
+    /too short/,
+    "incorrect length",
   );
-  assert.throws(() => decode(Uint8Array.from([0xb0, 2])), Error, "too short");
   assert.throws(
-    () => decode(Uint8Array.from([0xb0, 3, 0, 0, 0])),
-    Error,
-    "too long",
+    () => decode(Uint8Array.from([0xb0, 3, 0, 0, 0]), codecOptsV4),
+    /too long/,
+    "additional bytes",
+  );
+});
+
+test("decode invalid Unsuback V5, invalid reasonCode", () => {
+  assert.throws(
+    () =>
+      decode(
+        Uint8Array.from([224, 4, 1, 0, 0, ReasonCode.quotaExceeded]),
+        codecOptsV5,
+      ),
+    /Invalid reason code/,
   );
 });

package/mqttPacket/unsuback.ts

@@ -1,34 +1,89 @@
-import type { PacketId, TPacketType } from "./types.ts";
+import type {
+  CodecOpts,
+  PacketId,
+  ProtocolLevelNoV5,
+  TPacketType,
+  TReasonCode,
+} from "./types.ts";
+import type { UnsubackProperties } from "./Properties.ts";
 import { PacketType } from "./PacketType.ts";
-import { Decoder } from "./decoder.ts";
+import { Decoder, hasEmptyFlags } from "./decoder.ts";
 import { Encoder } from "./encoder.ts";
 
 /**
  * UnsubackPacket is sent by the server to the client to confirm receipt
  * of an UnsubscribePacket.
  */
-export type UnsubackPacket = {
+export type UnsubackPacketV4 = {
   type: TPacketType;
+  protocolLevel: ProtocolLevelNoV5;
   id: PacketId;
 };
 
+export type UnsubackPacketV5 = {
+  type: TPacketType;
+  protocolLevel: 5;
+  id: PacketId;
+  properties: UnsubackProperties;
+  reasonCodes: Array<TReasonCode>;
+};
+
+export type UnsubackPacket = UnsubackPacketV4 | UnsubackPacketV5;
+
 export const unsuback: {
-  encode(packet: UnsubackPacket): { flags: number; bytes: number[] };
-  decode(buffer: Uint8Array): UnsubackPacket;
+  encode(packet: UnsubackPacket, codecOpts: CodecOpts): Uint8Array;
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    packetType: TPacketType,
+  ): UnsubackPacket;
 } = {
-  encode(packet: UnsubackPacket): { flags: number; bytes: number[] } {
+  encode(packet: UnsubackPacket, codecOpts: CodecOpts): Uint8Array {
     const flags = 0;
-    const encoder = new Encoder();
+    const encoder = new Encoder(packet.type);
     encoder.setInt16(packet.id);
-    return { flags, bytes: encoder.done() };
+    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);
   },
 
-  decode(buffer: Uint8Array): UnsubackPacket {
-    const decoder = new Decoder(buffer);
+  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>,
+      };
+    }
     decoder.done();
     return {
       type: PacketType.unsuback,
+      protocolLevel: codecOpts.protocolLevel,
       id,
     };
   },

package/mqttPacket/unsubscribe.test.ts

@@ -1,16 +1,31 @@
 import { PacketType } from "./PacketType.ts";
 import assert from "node:assert/strict";
 import { test } from "node:test";
+import { decode, encode, MQTTLevel } from "./mod.ts";
+import type { CodecOpts } from "./mod.ts";
 
-import { decode, encode } from "./mod.ts";
+const codecOptsV4: CodecOpts = {
+  protocolLevel: MQTTLevel.v4,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
 
-test("encode Unsubscribe", () => {
+const codecOptsV5: CodecOpts = {
+  protocolLevel: MQTTLevel.v5,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+test("encode/decode Unsubscribe V4", () => {
+  const packet = {
+    type: PacketType.unsubscribe,
+    protocolLevel: MQTTLevel.v4,
+    id: 1,
+    topicFilters: ["a/b", "c/d"],
+  };
+  const encoded = encode(packet, codecOptsV4);
   assert.deepStrictEqual(
-    encode({
-      type: PacketType.unsubscribe,
-      id: 1,
-      topicFilters: ["a/b", "c/d"],
-    }),
+    encoded,
     Uint8Array.from([
       // fixedHeader
       0xa2, // packetType + flags
@@ -31,37 +46,44 @@ test("encode Unsubscribe", () => {
       100, // 'd'
     ]),
   );
+  const decoded = decode(encoded, codecOptsV4);
+  assert.deepStrictEqual(decoded, packet);
 });
 
-test("decode Unsubscribe", () => {
+test("encode/decode Unsubscribe V5", () => {
+  const packet = {
+    type: PacketType.unsubscribe,
+    protocolLevel: MQTTLevel.v5,
+    id: 1,
+    properties: {},
+    topicFilters: ["a/b", "c/d"],
+  };
+  const encoded = encode(packet, codecOptsV4);
   assert.deepStrictEqual(
-    decode(
-      Uint8Array.from([
-        // fixedHeader
-        0xa2, // packetType + flags
-        12, // remainingLength
-        // variableHeader
-        0, // id MSB
-        1, // id LSB
-        // payload
-        0, // topic filter length MSB
-        3, // topic filter length LSB
-        97, // 'a'
-        47, // '/'
-        98, // 'b'
-        0, // topic filter length MSB
-        3, // topic filter length LSB
-        99, // 'c'
-        47, // '/'
-        100, // 'd'
-      ]),
-    ),
-    {
-      type: PacketType.unsubscribe,
-      id: 1,
-      topicFilters: ["a/b", "c/d"],
-    },
+    encoded,
+    Uint8Array.from([
+      // fixedHeader
+      0xa2, // packetType + flags
+      13, // remainingLength
+      // variableHeader
+      0, // id MSB
+      1, // id LSB
+      0, // property length
+      // payload
+      0, // topic filter length MSB
+      3, // topic filter length LSB
+      97, // 'a'
+      47, // '/'
+      98, // 'b'
+      0, // topic filter length MSB
+      3, // topic filter length LSB
+      99, // 'c'
+      47, // '/'
+      100, // 'd'
+    ]),
   );
+  const decoded = decode(encoded, codecOptsV5);
+  assert.deepStrictEqual(decoded, packet);
 });
 
 test("decode Unsubscribe missing bit 1 flag", () => {
@@ -87,6 +109,7 @@ test("decode Unsubscribe missing bit 1 flag", () => {
           47, // '/'
           100, // 'd'
         ]),
+        codecOptsV4,
       ),
     Error,
     "Invalid header",
@@ -114,6 +137,7 @@ test("decode unsubscribe packet too short", () => {
           3, // topic filter length LSB
           99, // 'c'
         ]),
+        codecOptsV4,
       ),
     Error,
     "too short",
@@ -129,6 +153,7 @@ test("decode unsubscribe packet too short", () => {
           0, // id MSB
           1, // id LSB
         ]),
+        codecOptsV4,
       ),
     Error,
     "too short",