feat(mqtt): serve MQTT over WebSocket so browsers can consume the broker

Add a WebSocket listener (:8083) alongside raw TCP on the broker, and route
ws(s)://<host>/push to it through Traefik (TLS terminated at the edge, mirroring
mqtts and realtime's wss). Covers it with an e2e that speaks MQTT 5.0 over a
WebSocket binary frame end to end: enhanced-auth CONNECT and an ACL-checked
SUBSCRIBE granted at the topic's QoS.
This commit is contained in:
ArnabChatterjee20k committed 2026-09-18 11:31:32 +05:30
1 parent 417f0efe8d
commit be501b4656
3 files changed
+94 -1

No files matched your search

+3 -1
View File
@@ -174,8 +174,10 @@ $registerConnectionResources($container);
/** @var \Utopia\Telemetry\Adapter $telemetry */
$telemetry = $container->get('telemetry');
$maxPacketSize = (int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000');
$adapter = new Adapter\Swoole([
new Adapter\Swoole\Tcp('0.0.0.0', 1883, (int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000')),
new Adapter\Swoole\Tcp('0.0.0.0', 1883, $maxPacketSize),
new Adapter\Swoole\WebSocket('0.0.0.0', (int) System::getEnv('_APP_MQTT_WS_PORT', '8083'), $maxPacketSize),
], workers: 1);
$mqtt = new Mqtt($telemetry, new PubSubPool($register->get('pools')->get('pubsub')));
+12
View File
@@ -384,6 +384,16 @@ services:
- traefik.tcp.routers.appwrite_mqtt.tls=true
- traefik.tcp.routers.appwrite_mqtt.service=appwrite_mqtt
- traefik.tcp.services.appwrite_mqtt.loadbalancer.server.port=1883
# MQTT-over-WebSocket for browser clients: ws(s)://<host>/push is terminated at the
# web/websecure entrypoints and forwarded to the broker's WebSocket listener (:8083).
- traefik.http.routers.appwrite_mqtt_ws.entrypoints=appwrite_web
- traefik.http.routers.appwrite_mqtt_ws.rule=PathPrefix(`/push`)
- traefik.http.routers.appwrite_mqtt_ws.service=appwrite_mqtt_ws
- traefik.http.routers.appwrite_mqtt_ws_secure.entrypoints=appwrite_websecure
- traefik.http.routers.appwrite_mqtt_ws_secure.rule=PathPrefix(`/push`)
- traefik.http.routers.appwrite_mqtt_ws_secure.service=appwrite_mqtt_ws
- traefik.http.routers.appwrite_mqtt_ws_secure.tls=true
- traefik.http.services.appwrite_mqtt_ws.loadbalancer.server.port=8083
networks:
- appwrite
environment:
@@ -414,6 +424,8 @@ services:
- _APP_LOGGING_CONFIG_REALTIME
- _APP_DATABASE_SHARED_TABLES
- _APP_MQTT_REPLAY_DEPTH
- _APP_MQTT_WS_PORT
- _APP_MQTT_MAX_PACKET_SIZE
- _APP_POOL_ADAPTER=swoole
appwrite-worker:
@@ -6,11 +6,19 @@ namespace Tests\E2E\Services\Mqtt;
use Appwrite\Messaging\Status as MessageStatus;
use PHPUnit\Framework\Attributes\Group;
use Swoole\Coroutine\Http\Client as WebSocketClient;
use Swoole\WebSocket\Frame;
use Tests\E2E\Client;
use Tests\E2E\Scopes\ProjectCustom;
use Tests\E2E\Scopes\Scope;
use Tests\E2E\Scopes\SideServer;
use Utopia\Database\Helpers\ID;
use Utopia\Mqtt\Packet;
use Utopia\Mqtt\Packet\Specs\V5;
use Utopia\Mqtt\Properties;
use Utopia\Mqtt\Property;
use function Swoole\Coroutine\run;
/**
* End-to-end tests for the MQTT push broker (src/Appwrite/Mqtt). Publishing is a server
@@ -33,6 +41,7 @@ final class MqttServerTest extends Scope
private const BROKER_HOST = 'appwrite-mqtt';
private const BROKER_PORT = 1883;
private const BROKER_WS_PORT = 8083;
/**
* Create a user and mint a session-less JWT for it. The broker's JWT path skips
@@ -369,6 +378,76 @@ final class MqttServerTest extends Scope
$this->assertEquals(['matchId' => '42'], $payload['data']);
}
/**
* MQTT over WebSocket: browser clients reach the broker through its WebSocket listener
* (appwrite-mqtt:8083, routed as ws(s)://<host>/push) instead of raw TCP. The same
* enhanced-auth CONNECT and SUBSCRIBE exchange must work with each MQTT packet carried in
* a WebSocket binary frame, exercising the broker's WebSocket transport, packet reassembly
* and framed send in both directions.
*/
public function testWebSocketConnectAndSubscribe(): void
{
$projectId = $this->getProject()['$id'];
['userId' => $userId, 'jwt' => $jwt] = $this->createUser();
$server = [
'content-type' => 'application/json',
'x-appwrite-project' => $projectId,
'x-appwrite-key' => $this->getProject()['apiKey'],
];
$topicId = $this->setupPushTopic($server, $userId, 'appwrite-mqtt-ws');
$connackReason = null;
$codes = [];
run(function () use ($projectId, $jwt, $userId, $topicId, &$connackReason, &$codes) {
$client = new WebSocketClient(self::BROKER_HOST, self::BROKER_WS_PORT);
$client->set(['timeout' => 10]);
$this->assertTrue($client->upgrade('/push'), 'websocket upgrade failed');
$properties = (new Properties())
->add(new Property(Property::AUTHENTICATION_METHOD, 'appwrite-jwt'))
->add(new Property(Property::AUTHENTICATION_DATA, $jwt))
->add(new Property(Property::USER, ['projectId' => $projectId]));
$buffer = '';
$client->push(V5::connect('e2e-ws-' . $userId, 60, true, $properties), WEBSOCKET_OPCODE_BINARY);
$connack = $this->wsReceive($client, $buffer);
$connackReason = \ord($connack->body[1] ?? "\x80");
$client->push(V5::subscribe(1, [$topicId], 1), WEBSOCKET_OPCODE_BINARY);
$suback = $this->wsReceive($client, $buffer);
// SUBACK body: [packetId:2][properties][one reason code per filter].
$offset = Properties::skip($suback->body, 2);
for ($i = $offset; $i < \strlen($suback->body); $i++) {
$codes[] = \ord($suback->body[$i]);
}
$client->close();
});
// Test for SUCCESS: the WebSocket carrier authenticated the CONNECT and granted the
// subscription at the topic's QoS, proving browser clients can consume the broker.
$this->assertSame(0, $connackReason, 'CONNACK over WebSocket was not success');
$this->assertSame([1], $codes, 'SUBACK over WebSocket did not grant QoS 1');
}
/** Read WebSocket frames until one whole MQTT packet reassembles out of their payloads. */
private function wsReceive(WebSocketClient $client, string &$buffer): Packet
{
while (true) {
[$packets, $buffer] = Packet::frames($buffer);
if ($packets !== []) {
return Packet::parse($packets[0]);
}
$frame = $client->recv(10);
$this->assertInstanceOf(Frame::class, $frame, 'websocket receive failed');
$buffer .= (string) $frame->data;
}
}
/**
* Offline QoS 1 session replay: a persistent-session subscriber (cleanStart = false,
* stable client id) subscribes once to register its cursor, disconnects, and while it