feat(messaging): add Appwrite Push adapter for MQTT 5 integration

[ArnabChatterjee20k]

Appwrite Push (MQTT 5) adapter

Adds a Push adapter that talks to Appwrite's custom MQTT 5 broker, a minimal MQTT 5 control-packet codec (Helpers/MQTT), and a spawned mock broker for tests.

The adapter speaks the broker's enhanced-authentication CONNECT dialect: the credential rides in the Authentication Method/Data properties and the project in a projectId User Property. The broker scopes every topic by that project, so callers use bare device topics.

Publish — send()

use Utopia\Messaging\Adapter\Push\Appwrite;
use Utopia\Messaging\Messages\Push;

$adapter = new Appwrite(
    endpoint: 'broker.example.com:1883',
    projectId: '<projectId>',
    credential: $jwt,            // an Appwrite JWT (or a session secret)
    authMethod: 'appwrite-jwt',  // or 'appwrite-session'
    tls: true,
);

$response = $adapter->send(new Push(
    to: ['device-token-1', 'device-token-2'], // each published to appwrite/push/{token}
    title: 'Hello',
    body: 'World',
    data: ['key' => 'value'],
));

// $response['deliveredTo'], $response['results'][n]['status'] ...

Publishes are pipelined at QoS 1 (send a window of PUBLISHes, drain PUBACKs by packet id, refill), so throughput scales with socket bandwidth rather than round-trip latency.

Consume — consume()

The same enhanced-auth connection can subscribe. consume() subscribes to the given topics and invokes a callback for each message, until a message limit or timeout is reached (QoS 1 messages are acked):

$adapter->consume(
    topics: ['appwrite/push/device-token-1'],
    onMessage: function (array $message): void {
        // $message['topic'], $message['payload'], $message['qos']
    },
    limit: 1,
    timeout: 5.0,
);

This is what verifies broker fan-out end to end from the consumer side (e.g. a device receiving what a publisher sent).

Telemetry

An optional Telemetry adapter can be injected; it defaults to the base no-op counter:

new Appwrite(/* ... */, telemetry: $telemetry);

Codec — Helpers/MQTT

A transport-agnostic MQTT 5 codec: encode/parse CONNECT, CONNACK, PUBLISH, PUBACK, SUBSCRIBE, SUBACK, PINGREQ/RESP, DISCONNECT, and the v5 property block (User Properties, enhanced-auth, message expiry, …). Both the adapter and the tests build on it.

Tests

tests/Messaging/Adapter/Push/AppwriteTest.php drives the adapter against a spawned in-process mock broker (FakeBroker.php) that accepts the enhanced-auth CONNECT and acks QoS 1 publishes: device-topic publishes, pipelined PUBACK counting, expired-token reason codes, and the CONNECT property block (projectId + credential, not username/password).