@seriousme/opifex 1.11.3 → 2.1.0

package/dev_utils/packetHelpers.ts

@@ -0,0 +1,404 @@
+import type { MqttConn } from "../mqttConn/mqttConn.ts";
+import { withTimeout } from "./timers.ts";
+import { delay } from "./timers.ts";
+import { MQTTLevel, PacketType, ReasonCode } from "../mqttPacket/mod.ts";
+import type {
+  AnyPacket,
+  AuthPacket,
+  ConnackPacket,
+  ConnectPacket,
+  DisconnectProperties,
+  ProtocolLevel,
+  PublishProperties,
+  QoS,
+  Topic,
+  TopicFilter,
+  UnsubackPacket,
+} from "../mqttPacket/mod.ts";
+import type {
+  ConnackPacketV4,
+  ConnackPacketV5,
+} from "../mqttPacket/connack.ts";
+import type { ConnectPacketV5 } from "../mqttPacket/connect.ts";
+import assert from "node:assert/strict";
+import { logger } from "../utils/mod.ts";
+
+const txtEncoder = new TextEncoder();
+
+let clientIdCounter = 1;
+
+const PINGREQ_PACKET: AnyPacket = Object.freeze({
+  type: PacketType.pingreq,
+  protocolLevel: MQTTLevel.v4,
+});
+
+export function nextPacketWithTimeOut(
+  conn: MqttConn,
+  timeoutMs: number,
+): Promise<IteratorResult<AnyPacket> | null> {
+  return withTimeout(conn.next(), timeoutMs);
+}
+
+export async function checkNoPacket(mqttConn: MqttConn, timeoutMs = 10) {
+  const result = await nextPacketWithTimeOut(mqttConn, timeoutMs);
+  assert.equal(result, null, "no packet received");
+}
+
+async function baseConnect(mqttConn: MqttConn, {
+  level = MQTTLevel.v4 as ProtocolLevel,
+  clientId = `testClient-${clientIdCounter++}`,
+  username = "IoTester_1",
+  password = "strong_password",
+  keepAlive = 0,
+  clean = true,
+  will = undefined as ConnectPacket["will"],
+  properties = {},
+  checkAck = true,
+} = {}): Promise<ConnackPacket | AuthPacket> {
+  mqttConn.codecOpts.protocolLevel = level;
+  const connectPacket: ConnectPacket = {
+    type: PacketType.connect,
+    protocolName: "MQTT",
+    protocolLevel: level,
+    clientId,
+    clean,
+    keepAlive,
+    username,
+    password: password !== "" ? txtEncoder.encode(password) : undefined,
+    will,
+  };
+  if (connectPacket.protocolLevel === MQTTLevel.v5) {
+    connectPacket.properties = properties;
+  }
+  logger.verbose("connectHelper: sending connect");
+  logger.debug({ connectPacket });
+
+  mqttConn.send(connectPacket);
+  const { value: connack } = await mqttConn.next();
+  logger.verbose("connectHelper: connack", connack);
+  if (checkAck) {
+    assert.deepStrictEqual(
+      connack.type,
+      PacketType.connack,
+      "Expected CONNACK",
+    );
+  }
+  mqttConn.codecOpts.protocolLevel = level;
+  return connack;
+}
+
+export async function connect(mqttConn: MqttConn, {
+  level = MQTTLevel.v4,
+  clientId = `testClient-${clientIdCounter++}`,
+  username = "IoTester_1",
+  password = "strong_password",
+  keepAlive = 0,
+  clean = true,
+  will = undefined as ConnectPacket["will"],
+  checkAck = true,
+} = {}): Promise<ConnackPacketV4> {
+  return await baseConnect(mqttConn, {
+    level,
+    clientId,
+    username,
+    password,
+    keepAlive,
+    clean,
+    will,
+    checkAck,
+  }) as ConnackPacketV4;
+}
+
+export async function connect5(mqttConn: MqttConn, {
+  clientId = `testClient-${clientIdCounter++}`,
+  username = "IoTester_1",
+  password = "strong_password",
+  keepAlive = 0,
+  clean = true,
+  will = undefined as ConnectPacket["will"],
+  properties = {} as ConnectPacketV5["properties"],
+  checkAck = true,
+} = {}): Promise<ConnackPacketV5> {
+  return await baseConnect(mqttConn, {
+    level: MQTTLevel.v5,
+    clientId,
+    username,
+    password,
+    keepAlive,
+    clean,
+    will,
+    properties,
+    checkAck,
+  }) as ConnackPacketV5;
+}
+
+export async function auth(mqttConn: MqttConn, {
+  reasonCode = ReasonCode.continueAuthentication,
+  authMethod = "SCRAM-SHA-256",
+  authData = new Uint8Array([1]),
+  noMethod = false,
+  noData = false,
+} = {}) {
+  const authPacket: AuthPacket = {
+    type: PacketType.auth,
+    protocolLevel: 5,
+    reasonCode,
+    properties: {
+      authenticationMethod: noMethod ? undefined : authMethod,
+      authenticationData: noData ? undefined : authData,
+    },
+  };
+  await mqttConn.send(authPacket);
+  const { value } = await mqttConn.next();
+  return value;
+}
+
+export async function subscribe(
+  subscriber: MqttConn,
+  subscriptions: {
+    topicFilter: TopicFilter;
+    qos: QoS;
+  }[],
+  {
+    id = 24,
+    checkAcks = true,
+  } = {},
+) {
+  const subscribePacket = {
+    type: PacketType.subscribe,
+    protocolLevel: MQTTLevel.v4,
+    id,
+    subscriptions,
+  };
+
+  subscriber.send(subscribePacket);
+
+  const { value: packet } = await subscriber.next();
+  if (checkAcks) {
+    assert.equal(packet.type, PacketType.suback, "Expected SUBACK");
+    assert.equal(packet.id, id, "SUBACK ID should match SUBSCRIBE ID");
+    const results = packet.returnCodes || packet.reasonCodes;
+    assert.equal(results.length, subscriptions.length, "ACK count match");
+    for (let i = 0; i < results.length; i++) {
+      assert.equal(results[i], subscriptions[i].qos);
+    }
+  }
+  return packet;
+}
+
+export async function subscribe5(
+  subscriber: MqttConn,
+  subscriptions: {
+    topicFilter: TopicFilter;
+    qos: QoS;
+    noLocal?: boolean;
+    retainAsPublished?: boolean;
+    retainHandling?: number;
+  }[],
+  {
+    id = 24,
+    subscriptionIdentifier = undefined as number | undefined,
+    checkAcks = true,
+  } = {},
+) {
+  const properties = subscriptionIdentifier !== undefined
+    ? { subscriptionIdentifier }
+    : {};
+
+  const subscribePacket = {
+    type: PacketType.subscribe,
+    protocolLevel: MQTTLevel.v5,
+    id,
+    subscriptions,
+    properties,
+  };
+
+  subscriber.send(subscribePacket);
+  logger.debug("subscribe helper: sent subscription request");
+
+  const { value: packet } = await subscriber.next();
+  assert.equal(packet.type, PacketType.suback, "Expected SUBACK");
+  assert.equal(packet.id, id, "SUBACK ID should match SUBSCRIBE ID");
+  logger.debug("subscribe helper: received SubAck");
+
+  if (checkAcks) {
+    const results = packet.returnCodes || packet.reasonCodes;
+    assert.equal(results.length, subscriptions.length, "ACK count match");
+    for (let i = 0; i < results.length; i++) {
+      assert.equal(results[i], subscriptions[i].qos);
+    }
+  }
+  logger.debug("subscribe helper: acks ok");
+  return packet;
+}
+
+export async function unsubscribe(
+  subscriber: MqttConn,
+  topicFilters: TopicFilter[],
+  {
+    level = MQTTLevel.v4,
+    id = 24,
+  } = {},
+) {
+  subscriber.send({
+    type: PacketType.unsubscribe,
+    protocolLevel: level,
+    id,
+    topicFilters,
+  });
+  const { value: packet } = await subscriber.next();
+  assert.equal(packet.type, PacketType.unsuback, "Expected UNSUBACK");
+  assert.equal(packet.protocolLevel, level, "received expected level");
+  assert.equal(packet.id, id, "UNSUBACK ID should match UNSUBSCRIBE ID");
+}
+
+export async function unsubscribe5(
+  subscriber: MqttConn,
+  topicFilters: TopicFilter[],
+  { id = 24 } = {},
+): Promise<UnsubackPacket> {
+  subscriber.send({
+    type: PacketType.unsubscribe,
+    protocolLevel: MQTTLevel.v5,
+    id,
+    topicFilters,
+  });
+  const { value: packet } = await subscriber.next();
+  assert.equal(packet.type, PacketType.unsuback, "Expected UNSUBACK");
+  assert.equal(packet.protocolLevel, MQTTLevel.v5, "received expected level");
+  assert.equal(packet.id, id, "UNSUBACK ID should match UNSUBSCRIBE ID");
+  return packet;
+}
+
+export async function publish(
+  publisher: MqttConn,
+  topic: Topic,
+  qos: QoS,
+  {
+    level = MQTTLevel.v4 as ProtocolLevel,
+    id = 22,
+    payload = "payload",
+    retain = false,
+    properties = {},
+    checkAcks = true,
+  } = {},
+) {
+  const encodedPayload = txtEncoder.encode(payload);
+
+  await publisher.send({
+    type: PacketType.publish,
+    protocolLevel: level,
+    id,
+    topic,
+    qos,
+    payload: encodedPayload,
+    retain,
+    properties,
+  });
+  logger.debug("publish helper: sent publish");
+  if (!checkAcks || qos === 0) return;
+
+  const { value: ackPacket } = await publisher.next();
+  const expectedAckType = qos === 1 ? PacketType.puback : PacketType.pubrec;
+  assert.equal(ackPacket.type, expectedAckType, "received expected ack");
+  assert.equal(ackPacket.protocolLevel, level, "received expected level");
+  assert.equal(ackPacket.id, id, "packetid matches");
+  logger.debug("publish helper: received pubAck");
+
+  if (qos === 1) return ackPacket;
+
+  publisher.send({
+    type: PacketType.pubrel,
+    protocolLevel: level,
+    id,
+  });
+
+  const { value: compPacket } = await publisher.next();
+  assert.equal(
+    compPacket.type,
+    PacketType.pubcomp,
+    "received expected pubcomp",
+  );
+  assert.equal(compPacket.id, id, "packetid of pubcomp matches");
+}
+
+export function publish5(
+  publisher: MqttConn,
+  topic: Topic,
+  qos: QoS,
+  opts?: {
+    id?: number;
+    payload?: string;
+    retain?: boolean;
+    properties?: PublishProperties;
+    checkAcks?: boolean;
+  },
+) {
+  return publish(
+    publisher,
+    topic,
+    qos,
+    Object.assign({}, opts, { level: MQTTLevel.v5 }),
+  );
+}
+
+export async function disconnect(
+  mqttConn: MqttConn,
+  { level = MQTTLevel.v4 } = {},
+) {
+  mqttConn.send({
+    type: PacketType.disconnect,
+    protocolLevel: level,
+  });
+  await mqttConn.next();
+
+  assert.strictEqual(
+    mqttConn.isClosed,
+    true,
+    "Expected connection to be closed",
+  );
+}
+
+export async function disconnect5(mqttConn: MqttConn, opts?: {
+  reasonCode?: number;
+  properties?: DisconnectProperties;
+}) {
+  const packet = {
+    type: PacketType.disconnect,
+    protocolLevel: MQTTLevel.v5,
+    reasonCode: opts?.reasonCode,
+    properties: opts?.properties,
+  };
+
+  mqttConn.send(packet);
+  await mqttConn.next();
+  await mqttConn.next();
+
+  assert.strictEqual(
+    mqttConn.isClosed,
+    true,
+    "Expected connection to be closed",
+  );
+}
+
+export async function ping(mqttConn: MqttConn) {
+  mqttConn.send(PINGREQ_PACKET);
+  const { value: pingres } = await mqttConn.next();
+  assert.strictEqual(pingres.type, PacketType.pingres);
+}
+
+export async function receiveMessages(conn: MqttConn) {
+  const received = Array.fromAsync(conn);
+  await delay(10);
+  await disconnect(conn);
+  const messages = await received;
+  return messages;
+}
+
+export async function receiveMessages5(conn: MqttConn) {
+  const received = Array.fromAsync(conn);
+  await delay(10);
+  await disconnect5(conn);
+  const messages = await received;
+  return messages;
+}

package/dev_utils/test-handlers.ts

@@ -0,0 +1,98 @@
+import { ReasonCode } from "../server/mod.ts";
+import { logger } from "../utils/mod.ts";
+import type {
+  AuthenticatedResult,
+  Context,
+  ShareName,
+  Topic,
+} from "../server/mod.ts";
+
+const utf8Decoder = new TextDecoder();
+const userTable = new Map();
+userTable.set("IoTester_1", "strong_password");
+userTable.set("IoTester_2", "strong_password");
+const strictUsername = new RegExp(/^[a-zA-Z0-9]{0,23}$/);
+
+function isAuthenticated(
+  _ctx: Context,
+  clientId: string,
+  username: string,
+  password: Uint8Array,
+): AuthenticatedResult {
+  const pwd = utf8Decoder.decode(password);
+  logger.debug(
+    `Verifying authentication of client '${clientId}' with username '${username}'`,
+  );
+
+  if (!userTable.has(username)) {
+    if (!strictUsername.test(username)) {
+      return { reasonCode: ReasonCode.success };
+    }
+  }
+
+  const pass = userTable.get(username);
+  if (pwd === pass) {
+    return { reasonCode: ReasonCode.success };
+  }
+  return {
+    reasonCode: ReasonCode.badUserNameOrPassword,
+    reasonString: "Bad username or password",
+  };
+}
+
+function processAuth(
+  _ctx: Context,
+  _clientId: string,
+  _authMethod: string,
+  _authData: Uint8Array,
+) {
+  return {
+    reasonCode: ReasonCode.badAuthenticationMethod,
+    reasonString: "Authentication method not supported",
+  };
+}
+
+function isAuthorizedToPublish(ctx: Context, topic: Topic): boolean {
+  logger.debug(
+    "Checking authorization of client",
+    ctx.clientId,
+    "to publish on topic",
+    topic,
+  );
+  if (topic === "topic/unauthorized") {
+    return false;
+  }
+  return true;
+}
+function isAuthorizedToSubscribe(
+  ctx: Context,
+  topic: Topic,
+  shareName: ShareName,
+): boolean {
+  logger.debug(
+    "Checking authorization of client",
+    ctx.clientId,
+    "to subscribe to topic",
+    topic,
+    "using shareName",
+    shareName,
+  );
+  if (topic === "topic/unauthorized") {
+    return false;
+  }
+  return true;
+}
+
+export const handlers = {
+  isAuthenticated,
+  processAuth,
+  isAuthorizedToPublish,
+  isAuthorizedToSubscribe,
+};
+
+export function isAuthenticatedBroker(
+  ctx: Context,
+): AuthenticatedResult {
+  ctx.isBroker = true;
+  return { reasonCode: ReasonCode.success };
+}

package/dev_utils/timers.ts

@@ -6,6 +6,9 @@
 // This will also work on Deno:
 // https://docs.deno.com/api/node/timers/#namespace_setimmediate
 import { setImmediate } from "node:timers";
+import { setTimeout as delay } from "node:timers/promises";
+import type { AnyPacket } from "../mqttPacket/mod.ts";
+export { delay };
 
 let taskCounter = 0;
 
@@ -49,3 +52,14 @@ export const resolveAsap = (): Promise<void> => {
 export const resolveNextTick = (): Promise<void> => {
   return new Promise((resolve) => setImmediate(resolve));
 };
+
+/**
+ * Races a promise to test timeouts
+ */
+export function withTimeout(
+  promise: Promise<IteratorResult<AnyPacket>>,
+  timeoutMs: number,
+): Promise<IteratorResult<AnyPacket> | null> {
+  const timeoutPromise = delay(timeoutMs, null);
+  return Promise.race([promise, timeoutPromise]);
+}

package/dev_utils/webStreamPair.test.ts

@@ -0,0 +1,171 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { createWebStreamPair } from "./webStreamPair.ts";
+
+test("Echo server shuts down cleanly when client closes input", async () => {
+  const { input, output } = createWebStreamPair();
+
+  const echoPromise = output.readable.pipeTo(output.writable);
+
+  const writer = input.writable.getWriter();
+  const reader = input.readable.getReader();
+
+  // Client closes their side
+  await writer.close();
+
+  // The echo server's pipeTo should resolve and finish successfully
+  await assert.doesNotReject(echoPromise);
+
+  // The client's reader should now receive the end-of-stream signal
+  const { done } = await reader.read();
+  assert.strictEqual(done, true);
+
+  writer.releaseLock();
+  reader.releaseLock();
+});
+
+test("Data written to input.writable arrives at output.readable", async () => {
+  const { input, output } = createWebStreamPair();
+
+  const echoPromise = output.readable.pipeTo(output.writable);
+
+  const writer = input.writable.getWriter();
+  const reader = input.readable.getReader();
+
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+
+  // Write data to the input side
+  await writer.write(encoder.encode("Hello streaming world!"));
+  await writer.close(); // Close the stream after writing
+
+  // The echo server's pipeTo should resolve and finish successfully
+  await assert.doesNotReject(echoPromise);
+
+  // Read the data from the input side
+  const chunks: Uint8Array[] = [];
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (value) chunks.push(value);
+  }
+
+  // Combine chunks and decode to string
+  const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+  const resultUint8 = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    resultUint8.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  const readText = decoder.decode(resultUint8);
+
+  // Verify the text matches exactly
+  assert.strictEqual(readText, "Hello streaming world!");
+  reader.releaseLock();
+});
+
+test("Data can be written and read sequentially before closing", async () => {
+  const { input, output } = createWebStreamPair();
+  const echoPromise = output.readable.pipeTo(output.writable);
+
+  const writer = input.writable.getWriter();
+  const reader = input.readable.getReader();
+
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+
+  // 1. First Write & Read chunk
+  await writer.write(encoder.encode("Chunk 1"));
+  const result1 = await reader.read();
+  assert.strictEqual(result1.done, false);
+  assert.strictEqual(decoder.decode(result1.value), "Chunk 1");
+
+  // 2. Second Write & Read chunk
+  await writer.write(encoder.encode("Chunk 2"));
+  const result2 = await reader.read();
+  assert.strictEqual(result2.done, false);
+  assert.strictEqual(decoder.decode(result2.value), "Chunk 2");
+
+  // 3. Now we close the writable side mid-stream
+  await writer.close();
+
+  // The echo server's pipeTo should resolve and finish successfully
+  await assert.doesNotReject(echoPromise);
+
+  // 4. Verify that the readable side now registers the close signal
+  const finalResult = await reader.read();
+  assert.strictEqual(finalResult.done, true);
+  assert.strictEqual(finalResult.value, undefined);
+
+  writer.releaseLock();
+  reader.releaseLock();
+});
+
+test("Client detects when the echo server abruptly closes its end", async () => {
+  const { input, output } = createWebStreamPair();
+  const encoder = new TextEncoder();
+
+  // Set up a manual echo server so we can manipulate its controls
+  const serverReader = output.readable.getReader();
+  const serverWriter = output.writable.getWriter();
+
+  // Start a basic manual loop in the background
+  const serverLoop = (async () => {
+    try {
+      while (true) {
+        const { value, done } = await serverReader.read();
+        if (done) break;
+        await serverWriter.write(value);
+      }
+    } finally {
+      serverReader.releaseLock();
+      serverWriter.releaseLock();
+    }
+  })();
+
+  const clientWriter = input.writable.getWriter();
+  const clientReader = input.readable.getReader();
+
+  // --- Simulate Server Shutdown ---
+  // The echo server decides to close its writing side out of nowhere
+  try {
+    await serverWriter.close();
+    await serverReader.cancel();
+    await serverLoop;
+
+    const first = await clientReader.read();
+    assert.strictEqual(first.done, true);
+
+    await assert.rejects(
+      () => clientWriter.write(encoder.encode("Is anyone there?")),
+      /close|invalid/i,
+    );
+  } finally {
+    clientWriter.releaseLock();
+    clientReader.releaseLock();
+  }
+});
+
+test("Repeated close and cancel calls are idempotent", async () => {
+  const { input, output } = createWebStreamPair();
+
+  const inputWriter = input.writable.getWriter();
+  const inputReader = input.readable.getReader();
+  const outputWriter = output.writable.getWriter();
+  const outputReader = output.readable.getReader();
+
+  await Promise.allSettled([
+    inputWriter.close(),
+    outputWriter.close(),
+    inputReader.cancel(),
+    outputReader.cancel(),
+  ]);
+
+  inputWriter.releaseLock();
+  inputReader.releaseLock();
+  outputWriter.releaseLock();
+  outputReader.releaseLock();
+});