@seriousme/opifex 1.9.4 → 1.11.0

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,30 @@ export type ReturnCodes = number[];
  * Client identifier that uniquely identifies a client
  */
 export type ClientId = string;
+
+/**
+ * helper type to limit retain handling values
+ */
+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";
 
+export type UnsubackPacketV4 = {
+  type: TPacketType;
+  protocolLevel: ProtocolLevelNoV5;
+  id: PacketId;
+};
+
+export type UnsubackPacketV5 = {
+  type: TPacketType;
+  protocolLevel: 5;
+  id: PacketId;
+  properties: UnsubackProperties;
+  reasonCodes: Array<TReasonCode>;
+};
+
 /**
  * UnsubackPacket is sent by the server to the client to confirm receipt
  * of an UnsubscribePacket.
  */
-export type UnsubackPacket = {
-  type: TPacketType;
-  id: PacketId;
-};
+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",

package/mqttPacket/unsubscribe.ts

@@ -1,53 +1,100 @@
-import type { PacketId, Topic, TopicFilter, TPacketType } from "./types.ts";
+import type {
+  CodecOpts,
+  PacketId,
+  ProtocolLevelNoV5,
+  Topic,
+  TopicFilter,
+  TPacketType,
+} from "./types.ts";
+import type { UnsubscribeProperties } 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";
+import { Decoder, DecoderError } from "./decoder.ts";
 
-/**
- * UnsubscribePacket is sent from client to server to unsubscribe from topics
- */
-export type UnsubscribePacket = {
+export type UnsubscribePacketV4 = {
   type: TPacketType;
+  protocolLevel: ProtocolLevelNoV5;
   id: PacketId;
   topicFilters: TopicFilter[];
 };
 
+export type UnsubscribePacketV5 = {
+  type: TPacketType;
+  protocolLevel: 5;
+  id: PacketId;
+  properties?: UnsubscribeProperties;
+  topicFilters: TopicFilter[];
+};
+
+/**
+ * UnsubscribePacket is sent from client to server to unsubscribe from topics
+ */
+export type UnsubscribePacket = UnsubscribePacketV4 | UnsubscribePacketV5;
+
 export const unsubscribe: {
-  encode(packet: UnsubscribePacket): { flags: number; bytes: number[] };
-  decode(buffer: Uint8Array, flags: number): UnsubscribePacket;
+  encode(packet: UnsubscribePacket, codecOpts: CodecOpts): Uint8Array;
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    packetType: TPacketType,
+  ): UnsubscribePacket;
 } = {
-  encode(packet: UnsubscribePacket): { flags: number; bytes: number[] } {
+  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();
+    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 { flags, bytes: encoder.done() };
+    return encoder.done(flags);
   },
 
-  decode(buffer: Uint8Array, flags: number): UnsubscribePacket {
-    if (!booleanFlag(flags, BitMask.bit1)) {
+  decode(
+    buffer: Uint8Array,
+    flags: number,
+    codecOpts: CodecOpts,
+    packetType: TPacketType,
+  ): UnsubscribePacket {
+    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.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,
+      };
+    }
     return {
       type: PacketType.unsubscribe,
+      protocolLevel: 5,
       id,
+      properties,
       topicFilters,
     };
   },

package/mqttPacket/validators.ts

@@ -7,14 +7,29 @@ const invalidTopicRegEx = new RegExp(/^$|\+|#|\x00|\uFFFD/);
 // deno-lint-ignore no-control-regex
 const invalidTopicFilterRegEx = new RegExp(/^$|#.|[^\/]\+|\+[^\/]|\x00|\uFFFD/);
 
+/**
+ * check for invalid UTF-8 characters
+ * @param value string to test
+ * @returns true if the string contains invalid UTF-8 characters
+ */
 export function invalidUTF8(value: string): boolean {
   return invalidUTF8regEx.test(value);
 }
 
+/**
+ * check for invalid topic characters
+ * @param value
+ * @returns true if the topic is invalid
+ */
 export function invalidTopic(value: Topic): boolean {
   return invalidTopicRegEx.test(value);
 }
 
+/**
+ * check for invalid topic filter characters
+ * @param value topic filter to test
+ * @returns true if the topic filter is invalid
+ */
 export function invalidTopicFilter(value: TopicFilter): boolean {
   return invalidTopicFilterRegEx.test(value);
 }

package/node/tcpClient.ts

@@ -96,6 +96,6 @@ export class TcpClient extends Client {
     if (protocol === "mqtt:") {
       return this.connectMQTT(hostname, port);
     }
-    throw `Unsupported protocol: ${protocol}`;
+    throw new Error(`Unsupported protocol: ${protocol}`);
   }
 }

package/node/wrapNodeSocket.ts

@@ -4,6 +4,7 @@
 import type { Socket } from "node:net";
 import { Writable } from "node:stream";
 import type { NetAddr, SockConn } from "../socket/socket.ts";
+
 /**
  * Closes a Node.js socket if it is not already closed
  * @param sock - The Node.js socket to close
@@ -24,7 +25,7 @@ export function wrapNodeSocket(socket: Socket): SockConn {
     {
       type: "bytes",
       start(controller) {
-        socket.on("data", (data: ArrayBufferView) => {
+        socket.on("data", (data: Uint8Array<ArrayBuffer>) => {
           controller.enqueue(data);
           const desiredSize = controller.desiredSize ?? 0;
           if (desiredSize <= 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seriousme/opifex",
-  "version": "1.9.4",
+  "version": "1.11.0",
   "description": "MQTT client & server for Deno & NodeJS",
   "type": "module",
   "scripts": {
@@ -68,6 +68,6 @@
   },
   "homepage": "https://github.com/seriousme/opifex#readme",
   "devDependencies": {
-    "@types/node": "^22.13.1"
+    "@types/node": "^24.6.2"
   }
 }

package/persistence/deps.ts

@@ -7,6 +7,6 @@ export type {
   Topic,
   TopicFilter,
 } from "../mqttPacket/mod.ts";
-export { PacketType } from "../mqttPacket/mod.ts";
+export { MQTTLevel, PacketType } from "../mqttPacket/mod.ts";
 export { Trie } from "../trie/trie.ts";
 export { logger } from "../utils/mod.ts";

package/persistence/memory/memoryPersistence.test.ts

@@ -5,7 +5,8 @@ import {
 
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { PacketType, type PublishPacket } from "../deps.ts";
+import { MQTTLevel, PacketType } from "../deps.ts";
+import type { PublishPacket } from "../deps.ts";
 
 const payloadAny = new TextEncoder().encode("any");
 const qos = 1;
@@ -39,6 +40,7 @@ test("pub/sub should work", async () => {
   const topic = "/myTopic";
   const publishPacket: PublishPacket = {
     type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
     id: 1,
     topic,
     payload: payloadAny,
@@ -77,6 +79,7 @@ test("many packets should work", async () => {
   const numMessages = 1000;
   const publishPacket: PublishPacket = {
     type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
     id: 1,
     topic,
     payload: payloadAny,
@@ -123,6 +126,7 @@ test("unsubscribe should work", () => {
   const topic = "/myTopic";
   const publishPacket: PublishPacket = {
     type: PacketType.publish,
+    protocolLevel: MQTTLevel.v4,
     id: 1,
     topic,
     payload: payloadAny,

package/persistence/memory/memoryPersistence.ts

@@ -134,7 +134,7 @@ export class MemoryPersistence implements IPersistence {
       newPacket.qos = qos;
       //  logger.debug(`publish ${topic} to client ${clientId}`);
       const client = this.clientList.get(clientId);
-      client?.handler(packet);
+      client?.handler(newPacket);
     }
   }