MQTT over WebSocket

The WebSocket gateway accepts an HTTP Upgrade with the mqtt subprotocol, decodes bounded client frames, and publishes the reconstructed MQTT records into the same broker path as TCP clients.

Location configuration

location /mqtt {
  iot_gateway_websocket on;
  iot_gateway_websocket_protocol mqtt;
  iot_gateway_websocket_max_frame 81920;
  iot_gateway_websocket_identity header X-Device-ID;
  iot_gateway_websocket_iotd on;
  iot_gateway_websocket_iotd_rings /nginz-iot-production 4096 1024 1024 1 1;
}

Prefer an identity derived from verified TLS or a trusted upstream boundary. A public client-controlled header is not an authentication mechanism.

Protocol boundary

The gateway validates the Upgrade contract, masked client binary frames, fragmentation, and ping/pong/close frames. MQTT session, authorization, routing, and durability remain in the common broker pipeline.

The selected MQTT-over-WebSocket profile passed its complete 17-scenario matrix on both installed image variants. The same module also admits the selected OCPP 1.6J subprotocol. Broader WebSocket subprotocols and unframed MQTT remain out of scope.