@seriousme/opifex 1.6.2 → 1.7.0

package/server/handlers/handlePubrec.ts

@@ -1,9 +1,17 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PubrecPacket } from "../deps.ts";
 
-// qos 2
-// Discard message, Store PUBREC received <Packet Identifier>
-// send PUBREL <Packet Identifier>
+/**
+ * Handles PUBREC (QoS 2 Publish Received) packets
+ * @param ctx - The connection context
+ * @param packet - The PUBREC packet received from the client
+ * @returns Promise that resolves when handling is complete
+ * @description
+ * For QoS 2 message flow:
+ * 1. Discards the original publish message
+ * 2. Stores that PUBREC was received for the packet ID
+ * 3. Sends PUBREL packet in response
+ */
 export async function handlePubrec(
   ctx: Context,
   packet: PubrecPacket,

package/server/handlers/handlePubrel.ts

@@ -1,10 +1,18 @@
 import type { Context } from "../context.ts";
 import { PacketType, type PubrelPacket } from "../deps.ts";
 
-// qos 2 only
-// Method A, Initiate onward delivery of the Application Message1  then discard message
-// Send PUBCOMP <Packet Identifier>
-
+/**
+ * Handles PUBREL (QoS 2 publish release) packets
+ *
+ * @param ctx - The connection context
+ * @param packet - The PUBREL packet received from the client
+ * @returns Promise that resolves when handling is complete
+ * @description
+ * For QoS 2 message delivery:
+ * 1. Initiates onward delivery of the Application Message
+ * 2. Discards the stored message
+ * 3. Sends PUBCOMP packet with the Packet Identifier
+ */
 export async function handlePubrel(
   ctx: Context,
   packet: PubrelPacket,

package/server/handlers/handleSubscribe.ts

@@ -6,7 +6,18 @@ import {
   type Topic,
 } from "../deps.ts";
 
+/**
+ * @constant {number} SubscriptionFailure
+ * @description Code indicating a failed subscription attempt
+ */
 const SubscriptionFailure = 0x80;
+
+/**
+ * Checks if a client is authorized to subscribe to a topic
+ * @param  ctx - The connection context
+ * @param  topicFilter - The topic filter to check authorization for
+ * @returns True if authorized, false otherwise
+ */
 function authorizedToSubscribe(ctx: Context, topicFilter: Topic) {
   if (ctx.handlers.isAuthorizedToSubscribe) {
     return ctx.handlers.isAuthorizedToSubscribe(ctx, topicFilter);
@@ -14,13 +25,23 @@ function authorizedToSubscribe(ctx: Context, topicFilter: Topic) {
   return true;
 }
 
+/**
+ * @function handleSubscribe
+ * @description Processes an MQTT SUBSCRIBE packet
+ * @param {Context} ctx - The connection context
+ * @param {SubscribePacket} packet - The SUBSCRIBE packet received from the client
+ * @returns {Promise<void>}
+ * @throws {Error} If subscription processing fails
+ * @remarks The order of return codes in the SUBACK Packet MUST match the order of Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1]
+ */
 export async function handleSubscribe(
   ctx: Context,
   packet: SubscribePacket,
 ): Promise<void> {
-  //  The order of return codes in the SUBACK Packet MUST match the order of
-  //  Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1].
-
+  /*
+   * The order of return codes in the SUBACK Packet MUST match the order of
+   * Topic Filters in the SUBSCRIBE Packet [MQTT-3.9.3-1].
+   */
   const validSubscriptions: Subscription[] = [];
   const returnCodes = packet.subscriptions.map((sub) => {
     if (ctx.store) {
@@ -31,7 +52,7 @@ export async function handleSubscribe(
       validSubscriptions.push(sub);
       return sub.qos;
     }
-    return SubscriptionFailure; // failure
+    return SubscriptionFailure;
   });
 
   await ctx.send({
@@ -40,7 +61,9 @@ export async function handleSubscribe(
     returnCodes: returnCodes,
   });
 
-  // send any retained messages that match these subscriptions
+  /*
+   * send any retained messages that match these subscriptions
+   */
   if (ctx.store) {
     ctx.persistence.handleRetained(ctx.store.clientId);
   }

package/server/handlers/handleUnsubscribe.ts

@@ -1,6 +1,12 @@
 import type { Context } from "../context.ts";
 import { PacketType, type UnsubscribePacket } from "../deps.ts";
 
+/**
+ * Handles MQTT unsubscribe packets by removing subscriptions and sending acknowledgement
+ * @param ctx - The connection context containing client information and methods
+ * @param packet - The MQTT unsubscribe packet containing topics to unsubscribe from
+ * @returns Promise that resolves when unsubscribe is complete and acknowledged
+ */
 export async function handleUnsubscribe(
   ctx: Context,
   packet: UnsubscribePacket,

package/utils/asyncQueue.ts

@@ -1,15 +1,16 @@
 import { nextTick } from "./nextTick.ts";
-
 /**
  * An Async Queue is a queue that can be used to push items to it and then wait
  * for them to be consumed.
  *
  * @example
+ * ```ts
  * const queue = new AsyncQueue<string>();
  * queue.push("hello");
  * for await (const item of queue) {
  *   console.log(item); // "hello"
  * }
+ * ```
  */
 export class AsyncQueue<T> {
   private queue: T[] = [];

package/utils/nextTick.ts

@@ -1,5 +1,17 @@
 /**
- * @returns a promise that resolves on the nextTick of the event loop
+ * Returns a promise that resolves on the next tick of the Node.js event loop.
+ * This is useful for deferring execution of code until after the current call stack is cleared.
+ *
+ * @example
+ * ```ts
+ * async function example() {
+ *   console.log('Before nextTick');
+ *   await nextTick();
+ *   console.log('After nextTick');
+ * }
+ * ```
+ *
+ * @returns {Promise<void>} A promise that resolves on the next tick of the event loop
  */
 export function nextTick(): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, 0));

package/.github/workflows/closeStale.yml

@@ -1,15 +0,0 @@
-name: "Close stale issues"
-on:
-  schedule:
-    - cron: "5 0 * * *"
-
-jobs:
-  stale:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/stale@v3
-        with:
-          repo-token: ${{ secrets.GITHUB_TOKEN }}
-          days-before-stale: 30
-          days-before-close: 5
-          stale-issue-message: This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days'

package/.github/workflows/codeql-analysis.yml

@@ -1,71 +0,0 @@
-# For most projects, this workflow file will not need changing; you simply need
-# to commit it to your repository.
-#
-# You may wish to alter this file to override the set of languages analyzed,
-# or to provide custom queries or build logic.
-#
-# ******** NOTE ********
-# We have attempted to detect the languages in your repository. Please check
-# the `language` matrix defined below to confirm you have the correct set of
-# supported CodeQL languages.
-#
-name: "CodeQL"
-
-on:
-  push:
-    branches: [master]
-  pull_request:
-    # The branches below must be a subset of the branches above
-    branches: [master]
-  schedule:
-    - cron: "27 16 * * 3"
-
-jobs:
-  analyze:
-    name: Analyze
-    runs-on: ubuntu-latest
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-
-    strategy:
-      fail-fast: false
-      matrix:
-        language: ["javascript"]
-        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
-        # Learn more:
-        # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v2
-
-      # Initializes the CodeQL tools for scanning.
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@v1
-        with:
-          languages: ${{ matrix.language }}
-          # If you wish to specify custom queries, you can do so here or in a config file.
-          # By default, queries listed here will override any specified in a config file.
-          # Prefix the list here with "+" to use these queries and those in the config file.
-          # queries: ./path/to/local/query, your-org/your-repo/queries@main
-
-      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-      # If this step fails, then you should remove it and run the build manually (see below)
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v1
-
-      # ℹ️ Command-line programs to run using the OS shell.
-      # 📚 https://git.io/JvXDl
-
-      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-      #    and modify them (or add more) to build your code if your project
-      #    uses a compiled language
-
-      #- run: |
-      #   make bootstrap
-      #   make release
-
-      - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v1

package/.github/workflows/deno-ci.yml

@@ -1,16 +0,0 @@
-# This workflow will test on Deno lastest stable major and canary
-# see https://github.com/marketplace/actions/setup-deno for details
-name: Deno CI
-on: [push, pull_request]
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: denoland/setup-deno@v2
-        with:
-          deno-version: vx.x.x # Run with latest stable Deno.
-      - run: deno install
-      - run: deno fmt --check
-      - run: deno lint
-      - run: deno test -A

package/.github/workflows/nodejs-ci.yml

@@ -1,23 +0,0 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
-name: Node.js CI
-
-on: [push, pull_request]
-
-permissions: {}
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: ["22", "23"]
-    steps:
-      - uses: actions/checkout@v4
-      - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-      - run: npm run test

package/.github/workflows/publish.yml

@@ -1,16 +0,0 @@
-name: Publish
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write # The OIDC ID token is used for authentication with JSR.
-    steps:
-      - uses: actions/checkout@v4
-      - run: npx jsr publish

package/.github/workflows/update-license-year.sh

@@ -1,14 +0,0 @@
-#!/bin/bash
-
-license='LICENSE.txt'
-prefix='2016-'
-current_year=$(date +%Y)
-sed -i -e "s/$prefix\([0-9\]\+\)/$prefix$current_year/" $license
-
-if [ "$(git diff $license)" ]; then
-  git add $license
-  git commit -m "Update license year to $current_year"
-  git push
-else
-  echo "No changes detected in $license"
-fi

package/.github/workflows/update-license-year.yml

@@ -1,13 +0,0 @@
-name: Update License Year
-
-on:
-  schedule:
-    - cron: "5 12 1 1 *"
-
-jobs:
-  update_license:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - name: Update license year
-        run: ./update_license.sh

package/CHANGELOG.md

@@ -1,74 +0,0 @@
-# Changelog
-
-## [Unreleased]
-
-### Changed
-
-## [v1.6.2] 19-01-2025
-
-### Changed
-
-- fix: added more JSdoc comments
-
-## [v1.6.1] 18-01-2025
-
-### Changed
-
-- fix: fixed Deno lint type errors
-
-## [v1.6.0] 18-01-2025
-
-### Changed
-
-- added: export TcpClient and TcpServer for both NodeJS and Deno
-- added: export mqttPacket and utils
-
-## [v1.5.1] 16-01-2025
-
-### Changed
-
-- fixed issue with QoS=1
-
-## [v1.5.0] 02-01-2025
-
-### Changed
-
-- added client certificate support to mqtts.ts
-
-## [v1.4.0] 02-01-2025
-
-### Changed
-
-- added client certificate support (w0otness)
-
-## [v1.3.0] 19-11-2024
-
-### Changed
-
-- update: added architectural description of Opifex to documentation
-- update: added comments to platform specific code to explain boundary between
-  platform agnostic and platform specific.
-- update: set default clientId in client
-- fix: improve handling of errors if client connect fails
-
-## [v1.2.1] 01-11-2024
-
-### Changed
-
-- fix: unlock last BYOB request using respond(0)
-
-## [v1.2.0] 01-11-2024
-
-### Changed
-
-- added support for NodeJS < 22.0.6 by adding transpiled Javascript in `/dist`
-
-## [v1.1.0] 01-11-2024
-
-### Changed
-
-- added support for NodeJS >= 22.0.6 using --experimental-strip-types
-
-## [v1.0.0] 09-10-2022
-
-Initial version

package/deno.json

@@ -1,15 +0,0 @@
-{
-  "name": "@seriousme/opifex",
-  "version": "1.6.2",
-  "exports": {
-    "./server": "./server/mod.ts",
-    "./client": "./client/mod.ts",
-    "./mqttPacket": "./mqttPacket/mod.ts",
-    "./utils": "./utils/mod.ts",
-    "./tcpClient": "./deno/tcpClient.ts",
-    "./tcpServer": "./deno/tcpServer.ts"
-  },
-  "exclude": [
-    "dist"
-  ]
-}

package/deno.lock

@@ -1,34 +0,0 @@
-{
-  "version": "4",
-  "specifiers": {
-    "npm:@types/node@*": "22.5.4",
-    "npm:@types/node@^22.10.0": "22.10.0"
-  },
-  "npm": {
-    "@types/node@22.10.0": {
-      "integrity": "sha512-XC70cRZVElFHfIUB40FgZOBbgJYFKKMa5nb9lxcwYstFG/Mi+/Y0bGS+rs6Dmhmkpq4pnNiLiuZAbc02YCOnmA==",
-      "dependencies": [
-        "undici-types@6.20.0"
-      ]
-    },
-    "@types/node@22.5.4": {
-      "integrity": "sha512-FDuKUJQm/ju9fT/SeX/6+gBzoPzlVCzfzmGkwKvRHQVxi4BntVbyIwf6a4Xn62mrvndLiml6z/UBXIdEVjQLXg==",
-      "dependencies": [
-        "undici-types@6.19.8"
-      ]
-    },
-    "undici-types@6.19.8": {
-      "integrity": "sha512-ve2KP6f/JnbPBFyobGHuerC9g1FYGn/F8n1LWTwNxCEzd6IfqTwUQcNXgEtmmQ6DlRrC1hrSrBnCZPokRrDHjw=="
-    },
-    "undici-types@6.20.0": {
-      "integrity": "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="
-    }
-  },
-  "workspace": {
-    "packageJson": {
-      "dependencies": [
-        "npm:@types/node@^22.10.0"
-      ]
-    }
-  }
-}

package/dist/bin/conformanceServer.js

@@ -1,51 +0,0 @@
-#!/usr/bin/env -S node --experimental-strip-types
-// this server is intended to be used with https://github.com/eclipse/iottestware
-import { AuthenticationResult } from "../server/mod.js";
-import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
-import { TcpServer } from "../node/tcpServer.js";
-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}$/);
-const notAuthorizedTable = new Set();
-notAuthorizedTable.add(["123-456-789", "eclipse/iot/tesware/0data"]);
-function isAuthenticated(_ctx, clientId, username, password) {
-    const pwd = utf8Decoder.decode(password);
-    logger.debug(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
-    if (!userTable.has(username)) {
-        if (!strictUsername.test(username)) {
-            return AuthenticationResult.badUsernameOrPassword;
-        }
-    }
-    const pass = userTable.get(username);
-    if (pwd === pass) {
-        return AuthenticationResult.ok;
-    }
-    return AuthenticationResult.notAuthorized;
-}
-function isAuthorizedToPublish(ctx, topic) {
-    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`);
-    // if (notAuthorizedTable.has([ctx.client,topic])){
-    //   return false;
-    // }
-    return true;
-}
-function isAuthorizedToSubscribe(ctx, topic) {
-    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`);
-    return true;
-}
-/** start the server **/
-const { _: [portNum] } = parseArgs(getArgs());
-const port = Number(portNum ?? 1883);
-const hostname = "::";
-logger.level(LogLevel.info);
-const tcpServer = new TcpServer({ port, hostname }, {
-    handlers: {
-        isAuthenticated,
-        isAuthorizedToPublish,
-        isAuthorizedToSubscribe,
-    },
-});
-tcpServer.start();
-logger.info(`Server started on port ${tcpServer.port}`);

package/dist/bin/demoServer.js

@@ -1,46 +0,0 @@
-#!/usr/bin/env -S node --experimental-strip-types
-import { TcpServer } from "../node/tcpServer.js";
-import { AuthenticationResult } from "../server/mod.js";
-import { getArgs, logger, LogLevel, parseArgs } from "../utils/mod.js";
-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, clientId, username, password) {
-    const pwd = utf8Decoder.decode(password);
-    logger.info(`Verifying authentication of client '${clientId}' with username '${username}' and password '${pwd}'`);
-    return AuthenticationResult.ok;
-    // if (!userTable.has(username)) {
-    //   if (!strictUsername.test(username)) {
-    //     return AuthenticationResult.badUsernameOrPassword;
-    //   }
-    // }
-    // const pass = userTable.get(username);
-    // if (pwd === pass) {
-    //   return AuthenticationResult.ok;
-    // }
-    // return AuthenticationResult.badUsernameOrPassword;
-}
-function isAuthorizedToPublish(ctx, topic) {
-    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to publish on topic '${topic}'`);
-    return true;
-}
-function isAuthorizedToSubscribe(ctx, topic) {
-    logger.debug(`Checking authorization of client '${ctx.store?.clientId}' to subscribe to topic '${topic}'`);
-    return true;
-}
-/** start the server **/
-const { _: [portNum] } = parseArgs(getArgs());
-const port = Number(portNum ?? 1883);
-const hostname = "::";
-logger.level(LogLevel.info);
-const tcpServer = new TcpServer({ port, hostname }, {
-    handlers: {
-        isAuthenticated,
-        isAuthorizedToPublish,
-        isAuthorizedToSubscribe,
-    },
-});
-tcpServer.start();
-logger.info(`Server started on port ${tcpServer.port}`);