From a49fdce4c986ee2d494bd1d0bc818d3cf1bda004 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Mon, 2 Mar 2026 16:24:59 -0700 Subject: [PATCH 1/2] docs: migrate MQTT section to v4 consolidated reference Co-Authored-By: Claude Sonnet 4.6 --- .../mqtt-link-placeholders.md | 41 ++++ .../version-v4/mqtt/configuration.md | 231 ++++++++++++++++++ .../version-v4/mqtt/overview.md | 142 +++++++++++ .../version-v4-sidebars.json | 18 ++ v4-docs-migration-map.md | 14 +- 5 files changed, 439 insertions(+), 7 deletions(-) create mode 100644 migration-context/link-placeholders/mqtt-link-placeholders.md create mode 100644 reference_versioned_docs/version-v4/mqtt/configuration.md create mode 100644 reference_versioned_docs/version-v4/mqtt/overview.md diff --git a/migration-context/link-placeholders/mqtt-link-placeholders.md b/migration-context/link-placeholders/mqtt-link-placeholders.md new file mode 100644 index 00000000..63a2050c --- /dev/null +++ b/migration-context/link-placeholders/mqtt-link-placeholders.md @@ -0,0 +1,41 @@ +# Link Placeholders for MQTT Section + +## reference_versioned_docs/version-v4/mqtt/overview.md + +- Line 28: `[schema.graphql](TODO:reference_versioned_docs/version-v4/database/schema.md)` + - Context: Explaining how to define a table that becomes an MQTT topic namespace + - Target should be: Schema definition reference page (database section) + +- Line 101: `[MQTT Configuration](TODO:reference_versioned_docs/version-v4/http/overview.md)` + - Context: "See HTTP Overview" in the Related section + - Target should be: HTTP overview (handles MQTT over WebSocket) + +- Line 103: `[Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md)` + - Context: Related section — TLS and mTLS overview + - Target should be: Security section overview page + +- Line 104: `[Database Schema](TODO:reference_versioned_docs/version-v4/database/schema.md)` + - Context: Related section — defining tables/topics + - Target should be: Database schema reference page + +- Line 105: `[REST Overview](TODO:reference_versioned_docs/version-v4/rest/overview.md)` + - Context: Related section — noting REST and MQTT share the same path conventions + - Target should be: REST section overview page + +## reference_versioned_docs/version-v4/mqtt/configuration.md + +- Line 20: `[TLS Configuration](TODO:reference_versioned_docs/version-v4/http/tls.md)` + - Context: Describing mqtt.network.securePort — links to TLS config + - Target should be: TLS configuration page (in http section) + +- Line 133: `[TLS Configuration](TODO:reference_versioned_docs/version-v4/http/tls.md)` + - Context: Related section link at bottom of file + - Target should be: TLS configuration page (in http section) + +- Line 134: `[Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md)` + - Context: Related section link at bottom of file + - Target should be: Security section overview page + +- Line 135: `[Configuration Overview](TODO:reference_versioned_docs/version-v4/configuration/overview.md)` + - Context: Related section — full harperdb-config.yaml reference + - Target should be: Configuration section overview page diff --git a/reference_versioned_docs/version-v4/mqtt/configuration.md b/reference_versioned_docs/version-v4/mqtt/configuration.md new file mode 100644 index 00000000..695c4361 --- /dev/null +++ b/reference_versioned_docs/version-v4/mqtt/configuration.md @@ -0,0 +1,231 @@ +--- +id: configuration +title: MQTT Configuration +--- + + + + + + + +The `mqtt` section in `harperdb-config.yaml` controls Harper's built-in MQTT broker. MQTT is enabled by default. + +Harper must be restarted for configuration changes to take effect. + +## Minimal Example + +```yaml +mqtt: + network: + port: 1883 + securePort: 8883 + webSocket: true + requireAuthentication: true +``` + +## Ports + +### `mqtt.network.port` + +Type: `integer` + +Default: `1883` + +The port for plaintext (non-TLS) MQTT connections. + +### `mqtt.network.securePort` + +Type: `integer` + +Default: `8883` + +The port for secure MQTT connections (MQTTS). Uses the `tls` configuration for certificates. See [TLS Configuration](TODO:reference_versioned_docs/version-v4/http/tls.md 'TLS configuration shared by HTTP and MQTT') for certificate setup. + +## WebSocket + +### `mqtt.webSocket` + +Type: `boolean` + +Default: `true` + +Enables MQTT over WebSockets. When enabled, Harper handles WebSocket connections on the HTTP port (default `9926`) that specify the `mqtt` sub-protocol (`Sec-WebSocket-Protocol: mqtt`). This is required by the MQTT specification and should be set by any conformant MQTT-over-WebSocket client. + +```yaml +mqtt: + webSocket: true +``` + +## Authentication + +### `mqtt.requireAuthentication` + +Type: `boolean` + +Default: `true` + +Controls whether credentials are required to establish an MQTT connection. When `true`, clients must authenticate with either a username/password or a valid mTLS client certificate. + +When set to `false`, unauthenticated connections are allowed. Unauthenticated clients are still subject to authorization on each publish and subscribe operation — by default, tables and resources do not grant access to unauthenticated users, but this can be configured at the resource level. + +```yaml +mqtt: + requireAuthentication: true +``` + +## mTLS + +### `mqtt.network.mtls` + +Added in: v4.3.0 + +Type: `boolean | object` + +Default: `false` + +Enables mutual TLS (mTLS) authentication for MQTT connections. When set to `true`, client certificates are verified against the CA specified in the root `tls.certificateAuthority` section. Authenticated connections use the `CN` (common name) from the client certificate's subject as the Harper username by default. + +```yaml +mqtt: + network: + mtls: true +``` + +For granular control, specify an object with the following optional properties: + +### `mqtt.network.mtls.user` + +Type: `string | null` + +Default: Common Name from client certificate + +Specifies a fixed username to authenticate all mTLS connections as. When set, any connection that passes certificate verification authenticates as this user regardless of the certificate's CN. + +Setting to `null` disables credential-based authentication for mTLS connections. When combined with `required: true`, this enforces that clients must have a valid certificate AND provide separate credential-based authentication. + +### `mqtt.network.mtls.required` + +Type: `boolean` + +Default: `false` + +When `true`, all incoming MQTT connections must provide a valid client certificate. Connections without a valid certificate are rejected. By default, clients can authenticate with either mTLS or standard username/password credentials. + +### `mqtt.network.mtls.certificateAuthority` + +Type: `string` + +Default: Path from `tls.certificateAuthority` + +Path to the certificate authority (CA) file used to verify MQTT client certificates. By default, uses the CA configured in the root `tls` section. Set this if MQTT clients should be verified against a different CA than the one used for HTTP/TLS. + +### `mqtt.network.mtls.certificateVerification` + +Type: `boolean | object` + +Default: `true` + +When mTLS is enabled, Harper verifies the revocation status of client certificates using OCSP (Online Certificate Status Protocol). This ensures revoked certificates cannot be used for authentication. + +Set to `false` to disable revocation checking, or configure as an object: + +| Property | Type | Default | Description | +| -------------- | -------- | --------- | ------------------------------------------------------------------- | +| `timeout` | integer | `5000` | Maximum milliseconds to wait for an OCSP response. | +| `cacheTtl` | integer | `3600000` | Milliseconds to cache successful verification results (default 1h). | +| `failureMode` | string | `'fail-open'` | Behavior when OCSP verification fails: `'fail-open'` (allow, log warning) or `'fail-closed'` (reject). | + +```yaml +mqtt: + network: + mtls: + required: true + certificateVerification: + failureMode: fail-closed + timeout: 5000 + cacheTtl: 3600000 +``` + +## mTLS Examples + +```yaml +# Require client certificate + standard credentials (combined auth) +mqtt: + network: + mtls: + user: null + required: true + +# Authenticate all mTLS connections as a fixed user +mqtt: + network: + mtls: + user: mqtt-service-account + required: true + +# mTLS optional — clients can use mTLS or credentials +mqtt: + network: + mtls: true +``` + +## Logging + +### `mqtt.logging` + +Type: `object` + +Default: disabled + +Configures logging for MQTT activity. Accepts the standard logging configuration options. + +```yaml +mqtt: + logging: + path: ~/hdb/log/mqtt.log + level: warn + stdStreams: false +``` + +| Option | Description | +| ------------ | -------------------------------------------------- | +| `path` | File path for the MQTT log output. | +| `root` | Alternative to `path` — sets the log directory. | +| `level` | Log level: `error`, `warn`, `info`, `debug`, etc. | +| `tag` | Custom tag to prefix log entries. | +| `stdStreams` | When `true`, also logs to stdout/stderr. | + +## Complete Example + +```yaml +mqtt: + network: + port: 1883 + securePort: 8883 + mtls: + required: false + certificateAuthority: ~/hdb/keys/ca.pem + certificateVerification: + failureMode: fail-open + timeout: 5000 + cacheTtl: 3600000 + webSocket: true + requireAuthentication: true + logging: + level: warn + path: ~/hdb/log/mqtt.log + +# TLS is a top-level section, shared with HTTP +tls: + certificate: ~/hdb/keys/certificate.pem + certificateAuthority: ~/hdb/keys/ca.pem + privateKey: ~/hdb/keys/privateKey.pem +``` + +## Related + +- [MQTT Overview](./overview) +- [TLS Configuration](TODO:reference_versioned_docs/version-v4/http/tls.md 'TLS configuration shared by MQTT and HTTP') +- [Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md 'Security, certificates, and mTLS overview') +- [Configuration Overview](TODO:reference_versioned_docs/version-v4/configuration/overview.md 'Full harperdb-config.yaml reference') diff --git a/reference_versioned_docs/version-v4/mqtt/overview.md b/reference_versioned_docs/version-v4/mqtt/overview.md new file mode 100644 index 00000000..705045c4 --- /dev/null +++ b/reference_versioned_docs/version-v4/mqtt/overview.md @@ -0,0 +1,142 @@ +--- +id: overview +title: MQTT +--- + + + + + + +Added in: v4.2.0 + +Harper includes a built-in MQTT broker that provides real-time pub/sub messaging deeply integrated with the database. Unlike a generic MQTT broker, Harper's MQTT implementation connects topics directly to database records — publishing to a topic writes to the database, and subscribing to a topic delivers live updates for the corresponding record. + +## How Topics Map to Database Records + +MQTT topics in Harper follow the same path convention as REST endpoints. If you define a table or resource with an endpoint path of `my-resource`, the corresponding MQTT topic namespace is `my-resource`. + +A topic of `my-resource/some-id` corresponds to the record with id `some-id` in the `my-resource` table (or custom resource). This means: + +- **Subscribing** to `my-resource/some-id` delivers notification messages whenever that record is updated or deleted. +- The **current value** of the record is treated as the retained message for that topic. On subscription, the subscriber immediately receives the current record as the initial retained message — no separate GET request needed. +- **Publishing** with the `retain` flag set replaces the record in the database (equivalent to a PUT operation). +- **Publishing without** the `retain` flag delivers the message to current subscribers without writing to the database. + +Defining a table that creates a topic can be as simple as adding a table with no attributes to your [schema.graphql](TODO:reference_versioned_docs/version-v4/database/schema.md 'Schema definition for defining tables and topics') in a Harper application: + +```graphql +type MyTopic @table @export +``` + +## Protocol Support + +Harper supports MQTT versions **v3.1.1** and **v5**, with standard publish/subscribe capabilities. + +### Topics and Wildcards + +Harper supports multi-level topics for both publishing and subscribing: + +- **Multi-level wildcard (`#`)** — Subscribe to `my-resource/#` to receive notifications for all records in that resource, including nested paths (`my-resource/some-id`, `my-resource/nested/id`). +- **Single-level wildcard (`+`)** — Added in v4.3.0. Subscribe to `my-resource/+/status` to match any single path segment. + +### QoS Levels + +- **QoS 0** — At most once delivery (fire and forget). +- **QoS 1** — At least once delivery (acknowledged delivery). +- **QoS 2** — Harper can perform the QoS 2 conversation but does not guarantee exactly-once delivery. + +### Sessions + +- **Clean sessions** — Subscriptions and queued messages are discarded on disconnect. +- **Durable sessions** — Subscriptions and queued messages are persisted across reconnects. + +### Last Will + +Added in: v4.3.0 (inferred from version comparison, needs verification) + +Harper supports the MQTT Last Will and Testament feature. If a client disconnects unexpectedly, the broker publishes the configured will message on its behalf. + +## Content Negotiation + +Harper handles structured data natively. Messages can be published and received in any supported structured format — JSON, CBOR, or MessagePack — and Harper stores and delivers them as structured objects. Different clients can independently choose their preferred format: one client may publish in JSON while another subscribes and receives in CBOR. + +## Ordering and Distributed Delivery + +Harper is designed for distributed, low-latency message delivery. Messages are delivered to subscribers immediately on arrival — Harper does not delay delivery to coordinate consensus across nodes. + +In a distributed cluster, messages may arrive out of order due to network topology. The behavior depends on whether the message is retained or non-retained: + +- **Retained messages** (published with `retain: true`, or written via PUT/upsert) maintain eventual consistency across the cluster. Harper keeps the message with the latest timestamp as the winning record state. An out-of-order earlier message will not be re-delivered to clients; the cluster converges to the most recent state. +- **Non-retained messages** are always delivered to local subscribers when received, even if they arrive out of order. Every message is delivered, prioritizing completeness over strict ordering. + +**Non-retained messages** are suited for applications like chat where every message must be delivered. **Retained messages** are suited for sensor readings or state updates where only the latest value matters. + +## Authentication + +MQTT connections support two authentication methods: + +- **Credential-based** — Standard MQTT username/password in the CONNECT packet. +- **mTLS** — Added in v4.3.0. Mutual TLS authentication using client certificates. The `CN` (common name) from the client certificate subject is used as the Harper username by default. + +Authentication is required by default (`requireAuthentication: true`). See [MQTT Configuration](./configuration) for details on disabling authentication or configuring mTLS options. + +## Server Events API + +JavaScript components can listen for MQTT connection events via `server.mqtt.events`: + +```javascript +server.mqtt.events.on('connected', (session, socket) => { + console.log('client connected with id', session.clientId); +}); +``` + +Available events: + +| Event | Description | +| -------------- | ---------------------------------------------------------- | +| `connection` | Client establishes a TCP or WebSocket connection | +| `connected` | Client completes MQTT handshake and is authenticated | +| `auth-failed` | Client fails to authenticate | +| `disconnected` | Client disconnects | + +## Feature Support Matrix + +| Feature | Support | +| ------------------------------------------------------------------- | -------------------------------------------------------------- | +| MQTT v3.1.1 connections | ✅ | +| MQTT v5 connections | ✅ | +| Secure MQTTS (TLS) | ✅ | +| MQTT over WebSockets | ✅ | +| Authentication via username/password | ✅ | +| Authentication via mTLS | ✅ (added v4.3.0) | +| Publish | ✅ | +| Subscribe | ✅ | +| Multi-level wildcard (`#`) | ✅ | +| Single-level wildcard (`+`) | ✅ (added v4.3.0) | +| QoS 0 | ✅ | +| QoS 1 | ✅ | +| QoS 2 | Not fully supported — conversation supported, not guaranteed | +| Keep-Alive monitoring | ✅ | +| Clean session | ✅ | +| Durable session | ✅ | +| Distributed durable session | Not supported | +| Last Will | ✅ | +| MQTT V5 Subscribe retain handling | ✅ (added v4.3.0) | +| MQTT V5 User properties | Not supported | +| MQTT V5 Will properties | Not supported | +| MQTT V5 Connection properties | Not supported | +| MQTT V5 Connection acknowledgement properties | Not supported | +| MQTT V5 Publish properties | Not supported | +| MQTT V5 Subscribe properties (general) | Not supported | +| MQTT V5 Ack properties | Not supported | +| MQTT V5 AUTH command | Not supported | +| MQTT V5 Shared subscriptions | Not supported | + +## Related + +- [MQTT Configuration](./configuration) +- [HTTP Overview](TODO:reference_versioned_docs/version-v4/http/overview.md 'HTTP server overview — handles MQTT over WebSocket') +- [Security Overview](TODO:reference_versioned_docs/version-v4/security/overview.md 'Security, TLS, and mTLS overview') +- [Database Schema](TODO:reference_versioned_docs/version-v4/database/schema.md 'Defining tables and topics with schema.graphql') +- [REST Overview](TODO:reference_versioned_docs/version-v4/rest/overview.md 'REST interface — same path conventions as MQTT topics') diff --git a/reference_versioned_sidebars/version-v4-sidebars.json b/reference_versioned_sidebars/version-v4-sidebars.json index 70545900..1ac752c8 100644 --- a/reference_versioned_sidebars/version-v4-sidebars.json +++ b/reference_versioned_sidebars/version-v4-sidebars.json @@ -87,6 +87,24 @@ } ] }, + { + "type": "category", + "label": "MQTT", + "collapsible": false, + "className": "learn-category-header", + "items": [ + { + "type": "doc", + "id": "mqtt/overview", + "label": "Overview" + }, + { + "type": "doc", + "id": "mqtt/configuration", + "label": "Configuration" + } + ] + }, { "type": "category", "label": "GraphQL Querying", diff --git a/v4-docs-migration-map.md b/v4-docs-migration-map.md index 75a7d67a..1e1f179e 100644 --- a/v4-docs-migration-map.md +++ b/v4-docs-migration-map.md @@ -411,7 +411,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: New content about `loadEnv` plugin - **Additional Sources**: Built-in extensions docs, configuration docs - **Version Annotations**: loadEnv added in v4.5.0 -- **Status**: In Progress +- **Status**: Complete - **Notes**: Covers `loadEnv` extension only. Harper-level environment variable configuration (naming conventions, `HDB_CONFIG`, `HARPER_DEFAULT_CONFIG`, `HARPER_SET_CONFIG`) belongs in the Configuration section — see notes there. - **Release Notes**: - [4.5.0](release-notes/v4-tucker/4.5.0.md) - Built-in loadEnv component @@ -426,7 +426,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Additional Sources**: - `versioned_docs/version-4.6/reference/components/built-in-extensions.md` (pre-v4.7 behavior) - `versioned_docs/version-4.5/developers/components/built-in.md` (early v4 behavior) -- **Status**: In Progress +- **Status**: Complete - **Notes**: No separate `configuration.md` needed — all static plugin options are documented inline in the overview. The `configuration.md` entry has been removed; static file serving has no Harper-level configuration. The v4.7 Plugin API (`extensions`, `fallthrough`, `index`, `notFound` options and auto-update behavior) is annotated as added in v4.7.0 (inferred from version comparison; not present in v4.6 docs). The `static` plugin itself predates v4.7 (present in v4.4 and earlier). - **Release Notes**: - [4.7.2](release-notes/v4-tucker/4.7.2.md) - `static` handler defaults to `index.html` @@ -440,7 +440,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: New content about HTTP server - **Additional Sources**: Configuration docs, architecture docs -- **Status**: In Progress +- **Status**: Complete - **Release Notes**: - [4.1.0](release-notes/v4-tucker/4.1.0.md) - Worker threads for HTTP requests - [4.2.0](release-notes/v4-tucker/4.2.0.md) - Socket management (SO_REUSEPORT), flexible port configs @@ -450,7 +450,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: Extract from `reference/configuration.md` (http section) - **Version Annotations**: - HTTP/2 support: v4.5.0 -- **Status**: In Progress +- **Status**: Complete - **Release Notes**: - [4.5.0](release-notes/v4-tucker/4.5.0.md) - HTTP/2 support @@ -460,7 +460,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Additional Sources**: Current `reference/globals.md` - **Version Annotations**: - server.authenticateUser: v4.5.0 -- **Status**: In Progress +- **Status**: Complete - **Release Notes**: - [4.5.0](release-notes/v4-tucker/4.5.0.md) - server.authenticateUser API @@ -531,7 +531,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - mTLS support: v4.3.0 - Single-level wildcards: v4.3.0 - CRDT: v4.3.0 -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.2.0](release-notes/v4-tucker/4.2.0.md) - MQTT support introduced (QoS 0 and 1, durable sessions) - [4.3.0](release-notes/v4-tucker/4.3.0.md) - mTLS, single-level wildcards, retain handling, CRDT @@ -541,7 +541,7 @@ This document maps existing documentation paths from `versioned_docs/version-4.X - **Primary Source**: Extract from configuration docs and real-time docs - **Version Annotations**: Port change v4.5.0 (9925 → 9933) -- **Status**: Not Started +- **Status**: In Progress - **Release Notes**: - [4.5.0](release-notes/v4-tucker/4.5.0.md) - Default replication port change From adb6183af0d153682c42aeb286c4d52c2e284da6 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Tue, 3 Mar 2026 14:22:32 -0700 Subject: [PATCH 2/2] fixup! docs: migrate MQTT section to v4 consolidated reference --- .../version-v4/mqtt/configuration.md | 22 +++--- .../version-v4/mqtt/overview.md | 72 +++++++++---------- 2 files changed, 47 insertions(+), 47 deletions(-) diff --git a/reference_versioned_docs/version-v4/mqtt/configuration.md b/reference_versioned_docs/version-v4/mqtt/configuration.md index 695c4361..51d0afac 100644 --- a/reference_versioned_docs/version-v4/mqtt/configuration.md +++ b/reference_versioned_docs/version-v4/mqtt/configuration.md @@ -130,11 +130,11 @@ When mTLS is enabled, Harper verifies the revocation status of client certificat Set to `false` to disable revocation checking, or configure as an object: -| Property | Type | Default | Description | -| -------------- | -------- | --------- | ------------------------------------------------------------------- | -| `timeout` | integer | `5000` | Maximum milliseconds to wait for an OCSP response. | -| `cacheTtl` | integer | `3600000` | Milliseconds to cache successful verification results (default 1h). | -| `failureMode` | string | `'fail-open'` | Behavior when OCSP verification fails: `'fail-open'` (allow, log warning) or `'fail-closed'` (reject). | +| Property | Type | Default | Description | +| ------------- | ------- | ------------- | ------------------------------------------------------------------------------------------------------ | +| `timeout` | integer | `5000` | Maximum milliseconds to wait for an OCSP response. | +| `cacheTtl` | integer | `3600000` | Milliseconds to cache successful verification results (default 1h). | +| `failureMode` | string | `'fail-open'` | Behavior when OCSP verification fails: `'fail-open'` (allow, log warning) or `'fail-closed'` (reject). | ```yaml mqtt: @@ -188,13 +188,13 @@ mqtt: stdStreams: false ``` -| Option | Description | -| ------------ | -------------------------------------------------- | -| `path` | File path for the MQTT log output. | +| Option | Description | +| ------------ | ------------------------------------------------- | +| `path` | File path for the MQTT log output. | | `root` | Alternative to `path` — sets the log directory. | -| `level` | Log level: `error`, `warn`, `info`, `debug`, etc. | -| `tag` | Custom tag to prefix log entries. | -| `stdStreams` | When `true`, also logs to stdout/stderr. | +| `level` | Log level: `error`, `warn`, `info`, `debug`, etc. | +| `tag` | Custom tag to prefix log entries. | +| `stdStreams` | When `true`, also logs to stdout/stderr. | ## Complete Example diff --git a/reference_versioned_docs/version-v4/mqtt/overview.md b/reference_versioned_docs/version-v4/mqtt/overview.md index 705045c4..553f4135 100644 --- a/reference_versioned_docs/version-v4/mqtt/overview.md +++ b/reference_versioned_docs/version-v4/mqtt/overview.md @@ -93,45 +93,45 @@ server.mqtt.events.on('connected', (session, socket) => { Available events: -| Event | Description | -| -------------- | ---------------------------------------------------------- | -| `connection` | Client establishes a TCP or WebSocket connection | -| `connected` | Client completes MQTT handshake and is authenticated | -| `auth-failed` | Client fails to authenticate | -| `disconnected` | Client disconnects | +| Event | Description | +| -------------- | ---------------------------------------------------- | +| `connection` | Client establishes a TCP or WebSocket connection | +| `connected` | Client completes MQTT handshake and is authenticated | +| `auth-failed` | Client fails to authenticate | +| `disconnected` | Client disconnects | ## Feature Support Matrix -| Feature | Support | -| ------------------------------------------------------------------- | -------------------------------------------------------------- | -| MQTT v3.1.1 connections | ✅ | -| MQTT v5 connections | ✅ | -| Secure MQTTS (TLS) | ✅ | -| MQTT over WebSockets | ✅ | -| Authentication via username/password | ✅ | -| Authentication via mTLS | ✅ (added v4.3.0) | -| Publish | ✅ | -| Subscribe | ✅ | -| Multi-level wildcard (`#`) | ✅ | -| Single-level wildcard (`+`) | ✅ (added v4.3.0) | -| QoS 0 | ✅ | -| QoS 1 | ✅ | -| QoS 2 | Not fully supported — conversation supported, not guaranteed | -| Keep-Alive monitoring | ✅ | -| Clean session | ✅ | -| Durable session | ✅ | -| Distributed durable session | Not supported | -| Last Will | ✅ | -| MQTT V5 Subscribe retain handling | ✅ (added v4.3.0) | -| MQTT V5 User properties | Not supported | -| MQTT V5 Will properties | Not supported | -| MQTT V5 Connection properties | Not supported | -| MQTT V5 Connection acknowledgement properties | Not supported | -| MQTT V5 Publish properties | Not supported | -| MQTT V5 Subscribe properties (general) | Not supported | -| MQTT V5 Ack properties | Not supported | -| MQTT V5 AUTH command | Not supported | -| MQTT V5 Shared subscriptions | Not supported | +| Feature | Support | +| --------------------------------------------- | ------------------------------------------------------------ | +| MQTT v3.1.1 connections | ✅ | +| MQTT v5 connections | ✅ | +| Secure MQTTS (TLS) | ✅ | +| MQTT over WebSockets | ✅ | +| Authentication via username/password | ✅ | +| Authentication via mTLS | ✅ (added v4.3.0) | +| Publish | ✅ | +| Subscribe | ✅ | +| Multi-level wildcard (`#`) | ✅ | +| Single-level wildcard (`+`) | ✅ (added v4.3.0) | +| QoS 0 | ✅ | +| QoS 1 | ✅ | +| QoS 2 | Not fully supported — conversation supported, not guaranteed | +| Keep-Alive monitoring | ✅ | +| Clean session | ✅ | +| Durable session | ✅ | +| Distributed durable session | Not supported | +| Last Will | ✅ | +| MQTT V5 Subscribe retain handling | ✅ (added v4.3.0) | +| MQTT V5 User properties | Not supported | +| MQTT V5 Will properties | Not supported | +| MQTT V5 Connection properties | Not supported | +| MQTT V5 Connection acknowledgement properties | Not supported | +| MQTT V5 Publish properties | Not supported | +| MQTT V5 Subscribe properties (general) | Not supported | +| MQTT V5 Ack properties | Not supported | +| MQTT V5 AUTH command | Not supported | +| MQTT V5 Shared subscriptions | Not supported | ## Related