@seriousme/opifex 1.9.3 → 1.10.1

package/mqttPacket/mod.ts

@@ -7,39 +7,64 @@
 
 import type {
   ClientId,
+  CodecOpts,
   Dup,
   PacketId,
   Payload,
+  ProtocolLevel,
   QoS,
   ReturnCodes,
   TAuthenticationResult,
   Topic,
   TopicFilter,
   TPacketType,
+  TReasonCode,
+  TRetainHandling,
+  UTF8StringPair,
 } from "./types.ts";
+
+export { MQTTLevel } from "./protocolLevels.ts";
+export { RetainHandling } from "./RetainHandling.ts";
+export { ReasonCode, ReasonCodeByNumber } from "./ReasonCode.ts";
 import { PacketNameByType, PacketType } from "./PacketType.ts";
 import { invalidTopic, invalidTopicFilter, invalidUTF8 } from "./validators.ts";
 import { decodeLength, encodeLength } from "./length.ts";
-import { connect, type ConnectPacket } from "./connect.ts";
-import { connack, type ConnackPacket } from "./connack.ts";
+import { connect } from "./connect.ts";
+import { connack } from "./connack.ts";
 import {
   AuthenticationResult,
   AuthenticationResultByNumber,
 } from "./AuthenticationResult.ts";
-import { publish, type PublishPacket } from "./publish.ts";
-import { puback, type PubackPacket } from "./puback.ts";
-import { pubrec, type PubrecPacket } from "./pubrec.ts";
-import { pubrel, type PubrelPacket } from "./pubrel.ts";
-import { pubcomp, type PubcompPacket } from "./pubcomp.ts";
-import { subscribe, type SubscribePacket } from "./subscribe.ts";
-import { suback, type SubackPacket } from "./suback.ts";
-import { unsubscribe, type UnsubscribePacket } from "./unsubscribe.ts";
-import { unsuback, type UnsubackPacket } from "./unsuback.ts";
-import { pingreq, type PingreqPacket } from "./pingreq.ts";
-import { pingres, type PingresPacket } from "./pingres.ts";
-import { disconnect, type DisconnectPacket } from "./disconnect.ts";
+import { publish } from "./publish.ts";
+import { anyAck } from "./pubblishAcks.ts";
+import { subscribe } from "./subscribe.ts";
+import { suback } from "./suback.ts";
+import { unsubscribe } from "./unsubscribe.ts";
+import { unsuback } from "./unsuback.ts";
+import { pingreq } from "./pingreq.ts";
+import { pingres } from "./pingres.ts";
+import { disconnect } from "./disconnect.ts";
+import { auth } from "./auth.ts";
 import { DecoderError } from "./decoder.ts";
 
+import type { ConnectPacket } from "./connect.ts";
+import type { ConnackPacket } from "./connack.ts";
+import type { PublishPacket } from "./publish.ts";
+import type {
+  PubackPacket,
+  PubcompPacket,
+  PubrecPacket,
+  PubrelPacket,
+} from "./pubblishAcks.ts";
+import type { SubscribePacket } from "./subscribe.ts";
+import type { SubackPacket } from "./suback.ts";
+import type { UnsubscribePacket } from "./unsubscribe.ts";
+import type { UnsubackPacket } from "./unsuback.ts";
+import type { PingreqPacket } from "./pingreq.ts";
+import type { PingresPacket } from "./pingres.ts";
+import type { DisconnectPacket } from "./disconnect.ts";
+import type { AuthPacket } from "./auth.ts";
+
 /**
  * this can be any possible MQTT packet
  */
@@ -57,10 +82,13 @@ export type AnyPacket =
   | UnsubackPacket
   | PingreqPacket
   | PingresPacket
-  | DisconnectPacket;
+  | DisconnectPacket
+  | AuthPacket;
 
 export type {
+  AuthPacket,
   ClientId,
+  CodecOpts,
   ConnackPacket,
   ConnectPacket,
   DisconnectPacket,
@@ -69,6 +97,7 @@ export type {
   Payload,
   PingreqPacket,
   PingresPacket,
+  ProtocolLevel,
   PubackPacket,
   PubcompPacket,
   PublishPacket,
@@ -82,8 +111,11 @@ export type {
   Topic,
   TopicFilter,
   TPacketType,
+  TReasonCode,
+  TRetainHandling,
   UnsubackPacket,
   UnsubscribePacket,
+  UTF8StringPair,
 };
 
 export type { Subscription } from "./subscribe.ts";
@@ -109,10 +141,10 @@ export const packetsByType = [
   connect, // 1
   connack, // 2
   publish, // 3
-  puback, // 4
-  pubrec, // 5
-  pubrel, // 6
-  pubcomp, // 7
+  anyAck, // 4 puback
+  anyAck, // 5 pubrec
+  anyAck, // 6 pubrel
+  anyAck, // 7 pubcomp
   subscribe, // 8
   suback, // 9
   unsubscribe, // 10
@@ -120,29 +152,29 @@ export const packetsByType = [
   pingreq, // 12
   pingres, // 13
   disconnect, // 14
+  auth, // 15
 ] as const;
 
 /**
  * @function encode
  * @description Encodes an MQTT packet object into a binary Uint8Array format
  * @param {AnyPacket} packet - The MQTT packet object to encode
+ * @param {CodecOpts} codecOpts - options to use during encoding
  * @returns {Uint8Array} The encoded packet as a binary buffer
  * @throws {Error} If packet encoding fails
  */
-export function encode(packet: AnyPacket): Uint8Array {
+export function encode(
+  packet: AnyPacket,
+  codecOpts: CodecOpts,
+): Uint8Array {
   const packetType: number = packet.type;
   // deno-lint-ignore no-explicit-any
   const pkt: any = packet;
-  const encoded = packetsByType[packetType]?.encode(pkt);
+  const encoded = packetsByType[packetType]?.encode(pkt, codecOpts);
   if (!encoded) {
     throw Error("Packet encoding failed");
   }
-  const { flags, bytes } = encoded;
-  return Uint8Array.from([
-    (packetType << 4) | flags,
-    ...encodeLength(bytes.length),
-    ...bytes,
-  ]);
+  return encoded;
 }
 
 /**
@@ -150,38 +182,49 @@ export function encode(packet: AnyPacket): Uint8Array {
  * @description Decodes a packet payload from binary format into an MQTT packet object
  * @param {number} firstByte - The first byte of the MQTT packet containing type and flags
  * @param {Uint8Array} buffer - The binary buffer containing the packet payload
+ * @param {CodecOpts} codecOpts - options to use during encoding
  * @returns {AnyPacket} The decoded MQTT packet object
- * @throws {Error} If packet decoding fails
+ * @throws {DecoderError} If packet decoding fails
  */
 
 export function decodePayload(
   firstByte: number,
   buffer: Uint8Array,
+  codecOpts: CodecOpts,
 ): AnyPacket {
   const packetType = firstByte >> 4;
   const flags = firstByte & 0x0f;
-  const packet = packetsByType[packetType]?.decode(buffer, flags);
+  const packet = packetsByType[packetType]?.decode(
+    buffer,
+    flags,
+    codecOpts,
+    packetType as TPacketType,
+  );
   if (packet !== undefined) {
     return packet;
   }
-  throw new Error("packet decoding failed");
+  throw new DecoderError("packet decoding failed");
 }
 
 /**
  * @function decode
  * @description Decodes a complete MQTT packet from binary format into a packet object
  * @param {Uint8Array} buffer - The binary buffer containing the complete MQTT packet
+ * @param {CodecOpts} codecOpts - the options for the decoder
  * @returns {AnyPacket} The decoded MQTT packet object
  * @throws {DecoderError} If packet decoding fails due to invalid format or insufficient data
  */
-export function decode(buffer: Uint8Array): AnyPacket {
+export function decode(
+  buffer: Uint8Array,
+  codecOpts: CodecOpts,
+): AnyPacket {
   if (buffer.length < 2) {
     throw new DecoderError("Packet decoding failed");
   }
   const { length, numLengthBytes } = decodeLength(buffer, 1);
   const start = numLengthBytes + 1;
   const end = start + length;
-  return decodePayload(buffer[0], buffer.subarray(start, end));
+  return decodePayload(buffer[0], buffer.subarray(start, end), codecOpts);
 }
 
 export { getLengthDecoder } from "../mqttPacket/length.ts";

package/mqttPacket/pingreq.test.ts

@@ -2,13 +2,58 @@ 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 } from "./mod.ts";
+import type { CodecOpts } from "./mod.ts";
 
-test("encode Pingreq", () => {
+const codecOptsV4: CodecOpts = {
+  protocolLevel: MQTTLevel.v4,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+const codecOptsV5: CodecOpts = {
+  protocolLevel: MQTTLevel.v5,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+test("encode Pingreq v4", () => {
+  assert.deepStrictEqual(
+    encode({
+      type: PacketType.pingreq,
+      protocolLevel: MQTTLevel.v4,
+    }, codecOptsV4),
+    Uint8Array.from([
+      // fixedHeader
+      192, // packetType + flags
+      0, // remainingLength
+    ]),
+  );
+});
+
+test("decode Pingreq v4", () => {
+  assert.deepStrictEqual(
+    decode(
+      Uint8Array.from([
+        // fixedHeader
+        192, // packetType + flags
+        0, // remainingLength
+      ]),
+      codecOptsV4,
+    ),
+    {
+      type: PacketType.pingreq,
+      protocolLevel: MQTTLevel.v4,
+    },
+  );
+});
+
+test("encode Pingreq v5", () => {
   assert.deepStrictEqual(
     encode({
       type: PacketType.pingreq,
-    }),
+      protocolLevel: MQTTLevel.v5,
+    }, codecOptsV5),
     Uint8Array.from([
       // fixedHeader
       192, // packetType + flags
@@ -17,7 +62,7 @@ test("encode Pingreq", () => {
   );
 });
 
-test("decode Pingreq", () => {
+test("decode Pingreq v5", () => {
   assert.deepStrictEqual(
     decode(
       Uint8Array.from([
@@ -25,9 +70,11 @@ test("decode Pingreq", () => {
         192, // packetType + flags
         0, // remainingLength
       ]),
+      codecOptsV5,
     ),
     {
       type: PacketType.pingreq,
+      protocolLevel: MQTTLevel.v5,
     },
   );
 });
@@ -43,6 +90,7 @@ test("decode invalid Pingreq", () => {
           0,
           0,
         ]),
+        codecOptsV4,
       ),
     Error,
     "too long",

package/mqttPacket/pingreq.ts

@@ -1,28 +1,41 @@
 import { PacketType } from "./PacketType.ts";
 import { hasEmptyFlags, isEmptyBuf } from "./decoder.ts";
-import type { TPacketType } from "./types.ts";
+import type { CodecOpts, ProtocolLevel, TPacketType } from "./types.ts";
 
 /**
  * PingreqPacket is a packet that is sent to the server to keep the connection alive
  */
 export type PingreqPacket = {
   type: TPacketType;
+  protocolLevel: ProtocolLevel;
 };
 
+const PINGRES_PACKET = new Uint8Array([PacketType.pingreq << 4, 0]);
+
 export const pingreq: {
-  encode(_packet: PingreqPacket): { flags: number; bytes: number[] };
-  decode(buffer: Uint8Array, flags: number): PingreqPacket;
+  encode(_packet: PingreqPacket, _codecOpts: CodecOpts): Uint8Array;
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    _packetType: TPacketType,
+  ): PingreqPacket;
 } = {
-  encode(_packet: PingreqPacket): { flags: number; bytes: number[] } {
-    const flags = 0;
-    return { flags, bytes: [] };
+  encode(_packet: PingreqPacket, _codecOpts: CodecOpts): Uint8Array {
+    return PINGRES_PACKET;
   },
 
-  decode(buffer: Uint8Array, flags: number): PingreqPacket {
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    _packetType: TPacketType,
+  ): PingreqPacket {
     hasEmptyFlags(flags);
     isEmptyBuf(buffer);
     return {
       type: PacketType.pingreq,
+      protocolLevel: codecOpts.protocolLevel,
     };
   },
 };

package/mqttPacket/pingres.test.ts

@@ -2,13 +2,58 @@ 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 } from "./mod.ts";
+import type { CodecOpts } from "./mod.ts";
 
-test("encode Pingres", () => {
+const codecOptsV4: CodecOpts = {
+  protocolLevel: MQTTLevel.v4,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+const codecOptsV5: CodecOpts = {
+  protocolLevel: MQTTLevel.v5,
+  maxIncomingPacketSize: 0xffff,
+  maxOutgoingPacketSize: 0xffff,
+};
+
+test("encode Pingres V4", () => {
+  assert.deepStrictEqual(
+    encode({
+      type: PacketType.pingres,
+      protocolLevel: MQTTLevel.v4,
+    }, codecOptsV4),
+    Uint8Array.from([
+      // fixedHeader
+      208, // packetType + flags
+      0, // remainingLength
+    ]),
+  );
+});
+
+test("decode Pingres V4", () => {
+  assert.deepStrictEqual(
+    decode(
+      Uint8Array.from([
+        // fixedHeader
+        208, // packetType + flags
+        0, // remainingLength
+      ]),
+      codecOptsV4,
+    ),
+    {
+      type: PacketType.pingres,
+      protocolLevel: MQTTLevel.v4,
+    },
+  );
+});
+
+test("encode Pingres V5", () => {
   assert.deepStrictEqual(
     encode({
       type: PacketType.pingres,
-    }),
+      protocolLevel: MQTTLevel.v5,
+    }, codecOptsV5),
     Uint8Array.from([
       // fixedHeader
       208, // packetType + flags
@@ -17,7 +62,7 @@ test("encode Pingres", () => {
   );
 });
 
-test("decode Pingres", () => {
+test("decode Pingres V5", () => {
   assert.deepStrictEqual(
     decode(
       Uint8Array.from([
@@ -25,9 +70,11 @@ test("decode Pingres", () => {
         208, // packetType + flags
         0, // remainingLength
       ]),
+      codecOptsV5,
     ),
     {
       type: PacketType.pingres,
+      protocolLevel: MQTTLevel.v5,
     },
   );
 });
@@ -43,6 +90,7 @@ test("decode invalid Pingres", () => {
           0,
           0,
         ]),
+        codecOptsV4,
       ),
     Error,
     "too long",

package/mqttPacket/pingres.ts

@@ -1,6 +1,6 @@
 import { PacketType } from "./PacketType.ts";
-import { isEmptyBuf } from "./decoder.ts";
-import type { TPacketType } from "./types.ts";
+import { hasEmptyFlags, isEmptyBuf } from "./decoder.ts";
+import type { CodecOpts, ProtocolLevel, TPacketType } from "./types.ts";
 
 /**
  * PingresPacket is  an empty packet that is sent by the server in response to a PingreqPacket.
@@ -8,21 +8,35 @@ import type { TPacketType } from "./types.ts";
  */
 export type PingresPacket = {
   type: TPacketType;
+  protocolLevel: ProtocolLevel;
 };
 
+const PINGRES_PACKET = new Uint8Array([PacketType.pingres << 4, 0]);
+
 export const pingres: {
-  encode(_packet: PingresPacket): { flags: number; bytes: number[] };
-  decode(buffer: Uint8Array): PingresPacket;
+  encode(packet: PingresPacket, _codecOpts: CodecOpts): Uint8Array;
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    _packetType: TPacketType,
+  ): PingresPacket;
 } = {
-  encode(_packet: PingresPacket): { flags: number; bytes: number[] } {
-    const flags = 0;
-    return { flags, bytes: [] };
+  encode(_packet: PingresPacket, _codecOpts: CodecOpts): Uint8Array {
+    return PINGRES_PACKET;
   },
 
-  decode(buffer: Uint8Array): PingresPacket {
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    _packetType: TPacketType,
+  ): PingresPacket {
+    hasEmptyFlags(flags);
     isEmptyBuf(buffer);
     return {
       type: PacketType.pingres,
+      protocolLevel: codecOpts.protocolLevel,
     };
   },
 };

package/mqttPacket/properties.test.ts

@@ -0,0 +1,193 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { Encoder } from "./encoder.ts";
+import { Decoder } from "./decoder.ts";
+import { PacketType } from "./PacketType.ts";
+
+test("encoder.setProperties encodes allowed properties for connect", () => {
+  const encoder = new Encoder(PacketType.connect);
+  const props = {
+    sessionExpiryInterval: 60,
+    authenticationMethod: "basic",
+    authenticationData: new Uint8Array([1, 2, 3]),
+    requestProblemInformation: true,
+    requestResponseInformation: false,
+    receiveMaximum: 100,
+    topicAliasMaximum: 10,
+    userProperty: [["key", "value"]],
+    maximumPacketSize: 1024,
+  };
+  encoder.setProperties(props, PacketType.connect, 2048);
+  assert.equal(encoder.encodedSize(), 48);
+});
+
+test("decoder.getProperties decodes allowed properties for connect", () => {
+  const encoder = new Encoder(PacketType.connect);
+  const props = {
+    sessionExpiryInterval: 60,
+    authenticationMethod: "basic",
+    authenticationData: new Uint8Array([1, 2, 3]),
+    requestProblemInformation: true,
+    requestResponseInformation: false,
+    receiveMaximum: 100,
+    topicAliasMaximum: 10,
+    userProperty: [["key1", "value1"], ["key2", "value2"]],
+    maximumPacketSize: 1024,
+  };
+  encoder.setProperties(props, PacketType.connect, 2048);
+  const buf = encoder.done(0);
+  // skip the first byte which contains the packet identifier
+  // and the second byte that holds the packet length
+  const decoder = new Decoder(PacketType.connect, buf, 2);
+  const decoded = decoder.getProperties(PacketType.connect);
+  assert.equal(decoded.sessionExpiryInterval, 60);
+  assert.equal(decoded.authenticationMethod, "basic");
+  assert.deepEqual(decoded.authenticationData, new Uint8Array([1, 2, 3]));
+  assert.equal(decoded.requestProblemInformation, true);
+  assert.equal(decoded.requestResponseInformation, false);
+  assert.equal(decoded.receiveMaximum, 100);
+  assert.equal(decoded.topicAliasMaximum, 10);
+  assert.deepEqual(decoded.userProperty, [["key1", "value1"], [
+    "key2",
+    "value2",
+  ]]);
+  assert.equal(decoded.maximumPacketSize, 1024);
+});
+
+test("decoder.getProperties decodes allowed properties for connack", () => {
+  const encoder = new Encoder(PacketType.connack);
+  const props = {
+    maximumQos: 2,
+    reasonString: "very good reason",
+  };
+  encoder.setProperties(props, PacketType.connack, 2048);
+  const buf = encoder.done(0);
+  // skip the first byte which contains the packet identifier
+  // and the second byte that holds the packet length
+  const decoder = new Decoder(PacketType.connack, buf, 2);
+  const decoded = decoder.getProperties(PacketType.connack);
+  assert.equal(decoded.maximumQos, 2);
+});
+
+test("encoder.setProperties does not encode properties not allowed for packet type", () => {
+  const encoder = new Encoder(PacketType.publish);
+  const props = {
+    userProperty: [["key", "value"]],
+    // Not allowed for publish
+    sessionExpiryInterval: 60,
+    authenticationMethod: "basic",
+    authenticationData: new Uint8Array([1, 2, 3]),
+    requestProblemInformation: true,
+    requestResponseInformation: false,
+    receiveMaximum: 100,
+    topicAliasMaximum: 10,
+    maximumPacketSize: 1024,
+  };
+  encoder.setProperties(props, PacketType.publish, 2048);
+  const buf = encoder.done(0);
+  const decoder = new Decoder(PacketType.publish, buf, 2);
+  const decoded = decoder.getProperties(PacketType.publish);
+  assert.deepStrictEqual(Object.keys(decoded), [
+    "userProperty",
+  ]);
+});
+
+test("decoder.getProperties throws on duplicate property", () => {
+  const encoder = new Encoder(PacketType.publish);
+  // Manually encode duplicate properties
+  encoder.setVariableByteInteger(0x04); // propertyLength
+  encoder.setVariableByteInteger(0x01); // payloadFormatIndicator
+  encoder.setByte(1);
+  encoder.setVariableByteInteger(0x01); // payloadFormatIndicator again
+  encoder.setByte(1);
+  const buf = encoder.done(0);
+  const decoder = new Decoder(PacketType.publish, buf, 2);
+  assert.throws(
+    () => decoder.getProperties(PacketType.publish),
+    /Property payloadFormatIndicator only allowed once/,
+  );
+});
+
+test("decoder.getProperties throws on property not allowed for packet type", () => {
+  const encoder = new Encoder(PacketType.publish);
+  encoder.setVariableByteInteger(0x05); // propertyLength
+  encoder.setVariableByteInteger(0x13); // serverKeepAlive (not allowed for publish)
+  encoder.setInt32(30);
+  const buf = encoder.done(0);
+  const decoder = new Decoder(PacketType.publish, buf, 2);
+  assert.throws(
+    () => decoder.getProperties(PacketType.publish),
+    /Property type serverKeepAlive not allowed/,
+  );
+});
+
+test("encoder.setProperties rewinds marker if encodedSize exceeds maximumPacketSize", () => {
+  const encoder = new Encoder(PacketType.puback);
+  const props = {
+    reasonString: "small",
+    userProperty: [["key", "value"]],
+  };
+  encoder.setProperties(props, PacketType.puback, 10); // very small max size
+  assert.equal(encoder.encodedSize(), 9);
+});
+
+test("encoder.setProperties removes all properties if encodedSize exceeds maximumPacketSize", () => {
+  const encoder = new Encoder(PacketType.puback);
+  const props = {
+    reasonString: "a very long reason",
+    userProperty: [["key", "value"]],
+  };
+  encoder.setProperties(props, PacketType.puback, 10); // very small max size
+  assert.equal(encoder.encodedSize(), 1); // only propertyLength 0 remains
+});
+
+test("decodeProperty throws on invalid property kind", () => {
+  const encoder = new Encoder(PacketType.publish);
+  // Manually encode an invalid property kind
+  encoder.setVariableByteInteger(0x02); // propertyLength
+  encoder.setVariableByteInteger(0xF0); // Invalid property ID
+  encoder.setByte(1);
+
+  const buf = encoder.done(0);
+  const decoder = new Decoder(PacketType.publish, buf, 2);
+
+  assert.throws(
+    () => decoder.getProperties(PacketType.publish),
+    /Property type 240 not allowed/,
+  );
+});
+
+test("userProperty must be an array", () => {
+  const encoder = new Encoder(PacketType.puback);
+  const props = {
+    userProperty: "I am not an array",
+  };
+  assert.throws(
+    () => encoder.setProperties(props, PacketType.puback, 10),
+    / userProperty must be an array/,
+  );
+});
+
+test("userProperty item must be an array", () => {
+  const encoder = new Encoder(PacketType.puback);
+  const props = {
+    userProperty: ["a", "b"],
+  };
+  assert.throws(
+    () => encoder.setProperties(props, PacketType.puback, 10),
+    / userProperty item must be an array/,
+  );
+});
+
+test("encode/decode subscriptionIdentifiers", () => {
+  const props = { subscriptionIdentifiers: [3, 5, 7] };
+  const bytes = new Uint8Array([48, 7, 6, 0xb, 3, 0xb, 5, 0xb, 7]);
+  const encoder = new Encoder(PacketType.publish);
+  encoder.setProperties(props, PacketType.publish, 1000);
+  const buf = encoder.done(0);
+  assert.deepStrictEqual(buf, bytes);
+  const decoder = new Decoder(PacketType.publish, buf, 2);
+  const decoded = decoder.getProperties(PacketType.publish);
+  assert.deepStrictEqual(decoded, props);
+});