aedes 0.51.3 → 1.0.0

package/docs/Aedes.md

@@ -2,7 +2,9 @@
 # Aedes
 
 - [Aedes](#aedes)
-  - [new Aedes([options]) / new Aedes.Server([options])](#new-aedesoptions--new-aedesserveroptions)
+  - [new Aedes(\[options\])](#new-aedesoptions)
+  - [Aedes.createBroker(\[options\])](#aedescreatebrokeroptions)
+  - [aedes.listen()](#aedeslisten)
   - [aedes.id](#aedesid)
   - [aedes.connectedClients](#aedesconnectedclients)
   - [aedes.closed](#aedesclosed)
@@ -23,7 +25,7 @@
   - [aedes.subscribe (topic, deliverfunc, callback)](#aedessubscribe-topic-deliverfunc-callback)
   - [aedes.unsubscribe (topic, deliverfunc, callback)](#aedesunsubscribe-topic-deliverfunc-callback)
   - [aedes.publish (packet, callback)](#aedespublish-packet-callback)
-  - [aedes.close ([callback])](#aedesclose-callback)
+  - [aedes.close (\[callback\])](#aedesclose-callback)
   - [Handler: preConnect (client, packet, callback)](#handler-preconnect-client-packet-callback)
   - [Handler: authenticate (client, username, password, callback)](#handler-authenticate-client-username-password-callback)
   - [Handler: authorizePublish (client, packet, callback)](#handler-authorizepublish-client-packet-callback)
@@ -31,23 +33,75 @@
   - [Handler: authorizeForward (client, packet)](#handler-authorizeforward-client-packet)
   - [Handler: published (packet, client, callback)](#handler-published-packet-client-callback)
 
-## new Aedes([options]) / new Aedes.Server([options])
+## new Aedes([options])
 
 - options `<object>`
   - `mq` [`<MQEmitter>`](../README.md#mqemitter) middleware used to deliver messages to subscribed clients. In a cluster environment it is used also to share messages between brokers instances. __Default__: `mqemitter`
-  - `concurrency` `<number>` maximum number of concurrent messages delivered by `mq`. __Default__: `100`
+  - `concurrency` `<number>` maximum number of concurrent messages that can be processed simultaneously by `mq`. __Default__: `100`
+
+    __Note:__ Concurrency determines how many messages can be "in-flight" at once. When a slow client blocks (socket buffer full), the message delivery hangs waiting for the `drain` event. With `N` concurrency slots and ANY frozen subscriber on a topic, fast clients will receive at most `N` messages before complete deadlock. Higher concurrency = larger buffer before freeze, but without `drainTimeout`, deadlock is __inevitable__. Use `drainTimeout` to protect against this.
   - `persistence` [`<Persistence>`](../README.md#persistence) middleware that stores _QoS > 0, retained, will_ packets and _subscriptions_. __Default__: `aedes-persistence` (_in memory_)
+  Versions 1.x and above require persistence to support async access,see [MIGRATION.md][MIGRATION] for details.
   - `queueLimit` `<number>` maximum number of queued messages before client session is established. If number of queued items exceeds, `connectionError` throws an error `Client queue limit reached`. __Default__: `42`
   - `maxClientsIdLength` option to override MQTT 3.1.0 clients Id length limit. __Default__: `23`
   - `heartbeatInterval` `<number>` an interval in millisconds at which server beats its health signal in `$SYS/<aedes.id>/heartbeat` topic. __Default__: `60000`
   - `id` `<string>` aedes broker unique identifier. __Default__: `uuidv4()`
   - `connectTimeout` `<number>` maximum waiting time in milliseconds waiting for a [`CONNECT`][CONNECT] packet. __Default__: `30000`
   - `keepaliveLimit` `<number>` maximum client keep alive time allowed, 0 means no limit. __Default__: `0`
+  - `drainTimeout` `<number>` maximum time in milliseconds to wait for a slow client's socket to drain before disconnecting it. When a client's socket buffer fills up (e.g., slow network, unresponsive client), the broker waits for the `drain` event. Without a timeout, one slow client can block message delivery to all other clients. Set to `0` to disable and wait indefinitely (not recommended). __Default__: `60000` (60 seconds)
+
+    __Why use drainTimeout?__ When publishing messages, if a client's TCP buffer is full, `socket.write()` returns `false` and the broker waits for the `drain` event before continuing. If the client stops reading (slow 3G, crashed app, malicious client), `drain` never fires and that message hangs forever. Even with high `concurrency`, a single frozen subscriber will eventually exhaust all slots and cause __complete deadlock__ - no more messages can be delivered to ANY client. This is a DoS vulnerability.
+
+    __Recommended settings:__
+    - Production: `10000` - `60000` ms (10-60 seconds)
+    - High-latency networks: Higher values to avoid disconnecting legitimate slow clients
+    - IoT/embedded devices: Consider client capabilities when setting timeout
+
+    ```js
+    // Recommended for production
+    const broker = await Aedes.createBroker({
+      drainTimeout: 30000  // Disconnect unresponsive clients after 30 seconds (default: 60000)
+      // drainTimeout: 0   // Disable timeout - NOT RECOMMENDED: vulnerable to DoS
+    })
+
+    // Monitor disconnections (optional)
+    broker.on('clientDisconnect', (client) => {
+      console.log(`Client ${client.id} disconnected`)
+    })
+    ```
+
 - Returns `<Aedes>`
 
-Create a new Aedes server.
+Create a new Aedes server instance.
+
+Aedes is the class exported by this module.
+The instance will only start listening after [aedes.listen()](#aedeslisten) is called.
+The recommended way to start an Aedes server is to use [Aedes.createBroker([options])](#aedescreatebrokeroptions) instead.
+
+## Aedes.createBroker([options])
+
+An async static method in the Aedes class which creates the instance and automatically awaits `listen()`.
+
+Using `Aedes.createBroker([options])` is the recommended way to start Aedes, example:
 
-Aedes is the class and function exposed by this module. It can be created by `Aedes()` or using `new Aedes()`. An variant `aedes.Server` is for TypeScript or ES modules.
+```js
+const aedes = await Aedes.createBroker([options])
+```
+
+It uses the same options as [new Aedes([options])](#new-aedesoptions)
+
+## aedes.listen()
+
+Async method to make the aedes instance start listening.
+Example:
+
+```js
+const aedes = new Aedes([options])
+await aedes.listen()
+```
+
+You should typically not need to use this as it is more compact to use
+[Aedes.createBroker([options])](#aedescreatebrokeroptions) instead.
 
 ## aedes.id
 
@@ -173,8 +227,11 @@ Emitted when server is closed.
 A connection listener that pipe stream to aedes.
 
 ```js
-const aedes = require('./aedes')()
-const server = require('net').createServer(aedes.handle)
+import { createServer } from 'node:net'
+import { Aedes } from 'aedes'
+
+const aedes = await Aedes.createBroker()
+const server = createServer(aedes.handle)
 ```
 
 ## aedes.subscribe (topic, deliverfunc, callback)
@@ -414,3 +471,4 @@ same as [`Event: publish`](#event-publish), but provides a backpressure function
 [PINGREQ]: https://github.com/mqttjs/mqtt-packet#pingreq
 [PUBLISH]: https://github.com/mqttjs/mqtt-packet#publish
 [PUBREL]: https://github.com/mqttjs/mqtt-packet#pubrel
+[MIGRATION]: MIGRATION.md

package/docs/Client.md

@@ -34,13 +34,13 @@ Client connection stream object.
 
 In the case of `net.createServer`, `conn` passed to the `connectionlistener` function by node's [net.createServer](https://nodejs.org/api/net.html#net_net_createserver_options_connectionlistener) API.
 
-In the case of [`websocket-stream`][websocket-stream], it's the `stream` argument passed to the websocket `handle` function in [`websocket-stream #on-the-server`][websocket-stream-doc-on-the-server]].
+In the case of [`ws`][ws], it's the `stream.Duplex` argument passed to the `handle` function.
 
 ## client.req
 
 - `<http.IncomingMessage>`
 
-only for [`websocket-stream`][websocket-stream]. It is a HTTP Websocket upgrade request object passed to websocket `handle` function in [`websocket-stream #on-the-server`][websocket-stream-doc-on-the-server]. It gives an option for accessing headers or cookies.
+only for [`ws`][ws]. It is a HTTP Websocket upgrade request object passed to the `handle` function. It gives an option for accessing headers or cookies.
 
 ## client.connecting
 
@@ -152,5 +152,4 @@ Clear all outgoing messages (QoS > 1) related to this client from persistence
 [SUBSCRIBE]: https://github.com/mqttjs/mqtt-packet#subscribe
 [UNSUBSCRIBE]: https://github.com/mqttjs/mqtt-packet#unsubscribe
 
-[websocket-stream]: https://www.npmjs.com/websocket-stream
-[websocket-stream-doc-on-the-server]: https://github.com/maxogden/websocket-stream/blob/master/readme.md#on-the-server
+[ws]: https://www.npmjs.com/package/ws

package/docs/Examples.md

@@ -4,24 +4,27 @@
 ## Simple plain MQTT server
 
 ```js
-const aedes = require('aedes')()
-const server = require('net').createServer(aedes.handle)
+import { createServer } from 'node:net'
+import Aedes from 'aedes'
+
 const port = 1883
 
+const aedes = await Aedes.createBroker()
+const server = createServer(aedes.handle)
+
 server.listen(port, function () {
   console.log('server started and listening on port ', port)
 })
 ```
 
-## Typescript
+## CommonJS
 
-```ts
-import Aedes from 'aedes'
-import { createServer } from 'net'
+```js
+const { createServer } = require('node:net')
+const { Aedes } = require('aedes')
 
+const aedes = await Aedes.createBroker()
 const port = 1883
-
-const aedes = new Aedes()
 const server = createServer(aedes.handle)
 
 server.listen(port, function () {
@@ -32,10 +35,11 @@ server.listen(port, function () {
 ## Simple plain MQTT server using server-factory
 
 ```js
-const aedes = require('aedes')()
-const { createServer } = require('aedes-server-factory')
+import { Aedes } from 'aedes'
+import { createServer } from 'aedes-server-factory'
 const port = 1883
 
+const aedes = await Aedes.createBroker()
 const server = createServer(aedes)
 
 server.listen(port, function () {
@@ -46,16 +50,18 @@ server.listen(port, function () {
 ## MQTT over TLS / MQTTS
 
 ```js
-const fs = require('fs')
-const aedes = require('aedes')()
+import { createServer } from 'node:tls'
+import { readFileSync } from 'node:fs'
+import { Aedes } from 'aedes'
+
 const port = 8883
 
 const options = {
-  key: fs.readFileSync('YOUR_PRIVATE_KEY_FILE.pem'),
-  cert: fs.readFileSync('YOUR_PUBLIC_CERT_FILE.pem')
+  key: readFileSync('YOUR_PRIVATE_KEY_FILE.pem'),
+  cert: readFileSync('YOUR_PUBLIC_CERT_FILE.pem')
 }
-
-const server = require('tls').createServer(options, aedes.handle)
+const aedes = await Aedes.createBroker()
+const server = createServer(options, aedes.handle)
 
 server.listen(port, function () {
   console.log('server started and listening on port ', port)
@@ -65,12 +71,22 @@ server.listen(port, function () {
 ## MQTT server over WebSocket
 
 ```js
-const aedes = require('aedes')()
-const httpServer = require('http').createServer()
-const ws = require('websocket-stream')
+import { createServer } from 'node:http'
+import { Aedes } from 'aedes'
+import { WebSocketServer, createWebSocketStream } from 'ws'
+
 const port = 8888
 
-ws.createServer({ server: httpServer }, aedes.handle)
+const aedes = await Aedes.createBroker()
+const httpServer = createServer()
+const wss = new WebSocketServer({
+  server:httpServer
+})
+
+wss.on('connection', (websocket, req) => {
+  const stream = createWebSocketStream(websocket)
+  aedes.handle(stream, req)
+})
 
 httpServer.listen(port, function () {
   console.log('websocket server listening on port ', port)
@@ -80,10 +96,11 @@ httpServer.listen(port, function () {
 ## MQTT server over WebSocket using server-factory
 
 ```js
-const aedes = require('aedes')()
-const { createServer } = require('aedes-server-factory')
+import { Aedes } from 'aedes'
+import { createServer } from 'aedes-server-factory'
 const port = 8888
 
+const aedes = await Aedes.createBroker()
 const httpServer = createServer(aedes, { ws: true })
 
 httpServer.listen(port, function () {

package/docs/MIGRATION.md

@@ -0,0 +1,50 @@
+# Migration
+
+## From 0.x to 1.x
+
+Version 1.x changes the persistence interface from callback to async/await.
+This also means that the startup of Aedes needs to be awaited to avoid race
+ conditions. 1.x also removed the default export to avoid mixups between old
+  and new behaviour.
+
+### ESM/Typescript
+
+If you previously had code that looks like:
+
+```js
+import aedes from 'aedes'
+const broker = aedes(opts)
+```
+
+You should replace it by:
+
+```js
+import { Aedes } from 'aedes'
+const broker = await Aedes.createBroker(opts)
+```
+
+### Commonjs
+
+If you previously had code that looks like:
+
+```js
+const aedes = require('aedes')
+const broker = aedes(opts)
+```
+
+You should replace it by:
+
+```js
+const { Aedes } = require('aedes')
+const broker = await Aedes.createBroker(opts)
+```
+
+Make sure that the persistence interface that you use is recent enough so that
+it supports the new async interface. Aedes will exit if it does not find an
+async persistence interface.
+The following versions are the minimum versions to use:
+
+- aedes-persistence: 10.2.2
+- aedes-persistence-level: 9.1.2
+- aedes-persistence-mongodb: 9.3.1
+- aedes-persistence-redis: 11.2.1

package/eslint.config.js

@@ -0,0 +1,8 @@
+import neostandard from 'neostandard'
+const ns = neostandard({ ts: true })
+for (const item of ns) {
+  if (item?.languageOptions?.ecmaVersion < 2025) {
+    item.languageOptions.ecmaVersion = 2025
+  }
+}
+export default ns

package/example.js

@@ -1,44 +1,55 @@
-'use strict'
+import net from 'node:net'
+import http from 'node:http'
+import { Aedes } from './aedes.js'
+import ws from 'ws'
 
-const aedes = require('./aedes')()
-const server = require('net').createServer(aedes.handle)
-const httpServer = require('http').createServer()
-const ws = require('websocket-stream')
 const port = 1883
 const wsPort = 8888
 
-server.listen(port, function () {
-  console.log('server listening on port', port)
-})
-
-ws.createServer({
-  server: httpServer
-}, aedes.handle)
-
-httpServer.listen(wsPort, function () {
-  console.log('websocket server listening on port', wsPort)
-})
-
-aedes.on('clientError', function (client, err) {
-  console.log('client error', client.id, err.message, err.stack)
-})
-
-aedes.on('connectionError', function (client, err) {
-  console.log('client error', client, err.message, err.stack)
-})
-
-aedes.on('publish', function (packet, client) {
-  if (client) {
-    console.log('message from client', client.id)
-  }
-})
-
-aedes.on('subscribe', function (subscriptions, client) {
-  if (client) {
-    console.log('subscribe from client', subscriptions, client.id)
-  }
-})
-
-aedes.on('client', function (client) {
-  console.log('new client', client.id)
-})
+async function startAedes () {
+  const aedes = await Aedes.createBroker()
+  const server = net.createServer(aedes.handle)
+  const httpServer = http.createServer()
+  server.listen(port, function () {
+    console.log('server listening on port', port)
+  })
+
+  const wss = new ws.WebSocketServer({
+    server: httpServer
+  })
+
+  wss.on('connection', (websocket, req) => {
+    const stream = ws.createWebSocketStream(websocket)
+    aedes.handle(stream, req)
+  })
+
+  httpServer.listen(wsPort, function () {
+    console.log('websocket server listening on port', wsPort)
+  })
+
+  aedes.on('clientError', function (client, err) {
+    console.log('client error', client.id, err.message, err.stack)
+  })
+
+  aedes.on('connectionError', function (client, err) {
+    console.log('client error', client, err.message, err.stack)
+  })
+
+  aedes.on('publish', function (packet, client) {
+    if (client) {
+      console.log('message from client', client.id)
+    }
+  })
+
+  aedes.on('subscribe', function (subscriptions, client) {
+    if (client) {
+      console.log('subscribe from client', subscriptions, client.id)
+    }
+  })
+
+  aedes.on('client', function (client) {
+    console.log('new client', client.id)
+  })
+}
+
+startAedes()

package/examples/clusters/index.js

@@ -1,29 +1,34 @@
-const cluster = require('cluster')
-const Aedes = require('aedes')
-const { createServer } = require('net')
-const { cpus } = require('os')
+import cluster from 'node:cluster'
+import { createServer } from 'node:net'
+import { cpus } from 'node:os'
+import { Aedes } from '../../aedes.js'
 const MONGO_URL = 'mongodb://127.0.0.1/aedes-clusters'
 
-const mq = process.env.MQ === 'redis'
-  ? require('mqemitter-redis')({
-    port: process.env.REDIS_PORT || 6379
-  })
-  : require('mqemitter-mongodb')({
-    url: MONGO_URL
-  })
-
-const persistence = process.env.PERSISTENCE === 'redis'
-  ? require('aedes-persistence-redis')({
-    port: process.env.REDIS_PORT || 6379
-  })
-  : require('aedes-persistence-mongodb')({
-    url: MONGO_URL
-  })
+async function importAndCall (mod, params) {
+  const imported = await import(mod)
+  return imported.default(params)
+}
 
-function startAedes () {
+async function startAedes () {
   const port = 1883
 
-  const aedes = Aedes({
+  const mq = process.env.MQ === 'redis'
+    ? await importAndCall('mqemitter-redis', {
+      port: process.env.REDIS_PORT || 6379
+    })
+    : await importAndCall('mqemitter-mongodb', {
+      url: MONGO_URL
+    })
+
+  const persistence = process.env.PERSISTENCE === 'redis'
+    ? await importAndCall('aedes-persistence-redis', {
+      port: process.env.REDIS_PORT || 6379
+    })
+    : await importAndCall('aedes-persistence-mongodb', {
+      url: MONGO_URL
+    })
+
+  const aedes = await Aedes.createBroker({
     id: 'BROKER_' + cluster.worker.id,
     mq,
     persistence
@@ -43,12 +48,12 @@ function startAedes () {
 
   aedes.on('subscribe', function (subscriptions, client) {
     console.log('MQTT client \x1b[32m' + (client ? client.id : client) +
-            '\x1b[0m subscribed to topics: ' + subscriptions.map(s => s.topic).join('\n'), 'from broker', aedes.id)
+      '\x1b[0m subscribed to topics: ' + subscriptions.map(s => s.topic).join('\n'), 'from broker', aedes.id)
   })
 
   aedes.on('unsubscribe', function (subscriptions, client) {
     console.log('MQTT client \x1b[32m' + (client ? client.id : client) +
-            '\x1b[0m unsubscribed to topics: ' + subscriptions.join('\n'), 'from broker', aedes.id)
+      '\x1b[0m unsubscribed to topics: ' + subscriptions.join('\n'), 'from broker', aedes.id)
   })
 
   // fired when a client connects

package/examples/clusters/package.json

@@ -2,17 +2,21 @@
   "name": "aedes_clusters",
   "version": "1.0.0",
   "description": "Testing Aedes Broker with clusters",
-  "main": "index.js",
+  "type": "module",
+  "exports": "./index.js",
+  "engines": {
+		"node": ">=20"
+	},
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "author": "robertsLando",
   "license": "MIT",
   "dependencies": {
-    "aedes": "^0.48.1",
-    "aedes-persistence-mongodb": "^9.1.0",
-    "aedes-persistence-redis": "^9.0.1",
-    "mqemitter-mongodb": "^8.1.0",
-    "mqemitter-redis": "^5.0.0"
+    "aedes": "^0.51.3",
+    "aedes-persistence-mongodb": "^9.3.1",
+    "aedes-persistence-redis": "^11.2.1",
+    "mqemitter-mongodb": "^9.0.1",
+    "mqemitter-redis": "^7.1.0"
   }
 }