Skip to main content

Sessions

An MQTT session holds a client's subscriptions and unacknowledged messages; a persistent one outlives the connection and resumes on reconnect.

A persistent session from the first CONNECT to its resumption after a lost connectionThis serviceMQTT serverCONNECT: client id,clean start false,session expiry, willCONNACKsession present: noPINGREQ when idlefor the keep-aliveThe connection is lost,no DISCONNECTThe server publishesthe last willIt keeps the session:subscriptions andunacknowledged messagesCONNECT again:the same client id,clean start falseCONNACKsession present: yesThe kept messagesare sent again
The diagram as text
  1. This service: CONNECT: client id, clean start false, session expiry, will; PINGREQ when idle for the keep-alive; CONNECT again: the same client id, clean start false
  2. MQTT server: CONNACK session present: no; The connection is lost, no DISCONNECT; The server publishes the last will; It keeps the session: subscriptions and unacknowledged messages; CONNACK session present: yes; The kept messages are sent again
  3. CONNECT: client id, clean start false, session expiry, will → CONNACK session present: no
  4. CONNACK session present: no → PINGREQ when idle for the keep-alive
  5. PINGREQ when idle for the keep-alive → The connection is lost, no DISCONNECT
  6. The connection is lost, no DISCONNECT → The server publishes the last will
  7. The server publishes the last will → It keeps the session: subscriptions and unacknowledged messages
  8. It keeps the session: subscriptions and unacknowledged messages → CONNECT again: the same client id, clean start false
  9. CONNECT again: the same client id, clean start false → CONNACK session present: yes
  10. CONNACK session present: yes → The kept messages are sent again

The client id names the session. MqttBroker::new takes it beside the URL, and a second connection with the same id takes the session over.

Two settings of the CONNECT decide whether the session outlives the connection. clean_start(false) asks the server to resume the session the client id already has. session_expiry says how long the server keeps it after the connection ends, in whole seconds. Without them a connection starts a clean session, which ends with the connection.

The CONNACK answers whether the server found the session. When it reports none, this crate subscribes every filter again. When the session is present, the subscriptions are still on the server, and the QoS 1 and QoS 2 messages that arrived while the service was away, or that it never acknowledged, come next. Those messages can arrive before the subscription they belong to has opened, so the crate holds up to 1024 of them until it does.

The keep-alive is the longest silence the connection allows. When nothing else travels, the client sends a PINGREQ, and the server ends a connection that stays silent for one and a half times the interval. rumqttc asks for 60 seconds unless keep_alive names another, and its minimum is 5 seconds.

The last will is a message the CONNECT leaves with the server. The server publishes it when the connection ends without a DISCONNECT: a crash, a lost network, a keep-alive that ran out. A shutdown sends the DISCONNECT, so a service that stops cleanly publishes no will.

Two more settings of the CONNECT bound what the server sends. The Receive Maximum is drawn on Quality of service. The Maximum Packet Size is the largest packet the client accepts, and the server discards a message larger than that for this client instead of sending it. This crate announces 1 MiB by default, and max_packet_size changes it. The CONNACK also says whether the server offers subscription identifiers, which Demultiplexing relies on.

The session is the protocol's own, from sections 3.1, 3.2 and 4.1 of the MQTT 5.0 standard. How this crate opens and closes it is on Lifecycle.