Passerelle MQTT

bext agit comme un courtier de passerelle MQTT 5 : les appareils IoT se connectent via MQTT standard et les messages sont acheminés vers le système de plugins et l'infrastructure pub/sub de bext. bext n’est pas un courtier à persistance totale ; il relie le trafic MQTT à la logique de votre application.

Activation de MQTT#

Ajoutez une section [mqtt] à bext.config.toml :

toml

[mqtt]
enabled = true
bind = "0.0.0.0:1883"
tls_bind = "0.0.0.0:8883"
max_connections = 10000
max_packet_size_bytes = 65536

Compilez avec l'indicateur de fonctionnalité mqtt :

bash

bext build --features mqtt

Ports d'écoute#

MQTT s'exécute sur ses propres écouteurs TCP, distincts du port HTTP :

Port	Protocole	Description
1883	MQTT	TCP simple (utilisation LAN/dev).
8883	MQTTS	Chiffré en TLS (production).

TLS utilise le même certificat configuré dans la section [tls] du site.

Modèle de passerelle#

bext est une passerelle, et non un courtier autonome. Cela signifie:

Les publications MQTT entrantes sont transmises aux plugins bext et au serveur interne. pub/sous-bus.
Les plugins peuvent s'abonner aux sujets MQTT et react aux messages.
Il n’existe pas de persistance intégrée des messages sauvegardés sur disque. Des messages qui qui ne peuvent pas être livrés sont supprimés après les nouvelles tentatives de QoS.

code

  IoT Device ──mqtt──▶ bext ──▶ Plugin handler
                         │
                         └──▶ PubSub bus (SSE, WebSocket subscribers)

Fonctionnalités MQTT 5#

bext implémente le protocole MQTT 5.0 (RFC 9431) :

Qualité de service#

Niveau de qualité de service	Garantie	Cas d'utilisation
0	Au plus une fois (tirer et oublier)	Télémétrie du capteur.
1	Au moins une fois (ack requis)	Commandes, alertes.
2	Exactement une fois (poignée de main en 4 étapes)	Facturation, changements d'état.

Séances#

Clean Start — le client démarre à nouveau, sans état stocké.
Session persistante — bext stocke les abonnements et la QoS en attente 1/2 messages pour l’intervalle d’expiration de la session.

toml

[mqtt]
session_expiry_secs = 3600   # 1 hour default

Caractères génériques de sujet#

Les abonnements génériques MQTT standard sont pris en charge :

Caractère générique	Exemple	Matchs
`+`	`sensors/+/temp`	`sensors/room1/temp`, etc.
`#`	`sensors/#`	Tout sous `sensors/`.

Authentification#

Les clients MQTT s'authentifient via le modèle de jeton dans le nom d'utilisateur. Le client envoie un jeton Bearer en tant que nom d'utilisateur MQTT et bext le valide via la même fonctionnalité d'authentification utilisée pour HTTP :

code

Username: Bearer eyJhbGciOi...
Password: (empty or ignored)

Vous pouvez également utiliser l'authentification par certificat client sur MQTTS pour les flottes d'appareils où la gestion des jetons n'est pas pratique.

toml

[mqtt.auth]
mode = "token"        # "token" | "cert" | "none"

Pont de publication HTTP#

Publiez des messages MQTT à partir de n'importe quel client HTTP via le point de terminaison du pont intégré :

code

POST /__bext/mqtt/publish
Content-Type: application/json

{
  "topic": "sensors/room1/temp",
  "payload": "22.5",
  "qos": 1,
  "retain": false
}

Ceci est utile pour les services backend qui ne disposent pas de bibliothèque client MQTT ou pour déclencher des commandes de périphérique à partir d'un tableau de bord Web.

Intégration de plugins#

Les plugins peuvent s'abonner aux sujets MQTT et publier des messages :

rust

use bext::mqtt::{MqttBus, MqttMessage};

async fn on_mqtt_message(msg: MqttMessage, bus: &MqttBus) {
    println!("topic={} payload={}", msg.topic, msg.payload_str());

    // Publish a response
    bus.publish("devices/ack", b"ok", QoS::AtLeastOnce).await?;
}

Enregistrez l'abonnement dans le manifeste du plugin :

toml

[plugin]
name = "sensor-handler"

[[plugin.mqtt_subscriptions]]
topic = "sensors/+/temp"
qos = 1

Messages conservés#

Lorsque retain = true, bext stocke le dernier message par sujet en mémoire. Les nouveaux abonnés reçoivent immédiatement le message retenu pour les sujets correspondants. Il s'agit du comportement MQTT standard pour les modèles de « dernière valeur connue ».

Messages de testament#

Les clients peuvent définir un dernier testament (LWT) lors de la connexion. Si le client se déconnecte de manière inappropriée, bext publie le message testamentaire dans le sujet spécifié :

code

Will Topic: devices/sensor-42/status
Will Payload: offline
Will QoS: 1
Will Retain: true

Métrique#

Métrique	Description
`mqtt_connections_active`	Connexions client MQTT actuelles.
`mqtt_messages_received_total`	Messages reçus des clients.
`mqtt_messages_sent_total`	Messages envoyés aux clients.
`mqtt_subscriptions_active`	Abonnements à des sujets actifs.

Indicateur de fonctionnalité#

MQTT nécessite l'indicateur de fonctionnalité mqtt :

bash

bext build --features mqtt

Sans cet indicateur, la section de configuration [mqtt] est ignorée.

Attention

bext est une passerelle, pas un courtier de persistance. Les messages qui ne peuvent pas être transmis dans les limites des nouvelles tentatives de QoS sont supprimés : il n'y a pas de file d'attente durable derrière eux. Pour les charges de travail qui nécessitent une livraison garantie lors des redémarrages du courtier, établissez un lien vers un courtier externe (Mosquitto, EMQX, etc.) à partir d'un plug-in plutôt que de compter sur le magasin de sessions en mémoire de bext.

Conseil

Le port 1883 (TCP simple) convient uniquement à une utilisation LAN ou de développement. En production, utilisez le port 8883 (MQTTS) et le mode d'authentification cert afin que les informations d'identification de l'appareil ne soient pas transmises en texte brut.

En rapport#

Aperçu des plugins — comment enregistrer les gestionnaires d'abonnement MQTT dans un plugin
Événements envoyés par le serveur — Alternative HTTP Push pour les utilisateurs de navigateur du même bus pub/sub
WebSockets — alternative HTTP bidirectionnelle pour les clients Web qui ne peuvent pas utiliser MQTT natif
Capacité d'authentification — authentification du jeton et du certificat connectés à l'écouteur MQTT
Aperçu des capacités — liste complète des fonctionnalités d'exécution de bext

Links#

mqtt.org — site officiel du projet MQTT
Spécification OASIS MQTT version 5.0 — la norme MQTT 5 bext implémente