Aedes Server Factory

0.2.1 verified Tue Apr 21 auth: no javascript

aedes-server-factory is a utility library designed to simplify the creation and configuration of various server types for the Aedes MQTT broker. It currently supports TCP, HTTP, HTTP2, WebSockets (WS), and PROXY decoders, with ongoing work for TLS, HTTPS, and WSS. The latest stable version is 0.2.1, with releases happening infrequently, often driven by bug fixes or minor feature enhancements related to server handling. Its primary differentiator is providing a consolidated API to instantiate and bind Aedes to different network protocols and server technologies, abstracting away the boilerplate involved in connecting an MQTT broker to diverse client interfaces. It offers flexible options for secure connections and proxy support.

Common errors

error TypeError: aedes.handle is not a function ↓

cause Attempting to call `aedes.handle` directly on an object that is not a proper Aedes instance or has not been correctly initialized.

fix

Ensure aedes is correctly initialized via const aedes = require('aedes')() or import Aedes from 'aedes'; const aedes = Aedes(); before passing it to createServer.

error Error: listen EADDRINUSE: address already in use :::1883 ↓

cause Another process is already using the specified port, preventing the server from starting.

fix

Change the port number to an available one, or identify and terminate the process currently occupying the port (e.g., lsof -i :1883 on macOS/Linux or netstat -ano | findstr :1883 on Windows).

error Error: WebSocket connection to 'ws://localhost:8080/' failed: Error during WebSocket handshake: Unexpected response code: 400 ↓

cause The underlying HTTP server is running, but the WebSocket upgrade request failed, possibly because `ws: true` was not set, or there's an issue with the `ws` package.

fix

Verify that ws: true is correctly passed in the options to createServer and that the ws package is installed (npm install ws). Also, check your client-side WebSocket URL and protocol for correctness.

Warnings

breaking Version 0.2.0 included a fix for an infinite loop issue (#8) which was subsequently reverted in 0.2.0 itself (#10) due to unintended side effects. Users who relied on the fix in interim builds might find the behavior reverted, and should carefully test error handling, especially for WS servers. ↓

fix Review your WebSocket error handling. The `customWSErrorHandler` option can be used to provide specific error management. Monitor for new releases addressing this comprehensively.

gotcha When using `ws: true`, `createServer` returns the underlying HTTP/HTTP2/HTTPS server instance, not the WebSocket server directly. Methods like `.close()` should be called on this returned instance. ↓

fix Ensure you are interacting with the correct server instance returned by `createServer`. For WebSocket setups, the returned object is the HTTP server providing the WebSocket upgrade path.

gotcha TLS/HTTPS/HTTP2/WSS support is marked as 'Work In Progress' in the README. While options exist, they might not be fully stable or production-ready as of version 0.2.1. ↓

fix Thoroughly test TLS/HTTPS/HTTP2/WSS configurations in non-production environments. Check the latest GitHub issues and pull requests for status updates and potential workarounds or recommended alternative approaches for production deployments.

Install

npm install aedes-server-factory

yarn add aedes-server-factory

pnpm add aedes-server-factory

Imports

createServer
wrong
```
const { createServer } = require('aedes-server-factory');
```
correct
```
import { createServer } from 'aedes-server-factory';
```
While CommonJS `require` still works for Node.js, `import` is preferred for modern TypeScript/ESM projects.
Aedes
wrong
```
import { Aedes } from 'aedes';
```
correct
```
import Aedes from 'aedes';
```
Aedes is a default export, not a named export.

Quickstart

Demonstrates creating both a default TCP MQTT server and a WebSocket server using an underlying HTTP server with aedes-server-factory.

import Aedes from 'aedes';
import { createServer } from 'aedes-server-factory';
import { createServer as createHttpServer } from 'http';

const aedes = Aedes();

// Create a basic TCP MQTT server
const tcpServer = createServer(aedes);
tcpServer.listen(1883, () => {
  console.log('Aedes TCP server listening on port 1883');
});

// Create an HTTP server and bind it for WebSockets
const httpServer = createHttpServer();
const wsServer = createServer(aedes, { ws: true, http: httpServer });

httpServer.listen(8080, () => {
  console.log('Aedes HTTP/WS server listening on port 8080');
});

// Handle cleanup on process exit
process.on('SIGTERM', () => {
  console.log('Shutting down Aedes servers...');
  tcpServer.close(() => console.log('TCP server closed.'));
  wsServer.close(() => console.log('HTTP/WS server closed.'));
  aedes.close(() => console.log('Aedes broker closed.'));
});