Connection Lifecycle
Handle CONNECT, CONNACK, heartbeat, close, and recovery against the current Gateway implementation.
Establish a connection
Transport open
-> CONNECT (sole first packet)
-> authentication and Session activation
-> CONNACK
-> activeCONNECTmust be the sole first packet. A batch tail or another packet while authentication is pending closes the connection.- The server negotiates the protocol version (currently v6; client values
0or above v6 select v6), stores UID and device state plus encryption Session state when enabled, then activates online Presence. - A non-success
CONNACKis written before close. If a successfulCONNACKcannot be written, completed activation is rolled back.
CONNACK success is not product ready
Success proves only that the protocol Session exists. Recover durable messages and merge local state before ordinary product sends are enabled.
Active session
| Direction | Exchange | Completion boundary |
|---|---|---|
| Client → Server | PING → PONG | Heartbeat response only |
| Client → Server | SEND → SENDACK | Protocol send result; not peer receipt or product execution |
| Server → Client | RECV → RECVACK | Session receive feedback; not end-user read state |
The default read-idle timeout is three minutes. Only inbound activity refreshes it; server outbound traffic does not. Proxy and load-balancer idle policies must accommodate the effective heartbeat.
Close and recover
ReasonAuthFailorReasonBan: stop automatic reconnect and repair credentials or policy state.ReasonClientKeyIsEmptyorReasonProtocolUpgradeRequired: fix client configuration or version first.ReasonRateLimit,ReasonSystemError, or transport loss: use only bounded backoff with jitter; rediscover Gateway ingress when needed.- Any other failure: preserve the raw Reason Code and fail closed; do not guess that it is retryable.
After close, stop new sends. Reuse a stable client_msg_no for the same product send and distinct client_seq values for concurrent wire attempts. Return to ready only after CONNACK succeeds and durable-message recovery completes.
The current default composition enables Session payload encryption; CONNECT without client_key returns ReasonClientKeyIsEmpty. This encryption does not replace TLS, product identity and token verification, or Product HTTP protection. The default composition also does not automatically turn a stored token into a CONNECT verifier; production must wire explicit verification and revocation policy.
Continue with Packet Types and Reason Codes.