From cd54fb58db5c88cb6b8a033835ee3ce02c2f1e20 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 21 Aug 2026 15:33:23 +0530 Subject: [PATCH 001/146] A basic mqtt broker in place running and getting connected through clients --- Dockerfile | 1 + app/mqtt.php | 12 ++ bin/mqtt | 3 + composer.json | 3 +- docker-compose.override.yml | 12 ++ docker-compose.yml | 17 +++ src/Utopia/Mqtt/Broker.php | 244 ++++++++++++++++++++++++++++++++++++ 7 files changed, 291 insertions(+), 1 deletion(-) create mode 100644 app/mqtt.php create mode 100755 bin/mqtt create mode 100644 src/Utopia/Mqtt/Broker.php diff --git a/Dockerfile b/Dockerfile index 13ca2f0d47..5f86caa715 100755 --- a/Dockerfile +++ b/Dockerfile @@ -69,6 +69,7 @@ RUN chmod +x /usr/local/bin/doctor && \ chmod +x /usr/local/bin/maintenance && \ chmod +x /usr/local/bin/migrate && \ chmod +x /usr/local/bin/realtime && \ + chmod +x /usr/local/bin/mqtt && \ chmod +x /usr/local/bin/schedule && \ chmod +x /usr/local/bin/schedule-functions && \ chmod +x /usr/local/bin/schedule-executions && \ diff --git a/app/mqtt.php b/app/mqtt.php new file mode 100644 index 0000000000..bb871e36ed --- /dev/null +++ b/app/mqtt.php @@ -0,0 +1,12 @@ +start(); diff --git a/bin/mqtt b/bin/mqtt new file mode 100755 index 0000000000..2638682e1a --- /dev/null +++ b/bin/mqtt @@ -0,0 +1,3 @@ +#!/bin/sh + +exec php /usr/src/code/app/mqtt.php "$@" diff --git a/composer.json b/composer.json index f5de650609..b092512466 100644 --- a/composer.json +++ b/composer.json @@ -26,7 +26,8 @@ "psr-4": { "Appwrite\\": "src/Appwrite", "Executor\\": "src/Executor", - "Utopia\\Bus\\": "src/Utopia/Bus" + "Utopia\\Bus\\": "src/Utopia/Bus", + "Utopia\\Mqtt\\": "src/Utopia/Mqtt" } }, "autoload-dev": { diff --git a/docker-compose.override.yml b/docker-compose.override.yml index 460d13684d..5646e25b89 100644 --- a/docker-compose.override.yml +++ b/docker-compose.override.yml @@ -50,6 +50,18 @@ services: - ./src:/usr/src/code/src ports: - 9502:80 + appwrite-mqtt: + build: + context: . + target: development + args: + DEBUG: false + TESTING: true + VERSION: dev + image: appwrite-dev + volumes: + - ./app:/usr/src/code/app + - ./src:/usr/src/code/src appwrite-worker: build: context: . diff --git a/docker-compose.yml b/docker-compose.yml index fe93003d28..f4103a891d 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -311,6 +311,23 @@ services: - _APP_DATABASE_SHARED_TABLES - _APP_POOL_ADAPTER=swoole + appwrite-mqtt: + entrypoint: mqtt + logging: + driver: json-file + options: + max-file: "5" + max-size: 10m + container_name: appwrite-mqtt + image: ${_APP_IMAGE:-appwrite/appwrite}:${_APP_VERSION:-latest} + restart: unless-stopped + networks: + - appwrite + ports: + - 1883:1883 + environment: + - _APP_ENV + appwrite-worker: entrypoint: worker restart: unless-stopped diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php new file mode 100644 index 0000000000..1cefeb0412 --- /dev/null +++ b/src/Utopia/Mqtt/Broker.php @@ -0,0 +1,244 @@ + fd => protocol level (4 = 3.1.1, 5 = 5.0) */ + private array $protocol = []; + + /** @var array> fd => set of subscribed topic filters */ + private array $subscriptions = []; + + public function __construct( + private readonly string $host = '0.0.0.0', + private readonly int $port = 1883, + ) { + } + + public function start(): void + { + $server = new Server($this->host, $this->port, SWOOLE_BASE); + $server->set([ + 'open_mqtt_protocol' => true, + 'worker_num' => 1, + ]); + + $server->on('receive', $this->onReceive(...)); + $server->on('close', $this->onClose(...)); + + echo "MQTT broker listening on {$this->host}:{$this->port}\n"; + $server->start(); + } + + private function onReceive(Server $server, int $fd, int $reactorId, string $data): void + { + $type = ord($data[0]) >> 4; + $flags = ord($data[0]) & 0x0F; + + [$remaining, $lenBytes] = $this->decodeLength($data, 1); + $body = substr($data, 1 + $lenBytes, $remaining); + + match ($type) { + self::CONNECT => $this->handleConnect($server, $fd, $body), + self::SUBSCRIBE => $this->handleSubscribe($server, $fd, $body), + self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), + self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), + self::PINGREQ => $server->send($fd, chr(0xD0) . chr(0x00)), + self::DISCONNECT => $server->close($fd), + default => null, + }; + } + + private function handleConnect(Server $server, int $fd, string $body): void + { + $offset = 0; + [, $offset] = $this->readString($body, $offset); // protocol name + $level = ord($body[$offset]); + $this->protocol[$fd] = $level; + + // CONNACK: [ack flags = 0][reason code = 0](+ [property length = 0] for v5) + $variable = chr(0x00) . chr(0x00) . ($level >= 5 ? chr(0x00) : ''); + $server->send($fd, chr(0x20) . $this->encodeLength(strlen($variable)) . $variable); + } + + private function handleSubscribe(Server $server, int $fd, string $body): void + { + $offset = 0; + $packetId = substr($body, 0, 2); + $offset += 2; + $offset = $this->skipProperties($fd, $body, $offset); + + $granted = ''; + while ($offset < strlen($body)) { + [$filter, $offset] = $this->readString($body, $offset); + $offset += 1; // subscription options byte + $this->subscriptions[$fd][$filter] = true; + $granted .= chr(0x00); // granted QoS 0 + } + + // SUBACK: packet id (+ property length 0 for v5) + granted codes + $variable = $packetId . ($this->protocol[$fd] >= 5 ? chr(0x00) : '') . $granted; + $server->send($fd, chr(0x90) . $this->encodeLength(strlen($variable)) . $variable); + } + + private function handleUnsubscribe(Server $server, int $fd, string $body): void + { + $offset = 0; + $packetId = substr($body, 0, 2); + $offset += 2; + $offset = $this->skipProperties($fd, $body, $offset); + + $count = 0; + while ($offset < strlen($body)) { + [$filter, $offset] = $this->readString($body, $offset); + unset($this->subscriptions[$fd][$filter]); + $count++; + } + + // UNSUBACK: packet id (+ property length 0 + one reason code per filter for v5) + $variable = $packetId; + if ($this->protocol[$fd] >= 5) { + $variable .= chr(0x00) . str_repeat(chr(0x00), $count); + } + $server->send($fd, chr(0xB0) . $this->encodeLength(strlen($variable)) . $variable); + } + + private function handlePublish(Server $server, int $fd, int $flags, string $body): void + { + $qos = ($flags >> 1) & 0x03; + + [$topic, $offset] = $this->readString($body, 0); + + $packetId = null; + if ($qos > 0) { + $packetId = substr($body, $offset, 2); + $offset += 2; + } + $offset = $this->skipProperties($fd, $body, $offset); + $payload = substr($body, $offset); + + $this->deliver($server, $topic, $payload); + + if ($qos === 1 && $packetId !== null) { + // PUBACK: packet id (reason/properties omitted -> valid for both versions) + $server->send($fd, chr(0x40) . chr(0x02) . $packetId); + } + } + + private function deliver(Server $server, string $topic, string $payload): void + { + foreach ($this->subscriptions as $fd => $filters) { + foreach ($filters as $filter => $_) { + if ($this->matches($filter, $topic)) { + $variable = $this->encodeString($topic) + . (($this->protocol[$fd] ?? 4) >= 5 ? chr(0x00) : '') + . $payload; + // PUBLISH, QoS 0 + $server->send($fd, chr(0x30) . $this->encodeLength(strlen($variable)) . $variable); + break; // one copy per subscriber even if several filters match + } + } + } + } + + private function onClose(Server $server, int $fd): void + { + unset($this->subscriptions[$fd], $this->protocol[$fd]); + } + + /** + * MQTT topic filter matching with '+' (single level) and '#' (multi level). + */ + private function matches(string $filter, string $topic): bool + { + if ($filter === $topic) { + return true; + } + + $filterParts = explode('/', $filter); + $topicParts = explode('/', $topic); + + foreach ($filterParts as $i => $part) { + if ($part === '#') { + return true; + } + if (!isset($topicParts[$i])) { + return false; + } + if ($part !== '+' && $part !== $topicParts[$i]) { + return false; + } + } + + return count($filterParts) === count($topicParts); + } + + /** + * Skip the MQTT 5.0 property block (variable-length length prefix + bytes). + * No-op for MQTT 3.1.1, which has no properties. + */ + private function skipProperties(int $fd, string $body, int $offset): int + { + if (($this->protocol[$fd] ?? 4) < 5) { + return $offset; + } + [$length, $lenBytes] = $this->decodeLength($body, $offset); + return $offset + $lenBytes + $length; + } + + /** @return array{0: string, 1: int} decoded string and the new offset */ + private function readString(string $data, int $offset): array + { + $length = (ord($data[$offset]) << 8) + ord($data[$offset + 1]); + $value = substr($data, $offset + 2, $length); + return [$value, $offset + 2 + $length]; + } + + private function encodeString(string $value): string + { + $length = strlen($value); + return chr($length >> 8) . chr($length & 0xFF) . $value; + } + + /** Decode a variable-length integer. @return array{0: int, 1: int} value and byte count */ + private function decodeLength(string $data, int $offset): array + { + $value = 0; + $multiplier = 1; + $bytes = 0; + do { + $byte = ord($data[$offset + $bytes]); + $value += ($byte & 0x7F) * $multiplier; + $multiplier *= 128; + $bytes++; + } while (($byte & 0x80) !== 0); + + return [$value, $bytes]; + } + + private function encodeLength(int $length): string + { + $out = ''; + do { + $byte = $length % 128; + $length = intdiv($length, 128); + if ($length > 0) { + $byte |= 0x80; + } + $out .= chr($byte); + } while ($length > 0); + + return $out; + } +} From 357309de748349b14b834d4d5271d7443cbb5e32 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 21 Aug 2026 17:08:39 +0530 Subject: [PATCH 002/146] basic auth setup in the broker --- src/Utopia/Mqtt/Broker.php | 77 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 1cefeb0412..435ad1d6c5 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -13,6 +13,16 @@ class Broker private const UNSUBSCRIBE = 10; private const PINGREQ = 12; private const DISCONNECT = 14; + private const AUTH = 15; + + // Authenticate reason codes (MQTT 5.0). + private const AUTH_SUCCESS = 0x00; + private const AUTH_CONTINUE = 0x18; + private const AUTH_REAUTH = 0x19; + + // Property identifiers, shared between CONNECT and AUTH property blocks. + private const PROP_AUTH_METHOD = 0x15; + private const PROP_AUTH_DATA = 0x16; /** @var array fd => protocol level (4 = 3.1.1, 5 = 5.0) */ private array $protocol = []; @@ -43,8 +53,10 @@ class Broker private function onReceive(Server $server, int $fd, int $reactorId, string $data): void { + var_dump($data); $type = ord($data[0]) >> 4; $flags = ord($data[0]) & 0x0F; + var_dump($type); [$remaining, $lenBytes] = $this->decodeLength($data, 1); $body = substr($data, 1 + $lenBytes, $remaining); @@ -54,6 +66,7 @@ class Broker self::SUBSCRIBE => $this->handleSubscribe($server, $fd, $body), self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), + self::AUTH => $this->handleAuth($server, $fd, $body), self::PINGREQ => $server->send($fd, chr(0xD0) . chr(0x00)), self::DISCONNECT => $server->close($fd), default => null, @@ -114,6 +127,70 @@ class Broker $server->send($fd, chr(0xB0) . $this->encodeLength(strlen($variable)) . $variable); } + private function handleAuth(Server $server, int $fd, string $body): void + { + if ($body === '') { + // Shorthand: remaining length 0 means reason Success with no properties. + $reasonCode = self::AUTH_SUCCESS; + $method = $data = ''; + } else { + $reasonCode = ord($body[0]); + [$method, $data] = $this->readAuthProperties($body, 1); + } + + // $reasonCode: 0x19 re-authenticate, 0x18 continue. + // $method e.g. "appwrite-session"; $data is the credential to verify. + // TODO: verify $data and derive the identity, then persist it for this $fd. + // Success on a live connection is acknowledged with an AUTH packet; + // failure should DISCONNECT (or CONNACK 0x87 during the initial handshake). + $server->send($fd, $this->encodeAuth(self::AUTH_SUCCESS, $method)); + } + + /** + * Read the Authentication Method and Data from a property block. + * Works for both the AUTH packet and the CONNECT properties. + * + * @return array{0: string, 1: string} [authMethod, authData] + */ + private function readAuthProperties(string $body, int $offset): array + { + $method = $data = ''; + + [$length, $lenBytes] = $this->decodeLength($body, $offset); + $offset += $lenBytes; + $end = $offset + $length; + + while ($offset < $end) { + $id = ord($body[$offset]); + $offset++; + + match ($id) { + self::PROP_AUTH_METHOD => [$method, $offset] = $this->readString($body, $offset), + self::PROP_AUTH_DATA => [$data, $offset] = $this->readString($body, $offset), + // POC assumption: clients send only method and data. A general + // skip needs each property's wire type to advance correctly. + default => throw new \RuntimeException('Unhandled auth property 0x' . dechex($id)), + }; + } + + return [$method, $data]; + } + + private function encodeAuth(int $reasonCode, string $method, string $data = ''): string + { + $properties = ''; + if ($method !== '') { + $properties .= chr(self::PROP_AUTH_METHOD) . $this->encodeString($method); + } + if ($data !== '') { + $properties .= chr(self::PROP_AUTH_DATA) . $this->encodeString($data); + } + + $variable = chr($reasonCode) . $this->encodeLength(strlen($properties)) . $properties; + + return chr(self::AUTH << 4) . $this->encodeLength(strlen($variable)) . $variable; + } + private function handlePublish(Server $server, int $fd, int $flags, string $body): void { $qos = ($flags >> 1) & 0x03; From b3e7c96c3183b9704556532687b7f01ef0ce515a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 21 Aug 2026 18:17:38 +0530 Subject: [PATCH 003/146] feat(mqtt): enhance CONNECT handling with user properties support --- src/Utopia/Mqtt/Broker.php | 61 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 58 insertions(+), 3 deletions(-) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 435ad1d6c5..f9d5331e7c 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -23,10 +23,14 @@ class Broker // Property identifiers, shared between CONNECT and AUTH property blocks. private const PROP_AUTH_METHOD = 0x15; private const PROP_AUTH_DATA = 0x16; + private const PROP_USER = 0x26; /** @var array fd => protocol level (4 = 3.1.1, 5 = 5.0) */ private array $protocol = []; + /** @var array fd => project id (from the CONNECT username field) */ + private array $project = []; + /** @var array> fd => set of subscribed topic filters */ private array $subscriptions = []; @@ -53,10 +57,8 @@ class Broker private function onReceive(Server $server, int $fd, int $reactorId, string $data): void { - var_dump($data); $type = ord($data[0]) >> 4; $flags = ord($data[0]) & 0x0F; - var_dump($type); [$remaining, $lenBytes] = $this->decodeLength($data, 1); $body = substr($data, 1 + $lenBytes, $remaining); @@ -77,14 +79,67 @@ class Broker { $offset = 0; [, $offset] = $this->readString($body, $offset); // protocol name + $level = ord($body[$offset]); $this->protocol[$fd] = $level; + $offset += 1; // protocol level + $offset += 1; // connect flags + $offset += 2; // keep alive + + // CONNECT properties carry enhanced auth and our custom metadata. + [$userProperties] = $this->readUserProperties($fd, $body, $offset); + + // projectId is sent as a User Property. deviceType and any other client + // metadata can be added the same way, e.g. $userProperties['deviceType']. + $project = $userProperties['projectId'] ?? ''; + + $this->project[$fd] = $project; + echo "CONNECT project={$project}\n"; + + // TODO: select the project DB from $project and verify the session credential. // CONNACK: [ack flags = 0][reason code = 0](+ [property length = 0] for v5) $variable = chr(0x00) . chr(0x00) . ($level >= 5 ? chr(0x00) : ''); $server->send($fd, chr(0x20) . $this->encodeLength(strlen($variable)) . $variable); } + /** + * Read the User Properties from a v5 CONNECT property block as a key/value map, + * skipping the auth method/data. No-op for MQTT 3.1.1 (no properties). + * + * @return array{0: array, 1: int} [userProperties, newOffset] + */ + private function readUserProperties(int $fd, string $body, int $offset): array + { + $userProperties = []; + + if (($this->protocol[$fd] ?? 4) < 5) { + return [$userProperties, $offset]; + } + + [$length, $lenBytes] = $this->decodeLength($body, $offset); + $offset += $lenBytes; + $end = $offset + $length; + + while ($offset < $end) { + $id = ord($body[$offset]); + $offset++; + + if ($id === self::PROP_AUTH_METHOD || $id === self::PROP_AUTH_DATA) { + [, $offset] = $this->readString($body, $offset); + } elseif ($id === self::PROP_USER) { + [$key, $offset] = $this->readString($body, $offset); + [$value, $offset] = $this->readString($body, $offset); + $userProperties[$key] = $value; + } else { + // POC assumption: clients send only auth and user properties. + throw new \RuntimeException('Unhandled connect property 0x' . dechex($id)); + } + } + + return [$userProperties, $offset]; + } + private function handleSubscribe(Server $server, int $fd, string $body): void { $offset = 0; @@ -231,7 +286,7 @@ class Broker private function onClose(Server $server, int $fd): void { - unset($this->subscriptions[$fd], $this->protocol[$fd]); + unset($this->subscriptions[$fd], $this->protocol[$fd], $this->project[$fd]); } /** From 2d83a09325eb4572ce903f34b5544e1409cc571c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 11:01:35 +0530 Subject: [PATCH 004/146] feat(mqtt): update packet handling with proper reason codes and response formatting --- src/Utopia/Mqtt/Broker.php | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index f9d5331e7c..0956aeb25b 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -8,14 +8,20 @@ class Broker { // Control packet types (MQTT fixed header, high nibble). private const CONNECT = 1; + private const CONNACK = 2; private const PUBLISH = 3; + private const PUBACK = 4; private const SUBSCRIBE = 8; + private const SUBACK = 9; private const UNSUBSCRIBE = 10; + private const UNSUBACK = 11; private const PINGREQ = 12; + private const PINGRESP = 13; private const DISCONNECT = 14; private const AUTH = 15; - // Authenticate reason codes (MQTT 5.0). + // Reason codes (MQTT 5.0). 0x00 is Success across every acknowledgement. + private const REASON_SUCCESS = 0x00; private const AUTH_SUCCESS = 0x00; private const AUTH_CONTINUE = 0x18; private const AUTH_REAUTH = 0x19; @@ -69,7 +75,7 @@ class Broker self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), self::AUTH => $this->handleAuth($server, $fd, $body), - self::PINGREQ => $server->send($fd, chr(0xD0) . chr(0x00)), + self::PINGREQ => $server->send($fd, chr(self::PINGRESP << 4) . $this->encodeLength(0)), self::DISCONNECT => $server->close($fd), default => null, }; @@ -98,9 +104,9 @@ class Broker // TODO: select the project DB from $project and verify the session credential. - // CONNACK: [ack flags = 0][reason code = 0](+ [property length = 0] for v5) - $variable = chr(0x00) . chr(0x00) . ($level >= 5 ? chr(0x00) : ''); - $server->send($fd, chr(0x20) . $this->encodeLength(strlen($variable)) . $variable); + // CONNACK: [ack flags = 0][reason code](+ [property length = 0] for v5) + $variable = chr(0x00) . chr(self::REASON_SUCCESS) . ($level >= 5 ? $this->encodeLength(0) : ''); + $server->send($fd, chr(self::CONNACK << 4) . $this->encodeLength(strlen($variable)) . $variable); } /** @@ -152,12 +158,12 @@ class Broker [$filter, $offset] = $this->readString($body, $offset); $offset += 1; // subscription options byte $this->subscriptions[$fd][$filter] = true; - $granted .= chr(0x00); // granted QoS 0 + $granted .= chr(self::REASON_SUCCESS); // granted QoS 0 } // SUBACK: packet id (+ property length 0 for v5) + granted codes - $variable = $packetId . ($this->protocol[$fd] >= 5 ? chr(0x00) : '') . $granted; - $server->send($fd, chr(0x90) . $this->encodeLength(strlen($variable)) . $variable); + $variable = $packetId . ($this->protocol[$fd] >= 5 ? $this->encodeLength(0) : '') . $granted; + $server->send($fd, chr(self::SUBACK << 4) . $this->encodeLength(strlen($variable)) . $variable); } private function handleUnsubscribe(Server $server, int $fd, string $body): void @@ -177,9 +183,9 @@ class Broker // UNSUBACK: packet id (+ property length 0 + one reason code per filter for v5) $variable = $packetId; if ($this->protocol[$fd] >= 5) { - $variable .= chr(0x00) . str_repeat(chr(0x00), $count); + $variable .= $this->encodeLength(0) . str_repeat(chr(self::REASON_SUCCESS), $count); } - $server->send($fd, chr(0xB0) . $this->encodeLength(strlen($variable)) . $variable); + $server->send($fd, chr(self::UNSUBACK << 4) . $this->encodeLength(strlen($variable)) . $variable); } private function handleAuth(Server $server, int $fd, string $body): void @@ -264,7 +270,7 @@ class Broker if ($qos === 1 && $packetId !== null) { // PUBACK: packet id (reason/properties omitted -> valid for both versions) - $server->send($fd, chr(0x40) . chr(0x02) . $packetId); + $server->send($fd, chr(self::PUBACK << 4) . $this->encodeLength(strlen($packetId)) . $packetId); } } @@ -274,10 +280,10 @@ class Broker foreach ($filters as $filter => $_) { if ($this->matches($filter, $topic)) { $variable = $this->encodeString($topic) - . (($this->protocol[$fd] ?? 4) >= 5 ? chr(0x00) : '') + . (($this->protocol[$fd] ?? 4) >= 5 ? $this->encodeLength(0) : '') . $payload; // PUBLISH, QoS 0 - $server->send($fd, chr(0x30) . $this->encodeLength(strlen($variable)) . $variable); + $server->send($fd, chr(self::PUBLISH << 4) . $this->encodeLength(strlen($variable)) . $variable); break; // one copy per subscriber even if several filters match } } From dfb64da9ab5e2f19f0019f0c0f7b5d8b11cccc43 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 11:32:16 +0530 Subject: [PATCH 005/146] added runtime deps in the broker --- src/Utopia/Mqtt/Broker.php | 169 +++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 0956aeb25b..56076ed506 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -2,7 +2,176 @@ namespace Utopia\Mqtt; +use Appwrite\Utopia\Database\Documents\User; +use Swoole\Coroutine; +use Swoole\Runtime; use Swoole\Server; +use Utopia\Cache\Adapter\Pool as CachePool; +use Utopia\Cache\Adapter\Sharding; +use Utopia\Cache\Cache; +use Utopia\Config\Config; +use Utopia\Database\Adapter\Pool as DatabasePool; +use Utopia\Database\Database; +use Utopia\Database\Document; +use Utopia\DSN\DSN; +use Utopia\System\System; + +// Currently using the realtime init only as its matching the requirements +// TODO: scope the connection init to a separate mqtt connection +require_once __DIR__ . '/../../../app/init.php'; + +if (System::getEnv('_APP_EDITION', 'self-hosted') === 'self-hosted') { + require_once __DIR__ . '/../../../app/init/span.php'; +} + +/** @var Registry $register */ +$register = $GLOBALS['register'] ?? throw new \RuntimeException('Registry not initialized'); + +$registerConnectionResources ??= require __DIR__ . '/../../../app/init/realtime/connection.php'; + +Runtime::enableCoroutine(SWOOLE_HOOK_ALL); + + +// Allows overriding +if (!function_exists('getConsoleDB')) { + function getConsoleDB(): Database + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['dbForPlatform'])) { + return $ctx['dbForPlatform']; + } + + global $register; + + /** @var Group $pools */ + $pools = $register->get('pools'); + + $adapter = new DatabasePool($pools->get('console')); + $database = new Database($adapter, getCache()); + $database + ->setDatabase(APP_DATABASE) + ->setNamespace('_console') + ->setMetadata('host', \gethostname()) + ->setMetadata('project', '_console'); + $database->setDocumentType('users', User::class); + return $ctx['dbForPlatform'] = $database; + } +} + +// Allows overriding +if (!function_exists('getProjectDB')) { + function getProjectDB(Document $project): Database + { + $ctx = Coroutine::getContext(); + + if (!isset($ctx['dbForProject'])) { + $ctx['dbForProject'] = []; + } + + if (isset($ctx['dbForProject'][$project->getSequence()])) { + return $ctx['dbForProject'][$project->getSequence()]; + } + + global $register; + + /** @var Group $pools */ + $pools = $register->get('pools'); + + if ($project->isEmpty() || $project->getId() === 'console') { + return getConsoleDB(); + } + + try { + $dsn = new DSN($project->getAttribute('database')); + } catch (\InvalidArgumentException) { + // TODO: Temporary until all projects are using shared tables + $dsn = new DSN('mysql://' . $project->getAttribute('database')); + } + + $adapter = new DatabasePool($pools->get($dsn->getHost())); + $database = new Database($adapter, getCache()); + + $sharedTables = \explode(',', System::getEnv('_APP_DATABASE_SHARED_TABLES', '')); + + if (\in_array($dsn->getHost(), $sharedTables)) { + $collections = Config::getParam('collections', []); + $projectCollections = $collections['projects'] ?? []; + $projectsGlobalCollections = array_keys($projectCollections); + $projectsGlobalCollections[] = 'audit'; + + $database + ->setSharedTables(true) + ->setGlobalCollections($projectsGlobalCollections) + ->setTenant($project->getSequence()) + ->setNamespace($dsn->getParam('namespace')); + } else { + $database + ->setSharedTables(false) + ->setTenant(null) + ->setNamespace('_' . $project->getSequence()); + } + + $database + ->setDatabase(APP_DATABASE) + ->setMetadata('host', \gethostname()) + ->setMetadata('project', $project->getId()); + + $database->setDocumentType('users', User::class); + + return $ctx['dbForProject'][$project->getSequence()] = $database; + } +} + +// Allows overriding +if (!function_exists('getCache')) { + function getCache(): Cache + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['cache'])) { + return $ctx['cache']; + } + + global $register; + + $pools = $register->get('pools'); /** @var Group $pools */ + + $list = Config::getParam('pools-cache', []); + $adapters = []; + + foreach ($list as $value) { + $adapters[] = new CachePool($pools->get($value)); + } + + return $ctx['cache'] = new Cache(new Sharding($adapters)); + } +} + +// Allows overriding +if (!function_exists('getRedis')) { + function getRedis(): \Redis + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['redis'])) { + return $ctx['redis']; + } + + $host = System::getEnv('_APP_REDIS_HOST', 'localhost'); + $port = System::getEnv('_APP_REDIS_PORT', 6379); + $pass = System::getEnv('_APP_REDIS_PASS', ''); + + $redis = new \Redis(); + @$redis->pconnect($host, (int)$port); + if ($pass) { + $redis->auth($pass); + } + $redis->setOption(\Redis::OPT_READ_TIMEOUT, -1); + + return $ctx['redis'] = $redis; + } +} class Broker { From 03f3d1c2f43a59312bb096dcd38ba29ff4072163 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 11:33:56 +0530 Subject: [PATCH 006/146] added todo note --- src/Utopia/Mqtt/Broker.php | 1 + 1 file changed, 1 insertion(+) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 56076ed506..09d33f0e18 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -173,6 +173,7 @@ if (!function_exists('getRedis')) { } } +// TODO: Having it as a class but should be like functions like the realtime service with message handlers as action class Broker { // Control packet types (MQTT fixed header, high nibble). From 6bec52230dae652bb6fe3d83b782f3efe38b095f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 12:14:04 +0530 Subject: [PATCH 007/146] added env to the mqtt broker --- docker-compose.yml | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docker-compose.yml b/docker-compose.yml index f4103a891d..64def4243b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -327,6 +327,32 @@ services: - 1883:1883 environment: - _APP_ENV + - _APP_WORKER_PER_CORE + - _APP_OPTIONS_ABUSE + - _APP_OPTIONS_ROUTER_PROTECTION + - _APP_REALTIME_TAIL_RATE + - _APP_OPENSSL_KEY_V1 + - _APP_REDIS_HOST + - _APP_REDIS_PORT + - _APP_REDIS_USER + - _APP_REDIS_PASS + - _APP_DB_ADAPTER + - _APP_DB_HOST + - _APP_DB_PORT + - _APP_DB_SCHEMA + - _APP_DB_USER + - _APP_DB_PASS + - _APP_DB_ADAPTER_VECTORSDB + - _APP_DB_HOST_VECTORSDB + - _APP_DB_PORT_VECTORSDB + - _APP_DB_SCHEMA_VECTORSDB + - _APP_DB_USER_VECTORSDB + - _APP_DB_PASS_VECTORSDB + - _APP_LOGGING_CONFIG + - _APP_LOGGING_FORMAT + - _APP_LOGGING_CONFIG_REALTIME + - _APP_DATABASE_SHARED_TABLES + - _APP_POOL_ADAPTER=swoole appwrite-worker: entrypoint: worker From b8bcbe8b1cf21f1018e4bfdad15cf384099add6a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 12:21:13 +0530 Subject: [PATCH 008/146] feat(mqtt): add auth seam, unified property reader, and reauth enforcement Introduce an injected onConnect authenticator so the broker stays free of any Appwrite dependency (extractable to utopia-php/mqtt). CONNECT resolves an identity via the authenticator and rejects with CONNACK 0x87 on failure; the AUTH packet re-verifies on reauth and enforces the projectId matches the one pinned at CONNECT, so a connection cannot switch tenants. Fold the CONNECT and AUTH property blocks into one reader, and name the response/reason-code bytes as constants instead of raw hex. --- src/Utopia/Mqtt/Broker.php | 341 ++++++++++++------------------------- 1 file changed, 105 insertions(+), 236 deletions(-) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 09d33f0e18..27c0b1fb29 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -2,178 +2,8 @@ namespace Utopia\Mqtt; -use Appwrite\Utopia\Database\Documents\User; -use Swoole\Coroutine; -use Swoole\Runtime; use Swoole\Server; -use Utopia\Cache\Adapter\Pool as CachePool; -use Utopia\Cache\Adapter\Sharding; -use Utopia\Cache\Cache; -use Utopia\Config\Config; -use Utopia\Database\Adapter\Pool as DatabasePool; -use Utopia\Database\Database; -use Utopia\Database\Document; -use Utopia\DSN\DSN; -use Utopia\System\System; -// Currently using the realtime init only as its matching the requirements -// TODO: scope the connection init to a separate mqtt connection -require_once __DIR__ . '/../../../app/init.php'; - -if (System::getEnv('_APP_EDITION', 'self-hosted') === 'self-hosted') { - require_once __DIR__ . '/../../../app/init/span.php'; -} - -/** @var Registry $register */ -$register = $GLOBALS['register'] ?? throw new \RuntimeException('Registry not initialized'); - -$registerConnectionResources ??= require __DIR__ . '/../../../app/init/realtime/connection.php'; - -Runtime::enableCoroutine(SWOOLE_HOOK_ALL); - - -// Allows overriding -if (!function_exists('getConsoleDB')) { - function getConsoleDB(): Database - { - $ctx = Coroutine::getContext(); - - if (isset($ctx['dbForPlatform'])) { - return $ctx['dbForPlatform']; - } - - global $register; - - /** @var Group $pools */ - $pools = $register->get('pools'); - - $adapter = new DatabasePool($pools->get('console')); - $database = new Database($adapter, getCache()); - $database - ->setDatabase(APP_DATABASE) - ->setNamespace('_console') - ->setMetadata('host', \gethostname()) - ->setMetadata('project', '_console'); - $database->setDocumentType('users', User::class); - return $ctx['dbForPlatform'] = $database; - } -} - -// Allows overriding -if (!function_exists('getProjectDB')) { - function getProjectDB(Document $project): Database - { - $ctx = Coroutine::getContext(); - - if (!isset($ctx['dbForProject'])) { - $ctx['dbForProject'] = []; - } - - if (isset($ctx['dbForProject'][$project->getSequence()])) { - return $ctx['dbForProject'][$project->getSequence()]; - } - - global $register; - - /** @var Group $pools */ - $pools = $register->get('pools'); - - if ($project->isEmpty() || $project->getId() === 'console') { - return getConsoleDB(); - } - - try { - $dsn = new DSN($project->getAttribute('database')); - } catch (\InvalidArgumentException) { - // TODO: Temporary until all projects are using shared tables - $dsn = new DSN('mysql://' . $project->getAttribute('database')); - } - - $adapter = new DatabasePool($pools->get($dsn->getHost())); - $database = new Database($adapter, getCache()); - - $sharedTables = \explode(',', System::getEnv('_APP_DATABASE_SHARED_TABLES', '')); - - if (\in_array($dsn->getHost(), $sharedTables)) { - $collections = Config::getParam('collections', []); - $projectCollections = $collections['projects'] ?? []; - $projectsGlobalCollections = array_keys($projectCollections); - $projectsGlobalCollections[] = 'audit'; - - $database - ->setSharedTables(true) - ->setGlobalCollections($projectsGlobalCollections) - ->setTenant($project->getSequence()) - ->setNamespace($dsn->getParam('namespace')); - } else { - $database - ->setSharedTables(false) - ->setTenant(null) - ->setNamespace('_' . $project->getSequence()); - } - - $database - ->setDatabase(APP_DATABASE) - ->setMetadata('host', \gethostname()) - ->setMetadata('project', $project->getId()); - - $database->setDocumentType('users', User::class); - - return $ctx['dbForProject'][$project->getSequence()] = $database; - } -} - -// Allows overriding -if (!function_exists('getCache')) { - function getCache(): Cache - { - $ctx = Coroutine::getContext(); - - if (isset($ctx['cache'])) { - return $ctx['cache']; - } - - global $register; - - $pools = $register->get('pools'); /** @var Group $pools */ - - $list = Config::getParam('pools-cache', []); - $adapters = []; - - foreach ($list as $value) { - $adapters[] = new CachePool($pools->get($value)); - } - - return $ctx['cache'] = new Cache(new Sharding($adapters)); - } -} - -// Allows overriding -if (!function_exists('getRedis')) { - function getRedis(): \Redis - { - $ctx = Coroutine::getContext(); - - if (isset($ctx['redis'])) { - return $ctx['redis']; - } - - $host = System::getEnv('_APP_REDIS_HOST', 'localhost'); - $port = System::getEnv('_APP_REDIS_PORT', 6379); - $pass = System::getEnv('_APP_REDIS_PASS', ''); - - $redis = new \Redis(); - @$redis->pconnect($host, (int)$port); - if ($pass) { - $redis->auth($pass); - } - $redis->setOption(\Redis::OPT_READ_TIMEOUT, -1); - - return $ctx['redis'] = $redis; - } -} - -// TODO: Having it as a class but should be like functions like the realtime service with message handlers as action class Broker { // Control packet types (MQTT fixed header, high nibble). @@ -192,6 +22,7 @@ class Broker // Reason codes (MQTT 5.0). 0x00 is Success across every acknowledgement. private const REASON_SUCCESS = 0x00; + private const REASON_NOT_AUTHORIZED = 0x87; private const AUTH_SUCCESS = 0x00; private const AUTH_CONTINUE = 0x18; private const AUTH_REAUTH = 0x19; @@ -204,18 +35,38 @@ class Broker /** @var array fd => protocol level (4 = 3.1.1, 5 = 5.0) */ private array $protocol = []; - /** @var array fd => project id (from the CONNECT username field) */ + /** @var array fd => project id (from a CONNECT User Property) */ private array $project = []; /** @var array> fd => set of subscribed topic filters */ private array $subscriptions = []; + /** @var array> fd => resolved identity (project/user ids) */ + private array $identity = []; + + /** + * + * @var (callable(string, string): array)|null + */ + private $authenticator = null; + public function __construct( private readonly string $host = '0.0.0.0', private readonly int $port = 1883, ) { } + /** + * Register the CONNECT authenticator. Without one the broker accepts every + * connection (raw protocol testing). + * + * @param callable(string, string): array $authenticator + */ + public function onConnect(callable $authenticator): void + { + $this->authenticator = $authenticator; + } + public function start(): void { $server = new Server($this->host, $this->port, SWOOLE_BASE); @@ -262,35 +113,47 @@ class Broker $offset += 1; // connect flags $offset += 2; // keep alive - // CONNECT properties carry enhanced auth and our custom metadata. - [$userProperties] = $this->readUserProperties($fd, $body, $offset); + $properties = $this->getProperties($fd, $body, $offset); - // projectId is sent as a User Property. deviceType and any other client - // metadata can be added the same way, e.g. $userProperties['deviceType']. - $project = $userProperties['projectId'] ?? ''; + $projectId = $properties['user']['projectId'] ?? ''; + $this->project[$fd] = $projectId; - $this->project[$fd] = $project; - echo "CONNECT project={$project}\n"; + // TODO: add abuse limiting keyed on the client ip. + if ($this->authenticator !== null) { + $identity = ($this->authenticator)($projectId, $properties['authData']); - // TODO: select the project DB from $project and verify the session credential. + if ($identity === []) { + $this->sendConnack($server, $fd, $level, self::REASON_NOT_AUTHORIZED); + $server->close($fd); + return; + } + $this->identity[$fd] = $identity; + } + + $this->sendConnack($server, $fd, $level, self::REASON_SUCCESS); + } + + private function sendConnack(Server $server, int $fd, int $level, int $reasonCode): void + { // CONNACK: [ack flags = 0][reason code](+ [property length = 0] for v5) - $variable = chr(0x00) . chr(self::REASON_SUCCESS) . ($level >= 5 ? $this->encodeLength(0) : ''); + $variable = chr(0x00) . chr($reasonCode) . ($level >= 5 ? $this->encodeLength(0) : ''); $server->send($fd, chr(self::CONNACK << 4) . $this->encodeLength(strlen($variable)) . $variable); } /** - * Read the User Properties from a v5 CONNECT property block as a key/value map, - * skipping the auth method/data. No-op for MQTT 3.1.1 (no properties). + * Read a v5 property block: User Properties as a key/value map plus the + * Authentication Method and Data. Shared by CONNECT and AUTH, which carry an + * identical block. No-op for MQTT 3.1.1 (no properties). * - * @return array{0: array, 1: int} [userProperties, newOffset] + * @return array{user: array, authMethod: string, authData: string} */ - private function readUserProperties(int $fd, string $body, int $offset): array + private function getProperties(int $fd, string $body, int $offset): array { - $userProperties = []; + $properties = ['user' => [], 'authMethod' => '', 'authData' => '']; if (($this->protocol[$fd] ?? 4) < 5) { - return [$userProperties, $offset]; + return $properties; } [$length, $lenBytes] = $this->decodeLength($body, $offset); @@ -301,19 +164,25 @@ class Broker $id = ord($body[$offset]); $offset++; - if ($id === self::PROP_AUTH_METHOD || $id === self::PROP_AUTH_DATA) { - [, $offset] = $this->readString($body, $offset); - } elseif ($id === self::PROP_USER) { - [$key, $offset] = $this->readString($body, $offset); - [$value, $offset] = $this->readString($body, $offset); - $userProperties[$key] = $value; - } else { - // POC assumption: clients send only auth and user properties. - throw new \RuntimeException('Unhandled connect property 0x' . dechex($id)); + switch ($id) { + case self::PROP_AUTH_METHOD: + [$properties['authMethod'], $offset] = $this->readString($body, $offset); + break; + case self::PROP_AUTH_DATA: + [$properties['authData'], $offset] = $this->readString($body, $offset); + break; + case self::PROP_USER: + [$key, $offset] = $this->readString($body, $offset); + [$value, $offset] = $this->readString($body, $offset); + $properties['user'][$key] = $value; + break; + default: + // POC assumption: clients send only auth and user properties. + throw new \RuntimeException('Unhandled connect property 0x' . dechex($id)); } } - return [$userProperties, $offset]; + return $properties; } private function handleSubscribe(Server $server, int $fd, string $body): void @@ -360,51 +229,46 @@ class Broker private function handleAuth(Server $server, int $fd, string $body): void { - if ($body === '') { - // Shorthand: remaining length 0 means reason Success with no properties. - $reasonCode = self::AUTH_SUCCESS; - $method = $data = ''; - } else { - $reasonCode = ord($body[0]); - [$method, $data] = $this->readAuthProperties($body, 1); + $method = ''; + $data = ''; + $userProperties = []; + + if ($body !== '') { + // $body[0] is the reason code (0x19 re-authenticate) + // from the offset 1 everything is the mqtt v5 properties + $properties = $this->getProperties($fd, $body, 1); + $method = $properties['authMethod']; + $data = $properties['authData']; + $userProperties = $properties['user']; } - // $reasonCode: 0x19 re-authenticate, 0x18 continue. - // $method e.g. "appwrite-session"; $data is the credential to verify. - // TODO: verify $data and derive the identity, then persist it for this $fd. - // Success on a live connection is acknowledged with an AUTH packet; - // failure should DISCONNECT (or CONNACK 0x87 during the initial handshake). + // The AUTH packet re-sends projectId as a User Property. + // TODO: check the events for the reauth only refreshes + // the credential, so enforce it stays on the project resolved at CONNECT — the + // connection must not switch tenants — then verify the fresh credential. + if ($this->authenticator !== null) { + $projectId = $userProperties['projectId'] ?? ''; + + $identity = ($projectId !== '' && $projectId === ($this->project[$fd] ?? '')) + ? ($this->authenticator)($projectId, $data) + : []; + + if ($identity === []) { + $this->sendDisconnect($server, $fd, self::REASON_NOT_AUTHORIZED); + return; + } + + $this->identity[$fd] = $identity; + } + + // Acknowledge success on the live connection with an AUTH packet. $server->send($fd, $this->encodeAuth(self::AUTH_SUCCESS, $method)); } - /** - * Read the Authentication Method and Data from a property block. - * Works for both the AUTH packet and the CONNECT properties. - * - * @return array{0: string, 1: string} [authMethod, authData] - */ - private function readAuthProperties(string $body, int $offset): array + private function sendDisconnect(Server $server, int $fd, int $reasonCode): void { - $method = $data = ''; - - [$length, $lenBytes] = $this->decodeLength($body, $offset); - $offset += $lenBytes; - $end = $offset + $length; - - while ($offset < $end) { - $id = ord($body[$offset]); - $offset++; - - match ($id) { - self::PROP_AUTH_METHOD => [$method, $offset] = $this->readString($body, $offset), - self::PROP_AUTH_DATA => [$data, $offset] = $this->readString($body, $offset), - // POC assumption: clients send only method and data. A general - // skip needs each property's wire type to advance correctly. - default => throw new \RuntimeException('Unhandled auth property 0x' . dechex($id)), - }; - } - - return [$method, $data]; + $server->send($fd, chr(self::DISCONNECT << 4) . $this->encodeLength(1) . chr($reasonCode)); + $server->close($fd); } private function encodeAuth(int $reasonCode, string $method, string $data = ''): string @@ -462,7 +326,12 @@ class Broker private function onClose(Server $server, int $fd): void { - unset($this->subscriptions[$fd], $this->protocol[$fd], $this->project[$fd]); + unset( + $this->subscriptions[$fd], + $this->protocol[$fd], + $this->project[$fd], + $this->identity[$fd], + ); } /** From e0bc3f61196507b60681fb2570f3969d2924b721 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 12:21:21 +0530 Subject: [PATCH 009/146] feat(mqtt): add per-connection resources for project and session auth MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The MQTT analog of app/init/realtime/connection.php, without the HTTP surface (origin/CSRF, cookies, dev keys, impersonation). Resolves the project from the CONNECT projectId and verifies the session secret via Store::decode + User::sessionVerify — the same transport-agnostic domain logic HTTP uses. --- app/init/mqtt/connection.php | 56 ++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 app/init/mqtt/connection.php diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php new file mode 100644 index 0000000000..762207fe09 --- /dev/null +++ b/app/init/mqtt/connection.php @@ -0,0 +1,56 @@ +set('authorization', function () { + return new Authorization(); + }, []); + + $container->set('project', function (string $projectId, Document $console, Authorization $authorization) { + if ($projectId === '' || $projectId === 'console') { + return $console; + } + + $dbForPlatform = getConsoleDB(); + + return $authorization->skip(fn () => $dbForPlatform->getDocument('projects', $projectId)); + }, ['projectId', 'console', 'authorization']); + + $container->set('user', function (Document $project, string $sessionSecret, Authorization $authorization) { + if ($project->isEmpty() || $sessionSecret === '') { + return new User([]); + } + + $authorization->setDefaultStatus(true); + + // The session secret arrives as the same Store-encoded "id:secret" blob the + // SDK sends over x-appwrite-session; decode it to recover both halves. + $store = new Store(); + $store->decode($sessionSecret); + + $proofForToken = new Token(); + $proofForToken->setHash(new Sha()); + + $dbForProject = getProjectDB($project); + $dbForProject->setAuthorization($authorization); + + /** @var User $user */ + $user = $dbForProject->getDocument('users', $store->getProperty('id', '')); + + if ( + $user->isEmpty() + || !$user->sessionVerify($store->getProperty('secret', ''), $proofForToken) + ) { + return new User([]); + } + + return $user; + }, ['project', 'sessionSecret', 'authorization']); +}; From 9a27ec6fd53c985d8820988ee6135d9360f23b4a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 12:21:30 +0530 Subject: [PATCH 010/146] feat(mqtt): bootstrap the broker process and wire the authenticator Mirror the realtime process bootstrap (init, DB pool helpers, coroutine runtime) and register the container-backed authenticator on the broker. The authenticator builds a child container from the CONNECT projectId and session secret, resolves project and user, and returns the identity (or empty to reject). --- app/mqtt.php | 182 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 177 insertions(+), 5 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index bb871e36ed..3446c6b9a7 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -1,12 +1,184 @@ has('pools')) { + $container->set('pools', function ($register) { + return $register->get('pools'); + }, ['register']); +} + +// DB bootstrap helpers, mirroring app/realtime.php. These are process-level (pools + +// cache), not HTTP; the connection resources call them to reach the project/console DB. +if (!function_exists('getCache')) { + function getCache(): Cache + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['cache'])) { + return $ctx['cache']; + } + + global $register; + + /** @var Group $pools */ + $pools = $register->get('pools'); + + $adapters = []; + foreach (Config::getParam('pools-cache', []) as $value) { + $adapters[] = new CachePool($pools->get($value)); + } + + return $ctx['cache'] = new Cache(new Sharding($adapters)); + } +} + +if (!function_exists('getConsoleDB')) { + function getConsoleDB(): Database + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['dbForPlatform'])) { + return $ctx['dbForPlatform']; + } + + global $register; + + /** @var Group $pools */ + $pools = $register->get('pools'); + + $adapter = new DatabasePool($pools->get('console')); + $database = new Database($adapter, getCache()); + $database + ->setDatabase(APP_DATABASE) + ->setNamespace('_console') + ->setMetadata('host', \gethostname()) + ->setMetadata('project', '_console'); + $database->setDocumentType('users', User::class); + + return $ctx['dbForPlatform'] = $database; + } +} + +if (!function_exists('getProjectDB')) { + function getProjectDB(Document $project): Database + { + $ctx = Coroutine::getContext(); + + if (!isset($ctx['dbForProject'])) { + $ctx['dbForProject'] = []; + } + + if (isset($ctx['dbForProject'][$project->getSequence()])) { + return $ctx['dbForProject'][$project->getSequence()]; + } + + if ($project->isEmpty() || $project->getId() === 'console') { + return getConsoleDB(); + } + + global $register; + + /** @var Group $pools */ + $pools = $register->get('pools'); + + try { + $dsn = new DSN($project->getAttribute('database')); + } catch (\InvalidArgumentException) { + $dsn = new DSN('mysql://' . $project->getAttribute('database')); + } + + $adapter = new DatabasePool($pools->get($dsn->getHost())); + $database = new Database($adapter, getCache()); + + $sharedTables = \explode(',', System::getEnv('_APP_DATABASE_SHARED_TABLES', '')); + + if (\in_array($dsn->getHost(), $sharedTables)) { + $projectCollections = Config::getParam('collections', [])['projects'] ?? []; + $globalCollections = array_keys($projectCollections); + $globalCollections[] = 'audit'; + + $database + ->setSharedTables(true) + ->setGlobalCollections($globalCollections) + ->setTenant($project->getSequence()) + ->setNamespace($dsn->getParam('namespace')); + } else { + $database + ->setSharedTables(false) + ->setTenant(null) + ->setNamespace('_' . $project->getSequence()); + } + + $database + ->setDatabase(APP_DATABASE) + ->setMetadata('host', \gethostname()) + ->setMetadata('project', $project->getId()); + $database->setDocumentType('users', User::class); + + return $ctx['dbForProject'][$project->getSequence()] = $database; + } +} + +/** + * Authenticate a CONNECT: resolve the project and verify the session in a child + * container, using the same domain logic as HTTP/realtime. Returns the identity + * for the connection, or an empty array when the credential is invalid. + * + * @return array{projectId: string, userId: string}|array{} + */ +$authenticate = function (string $projectId, string $secret) use ($container, $registerMqttConnectionResources): array { + $connectionContainer = new Container($container); + $connectionContainer->set('projectId', fn () => $projectId); + $connectionContainer->set('sessionSecret', fn () => $secret); + + $registerMqttConnectionResources($connectionContainer); + + /** @var Document $project */ + $project = $connectionContainer->get('project'); + /** @var User $user */ + $user = $connectionContainer->get('user'); + + if ($project->isEmpty() || $user->isEmpty()) { + return []; + } + + return [ + 'projectId' => $project->getId(), + 'userId' => $user->getId(), + ]; +}; + +$broker = new Broker(host: '0.0.0.0', port: 1883); +$broker->onConnect($authenticate); $broker->start(); From 849264c115f56d9cb7990b29fa5f8d846e891ab7 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 13:51:21 +0530 Subject: [PATCH 011/146] fix(mqtt): bind authorization so the project resolves MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit getConsoleDB() returns a Database with its own Authorization instance, so $authorization->skip() was toggling a different object than the one the read checks against — the permission-filtered projects lookup came back empty. Bind the same Authorization before skipping, matching the user resolver. --- app/init/mqtt/connection.php | 1 + 1 file changed, 1 insertion(+) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 762207fe09..0cfe2339f4 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -19,6 +19,7 @@ return function (Container $container): void { } $dbForPlatform = getConsoleDB(); + $dbForPlatform->setAuthorization($authorization); return $authorization->skip(fn () => $dbForPlatform->getDocument('projects', $projectId)); }, ['projectId', 'console', 'authorization']); From 04dbaeefb4de7705ff8dc6f2734df67f4dd3a048 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 13:51:34 +0530 Subject: [PATCH 012/146] feat(mqtt): authenticate by auth method and support JWT credentials Thread the CONNECT Authentication Method through the authenticator seam (projectId, authMethod, credential) so the resolver can pick how to read the credential. On "appwrite-jwt" the user factory decodes the HS256 JWT with _APP_OPENSSL_KEY_V1 and checks the session is still active; otherwise it Store-decodes the session blob and runs sessionVerify. Reauth passes the method through the same way. Rename the connection credential from sessionSecret. --- app/init/mqtt/connection.php | 41 ++++++++++++++++++++++++++++-------- app/mqtt.php | 5 +++-- src/Utopia/Mqtt/Broker.php | 8 +++---- 3 files changed, 39 insertions(+), 15 deletions(-) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 0cfe2339f4..50d8cdaf85 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -1,5 +1,7 @@ set('authorization', function () { @@ -24,24 +27,44 @@ return function (Container $container): void { return $authorization->skip(fn () => $dbForPlatform->getDocument('projects', $projectId)); }, ['projectId', 'console', 'authorization']); - $container->set('user', function (Document $project, string $sessionSecret, Authorization $authorization) { - if ($project->isEmpty() || $sessionSecret === '') { + $container->set('user', function (Document $project, string $authMethod, string $credential, Authorization $authorization) { + if ($project->isEmpty() || $credential === '') { return new User([]); } $authorization->setDefaultStatus(true); - // The session secret arrives as the same Store-encoded "id:secret" blob the - // SDK sends over x-appwrite-session; decode it to recover both halves. + $dbForProject = getProjectDB($project); + $dbForProject->setAuthorization($authorization); + + if ($authMethod === 'appwrite-jwt') { + $jwt = new JWT(System::getEnv('_APP_OPENSSL_KEY_V1'), 'HS256', 3600, 0); + + try { + $payload = $jwt->decode($credential); + } catch (JWTException) { + return new User([]); + } + + $userId = $payload['userId'] ?? ''; + $sessionId = $payload['sessionId'] ?? ''; + + /** @var User $user */ + $user = $dbForProject->getDocument('users', $userId); + + if ($user->isEmpty() || ($sessionId !== '' && !$user->sessionActive($sessionId))) { + return new User([]); + } + + return $user; + } + $store = new Store(); - $store->decode($sessionSecret); + $store->decode($credential); $proofForToken = new Token(); $proofForToken->setHash(new Sha()); - $dbForProject = getProjectDB($project); - $dbForProject->setAuthorization($authorization); - /** @var User $user */ $user = $dbForProject->getDocument('users', $store->getProperty('id', '')); @@ -53,5 +76,5 @@ return function (Container $container): void { } return $user; - }, ['project', 'sessionSecret', 'authorization']); + }, ['project', 'authMethod', 'credential', 'authorization']); }; diff --git a/app/mqtt.php b/app/mqtt.php index 3446c6b9a7..321f97a5b5 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -157,10 +157,11 @@ if (!function_exists('getProjectDB')) { * * @return array{projectId: string, userId: string}|array{} */ -$authenticate = function (string $projectId, string $secret) use ($container, $registerMqttConnectionResources): array { +$authenticate = function (string $projectId, string $authMethod, string $credential) use ($container, $registerMqttConnectionResources): array { $connectionContainer = new Container($container); $connectionContainer->set('projectId', fn () => $projectId); - $connectionContainer->set('sessionSecret', fn () => $secret); + $connectionContainer->set('authMethod', fn () => $authMethod); + $connectionContainer->set('credential', fn () => $credential); $registerMqttConnectionResources($connectionContainer); diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 27c0b1fb29..8b3afd3db4 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -46,7 +46,7 @@ class Broker /** * - * @var (callable(string, string): array)|null + * @var (callable(string, string, string): array)|null */ private $authenticator = null; @@ -60,7 +60,7 @@ class Broker * Register the CONNECT authenticator. Without one the broker accepts every * connection (raw protocol testing). * - * @param callable(string, string): array $authenticator + * @param callable(string, string, string): array $authenticator */ public function onConnect(callable $authenticator): void { @@ -120,7 +120,7 @@ class Broker // TODO: add abuse limiting keyed on the client ip. if ($this->authenticator !== null) { - $identity = ($this->authenticator)($projectId, $properties['authData']); + $identity = ($this->authenticator)($projectId, $properties['authMethod'], $properties['authData']); if ($identity === []) { $this->sendConnack($server, $fd, $level, self::REASON_NOT_AUTHORIZED); @@ -250,7 +250,7 @@ class Broker $projectId = $userProperties['projectId'] ?? ''; $identity = ($projectId !== '' && $projectId === ($this->project[$fd] ?? '')) - ? ($this->authenticator)($projectId, $data) + ? ($this->authenticator)($projectId, $method, $data) : []; if ($identity === []) { From 505bd4433f0fed0ccc6d4eef96fbfabbe714edda Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 15:53:29 +0530 Subject: [PATCH 013/146] feat(mqtt): implement QoS 1 for PUBLISH and add packet ID management --- src/Utopia/Mqtt/Broker.php | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 8b3afd3db4..347619940a 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -27,6 +27,8 @@ class Broker private const AUTH_CONTINUE = 0x18; private const AUTH_REAUTH = 0x19; + private const QOS_1 = 1; + // Property identifiers, shared between CONNECT and AUTH property blocks. private const PROP_AUTH_METHOD = 0x15; private const PROP_AUTH_DATA = 0x16; @@ -44,6 +46,9 @@ class Broker /** @var array> fd => resolved identity (project/user ids) */ private array $identity = []; + /** @var array fd => last outbound packet id (QoS 1 delivery) */ + private array $packetId = []; + /** * * @var (callable(string, string, string): array)|null @@ -95,6 +100,7 @@ class Broker self::SUBSCRIBE => $this->handleSubscribe($server, $fd, $body), self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), + self::PUBACK => null, self::AUTH => $this->handleAuth($server, $fd, $body), self::PINGREQ => $server->send($fd, chr(self::PINGRESP << 4) . $this->encodeLength(0)), self::DISCONNECT => $server->close($fd), @@ -197,7 +203,7 @@ class Broker [$filter, $offset] = $this->readString($body, $offset); $offset += 1; // subscription options byte $this->subscriptions[$fd][$filter] = true; - $granted .= chr(self::REASON_SUCCESS); // granted QoS 0 + $granted .= chr(self::QOS_1); // granted max QoS 1 } // SUBACK: packet id (+ property length 0 for v5) + granted codes @@ -313,17 +319,30 @@ class Broker foreach ($this->subscriptions as $fd => $filters) { foreach ($filters as $filter => $_) { if ($this->matches($filter, $topic)) { + $packetId = $this->getNextPacketId($fd); + // Variable header order: topic, packet id (QoS > 0), properties (v5), payload. $variable = $this->encodeString($topic) + . chr($packetId >> 8) . chr($packetId & 0xFF) . (($this->protocol[$fd] ?? 4) >= 5 ? $this->encodeLength(0) : '') . $payload; - // PUBLISH, QoS 0 - $server->send($fd, chr(self::PUBLISH << 4) . $this->encodeLength(strlen($variable)) . $variable); + // PUBLISH, QoS 1 (flags = QoS << 1) + $header = chr((self::PUBLISH << 4) | (self::QOS_1 << 1)); + $server->send($fd, $header . $this->encodeLength(strlen($variable)) . $variable); break; // one copy per subscriber even if several filters match } } } } + /** Next per-connection outbound packet id, wrapping 1..65535 (0 is not allowed). */ + private function getNextPacketId(int $fd): int + { + $next = (($this->packetId[$fd] ?? 0) % 0xFFFF) + 1; + $this->packetId[$fd] = $next; + + return $next; + } + private function onClose(Server $server, int $fd): void { unset( @@ -331,6 +350,7 @@ class Broker $this->protocol[$fd], $this->project[$fd], $this->identity[$fd], + $this->packetId[$fd], ); } From cfe4fa22a3433ed182962f0393ee3d28bdedebdf Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 24 Aug 2026 19:31:35 +0530 Subject: [PATCH 014/146] added subscription store --- src/Utopia/Mqtt/SubscriptionStore.php | 85 +++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 src/Utopia/Mqtt/SubscriptionStore.php diff --git a/src/Utopia/Mqtt/SubscriptionStore.php b/src/Utopia/Mqtt/SubscriptionStore.php new file mode 100644 index 0000000000..3a6525db61 --- /dev/null +++ b/src/Utopia/Mqtt/SubscriptionStore.php @@ -0,0 +1,85 @@ +nodes[$nodeName]); + } + public function addNode(string $nodeKey, Node $value){ + $this->nodes[$nodeKey] = $value; + } +} + +class SubscriptionStore{ + /** @var array subId => record */ + private array $subscriptions = []; + /** @var array> fd => set of subIds (onClose cleanup) */ + private array $byFd = []; + private Node $root; + + public function __construct() { + $this->root = new Node(); + } + public function upsert(string $projectId, string $userId, string $subId, string $topic, int $fd){ + if(isset($this->subscriptions[$subId])){ + $oldTopic = $this->subscriptions[$subId]['topic']; + $this->delete($projectId, $userId, $oldTopic, $subId); + } + $nodes = [$projectId,...explode("/", $topic)]; + $parent = $this->root; + foreach ($nodes as $index => $node) { + if(!$parent->hasNode($node)) $parent->addNode($node, new Node()); + $parent = $parent->nodes[$node]; + if($index === count($nodes) - 1) array_push($parent->subId , $subId); + } + $this->subscriptions[$subId] = [ + 'projectId' => $projectId, + 'userId' => $userId, + 'topic' => $topic, + 'fd' => $fd, + ]; + $this->byFd[$fd][$subId] = true; + } + public function delete(string $projectId, string $userId, string $oldTopic, string $subId){ + $nodes = [$projectId,...explode("/", $oldTopic)]; + $parent = $this->root; + foreach ($nodes as $index => $node) { + if(!$parent->hasNode($node)) break; + $parent = $parent->nodes[$node]; + if($index === count($nodes) - 1){ + if (($key = array_search($subId, $parent->subId)) !== false) { + unset($parent->subId[$key]); + } + }; + } + $fd = $this->subscriptions[$subId]['fd'] ?? null; + unset($this->subscriptions[$subId]); + if($fd !== null){ + unset($this->byFd[$fd][$subId]); + if(empty($this->byFd[$fd])) unset($this->byFd[$fd]); + } + } + public function removeConnection(int $fd){ + foreach(array_keys($this->byFd[$fd] ?? []) as $subId){ + $record = $this->subscriptions[$subId]; + $this->delete($record['projectId'], $record['userId'], $record['topic'], $subId); + } + } + public function hasSubscribers(string $projectId , string $topic) : array | null{ + $nodes = [$projectId,...explode("/", $topic)]; + $parent = $this->root; + foreach ($nodes as $index => $node) { + if(!($parent->hasNode($node) || $parent->hasNode('+'))) { + return null; + } + $parent = $parent->nodes[$node]; + if($index === count($nodes) - 1){ + return $parent->subId; + }; + } + return null; + } +} \ No newline at end of file From bb02dcaceea640038dd6587f62f07bd2ee67155a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 16:05:24 +0530 Subject: [PATCH 015/146] feat - added trie based subscription store --- src/Utopia/Mqtt/SubscriptionStore.php | 229 ++++++++++++++++++-------- 1 file changed, 164 insertions(+), 65 deletions(-) diff --git a/src/Utopia/Mqtt/SubscriptionStore.php b/src/Utopia/Mqtt/SubscriptionStore.php index 3a6525db61..2a744d7b44 100644 --- a/src/Utopia/Mqtt/SubscriptionStore.php +++ b/src/Utopia/Mqtt/SubscriptionStore.php @@ -1,85 +1,184 @@ child segments keyed by topic level */ + public array $nodes = []; + /** @var array fd => granted QoS for the subscription ending at this node */ + public array $fds = []; + + public function hasNode(string $nodeName) + { return isset($this->nodes[$nodeName]); } - public function addNode(string $nodeKey, Node $value){ - $this->nodes[$nodeKey] = $value; + public function addNode(string $nodeKey, Node $value) + { + $this->nodes[$nodeKey] = $value; } } -class SubscriptionStore{ - /** @var array subId => record */ - private array $subscriptions = []; - /** @var array> fd => set of subIds (onClose cleanup) */ - private array $byFd = []; +class SubscriptionStore +{ + /** + * fd => connection record + * + * @var array}> + */ + private array $connections = []; + + /** + * + * [ROOT] -> + * [PROJECT_ID] -> + * [LEVEL_0] -> e.g. 'test', '+' + * [LEVEL_1] -> e.g. 'hello', '+', '#' + * fds: [FD => QOS, ...] + * + * Example —> subs `test/hello` (fd 11) and `test/#` (fd 12) under project P: + * + * [ROOT] -> [P] -> ['test'] -> ['hello'] -> fds: [11 => 1] + * -> ['#'] -> fds: [12 => 1] + */ private Node $root; - public function __construct() { + public function __construct() + { $this->root = new Node(); } - public function upsert(string $projectId, string $userId, string $subId, string $topic, int $fd){ - if(isset($this->subscriptions[$subId])){ - $oldTopic = $this->subscriptions[$subId]['topic']; - $this->delete($projectId, $userId, $oldTopic, $subId); + + public function subscribe(string $projectId, string $userId, string $subId, string $topic, int $fd, int $qos = 1) + { + if (isset($this->connections[$fd]['subs'][$subId])) { + $this->unsubscribe($subId, $fd); } - $nodes = [$projectId,...explode("/", $topic)]; + + $nodes = [$projectId, ...explode("/", $topic)]; $parent = $this->root; foreach ($nodes as $index => $node) { - if(!$parent->hasNode($node)) $parent->addNode($node, new Node()); - $parent = $parent->nodes[$node]; - if($index === count($nodes) - 1) array_push($parent->subId , $subId); - } - $this->subscriptions[$subId] = [ - 'projectId' => $projectId, - 'userId' => $userId, - 'topic' => $topic, - 'fd' => $fd, - ]; - $this->byFd[$fd][$subId] = true; - } - public function delete(string $projectId, string $userId, string $oldTopic, string $subId){ - $nodes = [$projectId,...explode("/", $oldTopic)]; - $parent = $this->root; - foreach ($nodes as $index => $node) { - if(!$parent->hasNode($node)) break; - $parent = $parent->nodes[$node]; - if($index === count($nodes) - 1){ - if (($key = array_search($subId, $parent->subId)) !== false) { - unset($parent->subId[$key]); - } - }; - } - $fd = $this->subscriptions[$subId]['fd'] ?? null; - unset($this->subscriptions[$subId]); - if($fd !== null){ - unset($this->byFd[$fd][$subId]); - if(empty($this->byFd[$fd])) unset($this->byFd[$fd]); - } - } - public function removeConnection(int $fd){ - foreach(array_keys($this->byFd[$fd] ?? []) as $subId){ - $record = $this->subscriptions[$subId]; - $this->delete($record['projectId'], $record['userId'], $record['topic'], $subId); - } - } - public function hasSubscribers(string $projectId , string $topic) : array | null{ - $nodes = [$projectId,...explode("/", $topic)]; - $parent = $this->root; - foreach ($nodes as $index => $node) { - if(!($parent->hasNode($node) || $parent->hasNode('+'))) { - return null; + if (!$parent->hasNode($node)) { + $parent->addNode($node, new Node()); } $parent = $parent->nodes[$node]; - if($index === count($nodes) - 1){ - return $parent->subId; - }; + if ($index === count($nodes) - 1) { + $parent->fds[$fd] = $qos; + } } - return null; + + if (!isset($this->connections[$fd])) { + $this->connections[$fd] = [ + 'projectId' => $projectId, + 'userId' => $userId, + 'subs' => [], + ]; + } + $this->connections[$fd]['subs'][$subId] = ['topic' => $topic, 'qos' => $qos]; } -} \ No newline at end of file + + public function unsubscribe(string $subId, int $fd) + { + $topic = $this->connections[$fd]['subs'][$subId]['topic'] ?? null; + if ($topic === null) { + return; + } + + $projectId = $this->connections[$fd]['projectId']; + $nodes = [$projectId, ...explode("/", $topic)]; + + $path = []; + $parent = $this->root; + foreach ($nodes as $node) { + if (!$parent->hasNode($node)) { + $parent = null; + break; + } + $path[] = [$parent, $node]; + $parent = $parent->nodes[$node]; + } + + // pruning the dead topic + if ($parent !== null) { + unset($parent->fds[$fd]); + + for ($i = count($path) - 1; $i >= 0; $i--) { + [$parentNode, $key] = $path[$i]; + $child = $parentNode->nodes[$key]; + if (empty($child->nodes) && empty($child->fds)) { + unset($parentNode->nodes[$key]); + } else { + break; + } + } + } + + unset($this->connections[$fd]['subs'][$subId]); + if (empty($this->connections[$fd]['subs'])) { + unset($this->connections[$fd]); + } + } + + public function close(int $fd) + { + foreach (array_keys($this->connections[$fd]['subs'] ?? []) as $subId) { + $this->unsubscribe($subId, $fd); + } + unset($this->connections[$fd]); + } + + /** + * + * @return array fd => granted QoS + */ + public function getSubscribers(string $projectId, string $topic): array + { + $nodes = [$projectId, ...explode("/", $topic)]; + + $current = [$this->root]; + $fds = []; + + $collect = function (Node $node) use (&$fds): void { + foreach ($node->fds as $fd => $qos) { + $fds[$fd] = max($fds[$fd] ?? 0, $qos); + } + }; + + foreach ($nodes as $node) { + $next = []; + + foreach ($current as $parent) { + // # matches everything from this level onward + if ($parent->hasNode('#')) { + $collect($parent->nodes['#']); + } + + // exact match + if ($parent->hasNode($node)) { + $next[] = $parent->nodes[$node]; + } + + // + matches exactly one level + if ($parent->hasNode('+')) { + $next[] = $parent->nodes['+']; + } + } + + $current = $next; + + if (empty($current)) { + break; + } + } + + foreach ($current as $parent) { + $collect($parent); + + // a trailing #, e.g. sub `a/#` matching publish `a` + if ($parent->hasNode('#')) { + $collect($parent->nodes['#']); + } + } + + return $fds; + } +} From 6d7171a45ce99ab7befa06e5feb8fa76400ef218 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 16:05:39 +0530 Subject: [PATCH 016/146] unit tests for the subscription store --- .../Utopia/Mqtt/SubscriptionStoreTest.php | 169 ++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php diff --git a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php new file mode 100644 index 0000000000..7cd9644843 --- /dev/null +++ b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php @@ -0,0 +1,169 @@ +store = new SubscriptionStore(); + } + + /** + * @return array + */ + public static function matchProvider(): array + { + return [ + // filter, publish topic, should match + 'exact single level' => ['sport', 'sport', true], + 'exact rejects deeper' => ['sport', 'sport/x', false], + 'exact rejects sibling' => ['a/b', 'a/c', false], + + '+ matches one level' => ['sport/+', 'sport/x', true], + '+ requires a level' => ['sport/+', 'sport', false], + '+ does not span two levels' => ['sport/+', 'sport/x/y', false], + '+ leading level' => ['+/hello', 'test/hello', true], + '+ leading needs a level' => ['+/hello', 'hello', false], + '+ interior level' => ['test/+/x', 'test/a/x', true], + '+ interior is single level' => ['test/+/x', 'test/a/b/x', false], + + '# matches parent level' => ['sport/#', 'sport', true], + '# matches one deeper' => ['sport/#', 'sport/x', true], + '# matches many deeper' => ['sport/#', 'sport/x/y', true], + 'root # matches everything' => ['#', 'a/b/c', true], + ]; + } + + #[DataProvider('matchProvider')] + public function testWildcardMatching(string $filter, string $topic, bool $shouldMatch): void + { + $this->store->subscribe(self::PROJECT, 'user', 'sub', $filter, 1, 1); + + $subscribers = $this->store->getSubscribers(self::PROJECT, $topic); + + $this->assertSame($shouldMatch, \array_key_exists(1, $subscribers)); + } + + public function testNoSubscribersReturnsEmpty(): void + { + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + + $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'nope')); + } + + public function testReturnsGrantedQos(): void + { + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + + $this->assertSame([1 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); + } + + public function testFanOutToMultipleConnections(): void + { + $this->store->subscribe(self::PROJECT, 'user', 'a', 'test/+', 11, 1); + $this->store->subscribe(self::PROJECT, 'user', 'b', 'test/#', 12, 1); + $this->store->subscribe(self::PROJECT, 'user', 'c', 'test/hello', 13, 1); + + $subscribers = $this->store->getSubscribers(self::PROJECT, 'test/hello'); + + \ksort($subscribers); + $this->assertSame([11 => 1, 12 => 1, 13 => 1], $subscribers); + } + + public function testConnectionMatchedByTwoFiltersIsDedupedToHighestQos(): void + { + // Same fd matched by an exact (QoS 0) and a wildcard (QoS 1) subscription. + $this->store->subscribe(self::PROJECT, 'user', 'exact', 'test/hello', 7, 0); + $this->store->subscribe(self::PROJECT, 'user', 'wild', 'test/#', 7, 1); + + $subscribers = $this->store->getSubscribers(self::PROJECT, 'test/hello'); + + $this->assertSame([7 => 1], $subscribers); + } + + public function testResubscribeSameFilterReplacesGrantedQos(): void + { + // MQTT 3.8.4: re-subscribing the same (connection, subId) replaces the grant. + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 0); + + $this->assertSame([1 => 0], $this->store->getSubscribers(self::PROJECT, 'test/hello')); + } + + public function testResubscribeToNewTopicDropsOldTopic(): void + { + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/world', 1, 1); + + $this->assertArrayNotHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/hello')); + $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/world')); + } + + public function testProjectIsolation(): void + { + $this->store->subscribe('projectA', 'user', 'sub', 'test/hello', 1, 1); + $this->store->subscribe('projectB', 'user', 'sub', 'test/hello', 2, 1); + + $this->assertSame([1 => 1], $this->store->getSubscribers('projectA', 'test/hello')); + $this->assertSame([2 => 1], $this->store->getSubscribers('projectB', 'test/hello')); + } + + public function testUnsubscribeRemovesOnlyThatSubscription(): void + { + // One connection, two subscriptions under different subIds. + $this->store->subscribe(self::PROJECT, 'user', 'first', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'second', 'test/world', 1, 1); + + $this->store->unsubscribe('first', 1); + + $this->assertArrayNotHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/hello')); + $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/world')); + } + + public function testUnsubscribeUnknownSubIsNoop(): void + { + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + + $this->store->unsubscribe('missing', 1); + $this->store->unsubscribe('sub', 999); + + $this->assertSame([1 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); + } + + public function testUnsubscribeThenTopicNoLongerMatchesWildcard(): void + { + // Covers pruning behaviour observably: after the only subscriber leaves, a + // wildcard publish that used to match returns nothing. + $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/deep/leaf', 1, 1); + $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); + + $this->store->unsubscribe('sub', 1); + + $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); + $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); + } + + public function testCloseRemovesEverySubscriptionForConnection(): void + { + $this->store->subscribe(self::PROJECT, 'user', 'first', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'second', 'other/#', 1, 1); + // A second connection that must survive the close. + $this->store->subscribe(self::PROJECT, 'user', 'keep', 'test/hello', 2, 1); + + $this->store->close(1); + + $this->assertSame([2 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); + $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'other/x')); + } +} From 2e3e3e667e12b66adee1fb34253894796fad14da Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 16:06:01 +0530 Subject: [PATCH 017/146] integrated the subscription inside the broker for subscription management --- src/Utopia/Mqtt/Broker.php | 83 ++++++++++++++------------------------ 1 file changed, 30 insertions(+), 53 deletions(-) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 347619940a..5c90aa6559 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -24,8 +24,8 @@ class Broker private const REASON_SUCCESS = 0x00; private const REASON_NOT_AUTHORIZED = 0x87; private const AUTH_SUCCESS = 0x00; - private const AUTH_CONTINUE = 0x18; - private const AUTH_REAUTH = 0x19; + private const AUTH_CONTINUE = 0x18; // @phpstan-ignore classConstant.unused (reserved for multi-round continue-auth) + private const AUTH_REAUTH = 0x19; // @phpstan-ignore classConstant.unused (reserved for the reauth flow) private const QOS_1 = 1; @@ -40,8 +40,8 @@ class Broker /** @var array fd => project id (from a CONNECT User Property) */ private array $project = []; - /** @var array> fd => set of subscribed topic filters */ - private array $subscriptions = []; + /** Bidirectional subscription index: fd <-> project-scoped topic trie. */ + private SubscriptionStore $subscriptions; /** @var array> fd => resolved identity (project/user ids) */ private array $identity = []; @@ -59,6 +59,7 @@ class Broker private readonly string $host = '0.0.0.0', private readonly int $port = 1883, ) { + $this->subscriptions = new SubscriptionStore(); } /** @@ -196,16 +197,20 @@ class Broker $offset = 0; $packetId = substr($body, 0, 2); $offset += 2; + + $subId = $this->getProperties($fd, $body, $offset)['user']['subId'] ?? ''; $offset = $this->skipProperties($fd, $body, $offset); + $projectId = $this->project[$fd] ?? ''; + $userId = $this->identity[$fd]['userId'] ?? ''; + $granted = ''; while ($offset < strlen($body)) { [$filter, $offset] = $this->readString($body, $offset); $offset += 1; // subscription options byte - $this->subscriptions[$fd][$filter] = true; + $this->subscriptions->subscribe($projectId, $userId, $subId ?: $filter, $filter, $fd, self::QOS_1); $granted .= chr(self::QOS_1); // granted max QoS 1 } - // SUBACK: packet id (+ property length 0 for v5) + granted codes $variable = $packetId . ($this->protocol[$fd] >= 5 ? $this->encodeLength(0) : '') . $granted; $server->send($fd, chr(self::SUBACK << 4) . $this->encodeLength(strlen($variable)) . $variable); @@ -216,12 +221,14 @@ class Broker $offset = 0; $packetId = substr($body, 0, 2); $offset += 2; + + $subId = $this->getProperties($fd, $body, $offset)['user']['subId'] ?? ''; $offset = $this->skipProperties($fd, $body, $offset); $count = 0; while ($offset < strlen($body)) { [$filter, $offset] = $this->readString($body, $offset); - unset($this->subscriptions[$fd][$filter]); + $this->subscriptions->unsubscribe($subId ?: $filter, $fd); $count++; } @@ -306,32 +313,29 @@ class Broker $offset = $this->skipProperties($fd, $body, $offset); $payload = substr($body, $offset); - $this->deliver($server, $topic, $payload); + foreach ($this->subscriptions->getSubscribers($this->project[$fd] ?? '', $topic) as $subscriberFd => $grantedQos) { + $this->send($server, $subscriberFd, $topic, $payload, min($qos, $grantedQos)); + } - if ($qos === 1 && $packetId !== null) { + if ($qos === 1) { // PUBACK: packet id (reason/properties omitted -> valid for both versions) $server->send($fd, chr(self::PUBACK << 4) . $this->encodeLength(strlen($packetId)) . $packetId); } } - private function deliver(Server $server, string $topic, string $payload): void + private function send(Server $server, int $fd, string $topic, string $payload, int $qos): void { - foreach ($this->subscriptions as $fd => $filters) { - foreach ($filters as $filter => $_) { - if ($this->matches($filter, $topic)) { - $packetId = $this->getNextPacketId($fd); - // Variable header order: topic, packet id (QoS > 0), properties (v5), payload. - $variable = $this->encodeString($topic) - . chr($packetId >> 8) . chr($packetId & 0xFF) - . (($this->protocol[$fd] ?? 4) >= 5 ? $this->encodeLength(0) : '') - . $payload; - // PUBLISH, QoS 1 (flags = QoS << 1) - $header = chr((self::PUBLISH << 4) | (self::QOS_1 << 1)); - $server->send($fd, $header . $this->encodeLength(strlen($variable)) . $variable); - break; // one copy per subscriber even if several filters match - } - } + // Variable header order: topic, packet id (QoS > 0), properties (v5), payload. + $variable = $this->encodeString($topic); + if ($qos > 0) { + $packetId = $this->getNextPacketId($fd); + $variable .= chr($packetId >> 8) . chr($packetId & 0xFF); } + $variable .= ((($this->protocol[$fd] ?? 4) >= 5 ? $this->encodeLength(0) : '')) . $payload; + + // PUBLISH, flags = QoS << 1 + $header = chr((self::PUBLISH << 4) | ($qos << 1)); + $server->send($fd, $header . $this->encodeLength(strlen($variable)) . $variable); } /** Next per-connection outbound packet id, wrapping 1..65535 (0 is not allowed). */ @@ -345,8 +349,8 @@ class Broker private function onClose(Server $server, int $fd): void { + $this->subscriptions->close($fd); unset( - $this->subscriptions[$fd], $this->protocol[$fd], $this->project[$fd], $this->identity[$fd], @@ -354,33 +358,6 @@ class Broker ); } - /** - * MQTT topic filter matching with '+' (single level) and '#' (multi level). - */ - private function matches(string $filter, string $topic): bool - { - if ($filter === $topic) { - return true; - } - - $filterParts = explode('/', $filter); - $topicParts = explode('/', $topic); - - foreach ($filterParts as $i => $part) { - if ($part === '#') { - return true; - } - if (!isset($topicParts[$i])) { - return false; - } - if ($part !== '+' && $part !== $topicParts[$i]) { - return false; - } - } - - return count($filterParts) === count($topicParts); - } - /** * Skip the MQTT 5.0 property block (variable-length length prefix + bytes). * No-op for MQTT 3.1.1, which has no properties. From e6d691809a095083e58907431070bf780a59335c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 17:29:14 +0530 Subject: [PATCH 018/146] updated the messaging package to use the appwrite push poc adapter from the monorepo --- composer.json | 29 +++++++++++++++++++++++ composer.lock | 65 +++++++++++++++------------------------------------ 2 files changed, 48 insertions(+), 46 deletions(-) diff --git a/composer.json b/composer.json index b092512466..0f15f694f5 100644 --- a/composer.json +++ b/composer.json @@ -66,6 +66,35 @@ } } }, + { + "type": "package", + "package": { + "name": "utopia-php/messaging", + "version": "2.1.999", + "source": { + "url": "https://github.com/utopia-php/monorepo.git", + "type": "git", + "reference": "appwrite-mqtt-poc" + }, + "autoload": { + "psr-4": { + "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" + } + }, + "require": { + "php": ">=8.5.0", + "ext-curl": "*", + "ext-openssl": "*", + "ext-swoole": "*", + "psr/http-client": "^1.0", + "psr/http-message": "^1.1 || ^2.0", + "utopia-php/client": "^0.3", + "utopia-php/pools": "^2.0", + "utopia-php/smtp": "^0.1", + "utopia-php/telemetry": "^0.4" + } + } + }, { "type": "vcs", "url": "https://github.com/utopia-php/auth" diff --git a/composer.lock b/composer.lock index 5a75f74711..712685a0cb 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "4fd078c5f4c652e6b07c639e275b520c", + "content-hash": "69ee43671963861ad7266732f31d62b4", "packages": [ { "name": "adhocore/jwt", @@ -609,23 +609,23 @@ }, { "name": "google/protobuf", - "version": "v5.35.1", + "version": "v5.36.0", "source": { "type": "git", "url": "https://github.com/protocolbuffers/protobuf-php.git", - "reference": "55bb4a7d6739b5af0927b96213c1371a3afb7cfb" + "reference": "9c105104b54709ecd902494ab340ed2122789b2d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/55bb4a7d6739b5af0927b96213c1371a3afb7cfb", - "reference": "55bb4a7d6739b5af0927b96213c1371a3afb7cfb", + "url": "https://api.github.com/repos/protocolbuffers/protobuf-php/zipball/9c105104b54709ecd902494ab340ed2122789b2d", + "reference": "9c105104b54709ecd902494ab340ed2122789b2d", "shasum": "" }, "require": { "php": ">=8.2.0" }, "require-dev": { - "phpunit/phpunit": ">=11.5.0 <12.0.0" + "phpunit/phpunit": ">=11.5.50 <12.0.0" }, "suggest": { "ext-bcmath": "Need to support JSON deserialization" @@ -647,9 +647,9 @@ "proto" ], "support": { - "source": "https://github.com/protocolbuffers/protobuf-php/tree/v5.35.1" + "source": "https://github.com/protocolbuffers/protobuf-php/tree/v5.36.0" }, - "time": "2026-06-11T21:19:23+00:00" + "time": "2026-08-20T13:06:50+00:00" }, { "name": "halaxa/json-machine", @@ -2289,16 +2289,16 @@ }, { "name": "symfony/http-client", - "version": "v7.4.16", + "version": "v7.4.17", "source": { "type": "git", "url": "https://github.com/symfony/http-client.git", - "reference": "c513ed0ba5d1784a6b55fc84190dbe4451b12f41" + "reference": "d0aca330a822fe40376cd04c335cb48a24743d0c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/http-client/zipball/c513ed0ba5d1784a6b55fc84190dbe4451b12f41", - "reference": "c513ed0ba5d1784a6b55fc84190dbe4451b12f41", + "url": "https://api.github.com/repos/symfony/http-client/zipball/d0aca330a822fe40376cd04c335cb48a24743d0c", + "reference": "d0aca330a822fe40376cd04c335cb48a24743d0c", "shasum": "" }, "require": { @@ -2366,7 +2366,7 @@ "http" ], "support": { - "source": "https://github.com/symfony/http-client/tree/v7.4.16" + "source": "https://github.com/symfony/http-client/tree/v7.4.17" }, "funding": [ { @@ -2386,7 +2386,7 @@ "type": "tidelift" } ], - "time": "2026-07-29T16:20:51+00:00" + "time": "2026-08-21T17:40:08+00:00" }, { "name": "symfony/http-client-contracts", @@ -4229,17 +4229,11 @@ }, { "name": "utopia-php/messaging", - "version": "2.1.0", + "version": "2.1.999", "source": { "type": "git", - "url": "https://github.com/utopia-php/messaging.git", - "reference": "58b1ae43b35d72901907901d2ff73f1599cefc20" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/messaging/zipball/58b1ae43b35d72901907901d2ff73f1599cefc20", - "reference": "58b1ae43b35d72901907901d2ff73f1599cefc20", - "shasum": "" + "url": "https://github.com/utopia-php/monorepo.git", + "reference": "appwrite-mqtt-poc" }, "require": { "ext-curl": "*", @@ -4253,33 +4247,12 @@ "utopia-php/smtp": "^0.1", "utopia-php/telemetry": "^0.4" }, - "require-dev": { - "swoole/ide-helper": "^6.0" - }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Messaging\\": "src/Utopia/Messaging" + "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "description": "A simple, light and advanced PHP messaging library", - "keywords": [ - "library", - "messaging", - "php", - "upf", - "utopia", - "utopia-php" - ], - "support": { - "issues": "https://github.com/utopia-php/messaging/issues", - "source": "https://github.com/utopia-php/messaging/tree/2.1.0" - }, - "time": "2026-08-13T21:35:53+00:00" + } }, { "name": "utopia-php/migration", From e208a06160a44e65b0edd9bcadcba26e071cb234 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 17:29:21 +0530 Subject: [PATCH 019/146] added e2e tests --- .../Messaging/MessagingMqttServerTest.php | 163 ++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 tests/e2e/Services/Messaging/MessagingMqttServerTest.php diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php new file mode 100644 index 0000000000..f0cdb21860 --- /dev/null +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -0,0 +1,163 @@ +client->call(Client::METHOD_POST, '/users', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'userId' => $userId, + 'email' => 'mqtt-' . $userId . '@appwrite.io', + 'password' => 'password', + ]); + $this->assertEquals(201, $user['headers']['status-code']); + + $jwt = $this->client->call(Client::METHOD_POST, '/users/' . $userId . '/jwts', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), []); + $this->assertEquals(201, $jwt['headers']['status-code']); + $this->assertNotEmpty($jwt['body']['jwt']); + + return $jwt['body']['jwt']; + } + + private function newAdapter(string $projectId, string $credential): AppwritePush + { + return new AppwritePush( + endpoint: self::BROKER_HOST . ':' . self::BROKER_PORT, + projectId: $projectId, + credential: $credential, + authMethod: 'appwrite-jwt', + tls: false, + ); + } + + public function testAdapterPublishesToBroker(): void + { + $projectId = $this->getProject()['$id']; + $jwt = $this->createUserJwt(); + + // Test for SUCCESS + $response = $this->newAdapter($projectId, $jwt)->send(new Push( + to: ['device-1', 'device-2'], + title: 'Hi', + body: 'Hello', + )); + + $this->assertEquals('push', $response['type']); + $this->assertEquals(2, $response['deliveredTo']); + foreach ($response['results'] as $result) { + $this->assertEquals('success', $result['status']); + $this->assertEquals('', $result['error']); + } + } + + public function testUnauthorizedConnectRejected(): void + { + $projectId = $this->getProject()['$id']; + + // Test for FAILURE: a bogus credential yields CONNACK 0x87 and a closed socket, + // which the adapter surfaces as a thrown error out of send(). + $adapter = $this->newAdapter($projectId, 'not.a.valid.jwt'); + + $this->expectException(\Throwable::class); + $adapter->send(new Push( + to: ['device-1'], + title: 'Hi', + body: 'Hello', + )); + } + + public function testPublishConsumedBySubscriber(): void + { + $projectId = $this->getProject()['$id']; + $jwt = $this->createUserJwt(); + + $token = 'device-' . \uniqid(); + $topic = 'appwrite/push/' . $token; + + // Publish from a separate OS process so it runs while consume() blocks. The + // broker only fans out to already-connected subscribers, so the publisher waits + // a beat to let the consumer subscribe first. + $autoload = \dirname(__DIR__, 4) . '/vendor/autoload.php'; + $publisher = \tempnam(\sys_get_temp_dir(), 'mqtt-pub-') . '.php'; + \file_put_contents($publisher, <<<'PHP' + send(new Utopia\Messaging\Messages\Push(to: [$token], title: 'Ping', body: 'Pong', data: ['k' => 'v'])); + } catch (\Throwable $error) { + \fwrite(STDERR, $error->getMessage()); + } + PHP); + + $process = \proc_open( + [PHP_BINARY, $publisher, $autoload, self::BROKER_HOST . ':' . self::BROKER_PORT, $projectId, $jwt, $token], + [0 => ['pipe', 'r'], 1 => ['file', '/dev/null', 'a'], 2 => ['file', '/dev/null', 'a']], + $pipes, + ); + $this->assertNotFalse($process, 'could not start publisher process'); + + try { + // Consume through the adapter and assert the delivery inside the callback. + $received = []; + $handled = $this->newAdapter($projectId, $jwt)->consume( + [$topic], + function (array $message) use (&$received): void { + $received = $message; + }, + limit: 1, + timeout: 10.0, + ); + + // Test for SUCCESS: the broker delivered the publish to the subscribed consumer. + $this->assertSame(1, $handled, 'consumer did not receive the publish'); + $this->assertSame($topic, $received['topic']); + + $decoded = \json_decode($received['payload'], true); + $this->assertEquals('Ping', $decoded['notification']['title']); + $this->assertEquals('Pong', $decoded['notification']['body']); + $this->assertEquals(['k' => 'v'], $decoded['data']); + } finally { + \proc_close($process); + @\unlink($publisher); + } + } +} From 4243f6aeefedeb97bbd1406921dc459b517a92c6 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 17:58:43 +0530 Subject: [PATCH 020/146] reject blocked account during the connect --- app/init/mqtt/connection.php | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 50d8cdaf85..04f291c9ad 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -52,7 +52,11 @@ return function (Container $container): void { /** @var User $user */ $user = $dbForProject->getDocument('users', $userId); - if ($user->isEmpty() || ($sessionId !== '' && !$user->sessionActive($sessionId))) { + if ( + $user->isEmpty() + || $user->getAttribute('status', true) === false // blocked account + || ($sessionId !== '' && !$user->sessionActive($sessionId)) + ) { return new User([]); } @@ -70,6 +74,7 @@ return function (Container $container): void { if ( $user->isEmpty() + || $user->getAttribute('status', true) === false // blocked account || !$user->sessionVerify($store->getProperty('secret', ''), $proofForToken) ) { return new User([]); From 0f71d29a82b5711aabe02de08c826036379a211f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 17:59:15 +0530 Subject: [PATCH 021/146] enhance MQTT broker with telemetry and authorization features --- src/Utopia/Mqtt/Broker.php | 139 +++++++++++++++++++++++++++++++++---- 1 file changed, 126 insertions(+), 13 deletions(-) diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 5c90aa6559..7d0be86061 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -3,6 +3,11 @@ namespace Utopia\Mqtt; use Swoole\Server; +use Utopia\Span\Span; +use Utopia\Telemetry\Adapter as Telemetry; +use Utopia\Telemetry\Adapter\None as NoTelemetry; +use Utopia\Telemetry\Counter; +use Utopia\Telemetry\UpDownCounter; class Broker { @@ -49,17 +54,50 @@ class Broker /** @var array fd => last outbound packet id (QoS 1 delivery) */ private array $packetId = []; + /** @var array fds counted as active (accepted CONNECT), for a balanced gauge */ + private array $active = []; + /** * * @var (callable(string, string, string): array)|null */ private $authenticator = null; + /** + * ACL for SUBSCRIBE: given the connection identity and a topic filter, may it subscribe? + * Without one, every authenticated connection may subscribe to anything. + * + * @var (callable(array, string): bool)|null + */ + private $authorizer = null; + + private Counter $connectionsOpened; + private UpDownCounter $connectionsActive; + private Counter $subscriptionsCounter; + private Counter $messagesPublished; + private Counter $messagesDelivered; + private Counter $messagesDropped; + public function __construct( private readonly string $host = '0.0.0.0', private readonly int $port = 1883, ) { $this->subscriptions = new SubscriptionStore(); + $this->withTelemetry(new NoTelemetry()); + } + + /** + * Register telemetry instruments for connection and delivery metrics. Defaults to a + * no-op adapter, so the broker works untelemetered (e.g. raw protocol testing). + */ + public function withTelemetry(Telemetry $telemetry): void + { + $this->connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); + $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); + $this->subscriptionsCounter = $telemetry->createCounter('mqtt.subscriptions'); + $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); + $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); + $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); } /** @@ -73,6 +111,17 @@ class Broker $this->authenticator = $authenticator; } + /** + * Register the SUBSCRIBE authorizer (ACL). Denied filters are answered with a + * Not Authorized reason code and never enter the subscription store. + * + * @param callable(array, string): bool $authorizer + */ + public function onSubscribe(callable $authorizer): void + { + $this->authorizer = $authorizer; + } + public function start(): void { $server = new Server($this->host, $this->port, SWOOLE_BASE); @@ -96,16 +145,43 @@ class Broker [$remaining, $lenBytes] = $this->decodeLength($data, 1); $body = substr($data, 1 + $lenBytes, $remaining); - match ($type) { - self::CONNECT => $this->handleConnect($server, $fd, $body), - self::SUBSCRIBE => $this->handleSubscribe($server, $fd, $body), - self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), - self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), - self::PUBACK => null, - self::AUTH => $this->handleAuth($server, $fd, $body), - self::PINGREQ => $server->send($fd, chr(self::PINGRESP << 4) . $this->encodeLength(0)), - self::DISCONNECT => $server->close($fd), - default => null, + // One span per control packet, tagged with the connection's identity for tracing. + $span = Span::init('mqtt.' . $this->packetName($type)); + $span->set('mqtt.fd', $fd); + $span->set('project.id', $this->project[$fd] ?? ''); + $span->set('user.id', $this->identity[$fd]['userId'] ?? ''); + + try { + match ($type) { + self::CONNECT => $this->handleConnect($server, $fd, $body), + self::SUBSCRIBE => $this->handleSubscribe($server, $fd, $body), + self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), + self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), + self::PUBACK => null, + self::AUTH => $this->handleAuth($server, $fd, $body), + self::PINGREQ => $server->send($fd, chr(self::PINGRESP << 4) . $this->encodeLength(0)), + self::DISCONNECT => $server->close($fd), + default => null, + }; + $span->finish(); + } catch (\Throwable $error) { + $span->finish(error: $error); + throw $error; + } + } + + private function packetName(int $type): string + { + return match ($type) { + self::CONNECT => 'connect', + self::SUBSCRIBE => 'subscribe', + self::UNSUBSCRIBE => 'unsubscribe', + self::PUBLISH => 'publish', + self::PUBACK => 'puback', + self::AUTH => 'auth', + self::PINGREQ => 'pingreq', + self::DISCONNECT => 'disconnect', + default => 'unknown', }; } @@ -124,20 +200,29 @@ class Broker $projectId = $properties['user']['projectId'] ?? ''; $this->project[$fd] = $projectId; + $authMethod = $properties['authMethod']; + Span::add('project.id', $projectId); + Span::add('mqtt.auth_method', $authMethod); // TODO: add abuse limiting keyed on the client ip. if ($this->authenticator !== null) { - $identity = ($this->authenticator)($projectId, $properties['authMethod'], $properties['authData']); + $identity = ($this->authenticator)($projectId, $authMethod, $properties['authData']); if ($identity === []) { + $this->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); + Span::add('mqtt.result', 'rejected'); $this->sendConnack($server, $fd, $level, self::REASON_NOT_AUTHORIZED); $server->close($fd); return; } $this->identity[$fd] = $identity; + Span::add('user.id', $identity['userId'] ?? ''); } + $this->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); + $this->connectionsActive->add(1); + $this->active[$fd] = true; $this->sendConnack($server, $fd, $level, self::REASON_SUCCESS); } @@ -203,13 +288,25 @@ class Broker $projectId = $this->project[$fd] ?? ''; $userId = $this->identity[$fd]['userId'] ?? ''; + $identity = $this->identity[$fd] ?? []; $granted = ''; while ($offset < strlen($body)) { [$filter, $offset] = $this->readString($body, $offset); $offset += 1; // subscription options byte + Span::add('mqtt.topic', $filter); + + // ACL: an unauthorized filter is answered Not Authorized and never stored. + if ($this->authorizer !== null && !($this->authorizer)($identity, $filter)) { + $granted .= chr(self::REASON_NOT_AUTHORIZED); + $this->subscriptionsCounter->add(1, ['result' => 'denied']); + Span::add('mqtt.result', 'denied'); + continue; + } + $this->subscriptions->subscribe($projectId, $userId, $subId ?: $filter, $filter, $fd, self::QOS_1); $granted .= chr(self::QOS_1); // granted max QoS 1 + $this->subscriptionsCounter->add(1, ['result' => 'granted']); } // SUBACK: packet id (+ property length 0 for v5) + granted codes $variable = $packetId . ($this->protocol[$fd] >= 5 ? $this->encodeLength(0) : '') . $granted; @@ -313,8 +410,20 @@ class Broker $offset = $this->skipProperties($fd, $body, $offset); $payload = substr($body, $offset); - foreach ($this->subscriptions->getSubscribers($this->project[$fd] ?? '', $topic) as $subscriberFd => $grantedQos) { - $this->send($server, $subscriberFd, $topic, $payload, min($qos, $grantedQos)); + Span::add('mqtt.topic', $topic); + $this->messagesPublished->add(1, ['qos' => $qos]); + + $subscribers = $this->subscriptions->getSubscribers($this->project[$fd] ?? '', $topic); + Span::add('mqtt.subscribers', count($subscribers)); + + if ($subscribers === []) { + $this->messagesDropped->add(1, ['reason' => 'no_subscriber']); + } + + foreach ($subscribers as $subscriberFd => $grantedQos) { + $effectiveQos = min($qos, $grantedQos); + $this->send($server, $subscriberFd, $topic, $payload, $effectiveQos); + $this->messagesDelivered->add(1, ['qos' => $effectiveQos]); } if ($qos === 1) { @@ -349,12 +458,16 @@ class Broker private function onClose(Server $server, int $fd): void { + if (isset($this->active[$fd])) { + $this->connectionsActive->add(-1); + } $this->subscriptions->close($fd); unset( $this->protocol[$fd], $this->project[$fd], $this->identity[$fd], $this->packetId[$fd], + $this->active[$fd], ); } From e9a45cac29eb1b4f8d72b2edf2ded7769e606dc9 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 17:59:38 +0530 Subject: [PATCH 022/146] add authorization for MQTT subscription to block access for blocked accounts --- app/mqtt.php | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/app/mqtt.php b/app/mqtt.php index 321f97a5b5..a9561057d9 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -10,6 +10,7 @@ use Utopia\Config\Config; use Utopia\Database\Adapter\Pool as DatabasePool; use Utopia\Database\Database; use Utopia\Database\Document; +use Utopia\Database\Validator\Authorization; use Utopia\DI\Container; use Utopia\DSN\DSN; use Utopia\Mqtt\Broker; @@ -180,6 +181,47 @@ $authenticate = function (string $projectId, string $authMethod, string $credent ]; }; +/** + * ACL for SUBSCRIBE: refuse blocked accounts. Re-checked per subscribe so a block + * applied mid-connection takes effect on the next subscription. + * + * TODO: also authorize the topic itself — verify it maps to an existing messaging + * Topic in the project (topics API/collection) and that this user is allowed on it. + * A subscription to a non-existent or unauthorized topic should be denied. Deferred + * until the topic subscription model is wired. + */ +$authorize = function (array $identity, string $topic) use ($container, $registerMqttConnectionResources): bool { + $userId = $identity['userId'] ?? ''; + $projectId = $identity['projectId'] ?? ''; + if ($userId === '' || $projectId === '') { + return false; + } + + $connectionContainer = new Container($container); + $connectionContainer->set('projectId', fn () => $projectId); + $registerMqttConnectionResources($connectionContainer); + + /** @var Authorization $authorization */ + $authorization = $connectionContainer->get('authorization'); + /** @var Document $project */ + $project = $connectionContainer->get('project'); + if ($project->isEmpty()) { + return false; + } + + $dbForProject = getProjectDB($project); + $dbForProject->setAuthorization($authorization); + $user = $authorization->skip(fn () => $dbForProject->getDocument('users', $userId)); + + // status: true = enabled, false = blocked. + return !$user->isEmpty() && $user->getAttribute('status', true) !== false; +}; + +/** @var \Utopia\Telemetry\Adapter $telemetry */ +$telemetry = $container->get('telemetry'); + $broker = new Broker(host: '0.0.0.0', port: 1883); $broker->onConnect($authenticate); +$broker->onSubscribe($authorize); +$broker->withTelemetry($telemetry); $broker->start(); From 929cc611e8ddadd56a404284dbeb7dcad5235d0b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 17:59:42 +0530 Subject: [PATCH 023/146] refactor e2e tests for MQTT push broker: update user creation method and add blocked user connection rejection test --- .../Messaging/MessagingMqttServerTest.php | 55 ++++++++++++++----- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index f0cdb21860..06c3d792d5 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -16,7 +16,10 @@ use Utopia\Messaging\Messages\Push; * End-to-end tests for the MQTT push broker (src/Utopia/Mqtt), driven by the * utopia-php/messaging Appwrite Push adapter. Exercises the real broker container * over TCP: enhanced-auth CONNECT against the project/user graph, QoS 1 - * publish/ack, and — via the adapter's consume() callback — fan-out to a subscriber. + * publish/ack, fan-out to a subscriber via consume(), and subscribe-side ACL. + * + * Blocked accounts are refused at CONNECT (CONNACK 0x87); the subscribe authorizer + * re-checks as defense in depth. (Topic-existence authorization is still pending.) */ final class MessagingMqttServerTest extends Scope { @@ -30,8 +33,10 @@ final class MessagingMqttServerTest extends Scope * Create a user and mint a session-less JWT for it. The broker's JWT path skips * the session check when the payload carries no sessionId, so the user resolves * as long as it exists in the project. + * + * @return array{userId: string, jwt: string} */ - private function createUserJwt(): string + private function createUser(): array { $userId = ID::unique(); @@ -52,7 +57,7 @@ final class MessagingMqttServerTest extends Scope $this->assertEquals(201, $jwt['headers']['status-code']); $this->assertNotEmpty($jwt['body']['jwt']); - return $jwt['body']['jwt']; + return ['userId' => $userId, 'jwt' => $jwt['body']['jwt']]; } private function newAdapter(string $projectId, string $credential): AppwritePush @@ -69,9 +74,9 @@ final class MessagingMqttServerTest extends Scope public function testAdapterPublishesToBroker(): void { $projectId = $this->getProject()['$id']; - $jwt = $this->createUserJwt(); + $jwt = $this->createUser()['jwt']; - // Test for SUCCESS + // Test for SUCCESS: publishing is a server privilege (not ACL-gated). $response = $this->newAdapter($projectId, $jwt)->send(new Push( to: ['device-1', 'device-2'], title: 'Hi', @@ -102,41 +107,63 @@ final class MessagingMqttServerTest extends Scope )); } + public function testBlockedUserConnectRejected(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $userId, 'jwt' => $jwt] = $this->createUser(); + + // Block the account. + $status = $this->client->call(Client::METHOD_PATCH, '/users/' . $userId . '/status', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $projectId, + ], $this->getHeaders()), ['status' => false]); + $this->assertEquals(200, $status['headers']['status-code']); + + // Test for FAILURE: a blocked account is refused at CONNECT (CONNACK 0x87), + // which the adapter surfaces as a thrown error out of send(). + $this->expectException(\Throwable::class); + $this->expectExceptionMessageMatches('/reject/i'); + $this->newAdapter($projectId, $jwt)->send(new Push( + to: ['device-1'], + title: 'Hi', + body: 'Hello', + )); + } + public function testPublishConsumedBySubscriber(): void { $projectId = $this->getProject()['$id']; - $jwt = $this->createUserJwt(); + ['userId' => $userId, 'jwt' => $jwt] = $this->createUser(); - $token = 'device-' . \uniqid(); - $topic = 'appwrite/push/' . $token; + // The connection subscribes to its own user scope (ACL-allowed) and the server + // publishes to that same topic. + $topic = 'appwrite/push/' . $userId; // Publish from a separate OS process so it runs while consume() blocks. The - // broker only fans out to already-connected subscribers, so the publisher waits - // a beat to let the consumer subscribe first. + // broker only fans out to already-connected subscribers, so the publisher waits. $autoload = \dirname(__DIR__, 4) . '/vendor/autoload.php'; $publisher = \tempnam(\sys_get_temp_dir(), 'mqtt-pub-') . '.php'; \file_put_contents($publisher, <<<'PHP' send(new Utopia\Messaging\Messages\Push(to: [$token], title: 'Ping', body: 'Pong', data: ['k' => 'v'])); + $adapter->send(new Utopia\Messaging\Messages\Push(to: [$userId], title: 'Ping', body: 'Pong', data: ['k' => 'v'])); } catch (\Throwable $error) { \fwrite(STDERR, $error->getMessage()); } PHP); $process = \proc_open( - [PHP_BINARY, $publisher, $autoload, self::BROKER_HOST . ':' . self::BROKER_PORT, $projectId, $jwt, $token], + [PHP_BINARY, $publisher, $autoload, self::BROKER_HOST . ':' . self::BROKER_PORT, $projectId, $jwt, $userId], [0 => ['pipe', 'r'], 1 => ['file', '/dev/null', 'a'], 2 => ['file', '/dev/null', 'a']], $pipes, ); $this->assertNotFalse($process, 'could not start publisher process'); try { - // Consume through the adapter and assert the delivery inside the callback. $received = []; $handled = $this->newAdapter($projectId, $jwt)->consume( [$topic], From 6c451e5fb66f3341edbc35111640320375b09479 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 18:17:09 +0530 Subject: [PATCH 024/146] configure Traefik for MQTT: add entrypoint and routing for secure MQTT connections --- docker-compose.yml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docker-compose.yml b/docker-compose.yml index 64def4243b..4ac252158b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -21,9 +21,11 @@ services: - --providers.docker.constraints=Label(`traefik.constraint-label-stack`,`appwrite`) - --entrypoints.appwrite_web.address=:80 - --entrypoints.appwrite_websecure.address=:443 + - --entrypoints.appwrite_mqtt.address=:8883 ports: - ${_APP_HTTP_PORT:-80}:80 - ${_APP_HTTPS_PORT:-443}:443 + - ${_APP_MQTT_PORT:-8883}:8883 volumes: - /var/run/docker.sock:/var/run/docker.sock - appwrite-config:/storage/config:ro @@ -321,6 +323,17 @@ services: container_name: appwrite-mqtt image: ${_APP_IMAGE:-appwrite/appwrite}:${_APP_VERSION:-latest} restart: unless-stopped + labels: + - traefik.enable=true + - traefik.constraint-label-stack=appwrite + - traefik.docker.network=appwrite + # TLS is terminated here (mqtts, :8883) and forwarded as plaintext MQTT to :1883, + # mirroring how realtime's wss is terminated at the appwrite_websecure entrypoint. + - traefik.tcp.routers.appwrite_mqtt.entrypoints=appwrite_mqtt + - traefik.tcp.routers.appwrite_mqtt.rule=HostSNI(`*`) + - traefik.tcp.routers.appwrite_mqtt.tls=true + - traefik.tcp.routers.appwrite_mqtt.service=appwrite_mqtt + - traefik.tcp.services.appwrite_mqtt.loadbalancer.server.port=1883 networks: - appwrite ports: From a3d8b2285124132fdbdda853498dfd58fc1edccc Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 25 Aug 2026 18:17:16 +0530 Subject: [PATCH 025/146] add maxPacketSize configuration to MQTT Broker for improved packet handling --- app/mqtt.php | 6 +++++- src/Utopia/Mqtt/Broker.php | 2 ++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/app/mqtt.php b/app/mqtt.php index a9561057d9..013855b955 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -220,7 +220,11 @@ $authorize = function (array $identity, string $topic) use ($container, $registe /** @var \Utopia\Telemetry\Adapter $telemetry */ $telemetry = $container->get('telemetry'); -$broker = new Broker(host: '0.0.0.0', port: 1883); +$broker = new Broker( + host: '0.0.0.0', + port: 1883, + maxPacketSize: (int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000'), +); $broker->onConnect($authenticate); $broker->onSubscribe($authorize); $broker->withTelemetry($telemetry); diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php index 7d0be86061..99fbf8588e 100644 --- a/src/Utopia/Mqtt/Broker.php +++ b/src/Utopia/Mqtt/Broker.php @@ -81,6 +81,7 @@ class Broker public function __construct( private readonly string $host = '0.0.0.0', private readonly int $port = 1883, + private readonly int $maxPacketSize = 64000, ) { $this->subscriptions = new SubscriptionStore(); $this->withTelemetry(new NoTelemetry()); @@ -128,6 +129,7 @@ class Broker $server->set([ 'open_mqtt_protocol' => true, 'worker_num' => 1, + 'package_max_length' => $this->maxPacketSize, ]); $server->on('receive', $this->onReceive(...)); From 2f53227e02a3a5651769949dc2e09cfa6816755e Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:36:40 +0530 Subject: [PATCH 026/146] add swappable transport adapter for the MQTT broker --- src/Utopia/Mqtt/Adapter.php | 88 +++++++++++++++++++++++ src/Utopia/Mqtt/Adapter/Swoole.php | 109 +++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+) create mode 100644 src/Utopia/Mqtt/Adapter.php create mode 100644 src/Utopia/Mqtt/Adapter/Swoole.php diff --git a/src/Utopia/Mqtt/Adapter.php b/src/Utopia/Mqtt/Adapter.php new file mode 100644 index 0000000000..bd7a5bf360 --- /dev/null +++ b/src/Utopia/Mqtt/Adapter.php @@ -0,0 +1,88 @@ + */ + protected array $config = []; + + public function __construct(string $host = '0.0.0.0', int $port = 1883) + { + $this->host = $host; + $this->port = $port; + } + + /** + * Starts the server. + */ + abstract public function start(): void; + + /** + * Shuts down the server. + */ + abstract public function shutdown(): void; + + /** + * Sends raw bytes to a single connection. + * + * @param int $connection Connection ID. + * @param string $message Encoded MQTT packet. + */ + abstract public function send(int $connection, string $message): void; + + /** + * Closes a connection. + * + * @param int $connection Connection ID. + */ + abstract public function close(int $connection): void; + + /** + * Is called when the server starts. + */ + abstract public function onStart(callable $callback): self; + + /** + * Is called when a worker starts. + */ + abstract public function onWorkerStart(callable $callback): self; + + /** + * Is called when a framed MQTT packet is received. The callback is invoked + * with (int $connection, string $data). + */ + abstract public function onReceive(callable $callback): self; + + /** + * Is called when a connection is closed. The callback is invoked with + * (int $connection). + */ + abstract public function onClose(callable $callback): self; + + /** + * Sets the maximum packet length in bytes. + */ + abstract public function setPackageMaxLength(int $bytes): self; + + /** + * Sets the number of workers. + */ + abstract public function setWorkerNumber(int $num): self; + + /** + * Returns the native server object from the adapter. + */ + abstract public function getNative(): mixed; + + /** + * Returns all connections. + * + * @return array + */ + abstract public function getConnections(): array; +} diff --git a/src/Utopia/Mqtt/Adapter/Swoole.php b/src/Utopia/Mqtt/Adapter/Swoole.php new file mode 100644 index 0000000000..a0cdf36a94 --- /dev/null +++ b/src/Utopia/Mqtt/Adapter/Swoole.php @@ -0,0 +1,109 @@ + */ + private static array $connections = []; + + public function __construct(string $host = '0.0.0.0', int $port = 1883) + { + parent::__construct($host, $port); + + $this->server = new Server($this->host, $this->port, SWOOLE_BASE); + + $this->config['open_mqtt_protocol'] = true; + $this->config['worker_num'] = 1; + } + + public function start(): void + { + $this->server->set($this->config); + $this->server->start(); + } + + public function shutdown(): void + { + $this->server->shutdown(); + } + + public function send(int $connection, string $message): void + { + $this->server->send($connection, $message); + } + + public function close(int $connection): void + { + $this->server->close($connection); + } + + public function onStart(callable $callback): self + { + $this->server->on('start', function () use ($callback) { + call_user_func($callback); + }); + + return $this; + } + + public function onWorkerStart(callable $callback): self + { + $this->server->on('workerStart', function (Server $server, int $workerId) use ($callback) { + call_user_func($callback, $workerId); + }); + + return $this; + } + + public function onReceive(callable $callback): self + { + $this->server->on('receive', function (Server $server, int $fd, int $reactorId, string $data) use ($callback) { + self::$connections[$fd] = true; + + call_user_func($callback, $fd, $data); + }); + + return $this; + } + + public function onClose(callable $callback): self + { + $this->server->on('close', function (Server $server, int $fd) use ($callback) { + unset(self::$connections[$fd]); + + call_user_func($callback, $fd); + }); + + return $this; + } + + public function setPackageMaxLength(int $bytes): self + { + $this->config['package_max_length'] = $bytes; + + return $this; + } + + public function setWorkerNumber(int $num): self + { + $this->config['worker_num'] = $num; + + return $this; + } + + public function getNative(): Server + { + return $this->server; + } + + public function getConnections(): array + { + return array_keys(self::$connections); + } +} From df10ec9dd09ccaeade4b0ab185ccbd09c81d32b2 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:36:56 +0530 Subject: [PATCH 027/146] add MQTT packet codec and per-connection state --- src/Utopia/Mqtt/Connection.php | 38 +++++++ src/Utopia/Mqtt/Packet.php | 199 +++++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+) create mode 100644 src/Utopia/Mqtt/Connection.php create mode 100644 src/Utopia/Mqtt/Packet.php diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php new file mode 100644 index 0000000000..2a693a2628 --- /dev/null +++ b/src/Utopia/Mqtt/Connection.php @@ -0,0 +1,38 @@ + resolved identity (project/user ids) from the authenticator */ + public array $identity = []; + + /** Counted as active (accepted CONNECT), for a balanced gauge. */ + public bool $active = false; + + private int $packetId = 0; + + public function __construct( + public readonly int $fd, + ) { + } + + /** Next outbound packet id, wrapping 1..65535 (0 is not allowed). */ + public function nextPacketId(): int + { + $this->packetId = ($this->packetId % 0xFFFF) + 1; + + return $this->packetId; + } +} diff --git a/src/Utopia/Mqtt/Packet.php b/src/Utopia/Mqtt/Packet.php new file mode 100644 index 0000000000..c21cd7277f --- /dev/null +++ b/src/Utopia/Mqtt/Packet.php @@ -0,0 +1,199 @@ +> 4; + $flags = ord($data[0]) & 0x0F; + + [$remaining, $lenBytes] = self::decodeLength($data, 1); + $body = substr($data, 1 + $lenBytes, $remaining); + + return new self($type, $flags, $body); + } + + public function name(): string + { + return match ($this->type) { + self::CONNECT => 'connect', + self::SUBSCRIBE => 'subscribe', + self::UNSUBSCRIBE => 'unsubscribe', + self::PUBLISH => 'publish', + self::PUBACK => 'puback', + self::AUTH => 'auth', + self::PINGREQ => 'pingreq', + self::DISCONNECT => 'disconnect', + default => 'unknown', + }; + } + + /** + * Encode an outbound PUBLISH for one subscriber. The variable header order is + * topic, packet id (QoS > 0), v5 property block, then payload. The packet id and + * protocol level are the subscriber's, not the publisher's. + */ + public static function publish(string $topic, string $payload, int $qos, int $packetId, int $protocol): string + { + $variable = self::encodeString($topic); + if ($qos > 0) { + $variable .= chr($packetId >> 8) . chr($packetId & 0xFF); + } + $variable .= ($protocol >= 5 ? self::encodeLength(0) : '') . $payload; + + $header = chr((self::PUBLISH << 4) | ($qos << 1)); + + return $header . self::encodeLength(strlen($variable)) . $variable; + } + + /** + * Read a v5 property block: User Properties as a key/value map plus the + * Authentication Method and Data. Shared by CONNECT and AUTH, which carry an + * identical block. No-op for MQTT 3.1.1 (no properties). + * + * @return array{user: array, authMethod: string, authData: string} + */ + public static function readProperties(string $body, int $offset, int $protocol): array + { + $properties = ['user' => [], 'authMethod' => '', 'authData' => '']; + + if ($protocol < 5) { + return $properties; + } + + [$length, $lenBytes] = self::decodeLength($body, $offset); + $offset += $lenBytes; + $end = $offset + $length; + + while ($offset < $end) { + $id = ord($body[$offset]); + $offset++; + + switch ($id) { + case self::PROP_AUTH_METHOD: + [$properties['authMethod'], $offset] = self::readString($body, $offset); + break; + case self::PROP_AUTH_DATA: + [$properties['authData'], $offset] = self::readString($body, $offset); + break; + case self::PROP_USER: + [$key, $offset] = self::readString($body, $offset); + [$value, $offset] = self::readString($body, $offset); + $properties['user'][$key] = $value; + break; + default: + // POC assumption: clients send only auth and user properties. + throw new \RuntimeException('Unhandled connect property 0x' . dechex($id)); + } + } + + return $properties; + } + + /** + * Skip the MQTT 5.0 property block (variable-length length prefix + bytes). + * No-op for MQTT 3.1.1, which has no properties. + */ + public static function skipProperties(string $body, int $offset, int $protocol): int + { + if ($protocol < 5) { + return $offset; + } + [$length, $lenBytes] = self::decodeLength($body, $offset); + + return $offset + $lenBytes + $length; + } + + /** @return array{0: string, 1: int} decoded string and the new offset */ + public static function readString(string $data, int $offset): array + { + $length = (ord($data[$offset]) << 8) + ord($data[$offset + 1]); + $value = substr($data, $offset + 2, $length); + + return [$value, $offset + 2 + $length]; + } + + public static function encodeString(string $value): string + { + $length = strlen($value); + + return chr($length >> 8) . chr($length & 0xFF) . $value; + } + + /** Decode a variable-length integer. @return array{0: int, 1: int} value and byte count */ + public static function decodeLength(string $data, int $offset): array + { + $value = 0; + $multiplier = 1; + $bytes = 0; + do { + $byte = ord($data[$offset + $bytes]); + $value += ($byte & 0x7F) * $multiplier; + $multiplier *= 128; + $bytes++; + } while (($byte & 0x80) !== 0); + + return [$value, $bytes]; + } + + public static function encodeLength(int $length): string + { + $out = ''; + do { + $byte = $length % 128; + $length = intdiv($length, 128); + if ($length > 0) { + $byte |= 0x80; + } + $out .= chr($byte); + } while ($length > 0); + + return $out; + } +} From 09e2c51d6d880a33dcd5537924b8c909df21cb38 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:36:56 +0530 Subject: [PATCH 028/146] add packet dispatcher and telemetry instruments --- src/Utopia/Mqtt/Dispatcher.php | 49 ++++++++++++++++++++++++++++++++++ src/Utopia/Mqtt/Metrics.php | 34 +++++++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 src/Utopia/Mqtt/Dispatcher.php create mode 100644 src/Utopia/Mqtt/Metrics.php diff --git a/src/Utopia/Mqtt/Dispatcher.php b/src/Utopia/Mqtt/Dispatcher.php new file mode 100644 index 0000000000..2437379b40 --- /dev/null +++ b/src/Utopia/Mqtt/Dispatcher.php @@ -0,0 +1,49 @@ + */ + private array $handlers = []; + + public function addHandler(Action $handler): self + { + $type = $handler->getLabels()[self::LABEL_TYPE] + ?? throw new \LogicException('MQTT packet handler is missing the packetType label.'); + + $this->handlers[$type] = $handler; + + return $this; + } + + /** + * Dispatch to the handler for this packet type. Unhandled types (e.g. PUBACK) + * are ignored, matching a broker that acknowledges only what it must. + */ + public function dispatch(Container $container, int $type): void + { + $handler = $this->handlers[$type] ?? null; + if ($handler === null) { + return; + } + + $args = []; + foreach ($handler->getOptions() as $option) { + $args[] = $container->get($option['name']); + } + + ($handler->getCallback())(...$args); + } +} diff --git a/src/Utopia/Mqtt/Metrics.php b/src/Utopia/Mqtt/Metrics.php new file mode 100644 index 0000000000..e4244e1ebe --- /dev/null +++ b/src/Utopia/Mqtt/Metrics.php @@ -0,0 +1,34 @@ +connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); + $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); + $this->subscriptions = $telemetry->createCounter('mqtt.subscriptions'); + $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); + $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); + $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); + } +} From 4f519e01bb32a577b115b49a3289a89487f6fe8c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:36:56 +0530 Subject: [PATCH 029/146] add MQTT push messaging adapter --- src/Appwrite/Messaging/Adapter/Mqtt.php | 162 ++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 src/Appwrite/Messaging/Adapter/Mqtt.php diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php new file mode 100644 index 0000000000..4901b91cd5 --- /dev/null +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -0,0 +1,162 @@ + Connection { protocol, projectId, identity, packetId, active } + * + * @var array + */ + public array $connections = []; + + /** Telemetry instruments the handlers record connection and delivery outcomes on. */ + public readonly Metrics $metrics; + + private ?SubscriptionStore $subscriptions = null; + + public function __construct( + private readonly Transport $transport, + Telemetry $telemetry, + ) { + $this->metrics = new Metrics($telemetry); + } + + /** + * The subscription index, created lazily so the adapter owns it rather than + * receiving it — the in-memory tree has no external dependency to wire in. + */ + private function subscriptions(): SubscriptionStore + { + return $this->subscriptions ??= new SubscriptionStore(); + } + + /** Get or create the connection state for a file descriptor. */ + public function open(int $fd): Connection + { + return $this->connections[$fd] ??= new Connection($fd); + } + + /** + * Drop a connection: balance the active gauge, remove every subscription, and + * forget its state. The transport-level socket close is handled by the caller. + */ + public function close(int $fd): void + { + $connection = $this->connections[$fd] ?? null; + if ($connection !== null && $connection->active) { + $this->metrics->connectionsActive->add(-1); + } + $this->unsubscribe($fd); + unset($this->connections[$fd]); + } + + /** + * Subscribe a connection to topic filters. $identifier is the fd, $channels the + * topic filters; roles and queries have no MQTT meaning and are ignored. The + * granted QoS is 1 and the user id comes from the resolved identity so the + * subscription store can scale per client. + * + * @param array $roles ignored + * @param array $channels topic filters + * @param array $queryGroup ignored + */ + public function subscribe(string $projectId, mixed $identifier, string $subscriptionId, array $roles, array $channels, array $queryGroup = []): void + { + $userId = $this->connections[$identifier]->identity['userId'] ?? ''; + + foreach ($channels as $topic) { + $this->subscriptions()->subscribe( + $projectId, + $userId, + $subscriptionId ?: $topic, + $topic, + $identifier, + Packet::QOS_1, + ); + } + } + + /** Remove every subscription for a connection (used on close). */ + public function unsubscribe(mixed $identifier): void + { + $this->subscriptions()->close($identifier); + } + + /** + * Fan a published message out to a topic's subscribers over the transport, encoding + * a PUBLISH per subscriber (their protocol and packet id) and recording delivery + * telemetry. MQTT carries raw bytes, so the message and its inbound QoS ride in + * $options ($options['payload'], $options['qos']) rather than the array $payload; + * $channels holds the topics. The MQTT analogue of Realtime::send. + * + * @param array $payload unused for MQTT (payload is binary, see $options) + * @param array $events ignored + * @param array $channels topics to publish to + * @param array $roles ignored + * @param array{payload?: string, qos?: int} $options + */ + public function send(string $projectId, array $payload, array $events, array $channels, array $roles, array $options = []): void + { + $message = $options['payload'] ?? ''; + $qos = $options['qos'] ?? 0; + + foreach ($channels as $topic) { + $this->metrics->messagesPublished->add(1, ['qos' => $qos]); + + $subscribers = $this->getSubscribers($projectId, $topic); + if ($subscribers === []) { + $this->metrics->messagesDropped->add(1, ['reason' => 'no_subscriber']); + continue; + } + + foreach ($subscribers as $fd => $grantedQos) { + $subscriber = $this->connections[$fd] ?? null; + if ($subscriber === null) { + continue; + } + $effectiveQos = min($qos, $grantedQos); + $this->transport->send($fd, Packet::publish( + $topic, + $message, + $effectiveQos, + $subscriber->nextPacketId(), + $subscriber->protocol, + )); + $this->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); + } + } + } + + /** Remove a single subscription (MQTT UNSUBSCRIBE). */ + public function unsubscribeSubscription(int $fd, string $subscriptionId): void + { + $this->subscriptions()->unsubscribe($subscriptionId, $fd); + } + + /** + * The fds subscribed to a topic in a project, each mapped to its granted QoS. + * + * @return array fd => granted QoS + */ + public function getSubscribers(string $projectId, string $topic): array + { + return $this->subscriptions()->getSubscribers($projectId, $topic); + } + + public function hasSubscriber(string $projectId, string $topic): bool + { + return $this->subscriptions()->getSubscribers($projectId, $topic) !== []; + } +} From 2278a3d8e43e37c35374fe8d933dc0093e48eceb Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:37:02 +0530 Subject: [PATCH 030/146] add one action handler per MQTT control packet --- src/Utopia/Mqtt/Handlers/Auth.php | 86 ++++++++++++++++++++++++ src/Utopia/Mqtt/Handlers/Connect.php | 79 ++++++++++++++++++++++ src/Utopia/Mqtt/Handlers/Disconnect.php | 27 ++++++++ src/Utopia/Mqtt/Handlers/Ping.php | 27 ++++++++ src/Utopia/Mqtt/Handlers/Publish.php | 54 +++++++++++++++ src/Utopia/Mqtt/Handlers/Subscribe.php | 66 ++++++++++++++++++ src/Utopia/Mqtt/Handlers/Unsubscribe.php | 52 ++++++++++++++ 7 files changed, 391 insertions(+) create mode 100644 src/Utopia/Mqtt/Handlers/Auth.php create mode 100644 src/Utopia/Mqtt/Handlers/Connect.php create mode 100644 src/Utopia/Mqtt/Handlers/Disconnect.php create mode 100644 src/Utopia/Mqtt/Handlers/Ping.php create mode 100644 src/Utopia/Mqtt/Handlers/Publish.php create mode 100644 src/Utopia/Mqtt/Handlers/Subscribe.php create mode 100644 src/Utopia/Mqtt/Handlers/Unsubscribe.php diff --git a/src/Utopia/Mqtt/Handlers/Auth.php b/src/Utopia/Mqtt/Handlers/Auth.php new file mode 100644 index 0000000000..1991aec1e6 --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Auth.php @@ -0,0 +1,86 @@ +desc('Re-authenticate a live connection with a fresh credential') + ->label(Dispatcher::LABEL_TYPE, Packet::AUTH) + ->inject('authenticator') + ->inject('connection') + ->inject('packet') + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param (callable(string, string, string): array)|null $authenticator + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(?callable $authenticator, Connection $connection, Packet $packet, callable $reply): void + { + $body = $packet->body; + $method = ''; + $data = ''; + $userProperties = []; + + if ($body !== '') { + // $body[0] is the reason code (0x19 re-authenticate) + // from the offset 1 everything is the mqtt v5 properties + $properties = Packet::readProperties($body, 1, $connection->protocol); + $method = $properties['authMethod']; + $data = $properties['authData']; + $userProperties = $properties['user']; + } + + // The AUTH packet re-sends projectId as a User Property. + // TODO: check the events for the reauth only refreshes + // the credential, so enforce it stays on the project resolved at CONNECT — the + // connection must not switch tenants — then verify the fresh credential. + if ($authenticator !== null) { + $projectId = $userProperties['projectId'] ?? ''; + + $identity = ($projectId !== '' && $projectId === $connection->projectId) + ? $authenticator($projectId, $method, $data) + : []; + + if ($identity === []) { + $reply($this->disconnect(Packet::REASON_NOT_AUTHORIZED), true); + return; + } + + $connection->identity = $identity; + } + + // Acknowledge success on the live connection with an AUTH packet. + $reply($this->auth(Packet::AUTH_SUCCESS, $method), false); + } + + private function disconnect(int $reasonCode): string + { + return chr(Packet::DISCONNECT << 4) . Packet::encodeLength(1) . chr($reasonCode); + } + + private function auth(int $reasonCode, string $method, string $data = ''): string + { + $properties = ''; + if ($method !== '') { + $properties .= chr(Packet::PROP_AUTH_METHOD) . Packet::encodeString($method); + } + if ($data !== '') { + $properties .= chr(Packet::PROP_AUTH_DATA) . Packet::encodeString($data); + } + + $variable = chr($reasonCode) . Packet::encodeLength(strlen($properties)) . $properties; + + return chr(Packet::AUTH << 4) . Packet::encodeLength(strlen($variable)) . $variable; + } +} diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php new file mode 100644 index 0000000000..fc4ce1a124 --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -0,0 +1,79 @@ +desc('Authenticate a CONNECT and open the session') + ->label(Dispatcher::LABEL_TYPE, Packet::CONNECT) + ->inject('authenticator') + ->inject('mqtt') + ->inject('connection') + ->inject('packet') + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param (callable(string, string, string): array)|null $authenticator + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(?callable $authenticator, Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + { + $body = $packet->body; + $offset = 0; + [, $offset] = Packet::readString($body, $offset); // protocol name + + $level = ord($body[$offset]); + $connection->protocol = $level; + $offset += 1; // protocol level + $offset += 1; // connect flags + $offset += 2; // keep alive + + $properties = Packet::readProperties($body, $offset, $level); + + $projectId = $properties['user']['projectId'] ?? ''; + $connection->projectId = $projectId; + $authMethod = $properties['authMethod']; + Span::add('project.id', $projectId); + Span::add('mqtt.auth_method', $authMethod); + + // TODO: add abuse limiting keyed on the client ip. + if ($authenticator !== null) { + $identity = $authenticator($projectId, $authMethod, $properties['authData']); + + if ($identity === []) { + $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); + Span::add('mqtt.result', 'rejected'); + $reply($this->connack($level, Packet::REASON_NOT_AUTHORIZED), true); + return; + } + + $connection->identity = $identity; + Span::add('user.id', $identity['userId'] ?? ''); + } + + $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); + $mqtt->metrics->connectionsActive->add(1); + $connection->active = true; + $reply($this->connack($level, Packet::REASON_SUCCESS), false); + } + + private function connack(int $level, int $reasonCode): string + { + // CONNACK: [ack flags = 0][reason code](+ [property length = 0] for v5) + $variable = chr(0x00) . chr($reasonCode) . ($level >= 5 ? Packet::encodeLength(0) : ''); + + return chr(Packet::CONNACK << 4) . Packet::encodeLength(strlen($variable)) . $variable; + } +} diff --git a/src/Utopia/Mqtt/Handlers/Disconnect.php b/src/Utopia/Mqtt/Handlers/Disconnect.php new file mode 100644 index 0000000000..209f035906 --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Disconnect.php @@ -0,0 +1,27 @@ +desc('Close the connection on client request') + ->label(Dispatcher::LABEL_TYPE, Packet::DISCONNECT) + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(callable $reply): void + { + $reply('', true); + } +} diff --git a/src/Utopia/Mqtt/Handlers/Ping.php b/src/Utopia/Mqtt/Handlers/Ping.php new file mode 100644 index 0000000000..b01a7dee6c --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Ping.php @@ -0,0 +1,27 @@ +desc('Reply to a client heartbeat') + ->label(Dispatcher::LABEL_TYPE, Packet::PINGREQ) + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(callable $reply): void + { + $reply(chr(Packet::PINGRESP << 4) . Packet::encodeLength(0), false); + } +} diff --git a/src/Utopia/Mqtt/Handlers/Publish.php b/src/Utopia/Mqtt/Handlers/Publish.php new file mode 100644 index 0000000000..3025413723 --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Publish.php @@ -0,0 +1,54 @@ +desc('Fan a published message out to matching subscribers') + ->label(Dispatcher::LABEL_TYPE, Packet::PUBLISH) + ->inject('mqtt') + ->inject('connection') + ->inject('packet') + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + { + $body = $packet->body; + $qos = ($packet->flags >> 1) & 0x03; + + [$topic, $offset] = Packet::readString($body, 0); + + $packetId = null; + if ($qos > 0) { + $packetId = substr($body, $offset, 2); + $offset += 2; + } + $offset = Packet::skipProperties($body, $offset, $connection->protocol); + $payload = substr($body, $offset); + + Span::add('mqtt.topic', $topic); + Span::add('mqtt.subscribers', count($mqtt->getSubscribers($connection->projectId, $topic))); + + $mqtt->send($connection->projectId, [], [], [$topic], [], ['payload' => $payload, 'qos' => $qos]); + + if ($qos === 1) { + // PUBACK: packet id (reason/properties omitted -> valid for both versions) + $reply(chr(Packet::PUBACK << 4) . Packet::encodeLength(strlen($packetId)) . $packetId, false); + } + } +} diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php new file mode 100644 index 0000000000..f9d55880ef --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -0,0 +1,66 @@ +desc('Subscribe to topic filters, enforcing the ACL') + ->label(Dispatcher::LABEL_TYPE, Packet::SUBSCRIBE) + ->inject('authorizer') + ->inject('mqtt') + ->inject('connection') + ->inject('packet') + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param (callable(array, string): bool)|null $authorizer + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(?callable $authorizer, Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + { + $body = $packet->body; + $offset = 0; + $packetId = substr($body, 0, 2); + $offset += 2; + + $subId = Packet::readProperties($body, $offset, $connection->protocol)['user']['subId'] ?? ''; + $offset = Packet::skipProperties($body, $offset, $connection->protocol); + + $identity = $connection->identity; + + $granted = ''; + while ($offset < strlen($body)) { + [$filter, $offset] = Packet::readString($body, $offset); + $offset += 1; // subscription options byte + Span::add('mqtt.topic', $filter); + + // ACL: an unauthorized filter is answered Not Authorized and never stored. + if ($authorizer !== null && !$authorizer($identity, $filter)) { + $granted .= chr(Packet::REASON_NOT_AUTHORIZED); + $mqtt->metrics->subscriptions->add(1, ['result' => 'denied']); + Span::add('mqtt.result', 'denied'); + continue; + } + + $mqtt->subscribe($connection->projectId, $connection->fd, $subId ?: $filter, [], [$filter]); + $granted .= chr(Packet::QOS_1); // granted max QoS 1 + $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); + } + + // SUBACK: packet id (+ property length 0 for v5) + granted codes + $variable = $packetId . ($connection->protocol >= 5 ? Packet::encodeLength(0) : '') . $granted; + $reply(chr(Packet::SUBACK << 4) . Packet::encodeLength(strlen($variable)) . $variable, false); + } +} diff --git a/src/Utopia/Mqtt/Handlers/Unsubscribe.php b/src/Utopia/Mqtt/Handlers/Unsubscribe.php new file mode 100644 index 0000000000..d407745f11 --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Unsubscribe.php @@ -0,0 +1,52 @@ +desc('Remove topic-filter subscriptions') + ->label(Dispatcher::LABEL_TYPE, Packet::UNSUBSCRIBE) + ->inject('mqtt') + ->inject('connection') + ->inject('packet') + ->inject('reply') + ->callback($this->action(...)); + } + + /** + * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) + */ + public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + { + $body = $packet->body; + $offset = 0; + $packetId = substr($body, 0, 2); + $offset += 2; + + $subId = Packet::readProperties($body, $offset, $connection->protocol)['user']['subId'] ?? ''; + $offset = Packet::skipProperties($body, $offset, $connection->protocol); + + $count = 0; + while ($offset < strlen($body)) { + [$filter, $offset] = Packet::readString($body, $offset); + $mqtt->unsubscribeSubscription($connection->fd, $subId ?: $filter); + $count++; + } + + // UNSUBACK: packet id (+ property length 0 + one reason code per filter for v5) + $variable = $packetId; + if ($connection->protocol >= 5) { + $variable .= Packet::encodeLength(0) . str_repeat(chr(Packet::REASON_SUCCESS), $count); + } + $reply(chr(Packet::UNSUBACK << 4) . Packet::encodeLength(strlen($variable)) . $variable, false); + } +} From ce13a7a9e47720d46d3fa1f34d8cb50eedbd91f0 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:37:02 +0530 Subject: [PATCH 031/146] wire broker from handlers and drop the monolithic Broker --- app/mqtt.php | 86 +++++- src/Utopia/Mqtt/Broker.php | 533 ------------------------------------- 2 files changed, 74 insertions(+), 545 deletions(-) delete mode 100644 src/Utopia/Mqtt/Broker.php diff --git a/app/mqtt.php b/app/mqtt.php index 013855b955..e5607302be 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -1,5 +1,6 @@ has('pools')) { }, ['register']); } -// DB bootstrap helpers, mirroring app/realtime.php. These are process-level (pools + -// cache), not HTTP; the connection resources call them to reach the project/console DB. if (!function_exists('getCache')) { function getCache(): Cache { @@ -220,12 +229,65 @@ $authorize = function (array $identity, string $topic) use ($container, $registe /** @var \Utopia\Telemetry\Adapter $telemetry */ $telemetry = $container->get('telemetry'); -$broker = new Broker( - host: '0.0.0.0', - port: 1883, - maxPacketSize: (int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000'), -); -$broker->onConnect($authenticate); -$broker->onSubscribe($authorize); -$broker->withTelemetry($telemetry); -$broker->start(); +$adapter = new Adapter\Swoole(host: '0.0.0.0', port: 1883); +$adapter->setPackageMaxLength((int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000')); + +$mqtt = new Mqtt($adapter, $telemetry); + +$dispatcher = (new Dispatcher()) + ->addHandler(new ConnectHandler()) + ->addHandler(new SubscribeHandler()) + ->addHandler(new UnsubscribeHandler()) + ->addHandler(new PublishHandler()) + ->addHandler(new AuthHandler()) + ->addHandler(new PingHandler()) + ->addHandler(new DisconnectHandler()); + +$adapter->onStart(fn () => print("MQTT broker started\n")); + +$adapter->onReceive(function (int $fd, string $data) use ( + $adapter, + $mqtt, + $dispatcher, + $authenticate, + $authorize, +): void { + $packet = Packet::parse($data); + $connection = $mqtt->open($fd); + + $span = Span::init('mqtt.' . $packet->name()); + $span->set('mqtt.fd', $fd); + $span->set('project.id', $connection->projectId); + $span->set('user.id', $connection->identity['userId'] ?? ''); + + $reply = function (string $packet = '', bool $close = false) use ($adapter, $fd): void { + if ($packet !== '') { + $adapter->send($fd, $packet); + } + if ($close) { + $adapter->close($fd); + } + }; + + $packetContainer = new Container(); + $packetContainer->set('mqtt', fn () => $mqtt); + $packetContainer->set('connection', fn () => $connection); + $packetContainer->set('packet', fn () => $packet); + $packetContainer->set('authenticator', fn () => $authenticate); + $packetContainer->set('authorizer', fn () => $authorize); + $packetContainer->set('reply', fn () => $reply); + + try { + $dispatcher->dispatch($packetContainer, $packet->type); + $span->finish(); + } catch (\Throwable $error) { + $span->finish(error: $error); + throw $error; + } +}); + +$adapter->onClose(function (int $fd) use ($mqtt): void { + $mqtt->close($fd); +}); + +$adapter->start(); diff --git a/src/Utopia/Mqtt/Broker.php b/src/Utopia/Mqtt/Broker.php deleted file mode 100644 index 99fbf8588e..0000000000 --- a/src/Utopia/Mqtt/Broker.php +++ /dev/null @@ -1,533 +0,0 @@ - fd => protocol level (4 = 3.1.1, 5 = 5.0) */ - private array $protocol = []; - - /** @var array fd => project id (from a CONNECT User Property) */ - private array $project = []; - - /** Bidirectional subscription index: fd <-> project-scoped topic trie. */ - private SubscriptionStore $subscriptions; - - /** @var array> fd => resolved identity (project/user ids) */ - private array $identity = []; - - /** @var array fd => last outbound packet id (QoS 1 delivery) */ - private array $packetId = []; - - /** @var array fds counted as active (accepted CONNECT), for a balanced gauge */ - private array $active = []; - - /** - * - * @var (callable(string, string, string): array)|null - */ - private $authenticator = null; - - /** - * ACL for SUBSCRIBE: given the connection identity and a topic filter, may it subscribe? - * Without one, every authenticated connection may subscribe to anything. - * - * @var (callable(array, string): bool)|null - */ - private $authorizer = null; - - private Counter $connectionsOpened; - private UpDownCounter $connectionsActive; - private Counter $subscriptionsCounter; - private Counter $messagesPublished; - private Counter $messagesDelivered; - private Counter $messagesDropped; - - public function __construct( - private readonly string $host = '0.0.0.0', - private readonly int $port = 1883, - private readonly int $maxPacketSize = 64000, - ) { - $this->subscriptions = new SubscriptionStore(); - $this->withTelemetry(new NoTelemetry()); - } - - /** - * Register telemetry instruments for connection and delivery metrics. Defaults to a - * no-op adapter, so the broker works untelemetered (e.g. raw protocol testing). - */ - public function withTelemetry(Telemetry $telemetry): void - { - $this->connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); - $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); - $this->subscriptionsCounter = $telemetry->createCounter('mqtt.subscriptions'); - $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); - $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); - $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); - } - - /** - * Register the CONNECT authenticator. Without one the broker accepts every - * connection (raw protocol testing). - * - * @param callable(string, string, string): array $authenticator - */ - public function onConnect(callable $authenticator): void - { - $this->authenticator = $authenticator; - } - - /** - * Register the SUBSCRIBE authorizer (ACL). Denied filters are answered with a - * Not Authorized reason code and never enter the subscription store. - * - * @param callable(array, string): bool $authorizer - */ - public function onSubscribe(callable $authorizer): void - { - $this->authorizer = $authorizer; - } - - public function start(): void - { - $server = new Server($this->host, $this->port, SWOOLE_BASE); - $server->set([ - 'open_mqtt_protocol' => true, - 'worker_num' => 1, - 'package_max_length' => $this->maxPacketSize, - ]); - - $server->on('receive', $this->onReceive(...)); - $server->on('close', $this->onClose(...)); - - echo "MQTT broker listening on {$this->host}:{$this->port}\n"; - $server->start(); - } - - private function onReceive(Server $server, int $fd, int $reactorId, string $data): void - { - $type = ord($data[0]) >> 4; - $flags = ord($data[0]) & 0x0F; - - [$remaining, $lenBytes] = $this->decodeLength($data, 1); - $body = substr($data, 1 + $lenBytes, $remaining); - - // One span per control packet, tagged with the connection's identity for tracing. - $span = Span::init('mqtt.' . $this->packetName($type)); - $span->set('mqtt.fd', $fd); - $span->set('project.id', $this->project[$fd] ?? ''); - $span->set('user.id', $this->identity[$fd]['userId'] ?? ''); - - try { - match ($type) { - self::CONNECT => $this->handleConnect($server, $fd, $body), - self::SUBSCRIBE => $this->handleSubscribe($server, $fd, $body), - self::UNSUBSCRIBE => $this->handleUnsubscribe($server, $fd, $body), - self::PUBLISH => $this->handlePublish($server, $fd, $flags, $body), - self::PUBACK => null, - self::AUTH => $this->handleAuth($server, $fd, $body), - self::PINGREQ => $server->send($fd, chr(self::PINGRESP << 4) . $this->encodeLength(0)), - self::DISCONNECT => $server->close($fd), - default => null, - }; - $span->finish(); - } catch (\Throwable $error) { - $span->finish(error: $error); - throw $error; - } - } - - private function packetName(int $type): string - { - return match ($type) { - self::CONNECT => 'connect', - self::SUBSCRIBE => 'subscribe', - self::UNSUBSCRIBE => 'unsubscribe', - self::PUBLISH => 'publish', - self::PUBACK => 'puback', - self::AUTH => 'auth', - self::PINGREQ => 'pingreq', - self::DISCONNECT => 'disconnect', - default => 'unknown', - }; - } - - private function handleConnect(Server $server, int $fd, string $body): void - { - $offset = 0; - [, $offset] = $this->readString($body, $offset); // protocol name - - $level = ord($body[$offset]); - $this->protocol[$fd] = $level; - $offset += 1; // protocol level - $offset += 1; // connect flags - $offset += 2; // keep alive - - $properties = $this->getProperties($fd, $body, $offset); - - $projectId = $properties['user']['projectId'] ?? ''; - $this->project[$fd] = $projectId; - $authMethod = $properties['authMethod']; - Span::add('project.id', $projectId); - Span::add('mqtt.auth_method', $authMethod); - - // TODO: add abuse limiting keyed on the client ip. - if ($this->authenticator !== null) { - $identity = ($this->authenticator)($projectId, $authMethod, $properties['authData']); - - if ($identity === []) { - $this->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); - Span::add('mqtt.result', 'rejected'); - $this->sendConnack($server, $fd, $level, self::REASON_NOT_AUTHORIZED); - $server->close($fd); - return; - } - - $this->identity[$fd] = $identity; - Span::add('user.id', $identity['userId'] ?? ''); - } - - $this->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); - $this->connectionsActive->add(1); - $this->active[$fd] = true; - $this->sendConnack($server, $fd, $level, self::REASON_SUCCESS); - } - - private function sendConnack(Server $server, int $fd, int $level, int $reasonCode): void - { - // CONNACK: [ack flags = 0][reason code](+ [property length = 0] for v5) - $variable = chr(0x00) . chr($reasonCode) . ($level >= 5 ? $this->encodeLength(0) : ''); - $server->send($fd, chr(self::CONNACK << 4) . $this->encodeLength(strlen($variable)) . $variable); - } - - /** - * Read a v5 property block: User Properties as a key/value map plus the - * Authentication Method and Data. Shared by CONNECT and AUTH, which carry an - * identical block. No-op for MQTT 3.1.1 (no properties). - * - * @return array{user: array, authMethod: string, authData: string} - */ - private function getProperties(int $fd, string $body, int $offset): array - { - $properties = ['user' => [], 'authMethod' => '', 'authData' => '']; - - if (($this->protocol[$fd] ?? 4) < 5) { - return $properties; - } - - [$length, $lenBytes] = $this->decodeLength($body, $offset); - $offset += $lenBytes; - $end = $offset + $length; - - while ($offset < $end) { - $id = ord($body[$offset]); - $offset++; - - switch ($id) { - case self::PROP_AUTH_METHOD: - [$properties['authMethod'], $offset] = $this->readString($body, $offset); - break; - case self::PROP_AUTH_DATA: - [$properties['authData'], $offset] = $this->readString($body, $offset); - break; - case self::PROP_USER: - [$key, $offset] = $this->readString($body, $offset); - [$value, $offset] = $this->readString($body, $offset); - $properties['user'][$key] = $value; - break; - default: - // POC assumption: clients send only auth and user properties. - throw new \RuntimeException('Unhandled connect property 0x' . dechex($id)); - } - } - - return $properties; - } - - private function handleSubscribe(Server $server, int $fd, string $body): void - { - $offset = 0; - $packetId = substr($body, 0, 2); - $offset += 2; - - $subId = $this->getProperties($fd, $body, $offset)['user']['subId'] ?? ''; - $offset = $this->skipProperties($fd, $body, $offset); - - $projectId = $this->project[$fd] ?? ''; - $userId = $this->identity[$fd]['userId'] ?? ''; - $identity = $this->identity[$fd] ?? []; - - $granted = ''; - while ($offset < strlen($body)) { - [$filter, $offset] = $this->readString($body, $offset); - $offset += 1; // subscription options byte - Span::add('mqtt.topic', $filter); - - // ACL: an unauthorized filter is answered Not Authorized and never stored. - if ($this->authorizer !== null && !($this->authorizer)($identity, $filter)) { - $granted .= chr(self::REASON_NOT_AUTHORIZED); - $this->subscriptionsCounter->add(1, ['result' => 'denied']); - Span::add('mqtt.result', 'denied'); - continue; - } - - $this->subscriptions->subscribe($projectId, $userId, $subId ?: $filter, $filter, $fd, self::QOS_1); - $granted .= chr(self::QOS_1); // granted max QoS 1 - $this->subscriptionsCounter->add(1, ['result' => 'granted']); - } - // SUBACK: packet id (+ property length 0 for v5) + granted codes - $variable = $packetId . ($this->protocol[$fd] >= 5 ? $this->encodeLength(0) : '') . $granted; - $server->send($fd, chr(self::SUBACK << 4) . $this->encodeLength(strlen($variable)) . $variable); - } - - private function handleUnsubscribe(Server $server, int $fd, string $body): void - { - $offset = 0; - $packetId = substr($body, 0, 2); - $offset += 2; - - $subId = $this->getProperties($fd, $body, $offset)['user']['subId'] ?? ''; - $offset = $this->skipProperties($fd, $body, $offset); - - $count = 0; - while ($offset < strlen($body)) { - [$filter, $offset] = $this->readString($body, $offset); - $this->subscriptions->unsubscribe($subId ?: $filter, $fd); - $count++; - } - - // UNSUBACK: packet id (+ property length 0 + one reason code per filter for v5) - $variable = $packetId; - if ($this->protocol[$fd] >= 5) { - $variable .= $this->encodeLength(0) . str_repeat(chr(self::REASON_SUCCESS), $count); - } - $server->send($fd, chr(self::UNSUBACK << 4) . $this->encodeLength(strlen($variable)) . $variable); - } - - private function handleAuth(Server $server, int $fd, string $body): void - { - $method = ''; - $data = ''; - $userProperties = []; - - if ($body !== '') { - // $body[0] is the reason code (0x19 re-authenticate) - // from the offset 1 everything is the mqtt v5 properties - $properties = $this->getProperties($fd, $body, 1); - $method = $properties['authMethod']; - $data = $properties['authData']; - $userProperties = $properties['user']; - } - - // The AUTH packet re-sends projectId as a User Property. - // TODO: check the events for the reauth only refreshes - // the credential, so enforce it stays on the project resolved at CONNECT — the - // connection must not switch tenants — then verify the fresh credential. - if ($this->authenticator !== null) { - $projectId = $userProperties['projectId'] ?? ''; - - $identity = ($projectId !== '' && $projectId === ($this->project[$fd] ?? '')) - ? ($this->authenticator)($projectId, $method, $data) - : []; - - if ($identity === []) { - $this->sendDisconnect($server, $fd, self::REASON_NOT_AUTHORIZED); - return; - } - - $this->identity[$fd] = $identity; - } - - // Acknowledge success on the live connection with an AUTH packet. - $server->send($fd, $this->encodeAuth(self::AUTH_SUCCESS, $method)); - } - - private function sendDisconnect(Server $server, int $fd, int $reasonCode): void - { - $server->send($fd, chr(self::DISCONNECT << 4) . $this->encodeLength(1) . chr($reasonCode)); - $server->close($fd); - } - - private function encodeAuth(int $reasonCode, string $method, string $data = ''): string - { - $properties = ''; - if ($method !== '') { - $properties .= chr(self::PROP_AUTH_METHOD) . $this->encodeString($method); - } - if ($data !== '') { - $properties .= chr(self::PROP_AUTH_DATA) . $this->encodeString($data); - } - - $variable = chr($reasonCode) . $this->encodeLength(strlen($properties)) . $properties; - - return chr(self::AUTH << 4) . $this->encodeLength(strlen($variable)) . $variable; - } - - private function handlePublish(Server $server, int $fd, int $flags, string $body): void - { - $qos = ($flags >> 1) & 0x03; - - [$topic, $offset] = $this->readString($body, 0); - - $packetId = null; - if ($qos > 0) { - $packetId = substr($body, $offset, 2); - $offset += 2; - } - $offset = $this->skipProperties($fd, $body, $offset); - $payload = substr($body, $offset); - - Span::add('mqtt.topic', $topic); - $this->messagesPublished->add(1, ['qos' => $qos]); - - $subscribers = $this->subscriptions->getSubscribers($this->project[$fd] ?? '', $topic); - Span::add('mqtt.subscribers', count($subscribers)); - - if ($subscribers === []) { - $this->messagesDropped->add(1, ['reason' => 'no_subscriber']); - } - - foreach ($subscribers as $subscriberFd => $grantedQos) { - $effectiveQos = min($qos, $grantedQos); - $this->send($server, $subscriberFd, $topic, $payload, $effectiveQos); - $this->messagesDelivered->add(1, ['qos' => $effectiveQos]); - } - - if ($qos === 1) { - // PUBACK: packet id (reason/properties omitted -> valid for both versions) - $server->send($fd, chr(self::PUBACK << 4) . $this->encodeLength(strlen($packetId)) . $packetId); - } - } - - private function send(Server $server, int $fd, string $topic, string $payload, int $qos): void - { - // Variable header order: topic, packet id (QoS > 0), properties (v5), payload. - $variable = $this->encodeString($topic); - if ($qos > 0) { - $packetId = $this->getNextPacketId($fd); - $variable .= chr($packetId >> 8) . chr($packetId & 0xFF); - } - $variable .= ((($this->protocol[$fd] ?? 4) >= 5 ? $this->encodeLength(0) : '')) . $payload; - - // PUBLISH, flags = QoS << 1 - $header = chr((self::PUBLISH << 4) | ($qos << 1)); - $server->send($fd, $header . $this->encodeLength(strlen($variable)) . $variable); - } - - /** Next per-connection outbound packet id, wrapping 1..65535 (0 is not allowed). */ - private function getNextPacketId(int $fd): int - { - $next = (($this->packetId[$fd] ?? 0) % 0xFFFF) + 1; - $this->packetId[$fd] = $next; - - return $next; - } - - private function onClose(Server $server, int $fd): void - { - if (isset($this->active[$fd])) { - $this->connectionsActive->add(-1); - } - $this->subscriptions->close($fd); - unset( - $this->protocol[$fd], - $this->project[$fd], - $this->identity[$fd], - $this->packetId[$fd], - $this->active[$fd], - ); - } - - /** - * Skip the MQTT 5.0 property block (variable-length length prefix + bytes). - * No-op for MQTT 3.1.1, which has no properties. - */ - private function skipProperties(int $fd, string $body, int $offset): int - { - if (($this->protocol[$fd] ?? 4) < 5) { - return $offset; - } - [$length, $lenBytes] = $this->decodeLength($body, $offset); - return $offset + $lenBytes + $length; - } - - /** @return array{0: string, 1: int} decoded string and the new offset */ - private function readString(string $data, int $offset): array - { - $length = (ord($data[$offset]) << 8) + ord($data[$offset + 1]); - $value = substr($data, $offset + 2, $length); - return [$value, $offset + 2 + $length]; - } - - private function encodeString(string $value): string - { - $length = strlen($value); - return chr($length >> 8) . chr($length & 0xFF) . $value; - } - - /** Decode a variable-length integer. @return array{0: int, 1: int} value and byte count */ - private function decodeLength(string $data, int $offset): array - { - $value = 0; - $multiplier = 1; - $bytes = 0; - do { - $byte = ord($data[$offset + $bytes]); - $value += ($byte & 0x7F) * $multiplier; - $multiplier *= 128; - $bytes++; - } while (($byte & 0x80) !== 0); - - return [$value, $bytes]; - } - - private function encodeLength(int $length): string - { - $out = ''; - do { - $byte = $length % 128; - $length = intdiv($length, 128); - if ($length > 0) { - $byte |= 0x80; - } - $out .= chr($byte); - } while ($length > 0); - - return $out; - } -} From 5718fa94e4804048ed70549330fa7f5bcd49114b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:58:44 +0530 Subject: [PATCH 032/146] publish messages over an 'mqtt' pub/sub channel --- src/Appwrite/Messaging/Adapter/Mqtt.php | 64 ++++++++++++------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 4901b91cd5..c2ffaf45fb 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -3,7 +3,7 @@ namespace Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter as MessagingAdapter; -use Utopia\Mqtt\Adapter as Transport; +use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Metrics; use Utopia\Mqtt\Packet; @@ -12,6 +12,8 @@ use Utopia\Telemetry\Adapter as Telemetry; class Mqtt extends MessagingAdapter { + private const CHANNEL = 'mqtt'; + /** * Connection registry. * @@ -26,10 +28,10 @@ class Mqtt extends MessagingAdapter private ?SubscriptionStore $subscriptions = null; - public function __construct( - private readonly Transport $transport, - Telemetry $telemetry, - ) { + private ?PubSubPool $pubSubPool = null; + + public function __construct(Telemetry $telemetry) + { $this->metrics = new Metrics($telemetry); } @@ -42,6 +44,16 @@ class Mqtt extends MessagingAdapter return $this->subscriptions ??= new SubscriptionStore(); } + private function getPubSubPool(): PubSubPool + { + if ($this->pubSubPool === null) { + global $register; + $this->pubSubPool = new PubSubPool($register->get('pools')->get('pubsub')); + } + + return $this->pubSubPool; + } + /** Get or create the connection state for a file descriptor. */ public function open(int $fd): Connection { @@ -95,11 +107,15 @@ class Mqtt extends MessagingAdapter } /** - * Fan a published message out to a topic's subscribers over the transport, encoding - * a PUBLISH per subscriber (their protocol and packet id) and recording delivery - * telemetry. MQTT carries raw bytes, so the message and its inbound QoS ride in - * $options ($options['payload'], $options['qos']) rather than the array $payload; - * $channels holds the topics. The MQTT analogue of Realtime::send. + * Publish a message onto the 'mqtt' pub/sub channel for fan-out. Every broker + * worker listens on that channel and delivers to its own local subscribers, so a + * publish reaches subscribers regardless of which worker holds them — the MQTT + * analogue of Realtime::send publishing to the realtime firehose. + * + * MQTT carries raw bytes, so the message and its inbound QoS ride in $options + * ($options['payload'], $options['qos']) rather than the array $payload; + * $channels holds the topics. The payload is base64-encoded to survive the JSON + * envelope. * * @param array $payload unused for MQTT (payload is binary, see $options) * @param array $events ignored @@ -114,28 +130,12 @@ class Mqtt extends MessagingAdapter foreach ($channels as $topic) { $this->metrics->messagesPublished->add(1, ['qos' => $qos]); - - $subscribers = $this->getSubscribers($projectId, $topic); - if ($subscribers === []) { - $this->metrics->messagesDropped->add(1, ['reason' => 'no_subscriber']); - continue; - } - - foreach ($subscribers as $fd => $grantedQos) { - $subscriber = $this->connections[$fd] ?? null; - if ($subscriber === null) { - continue; - } - $effectiveQos = min($qos, $grantedQos); - $this->transport->send($fd, Packet::publish( - $topic, - $message, - $effectiveQos, - $subscriber->nextPacketId(), - $subscriber->protocol, - )); - $this->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); - } + $this->getPubSubPool()->publish(self::CHANNEL, (string) json_encode([ + 'project' => $projectId, + 'topic' => $topic, + 'qos' => $qos, + 'payload' => base64_encode($message), + ])); } } From 6b31f0e89e82a153a335676bd47b10e1bdf972b7 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:58:44 +0530 Subject: [PATCH 033/146] add Server wrapper around the MQTT transport adapter --- src/Utopia/Mqtt/Server.php | 111 +++++++++++++++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 src/Utopia/Mqtt/Server.php diff --git a/src/Utopia/Mqtt/Server.php b/src/Utopia/Mqtt/Server.php new file mode 100644 index 0000000000..ca47e84e1d --- /dev/null +++ b/src/Utopia/Mqtt/Server.php @@ -0,0 +1,111 @@ + */ + protected array $errorCallbacks = []; + + protected Adapter $adapter; + + public function __construct(Adapter $adapter) + { + $this->adapter = $adapter; + } + + public function start(): void + { + try { + $this->adapter->start(); + } catch (Throwable $error) { + $this->onError($error, 'start'); + } + } + + public function shutdown(): void + { + try { + $this->adapter->shutdown(); + } catch (Throwable $error) { + $this->onError($error, 'shutdown'); + } + } + + public function send(int $connection, string $message): void + { + try { + $this->adapter->send($connection, $message); + } catch (Throwable $error) { + $this->onError($error, 'send'); + } + } + + public function close(int $connection): void + { + try { + $this->adapter->close($connection); + } catch (Throwable $error) { + $this->onError($error, 'close'); + } + } + + public function onStart(callable $callback): self + { + $this->adapter->onStart($callback); + + return $this; + } + + public function onWorkerStart(callable $callback): self + { + $this->adapter->onWorkerStart($callback); + + return $this; + } + + public function onReceive(callable $callback): self + { + $this->adapter->onReceive($callback); + + return $this; + } + + public function onClose(callable $callback): self + { + $this->adapter->onClose($callback); + + return $this; + } + + /** + * @return array + */ + public function getConnections(): array + { + return $this->adapter->getConnections(); + } + + /** Register a callback run when a transport operation throws. */ + public function error(callable $callback): self + { + $this->errorCallbacks[] = $callback; + + return $this; + } + + private function onError(Throwable $error, string $action): void + { + foreach ($this->errorCallbacks as $callback) { + $callback($error, $action); + } + } +} From 5219356a346601fecdce43a8d4939594597139cf Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 12:58:44 +0530 Subject: [PATCH 034/146] fan out published messages to subscribers in the broker worker --- app/mqtt.php | 81 ++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 72 insertions(+), 9 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index e5607302be..6b9a8e4a4b 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -1,6 +1,7 @@ get('telemetry'); $adapter = new Adapter\Swoole(host: '0.0.0.0', port: 1883); $adapter->setPackageMaxLength((int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000')); -$mqtt = new Mqtt($adapter, $telemetry); +$server = new Server($adapter); +$server->error(fn (\Throwable $error, string $action) => Console::error("MQTT {$action} error: " . $error->getMessage())); + +$mqtt = new Mqtt($telemetry); $dispatcher = (new Dispatcher()) ->addHandler(new ConnectHandler()) @@ -243,10 +249,67 @@ $dispatcher = (new Dispatcher()) ->addHandler(new PingHandler()) ->addHandler(new DisconnectHandler()); -$adapter->onStart(fn () => print("MQTT broker started\n")); +$server->onStart(fn () => print("MQTT broker started\n")); -$adapter->onReceive(function (int $fd, string $data) use ( - $adapter, +$server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): void { + go(function () use ($server, $mqtt, $register): void { + $attempts = 0; + while ($attempts < 300) { + try { + $pubsub = new PubSubPool($register->get('pools')->get('pubsub')); + + if ($pubsub->ping(true)) { + $attempts = 0; + } + + $pubsub->subscribe(['mqtt'], function (mixed $redis, string $channel, string $payload) use ($server, $mqtt): void { + $event = json_decode($payload, true); + if (!\is_array($event)) { + return; + } + + $projectId = (string) ($event['project'] ?? ''); + $topic = (string) ($event['topic'] ?? ''); + $qos = (int) ($event['qos'] ?? 0); + $message = base64_decode((string) ($event['payload'] ?? '')); + + $subscribers = $mqtt->getSubscribers($projectId, $topic); + if ($subscribers === []) { + // No local subscriber on this worker; with multiple workers this + // counts per-worker rather than as a global drop. + $mqtt->metrics->messagesDropped->add(1, ['reason' => 'no_subscriber']); + return; + } + + foreach ($subscribers as $fd => $grantedQos) { + $subscriber = $mqtt->connections[$fd] ?? null; + if ($subscriber === null) { + continue; + } + $effectiveQos = min($qos, $grantedQos); + $server->send($fd, Packet::publish( + $topic, + $message, + $effectiveQos, + $subscriber->nextPacketId(), + $subscriber->protocol, + )); + $mqtt->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); + } + }); + } catch (\Throwable $error) { + $attempts++; + Console::error('MQTT pub/sub connection error: ' . $error->getMessage()); + sleep(DATABASE_RECONNECT_SLEEP); + } + } + + Console::error('Failed to maintain MQTT pub/sub subscription'); + }); +}); + +$server->onReceive(function (int $fd, string $data) use ( + $server, $mqtt, $dispatcher, $authenticate, @@ -260,12 +323,12 @@ $adapter->onReceive(function (int $fd, string $data) use ( $span->set('project.id', $connection->projectId); $span->set('user.id', $connection->identity['userId'] ?? ''); - $reply = function (string $packet = '', bool $close = false) use ($adapter, $fd): void { + $reply = function (string $packet = '', bool $close = false) use ($server, $fd): void { if ($packet !== '') { - $adapter->send($fd, $packet); + $server->send($fd, $packet); } if ($close) { - $adapter->close($fd); + $server->close($fd); } }; @@ -286,8 +349,8 @@ $adapter->onReceive(function (int $fd, string $data) use ( } }); -$adapter->onClose(function (int $fd) use ($mqtt): void { +$server->onClose(function (int $fd) use ($mqtt): void { $mqtt->close($fd); }); -$adapter->start(); +$server->start(); From c9eaa15efa477783c73dd08fc08f0fe09031b9ad Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 13:00:41 +0530 Subject: [PATCH 035/146] add unit test for the MQTT push adapter --- .../Appwrite/Messaging/Adapter/MqttTest.php | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 tests/unit/Appwrite/Messaging/Adapter/MqttTest.php diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php new file mode 100644 index 0000000000..f0de711b0f --- /dev/null +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -0,0 +1,149 @@ +open($fd); + $mqtt->subscribe($projectId, $fd, $subId, [], [$topic]); + } + + public function testOpenCreatesAndReusesConnection(): void + { + $mqtt = $this->adapter(); + + $connection = $mqtt->open(7); + + $this->assertInstanceOf(Connection::class, $connection); + $this->assertSame(7, $connection->fd); + $this->assertSame($connection, $mqtt->open(7), 'open() must return the same instance for the same fd'); + $this->assertArrayHasKey(7, $mqtt->connections); + } + + public function testSubscribeExposesSubscriberWithGrantedQos(): void + { + $mqtt = $this->adapter(); + + $this->join($mqtt, 'project-a', 11, 'appwrite/push/user-1'); + + $this->assertSame([11 => 1], $mqtt->getSubscribers('project-a', 'appwrite/push/user-1')); + $this->assertTrue($mqtt->hasSubscriber('project-a', 'appwrite/push/user-1')); + $this->assertFalse($mqtt->hasSubscriber('project-a', 'appwrite/push/user-2')); + } + + /** + * Topic-filter matching flows through to the store: + is one level, # is this + * level onward, an exact filter matches only itself. + * + * @return array + */ + public static function wildcardProvider(): array + { + return [ + 'exact match' => ['test/hello', 'test/hello', true], + 'exact miss' => ['test/hello', 'test/world', false], + '+ one level' => ['test/+', 'test/hello', true], + '+ not multi level' => ['test/+', 'test/a/b', false], + '# multi level' => ['test/#', 'test/a/b', true], + '# matches parent' => ['test/#', 'test', true], + '# not sibling' => ['test/#', 'other', false], + ]; + } + + #[DataProvider('wildcardProvider')] + public function testTopicFilterMatching(string $filter, string $publishTopic, bool $shouldMatch): void + { + $mqtt = $this->adapter(); + $this->join($mqtt, 'project-a', 21, $filter); + + $subscribers = $mqtt->getSubscribers('project-a', $publishTopic); + + $this->assertSame($shouldMatch, isset($subscribers[21])); + } + + public function testSubscribersAreIsolatedPerProject(): void + { + $mqtt = $this->adapter(); + + $this->join($mqtt, 'project-a', 31, 'shared/topic'); + $this->join($mqtt, 'project-b', 32, 'shared/topic'); + + $this->assertSame([31 => 1], $mqtt->getSubscribers('project-a', 'shared/topic')); + $this->assertSame([32 => 1], $mqtt->getSubscribers('project-b', 'shared/topic')); + } + + public function testUnsubscribeSubscriptionRemovesOnlyThatFilter(): void + { + $mqtt = $this->adapter(); + $mqtt->open(41); + $mqtt->subscribe('project-a', 41, 'sub-orders', [], ['orders/new']); + $mqtt->subscribe('project-a', 41, 'sub-alerts', [], ['alerts/all']); + + $mqtt->unsubscribeSubscription(41, 'sub-orders'); + + $this->assertFalse($mqtt->hasSubscriber('project-a', 'orders/new')); + $this->assertSame([41 => 1], $mqtt->getSubscribers('project-a', 'alerts/all')); + } + + public function testSubscriptionIdFallsBackToTopic(): void + { + $mqtt = $this->adapter(); + // Empty subscription id: the topic itself becomes the id used for removal. + $this->join($mqtt, 'project-a', 51, 'news/tech'); + + $mqtt->unsubscribeSubscription(51, 'news/tech'); + + $this->assertFalse($mqtt->hasSubscriber('project-a', 'news/tech')); + } + + public function testUnsubscribeRemovesEveryFilterForConnection(): void + { + $mqtt = $this->adapter(); + $mqtt->open(61); + $mqtt->subscribe('project-a', 61, 'a', [], ['a/one']); + $mqtt->subscribe('project-a', 61, 'b', [], ['b/two']); + + $mqtt->unsubscribe(61); + + $this->assertFalse($mqtt->hasSubscriber('project-a', 'a/one')); + $this->assertFalse($mqtt->hasSubscriber('project-a', 'b/two')); + } + + public function testCloseRemovesSubscriptionsAndForgetsConnection(): void + { + $mqtt = $this->adapter(); + $connection = $mqtt->open(71); + $connection->active = true; + $mqtt->subscribe('project-a', 71, 'sub', [], ['live/feed']); + + $mqtt->close(71); + + $this->assertArrayNotHasKey(71, $mqtt->connections); + $this->assertFalse($mqtt->hasSubscriber('project-a', 'live/feed')); + $this->assertNotSame($connection, $mqtt->open(71), 'a reopened fd is a fresh connection'); + } +} From 19125da0ed00ebe2111d1528e251aefa82c9b5fd Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 27 Aug 2026 13:27:01 +0530 Subject: [PATCH 036/146] fixed tls --- docker-compose.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index f218625c3c..22e0edfb1c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -346,8 +346,6 @@ services: - traefik.tcp.services.appwrite_mqtt.loadbalancer.server.port=1883 networks: - appwrite - ports: - - 1883:1883 environment: - _APP_ENV - _APP_WORKER_PER_CORE From 0696509ca58c07277c17ed9f2afc26ed33192b93 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 28 Aug 2026 11:41:23 +0530 Subject: [PATCH 037/146] adopt the utopia-php/mqtt package for the broker transport and codec Pull the extracted transport (Adapter/Swoole/Server/Client) and MQTT codec (Packet + V3/V5 encoders, Properties/Property) from the new utopia-php/mqtt package instead of the in-repo copies, and migrate the broker off the local Packet onto the package's version-split codec. - composer: add the utopia-php/mqtt VCS repo and require dev-dev - remove the in-repo Adapter, Adapter/Swoole, Server and Packet, now provided by the package - rewrite the handlers' inline byte-work to V3/V5 encoders and Properties/Property parsing; CONNACK/SUBACK now carry each version's own acknowledgement vocabulary (v3 return codes, v5 reason codes) rather than sending v5 reason codes to 3.1.1 clients The broker classes (Connection, Dispatcher, Metrics, SubscriptionStore, Handlers) stay under Utopia\Mqtt in this repo; Composer merges the PSR-4 prefix across the app and the package with no class-name overlap. --- app/mqtt.php | 13 +- composer.json | 5 + composer.lock | 65 +++++++- src/Utopia/Mqtt/Adapter.php | 88 ---------- src/Utopia/Mqtt/Adapter/Swoole.php | 109 ------------- src/Utopia/Mqtt/Handlers/Auth.php | 42 ++--- src/Utopia/Mqtt/Handlers/Connect.php | 34 ++-- src/Utopia/Mqtt/Handlers/Ping.php | 2 +- src/Utopia/Mqtt/Handlers/Publish.php | 13 +- src/Utopia/Mqtt/Handlers/Subscribe.php | 28 +++- src/Utopia/Mqtt/Handlers/Unsubscribe.php | 23 ++- src/Utopia/Mqtt/Packet.php | 199 ----------------------- src/Utopia/Mqtt/Server.php | 111 ------------- 13 files changed, 160 insertions(+), 572 deletions(-) delete mode 100644 src/Utopia/Mqtt/Adapter.php delete mode 100644 src/Utopia/Mqtt/Adapter/Swoole.php delete mode 100644 src/Utopia/Mqtt/Packet.php delete mode 100644 src/Utopia/Mqtt/Server.php diff --git a/app/mqtt.php b/app/mqtt.php index 6b9a8e4a4b..97d073e12d 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -26,6 +26,8 @@ use Utopia\Mqtt\Handlers\Publish as PublishHandler; use Utopia\Mqtt\Handlers\Subscribe as SubscribeHandler; use Utopia\Mqtt\Handlers\Unsubscribe as UnsubscribeHandler; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Packet\V3; +use Utopia\Mqtt\Packet\V5; use Utopia\Mqtt\Server; use Utopia\Pools\Group; use Utopia\Registry\Registry; @@ -287,13 +289,10 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): continue; } $effectiveQos = min($qos, $grantedQos); - $server->send($fd, Packet::publish( - $topic, - $message, - $effectiveQos, - $subscriber->nextPacketId(), - $subscriber->protocol, - )); + $packetId = $subscriber->nextPacketId(); + $server->send($fd, $subscriber->protocol >= 5 + ? V5::publish($topic, $message, $effectiveQos, $packetId) + : V3::publish($topic, $message, $effectiveQos, $packetId)); $mqtt->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); } }); diff --git a/composer.json b/composer.json index b5668042fa..812087cf62 100644 --- a/composer.json +++ b/composer.json @@ -102,6 +102,10 @@ { "type": "vcs", "url": "https://github.com/utopia-php/vcs" + }, + { + "type": "vcs", + "url": "https://github.com/utopia-php/mqtt" } ], "require": { @@ -145,6 +149,7 @@ "utopia-php/logger": "0.8.*", "utopia-php/messaging": "^2.1", "utopia-php/migration": "^2.0.0", + "utopia-php/mqtt": "dev-dev", "utopia-php/platform": "^1.0@RC", "utopia-php/pools": "2.*", "utopia-php/span": "3.0.*", diff --git a/composer.lock b/composer.lock index 2885447322..0ae3cfe482 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "9cc2463aa88f43848b152cf521b2bc24", + "content-hash": "147d04eecbbad30bffda849d77c6dec0", "packages": [ { "name": "adhocore/jwt", @@ -4370,6 +4370,68 @@ }, "time": "2026-08-13T01:55:11+00:00" }, + { + "name": "utopia-php/mqtt", + "version": "dev-dev", + "source": { + "type": "git", + "url": "git@github.com:utopia-php/mqtt.git", + "reference": "183f0603f94be4602075b9f7931c50412b8701b0" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/183f0603f94be4602075b9f7931c50412b8701b0", + "reference": "183f0603f94be4602075b9f7931c50412b8701b0", + "shasum": "" + }, + "require": { + "php": ">=8.1" + }, + "require-dev": { + "laravel/pint": "^1.15", + "phpstan/phpstan": "^1.12", + "phpunit/phpunit": "^10.5", + "swoole/ide-helper": "5.1.2" + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\Mqtt\\": "src/Mqtt" + } + }, + "autoload-dev": { + "psr-4": { + "Utopia\\Mqtt\\Tests\\": "tests" + } + }, + "scripts": { + "test": [ + "./vendor/bin/phpunit" + ], + "lint": [ + "./vendor/bin/pint --test --preset=psr12 src tests" + ], + "format": [ + "./vendor/bin/pint --preset=psr12 src tests" + ], + "check": [ + "./vendor/bin/phpstan analyse --level max src tests" + ] + }, + "license": [ + "MIT" + ], + "description": "A simple abstraction for building MQTT 5.0 brokers.", + "keywords": [ + "broker", + "framework", + "mqtt", + "php", + "upf", + "utopia" + ], + "time": "2026-08-28T05:53:03+00:00" + }, { "name": "utopia-php/platform", "version": "1.0.999", @@ -8506,6 +8568,7 @@ "minimum-stability": "dev", "stability-flags": { "utopia-php/http": 5, + "utopia-php/mqtt": 20, "utopia-php/platform": 5 }, "prefer-stable": true, diff --git a/src/Utopia/Mqtt/Adapter.php b/src/Utopia/Mqtt/Adapter.php deleted file mode 100644 index bd7a5bf360..0000000000 --- a/src/Utopia/Mqtt/Adapter.php +++ /dev/null @@ -1,88 +0,0 @@ - */ - protected array $config = []; - - public function __construct(string $host = '0.0.0.0', int $port = 1883) - { - $this->host = $host; - $this->port = $port; - } - - /** - * Starts the server. - */ - abstract public function start(): void; - - /** - * Shuts down the server. - */ - abstract public function shutdown(): void; - - /** - * Sends raw bytes to a single connection. - * - * @param int $connection Connection ID. - * @param string $message Encoded MQTT packet. - */ - abstract public function send(int $connection, string $message): void; - - /** - * Closes a connection. - * - * @param int $connection Connection ID. - */ - abstract public function close(int $connection): void; - - /** - * Is called when the server starts. - */ - abstract public function onStart(callable $callback): self; - - /** - * Is called when a worker starts. - */ - abstract public function onWorkerStart(callable $callback): self; - - /** - * Is called when a framed MQTT packet is received. The callback is invoked - * with (int $connection, string $data). - */ - abstract public function onReceive(callable $callback): self; - - /** - * Is called when a connection is closed. The callback is invoked with - * (int $connection). - */ - abstract public function onClose(callable $callback): self; - - /** - * Sets the maximum packet length in bytes. - */ - abstract public function setPackageMaxLength(int $bytes): self; - - /** - * Sets the number of workers. - */ - abstract public function setWorkerNumber(int $num): self; - - /** - * Returns the native server object from the adapter. - */ - abstract public function getNative(): mixed; - - /** - * Returns all connections. - * - * @return array - */ - abstract public function getConnections(): array; -} diff --git a/src/Utopia/Mqtt/Adapter/Swoole.php b/src/Utopia/Mqtt/Adapter/Swoole.php deleted file mode 100644 index a0cdf36a94..0000000000 --- a/src/Utopia/Mqtt/Adapter/Swoole.php +++ /dev/null @@ -1,109 +0,0 @@ - */ - private static array $connections = []; - - public function __construct(string $host = '0.0.0.0', int $port = 1883) - { - parent::__construct($host, $port); - - $this->server = new Server($this->host, $this->port, SWOOLE_BASE); - - $this->config['open_mqtt_protocol'] = true; - $this->config['worker_num'] = 1; - } - - public function start(): void - { - $this->server->set($this->config); - $this->server->start(); - } - - public function shutdown(): void - { - $this->server->shutdown(); - } - - public function send(int $connection, string $message): void - { - $this->server->send($connection, $message); - } - - public function close(int $connection): void - { - $this->server->close($connection); - } - - public function onStart(callable $callback): self - { - $this->server->on('start', function () use ($callback) { - call_user_func($callback); - }); - - return $this; - } - - public function onWorkerStart(callable $callback): self - { - $this->server->on('workerStart', function (Server $server, int $workerId) use ($callback) { - call_user_func($callback, $workerId); - }); - - return $this; - } - - public function onReceive(callable $callback): self - { - $this->server->on('receive', function (Server $server, int $fd, int $reactorId, string $data) use ($callback) { - self::$connections[$fd] = true; - - call_user_func($callback, $fd, $data); - }); - - return $this; - } - - public function onClose(callable $callback): self - { - $this->server->on('close', function (Server $server, int $fd) use ($callback) { - unset(self::$connections[$fd]); - - call_user_func($callback, $fd); - }); - - return $this; - } - - public function setPackageMaxLength(int $bytes): self - { - $this->config['package_max_length'] = $bytes; - - return $this; - } - - public function setWorkerNumber(int $num): self - { - $this->config['worker_num'] = $num; - - return $this; - } - - public function getNative(): Server - { - return $this->server; - } - - public function getConnections(): array - { - return array_keys(self::$connections); - } -} diff --git a/src/Utopia/Mqtt/Handlers/Auth.php b/src/Utopia/Mqtt/Handlers/Auth.php index 1991aec1e6..daac0b8059 100644 --- a/src/Utopia/Mqtt/Handlers/Auth.php +++ b/src/Utopia/Mqtt/Handlers/Auth.php @@ -5,6 +5,9 @@ namespace Utopia\Mqtt\Handlers; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Packet\V5; +use Utopia\Mqtt\Properties; +use Utopia\Mqtt\Property; use Utopia\Platform\Action; class Auth extends Action @@ -33,12 +36,12 @@ class Auth extends Action $userProperties = []; if ($body !== '') { - // $body[0] is the reason code (0x19 re-authenticate) - // from the offset 1 everything is the mqtt v5 properties - $properties = Packet::readProperties($body, 1, $connection->protocol); - $method = $properties['authMethod']; - $data = $properties['authData']; - $userProperties = $properties['user']; + // $body[0] is the reason code (0x19 re-authenticate); + // from offset 1 everything is the MQTT 5.0 property block. + [$properties] = Properties::parse($body, 1); + $method = (string) ($properties->get(Property::AUTHENTICATION_METHOD) ?? ''); + $data = (string) ($properties->get(Property::AUTHENTICATION_DATA) ?? ''); + $userProperties = $properties->user(); } // The AUTH packet re-sends projectId as a User Property. @@ -53,34 +56,19 @@ class Auth extends Action : []; if ($identity === []) { - $reply($this->disconnect(Packet::REASON_NOT_AUTHORIZED), true); + $reply(V5::disconnect(V5::REASON_NOT_AUTHORIZED), true); return; } $connection->identity = $identity; } - // Acknowledge success on the live connection with an AUTH packet. - $reply($this->auth(Packet::AUTH_SUCCESS, $method), false); - } - - private function disconnect(int $reasonCode): string - { - return chr(Packet::DISCONNECT << 4) . Packet::encodeLength(1) . chr($reasonCode); - } - - private function auth(int $reasonCode, string $method, string $data = ''): string - { - $properties = ''; + // Acknowledge success on the live connection with an AUTH packet that echoes + // the authentication method back. + $properties = new Properties(); if ($method !== '') { - $properties .= chr(Packet::PROP_AUTH_METHOD) . Packet::encodeString($method); + $properties->add(new Property(Property::AUTHENTICATION_METHOD, $method)); } - if ($data !== '') { - $properties .= chr(Packet::PROP_AUTH_DATA) . Packet::encodeString($data); - } - - $variable = chr($reasonCode) . Packet::encodeLength(strlen($properties)) . $properties; - - return chr(Packet::AUTH << 4) . Packet::encodeLength(strlen($variable)) . $variable; + $reply(V5::auth(V5::AUTH_SUCCESS, $properties), false); } } diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php index fc4ce1a124..2ec65a71a5 100644 --- a/src/Utopia/Mqtt/Handlers/Connect.php +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -6,6 +6,10 @@ use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Packet\V3; +use Utopia\Mqtt\Packet\V5; +use Utopia\Mqtt\Properties; +use Utopia\Mqtt\Property; use Utopia\Platform\Action; use Utopia\Span\Span; @@ -40,22 +44,30 @@ class Connect extends Action $offset += 1; // connect flags $offset += 2; // keep alive - $properties = Packet::readProperties($body, $offset, $level); + // MQTT 3.1.1 carries no property block; enhanced auth and metadata are 5.0 only. + $authMethod = ''; + $authData = ''; + $user = []; + if ($level >= 5) { + [$properties] = Properties::parse($body, $offset); + $authMethod = (string) ($properties->get(Property::AUTHENTICATION_METHOD) ?? ''); + $authData = (string) ($properties->get(Property::AUTHENTICATION_DATA) ?? ''); + $user = $properties->user(); + } - $projectId = $properties['user']['projectId'] ?? ''; + $projectId = $user['projectId'] ?? ''; $connection->projectId = $projectId; - $authMethod = $properties['authMethod']; Span::add('project.id', $projectId); Span::add('mqtt.auth_method', $authMethod); // TODO: add abuse limiting keyed on the client ip. if ($authenticator !== null) { - $identity = $authenticator($projectId, $authMethod, $properties['authData']); + $identity = $authenticator($projectId, $authMethod, $authData); if ($identity === []) { $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); Span::add('mqtt.result', 'rejected'); - $reply($this->connack($level, Packet::REASON_NOT_AUTHORIZED), true); + $reply($this->connack($level, false), true); return; } @@ -66,14 +78,16 @@ class Connect extends Action $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); $mqtt->metrics->connectionsActive->add(1); $connection->active = true; - $reply($this->connack($level, Packet::REASON_SUCCESS), false); + $reply($this->connack($level, true), false); } - private function connack(int $level, int $reasonCode): string + /** CONNACK, with the acknowledgement code in each version's own vocabulary. */ + private function connack(int $level, bool $accepted): string { - // CONNACK: [ack flags = 0][reason code](+ [property length = 0] for v5) - $variable = chr(0x00) . chr($reasonCode) . ($level >= 5 ? Packet::encodeLength(0) : ''); + if ($level >= 5) { + return V5::connack($accepted ? V5::REASON_SUCCESS : V5::REASON_NOT_AUTHORIZED); + } - return chr(Packet::CONNACK << 4) . Packet::encodeLength(strlen($variable)) . $variable; + return V3::connack($accepted ? V3::RETURN_ACCEPTED : V3::RETURN_NOT_AUTHORIZED); } } diff --git a/src/Utopia/Mqtt/Handlers/Ping.php b/src/Utopia/Mqtt/Handlers/Ping.php index b01a7dee6c..84d40ffc18 100644 --- a/src/Utopia/Mqtt/Handlers/Ping.php +++ b/src/Utopia/Mqtt/Handlers/Ping.php @@ -22,6 +22,6 @@ class Ping extends Action */ public function action(callable $reply): void { - $reply(chr(Packet::PINGRESP << 4) . Packet::encodeLength(0), false); + $reply(Packet::pingresp(), false); } } diff --git a/src/Utopia/Mqtt/Handlers/Publish.php b/src/Utopia/Mqtt/Handlers/Publish.php index 3025413723..b4e7699226 100644 --- a/src/Utopia/Mqtt/Handlers/Publish.php +++ b/src/Utopia/Mqtt/Handlers/Publish.php @@ -6,6 +6,9 @@ use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Packet\V3; +use Utopia\Mqtt\Packet\V5; +use Utopia\Mqtt\Properties; use Utopia\Platform\Action; use Utopia\Span\Span; @@ -29,7 +32,7 @@ class Publish extends Action public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void { $body = $packet->body; - $qos = ($packet->flags >> 1) & 0x03; + $qos = $packet->qos(); [$topic, $offset] = Packet::readString($body, 0); @@ -38,7 +41,9 @@ class Publish extends Action $packetId = substr($body, $offset, 2); $offset += 2; } - $offset = Packet::skipProperties($body, $offset, $connection->protocol); + if ($connection->protocol >= 5) { + $offset = Properties::skip($body, $offset); + } $payload = substr($body, $offset); Span::add('mqtt.topic', $topic); @@ -47,8 +52,8 @@ class Publish extends Action $mqtt->send($connection->projectId, [], [], [$topic], [], ['payload' => $payload, 'qos' => $qos]); if ($qos === 1) { - // PUBACK: packet id (reason/properties omitted -> valid for both versions) - $reply(chr(Packet::PUBACK << 4) . Packet::encodeLength(strlen($packetId)) . $packetId, false); + // PUBACK is a bare packet id in both versions (reason/properties omitted). + $reply($connection->protocol >= 5 ? V5::puback($packetId) : V3::puback($packetId), false); } } } diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index f9d55880ef..7c9144b04f 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -6,6 +6,9 @@ use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Packet\V3; +use Utopia\Mqtt\Packet\V5; +use Utopia\Mqtt\Properties; use Utopia\Platform\Action; use Utopia\Span\Span; @@ -35,20 +38,28 @@ class Subscribe extends Action $packetId = substr($body, 0, 2); $offset += 2; - $subId = Packet::readProperties($body, $offset, $connection->protocol)['user']['subId'] ?? ''; - $offset = Packet::skipProperties($body, $offset, $connection->protocol); + $subId = ''; + if ($connection->protocol >= 5) { + [$properties, $offset] = Properties::parse($body, $offset); + $subId = (string) ($properties->user()['subId'] ?? ''); + } $identity = $connection->identity; + // A denied filter answers with each version's own failure marker; a granted one + // with max QoS 1 (0x01), which is a granted-QoS byte in 3.1.1 and a Success + // reason code in 5.0. + $denied = $connection->protocol >= 5 ? V5::REASON_NOT_AUTHORIZED : V3::SUBSCRIBE_FAILURE; + $granted = ''; while ($offset < strlen($body)) { [$filter, $offset] = Packet::readString($body, $offset); $offset += 1; // subscription options byte Span::add('mqtt.topic', $filter); - // ACL: an unauthorized filter is answered Not Authorized and never stored. + // ACL: an unauthorized filter is refused and never stored. if ($authorizer !== null && !$authorizer($identity, $filter)) { - $granted .= chr(Packet::REASON_NOT_AUTHORIZED); + $granted .= chr($denied); $mqtt->metrics->subscriptions->add(1, ['result' => 'denied']); Span::add('mqtt.result', 'denied'); continue; @@ -59,8 +70,11 @@ class Subscribe extends Action $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); } - // SUBACK: packet id (+ property length 0 for v5) + granted codes - $variable = $packetId . ($connection->protocol >= 5 ? Packet::encodeLength(0) : '') . $granted; - $reply(chr(Packet::SUBACK << 4) . Packet::encodeLength(strlen($variable)) . $variable, false); + $reply( + $connection->protocol >= 5 + ? V5::suback($packetId, $granted) + : V3::suback($packetId, $granted), + false, + ); } } diff --git a/src/Utopia/Mqtt/Handlers/Unsubscribe.php b/src/Utopia/Mqtt/Handlers/Unsubscribe.php index d407745f11..d9112a00d6 100644 --- a/src/Utopia/Mqtt/Handlers/Unsubscribe.php +++ b/src/Utopia/Mqtt/Handlers/Unsubscribe.php @@ -6,6 +6,9 @@ use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Packet\V3; +use Utopia\Mqtt\Packet\V5; +use Utopia\Mqtt\Properties; use Utopia\Platform\Action; class Unsubscribe extends Action @@ -32,8 +35,11 @@ class Unsubscribe extends Action $packetId = substr($body, 0, 2); $offset += 2; - $subId = Packet::readProperties($body, $offset, $connection->protocol)['user']['subId'] ?? ''; - $offset = Packet::skipProperties($body, $offset, $connection->protocol); + $subId = ''; + if ($connection->protocol >= 5) { + [$properties, $offset] = Properties::parse($body, $offset); + $subId = (string) ($properties->user()['subId'] ?? ''); + } $count = 0; while ($offset < strlen($body)) { @@ -42,11 +48,12 @@ class Unsubscribe extends Action $count++; } - // UNSUBACK: packet id (+ property length 0 + one reason code per filter for v5) - $variable = $packetId; - if ($connection->protocol >= 5) { - $variable .= Packet::encodeLength(0) . str_repeat(chr(Packet::REASON_SUCCESS), $count); - } - $reply(chr(Packet::UNSUBACK << 4) . Packet::encodeLength(strlen($variable)) . $variable, false); + // 5.0 carries a Success reason code per filter; 3.1.1 UNSUBACK is bare. + $reply( + $connection->protocol >= 5 + ? V5::unsuback($packetId, $count) + : V3::unsuback($packetId), + false, + ); } } diff --git a/src/Utopia/Mqtt/Packet.php b/src/Utopia/Mqtt/Packet.php deleted file mode 100644 index c21cd7277f..0000000000 --- a/src/Utopia/Mqtt/Packet.php +++ /dev/null @@ -1,199 +0,0 @@ -> 4; - $flags = ord($data[0]) & 0x0F; - - [$remaining, $lenBytes] = self::decodeLength($data, 1); - $body = substr($data, 1 + $lenBytes, $remaining); - - return new self($type, $flags, $body); - } - - public function name(): string - { - return match ($this->type) { - self::CONNECT => 'connect', - self::SUBSCRIBE => 'subscribe', - self::UNSUBSCRIBE => 'unsubscribe', - self::PUBLISH => 'publish', - self::PUBACK => 'puback', - self::AUTH => 'auth', - self::PINGREQ => 'pingreq', - self::DISCONNECT => 'disconnect', - default => 'unknown', - }; - } - - /** - * Encode an outbound PUBLISH for one subscriber. The variable header order is - * topic, packet id (QoS > 0), v5 property block, then payload. The packet id and - * protocol level are the subscriber's, not the publisher's. - */ - public static function publish(string $topic, string $payload, int $qos, int $packetId, int $protocol): string - { - $variable = self::encodeString($topic); - if ($qos > 0) { - $variable .= chr($packetId >> 8) . chr($packetId & 0xFF); - } - $variable .= ($protocol >= 5 ? self::encodeLength(0) : '') . $payload; - - $header = chr((self::PUBLISH << 4) | ($qos << 1)); - - return $header . self::encodeLength(strlen($variable)) . $variable; - } - - /** - * Read a v5 property block: User Properties as a key/value map plus the - * Authentication Method and Data. Shared by CONNECT and AUTH, which carry an - * identical block. No-op for MQTT 3.1.1 (no properties). - * - * @return array{user: array, authMethod: string, authData: string} - */ - public static function readProperties(string $body, int $offset, int $protocol): array - { - $properties = ['user' => [], 'authMethod' => '', 'authData' => '']; - - if ($protocol < 5) { - return $properties; - } - - [$length, $lenBytes] = self::decodeLength($body, $offset); - $offset += $lenBytes; - $end = $offset + $length; - - while ($offset < $end) { - $id = ord($body[$offset]); - $offset++; - - switch ($id) { - case self::PROP_AUTH_METHOD: - [$properties['authMethod'], $offset] = self::readString($body, $offset); - break; - case self::PROP_AUTH_DATA: - [$properties['authData'], $offset] = self::readString($body, $offset); - break; - case self::PROP_USER: - [$key, $offset] = self::readString($body, $offset); - [$value, $offset] = self::readString($body, $offset); - $properties['user'][$key] = $value; - break; - default: - // POC assumption: clients send only auth and user properties. - throw new \RuntimeException('Unhandled connect property 0x' . dechex($id)); - } - } - - return $properties; - } - - /** - * Skip the MQTT 5.0 property block (variable-length length prefix + bytes). - * No-op for MQTT 3.1.1, which has no properties. - */ - public static function skipProperties(string $body, int $offset, int $protocol): int - { - if ($protocol < 5) { - return $offset; - } - [$length, $lenBytes] = self::decodeLength($body, $offset); - - return $offset + $lenBytes + $length; - } - - /** @return array{0: string, 1: int} decoded string and the new offset */ - public static function readString(string $data, int $offset): array - { - $length = (ord($data[$offset]) << 8) + ord($data[$offset + 1]); - $value = substr($data, $offset + 2, $length); - - return [$value, $offset + 2 + $length]; - } - - public static function encodeString(string $value): string - { - $length = strlen($value); - - return chr($length >> 8) . chr($length & 0xFF) . $value; - } - - /** Decode a variable-length integer. @return array{0: int, 1: int} value and byte count */ - public static function decodeLength(string $data, int $offset): array - { - $value = 0; - $multiplier = 1; - $bytes = 0; - do { - $byte = ord($data[$offset + $bytes]); - $value += ($byte & 0x7F) * $multiplier; - $multiplier *= 128; - $bytes++; - } while (($byte & 0x80) !== 0); - - return [$value, $bytes]; - } - - public static function encodeLength(int $length): string - { - $out = ''; - do { - $byte = $length % 128; - $length = intdiv($length, 128); - if ($length > 0) { - $byte |= 0x80; - } - $out .= chr($byte); - } while ($length > 0); - - return $out; - } -} diff --git a/src/Utopia/Mqtt/Server.php b/src/Utopia/Mqtt/Server.php deleted file mode 100644 index ca47e84e1d..0000000000 --- a/src/Utopia/Mqtt/Server.php +++ /dev/null @@ -1,111 +0,0 @@ - */ - protected array $errorCallbacks = []; - - protected Adapter $adapter; - - public function __construct(Adapter $adapter) - { - $this->adapter = $adapter; - } - - public function start(): void - { - try { - $this->adapter->start(); - } catch (Throwable $error) { - $this->onError($error, 'start'); - } - } - - public function shutdown(): void - { - try { - $this->adapter->shutdown(); - } catch (Throwable $error) { - $this->onError($error, 'shutdown'); - } - } - - public function send(int $connection, string $message): void - { - try { - $this->adapter->send($connection, $message); - } catch (Throwable $error) { - $this->onError($error, 'send'); - } - } - - public function close(int $connection): void - { - try { - $this->adapter->close($connection); - } catch (Throwable $error) { - $this->onError($error, 'close'); - } - } - - public function onStart(callable $callback): self - { - $this->adapter->onStart($callback); - - return $this; - } - - public function onWorkerStart(callable $callback): self - { - $this->adapter->onWorkerStart($callback); - - return $this; - } - - public function onReceive(callable $callback): self - { - $this->adapter->onReceive($callback); - - return $this; - } - - public function onClose(callable $callback): self - { - $this->adapter->onClose($callback); - - return $this; - } - - /** - * @return array - */ - public function getConnections(): array - { - return $this->adapter->getConnections(); - } - - /** Register a callback run when a transport operation throws. */ - public function error(callable $callback): self - { - $this->errorCallbacks[] = $callback; - - return $this; - } - - private function onError(Throwable $error, string $action): void - { - foreach ($this->errorCallbacks as $callback) { - $callback($error, $action); - } - } -} From 91aa35941d55d9f6868602a927eb2fa1e19aeb3e Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 28 Aug 2026 12:52:07 +0530 Subject: [PATCH 038/146] yield MQTT test data providers to satisfy the Refactor check Rector's YieldDataProviderRector converts the wildcard/match data providers from returned arrays to yielded generators; apply it so composer refactor:check (the CI Refactor gate) passes. --- .../Appwrite/Messaging/Adapter/MqttTest.php | 20 +++++----- .../Utopia/Mqtt/SubscriptionStoreTest.php | 38 +++++++++---------- 2 files changed, 26 insertions(+), 32 deletions(-) diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php index f0de711b0f..229180ba4b 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -59,19 +59,17 @@ final class MqttTest extends TestCase * Topic-filter matching flows through to the store: + is one level, # is this * level onward, an exact filter matches only itself. * - * @return array + * @return \Iterator */ - public static function wildcardProvider(): array + public static function wildcardProvider(): \Iterator { - return [ - 'exact match' => ['test/hello', 'test/hello', true], - 'exact miss' => ['test/hello', 'test/world', false], - '+ one level' => ['test/+', 'test/hello', true], - '+ not multi level' => ['test/+', 'test/a/b', false], - '# multi level' => ['test/#', 'test/a/b', true], - '# matches parent' => ['test/#', 'test', true], - '# not sibling' => ['test/#', 'other', false], - ]; + yield 'exact match' => ['test/hello', 'test/hello', true]; + yield 'exact miss' => ['test/hello', 'test/world', false]; + yield '+ one level' => ['test/+', 'test/hello', true]; + yield '+ not multi level' => ['test/+', 'test/a/b', false]; + yield '# multi level' => ['test/#', 'test/a/b', true]; + yield '# matches parent' => ['test/#', 'test', true]; + yield '# not sibling' => ['test/#', 'other', false]; } #[DataProvider('wildcardProvider')] diff --git a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php index 7cd9644843..307265ce51 100644 --- a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php +++ b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php @@ -20,29 +20,25 @@ final class SubscriptionStoreTest extends TestCase } /** - * @return array + * @return \Iterator */ - public static function matchProvider(): array + public static function matchProvider(): \Iterator { - return [ - // filter, publish topic, should match - 'exact single level' => ['sport', 'sport', true], - 'exact rejects deeper' => ['sport', 'sport/x', false], - 'exact rejects sibling' => ['a/b', 'a/c', false], - - '+ matches one level' => ['sport/+', 'sport/x', true], - '+ requires a level' => ['sport/+', 'sport', false], - '+ does not span two levels' => ['sport/+', 'sport/x/y', false], - '+ leading level' => ['+/hello', 'test/hello', true], - '+ leading needs a level' => ['+/hello', 'hello', false], - '+ interior level' => ['test/+/x', 'test/a/x', true], - '+ interior is single level' => ['test/+/x', 'test/a/b/x', false], - - '# matches parent level' => ['sport/#', 'sport', true], - '# matches one deeper' => ['sport/#', 'sport/x', true], - '# matches many deeper' => ['sport/#', 'sport/x/y', true], - 'root # matches everything' => ['#', 'a/b/c', true], - ]; + // filter, publish topic, should match + yield 'exact single level' => ['sport', 'sport', true]; + yield 'exact rejects deeper' => ['sport', 'sport/x', false]; + yield 'exact rejects sibling' => ['a/b', 'a/c', false]; + yield '+ matches one level' => ['sport/+', 'sport/x', true]; + yield '+ requires a level' => ['sport/+', 'sport', false]; + yield '+ does not span two levels' => ['sport/+', 'sport/x/y', false]; + yield '+ leading level' => ['+/hello', 'test/hello', true]; + yield '+ leading needs a level' => ['+/hello', 'hello', false]; + yield '+ interior level' => ['test/+/x', 'test/a/x', true]; + yield '+ interior is single level' => ['test/+/x', 'test/a/b/x', false]; + yield '# matches parent level' => ['sport/#', 'sport', true]; + yield '# matches one deeper' => ['sport/#', 'sport/x', true]; + yield '# matches many deeper' => ['sport/#', 'sport/x/y', true]; + yield 'root # matches everything' => ['#', 'a/b/c', true]; } #[DataProvider('matchProvider')] From 5bafaad6b408734540b108dd93afe40c99d5e7d5 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 1 Sep 2026 09:52:03 +0530 Subject: [PATCH 039/146] fix: update content-hash in composer.lock to match current dependencies --- composer.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.lock b/composer.lock index d8ae453e5d..2859fd9b73 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "8421ff4db771a69dea3af12a11983553", + "content-hash": "e92a2d45ca21384279458ee6203fefe2", "packages": [ { "name": "adhocore/jwt", From 2b6393da2ee8d54d1a3b6c52b8498271446d1022 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 1 Sep 2026 11:03:34 +0530 Subject: [PATCH 040/146] fix: update MessagingMqttServerTest to use dynamic autoloader path and add group attribute --- .../Services/Messaging/MessagingMqttServerTest.php | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 06c3d792d5..78243c30d7 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -4,6 +4,7 @@ declare(strict_types=1); namespace Tests\E2E\Services\Messaging; +use PHPUnit\Framework\Attributes\Group; use Tests\E2E\Client; use Tests\E2E\Scopes\ProjectCustom; use Tests\E2E\Scopes\Scope; @@ -20,7 +21,12 @@ use Utopia\Messaging\Messages\Push; * * Blocked accounts are refused at CONNECT (CONNACK 0x87); the subscribe authorizer * re-checks as defense in depth. (Topic-existence authorization is still pending.) + * + * Grouped `mqtt` because it needs the broker container (appwrite-mqtt:1883): the + * standard e2e stacks exclude this group, and a dedicated lane that runs the broker + * selects it with --group mqtt. */ +#[Group('mqtt')] final class MessagingMqttServerTest extends Scope { use ProjectCustom; @@ -141,7 +147,10 @@ final class MessagingMqttServerTest extends Scope // Publish from a separate OS process so it runs while consume() blocks. The // broker only fans out to already-connected subscribers, so the publisher waits. - $autoload = \dirname(__DIR__, 4) . '/vendor/autoload.php'; + // Resolve the autoloader from the running one rather than a fixed relative depth, + // so it works both standalone (repo vendor/) and vendored inside another project + // (e.g. cloud's vendor/appwrite/server-ce, whose own vendor/ is not installed). + $autoload = \dirname((new \ReflectionClass(\Composer\Autoload\ClassLoader::class))->getFileName(), 2) . '/autoload.php'; $publisher = \tempnam(\sys_get_temp_dir(), 'mqtt-pub-') . '.php'; \file_put_contents($publisher, <<<'PHP' Date: Tue, 1 Sep 2026 15:47:20 +0530 Subject: [PATCH 041/146] restore the mqtts entrypoint in the dev traefik override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The development compose override replaces traefik's command wholesale, so it dropped the appwrite_mqtt entrypoint the base defines — leaving Traefik not listening on :8883 and the appwrite-mqtt broker unreachable from host clients (the :8883 port publish survives via ports concatenation, but had no entrypoint behind it). Repeat the entrypoint in the override command. --- docker-compose.override.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docker-compose.override.yml b/docker-compose.override.yml index 2f9f45ed9a..2482f58e39 100644 --- a/docker-compose.override.yml +++ b/docker-compose.override.yml @@ -517,6 +517,11 @@ services: - --providers.docker.constraints=Label(`traefik.constraint-label-stack`,`appwrite`) - --entrypoints.appwrite_web.address=:80 - --entrypoints.appwrite_websecure.address=:443 + # This dev override replaces the base command wholesale, so the mqtts + # entrypoint must be repeated here or Traefik won't listen on :8883 and the + # appwrite-mqtt broker is unreachable (the :8883 port publish survives via + # ports concatenation, but has no entrypoint behind it without this). + - --entrypoints.appwrite_mqtt.address=:8883 - --log.level=DEBUG - --api.insecure=true - --accesslog=true From 3bc95eb620232f60d3262380327823decf5cfe6b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 7 Sep 2026 18:02:26 +0530 Subject: [PATCH 042/146] feat(mqtt): enhance connection handling with clientId and cleanStart properties --- composer.lock | 8 ++++---- src/Utopia/Mqtt/Connection.php | 11 +++++++++-- src/Utopia/Mqtt/Handlers/Connect.php | 4 ++++ 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/composer.lock b/composer.lock index 2859fd9b73..395a21ed6d 100644 --- a/composer.lock +++ b/composer.lock @@ -4453,12 +4453,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/mqtt.git", - "reference": "e25b603c77499c516279e37ed3229f1e5d025c42" + "reference": "b36f0f47b20dfdac20ec2275e9b1e54300e68e50" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/e25b603c77499c516279e37ed3229f1e5d025c42", - "reference": "e25b603c77499c516279e37ed3229f1e5d025c42", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/b36f0f47b20dfdac20ec2275e9b1e54300e68e50", + "reference": "b36f0f47b20dfdac20ec2275e9b1e54300e68e50", "shasum": "" }, "require": { @@ -4511,7 +4511,7 @@ "source": "https://github.com/utopia-php/mqtt/tree/dev", "issues": "https://github.com/utopia-php/mqtt/issues" }, - "time": "2026-08-28T06:28:12+00:00" + "time": "2026-09-07T12:31:12+00:00" }, { "name": "utopia-php/platform", diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index 2a693a2628..3f33f38354 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -4,8 +4,9 @@ namespace Utopia\Mqtt; /** * Per-connection state, keyed by the transport's file descriptor. Handlers mutate - * it across the packet lifecycle: CONNECT records the protocol level and resolved - * identity, PUBLISH draws outbound packet ids for QoS 1 delivery. + * it across the packet lifecycle: CONNECT records the protocol level, client id, + * clean-start flag, and resolved identity; PUBLISH draws outbound packet ids for + * QoS 1 delivery. */ class Connection { @@ -15,6 +16,12 @@ class Connection /** Project id from the CONNECT User Property. */ public string $projectId = ''; + /** Client Identifier from CONNECT; the per-device session anchor. Empty when the client sends none. */ + public string $clientId = ''; + + /** Clean Start (5.0) / Clean Session (3.1.1): true discards any stored session, so delivery is live-only. */ + public bool $cleanStart = true; + /** @var array resolved identity (project/user ids) from the authenticator */ public array $identity = []; diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php index 2ec65a71a5..2556175ca0 100644 --- a/src/Utopia/Mqtt/Handlers/Connect.php +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -44,6 +44,10 @@ class Connect extends Action $offset += 1; // connect flags $offset += 2; // keep alive + // Session anchor: the per-device client id and whether to discard any stored session. + $connection->clientId = Packet::getClientId($body); + $connection->cleanStart = Packet::isCleanStart($body); + // MQTT 3.1.1 carries no property block; enhanced auth and metadata are 5.0 only. $authMethod = ''; $authData = ''; From e2db16d4c78e6e1db5bd6db50485609ff65f3df9 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 7 Sep 2026 18:07:14 +0530 Subject: [PATCH 043/146] bump packages --- composer.json | 26 ------ composer.lock | 220 ++++++++++++++++++++++++++++++-------------------- 2 files changed, 133 insertions(+), 113 deletions(-) diff --git a/composer.json b/composer.json index 822f8904c7..e9bb8c0552 100644 --- a/composer.json +++ b/composer.json @@ -40,32 +40,6 @@ "minimum-stability": "dev", "prefer-stable": true, "repositories": [ - { - "type": "package", - "package": { - "name": "utopia-php/platform", - "version": "1.0.999", - "source": { - "url": "https://github.com/utopia-php/monorepo.git", - "type": "git", - "reference": "cursor/multi-job-queue-platform-f0c8" - }, - "autoload": { - "psr-4": { - "Utopia\\Platform\\": "packages/platform/src/Platform" - } - }, - "require": { - "php": ">=8.5", - "ext-json": "*", - "ext-redis": "*", - "utopia-php/cli": "^0.24", - "utopia-php/http": "^2.0@RC", - "utopia-php/queue": "0.23.* || 0.24.* || ^1.0.0", - "utopia-php/servers": "^0.4" - } - } - }, { "type": "package", "package": { diff --git a/composer.lock b/composer.lock index 1a87aa4635..5672e60704 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "1894661a7a85782143bcf13ad458427d", + "content-hash": "068dc0b8f742ab59c006da7e9b4fd573", "packages": [ { "name": "adhocore/jwt", @@ -163,21 +163,21 @@ }, { "name": "appwrite/php-runtimes", - "version": "0.20.5", + "version": "0.20.6", "source": { "type": "git", "url": "https://github.com/appwrite/runtimes.git", - "reference": "239b65d2ab55aead6e64eca52c201268de21afd4" + "reference": "d2524cc5552cd50608835187d9939dcdf2ae6154" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/appwrite/runtimes/zipball/239b65d2ab55aead6e64eca52c201268de21afd4", - "reference": "239b65d2ab55aead6e64eca52c201268de21afd4", + "url": "https://api.github.com/repos/appwrite/runtimes/zipball/d2524cc5552cd50608835187d9939dcdf2ae6154", + "reference": "d2524cc5552cd50608835187d9939dcdf2ae6154", "shasum": "" }, "require": { "php": ">=8.0", - "utopia-php/system": "0.10.*" + "utopia-php/system": "^0.10 || ^0.11" }, "require-dev": { "laravel/pint": "^1.15", @@ -212,9 +212,9 @@ ], "support": { "issues": "https://github.com/appwrite/runtimes/issues", - "source": "https://github.com/appwrite/runtimes/tree/0.20.5" + "source": "https://github.com/appwrite/runtimes/tree/0.20.6" }, - "time": "2026-09-06T16:45:54+00:00" + "time": "2026-09-07T11:49:02+00:00" }, { "name": "brick/math", @@ -3042,16 +3042,16 @@ }, { "name": "utopia-php/audit", - "version": "4.0.1", + "version": "4.0.2", "source": { "type": "git", "url": "https://github.com/utopia-php/audit.git", - "reference": "69b8e2a6680585604da326fb7abefb316b6de422" + "reference": "2e5a0b89ed6f65ef2ad9f1e10296a77871957550" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/audit/zipball/69b8e2a6680585604da326fb7abefb316b6de422", - "reference": "69b8e2a6680585604da326fb7abefb316b6de422", + "url": "https://api.github.com/repos/utopia-php/audit/zipball/2e5a0b89ed6f65ef2ad9f1e10296a77871957550", + "reference": "2e5a0b89ed6f65ef2ad9f1e10296a77871957550", "shasum": "" }, "require": { @@ -3081,22 +3081,22 @@ ], "support": { "issues": "https://github.com/utopia-php/audit/issues", - "source": "https://github.com/utopia-php/audit/tree/4.0.1" + "source": "https://github.com/utopia-php/audit/tree/4.0.2" }, - "time": "2026-08-27T06:13:20+00:00" + "time": "2026-09-02T15:57:19+00:00" }, { "name": "utopia-php/auth", - "version": "0.10.1", + "version": "0.10.2", "source": { "type": "git", "url": "https://github.com/utopia-php/auth.git", - "reference": "0f1a342bceebc2659736e52a4496daf24ca4954c" + "reference": "1cefec1218c91d5def4ba7293b308e85f7dffc41" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/auth/zipball/0f1a342bceebc2659736e52a4496daf24ca4954c", - "reference": "0f1a342bceebc2659736e52a4496daf24ca4954c", + "url": "https://api.github.com/repos/utopia-php/auth/zipball/1cefec1218c91d5def4ba7293b308e85f7dffc41", + "reference": "1cefec1218c91d5def4ba7293b308e85f7dffc41", "shasum": "" }, "require": { @@ -3139,10 +3139,10 @@ "security" ], "support": { - "source": "https://github.com/utopia-php/auth/tree/0.10.1", + "source": "https://github.com/utopia-php/auth/tree/0.10.2", "issues": "https://github.com/utopia-php/auth/issues" }, - "time": "2026-07-23T07:34:27+00:00" + "time": "2026-09-02T15:57:19+00:00" }, { "name": "utopia-php/balancer", @@ -3194,16 +3194,16 @@ }, { "name": "utopia-php/cache", - "version": "5.0.0", + "version": "5.0.2", "source": { "type": "git", "url": "https://github.com/utopia-php/cache.git", - "reference": "0d0752785fc81b5afd6571f4291763166a6532bc" + "reference": "1b1f999a0095e9614d466d01d1cc3fffd9756acd" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/0d0752785fc81b5afd6571f4291763166a6532bc", - "reference": "0d0752785fc81b5afd6571f4291763166a6532bc", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/1b1f999a0095e9614d466d01d1cc3fffd9756acd", + "reference": "1b1f999a0095e9614d466d01d1cc3fffd9756acd", "shasum": "" }, "require": { @@ -3247,9 +3247,9 @@ ], "support": { "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/5.0.0" + "source": "https://github.com/utopia-php/cache/tree/5.0.2" }, - "time": "2026-08-21T11:04:48+00:00" + "time": "2026-09-03T09:15:30+00:00" }, { "name": "utopia-php/cdn", @@ -3846,16 +3846,16 @@ }, { "name": "utopia-php/domains", - "version": "4.0.0", + "version": "4.1.0", "source": { "type": "git", "url": "https://github.com/utopia-php/domains.git", - "reference": "6029a55444bd32be85cd06c42576250ed88ac2e3" + "reference": "1a6decf322edb112e05f61ff38a3be7df62ef561" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/domains/zipball/6029a55444bd32be85cd06c42576250ed88ac2e3", - "reference": "6029a55444bd32be85cd06c42576250ed88ac2e3", + "url": "https://api.github.com/repos/utopia-php/domains/zipball/1a6decf322edb112e05f61ff38a3be7df62ef561", + "reference": "1a6decf322edb112e05f61ff38a3be7df62ef561", "shasum": "" }, "require": { @@ -3900,9 +3900,9 @@ ], "support": { "issues": "https://github.com/utopia-php/domains/issues", - "source": "https://github.com/utopia-php/domains/tree/4.0.0" + "source": "https://github.com/utopia-php/domains/tree/4.1.0" }, - "time": "2026-09-04T18:31:54+00:00" + "time": "2026-09-07T10:57:13+00:00" }, { "name": "utopia-php/dsn", @@ -4108,16 +4108,16 @@ }, { "name": "utopia-php/image", - "version": "0.8.9", + "version": "0.8.12", "source": { "type": "git", "url": "https://github.com/utopia-php/image.git", - "reference": "6647714267e43bae25c8e8ae7021264eca4a1e84" + "reference": "cab2779faf1e02f3bed9bc5cddd6350a69056948" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/image/zipball/6647714267e43bae25c8e8ae7021264eca4a1e84", - "reference": "6647714267e43bae25c8e8ae7021264eca4a1e84", + "url": "https://api.github.com/repos/utopia-php/image/zipball/cab2779faf1e02f3bed9bc5cddd6350a69056948", + "reference": "cab2779faf1e02f3bed9bc5cddd6350a69056948", "shasum": "" }, "require": { @@ -4148,9 +4148,9 @@ ], "support": { "issues": "https://github.com/utopia-php/image/issues", - "source": "https://github.com/utopia-php/image/tree/0.8.9" + "source": "https://github.com/utopia-php/image/tree/0.8.12" }, - "time": "2026-07-20T18:04:09+00:00" + "time": "2026-09-07T10:00:40+00:00" }, { "name": "utopia-php/locale", @@ -4391,27 +4391,27 @@ "time": "2026-08-13T01:55:11+00:00" }, { - "name": "utopia-php/platform", - "version": "1.0.0-rc20", + "name": "utopia-php/mqtt", + "version": "dev-dev", "source": { "type": "git", - "url": "https://github.com/utopia-php/platform.git", - "reference": "746d403d417bb8ae42e5f8d94e1bbe0e75e4c87d" + "url": "https://github.com/utopia-php/mqtt.git", + "reference": "b36f0f47b20dfdac20ec2275e9b1e54300e68e50" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/platform/zipball/746d403d417bb8ae42e5f8d94e1bbe0e75e4c87d", - "reference": "746d403d417bb8ae42e5f8d94e1bbe0e75e4c87d", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/b36f0f47b20dfdac20ec2275e9b1e54300e68e50", + "reference": "b36f0f47b20dfdac20ec2275e9b1e54300e68e50", "shasum": "" }, "require": { - "ext-json": "*", - "ext-redis": "*", - "php": ">=8.5", - "utopia-php/cli": "^0.24", - "utopia-php/http": "^2.0@RC", - "utopia-php/queue": "0.23.* || 0.24.* || ^1.0.0 || ^2.0.0", - "utopia-php/servers": "^0.4" + "php": ">=8.1" + }, + "require-dev": { + "laravel/pint": "^1.15", + "phpstan/phpstan": "^1.12", + "phpunit/phpunit": "^10.5", + "swoole/ide-helper": "5.1.2" }, "type": "library", "autoload": { @@ -4450,6 +4450,53 @@ "upf", "utopia" ], + "support": { + "source": "https://github.com/utopia-php/mqtt/tree/dev", + "issues": "https://github.com/utopia-php/mqtt/issues" + }, + "time": "2026-09-07T12:31:12+00:00" + }, + { + "name": "utopia-php/platform", + "version": "1.0.0-rc20", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/platform.git", + "reference": "746d403d417bb8ae42e5f8d94e1bbe0e75e4c87d" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/platform/zipball/746d403d417bb8ae42e5f8d94e1bbe0e75e4c87d", + "reference": "746d403d417bb8ae42e5f8d94e1bbe0e75e4c87d", + "shasum": "" + }, + "require": { + "ext-json": "*", + "ext-redis": "*", + "php": ">=8.5", + "utopia-php/cli": "^0.24", + "utopia-php/http": "^2.0@RC", + "utopia-php/queue": "0.23.* || 0.24.* || ^1.0.0 || ^2.0.0", + "utopia-php/servers": "^0.4" + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\Platform\\": "src/Platform" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "description": "Light and Fast Platform Library", + "keywords": [ + "framework", + "php", + "platform", + "upf", + "utopia" + ], "support": { "issues": "https://github.com/utopia-php/platform/issues", "source": "https://github.com/utopia-php/platform/tree/1.0.0-rc20" @@ -4458,16 +4505,16 @@ }, { "name": "utopia-php/pools", - "version": "2.1.1", + "version": "2.1.2", "source": { "type": "git", "url": "https://github.com/utopia-php/pools.git", - "reference": "bc689b818fe1de0df72db6e51ab2f52b838b1209" + "reference": "a45d867e56de82a2eb6e1eb3ea78d4c2f6059f4a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/pools/zipball/bc689b818fe1de0df72db6e51ab2f52b838b1209", - "reference": "bc689b818fe1de0df72db6e51ab2f52b838b1209", + "url": "https://api.github.com/repos/utopia-php/pools/zipball/a45d867e56de82a2eb6e1eb3ea78d4c2f6059f4a", + "reference": "a45d867e56de82a2eb6e1eb3ea78d4c2f6059f4a", "shasum": "" }, "require": { @@ -4508,9 +4555,9 @@ ], "support": { "issues": "https://github.com/utopia-php/pools/issues", - "source": "https://github.com/utopia-php/pools/tree/2.1.1" + "source": "https://github.com/utopia-php/pools/tree/2.1.2" }, - "time": "2026-09-02T15:57:19+00:00" + "time": "2026-09-07T07:02:57+00:00" }, { "name": "utopia-php/psr7", @@ -4835,16 +4882,16 @@ }, { "name": "utopia-php/smtp", - "version": "0.1.0", + "version": "0.1.1", "source": { "type": "git", "url": "https://github.com/utopia-php/smtp.git", - "reference": "6b07b8038aad5ca35896e9456a305ac8fefe8a72" + "reference": "545d363d7a16f1e43f4ce96695a37c12da726b20" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/smtp/zipball/6b07b8038aad5ca35896e9456a305ac8fefe8a72", - "reference": "6b07b8038aad5ca35896e9456a305ac8fefe8a72", + "url": "https://api.github.com/repos/utopia-php/smtp/zipball/545d363d7a16f1e43f4ce96695a37c12da726b20", + "reference": "545d363d7a16f1e43f4ce96695a37c12da726b20", "shasum": "" }, "require": { @@ -4874,9 +4921,9 @@ ], "support": { "issues": "https://github.com/utopia-php/smtp/issues", - "source": "https://github.com/utopia-php/smtp/tree/0.1.0" + "source": "https://github.com/utopia-php/smtp/tree/0.1.1" }, - "time": "2026-08-13T16:10:56+00:00" + "time": "2026-09-02T15:57:19+00:00" }, { "name": "utopia-php/span", @@ -5210,16 +5257,16 @@ }, { "name": "utopia-php/vcs", - "version": "5.2.5", + "version": "5.3.0", "source": { "type": "git", "url": "https://github.com/utopia-php/vcs.git", - "reference": "8e353113381328489b9a9a736156758c642c875c" + "reference": "24b382273e10b9f530be365d3cd833c508e545a6" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/vcs/zipball/8e353113381328489b9a9a736156758c642c875c", - "reference": "8e353113381328489b9a9a736156758c642c875c", + "url": "https://api.github.com/repos/utopia-php/vcs/zipball/24b382273e10b9f530be365d3cd833c508e545a6", + "reference": "24b382273e10b9f530be365d3cd833c508e545a6", "shasum": "" }, "require": { @@ -5261,10 +5308,10 @@ "vcs" ], "support": { - "source": "https://github.com/utopia-php/vcs/tree/5.2.5", + "source": "https://github.com/utopia-php/vcs/tree/5.3.0", "issues": "https://github.com/utopia-php/vcs/issues" }, - "time": "2026-08-25T09:26:43+00:00" + "time": "2026-09-02T15:57:19+00:00" }, { "name": "utopia-php/websocket", @@ -5457,16 +5504,16 @@ "packages-dev": [ { "name": "appwrite/sdk-generator", - "version": "4.9.0", + "version": "4.9.1", "source": { "type": "git", "url": "https://github.com/appwrite/sdk-generator.git", - "reference": "888b0ecdc0f755787302b24d3f41b5875f6ef99b" + "reference": "599f7428d9c352bdd7d3535167ca16af9087e8be" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/appwrite/sdk-generator/zipball/888b0ecdc0f755787302b24d3f41b5875f6ef99b", - "reference": "888b0ecdc0f755787302b24d3f41b5875f6ef99b", + "url": "https://api.github.com/repos/appwrite/sdk-generator/zipball/599f7428d9c352bdd7d3535167ca16af9087e8be", + "reference": "599f7428d9c352bdd7d3535167ca16af9087e8be", "shasum": "" }, "require": { @@ -5503,9 +5550,9 @@ "description": "SDK generator for Appwrite APIs across multiple programming languages and platforms", "support": { "issues": "https://github.com/appwrite/sdk-generator/issues", - "source": "https://github.com/appwrite/sdk-generator/tree/4.9.0" + "source": "https://github.com/appwrite/sdk-generator/tree/4.9.1" }, - "time": "2026-09-07T10:19:46+00:00" + "time": "2026-09-07T10:40:29+00:00" }, { "name": "brianium/paratest", @@ -6215,11 +6262,11 @@ }, { "name": "phpstan/phpstan", - "version": "2.2.12", + "version": "2.2.13", "dist": { "type": "zip", - "url": "https://api.github.com/repos/phpstan/phpstan/zipball/174b0d88710f00a42598886504dd7a146f91ace5", - "reference": "174b0d88710f00a42598886504dd7a146f91ace5", + "url": "https://api.github.com/repos/phpstan/phpstan/zipball/9ba9ac76ee9c5cf5b56d58eb5deec6315b7a0260", + "reference": "9ba9ac76ee9c5cf5b56d58eb5deec6315b7a0260", "shasum": "" }, "require": { @@ -6275,7 +6322,7 @@ "type": "github" } ], - "time": "2026-08-31T19:09:43+00:00" + "time": "2026-09-03T20:38:19+00:00" }, { "name": "phpunit/php-code-coverage", @@ -6714,16 +6761,16 @@ }, { "name": "rector/rector", - "version": "2.6.5", + "version": "2.6.6", "source": { "type": "git", "url": "https://github.com/rectorphp/rector.git", - "reference": "f8686605798c755456327a3597201c3b5be76294" + "reference": "ca069d6c79feaa6651b423c15d101a27a436093e" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/rectorphp/rector/zipball/f8686605798c755456327a3597201c3b5be76294", - "reference": "f8686605798c755456327a3597201c3b5be76294", + "url": "https://api.github.com/repos/rectorphp/rector/zipball/ca069d6c79feaa6651b423c15d101a27a436093e", + "reference": "ca069d6c79feaa6651b423c15d101a27a436093e", "shasum": "" }, "require": { @@ -6759,7 +6806,7 @@ ], "support": { "issues": "https://github.com/rectorphp/rector/issues", - "source": "https://github.com/rectorphp/rector/tree/2.6.5" + "source": "https://github.com/rectorphp/rector/tree/2.6.6" }, "funding": [ { @@ -6767,7 +6814,7 @@ "type": "github" } ], - "time": "2026-08-30T22:02:04+00:00" + "time": "2026-09-02T09:38:46+00:00" }, { "name": "sebastian/cli-parser", @@ -8580,8 +8627,7 @@ "minimum-stability": "dev", "stability-flags": { "utopia-php/http": 5, - "utopia-php/mqtt": 20, - "utopia-php/platform": 5 + "utopia-php/mqtt": 20 }, "prefer-stable": true, "prefer-lowest": false, From 37d427e796dc7e52e4d51ed87dba3dd8e06dbb74 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 7 Sep 2026 18:24:34 +0530 Subject: [PATCH 044/146] feat(mqtt): encapsulate clientId and cleanStart properties in Connection class --- app/mqtt.php | 2 ++ src/Utopia/Mqtt/Connection.php | 12 +++++++++++- src/Utopia/Mqtt/Handlers/Connect.php | 3 +-- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 97d073e12d..22db6a8e92 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -321,6 +321,8 @@ $server->onReceive(function (int $fd, string $data) use ( $span->set('mqtt.fd', $fd); $span->set('project.id', $connection->projectId); $span->set('user.id', $connection->identity['userId'] ?? ''); + $span->set('mqtt.clientId', $connection->getClientId() ?? ''); + $span->set('mqtt.cleanStart', $connection->cleanStart ?? ''); $reply = function (string $packet = '', bool $close = false) use ($server, $fd): void { if ($packet !== '') { diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index 3f33f38354..b41a96cf91 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -17,7 +17,7 @@ class Connection public string $projectId = ''; /** Client Identifier from CONNECT; the per-device session anchor. Empty when the client sends none. */ - public string $clientId = ''; + private string $clientId = ''; /** Clean Start (5.0) / Clean Session (3.1.1): true discards any stored session, so delivery is live-only. */ public bool $cleanStart = true; @@ -42,4 +42,14 @@ class Connection return $this->packetId; } + + public function setClientId(string $clientId): void + { + if(empty($clientId)) $this->clientId = 'custom_'.$this->projectId.''.$this->identity['userId']; + $this->clientId = $clientId; + } + + public function getClientId() : string { + return $this->clientId; + } } diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php index 2556175ca0..378066b34a 100644 --- a/src/Utopia/Mqtt/Handlers/Connect.php +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -44,8 +44,7 @@ class Connect extends Action $offset += 1; // connect flags $offset += 2; // keep alive - // Session anchor: the per-device client id and whether to discard any stored session. - $connection->clientId = Packet::getClientId($body); + $connection->setClientId(Packet::getClientId($body)); $connection->cleanStart = Packet::isCleanStart($body); // MQTT 3.1.1 carries no property block; enhanced auth and metadata are 5.0 only. From 39b440ac4caf374f55824c20b8e32f8e879e35ec Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 7 Sep 2026 18:47:25 +0530 Subject: [PATCH 045/146] feat(mqtt): improve clientId handling in Connection class and update Connect handler --- src/Utopia/Mqtt/Connection.php | 18 +++++++++++++----- src/Utopia/Mqtt/Handlers/Connect.php | 4 +++- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index b41a96cf91..3d43b2143c 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -2,6 +2,8 @@ namespace Utopia\Mqtt; +use Exception; + /** * Per-connection state, keyed by the transport's file descriptor. Handlers mutate * it across the packet lifecycle: CONNECT records the protocol level, client id, @@ -16,7 +18,7 @@ class Connection /** Project id from the CONNECT User Property. */ public string $projectId = ''; - /** Client Identifier from CONNECT; the per-device session anchor. Empty when the client sends none. */ + /** The per-device session anchor: the client-supplied CONNECT id, or a derived fallback (see resolveClientId). */ private string $clientId = ''; /** Clean Start (5.0) / Clean Session (3.1.1): true discards any stored session, so delivery is live-only. */ @@ -43,13 +45,19 @@ class Connection return $this->packetId; } - public function setClientId(string $clientId): void + public function setClientId(string $clientId): void { - if(empty($clientId)) $this->clientId = 'custom_'.$this->projectId.''.$this->identity['userId']; - $this->clientId = $clientId; + if (empty($this->identity)) { + // TODO: has a better way here + throw new Exception("Account identity needs to be resolved first"); + } + $this->clientId = $clientId !== '' + ? $clientId + : 'custom_' . $this->projectId . '_' . ($this->identity['userId'] ?? ''); } - public function getClientId() : string { + public function getClientId(): string + { return $this->clientId; } } diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php index 378066b34a..174face4a6 100644 --- a/src/Utopia/Mqtt/Handlers/Connect.php +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -44,7 +44,6 @@ class Connect extends Action $offset += 1; // connect flags $offset += 2; // keep alive - $connection->setClientId(Packet::getClientId($body)); $connection->cleanStart = Packet::isCleanStart($body); // MQTT 3.1.1 carries no property block; enhanced auth and metadata are 5.0 only. @@ -78,6 +77,9 @@ class Connect extends Action Span::add('user.id', $identity['userId'] ?? ''); } + // needed to be done after the clientId after the identity resolution only + $connection->setClientId(Packet::getClientId($body)); + $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); $mqtt->metrics->connectionsActive->add(1); $connection->active = true; From 7603b771e48a03b13fac75331469feae6b2ccc8f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 09:54:01 +0530 Subject: [PATCH 046/146] feat(mqtt): update Connection class and add unit tests for clientId handling --- src/Utopia/Mqtt/Connection.php | 10 ++--- src/Utopia/Mqtt/Dispatcher.php | 3 +- tests/unit/Utopia/Mqtt/ConnectionTest.php | 53 +++++++++++++++++++++++ 3 files changed, 60 insertions(+), 6 deletions(-) create mode 100644 tests/unit/Utopia/Mqtt/ConnectionTest.php diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index 3d43b2143c..0a857530cb 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -2,7 +2,7 @@ namespace Utopia\Mqtt; -use Exception; +use Appwrite\Extend\Exception; /** * Per-connection state, keyed by the transport's file descriptor. Handlers mutate @@ -18,7 +18,7 @@ class Connection /** Project id from the CONNECT User Property. */ public string $projectId = ''; - /** The per-device session anchor: the client-supplied CONNECT id, or a derived fallback (see resolveClientId). */ + /** The per-device session anchor: the client-supplied CONNECT id, or an account-level fallback (see setClientId). */ private string $clientId = ''; /** Clean Start (5.0) / Clean Session (3.1.1): true discards any stored session, so delivery is live-only. */ @@ -47,10 +47,10 @@ class Connection public function setClientId(string $clientId): void { - if (empty($this->identity)) { - // TODO: has a better way here - throw new Exception("Account identity needs to be resolved first"); + if ($this->identity === []) { + throw new Exception(Exception::USER_UNAUTHORIZED, 'Client id cannot be set before the identity is resolved'); } + $this->clientId = $clientId !== '' ? $clientId : 'custom_' . $this->projectId . '_' . ($this->identity['userId'] ?? ''); diff --git a/src/Utopia/Mqtt/Dispatcher.php b/src/Utopia/Mqtt/Dispatcher.php index 2437379b40..b459639d61 100644 --- a/src/Utopia/Mqtt/Dispatcher.php +++ b/src/Utopia/Mqtt/Dispatcher.php @@ -2,6 +2,7 @@ namespace Utopia\Mqtt; +use Appwrite\Extend\Exception; use Utopia\DI\Container; use Utopia\Platform\Action; @@ -21,7 +22,7 @@ class Dispatcher public function addHandler(Action $handler): self { $type = $handler->getLabels()[self::LABEL_TYPE] - ?? throw new \LogicException('MQTT packet handler is missing the packetType label.'); + ?? throw new Exception(Exception::GENERAL_SERVER_ERROR, 'MQTT packet handler is missing the packetType label.'); $this->handlers[$type] = $handler; diff --git a/tests/unit/Utopia/Mqtt/ConnectionTest.php b/tests/unit/Utopia/Mqtt/ConnectionTest.php new file mode 100644 index 0000000000..5e232475e8 --- /dev/null +++ b/tests/unit/Utopia/Mqtt/ConnectionTest.php @@ -0,0 +1,53 @@ +assertTrue($connection->cleanStart); + } + + public function testClientSuppliedIdIsStoredVerbatim(): void + { + $connection = new Connection(1); + $connection->identity = ['userId' => 'user-1']; + $connection->projectId = 'project-1'; + + $connection->setClientId('device-tv'); + + $this->assertSame('device-tv', $connection->getClientId()); + } + + public function testEmptyIdDerivesAccountLevelAnchor(): void + { + $connection = new Connection(1); + $connection->identity = ['userId' => 'user-1']; + $connection->projectId = 'project-1'; + + $connection->setClientId(''); + + $this->assertSame('custom_project-1_user-1', $connection->getClientId()); + } + + public function testSetClientIdBeforeIdentityIsRejected(): void + { + $connection = new Connection(1); + + try { + $connection->setClientId('device-tv'); + $this->fail('setClientId must reject a connection with no resolved identity'); + } catch (Exception $e) { + $this->assertSame(Exception::USER_UNAUTHORIZED, $e->getType()); + } + } +} From a8993bb5465fe58342c48d49d1f5370081ae5bb9 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 09:57:45 +0530 Subject: [PATCH 047/146] feat(mqtt): update cleanStart and clientId handling in Connect handler --- app/mqtt.php | 3 +-- src/Utopia/Mqtt/Handlers/Connect.php | 4 +++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 22db6a8e92..5c2b82b64d 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -321,8 +321,7 @@ $server->onReceive(function (int $fd, string $data) use ( $span->set('mqtt.fd', $fd); $span->set('project.id', $connection->projectId); $span->set('user.id', $connection->identity['userId'] ?? ''); - $span->set('mqtt.clientId', $connection->getClientId() ?? ''); - $span->set('mqtt.cleanStart', $connection->cleanStart ?? ''); + $span->set('mqtt.clean_start', $connection->cleanStart); $reply = function (string $packet = '', bool $close = false) use ($server, $fd): void { if ($packet !== '') { diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php index 174face4a6..16ab0d389f 100644 --- a/src/Utopia/Mqtt/Handlers/Connect.php +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -45,6 +45,7 @@ class Connect extends Action $offset += 2; // keep alive $connection->cleanStart = Packet::isCleanStart($body); + Span::add('mqtt.clean_start', $connection->cleanStart); // MQTT 3.1.1 carries no property block; enhanced auth and metadata are 5.0 only. $authMethod = ''; @@ -77,8 +78,9 @@ class Connect extends Action Span::add('user.id', $identity['userId'] ?? ''); } - // needed to be done after the clientId after the identity resolution only + // The client id can only be resolved once the identity is known. $connection->setClientId(Packet::getClientId($body)); + Span::add('mqtt.client_id', $connection->getClientId()); $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); $mqtt->metrics->connectionsActive->add(1); From 0ca5292dd42c0c41323e14557ad8ab84cfc1e4c5 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 18:20:36 +0530 Subject: [PATCH 048/146] feat(mqtt): session identity and QoS 1 in-flight tracking on Connection --- src/Utopia/Mqtt/Connection.php | 34 +++++++++++++++++++++-- tests/unit/Utopia/Mqtt/ConnectionTest.php | 19 +++++++++++++ 2 files changed, 51 insertions(+), 2 deletions(-) diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index 0a857530cb..08480db25c 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -7,8 +7,8 @@ use Appwrite\Extend\Exception; /** * Per-connection state, keyed by the transport's file descriptor. Handlers mutate * it across the packet lifecycle: CONNECT records the protocol level, client id, - * clean-start flag, and resolved identity; PUBLISH draws outbound packet ids for - * QoS 1 delivery. + * clean-start flag, and resolved identity; delivery draws outbound packet ids and + * tracks each QoS 1 message in flight until its PUBACK. */ class Connection { @@ -32,6 +32,15 @@ class Connection private int $packetId = 0; + /** + * Outbound QoS 1 deliveries awaiting a PUBACK, keyed by packet id. Each entry + * keeps the topic and the durable sequence delivered, so the matching PUBACK + * can advance that topic's cursor. Emptied as acks arrive. + * + * @var array + */ + private array $inflight = []; + public function __construct( public readonly int $fd, ) { @@ -45,6 +54,27 @@ class Connection return $this->packetId; } + /** Record an outbound QoS 1 delivery so its PUBACK can be matched back to a topic and sequence. */ + public function track(int $packetId, string $topic, int $sequence): void + { + $this->inflight[$packetId] = ['topic' => $topic, 'sequence' => $sequence]; + } + + /** + * Resolve a PUBACK to the delivery it acknowledges, removing it from the + * in-flight set. Returns the topic and sequence, or null for an unknown or + * duplicate ack. + * + * @return array{topic: string, sequence: int}|null + */ + public function acknowledge(int $packetId): ?array + { + $delivery = $this->inflight[$packetId] ?? null; + unset($this->inflight[$packetId]); + + return $delivery; + } + public function setClientId(string $clientId): void { if ($this->identity === []) { diff --git a/tests/unit/Utopia/Mqtt/ConnectionTest.php b/tests/unit/Utopia/Mqtt/ConnectionTest.php index 5e232475e8..41dc0c4b50 100644 --- a/tests/unit/Utopia/Mqtt/ConnectionTest.php +++ b/tests/unit/Utopia/Mqtt/ConnectionTest.php @@ -50,4 +50,23 @@ final class ConnectionTest extends TestCase $this->assertSame(Exception::USER_UNAUTHORIZED, $e->getType()); } } + + public function testAcknowledgeResolvesATrackedDelivery(): void + { + $connection = new Connection(1); + $connection->track(7, 'appwrite/push/user-1', 42); + + $this->assertSame(['topic' => 'appwrite/push/user-1', 'sequence' => 42], $connection->acknowledge(7)); + } + + public function testAcknowledgeIsIdempotentForAnUnknownOrRepeatedAck(): void + { + $connection = new Connection(1); + $connection->track(7, 'appwrite/push/user-1', 42); + + $connection->acknowledge(7); + + $this->assertNull($connection->acknowledge(7), 'a second ack for the same id resolves to nothing'); + $this->assertNull($connection->acknowledge(99), 'an ack for an untracked id resolves to nothing'); + } } From a5e5dd1c6788e0dc28e7f2504d9392428e1c0bc2 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 18:20:36 +0530 Subject: [PATCH 049/146] feat(mqtt): PUBACK handler with cursor persistence and delivery tracking --- app/mqtt.php | 59 ++++++++++++++++++++++++++- src/Utopia/Mqtt/Handlers/Puback.php | 63 +++++++++++++++++++++++++++++ src/Utopia/Mqtt/Metrics.php | 2 + 3 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 src/Utopia/Mqtt/Handlers/Puback.php diff --git a/app/mqtt.php b/app/mqtt.php index 5c2b82b64d..1d0ccbe1a4 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -22,6 +22,7 @@ use Utopia\Mqtt\Handlers\Auth as AuthHandler; use Utopia\Mqtt\Handlers\Connect as ConnectHandler; use Utopia\Mqtt\Handlers\Disconnect as DisconnectHandler; use Utopia\Mqtt\Handlers\Ping as PingHandler; +use Utopia\Mqtt\Handlers\Puback as PubackHandler; use Utopia\Mqtt\Handlers\Publish as PublishHandler; use Utopia\Mqtt\Handlers\Subscribe as SubscribeHandler; use Utopia\Mqtt\Handlers\Unsubscribe as UnsubscribeHandler; @@ -165,6 +166,54 @@ if (!function_exists('getProjectDB')) { } } +if (!function_exists('getCache')) { + function getCache(): Cache + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['cache'])) { + return $ctx['cache']; + } + + global $register; + + $pools = $register->get('pools'); /** @var Group $pools */ + + $list = Config::getParam('pools-cache', []); + $adapters = []; + + foreach ($list as $value) { + $adapters[] = new CachePool($pools->get($value)); + } + + return $ctx['cache'] = new Cache(new Sharding($adapters)); + } +} + +if (!function_exists('getRedis')) { + function getRedis(): \Redis + { + $ctx = Coroutine::getContext(); + + if (isset($ctx['redis'])) { + return $ctx['redis']; + } + + $host = System::getEnv('_APP_REDIS_HOST', 'localhost'); + $port = System::getEnv('_APP_REDIS_PORT', 6379); + $pass = System::getEnv('_APP_REDIS_PASS', ''); + + $redis = new \Redis(); + @$redis->pconnect($host, (int)$port); + if ($pass) { + $redis->auth($pass); + } + $redis->setOption(\Redis::OPT_READ_TIMEOUT, -1); + + return $ctx['redis'] = $redis; + } +} + /** * Authenticate a CONNECT: resolve the project and verify the session in a child * container, using the same domain logic as HTTP/realtime. Returns the identity @@ -247,6 +296,7 @@ $dispatcher = (new Dispatcher()) ->addHandler(new SubscribeHandler()) ->addHandler(new UnsubscribeHandler()) ->addHandler(new PublishHandler()) + ->addHandler(new PubackHandler()) ->addHandler(new AuthHandler()) ->addHandler(new PingHandler()) ->addHandler(new DisconnectHandler()); @@ -273,6 +323,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): $projectId = (string) ($event['project'] ?? ''); $topic = (string) ($event['topic'] ?? ''); $qos = (int) ($event['qos'] ?? 0); + $sequence = (int) ($event['payload']['sequence'] ?? 0); $message = base64_decode((string) ($event['payload'] ?? '')); $subscribers = $mqtt->getSubscribers($projectId, $topic); @@ -294,6 +345,11 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): ? V5::publish($topic, $message, $effectiveQos, $packetId) : V3::publish($topic, $message, $effectiveQos, $packetId)); $mqtt->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); + + // Hold QoS 1 deliveries until the subscriber's PUBACK matches them back. + if ($effectiveQos === 1) { + $subscriber->track($packetId, $topic, $sequence); + } } }); } catch (\Throwable $error) { @@ -313,6 +369,7 @@ $server->onReceive(function (int $fd, string $data) use ( $dispatcher, $authenticate, $authorize, + $container ): void { $packet = Packet::parse($data); $connection = $mqtt->open($fd); @@ -332,7 +389,7 @@ $server->onReceive(function (int $fd, string $data) use ( } }; - $packetContainer = new Container(); + $packetContainer = new Container($container); $packetContainer->set('mqtt', fn () => $mqtt); $packetContainer->set('connection', fn () => $connection); $packetContainer->set('packet', fn () => $packet); diff --git a/src/Utopia/Mqtt/Handlers/Puback.php b/src/Utopia/Mqtt/Handlers/Puback.php new file mode 100644 index 0000000000..0adb6dee71 --- /dev/null +++ b/src/Utopia/Mqtt/Handlers/Puback.php @@ -0,0 +1,63 @@ +desc('Acknowledge a delivered QoS 1 message and advance the subscriber cursor') + ->label(Dispatcher::LABEL_TYPE, Packet::PUBACK) + ->inject('mqtt') + ->inject('connection') + ->inject('packet') + ->inject('reply') + ->callback($this->action(...)); + } + + public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + { + $body = $packet->body; + + if (\strlen($body) < 2) { + return; + } + + $connectionMetdata = $mqtt->getConnection($connection->fd); + if ($connectionMetdata['userId'] !== $connection->identity['userId'] || $connectionMetdata['projectId'] !== $connection->projectId) { + $reply(V5::disconnect(V5::REASON_NOT_AUTHORIZED), true); + return; + } + + // PUBACK opens with the two-byte packet id in both versions. + [$packetId] = Packet::readInt16($body, 0); + + $delivery = $connection->acknowledge($packetId); + if ($delivery === null) { + return; + } + + Span::add('mqtt.topic', $delivery['topic']); + Span::add('mqtt.sequence', $delivery['sequence']); + $mqtt->metrics->messagesAcked->add(1); + + $cache = getCache(); + $key = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $delivery['topic']; + $cache->save($key, ['sequence' => $delivery['sequence']]); + } +} diff --git a/src/Utopia/Mqtt/Metrics.php b/src/Utopia/Mqtt/Metrics.php index e4244e1ebe..add3958f51 100644 --- a/src/Utopia/Mqtt/Metrics.php +++ b/src/Utopia/Mqtt/Metrics.php @@ -21,6 +21,7 @@ class Metrics public Counter $messagesPublished; public Counter $messagesDelivered; public Counter $messagesDropped; + public Counter $messagesAcked; public function __construct(Telemetry $telemetry) { @@ -30,5 +31,6 @@ class Metrics $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); + $this->messagesAcked = $telemetry->createCounter('mqtt.messages.acked'); } } From 3792b70d88eec51d373286ea9ea8ea594891caa1 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 18:20:36 +0530 Subject: [PATCH 050/146] feat(mqtt): resolve an fd's connection record from the subscription store --- src/Appwrite/Messaging/Adapter/Mqtt.php | 12 ++++++++++++ src/Utopia/Mqtt/SubscriptionStore.php | 8 ++++++++ tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php | 16 ++++++++++++++++ 3 files changed, 36 insertions(+) diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index c2ffaf45fb..9baf1eeaa4 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -159,4 +159,16 @@ class Mqtt extends MessagingAdapter { return $this->subscriptions()->getSubscribers($projectId, $topic) !== []; } + + /** + * The subscription-store record for an fd: its project, user, and subscriptions, + * or null when the fd holds none. This is the store's copy (the projectId/userId + * captured at subscribe time), not the live Connection object from open(). + * + * @return array{projectId: string, userId: string, subs: array}|null + */ + public function getConnection(int $fd): ?array + { + return $this->subscriptions()->getConnection($fd); + } } diff --git a/src/Utopia/Mqtt/SubscriptionStore.php b/src/Utopia/Mqtt/SubscriptionStore.php index 2a744d7b44..8b5151e378 100644 --- a/src/Utopia/Mqtt/SubscriptionStore.php +++ b/src/Utopia/Mqtt/SubscriptionStore.php @@ -126,6 +126,14 @@ class SubscriptionStore unset($this->connections[$fd]); } + /** + * @return array{projectId: string, userId: string, subs: array}|null + */ + public function getConnection(int $fd): ?array + { + return $this->connections[$fd] ?? null; + } + /** * * @return array fd => granted QoS diff --git a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php index 307265ce51..096266a799 100644 --- a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php +++ b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php @@ -162,4 +162,20 @@ final class SubscriptionStoreTest extends TestCase $this->assertSame([2 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'other/x')); } + + public function testGetConnectionReturnsTheFdRecord(): void + { + $this->store->subscribe(self::PROJECT, 'user-1', 'sub', 'test/hello', 9, 1); + + $connection = $this->store->getConnection(9); + + $this->assertSame(self::PROJECT, $connection['projectId']); + $this->assertSame('user-1', $connection['userId']); + $this->assertSame('test/hello', $connection['subs']['sub']['topic']); + } + + public function testGetConnectionIsNullForAnUnknownFd(): void + { + $this->assertNull($this->store->getConnection(404)); + } } From 1385f2850c86d4f1e0d965c0d10e4d56e9fa735b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 18:20:36 +0530 Subject: [PATCH 051/146] feat(mqtt): persist subId and scaffold session replay on subscribe --- src/Utopia/Mqtt/Handlers/Subscribe.php | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index 7c9144b04f..9d7d88326e 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -52,6 +52,7 @@ class Subscribe extends Action $denied = $connection->protocol >= 5 ? V5::REASON_NOT_AUTHORIZED : V3::SUBSCRIBE_FAILURE; $granted = ''; + $topics = []; while ($offset < strlen($body)) { [$filter, $offset] = Packet::readString($body, $offset); $offset += 1; // subscription options byte @@ -68,6 +69,11 @@ class Subscribe extends Action $mqtt->subscribe($connection->projectId, $connection->fd, $subId ?: $filter, [], [$filter]); $granted .= chr(Packet::QOS_1); // granted max QoS 1 $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); + + // TODO: if we can save directly in the same cache key only + $key = 'mqtt:sub:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $filter; + getCache()->save($key, ['subId' => $subId, 'qos' => Packet::QOS_1]); + $topics[] = $filter; } $reply( @@ -76,5 +82,23 @@ class Subscribe extends Action : V3::suback($packetId, $granted), false, ); + + // session replay + // TODO: update the ttl + bulk fetch + bulk upload to the cache to reduce the network calls + foreach ($topics as $topic) { + $lastMessageCursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $topic; + $payload = getCache()->load($lastMessageCursorKey, 3600); + $sequence = $payload['sequence'] ?? null; + var_dump($payload); + if ($sequence !== null) { + // TODO: fetch the last global message cursor then calculate the depth and send + $packetId = $connection->nextPacketId(); + $publish = $connection->protocol >= 5 + ? V5::publish($topic, json_encode($payload), Packet::QOS_1, $packetId, dup: true) + : V3::publish($topic, json_encode($payload), Packet::QOS_1, $packetId, dup: true); + $reply($publish, false); + $connection->track($packetId, $topic, $sequence); + } + } } } From b018aef303e295b28d7785442312a5902841fb77 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 8 Sep 2026 18:20:36 +0530 Subject: [PATCH 052/146] chore(mqtt): cursor/message resource stubs and local broker compose --- app/init/mqtt/connection.php | 9 +++++++++ docker-compose.yml | 4 ++++ 2 files changed, 13 insertions(+) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 04f291c9ad..56cfbbb355 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -82,4 +82,13 @@ return function (Container $container): void { return $user; }, ['project', 'authMethod', 'credential', 'authorization']); + + // TODO: needed a better naming + $container->set('setMessageCursor', function (string $projectId, string $userId, string $clientId, string $topic, string $messageId) { + + }); + + $container->set('getMessages', function (string $projectId, string $userId, string $clientId, string $topic, string $messageId) { + + }); }; diff --git a/docker-compose.yml b/docker-compose.yml index 9a53585e81..e6d96284e2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -378,6 +378,10 @@ services: - traefik.tcp.services.appwrite_mqtt.loadbalancer.server.port=1883 networks: - appwrite + ports: + - 1883:1883 + volumes: + - ./vendor:/usr/src/code/vendor environment: - _APP_ENV - _APP_WORKER_PER_CORE From e473c64c0833616dd33cf15e8b188522c5f18125 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 09:43:36 +0530 Subject: [PATCH 053/146] bump composer lock --- composer.lock | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/composer.lock b/composer.lock index 5672e60704..1ca78587e5 100644 --- a/composer.lock +++ b/composer.lock @@ -4396,19 +4396,19 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/mqtt.git", - "reference": "b36f0f47b20dfdac20ec2275e9b1e54300e68e50" + "reference": "9165bccb7b7a03ad3dceb4c00fdcd53f52152cbd" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/b36f0f47b20dfdac20ec2275e9b1e54300e68e50", - "reference": "b36f0f47b20dfdac20ec2275e9b1e54300e68e50", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/9165bccb7b7a03ad3dceb4c00fdcd53f52152cbd", + "reference": "9165bccb7b7a03ad3dceb4c00fdcd53f52152cbd", "shasum": "" }, "require": { "php": ">=8.1" }, "require-dev": { - "laravel/pint": "^1.15", + "laravel/pint": "^1.15 <1.21", "phpstan/phpstan": "^1.12", "phpunit/phpunit": "^10.5", "swoole/ide-helper": "5.1.2" @@ -4454,7 +4454,7 @@ "source": "https://github.com/utopia-php/mqtt/tree/dev", "issues": "https://github.com/utopia-php/mqtt/issues" }, - "time": "2026-09-07T12:31:12+00:00" + "time": "2026-09-08T08:18:35+00:00" }, { "name": "utopia-php/platform", From 6ac319dc205884594183c8c6d8c33a207ff0cafa Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 12:42:36 +0530 Subject: [PATCH 054/146] feat(mqtt): persist published messages and replay backlog on subscribe WIP checkpoint: publish writes to the messages collection with topics, subscribe reads the tail and replays, plus delivery/is_broker spans. Co-Authored-By: Claude Opus 4.8 --- app/mqtt.php | 14 ++++++++ src/Utopia/Mqtt/Handlers/Publish.php | 14 ++++++++ src/Utopia/Mqtt/Handlers/Subscribe.php | 44 +++++++++++++++++++------- 3 files changed, 61 insertions(+), 11 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 1d0ccbe1a4..cc009b2e7c 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -326,11 +326,22 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): $sequence = (int) ($event['payload']['sequence'] ?? 0); $message = base64_decode((string) ($event['payload'] ?? '')); + // The broker is the sender on this hop (fan-out to subscribers), so the + // span is marked is_broker to separate it from client-originated packets. + $span = Span::init('mqtt.deliver'); + $span->set('project.id', $projectId); + $span->set('mqtt.topic', $topic); + $span->set('mqtt.qos', $qos); + $span->set('mqtt.is_broker', true); + $subscribers = $mqtt->getSubscribers($projectId, $topic); + $span->set('mqtt.subscribers', count($subscribers)); + if ($subscribers === []) { // No local subscriber on this worker; with multiple workers this // counts per-worker rather than as a global drop. $mqtt->metrics->messagesDropped->add(1, ['reason' => 'no_subscriber']); + $span->finish(); return; } @@ -351,6 +362,8 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): $subscriber->track($packetId, $topic, $sequence); } } + + $span->finish(); }); } catch (\Throwable $error) { $attempts++; @@ -379,6 +392,7 @@ $server->onReceive(function (int $fd, string $data) use ( $span->set('project.id', $connection->projectId); $span->set('user.id', $connection->identity['userId'] ?? ''); $span->set('mqtt.clean_start', $connection->cleanStart); + $span->set('mqtt.is_broker', false); // an inbound packet from a client $reply = function (string $packet = '', bool $close = false) use ($server, $fd): void { if ($packet !== '') { diff --git a/src/Utopia/Mqtt/Handlers/Publish.php b/src/Utopia/Mqtt/Handlers/Publish.php index b4e7699226..b1d8791c77 100644 --- a/src/Utopia/Mqtt/Handlers/Publish.php +++ b/src/Utopia/Mqtt/Handlers/Publish.php @@ -2,7 +2,9 @@ namespace Utopia\Mqtt\Handlers; +use Appwrite\ID; use Appwrite\Messaging\Adapter\Mqtt; +use Utopia\Database\Document; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; @@ -54,6 +56,18 @@ class Publish extends Action if ($qos === 1) { // PUBACK is a bare packet id in both versions (reason/properties omitted). $reply($connection->protocol >= 5 ? V5::puback($packetId) : V3::puback($packetId), false); + + // TODO: remove it from here. It shall be in the messaging worker + $consoleDatabase = getConsoleDB(); + $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); + $projectDB = getProjectDB($project); + $message = new Document([ + '$id' => ID::unique(), + 'providerType' => MESSAGE_TYPE_PUSH, + 'topics' => [$topic], + 'data' => ['payload' => $payload, 'qos' => $qos], + ]); + $projectDB->createDocument('messages', $message); } } } diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index 9d7d88326e..e0a2000f2f 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -3,6 +3,7 @@ namespace Utopia\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; +use Utopia\Database\Query; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; @@ -85,20 +86,41 @@ class Subscribe extends Action // session replay // TODO: update the ttl + bulk fetch + bulk upload to the cache to reduce the network calls + // same for the database below + $consoleDatabase = getConsoleDB(); + $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); + $projectDB = getProjectDB($project); + + $cache = getCache(); foreach ($topics as $topic) { $lastMessageCursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $topic; - $payload = getCache()->load($lastMessageCursorKey, 3600); - $sequence = $payload['sequence'] ?? null; - var_dump($payload); - if ($sequence !== null) { - // TODO: fetch the last global message cursor then calculate the depth and send - $packetId = $connection->nextPacketId(); - $publish = $connection->protocol >= 5 - ? V5::publish($topic, json_encode($payload), Packet::QOS_1, $packetId, dup: true) - : V3::publish($topic, json_encode($payload), Packet::QOS_1, $packetId, dup: true); - $reply($publish, false); - $connection->track($packetId, $topic, $sequence); + $payload = $cache->load($lastMessageCursorKey, 3600); + + $topicDocument = $projectDB->getAuthorization()->skip(fn () => $projectDB->findOne('messages', [Query::containsAny('topics', [$topic]), Query::orderDesc('$sequence'), Query::orderDesc('data')])); + if($topicDocument->isEmpty()) continue; + if(empty($topicDocument->getAttribute('data'))) continue; + + $sequence = $topicDocument?->getAttribute('$sequence') ?? -1; + + if ($payload === false) { + // Newly connected device: register at the current tail so it starts from now. + $cache->save($lastMessageCursorKey, ['sequence' => $sequence]); + continue; } + + $lastSubscriberSequence = max(-1, $payload['sequence'] ?? -1); + + if($lastSubscriberSequence === $sequence){ + continue; + } + + // TODO: fetch the last global message cursor then calculate the depth and send + $packetId = $connection->nextPacketId(); + $publish = $connection->protocol >= 5 + ? V5::publish($topic, json_encode($topicDocument->getAttribute('data')), Packet::QOS_1, $packetId, dup: true) + : V3::publish($topic, json_encode($topicDocument->getAttribute('data')), Packet::QOS_1, $packetId, dup: true); + $reply($publish, false); + $connection->track($packetId, $topic, $sequence); } } } From 6c56000e20e570611c0e0d55caae21d312311b5f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 13:55:12 +0530 Subject: [PATCH 055/146] feat(messaging): add messages_appwrite ledger collection and provider constant --- app/config/collections/common.php | 70 +++++++++++++++++++++++++++++++ app/init/constants.php | 2 + 2 files changed, 72 insertions(+) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index 469d2a78eb..b1603055ed 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2212,6 +2212,76 @@ return [ ], ], + 'messages_appwrite' => [ + '$collection' => ID::custom(DATABASE::METADATA), + '$id' => ID::custom('messages_appwrite'), + 'name' => 'MQTT Messages', + 'attributes' => [ + [ + '$id' => ID::custom('topic'), + 'type' => Database::VAR_STRING, + 'format' => '', + 'size' => Database::LENGTH_KEY, + 'signed' => true, + 'required' => true, + 'default' => null, + 'array' => false, + 'filters' => [], + ], + [ + '$id' => ID::custom('data'), + 'type' => Database::VAR_STRING, + 'format' => '', + 'size' => 65535, + 'signed' => true, + 'required' => true, + 'default' => null, + 'array' => false, + 'filters' => ['json'], + ], + // default null means client choose their qos level and no restriction + [ + '$id' => ID::custom('qos'), + 'type' => Database::VAR_INTEGER, + 'format' => '', + 'size' => 0, + 'signed' => true, + 'required' => false, + 'default' => null, + 'array' => false, + 'filters' => [], + ], + // expiry for offline persistence + [ + '$id' => ID::custom('expireAt'), + 'type' => Database::VAR_DATETIME, + 'format' => '', + 'size' => 0, + 'signed' => false, + 'required' => true, + 'default' => null, + 'array' => false, + 'filters' => ['datetime'], + ], + ], + 'indexes' => [ + [ + '$id' => ID::custom('_key_topic'), + 'type' => Database::INDEX_KEY, + 'attributes' => ['topic'], + 'lengths' => [], + 'orders' => [Database::ORDER_ASC], + ], + [ + '$id' => ID::custom('_key_expireAt'), + 'type' => Database::INDEX_KEY, + 'attributes' => ['expireAt'], + 'lengths' => [], + 'orders' => [Database::ORDER_ASC], + ], + ], + ], + 'topics' => [ '$collection' => ID::custom(DATABASE::METADATA), '$id' => ID::custom('topics'), diff --git a/app/init/constants.php b/app/init/constants.php index 050a20b97f..78cbf9fe80 100644 --- a/app/init/constants.php +++ b/app/init/constants.php @@ -335,6 +335,8 @@ const FUNCTION_ALLOWLIST_HEADERS_RESPONSE = ['content-type', 'content-length']; const MESSAGE_TYPE_EMAIL = 'email'; const MESSAGE_TYPE_SMS = 'sms'; const MESSAGE_TYPE_PUSH = 'push'; +// Message providers +const MESSAGE_PROVIDER_APPWRITE = 'appwrite'; // Notification types const NOTIFICATION_TYPE_EMAIL = MESSAGE_TYPE_EMAIL; const NOTIFICATION_TYPE_SMS = MESSAGE_TYPE_SMS; From fdaa3d5743c11d75fdc56c150ff6044a507f4c69 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 13:55:12 +0530 Subject: [PATCH 056/146] feat(messaging): add Appwrite push provider create and update endpoints --- .../Http/Providers/Appwrite/Create.php | 91 +++++++++++++++++++ .../Http/Providers/Appwrite/Update.php | 90 ++++++++++++++++++ .../Modules/Messaging/Services/Http.php | 4 + 3 files changed, 185 insertions(+) create mode 100644 src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php create mode 100644 src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php new file mode 100644 index 0000000000..fa0893f221 --- /dev/null +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php @@ -0,0 +1,91 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_POST) + ->setHttpPath('/v1/messaging/providers/appwrite') + ->desc('Create Appwrite provider') + ->groups(['api', 'messaging']) + ->label('audits.event', 'provider.create') + ->label('audits.resource', 'provider/{response.$id}') + ->label('event', 'providers.[providerId].create') + ->label('scope', 'providers.write') + ->label('resourceType', RESOURCE_TYPE_PROVIDERS) + ->label('sdk', new Method( + namespace: 'messaging', + group: 'providers', + name: 'createAppwriteProvider', + description: '/docs/references/messaging/create-appwrite-provider.md', + auth: [AuthType::ADMIN, AuthType::KEY], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_CREATED, + model: Response::MODEL_PROVIDER, + ) + ] + )) + ->param('providerId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.', false, ['dbForProject']) + ->param('name', '', new Text(128), 'Provider name.') + ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) + ->inject('queueForEvents') + ->inject('dbForProject') + ->inject('response') + ->callback($this->action(...)); + } + + public function action(string $providerId, string $name, ?bool $enabled, Event $queueForEvents, Database $dbForProject, Response $response) + { + $providerId = $providerId == 'unique()' ? ID::unique() : $providerId; + + $provider = new Document([ + '$id' => $providerId, + 'name' => $name, + 'provider' => MESSAGE_PROVIDER_APPWRITE, + 'type' => MESSAGE_TYPE_PUSH, + 'enabled' => $enabled ?? true, + 'credentials' => [], + ]); + + try { + $provider = $dbForProject->createDocument('providers', $provider); + } catch (DuplicateException) { + throw new Exception(Exception::PROVIDER_ALREADY_EXISTS); + } + + $queueForEvents + ->setParam('providerId', $provider->getId()); + + $response + ->setStatusCode(Response::STATUS_CODE_CREATED) + ->dynamic($provider, Response::MODEL_PROVIDER); + } +} diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php new file mode 100644 index 0000000000..aa2210cbb9 --- /dev/null +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php @@ -0,0 +1,90 @@ +setHttpMethod(Action::HTTP_REQUEST_METHOD_PATCH) + ->setHttpPath('/v1/messaging/providers/appwrite/:providerId') + ->desc('Update Appwrite provider') + ->groups(['api', 'messaging']) + ->label('audits.event', 'provider.update') + ->label('audits.resource', 'provider/{response.$id}') + ->label('event', 'providers.[providerId].update') + ->label('scope', 'providers.write') + ->label('resourceType', RESOURCE_TYPE_PROVIDERS) + ->label('sdk', new Method( + namespace: 'messaging', + group: 'providers', + name: 'updateAppwriteProvider', + description: '/docs/references/messaging/update-appwrite-provider.md', + auth: [AuthType::ADMIN, AuthType::KEY], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PROVIDER, + ) + ] + )) + ->param('providerId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Provider ID.', false, ['dbForProject']) + ->param('name', '', new Text(128), 'Provider name.', true) + ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) + ->inject('queueForEvents') + ->inject('dbForProject') + ->inject('response') + ->callback($this->action(...)); + } + + public function action(string $providerId, string $name, ?bool $enabled, Event $queueForEvents, Database $dbForProject, Response $response) + { + $provider = $dbForProject->getDocument('providers', $providerId); + + if ($provider->isEmpty()) { + throw new Exception(Exception::PROVIDER_NOT_FOUND); + } + + if ($provider->getAttribute('provider') !== MESSAGE_PROVIDER_APPWRITE) { + throw new Exception(Exception::PROVIDER_INCORRECT_TYPE); + } + + if (!empty($name)) { + $provider->setAttribute('name', $name); + } + + if (!\is_null($enabled)) { + $provider->setAttribute('enabled', $enabled); + } + + $provider = $dbForProject->updateDocument('providers', $provider->getId(), $provider); + + $queueForEvents + ->setParam('providerId', $provider->getId()); + + $response + ->dynamic($provider, Response::MODEL_PROVIDER); + } +} diff --git a/src/Appwrite/Platform/Modules/Messaging/Services/Http.php b/src/Appwrite/Platform/Modules/Messaging/Services/Http.php index bfbf72173c..7c44fd2293 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Services/Http.php +++ b/src/Appwrite/Platform/Modules/Messaging/Services/Http.php @@ -14,6 +14,8 @@ use Appwrite\Platform\Modules\Messaging\Http\Messages\Targets\XList as ListTarge use Appwrite\Platform\Modules\Messaging\Http\Messages\XList as ListMessages; use Appwrite\Platform\Modules\Messaging\Http\Providers\Apns\Create as CreateApnsProvider; use Appwrite\Platform\Modules\Messaging\Http\Providers\Apns\Update as UpdateApnsProvider; +use Appwrite\Platform\Modules\Messaging\Http\Providers\Appwrite\Create as CreateAppwriteProvider; +use Appwrite\Platform\Modules\Messaging\Http\Providers\Appwrite\Update as UpdateAppwriteProvider; use Appwrite\Platform\Modules\Messaging\Http\Providers\Delete as DeleteProvider; use Appwrite\Platform\Modules\Messaging\Http\Providers\Fcm\Create as CreateFcmProvider; use Appwrite\Platform\Modules\Messaging\Http\Providers\Fcm\Update as UpdateFcmProvider; @@ -81,6 +83,8 @@ class Http extends Service $this->addAction(UpdateFcmProvider::getName(), new UpdateFcmProvider()); $this->addAction(CreateApnsProvider::getName(), new CreateApnsProvider()); $this->addAction(UpdateApnsProvider::getName(), new UpdateApnsProvider()); + $this->addAction(CreateAppwriteProvider::getName(), new CreateAppwriteProvider()); + $this->addAction(UpdateAppwriteProvider::getName(), new UpdateAppwriteProvider()); $this->addAction(ListProviders::getName(), new ListProviders()); $this->addAction(GetProvider::getName(), new GetProvider()); $this->addAction(DeleteProvider::getName(), new DeleteProvider()); From a5026d8ec387f0e7f38410fb8a0a1675580529f1 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 13:55:12 +0530 Subject: [PATCH 057/146] test(messaging): cover Appwrite provider create and update endpoints --- .../e2e/Services/Messaging/MessagingBase.php | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/tests/e2e/Services/Messaging/MessagingBase.php b/tests/e2e/Services/Messaging/MessagingBase.php index e783fa0dd6..1e3c2d448f 100644 --- a/tests/e2e/Services/Messaging/MessagingBase.php +++ b/tests/e2e/Services/Messaging/MessagingBase.php @@ -861,6 +861,65 @@ trait MessagingBase } } + public function testCreateAppwriteProvider(): void + { + // Test for SUCCESS: the built-in Appwrite (MQTT) push provider needs no credentials. + $provider = $this->client->call(Client::METHOD_POST, '/messaging/providers/appwrite', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'providerId' => ID::unique(), + 'name' => 'Appwrite1', + 'enabled' => true, + ]); + + $this->assertEquals(201, $provider['headers']['status-code']); + $this->assertEquals('Appwrite1', $provider['body']['name']); + $this->assertEquals('appwrite', $provider['body']['provider']); + $this->assertEquals('push', $provider['body']['type']); + $this->assertTrue($provider['body']['enabled']); + } + + public function testUpdateAppwriteProvider(): void + { + $provider = $this->client->call(Client::METHOD_POST, '/messaging/providers/appwrite', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'providerId' => ID::unique(), + 'name' => 'Appwrite-before', + 'enabled' => true, + ]); + $this->assertEquals(201, $provider['headers']['status-code']); + + // Test for SUCCESS: name and enabled are updated. + $response = $this->client->call(Client::METHOD_PATCH, '/messaging/providers/appwrite/' . $provider['body']['$id'], [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'name' => 'Appwrite-after', + 'enabled' => false, + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals('Appwrite-after', $response['body']['name']); + $this->assertFalse($response['body']['enabled']); + + // Test for FAILURE: an unknown provider id is not found. + $missing = $this->client->call(Client::METHOD_PATCH, '/messaging/providers/appwrite/' . ID::unique(), [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'name' => 'Nope', + ]); + + $this->assertEquals(404, $missing['headers']['status-code']); + } + public function testUpdateProviders(): void { $providers = $this->setupCreatedProviders(); From ec3e0aaba3801dca300ad0fa028959ad0a285266 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 14:32:55 +0530 Subject: [PATCH 058/146] refactor(mqtt): key subscriptions by topic and drop subId --- src/Appwrite/Messaging/Adapter/Mqtt.php | 14 ++++++------- src/Utopia/Mqtt/Handlers/Subscribe.php | 19 ++++++++++-------- src/Utopia/Mqtt/Handlers/Unsubscribe.php | 7 +++---- src/Utopia/Mqtt/SubscriptionStore.php | 25 ++++++++++++------------ 4 files changed, 33 insertions(+), 32 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 9baf1eeaa4..f78c504f9d 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -76,10 +76,11 @@ class Mqtt extends MessagingAdapter /** * Subscribe a connection to topic filters. $identifier is the fd, $channels the - * topic filters; roles and queries have no MQTT meaning and are ignored. The - * granted QoS is 1 and the user id comes from the resolved identity so the - * subscription store can scale per client. + * topic filters; roles, queries and $subscriptionId have no MQTT meaning and are + * ignored (the store keys by topic). The granted QoS is 1 and the user id comes + * from the resolved identity so the subscription store can scale per client. * + * @param string $subscriptionId ignored (part of the Messaging adapter contract) * @param array $roles ignored * @param array $channels topic filters * @param array $queryGroup ignored @@ -92,7 +93,6 @@ class Mqtt extends MessagingAdapter $this->subscriptions()->subscribe( $projectId, $userId, - $subscriptionId ?: $topic, $topic, $identifier, Packet::QOS_1, @@ -139,10 +139,10 @@ class Mqtt extends MessagingAdapter } } - /** Remove a single subscription (MQTT UNSUBSCRIBE). */ - public function unsubscribeSubscription(int $fd, string $subscriptionId): void + /** Remove a single topic subscription (MQTT UNSUBSCRIBE). */ + public function unsubscribeSubscription(int $fd, string $topic): void { - $this->subscriptions()->unsubscribe($subscriptionId, $fd); + $this->subscriptions()->unsubscribe($topic, $fd); } /** diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index e0a2000f2f..8cc14158f0 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -39,10 +39,9 @@ class Subscribe extends Action $packetId = substr($body, 0, 2); $offset += 2; - $subId = ''; + // MQTT 5.0 carries a property block before the filters; skip it to reach them. if ($connection->protocol >= 5) { - [$properties, $offset] = Properties::parse($body, $offset); - $subId = (string) ($properties->user()['subId'] ?? ''); + $offset = Properties::skip($body, $offset); } $identity = $connection->identity; @@ -67,13 +66,13 @@ class Subscribe extends Action continue; } - $mqtt->subscribe($connection->projectId, $connection->fd, $subId ?: $filter, [], [$filter]); + $mqtt->subscribe($connection->projectId, $connection->fd, '', [], [$filter]); $granted .= chr(Packet::QOS_1); // granted max QoS 1 $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); // TODO: if we can save directly in the same cache key only $key = 'mqtt:sub:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $filter; - getCache()->save($key, ['subId' => $subId, 'qos' => Packet::QOS_1]); + getCache()->save($key, ['qos' => Packet::QOS_1]); $topics[] = $filter; } @@ -97,8 +96,12 @@ class Subscribe extends Action $payload = $cache->load($lastMessageCursorKey, 3600); $topicDocument = $projectDB->getAuthorization()->skip(fn () => $projectDB->findOne('messages', [Query::containsAny('topics', [$topic]), Query::orderDesc('$sequence'), Query::orderDesc('data')])); - if($topicDocument->isEmpty()) continue; - if(empty($topicDocument->getAttribute('data'))) continue; + if ($topicDocument->isEmpty()) { + continue; + } + if (empty($topicDocument->getAttribute('data'))) { + continue; + } $sequence = $topicDocument?->getAttribute('$sequence') ?? -1; @@ -110,7 +113,7 @@ class Subscribe extends Action $lastSubscriberSequence = max(-1, $payload['sequence'] ?? -1); - if($lastSubscriberSequence === $sequence){ + if ($lastSubscriberSequence === $sequence) { continue; } diff --git a/src/Utopia/Mqtt/Handlers/Unsubscribe.php b/src/Utopia/Mqtt/Handlers/Unsubscribe.php index d9112a00d6..92b5e69bcb 100644 --- a/src/Utopia/Mqtt/Handlers/Unsubscribe.php +++ b/src/Utopia/Mqtt/Handlers/Unsubscribe.php @@ -35,16 +35,15 @@ class Unsubscribe extends Action $packetId = substr($body, 0, 2); $offset += 2; - $subId = ''; + // MQTT 5.0 carries a property block before the filters; skip it to reach them. if ($connection->protocol >= 5) { - [$properties, $offset] = Properties::parse($body, $offset); - $subId = (string) ($properties->user()['subId'] ?? ''); + $offset = Properties::skip($body, $offset); } $count = 0; while ($offset < strlen($body)) { [$filter, $offset] = Packet::readString($body, $offset); - $mqtt->unsubscribeSubscription($connection->fd, $subId ?: $filter); + $mqtt->unsubscribeSubscription($connection->fd, $filter); $count++; } diff --git a/src/Utopia/Mqtt/SubscriptionStore.php b/src/Utopia/Mqtt/SubscriptionStore.php index 8b5151e378..0813d4e836 100644 --- a/src/Utopia/Mqtt/SubscriptionStore.php +++ b/src/Utopia/Mqtt/SubscriptionStore.php @@ -22,9 +22,9 @@ class Node class SubscriptionStore { /** - * fd => connection record + * fd => connection record. * - * @var array}> + * @var array}> */ private array $connections = []; @@ -48,10 +48,10 @@ class SubscriptionStore $this->root = new Node(); } - public function subscribe(string $projectId, string $userId, string $subId, string $topic, int $fd, int $qos = 1) + public function subscribe(string $projectId, string $userId, string $topic, int $fd, int $qos = 1) { - if (isset($this->connections[$fd]['subs'][$subId])) { - $this->unsubscribe($subId, $fd); + if (isset($this->connections[$fd]['subs'][$topic])) { + $this->unsubscribe($topic, $fd); } $nodes = [$projectId, ...explode("/", $topic)]; @@ -73,13 +73,12 @@ class SubscriptionStore 'subs' => [], ]; } - $this->connections[$fd]['subs'][$subId] = ['topic' => $topic, 'qos' => $qos]; + $this->connections[$fd]['subs'][$topic] = $qos; } - public function unsubscribe(string $subId, int $fd) + public function unsubscribe(string $topic, int $fd) { - $topic = $this->connections[$fd]['subs'][$subId]['topic'] ?? null; - if ($topic === null) { + if (!isset($this->connections[$fd]['subs'][$topic])) { return; } @@ -112,7 +111,7 @@ class SubscriptionStore } } - unset($this->connections[$fd]['subs'][$subId]); + unset($this->connections[$fd]['subs'][$topic]); if (empty($this->connections[$fd]['subs'])) { unset($this->connections[$fd]); } @@ -120,14 +119,14 @@ class SubscriptionStore public function close(int $fd) { - foreach (array_keys($this->connections[$fd]['subs'] ?? []) as $subId) { - $this->unsubscribe($subId, $fd); + foreach (array_keys($this->connections[$fd]['subs'] ?? []) as $topic) { + $this->unsubscribe($topic, $fd); } unset($this->connections[$fd]); } /** - * @return array{projectId: string, userId: string, subs: array}|null + * @return array{projectId: string, userId: string, subs: array}|null */ public function getConnection(int $fd): ?array { From dcbf4be7c542dce59e49c75d423afcd25e479e5d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 14:32:55 +0530 Subject: [PATCH 059/146] test(mqtt): update subscription store and adapter tests for topic keying --- .../Appwrite/Messaging/Adapter/MqttTest.php | 15 ++-- .../Utopia/Mqtt/SubscriptionStoreTest.php | 68 ++++++++----------- 2 files changed, 36 insertions(+), 47 deletions(-) diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php index 229180ba4b..f22220b4c4 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -25,11 +25,11 @@ final class MqttTest extends TestCase return new Mqtt(new NoTelemetry()); } - /** open() the fd, then subscribe it to $topic (subId defaults to the topic). */ - private function join(Mqtt $mqtt, string $projectId, int $fd, string $topic, string $subId = ''): void + /** open() the fd, then subscribe it to $topic (the store keys by topic). */ + private function join(Mqtt $mqtt, string $projectId, int $fd, string $topic): void { $mqtt->open($fd); - $mqtt->subscribe($projectId, $fd, $subId, [], [$topic]); + $mqtt->subscribe($projectId, $fd, '', [], [$topic]); } public function testOpenCreatesAndReusesConnection(): void @@ -98,19 +98,18 @@ final class MqttTest extends TestCase { $mqtt = $this->adapter(); $mqtt->open(41); - $mqtt->subscribe('project-a', 41, 'sub-orders', [], ['orders/new']); - $mqtt->subscribe('project-a', 41, 'sub-alerts', [], ['alerts/all']); + $mqtt->subscribe('project-a', 41, '', [], ['orders/new']); + $mqtt->subscribe('project-a', 41, '', [], ['alerts/all']); - $mqtt->unsubscribeSubscription(41, 'sub-orders'); + $mqtt->unsubscribeSubscription(41, 'orders/new'); $this->assertFalse($mqtt->hasSubscriber('project-a', 'orders/new')); $this->assertSame([41 => 1], $mqtt->getSubscribers('project-a', 'alerts/all')); } - public function testSubscriptionIdFallsBackToTopic(): void + public function testUnsubscribeByTopic(): void { $mqtt = $this->adapter(); - // Empty subscription id: the topic itself becomes the id used for removal. $this->join($mqtt, 'project-a', 51, 'news/tech'); $mqtt->unsubscribeSubscription(51, 'news/tech'); diff --git a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php index 096266a799..0977dac608 100644 --- a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php +++ b/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php @@ -44,7 +44,7 @@ final class SubscriptionStoreTest extends TestCase #[DataProvider('matchProvider')] public function testWildcardMatching(string $filter, string $topic, bool $shouldMatch): void { - $this->store->subscribe(self::PROJECT, 'user', 'sub', $filter, 1, 1); + $this->store->subscribe(self::PROJECT, 'user', $filter, 1, 1); $subscribers = $this->store->getSubscribers(self::PROJECT, $topic); @@ -53,23 +53,23 @@ final class SubscriptionStoreTest extends TestCase public function testNoSubscribersReturnsEmpty(): void { - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'nope')); } public function testReturnsGrantedQos(): void { - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); $this->assertSame([1 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); } public function testFanOutToMultipleConnections(): void { - $this->store->subscribe(self::PROJECT, 'user', 'a', 'test/+', 11, 1); - $this->store->subscribe(self::PROJECT, 'user', 'b', 'test/#', 12, 1); - $this->store->subscribe(self::PROJECT, 'user', 'c', 'test/hello', 13, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/+', 11, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/#', 12, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 13, 1); $subscribers = $this->store->getSubscribers(self::PROJECT, 'test/hello'); @@ -80,8 +80,8 @@ final class SubscriptionStoreTest extends TestCase public function testConnectionMatchedByTwoFiltersIsDedupedToHighestQos(): void { // Same fd matched by an exact (QoS 0) and a wildcard (QoS 1) subscription. - $this->store->subscribe(self::PROJECT, 'user', 'exact', 'test/hello', 7, 0); - $this->store->subscribe(self::PROJECT, 'user', 'wild', 'test/#', 7, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 7, 0); + $this->store->subscribe(self::PROJECT, 'user', 'test/#', 7, 1); $subscribers = $this->store->getSubscribers(self::PROJECT, 'test/hello'); @@ -90,49 +90,40 @@ final class SubscriptionStoreTest extends TestCase public function testResubscribeSameFilterReplacesGrantedQos(): void { - // MQTT 3.8.4: re-subscribing the same (connection, subId) replaces the grant. - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 0); + // MQTT 3.8.4: re-subscribing the same (connection, topic) replaces the grant. + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 0); $this->assertSame([1 => 0], $this->store->getSubscribers(self::PROJECT, 'test/hello')); } - public function testResubscribeToNewTopicDropsOldTopic(): void - { - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/world', 1, 1); - - $this->assertArrayNotHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/hello')); - $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/world')); - } - public function testProjectIsolation(): void { - $this->store->subscribe('projectA', 'user', 'sub', 'test/hello', 1, 1); - $this->store->subscribe('projectB', 'user', 'sub', 'test/hello', 2, 1); + $this->store->subscribe('projectA', 'user', 'test/hello', 1, 1); + $this->store->subscribe('projectB', 'user', 'test/hello', 2, 1); $this->assertSame([1 => 1], $this->store->getSubscribers('projectA', 'test/hello')); $this->assertSame([2 => 1], $this->store->getSubscribers('projectB', 'test/hello')); } - public function testUnsubscribeRemovesOnlyThatSubscription(): void + public function testUnsubscribeRemovesOnlyThatTopic(): void { - // One connection, two subscriptions under different subIds. - $this->store->subscribe(self::PROJECT, 'user', 'first', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'second', 'test/world', 1, 1); + // One connection subscribed to two topics. + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/world', 1, 1); - $this->store->unsubscribe('first', 1); + $this->store->unsubscribe('test/hello', 1); $this->assertArrayNotHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/hello')); $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/world')); } - public function testUnsubscribeUnknownSubIsNoop(): void + public function testUnsubscribeUnknownTopicIsNoop(): void { - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - $this->store->unsubscribe('missing', 1); - $this->store->unsubscribe('sub', 999); + $this->store->unsubscribe('missing/topic', 1); + $this->store->unsubscribe('test/hello', 999); $this->assertSame([1 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); } @@ -141,21 +132,20 @@ final class SubscriptionStoreTest extends TestCase { // Covers pruning behaviour observably: after the only subscriber leaves, a // wildcard publish that used to match returns nothing. - $this->store->subscribe(self::PROJECT, 'user', 'sub', 'test/deep/leaf', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/deep/leaf', 1, 1); $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); - $this->store->unsubscribe('sub', 1); + $this->store->unsubscribe('test/deep/leaf', 1); $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); - $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); } public function testCloseRemovesEverySubscriptionForConnection(): void { - $this->store->subscribe(self::PROJECT, 'user', 'first', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'second', 'other/#', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); + $this->store->subscribe(self::PROJECT, 'user', 'other/#', 1, 1); // A second connection that must survive the close. - $this->store->subscribe(self::PROJECT, 'user', 'keep', 'test/hello', 2, 1); + $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 2, 1); $this->store->close(1); @@ -165,13 +155,13 @@ final class SubscriptionStoreTest extends TestCase public function testGetConnectionReturnsTheFdRecord(): void { - $this->store->subscribe(self::PROJECT, 'user-1', 'sub', 'test/hello', 9, 1); + $this->store->subscribe(self::PROJECT, 'user-1', 'test/hello', 9, 1); $connection = $this->store->getConnection(9); $this->assertSame(self::PROJECT, $connection['projectId']); $this->assertSame('user-1', $connection['userId']); - $this->assertSame('test/hello', $connection['subs']['sub']['topic']); + $this->assertSame(1, $connection['subs']['test/hello']); } public function testGetConnectionIsNullForAnUnknownFd(): void From bf7de1b67653c8a50e98198e083424470078893f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 15:35:55 +0530 Subject: [PATCH 060/146] refactor(mqtt): remove unused cache saving logic in Subscribe handler and update SubscriptionStore docblock for clarity --- src/Utopia/Mqtt/Handlers/Subscribe.php | 3 --- src/Utopia/Mqtt/SubscriptionStore.php | 2 +- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index 8cc14158f0..5d589c680b 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -70,9 +70,6 @@ class Subscribe extends Action $granted .= chr(Packet::QOS_1); // granted max QoS 1 $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); - // TODO: if we can save directly in the same cache key only - $key = 'mqtt:sub:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $filter; - getCache()->save($key, ['qos' => Packet::QOS_1]); $topics[] = $filter; } diff --git a/src/Utopia/Mqtt/SubscriptionStore.php b/src/Utopia/Mqtt/SubscriptionStore.php index 0813d4e836..038bbb0438 100644 --- a/src/Utopia/Mqtt/SubscriptionStore.php +++ b/src/Utopia/Mqtt/SubscriptionStore.php @@ -22,7 +22,7 @@ class Node class SubscriptionStore { /** - * fd => connection record. + * fd => connection record. subs are the topic details and in future if required we can use subIds here as well similar to the realtime * * @var array}> */ From 03bd5926d2e02d2149c21196efcc413f142d8c96 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 17:01:41 +0530 Subject: [PATCH 061/146] feat(messaging): topic sequence counter and per-topic MQTT settings columns --- app/config/collections/common.php | 70 ++++++++++++++++++++----------- 1 file changed, 45 insertions(+), 25 deletions(-) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index b1603055ed..0841101d83 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2239,45 +2239,27 @@ return [ 'array' => false, 'filters' => ['json'], ], - // default null means client choose their qos level and no restriction + // The per-topic sequence, copied from the topic counter at insert time. qos and + // expiry are topic settings now (see the topics collection), not per message. [ - '$id' => ID::custom('qos'), + '$id' => ID::custom('sequence'), 'type' => Database::VAR_INTEGER, 'format' => '', 'size' => 0, 'signed' => true, - 'required' => false, + 'required' => true, 'default' => null, 'array' => false, 'filters' => [], ], - // expiry for offline persistence - [ - '$id' => ID::custom('expireAt'), - 'type' => Database::VAR_DATETIME, - 'format' => '', - 'size' => 0, - 'signed' => false, - 'required' => true, - 'default' => null, - 'array' => false, - 'filters' => ['datetime'], - ], ], 'indexes' => [ [ - '$id' => ID::custom('_key_topic'), + '$id' => ID::custom('_key_topic_sequence'), 'type' => Database::INDEX_KEY, - 'attributes' => ['topic'], + 'attributes' => ['topic', 'sequence'], 'lengths' => [], - 'orders' => [Database::ORDER_ASC], - ], - [ - '$id' => ID::custom('_key_expireAt'), - 'type' => Database::INDEX_KEY, - 'attributes' => ['expireAt'], - 'lengths' => [], - 'orders' => [Database::ORDER_ASC], + 'orders' => [Database::ORDER_ASC, Database::ORDER_ASC], ], ], ], @@ -2364,6 +2346,44 @@ return [ 'array' => false, 'filters' => ['topicSearch'], ], + // monotonic message counter for this topic. It is the tail sequence, so + // a client's backlog depth is this minus the client's cursor. + [ + '$id' => ID::custom('sequence'), + 'type' => Database::VAR_INTEGER, + 'format' => '', + 'size' => 0, + 'signed' => true, + 'required' => false, + 'default' => 0, + 'array' => false, + 'filters' => [], + ], + // null lets the subscriber choose. + [ + '$id' => ID::custom('qos'), + 'type' => Database::VAR_INTEGER, + 'format' => '', + 'size' => 0, + 'signed' => true, + 'required' => false, + 'default' => null, + 'array' => false, + 'filters' => [], + ], + // message retention in seconds capped at 7 days. A ledger message expires + // this long after it is written. + [ + '$id' => ID::custom('expiry'), + 'type' => Database::VAR_INTEGER, + 'format' => '', + 'size' => 0, + 'signed' => false, + 'required' => false, + 'default' => null, + 'array' => false, + 'filters' => [], + ], ], 'indexes' => [ From 9032845909a294d67f78ea8d444d9df62268e41e Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 17:01:41 +0530 Subject: [PATCH 062/146] feat(messaging): qos and expiry settings on Appwrite provider and topic endpoints --- .../Messaging/Http/Providers/Appwrite/Create.php | 9 ++++++++- .../Messaging/Http/Providers/Appwrite/Update.php | 16 +++++++++++++++- .../Modules/Messaging/Http/Topics/Create.php | 8 +++++++- .../Modules/Messaging/Http/Topics/Update.php | 13 ++++++++++++- src/Appwrite/Utopia/Response/Model/Topic.php | 14 ++++++++++++++ 5 files changed, 56 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php index fa0893f221..746f1576ab 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Create.php @@ -17,6 +17,7 @@ use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Boolean; use Utopia\Validator\Nullable; +use Utopia\Validator\Range; use Utopia\Validator\Text; class Create extends Action @@ -56,13 +57,15 @@ class Create extends Action ->param('providerId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.', false, ['dbForProject']) ->param('name', '', new Text(128), 'Provider name.') ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) + ->param('qos', null, new Nullable(new Range(0, 1)), 'Default QoS for topics on this provider (0 or 1). Null lets the subscriber choose.', true) + ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Default message retention in seconds for offline delivery. Max 7 days (604800).', true) ->inject('queueForEvents') ->inject('dbForProject') ->inject('response') ->callback($this->action(...)); } - public function action(string $providerId, string $name, ?bool $enabled, Event $queueForEvents, Database $dbForProject, Response $response) + public function action(string $providerId, string $name, ?bool $enabled, ?int $qos, ?int $expiry, Event $queueForEvents, Database $dbForProject, Response $response) { $providerId = $providerId == 'unique()' ? ID::unique() : $providerId; @@ -73,6 +76,10 @@ class Create extends Action 'type' => MESSAGE_TYPE_PUSH, 'enabled' => $enabled ?? true, 'credentials' => [], + 'options' => [ + 'qos' => $qos, + 'expiry' => $expiry, + ], ]); try { diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php index aa2210cbb9..d9e9a9e9eb 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php @@ -14,6 +14,7 @@ use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Boolean; use Utopia\Validator\Nullable; +use Utopia\Validator\Range; use Utopia\Validator\Text; class Update extends Action @@ -53,13 +54,15 @@ class Update extends Action ->param('providerId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Provider ID.', false, ['dbForProject']) ->param('name', '', new Text(128), 'Provider name.', true) ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) + ->param('qos', null, new Nullable(new Range(0, 1)), 'Default QoS for topics on this provider (0 or 1). Null lets the subscriber choose.', true) + ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Default message retention in seconds for offline delivery. Max 7 days (604800).', true) ->inject('queueForEvents') ->inject('dbForProject') ->inject('response') ->callback($this->action(...)); } - public function action(string $providerId, string $name, ?bool $enabled, Event $queueForEvents, Database $dbForProject, Response $response) + public function action(string $providerId, string $name, ?bool $enabled, ?int $qos, ?int $expiry, Event $queueForEvents, Database $dbForProject, Response $response) { $provider = $dbForProject->getDocument('providers', $providerId); @@ -79,6 +82,17 @@ class Update extends Action $provider->setAttribute('enabled', $enabled); } + if (!\is_null($qos) || !\is_null($expiry)) { + $options = $provider->getAttribute('options', []); + if (!\is_null($qos)) { + $options['qos'] = $qos; + } + if (!\is_null($expiry)) { + $options['expiry'] = $expiry; + } + $provider->setAttribute('options', $options); + } + $provider = $dbForProject->updateDocument('providers', $provider->getId(), $provider); $queueForEvents diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php index 6d09d9c948..e527881c83 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php @@ -17,6 +17,8 @@ use Utopia\Database\Helpers\ID; use Utopia\Database\Validator\Roles; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; +use Utopia\Validator\Nullable; +use Utopia\Validator\Range; use Utopia\Validator\Text; class Create extends Action @@ -56,13 +58,15 @@ class Create extends Action ->param('topicId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Topic ID. Choose a custom Topic ID or a new Topic ID.', false, ['dbForProject']) ->param('name', '', new Text(128), 'Topic Name.') ->param('subscribe', [Role::users()], new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true) + ->param('qos', null, new Nullable(new Range(0, 1)), 'QoS for MQTT delivery on this topic (0 or 1). Null lets the subscriber choose.', true) + ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Message retention in seconds for offline delivery. Max 7 days (604800).', true) ->inject('queueForEvents') ->inject('dbForProject') ->inject('response') ->callback($this->action(...)); } - public function action(string $topicId, string $name, array $subscribe, Event $queueForEvents, Database $dbForProject, Response $response) + public function action(string $topicId, string $name, array $subscribe, ?int $qos, ?int $expiry, Event $queueForEvents, Database $dbForProject, Response $response) { $topicId = $topicId == 'unique()' ? ID::unique() : $topicId; @@ -70,6 +74,8 @@ class Create extends Action '$id' => $topicId, 'name' => $name, 'subscribe' => $subscribe, + 'qos' => $qos, + 'expiry' => $expiry, ]); try { diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php index 272a8cfe45..51d0358c2d 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php @@ -14,6 +14,7 @@ use Utopia\Database\Validator\UID; use Utopia\Platform\Action; use Utopia\Platform\Scope\HTTP; use Utopia\Validator\Nullable; +use Utopia\Validator\Range; use Utopia\Validator\Text; class Update extends Action @@ -53,13 +54,15 @@ class Update extends Action ->param('topicId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Topic ID.', false, ['dbForProject']) ->param('name', null, new Nullable(new Text(128)), 'Topic Name.', true) ->param('subscribe', null, new Nullable(new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE)), 'An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true) + ->param('qos', null, new Nullable(new Range(0, 1)), 'QoS for MQTT delivery on this topic (0 or 1). Null lets the subscriber choose.', true) + ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Message retention in seconds for offline delivery. Max 7 days (604800).', true) ->inject('queueForEvents') ->inject('dbForProject') ->inject('response') ->callback($this->action(...)); } - public function action(string $topicId, ?string $name, ?array $subscribe, Event $queueForEvents, Database $dbForProject, Response $response) + public function action(string $topicId, ?string $name, ?array $subscribe, ?int $qos, ?int $expiry, Event $queueForEvents, Database $dbForProject, Response $response) { $topic = $dbForProject->getDocument('topics', $topicId); @@ -75,6 +78,14 @@ class Update extends Action $topic->setAttribute('subscribe', $subscribe); } + if (!\is_null($qos)) { + $topic->setAttribute('qos', $qos); + } + + if (!\is_null($expiry)) { + $topic->setAttribute('expiry', $expiry); + } + $topic = $dbForProject->updateDocument('topics', $topicId, $topic); $queueForEvents diff --git a/src/Appwrite/Utopia/Response/Model/Topic.php b/src/Appwrite/Utopia/Response/Model/Topic.php index dd81430164..efed322388 100644 --- a/src/Appwrite/Utopia/Response/Model/Topic.php +++ b/src/Appwrite/Utopia/Response/Model/Topic.php @@ -58,6 +58,20 @@ class Topic extends Model 'default' => ['users'], 'example' => 'users', 'array' => true, + ]) + ->addRule('qos', [ + 'type' => self::TYPE_INTEGER, + 'description' => 'MQTT QoS for delivery on this topic. Null lets the subscriber choose their level.', + 'default' => null, + 'example' => 1, + 'required' => false, + ]) + ->addRule('expiry', [ + 'type' => self::TYPE_INTEGER, + 'description' => 'Message retention in seconds for offline delivery.', + 'default' => null, + 'example' => 604800, + 'required' => false, ]); } From 6330a342adc350e993733b6a621aef4fdd460305 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 17:01:41 +0530 Subject: [PATCH 063/146] test(messaging): cover qos and expiry on provider and topic endpoints --- .../e2e/Services/Messaging/MessagingBase.php | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/tests/e2e/Services/Messaging/MessagingBase.php b/tests/e2e/Services/Messaging/MessagingBase.php index 1e3c2d448f..4634905b27 100644 --- a/tests/e2e/Services/Messaging/MessagingBase.php +++ b/tests/e2e/Services/Messaging/MessagingBase.php @@ -872,6 +872,8 @@ trait MessagingBase 'providerId' => ID::unique(), 'name' => 'Appwrite1', 'enabled' => true, + 'qos' => 1, + 'expiry' => 3600, ]); $this->assertEquals(201, $provider['headers']['status-code']); @@ -879,6 +881,8 @@ trait MessagingBase $this->assertEquals('appwrite', $provider['body']['provider']); $this->assertEquals('push', $provider['body']['type']); $this->assertTrue($provider['body']['enabled']); + $this->assertEquals(1, $provider['body']['options']['qos']); + $this->assertEquals(3600, $provider['body']['options']['expiry']); } public function testUpdateAppwriteProvider(): void @@ -902,11 +906,15 @@ trait MessagingBase ], [ 'name' => 'Appwrite-after', 'enabled' => false, + 'qos' => 0, + 'expiry' => 7200, ]); $this->assertEquals(200, $response['headers']['status-code']); $this->assertEquals('Appwrite-after', $response['body']['name']); $this->assertFalse($response['body']['enabled']); + $this->assertEquals(0, $response['body']['options']['qos']); + $this->assertEquals(7200, $response['body']['options']['expiry']); // Test for FAILURE: an unknown provider id is not found. $missing = $this->client->call(Client::METHOD_PATCH, '/messaging/providers/appwrite/' . ID::unique(), [ @@ -920,6 +928,39 @@ trait MessagingBase $this->assertEquals(404, $missing['headers']['status-code']); } + public function testCreateTopicWithMqttSettings(): void + { + // Test for SUCCESS: a topic carries its MQTT qos and expiry settings. + $topic = $this->client->call(Client::METHOD_POST, '/messaging/topics', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'topicId' => ID::unique(), + 'name' => 'mqtt-settings-topic', + 'qos' => 1, + 'expiry' => 3600, + ]); + + $this->assertEquals(201, $topic['headers']['status-code']); + $this->assertEquals(1, $topic['body']['qos']); + $this->assertEquals(3600, $topic['body']['expiry']); + + // Test for SUCCESS: the settings update. + $response = $this->client->call(Client::METHOD_PATCH, '/messaging/topics/' . $topic['body']['$id'], [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'qos' => 0, + 'expiry' => 7200, + ]); + + $this->assertEquals(200, $response['headers']['status-code']); + $this->assertEquals(0, $response['body']['qos']); + $this->assertEquals(7200, $response['body']['expiry']); + } + public function testUpdateProviders(): void { $providers = $this->setupCreatedProviders(); From 272461c76db5c953d8b7078daa6187d8306374ea Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Wed, 9 Sep 2026 17:30:46 +0530 Subject: [PATCH 064/146] feat(messaging): add messageId and messageInternalId attributes to messages collection --- app/config/collections/common.php | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index 0841101d83..77a59ffc6e 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2239,6 +2239,28 @@ return [ 'array' => false, 'filters' => ['json'], ], + [ + '$id' => ID::custom('messageId'), + 'type' => Database::VAR_STRING, + 'format' => '', + 'size' => Database::LENGTH_KEY, + 'signed' => true, + 'required' => false, + 'default' => null, + 'array' => false, + 'filters' => [], + ], + [ + '$id' => ID::custom('messageInternalId'), + 'type' => Database::VAR_STRING, + 'format' => '', + 'size' => Database::LENGTH_KEY, + 'signed' => true, + 'required' => false, + 'default' => null, + 'array' => false, + 'filters' => [], + ], // The per-topic sequence, copied from the topic counter at insert time. qos and // expiry are topic settings now (see the topics collection), not per message. [ @@ -2261,6 +2283,13 @@ return [ 'lengths' => [], 'orders' => [Database::ORDER_ASC, Database::ORDER_ASC], ], + [ + '$id' => ID::custom('_key_messageInternalId'), + 'type' => Database::INDEX_KEY, + 'attributes' => ['messageInternalId'], + 'lengths' => [], + 'orders' => [Database::ORDER_ASC], + ], ], ], From 1c1c5705a8c2aefd23eae8727d19979be4c75f9b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 10 Sep 2026 11:24:30 +0530 Subject: [PATCH 065/146] feat(messaging): add Appwrite push adapter for internal broker publish The built-in push provider no longer routes through the messaging lib's MQTT socket client. A new Appwrite\Messaging\Adapter\Push\Appwrite extends the Utopia push adapter and, for each topic, appends one ledger row under the per-topic sequence then fans out over internal pub/sub via the Mqtt broker adapter. This is the single server-side publish path: no outbound socket, no auth session, no way to publish from outside the worker. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_013xRoAk93U3eARtxvehV2hW --- .../Messaging/Adapter/Push/Appwrite.php | 181 ++++++++++++++++++ src/Appwrite/Platform/Workers/Messaging.php | 18 +- 2 files changed, 197 insertions(+), 2 deletions(-) create mode 100644 src/Appwrite/Messaging/Adapter/Push/Appwrite.php diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php new file mode 100644 index 0000000000..792b7c7939 --- /dev/null +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -0,0 +1,181 @@ +getTo()` carries topic identifiers for this provider (not device + * tokens); the recipient resolution upstream feeds topics rather than targets. + */ +class Appwrite extends PushAdapter +{ + protected const NAME = 'Appwrite'; + + /** + * @param Mqtt $broker the broker adapter used for internal pub/sub fan-out + * @param Database $dbForProject the project database holding the topics and ledger + * @param string $projectId the project every topic and publish is scoped to + * @param string $messageId source campaign message id (client-side dedup key) + * @param ?string $messageInternalId source message internal id (correlation) + * @param int $qos delivery QoS for the fan-out envelope + */ + public function __construct( + private readonly Mqtt $broker, + private readonly Database $dbForProject, + private readonly string $projectId, + private readonly string $messageId, + private readonly ?string $messageInternalId, + private readonly int $qos = Packet::QOS_1, + ?Telemetry $telemetry = null, + ) { + parent::__construct($telemetry); + } + + public function getName(): string + { + return static::NAME; + } + + public function getMaxMessagesPerRequest(): int + { + return 5000; + } + + /** + * {@inheritdoc} + */ + protected function process(PushMessage $message): array + { + $payload = $this->buildPayload($message); + $response = new Response($this->getType()); + + foreach ($message->getTo() as $topic) { + try { + $this->persist($topic, $payload); + $this->broker->send( + $this->projectId, + [], + [], + [$topic], + [], + ['payload' => $payload, 'qos' => $this->qos], + ); + + $response->incrementDeliveredTo(); + $response->addResult($topic); + } catch (\Throwable $error) { + $response->addResult($topic, $error->getMessage()); + } + } + + return $response->toArray(); + } + + /** + * Append the payload to the topic's ledger under the next sequence. The + * atomic increment on the topic row hands back the tail so the ledger row + * and the topic counter never diverge under concurrent publishes. + */ + private function persist(string $topic, string $payload): void + { + $authorization = $this->dbForProject->getAuthorization(); + + $sequence = $authorization->skip( + fn () => $this->dbForProject->increaseDocumentAttribute('topics', $topic, 'sequence', 1) + )->getAttribute('sequence'); + + $authorization->skip( + fn () => $this->dbForProject->createDocument('messages_appwrite', new Document([ + '$id' => ID::unique(), + 'topic' => $topic, + 'data' => $payload, + 'messageId' => $this->messageId, + 'messageInternalId' => $this->messageInternalId, + 'sequence' => $sequence, + ])) + ); + } + + /** + * Build the notification envelope delivered to devices. Mirrors the shape + * FCM and APNS expose so SDK consumers render a consistent payload. + */ + private function buildPayload(PushMessage $message): string + { + $envelope = []; + + if ($message->getTitle() !== null) { + $envelope['notification']['title'] = $message->getTitle(); + } + if ($message->getBody() !== null) { + $envelope['notification']['body'] = $message->getBody(); + } + if ($message->getImage() !== null) { + $envelope['notification']['image'] = $message->getImage(); + } + if ($message->getIcon() !== null) { + $envelope['notification']['icon'] = $message->getIcon(); + } + if ($message->getColor() !== null) { + $envelope['notification']['color'] = $message->getColor(); + } + if ($message->getSound() !== null) { + $envelope['notification']['sound'] = $message->getSound(); + } + if ($message->getTag() !== null) { + $envelope['notification']['tag'] = $message->getTag(); + } + if ($message->getBadge() !== null) { + $envelope['notification']['badge'] = $message->getBadge(); + } + if ($message->getAction() !== null) { + $envelope['notification']['action'] = $message->getAction(); + } + if ($message->getContentAvailable() !== null) { + $envelope['notification']['contentAvailable'] = $message->getContentAvailable(); + } + if ($message->getCritical() !== null) { + $envelope['notification']['critical'] = $message->getCritical(); + } + if ($message->getData() !== null) { + $envelope['data'] = $message->getData(); + } + if ($message->getPriority() instanceof Priority) { + $envelope['priority'] = match ($message->getPriority()) { + Priority::HIGH => 'high', + Priority::NORMAL => 'normal', + }; + } + + $json = json_encode($envelope, JSON_UNESCAPED_SLASHES); + if ($json === false) { + throw new \RuntimeException('Failed to encode push payload: ' . json_last_error_msg()); + } + + return $json; + } +} diff --git a/src/Appwrite/Platform/Workers/Messaging.php b/src/Appwrite/Platform/Workers/Messaging.php index 106be49dd4..0a035d47c2 100644 --- a/src/Appwrite/Platform/Workers/Messaging.php +++ b/src/Appwrite/Platform/Workers/Messaging.php @@ -4,6 +4,8 @@ namespace Appwrite\Platform\Workers; use Appwrite\Event\Message\Usage; use Appwrite\Event\Publisher\Usage as UsagePublisher; +use Appwrite\Messaging\Adapter\Mqtt; +use Appwrite\Messaging\Adapter\Push\Appwrite as AppwritePush; use Appwrite\Messaging\Status as MessageStatus; use Appwrite\Usage\Context as UsageContext; use Utopia\Config\Config; @@ -40,6 +42,7 @@ use Utopia\Messaging\Messages\Email\Attachment; use Utopia\Messaging\Messages\Push; use Utopia\Messaging\Messages\SMS; use Utopia\Messaging\Priority; +use Utopia\Mqtt\Packet; use Utopia\Platform\Action; use Utopia\Queue\Message; use Utopia\Span\Span; @@ -224,7 +227,7 @@ class Messaging extends Action $adapter = match ($resolvedProviderType) { MESSAGE_TYPE_SMS => $this->getSmsAdapter($provider), - MESSAGE_TYPE_PUSH => $this->getPushAdapter($provider), + MESSAGE_TYPE_PUSH => $this->getPushAdapter($provider, $dbForProject, $project, $message), MESSAGE_TYPE_EMAIL => $this->getEmailAdapter($provider), default => throw new \Exception('Provider with the requested ID is of the incorrect type') }; @@ -908,7 +911,7 @@ class Messaging extends Action return $adapter; } - protected function getPushAdapter(Document $provider): ?PushAdapter + protected function getPushAdapter(Document $provider, Database $dbForProject, Document $project, Document $message): ?PushAdapter { $credentials = $provider->getAttribute('credentials'); $options = $provider->getAttribute('options'); @@ -923,6 +926,17 @@ class Messaging extends Action $options['sandbox'] ?? false ), 'fcm' => new FCM(\json_encode($credentials['serviceAccountJSON'])), + // The built-in broker: no third-party socket, no auth session. The adapter is + // the single server-side publish path, writing the ledger and fanning out over + // internal pub/sub, so publishing stays impossible from outside the worker. + 'appwrite' => new AppwritePush( + new Mqtt($this->telemetry), + $dbForProject, + $project->getId(), + $message->getId(), + $message->getSequence(), + $options['qos'] ?? Packet::QOS_1, + ), default => null }; From 1367d60f5bff52bd3b5efeef623081ad5d853112 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 10 Sep 2026 11:31:04 +0530 Subject: [PATCH 066/146] feat(messaging): add Appwrite push adapter for internal broker publish The built-in push provider no longer routes through the messaging lib's MQTT socket client. A new Appwrite\Messaging\Adapter\Push\Appwrite extends the Utopia push adapter and, for each topic, appends one ledger row under the per-topic sequence then fans out over internal pub/sub via the Mqtt broker adapter. This is the single server-side publish path: no outbound socket, no auth session, no way to publish from outside the worker. --- .../Messaging/Adapter/Push/Appwrite.php | 23 ------------------- src/Appwrite/Platform/Workers/Messaging.php | 3 --- 2 files changed, 26 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index 792b7c7939..7e585fc213 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -13,24 +13,6 @@ use Utopia\Messaging\Response; use Utopia\Mqtt\Packet; use Utopia\Telemetry\Adapter as Telemetry; -/** - * Appwrite's built-in push provider. - * - * Unlike FCM or APNS, this never opens an outbound socket to a third party. It - * is the single server-side publish path into Appwrite's own MQTT broker: for - * each topic it appends one row to the append-only {@see messages_appwrite} - * ledger under a per-topic sequence, then hands the payload to the {@see Mqtt} - * broker adapter, which fans it out over the internal pub/sub channel to every - * broker worker holding live subscribers. - * - * The ledger is the source of truth for offline QoS 1 replay: a reconnecting - * client resumes from its cursor and reads forward by sequence. Live fan-out - * and durable replay are therefore written in one place, here, so there is - * exactly one writer per topic and no way to publish from outside the worker. - * - * `$message->getTo()` carries topic identifiers for this provider (not device - * tokens); the recipient resolution upstream feeds topics rather than targets. - */ class Appwrite extends PushAdapter { protected const NAME = 'Appwrite'; @@ -95,11 +77,6 @@ class Appwrite extends PushAdapter return $response->toArray(); } - /** - * Append the payload to the topic's ledger under the next sequence. The - * atomic increment on the topic row hands back the tail so the ledger row - * and the topic counter never diverge under concurrent publishes. - */ private function persist(string $topic, string $payload): void { $authorization = $this->dbForProject->getAuthorization(); diff --git a/src/Appwrite/Platform/Workers/Messaging.php b/src/Appwrite/Platform/Workers/Messaging.php index 0a035d47c2..8a87f0a7fa 100644 --- a/src/Appwrite/Platform/Workers/Messaging.php +++ b/src/Appwrite/Platform/Workers/Messaging.php @@ -926,9 +926,6 @@ class Messaging extends Action $options['sandbox'] ?? false ), 'fcm' => new FCM(\json_encode($credentials['serviceAccountJSON'])), - // The built-in broker: no third-party socket, no auth session. The adapter is - // the single server-side publish path, writing the ledger and fanning out over - // internal pub/sub, so publishing stays impossible from outside the worker. 'appwrite' => new AppwritePush( new Mqtt($this->telemetry), $dbForProject, From 6f6a6cd37b1c51992c264c853194f95e8ac91fcb Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 10 Sep 2026 11:57:38 +0530 Subject: [PATCH 067/146] test(messaging): unit tests for the Appwrite push adapter Cover process() against an in-memory database and a fake broker: the ledger row written under the atomically-incremented topic sequence, sequence advancing per publish, independent per-topic counters, envelope shape, and per-topic failure isolation (a bad topic never sinks the rest, and a durable row survives a fan-out failure for later replay). --- .../Messaging/Adapter/Push/AppwriteTest.php | 320 ++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php diff --git a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php new file mode 100644 index 0000000000..d693aadfc9 --- /dev/null +++ b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php @@ -0,0 +1,320 @@ +, options: array}> */ + public array $published = []; + + /** @var array topics to reject, to simulate a fan-out failure */ + public array $failTopics = []; + + public function __construct() + { + parent::__construct(new NoTelemetry()); + } + + public function send(string $projectId, array $payload, array $events, array $channels, array $roles, array $options = []): void + { + foreach ($channels as $topic) { + if (\in_array($topic, $this->failTopics, true)) { + throw new \RuntimeException("broker refused {$topic}"); + } + } + + $this->published[] = [ + 'projectId' => $projectId, + 'channels' => $channels, + 'options' => $options, + ]; + } +} + +/** + * Unit tests for the built-in Appwrite push provider: the append-to-ledger plus + * internal fan-out that process() performs per topic. A real in-memory Database + * backs the topics counter and the messages_appwrite ledger, and a FakeBroker + * captures the fan-out, so no Redis or transport is involved. + * + * The broker CONNECT/publish/subscribe transport is covered by the mqtt-grouped + * e2e (MessagingMqttServerTest) instead. + */ +final class AppwriteTest extends TestCase +{ + private const PROJECT_ID = 'project-a'; + + private Database $database; + + protected function setUp(): void + { + $authorization = new Authorization(); + $authorization->addRole(Role::any()->toString()); + + $this->database = new Database(new Memory(), new Cache(new NoCache())); + $this->database + ->setAuthorization($authorization) + ->setDatabase('mqttTests') + ->setNamespace('mqtt_' . \uniqid()); + $this->database->create(); + + $any = [ + Permission::create(Role::any()), + Permission::read(Role::any()), + Permission::update(Role::any()), + Permission::delete(Role::any()), + ]; + + // The topic counter: only the monotonic `sequence` the adapter increments. + $this->database->createCollection('topics', [], [], $any, false); + $this->database->createAttribute('topics', 'sequence', Database::VAR_INTEGER, 0, false, 0); + + // The append-only ledger. `data` is a plain string here (the adapter passes an + // already-encoded JSON envelope); the production collection's json filter is a + // storage detail, not adapter behaviour. + $this->database->createCollection('messages_appwrite', [], [], $any, false); + $this->database->createAttribute('messages_appwrite', 'topic', Database::VAR_STRING, 255, true); + $this->database->createAttribute('messages_appwrite', 'data', Database::VAR_STRING, 65535, true); + $this->database->createAttribute('messages_appwrite', 'messageId', Database::VAR_STRING, 255, false); + $this->database->createAttribute('messages_appwrite', 'messageInternalId', Database::VAR_STRING, 255, false); + $this->database->createAttribute('messages_appwrite', 'sequence', Database::VAR_INTEGER, 0, true); + } + + /** Seed a topic row with a starting sequence (the current tail). */ + private function seedTopic(string $topicId, int $sequence = 0): void + { + $this->database->createDocument('topics', new Document([ + '$id' => $topicId, + 'sequence' => $sequence, + ])); + } + + private function adapter(FakeBroker $broker, int $qos = 1, string $messageId = 'msg-1', ?string $messageInternalId = 'internal-1'): AppwritePush + { + return new AppwritePush( + $broker, + $this->database, + self::PROJECT_ID, + $messageId, + $messageInternalId, + $qos, + ); + } + + /** + * @return array + */ + private function ledger(): array + { + return $this->database->getAuthorization()->skip(fn () => $this->database->find('messages_appwrite')); + } + + /** The topic counter row, read past authorization. */ + private function topic(string $topicId): Document + { + return $this->database->getAuthorization()->skip(fn () => $this->database->getDocument('topics', $topicId)); + } + + public function testMetadata(): void + { + $adapter = $this->adapter(new FakeBroker()); + + $this->assertSame('Appwrite', $adapter->getName()); + $this->assertSame('push', $adapter->getType()); + $this->assertSame(Push::class, $adapter->getMessageType()); + $this->assertSame(5000, $adapter->getMaxMessagesPerRequest()); + } + + public function testPublishWritesLedgerAndFansOut(): void + { + $this->seedTopic('topic-1', 0); + $broker = new FakeBroker(); + + $response = $this->adapter($broker, qos: 1)->send(new Push( + to: ['topic-1'], + title: 'Hi', + body: 'Hello', + )); + + // Response: one topic, delivered, no failures. + $this->assertSame('push', $response['type']); + $this->assertSame(1, $response['deliveredTo']); + $this->assertCount(1, $response['results']); + $this->assertSame('success', $response['results'][0]['status']); + $this->assertSame('topic-1', $response['results'][0]['recipient']); + + // The topic counter advanced 0 -> 1. + $topic = $this->topic('topic-1'); + $this->assertSame(1, $topic->getAttribute('sequence')); + + // One ledger row, carrying the copied sequence and the source message ids. + $ledger = $this->ledger(); + $this->assertCount(1, $ledger); + $row = $ledger[0]; + $this->assertSame('topic-1', $row->getAttribute('topic')); + $this->assertSame(1, $row->getAttribute('sequence')); + $this->assertSame('msg-1', $row->getAttribute('messageId')); + $this->assertSame('internal-1', $row->getAttribute('messageInternalId')); + + // The fan-out reached the broker with the same project, topic, payload and QoS. + $this->assertCount(1, $broker->published); + $publish = $broker->published[0]; + $this->assertSame(self::PROJECT_ID, $publish['projectId']); + $this->assertSame(['topic-1'], $publish['channels']); + $this->assertSame(1, $publish['options']['qos']); + // The ledger stores exactly what was published. + $this->assertSame($row->getAttribute('data'), $publish['options']['payload']); + } + + public function testPayloadEnvelopeShape(): void + { + $this->seedTopic('topic-1', 0); + $broker = new FakeBroker(); + + $this->adapter($broker)->send(new Push( + to: ['topic-1'], + title: 'Match tonight', + body: 'India vs Australia', + data: ['matchId' => '42'], + priority: Priority::HIGH, + )); + + $payload = \json_decode($broker->published[0]['options']['payload'], true); + + $this->assertSame('Match tonight', $payload['notification']['title']); + $this->assertSame('India vs Australia', $payload['notification']['body']); + $this->assertSame(['matchId' => '42'], $payload['data']); + $this->assertSame('high', $payload['priority']); + } + + public function testSequenceAdvancesPerPublish(): void + { + $this->seedTopic('topic-1', 0); + $broker = new FakeBroker(); + $adapter = $this->adapter($broker); + + $adapter->send(new Push(to: ['topic-1'], title: 'first')); + $adapter->send(new Push(to: ['topic-1'], title: 'second')); + + $sequences = \array_map( + static fn (Document $row): int => $row->getAttribute('sequence'), + $this->ledger(), + ); + \sort($sequences); + $this->assertSame([1, 2], $sequences); + + $topic = $this->topic('topic-1'); + $this->assertSame(2, $topic->getAttribute('sequence')); + } + + public function testEachTopicGetsItsOwnSequence(): void + { + // Two topics at different tails: each advances independently. + $this->seedTopic('topic-1', 5); + $this->seedTopic('topic-2', 0); + $broker = new FakeBroker(); + + $response = $this->adapter($broker)->send(new Push( + to: ['topic-1', 'topic-2'], + title: 'broadcast', + )); + + $this->assertSame(2, $response['deliveredTo']); + $this->assertCount(2, $broker->published); + + $sequenceByTopic = []; + foreach ($this->ledger() as $row) { + $sequenceByTopic[$row->getAttribute('topic')] = $row->getAttribute('sequence'); + } + $this->assertSame(6, $sequenceByTopic['topic-1']); + $this->assertSame(1, $sequenceByTopic['topic-2']); + } + + public function testUnknownTopicFailsWithoutSinkingOthers(): void + { + // Only the first topic exists; the second has no counter row to increment. + $this->seedTopic('topic-1', 0); + $broker = new FakeBroker(); + + $response = $this->adapter($broker)->send(new Push( + to: ['topic-1', 'missing-topic'], + title: 'Hi', + )); + + // The good topic is delivered; the missing one is a per-recipient failure. + $this->assertSame(1, $response['deliveredTo']); + $this->assertCount(2, $response['results']); + + $byRecipient = []; + foreach ($response['results'] as $result) { + $byRecipient[$result['recipient']] = $result; + } + $this->assertSame('success', $byRecipient['topic-1']['status']); + $this->assertSame('failure', $byRecipient['missing-topic']['status']); + $this->assertNotSame('', $byRecipient['missing-topic']['error']); + + // The failure left no ledger row and never reached the broker. + $ledger = $this->ledger(); + $this->assertCount(1, $ledger); + $this->assertSame('topic-1', $ledger[0]->getAttribute('topic')); + $this->assertCount(1, $broker->published); + $this->assertSame(['topic-1'], $broker->published[0]['channels']); + } + + public function testFanOutFailureIsRecordedPerTopic(): void + { + // The ledger write succeeds but the broker rejects the fan-out: the topic is a + // failure, yet the durable row is already written for later replay. + $this->seedTopic('topic-1', 0); + $broker = new FakeBroker(); + $broker->failTopics = ['topic-1']; + + $response = $this->adapter($broker)->send(new Push( + to: ['topic-1'], + title: 'Hi', + )); + + $this->assertSame(0, $response['deliveredTo']); + $this->assertSame('failure', $response['results'][0]['status']); + $this->assertCount(1, $this->ledger()); + $this->assertCount(0, $broker->published); + } + + public function testInvalidMessageTypeRejected(): void + { + $this->expectException(\Exception::class); + $this->expectExceptionMessage('Invalid message type.'); + + // A non-push message is rejected by the base adapter before process() runs. + $this->adapter(new FakeBroker())->send(new Email( + to: ['nobody@appwrite.io'], + subject: 'nope', + content: 'nope', + fromName: 'Appwrite', + fromEmail: 'noreply@appwrite.io', + )); + } +} From c7afd92853661d699b5d6d150d2d93608e13758d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 10 Sep 2026 12:02:40 +0530 Subject: [PATCH 068/146] test(messaging): e2e for the Appwrite push campaign publish flow Drive the built-in provider through the public API end to end: create the provider, a topic, a user, a push target whose identifier is the topic, and a subscriber, then publish a push message to the topic and assert the worker fans it into the broker and marks the message sent with one delivery and no errors. Publish goes only through the message campaign path, never an outside MQTT PUBLISH, matching the server-publish-only model. The provider needs no external credentials, so this runs without a DSN gate. --- .../e2e/Services/Messaging/MessagingBase.php | 108 ++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/tests/e2e/Services/Messaging/MessagingBase.php b/tests/e2e/Services/Messaging/MessagingBase.php index 4634905b27..39577ae79e 100644 --- a/tests/e2e/Services/Messaging/MessagingBase.php +++ b/tests/e2e/Services/Messaging/MessagingBase.php @@ -961,6 +961,114 @@ trait MessagingBase $this->assertEquals(7200, $response['body']['expiry']); } + /** + * The built-in Appwrite (MQTT) push provider is server-published only: a message + * campaign is the single publish path, never an outside MQTT PUBLISH. This drives + * that path end to end through the public API — provider, topic, subscriber, then + * a push message the worker fans out into the broker — and asserts delivery. + * + * Unlike the FCM/APNS push tests, this needs no external credentials or DSN, so it + * always runs: the broker is Appwrite's own. + */ + public function testSendPushViaAppwriteProvider(): void + { + // The built-in push provider: no credentials, enabled by default here. + $provider = $this->client->call(Client::METHOD_POST, '/messaging/providers/appwrite', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'providerId' => ID::unique(), + 'name' => 'Appwrite-send', + 'enabled' => true, + ]); + $this->assertEquals(201, $provider['headers']['status-code']); + + // The topic doubles as the MQTT topic devices subscribe to; its id is the + // delivery topic the broker fans out on. + $topic = $this->client->call(Client::METHOD_POST, '/messaging/topics', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'topicId' => ID::unique(), + 'name' => 'appwrite-push-topic', + 'qos' => 1, + ]); + $this->assertEquals(201, $topic['headers']['status-code']); + $topicId = $topic['body']['$id']; + + $user = $this->client->call(Client::METHOD_POST, '/users', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'userId' => ID::unique(), + 'email' => 'appwrite-push-' . ID::unique() . '@mail.org', + 'password' => 'password', + 'name' => 'Appwrite Push User', + ]); + $this->assertEquals(201, $user['headers']['status-code']); + + // The push target's identifier is the MQTT topic the device listens on, which + // for the built-in provider is the topic id itself. + $target = $this->client->call(Client::METHOD_POST, '/users/' . $user['body']['$id'] . '/targets', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'targetId' => ID::unique(), + 'providerType' => 'push', + 'providerId' => $provider['body']['$id'], + 'identifier' => $topicId, + ]); + $this->assertEquals(201, $target['headers']['status-code']); + + $subscriber = $this->client->call(Client::METHOD_POST, '/messaging/topics/' . $topicId . '/subscribers', \array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders()), [ + 'subscriberId' => ID::unique(), + 'targetId' => $target['body']['$id'], + ]); + $this->assertEquals(201, $subscriber['headers']['status-code']); + + // Publish through the campaign path, targeting the topic. + $push = $this->client->call(Client::METHOD_POST, '/messaging/messages/push', [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ], [ + 'messageId' => ID::unique(), + 'topics' => [$topicId], + 'title' => 'Match update', + 'body' => 'India needs 12 off 6', + 'data' => ['matchId' => '42'], + ]); + $this->assertEquals(201, $push['headers']['status-code']); + $pushMessageId = $push['body']['$id']; + + // Test for SUCCESS: the worker fans the message into the broker and marks it sent. + $this->assertEventually(function () use ($pushMessageId) { + $response = $this->client->call(Client::METHOD_GET, '/messaging/messages/' . $pushMessageId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertContains($response['body']['status'], [MessageStatus::SENT, MessageStatus::FAILED]); + }, 30000, 500); + + $message = $this->client->call(Client::METHOD_GET, '/messaging/messages/' . $pushMessageId, [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]); + $this->assertEquals(200, $message['headers']['status-code']); + $this->assertEquals(MessageStatus::SENT, $message['body']['status']); + $this->assertEquals(1, $message['body']['deliveredTotal']); + $this->assertCount(0, $message['body']['deliveryErrors']); + } + public function testUpdateProviders(): void { $providers = $this->setupCreatedProviders(); From 0a4f70129cf2c17c0d0977a71201ef5826236727 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 08:31:21 +0530 Subject: [PATCH 069/146] bump cache --- composer.json | 29 ++++++++++++ composer.lock | 119 ++++++-------------------------------------------- 2 files changed, 43 insertions(+), 105 deletions(-) diff --git a/composer.json b/composer.json index 308f244580..c84f2616a1 100644 --- a/composer.json +++ b/composer.json @@ -69,6 +69,35 @@ } } }, + { + "type": "package", + "package": { + "name": "utopia-php/cache", + "version": "5.0.999", + "source": { + "url": "https://github.com/utopia-php/monorepo.git", + "type": "git", + "reference": "appwrite-mqtt-poc" + }, + "autoload": { + "psr-4": { + "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" + } + }, + "require": { + "php": ">=8.5.0", + "ext-curl": "*", + "ext-openssl": "*", + "ext-swoole": "*", + "psr/http-client": "^1.0", + "psr/http-message": "^1.1 || ^2.0", + "utopia-php/client": "^0.3", + "utopia-php/pools": "^2.0", + "utopia-php/smtp": "^0.1", + "utopia-php/telemetry": "^0.4" + } + } + }, { "type": "vcs", "url": "https://github.com/utopia-php/auth" diff --git a/composer.lock b/composer.lock index ed24beebc2..3b93530ff7 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "898dbb4270192e3f4c1e4f14a751f975", + "content-hash": "a1bb9cd493b34ae7dc1d60a01fb95e30", "packages": [ { "name": "adhocore/jwt", @@ -3037,62 +3037,30 @@ }, { "name": "utopia-php/cache", - "version": "5.0.0", + "version": "5.0.999", "source": { "type": "git", - "url": "https://github.com/utopia-php/cache.git", - "reference": "0d0752785fc81b5afd6571f4291763166a6532bc" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/0d0752785fc81b5afd6571f4291763166a6532bc", - "reference": "0d0752785fc81b5afd6571f4291763166a6532bc", - "shasum": "" + "url": "https://github.com/utopia-php/monorepo.git", + "reference": "appwrite-mqtt-poc" }, "require": { - "ext-json": "*", - "php": ">=8.4", - "utopia-php/circuit-breaker": "^0.4", + "ext-curl": "*", + "ext-openssl": "*", + "ext-swoole": "*", + "php": ">=8.5.0", + "psr/http-client": "^1.0", + "psr/http-message": "^1.1 || ^2.0", + "utopia-php/client": "^0.3", "utopia-php/pools": "^2.0", + "utopia-php/smtp": "^0.1", "utopia-php/telemetry": "^0.4" }, - "require-dev": { - "swoole/ide-helper": "^6.0" - }, - "suggest": { - "ext-memcached": "Required for the Memcached and Hazelcast adapters.", - "ext-redis": "Required for the Redis, RedisCluster and Sharding adapters.", - "ext-swoole": "Required for the multiplexing Redis adapter (>=6.0)." - }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Cache\\": "src/Cache" + "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Team Appwrite", - "email": "team@appwrite.io" - } - ], - "description": "A simple cache library to manage application cache storing, loading and purging", - "keywords": [ - "cache", - "framework", - "php", - "upf", - "utopia" - ], - "support": { - "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/5.0.0" - }, - "time": "2026-08-21T11:04:48+00:00" + } }, { "name": "utopia-php/cdn", @@ -3170,65 +3138,6 @@ }, "time": "2026-08-29T11:50:39+00:00" }, - { - "name": "utopia-php/circuit-breaker", - "version": "0.4.0", - "source": { - "type": "git", - "url": "https://github.com/utopia-php/circuit-breaker.git", - "reference": "c6d93c7ba9d895cf906360e000f74ff762d83e17" - }, - "dist": { - "type": "zip", - "url": "https://api.github.com/repos/utopia-php/circuit-breaker/zipball/c6d93c7ba9d895cf906360e000f74ff762d83e17", - "reference": "c6d93c7ba9d895cf906360e000f74ff762d83e17", - "shasum": "" - }, - "require": { - "php": ">=8.2" - }, - "require-dev": { - "utopia-php/telemetry": "^0.4.6" - }, - "suggest": { - "ext-opentelemetry": "Required by utopia-php/telemetry when using OpenTelemetry metrics.", - "ext-protobuf": "Required by utopia-php/telemetry when using OpenTelemetry metrics.", - "ext-redis": "Required when using Utopia\\CircuitBreaker\\Adapter\\Redis with the phpredis extension.", - "ext-swoole": "Required when using Utopia\\CircuitBreaker\\Adapter\\SwooleTable.", - "utopia-php/telemetry": "Required when passing telemetry adapters or running the local telemetry demo." - }, - "type": "library", - "autoload": { - "psr-4": { - "Utopia\\CircuitBreaker\\": "src/CircuitBreaker/" - } - }, - "notification-url": "https://packagist.org/downloads/", - "license": [ - "MIT" - ], - "authors": [ - { - "name": "Team Appwrite", - "email": "team@appwrite.io" - } - ], - "description": "Light & simple Circuit Breaker for PHP to prevent cascading failures in distributed systems.", - "keywords": [ - "circuit-breaker", - "fault-tolerance", - "framework", - "php", - "resilience", - "upf", - "utopia" - ], - "support": { - "issues": "https://github.com/utopia-php/circuit-breaker/issues", - "source": "https://github.com/utopia-php/circuit-breaker/tree/0.4.0" - }, - "time": "2026-08-21T10:20:24+00:00" - }, { "name": "utopia-php/cli", "version": "0.24.4", From c900938a9d8451d764f7e4e4bbffb1dd5159115a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 08:48:31 +0530 Subject: [PATCH 070/146] updated cache --- composer.json | 2 +- composer.lock | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/composer.json b/composer.json index c84f2616a1..571cf6c5e9 100644 --- a/composer.json +++ b/composer.json @@ -77,7 +77,7 @@ "source": { "url": "https://github.com/utopia-php/monorepo.git", "type": "git", - "reference": "appwrite-mqtt-poc" + "reference": "bulk-cache-load" }, "autoload": { "psr-4": { diff --git a/composer.lock b/composer.lock index 3b93530ff7..ef2759eddf 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "a1bb9cd493b34ae7dc1d60a01fb95e30", + "content-hash": "afb18eb0e5b98842199bcf935378b483", "packages": [ { "name": "adhocore/jwt", @@ -3041,7 +3041,7 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/monorepo.git", - "reference": "appwrite-mqtt-poc" + "reference": "bulk-cache-load" }, "require": { "ext-curl": "*", From e5e8ab33afff90e3d032ccdc8ab7fba6a874f5fa Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 12:23:16 +0530 Subject: [PATCH 071/146] refactor(messaging): rename push ledger collection to appwrite_push_ledger --- app/config/collections/common.php | 4 ++-- src/Appwrite/Messaging/Adapter/Push/Appwrite.php | 2 +- .../Messaging/Adapter/Push/AppwriteTest.php | 14 +++++++------- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index 77a59ffc6e..bf1cd82c56 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2212,9 +2212,9 @@ return [ ], ], - 'messages_appwrite' => [ + 'appwrite_push_ledger' => [ '$collection' => ID::custom(DATABASE::METADATA), - '$id' => ID::custom('messages_appwrite'), + '$id' => ID::custom('appwrite_push_ledger'), 'name' => 'MQTT Messages', 'attributes' => [ [ diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index 7e585fc213..3729cc51d0 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -86,7 +86,7 @@ class Appwrite extends PushAdapter )->getAttribute('sequence'); $authorization->skip( - fn () => $this->dbForProject->createDocument('messages_appwrite', new Document([ + fn () => $this->dbForProject->createDocument('appwrite_push_ledger', new Document([ '$id' => ID::unique(), 'topic' => $topic, 'data' => $payload, diff --git a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php index d693aadfc9..eea40f6d1c 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php @@ -95,12 +95,12 @@ final class AppwriteTest extends TestCase // The append-only ledger. `data` is a plain string here (the adapter passes an // already-encoded JSON envelope); the production collection's json filter is a // storage detail, not adapter behaviour. - $this->database->createCollection('messages_appwrite', [], [], $any, false); - $this->database->createAttribute('messages_appwrite', 'topic', Database::VAR_STRING, 255, true); - $this->database->createAttribute('messages_appwrite', 'data', Database::VAR_STRING, 65535, true); - $this->database->createAttribute('messages_appwrite', 'messageId', Database::VAR_STRING, 255, false); - $this->database->createAttribute('messages_appwrite', 'messageInternalId', Database::VAR_STRING, 255, false); - $this->database->createAttribute('messages_appwrite', 'sequence', Database::VAR_INTEGER, 0, true); + $this->database->createCollection('appwrite_push_ledger', [], [], $any, false); + $this->database->createAttribute('appwrite_push_ledger', 'topic', Database::VAR_STRING, 255, true); + $this->database->createAttribute('appwrite_push_ledger', 'data', Database::VAR_STRING, 65535, true); + $this->database->createAttribute('appwrite_push_ledger', 'messageId', Database::VAR_STRING, 255, false); + $this->database->createAttribute('appwrite_push_ledger', 'messageInternalId', Database::VAR_STRING, 255, false); + $this->database->createAttribute('appwrite_push_ledger', 'sequence', Database::VAR_INTEGER, 0, true); } /** Seed a topic row with a starting sequence (the current tail). */ @@ -129,7 +129,7 @@ final class AppwriteTest extends TestCase */ private function ledger(): array { - return $this->database->getAuthorization()->skip(fn () => $this->database->find('messages_appwrite')); + return $this->database->getAuthorization()->skip(fn () => $this->database->find('appwrite_push_ledger')); } /** The topic counter row, read past authorization. */ From b0b5fc5fb408f5ab7fca075de5c3049d6c3a529d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 12:23:16 +0530 Subject: [PATCH 072/146] chore(deps): point utopia-php/cache at the batch/ttl branch (loadMany/saveMany) --- composer.json | 19 ++++------- composer.lock | 88 +++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 82 insertions(+), 25 deletions(-) diff --git a/composer.json b/composer.json index 571cf6c5e9..5dc6c6b890 100644 --- a/composer.json +++ b/composer.json @@ -73,27 +73,22 @@ "type": "package", "package": { "name": "utopia-php/cache", - "version": "5.0.999", + "version": "dev-bulk-cache-load", "source": { "url": "https://github.com/utopia-php/monorepo.git", "type": "git", - "reference": "bulk-cache-load" + "reference": "c340994cea9841853d7722488bde443ec9d3f629" }, "autoload": { "psr-4": { - "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" + "Utopia\\Cache\\": "packages/cache/src/Cache" } }, "require": { - "php": ">=8.5.0", - "ext-curl": "*", - "ext-openssl": "*", - "ext-swoole": "*", - "psr/http-client": "^1.0", - "psr/http-message": "^1.1 || ^2.0", - "utopia-php/client": "^0.3", + "php": ">=8.4", + "ext-json": "*", + "utopia-php/circuit-breaker": "^0.4", "utopia-php/pools": "^2.0", - "utopia-php/smtp": "^0.1", "utopia-php/telemetry": "^0.4" } } @@ -136,7 +131,7 @@ "utopia-php/audit": "^4.0", "utopia-php/auth": "^0.10", "utopia-php/balancer": "0.4.*", - "utopia-php/cache": "^5.0.0", + "utopia-php/cache": "dev-bulk-cache-load as 5.0.999", "utopia-php/cdn": "^0.0.8", "utopia-php/cli": "^0.24", "utopia-php/compression": "0.1.*", diff --git a/composer.lock b/composer.lock index ef2759eddf..de7661f993 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "afb18eb0e5b98842199bcf935378b483", + "content-hash": "cc18bd79655117398497d7a4ca68c3cf", "packages": [ { "name": "adhocore/jwt", @@ -3037,28 +3037,23 @@ }, { "name": "utopia-php/cache", - "version": "5.0.999", + "version": "dev-bulk-cache-load", "source": { "type": "git", "url": "https://github.com/utopia-php/monorepo.git", - "reference": "bulk-cache-load" + "reference": "c340994cea9841853d7722488bde443ec9d3f629" }, "require": { - "ext-curl": "*", - "ext-openssl": "*", - "ext-swoole": "*", - "php": ">=8.5.0", - "psr/http-client": "^1.0", - "psr/http-message": "^1.1 || ^2.0", - "utopia-php/client": "^0.3", + "ext-json": "*", + "php": ">=8.4", + "utopia-php/circuit-breaker": "^0.4", "utopia-php/pools": "^2.0", - "utopia-php/smtp": "^0.1", "utopia-php/telemetry": "^0.4" }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" + "Utopia\\Cache\\": "packages/cache/src/Cache" } } }, @@ -3138,6 +3133,65 @@ }, "time": "2026-08-29T11:50:39+00:00" }, + { + "name": "utopia-php/circuit-breaker", + "version": "0.4.0", + "source": { + "type": "git", + "url": "https://github.com/utopia-php/circuit-breaker.git", + "reference": "c6d93c7ba9d895cf906360e000f74ff762d83e17" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/circuit-breaker/zipball/c6d93c7ba9d895cf906360e000f74ff762d83e17", + "reference": "c6d93c7ba9d895cf906360e000f74ff762d83e17", + "shasum": "" + }, + "require": { + "php": ">=8.2" + }, + "require-dev": { + "utopia-php/telemetry": "^0.4.6" + }, + "suggest": { + "ext-opentelemetry": "Required by utopia-php/telemetry when using OpenTelemetry metrics.", + "ext-protobuf": "Required by utopia-php/telemetry when using OpenTelemetry metrics.", + "ext-redis": "Required when using Utopia\\CircuitBreaker\\Adapter\\Redis with the phpredis extension.", + "ext-swoole": "Required when using Utopia\\CircuitBreaker\\Adapter\\SwooleTable.", + "utopia-php/telemetry": "Required when passing telemetry adapters or running the local telemetry demo." + }, + "type": "library", + "autoload": { + "psr-4": { + "Utopia\\CircuitBreaker\\": "src/CircuitBreaker/" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Team Appwrite", + "email": "team@appwrite.io" + } + ], + "description": "Light & simple Circuit Breaker for PHP to prevent cascading failures in distributed systems.", + "keywords": [ + "circuit-breaker", + "fault-tolerance", + "framework", + "php", + "resilience", + "upf", + "utopia" + ], + "support": { + "issues": "https://github.com/utopia-php/circuit-breaker/issues", + "source": "https://github.com/utopia-php/circuit-breaker/tree/0.4.0" + }, + "time": "2026-08-21T10:20:24+00:00" + }, { "name": "utopia-php/cli", "version": "0.24.4", @@ -8481,9 +8535,17 @@ "time": "2026-09-04T16:56:24+00:00" } ], - "aliases": [], + "aliases": [ + { + "package": "utopia-php/cache", + "version": "dev-bulk-cache-load", + "alias": "5.0.999", + "alias_normalized": "5.0.999.0" + } + ], "minimum-stability": "dev", "stability-flags": { + "utopia-php/cache": 20, "utopia-php/http": 5, "utopia-php/mqtt": 20 }, From 1ec70ae35c6d9d1108871c8480c30c2e976c55f8 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 12:23:16 +0530 Subject: [PATCH 073/146] feat(mqtt): replay missed messages from the ledger on subscribe One cursor hash per client (topic => sequence). On subscribe, new topics seed at the tail; resumed topics replay from the ledger up to a max depth, delivered QoS 1 (cursor advances on PUBACK). clean-start purges the session. --- src/Utopia/Mqtt/Handlers/Subscribe.php | 91 ++++++++++++++++++-------- 1 file changed, 62 insertions(+), 29 deletions(-) diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index 5d589c680b..fea8a19f21 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -80,47 +80,80 @@ class Subscribe extends Action false, ); - // session replay - // TODO: update the ttl + bulk fetch + bulk upload to the cache to reduce the network calls - // same for the database below + if ($topics === []) { + return; + } + + // TODO: expiry should track the plan + $expiry = 3600; + $maxDepth = 5; + $consoleDatabase = getConsoleDB(); $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); $projectDB = getProjectDB($project); - $cache = getCache(); + + $cursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); + + // A clean-start session discards any persisted cursor before resuming. + if ($connection->cleanStart) { + $cache->purge($cursorKey); + } + + $cursors = $cache->loadMany($cursorKey, $expiry); + $known = array_keys($cursors); + $newTopics = array_values(array_diff($topics, $known)); + $resumeTopics = array_values(array_intersect($topics, $known)); + + // Current tail (topics.sequence) per subscribed topic: the seed for new topics and + // the upper bound for replay. getDocument is cached, so repeated reads are cheap. + $tails = []; foreach ($topics as $topic) { - $lastMessageCursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $topic; - $payload = $cache->load($lastMessageCursorKey, 3600); - - $topicDocument = $projectDB->getAuthorization()->skip(fn () => $projectDB->findOne('messages', [Query::containsAny('topics', [$topic]), Query::orderDesc('$sequence'), Query::orderDesc('data')])); - if ($topicDocument->isEmpty()) { - continue; + $topicDocument = $projectDB->getAuthorization()->skip(fn () => $projectDB->getDocument('topics', $topic)); + if (!$topicDocument->isEmpty()) { + $tails[$topic] = (int) $topicDocument->getAttribute('sequence', 0); } - if (empty($topicDocument->getAttribute('data'))) { + } + + $persist = []; + foreach ($newTopics as $topic) { + $persist[$topic] = ['sequence' => $tails[$topic] ?? 0]; + } + foreach ($resumeTopics as $topic) { + $persist[$topic] = $cursors[$topic]; + } + + foreach ($resumeTopics as $topic) { + $from = (int) ($cursors[$topic]['sequence'] ?? 0); + $tail = $tails[$topic] ?? $from; + if ($tail <= $from) { continue; } - $sequence = $topicDocument?->getAttribute('$sequence') ?? -1; + $start = max($from + 1, $tail - $maxDepth + 1); + $messages = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('appwrite_push_ledger', [ + Query::equal('topic', [$topic]), + Query::greaterThanEqual('sequence', $start), + Query::orderAsc('sequence'), + Query::limit($maxDepth), + ])); - if ($payload === false) { - // Newly connected device: register at the current tail so it starts from now. - $cache->save($lastMessageCursorKey, ['sequence' => $sequence]); - continue; + foreach ($messages as $message) { + $packetId = $connection->nextPacketId(); + // The ledger `data` (json filter) already holds the encoded envelope + // string the live path publishes; re-encoding it would double-encode. + $stored = $message->getAttribute('data'); + $data = \is_string($stored) ? $stored : (string) json_encode($stored); + $publish = $connection->protocol >= 5 + ? V5::publish($topic, $data, Packet::QOS_1, $packetId, dup: true) + : V3::publish($topic, $data, Packet::QOS_1, $packetId, dup: true); + $reply($publish, false); + $connection->track($packetId, $topic, (int) $message->getAttribute('sequence')); } + } - $lastSubscriberSequence = max(-1, $payload['sequence'] ?? -1); - - if ($lastSubscriberSequence === $sequence) { - continue; - } - - // TODO: fetch the last global message cursor then calculate the depth and send - $packetId = $connection->nextPacketId(); - $publish = $connection->protocol >= 5 - ? V5::publish($topic, json_encode($topicDocument->getAttribute('data')), Packet::QOS_1, $packetId, dup: true) - : V3::publish($topic, json_encode($topicDocument->getAttribute('data')), Packet::QOS_1, $packetId, dup: true); - $reply($publish, false); - $connection->track($packetId, $topic, $sequence); + if ($persist !== []) { + $cache->saveMany($cursorKey, $persist, $expiry); } } } From 218324f0d98773fd28b6fd890bac36279b69bad4 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 12:23:16 +0530 Subject: [PATCH 074/146] fix(mqtt): advance the subscriber cursor monotonically on puback Per-packet PUBACK coroutines can run concurrently; only move the cursor forward so a stale/out-of-order ack cannot rewind it and re-deliver the tail. --- src/Utopia/Mqtt/Handlers/Puback.php | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/Utopia/Mqtt/Handlers/Puback.php b/src/Utopia/Mqtt/Handlers/Puback.php index 0adb6dee71..7fe9975c0b 100644 --- a/src/Utopia/Mqtt/Handlers/Puback.php +++ b/src/Utopia/Mqtt/Handlers/Puback.php @@ -57,7 +57,13 @@ class Puback extends Action $mqtt->metrics->messagesAcked->add(1); $cache = getCache(); - $key = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId() . ':' . $delivery['topic']; - $cache->save($key, ['sequence' => $delivery['sequence']]); + $cursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); + $topic = $delivery['topic']; + $sequence = (int) $delivery['sequence']; + + $current = $cache->loadMany($cursorKey, 3600, [$topic]); + if ($sequence > (int) ($current[$topic]['sequence'] ?? -1)) { + $cache->saveMany($cursorKey, [$topic => ['sequence' => $sequence]], 3600); + } } } From 9bb47c9a63c289f5fc6f227790f4ff0df5e91077 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 12:23:16 +0530 Subject: [PATCH 075/146] test(messaging): in-repo MQTT subscriber and broker e2e Add MqttSubscriber (utopia-php/mqtt codec) so tests control clientId/cleanStart, dropping the messaging client for subscribing. Cover CONNECT auth, campaign fan-out to a live subscriber, offline session replay, max-depth cap, clean-start. --- .../Messaging/MessagingMqttServerTest.php | 396 +++++++++++++----- .../e2e/Services/Messaging/MqttSubscriber.php | 212 ++++++++++ 2 files changed, 500 insertions(+), 108 deletions(-) create mode 100644 tests/e2e/Services/Messaging/MqttSubscriber.php diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 78243c30d7..a9dc99b929 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -4,23 +4,22 @@ declare(strict_types=1); namespace Tests\E2E\Services\Messaging; +use Appwrite\Messaging\Status as MessageStatus; use PHPUnit\Framework\Attributes\Group; 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\Messaging\Adapter\Push\Appwrite as AppwritePush; -use Utopia\Messaging\Messages\Push; /** - * End-to-end tests for the MQTT push broker (src/Utopia/Mqtt), driven by the - * utopia-php/messaging Appwrite Push adapter. Exercises the real broker container - * over TCP: enhanced-auth CONNECT against the project/user graph, QoS 1 - * publish/ack, fan-out to a subscriber via consume(), and subscribe-side ACL. + * End-to-end tests for the MQTT push broker (src/Utopia/Mqtt). Publishing is a server + * privilege driven entirely through the Messaging HTTP campaign path (there is no + * outside MQTT publish); the subscriber side is a self-contained MqttSubscriber over + * TCP. Exercises enhanced-auth CONNECT against the project/user graph, campaign + * fan-out to a live subscriber, and offline QoS 1 session replay from the ledger. * - * Blocked accounts are refused at CONNECT (CONNACK 0x87); the subscribe authorizer - * re-checks as defense in depth. (Topic-existence authorization is still pending.) + * Blocked/unauthenticated accounts are refused at CONNECT (CONNACK reason 0x87). * * Grouped `mqtt` because it needs the broker container (appwrite-mqtt:1883): the * standard e2e stacks exclude this group, and a dedicated lane that runs the broker @@ -66,51 +65,15 @@ final class MessagingMqttServerTest extends Scope return ['userId' => $userId, 'jwt' => $jwt['body']['jwt']]; } - private function newAdapter(string $projectId, string $credential): AppwritePush - { - return new AppwritePush( - endpoint: self::BROKER_HOST . ':' . self::BROKER_PORT, - projectId: $projectId, - credential: $credential, - authMethod: 'appwrite-jwt', - tls: false, - ); - } - - public function testAdapterPublishesToBroker(): void - { - $projectId = $this->getProject()['$id']; - $jwt = $this->createUser()['jwt']; - - // Test for SUCCESS: publishing is a server privilege (not ACL-gated). - $response = $this->newAdapter($projectId, $jwt)->send(new Push( - to: ['device-1', 'device-2'], - title: 'Hi', - body: 'Hello', - )); - - $this->assertEquals('push', $response['type']); - $this->assertEquals(2, $response['deliveredTo']); - foreach ($response['results'] as $result) { - $this->assertEquals('success', $result['status']); - $this->assertEquals('', $result['error']); - } - } - public function testUnauthorizedConnectRejected(): void { $projectId = $this->getProject()['$id']; - // Test for FAILURE: a bogus credential yields CONNACK 0x87 and a closed socket, - // which the adapter surfaces as a thrown error out of send(). - $adapter = $this->newAdapter($projectId, 'not.a.valid.jwt'); - - $this->expectException(\Throwable::class); - $adapter->send(new Push( - to: ['device-1'], - title: 'Hi', - body: 'Hello', - )); + // Test for FAILURE: a bogus credential is refused at CONNECT with reason 0x87 + // (not authorized). + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0x87, $subscriber->connect($projectId, 'not.a.valid.jwt', 'e2e-reject', cleanStart: true)); + $subscriber->disconnect(); } public function testBlockedUserConnectRejected(): void @@ -125,75 +88,292 @@ final class MessagingMqttServerTest extends Scope ], $this->getHeaders()), ['status' => false]); $this->assertEquals(200, $status['headers']['status-code']); - // Test for FAILURE: a blocked account is refused at CONNECT (CONNACK 0x87), - // which the adapter surfaces as a thrown error out of send(). - $this->expectException(\Throwable::class); - $this->expectExceptionMessageMatches('/reject/i'); - $this->newAdapter($projectId, $jwt)->send(new Push( - to: ['device-1'], - title: 'Hi', - body: 'Hello', - )); + // Test for FAILURE: a blocked account is refused at CONNECT with reason 0x87. + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0x87, $subscriber->connect($projectId, $jwt, 'e2e-blocked', cleanStart: true)); + $subscriber->disconnect(); } - public function testPublishConsumedBySubscriber(): void + /** + * The messaging graph for the built-in Appwrite push provider: a provider, a topic + * (whose id is the MQTT delivery channel), a user with a push target identified by + * that topic id, and a subscription. Returns the topic id. + * + * @param array $server server-key headers + */ + private function setupPushTopic(array $server, string $userId, string $name): string + { + $provider = $this->client->call(Client::METHOD_POST, '/messaging/providers/appwrite', $server, [ + 'providerId' => ID::unique(), + 'name' => $name, + 'enabled' => true, + ]); + $this->assertEquals(201, $provider['headers']['status-code']); + + $topic = $this->client->call(Client::METHOD_POST, '/messaging/topics', $server, [ + 'topicId' => ID::unique(), + 'name' => $name, + 'qos' => 1, + ]); + $this->assertEquals(201, $topic['headers']['status-code']); + $topicId = $topic['body']['$id']; + + $target = $this->client->call(Client::METHOD_POST, '/users/' . $userId . '/targets', $server, [ + 'targetId' => ID::unique(), + 'providerType' => 'push', + 'providerId' => $provider['body']['$id'], + 'identifier' => $topicId, + ]); + $this->assertEquals(201, $target['headers']['status-code']); + + $subscriber = $this->client->call(Client::METHOD_POST, '/messaging/topics/' . $topicId . '/subscribers', $server, [ + 'subscriberId' => ID::unique(), + 'targetId' => $target['body']['$id'], + ]); + $this->assertEquals(201, $subscriber['headers']['status-code']); + + return $topicId; + } + + /** + * Publish a push campaign to a topic and block until the worker marks it terminal + * (SENT persists it to the ledger and fans it into the broker). + * + * @param array $server + * @param array $data + */ + private function publishCampaign(array $server, string $topicId, string $title, string $body, array $data = []): void + { + $push = $this->client->call(Client::METHOD_POST, '/messaging/messages/push', $server, [ + 'messageId' => ID::unique(), + 'topics' => [$topicId], + 'title' => $title, + 'body' => $body, + 'data' => $data, + ]); + $this->assertEquals(201, $push['headers']['status-code']); + $messageId = $push['body']['$id']; + + $this->assertEventually(function () use ($server, $messageId) { + $message = $this->client->call(Client::METHOD_GET, '/messaging/messages/' . $messageId, $server); + $this->assertContains($message['body']['status'], [MessageStatus::SENT, MessageStatus::FAILED]); + }, 30000, 500); + } + + /** + * Full flow: a Messaging push campaign fans out through the worker and the built-in + * Appwrite provider into the broker, and a live MQTT subscriber on the topic-id + * channel receives it. The subscriber is our own MqttSubscriber (no messaging + * adapter): connect + subscribe, publish the campaign, then read the live delivery. + */ + public function testCampaignFansOutToMqttSubscriber(): void { $projectId = $this->getProject()['$id']; ['userId' => $userId, 'jwt' => $jwt] = $this->createUser(); - // The connection subscribes to its own user scope (ACL-allowed) and the server - // publishes to that same topic. - $topic = 'appwrite/push/' . $userId; + $server = [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $projectId, + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]; + $topicId = $this->setupPushTopic($server, $userId, 'appwrite-mqtt-flow'); - // Publish from a separate OS process so it runs while consume() blocks. The - // broker only fans out to already-connected subscribers, so the publisher waits. - // Resolve the autoloader from the running one rather than a fixed relative depth, - // so it works both standalone (repo vendor/) and vendored inside another project - // (e.g. cloud's vendor/appwrite/server-ce, whose own vendor/ is not installed). - $autoload = \dirname((new \ReflectionClass(\Composer\Autoload\ClassLoader::class))->getFileName(), 2) . '/autoload.php'; - $publisher = \tempnam(\sys_get_temp_dir(), 'mqtt-pub-') . '.php'; - \file_put_contents($publisher, <<<'PHP' - send(new Utopia\Messaging\Messages\Push(to: [$userId], title: 'Ping', body: 'Pong', data: ['k' => 'v'])); - } catch (\Throwable $error) { - \fwrite(STDERR, $error->getMessage()); - } - PHP); - - $process = \proc_open( - [PHP_BINARY, $publisher, $autoload, self::BROKER_HOST . ':' . self::BROKER_PORT, $projectId, $jwt, $userId], - [0 => ['pipe', 'r'], 1 => ['file', '/dev/null', 'a'], 2 => ['file', '/dev/null', 'a']], - $pipes, - ); - $this->assertNotFalse($process, 'could not start publisher process'); + // Subscribe first (the fan-out only reaches connected subscribers), then publish, + // then read the delivery that lands on the still-open socket. + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-flow-' . $userId, cleanStart: true)); + $subscriber->subscribe([$topicId]); try { - $received = []; - $handled = $this->newAdapter($projectId, $jwt)->consume( - [$topic], - function (array $message) use (&$received): void { - $received = $message; - }, - limit: 1, - timeout: 10.0, - ); - - // Test for SUCCESS: the broker delivered the publish to the subscribed consumer. - $this->assertSame(1, $handled, 'consumer did not receive the publish'); - $this->assertSame($topic, $received['topic']); - - $decoded = \json_decode($received['payload'], true); - $this->assertEquals('Ping', $decoded['notification']['title']); - $this->assertEquals('Pong', $decoded['notification']['body']); - $this->assertEquals(['k' => 'v'], $decoded['data']); + $this->publishCampaign($server, $topicId, 'Match update', 'India needs 12 off 6', ['matchId' => '42']); + $received = $subscriber->consume(limit: 1, timeout: 20.0); } finally { - \proc_close($process); - @\unlink($publisher); + $subscriber->disconnect(); + } + + // Test for SUCCESS: the campaign reached the live subscriber through the broker. + $this->assertCount(1, $received, 'subscriber did not receive the campaign'); + $this->assertSame($topicId, $received[0]['topic']); + + $payload = \json_decode($received[0]['payload'], true); + $this->assertEquals('Match update', $payload['notification']['title']); + $this->assertEquals('India needs 12 off 6', $payload['notification']['body']); + $this->assertEquals(['matchId' => '42'], $payload['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 + * is offline two campaigns are published. On reconnect the broker replays the missed + * messages from the ledger, in order, and PUBACK advances the cursor. + */ + public function testSessionReplaysOfflineMessages(): 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-replay'); + + $clientId = 'e2e-replay-' . $userId; + + // 1) Persistent session seeds its cursor at the current tail; a new topic does not + // replay, so it receives nothing. + $seed = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $seed->connect($projectId, $jwt, $clientId, cleanStart: false)); + $seed->subscribe([$topicId]); + $this->assertCount(0, $seed->consume(limit: 1, timeout: 2.0)); + $seed->disconnect(); + + // 2) Two campaigns are published while that subscriber is offline. + $bodies = ['first offline message', 'second offline message']; + foreach ($bodies as $index => $body) { + $this->publishCampaign($server, $topicId, 'Update ' . $index, $body, ['n' => (string) $index]); + } + + // 3) The same persistent session reconnects and the broker replays both, in order. + $resume = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $resume->connect($projectId, $jwt, $clientId, cleanStart: false)); + $resume->subscribe([$topicId]); + $received = $resume->consume(limit: 2, timeout: 10.0); + $resume->disconnect(); + + // Test for SUCCESS: both offline messages replayed, in sequence order. + $this->assertCount(2, $received, 'offline messages were not replayed'); + foreach ($received as $message) { + $this->assertSame($topicId, $message['topic']); + $this->assertTrue($message['dup'], 'replayed messages carry the DUP flag'); + } + $replayedBodies = \array_map( + fn (array $message): string => \json_decode($message['payload'], true)['notification']['body'], + $received, + ); + $this->assertSame($bodies, $replayedBodies); + + // 4) The PUBACKs advanced the cursor past the earlier message, so a third connect + // never re-delivers it. (Acks run in per-packet coroutines, so under QoS 1 the tail + // may be re-delivered; the cursor never rewinds below the first ack.) + \usleep(1000000); + $again = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $again->connect($projectId, $jwt, $clientId, cleanStart: false)); + $again->subscribe([$topicId]); + $leftover = $again->consume(limit: 2, timeout: 3.0); + $again->disconnect(); + + $leftoverBodies = \array_map( + fn (array $message): string => \json_decode($message['payload'], true)['notification']['body'], + $leftover, + ); + $this->assertNotContains($bodies[0], $leftoverBodies, 'an already-acked message was re-delivered'); + } + + /** + * Replay is bounded by the broker's max depth: when more messages accumulate offline + * than the cap, only the most recent $maxDepth are replayed (the older ones are + * dropped and the cursor jumps to the tail), and a later reconnect replays nothing. + */ + public function testReplayIsBoundedByMaxDepth(): void + { + // Mirrors the handler's cap (Subscribe.php $maxDepth). + $maxDepth = 5; + $overflow = $maxDepth + 2; + + $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-depth'); + $clientId = 'e2e-depth-' . $userId; + + // Seed the persistent session at the current tail, then go offline. + $seed = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $seed->connect($projectId, $jwt, $clientId, cleanStart: false)); + $seed->subscribe([$topicId]); + $this->assertCount(0, $seed->consume(limit: 1, timeout: 2.0)); + $seed->disconnect(); + + // Publish more than the cap while offline. + $bodies = []; + for ($i = 0; $i < $overflow; $i++) { + $body = 'offline message ' . $i; + $bodies[] = $body; + $this->publishCampaign($server, $topicId, 'Update ' . $i, $body, ['n' => (string) $i]); + } + + // Reconnect: only the last $maxDepth replay, in order. + $resume = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $resume->connect($projectId, $jwt, $clientId, cleanStart: false)); + $resume->subscribe([$topicId]); + $received = $resume->consume(limit: $overflow, timeout: 10.0); + $resume->disconnect(); + + $this->assertCount($maxDepth, $received, 'replay was not capped at max depth'); + $replayedBodies = \array_map( + fn (array $message): string => \json_decode($message['payload'], true)['notification']['body'], + $received, + ); + $this->assertSame(\array_slice($bodies, -$maxDepth), $replayedBodies); + + // The dropped (capped-out) messages are gone for good: a later reconnect never + // re-delivers them. (Acks are processed in per-packet coroutines, so under QoS 1 a + // tail message may be re-delivered; the guarantee we assert is that the cursor never + // rewinds below the replayed window, so the dropped set is never seen again.) + \usleep(1000000); + $again = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $again->connect($projectId, $jwt, $clientId, cleanStart: false)); + $again->subscribe([$topicId]); + $leftover = $again->consume(limit: $overflow, timeout: 3.0); + $again->disconnect(); + + $leftoverBodies = \array_map( + fn (array $message): string => \json_decode($message['payload'], true)['notification']['body'], + $leftover, + ); + foreach (\array_slice($bodies, 0, $overflow - $maxDepth) as $droppedBody) { + $this->assertNotContains($droppedBody, $leftoverBodies, 'a capped-out message was re-delivered'); } } + + /** + * A clean-start reconnect discards the persisted session: the cursor is purged and the + * client re-seeds at the current tail, so an offline backlog is NOT replayed. + */ + public function testCleanStartDiscardsSession(): 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-clean'); + $clientId = 'e2e-clean-' . $userId; + + // Establish a persistent session, then go offline. + $seed = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $seed->connect($projectId, $jwt, $clientId, cleanStart: false)); + $seed->subscribe([$topicId]); + $this->assertCount(0, $seed->consume(limit: 1, timeout: 2.0)); + $seed->disconnect(); + + // A message accumulates while offline. + $this->publishCampaign($server, $topicId, 'Update', 'while offline', ['n' => '0']); + + // Reconnect with cleanStart = true: the session is discarded, so nothing replays. + $fresh = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $fresh->connect($projectId, $jwt, $clientId, cleanStart: true)); + $fresh->subscribe([$topicId]); + $this->assertCount(0, $fresh->consume(limit: 1, timeout: 3.0), 'clean-start session should not replay a backlog'); + $fresh->disconnect(); + } } diff --git a/tests/e2e/Services/Messaging/MqttSubscriber.php b/tests/e2e/Services/Messaging/MqttSubscriber.php new file mode 100644 index 0000000000..b4584f0c30 --- /dev/null +++ b/tests/e2e/Services/Messaging/MqttSubscriber.php @@ -0,0 +1,212 @@ +host}:{$this->port}", $errno, $errstr, $this->connectTimeout); + if ($socket === false) { + throw new \RuntimeException("mqtt connect failed: {$errstr} ({$errno})"); + } + $this->socket = $socket; + + $properties = new Properties(); + $properties->add(new Property(Property::AUTHENTICATION_METHOD, $authMethod)); + $properties->add(new Property(Property::AUTHENTICATION_DATA, $credential)); + $properties->add(new Property(Property::USER, ['projectId' => $projectId])); + + $this->write(V5::connect($clientId, 60, $cleanStart, $properties)); + + $packet = $this->readPacket(microtime(true) + $this->connectTimeout); + if ($packet === null || $packet->type !== Packet::CONNACK) { + throw new \RuntimeException('mqtt: no CONNACK received'); + } + + // CONNACK body: [acknowledge flags][reason code][properties]. + return \ord($packet->body[1] ?? "\x80"); + } + + /** + * SUBSCRIBE to the given topic filters at QoS 1; returns once the SUBACK arrives. + * + * @param string[] $topics + */ + public function subscribe(array $topics, float $timeout = 5.0): void + { + $this->write(V5::subscribe($this->nextPacketId(), $topics, Packet::QOS_1)); + + $deadline = microtime(true) + $timeout; + while (true) { + $packet = $this->readPacket($deadline); + if ($packet === null) { + throw new \RuntimeException('mqtt: no SUBACK received'); + } + if ($packet->type === Packet::SUBACK) { + return; + } + // Ignore any early PUBLISH replay queued before the SUBACK; consume() reads those. + } + } + + /** + * Consume up to $limit QoS 1 PUBLISH messages within $timeout seconds, PUBACKing each. + * + * @return array + */ + public function consume(int $limit, float $timeout): array + { + $deadline = microtime(true) + $timeout; + $received = []; + + while (\count($received) < $limit) { + $packet = $this->readPacket($deadline); + if ($packet === null) { + break; // timeout or disconnect + } + if ($packet->type !== Packet::PUBLISH) { + continue; + } + + $body = $packet->body; + [$topic, $offset] = Packet::readString($body, 0); + + $packetIdBytes = ''; + if ($packet->qos() > 0) { + $packetIdBytes = substr($body, $offset, 2); + $offset += 2; + } + $offset = Properties::skip($body, $offset); + $payload = substr($body, $offset); + + $received[] = ['topic' => $topic, 'payload' => $payload, 'dup' => $packet->dup()]; + + if ($packet->qos() === 1 && $packetIdBytes !== '') { + $this->write(V5::puback($packetIdBytes)); + } + } + + return $received; + } + + public function disconnect(): void + { + if (!\is_resource($this->socket)) { + return; + } + @fwrite($this->socket, V5::disconnect(0)); // 0x00 = normal disconnection + @fclose($this->socket); + $this->socket = null; + } + + private function write(string $packet): void + { + if (!\is_resource($this->socket)) { + throw new \RuntimeException('mqtt: socket is not connected'); + } + @fwrite($this->socket, $packet); + } + + /** Read one whole MQTT packet (fixed header + remaining length + body), or null on timeout/EOF. */ + private function readPacket(float $deadline): ?Packet + { + $header = $this->readBytes(1, $deadline); + if ($header === null) { + return null; + } + + // Remaining Length is a 1-4 byte variable-length integer. + $lengthBytes = ''; + $multiplier = 1; + $length = 0; + do { + $next = $this->readBytes(1, $deadline); + if ($next === null) { + return null; + } + $lengthBytes .= $next; + $byte = \ord($next); + $length += ($byte & 0x7F) * $multiplier; + $multiplier *= 128; + } while (($byte & 0x80) !== 0 && \strlen($lengthBytes) < 4); + + $body = $length > 0 ? $this->readBytes($length, $deadline) : ''; + if ($body === null) { + return null; + } + + return Packet::parse($header . $lengthBytes . $body); + } + + /** Read exactly $n bytes before $deadline, or null on timeout/EOF. */ + private function readBytes(int $n, float $deadline): ?string + { + $buffer = ''; + while (\strlen($buffer) < $n) { + $remaining = $deadline - microtime(true); + if ($remaining <= 0) { + return null; + } + + $read = [$this->socket]; + $write = null; + $except = null; + $seconds = (int) $remaining; + $ready = @stream_select($read, $write, $except, $seconds, (int) (($remaining - $seconds) * 1_000_000)); + if ($ready === false) { + return null; + } + if ($ready === 0) { + continue; // nothing readable yet; re-check the deadline + } + + $chunk = @fread($this->socket, $n - \strlen($buffer)); + if ($chunk === false || ($chunk === '' && feof($this->socket))) { + return null; + } + $buffer .= $chunk; + } + + return $buffer; + } + + private function nextPacketId(): int + { + $this->packetId = ($this->packetId % 65535) + 1; + + return $this->packetId; + } +} From ad9d747aa4ef4cc86b4b8e70d7b265168681364a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 12:23:16 +0530 Subject: [PATCH 076/146] chore(mqtt): drop the dev vendor bind-mount from the broker service --- docker-compose.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index b0745f0270..2850033453 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -382,8 +382,6 @@ services: - appwrite ports: - 1883:1883 - volumes: - - ./vendor:/usr/src/code/vendor environment: - _APP_ENV - _APP_WORKER_PER_CORE From 7e882b438fd209621f0146ebb57a91c602eaded8 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:06:10 +0530 Subject: [PATCH 077/146] fix(mqtt): carry the durable sequence through the fan-out envelope The consume loop read sequence off the base64 payload string (always 0), so live QoS 1 deliveries tracked sequence 0 and PUBACK never advanced the cursor. Publish it as a top-level envelope field and read it there. --- app/mqtt.php | 2 +- src/Appwrite/Messaging/Adapter/Mqtt.php | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/app/mqtt.php b/app/mqtt.php index cc009b2e7c..2c98c40d42 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -323,7 +323,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): $projectId = (string) ($event['project'] ?? ''); $topic = (string) ($event['topic'] ?? ''); $qos = (int) ($event['qos'] ?? 0); - $sequence = (int) ($event['payload']['sequence'] ?? 0); + $sequence = (int) ($event['sequence'] ?? 0); $message = base64_decode((string) ($event['payload'] ?? '')); // The broker is the sender on this hop (fan-out to subscribers), so the diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index f78c504f9d..ef69d14f6a 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -127,6 +127,7 @@ class Mqtt extends MessagingAdapter { $message = $options['payload'] ?? ''; $qos = $options['qos'] ?? 0; + $sequence = (int) ($options['sequence'] ?? 0); foreach ($channels as $topic) { $this->metrics->messagesPublished->add(1, ['qos' => $qos]); @@ -134,6 +135,7 @@ class Mqtt extends MessagingAdapter 'project' => $projectId, 'topic' => $topic, 'qos' => $qos, + 'sequence' => $sequence, 'payload' => base64_encode($message), ])); } From 6f86a77465026d0bde686e865f8878c72ac573aa Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:06:10 +0530 Subject: [PATCH 078/146] fix(messaging): return the ledger sequence and make persist idempotent persist() returns the sequence so the fan-out envelope carries it, and dedups on (messageId, topic): a retry after a transient publish failure reuses the existing row instead of double-incrementing the counter and inserting a duplicate. --- .../Messaging/Adapter/Push/Appwrite.php | 26 ++++++++++++++++--- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index 3729cc51d0..d3a53d8260 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -6,6 +6,7 @@ use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Helpers\ID; +use Utopia\Database\Query; use Utopia\Messaging\Adapter\Push as PushAdapter; use Utopia\Messaging\Messages\Push as PushMessage; use Utopia\Messaging\Priority; @@ -57,14 +58,14 @@ class Appwrite extends PushAdapter foreach ($message->getTo() as $topic) { try { - $this->persist($topic, $payload); + $sequence = $this->persist($topic, $payload); $this->broker->send( $this->projectId, [], [], [$topic], [], - ['payload' => $payload, 'qos' => $this->qos], + ['payload' => $payload, 'qos' => $this->qos, 'sequence' => $sequence], ); $response->incrementDeliveredTo(); @@ -77,11 +78,26 @@ class Appwrite extends PushAdapter return $response->toArray(); } - private function persist(string $topic, string $payload): void + /** + * Append the notification to the ledger and return its per-topic sequence. Idempotent + * on (messageId, topic): a retry after a transient publish failure reuses the existing + * row and sequence instead of incrementing the topic counter or inserting a duplicate. + */ + private function persist(string $topic, string $payload): int { $authorization = $this->dbForProject->getAuthorization(); - $sequence = $authorization->skip( + $existing = $authorization->skip( + fn () => $this->dbForProject->findOne('appwrite_push_ledger', [ + Query::equal('messageId', [$this->messageId]), + Query::equal('topic', [$topic]), + ]) + ); + if (!$existing->isEmpty()) { + return (int) $existing->getAttribute('sequence'); + } + + $sequence = (int) $authorization->skip( fn () => $this->dbForProject->increaseDocumentAttribute('topics', $topic, 'sequence', 1) )->getAttribute('sequence'); @@ -95,6 +111,8 @@ class Appwrite extends PushAdapter 'sequence' => $sequence, ])) ); + + return $sequence; } /** From cd7f85a59bd9d38f5db9e7a67c8315f3fa74c949 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:06:10 +0530 Subject: [PATCH 079/146] fix(mqtt): advance the cursor to the highest contiguous ack A non-contiguous PUBACK (acking 7 while 6 is pending) must not skip the gap. acknowledge() derives the contiguous boundary from the in-flight set and the cursor advances to that, so an unacked message is replayed on reconnect, never lost. --- src/Utopia/Mqtt/Connection.php | 31 +++++++++++++++++++++++------ src/Utopia/Mqtt/Handlers/Puback.php | 9 ++++++--- 2 files changed, 31 insertions(+), 9 deletions(-) diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index 08480db25c..b3a8a26b38 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -35,7 +35,9 @@ class Connection /** * Outbound QoS 1 deliveries awaiting a PUBACK, keyed by packet id. Each entry * keeps the topic and the durable sequence delivered, so the matching PUBACK - * can advance that topic's cursor. Emptied as acks arrive. + * can advance that topic's cursor. Emptied as acks arrive; the remaining entries + * are exactly this session's unacked gaps, used to advance the cursor only to the + * highest *contiguous* ack (Redis holds only the committed cursor, not the gaps). * * @var array */ @@ -61,18 +63,35 @@ class Connection } /** - * Resolve a PUBACK to the delivery it acknowledges, removing it from the - * in-flight set. Returns the topic and sequence, or null for an unknown or - * duplicate ack. + * Resolve a PUBACK to the delivery it acknowledges, removing it from the in-flight + * set. Returns the topic, the acked sequence, and `cursor`: the highest sequence + * safe to persist — one below the lowest sequence still in flight for the topic, or + * this ack's sequence once nothing is pending. Advancing to `cursor` (not `sequence`) + * keeps a non-contiguous ack from skipping an earlier unacked message; the worst case + * is a harmless tail re-delivery on reconnect, never a lost message. Returns null for + * an unknown or duplicate ack. * - * @return array{topic: string, sequence: int}|null + * @return array{topic: string, sequence: int, cursor: int}|null */ public function acknowledge(int $packetId): ?array { $delivery = $this->inflight[$packetId] ?? null; unset($this->inflight[$packetId]); + if ($delivery === null) { + return null; + } - return $delivery; + $topic = $delivery['topic']; + $pending = []; + foreach ($this->inflight as $entry) { + if ($entry['topic'] === $topic) { + $pending[] = $entry['sequence']; + } + } + + $cursor = $pending === [] ? $delivery['sequence'] : (min($pending) - 1); + + return ['topic' => $topic, 'sequence' => $delivery['sequence'], 'cursor' => $cursor]; } public function setClientId(string $clientId): void diff --git a/src/Utopia/Mqtt/Handlers/Puback.php b/src/Utopia/Mqtt/Handlers/Puback.php index 7fe9975c0b..1f2bd897ac 100644 --- a/src/Utopia/Mqtt/Handlers/Puback.php +++ b/src/Utopia/Mqtt/Handlers/Puback.php @@ -56,14 +56,17 @@ class Puback extends Action Span::add('mqtt.sequence', $delivery['sequence']); $mqtt->metrics->messagesAcked->add(1); + // Advance to the contiguous boundary from acknowledge(), never the acked sequence + // itself: a non-contiguous ack must not skip an earlier unacked message. The + // monotonic guard covers concurrent per-packet PUBACK coroutines. $cache = getCache(); $cursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); $topic = $delivery['topic']; - $sequence = (int) $delivery['sequence']; + $cursor = (int) $delivery['cursor']; $current = $cache->loadMany($cursorKey, 3600, [$topic]); - if ($sequence > (int) ($current[$topic]['sequence'] ?? -1)) { - $cache->saveMany($cursorKey, [$topic => ['sequence' => $sequence]], 3600); + if ($cursor > (int) ($current[$topic]['sequence'] ?? -1)) { + $cache->saveMany($cursorKey, [$topic => ['sequence' => $cursor]], 3600); } } } From 12e25e995d52b591b028c1d96579c96f2960323c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:06:10 +0530 Subject: [PATCH 080/146] test(messaging): non-contiguous ack redelivery MqttSubscriber can skip acking a chosen message; add an e2e that leaves the middle of a replayed batch unacked and asserts it is re-delivered on reconnect. --- .../Messaging/MessagingMqttServerTest.php | 53 +++++++++++++++++++ .../e2e/Services/Messaging/MqttSubscriber.php | 8 ++- 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index a9dc99b929..621dcce86e 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -271,6 +271,59 @@ final class MessagingMqttServerTest extends Scope $this->assertNotContains($bodies[0], $leftoverBodies, 'an already-acked message was re-delivered'); } + /** + * Non-contiguous acks must not drop the gap. A persistent session replays three + * messages and acks the first and third but not the middle; the cursor advances only + * to the highest contiguous ack, so on reconnect the broker re-delivers the unacked + * middle message rather than skipping past it. + */ + public function testNonContiguousAckDoesNotDropMessages(): 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-gap'); + $clientId = 'e2e-gap-' . $userId; + + // Seed the persistent session, then publish three messages while offline. + $seed = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $seed->connect($projectId, $jwt, $clientId, cleanStart: false)); + $seed->subscribe([$topicId]); + $this->assertCount(0, $seed->consume(limit: 1, timeout: 2.0)); + $seed->disconnect(); + + foreach (['first', 'second', 'third'] as $index => $body) { + $this->publishCampaign($server, $topicId, 'Update ' . $index, $body, ['n' => (string) $index]); + } + + // Replay all three, but ack only the first and third — leave the middle unacked. + $resume = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $resume->connect($projectId, $jwt, $clientId, cleanStart: false)); + $resume->subscribe([$topicId]); + $received = $resume->consume(limit: 3, timeout: 10.0, shouldAck: fn (int $i): bool => $i !== 1); + $resume->disconnect(); + $this->assertCount(3, $received); + + // On reconnect the unacked middle message is re-delivered, not skipped. + \usleep(1000000); + $again = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $again->connect($projectId, $jwt, $clientId, cleanStart: false)); + $again->subscribe([$topicId]); + $redelivered = $again->consume(limit: 3, timeout: 5.0); + $again->disconnect(); + + $redeliveredBodies = \array_map( + fn (array $message): string => \json_decode($message['payload'], true)['notification']['body'], + $redelivered, + ); + $this->assertContains('second', $redeliveredBodies, 'the unacked middle message was dropped'); + } + /** * Replay is bounded by the broker's max depth: when more messages accumulate offline * than the cap, only the most recent $maxDepth are replayed (the older ones are diff --git a/tests/e2e/Services/Messaging/MqttSubscriber.php b/tests/e2e/Services/Messaging/MqttSubscriber.php index b4584f0c30..2817956711 100644 --- a/tests/e2e/Services/Messaging/MqttSubscriber.php +++ b/tests/e2e/Services/Messaging/MqttSubscriber.php @@ -84,10 +84,13 @@ final class MqttSubscriber /** * Consume up to $limit QoS 1 PUBLISH messages within $timeout seconds, PUBACKing each. + * $shouldAck, given the 0-based index of a received message, may return false to skip + * its PUBACK — used to simulate non-contiguous acknowledgement. * + * @param (callable(int): bool)|null $shouldAck * @return array */ - public function consume(int $limit, float $timeout): array + public function consume(int $limit, float $timeout, ?callable $shouldAck = null): array { $deadline = microtime(true) + $timeout; $received = []; @@ -114,7 +117,8 @@ final class MqttSubscriber $received[] = ['topic' => $topic, 'payload' => $payload, 'dup' => $packet->dup()]; - if ($packet->qos() === 1 && $packetIdBytes !== '') { + $ack = $shouldAck === null || $shouldAck(\count($received) - 1); + if ($ack && $packet->qos() === 1 && $packetIdBytes !== '') { $this->write(V5::puback($packetIdBytes)); } } From b42090c60aab7b7201c8ec97e4c8feee99b1f6a7 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:10:04 +0530 Subject: [PATCH 081/146] fix(mqtt): record CONNECT span attributes after dispatch The identity, project and clean-start flag are populated by the CONNECT handler during dispatch, so reading them before it recorded empty/default telemetry. --- app/mqtt.php | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 2c98c40d42..02748a71c4 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -389,9 +389,6 @@ $server->onReceive(function (int $fd, string $data) use ( $span = Span::init('mqtt.' . $packet->name()); $span->set('mqtt.fd', $fd); - $span->set('project.id', $connection->projectId); - $span->set('user.id', $connection->identity['userId'] ?? ''); - $span->set('mqtt.clean_start', $connection->cleanStart); $span->set('mqtt.is_broker', false); // an inbound packet from a client $reply = function (string $packet = '', bool $close = false) use ($server, $fd): void { @@ -413,8 +410,16 @@ $server->onReceive(function (int $fd, string $data) use ( try { $dispatcher->dispatch($packetContainer, $packet->type); + + // The identity, project and clean-start flag are populated by the CONNECT + // handler during dispatch, so record them afterwards rather than as defaults. + $span->set('project.id', $connection->projectId); + $span->set('user.id', $connection->identity['userId'] ?? ''); + $span->set('mqtt.clean_start', $connection->cleanStart); $span->finish(); } catch (\Throwable $error) { + $span->set('project.id', $connection->projectId); + $span->set('user.id', $connection->identity['userId'] ?? ''); $span->finish(error: $error); throw $error; } From db80596c73c271f8a0f41d713cc895d3992c8834 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:10:04 +0530 Subject: [PATCH 082/146] feat(messaging): unique index on the push ledger (messageId, topic) Enforces one ledger row per message/topic so a concurrent retry can't duplicate a notification or double-increment the sequence. --- app/config/collections/common.php | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index bf1cd82c56..c0c530deb8 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2290,6 +2290,13 @@ return [ 'lengths' => [], 'orders' => [Database::ORDER_ASC], ], + [ + '$id' => ID::custom('_key_message_topic'), + 'type' => Database::INDEX_UNIQUE, + 'attributes' => ['messageId', 'topic'], + 'lengths' => [], + 'orders' => [Database::ORDER_ASC, Database::ORDER_ASC], + ], ], ], From af6e97e062cc9c4e41236ebd81a553eb40c07f6c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:10:04 +0530 Subject: [PATCH 083/146] test(messaging): distinct message ids per publish + republish idempotency --- .../Messaging/Adapter/Push/AppwriteTest.php | 20 ++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php index eea40f6d1c..edd0997eb0 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php @@ -214,10 +214,10 @@ final class AppwriteTest extends TestCase { $this->seedTopic('topic-1', 0); $broker = new FakeBroker(); - $adapter = $this->adapter($broker); - $adapter->send(new Push(to: ['topic-1'], title: 'first')); - $adapter->send(new Push(to: ['topic-1'], title: 'second')); + // Two distinct campaigns (distinct message ids) to the same topic. + $this->adapter($broker, messageId: 'msg-1')->send(new Push(to: ['topic-1'], title: 'first')); + $this->adapter($broker, messageId: 'msg-2')->send(new Push(to: ['topic-1'], title: 'second')); $sequences = \array_map( static fn (Document $row): int => $row->getAttribute('sequence'), @@ -230,6 +230,20 @@ final class AppwriteTest extends TestCase $this->assertSame(2, $topic->getAttribute('sequence')); } + public function testRepublishIsIdempotent(): void + { + // Re-sending the same campaign (a retry after a transient failure) must not + // advance the sequence or add a second ledger row for the (message, topic) pair. + $this->seedTopic('topic-1', 0); + $broker = new FakeBroker(); + + $this->adapter($broker, messageId: 'msg-1')->send(new Push(to: ['topic-1'], title: 'once')); + $this->adapter($broker, messageId: 'msg-1')->send(new Push(to: ['topic-1'], title: 'once')); + + $this->assertCount(1, $this->ledger()); + $this->assertSame(1, $this->topic('topic-1')->getAttribute('sequence')); + } + public function testEachTopicGetsItsOwnSequence(): void { // Two topics at different tails: each advances independently. From 206df3533bdfd9f0b2bce04364733c0f1b8a2401 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:12:43 +0530 Subject: [PATCH 084/146] test(mqtt): assert acknowledge's contiguous-cursor outcome, not the raw record --- tests/unit/Utopia/Mqtt/ConnectionTest.php | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/tests/unit/Utopia/Mqtt/ConnectionTest.php b/tests/unit/Utopia/Mqtt/ConnectionTest.php index 41dc0c4b50..dc03d2560b 100644 --- a/tests/unit/Utopia/Mqtt/ConnectionTest.php +++ b/tests/unit/Utopia/Mqtt/ConnectionTest.php @@ -56,7 +56,25 @@ final class ConnectionTest extends TestCase $connection = new Connection(1); $connection->track(7, 'appwrite/push/user-1', 42); - $this->assertSame(['topic' => 'appwrite/push/user-1', 'sequence' => 42], $connection->acknowledge(7)); + $ack = $connection->acknowledge(7); + $this->assertSame('appwrite/push/user-1', $ack['topic']); + $this->assertSame(42, $ack['sequence']); + // Nothing else in flight, so the cursor advances to the acked sequence. + $this->assertSame(42, $ack['cursor']); + } + + public function testAcknowledgeAdvancesCursorOnlyToTheContiguousBoundary(): void + { + // Deliver 5, 6, 7; ack 5 and 7 while 6 is still pending. The cursor must stop + // below the gap (5), never jumping to the acked 7 and skipping the unacked 6. + $connection = new Connection(1); + $connection->track(1, 'topic', 5); + $connection->track(2, 'topic', 6); + $connection->track(3, 'topic', 7); + + $this->assertSame(5, $connection->acknowledge(1)['cursor']); // 6,7 pending -> boundary 5 + $this->assertSame(5, $connection->acknowledge(3)['cursor']); // 6 pending -> boundary 5 + $this->assertSame(6, $connection->acknowledge(2)['cursor']); // none pending -> this ack (6) } public function testAcknowledgeIsIdempotentForAnUnknownOrRepeatedAck(): void From 38b3e19beba38f31cabe6a586cae954f556879ca Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:26:50 +0530 Subject: [PATCH 085/146] fix(messaging): persist push ledger increment and insert atomically Wrap the topic sequence increment and ledger insert in withTransaction so a crash between them cannot leave a gap in the per-topic sequence. --- .../Messaging/Adapter/Push/Appwrite.php | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index d3a53d8260..4e7dff068b 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -97,22 +97,24 @@ class Appwrite extends PushAdapter return (int) $existing->getAttribute('sequence'); } - $sequence = (int) $authorization->skip( - fn () => $this->dbForProject->increaseDocumentAttribute('topics', $topic, 'sequence', 1) - )->getAttribute('sequence'); + return (int) $authorization->skip( + fn () => $this->dbForProject->withTransaction(function () use ($topic, $payload): int { + $sequence = (int) $this->dbForProject + ->increaseDocumentAttribute('topics', $topic, 'sequence', 1) + ->getAttribute('sequence'); - $authorization->skip( - fn () => $this->dbForProject->createDocument('appwrite_push_ledger', new Document([ - '$id' => ID::unique(), - 'topic' => $topic, - 'data' => $payload, - 'messageId' => $this->messageId, - 'messageInternalId' => $this->messageInternalId, - 'sequence' => $sequence, - ])) + $this->dbForProject->createDocument('appwrite_push_ledger', new Document([ + '$id' => ID::unique(), + 'topic' => $topic, + 'data' => $payload, + 'messageId' => $this->messageId, + 'messageInternalId' => $this->messageInternalId, + 'sequence' => $sequence, + ])); + + return $sequence; + }) ); - - return $sequence; } /** From b5431990a13e38bfaeafacac49575ebe3ccc1b5f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:26:57 +0530 Subject: [PATCH 086/146] fix(messaging): correct Mqtt adapter phpstan docblocks Add sequence to the send() options shape and match getConnection()'s subs return type to the flat topic => qos map the store actually returns. --- src/Appwrite/Messaging/Adapter/Mqtt.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index ef69d14f6a..904cdf1f55 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -121,7 +121,7 @@ class Mqtt extends MessagingAdapter * @param array $events ignored * @param array $channels topics to publish to * @param array $roles ignored - * @param array{payload?: string, qos?: int} $options + * @param array{payload?: string, qos?: int, sequence?: int} $options */ public function send(string $projectId, array $payload, array $events, array $channels, array $roles, array $options = []): void { @@ -167,7 +167,7 @@ class Mqtt extends MessagingAdapter * or null when the fd holds none. This is the store's copy (the projectId/userId * captured at subscribe time), not the live Connection object from open(). * - * @return array{projectId: string, userId: string, subs: array}|null + * @return array{projectId: string, userId: string, subs: array}|null */ public function getConnection(int $fd): ?array { From 6c9a8fc1da07aa7d5a9bd1038fda3862b05ac4f7 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:26:57 +0530 Subject: [PATCH 087/146] docs(mqtt): clarify cursor-advance comments with a worked example Explain in the acknowledge() docblock and PUBACK handler why the cursor stops at the contiguous boundary rather than the acked sequence, with a 5/6/7 example. --- src/Utopia/Mqtt/Connection.php | 7 +++++++ src/Utopia/Mqtt/Handlers/Puback.php | 6 +++--- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index b3a8a26b38..58049348df 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -71,6 +71,13 @@ class Connection * is a harmless tail re-delivery on reconnect, never a lost message. Returns null for * an unknown or duplicate ack. * + * Example — messages 5, 6, 7 were delivered and the client acks 5, then 7 (6 is still + * pending): + * ack 5 -> in flight {6, 7}, cursor = 5 (lowest pending is 6, so stop at 5) + * ack 7 -> in flight {6}, cursor = 5 (6 is still the gap, don't jump to 7) + * ack 6 -> in flight {}, cursor = 6 (nothing pending; 7 may be re-sent later) + * The cursor never moves past the unacked 6, so on reconnect 6 is replayed, not lost. + * * @return array{topic: string, sequence: int, cursor: int}|null */ public function acknowledge(int $packetId): ?array diff --git a/src/Utopia/Mqtt/Handlers/Puback.php b/src/Utopia/Mqtt/Handlers/Puback.php index 1f2bd897ac..b6c33f2d06 100644 --- a/src/Utopia/Mqtt/Handlers/Puback.php +++ b/src/Utopia/Mqtt/Handlers/Puback.php @@ -56,9 +56,9 @@ class Puback extends Action Span::add('mqtt.sequence', $delivery['sequence']); $mqtt->metrics->messagesAcked->add(1); - // Advance to the contiguous boundary from acknowledge(), never the acked sequence - // itself: a non-contiguous ack must not skip an earlier unacked message. The - // monotonic guard covers concurrent per-packet PUBACK coroutines. + // Save how far the client has caught up (the "cursor" from acknowledge), not the + // sequence it just acked — so an out-of-order ack can't skip a still-unacked + // message. Only ever move the cursor forward, so two acks at once can't rewind it. $cache = getCache(); $cursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); $topic = $delivery['topic']; From 5adb6585bd6a64435c098dc8b7d2f396ed49f588 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:34:05 +0530 Subject: [PATCH 088/146] fix(messaging): make push ledger persist idempotent under concurrent retries Catch the (messageId, topic) unique-index Duplicate so a losing concurrent attempt resolves to the winner's sequence instead of surfacing a failure or opening a sequence gap. Extract findLedger for the shared dedup lookup. --- .../Messaging/Adapter/Push/Appwrite.php | 62 ++++++++++++------- 1 file changed, 41 insertions(+), 21 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index 4e7dff068b..7cf091b412 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -5,8 +5,10 @@ namespace Appwrite\Messaging\Adapter\Push; use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Database\Database; use Utopia\Database\Document; +use Utopia\Database\Exception\Duplicate; use Utopia\Database\Helpers\ID; use Utopia\Database\Query; +use Utopia\Database\Validator\Authorization; use Utopia\Messaging\Adapter\Push as PushAdapter; use Utopia\Messaging\Messages\Push as PushMessage; use Utopia\Messaging\Priority; @@ -82,38 +84,56 @@ class Appwrite extends PushAdapter * Append the notification to the ledger and return its per-topic sequence. Idempotent * on (messageId, topic): a retry after a transient publish failure reuses the existing * row and sequence instead of incrementing the topic counter or inserting a duplicate. + * + * The increment and insert run in one transaction so a failed insert rolls the + * increment back — the topic sequence never advances without a matching ledger row. + * The unique index on (messageId, topic) also serialises two concurrent attempts: + * the loser's insert throws Duplicate, its increment rolls back, and it resolves to + * the winner's sequence instead of opening a gap. */ private function persist(string $topic, string $payload): int { $authorization = $this->dbForProject->getAuthorization(); - $existing = $authorization->skip( - fn () => $this->dbForProject->findOne('appwrite_push_ledger', [ - Query::equal('messageId', [$this->messageId]), - Query::equal('topic', [$topic]), - ]) - ); + $existing = $this->findLedger($authorization, $topic); if (!$existing->isEmpty()) { return (int) $existing->getAttribute('sequence'); } - return (int) $authorization->skip( - fn () => $this->dbForProject->withTransaction(function () use ($topic, $payload): int { - $sequence = (int) $this->dbForProject - ->increaseDocumentAttribute('topics', $topic, 'sequence', 1) - ->getAttribute('sequence'); + try { + return (int) $authorization->skip( + fn () => $this->dbForProject->withTransaction(function () use ($topic, $payload): int { + $sequence = (int) $this->dbForProject + ->increaseDocumentAttribute('topics', $topic, 'sequence', 1) + ->getAttribute('sequence'); - $this->dbForProject->createDocument('appwrite_push_ledger', new Document([ - '$id' => ID::unique(), - 'topic' => $topic, - 'data' => $payload, - 'messageId' => $this->messageId, - 'messageInternalId' => $this->messageInternalId, - 'sequence' => $sequence, - ])); + $this->dbForProject->createDocument('appwrite_push_ledger', new Document([ + '$id' => ID::unique(), + 'topic' => $topic, + 'data' => $payload, + 'messageId' => $this->messageId, + 'messageInternalId' => $this->messageInternalId, + 'sequence' => $sequence, + ])); - return $sequence; - }) + return $sequence; + }) + ); + } catch (Duplicate) { + // A concurrent attempt won the (messageId, topic) unique index; its row and + // increment are committed. Return that sequence rather than incrementing again. + return (int) $this->findLedger($authorization, $topic)->getAttribute('sequence'); + } + } + + /** The existing ledger row for this campaign message on a topic, or an empty document. */ + private function findLedger(Authorization $authorization, string $topic): Document + { + return $authorization->skip( + fn () => $this->dbForProject->findOne('appwrite_push_ledger', [ + Query::equal('messageId', [$this->messageId]), + Query::equal('topic', [$topic]), + ]) ); } From 0c464a71628290ae159aea35a8c15821701f2f5f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:34:05 +0530 Subject: [PATCH 089/146] fix(messaging): let explicit null reset topic and provider qos/expiry An omitted param and an explicit null both arrive as null, so key on the request body's presence to restore the documented default (subscriber-chosen QoS, no expiry) instead of silently retaining the old value. --- .../Messaging/Http/Providers/Appwrite/Update.php | 14 ++++++++++---- .../Modules/Messaging/Http/Topics/Update.php | 14 +++++++++++--- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php index d9e9a9e9eb..846ea64678 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Providers/Appwrite/Update.php @@ -7,6 +7,7 @@ use Appwrite\Extend\Exception; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; +use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; use Utopia\Database\Database; use Utopia\Database\Validator\UID; @@ -56,13 +57,14 @@ class Update extends Action ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) ->param('qos', null, new Nullable(new Range(0, 1)), 'Default QoS for topics on this provider (0 or 1). Null lets the subscriber choose.', true) ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Default message retention in seconds for offline delivery. Max 7 days (604800).', true) + ->inject('request') ->inject('queueForEvents') ->inject('dbForProject') ->inject('response') ->callback($this->action(...)); } - public function action(string $providerId, string $name, ?bool $enabled, ?int $qos, ?int $expiry, Event $queueForEvents, Database $dbForProject, Response $response) + public function action(string $providerId, string $name, ?bool $enabled, ?int $qos, ?int $expiry, Request $request, Event $queueForEvents, Database $dbForProject, Response $response) { $provider = $dbForProject->getDocument('providers', $providerId); @@ -82,12 +84,16 @@ class Update extends Action $provider->setAttribute('enabled', $enabled); } - if (!\is_null($qos) || !\is_null($expiry)) { + // qos and expiry are nullable defaults: an explicit null resets them (subscriber + // chooses the QoS, no expiry). An omitted param and an explicit null both arrive as + // null, so key on the request body's presence rather than the value. + $params = $request->getParams(); + if (\array_key_exists('qos', $params) || \array_key_exists('expiry', $params)) { $options = $provider->getAttribute('options', []); - if (!\is_null($qos)) { + if (\array_key_exists('qos', $params)) { $options['qos'] = $qos; } - if (!\is_null($expiry)) { + if (\array_key_exists('expiry', $params)) { $options['expiry'] = $expiry; } $provider->setAttribute('options', $options); diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php index 51d0358c2d..515611c975 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php @@ -7,6 +7,7 @@ use Appwrite\Extend\Exception; use Appwrite\SDK\AuthType; use Appwrite\SDK\Method; use Appwrite\SDK\Response as SDKResponse; +use Appwrite\Utopia\Request; use Appwrite\Utopia\Response; use Utopia\Database\Database; use Utopia\Database\Validator\Roles; @@ -56,13 +57,14 @@ class Update extends Action ->param('subscribe', null, new Nullable(new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE)), 'An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true) ->param('qos', null, new Nullable(new Range(0, 1)), 'QoS for MQTT delivery on this topic (0 or 1). Null lets the subscriber choose.', true) ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Message retention in seconds for offline delivery. Max 7 days (604800).', true) + ->inject('request') ->inject('queueForEvents') ->inject('dbForProject') ->inject('response') ->callback($this->action(...)); } - public function action(string $topicId, ?string $name, ?array $subscribe, ?int $qos, ?int $expiry, Event $queueForEvents, Database $dbForProject, Response $response) + public function action(string $topicId, ?string $name, ?array $subscribe, ?int $qos, ?int $expiry, Request $request, Event $queueForEvents, Database $dbForProject, Response $response) { $topic = $dbForProject->getDocument('topics', $topicId); @@ -78,11 +80,17 @@ class Update extends Action $topic->setAttribute('subscribe', $subscribe); } - if (!\is_null($qos)) { + // qos and expiry are nullable settings: an explicit null resets them to the + // documented default (subscriber-chosen QoS, no expiry). Since an omitted param + // and an explicit null both arrive as null, honour the key's presence in the + // request body rather than the value, so a reset isn't silently ignored. + $params = $request->getParams(); + + if (\array_key_exists('qos', $params)) { $topic->setAttribute('qos', $qos); } - if (!\is_null($expiry)) { + if (\array_key_exists('expiry', $params)) { $topic->setAttribute('expiry', $expiry); } From 87e8b693985f96b34575c8393326b9426abc87d1 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 13:41:14 +0530 Subject: [PATCH 090/146] docs(messaging): add reference descriptions for Appwrite push provider Spec generation reads these per-endpoint markdown files; the create/update Appwrite provider endpoints referenced them but the files were missing, failing the specs CI step. --- docs/references/messaging/create-appwrite-provider.md | 1 + docs/references/messaging/update-appwrite-provider.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/references/messaging/create-appwrite-provider.md create mode 100644 docs/references/messaging/update-appwrite-provider.md diff --git a/docs/references/messaging/create-appwrite-provider.md b/docs/references/messaging/create-appwrite-provider.md new file mode 100644 index 0000000000..c8ece30540 --- /dev/null +++ b/docs/references/messaging/create-appwrite-provider.md @@ -0,0 +1 @@ +Create a new Appwrite push provider. \ No newline at end of file diff --git a/docs/references/messaging/update-appwrite-provider.md b/docs/references/messaging/update-appwrite-provider.md new file mode 100644 index 0000000000..0f065cb830 --- /dev/null +++ b/docs/references/messaging/update-appwrite-provider.md @@ -0,0 +1 @@ +Update an Appwrite push provider by its unique ID. \ No newline at end of file From a9d6fc428b117ce75ec60afe1f98595d81494d76 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 14:23:29 +0530 Subject: [PATCH 091/146] refactor(messaging): rename appwrite_push_ledger to appwritePushLedger for consistency --- app/config/collections/common.php | 4 ++-- src/Appwrite/Messaging/Adapter/Push/Appwrite.php | 4 ++-- src/Utopia/Mqtt/Handlers/Puback.php | 2 +- src/Utopia/Mqtt/Handlers/Subscribe.php | 4 ++-- .../Messaging/Adapter/Push/AppwriteTest.php | 14 +++++++------- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index c0c530deb8..e4d1c1c3c4 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2212,9 +2212,9 @@ return [ ], ], - 'appwrite_push_ledger' => [ + 'appwritePushLedger' => [ '$collection' => ID::custom(DATABASE::METADATA), - '$id' => ID::custom('appwrite_push_ledger'), + '$id' => ID::custom('appwritePushLedger'), 'name' => 'MQTT Messages', 'attributes' => [ [ diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index 7cf091b412..99ad450cd0 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -107,7 +107,7 @@ class Appwrite extends PushAdapter ->increaseDocumentAttribute('topics', $topic, 'sequence', 1) ->getAttribute('sequence'); - $this->dbForProject->createDocument('appwrite_push_ledger', new Document([ + $this->dbForProject->createDocument('appwritePushLedger', new Document([ '$id' => ID::unique(), 'topic' => $topic, 'data' => $payload, @@ -130,7 +130,7 @@ class Appwrite extends PushAdapter private function findLedger(Authorization $authorization, string $topic): Document { return $authorization->skip( - fn () => $this->dbForProject->findOne('appwrite_push_ledger', [ + fn () => $this->dbForProject->findOne('appwritePushLedger', [ Query::equal('messageId', [$this->messageId]), Query::equal('topic', [$topic]), ]) diff --git a/src/Utopia/Mqtt/Handlers/Puback.php b/src/Utopia/Mqtt/Handlers/Puback.php index b6c33f2d06..085c00a37b 100644 --- a/src/Utopia/Mqtt/Handlers/Puback.php +++ b/src/Utopia/Mqtt/Handlers/Puback.php @@ -60,7 +60,7 @@ class Puback extends Action // sequence it just acked — so an out-of-order ack can't skip a still-unacked // message. Only ever move the cursor forward, so two acks at once can't rewind it. $cache = getCache(); - $cursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); + $cursorKey = 'appwrite:push:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); $topic = $delivery['topic']; $cursor = (int) $delivery['cursor']; diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index fea8a19f21..e25cad0fc3 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -93,7 +93,7 @@ class Subscribe extends Action $projectDB = getProjectDB($project); $cache = getCache(); - $cursorKey = 'mqtt:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); + $cursorKey = 'appwrite:push:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); // A clean-start session discards any persisted cursor before resuming. if ($connection->cleanStart) { @@ -131,7 +131,7 @@ class Subscribe extends Action } $start = max($from + 1, $tail - $maxDepth + 1); - $messages = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('appwrite_push_ledger', [ + $messages = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('appwritePushLedger', [ Query::equal('topic', [$topic]), Query::greaterThanEqual('sequence', $start), Query::orderAsc('sequence'), diff --git a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php index edd0997eb0..d8cbbe87bc 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php @@ -95,12 +95,12 @@ final class AppwriteTest extends TestCase // The append-only ledger. `data` is a plain string here (the adapter passes an // already-encoded JSON envelope); the production collection's json filter is a // storage detail, not adapter behaviour. - $this->database->createCollection('appwrite_push_ledger', [], [], $any, false); - $this->database->createAttribute('appwrite_push_ledger', 'topic', Database::VAR_STRING, 255, true); - $this->database->createAttribute('appwrite_push_ledger', 'data', Database::VAR_STRING, 65535, true); - $this->database->createAttribute('appwrite_push_ledger', 'messageId', Database::VAR_STRING, 255, false); - $this->database->createAttribute('appwrite_push_ledger', 'messageInternalId', Database::VAR_STRING, 255, false); - $this->database->createAttribute('appwrite_push_ledger', 'sequence', Database::VAR_INTEGER, 0, true); + $this->database->createCollection('appwritePushLedger', [], [], $any, false); + $this->database->createAttribute('appwritePushLedger', 'topic', Database::VAR_STRING, 255, true); + $this->database->createAttribute('appwritePushLedger', 'data', Database::VAR_STRING, 65535, true); + $this->database->createAttribute('appwritePushLedger', 'messageId', Database::VAR_STRING, 255, false); + $this->database->createAttribute('appwritePushLedger', 'messageInternalId', Database::VAR_STRING, 255, false); + $this->database->createAttribute('appwritePushLedger', 'sequence', Database::VAR_INTEGER, 0, true); } /** Seed a topic row with a starting sequence (the current tail). */ @@ -129,7 +129,7 @@ final class AppwriteTest extends TestCase */ private function ledger(): array { - return $this->database->getAuthorization()->skip(fn () => $this->database->find('appwrite_push_ledger')); + return $this->database->getAuthorization()->skip(fn () => $this->database->find('appwritePushLedger')); } /** The topic counter row, read past authorization. */ From a630bd3a42ed42467dda77e3dac84dc810ca0917 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:04:37 +0530 Subject: [PATCH 092/146] chore(deps): use published utopia-php/cache and messaging releases Drop the inline monorepo type:package repositories for utopia-php/cache and utopia-php/messaging now that the batch-cache work is released; require utopia-php/cache ^5.0. --- composer.json | 55 +---------------------------- composer.lock | 96 ++++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 77 insertions(+), 74 deletions(-) diff --git a/composer.json b/composer.json index 31674ae96a..650005f6dd 100644 --- a/composer.json +++ b/composer.json @@ -40,59 +40,6 @@ "minimum-stability": "dev", "prefer-stable": true, "repositories": [ - { - "type": "package", - "package": { - "name": "utopia-php/messaging", - "version": "2.1.999", - "source": { - "url": "https://github.com/utopia-php/monorepo.git", - "type": "git", - "reference": "appwrite-mqtt-poc" - }, - "autoload": { - "psr-4": { - "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" - } - }, - "require": { - "php": ">=8.5.0", - "ext-curl": "*", - "ext-openssl": "*", - "ext-swoole": "*", - "psr/http-client": "^1.0", - "psr/http-message": "^1.1 || ^2.0", - "utopia-php/client": "^0.4", - "utopia-php/pools": "^2.0", - "utopia-php/smtp": "^0.1", - "utopia-php/telemetry": "^0.4" - } - } - }, - { - "type": "package", - "package": { - "name": "utopia-php/cache", - "version": "dev-bulk-cache-load", - "source": { - "url": "https://github.com/utopia-php/monorepo.git", - "type": "git", - "reference": "c340994cea9841853d7722488bde443ec9d3f629" - }, - "autoload": { - "psr-4": { - "Utopia\\Cache\\": "packages/cache/src/Cache" - } - }, - "require": { - "php": ">=8.4", - "ext-json": "*", - "utopia-php/circuit-breaker": "^0.4", - "utopia-php/pools": "^2.0", - "utopia-php/telemetry": "^0.4" - } - } - }, { "type": "vcs", "url": "https://github.com/utopia-php/auth" @@ -131,7 +78,7 @@ "utopia-php/audit": "^4.0", "utopia-php/auth": "^0.11", "utopia-php/balancer": "0.4.*", - "utopia-php/cache": "dev-bulk-cache-load as 5.0.999", + "utopia-php/cache": "^5.0", "utopia-php/cdn": "^0.0.11", "utopia-php/cli": "^0.24", "utopia-php/compression": "0.1.*", diff --git a/composer.lock b/composer.lock index f8ac26362d..b6bb925325 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "e0de6ceea0738acc2df7824646c70f6b", + "content-hash": "7c0ea679d70fcde2e936cca98fc0fb13", "packages": [ { "name": "adhocore/jwt", @@ -3037,11 +3037,17 @@ }, { "name": "utopia-php/cache", - "version": "dev-bulk-cache-load", + "version": "5.0.3", "source": { "type": "git", - "url": "https://github.com/utopia-php/monorepo.git", - "reference": "c340994cea9841853d7722488bde443ec9d3f629" + "url": "https://github.com/utopia-php/cache.git", + "reference": "f808a39d018e1f325ac553b8de39798cae40c1f9" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/f808a39d018e1f325ac553b8de39798cae40c1f9", + "reference": "f808a39d018e1f325ac553b8de39798cae40c1f9", + "shasum": "" }, "require": { "ext-json": "*", @@ -3050,12 +3056,43 @@ "utopia-php/pools": "^2.0", "utopia-php/telemetry": "^0.4" }, + "require-dev": { + "swoole/ide-helper": "^6.0" + }, + "suggest": { + "ext-memcached": "Required for the Memcached and Hazelcast adapters.", + "ext-redis": "Required for the Redis, RedisCluster and Sharding adapters.", + "ext-swoole": "Required for the multiplexing Redis adapter (>=6.0)." + }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Cache\\": "packages/cache/src/Cache" + "Utopia\\Cache\\": "src/Cache" } - } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Team Appwrite", + "email": "team@appwrite.io" + } + ], + "description": "A simple cache library to manage application cache storing, loading and purging", + "keywords": [ + "cache", + "framework", + "php", + "upf", + "utopia" + ], + "support": { + "issues": "https://github.com/utopia-php/cache/issues", + "source": "https://github.com/utopia-php/cache/tree/5.0.3" + }, + "time": "2026-09-11T08:23:02+00:00" }, { "name": "utopia-php/cdn", @@ -4045,11 +4082,17 @@ }, { "name": "utopia-php/messaging", - "version": "2.1.999", + "version": "2.1.3", "source": { "type": "git", - "url": "https://github.com/utopia-php/monorepo.git", - "reference": "appwrite-mqtt-poc" + "url": "https://github.com/utopia-php/messaging.git", + "reference": "99dfd12d5ba61d4bd677361de714411c13d9a01b" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/utopia-php/messaging/zipball/99dfd12d5ba61d4bd677361de714411c13d9a01b", + "reference": "99dfd12d5ba61d4bd677361de714411c13d9a01b", + "shasum": "" }, "require": { "ext-curl": "*", @@ -4063,12 +4106,33 @@ "utopia-php/smtp": "^0.1", "utopia-php/telemetry": "^0.4" }, + "require-dev": { + "swoole/ide-helper": "^6.0" + }, "type": "library", "autoload": { "psr-4": { - "Utopia\\Messaging\\": "packages/messaging/src/Utopia/Messaging" + "Utopia\\Messaging\\": "src/Utopia/Messaging" } - } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "description": "A simple, light and advanced PHP messaging library", + "keywords": [ + "library", + "messaging", + "php", + "upf", + "utopia", + "utopia-php" + ], + "support": { + "issues": "https://github.com/utopia-php/messaging/issues", + "source": "https://github.com/utopia-php/messaging/tree/2.1.3" + }, + "time": "2026-09-09T11:20:02+00:00" }, { "name": "utopia-php/migration", @@ -8494,17 +8558,9 @@ "time": "2026-07-03T20:44:34+00:00" } ], - "aliases": [ - { - "package": "utopia-php/cache", - "version": "dev-bulk-cache-load", - "alias": "5.0.999", - "alias_normalized": "5.0.999.0" - } - ], + "aliases": [], "minimum-stability": "dev", "stability-flags": { - "utopia-php/cache": 20, "utopia-php/http": 5, "utopia-php/mqtt": 20 }, From 79d6abf9538a1ebae20de406f77623f56a36c74a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:04:37 +0530 Subject: [PATCH 093/146] fix(messaging): lock the topic row on push persist Open the persist transaction by reading the topic row FOR UPDATE and re-check the ledger under the lock, so a concurrent attempt for the same message waits and reuses the committed sequence instead of racing a second increment. Drops the Duplicate catch; the unique index stays as a backstop. --- .../Messaging/Adapter/Push/Appwrite.php | 59 ++++++++++--------- 1 file changed, 31 insertions(+), 28 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php index 99ad450cd0..f19d16b703 100644 --- a/src/Appwrite/Messaging/Adapter/Push/Appwrite.php +++ b/src/Appwrite/Messaging/Adapter/Push/Appwrite.php @@ -5,7 +5,6 @@ namespace Appwrite\Messaging\Adapter\Push; use Appwrite\Messaging\Adapter\Mqtt; use Utopia\Database\Database; use Utopia\Database\Document; -use Utopia\Database\Exception\Duplicate; use Utopia\Database\Helpers\ID; use Utopia\Database\Query; use Utopia\Database\Validator\Authorization; @@ -85,11 +84,12 @@ class Appwrite extends PushAdapter * on (messageId, topic): a retry after a transient publish failure reuses the existing * row and sequence instead of incrementing the topic counter or inserting a duplicate. * - * The increment and insert run in one transaction so a failed insert rolls the - * increment back — the topic sequence never advances without a matching ledger row. - * The unique index on (messageId, topic) also serialises two concurrent attempts: - * the loser's insert throws Duplicate, its increment rolls back, and it resolves to - * the winner's sequence instead of opening a gap. + * The increment and insert run in one transaction, opened by locking the topic row + * (getDocument FOR UPDATE). A concurrent attempt for the same message blocks on that + * lock, then re-reads the ledger row this transaction committed rather than racing a + * second increment — so the topic sequence can't advance without a matching row, and + * two attempts can't open a gap. The unique index on (messageId, topic) remains as a + * correctness backstop. */ private function persist(string $topic, string $payload): int { @@ -100,30 +100,33 @@ class Appwrite extends PushAdapter return (int) $existing->getAttribute('sequence'); } - try { - return (int) $authorization->skip( - fn () => $this->dbForProject->withTransaction(function () use ($topic, $payload): int { - $sequence = (int) $this->dbForProject - ->increaseDocumentAttribute('topics', $topic, 'sequence', 1) - ->getAttribute('sequence'); + return (int) $authorization->skip( + fn () => $this->dbForProject->withTransaction(function () use ($topic, $payload, $authorization): int { + // Lock the topic row so a concurrent attempt for the same message waits here. + $this->dbForProject->getDocument('topics', $topic, forUpdate: true); - $this->dbForProject->createDocument('appwritePushLedger', new Document([ - '$id' => ID::unique(), - 'topic' => $topic, - 'data' => $payload, - 'messageId' => $this->messageId, - 'messageInternalId' => $this->messageInternalId, - 'sequence' => $sequence, - ])); + // Re-check under the lock: a racing attempt may have persisted it already. + $existing = $this->findLedger($authorization, $topic); + if (!$existing->isEmpty()) { + return (int) $existing->getAttribute('sequence'); + } - return $sequence; - }) - ); - } catch (Duplicate) { - // A concurrent attempt won the (messageId, topic) unique index; its row and - // increment are committed. Return that sequence rather than incrementing again. - return (int) $this->findLedger($authorization, $topic)->getAttribute('sequence'); - } + $sequence = (int) $this->dbForProject + ->increaseDocumentAttribute('topics', $topic, 'sequence', 1) + ->getAttribute('sequence'); + + $this->dbForProject->createDocument('appwritePushLedger', new Document([ + '$id' => ID::unique(), + 'topic' => $topic, + 'data' => $payload, + 'messageId' => $this->messageId, + 'messageInternalId' => $this->messageInternalId, + 'sequence' => $sequence, + ])); + + return $sequence; + }) + ); } /** The existing ledger row for this campaign message on a topic, or an empty document. */ From 595f8872a3d8b675838516ddd3ac838449ec1471 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:04:38 +0530 Subject: [PATCH 094/146] feat(mqtt): enforce topic existence and grant QoS from the topic A SUBSCRIBE filter is granted only if it maps to an existing project topic, and the granted QoS is the client's requested max capped by the topic's configured qos. Topics are fetched in a single find for all allowed filters rather than one getDocument each; the granted QoS flows into the subscription store. --- src/Appwrite/Messaging/Adapter/Mqtt.php | 5 +- src/Utopia/Mqtt/Handlers/Subscribe.php | 76 ++++++++++++++++++------- 2 files changed, 57 insertions(+), 24 deletions(-) diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 904cdf1f55..0cdc6a471c 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -84,8 +84,9 @@ class Mqtt extends MessagingAdapter * @param array $roles ignored * @param array $channels topic filters * @param array $queryGroup ignored + * @param int $qos granted QoS stored per subscription (delivery is clamped to it) */ - public function subscribe(string $projectId, mixed $identifier, string $subscriptionId, array $roles, array $channels, array $queryGroup = []): void + public function subscribe(string $projectId, mixed $identifier, string $subscriptionId, array $roles, array $channels, array $queryGroup = [], int $qos = Packet::QOS_1): void { $userId = $this->connections[$identifier]->identity['userId'] ?? ''; @@ -95,7 +96,7 @@ class Mqtt extends MessagingAdapter $userId, $topic, $identifier, - Packet::QOS_1, + $qos, ); } } diff --git a/src/Utopia/Mqtt/Handlers/Subscribe.php b/src/Utopia/Mqtt/Handlers/Subscribe.php index e25cad0fc3..ea5e176f34 100644 --- a/src/Utopia/Mqtt/Handlers/Subscribe.php +++ b/src/Utopia/Mqtt/Handlers/Subscribe.php @@ -46,31 +46,67 @@ class Subscribe extends Action $identity = $connection->identity; - // A denied filter answers with each version's own failure marker; a granted one - // with max QoS 1 (0x01), which is a granted-QoS byte in 3.1.1 and a Success - // reason code in 5.0. $denied = $connection->protocol >= 5 ? V5::REASON_NOT_AUTHORIZED : V3::SUBSCRIBE_FAILURE; - $granted = ''; - $topics = []; + $consoleDatabase = getConsoleDB(); + $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); + $projectDB = getProjectDB($project); + + // Parse every (filter, requested QoS) in order; the SUBACK carries one reason code + // per filter in this order. Bits 0-1 of the subscription options byte are the max QoS. + $filters = []; while ($offset < strlen($body)) { [$filter, $offset] = Packet::readString($body, $offset); - $offset += 1; // subscription options byte + $filters[] = [$filter, isset($body[$offset]) ? \ord($body[$offset]) & 0x03 : 0]; + $offset += 1; + } + + $allowed = []; + foreach ($filters as [$filter]) { + if (!isset($allowed[$filter]) && ($authorizer === null || $authorizer($identity, $filter))) { + $allowed[$filter] = true; + } + } + + $topicsById = []; + if ($allowed !== []) { + $documents = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('topics', [ + Query::equal('$id', array_keys($allowed)), + Query::limit(\count($allowed)), + ])); + foreach ($documents as $document) { + $topicsById[$document->getId()] = $document; + } + } + + $granted = ''; + $topicDocuments = []; // filter => topic document, reused for replay below + foreach ($filters as [$filter, $requestedQos]) { Span::add('mqtt.topic', $filter); - // ACL: an unauthorized filter is refused and never stored. - if ($authorizer !== null && !$authorizer($identity, $filter)) { + if (!isset($allowed[$filter])) { $granted .= chr($denied); $mqtt->metrics->subscriptions->add(1, ['result' => 'denied']); - Span::add('mqtt.result', 'denied'); continue; } - $mqtt->subscribe($connection->projectId, $connection->fd, '', [], [$filter]); - $granted .= chr(Packet::QOS_1); // granted max QoS 1 + // A filter is granted only if it maps to an existing project topic. + $topicDocument = $topicsById[$filter] ?? null; + if ($topicDocument === null) { + $granted .= chr($denied); + $mqtt->metrics->subscriptions->add(1, ['result' => 'unknown']); + continue; + } + + // Requested max QoS, capped by the topic's configured QoS (null = no cap, broker max 1). + $topicQos = $topicDocument->getAttribute('qos'); + $grantedQos = min($requestedQos, $topicQos === null ? Packet::QOS_1 : (int) $topicQos); + + $mqtt->subscribe($connection->projectId, $connection->fd, '', [], [$filter], [], $grantedQos); + $granted .= chr($grantedQos); $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); - $topics[] = $filter; + $topicDocuments[$filter] = $topicDocument; } $reply( @@ -80,17 +116,16 @@ class Subscribe extends Action false, ); - if ($topics === []) { + if ($topicDocuments === []) { return; } + $topics = array_keys($topicDocuments); + // TODO: expiry should track the plan $expiry = 3600; $maxDepth = 5; - $consoleDatabase = getConsoleDB(); - $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); - $projectDB = getProjectDB($project); $cache = getCache(); $cursorKey = 'appwrite:push:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); @@ -106,13 +141,10 @@ class Subscribe extends Action $resumeTopics = array_values(array_intersect($topics, $known)); // Current tail (topics.sequence) per subscribed topic: the seed for new topics and - // the upper bound for replay. getDocument is cached, so repeated reads are cheap. + // the upper bound for replay. Reuses the documents fetched during the grant loop. $tails = []; - foreach ($topics as $topic) { - $topicDocument = $projectDB->getAuthorization()->skip(fn () => $projectDB->getDocument('topics', $topic)); - if (!$topicDocument->isEmpty()) { - $tails[$topic] = (int) $topicDocument->getAttribute('sequence', 0); - } + foreach ($topicDocuments as $topic => $topicDocument) { + $tails[$topic] = (int) $topicDocument->getAttribute('sequence', 0); } $persist = []; From 58a7d4336be564d7cb2542e6dc2cbeaf50d9debf Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:04:38 +0530 Subject: [PATCH 095/146] test(messaging): cover subscribe rejection and QoS capping MqttSubscriber.subscribe returns the SUBACK reason codes and takes a requested QoS; add e2e for an unknown-topic rejection and QoS capped by the topic config. --- .../Messaging/MessagingMqttServerTest.php | 48 ++++++++++++++++++- .../e2e/Services/Messaging/MqttSubscriber.php | 19 ++++++-- 2 files changed, 61 insertions(+), 6 deletions(-) diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 621dcce86e..5d909c3492 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -94,6 +94,50 @@ final class MessagingMqttServerTest extends Scope $subscriber->disconnect(); } + public function testSubscribeToUnknownTopicRejected(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $userId, 'jwt' => $jwt] = $this->createUser(); + + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-unknown-' . $userId, cleanStart: true)); + + try { + // Test for FAILURE: a filter that maps to no project topic is refused in the + // SUBACK (reason 0x87), not silently granted. + $codes = $subscriber->subscribe(['does-not-exist-' . $userId]); + $this->assertSame([0x87], $codes); + } finally { + $subscriber->disconnect(); + } + } + + public function testGrantedQosIsCappedByTopicConfig(): 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'], + ]; + $topicQos1 = $this->setupPushTopic($server, $userId, 'mqtt-qos1', qos: 1); + $topicQos0 = $this->setupPushTopic($server, $userId, 'mqtt-qos0', qos: 0); + + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-qos-' . $userId, cleanStart: true)); + + try { + // The client requests QoS 1 for both: the qos-1 topic grants 1, the qos-0 topic + // caps the grant to 0 (the topic's configured QoS wins from the DB). + $this->assertSame([1], $subscriber->subscribe([$topicQos1], 1)); + $this->assertSame([0], $subscriber->subscribe([$topicQos0], 1)); + } finally { + $subscriber->disconnect(); + } + } + /** * The messaging graph for the built-in Appwrite push provider: a provider, a topic * (whose id is the MQTT delivery channel), a user with a push target identified by @@ -101,7 +145,7 @@ final class MessagingMqttServerTest extends Scope * * @param array $server server-key headers */ - private function setupPushTopic(array $server, string $userId, string $name): string + private function setupPushTopic(array $server, string $userId, string $name, int $qos = 1): string { $provider = $this->client->call(Client::METHOD_POST, '/messaging/providers/appwrite', $server, [ 'providerId' => ID::unique(), @@ -113,7 +157,7 @@ final class MessagingMqttServerTest extends Scope $topic = $this->client->call(Client::METHOD_POST, '/messaging/topics', $server, [ 'topicId' => ID::unique(), 'name' => $name, - 'qos' => 1, + 'qos' => $qos, ]); $this->assertEquals(201, $topic['headers']['status-code']); $topicId = $topic['body']['$id']; diff --git a/tests/e2e/Services/Messaging/MqttSubscriber.php b/tests/e2e/Services/Messaging/MqttSubscriber.php index 2817956711..4369fa3645 100644 --- a/tests/e2e/Services/Messaging/MqttSubscriber.php +++ b/tests/e2e/Services/Messaging/MqttSubscriber.php @@ -61,13 +61,16 @@ final class MqttSubscriber } /** - * SUBSCRIBE to the given topic filters at QoS 1; returns once the SUBACK arrives. + * SUBSCRIBE to the given topic filters at the requested max QoS; returns the SUBACK + * reason code per filter (a granted QoS 0x00/0x01, or a failure such as 0x87), index + * aligned with $topics. * * @param string[] $topics + * @return array */ - public function subscribe(array $topics, float $timeout = 5.0): void + public function subscribe(array $topics, int $qos = Packet::QOS_1, float $timeout = 5.0): array { - $this->write(V5::subscribe($this->nextPacketId(), $topics, Packet::QOS_1)); + $this->write(V5::subscribe($this->nextPacketId(), $topics, $qos)); $deadline = microtime(true) + $timeout; while (true) { @@ -76,7 +79,15 @@ final class MqttSubscriber throw new \RuntimeException('mqtt: no SUBACK received'); } if ($packet->type === Packet::SUBACK) { - return; + // SUBACK body: [packetId:2][properties][one reason code per filter]. + $offset = Properties::skip($packet->body, 2); + + $codes = []; + for ($i = $offset; $i < \strlen($packet->body); $i++) { + $codes[] = \ord($packet->body[$i]); + } + + return $codes; } // Ignore any early PUBLISH replay queued before the SUBACK; consume() reads those. } From 68d2d11cd0bdab948b69f3b978b14eb4ab6882df Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:04:58 +0530 Subject: [PATCH 096/146] refactor(mqtt): remove the client PUBLISH handler Publishing is a server privilege driven through the Messaging HTTP campaign path; there is no outside MQTT publish, so drop the PUBLISH handler and its registration. An inbound PUBLISH now has no handler and is ignored. --- app/mqtt.php | 2 - src/Utopia/Mqtt/Handlers/Publish.php | 73 ---------------------------- 2 files changed, 75 deletions(-) delete mode 100644 src/Utopia/Mqtt/Handlers/Publish.php diff --git a/app/mqtt.php b/app/mqtt.php index 02748a71c4..5da0279f01 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -23,7 +23,6 @@ use Utopia\Mqtt\Handlers\Connect as ConnectHandler; use Utopia\Mqtt\Handlers\Disconnect as DisconnectHandler; use Utopia\Mqtt\Handlers\Ping as PingHandler; use Utopia\Mqtt\Handlers\Puback as PubackHandler; -use Utopia\Mqtt\Handlers\Publish as PublishHandler; use Utopia\Mqtt\Handlers\Subscribe as SubscribeHandler; use Utopia\Mqtt\Handlers\Unsubscribe as UnsubscribeHandler; use Utopia\Mqtt\Packet; @@ -295,7 +294,6 @@ $dispatcher = (new Dispatcher()) ->addHandler(new ConnectHandler()) ->addHandler(new SubscribeHandler()) ->addHandler(new UnsubscribeHandler()) - ->addHandler(new PublishHandler()) ->addHandler(new PubackHandler()) ->addHandler(new AuthHandler()) ->addHandler(new PingHandler()) diff --git a/src/Utopia/Mqtt/Handlers/Publish.php b/src/Utopia/Mqtt/Handlers/Publish.php deleted file mode 100644 index b1d8791c77..0000000000 --- a/src/Utopia/Mqtt/Handlers/Publish.php +++ /dev/null @@ -1,73 +0,0 @@ -desc('Fan a published message out to matching subscribers') - ->label(Dispatcher::LABEL_TYPE, Packet::PUBLISH) - ->inject('mqtt') - ->inject('connection') - ->inject('packet') - ->inject('reply') - ->callback($this->action(...)); - } - - /** - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) - */ - public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void - { - $body = $packet->body; - $qos = $packet->qos(); - - [$topic, $offset] = Packet::readString($body, 0); - - $packetId = null; - if ($qos > 0) { - $packetId = substr($body, $offset, 2); - $offset += 2; - } - if ($connection->protocol >= 5) { - $offset = Properties::skip($body, $offset); - } - $payload = substr($body, $offset); - - Span::add('mqtt.topic', $topic); - Span::add('mqtt.subscribers', count($mqtt->getSubscribers($connection->projectId, $topic))); - - $mqtt->send($connection->projectId, [], [], [$topic], [], ['payload' => $payload, 'qos' => $qos]); - - if ($qos === 1) { - // PUBACK is a bare packet id in both versions (reason/properties omitted). - $reply($connection->protocol >= 5 ? V5::puback($packetId) : V3::puback($packetId), false); - - // TODO: remove it from here. It shall be in the messaging worker - $consoleDatabase = getConsoleDB(); - $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); - $projectDB = getProjectDB($project); - $message = new Document([ - '$id' => ID::unique(), - 'providerType' => MESSAGE_TYPE_PUSH, - 'topics' => [$topic], - 'data' => ['payload' => $payload, 'qos' => $qos], - ]); - $projectDB->createDocument('messages', $message); - } - } -} From 0d69b3ebb55ded7e05805fb4a668715fc9ca0fd6 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:05:07 +0530 Subject: [PATCH 097/146] refactor(mqtt): resolve connection auth via the connection container Move the CONNECT authenticator and per-SUBSCRIBE authorizer into app/init/mqtt/connection.php as container services; app/mqtt.php registers them on the global container and the handlers inherit them through the packet container. project/user are plain resolver closures (nothing else injects them), so there is no per-connection child container or DI re-registration. --- app/init/mqtt/connection.php | 61 ++++++++++++++++++++++------- app/mqtt.php | 75 +++--------------------------------- 2 files changed, 52 insertions(+), 84 deletions(-) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 56cfbbb355..e020038054 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -6,28 +6,25 @@ use Appwrite\Utopia\Database\Documents\User; use Utopia\Auth\Hashes\Sha; use Utopia\Auth\Proofs\Token; use Utopia\Auth\Store; +use Utopia\Config\Config; use Utopia\Database\Document; use Utopia\Database\Validator\Authorization; use Utopia\DI\Container; use Utopia\System\System; return function (Container $container): void { - $container->set('authorization', function () { - return new Authorization(); - }, []); - - $container->set('project', function (string $projectId, Document $console, Authorization $authorization) { + $getProject = function (string $projectId, Authorization $authorization): Document { if ($projectId === '' || $projectId === 'console') { - return $console; + return new Document(Config::getParam('console')); } $dbForPlatform = getConsoleDB(); $dbForPlatform->setAuthorization($authorization); return $authorization->skip(fn () => $dbForPlatform->getDocument('projects', $projectId)); - }, ['projectId', 'console', 'authorization']); + }; - $container->set('user', function (Document $project, string $authMethod, string $credential, Authorization $authorization) { + $getUser = function (Document $project, string $authMethod, string $credential, Authorization $authorization): User { if ($project->isEmpty() || $credential === '') { return new User([]); } @@ -81,14 +78,50 @@ return function (Container $container): void { } return $user; - }, ['project', 'authMethod', 'credential', 'authorization']); + }; - // TODO: needed a better naming - $container->set('setMessageCursor', function (string $projectId, string $userId, string $clientId, string $topic, string $messageId) { + $container->set('authenticator', function () use ($getProject, $getUser): callable { + return function (string $projectId, string $authMethod, string $credential) use ($getProject, $getUser): array { + $authorization = new Authorization(); - }); + $project = $getProject($projectId, $authorization); + if ($project->isEmpty()) { + return []; + } - $container->set('getMessages', function (string $projectId, string $userId, string $clientId, string $topic, string $messageId) { + $user = $getUser($project, $authMethod, $credential, $authorization); + if ($user->isEmpty()) { + return []; + } - }); + return [ + 'projectId' => $project->getId(), + 'userId' => $user->getId(), + ]; + }; + }, []); + + $container->set('authorizer', function () use ($getProject): callable { + return function (array $identity, string $topic) use ($getProject): bool { + $userId = $identity['userId'] ?? ''; + $projectId = $identity['projectId'] ?? ''; + if ($userId === '' || $projectId === '') { + return false; + } + + $authorization = new Authorization(); + + $project = $getProject($projectId, $authorization); + if ($project->isEmpty()) { + return false; + } + + $dbForProject = getProjectDB($project); + $dbForProject->setAuthorization($authorization); + $user = $authorization->skip(fn () => $dbForProject->getDocument('users', $userId)); + + // status: true = enabled, false = blocked. + return !$user->isEmpty() && $user->getAttribute('status', true) !== false; + }; + }, []); }; diff --git a/app/mqtt.php b/app/mqtt.php index 5da0279f01..84dbaf541b 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -13,7 +13,6 @@ use Utopia\Console; use Utopia\Database\Adapter\Pool as DatabasePool; use Utopia\Database\Database; use Utopia\Database\Document; -use Utopia\Database\Validator\Authorization; use Utopia\DI\Container; use Utopia\DSN\DSN; use Utopia\Mqtt\Adapter; @@ -213,71 +212,10 @@ if (!function_exists('getRedis')) { } } -/** - * Authenticate a CONNECT: resolve the project and verify the session in a child - * container, using the same domain logic as HTTP/realtime. Returns the identity - * for the connection, or an empty array when the credential is invalid. - * - * @return array{projectId: string, userId: string}|array{} - */ -$authenticate = function (string $projectId, string $authMethod, string $credential) use ($container, $registerMqttConnectionResources): array { - $connectionContainer = new Container($container); - $connectionContainer->set('projectId', fn () => $projectId); - $connectionContainer->set('authMethod', fn () => $authMethod); - $connectionContainer->set('credential', fn () => $credential); - - $registerMqttConnectionResources($connectionContainer); - - /** @var Document $project */ - $project = $connectionContainer->get('project'); - /** @var User $user */ - $user = $connectionContainer->get('user'); - - if ($project->isEmpty() || $user->isEmpty()) { - return []; - } - - return [ - 'projectId' => $project->getId(), - 'userId' => $user->getId(), - ]; -}; - -/** - * ACL for SUBSCRIBE: refuse blocked accounts. Re-checked per subscribe so a block - * applied mid-connection takes effect on the next subscription. - * - * TODO: also authorize the topic itself — verify it maps to an existing messaging - * Topic in the project (topics API/collection) and that this user is allowed on it. - * A subscription to a non-existent or unauthorized topic should be denied. Deferred - * until the topic subscription model is wired. - */ -$authorize = function (array $identity, string $topic) use ($container, $registerMqttConnectionResources): bool { - $userId = $identity['userId'] ?? ''; - $projectId = $identity['projectId'] ?? ''; - if ($userId === '' || $projectId === '') { - return false; - } - - $connectionContainer = new Container($container); - $connectionContainer->set('projectId', fn () => $projectId); - $registerMqttConnectionResources($connectionContainer); - - /** @var Authorization $authorization */ - $authorization = $connectionContainer->get('authorization'); - /** @var Document $project */ - $project = $connectionContainer->get('project'); - if ($project->isEmpty()) { - return false; - } - - $dbForProject = getProjectDB($project); - $dbForProject->setAuthorization($authorization); - $user = $authorization->skip(fn () => $dbForProject->getDocument('users', $userId)); - - // status: true = enabled, false = blocked. - return !$user->isEmpty() && $user->getAttribute('status', true) !== false; -}; +// Register the CONNECT authenticator and per-SUBSCRIBE authorizer on the global container +// (see app/init/mqtt/connection.php). The CONNECT/SUBSCRIBE handlers inject them by name, +// resolved through the packet container that inherits from this one. +$registerMqttConnectionResources($container); /** @var \Utopia\Telemetry\Adapter $telemetry */ $telemetry = $container->get('telemetry'); @@ -378,8 +316,6 @@ $server->onReceive(function (int $fd, string $data) use ( $server, $mqtt, $dispatcher, - $authenticate, - $authorize, $container ): void { $packet = Packet::parse($data); @@ -398,12 +334,11 @@ $server->onReceive(function (int $fd, string $data) use ( } }; + // authenticator/authorizer are inherited from the global container (registered above). $packetContainer = new Container($container); $packetContainer->set('mqtt', fn () => $mqtt); $packetContainer->set('connection', fn () => $connection); $packetContainer->set('packet', fn () => $packet); - $packetContainer->set('authenticator', fn () => $authenticate); - $packetContainer->set('authorizer', fn () => $authorize); $packetContainer->set('reply', fn () => $reply); try { From f7108cc3800683133f68383ff0d707719806f4b2 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:44:34 +0530 Subject: [PATCH 098/146] feat(mqtt): add the keep-alive timing wheel and connection state KeepAlive is a hashed timing wheel: connections bucket by their deadline second, schedule() returns the slot the caller stores on the Connection, drain() returns every fd due at or before a tick, and remove() drops a fd (and its emptied bucket). Connection carries keepAlive/expiresAt/wheelSlot and touch() pushes the deadline to keepAlive x MULTIPLIER; the CONNECT handler parses the keep-alive it used to skip. --- app/mqtt.php | 31 ++++++++ src/Appwrite/Messaging/Adapter/Mqtt.php | 14 +++- src/Utopia/Mqtt/Connection.php | 20 +++++ src/Utopia/Mqtt/Handlers/Connect.php | 3 +- src/Utopia/Mqtt/KeepAlive.php | 72 +++++++++++++++++ .../Messaging/MessagingMqttServerTest.php | 17 ++++ .../e2e/Services/Messaging/MqttSubscriber.php | 41 +++++++++- tests/unit/Utopia/Mqtt/ConnectionTest.php | 21 +++++ tests/unit/Utopia/Mqtt/KeepAliveTest.php | 77 +++++++++++++++++++ 9 files changed, 291 insertions(+), 5 deletions(-) create mode 100644 src/Utopia/Mqtt/KeepAlive.php create mode 100644 tests/unit/Utopia/Mqtt/KeepAliveTest.php diff --git a/app/mqtt.php b/app/mqtt.php index 84dbaf541b..53819beabc 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -5,6 +5,7 @@ use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Appwrite\Utopia\Database\Documents\User; use Swoole\Coroutine; use Swoole\Runtime; +use Swoole\Timer; use Utopia\Cache\Adapter\Pool as CachePool; use Utopia\Cache\Adapter\Sharding; use Utopia\Cache\Cache; @@ -24,6 +25,7 @@ use Utopia\Mqtt\Handlers\Ping as PingHandler; use Utopia\Mqtt\Handlers\Puback as PubackHandler; use Utopia\Mqtt\Handlers\Subscribe as SubscribeHandler; use Utopia\Mqtt\Handlers\Unsubscribe as UnsubscribeHandler; +use Utopia\Mqtt\KeepAlive; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; @@ -240,6 +242,27 @@ $dispatcher = (new Dispatcher()) $server->onStart(fn () => print("MQTT broker started\n")); $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): void { + // Keep-alive reaper: every INTERVAL seconds drain the wheel's due buckets and close any + // client silent past its deadline (keepAlive x MULTIPLIER). A survivor whose deadline was + // pushed forward by recent traffic is rescheduled instead. onClose balances the gauge and + // forgets the fd. Per worker, since connections and the wheel are per worker. + Timer::tick(KeepAlive::INTERVAL * 1000, function () use ($server, $mqtt): void { + $now = microtime(true); + + foreach ($mqtt->keepAlive->drain((int) $now) as $fd) { + $connection = $mqtt->connections[$fd] ?? null; + if ($connection === null || $connection->keepAlive <= 0) { + continue; + } + + if ($connection->expiresAt <= $now) { + $server->close($fd); + } else { + $connection->wheelSlot = $mqtt->keepAlive->schedule($fd, $connection->expiresAt); + } + } + }); + go(function () use ($server, $mqtt, $register): void { $attempts = 0; while ($attempts < 300) { @@ -344,6 +367,14 @@ $server->onReceive(function (int $fd, string $data) use ( try { $dispatcher->dispatch($packetContainer, $packet->type); + // Every inbound packet is liveness: push the deadline forward (O(1), no wheel touch). + // The wheel is seeded once, when CONNECT establishes the interval; later packets only + // move the deadline and the reaper reschedules lazily when it visits the slot. + $connection->touch(microtime(true)); + if ($packet->type === Packet::CONNECT && $connection->active && $connection->keepAlive > 0) { + $connection->wheelSlot = $mqtt->keepAlive->schedule($fd, $connection->expiresAt); + } + // The identity, project and clean-start flag are populated by the CONNECT // handler during dispatch, so record them afterwards rather than as defaults. $span->set('project.id', $connection->projectId); diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 0cdc6a471c..10b17da7c7 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -5,6 +5,7 @@ namespace Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter as MessagingAdapter; use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Utopia\Mqtt\Connection; +use Utopia\Mqtt\KeepAlive; use Utopia\Mqtt\Metrics; use Utopia\Mqtt\Packet; use Utopia\Mqtt\SubscriptionStore; @@ -26,6 +27,9 @@ class Mqtt extends MessagingAdapter /** Telemetry instruments the handlers record connection and delivery outcomes on. */ public readonly Metrics $metrics; + /** Keep-alive reaper wheel: connections register their deadline here, the tick drains it. */ + public readonly KeepAlive $keepAlive; + private ?SubscriptionStore $subscriptions = null; private ?PubSubPool $pubSubPool = null; @@ -33,6 +37,7 @@ class Mqtt extends MessagingAdapter public function __construct(Telemetry $telemetry) { $this->metrics = new Metrics($telemetry); + $this->keepAlive = new KeepAlive(); } /** @@ -67,8 +72,13 @@ class Mqtt extends MessagingAdapter public function close(int $fd): void { $connection = $this->connections[$fd] ?? null; - if ($connection !== null && $connection->active) { - $this->metrics->connectionsActive->add(-1); + if ($connection !== null) { + if ($connection->active) { + $this->metrics->connectionsActive->add(-1); + } + if ($connection->wheelSlot > 0) { + $this->keepAlive->remove($fd, $connection->wheelSlot); + } } $this->unsubscribe($fd); unset($this->connections[$fd]); diff --git a/src/Utopia/Mqtt/Connection.php b/src/Utopia/Mqtt/Connection.php index 58049348df..0198619512 100644 --- a/src/Utopia/Mqtt/Connection.php +++ b/src/Utopia/Mqtt/Connection.php @@ -30,6 +30,15 @@ class Connection /** Counted as active (accepted CONNECT), for a balanced gauge. */ public bool $active = false; + /** CONNECT keep-alive interval in seconds; 0 disables keep-alive (the client is never reaped). */ + public int $keepAlive = 0; + + /** Absolute unix deadline (fractional seconds) past which a silent client is reaped; 0 while disabled. */ + public float $expiresAt = 0.0; + + /** The keep-alive wheel bucket (second) this connection currently sits in; 0 when not scheduled. */ + public int $wheelSlot = 0; + private int $packetId = 0; /** @@ -48,6 +57,17 @@ class Connection ) { } + /** + * Push the keep-alive deadline to KeepAlive::MULTIPLIER x the negotiated interval past + * $now — every inbound packet is liveness. No-op when keep-alive is disabled. + */ + public function touch(float $now): void + { + if ($this->keepAlive > 0) { + $this->expiresAt = $now + $this->keepAlive * KeepAlive::MULTIPLIER; + } + } + /** Next outbound packet id, wrapping 1..65535 (0 is not allowed). */ public function nextPacketId(): int { diff --git a/src/Utopia/Mqtt/Handlers/Connect.php b/src/Utopia/Mqtt/Handlers/Connect.php index 16ab0d389f..6f013b5c4c 100644 --- a/src/Utopia/Mqtt/Handlers/Connect.php +++ b/src/Utopia/Mqtt/Handlers/Connect.php @@ -42,7 +42,8 @@ class Connect extends Action $connection->protocol = $level; $offset += 1; // protocol level $offset += 1; // connect flags - $offset += 2; // keep alive + [$keepAlive, $offset] = Packet::readInt16($body, $offset); // keep alive (seconds) + $connection->keepAlive = $keepAlive; $connection->cleanStart = Packet::isCleanStart($body); Span::add('mqtt.clean_start', $connection->cleanStart); diff --git a/src/Utopia/Mqtt/KeepAlive.php b/src/Utopia/Mqtt/KeepAlive.php new file mode 100644 index 0000000000..bb581d7ba7 --- /dev/null +++ b/src/Utopia/Mqtt/KeepAlive.php @@ -0,0 +1,72 @@ +> deadline second => set of fds */ + private array $buckets = []; + + /** Highest second already drained; buckets at or before it are gone. */ + private int $cursor; + + public function __construct(?int $now = null) + { + $this->cursor = $now ?? \time(); + } + + public function schedule(int $fd, float $expiresAt): int + { + $slot = \max((int) $expiresAt, $this->cursor + 1); + $this->buckets[$slot][$fd] = true; + + return $slot; + } + + public function remove(int $fd, int $slot): void + { + unset($this->buckets[$slot][$fd]); + + // Drop the whole bucket once its last connection leaves, so a future second emptied + // by disconnects doesn't linger as an empty array until the tick reaches it. + if (($this->buckets[$slot] ?? null) === []) { + unset($this->buckets[$slot]); + } + } + + /** + * + * @return array + */ + public function drain(int $now): array + { + $fds = []; + + for ($second = $this->cursor + 1; $second <= $now; $second++) { + if (!isset($this->buckets[$second])) { + continue; + } + + foreach (\array_keys($this->buckets[$second]) as $fd) { + $fds[] = $fd; + } + + unset($this->buckets[$second]); + } + + $this->cursor = \max($this->cursor, $now); + + return $fds; + } +} diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 5d909c3492..2be2d34db2 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -112,6 +112,23 @@ final class MessagingMqttServerTest extends Scope } } + public function testKeepAliveReapsSilentClient(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $userId, 'jwt' => $jwt] = $this->createUser(); + + // Connect with a 1s keep-alive (reap deadline 1.5s) and then stay silent. The reaper + // must close the socket. Its tick period bounds detection, so allow generous slack. + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-keepalive-' . $userId, cleanStart: true, keepAlive: 1)); + + try { + $this->assertTrue($subscriber->awaitClose(40.0), 'broker did not reap a silent client past its keep-alive'); + } finally { + $subscriber->disconnect(); + } + } + public function testGrantedQosIsCappedByTopicConfig(): void { $projectId = $this->getProject()['$id']; diff --git a/tests/e2e/Services/Messaging/MqttSubscriber.php b/tests/e2e/Services/Messaging/MqttSubscriber.php index 4369fa3645..5e3ecdcd21 100644 --- a/tests/e2e/Services/Messaging/MqttSubscriber.php +++ b/tests/e2e/Services/Messaging/MqttSubscriber.php @@ -34,7 +34,7 @@ final class MqttSubscriber * Enhanced-auth CONNECT. Returns the CONNACK reason code (0 = success); the broker * rejects with 0x87 (not authorized). Throws only on a transport failure. */ - public function connect(string $projectId, string $credential, string $clientId, bool $cleanStart, string $authMethod = 'appwrite-jwt'): int + public function connect(string $projectId, string $credential, string $clientId, bool $cleanStart, string $authMethod = 'appwrite-jwt', int $keepAlive = 60): int { $errno = 0; $errstr = ''; @@ -49,7 +49,7 @@ final class MqttSubscriber $properties->add(new Property(Property::AUTHENTICATION_DATA, $credential)); $properties->add(new Property(Property::USER, ['projectId' => $projectId])); - $this->write(V5::connect($clientId, 60, $cleanStart, $properties)); + $this->write(V5::connect($clientId, $keepAlive, $cleanStart, $properties)); $packet = $this->readPacket(microtime(true) + $this->connectTimeout); if ($packet === null || $packet->type !== Packet::CONNACK) { @@ -137,6 +137,43 @@ final class MqttSubscriber return $received; } + /** + * Block until the broker closes the connection, or $timeout seconds elapse. Returns true + * if the broker closed it (keep-alive reap), false on timeout while still connected. + */ + public function awaitClose(float $timeout): bool + { + if (!\is_resource($this->socket)) { + return true; + } + + $deadline = microtime(true) + $timeout; + while (true) { + $remaining = $deadline - microtime(true); + if ($remaining <= 0) { + return false; + } + + $read = [$this->socket]; + $write = null; + $except = null; + $seconds = (int) $remaining; + $ready = @stream_select($read, $write, $except, $seconds, (int) (($remaining - $seconds) * 1_000_000)); + if ($ready === false) { + return false; + } + if ($ready === 0) { + continue; // idle but still open + } + + // Readable: a broker-closed socket reads '' at EOF; anything else keeps it open. + $chunk = @fread($this->socket, 1024); + if (($chunk === '' || $chunk === false) && feof($this->socket)) { + return true; + } + } + } + public function disconnect(): void { if (!\is_resource($this->socket)) { diff --git a/tests/unit/Utopia/Mqtt/ConnectionTest.php b/tests/unit/Utopia/Mqtt/ConnectionTest.php index dc03d2560b..a3f027d3b0 100644 --- a/tests/unit/Utopia/Mqtt/ConnectionTest.php +++ b/tests/unit/Utopia/Mqtt/ConnectionTest.php @@ -7,6 +7,7 @@ namespace Tests\Unit\Utopia\Mqtt; use Appwrite\Extend\Exception; use PHPUnit\Framework\TestCase; use Utopia\Mqtt\Connection; +use Utopia\Mqtt\KeepAlive; final class ConnectionTest extends TestCase { @@ -17,6 +18,26 @@ final class ConnectionTest extends TestCase $this->assertTrue($connection->cleanStart); } + public function testTouchSetsTheDeadlineToKeepAliveTimesMultiplier(): void + { + $connection = new Connection(1); + $connection->keepAlive = 20; + + $connection->touch(1000.0); + + $this->assertSame(1000.0 + 20 * KeepAlive::MULTIPLIER, $connection->expiresAt); + } + + public function testTouchIsANoOpWhenKeepAliveIsDisabled(): void + { + $connection = new Connection(1); + // keepAlive defaults to 0 (disabled). + + $connection->touch(1000.0); + + $this->assertEqualsWithDelta(0.0, $connection->expiresAt, PHP_FLOAT_EPSILON); + } + public function testClientSuppliedIdIsStoredVerbatim(): void { $connection = new Connection(1); diff --git a/tests/unit/Utopia/Mqtt/KeepAliveTest.php b/tests/unit/Utopia/Mqtt/KeepAliveTest.php new file mode 100644 index 0000000000..45a616a67e --- /dev/null +++ b/tests/unit/Utopia/Mqtt/KeepAliveTest.php @@ -0,0 +1,77 @@ +assertSame(1005, $wheel->schedule(7, 1005.5)); // floors to second 1005 + $this->assertSame([], $wheel->drain(1004), 'not due before its second'); + $this->assertSame([7], $wheel->drain(1005), 'due at its second'); + $this->assertSame([], $wheel->drain(1006), 'drained, not returned again'); + } + + public function testOneTickDrainsEveryElapsedSecond(): void + { + // Bucket resolution (1s) is finer than the tick, so a single coarse tick must drain + // the whole elapsed range, never skipping a bucket between ticks. + $wheel = new KeepAlive(1000); + $wheel->schedule(1, 1003.0); + $wheel->schedule(2, 1007.9); + + $this->assertSame([1, 2], $wheel->drain(1020)); + } + + public function testConnectionsSharingASecondAreAllReturned(): void + { + $wheel = new KeepAlive(1000); + $wheel->schedule(1, 1002.1); + $wheel->schedule(2, 1002.9); + + $this->assertSame([1, 2], $wheel->drain(1002)); + } + + public function testRemoveTakesAConnectionOffItsSlot(): void + { + $wheel = new KeepAlive(1000); + $slot = $wheel->schedule(7, 1002.0); + + $wheel->remove(7, $slot); + + $this->assertSame([], $wheel->drain(1002)); + } + + public function testRemovingAnAlreadyDrainedSlotIsHarmless(): void + { + $wheel = new KeepAlive(1000); + $slot = $wheel->schedule(7, 1002.0); + $this->assertSame([7], $wheel->drain(1002)); + + $wheel->remove(7, $slot); // e.g. a close that races the reaper + + $this->assertSame([], $wheel->drain(1003)); + } + + public function testADeadlineAlreadyPastLandsInTheNextTick(): void + { + // Never drop a connection into an already-drained second: it must resolve to cursor + 1. + $wheel = new KeepAlive(1000); + + $this->assertSame(1001, $wheel->schedule(7, 999.0)); + $this->assertSame([7], $wheel->drain(1001)); + } + + public function testDefaults(): void + { + $this->assertSame(20, KeepAlive::INTERVAL); + $this->assertEqualsWithDelta(1.5, KeepAlive::MULTIPLIER, PHP_FLOAT_EPSILON); + } +} From a949768baec08ce2384b714578020d4e48acdc04 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 16:44:34 +0530 Subject: [PATCH 099/146] test(mqtt): cover the keep-alive wheel and reaper Unit-test the wheel (schedule/drain/remove, coarse-tick range drain, past deadline, emptied-bucket cleanup) and Connection::touch. E2e: a silent client is reaped past its keep-alive, and an actively pinging client survives a full reaper interval (also exercising PINGREQ/PINGRESP). Adds MqttSubscriber ping/awaitClose and a keepAlive connect param. --- .../Messaging/MessagingMqttServerTest.php | 25 +++++++++++++++++++ .../e2e/Services/Messaging/MqttSubscriber.php | 18 +++++++++++++ 2 files changed, 43 insertions(+) diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 2be2d34db2..94ba3d5f04 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -11,6 +11,7 @@ use Tests\E2E\Scopes\ProjectCustom; use Tests\E2E\Scopes\Scope; use Tests\E2E\Scopes\SideServer; use Utopia\Database\Helpers\ID; +use Utopia\Mqtt\KeepAlive; /** * End-to-end tests for the MQTT push broker (src/Utopia/Mqtt). Publishing is a server @@ -129,6 +130,30 @@ final class MessagingMqttServerTest extends Scope } } + public function testKeepAlivePingKeepsClientAlive(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $userId, 'jwt' => $jwt] = $this->createUser(); + + // 1s keep-alive (reap deadline 1.5s). Ping steadily across a full reaper interval: each + // PINGREQ must draw a PINGRESP and push the deadline forward, so the client is never reaped. + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-ping-' . $userId, cleanStart: true, keepAlive: 1)); + + try { + $deadline = microtime(true) + KeepAlive::INTERVAL + 5; // span at least one reaper tick + while (microtime(true) < $deadline) { + $this->assertTrue($subscriber->ping(2.0), 'broker did not answer PINGRESP'); + usleep(800_000); // < the 1.5s deadline, so activity stays ahead of the reaper + } + + // Still connected: an immediate close-await times out rather than seeing an EOF. + $this->assertFalse($subscriber->awaitClose(0.5), 'an actively pinging client was reaped'); + } finally { + $subscriber->disconnect(); + } + } + public function testGrantedQosIsCappedByTopicConfig(): void { $projectId = $this->getProject()['$id']; diff --git a/tests/e2e/Services/Messaging/MqttSubscriber.php b/tests/e2e/Services/Messaging/MqttSubscriber.php index 5e3ecdcd21..e58b9fc2ff 100644 --- a/tests/e2e/Services/Messaging/MqttSubscriber.php +++ b/tests/e2e/Services/Messaging/MqttSubscriber.php @@ -141,6 +141,24 @@ final class MqttSubscriber * Block until the broker closes the connection, or $timeout seconds elapse. Returns true * if the broker closed it (keep-alive reap), false on timeout while still connected. */ + /** Send a PINGREQ and return true once the broker answers PINGRESP within $timeout. */ + public function ping(float $timeout = 2.0): bool + { + $this->write(Packet::pingreq()); + + $deadline = microtime(true) + $timeout; + while (true) { + $packet = $this->readPacket($deadline); + if ($packet === null) { + return false; + } + if ($packet->type === Packet::PINGRESP) { + return true; + } + // Ignore any interleaved PUBLISH; keep waiting for the PINGRESP. + } + } + public function awaitClose(float $timeout): bool { if (!\is_resource($this->socket)) { From af80c5cb4b60daff7ecffc8d4719321af1e149fe Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 17:14:26 +0530 Subject: [PATCH 100/146] refactor(mqtt): move the broker to src/Appwrite/Mqtt Relocate the broker logic (Connection, Dispatcher, KeepAlive, Metrics, SubscriptionStore, Handlers) from Utopia\Mqtt to Appwrite\Mqtt, next to Realtime, since these are app classes not overrides of the utopia-php/mqtt package (which still provides the generic codec: Packet, Properties, Server, Adapter). Drops the src/Utopia/Mqtt PSR-4 override; moves the unit tests too. Also makes offline replay plan/topic-driven: replay depth comes from getPlanForUser (env _APP_MQTT_REPLAY_DEPTH, default 5, overridden in Cloud) and the cursor TTL from the subscribed topics' expiry. --- app/mqtt.php | 25 ++++++++++++------- composer.json | 3 +-- src/Appwrite/Messaging/Adapter/Mqtt.php | 8 +++--- src/{Utopia => Appwrite}/Mqtt/Connection.php | 2 +- src/{Utopia => Appwrite}/Mqtt/Dispatcher.php | 2 +- .../Mqtt/Handlers/Auth.php | 6 ++--- .../Mqtt/Handlers/Connect.php | 6 ++--- .../Mqtt/Handlers/Disconnect.php | 4 +-- .../Mqtt/Handlers/Ping.php | 4 +-- .../Mqtt/Handlers/Puback.php | 6 ++--- .../Mqtt/Handlers/Subscribe.php | 19 +++++++++----- .../Mqtt/Handlers/Unsubscribe.php | 6 ++--- src/{Utopia => Appwrite}/Mqtt/KeepAlive.php | 4 +-- src/{Utopia => Appwrite}/Mqtt/Metrics.php | 2 +- .../Mqtt/SubscriptionStore.php | 2 +- .../Messaging/MessagingMqttServerTest.php | 4 +-- .../e2e/Services/Messaging/MqttSubscriber.php | 8 +++--- .../Appwrite/Messaging/Adapter/MqttTest.php | 2 +- .../Mqtt/ConnectionTest.php | 6 ++--- .../Mqtt/KeepAliveTest.php | 4 +-- .../Mqtt/SubscriptionStoreTest.php | 4 +-- 21 files changed, 70 insertions(+), 57 deletions(-) rename src/{Utopia => Appwrite}/Mqtt/Connection.php (99%) rename src/{Utopia => Appwrite}/Mqtt/Dispatcher.php (98%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Auth.php (96%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Connect.php (97%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Disconnect.php (90%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Ping.php (89%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Puback.php (96%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Subscribe.php (93%) rename src/{Utopia => Appwrite}/Mqtt/Handlers/Unsubscribe.php (94%) rename src/{Utopia => Appwrite}/Mqtt/KeepAlive.php (98%) rename src/{Utopia => Appwrite}/Mqtt/Metrics.php (98%) rename src/{Utopia => Appwrite}/Mqtt/SubscriptionStore.php (99%) rename tests/unit/{Utopia => Appwrite}/Mqtt/ConnectionTest.php (97%) rename tests/unit/{Utopia => Appwrite}/Mqtt/KeepAliveTest.php (97%) rename tests/unit/{Utopia => Appwrite}/Mqtt/SubscriptionStoreTest.php (98%) diff --git a/app/mqtt.php b/app/mqtt.php index 53819beabc..b69df6a71e 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -1,6 +1,15 @@ getAttribute('expiry', 0)); + } + if ($expiry <= 0) { + $expiry = 3600; + } + + // Replay depth comes from the user's org plan (self-hosted default; see getPlanForUser). + $maxDepth = getPlanForUser($project, $connection->identity['userId'] ?? ''); $cache = getCache(); diff --git a/src/Utopia/Mqtt/Handlers/Unsubscribe.php b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php similarity index 94% rename from src/Utopia/Mqtt/Handlers/Unsubscribe.php rename to src/Appwrite/Mqtt/Handlers/Unsubscribe.php index 92b5e69bcb..0eca309eb5 100644 --- a/src/Utopia/Mqtt/Handlers/Unsubscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php @@ -1,10 +1,10 @@ socket)) { diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php index f22220b4c4..6c8cb44f2c 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -7,7 +7,7 @@ namespace Tests\Unit\Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter\Mqtt; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; -use Utopia\Mqtt\Connection; +use Appwrite\Mqtt\Connection; use Utopia\Telemetry\Adapter\None as NoTelemetry; /** diff --git a/tests/unit/Utopia/Mqtt/ConnectionTest.php b/tests/unit/Appwrite/Mqtt/ConnectionTest.php similarity index 97% rename from tests/unit/Utopia/Mqtt/ConnectionTest.php rename to tests/unit/Appwrite/Mqtt/ConnectionTest.php index a3f027d3b0..c205814a09 100644 --- a/tests/unit/Utopia/Mqtt/ConnectionTest.php +++ b/tests/unit/Appwrite/Mqtt/ConnectionTest.php @@ -2,12 +2,12 @@ declare(strict_types=1); -namespace Tests\Unit\Utopia\Mqtt; +namespace Tests\Unit\Appwrite\Mqtt; use Appwrite\Extend\Exception; +use Appwrite\Mqtt\Connection; +use Appwrite\Mqtt\KeepAlive; use PHPUnit\Framework\TestCase; -use Utopia\Mqtt\Connection; -use Utopia\Mqtt\KeepAlive; final class ConnectionTest extends TestCase { diff --git a/tests/unit/Utopia/Mqtt/KeepAliveTest.php b/tests/unit/Appwrite/Mqtt/KeepAliveTest.php similarity index 97% rename from tests/unit/Utopia/Mqtt/KeepAliveTest.php rename to tests/unit/Appwrite/Mqtt/KeepAliveTest.php index 45a616a67e..d145299b4d 100644 --- a/tests/unit/Utopia/Mqtt/KeepAliveTest.php +++ b/tests/unit/Appwrite/Mqtt/KeepAliveTest.php @@ -2,10 +2,10 @@ declare(strict_types=1); -namespace Tests\Unit\Utopia\Mqtt; +namespace Tests\Unit\Appwrite\Mqtt; +use Appwrite\Mqtt\KeepAlive; use PHPUnit\Framework\TestCase; -use Utopia\Mqtt\KeepAlive; final class KeepAliveTest extends TestCase { diff --git a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php b/tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php similarity index 98% rename from tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php rename to tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php index 0977dac608..d9f77f2f4b 100644 --- a/tests/unit/Utopia/Mqtt/SubscriptionStoreTest.php +++ b/tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php @@ -2,11 +2,11 @@ declare(strict_types=1); -namespace Tests\Unit\Utopia\Mqtt; +namespace Tests\Unit\Appwrite\Mqtt; +use Appwrite\Mqtt\SubscriptionStore; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; -use Utopia\Mqtt\SubscriptionStore; final class SubscriptionStoreTest extends TestCase { From bdd3c11f7945afef85fd21410fdcb1372c817331 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 17:14:26 +0530 Subject: [PATCH 101/146] chore(mqtt): expose _APP_MQTT_REPLAY_DEPTH Declare the broker's offline-replay depth env var (default 5) on the appwrite-mqtt service and in .env. --- .env | 1 + docker-compose.yml | 1 + 2 files changed, 2 insertions(+) diff --git a/.env b/.env index 2ab4f1005c..a3eb30ac41 100644 --- a/.env +++ b/.env @@ -59,6 +59,7 @@ _APP_DB_PASS=password _APP_DB_ROOT_PASS=rootsecretpassword _APP_DATABASE_SHARED_NAMESPACE= _APP_DATABASE_SHARED_TABLES= +_APP_MQTT_REPLAY_DEPTH=5 _APP_DB_ADAPTER_DOCUMENTSDB=mongodb _APP_DB_HOST_DOCUMENTSDB=mongodb _APP_DB_PORT_DOCUMENTSDB=27017 diff --git a/docker-compose.yml b/docker-compose.yml index 7c329c87fb..c207511033 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -409,6 +409,7 @@ services: - _APP_LOGGING_FORMAT - _APP_LOGGING_CONFIG_REALTIME - _APP_DATABASE_SHARED_TABLES + - _APP_MQTT_REPLAY_DEPTH - _APP_POOL_ADAPTER=swoole appwrite-worker: From 3d7def654b1196f1e933e2cd950d43ddde6d8266 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 17:18:32 +0530 Subject: [PATCH 102/146] lint --- tests/unit/Appwrite/Messaging/Adapter/MqttTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php index 6c8cb44f2c..bc4e58b046 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -5,9 +5,9 @@ declare(strict_types=1); namespace Tests\Unit\Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter\Mqtt; +use Appwrite\Mqtt\Connection; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; -use Appwrite\Mqtt\Connection; use Utopia\Telemetry\Adapter\None as NoTelemetry; /** From 214223e89181f5b35c26b0c74a1b60286d1ad948 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 17:25:46 +0530 Subject: [PATCH 103/146] refactor(mqtt): rename touch method to updateExpiresAt for clarity --- app/mqtt.php | 2 +- src/Appwrite/Mqtt/Connection.php | 2 +- src/Appwrite/Platform/Installer/Http/Installer/Complete.php | 2 +- tests/unit/Appwrite/Mqtt/ConnectionTest.php | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index b69df6a71e..76f72e3977 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -377,7 +377,7 @@ $server->onReceive(function (int $fd, string $data) use ( // Every inbound packet is liveness: push the deadline forward (O(1), no wheel touch). // The wheel is seeded once, when CONNECT establishes the interval; later packets only // move the deadline and the reaper reschedules lazily when it visits the slot. - $connection->touch(microtime(true)); + $connection->updateExpiresAt(microtime(true)); if ($packet->type === Packet::CONNECT && $connection->active && $connection->keepAlive > 0) { $connection->wheelSlot = $mqtt->keepAlive->schedule($fd, $connection->expiresAt); } diff --git a/src/Appwrite/Mqtt/Connection.php b/src/Appwrite/Mqtt/Connection.php index 72b969a6cf..5f6d2a3ad1 100644 --- a/src/Appwrite/Mqtt/Connection.php +++ b/src/Appwrite/Mqtt/Connection.php @@ -61,7 +61,7 @@ class Connection * Push the keep-alive deadline to KeepAlive::MULTIPLIER x the negotiated interval past * $now — every inbound packet is liveness. No-op when keep-alive is disabled. */ - public function touch(float $now): void + public function updateExpiresAt(float $now): void { if ($this->keepAlive > 0) { $this->expiresAt = $now + $this->keepAlive * KeepAlive::MULTIPLIER; diff --git a/src/Appwrite/Platform/Installer/Http/Installer/Complete.php b/src/Appwrite/Platform/Installer/Http/Installer/Complete.php index 69f7d4b072..5d2750123d 100644 --- a/src/Appwrite/Platform/Installer/Http/Installer/Complete.php +++ b/src/Appwrite/Platform/Installer/Http/Installer/Complete.php @@ -46,7 +46,7 @@ class Complete extends Action $state->updateGlobalLock($installId, Server::STATUS_COMPLETED); } - @touch(Server::INSTALLER_COMPLETE_FILE); + @updateExpiresAt(Server::INSTALLER_COMPLETE_FILE); $progressData = ($installId !== '') ? $state->readProgressFile($installId) : []; diff --git a/tests/unit/Appwrite/Mqtt/ConnectionTest.php b/tests/unit/Appwrite/Mqtt/ConnectionTest.php index c205814a09..0405784235 100644 --- a/tests/unit/Appwrite/Mqtt/ConnectionTest.php +++ b/tests/unit/Appwrite/Mqtt/ConnectionTest.php @@ -23,7 +23,7 @@ final class ConnectionTest extends TestCase $connection = new Connection(1); $connection->keepAlive = 20; - $connection->touch(1000.0); + $connection->updateExpiresAt(1000.0); $this->assertSame(1000.0 + 20 * KeepAlive::MULTIPLIER, $connection->expiresAt); } @@ -33,7 +33,7 @@ final class ConnectionTest extends TestCase $connection = new Connection(1); // keepAlive defaults to 0 (disabled). - $connection->touch(1000.0); + $connection->updateExpiresAt(1000.0); $this->assertEqualsWithDelta(0.0, $connection->expiresAt, PHP_FLOAT_EPSILON); } From 0d3b19ed749c3b5c52657ef9d946d2b59f46700d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 11 Sep 2026 17:29:52 +0530 Subject: [PATCH 104/146] reverted redundant file --- src/Appwrite/Platform/Installer/Http/Installer/Complete.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Platform/Installer/Http/Installer/Complete.php b/src/Appwrite/Platform/Installer/Http/Installer/Complete.php index 5d2750123d..69f7d4b072 100644 --- a/src/Appwrite/Platform/Installer/Http/Installer/Complete.php +++ b/src/Appwrite/Platform/Installer/Http/Installer/Complete.php @@ -46,7 +46,7 @@ class Complete extends Action $state->updateGlobalLock($installId, Server::STATUS_COMPLETED); } - @updateExpiresAt(Server::INSTALLER_COMPLETE_FILE); + @touch(Server::INSTALLER_COMPLETE_FILE); $progressData = ($installId !== '') ? $state->readProgressFile($installId) : []; From 786892d44ec64295ebf5c6be5dfaa6801ad7a061 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:14:52 +0530 Subject: [PATCH 105/146] feat(mqtt): implement session-based authentication for MQTT connections --- app/init/mqtt/connection.php | 87 ++++++++++--------- .../Messaging/MessagingMqttServerTest.php | 43 +++++++++ 2 files changed, 89 insertions(+), 41 deletions(-) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index e020038054..8b6f12d079 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -34,50 +34,55 @@ return function (Container $container): void { $dbForProject = getProjectDB($project); $dbForProject->setAuthorization($authorization); - if ($authMethod === 'appwrite-jwt') { - $jwt = new JWT(System::getEnv('_APP_OPENSSL_KEY_V1'), 'HS256', 3600, 0); + switch ($authMethod) { + case 'appwrite-jwt': + $jwt = new JWT(System::getEnv('_APP_OPENSSL_KEY_V1'), 'HS256', 3600, 0); - try { - $payload = $jwt->decode($credential); - } catch (JWTException) { + try { + $payload = $jwt->decode($credential); + } catch (JWTException) { + return new User([]); + } + + $userId = $payload['userId'] ?? ''; + $sessionId = $payload['sessionId'] ?? ''; + + /** @var User $user */ + $user = $dbForProject->getDocument('users', $userId); + + if ( + $user->isEmpty() + || $user->getAttribute('status', true) === false // blocked account + || ($sessionId !== '' && !$user->sessionActive($sessionId)) + ) { + return new User([]); + } + + return $user; + + case 'appwrite-session': + $store = new Store(); + $store->decode($credential); + + $proofForToken = new Token(); + $proofForToken->setHash(new Sha()); + + /** @var User $user */ + $user = $dbForProject->getDocument('users', $store->getProperty('id', '')); + + if ( + $user->isEmpty() + || $user->getAttribute('status', true) === false // blocked account + || !$user->sessionVerify($store->getProperty('secret', ''), $proofForToken) + ) { + return new User([]); + } + + return $user; + + default: return new User([]); - } - - $userId = $payload['userId'] ?? ''; - $sessionId = $payload['sessionId'] ?? ''; - - /** @var User $user */ - $user = $dbForProject->getDocument('users', $userId); - - if ( - $user->isEmpty() - || $user->getAttribute('status', true) === false // blocked account - || ($sessionId !== '' && !$user->sessionActive($sessionId)) - ) { - return new User([]); - } - - return $user; } - - $store = new Store(); - $store->decode($credential); - - $proofForToken = new Token(); - $proofForToken->setHash(new Sha()); - - /** @var User $user */ - $user = $dbForProject->getDocument('users', $store->getProperty('id', '')); - - if ( - $user->isEmpty() - || $user->getAttribute('status', true) === false // blocked account - || !$user->sessionVerify($store->getProperty('secret', ''), $proofForToken) - ) { - return new User([]); - } - - return $user; }; $container->set('authenticator', function () use ($getProject, $getUser): callable { diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 5c6fec7bbc..9f2084f7dd 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -66,6 +66,23 @@ final class MessagingMqttServerTest extends Scope return ['userId' => $userId, 'jwt' => $jwt['body']['jwt']]; } + /** + * Create a server-side session for a user and return its credential — the base64({id, + * secret}) store blob the broker's appwrite-session auth decodes (the same value a client + * holds as its session cookie). + */ + private function createSession(string $userId): string + { + $session = $this->client->call(Client::METHOD_POST, '/users/' . $userId . '/sessions', array_merge([ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + ], $this->getHeaders())); + $this->assertEquals(201, $session['headers']['status-code']); + $this->assertNotEmpty($session['body']['secret']); + + return $session['body']['secret']; + } + public function testUnauthorizedConnectRejected(): void { $projectId = $this->getProject()['$id']; @@ -95,6 +112,32 @@ final class MessagingMqttServerTest extends Scope $subscriber->disconnect(); } + public function testSessionAuthConnect(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $userId] = $this->createUser(); + $credential = $this->createSession($userId); + + // Test for SUCCESS: a valid session credential authenticates via appwrite-session, + // the session-based analogue of the JWT auth method. + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $credential, 'e2e-session-' . $userId, cleanStart: true, authMethod: 'appwrite-session')); + $subscriber->disconnect(); + } + + public function testSessionAuthWithInvalidSecretRejected(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $userId] = $this->createUser(); + + // Test for FAILURE: a well-formed store blob with a wrong secret is refused at CONNECT + // with reason 0x87 (the session does not verify). + $credential = base64_encode((string) json_encode(['id' => $userId, 'secret' => 'not-a-real-secret'])); + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0x87, $subscriber->connect($projectId, $credential, 'e2e-badsession-' . $userId, cleanStart: true, authMethod: 'appwrite-session')); + $subscriber->disconnect(); + } + public function testSubscribeToUnknownTopicRejected(): void { $projectId = $this->getProject()['$id']; From 4a4b0fb374987a64ea3ace0ca290e8cb0d94050a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:22:51 +0530 Subject: [PATCH 106/146] feat(mqtt): add broker telemetry instruments Declare histograms for auth/connection duration and message size, counters for bytes received/sent, reauth {result}, and puback received. --- src/Appwrite/Mqtt/Metrics.php | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/Appwrite/Mqtt/Metrics.php b/src/Appwrite/Mqtt/Metrics.php index 8e329bef67..dc04f701c9 100644 --- a/src/Appwrite/Mqtt/Metrics.php +++ b/src/Appwrite/Mqtt/Metrics.php @@ -4,6 +4,7 @@ namespace Appwrite\Mqtt; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Counter; +use Utopia\Telemetry\Histogram; use Utopia\Telemetry\UpDownCounter; /** @@ -22,6 +23,13 @@ class Metrics public Counter $messagesDelivered; public Counter $messagesDropped; public Counter $messagesAcked; + public Counter $pubacksReceived; + public Counter $reauth; + public Counter $bytesReceived; + public Counter $bytesSent; + public Histogram $authDuration; + public Histogram $connectionDuration; + public Histogram $messageSize; public function __construct(Telemetry $telemetry) { @@ -32,5 +40,12 @@ class Metrics $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); $this->messagesAcked = $telemetry->createCounter('mqtt.messages.acked'); + $this->pubacksReceived = $telemetry->createCounter('mqtt.puback.received'); + $this->reauth = $telemetry->createCounter('mqtt.reauth'); + $this->bytesReceived = $telemetry->createCounter('mqtt.bytes.received', 'By'); + $this->bytesSent = $telemetry->createCounter('mqtt.bytes.sent', 'By'); + $this->authDuration = $telemetry->createHistogram('mqtt.auth.duration', 's'); + $this->connectionDuration = $telemetry->createHistogram('mqtt.connection.duration', 's'); + $this->messageSize = $telemetry->createHistogram('mqtt.message.size', 'By'); } } From b1ab5ba6fbe09bc673930610e2a5bd2dcab5ceaa Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:22:51 +0530 Subject: [PATCH 107/146] feat(mqtt): record connection duration, message size, and byte counters Stamp Connection::openedAt and record the connection lifetime on close; record the published payload size on send; count bytes in on every packet and bytes out on every reply and fan-out delivery. --- app/mqtt.php | 12 +++++++++--- src/Appwrite/Messaging/Adapter/Mqtt.php | 3 +++ src/Appwrite/Mqtt/Connection.php | 4 ++++ 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 76f72e3977..705d6bfed8 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -318,9 +318,11 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): } $effectiveQos = min($qos, $grantedQos); $packetId = $subscriber->nextPacketId(); - $server->send($fd, $subscriber->protocol >= 5 + $publish = $subscriber->protocol >= 5 ? V5::publish($topic, $message, $effectiveQos, $packetId) - : V3::publish($topic, $message, $effectiveQos, $packetId)); + : V3::publish($topic, $message, $effectiveQos, $packetId); + $server->send($fd, $publish); + $mqtt->metrics->bytesSent->add(\strlen($publish)); $mqtt->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); // Hold QoS 1 deliveries until the subscriber's PUBACK matches them back. @@ -351,13 +353,17 @@ $server->onReceive(function (int $fd, string $data) use ( $packet = Packet::parse($data); $connection = $mqtt->open($fd); + $mqtt->metrics->bytesReceived->add(\strlen($data)); + $span = Span::init('mqtt.' . $packet->name()); $span->set('mqtt.fd', $fd); $span->set('mqtt.is_broker', false); // an inbound packet from a client + $span->set('mqtt.bytes', \strlen($data)); - $reply = function (string $packet = '', bool $close = false) use ($server, $fd): void { + $reply = function (string $packet = '', bool $close = false) use ($server, $mqtt, $fd): void { if ($packet !== '') { $server->send($fd, $packet); + $mqtt->metrics->bytesSent->add(\strlen($packet)); } if ($close) { $server->close($fd); diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 45daf05e90..7551ba1f59 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -75,6 +75,7 @@ class Mqtt extends MessagingAdapter if ($connection !== null) { if ($connection->active) { $this->metrics->connectionsActive->add(-1); + $this->metrics->connectionDuration->record(microtime(true) - $connection->openedAt); } if ($connection->wheelSlot > 0) { $this->keepAlive->remove($fd, $connection->wheelSlot); @@ -140,6 +141,8 @@ class Mqtt extends MessagingAdapter $qos = $options['qos'] ?? 0; $sequence = (int) ($options['sequence'] ?? 0); + $this->metrics->messageSize->record(\strlen($message)); + foreach ($channels as $topic) { $this->metrics->messagesPublished->add(1, ['qos' => $qos]); $this->getPubSubPool()->publish(self::CHANNEL, (string) json_encode([ diff --git a/src/Appwrite/Mqtt/Connection.php b/src/Appwrite/Mqtt/Connection.php index 5f6d2a3ad1..675e5162ae 100644 --- a/src/Appwrite/Mqtt/Connection.php +++ b/src/Appwrite/Mqtt/Connection.php @@ -52,9 +52,13 @@ class Connection */ private array $inflight = []; + /** Wall-clock time (fractional unix seconds) the connection was opened, for its lifetime metric. */ + public readonly float $openedAt; + public function __construct( public readonly int $fd, ) { + $this->openedAt = microtime(true); } /** From 82aff08a758a16e75097672696efbf50ff9bf242 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:22:51 +0530 Subject: [PATCH 108/146] feat(mqtt): record auth duration, reauth, and puback metrics Time the authenticator call on CONNECT and AUTH (auth duration + span); count AUTH reauth outcomes as reauth {result}; count PUBACKs as puback received. --- src/Appwrite/Mqtt/Handlers/Auth.php | 18 ++++++++++++++---- src/Appwrite/Mqtt/Handlers/Connect.php | 4 ++++ src/Appwrite/Mqtt/Handlers/Puback.php | 1 + 3 files changed, 19 insertions(+), 4 deletions(-) diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php index e9ffc10d8e..d403b12d85 100644 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ b/src/Appwrite/Mqtt/Handlers/Auth.php @@ -2,6 +2,7 @@ namespace Appwrite\Mqtt\Handlers; +use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; use Utopia\Mqtt\Packet; @@ -9,6 +10,7 @@ use Utopia\Mqtt\Packet\V5; use Utopia\Mqtt\Properties; use Utopia\Mqtt\Property; use Utopia\Platform\Action; +use Utopia\Span\Span; class Auth extends Action { @@ -17,6 +19,7 @@ class Auth extends Action $this ->desc('Re-authenticate a live connection with a fresh credential') ->label(Dispatcher::LABEL_TYPE, Packet::AUTH) + ->inject('mqtt') ->inject('authenticator') ->inject('connection') ->inject('packet') @@ -28,7 +31,7 @@ class Auth extends Action * @param (callable(string, string, string): array)|null $authenticator * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) */ - public function action(?callable $authenticator, Connection $connection, Packet $packet, callable $reply): void + public function action(Mqtt $mqtt, ?callable $authenticator, Connection $connection, Packet $packet, callable $reply): void { $body = $packet->body; $method = ''; @@ -51,16 +54,23 @@ class Auth extends Action if ($authenticator !== null) { $projectId = $userProperties['projectId'] ?? ''; - $identity = ($projectId !== '' && $projectId === $connection->projectId) - ? $authenticator($projectId, $method, $data) - : []; + $identity = []; + if ($projectId !== '' && $projectId === $connection->projectId) { + $start = microtime(true); + $identity = $authenticator($projectId, $method, $data); + $mqtt->metrics->authDuration->record(microtime(true) - $start); + } if ($identity === []) { + $mqtt->metrics->reauth->add(1, ['result' => 'rejected']); + Span::add('mqtt.result', 'rejected'); $reply(V5::disconnect(V5::REASON_NOT_AUTHORIZED), true); return; } $connection->identity = $identity; + $mqtt->metrics->reauth->add(1, ['result' => 'success']); + Span::add('mqtt.result', 'reauthenticated'); } // Acknowledge success on the live connection with an AUTH packet that echoes diff --git a/src/Appwrite/Mqtt/Handlers/Connect.php b/src/Appwrite/Mqtt/Handlers/Connect.php index 650aef42a5..388317c0d5 100644 --- a/src/Appwrite/Mqtt/Handlers/Connect.php +++ b/src/Appwrite/Mqtt/Handlers/Connect.php @@ -66,7 +66,11 @@ class Connect extends Action // TODO: add abuse limiting keyed on the client ip. if ($authenticator !== null) { + $start = microtime(true); $identity = $authenticator($projectId, $authMethod, $authData); + $duration = microtime(true) - $start; + $mqtt->metrics->authDuration->record($duration); + Span::add('mqtt.auth.duration', $duration); if ($identity === []) { $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); diff --git a/src/Appwrite/Mqtt/Handlers/Puback.php b/src/Appwrite/Mqtt/Handlers/Puback.php index 22c037187d..b399de7558 100644 --- a/src/Appwrite/Mqtt/Handlers/Puback.php +++ b/src/Appwrite/Mqtt/Handlers/Puback.php @@ -55,6 +55,7 @@ class Puback extends Action Span::add('mqtt.topic', $delivery['topic']); Span::add('mqtt.sequence', $delivery['sequence']); $mqtt->metrics->messagesAcked->add(1); + $mqtt->metrics->pubacksReceived->add(1); // Save how far the client has caught up (the "cursor" from acknowledge), not the // sequence it just acked — so an out-of-order ack can't skip a still-unacked From d1e12320d4798fc8b99c7756c01080fe77cefd71 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:26:14 +0530 Subject: [PATCH 109/146] removed comment --- src/Appwrite/Mqtt/Handlers/Auth.php | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php index d403b12d85..c11140f3e1 100644 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ b/src/Appwrite/Mqtt/Handlers/Auth.php @@ -48,9 +48,6 @@ class Auth extends Action } // The AUTH packet re-sends projectId as a User Property. - // TODO: check the events for the reauth only refreshes - // the credential, so enforce it stays on the project resolved at CONNECT — the - // connection must not switch tenants — then verify the fresh credential. if ($authenticator !== null) { $projectId = $userProperties['projectId'] ?? ''; From 7780a94922e9f7a4976c0efefc7e8444711e306c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:45:04 +0530 Subject: [PATCH 110/146] fix(mqtt): reject a reauth that switches the authenticated user AUTH only refreshes the credential for the identity resolved at CONNECT; a resolved userId that differs from the connection's (or a failed verify) now drops the connection. Allowing the switch kept the previous user's subscriptions on the socket, leaking their fan-out to the new user and breaking PUBACK ownership. --- src/Appwrite/Mqtt/Handlers/Auth.php | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php index c11140f3e1..65a3065fab 100644 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ b/src/Appwrite/Mqtt/Handlers/Auth.php @@ -58,7 +58,11 @@ class Auth extends Action $mqtt->metrics->authDuration->record(microtime(true) - $start); } - if ($identity === []) { + // Reauth only refreshes the credential for the identity resolved at CONNECT — it + // must not switch the user (or project). Allowing a switch would keep the previous + // user's subscriptions on this connection, leaking their fan-out to the new user + // and breaking PUBACK ownership checks. A mismatch (or failure) drops the connection. + if ($identity === [] || ($identity['userId'] ?? '') !== ($connection->identity['userId'] ?? '')) { $mqtt->metrics->reauth->add(1, ['result' => 'rejected']); Span::add('mqtt.result', 'rejected'); $reply(V5::disconnect(V5::REASON_NOT_AUTHORIZED), true); From 6a55707bcf9ccabc8e7c998a1513c58a0350932d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:45:04 +0530 Subject: [PATCH 111/146] feat(mqtt): rate-limit CONNECT per user Refuse a user connecting more than 128 times per minute (Abuse + Redis time limit), gated by _APP_OPTIONS_ABUSE. Keyed on userId for now; IP-based is a follow-up once the infra surfaces the client IP to the broker. --- src/Appwrite/Mqtt/Handlers/Connect.php | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/src/Appwrite/Mqtt/Handlers/Connect.php b/src/Appwrite/Mqtt/Handlers/Connect.php index 388317c0d5..80d041b8ec 100644 --- a/src/Appwrite/Mqtt/Handlers/Connect.php +++ b/src/Appwrite/Mqtt/Handlers/Connect.php @@ -5,6 +5,8 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Utopia\Abuse\Abuse; +use Utopia\Abuse\Adapters\TimeLimit\Redis as TimeLimitRedis; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; @@ -12,6 +14,7 @@ use Utopia\Mqtt\Properties; use Utopia\Mqtt\Property; use Utopia\Platform\Action; use Utopia\Span\Span; +use Utopia\System\System; class Connect extends Action { @@ -64,7 +67,6 @@ class Connect extends Action Span::add('project.id', $projectId); Span::add('mqtt.auth_method', $authMethod); - // TODO: add abuse limiting keyed on the client ip. if ($authenticator !== null) { $start = microtime(true); $identity = $authenticator($projectId, $authMethod, $authData); @@ -81,6 +83,21 @@ class Connect extends Action $connection->identity = $identity; Span::add('user.id', $identity['userId'] ?? ''); + + // Rate-limit CONNECT per user. + // TODO: in future this will be IP based; currently keyed on userId because the + // infra does not surface the client IP to the broker. + if (System::getEnv('_APP_OPTIONS_ABUSE', 'enabled') === 'enabled') { + $timeLimit = new TimeLimitRedis('mqtt:connect:{userId}', 128, 60, getRedis()); + $timeLimit->setParam('{userId}', $identity['userId'] ?? ''); + + if ((new Abuse($timeLimit))->check()) { + $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'abuse']); + Span::add('mqtt.result', 'abuse'); + $reply($this->connack($level, false), true); + return; + } + } } // The client id can only be resolved once the identity is known. From 35b7b3872bfdf8ec21bd1a0a511ebf60841c387d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:45:04 +0530 Subject: [PATCH 112/146] feat(mqtt): enforce topic subscribe roles, QoS-aware replay, depth floor Grant a filter only if the subscriber's roles satisfy the topic's subscribe roles (empty or 'any' = open). Skip offline replay for QoS 0 subscriptions (live-only) and floor the plan replay depth at 1 so a misconfig can't disable replay. Adds an e2e for role-gated subscribe (forbidden vs owner-granted). --- src/Appwrite/Mqtt/Handlers/Subscribe.php | 45 ++++++++++++++++++- .../Messaging/MessagingMqttServerTest.php | 40 +++++++++++++++++ 2 files changed, 83 insertions(+), 2 deletions(-) diff --git a/src/Appwrite/Mqtt/Handlers/Subscribe.php b/src/Appwrite/Mqtt/Handlers/Subscribe.php index 5dde976a5d..e2bd25988b 100644 --- a/src/Appwrite/Mqtt/Handlers/Subscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Subscribe.php @@ -5,6 +5,8 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Utopia\Database\Documents\User; +use Utopia\Database\Helpers\Role; use Utopia\Database\Query; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; @@ -52,6 +54,12 @@ class Subscribe extends Action $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); $projectDB = getProjectDB($project); + // The subscriber's roles, resolved once, to enforce each topic's subscribe ACL below. + $authorization = $projectDB->getAuthorization(); + /** @var User $user */ + $user = $authorization->skip(fn () => $projectDB->getDocument('users', $connection->identity['userId'] ?? '')); + $roles = $user->getRoles($authorization); + // Parse every (filter, requested QoS) in order; the SUBACK carries one reason code // per filter in this order. Bits 0-1 of the subscription options byte are the max QoS. $filters = []; @@ -81,6 +89,7 @@ class Subscribe extends Action $granted = ''; $topicDocuments = []; // filter => topic document, reused for replay below + $grantedQosByTopic = []; // filter => granted QoS, so replay honours it below foreach ($filters as [$filter, $requestedQos]) { Span::add('mqtt.topic', $filter); @@ -98,6 +107,13 @@ class Subscribe extends Action continue; } + // The topic's subscribe roles gate who may subscribe. + if (!$this->authorizedForTopic($topicDocument->getAttribute('subscribe', []) ?? [], $roles)) { + $granted .= chr($denied); + $mqtt->metrics->subscriptions->add(1, ['result' => 'forbidden']); + continue; + } + // Requested max QoS, capped by the topic's configured QoS (null = no cap, broker max 1). $topicQos = $topicDocument->getAttribute('qos'); $grantedQos = min($requestedQos, $topicQos === null ? Packet::QOS_1 : (int) $topicQos); @@ -107,6 +123,7 @@ class Subscribe extends Action $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); $topicDocuments[$filter] = $topicDocument; + $grantedQosByTopic[$filter] = $grantedQos; } $reply( @@ -130,8 +147,8 @@ class Subscribe extends Action $expiry = 3600; } - // Replay depth comes from the user's org plan (self-hosted default; see getPlanForUser). - $maxDepth = getPlanForUser($project, $connection->identity['userId'] ?? ''); + // Replay depth comes from the user's org plan (self-hosted default; see getPlanForUser) + $maxDepth = max(1, getPlanForUser($project, $connection->identity['userId'] ?? '')); $cache = getCache(); @@ -163,6 +180,10 @@ class Subscribe extends Action } foreach ($resumeTopics as $topic) { + if (($grantedQosByTopic[$topic] ?? Packet::QOS_1) < Packet::QOS_1) { + continue; + } + $from = (int) ($cursors[$topic]['sequence'] ?? 0); $tail = $tails[$topic] ?? $from; if ($tail <= $from) { @@ -195,4 +216,24 @@ class Subscribe extends Action $cache->saveMany($cursorKey, $persist, $expiry); } } + + /** + * Whether the subscriber's roles satisfy a topic's subscribe roles. No configured roles + * means the topic is open to everyone, as does an explicit `any` role. + * + * @param array $topicRoles the topic's `subscribe` roles + * @param array $userRoles the subscriber's resolved roles + */ + private function authorizedForTopic(array $topicRoles, array $userRoles): bool + { + if ($topicRoles === []) { + return true; + } + + if (\in_array(Role::any()->toString(), $topicRoles, true)) { + return true; + } + + return \array_intersect($topicRoles, $userRoles) !== []; + } } diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php index 9f2084f7dd..fe66fea833 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Messaging/MessagingMqttServerTest.php @@ -156,6 +156,46 @@ final class MessagingMqttServerTest extends Scope } } + public function testSubscribeForbiddenByTopicRoles(): void + { + $projectId = $this->getProject()['$id']; + ['userId' => $ownerId, 'jwt' => $ownerJwt] = $this->createUser(); + ['userId' => $otherId, 'jwt' => $otherJwt] = $this->createUser(); + + $server = [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $projectId, + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]; + + // A topic only the owner may subscribe to. + $topic = $this->client->call(Client::METHOD_POST, '/messaging/topics', $server, [ + 'topicId' => ID::unique(), + 'name' => 'mqtt-restricted', + 'subscribe' => ['user:' . $ownerId], + ]); + $this->assertEquals(201, $topic['headers']['status-code']); + $topicId = $topic['body']['$id']; + + // Test for FAILURE: a user outside the topic's subscribe roles is refused (0x87). + $other = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $other->connect($projectId, $otherJwt, 'e2e-acl-other-' . $otherId, cleanStart: true)); + try { + $this->assertSame([0x87], $other->subscribe([$topicId])); + } finally { + $other->disconnect(); + } + + // Test for SUCCESS: the owner is inside the roles and is granted. + $owner = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $owner->connect($projectId, $ownerJwt, 'e2e-acl-owner-' . $ownerId, cleanStart: true)); + try { + $this->assertSame([1], $owner->subscribe([$topicId])); + } finally { + $owner->disconnect(); + } + } + public function testKeepAliveReapsSilentClient(): void { $projectId = $this->getProject()['$id']; From 24bac4e89d891de1a6e7f05355cc3fbc25f12930 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:56:31 +0530 Subject: [PATCH 113/146] fix(mqtt): don't let a bad packet crash the worker Wrap the whole onReceive lifecycle: a malformed packet or a handler failure is logged and drops only that connection, instead of bubbling up and taking down the Swoole worker (and every other connection it holds). --- app/mqtt.php | 65 +++++++++++++++++++++++++++------------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 705d6bfed8..5d3990d6a4 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -350,34 +350,38 @@ $server->onReceive(function (int $fd, string $data) use ( $dispatcher, $container ): void { - $packet = Packet::parse($data); - $connection = $mqtt->open($fd); - - $mqtt->metrics->bytesReceived->add(\strlen($data)); - - $span = Span::init('mqtt.' . $packet->name()); - $span->set('mqtt.fd', $fd); - $span->set('mqtt.is_broker', false); // an inbound packet from a client - $span->set('mqtt.bytes', \strlen($data)); - - $reply = function (string $packet = '', bool $close = false) use ($server, $mqtt, $fd): void { - if ($packet !== '') { - $server->send($fd, $packet); - $mqtt->metrics->bytesSent->add(\strlen($packet)); - } - if ($close) { - $server->close($fd); - } - }; - - // authenticator/authorizer are inherited from the global container (registered above). - $packetContainer = new Container($container); - $packetContainer->set('mqtt', fn () => $mqtt); - $packetContainer->set('connection', fn () => $connection); - $packetContainer->set('packet', fn () => $packet); - $packetContainer->set('reply', fn () => $reply); - + // The whole packet lifecycle is wrapped: a malformed packet or a handler failure must + // drop only this connection, never bubble up and take down the worker (and every other + // connection it holds). + $span = null; try { + $packet = Packet::parse($data); + $connection = $mqtt->open($fd); + + $mqtt->metrics->bytesReceived->add(\strlen($data)); + + $span = Span::init('mqtt.' . $packet->name()); + $span->set('mqtt.fd', $fd); + $span->set('mqtt.is_broker', false); // an inbound packet from a client + $span->set('mqtt.bytes', \strlen($data)); + + $reply = function (string $packet = '', bool $close = false) use ($server, $mqtt, $fd): void { + if ($packet !== '') { + $server->send($fd, $packet); + $mqtt->metrics->bytesSent->add(\strlen($packet)); + } + if ($close) { + $server->close($fd); + } + }; + + // authenticator/authorizer are inherited from the global container (registered above). + $packetContainer = new Container($container); + $packetContainer->set('mqtt', fn () => $mqtt); + $packetContainer->set('connection', fn () => $connection); + $packetContainer->set('packet', fn () => $packet); + $packetContainer->set('reply', fn () => $reply); + $dispatcher->dispatch($packetContainer, $packet->type); // Every inbound packet is liveness: push the deadline forward (O(1), no wheel touch). @@ -395,10 +399,9 @@ $server->onReceive(function (int $fd, string $data) use ( $span->set('mqtt.clean_start', $connection->cleanStart); $span->finish(); } catch (\Throwable $error) { - $span->set('project.id', $connection->projectId); - $span->set('user.id', $connection->identity['userId'] ?? ''); - $span->finish(error: $error); - throw $error; + Console::error('MQTT packet error on fd ' . $fd . ': ' . $error->getMessage()); + $span?->finish(error: $error); + $server->close($fd); } }); From 649eb7220a82a1de3d880c772851bdd7f84180df Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:56:31 +0530 Subject: [PATCH 114/146] feat(messaging): purge push ledger messages older than a week MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add deleteExpiredPushLedger to the maintenance run — the ledger only backs offline replay, whose window is capped at 7 days, so older rows can be dropped. --- src/Appwrite/Platform/Workers/Deletes.php | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/Appwrite/Platform/Workers/Deletes.php b/src/Appwrite/Platform/Workers/Deletes.php index d1282af846..bb071277f2 100644 --- a/src/Appwrite/Platform/Workers/Deletes.php +++ b/src/Appwrite/Platform/Workers/Deletes.php @@ -354,6 +354,7 @@ class Deletes extends Action $this->deleteExpiredChallenges($project, $getProjectDB); $this->deleteExpiredTransactions($project, $getProjectDB); $this->deleteExpiredPresences($project, $getProjectDB, $publisherForUsage); + $this->deleteExpiredPushLedger($project, $getProjectDB); $this->deleteOldDeployments($publisherForDeletes, $project, $getProjectDB); $this->updateProcessingMigrations($project, $getProjectDB); break; @@ -2002,6 +2003,20 @@ class Deletes extends Action }); } + private function deleteExpiredPushLedger(Document $project, callable $getProjectDB): void + { + Console::info('Delete expired push ledger messages'); + + $dbForProject = $getProjectDB($project); + $expired = DateTime::addSeconds(new \DateTime(), -1 * 60 * 60 * 24 * 7); + + $dbForProject->deleteDocuments('appwritePushLedger', [ + Query::lessThan('$createdAt', $expired), + ], onError: function (Throwable $th) { + // Swallow errors (e.g. projects without the push ledger collection). + }); + } + private function deleteExpiredPresences(Document $project, callable $getProjectDB, UsagePublisher $publisherForUsage): void { Console::info('Delete expired presences'); From 8a79082bd0b7677c9e0e12f02668acce362ae40c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:56:31 +0530 Subject: [PATCH 115/146] fix(mqtt): stop publishing the broker's plaintext port MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the 1883:1883 host mapping so the broker is only reachable over the Traefik mqtts entrypoint (:8883, TLS) — mirroring realtime's wss — never plaintext from outside. Internal callers still reach appwrite-mqtt:1883 over the network. --- docker-compose.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 49f3cb539a..f98f9e8608 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -381,8 +381,6 @@ services: - traefik.tcp.services.appwrite_mqtt.loadbalancer.server.port=1883 networks: - appwrite - ports: - - 1883:1883 environment: - _APP_ENV - _APP_WORKER_PER_CORE From 71045dab4a36a4401c3141519b47db700b9aac71 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 10:56:31 +0530 Subject: [PATCH 116/146] ci: run the MQTT e2e in a dedicated broker lane Add a Tests / E2E / MQTT job that boots the stack, waits for the broker, and runs the mqtt group; exclude that group from the general service lanes so the broker-dependent tests only run where the broker is guaranteed up. --- .github/workflows/ci.yml | 67 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f3c96096c4..031873af19 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -419,6 +419,71 @@ jobs: echo "=== Appwrite Logs ===" docker compose logs --timestamps + e2e_mqtt: + name: Tests / E2E / MQTT + runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64/volume=60g/spot=price-capacity-optimized/retry=when-interrupted/extras=otel+ecr-cache + timeout-minutes: 15 + needs: build + permissions: + contents: read + packages: read + env: + COMPOSE_PROFILES: '' + steps: + - name: checkout + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Login to Docker Hub + if: ${{ env.DOCKERHUB_AUTH_AVAILABLE == 'true' }} + uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0 + with: + username: ${{ vars.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + + - parallel: + - name: Pull Docker Image + run: | + docker pull ${{ env.RUNS_ON_ECR_CACHE }}:${{ env.IMAGE }}-${{ github.sha }} + docker tag ${{ env.RUNS_ON_ECR_CACHE }}:${{ env.IMAGE }}-${{ github.sha }} ${{ env.IMAGE }} + + - name: Pull Docker Compose images + timeout-minutes: 5 + run: | + for attempt in 1 2 3; do + if docker compose pull --quiet --ignore-buildable; then + break + elif [ "$attempt" -eq 3 ]; then + echo "::error::docker compose pull failed after 3 attempts; aborting" + exit 1 + fi + echo "::warning::docker compose pull failed (attempt ${attempt}/3); retrying in 15s" + sleep 15 + done + + - name: Load and Start Appwrite + timeout-minutes: 5 + run: docker compose up -d --quiet-pull --wait + + - name: Wait for MQTT broker + timeout-minutes: 3 + run: | + while ! docker logs appwrite-mqtt 2>&1 | grep -q "MQTT broker started"; do + echo "Waiting for the MQTT broker to come online" + sleep 1 + done + + - name: Run MQTT Tests + timeout-minutes: 15 + run: >- + docker compose exec -T + appwrite test /usr/src/code/tests/e2e/Services/Messaging/MessagingMqttServerTest.php --group mqtt + + - name: Failure Logs + if: failure() + run: | + echo "=== Appwrite Logs ===" + docker compose logs --timestamps + e2e_service: name: Tests / E2E / ${{ matrix.database }} (${{ matrix.mode }}) / ${{ matrix.service.name }} runs-on: ${{ matrix.service.runner }} @@ -576,7 +641,7 @@ jobs: -e _APP_E2E_RESPONSE_FORMAT="${{ github.event.inputs.response_format }}" \ -e _TESTS_OAUTH2_GITHUB_CLIENT_ID="${{ secrets.TESTS_OAUTH2_GITHUB_CLIENT_ID }}" \ -e _TESTS_OAUTH2_GITHUB_CLIENT_SECRET="${{ secrets.TESTS_OAUTH2_GITHUB_CLIENT_SECRET }}" \ - appwrite vendor/bin/paratest --processes "$PARATEST_PROCESSES" $FUNCTIONAL_FLAG "$SERVICE_PATH" --exclude-group abuseEnabled --exclude-group screenshots --exclude-group antivirus --log-junit tests/e2e/Services/${{ matrix.service.name }}/junit.xml + appwrite vendor/bin/paratest --processes "$PARATEST_PROCESSES" $FUNCTIONAL_FLAG "$SERVICE_PATH" --exclude-group abuseEnabled --exclude-group screenshots --exclude-group antivirus --exclude-group mqtt --log-junit tests/e2e/Services/${{ matrix.service.name }}/junit.xml - name: Failure Logs if: failure() From 20755051a3aa6327770d08e2c11e6343752daac9 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 17:52:24 +0530 Subject: [PATCH 117/146] docs(mqtt): explain QoS levels and the push ledger --- app/config/collections/common.php | 4 +++- .../Platform/Modules/Messaging/Http/Topics/Create.php | 2 +- .../Platform/Modules/Messaging/Http/Topics/Update.php | 2 +- src/Appwrite/Platform/Workers/Deletes.php | 6 ++++++ 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/app/config/collections/common.php b/app/config/collections/common.php index e4d1c1c3c4..83e987fbd5 100644 --- a/app/config/collections/common.php +++ b/app/config/collections/common.php @@ -2395,7 +2395,9 @@ return [ 'array' => false, 'filters' => [], ], - // null lets the subscriber choose. + // MQTT quality of service for delivery on this topic: 0 is fire-and-forget + // (only clients connected at publish time), 1 persists each message and replays + // it when a client reconnects unacknowledged. null lets the subscriber choose. [ '$id' => ID::custom('qos'), 'type' => Database::VAR_INTEGER, diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php index e527881c83..81b390cdbb 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Create.php @@ -58,7 +58,7 @@ class Create extends Action ->param('topicId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Topic ID. Choose a custom Topic ID or a new Topic ID.', false, ['dbForProject']) ->param('name', '', new Text(128), 'Topic Name.') ->param('subscribe', [Role::users()], new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE), 'An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true) - ->param('qos', null, new Nullable(new Range(0, 1)), 'QoS for MQTT delivery on this topic (0 or 1). Null lets the subscriber choose.', true) + ->param('qos', null, new Nullable(new Range(0, 1)), 'MQTT delivery quality of service for this topic. 0 is fire-and-forget (delivered only to clients connected at publish time). 1 persists each message and replays it when a client reconnects without having acknowledged it. Null lets the subscriber choose.', true) ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Message retention in seconds for offline delivery. Max 7 days (604800).', true) ->inject('queueForEvents') ->inject('dbForProject') diff --git a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php index 515611c975..7138d8e0c5 100644 --- a/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php +++ b/src/Appwrite/Platform/Modules/Messaging/Http/Topics/Update.php @@ -55,7 +55,7 @@ class Update extends Action ->param('topicId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Topic ID.', false, ['dbForProject']) ->param('name', null, new Nullable(new Text(128)), 'Topic Name.', true) ->param('subscribe', null, new Nullable(new Roles(APP_LIMIT_ARRAY_PARAMS_SIZE)), 'An array of role strings with subscribe permission. By default all users are granted with any subscribe permission. [learn more about roles](https://appwrite.io/docs/permissions#permission-roles). Maximum of ' . APP_LIMIT_ARRAY_PARAMS_SIZE . ' roles are allowed, each 64 characters long.', true) - ->param('qos', null, new Nullable(new Range(0, 1)), 'QoS for MQTT delivery on this topic (0 or 1). Null lets the subscriber choose.', true) + ->param('qos', null, new Nullable(new Range(0, 1)), 'MQTT delivery quality of service for this topic. 0 is fire-and-forget (delivered only to clients connected at publish time). 1 persists each message and replays it when a client reconnects without having acknowledged it. Null lets the subscriber choose.', true) ->param('expiry', null, new Nullable(new Range(0, 604800)), 'Message retention in seconds for offline delivery. Max 7 days (604800).', true) ->inject('request') ->inject('queueForEvents') diff --git a/src/Appwrite/Platform/Workers/Deletes.php b/src/Appwrite/Platform/Workers/Deletes.php index bb071277f2..a1649cf442 100644 --- a/src/Appwrite/Platform/Workers/Deletes.php +++ b/src/Appwrite/Platform/Workers/Deletes.php @@ -2003,6 +2003,12 @@ class Deletes extends Action }); } + /** + * The push ledger (appwritePushLedger) is the append-only record of QoS 1 push + * messages the MQTT broker keeps so it can replay any a client missed while offline. + * Replay only ever reaches back one week, so entries older than that are dead weight + * and are pruned here, mirroring how expired presences are cleaned up. + */ private function deleteExpiredPushLedger(Document $project, callable $getProjectDB): void { Console::info('Delete expired push ledger messages'); From 3a5e4de9a776577b096394284d4dd57a6b35f98f Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 17:52:48 +0530 Subject: [PATCH 118/146] refactor(mqtt): give handlers a typed Response instead of a reply callable --- app/mqtt.php | 17 +++------- src/Appwrite/Mqtt/Handlers/Auth.php | 11 +++--- src/Appwrite/Mqtt/Handlers/Connect.php | 14 ++++---- src/Appwrite/Mqtt/Handlers/Disconnect.php | 10 +++--- src/Appwrite/Mqtt/Handlers/Ping.php | 10 +++--- src/Appwrite/Mqtt/Handlers/Puback.php | 8 +++-- src/Appwrite/Mqtt/Handlers/Subscribe.php | 11 +++--- src/Appwrite/Mqtt/Handlers/Unsubscribe.php | 11 +++--- src/Appwrite/Mqtt/Response.php | 39 ++++++++++++++++++++++ 9 files changed, 80 insertions(+), 51 deletions(-) create mode 100644 src/Appwrite/Mqtt/Response.php diff --git a/app/mqtt.php b/app/mqtt.php index 5d3990d6a4..0ec44eb34d 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -10,6 +10,7 @@ use Appwrite\Mqtt\Handlers\Puback as PubackHandler; use Appwrite\Mqtt\Handlers\Subscribe as SubscribeHandler; use Appwrite\Mqtt\Handlers\Unsubscribe as UnsubscribeHandler; use Appwrite\Mqtt\KeepAlive; +use Appwrite\Mqtt\Response; use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Appwrite\Utopia\Database\Documents\User; use Swoole\Coroutine; @@ -44,7 +45,7 @@ if (System::getEnv('_APP_EDITION', 'self-hosted') === 'self-hosted') { /** @var Registry $register */ $register = $GLOBALS['register'] ?? throw new \RuntimeException('Registry not initialized'); -$registerMqttConnectionResources ??= require __DIR__ . '/init/mqtt/connection.php'; +$registerConnectionResources ??= require __DIR__ . '/init/mqtt/connection.php'; Runtime::enableCoroutine(SWOOLE_HOOK_ALL); @@ -224,7 +225,7 @@ if (!function_exists('getRedis')) { // Register the CONNECT authenticator and per-SUBSCRIBE authorizer on the global container // (see app/init/mqtt/connection.php). The CONNECT/SUBSCRIBE handlers inject them by name, // resolved through the packet container that inherits from this one. -$registerMqttConnectionResources($container); +$registerConnectionResources($container); /** @var \Utopia\Telemetry\Adapter $telemetry */ $telemetry = $container->get('telemetry'); @@ -365,22 +366,14 @@ $server->onReceive(function (int $fd, string $data) use ( $span->set('mqtt.is_broker', false); // an inbound packet from a client $span->set('mqtt.bytes', \strlen($data)); - $reply = function (string $packet = '', bool $close = false) use ($server, $mqtt, $fd): void { - if ($packet !== '') { - $server->send($fd, $packet); - $mqtt->metrics->bytesSent->add(\strlen($packet)); - } - if ($close) { - $server->close($fd); - } - }; + $response = new Response($server, $fd, $mqtt->metrics->bytesSent); // authenticator/authorizer are inherited from the global container (registered above). $packetContainer = new Container($container); $packetContainer->set('mqtt', fn () => $mqtt); $packetContainer->set('connection', fn () => $connection); $packetContainer->set('packet', fn () => $packet); - $packetContainer->set('reply', fn () => $reply); + $packetContainer->set('response', fn () => $response); $dispatcher->dispatch($packetContainer, $packet->type); diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php index 65a3065fab..6f6a873aac 100644 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ b/src/Appwrite/Mqtt/Handlers/Auth.php @@ -5,6 +5,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V5; use Utopia\Mqtt\Properties; @@ -23,15 +24,14 @@ class Auth extends Action ->inject('authenticator') ->inject('connection') ->inject('packet') - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } /** * @param (callable(string, string, string): array)|null $authenticator - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) */ - public function action(Mqtt $mqtt, ?callable $authenticator, Connection $connection, Packet $packet, callable $reply): void + public function action(Mqtt $mqtt, ?callable $authenticator, Connection $connection, Packet $packet, Response $response): void { $body = $packet->body; $method = ''; @@ -65,7 +65,8 @@ class Auth extends Action if ($identity === [] || ($identity['userId'] ?? '') !== ($connection->identity['userId'] ?? '')) { $mqtt->metrics->reauth->add(1, ['result' => 'rejected']); Span::add('mqtt.result', 'rejected'); - $reply(V5::disconnect(V5::REASON_NOT_AUTHORIZED), true); + $response->send(V5::disconnect(V5::REASON_NOT_AUTHORIZED)); + $response->close(); return; } @@ -80,6 +81,6 @@ class Auth extends Action if ($method !== '') { $properties->add(new Property(Property::AUTHENTICATION_METHOD, $method)); } - $reply(V5::auth(V5::AUTH_SUCCESS, $properties), false); + $response->send(V5::auth(V5::AUTH_SUCCESS, $properties)); } } diff --git a/src/Appwrite/Mqtt/Handlers/Connect.php b/src/Appwrite/Mqtt/Handlers/Connect.php index 80d041b8ec..2c4e858933 100644 --- a/src/Appwrite/Mqtt/Handlers/Connect.php +++ b/src/Appwrite/Mqtt/Handlers/Connect.php @@ -5,6 +5,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Utopia\Abuse\Abuse; use Utopia\Abuse\Adapters\TimeLimit\Redis as TimeLimitRedis; use Utopia\Mqtt\Packet; @@ -27,15 +28,14 @@ class Connect extends Action ->inject('mqtt') ->inject('connection') ->inject('packet') - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } /** * @param (callable(string, string, string): array)|null $authenticator - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) */ - public function action(?callable $authenticator, Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + public function action(?callable $authenticator, Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void { $body = $packet->body; $offset = 0; @@ -77,7 +77,8 @@ class Connect extends Action if ($identity === []) { $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); Span::add('mqtt.result', 'rejected'); - $reply($this->connack($level, false), true); + $response->send($this->connack($level, false)); + $response->close(); return; } @@ -94,7 +95,8 @@ class Connect extends Action if ((new Abuse($timeLimit))->check()) { $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'abuse']); Span::add('mqtt.result', 'abuse'); - $reply($this->connack($level, false), true); + $response->send($this->connack($level, false)); + $response->close(); return; } } @@ -107,7 +109,7 @@ class Connect extends Action $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); $mqtt->metrics->connectionsActive->add(1); $connection->active = true; - $reply($this->connack($level, true), false); + $response->send($this->connack($level, true)); } /** CONNACK, with the acknowledgement code in each version's own vocabulary. */ diff --git a/src/Appwrite/Mqtt/Handlers/Disconnect.php b/src/Appwrite/Mqtt/Handlers/Disconnect.php index d5edd4bc2b..e9ab621e69 100644 --- a/src/Appwrite/Mqtt/Handlers/Disconnect.php +++ b/src/Appwrite/Mqtt/Handlers/Disconnect.php @@ -3,6 +3,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Utopia\Mqtt\Packet; use Utopia\Platform\Action; @@ -13,15 +14,12 @@ class Disconnect extends Action $this ->desc('Close the connection on client request') ->label(Dispatcher::LABEL_TYPE, Packet::DISCONNECT) - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } - /** - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) - */ - public function action(callable $reply): void + public function action(Response $response): void { - $reply('', true); + $response->close(); } } diff --git a/src/Appwrite/Mqtt/Handlers/Ping.php b/src/Appwrite/Mqtt/Handlers/Ping.php index bf627b5c1b..fded3af7af 100644 --- a/src/Appwrite/Mqtt/Handlers/Ping.php +++ b/src/Appwrite/Mqtt/Handlers/Ping.php @@ -3,6 +3,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Utopia\Mqtt\Packet; use Utopia\Platform\Action; @@ -13,15 +14,12 @@ class Ping extends Action $this ->desc('Reply to a client heartbeat') ->label(Dispatcher::LABEL_TYPE, Packet::PINGREQ) - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } - /** - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) - */ - public function action(callable $reply): void + public function action(Response $response): void { - $reply(Packet::pingresp(), false); + $response->send(Packet::pingresp()); } } diff --git a/src/Appwrite/Mqtt/Handlers/Puback.php b/src/Appwrite/Mqtt/Handlers/Puback.php index b399de7558..ffd2cbbf28 100644 --- a/src/Appwrite/Mqtt/Handlers/Puback.php +++ b/src/Appwrite/Mqtt/Handlers/Puback.php @@ -5,6 +5,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V5; use Utopia\Platform\Action; @@ -26,11 +27,11 @@ class Puback extends Action ->inject('mqtt') ->inject('connection') ->inject('packet') - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } - public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + public function action(Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void { $body = $packet->body; @@ -40,7 +41,8 @@ class Puback extends Action $connectionMetdata = $mqtt->getConnection($connection->fd); if ($connectionMetdata['userId'] !== $connection->identity['userId'] || $connectionMetdata['projectId'] !== $connection->projectId) { - $reply(V5::disconnect(V5::REASON_NOT_AUTHORIZED), true); + $response->send(V5::disconnect(V5::REASON_NOT_AUTHORIZED)); + $response->close(); return; } diff --git a/src/Appwrite/Mqtt/Handlers/Subscribe.php b/src/Appwrite/Mqtt/Handlers/Subscribe.php index e2bd25988b..592347f0f0 100644 --- a/src/Appwrite/Mqtt/Handlers/Subscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Subscribe.php @@ -5,6 +5,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Appwrite\Utopia\Database\Documents\User; use Utopia\Database\Helpers\Role; use Utopia\Database\Query; @@ -26,15 +27,14 @@ class Subscribe extends Action ->inject('mqtt') ->inject('connection') ->inject('packet') - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } /** * @param (callable(array, string): bool)|null $authorizer - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) */ - public function action(?callable $authorizer, Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + public function action(?callable $authorizer, Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void { $body = $packet->body; $offset = 0; @@ -126,11 +126,10 @@ class Subscribe extends Action $grantedQosByTopic[$filter] = $grantedQos; } - $reply( + $response->send( $connection->protocol >= 5 ? V5::suback($packetId, $granted) : V3::suback($packetId, $granted), - false, ); if ($topicDocuments === []) { @@ -207,7 +206,7 @@ class Subscribe extends Action $publish = $connection->protocol >= 5 ? V5::publish($topic, $data, Packet::QOS_1, $packetId, dup: true) : V3::publish($topic, $data, Packet::QOS_1, $packetId, dup: true); - $reply($publish, false); + $response->send($publish); $connection->track($packetId, $topic, (int) $message->getAttribute('sequence')); } } diff --git a/src/Appwrite/Mqtt/Handlers/Unsubscribe.php b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php index 0eca309eb5..c0e25600c5 100644 --- a/src/Appwrite/Mqtt/Handlers/Unsubscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php @@ -5,6 +5,7 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; +use Appwrite\Mqtt\Response; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; @@ -21,14 +22,11 @@ class Unsubscribe extends Action ->inject('mqtt') ->inject('connection') ->inject('packet') - ->inject('reply') + ->inject('response') ->callback($this->action(...)); } - /** - * @param callable(string, bool): void $reply writes a packet back to this connection (and optionally closes it) - */ - public function action(Mqtt $mqtt, Connection $connection, Packet $packet, callable $reply): void + public function action(Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void { $body = $packet->body; $offset = 0; @@ -48,11 +46,10 @@ class Unsubscribe extends Action } // 5.0 carries a Success reason code per filter; 3.1.1 UNSUBACK is bare. - $reply( + $response->send( $connection->protocol >= 5 ? V5::unsuback($packetId, $count) : V3::unsuback($packetId), - false, ); } } diff --git a/src/Appwrite/Mqtt/Response.php b/src/Appwrite/Mqtt/Response.php new file mode 100644 index 0000000000..fee6279fde --- /dev/null +++ b/src/Appwrite/Mqtt/Response.php @@ -0,0 +1,39 @@ +server->send($this->fd, $packet); + $this->bytesSent->add(\strlen($packet)); + } + + /** Close the connection. */ + public function close(): void + { + $this->server->close($this->fd); + } +} From 91eea92e352c05f05ab50e3bf826c7e6c86d32d0 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 17:52:59 +0530 Subject: [PATCH 119/146] refactor(mqtt): make the packet dispatcher immutable --- app/mqtt.php | 17 +++++++++-------- src/Appwrite/Mqtt/Dispatcher.php | 29 ++++++++++++++++++++--------- 2 files changed, 29 insertions(+), 17 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 0ec44eb34d..4164775cd8 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -238,14 +238,15 @@ $server->error(fn (\Throwable $error, string $action) => Console::error("MQTT {$ $mqtt = new Mqtt($telemetry); -$dispatcher = (new Dispatcher()) - ->addHandler(new ConnectHandler()) - ->addHandler(new SubscribeHandler()) - ->addHandler(new UnsubscribeHandler()) - ->addHandler(new PubackHandler()) - ->addHandler(new AuthHandler()) - ->addHandler(new PingHandler()) - ->addHandler(new DisconnectHandler()); +$dispatcher = new Dispatcher([ + new ConnectHandler(), + new SubscribeHandler(), + new UnsubscribeHandler(), + new PubackHandler(), + new AuthHandler(), + new PingHandler(), + new DisconnectHandler(), +]); $server->onStart(fn () => print("MQTT broker started\n")); diff --git a/src/Appwrite/Mqtt/Dispatcher.php b/src/Appwrite/Mqtt/Dispatcher.php index 7e77a55401..17fb6ac79b 100644 --- a/src/Appwrite/Mqtt/Dispatcher.php +++ b/src/Appwrite/Mqtt/Dispatcher.php @@ -8,25 +8,36 @@ use Utopia\Platform\Action; /** * Routes a decoded MQTT packet to the handler registered for its control-packet - * type, resolving the handler's injections from the per-packet container. Mirrors - * the realtime message dispatcher (src/Appwrite/Realtime/Message/Dispatcher.php), - * keyed on the binary packet type instead of a JSON message type. + * type, resolving the handler's injections from the per-packet container, keyed on + * the binary packet type. + * + * The handler set is fixed at construction and never mutated afterwards: there is no + * addHandler/removeHandler. In a coroutine broker a single dispatcher is shared across + * every connection and packet, so a mutable registry would leak handler state across + * requests and invite ad-hoc reconfiguration; an immutable table keeps dispatch a pure + * lookup. */ class Dispatcher { public const LABEL_TYPE = 'packetType'; /** @var array */ - private array $handlers = []; + private readonly array $handlers; - public function addHandler(Action $handler): self + /** + * @param array $handlers each labelled with its packet type (self::LABEL_TYPE) + */ + public function __construct(array $handlers) { - $type = $handler->getLabels()[self::LABEL_TYPE] - ?? throw new Exception(Exception::GENERAL_SERVER_ERROR, 'MQTT packet handler is missing the packetType label.'); + $table = []; + foreach ($handlers as $handler) { + $type = $handler->getLabels()[self::LABEL_TYPE] + ?? throw new Exception(Exception::GENERAL_SERVER_ERROR, 'MQTT packet handler is missing the packetType label.'); - $this->handlers[$type] = $handler; + $table[$type] = $handler; + } - return $this; + $this->handlers = $table; } /** From ccac32aec872cc5a34ff4773905728a19e25a2da Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 18:01:38 +0530 Subject: [PATCH 120/146] refactor(mqtt): fold telemetry instruments into the adapter --- app/mqtt.php | 10 ++-- src/Appwrite/Messaging/Adapter/Mqtt.php | 64 +++++++++++++++++------- src/Appwrite/Mqtt/Handlers/Auth.php | 6 +-- src/Appwrite/Mqtt/Handlers/Connect.php | 10 ++-- src/Appwrite/Mqtt/Handlers/Puback.php | 4 +- src/Appwrite/Mqtt/Handlers/Subscribe.php | 8 +-- src/Appwrite/Mqtt/Metrics.php | 51 ------------------- 7 files changed, 66 insertions(+), 87 deletions(-) delete mode 100644 src/Appwrite/Mqtt/Metrics.php diff --git a/app/mqtt.php b/app/mqtt.php index 4164775cd8..dd68ef1823 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -308,7 +308,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): if ($subscribers === []) { // No local subscriber on this worker; with multiple workers this // counts per-worker rather than as a global drop. - $mqtt->metrics->messagesDropped->add(1, ['reason' => 'no_subscriber']); + $mqtt->messagesDropped->add(1, ['reason' => 'no_subscriber']); $span->finish(); return; } @@ -324,8 +324,8 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): ? V5::publish($topic, $message, $effectiveQos, $packetId) : V3::publish($topic, $message, $effectiveQos, $packetId); $server->send($fd, $publish); - $mqtt->metrics->bytesSent->add(\strlen($publish)); - $mqtt->metrics->messagesDelivered->add(1, ['qos' => $effectiveQos]); + $mqtt->bytesSent->add(\strlen($publish)); + $mqtt->messagesDelivered->add(1, ['qos' => $effectiveQos]); // Hold QoS 1 deliveries until the subscriber's PUBACK matches them back. if ($effectiveQos === 1) { @@ -360,14 +360,14 @@ $server->onReceive(function (int $fd, string $data) use ( $packet = Packet::parse($data); $connection = $mqtt->open($fd); - $mqtt->metrics->bytesReceived->add(\strlen($data)); + $mqtt->bytesReceived->add(\strlen($data)); $span = Span::init('mqtt.' . $packet->name()); $span->set('mqtt.fd', $fd); $span->set('mqtt.is_broker', false); // an inbound packet from a client $span->set('mqtt.bytes', \strlen($data)); - $response = new Response($server, $fd, $mqtt->metrics->bytesSent); + $response = new Response($server, $fd, $mqtt->bytesSent); // authenticator/authorizer are inherited from the global container (registered above). $packetContainer = new Container($container); diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 7551ba1f59..4a6842c2b1 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -5,11 +5,13 @@ namespace Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter as MessagingAdapter; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\KeepAlive; -use Appwrite\Mqtt\Metrics; use Appwrite\Mqtt\SubscriptionStore; use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Utopia\Mqtt\Packet; use Utopia\Telemetry\Adapter as Telemetry; +use Utopia\Telemetry\Counter; +use Utopia\Telemetry\Histogram; +use Utopia\Telemetry\UpDownCounter; class Mqtt extends MessagingAdapter { @@ -24,19 +26,47 @@ class Mqtt extends MessagingAdapter */ public array $connections = []; - /** Telemetry instruments the handlers record connection and delivery outcomes on. */ - public readonly Metrics $metrics; + // Telemetry instruments the broker records connection and delivery outcomes on + // (accepted/rejected, granted/denied, delivered/dropped). A no-op telemetry adapter + // yields no-op instruments, so the broker runs untelemetered under raw protocol tests. + public readonly Counter $connectionsOpened; + public readonly UpDownCounter $connectionsActive; + public readonly Counter $subscriptions; + public readonly Counter $messagesPublished; + public readonly Counter $messagesDelivered; + public readonly Counter $messagesDropped; + public readonly Counter $messagesAcked; + public readonly Counter $pubacksReceived; + public readonly Counter $reauth; + public readonly Counter $bytesReceived; + public readonly Counter $bytesSent; + public readonly Histogram $authDuration; + public readonly Histogram $connectionDuration; + public readonly Histogram $messageSize; /** Keep-alive reaper wheel: connections register their deadline here, the tick drains it. */ public readonly KeepAlive $keepAlive; - private ?SubscriptionStore $subscriptions = null; + private ?SubscriptionStore $subscriptionStore = null; private ?PubSubPool $pubSubPool = null; public function __construct(Telemetry $telemetry) { - $this->metrics = new Metrics($telemetry); + $this->connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); + $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); + $this->subscriptions = $telemetry->createCounter('mqtt.subscriptions'); + $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); + $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); + $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); + $this->messagesAcked = $telemetry->createCounter('mqtt.messages.acked'); + $this->pubacksReceived = $telemetry->createCounter('mqtt.puback.received'); + $this->reauth = $telemetry->createCounter('mqtt.reauth'); + $this->bytesReceived = $telemetry->createCounter('mqtt.bytes.received', 'By'); + $this->bytesSent = $telemetry->createCounter('mqtt.bytes.sent', 'By'); + $this->authDuration = $telemetry->createHistogram('mqtt.auth.duration', 's'); + $this->connectionDuration = $telemetry->createHistogram('mqtt.connection.duration', 's'); + $this->messageSize = $telemetry->createHistogram('mqtt.message.size', 'By'); $this->keepAlive = new KeepAlive(); } @@ -44,9 +74,9 @@ class Mqtt extends MessagingAdapter * The subscription index, created lazily so the adapter owns it rather than * receiving it — the in-memory tree has no external dependency to wire in. */ - private function subscriptions(): SubscriptionStore + private function subscriptionStore(): SubscriptionStore { - return $this->subscriptions ??= new SubscriptionStore(); + return $this->subscriptionStore ??= new SubscriptionStore(); } private function getPubSubPool(): PubSubPool @@ -74,8 +104,8 @@ class Mqtt extends MessagingAdapter $connection = $this->connections[$fd] ?? null; if ($connection !== null) { if ($connection->active) { - $this->metrics->connectionsActive->add(-1); - $this->metrics->connectionDuration->record(microtime(true) - $connection->openedAt); + $this->connectionsActive->add(-1); + $this->connectionDuration->record(microtime(true) - $connection->openedAt); } if ($connection->wheelSlot > 0) { $this->keepAlive->remove($fd, $connection->wheelSlot); @@ -102,7 +132,7 @@ class Mqtt extends MessagingAdapter $userId = $this->connections[$identifier]->identity['userId'] ?? ''; foreach ($channels as $topic) { - $this->subscriptions()->subscribe( + $this->subscriptionStore()->subscribe( $projectId, $userId, $topic, @@ -115,7 +145,7 @@ class Mqtt extends MessagingAdapter /** Remove every subscription for a connection (used on close). */ public function unsubscribe(mixed $identifier): void { - $this->subscriptions()->close($identifier); + $this->subscriptionStore()->close($identifier); } /** @@ -141,10 +171,10 @@ class Mqtt extends MessagingAdapter $qos = $options['qos'] ?? 0; $sequence = (int) ($options['sequence'] ?? 0); - $this->metrics->messageSize->record(\strlen($message)); + $this->messageSize->record(\strlen($message)); foreach ($channels as $topic) { - $this->metrics->messagesPublished->add(1, ['qos' => $qos]); + $this->messagesPublished->add(1, ['qos' => $qos]); $this->getPubSubPool()->publish(self::CHANNEL, (string) json_encode([ 'project' => $projectId, 'topic' => $topic, @@ -158,7 +188,7 @@ class Mqtt extends MessagingAdapter /** Remove a single topic subscription (MQTT UNSUBSCRIBE). */ public function unsubscribeSubscription(int $fd, string $topic): void { - $this->subscriptions()->unsubscribe($topic, $fd); + $this->subscriptionStore()->unsubscribe($topic, $fd); } /** @@ -168,12 +198,12 @@ class Mqtt extends MessagingAdapter */ public function getSubscribers(string $projectId, string $topic): array { - return $this->subscriptions()->getSubscribers($projectId, $topic); + return $this->subscriptionStore()->getSubscribers($projectId, $topic); } public function hasSubscriber(string $projectId, string $topic): bool { - return $this->subscriptions()->getSubscribers($projectId, $topic) !== []; + return $this->subscriptionStore()->getSubscribers($projectId, $topic) !== []; } /** @@ -185,6 +215,6 @@ class Mqtt extends MessagingAdapter */ public function getConnection(int $fd): ?array { - return $this->subscriptions()->getConnection($fd); + return $this->subscriptionStore()->getConnection($fd); } } diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php index 6f6a873aac..99e5243ff8 100644 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ b/src/Appwrite/Mqtt/Handlers/Auth.php @@ -55,7 +55,7 @@ class Auth extends Action if ($projectId !== '' && $projectId === $connection->projectId) { $start = microtime(true); $identity = $authenticator($projectId, $method, $data); - $mqtt->metrics->authDuration->record(microtime(true) - $start); + $mqtt->authDuration->record(microtime(true) - $start); } // Reauth only refreshes the credential for the identity resolved at CONNECT — it @@ -63,7 +63,7 @@ class Auth extends Action // user's subscriptions on this connection, leaking their fan-out to the new user // and breaking PUBACK ownership checks. A mismatch (or failure) drops the connection. if ($identity === [] || ($identity['userId'] ?? '') !== ($connection->identity['userId'] ?? '')) { - $mqtt->metrics->reauth->add(1, ['result' => 'rejected']); + $mqtt->reauth->add(1, ['result' => 'rejected']); Span::add('mqtt.result', 'rejected'); $response->send(V5::disconnect(V5::REASON_NOT_AUTHORIZED)); $response->close(); @@ -71,7 +71,7 @@ class Auth extends Action } $connection->identity = $identity; - $mqtt->metrics->reauth->add(1, ['result' => 'success']); + $mqtt->reauth->add(1, ['result' => 'success']); Span::add('mqtt.result', 'reauthenticated'); } diff --git a/src/Appwrite/Mqtt/Handlers/Connect.php b/src/Appwrite/Mqtt/Handlers/Connect.php index 2c4e858933..503bfbf134 100644 --- a/src/Appwrite/Mqtt/Handlers/Connect.php +++ b/src/Appwrite/Mqtt/Handlers/Connect.php @@ -71,11 +71,11 @@ class Connect extends Action $start = microtime(true); $identity = $authenticator($projectId, $authMethod, $authData); $duration = microtime(true) - $start; - $mqtt->metrics->authDuration->record($duration); + $mqtt->authDuration->record($duration); Span::add('mqtt.auth.duration', $duration); if ($identity === []) { - $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); + $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); Span::add('mqtt.result', 'rejected'); $response->send($this->connack($level, false)); $response->close(); @@ -93,7 +93,7 @@ class Connect extends Action $timeLimit->setParam('{userId}', $identity['userId'] ?? ''); if ((new Abuse($timeLimit))->check()) { - $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'abuse']); + $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'abuse']); Span::add('mqtt.result', 'abuse'); $response->send($this->connack($level, false)); $response->close(); @@ -106,8 +106,8 @@ class Connect extends Action $connection->setClientId(Packet::getClientId($body)); Span::add('mqtt.client_id', $connection->getClientId()); - $mqtt->metrics->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); - $mqtt->metrics->connectionsActive->add(1); + $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); + $mqtt->connectionsActive->add(1); $connection->active = true; $response->send($this->connack($level, true)); } diff --git a/src/Appwrite/Mqtt/Handlers/Puback.php b/src/Appwrite/Mqtt/Handlers/Puback.php index ffd2cbbf28..8e2c7c0c51 100644 --- a/src/Appwrite/Mqtt/Handlers/Puback.php +++ b/src/Appwrite/Mqtt/Handlers/Puback.php @@ -56,8 +56,8 @@ class Puback extends Action Span::add('mqtt.topic', $delivery['topic']); Span::add('mqtt.sequence', $delivery['sequence']); - $mqtt->metrics->messagesAcked->add(1); - $mqtt->metrics->pubacksReceived->add(1); + $mqtt->messagesAcked->add(1); + $mqtt->pubacksReceived->add(1); // Save how far the client has caught up (the "cursor" from acknowledge), not the // sequence it just acked — so an out-of-order ack can't skip a still-unacked diff --git a/src/Appwrite/Mqtt/Handlers/Subscribe.php b/src/Appwrite/Mqtt/Handlers/Subscribe.php index 592347f0f0..bac91501ce 100644 --- a/src/Appwrite/Mqtt/Handlers/Subscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Subscribe.php @@ -95,7 +95,7 @@ class Subscribe extends Action if (!isset($allowed[$filter])) { $granted .= chr($denied); - $mqtt->metrics->subscriptions->add(1, ['result' => 'denied']); + $mqtt->subscriptions->add(1, ['result' => 'denied']); continue; } @@ -103,14 +103,14 @@ class Subscribe extends Action $topicDocument = $topicsById[$filter] ?? null; if ($topicDocument === null) { $granted .= chr($denied); - $mqtt->metrics->subscriptions->add(1, ['result' => 'unknown']); + $mqtt->subscriptions->add(1, ['result' => 'unknown']); continue; } // The topic's subscribe roles gate who may subscribe. if (!$this->authorizedForTopic($topicDocument->getAttribute('subscribe', []) ?? [], $roles)) { $granted .= chr($denied); - $mqtt->metrics->subscriptions->add(1, ['result' => 'forbidden']); + $mqtt->subscriptions->add(1, ['result' => 'forbidden']); continue; } @@ -120,7 +120,7 @@ class Subscribe extends Action $mqtt->subscribe($connection->projectId, $connection->fd, '', [], [$filter], [], $grantedQos); $granted .= chr($grantedQos); - $mqtt->metrics->subscriptions->add(1, ['result' => 'granted']); + $mqtt->subscriptions->add(1, ['result' => 'granted']); $topicDocuments[$filter] = $topicDocument; $grantedQosByTopic[$filter] = $grantedQos; diff --git a/src/Appwrite/Mqtt/Metrics.php b/src/Appwrite/Mqtt/Metrics.php deleted file mode 100644 index dc04f701c9..0000000000 --- a/src/Appwrite/Mqtt/Metrics.php +++ /dev/null @@ -1,51 +0,0 @@ -connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); - $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); - $this->subscriptions = $telemetry->createCounter('mqtt.subscriptions'); - $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); - $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); - $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); - $this->messagesAcked = $telemetry->createCounter('mqtt.messages.acked'); - $this->pubacksReceived = $telemetry->createCounter('mqtt.puback.received'); - $this->reauth = $telemetry->createCounter('mqtt.reauth'); - $this->bytesReceived = $telemetry->createCounter('mqtt.bytes.received', 'By'); - $this->bytesSent = $telemetry->createCounter('mqtt.bytes.sent', 'By'); - $this->authDuration = $telemetry->createHistogram('mqtt.auth.duration', 's'); - $this->connectionDuration = $telemetry->createHistogram('mqtt.connection.duration', 's'); - $this->messageSize = $telemetry->createHistogram('mqtt.message.size', 'By'); - } -} From c0de5c6f251f7d9b060a90179a771168f65b9285 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 18:08:03 +0530 Subject: [PATCH 121/146] refactor(mqtt): inject pub/sub into the adapter instead of reaching for globals --- app/mqtt.php | 2 +- src/Appwrite/Messaging/Adapter/Mqtt.php | 18 +++-------------- src/Appwrite/Platform/Workers/Messaging.php | 12 +++++++++-- .../Appwrite/Messaging/Adapter/MqttTest.php | 20 ++++++++++++++++++- 4 files changed, 33 insertions(+), 19 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index dd68ef1823..e68e85902f 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -236,7 +236,7 @@ $adapter->setPackageMaxLength((int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', $server = new Server($adapter); $server->error(fn (\Throwable $error, string $action) => Console::error("MQTT {$action} error: " . $error->getMessage())); -$mqtt = new Mqtt($telemetry); +$mqtt = new Mqtt($telemetry, new PubSubPool($register->get('pools')->get('pubsub'))); $dispatcher = new Dispatcher([ new ConnectHandler(), diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 4a6842c2b1..52d6469ca8 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -6,7 +6,7 @@ use Appwrite\Messaging\Adapter as MessagingAdapter; use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\KeepAlive; use Appwrite\Mqtt\SubscriptionStore; -use Appwrite\PubSub\Adapter\Pool as PubSubPool; +use Appwrite\PubSub\Adapter as PubSub; use Utopia\Mqtt\Packet; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Counter; @@ -49,9 +49,7 @@ class Mqtt extends MessagingAdapter private ?SubscriptionStore $subscriptionStore = null; - private ?PubSubPool $pubSubPool = null; - - public function __construct(Telemetry $telemetry) + public function __construct(Telemetry $telemetry, private readonly PubSub $pubsub) { $this->connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); @@ -79,16 +77,6 @@ class Mqtt extends MessagingAdapter return $this->subscriptionStore ??= new SubscriptionStore(); } - private function getPubSubPool(): PubSubPool - { - if ($this->pubSubPool === null) { - global $register; - $this->pubSubPool = new PubSubPool($register->get('pools')->get('pubsub')); - } - - return $this->pubSubPool; - } - /** Get or create the connection state for a file descriptor. */ public function open(int $fd): Connection { @@ -175,7 +163,7 @@ class Mqtt extends MessagingAdapter foreach ($channels as $topic) { $this->messagesPublished->add(1, ['qos' => $qos]); - $this->getPubSubPool()->publish(self::CHANNEL, (string) json_encode([ + $this->pubsub->publish(self::CHANNEL, (string) json_encode([ 'project' => $projectId, 'topic' => $topic, 'qos' => $qos, diff --git a/src/Appwrite/Platform/Workers/Messaging.php b/src/Appwrite/Platform/Workers/Messaging.php index abd94d447c..1766c965e7 100644 --- a/src/Appwrite/Platform/Workers/Messaging.php +++ b/src/Appwrite/Platform/Workers/Messaging.php @@ -8,6 +8,7 @@ use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Messaging\Adapter\Push\Appwrite as AppwritePush; use Appwrite\Messaging\Status as MessageStatus; use Appwrite\OpenSSL\OpenSSL; +use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Appwrite\Usage\Context as UsageContext; use Utopia\Compression\Algorithms\GZIP; use Utopia\Compression\Algorithms\Zstd; @@ -48,6 +49,7 @@ use Utopia\Messaging\Messages\SMS; use Utopia\Messaging\Priority; use Utopia\Mqtt\Packet; use Utopia\Platform\Action; +use Utopia\Pools\Group; use Utopia\Psr7\Stream; use Utopia\Queue\Message; use Utopia\Span\Span; @@ -65,6 +67,8 @@ class Messaging extends Action private Telemetry $telemetry; + private Group $pools; + public static function getName(): string { return 'messaging'; @@ -83,6 +87,7 @@ class Messaging extends Action ->inject('deviceForFiles') ->inject('publisherForUsage') ->inject('telemetry') + ->inject('pools') ->callback($this->action(...)); } @@ -93,6 +98,7 @@ class Messaging extends Action * @param Device $deviceForFiles * @param UsagePublisher $publisherForUsage * @param Telemetry $telemetry + * @param Group $pools * @return void * @throws \Exception */ @@ -102,9 +108,11 @@ class Messaging extends Action Database $dbForProject, Device $deviceForFiles, UsagePublisher $publisherForUsage, - Telemetry $telemetry + Telemetry $telemetry, + Group $pools ): void { $this->telemetry = $telemetry; + $this->pools = $pools; $payload = $message->getPayload(); if (empty($payload)) { @@ -921,7 +929,7 @@ class Messaging extends Action ), 'fcm' => new FCM(\json_encode($credentials['serviceAccountJSON'])), 'appwrite' => new AppwritePush( - new Mqtt($this->telemetry), + new Mqtt($this->telemetry, new PubSubPool($this->pools->get('pubsub'))), $dbForProject, $project->getId(), $message->getId(), diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php index bc4e58b046..2afba6294a 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -6,6 +6,7 @@ namespace Tests\Unit\Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Mqtt\Connection; +use Appwrite\PubSub\Adapter as PubSub; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; use Utopia\Telemetry\Adapter\None as NoTelemetry; @@ -22,7 +23,24 @@ final class MqttTest extends TestCase { private function adapter(): Mqtt { - return new Mqtt(new NoTelemetry()); + // send() (the only path that publishes) is covered by e2e, so a null-object + // pub/sub is enough for the registry and subscription-store behaviour tested here. + $pubsub = new class () implements PubSub { + public function ping($message = null): bool + { + return true; + } + + public function subscribe($channels, $callback) + { + } + + public function publish($channel, $message) + { + } + }; + + return new Mqtt(new NoTelemetry(), $pubsub); } /** open() the fd, then subscribe it to $topic (the store keys by topic). */ From ed3a8a73f912b9e12933a5b364d6bb1f79c2c44a Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 18:09:54 +0530 Subject: [PATCH 122/146] refactor(mqtt): set up span exporters unconditionally like the other entrypoints --- app/mqtt.php | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index e68e85902f..bb99f7038a 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -38,9 +38,7 @@ use Utopia\System\System; require_once __DIR__ . '/init.php'; -if (System::getEnv('_APP_EDITION', 'self-hosted') === 'self-hosted') { - require_once __DIR__ . '/init/span.php'; -} +require_once __DIR__ . '/init/span.php'; /** @var Registry $register */ $register = $GLOBALS['register'] ?? throw new \RuntimeException('Registry not initialized'); From cb2165b05302435f7947620fa88b25e4b6aca886 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 18:13:16 +0530 Subject: [PATCH 123/146] ci(mqtt): gate the broker on a healthcheck instead of a log-scraping wait --- .github/workflows/ci.yml | 8 -------- docker-compose.yml | 6 ++++++ 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 031873af19..4dba1db485 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -464,14 +464,6 @@ jobs: timeout-minutes: 5 run: docker compose up -d --quiet-pull --wait - - name: Wait for MQTT broker - timeout-minutes: 3 - run: | - while ! docker logs appwrite-mqtt 2>&1 | grep -q "MQTT broker started"; do - echo "Waiting for the MQTT broker to come online" - sleep 1 - done - - name: Run MQTT Tests timeout-minutes: 15 run: >- diff --git a/docker-compose.yml b/docker-compose.yml index f98f9e8608..4156cdc7bd 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -368,6 +368,12 @@ services: container_name: appwrite-mqtt image: ${_APP_IMAGE:-appwrite/appwrite}:${_APP_VERSION:-latest} restart: unless-stopped + healthcheck: + test: ["CMD", "php", "-r", "exit(@fsockopen('127.0.0.1', 1883) ? 0 : 1);"] + interval: 5s + timeout: 5s + retries: 20 + start_period: 20s labels: - traefik.enable=true - traefik.constraint-label-stack=appwrite From 26587e85659da23764e39f3e83178439324ef058 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Mon, 14 Sep 2026 19:39:09 +0530 Subject: [PATCH 124/146] ci(mqtt): run the broker e2e as its own test suite, not a group exclusion --- .github/workflows/ci.yml | 4 ++-- phpunit.xml | 3 +++ .../MessagingMqttServerTest.php => Mqtt/MqttServerTest.php} | 4 ++-- tests/e2e/Services/{Messaging => Mqtt}/MqttSubscriber.php | 2 +- 4 files changed, 8 insertions(+), 5 deletions(-) rename tests/e2e/Services/{Messaging/MessagingMqttServerTest.php => Mqtt/MqttServerTest.php} (99%) rename tests/e2e/Services/{Messaging => Mqtt}/MqttSubscriber.php (99%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4dba1db485..3a9f75c5e3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -468,7 +468,7 @@ jobs: timeout-minutes: 15 run: >- docker compose exec -T - appwrite test /usr/src/code/tests/e2e/Services/Messaging/MessagingMqttServerTest.php --group mqtt + appwrite test /usr/src/code/tests/e2e/Services/Mqtt --group mqtt - name: Failure Logs if: failure() @@ -633,7 +633,7 @@ jobs: -e _APP_E2E_RESPONSE_FORMAT="${{ github.event.inputs.response_format }}" \ -e _TESTS_OAUTH2_GITHUB_CLIENT_ID="${{ secrets.TESTS_OAUTH2_GITHUB_CLIENT_ID }}" \ -e _TESTS_OAUTH2_GITHUB_CLIENT_SECRET="${{ secrets.TESTS_OAUTH2_GITHUB_CLIENT_SECRET }}" \ - appwrite vendor/bin/paratest --processes "$PARATEST_PROCESSES" $FUNCTIONAL_FLAG "$SERVICE_PATH" --exclude-group abuseEnabled --exclude-group screenshots --exclude-group antivirus --exclude-group mqtt --log-junit tests/e2e/Services/${{ matrix.service.name }}/junit.xml + appwrite vendor/bin/paratest --processes "$PARATEST_PROCESSES" $FUNCTIONAL_FLAG "$SERVICE_PATH" --exclude-group abuseEnabled --exclude-group screenshots --exclude-group antivirus --log-junit tests/e2e/Services/${{ matrix.service.name }}/junit.xml - name: Failure Logs if: failure() diff --git a/phpunit.xml b/phpunit.xml index 575340538c..8578308e4d 100644 --- a/phpunit.xml +++ b/phpunit.xml @@ -46,5 +46,8 @@ ./tests/e2e/Services/Functions/FunctionsCustomServerTest.php ./tests/e2e/Services/Functions/FunctionsCustomClientTest.php + + ./tests/e2e/Services/Mqtt + diff --git a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php b/tests/e2e/Services/Mqtt/MqttServerTest.php similarity index 99% rename from tests/e2e/Services/Messaging/MessagingMqttServerTest.php rename to tests/e2e/Services/Mqtt/MqttServerTest.php index fe66fea833..a5b8c53b36 100644 --- a/tests/e2e/Services/Messaging/MessagingMqttServerTest.php +++ b/tests/e2e/Services/Mqtt/MqttServerTest.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Tests\E2E\Services\Messaging; +namespace Tests\E2E\Services\Mqtt; use Appwrite\Messaging\Status as MessageStatus; use Appwrite\Mqtt\KeepAlive; @@ -27,7 +27,7 @@ use Utopia\Database\Helpers\ID; * selects it with --group mqtt. */ #[Group('mqtt')] -final class MessagingMqttServerTest extends Scope +final class MqttServerTest extends Scope { use ProjectCustom; use SideServer; diff --git a/tests/e2e/Services/Messaging/MqttSubscriber.php b/tests/e2e/Services/Mqtt/MqttSubscriber.php similarity index 99% rename from tests/e2e/Services/Messaging/MqttSubscriber.php rename to tests/e2e/Services/Mqtt/MqttSubscriber.php index 80327e3f02..0da7d8802b 100644 --- a/tests/e2e/Services/Messaging/MqttSubscriber.php +++ b/tests/e2e/Services/Mqtt/MqttSubscriber.php @@ -2,7 +2,7 @@ declare(strict_types=1); -namespace Tests\E2E\Services\Messaging; +namespace Tests\E2E\Services\Mqtt; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V5; From 31793a54df06729f5096e24beb48131a488a2156 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 15 Sep 2026 11:12:44 +0530 Subject: [PATCH 125/146] chore(mqtt): lock utopia-php/mqtt to the dev branch with the broker helpers --- composer.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/composer.lock b/composer.lock index df9df0c4ff..1bb9a8716f 100644 --- a/composer.lock +++ b/composer.lock @@ -4249,12 +4249,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/mqtt.git", - "reference": "9165bccb7b7a03ad3dceb4c00fdcd53f52152cbd" + "reference": "15a8f532d2a5310e20587b0f61c0e82c183419aa" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/9165bccb7b7a03ad3dceb4c00fdcd53f52152cbd", - "reference": "9165bccb7b7a03ad3dceb4c00fdcd53f52152cbd", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/15a8f532d2a5310e20587b0f61c0e82c183419aa", + "reference": "15a8f532d2a5310e20587b0f61c0e82c183419aa", "shasum": "" }, "require": { @@ -4307,7 +4307,7 @@ "source": "https://github.com/utopia-php/mqtt/tree/dev", "issues": "https://github.com/utopia-php/mqtt/issues" }, - "time": "2026-09-08T08:18:35+00:00" + "time": "2026-09-15T05:25:54+00:00" }, { "name": "utopia-php/openapi", From 97e7177f62308e533d6ff1c7809b90214fc67754 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 15 Sep 2026 11:12:44 +0530 Subject: [PATCH 126/146] refactor(mqtt): consume keep-alive, subscription store and connection from the library --- app/mqtt.php | 8 +- src/Appwrite/Messaging/Adapter/Mqtt.php | 26 ++- src/Appwrite/Mqtt/Connection.php | 143 --------------- src/Appwrite/Mqtt/Handlers/Auth.php | 4 +- src/Appwrite/Mqtt/Handlers/Connect.php | 14 +- src/Appwrite/Mqtt/Handlers/Puback.php | 6 +- src/Appwrite/Mqtt/Handlers/Subscribe.php | 8 +- src/Appwrite/Mqtt/Handlers/Unsubscribe.php | 2 +- src/Appwrite/Mqtt/KeepAlive.php | 72 -------- src/Appwrite/Mqtt/SubscriptionStore.php | 191 --------------------- 10 files changed, 36 insertions(+), 438 deletions(-) delete mode 100644 src/Appwrite/Mqtt/Connection.php delete mode 100644 src/Appwrite/Mqtt/KeepAlive.php delete mode 100644 src/Appwrite/Mqtt/SubscriptionStore.php diff --git a/app/mqtt.php b/app/mqtt.php index bb99f7038a..b739fb3011 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -9,7 +9,6 @@ use Appwrite\Mqtt\Handlers\Ping as PingHandler; use Appwrite\Mqtt\Handlers\Puback as PubackHandler; use Appwrite\Mqtt\Handlers\Subscribe as SubscribeHandler; use Appwrite\Mqtt\Handlers\Unsubscribe as UnsubscribeHandler; -use Appwrite\Mqtt\KeepAlive; use Appwrite\Mqtt\Response; use Appwrite\PubSub\Adapter\Pool as PubSubPool; use Appwrite\Utopia\Database\Documents\User; @@ -27,6 +26,7 @@ use Utopia\Database\Document; use Utopia\DI\Container; use Utopia\DSN\DSN; use Utopia\Mqtt\Adapter; +use Utopia\Mqtt\Keepalive; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; @@ -253,7 +253,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): // client silent past its deadline (keepAlive x MULTIPLIER). A survivor whose deadline was // pushed forward by recent traffic is rescheduled instead. onClose balances the gauge and // forgets the fd. Per worker, since connections and the wheel are per worker. - Timer::tick(KeepAlive::INTERVAL * 1000, function () use ($server, $mqtt): void { + Timer::tick($mqtt->keepAlive->interval * 1000, function () use ($server, $mqtt): void { $now = microtime(true); foreach ($mqtt->keepAlive->drain((int) $now) as $fd) { @@ -379,14 +379,14 @@ $server->onReceive(function (int $fd, string $data) use ( // Every inbound packet is liveness: push the deadline forward (O(1), no wheel touch). // The wheel is seeded once, when CONNECT establishes the interval; later packets only // move the deadline and the reaper reschedules lazily when it visits the slot. - $connection->updateExpiresAt(microtime(true)); + $connection->updateExpiresAt(microtime(true), $mqtt->keepAlive->multiplier); if ($packet->type === Packet::CONNECT && $connection->active && $connection->keepAlive > 0) { $connection->wheelSlot = $mqtt->keepAlive->schedule($fd, $connection->expiresAt); } // The identity, project and clean-start flag are populated by the CONNECT // handler during dispatch, so record them afterwards rather than as defaults. - $span->set('project.id', $connection->projectId); + $span->set('project.id', $connection->prefix); $span->set('user.id', $connection->identity['userId'] ?? ''); $span->set('mqtt.clean_start', $connection->cleanStart); $span->finish(); diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 52d6469ca8..138fc3f776 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -3,11 +3,11 @@ namespace Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter as MessagingAdapter; -use Appwrite\Mqtt\Connection; -use Appwrite\Mqtt\KeepAlive; -use Appwrite\Mqtt\SubscriptionStore; use Appwrite\PubSub\Adapter as PubSub; +use Utopia\Mqtt\Connection; +use Utopia\Mqtt\Keepalive; use Utopia\Mqtt\Packet; +use Utopia\Mqtt\Subscription\Store; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Counter; use Utopia\Telemetry\Histogram; @@ -20,7 +20,7 @@ class Mqtt extends MessagingAdapter /** * Connection registry. * - * [FD] -> Connection { protocol, projectId, identity, packetId, active } + * [FD] -> Connection { protocol, prefix, identity, packetId, active } * * @var array */ @@ -45,9 +45,9 @@ class Mqtt extends MessagingAdapter public readonly Histogram $messageSize; /** Keep-alive reaper wheel: connections register their deadline here, the tick drains it. */ - public readonly KeepAlive $keepAlive; + public readonly Keepalive $keepAlive; - private ?SubscriptionStore $subscriptionStore = null; + private ?Store $subscriptionStore = null; public function __construct(Telemetry $telemetry, private readonly PubSub $pubsub) { @@ -65,16 +65,16 @@ class Mqtt extends MessagingAdapter $this->authDuration = $telemetry->createHistogram('mqtt.auth.duration', 's'); $this->connectionDuration = $telemetry->createHistogram('mqtt.connection.duration', 's'); $this->messageSize = $telemetry->createHistogram('mqtt.message.size', 'By'); - $this->keepAlive = new KeepAlive(); + $this->keepAlive = new Keepalive(); } /** * The subscription index, created lazily so the adapter owns it rather than * receiving it — the in-memory tree has no external dependency to wire in. */ - private function subscriptionStore(): SubscriptionStore + private function subscriptionStore(): Store { - return $this->subscriptionStore ??= new SubscriptionStore(); + return $this->subscriptionStore ??= new Store(); } /** Get or create the connection state for a file descriptor. */ @@ -95,9 +95,7 @@ class Mqtt extends MessagingAdapter $this->connectionsActive->add(-1); $this->connectionDuration->record(microtime(true) - $connection->openedAt); } - if ($connection->wheelSlot > 0) { - $this->keepAlive->remove($fd, $connection->wheelSlot); - } + $this->keepAlive->remove($fd); } $this->unsubscribe($fd); unset($this->connections[$fd]); @@ -196,10 +194,10 @@ class Mqtt extends MessagingAdapter /** * The subscription-store record for an fd: its project, user, and subscriptions, - * or null when the fd holds none. This is the store's copy (the projectId/userId + * or null when the fd holds none. This is the store's copy (the prefix/userId * captured at subscribe time), not the live Connection object from open(). * - * @return array{projectId: string, userId: string, subs: array}|null + * @return array{prefix: string, userId: string, subs: array}|null */ public function getConnection(int $fd): ?array { diff --git a/src/Appwrite/Mqtt/Connection.php b/src/Appwrite/Mqtt/Connection.php deleted file mode 100644 index 675e5162ae..0000000000 --- a/src/Appwrite/Mqtt/Connection.php +++ /dev/null @@ -1,143 +0,0 @@ - resolved identity (project/user ids) from the authenticator */ - public array $identity = []; - - /** Counted as active (accepted CONNECT), for a balanced gauge. */ - public bool $active = false; - - /** CONNECT keep-alive interval in seconds; 0 disables keep-alive (the client is never reaped). */ - public int $keepAlive = 0; - - /** Absolute unix deadline (fractional seconds) past which a silent client is reaped; 0 while disabled. */ - public float $expiresAt = 0.0; - - /** The keep-alive wheel bucket (second) this connection currently sits in; 0 when not scheduled. */ - public int $wheelSlot = 0; - - private int $packetId = 0; - - /** - * Outbound QoS 1 deliveries awaiting a PUBACK, keyed by packet id. Each entry - * keeps the topic and the durable sequence delivered, so the matching PUBACK - * can advance that topic's cursor. Emptied as acks arrive; the remaining entries - * are exactly this session's unacked gaps, used to advance the cursor only to the - * highest *contiguous* ack (Redis holds only the committed cursor, not the gaps). - * - * @var array - */ - private array $inflight = []; - - /** Wall-clock time (fractional unix seconds) the connection was opened, for its lifetime metric. */ - public readonly float $openedAt; - - public function __construct( - public readonly int $fd, - ) { - $this->openedAt = microtime(true); - } - - /** - * Push the keep-alive deadline to KeepAlive::MULTIPLIER x the negotiated interval past - * $now — every inbound packet is liveness. No-op when keep-alive is disabled. - */ - public function updateExpiresAt(float $now): void - { - if ($this->keepAlive > 0) { - $this->expiresAt = $now + $this->keepAlive * KeepAlive::MULTIPLIER; - } - } - - /** Next outbound packet id, wrapping 1..65535 (0 is not allowed). */ - public function nextPacketId(): int - { - $this->packetId = ($this->packetId % 0xFFFF) + 1; - - return $this->packetId; - } - - /** Record an outbound QoS 1 delivery so its PUBACK can be matched back to a topic and sequence. */ - public function track(int $packetId, string $topic, int $sequence): void - { - $this->inflight[$packetId] = ['topic' => $topic, 'sequence' => $sequence]; - } - - /** - * Resolve a PUBACK to the delivery it acknowledges, removing it from the in-flight - * set. Returns the topic, the acked sequence, and `cursor`: the highest sequence - * safe to persist — one below the lowest sequence still in flight for the topic, or - * this ack's sequence once nothing is pending. Advancing to `cursor` (not `sequence`) - * keeps a non-contiguous ack from skipping an earlier unacked message; the worst case - * is a harmless tail re-delivery on reconnect, never a lost message. Returns null for - * an unknown or duplicate ack. - * - * Example — messages 5, 6, 7 were delivered and the client acks 5, then 7 (6 is still - * pending): - * ack 5 -> in flight {6, 7}, cursor = 5 (lowest pending is 6, so stop at 5) - * ack 7 -> in flight {6}, cursor = 5 (6 is still the gap, don't jump to 7) - * ack 6 -> in flight {}, cursor = 6 (nothing pending; 7 may be re-sent later) - * The cursor never moves past the unacked 6, so on reconnect 6 is replayed, not lost. - * - * @return array{topic: string, sequence: int, cursor: int}|null - */ - public function acknowledge(int $packetId): ?array - { - $delivery = $this->inflight[$packetId] ?? null; - unset($this->inflight[$packetId]); - if ($delivery === null) { - return null; - } - - $topic = $delivery['topic']; - $pending = []; - foreach ($this->inflight as $entry) { - if ($entry['topic'] === $topic) { - $pending[] = $entry['sequence']; - } - } - - $cursor = $pending === [] ? $delivery['sequence'] : (min($pending) - 1); - - return ['topic' => $topic, 'sequence' => $delivery['sequence'], 'cursor' => $cursor]; - } - - public function setClientId(string $clientId): void - { - if ($this->identity === []) { - throw new Exception(Exception::USER_UNAUTHORIZED, 'Client id cannot be set before the identity is resolved'); - } - - $this->clientId = $clientId !== '' - ? $clientId - : 'custom_' . $this->projectId . '_' . ($this->identity['userId'] ?? ''); - } - - public function getClientId(): string - { - return $this->clientId; - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php index 99e5243ff8..c165fff569 100644 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ b/src/Appwrite/Mqtt/Handlers/Auth.php @@ -3,9 +3,9 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; -use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; use Appwrite\Mqtt\Response; +use Utopia\Mqtt\Connection; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V5; use Utopia\Mqtt\Properties; @@ -52,7 +52,7 @@ class Auth extends Action $projectId = $userProperties['projectId'] ?? ''; $identity = []; - if ($projectId !== '' && $projectId === $connection->projectId) { + if ($projectId !== '' && $projectId === $connection->prefix) { $start = microtime(true); $identity = $authenticator($projectId, $method, $data); $mqtt->authDuration->record(microtime(true) - $start); diff --git a/src/Appwrite/Mqtt/Handlers/Connect.php b/src/Appwrite/Mqtt/Handlers/Connect.php index 503bfbf134..72f29d553d 100644 --- a/src/Appwrite/Mqtt/Handlers/Connect.php +++ b/src/Appwrite/Mqtt/Handlers/Connect.php @@ -3,11 +3,11 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; -use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; use Appwrite\Mqtt\Response; use Utopia\Abuse\Abuse; use Utopia\Abuse\Adapters\TimeLimit\Redis as TimeLimitRedis; +use Utopia\Mqtt\Connection; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; @@ -63,7 +63,7 @@ class Connect extends Action } $projectId = $user['projectId'] ?? ''; - $connection->projectId = $projectId; + $connection->prefix = $projectId; Span::add('project.id', $projectId); Span::add('mqtt.auth_method', $authMethod); @@ -102,8 +102,14 @@ class Connect extends Action } } - // The client id can only be resolved once the identity is known. - $connection->setClientId(Packet::getClientId($body)); + // The per-device session anchor: the client-supplied id, or an account-level fallback so + // reconnects resume the same session (the offline-replay cursor is keyed on it). Resolved + // here rather than in the library, which only server-assigns a generic id for an empty one. + $clientId = Packet::getClientId($body); + if ($clientId === '') { + $clientId = 'custom_' . $connection->prefix . '_' . ($connection->identity['userId'] ?? ''); + } + $connection->setClientId($clientId); Span::add('mqtt.client_id', $connection->getClientId()); $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); diff --git a/src/Appwrite/Mqtt/Handlers/Puback.php b/src/Appwrite/Mqtt/Handlers/Puback.php index 8e2c7c0c51..e0511eeaa0 100644 --- a/src/Appwrite/Mqtt/Handlers/Puback.php +++ b/src/Appwrite/Mqtt/Handlers/Puback.php @@ -3,9 +3,9 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; -use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; use Appwrite\Mqtt\Response; +use Utopia\Mqtt\Connection; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V5; use Utopia\Platform\Action; @@ -40,7 +40,7 @@ class Puback extends Action } $connectionMetdata = $mqtt->getConnection($connection->fd); - if ($connectionMetdata['userId'] !== $connection->identity['userId'] || $connectionMetdata['projectId'] !== $connection->projectId) { + if ($connectionMetdata['userId'] !== $connection->identity['userId'] || $connectionMetdata['prefix'] !== $connection->prefix) { $response->send(V5::disconnect(V5::REASON_NOT_AUTHORIZED)); $response->close(); return; @@ -63,7 +63,7 @@ class Puback extends Action // sequence it just acked — so an out-of-order ack can't skip a still-unacked // message. Only ever move the cursor forward, so two acks at once can't rewind it. $cache = getCache(); - $cursorKey = 'appwrite:push:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); + $cursorKey = 'appwrite:push:cursor:' . $connection->prefix . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); $topic = $delivery['topic']; $cursor = (int) $delivery['cursor']; diff --git a/src/Appwrite/Mqtt/Handlers/Subscribe.php b/src/Appwrite/Mqtt/Handlers/Subscribe.php index bac91501ce..2bbe6f30e4 100644 --- a/src/Appwrite/Mqtt/Handlers/Subscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Subscribe.php @@ -3,12 +3,12 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; -use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; use Appwrite\Mqtt\Response; use Appwrite\Utopia\Database\Documents\User; use Utopia\Database\Helpers\Role; use Utopia\Database\Query; +use Utopia\Mqtt\Connection; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; @@ -51,7 +51,7 @@ class Subscribe extends Action $denied = $connection->protocol >= 5 ? V5::REASON_NOT_AUTHORIZED : V3::SUBSCRIBE_FAILURE; $consoleDatabase = getConsoleDB(); - $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->projectId)); + $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->prefix)); $projectDB = getProjectDB($project); // The subscriber's roles, resolved once, to enforce each topic's subscribe ACL below. @@ -118,7 +118,7 @@ class Subscribe extends Action $topicQos = $topicDocument->getAttribute('qos'); $grantedQos = min($requestedQos, $topicQos === null ? Packet::QOS_1 : (int) $topicQos); - $mqtt->subscribe($connection->projectId, $connection->fd, '', [], [$filter], [], $grantedQos); + $mqtt->subscribe($connection->prefix, $connection->fd, '', [], [$filter], [], $grantedQos); $granted .= chr($grantedQos); $mqtt->subscriptions->add(1, ['result' => 'granted']); @@ -151,7 +151,7 @@ class Subscribe extends Action $cache = getCache(); - $cursorKey = 'appwrite:push:cursor:' . $connection->projectId . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); + $cursorKey = 'appwrite:push:cursor:' . $connection->prefix . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); // A clean-start session discards any persisted cursor before resuming. if ($connection->cleanStart) { diff --git a/src/Appwrite/Mqtt/Handlers/Unsubscribe.php b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php index c0e25600c5..572a04ed03 100644 --- a/src/Appwrite/Mqtt/Handlers/Unsubscribe.php +++ b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php @@ -3,9 +3,9 @@ namespace Appwrite\Mqtt\Handlers; use Appwrite\Messaging\Adapter\Mqtt; -use Appwrite\Mqtt\Connection; use Appwrite\Mqtt\Dispatcher; use Appwrite\Mqtt\Response; +use Utopia\Mqtt\Connection; use Utopia\Mqtt\Packet; use Utopia\Mqtt\Packet\V3; use Utopia\Mqtt\Packet\V5; diff --git a/src/Appwrite/Mqtt/KeepAlive.php b/src/Appwrite/Mqtt/KeepAlive.php deleted file mode 100644 index 34935fc28e..0000000000 --- a/src/Appwrite/Mqtt/KeepAlive.php +++ /dev/null @@ -1,72 +0,0 @@ -> deadline second => set of fds */ - private array $buckets = []; - - /** Highest second already drained; buckets at or before it are gone. */ - private int $cursor; - - public function __construct(?int $now = null) - { - $this->cursor = $now ?? \time(); - } - - public function schedule(int $fd, float $expiresAt): int - { - $slot = \max((int) $expiresAt, $this->cursor + 1); - $this->buckets[$slot][$fd] = true; - - return $slot; - } - - public function remove(int $fd, int $slot): void - { - unset($this->buckets[$slot][$fd]); - - // Drop the whole bucket once its last connection leaves, so a future second emptied - // by disconnects doesn't linger as an empty array until the tick reaches it. - if (($this->buckets[$slot] ?? null) === []) { - unset($this->buckets[$slot]); - } - } - - /** - * - * @return array - */ - public function drain(int $now): array - { - $fds = []; - - for ($second = $this->cursor + 1; $second <= $now; $second++) { - if (!isset($this->buckets[$second])) { - continue; - } - - foreach (\array_keys($this->buckets[$second]) as $fd) { - $fds[] = $fd; - } - - unset($this->buckets[$second]); - } - - $this->cursor = \max($this->cursor, $now); - - return $fds; - } -} diff --git a/src/Appwrite/Mqtt/SubscriptionStore.php b/src/Appwrite/Mqtt/SubscriptionStore.php deleted file mode 100644 index 7ecdc43dce..0000000000 --- a/src/Appwrite/Mqtt/SubscriptionStore.php +++ /dev/null @@ -1,191 +0,0 @@ - child segments keyed by topic level */ - public array $nodes = []; - /** @var array fd => granted QoS for the subscription ending at this node */ - public array $fds = []; - - public function hasNode(string $nodeName) - { - return isset($this->nodes[$nodeName]); - } - public function addNode(string $nodeKey, Node $value) - { - $this->nodes[$nodeKey] = $value; - } -} - -class SubscriptionStore -{ - /** - * fd => connection record. subs are the topic details and in future if required we can use subIds here as well similar to the realtime - * - * @var array}> - */ - private array $connections = []; - - /** - * - * [ROOT] -> - * [PROJECT_ID] -> - * [LEVEL_0] -> e.g. 'test', '+' - * [LEVEL_1] -> e.g. 'hello', '+', '#' - * fds: [FD => QOS, ...] - * - * Example —> subs `test/hello` (fd 11) and `test/#` (fd 12) under project P: - * - * [ROOT] -> [P] -> ['test'] -> ['hello'] -> fds: [11 => 1] - * -> ['#'] -> fds: [12 => 1] - */ - private Node $root; - - public function __construct() - { - $this->root = new Node(); - } - - public function subscribe(string $projectId, string $userId, string $topic, int $fd, int $qos = 1) - { - if (isset($this->connections[$fd]['subs'][$topic])) { - $this->unsubscribe($topic, $fd); - } - - $nodes = [$projectId, ...explode("/", $topic)]; - $parent = $this->root; - foreach ($nodes as $index => $node) { - if (!$parent->hasNode($node)) { - $parent->addNode($node, new Node()); - } - $parent = $parent->nodes[$node]; - if ($index === count($nodes) - 1) { - $parent->fds[$fd] = $qos; - } - } - - if (!isset($this->connections[$fd])) { - $this->connections[$fd] = [ - 'projectId' => $projectId, - 'userId' => $userId, - 'subs' => [], - ]; - } - $this->connections[$fd]['subs'][$topic] = $qos; - } - - public function unsubscribe(string $topic, int $fd) - { - if (!isset($this->connections[$fd]['subs'][$topic])) { - return; - } - - $projectId = $this->connections[$fd]['projectId']; - $nodes = [$projectId, ...explode("/", $topic)]; - - $path = []; - $parent = $this->root; - foreach ($nodes as $node) { - if (!$parent->hasNode($node)) { - $parent = null; - break; - } - $path[] = [$parent, $node]; - $parent = $parent->nodes[$node]; - } - - // pruning the dead topic - if ($parent !== null) { - unset($parent->fds[$fd]); - - for ($i = count($path) - 1; $i >= 0; $i--) { - [$parentNode, $key] = $path[$i]; - $child = $parentNode->nodes[$key]; - if (empty($child->nodes) && empty($child->fds)) { - unset($parentNode->nodes[$key]); - } else { - break; - } - } - } - - unset($this->connections[$fd]['subs'][$topic]); - if (empty($this->connections[$fd]['subs'])) { - unset($this->connections[$fd]); - } - } - - public function close(int $fd) - { - foreach (array_keys($this->connections[$fd]['subs'] ?? []) as $topic) { - $this->unsubscribe($topic, $fd); - } - unset($this->connections[$fd]); - } - - /** - * @return array{projectId: string, userId: string, subs: array}|null - */ - public function getConnection(int $fd): ?array - { - return $this->connections[$fd] ?? null; - } - - /** - * - * @return array fd => granted QoS - */ - public function getSubscribers(string $projectId, string $topic): array - { - $nodes = [$projectId, ...explode("/", $topic)]; - - $current = [$this->root]; - $fds = []; - - $collect = function (Node $node) use (&$fds): void { - foreach ($node->fds as $fd => $qos) { - $fds[$fd] = max($fds[$fd] ?? 0, $qos); - } - }; - - foreach ($nodes as $node) { - $next = []; - - foreach ($current as $parent) { - // # matches everything from this level onward - if ($parent->hasNode('#')) { - $collect($parent->nodes['#']); - } - - // exact match - if ($parent->hasNode($node)) { - $next[] = $parent->nodes[$node]; - } - - // + matches exactly one level - if ($parent->hasNode('+')) { - $next[] = $parent->nodes['+']; - } - } - - $current = $next; - - if (empty($current)) { - break; - } - } - - foreach ($current as $parent) { - $collect($parent); - - // a trailing #, e.g. sub `a/#` matching publish `a` - if ($parent->hasNode('#')) { - $collect($parent->nodes['#']); - } - } - - return $fds; - } -} From 9325ec9952c84c94b3fd1e9f711f7add847b32b2 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 15 Sep 2026 11:12:44 +0530 Subject: [PATCH 127/146] test(mqtt): point the suites at the library classes --- tests/e2e/Services/Mqtt/MqttServerTest.php | 3 +- .../Appwrite/Messaging/Adapter/MqttTest.php | 2 +- tests/unit/Appwrite/Mqtt/ConnectionTest.php | 111 ------------ tests/unit/Appwrite/Mqtt/KeepAliveTest.php | 77 -------- .../Appwrite/Mqtt/SubscriptionStoreTest.php | 171 ------------------ 5 files changed, 2 insertions(+), 362 deletions(-) delete mode 100644 tests/unit/Appwrite/Mqtt/ConnectionTest.php delete mode 100644 tests/unit/Appwrite/Mqtt/KeepAliveTest.php delete mode 100644 tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php diff --git a/tests/e2e/Services/Mqtt/MqttServerTest.php b/tests/e2e/Services/Mqtt/MqttServerTest.php index a5b8c53b36..721cd22cc4 100644 --- a/tests/e2e/Services/Mqtt/MqttServerTest.php +++ b/tests/e2e/Services/Mqtt/MqttServerTest.php @@ -5,7 +5,6 @@ declare(strict_types=1); namespace Tests\E2E\Services\Mqtt; use Appwrite\Messaging\Status as MessageStatus; -use Appwrite\Mqtt\KeepAlive; use PHPUnit\Framework\Attributes\Group; use Tests\E2E\Client; use Tests\E2E\Scopes\ProjectCustom; @@ -224,7 +223,7 @@ final class MqttServerTest extends Scope $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-ping-' . $userId, cleanStart: true, keepAlive: 1)); try { - $deadline = microtime(true) + KeepAlive::INTERVAL + 5; // span at least one reaper tick + $deadline = microtime(true) + 25; // span at least one reaper tick (broker interval is 20s) while (microtime(true) < $deadline) { $this->assertTrue($subscriber->ping(2.0), 'broker did not answer PINGRESP'); usleep(800_000); // < the 1.5s deadline, so activity stays ahead of the reaper diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php index 2afba6294a..8af590c1ef 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php @@ -5,10 +5,10 @@ declare(strict_types=1); namespace Tests\Unit\Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter\Mqtt; -use Appwrite\Mqtt\Connection; use Appwrite\PubSub\Adapter as PubSub; use PHPUnit\Framework\Attributes\DataProvider; use PHPUnit\Framework\TestCase; +use Utopia\Mqtt\Connection; use Utopia\Telemetry\Adapter\None as NoTelemetry; /** diff --git a/tests/unit/Appwrite/Mqtt/ConnectionTest.php b/tests/unit/Appwrite/Mqtt/ConnectionTest.php deleted file mode 100644 index 0405784235..0000000000 --- a/tests/unit/Appwrite/Mqtt/ConnectionTest.php +++ /dev/null @@ -1,111 +0,0 @@ -assertTrue($connection->cleanStart); - } - - public function testTouchSetsTheDeadlineToKeepAliveTimesMultiplier(): void - { - $connection = new Connection(1); - $connection->keepAlive = 20; - - $connection->updateExpiresAt(1000.0); - - $this->assertSame(1000.0 + 20 * KeepAlive::MULTIPLIER, $connection->expiresAt); - } - - public function testTouchIsANoOpWhenKeepAliveIsDisabled(): void - { - $connection = new Connection(1); - // keepAlive defaults to 0 (disabled). - - $connection->updateExpiresAt(1000.0); - - $this->assertEqualsWithDelta(0.0, $connection->expiresAt, PHP_FLOAT_EPSILON); - } - - public function testClientSuppliedIdIsStoredVerbatim(): void - { - $connection = new Connection(1); - $connection->identity = ['userId' => 'user-1']; - $connection->projectId = 'project-1'; - - $connection->setClientId('device-tv'); - - $this->assertSame('device-tv', $connection->getClientId()); - } - - public function testEmptyIdDerivesAccountLevelAnchor(): void - { - $connection = new Connection(1); - $connection->identity = ['userId' => 'user-1']; - $connection->projectId = 'project-1'; - - $connection->setClientId(''); - - $this->assertSame('custom_project-1_user-1', $connection->getClientId()); - } - - public function testSetClientIdBeforeIdentityIsRejected(): void - { - $connection = new Connection(1); - - try { - $connection->setClientId('device-tv'); - $this->fail('setClientId must reject a connection with no resolved identity'); - } catch (Exception $e) { - $this->assertSame(Exception::USER_UNAUTHORIZED, $e->getType()); - } - } - - public function testAcknowledgeResolvesATrackedDelivery(): void - { - $connection = new Connection(1); - $connection->track(7, 'appwrite/push/user-1', 42); - - $ack = $connection->acknowledge(7); - $this->assertSame('appwrite/push/user-1', $ack['topic']); - $this->assertSame(42, $ack['sequence']); - // Nothing else in flight, so the cursor advances to the acked sequence. - $this->assertSame(42, $ack['cursor']); - } - - public function testAcknowledgeAdvancesCursorOnlyToTheContiguousBoundary(): void - { - // Deliver 5, 6, 7; ack 5 and 7 while 6 is still pending. The cursor must stop - // below the gap (5), never jumping to the acked 7 and skipping the unacked 6. - $connection = new Connection(1); - $connection->track(1, 'topic', 5); - $connection->track(2, 'topic', 6); - $connection->track(3, 'topic', 7); - - $this->assertSame(5, $connection->acknowledge(1)['cursor']); // 6,7 pending -> boundary 5 - $this->assertSame(5, $connection->acknowledge(3)['cursor']); // 6 pending -> boundary 5 - $this->assertSame(6, $connection->acknowledge(2)['cursor']); // none pending -> this ack (6) - } - - public function testAcknowledgeIsIdempotentForAnUnknownOrRepeatedAck(): void - { - $connection = new Connection(1); - $connection->track(7, 'appwrite/push/user-1', 42); - - $connection->acknowledge(7); - - $this->assertNull($connection->acknowledge(7), 'a second ack for the same id resolves to nothing'); - $this->assertNull($connection->acknowledge(99), 'an ack for an untracked id resolves to nothing'); - } -} diff --git a/tests/unit/Appwrite/Mqtt/KeepAliveTest.php b/tests/unit/Appwrite/Mqtt/KeepAliveTest.php deleted file mode 100644 index d145299b4d..0000000000 --- a/tests/unit/Appwrite/Mqtt/KeepAliveTest.php +++ /dev/null @@ -1,77 +0,0 @@ -assertSame(1005, $wheel->schedule(7, 1005.5)); // floors to second 1005 - $this->assertSame([], $wheel->drain(1004), 'not due before its second'); - $this->assertSame([7], $wheel->drain(1005), 'due at its second'); - $this->assertSame([], $wheel->drain(1006), 'drained, not returned again'); - } - - public function testOneTickDrainsEveryElapsedSecond(): void - { - // Bucket resolution (1s) is finer than the tick, so a single coarse tick must drain - // the whole elapsed range, never skipping a bucket between ticks. - $wheel = new KeepAlive(1000); - $wheel->schedule(1, 1003.0); - $wheel->schedule(2, 1007.9); - - $this->assertSame([1, 2], $wheel->drain(1020)); - } - - public function testConnectionsSharingASecondAreAllReturned(): void - { - $wheel = new KeepAlive(1000); - $wheel->schedule(1, 1002.1); - $wheel->schedule(2, 1002.9); - - $this->assertSame([1, 2], $wheel->drain(1002)); - } - - public function testRemoveTakesAConnectionOffItsSlot(): void - { - $wheel = new KeepAlive(1000); - $slot = $wheel->schedule(7, 1002.0); - - $wheel->remove(7, $slot); - - $this->assertSame([], $wheel->drain(1002)); - } - - public function testRemovingAnAlreadyDrainedSlotIsHarmless(): void - { - $wheel = new KeepAlive(1000); - $slot = $wheel->schedule(7, 1002.0); - $this->assertSame([7], $wheel->drain(1002)); - - $wheel->remove(7, $slot); // e.g. a close that races the reaper - - $this->assertSame([], $wheel->drain(1003)); - } - - public function testADeadlineAlreadyPastLandsInTheNextTick(): void - { - // Never drop a connection into an already-drained second: it must resolve to cursor + 1. - $wheel = new KeepAlive(1000); - - $this->assertSame(1001, $wheel->schedule(7, 999.0)); - $this->assertSame([7], $wheel->drain(1001)); - } - - public function testDefaults(): void - { - $this->assertSame(20, KeepAlive::INTERVAL); - $this->assertEqualsWithDelta(1.5, KeepAlive::MULTIPLIER, PHP_FLOAT_EPSILON); - } -} diff --git a/tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php b/tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php deleted file mode 100644 index d9f77f2f4b..0000000000 --- a/tests/unit/Appwrite/Mqtt/SubscriptionStoreTest.php +++ /dev/null @@ -1,171 +0,0 @@ -store = new SubscriptionStore(); - } - - /** - * @return \Iterator - */ - public static function matchProvider(): \Iterator - { - // filter, publish topic, should match - yield 'exact single level' => ['sport', 'sport', true]; - yield 'exact rejects deeper' => ['sport', 'sport/x', false]; - yield 'exact rejects sibling' => ['a/b', 'a/c', false]; - yield '+ matches one level' => ['sport/+', 'sport/x', true]; - yield '+ requires a level' => ['sport/+', 'sport', false]; - yield '+ does not span two levels' => ['sport/+', 'sport/x/y', false]; - yield '+ leading level' => ['+/hello', 'test/hello', true]; - yield '+ leading needs a level' => ['+/hello', 'hello', false]; - yield '+ interior level' => ['test/+/x', 'test/a/x', true]; - yield '+ interior is single level' => ['test/+/x', 'test/a/b/x', false]; - yield '# matches parent level' => ['sport/#', 'sport', true]; - yield '# matches one deeper' => ['sport/#', 'sport/x', true]; - yield '# matches many deeper' => ['sport/#', 'sport/x/y', true]; - yield 'root # matches everything' => ['#', 'a/b/c', true]; - } - - #[DataProvider('matchProvider')] - public function testWildcardMatching(string $filter, string $topic, bool $shouldMatch): void - { - $this->store->subscribe(self::PROJECT, 'user', $filter, 1, 1); - - $subscribers = $this->store->getSubscribers(self::PROJECT, $topic); - - $this->assertSame($shouldMatch, \array_key_exists(1, $subscribers)); - } - - public function testNoSubscribersReturnsEmpty(): void - { - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - - $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'nope')); - } - - public function testReturnsGrantedQos(): void - { - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - - $this->assertSame([1 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); - } - - public function testFanOutToMultipleConnections(): void - { - $this->store->subscribe(self::PROJECT, 'user', 'test/+', 11, 1); - $this->store->subscribe(self::PROJECT, 'user', 'test/#', 12, 1); - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 13, 1); - - $subscribers = $this->store->getSubscribers(self::PROJECT, 'test/hello'); - - \ksort($subscribers); - $this->assertSame([11 => 1, 12 => 1, 13 => 1], $subscribers); - } - - public function testConnectionMatchedByTwoFiltersIsDedupedToHighestQos(): void - { - // Same fd matched by an exact (QoS 0) and a wildcard (QoS 1) subscription. - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 7, 0); - $this->store->subscribe(self::PROJECT, 'user', 'test/#', 7, 1); - - $subscribers = $this->store->getSubscribers(self::PROJECT, 'test/hello'); - - $this->assertSame([7 => 1], $subscribers); - } - - public function testResubscribeSameFilterReplacesGrantedQos(): void - { - // MQTT 3.8.4: re-subscribing the same (connection, topic) replaces the grant. - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 0); - - $this->assertSame([1 => 0], $this->store->getSubscribers(self::PROJECT, 'test/hello')); - } - - public function testProjectIsolation(): void - { - $this->store->subscribe('projectA', 'user', 'test/hello', 1, 1); - $this->store->subscribe('projectB', 'user', 'test/hello', 2, 1); - - $this->assertSame([1 => 1], $this->store->getSubscribers('projectA', 'test/hello')); - $this->assertSame([2 => 1], $this->store->getSubscribers('projectB', 'test/hello')); - } - - public function testUnsubscribeRemovesOnlyThatTopic(): void - { - // One connection subscribed to two topics. - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'test/world', 1, 1); - - $this->store->unsubscribe('test/hello', 1); - - $this->assertArrayNotHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/hello')); - $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/world')); - } - - public function testUnsubscribeUnknownTopicIsNoop(): void - { - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - - $this->store->unsubscribe('missing/topic', 1); - $this->store->unsubscribe('test/hello', 999); - - $this->assertSame([1 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); - } - - public function testUnsubscribeThenTopicNoLongerMatchesWildcard(): void - { - // Covers pruning behaviour observably: after the only subscriber leaves, a - // wildcard publish that used to match returns nothing. - $this->store->subscribe(self::PROJECT, 'user', 'test/deep/leaf', 1, 1); - $this->assertArrayHasKey(1, $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); - - $this->store->unsubscribe('test/deep/leaf', 1); - - $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'test/deep/leaf')); - } - - public function testCloseRemovesEverySubscriptionForConnection(): void - { - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 1, 1); - $this->store->subscribe(self::PROJECT, 'user', 'other/#', 1, 1); - // A second connection that must survive the close. - $this->store->subscribe(self::PROJECT, 'user', 'test/hello', 2, 1); - - $this->store->close(1); - - $this->assertSame([2 => 1], $this->store->getSubscribers(self::PROJECT, 'test/hello')); - $this->assertSame([], $this->store->getSubscribers(self::PROJECT, 'other/x')); - } - - public function testGetConnectionReturnsTheFdRecord(): void - { - $this->store->subscribe(self::PROJECT, 'user-1', 'test/hello', 9, 1); - - $connection = $this->store->getConnection(9); - - $this->assertSame(self::PROJECT, $connection['projectId']); - $this->assertSame('user-1', $connection['userId']); - $this->assertSame(1, $connection['subs']['test/hello']); - } - - public function testGetConnectionIsNullForAnUnknownFd(): void - { - $this->assertNull($this->store->getConnection(404)); - } -} From 0086d1d53604d83e0b9f425c3d244e88adf5deac Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 15 Sep 2026 11:20:05 +0530 Subject: [PATCH 128/146] test(mqtt): give the FakeBroker a pub/sub after the adapter DI change --- .../Messaging/Adapter/Push/AppwriteTest.php | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php index d8cbbe87bc..142c7b7d41 100644 --- a/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php +++ b/tests/unit/Appwrite/Messaging/Adapter/Push/AppwriteTest.php @@ -6,6 +6,7 @@ namespace Tests\Unit\Appwrite\Messaging\Adapter\Push; use Appwrite\Messaging\Adapter\Mqtt; use Appwrite\Messaging\Adapter\Push\Appwrite as AppwritePush; +use Appwrite\PubSub\Adapter as PubSub; use PHPUnit\Framework\TestCase; use Utopia\Cache\Adapter\None as NoCache; use Utopia\Cache\Cache; @@ -35,7 +36,21 @@ final class FakeBroker extends Mqtt public function __construct() { - parent::__construct(new NoTelemetry()); + // send() is overridden below, so the pub/sub is never used; a null-object satisfies it. + parent::__construct(new NoTelemetry(), new class () implements PubSub { + public function ping($message = null): bool + { + return true; + } + + public function subscribe($channels, $callback) + { + } + + public function publish($channel, $message) + { + } + }); } public function send(string $projectId, array $payload, array $events, array $channels, array $roles, array $options = []): void From fcbe44e20d897bf67ae2f7f49ab19f594659d395 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 15 Sep 2026 11:29:02 +0530 Subject: [PATCH 129/146] bump --- composer.lock | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/composer.lock b/composer.lock index 1bb9a8716f..78b255af8a 100644 --- a/composer.lock +++ b/composer.lock @@ -1401,16 +1401,16 @@ }, { "name": "open-telemetry/sem-conv", - "version": "1.38.0", + "version": "1.44.0", "source": { "type": "git", "url": "https://github.com/opentelemetry-php/sem-conv.git", - "reference": "e613bc640a407def4991b8a936a9b27edd9a3240" + "reference": "c94bc7ebacef039cda4f4c9270807dcc58b4e3af" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/opentelemetry-php/sem-conv/zipball/e613bc640a407def4991b8a936a9b27edd9a3240", - "reference": "e613bc640a407def4991b8a936a9b27edd9a3240", + "url": "https://api.github.com/repos/opentelemetry-php/sem-conv/zipball/c94bc7ebacef039cda4f4c9270807dcc58b4e3af", + "reference": "c94bc7ebacef039cda4f4c9270807dcc58b4e3af", "shasum": "" }, "require": { @@ -1454,7 +1454,7 @@ "issues": "https://github.com/open-telemetry/opentelemetry-php/issues", "source": "https://github.com/open-telemetry/opentelemetry-php" }, - "time": "2026-01-21T04:14:03+00:00" + "time": "2026-09-09T22:06:17+00:00" }, { "name": "paragonie/constant_time_encoding", @@ -3037,16 +3037,16 @@ }, { "name": "utopia-php/cache", - "version": "5.0.0", + "version": "5.0.3", "source": { "type": "git", "url": "https://github.com/utopia-php/cache.git", - "reference": "0d0752785fc81b5afd6571f4291763166a6532bc" + "reference": "f808a39d018e1f325ac553b8de39798cae40c1f9" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/cache/zipball/0d0752785fc81b5afd6571f4291763166a6532bc", - "reference": "0d0752785fc81b5afd6571f4291763166a6532bc", + "url": "https://api.github.com/repos/utopia-php/cache/zipball/f808a39d018e1f325ac553b8de39798cae40c1f9", + "reference": "f808a39d018e1f325ac553b8de39798cae40c1f9", "shasum": "" }, "require": { @@ -3090,9 +3090,9 @@ ], "support": { "issues": "https://github.com/utopia-php/cache/issues", - "source": "https://github.com/utopia-php/cache/tree/5.0.0" + "source": "https://github.com/utopia-php/cache/tree/5.0.3" }, - "time": "2026-08-21T11:04:48+00:00" + "time": "2026-09-11T08:23:02+00:00" }, { "name": "utopia-php/cdn", @@ -4393,16 +4393,16 @@ }, { "name": "utopia-php/pools", - "version": "2.1.1", + "version": "2.1.2", "source": { "type": "git", "url": "https://github.com/utopia-php/pools.git", - "reference": "bc689b818fe1de0df72db6e51ab2f52b838b1209" + "reference": "a45d867e56de82a2eb6e1eb3ea78d4c2f6059f4a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/pools/zipball/bc689b818fe1de0df72db6e51ab2f52b838b1209", - "reference": "bc689b818fe1de0df72db6e51ab2f52b838b1209", + "url": "https://api.github.com/repos/utopia-php/pools/zipball/a45d867e56de82a2eb6e1eb3ea78d4c2f6059f4a", + "reference": "a45d867e56de82a2eb6e1eb3ea78d4c2f6059f4a", "shasum": "" }, "require": { @@ -4443,9 +4443,9 @@ ], "support": { "issues": "https://github.com/utopia-php/pools/issues", - "source": "https://github.com/utopia-php/pools/tree/2.1.1" + "source": "https://github.com/utopia-php/pools/tree/2.1.2" }, - "time": "2026-09-02T15:57:19+00:00" + "time": "2026-09-07T07:02:57+00:00" }, { "name": "utopia-php/psr7", @@ -4959,16 +4959,16 @@ }, { "name": "utopia-php/telemetry", - "version": "0.4.8", + "version": "0.4.10", "source": { "type": "git", "url": "https://github.com/utopia-php/telemetry.git", - "reference": "6fb0bb579b3e249be720010bc12434c2ec6194bb" + "reference": "29432a590bf96597ba8f0e767c966be16481651a" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/telemetry/zipball/6fb0bb579b3e249be720010bc12434c2ec6194bb", - "reference": "6fb0bb579b3e249be720010bc12434c2ec6194bb", + "url": "https://api.github.com/repos/utopia-php/telemetry/zipball/29432a590bf96597ba8f0e767c966be16481651a", + "reference": "29432a590bf96597ba8f0e767c966be16481651a", "shasum": "" }, "require": { @@ -5004,9 +5004,9 @@ ], "support": { "issues": "https://github.com/utopia-php/telemetry/issues", - "source": "https://github.com/utopia-php/telemetry/tree/0.4.8" + "source": "https://github.com/utopia-php/telemetry/tree/0.4.10" }, - "time": "2026-09-02T15:57:19+00:00" + "time": "2026-09-11T06:27:08+00:00" }, { "name": "utopia-php/usage", From 83206d3d783a7fbf6f344b9db565b4a068f89cee Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Tue, 15 Sep 2026 15:58:46 +0530 Subject: [PATCH 130/146] bump --- composer.lock | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/composer.lock b/composer.lock index 3d715033cc..6cf7cbb340 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "a6c7073c169d41bd738310bdb883d0e3", + "content-hash": "8e82aa5125ccfa17c4a8ac67d128e3f5", "packages": [ { "name": "adhocore/jwt", @@ -4249,12 +4249,12 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/mqtt.git", - "reference": "15a8f532d2a5310e20587b0f61c0e82c183419aa" + "reference": "a4dafdebd5634ab64ebb08ad5930b603c5fc5d02" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/15a8f532d2a5310e20587b0f61c0e82c183419aa", - "reference": "15a8f532d2a5310e20587b0f61c0e82c183419aa", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/a4dafdebd5634ab64ebb08ad5930b603c5fc5d02", + "reference": "a4dafdebd5634ab64ebb08ad5930b603c5fc5d02", "shasum": "" }, "require": { @@ -4307,7 +4307,7 @@ "source": "https://github.com/utopia-php/mqtt/tree/dev", "issues": "https://github.com/utopia-php/mqtt/issues" }, - "time": "2026-09-15T05:25:54+00:00" + "time": "2026-09-15T07:09:28+00:00" }, { "name": "utopia-php/openapi", From e8932bed7d97948f62fa7e7540b4c94f60f8a7b0 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 17 Sep 2026 21:15:29 +0530 Subject: [PATCH 131/146] refactor(mqtt): consume the utopia-php/mqtt Server/Handler deep-module API Collapse the per-packet handlers, Dispatcher and Response into a single Appwrite\Mqtt\Handler that implements the library Handler interface; the Server now owns framing, dispatch, encoding, keep-alive and the subscription store. Resolve broker resources (cache, console/project DB, redis, plan) through the container instead of global functions. Honour each topic's expiry as the replay-cursor TTL (PUBACK preserves it with a 0-ttl save rather than shrinking it to the default hour), and clamp delivery QoS to the subscriber's granted QoS. Drop the adapter unit test whose registry/store behaviour now lives in the library. --- app/init/mqtt/connection.php | 10 +- app/mqtt.php | 393 ++++++------------ composer.lock | 11 +- src/Appwrite/Messaging/Adapter/Mqtt.php | 148 +------ src/Appwrite/Mqtt/Dispatcher.php | 61 --- src/Appwrite/Mqtt/Handler.php | 343 +++++++++++++++ src/Appwrite/Mqtt/Handlers/Auth.php | 86 ---- src/Appwrite/Mqtt/Handlers/Connect.php | 130 ------ src/Appwrite/Mqtt/Handlers/Disconnect.php | 25 -- src/Appwrite/Mqtt/Handlers/Ping.php | 25 -- src/Appwrite/Mqtt/Handlers/Puback.php | 75 ---- src/Appwrite/Mqtt/Handlers/Subscribe.php | 238 ----------- src/Appwrite/Mqtt/Handlers/Unsubscribe.php | 55 --- src/Appwrite/Mqtt/Response.php | 39 -- tests/e2e/Services/Mqtt/MqttSubscriber.php | 17 +- .../Appwrite/Messaging/Adapter/MqttTest.php | 164 -------- 16 files changed, 500 insertions(+), 1320 deletions(-) delete mode 100644 src/Appwrite/Mqtt/Dispatcher.php create mode 100644 src/Appwrite/Mqtt/Handler.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Auth.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Connect.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Disconnect.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Ping.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Puback.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Subscribe.php delete mode 100644 src/Appwrite/Mqtt/Handlers/Unsubscribe.php delete mode 100644 src/Appwrite/Mqtt/Response.php delete mode 100644 tests/unit/Appwrite/Messaging/Adapter/MqttTest.php diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 8b6f12d079..50ae943d63 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -13,25 +13,27 @@ use Utopia\DI\Container; use Utopia\System\System; return function (Container $container): void { - $getProject = function (string $projectId, Authorization $authorization): Document { + $getProject = function (string $projectId, Authorization $authorization) use ($container): Document { if ($projectId === '' || $projectId === 'console') { return new Document(Config::getParam('console')); } - $dbForPlatform = getConsoleDB(); + $getConsoleDB = $container->get('getConsoleDB'); + $dbForPlatform = $getConsoleDB(); $dbForPlatform->setAuthorization($authorization); return $authorization->skip(fn () => $dbForPlatform->getDocument('projects', $projectId)); }; - $getUser = function (Document $project, string $authMethod, string $credential, Authorization $authorization): User { + $getUser = function (Document $project, string $authMethod, string $credential, Authorization $authorization) use ($container): User { if ($project->isEmpty() || $credential === '') { return new User([]); } $authorization->setDefaultStatus(true); - $dbForProject = getProjectDB($project); + $getProjectDB = $container->get('getProjectDB'); + $dbForProject = $getProjectDB($project); $dbForProject->setAuthorization($authorization); switch ($authMethod) { diff --git a/app/mqtt.php b/app/mqtt.php index b739fb3011..dc27cc0c92 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -1,20 +1,11 @@ has('pools')) { }, ['register']); } -if (!function_exists('getCache')) { - function getCache(): Cache - { - $ctx = Coroutine::getContext(); +$container->set('getCache', fn () => function () use ($register): Cache { + $ctx = Coroutine::getContext(); - if (isset($ctx['cache'])) { - return $ctx['cache']; - } - - global $register; - - /** @var Group $pools */ - $pools = $register->get('pools'); - - $adapters = []; - foreach (Config::getParam('pools-cache', []) as $value) { - $adapters[] = new CachePool($pools->get($value)); - } - - return $ctx['cache'] = new Cache(new Sharding($adapters)); + if (isset($ctx['cache'])) { + return $ctx['cache']; } -} -if (!function_exists('getConsoleDB')) { - function getConsoleDB(): Database - { - $ctx = Coroutine::getContext(); + /** @var Group $pools */ + $pools = $register->get('pools'); - if (isset($ctx['dbForPlatform'])) { - return $ctx['dbForPlatform']; - } - - global $register; - - /** @var Group $pools */ - $pools = $register->get('pools'); - - $adapter = new DatabasePool($pools->get('console')); - $database = new Database($adapter, getCache()); - $database - ->setDatabase(APP_DATABASE) - ->setNamespace('_console') - ->setMetadata('host', \gethostname()) - ->setMetadata('project', '_console'); - $database->setDocumentType('users', User::class); - - return $ctx['dbForPlatform'] = $database; + $adapters = []; + foreach (Config::getParam('pools-cache', []) as $value) { + $adapters[] = new CachePool($pools->get($value)); } -} -if (!function_exists('getProjectDB')) { - function getProjectDB(Document $project): Database - { - $ctx = Coroutine::getContext(); + return $ctx['cache'] = new Cache(new Sharding($adapters)); +}, []); - if (!isset($ctx['dbForProject'])) { - $ctx['dbForProject'] = []; - } +$container->set('getConsoleDB', fn () => function () use ($register, $container): Database { + $ctx = Coroutine::getContext(); - if (isset($ctx['dbForProject'][$project->getSequence()])) { - return $ctx['dbForProject'][$project->getSequence()]; - } + if (isset($ctx['dbForPlatform'])) { + return $ctx['dbForPlatform']; + } - if ($project->isEmpty() || $project->getId() === 'console') { - return getConsoleDB(); - } + $getCache = $container->get('getCache'); - global $register; + /** @var Group $pools */ + $pools = $register->get('pools'); - /** @var Group $pools */ - $pools = $register->get('pools'); + $adapter = new DatabasePool($pools->get('console')); + $database = new Database($adapter, $getCache()); + $database + ->setDatabase(APP_DATABASE) + ->setNamespace('_console') + ->setMetadata('host', \gethostname()) + ->setMetadata('project', '_console'); + $database->setDocumentType('users', User::class); - try { - $dsn = new DSN($project->getAttribute('database')); - } catch (\InvalidArgumentException) { - $dsn = new DSN('mysql://' . $project->getAttribute('database')); - } + return $ctx['dbForPlatform'] = $database; +}, []); - $adapter = new DatabasePool($pools->get($dsn->getHost())); - $database = new Database($adapter, getCache()); +$container->set('getProjectDB', fn () => function (Document $project) use ($register, $container): Database { + $ctx = Coroutine::getContext(); - $sharedTables = \explode(',', System::getEnv('_APP_DATABASE_SHARED_TABLES', '')); + if (!isset($ctx['dbForProject'])) { + $ctx['dbForProject'] = []; + } - if (\in_array($dsn->getHost(), $sharedTables)) { - $projectCollections = Config::getParam('collections', [])['projects'] ?? []; - $globalCollections = array_keys($projectCollections); - $globalCollections[] = 'audit'; + if (isset($ctx['dbForProject'][$project->getSequence()])) { + return $ctx['dbForProject'][$project->getSequence()]; + } - $database - ->setSharedTables(true) - ->setGlobalCollections($globalCollections) - ->setTenant($project->getSequence()) - ->setNamespace($dsn->getParam('namespace')); - } else { - $database - ->setSharedTables(false) - ->setTenant(null) - ->setNamespace('_' . $project->getSequence()); - } + if ($project->isEmpty() || $project->getId() === 'console') { + $getConsoleDB = $container->get('getConsoleDB'); + + return $getConsoleDB(); + } + + $getCache = $container->get('getCache'); + + /** @var Group $pools */ + $pools = $register->get('pools'); + + try { + $dsn = new DSN($project->getAttribute('database')); + } catch (\InvalidArgumentException) { + $dsn = new DSN('mysql://' . $project->getAttribute('database')); + } + + $adapter = new DatabasePool($pools->get($dsn->getHost())); + $database = new Database($adapter, $getCache()); + + $sharedTables = \explode(',', System::getEnv('_APP_DATABASE_SHARED_TABLES', '')); + + if (\in_array($dsn->getHost(), $sharedTables)) { + $projectCollections = Config::getParam('collections', [])['projects'] ?? []; + $globalCollections = array_keys($projectCollections); + $globalCollections[] = 'audit'; $database - ->setDatabase(APP_DATABASE) - ->setMetadata('host', \gethostname()) - ->setMetadata('project', $project->getId()); - $database->setDocumentType('users', User::class); - - return $ctx['dbForProject'][$project->getSequence()] = $database; + ->setSharedTables(true) + ->setGlobalCollections($globalCollections) + ->setTenant($project->getSequence()) + ->setNamespace($dsn->getParam('namespace')); + } else { + $database + ->setSharedTables(false) + ->setTenant(null) + ->setNamespace('_' . $project->getSequence()); } -} -if (!function_exists('getPlanForUser')) { - function getPlanForUser(Document $project, string $userId): int - { - return (int) System::getEnv('_APP_MQTT_REPLAY_DEPTH', '5'); + $database + ->setDatabase(APP_DATABASE) + ->setMetadata('host', \gethostname()) + ->setMetadata('project', $project->getId()); + $database->setDocumentType('users', User::class); + + return $ctx['dbForProject'][$project->getSequence()] = $database; +}, []); + +$container->set('getPlanForUser', fn () => fn (Document $project, string $userId): int => (int) System::getEnv('_APP_MQTT_REPLAY_DEPTH', '5'), []); + +$container->set('getRedis', fn () => function (): \Redis { + $ctx = Coroutine::getContext(); + + if (isset($ctx['redis'])) { + return $ctx['redis']; } -} -if (!function_exists('getCache')) { - function getCache(): Cache - { - $ctx = Coroutine::getContext(); + $host = System::getEnv('_APP_REDIS_HOST', 'localhost'); + $port = System::getEnv('_APP_REDIS_PORT', 6379); + $pass = System::getEnv('_APP_REDIS_PASS', ''); - if (isset($ctx['cache'])) { - return $ctx['cache']; - } - - global $register; - - $pools = $register->get('pools'); /** @var Group $pools */ - - $list = Config::getParam('pools-cache', []); - $adapters = []; - - foreach ($list as $value) { - $adapters[] = new CachePool($pools->get($value)); - } - - return $ctx['cache'] = new Cache(new Sharding($adapters)); + $redis = new \Redis(); + @$redis->pconnect($host, (int)$port); + if ($pass) { + $redis->auth($pass); } -} + $redis->setOption(\Redis::OPT_READ_TIMEOUT, -1); -if (!function_exists('getRedis')) { - function getRedis(): \Redis - { - $ctx = Coroutine::getContext(); - - if (isset($ctx['redis'])) { - return $ctx['redis']; - } - - $host = System::getEnv('_APP_REDIS_HOST', 'localhost'); - $port = System::getEnv('_APP_REDIS_PORT', 6379); - $pass = System::getEnv('_APP_REDIS_PASS', ''); - - $redis = new \Redis(); - @$redis->pconnect($host, (int)$port); - if ($pass) { - $redis->auth($pass); - } - $redis->setOption(\Redis::OPT_READ_TIMEOUT, -1); - - return $ctx['redis'] = $redis; - } -} + return $ctx['redis'] = $redis; +}, []); // Register the CONNECT authenticator and per-SUBSCRIBE authorizer on the global container // (see app/init/mqtt/connection.php). The CONNECT/SUBSCRIBE handlers inject them by name, @@ -228,49 +174,25 @@ $registerConnectionResources($container); /** @var \Utopia\Telemetry\Adapter $telemetry */ $telemetry = $container->get('telemetry'); -$adapter = new Adapter\Swoole(host: '0.0.0.0', port: 1883); -$adapter->setPackageMaxLength((int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000')); - -$server = new Server($adapter); -$server->error(fn (\Throwable $error, string $action) => Console::error("MQTT {$action} error: " . $error->getMessage())); +$adapter = new Adapter\Swoole([ + new Adapter\Swoole\Tcp('0.0.0.0', 1883, (int) System::getEnv('_APP_MQTT_MAX_PACKET_SIZE', '64000')), +], workers: 1); $mqtt = new Mqtt($telemetry, new PubSubPool($register->get('pools')->get('pubsub'))); -$dispatcher = new Dispatcher([ - new ConnectHandler(), - new SubscribeHandler(), - new UnsubscribeHandler(), - new PubackHandler(), - new AuthHandler(), - new PingHandler(), - new DisconnectHandler(), -]); +// The broker owns framing, decoding, dispatch, per-version encoding, packet ids, the QoS +// handshake, keep-alive reaping and subscription matching. Appwrite policy lives in the Handler. +$handler = new Handler($container, $mqtt); +$server = new Server($adapter, $handler); +$server->setTelemetry($telemetry); // broker owns connection/packet/subscription metrics $server->onStart(fn () => print("MQTT broker started\n")); +$server->error(fn (\Throwable $error, string $action) => Console::error("MQTT {$action} error: " . $error->getMessage())); -$server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): void { - // Keep-alive reaper: every INTERVAL seconds drain the wheel's due buckets and close any - // client silent past its deadline (keepAlive x MULTIPLIER). A survivor whose deadline was - // pushed forward by recent traffic is rescheduled instead. onClose balances the gauge and - // forgets the fd. Per worker, since connections and the wheel are per worker. - Timer::tick($mqtt->keepAlive->interval * 1000, function () use ($server, $mqtt): void { - $now = microtime(true); - - foreach ($mqtt->keepAlive->drain((int) $now) as $fd) { - $connection = $mqtt->connections[$fd] ?? null; - if ($connection === null || $connection->keepAlive <= 0) { - continue; - } - - if ($connection->expiresAt <= $now) { - $server->close($fd); - } else { - $connection->wheelSlot = $mqtt->keepAlive->schedule($fd, $connection->expiresAt); - } - } - }); - - go(function () use ($server, $mqtt, $register): void { +// Server-initiated delivery: bridge the Redis 'mqtt' firehose to this worker's local subscribers. +// Appwrite clients never PUBLISH; messages are produced by the Messaging worker onto the channel. +$server->onWorkerStart(function (int $workerId) use ($server, $handler, $mqtt, $register): void { + go(function () use ($server, $handler, $mqtt, $register): void { $attempts = 0; while ($attempts < 300) { try { @@ -280,7 +202,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): $attempts = 0; } - $pubsub->subscribe(['mqtt'], function (mixed $redis, string $channel, string $payload) use ($server, $mqtt): void { + $pubsub->subscribe(['mqtt'], function (mixed $redis, string $channel, string $payload) use ($server, $handler, $mqtt): void { $event = json_decode($payload, true); if (!\is_array($event)) { return; @@ -292,43 +214,17 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): $sequence = (int) ($event['sequence'] ?? 0); $message = base64_decode((string) ($event['payload'] ?? '')); - // The broker is the sender on this hop (fan-out to subscribers), so the - // span is marked is_broker to separate it from client-originated packets. $span = Span::init('mqtt.deliver'); $span->set('project.id', $projectId); $span->set('mqtt.topic', $topic); $span->set('mqtt.qos', $qos); $span->set('mqtt.is_broker', true); - $subscribers = $mqtt->getSubscribers($projectId, $topic); - $span->set('mqtt.subscribers', count($subscribers)); + $delivered = $handler->deliver($server, $projectId, $topic, $message, $qos, $sequence); - if ($subscribers === []) { - // No local subscriber on this worker; with multiple workers this - // counts per-worker rather than as a global drop. + $span->set('mqtt.subscribers', $delivered); + if ($delivered === 0) { $mqtt->messagesDropped->add(1, ['reason' => 'no_subscriber']); - $span->finish(); - return; - } - - foreach ($subscribers as $fd => $grantedQos) { - $subscriber = $mqtt->connections[$fd] ?? null; - if ($subscriber === null) { - continue; - } - $effectiveQos = min($qos, $grantedQos); - $packetId = $subscriber->nextPacketId(); - $publish = $subscriber->protocol >= 5 - ? V5::publish($topic, $message, $effectiveQos, $packetId) - : V3::publish($topic, $message, $effectiveQos, $packetId); - $server->send($fd, $publish); - $mqtt->bytesSent->add(\strlen($publish)); - $mqtt->messagesDelivered->add(1, ['qos' => $effectiveQos]); - - // Hold QoS 1 deliveries until the subscriber's PUBACK matches them back. - if ($effectiveQos === 1) { - $subscriber->track($packetId, $topic, $sequence); - } } $span->finish(); @@ -344,61 +240,4 @@ $server->onWorkerStart(function (int $workerId) use ($server, $mqtt, $register): }); }); -$server->onReceive(function (int $fd, string $data) use ( - $server, - $mqtt, - $dispatcher, - $container -): void { - // The whole packet lifecycle is wrapped: a malformed packet or a handler failure must - // drop only this connection, never bubble up and take down the worker (and every other - // connection it holds). - $span = null; - try { - $packet = Packet::parse($data); - $connection = $mqtt->open($fd); - - $mqtt->bytesReceived->add(\strlen($data)); - - $span = Span::init('mqtt.' . $packet->name()); - $span->set('mqtt.fd', $fd); - $span->set('mqtt.is_broker', false); // an inbound packet from a client - $span->set('mqtt.bytes', \strlen($data)); - - $response = new Response($server, $fd, $mqtt->bytesSent); - - // authenticator/authorizer are inherited from the global container (registered above). - $packetContainer = new Container($container); - $packetContainer->set('mqtt', fn () => $mqtt); - $packetContainer->set('connection', fn () => $connection); - $packetContainer->set('packet', fn () => $packet); - $packetContainer->set('response', fn () => $response); - - $dispatcher->dispatch($packetContainer, $packet->type); - - // Every inbound packet is liveness: push the deadline forward (O(1), no wheel touch). - // The wheel is seeded once, when CONNECT establishes the interval; later packets only - // move the deadline and the reaper reschedules lazily when it visits the slot. - $connection->updateExpiresAt(microtime(true), $mqtt->keepAlive->multiplier); - if ($packet->type === Packet::CONNECT && $connection->active && $connection->keepAlive > 0) { - $connection->wheelSlot = $mqtt->keepAlive->schedule($fd, $connection->expiresAt); - } - - // The identity, project and clean-start flag are populated by the CONNECT - // handler during dispatch, so record them afterwards rather than as defaults. - $span->set('project.id', $connection->prefix); - $span->set('user.id', $connection->identity['userId'] ?? ''); - $span->set('mqtt.clean_start', $connection->cleanStart); - $span->finish(); - } catch (\Throwable $error) { - Console::error('MQTT packet error on fd ' . $fd . ': ' . $error->getMessage()); - $span?->finish(error: $error); - $server->close($fd); - } -}); - -$server->onClose(function (int $fd) use ($mqtt): void { - $mqtt->close($fd); -}); - $server->start(); diff --git a/composer.lock b/composer.lock index 650eb6b7bd..20a9fde1a2 100644 --- a/composer.lock +++ b/composer.lock @@ -4149,16 +4149,17 @@ "source": { "type": "git", "url": "https://github.com/utopia-php/mqtt.git", - "reference": "a4dafdebd5634ab64ebb08ad5930b603c5fc5d02" + "reference": "53ff974d0a179f07035241a8b8df0ca1b15a2ff5" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/a4dafdebd5634ab64ebb08ad5930b603c5fc5d02", - "reference": "a4dafdebd5634ab64ebb08ad5930b603c5fc5d02", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/53ff974d0a179f07035241a8b8df0ca1b15a2ff5", + "reference": "53ff974d0a179f07035241a8b8df0ca1b15a2ff5", "shasum": "" }, "require": { - "php": ">=8.1" + "php": ">=8.1", + "utopia-php/telemetry": "^0.4" }, "require-dev": { "laravel/pint": "^1.15 <1.21", @@ -4207,7 +4208,7 @@ "source": "https://github.com/utopia-php/mqtt/tree/dev", "issues": "https://github.com/utopia-php/mqtt/issues" }, - "time": "2026-09-15T07:09:28+00:00" + "time": "2026-09-17T15:41:04+00:00" }, { "name": "utopia-php/openapi", diff --git a/src/Appwrite/Messaging/Adapter/Mqtt.php b/src/Appwrite/Messaging/Adapter/Mqtt.php index 138fc3f776..cccf37fd42 100644 --- a/src/Appwrite/Messaging/Adapter/Mqtt.php +++ b/src/Appwrite/Messaging/Adapter/Mqtt.php @@ -4,146 +4,47 @@ namespace Appwrite\Messaging\Adapter; use Appwrite\Messaging\Adapter as MessagingAdapter; use Appwrite\PubSub\Adapter as PubSub; -use Utopia\Mqtt\Connection; -use Utopia\Mqtt\Keepalive; -use Utopia\Mqtt\Packet; -use Utopia\Mqtt\Subscription\Store; use Utopia\Telemetry\Adapter as Telemetry; use Utopia\Telemetry\Counter; use Utopia\Telemetry\Histogram; -use Utopia\Telemetry\UpDownCounter; +/** + * The MQTT producer: publishes messages onto the 'mqtt' pub/sub channel for the broker workers + * to fan out, and owns the broker telemetry instruments. Connection state, keep-alive and the + * subscription index now live inside the broker (utopia-php/mqtt Server), so they are gone here. + */ class Mqtt extends MessagingAdapter { private const CHANNEL = 'mqtt'; - /** - * Connection registry. - * - * [FD] -> Connection { protocol, prefix, identity, packetId, active } - * - * @var array - */ - public array $connections = []; - - // Telemetry instruments the broker records connection and delivery outcomes on - // (accepted/rejected, granted/denied, delivered/dropped). A no-op telemetry adapter - // yields no-op instruments, so the broker runs untelemetered under raw protocol tests. - public readonly Counter $connectionsOpened; - public readonly UpDownCounter $connectionsActive; - public readonly Counter $subscriptions; public readonly Counter $messagesPublished; public readonly Counter $messagesDelivered; public readonly Counter $messagesDropped; public readonly Counter $messagesAcked; public readonly Counter $pubacksReceived; public readonly Counter $reauth; - public readonly Counter $bytesReceived; - public readonly Counter $bytesSent; public readonly Histogram $authDuration; public readonly Histogram $connectionDuration; public readonly Histogram $messageSize; - /** Keep-alive reaper wheel: connections register their deadline here, the tick drains it. */ - public readonly Keepalive $keepAlive; - - private ?Store $subscriptionStore = null; - public function __construct(Telemetry $telemetry, private readonly PubSub $pubsub) { - $this->connectionsOpened = $telemetry->createCounter('mqtt.connections.opened'); - $this->connectionsActive = $telemetry->createUpDownCounter('mqtt.connections.active'); - $this->subscriptions = $telemetry->createCounter('mqtt.subscriptions'); $this->messagesPublished = $telemetry->createCounter('mqtt.messages.published'); $this->messagesDelivered = $telemetry->createCounter('mqtt.messages.delivered'); $this->messagesDropped = $telemetry->createCounter('mqtt.messages.dropped'); $this->messagesAcked = $telemetry->createCounter('mqtt.messages.acked'); $this->pubacksReceived = $telemetry->createCounter('mqtt.puback.received'); $this->reauth = $telemetry->createCounter('mqtt.reauth'); - $this->bytesReceived = $telemetry->createCounter('mqtt.bytes.received', 'By'); - $this->bytesSent = $telemetry->createCounter('mqtt.bytes.sent', 'By'); $this->authDuration = $telemetry->createHistogram('mqtt.auth.duration', 's'); $this->connectionDuration = $telemetry->createHistogram('mqtt.connection.duration', 's'); $this->messageSize = $telemetry->createHistogram('mqtt.message.size', 'By'); - $this->keepAlive = new Keepalive(); } /** - * The subscription index, created lazily so the adapter owns it rather than - * receiving it — the in-memory tree has no external dependency to wire in. - */ - private function subscriptionStore(): Store - { - return $this->subscriptionStore ??= new Store(); - } - - /** Get or create the connection state for a file descriptor. */ - public function open(int $fd): Connection - { - return $this->connections[$fd] ??= new Connection($fd); - } - - /** - * Drop a connection: balance the active gauge, remove every subscription, and - * forget its state. The transport-level socket close is handled by the caller. - */ - public function close(int $fd): void - { - $connection = $this->connections[$fd] ?? null; - if ($connection !== null) { - if ($connection->active) { - $this->connectionsActive->add(-1); - $this->connectionDuration->record(microtime(true) - $connection->openedAt); - } - $this->keepAlive->remove($fd); - } - $this->unsubscribe($fd); - unset($this->connections[$fd]); - } - - /** - * Subscribe a connection to topic filters. $identifier is the fd, $channels the - * topic filters; roles, queries and $subscriptionId have no MQTT meaning and are - * ignored (the store keys by topic). The granted QoS is 1 and the user id comes - * from the resolved identity so the subscription store can scale per client. - * - * @param string $subscriptionId ignored (part of the Messaging adapter contract) - * @param array $roles ignored - * @param array $channels topic filters - * @param array $queryGroup ignored - * @param int $qos granted QoS stored per subscription (delivery is clamped to it) - */ - public function subscribe(string $projectId, mixed $identifier, string $subscriptionId, array $roles, array $channels, array $queryGroup = [], int $qos = Packet::QOS_1): void - { - $userId = $this->connections[$identifier]->identity['userId'] ?? ''; - - foreach ($channels as $topic) { - $this->subscriptionStore()->subscribe( - $projectId, - $userId, - $topic, - $identifier, - $qos, - ); - } - } - - /** Remove every subscription for a connection (used on close). */ - public function unsubscribe(mixed $identifier): void - { - $this->subscriptionStore()->close($identifier); - } - - /** - * Publish a message onto the 'mqtt' pub/sub channel for fan-out. Every broker - * worker listens on that channel and delivers to its own local subscribers, so a - * publish reaches subscribers regardless of which worker holds them — the MQTT - * analogue of Realtime::send publishing to the realtime firehose. - * - * MQTT carries raw bytes, so the message and its inbound QoS ride in $options - * ($options['payload'], $options['qos']) rather than the array $payload; - * $channels holds the topics. The payload is base64-encoded to survive the JSON - * envelope. + * Publish a message onto the 'mqtt' pub/sub channel for fan-out. Every broker worker listens + * on that channel and delivers to its own local subscribers. The binary MQTT payload and its + * QoS ride in $options ($options['payload'], $options['qos'], $options['sequence']); $channels + * holds the topics. The payload is base64-encoded to survive the JSON envelope. * * @param array $payload unused for MQTT (payload is binary, see $options) * @param array $events ignored @@ -171,36 +72,19 @@ class Mqtt extends MessagingAdapter } } - /** Remove a single topic subscription (MQTT UNSUBSCRIBE). */ - public function unsubscribeSubscription(int $fd, string $topic): void - { - $this->subscriptionStore()->unsubscribe($topic, $fd); - } - /** - * The fds subscribed to a topic in a project, each mapped to its granted QoS. + * Part of the messaging-adapter contract but unused for MQTT: subscriptions are owned by the + * broker (utopia-php/mqtt Server records them from the SUBACK the Handler returns). * - * @return array fd => granted QoS + * @param array $roles + * @param array $channels + * @param array $queryGroup */ - public function getSubscribers(string $projectId, string $topic): array + public function subscribe(string $projectId, mixed $identifier, string $subscriptionId, array $roles, array $channels, array $queryGroup = []): void { - return $this->subscriptionStore()->getSubscribers($projectId, $topic); } - public function hasSubscriber(string $projectId, string $topic): bool + public function unsubscribe(mixed $identifier): void { - return $this->subscriptionStore()->getSubscribers($projectId, $topic) !== []; - } - - /** - * The subscription-store record for an fd: its project, user, and subscriptions, - * or null when the fd holds none. This is the store's copy (the prefix/userId - * captured at subscribe time), not the live Connection object from open(). - * - * @return array{prefix: string, userId: string, subs: array}|null - */ - public function getConnection(int $fd): ?array - { - return $this->subscriptionStore()->getConnection($fd); } } diff --git a/src/Appwrite/Mqtt/Dispatcher.php b/src/Appwrite/Mqtt/Dispatcher.php deleted file mode 100644 index 17fb6ac79b..0000000000 --- a/src/Appwrite/Mqtt/Dispatcher.php +++ /dev/null @@ -1,61 +0,0 @@ - */ - private readonly array $handlers; - - /** - * @param array $handlers each labelled with its packet type (self::LABEL_TYPE) - */ - public function __construct(array $handlers) - { - $table = []; - foreach ($handlers as $handler) { - $type = $handler->getLabels()[self::LABEL_TYPE] - ?? throw new Exception(Exception::GENERAL_SERVER_ERROR, 'MQTT packet handler is missing the packetType label.'); - - $table[$type] = $handler; - } - - $this->handlers = $table; - } - - /** - * Dispatch to the handler for this packet type. Unhandled types (e.g. PUBACK) - * are ignored, matching a broker that acknowledges only what it must. - */ - public function dispatch(Container $container, int $type): void - { - $handler = $this->handlers[$type] ?? null; - if ($handler === null) { - return; - } - - $args = []; - foreach ($handler->getOptions() as $option) { - $args[] = $container->get($option['name']); - } - - ($handler->getCallback())(...$args); - } -} diff --git a/src/Appwrite/Mqtt/Handler.php b/src/Appwrite/Mqtt/Handler.php new file mode 100644 index 0000000000..e398931d87 --- /dev/null +++ b/src/Appwrite/Mqtt/Handler.php @@ -0,0 +1,343 @@ +authMethod ?? ''; + + $connection->prefix = $connect->userProperties()['projectId'] ?? ''; + Span::add('project.id', $connection->prefix); + Span::add('mqtt.clean_start', $connect->cleanStart); + Span::add('mqtt.auth_method', $authMethod); + + $authenticator = $this->container->get('authenticator'); + + $start = microtime(true); + $identity = $authenticator($connection->prefix, $authMethod, $connect->authData ?? ''); + $this->mqtt->authDuration->record(microtime(true) - $start); + + if ($identity === []) { + Span::add('mqtt.result', 'rejected'); + return Connack::refuse(Connack::NOT_AUTHORIZED); + } + + $connection->identity = $identity; + Span::add('user.id', $identity['userId'] ?? ''); + + // Rate-limit CONNECT per user (keyed on userId until the infra surfaces client IP). + if (System::getEnv('_APP_OPTIONS_ABUSE', 'enabled') === 'enabled') { + $getRedis = $this->container->get('getRedis'); + $timeLimit = new TimeLimitRedis('mqtt:connect:{userId}', 128, 60, $getRedis()); + $timeLimit->setParam('{userId}', $identity['userId'] ?? ''); + + if ((new Abuse($timeLimit))->check()) { + Span::add('mqtt.result', 'abuse'); + return Connack::refuse(Connack::QUOTA_EXCEEDED); + } + } + + // The per-device session anchor: the client id, or an account-level fallback so reconnects + // resume the same session (the offline-replay cursor is keyed on it). + $clientId = $connect->clientId; + if ($clientId === '') { + $clientId = 'custom_' . $connection->prefix . '_' . ($identity['userId'] ?? ''); + } + $connection->setClientId($clientId); + Span::add('mqtt.client_id', $connection->getClientId()); + + return Connack::accept(); + } + + public function onAuthenticate(Auth $auth, Connection $connection): Connack|Auth|Disconnect + { + $projectId = $auth->userProperties()['projectId'] ?? ''; + + $identity = []; + if ($projectId !== '' && $projectId === $connection->prefix) { + $authenticator = $this->container->get('authenticator'); + $start = microtime(true); + $identity = $authenticator($projectId, $auth->method, $auth->data); + $this->mqtt->authDuration->record(microtime(true) - $start); + } + + // Reauth only refreshes the credential for the identity resolved at CONNECT — it must not + // switch user or project, which would leak the previous user's subscriptions. + if ($identity === [] || ($identity['userId'] ?? '') !== ($connection->identity['userId'] ?? '')) { + $this->mqtt->reauth->add(1, ['result' => 'rejected']); + Span::add('mqtt.result', 'rejected'); + return Disconnect::refuse(Disconnect::NOT_AUTHORIZED); + } + + $connection->identity = $identity; + $this->mqtt->reauth->add(1, ['result' => 'success']); + Span::add('mqtt.result', 'reauthenticated'); + + return Auth::success($auth->method); + } + + public function onSubscribe(Subscribe $subscribe, Connection $connection): Suback + { + $authorizer = $this->container->get('authorizer'); + $identity = $connection->identity; + + $projectDB = $this->getProjectDB($connection->prefix); + $authorization = $projectDB->getAuthorization(); + + /** @var User $user */ + $user = $authorization->skip(fn () => $projectDB->getDocument('users', $identity['userId'] ?? '')); + $roles = $user->getRoles($authorization); + + $allowed = []; + foreach ($subscribe->filters() as $filter) { + if (!isset($allowed[$filter->topic]) && ($authorizer === null || $authorizer($identity, $filter->topic))) { + $allowed[$filter->topic] = true; + } + } + + $topicsById = []; + if ($allowed !== []) { + $documents = $authorization->skip(fn () => $projectDB->find('topics', [ + Query::equal('$id', array_keys($allowed)), + Query::limit(\count($allowed)), + ])); + foreach ($documents as $document) { + $topicsById[$document->getId()] = $document; + } + } + + $suback = new Suback(); + $grantedTopics = []; + + foreach ($subscribe->filters() as $filter) { + Span::add('mqtt.topic', $filter->topic); + + $document = $topicsById[$filter->topic] ?? null; + if (!isset($allowed[$filter->topic]) || $document === null) { + $suback->deny(); + continue; + } + + if (!$this->authorizedForTopic($document->getAttribute('subscribe', []) ?? [], $roles)) { + $suback->deny(); + continue; + } + + $topicQos = $document->getAttribute('qos'); + $grantedQos = min($filter->qos, $topicQos === null ? Packet::QOS_1 : (int) $topicQos); + + $suback->grant($grantedQos); + $grantedTopics[$filter->topic] = [$document, $grantedQos]; + } + + if ($grantedTopics !== []) { + $this->replayBacklog($connection, $projectDB, $grantedTopics); + } + + return $suback; + } + + public function onUnsubscribe(Unsubscribe $unsubscribe, Connection $connection): Unsuback + { + // The broker has already dropped the filters from its subscription index. + $unsuback = new Unsuback(); + foreach ($unsubscribe->filters() as $filter) { + $unsuback->success(); + } + + return $unsuback; + } + + /** + * Appwrite is server -> client push: clients never PUBLISH, so an inbound one is ignored. + * Server-initiated fan-out goes through deliver() instead. + * + * @param iterable $subscribers + */ + public function onPublish(Publish $publish, Connection $connection, iterable $subscribers): void + { + } + + /** + * Fan a message out to a topic's local subscribers, each at the QoS granted to that + * subscription (clamped by the message QoS). Returns the number delivered. + */ + public function deliver(Server $server, string $projectId, string $topic, string $message, int $qos, int $sequence): int + { + $delivered = 0; + + foreach ($server->subscribers($projectId, $topic) as [$connection, $grantedQos]) { + $deliveryQos = min($qos, $grantedQos); + $connection->publish($topic, $message, qos: $deliveryQos, sequence: $sequence); + $this->mqtt->messagesDelivered->add(1, ['qos' => $deliveryQos]); + $delivered++; + } + + return $delivered; + } + + public function onPuback(Puback $puback, Connection $connection): void + { + $delivery = $connection->acknowledge($puback->packetId); + if ($delivery === null) { + return; + } + + Span::add('mqtt.topic', $delivery['topic']); + Span::add('mqtt.sequence', $delivery['sequence']); + $this->mqtt->messagesAcked->add(1); + $this->mqtt->pubacksReceived->add(1); + + $getCache = $this->container->get('getCache'); + $cache = $getCache(); + $key = $this->cursorKey($connection); + $topic = $delivery['topic']; + $cursor = (int) $delivery['cursor']; + + $current = $cache->loadMany($key, self::REPLAY_TTL, [$topic]); + if ($cursor > (int) ($current[$topic]['sequence'] ?? -1)) { + $cache->saveMany($key, [$topic => ['sequence' => $cursor]], 0); + } + } + + public function onDisconnect(?Disconnect $disconnect, Connection $connection): void + { + // The broker already removed the connection, its subscriptions and keep-alive slot, and + // records the active-connections gauge itself. Record the connection lifetime for + // accepted sessions. + if (($connection->identity['userId'] ?? '') !== '') { + $this->mqtt->connectionDuration->record(microtime(true) - $connection->openedAt); + } + } + + /** + * Whether the subscriber's roles satisfy a topic's subscribe roles. No configured roles (or an + * explicit `any`) means the topic is open to everyone. + * + * @param array $topicRoles + * @param array $userRoles + */ + private function authorizedForTopic(array $topicRoles, array $userRoles): bool + { + if ($topicRoles === [] || \in_array(Role::any()->toString(), $topicRoles, true)) { + return true; + } + + return \array_intersect($topicRoles, $userRoles) !== []; + } + + /** + * Replay the offline backlog for freshly granted QoS 1 topics: resume each topic's cursor, + * then re-deliver stored messages via the connection (DUP flagged), tagging each with its + * durable sequence so a later PUBACK maps back. + * + * @param array $grantedTopics filter => [document, grantedQos] + */ + private function replayBacklog(Connection $connection, Database $projectDB, array $grantedTopics): void + { + $getCache = $this->container->get('getCache'); + $getPlanForUser = $this->container->get('getPlanForUser'); + $cache = $getCache(); + $key = $this->cursorKey($connection); + $maxDepth = max(1, $getPlanForUser(new Document(['$id' => $connection->prefix]), $connection->identity['userId'] ?? '')); + + $expiry = 0; + foreach ($grantedTopics as [$document]) { + $expiry = max($expiry, (int) $document->getAttribute('expiry', 0)); + } + if ($expiry <= 0) { + $expiry = self::REPLAY_TTL; + } + + if ($connection->cleanStart) { + $cache->purge($key); + } + + $cursors = $cache->loadMany($key, $expiry); + $persist = []; + + foreach ($grantedTopics as $filter => [$document, $grantedQos]) { + $tail = (int) $document->getAttribute('sequence', 0); + $from = (int) ($cursors[$filter]['sequence'] ?? $tail); + $persist[$filter] = ['sequence' => $from]; + + if ($grantedQos < 1 || $tail <= $from) { + continue; + } + + $connection->resume($filter, $from); + + $start = max($from + 1, $tail - $maxDepth + 1); + $messages = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('appwritePushLedger', [ + Query::equal('topic', [$filter]), + Query::greaterThanEqual('sequence', $start), + Query::orderAsc('sequence'), + Query::limit($maxDepth), + ])); + + foreach ($messages as $message) { + $stored = $message->getAttribute('data'); + $data = \is_string($stored) ? $stored : (string) json_encode($stored); + $connection->publish($filter, $data, qos: 1, dup: true, sequence: (int) $message->getAttribute('sequence')); + } + } + + if ($persist !== []) { + $cache->saveMany($key, $persist, $expiry); + } + } + + private function cursorKey(Connection $connection): string + { + return 'appwrite:push:cursor:' . $connection->prefix + . ':' . ($connection->identity['userId'] ?? '') + . ':' . $connection->getClientId(); + } + + private function getProjectDB(string $projectId): Database + { + $getConsoleDB = $this->container->get('getConsoleDB'); + $getProjectDB = $this->container->get('getProjectDB'); + + $consoleDB = $getConsoleDB(); + $project = $consoleDB->getAuthorization()->skip(fn () => $consoleDB->getDocument('projects', $projectId)); + + return $getProjectDB($project); + } +} diff --git a/src/Appwrite/Mqtt/Handlers/Auth.php b/src/Appwrite/Mqtt/Handlers/Auth.php deleted file mode 100644 index c165fff569..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Auth.php +++ /dev/null @@ -1,86 +0,0 @@ -desc('Re-authenticate a live connection with a fresh credential') - ->label(Dispatcher::LABEL_TYPE, Packet::AUTH) - ->inject('mqtt') - ->inject('authenticator') - ->inject('connection') - ->inject('packet') - ->inject('response') - ->callback($this->action(...)); - } - - /** - * @param (callable(string, string, string): array)|null $authenticator - */ - public function action(Mqtt $mqtt, ?callable $authenticator, Connection $connection, Packet $packet, Response $response): void - { - $body = $packet->body; - $method = ''; - $data = ''; - $userProperties = []; - - if ($body !== '') { - // $body[0] is the reason code (0x19 re-authenticate); - // from offset 1 everything is the MQTT 5.0 property block. - [$properties] = Properties::parse($body, 1); - $method = (string) ($properties->get(Property::AUTHENTICATION_METHOD) ?? ''); - $data = (string) ($properties->get(Property::AUTHENTICATION_DATA) ?? ''); - $userProperties = $properties->user(); - } - - // The AUTH packet re-sends projectId as a User Property. - if ($authenticator !== null) { - $projectId = $userProperties['projectId'] ?? ''; - - $identity = []; - if ($projectId !== '' && $projectId === $connection->prefix) { - $start = microtime(true); - $identity = $authenticator($projectId, $method, $data); - $mqtt->authDuration->record(microtime(true) - $start); - } - - // Reauth only refreshes the credential for the identity resolved at CONNECT — it - // must not switch the user (or project). Allowing a switch would keep the previous - // user's subscriptions on this connection, leaking their fan-out to the new user - // and breaking PUBACK ownership checks. A mismatch (or failure) drops the connection. - if ($identity === [] || ($identity['userId'] ?? '') !== ($connection->identity['userId'] ?? '')) { - $mqtt->reauth->add(1, ['result' => 'rejected']); - Span::add('mqtt.result', 'rejected'); - $response->send(V5::disconnect(V5::REASON_NOT_AUTHORIZED)); - $response->close(); - return; - } - - $connection->identity = $identity; - $mqtt->reauth->add(1, ['result' => 'success']); - Span::add('mqtt.result', 'reauthenticated'); - } - - // Acknowledge success on the live connection with an AUTH packet that echoes - // the authentication method back. - $properties = new Properties(); - if ($method !== '') { - $properties->add(new Property(Property::AUTHENTICATION_METHOD, $method)); - } - $response->send(V5::auth(V5::AUTH_SUCCESS, $properties)); - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Connect.php b/src/Appwrite/Mqtt/Handlers/Connect.php deleted file mode 100644 index 72f29d553d..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Connect.php +++ /dev/null @@ -1,130 +0,0 @@ -desc('Authenticate a CONNECT and open the session') - ->label(Dispatcher::LABEL_TYPE, Packet::CONNECT) - ->inject('authenticator') - ->inject('mqtt') - ->inject('connection') - ->inject('packet') - ->inject('response') - ->callback($this->action(...)); - } - - /** - * @param (callable(string, string, string): array)|null $authenticator - */ - public function action(?callable $authenticator, Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void - { - $body = $packet->body; - $offset = 0; - [, $offset] = Packet::readString($body, $offset); // protocol name - - $level = ord($body[$offset]); - $connection->protocol = $level; - $offset += 1; // protocol level - $offset += 1; // connect flags - [$keepAlive, $offset] = Packet::readInt16($body, $offset); // keep alive (seconds) - $connection->keepAlive = $keepAlive; - - $connection->cleanStart = Packet::isCleanStart($body); - Span::add('mqtt.clean_start', $connection->cleanStart); - - // MQTT 3.1.1 carries no property block; enhanced auth and metadata are 5.0 only. - $authMethod = ''; - $authData = ''; - $user = []; - if ($level >= 5) { - [$properties] = Properties::parse($body, $offset); - $authMethod = (string) ($properties->get(Property::AUTHENTICATION_METHOD) ?? ''); - $authData = (string) ($properties->get(Property::AUTHENTICATION_DATA) ?? ''); - $user = $properties->user(); - } - - $projectId = $user['projectId'] ?? ''; - $connection->prefix = $projectId; - Span::add('project.id', $projectId); - Span::add('mqtt.auth_method', $authMethod); - - if ($authenticator !== null) { - $start = microtime(true); - $identity = $authenticator($projectId, $authMethod, $authData); - $duration = microtime(true) - $start; - $mqtt->authDuration->record($duration); - Span::add('mqtt.auth.duration', $duration); - - if ($identity === []) { - $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'rejected']); - Span::add('mqtt.result', 'rejected'); - $response->send($this->connack($level, false)); - $response->close(); - return; - } - - $connection->identity = $identity; - Span::add('user.id', $identity['userId'] ?? ''); - - // Rate-limit CONNECT per user. - // TODO: in future this will be IP based; currently keyed on userId because the - // infra does not surface the client IP to the broker. - if (System::getEnv('_APP_OPTIONS_ABUSE', 'enabled') === 'enabled') { - $timeLimit = new TimeLimitRedis('mqtt:connect:{userId}', 128, 60, getRedis()); - $timeLimit->setParam('{userId}', $identity['userId'] ?? ''); - - if ((new Abuse($timeLimit))->check()) { - $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'abuse']); - Span::add('mqtt.result', 'abuse'); - $response->send($this->connack($level, false)); - $response->close(); - return; - } - } - } - - // The per-device session anchor: the client-supplied id, or an account-level fallback so - // reconnects resume the same session (the offline-replay cursor is keyed on it). Resolved - // here rather than in the library, which only server-assigns a generic id for an empty one. - $clientId = Packet::getClientId($body); - if ($clientId === '') { - $clientId = 'custom_' . $connection->prefix . '_' . ($connection->identity['userId'] ?? ''); - } - $connection->setClientId($clientId); - Span::add('mqtt.client_id', $connection->getClientId()); - - $mqtt->connectionsOpened->add(1, ['auth_method' => $authMethod, 'result' => 'accepted']); - $mqtt->connectionsActive->add(1); - $connection->active = true; - $response->send($this->connack($level, true)); - } - - /** CONNACK, with the acknowledgement code in each version's own vocabulary. */ - private function connack(int $level, bool $accepted): string - { - if ($level >= 5) { - return V5::connack($accepted ? V5::REASON_SUCCESS : V5::REASON_NOT_AUTHORIZED); - } - - return V3::connack($accepted ? V3::RETURN_ACCEPTED : V3::RETURN_NOT_AUTHORIZED); - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Disconnect.php b/src/Appwrite/Mqtt/Handlers/Disconnect.php deleted file mode 100644 index e9ab621e69..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Disconnect.php +++ /dev/null @@ -1,25 +0,0 @@ -desc('Close the connection on client request') - ->label(Dispatcher::LABEL_TYPE, Packet::DISCONNECT) - ->inject('response') - ->callback($this->action(...)); - } - - public function action(Response $response): void - { - $response->close(); - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Ping.php b/src/Appwrite/Mqtt/Handlers/Ping.php deleted file mode 100644 index fded3af7af..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Ping.php +++ /dev/null @@ -1,25 +0,0 @@ -desc('Reply to a client heartbeat') - ->label(Dispatcher::LABEL_TYPE, Packet::PINGREQ) - ->inject('response') - ->callback($this->action(...)); - } - - public function action(Response $response): void - { - $response->send(Packet::pingresp()); - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Puback.php b/src/Appwrite/Mqtt/Handlers/Puback.php deleted file mode 100644 index e0511eeaa0..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Puback.php +++ /dev/null @@ -1,75 +0,0 @@ -desc('Acknowledge a delivered QoS 1 message and advance the subscriber cursor') - ->label(Dispatcher::LABEL_TYPE, Packet::PUBACK) - ->inject('mqtt') - ->inject('connection') - ->inject('packet') - ->inject('response') - ->callback($this->action(...)); - } - - public function action(Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void - { - $body = $packet->body; - - if (\strlen($body) < 2) { - return; - } - - $connectionMetdata = $mqtt->getConnection($connection->fd); - if ($connectionMetdata['userId'] !== $connection->identity['userId'] || $connectionMetdata['prefix'] !== $connection->prefix) { - $response->send(V5::disconnect(V5::REASON_NOT_AUTHORIZED)); - $response->close(); - return; - } - - // PUBACK opens with the two-byte packet id in both versions. - [$packetId] = Packet::readInt16($body, 0); - - $delivery = $connection->acknowledge($packetId); - if ($delivery === null) { - return; - } - - Span::add('mqtt.topic', $delivery['topic']); - Span::add('mqtt.sequence', $delivery['sequence']); - $mqtt->messagesAcked->add(1); - $mqtt->pubacksReceived->add(1); - - // Save how far the client has caught up (the "cursor" from acknowledge), not the - // sequence it just acked — so an out-of-order ack can't skip a still-unacked - // message. Only ever move the cursor forward, so two acks at once can't rewind it. - $cache = getCache(); - $cursorKey = 'appwrite:push:cursor:' . $connection->prefix . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); - $topic = $delivery['topic']; - $cursor = (int) $delivery['cursor']; - - $current = $cache->loadMany($cursorKey, 3600, [$topic]); - if ($cursor > (int) ($current[$topic]['sequence'] ?? -1)) { - $cache->saveMany($cursorKey, [$topic => ['sequence' => $cursor]], 3600); - } - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Subscribe.php b/src/Appwrite/Mqtt/Handlers/Subscribe.php deleted file mode 100644 index 2bbe6f30e4..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Subscribe.php +++ /dev/null @@ -1,238 +0,0 @@ -desc('Subscribe to topic filters, enforcing the ACL') - ->label(Dispatcher::LABEL_TYPE, Packet::SUBSCRIBE) - ->inject('authorizer') - ->inject('mqtt') - ->inject('connection') - ->inject('packet') - ->inject('response') - ->callback($this->action(...)); - } - - /** - * @param (callable(array, string): bool)|null $authorizer - */ - public function action(?callable $authorizer, Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void - { - $body = $packet->body; - $offset = 0; - $packetId = substr($body, 0, 2); - $offset += 2; - - // MQTT 5.0 carries a property block before the filters; skip it to reach them. - if ($connection->protocol >= 5) { - $offset = Properties::skip($body, $offset); - } - - $identity = $connection->identity; - - $denied = $connection->protocol >= 5 ? V5::REASON_NOT_AUTHORIZED : V3::SUBSCRIBE_FAILURE; - - $consoleDatabase = getConsoleDB(); - $project = $consoleDatabase->getAuthorization()->skip(fn () => $consoleDatabase->getDocument('projects', $connection->prefix)); - $projectDB = getProjectDB($project); - - // The subscriber's roles, resolved once, to enforce each topic's subscribe ACL below. - $authorization = $projectDB->getAuthorization(); - /** @var User $user */ - $user = $authorization->skip(fn () => $projectDB->getDocument('users', $connection->identity['userId'] ?? '')); - $roles = $user->getRoles($authorization); - - // Parse every (filter, requested QoS) in order; the SUBACK carries one reason code - // per filter in this order. Bits 0-1 of the subscription options byte are the max QoS. - $filters = []; - while ($offset < strlen($body)) { - [$filter, $offset] = Packet::readString($body, $offset); - $filters[] = [$filter, isset($body[$offset]) ? \ord($body[$offset]) & 0x03 : 0]; - $offset += 1; - } - - $allowed = []; - foreach ($filters as [$filter]) { - if (!isset($allowed[$filter]) && ($authorizer === null || $authorizer($identity, $filter))) { - $allowed[$filter] = true; - } - } - - $topicsById = []; - if ($allowed !== []) { - $documents = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('topics', [ - Query::equal('$id', array_keys($allowed)), - Query::limit(\count($allowed)), - ])); - foreach ($documents as $document) { - $topicsById[$document->getId()] = $document; - } - } - - $granted = ''; - $topicDocuments = []; // filter => topic document, reused for replay below - $grantedQosByTopic = []; // filter => granted QoS, so replay honours it below - foreach ($filters as [$filter, $requestedQos]) { - Span::add('mqtt.topic', $filter); - - if (!isset($allowed[$filter])) { - $granted .= chr($denied); - $mqtt->subscriptions->add(1, ['result' => 'denied']); - continue; - } - - // A filter is granted only if it maps to an existing project topic. - $topicDocument = $topicsById[$filter] ?? null; - if ($topicDocument === null) { - $granted .= chr($denied); - $mqtt->subscriptions->add(1, ['result' => 'unknown']); - continue; - } - - // The topic's subscribe roles gate who may subscribe. - if (!$this->authorizedForTopic($topicDocument->getAttribute('subscribe', []) ?? [], $roles)) { - $granted .= chr($denied); - $mqtt->subscriptions->add(1, ['result' => 'forbidden']); - continue; - } - - // Requested max QoS, capped by the topic's configured QoS (null = no cap, broker max 1). - $topicQos = $topicDocument->getAttribute('qos'); - $grantedQos = min($requestedQos, $topicQos === null ? Packet::QOS_1 : (int) $topicQos); - - $mqtt->subscribe($connection->prefix, $connection->fd, '', [], [$filter], [], $grantedQos); - $granted .= chr($grantedQos); - $mqtt->subscriptions->add(1, ['result' => 'granted']); - - $topicDocuments[$filter] = $topicDocument; - $grantedQosByTopic[$filter] = $grantedQos; - } - - $response->send( - $connection->protocol >= 5 - ? V5::suback($packetId, $granted) - : V3::suback($packetId, $granted), - ); - - if ($topicDocuments === []) { - return; - } - - $topics = array_keys($topicDocuments); - - $expiry = 0; - foreach ($topicDocuments as $topicDocument) { - $expiry = max($expiry, (int) $topicDocument->getAttribute('expiry', 0)); - } - if ($expiry <= 0) { - $expiry = 3600; - } - - // Replay depth comes from the user's org plan (self-hosted default; see getPlanForUser) - $maxDepth = max(1, getPlanForUser($project, $connection->identity['userId'] ?? '')); - - $cache = getCache(); - - $cursorKey = 'appwrite:push:cursor:' . $connection->prefix . ':' . $connection->identity['userId'] . ':' . $connection->getClientId(); - - // A clean-start session discards any persisted cursor before resuming. - if ($connection->cleanStart) { - $cache->purge($cursorKey); - } - - $cursors = $cache->loadMany($cursorKey, $expiry); - $known = array_keys($cursors); - $newTopics = array_values(array_diff($topics, $known)); - $resumeTopics = array_values(array_intersect($topics, $known)); - - // Current tail (topics.sequence) per subscribed topic: the seed for new topics and - // the upper bound for replay. Reuses the documents fetched during the grant loop. - $tails = []; - foreach ($topicDocuments as $topic => $topicDocument) { - $tails[$topic] = (int) $topicDocument->getAttribute('sequence', 0); - } - - $persist = []; - foreach ($newTopics as $topic) { - $persist[$topic] = ['sequence' => $tails[$topic] ?? 0]; - } - foreach ($resumeTopics as $topic) { - $persist[$topic] = $cursors[$topic]; - } - - foreach ($resumeTopics as $topic) { - if (($grantedQosByTopic[$topic] ?? Packet::QOS_1) < Packet::QOS_1) { - continue; - } - - $from = (int) ($cursors[$topic]['sequence'] ?? 0); - $tail = $tails[$topic] ?? $from; - if ($tail <= $from) { - continue; - } - - $start = max($from + 1, $tail - $maxDepth + 1); - $messages = $projectDB->getAuthorization()->skip(fn () => $projectDB->find('appwritePushLedger', [ - Query::equal('topic', [$topic]), - Query::greaterThanEqual('sequence', $start), - Query::orderAsc('sequence'), - Query::limit($maxDepth), - ])); - - foreach ($messages as $message) { - $packetId = $connection->nextPacketId(); - // The ledger `data` (json filter) already holds the encoded envelope - // string the live path publishes; re-encoding it would double-encode. - $stored = $message->getAttribute('data'); - $data = \is_string($stored) ? $stored : (string) json_encode($stored); - $publish = $connection->protocol >= 5 - ? V5::publish($topic, $data, Packet::QOS_1, $packetId, dup: true) - : V3::publish($topic, $data, Packet::QOS_1, $packetId, dup: true); - $response->send($publish); - $connection->track($packetId, $topic, (int) $message->getAttribute('sequence')); - } - } - - if ($persist !== []) { - $cache->saveMany($cursorKey, $persist, $expiry); - } - } - - /** - * Whether the subscriber's roles satisfy a topic's subscribe roles. No configured roles - * means the topic is open to everyone, as does an explicit `any` role. - * - * @param array $topicRoles the topic's `subscribe` roles - * @param array $userRoles the subscriber's resolved roles - */ - private function authorizedForTopic(array $topicRoles, array $userRoles): bool - { - if ($topicRoles === []) { - return true; - } - - if (\in_array(Role::any()->toString(), $topicRoles, true)) { - return true; - } - - return \array_intersect($topicRoles, $userRoles) !== []; - } -} diff --git a/src/Appwrite/Mqtt/Handlers/Unsubscribe.php b/src/Appwrite/Mqtt/Handlers/Unsubscribe.php deleted file mode 100644 index 572a04ed03..0000000000 --- a/src/Appwrite/Mqtt/Handlers/Unsubscribe.php +++ /dev/null @@ -1,55 +0,0 @@ -desc('Remove topic-filter subscriptions') - ->label(Dispatcher::LABEL_TYPE, Packet::UNSUBSCRIBE) - ->inject('mqtt') - ->inject('connection') - ->inject('packet') - ->inject('response') - ->callback($this->action(...)); - } - - public function action(Mqtt $mqtt, Connection $connection, Packet $packet, Response $response): void - { - $body = $packet->body; - $offset = 0; - $packetId = substr($body, 0, 2); - $offset += 2; - - // MQTT 5.0 carries a property block before the filters; skip it to reach them. - if ($connection->protocol >= 5) { - $offset = Properties::skip($body, $offset); - } - - $count = 0; - while ($offset < strlen($body)) { - [$filter, $offset] = Packet::readString($body, $offset); - $mqtt->unsubscribeSubscription($connection->fd, $filter); - $count++; - } - - // 5.0 carries a Success reason code per filter; 3.1.1 UNSUBACK is bare. - $response->send( - $connection->protocol >= 5 - ? V5::unsuback($packetId, $count) - : V3::unsuback($packetId), - ); - } -} diff --git a/src/Appwrite/Mqtt/Response.php b/src/Appwrite/Mqtt/Response.php deleted file mode 100644 index fee6279fde..0000000000 --- a/src/Appwrite/Mqtt/Response.php +++ /dev/null @@ -1,39 +0,0 @@ -server->send($this->fd, $packet); - $this->bytesSent->add(\strlen($packet)); - } - - /** Close the connection. */ - public function close(): void - { - $this->server->close($this->fd); - } -} diff --git a/tests/e2e/Services/Mqtt/MqttSubscriber.php b/tests/e2e/Services/Mqtt/MqttSubscriber.php index 0da7d8802b..df770b1a2a 100644 --- a/tests/e2e/Services/Mqtt/MqttSubscriber.php +++ b/tests/e2e/Services/Mqtt/MqttSubscriber.php @@ -23,6 +23,9 @@ final class MqttSubscriber private int $packetId = 0; + /** @var Packet[] PUBLISH packets read before the SUBACK (replay), drained by consume(). */ + private array $pending = []; + public function __construct( private readonly string $host, private readonly int $port, @@ -89,7 +92,9 @@ final class MqttSubscriber return $codes; } - // Ignore any early PUBLISH replay queued before the SUBACK; consume() reads those. + if ($packet->type === Packet::PUBLISH) { + $this->pending[] = $packet; // replay delivered before the SUBACK; consume() drains it + } } } @@ -107,9 +112,13 @@ final class MqttSubscriber $received = []; while (\count($received) < $limit) { - $packet = $this->readPacket($deadline); - if ($packet === null) { - break; // timeout or disconnect + if ($this->pending !== []) { + $packet = \array_shift($this->pending); + } else { + $packet = $this->readPacket($deadline); + if ($packet === null) { + break; // timeout or disconnect + } } if ($packet->type !== Packet::PUBLISH) { continue; diff --git a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php b/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php deleted file mode 100644 index 8af590c1ef..0000000000 --- a/tests/unit/Appwrite/Messaging/Adapter/MqttTest.php +++ /dev/null @@ -1,164 +0,0 @@ -open($fd); - $mqtt->subscribe($projectId, $fd, '', [], [$topic]); - } - - public function testOpenCreatesAndReusesConnection(): void - { - $mqtt = $this->adapter(); - - $connection = $mqtt->open(7); - - $this->assertInstanceOf(Connection::class, $connection); - $this->assertSame(7, $connection->fd); - $this->assertSame($connection, $mqtt->open(7), 'open() must return the same instance for the same fd'); - $this->assertArrayHasKey(7, $mqtt->connections); - } - - public function testSubscribeExposesSubscriberWithGrantedQos(): void - { - $mqtt = $this->adapter(); - - $this->join($mqtt, 'project-a', 11, 'appwrite/push/user-1'); - - $this->assertSame([11 => 1], $mqtt->getSubscribers('project-a', 'appwrite/push/user-1')); - $this->assertTrue($mqtt->hasSubscriber('project-a', 'appwrite/push/user-1')); - $this->assertFalse($mqtt->hasSubscriber('project-a', 'appwrite/push/user-2')); - } - - /** - * Topic-filter matching flows through to the store: + is one level, # is this - * level onward, an exact filter matches only itself. - * - * @return \Iterator - */ - public static function wildcardProvider(): \Iterator - { - yield 'exact match' => ['test/hello', 'test/hello', true]; - yield 'exact miss' => ['test/hello', 'test/world', false]; - yield '+ one level' => ['test/+', 'test/hello', true]; - yield '+ not multi level' => ['test/+', 'test/a/b', false]; - yield '# multi level' => ['test/#', 'test/a/b', true]; - yield '# matches parent' => ['test/#', 'test', true]; - yield '# not sibling' => ['test/#', 'other', false]; - } - - #[DataProvider('wildcardProvider')] - public function testTopicFilterMatching(string $filter, string $publishTopic, bool $shouldMatch): void - { - $mqtt = $this->adapter(); - $this->join($mqtt, 'project-a', 21, $filter); - - $subscribers = $mqtt->getSubscribers('project-a', $publishTopic); - - $this->assertSame($shouldMatch, isset($subscribers[21])); - } - - public function testSubscribersAreIsolatedPerProject(): void - { - $mqtt = $this->adapter(); - - $this->join($mqtt, 'project-a', 31, 'shared/topic'); - $this->join($mqtt, 'project-b', 32, 'shared/topic'); - - $this->assertSame([31 => 1], $mqtt->getSubscribers('project-a', 'shared/topic')); - $this->assertSame([32 => 1], $mqtt->getSubscribers('project-b', 'shared/topic')); - } - - public function testUnsubscribeSubscriptionRemovesOnlyThatFilter(): void - { - $mqtt = $this->adapter(); - $mqtt->open(41); - $mqtt->subscribe('project-a', 41, '', [], ['orders/new']); - $mqtt->subscribe('project-a', 41, '', [], ['alerts/all']); - - $mqtt->unsubscribeSubscription(41, 'orders/new'); - - $this->assertFalse($mqtt->hasSubscriber('project-a', 'orders/new')); - $this->assertSame([41 => 1], $mqtt->getSubscribers('project-a', 'alerts/all')); - } - - public function testUnsubscribeByTopic(): void - { - $mqtt = $this->adapter(); - $this->join($mqtt, 'project-a', 51, 'news/tech'); - - $mqtt->unsubscribeSubscription(51, 'news/tech'); - - $this->assertFalse($mqtt->hasSubscriber('project-a', 'news/tech')); - } - - public function testUnsubscribeRemovesEveryFilterForConnection(): void - { - $mqtt = $this->adapter(); - $mqtt->open(61); - $mqtt->subscribe('project-a', 61, 'a', [], ['a/one']); - $mqtt->subscribe('project-a', 61, 'b', [], ['b/two']); - - $mqtt->unsubscribe(61); - - $this->assertFalse($mqtt->hasSubscriber('project-a', 'a/one')); - $this->assertFalse($mqtt->hasSubscriber('project-a', 'b/two')); - } - - public function testCloseRemovesSubscriptionsAndForgetsConnection(): void - { - $mqtt = $this->adapter(); - $connection = $mqtt->open(71); - $connection->active = true; - $mqtt->subscribe('project-a', 71, 'sub', [], ['live/feed']); - - $mqtt->close(71); - - $this->assertArrayNotHasKey(71, $mqtt->connections); - $this->assertFalse($mqtt->hasSubscriber('project-a', 'live/feed')); - $this->assertNotSame($connection, $mqtt->open(71), 'a reopened fd is a fresh connection'); - } -} From 72e5465d3b7619b877e7539ccb8ac1b3c31c04ff Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 17 Sep 2026 21:25:50 +0530 Subject: [PATCH 132/146] test(mqtt): point the e2e subscriber at the relocated Packet\Specs\V5 codec --- tests/e2e/Services/Mqtt/MqttSubscriber.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/e2e/Services/Mqtt/MqttSubscriber.php b/tests/e2e/Services/Mqtt/MqttSubscriber.php index df770b1a2a..f005574107 100644 --- a/tests/e2e/Services/Mqtt/MqttSubscriber.php +++ b/tests/e2e/Services/Mqtt/MqttSubscriber.php @@ -5,7 +5,7 @@ declare(strict_types=1); namespace Tests\E2E\Services\Mqtt; use Utopia\Mqtt\Packet; -use Utopia\Mqtt\Packet\V5; +use Utopia\Mqtt\Packet\Specs\V5; use Utopia\Mqtt\Properties; use Utopia\Mqtt\Property; From 8d5e92e288a2429bf78ea48d12de81c693bcded4 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 17 Sep 2026 21:41:29 +0530 Subject: [PATCH 133/146] fix(mqtt): resolve getProjectDB via the container in the SUBSCRIBE authorizer The DI refactor moved the broker's DB/cache resolvers onto the container but left the authorizer closure calling the removed global getProjectDB(), so every SUBSCRIBE threw "Call to undefined function getProjectDB()" before the SUBACK (CONNECT was unaffected as it only uses the authenticator). --- app/init/mqtt/connection.php | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/app/init/mqtt/connection.php b/app/init/mqtt/connection.php index 50ae943d63..baeef339fa 100644 --- a/app/init/mqtt/connection.php +++ b/app/init/mqtt/connection.php @@ -108,8 +108,8 @@ return function (Container $container): void { }; }, []); - $container->set('authorizer', function () use ($getProject): callable { - return function (array $identity, string $topic) use ($getProject): bool { + $container->set('authorizer', function () use ($getProject, $container): callable { + return function (array $identity, string $topic) use ($getProject, $container): bool { $userId = $identity['userId'] ?? ''; $projectId = $identity['projectId'] ?? ''; if ($userId === '' || $projectId === '') { @@ -123,7 +123,8 @@ return function (Container $container): void { return false; } - $dbForProject = getProjectDB($project); + $getProjectDB = $container->get('getProjectDB'); + $dbForProject = $getProjectDB($project); $dbForProject->setAuthorization($authorization); $user = $authorization->skip(fn () => $dbForProject->getDocument('users', $userId)); From fd05c1224f7e4b69e6ba3e15d5263fca83e3cfaf Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 17 Sep 2026 22:01:46 +0530 Subject: [PATCH 134/146] debug(mqtt): temporary onSubscribe diagnostics [revert] --- src/Appwrite/Mqtt/Handler.php | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/src/Appwrite/Mqtt/Handler.php b/src/Appwrite/Mqtt/Handler.php index e398931d87..5cc162da25 100644 --- a/src/Appwrite/Mqtt/Handler.php +++ b/src/Appwrite/Mqtt/Handler.php @@ -166,6 +166,14 @@ class Handler implements MqttHandler $grantedTopics[$filter->topic] = [$document, $grantedQos]; } + \Utopia\CLI\Console::error('MQTT_SUB_DBG prefix=' . $connection->prefix + . ' uid=' . ($identity['userId'] ?? '(none)') + . ' roles=' . \json_encode($roles) + . ' filters=' . \json_encode(\array_map(fn ($f) => [$f->topic, $f->qos], $subscribe->filters())) + . ' allowed=' . \json_encode(\array_keys($allowed)) + . ' foundTopics=' . \json_encode(\array_keys($topicsById)) + . ' codes=' . \json_encode($suback->codes())); + if ($grantedTopics !== []) { $this->replayBacklog($connection, $projectDB, $grantedTopics); } From 4b41eea7d75ec05fac94f3c27511df313daf8133 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 17 Sep 2026 22:02:21 +0530 Subject: [PATCH 135/146] debug(mqtt): fix Console namespace [revert] --- src/Appwrite/Mqtt/Handler.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Appwrite/Mqtt/Handler.php b/src/Appwrite/Mqtt/Handler.php index 5cc162da25..6d3fad0fa5 100644 --- a/src/Appwrite/Mqtt/Handler.php +++ b/src/Appwrite/Mqtt/Handler.php @@ -166,7 +166,7 @@ class Handler implements MqttHandler $grantedTopics[$filter->topic] = [$document, $grantedQos]; } - \Utopia\CLI\Console::error('MQTT_SUB_DBG prefix=' . $connection->prefix + \Utopia\Console::error('MQTT_SUB_DBG prefix=' . $connection->prefix . ' uid=' . ($identity['userId'] ?? '(none)') . ' roles=' . \json_encode($roles) . ' filters=' . \json_encode(\array_map(fn ($f) => [$f->topic, $f->qos], $subscribe->filters())) From 417f0efe8dd196d800f5c7f631c21572db279564 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Thu, 17 Sep 2026 22:24:50 +0530 Subject: [PATCH 136/146] fix(mqtt): make the SUBSCRIBE ACL reads bypass permissions correctly Wire a request Authorization onto the broker's project/console DB handles and skip on that same instance: the DB enforces permissions against the instance set via setAuthorization, and topics can carry empty permissions, so the previous skip on a stale/unwired Authorization silently filtered every topic and denied all grants. onSubscribe now establishes the Authorization after the authorizer runs (it mutates the shared handle). Align the SUBACK denial reason code assertions to the library's 0x80. Removes the temporary diagnostics. --- src/Appwrite/Mqtt/Handler.php | 25 ++++++++++------------ tests/e2e/Services/Mqtt/MqttServerTest.php | 8 +++---- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/src/Appwrite/Mqtt/Handler.php b/src/Appwrite/Mqtt/Handler.php index 6d3fad0fa5..04638170b7 100644 --- a/src/Appwrite/Mqtt/Handler.php +++ b/src/Appwrite/Mqtt/Handler.php @@ -10,6 +10,7 @@ use Utopia\Database\Database; use Utopia\Database\Document; use Utopia\Database\Helpers\Role; use Utopia\Database\Query; +use Utopia\Database\Validator\Authorization; use Utopia\DI\Container; use Utopia\Mqtt\Connection; use Utopia\Mqtt\Handler as MqttHandler; @@ -118,11 +119,6 @@ class Handler implements MqttHandler $identity = $connection->identity; $projectDB = $this->getProjectDB($connection->prefix); - $authorization = $projectDB->getAuthorization(); - - /** @var User $user */ - $user = $authorization->skip(fn () => $projectDB->getDocument('users', $identity['userId'] ?? '')); - $roles = $user->getRoles($authorization); $allowed = []; foreach ($subscribe->filters() as $filter) { @@ -131,6 +127,13 @@ class Handler implements MqttHandler } } + $authorization = new Authorization(); + $projectDB->setAuthorization($authorization); + + /** @var User $user */ + $user = $authorization->skip(fn () => $projectDB->getDocument('users', $identity['userId'] ?? '')); + $roles = $user->getRoles($authorization); + $topicsById = []; if ($allowed !== []) { $documents = $authorization->skip(fn () => $projectDB->find('topics', [ @@ -166,14 +169,6 @@ class Handler implements MqttHandler $grantedTopics[$filter->topic] = [$document, $grantedQos]; } - \Utopia\Console::error('MQTT_SUB_DBG prefix=' . $connection->prefix - . ' uid=' . ($identity['userId'] ?? '(none)') - . ' roles=' . \json_encode($roles) - . ' filters=' . \json_encode(\array_map(fn ($f) => [$f->topic, $f->qos], $subscribe->filters())) - . ' allowed=' . \json_encode(\array_keys($allowed)) - . ' foundTopics=' . \json_encode(\array_keys($topicsById)) - . ' codes=' . \json_encode($suback->codes())); - if ($grantedTopics !== []) { $this->replayBacklog($connection, $projectDB, $grantedTopics); } @@ -344,7 +339,9 @@ class Handler implements MqttHandler $getProjectDB = $this->container->get('getProjectDB'); $consoleDB = $getConsoleDB(); - $project = $consoleDB->getAuthorization()->skip(fn () => $consoleDB->getDocument('projects', $projectId)); + $authorization = new Authorization(); + $consoleDB->setAuthorization($authorization); + $project = $authorization->skip(fn () => $consoleDB->getDocument('projects', $projectId)); return $getProjectDB($project); } diff --git a/tests/e2e/Services/Mqtt/MqttServerTest.php b/tests/e2e/Services/Mqtt/MqttServerTest.php index 721cd22cc4..6a7d1ed17a 100644 --- a/tests/e2e/Services/Mqtt/MqttServerTest.php +++ b/tests/e2e/Services/Mqtt/MqttServerTest.php @@ -147,9 +147,9 @@ final class MqttServerTest extends Scope try { // Test for FAILURE: a filter that maps to no project topic is refused in the - // SUBACK (reason 0x87), not silently granted. + // SUBACK (reason 0x80), not silently granted. $codes = $subscriber->subscribe(['does-not-exist-' . $userId]); - $this->assertSame([0x87], $codes); + $this->assertSame([0x80], $codes); } finally { $subscriber->disconnect(); } @@ -176,11 +176,11 @@ final class MqttServerTest extends Scope $this->assertEquals(201, $topic['headers']['status-code']); $topicId = $topic['body']['$id']; - // Test for FAILURE: a user outside the topic's subscribe roles is refused (0x87). + // Test for FAILURE: a user outside the topic's subscribe roles is refused (0x80). $other = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); $this->assertSame(0, $other->connect($projectId, $otherJwt, 'e2e-acl-other-' . $otherId, cleanStart: true)); try { - $this->assertSame([0x87], $other->subscribe([$topicId])); + $this->assertSame([0x80], $other->subscribe([$topicId])); } finally { $other->disconnect(); } From be501b465695a2c681032279bb475b358b70f30c Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 11:31:32 +0530 Subject: [PATCH 137/146] 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):///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. --- app/mqtt.php | 4 +- docker-compose.yml | 12 ++++ tests/e2e/Services/Mqtt/MqttServerTest.php | 79 ++++++++++++++++++++++ 3 files changed, 94 insertions(+), 1 deletion(-) diff --git a/app/mqtt.php b/app/mqtt.php index dc27cc0c92..9fc1531a98 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -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'))); diff --git a/docker-compose.yml b/docker-compose.yml index 9b1661d222..b26a7db10b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -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):///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: diff --git a/tests/e2e/Services/Mqtt/MqttServerTest.php b/tests/e2e/Services/Mqtt/MqttServerTest.php index 6a7d1ed17a..8b4e978860 100644 --- a/tests/e2e/Services/Mqtt/MqttServerTest.php +++ b/tests/e2e/Services/Mqtt/MqttServerTest.php @@ -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):///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 From 655f3c8e6a99db8af2c7bcfa337fc4a5f4b75031 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 11:38:55 +0530 Subject: [PATCH 138/146] test(mqtt): assert QoS-0 delivery is fire-and-forget (no packet id, no PUBACK) A subscription to a QoS-0 topic (grant capped from the client's QoS-1 request) is delivered at QoS 0 and the client sends no PUBACK. Expose the received QoS from the subscriber to lock the QoS-0/QoS-1 segregation in place. --- tests/e2e/Services/Mqtt/MqttServerTest.php | 36 ++++++++++++++++++++++ tests/e2e/Services/Mqtt/MqttSubscriber.php | 4 +-- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/tests/e2e/Services/Mqtt/MqttServerTest.php b/tests/e2e/Services/Mqtt/MqttServerTest.php index 8b4e978860..c66083e81c 100644 --- a/tests/e2e/Services/Mqtt/MqttServerTest.php +++ b/tests/e2e/Services/Mqtt/MqttServerTest.php @@ -378,6 +378,42 @@ final class MqttServerTest extends Scope $this->assertEquals(['matchId' => '42'], $payload['data']); } + /** + * QoS 0 is fire-and-forget and must stay segregated from QoS 1: a subscription to a + * QoS-0 topic is delivered at QoS 0, so the PUBLISH carries no packet id and the client + * sends no PUBACK (the broker tracks nothing and advances no replay cursor). The client + * requests QoS 1 but the topic caps the grant to 0. + */ + public function testQos0DeliveryHasNoPuback(): 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-qos0', qos: 0); + + $subscriber = new MqttSubscriber(self::BROKER_HOST, self::BROKER_PORT); + $this->assertSame(0, $subscriber->connect($projectId, $jwt, 'e2e-qos0-' . $userId, cleanStart: true)); + $this->assertSame([0], $subscriber->subscribe([$topicId], Packet::QOS_1), 'the QoS-0 topic must cap the grant to 0'); + + try { + $this->publishCampaign($server, $topicId, 'No ack', 'delivered at qos 0', ['k' => 'v']); + $received = $subscriber->consume(limit: 1, timeout: 20.0); + } finally { + $subscriber->disconnect(); + } + + // Test for SUCCESS: delivered once, at QoS 0 (no packet id, so the client never PUBACKs). + $this->assertCount(1, $received, 'qos 0 subscriber did not receive the campaign'); + $this->assertSame($topicId, $received[0]['topic']); + $this->assertSame(0, $received[0]['qos'], 'delivery to a QoS-0 subscription must be QoS 0'); + $this->assertFalse($received[0]['dup'], 'a QoS-0 delivery is never marked DUP'); + } + /** * MQTT over WebSocket: browser clients reach the broker through its WebSocket listener * (appwrite-mqtt:8083, routed as ws(s):///push) instead of raw TCP. The same diff --git a/tests/e2e/Services/Mqtt/MqttSubscriber.php b/tests/e2e/Services/Mqtt/MqttSubscriber.php index f005574107..ec7000e9cb 100644 --- a/tests/e2e/Services/Mqtt/MqttSubscriber.php +++ b/tests/e2e/Services/Mqtt/MqttSubscriber.php @@ -104,7 +104,7 @@ final class MqttSubscriber * its PUBACK — used to simulate non-contiguous acknowledgement. * * @param (callable(int): bool)|null $shouldAck - * @return array + * @return array */ public function consume(int $limit, float $timeout, ?callable $shouldAck = null): array { @@ -135,7 +135,7 @@ final class MqttSubscriber $offset = Properties::skip($body, $offset); $payload = substr($body, $offset); - $received[] = ['topic' => $topic, 'payload' => $payload, 'dup' => $packet->dup()]; + $received[] = ['topic' => $topic, 'payload' => $payload, 'dup' => $packet->dup(), 'qos' => $packet->qos()]; $ack = $shouldAck === null || $shouldAck(\count($received) - 1); if ($ack && $packet->qos() === 1 && $packetIdBytes !== '') { From 43cdd8d6915f10f6e6e9b9be0e93d91feba67638 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 11:50:42 +0530 Subject: [PATCH 139/146] fix(mqtt): expose MQTT-over-WebSocket only over TLS (wss) Drop the plaintext port-80 ws router; the CONNECT frame carries a reusable JWT/session credential, so route /push only through the websecure entrypoint (wss), matching the TLS-only mqtts TCP router. Addresses the credentials-over-plaintext review finding. --- docker-compose.yml | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index b26a7db10b..79466a7af9 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -384,11 +384,10 @@ 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):///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 + # MQTT-over-WebSocket for browser clients: wss:///push is terminated at the + # websecure entrypoint and forwarded to the broker's WebSocket listener (:8083). + # TLS-only (no plaintext ws on :80), mirroring the mqtts TCP router, so the reusable + # JWT/session credential in the CONNECT frame never traverses the network in the clear. - 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 From b459884ebbefc90753428010a1e4bc62221fbd0d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 12:08:34 +0530 Subject: [PATCH 140/146] refactor(mqtt): serve MQTT-over-WebSocket on a dedicated TLS port, not a /push path Give the WebSocket carrier its own TLS entrypoint (:8084, mqtt-wss) alongside the mqtts TCP entrypoint (:8883), each a catch-all on its port. The transport is now identified by host+port rather than a URL path, so one push endpoint (e.g. push.cloud.appwrite.io) serves both mqtts:// and wss:// and it no longer shares :443/paths with the API or realtime. Still TLS-only. --- docker-compose.yml | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 79466a7af9..e84c433c59 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -22,10 +22,12 @@ services: - --entrypoints.appwrite_web.address=:80 - --entrypoints.appwrite_websecure.address=:443 - --entrypoints.appwrite_mqtt.address=:8883 + - --entrypoints.appwrite_mqtt_ws.address=:8084 ports: - ${_APP_HTTP_PORT:-80}:80 - ${_APP_HTTPS_PORT:-443}:443 - ${_APP_MQTT_PORT:-8883}:8883 + - ${_APP_MQTT_WSS_PORT:-8084}:8084 volumes: - /var/run/docker.sock:/var/run/docker.sock - appwrite-config:/storage/config:ro @@ -384,14 +386,15 @@ 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: wss:///push is terminated at the - # websecure entrypoint and forwarded to the broker's WebSocket listener (:8083). - # TLS-only (no plaintext ws on :80), mirroring the mqtts TCP router, so the reusable - # JWT/session credential in the CONNECT frame never traverses the network in the clear. - - 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 + # MQTT-over-WebSocket for browser clients: wss://:8084 on its own TLS entrypoint + # (a dedicated port, not a URL path), the WebSocket sibling of the mqtts TCP router. The + # port identifies the broker, so a single push host serves both mqtts:// (:8883) and + # wss:// (:8084). TLS-only, so the reusable CONNECT credential never crosses the wire in + # the clear; TLS is terminated here and forwarded to the broker's WebSocket listener (:8083). + - traefik.http.routers.appwrite_mqtt_ws.entrypoints=appwrite_mqtt_ws + - traefik.http.routers.appwrite_mqtt_ws.rule=PathPrefix(`/`) + - traefik.http.routers.appwrite_mqtt_ws.service=appwrite_mqtt_ws + - traefik.http.routers.appwrite_mqtt_ws.tls=true - traefik.http.services.appwrite_mqtt_ws.loadbalancer.server.port=8083 networks: - appwrite From 082e33a5295f188939ee068280cfd22d874f5a17 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 12:10:15 +0530 Subject: [PATCH 141/146] test(mqtt): upgrade the WebSocket carrier at the root, not /push The WS transport is addressed by its dedicated TLS port, not a URL path, so the client upgrades at / rather than /push. --- tests/e2e/Services/Mqtt/MqttServerTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/e2e/Services/Mqtt/MqttServerTest.php b/tests/e2e/Services/Mqtt/MqttServerTest.php index c66083e81c..e00faca7bf 100644 --- a/tests/e2e/Services/Mqtt/MqttServerTest.php +++ b/tests/e2e/Services/Mqtt/MqttServerTest.php @@ -416,7 +416,7 @@ final class MqttServerTest extends Scope /** * MQTT over WebSocket: browser clients reach the broker through its WebSocket listener - * (appwrite-mqtt:8083, routed as ws(s):///push) instead of raw TCP. The same + * (appwrite-mqtt:8083, exposed as wss://:8084 on its own TLS port) 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. @@ -439,7 +439,7 @@ final class MqttServerTest extends Scope 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'); + $this->assertTrue($client->upgrade('/'), 'websocket upgrade failed'); $properties = (new Properties()) ->add(new Property(Property::AUTHENTICATION_METHOD, 'appwrite-jwt')) From 5b997eee6ac5545edb6b6f6d1385d525fc94760b Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 12:16:20 +0530 Subject: [PATCH 142/146] fix(mqtt): restore the wss entrypoint in the dev Traefik override The dev override replaces Traefik's command wholesale; it only re-declared the mqtts :8883 entrypoint, so the new mqtt-wss :8084 entrypoint was missing and wss was unreachable in the dev stack (the :8084 port publish survives via ports concatenation but had no entrypoint behind it). Re-declare it alongside mqtts. --- docker-compose.override.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docker-compose.override.yml b/docker-compose.override.yml index 1839b9b420..f9bd0f1686 100644 --- a/docker-compose.override.yml +++ b/docker-compose.override.yml @@ -516,11 +516,12 @@ services: - --providers.docker.constraints=Label(`traefik.constraint-label-stack`,`appwrite`) - --entrypoints.appwrite_web.address=:80 - --entrypoints.appwrite_websecure.address=:443 - # This dev override replaces the base command wholesale, so the mqtts - # entrypoint must be repeated here or Traefik won't listen on :8883 and the - # appwrite-mqtt broker is unreachable (the :8883 port publish survives via - # ports concatenation, but has no entrypoint behind it without this). + # This dev override replaces the base command wholesale, so the MQTT entrypoints + # must be repeated here or Traefik won't listen on :8883 (mqtts) and :8084 (wss) + # and the appwrite-mqtt broker is unreachable (the port publishes survive via + # ports concatenation, but have no entrypoint behind them without this). - --entrypoints.appwrite_mqtt.address=:8883 + - --entrypoints.appwrite_mqtt_ws.address=:8084 - --log.level=DEBUG - --api.insecure=true - --accesslog=true From 675448d48f24044cdfe80e4d37cd98439b3121d0 Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 16:13:31 +0530 Subject: [PATCH 143/146] refactor(mqtt): inject cache resolver and planForUser into the handler The handler no longer service-locates getCache/getPlanForUser off the container by string key; both arrive as typed constructor params. The cache stays a resolver closure because the pool-backed cache can only be built inside a coroutine, so it is resolved lazily per coroutine as before. --- app/mqtt.php | 2 +- src/Appwrite/Mqtt/Handler.php | 11 +++++------ 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/app/mqtt.php b/app/mqtt.php index 9fc1531a98..fb12d76731 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -184,7 +184,7 @@ $mqtt = new Mqtt($telemetry, new PubSubPool($register->get('pools')->get('pubsub // The broker owns framing, decoding, dispatch, per-version encoding, packet ids, the QoS // handshake, keep-alive reaping and subscription matching. Appwrite policy lives in the Handler. -$handler = new Handler($container, $mqtt); +$handler = new Handler($container, $mqtt, $container->get('getCache'), $container->get('getPlanForUser')); $server = new Server($adapter, $handler); $server->setTelemetry($telemetry); // broker owns connection/packet/subscription metrics diff --git a/src/Appwrite/Mqtt/Handler.php b/src/Appwrite/Mqtt/Handler.php index 04638170b7..1c93bd0476 100644 --- a/src/Appwrite/Mqtt/Handler.php +++ b/src/Appwrite/Mqtt/Handler.php @@ -36,6 +36,8 @@ class Handler implements MqttHandler public function __construct( private readonly Container $container, private readonly Mqtt $mqtt, + private readonly \Closure $getCache, + private readonly \Closure $planForUser, ) { } @@ -227,8 +229,7 @@ class Handler implements MqttHandler $this->mqtt->messagesAcked->add(1); $this->mqtt->pubacksReceived->add(1); - $getCache = $this->container->get('getCache'); - $cache = $getCache(); + $cache = ($this->getCache)(); $key = $this->cursorKey($connection); $topic = $delivery['topic']; $cursor = (int) $delivery['cursor']; @@ -274,11 +275,9 @@ class Handler implements MqttHandler */ private function replayBacklog(Connection $connection, Database $projectDB, array $grantedTopics): void { - $getCache = $this->container->get('getCache'); - $getPlanForUser = $this->container->get('getPlanForUser'); - $cache = $getCache(); + $cache = ($this->getCache)(); $key = $this->cursorKey($connection); - $maxDepth = max(1, $getPlanForUser(new Document(['$id' => $connection->prefix]), $connection->identity['userId'] ?? '')); + $maxDepth = max(1, ($this->planForUser)(new Document(['$id' => $connection->prefix]), $connection->identity['userId'] ?? '')); $expiry = 0; foreach ($grantedTopics as [$document]) { From 3e583dd8f6ad48541ff2b5961963d879e0304c4d Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 16:13:31 +0530 Subject: [PATCH 144/146] fix(mqtt): lower the pub/sub reconnect cap to 60 attempts The counter resets on a healthy ping, so this caps consecutive failures at ~2 minutes before the delivery bridge gives up. --- app/mqtt.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/mqtt.php b/app/mqtt.php index fb12d76731..8b88a71a8c 100644 --- a/app/mqtt.php +++ b/app/mqtt.php @@ -196,7 +196,7 @@ $server->error(fn (\Throwable $error, string $action) => Console::error("MQTT {$ $server->onWorkerStart(function (int $workerId) use ($server, $handler, $mqtt, $register): void { go(function () use ($server, $handler, $mqtt, $register): void { $attempts = 0; - while ($attempts < 300) { + while ($attempts < 60) { try { $pubsub = new PubSubPool($register->get('pools')->get('pubsub')); From 0cddef7dba63b119545575d18de077d95f936ecb Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 16:13:31 +0530 Subject: [PATCH 145/146] ci(mqtt): fold the MQTT e2e into the service matrix Drop the standalone e2e_mqtt job; add Mqtt to e2e_service with processes: 1 so the session/replay tests keep running serially against the one broker. --- .github/workflows/ci.yml | 58 +--------------------------------------- 1 file changed, 1 insertion(+), 57 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 65848b5bdb..f59aece246 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -228,6 +228,7 @@ jobs: { name: 'Project', runner: runner4, functional: true, processes: null }, { name: 'Organization', runner: runner4, functional: true, processes: null }, { name: 'Presences', runner: runner4, functional: true, processes: null }, + { name: 'Mqtt', runner: runner4, functional: false, processes: 1 }, ]; core.setOutput('services', JSON.stringify(services)); @@ -523,63 +524,6 @@ jobs: echo "=== Appwrite Logs ===" docker compose logs --timestamps - e2e_mqtt: - name: Tests / E2E / MQTT - runs-on: runs-on=${{ github.run_id }}/runner=4cpu-linux-x64/volume=60g/spot=price-capacity-optimized/retry=when-interrupted/extras=otel+ecr-cache - timeout-minutes: 15 - needs: build - permissions: - contents: read - packages: read - env: - COMPOSE_PROFILES: '' - steps: - - name: checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - - name: Login to Docker Hub - if: ${{ env.DOCKERHUB_AUTH_AVAILABLE == 'true' }} - uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0 - with: - username: ${{ vars.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} - - - parallel: - - name: Pull Docker Image - run: | - docker pull ${{ env.RUNS_ON_ECR_CACHE }}:${{ env.IMAGE }}-${{ github.sha }} - docker tag ${{ env.RUNS_ON_ECR_CACHE }}:${{ env.IMAGE }}-${{ github.sha }} ${{ env.IMAGE }} - - - name: Pull Docker Compose images - timeout-minutes: 5 - run: | - for attempt in 1 2 3; do - if docker compose pull --quiet --ignore-buildable; then - break - elif [ "$attempt" -eq 3 ]; then - echo "::error::docker compose pull failed after 3 attempts; aborting" - exit 1 - fi - echo "::warning::docker compose pull failed (attempt ${attempt}/3); retrying in 15s" - sleep 15 - done - - - name: Load and Start Appwrite - timeout-minutes: 5 - run: docker compose up -d --quiet-pull --wait - - - name: Run MQTT Tests - timeout-minutes: 15 - run: >- - docker compose exec -T - appwrite test /usr/src/code/tests/e2e/Services/Mqtt --group mqtt - - - name: Failure Logs - if: failure() - run: | - echo "=== Appwrite Logs ===" - docker compose logs --timestamps - e2e_service: name: Tests / E2E / ${{ matrix.database }} (${{ matrix.mode }}) / ${{ matrix.service.name }} runs-on: ${{ matrix.service.runner }} From fe72eebb4f7235243e96df88108993030f35dbae Mon Sep 17 00:00:00 2001 From: ArnabChatterjee20k Date: Fri, 18 Sep 2026 17:00:04 +0530 Subject: [PATCH 146/146] bump --- composer.json | 2 +- composer.lock | 19 +++++++++---------- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/composer.json b/composer.json index c0cc0638ae..2397a2cf06 100644 --- a/composer.json +++ b/composer.json @@ -103,7 +103,7 @@ "utopia-php/locale": "0.8.*", "utopia-php/messaging": "^2.1", "utopia-php/migration": "^2.0.0", - "utopia-php/mqtt": "dev-dev", + "utopia-php/mqtt": "0.0.*", "utopia-php/platform": "1.0.0-rc20", "utopia-php/pools": "2.*", "utopia-php/span": "^4.2", diff --git a/composer.lock b/composer.lock index 7bd5d0a730..bdf2fdf623 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "6d18c8c29cbbb950556109e8bfc61779", + "content-hash": "8a4455dd9986b24d5ab9788f1d97a2bf", "packages": [ { "name": "adhocore/jwt", @@ -4146,20 +4146,20 @@ }, { "name": "utopia-php/mqtt", - "version": "dev-dev", + "version": "0.0.1", "source": { "type": "git", "url": "https://github.com/utopia-php/mqtt.git", - "reference": "53ff974d0a179f07035241a8b8df0ca1b15a2ff5" + "reference": "d43d7e7f4b0c0854c5fd16c7ef085284d84b0d69" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/53ff974d0a179f07035241a8b8df0ca1b15a2ff5", - "reference": "53ff974d0a179f07035241a8b8df0ca1b15a2ff5", + "url": "https://api.github.com/repos/utopia-php/mqtt/zipball/d43d7e7f4b0c0854c5fd16c7ef085284d84b0d69", + "reference": "d43d7e7f4b0c0854c5fd16c7ef085284d84b0d69", "shasum": "" }, "require": { - "php": ">=8.1", + "php": ">=8.2", "utopia-php/telemetry": "^0.4" }, "require-dev": { @@ -4206,10 +4206,10 @@ "utopia" ], "support": { - "source": "https://github.com/utopia-php/mqtt/tree/dev", + "source": "https://github.com/utopia-php/mqtt/tree/0.0.1", "issues": "https://github.com/utopia-php/mqtt/issues" }, - "time": "2026-09-17T15:41:04+00:00" + "time": "2026-09-18T11:27:21+00:00" }, { "name": "utopia-php/openapi", @@ -8412,8 +8412,7 @@ "aliases": [], "minimum-stability": "dev", "stability-flags": { - "utopia-php/http": 5, - "utopia-php/mqtt": 20 + "utopia-php/http": 5 }, "prefer-stable": true, "prefer-lowest": false,