Appwrite push

[ArnabChatterjee20k]

What this PR adds

A native Push service on the client SDKs. It is the Realtime analog delivered over the Appwrite MQTT broker (MQTT 5 with enhanced auth), with no FCM or APNS. Push is server-initiated: a client subscribes and receives, there is no client publish. The credential is read off the Client (set a JWT or session on it, like every other service), so Push has no setJWT/setSession of its own.

Per-SDK transport: Flutter uses mqtt5_client (raw TCP on mobile and desktop, MQTT over WebSocket on web), React Native uses MQTT.js over react-native-tcp-socket, Web uses MQTT.js over WebSocket, Android uses HiveMQ, Apple uses MQTTNIO (the SDK's existing SwiftNIO stack), Unity uses MQTTnet.

The API

The whole surface is: create the service, subscribe, receive, tear down. Nothing on the connection is tunable, so there are no connection setters to call in the right order.

Call	What it does
Push(client)	Create the service. Reads the JWT or session off client.
subscribe(topics, callback, { background?, title?, reDeliverIfMissed? })	Subscribe to one topic or a list. Resolves after SUBACK (foreground). Returns a subscription handle.
handle.unsubscribe()	Drop that subscription. Closes the connection once the last one is gone.
handle.update({ background?, title?, reDeliverIfMissed? })	Change that subscription's options live, without resubscribing.
onOpen(cb) / onClose(cb) / onError(cb)	Connection lifecycle hooks (foreground connection).
close()	Tear down the connection and drop every subscription.
Client.setPushEndpoint(url)	Point at a specific broker. mqtt(s)://host:port on native, ws(s)://host in the browser. Append ?tlsInsecure=true to skip TLS cert verification (self-signed brokers, testing; native only).
Client.setPushClientId(id)	A stable client id, so the broker resumes this client's replay cursor across restarts.

Two things are per subscription rather than per connection, which is where MQTT itself puts them:

reDeliverIfMissed sets the subscription's QoS. true (the default) subscribes at QoS 1, so the broker holds that topic's messages and redelivers them on reconnect. false subscribes at QoS 0, at-most-once, so a message sent while you are disconnected is gone. The connection always keeps its session (clean start is always off), and the broker owns the replay window server-side, so reliability is a per-subscription choice and there is no connection-level replay flag.

background keeps a subscription delivering while the app is backgrounded or closed and posts a notification per message with title. The foreground service is reference-counted across subscriptions: it runs while any live subscription has background on, and stops once the last one goes. Each opted-in subscription posts notifications with its own title.

Duplicate messages

QoS 1 is at-least-once. After a reconnect the broker can redeliver a message you already handled, so a reDeliverIfMissed: true subscription may see the same message twice. If duplicates matter for your callback (for example it writes to a store or increments a counter), dedupe on the message: keep a set of recently seen message ids (or a hash of topic plus payload) and skip one you have already processed. A reDeliverIfMissed: false subscription does not redeliver, so it does not need this.

Usage

Flutter

// Auth lives on the Client; Push reads the JWT (or session) off it.
final client = Client()
    .setEndpoint('https://<region>.cloud.appwrite.io/v1')
    .setProject('<projectId>')
    .setJWT(jwt);

// Optional: point at a specific broker. Append ?tlsInsecure=true to skip cert checks.
client.setPushEndpoint('mqtts://<region>.cloud.appwrite.io:8883');
// Optional: a stable id so the broker resumes this client's replay cursor across restarts.
client.setPushClientId('device-42');

final push = Push(client);

// Connection lifecycle of the foreground (in-process) connection.
push.onOpen(() => print('connected'));
push.onClose(() => print('closed'));
push.onError((error) => print('error: $error'));

// Foreground subscription. Resolves after SUBACK. reDeliverIfMissed defaults to true (QoS 1).
final sub = await push.subscribe('user/123/#', (message) {
  print('${message.topic}: ${message.string}');
});

// Background subscription: keeps delivering while backgrounded/closed and posts a
// notification per message. Needs flutter_background_service + flutter_local_notifications.
final orders = await push.subscribe(
  'orders/#',
  (message) => print(message.string),
  background: true,
  title: 'Orders',
  reDeliverIfMissed: false, // QoS 0 for this one
);

// Change a subscription live, without resubscribing.
orders.update(background: false);        // stop background, keep receiving in foreground
orders.update(reDeliverIfMissed: true);  // switch this subscription to QoS 1

// Drop one subscription; the connection closes once the last one is gone.
sub.unsubscribe();

// Or tear everything down at once.
push.close();

React Native

import { Client, Push } from 'react-native-appwrite';

const client = new Client()
  .setEndpoint('https://<region>.cloud.appwrite.io/v1')
  .setProject('<projectId>')
  .setJWT(jwt);

client.setPushEndpoint('mqtts://<region>.cloud.appwrite.io:8883'); // ?tlsInsecure=true to skip cert checks
client.setPushClientId('device-42');

const push = new Push(client);

push.onOpen(() => console.log('connected'));
push.onClose(() => console.log('closed'));
push.onError((error) => console.log('error', error));

// Foreground subscription. Resolves after SUBACK. reDeliverIfMissed defaults to true.
const sub = await push.subscribe('user/123/#', (message) => {
  console.log(message.topic, message.payload.toString());
});

// Background subscription: Android foreground service + a notification per message.
// Needs the react-native-background-actions and expo-notifications peers, and the package
// added to your Expo plugins (it ships app.plugin.js for the Android 14+ manifest bits).
const orders = await push.subscribe('orders/#', (m) => console.log(m.topic), {
  background: true,
  title: 'Orders',
  reDeliverIfMissed: false,
});

orders.update({ background: false });
orders.update({ reDeliverIfMissed: true });

sub.unsubscribe();
push.close();

For background delivery, register the config plugin in app.json (or app.config.js) so Expo prebuild injects the Android 14+ foregroundServiceType and the FOREGROUND_SERVICE / FOREGROUND_SERVICE_DATA_SYNC / POST_NOTIFICATIONS permissions into the manifest. It is a no-op on iOS.

{
  "expo": {
    "plugins": ["react-native-appwrite"]
  }
}

Web

import { Client, Push } from 'appwrite';

const client = new Client()
  .setEndpoint('https://<region>.cloud.appwrite.io/v1')
  .setProject('<projectId>')
  .setJWT(jwt);

// Browser transport is MQTT over WebSocket; override with ws(s):// if needed.
client.setPushEndpoint('wss://<region>.cloud.appwrite.io');
client.setPushClientId('tab-42');

const push = new Push(client);

push.onOpen(() => console.log('connected'));
push.onClose(() => console.log('closed'));
push.onError((error) => console.log('error', error));

const sub = await push.subscribe('user/123/#', (message) => {
  console.log(message.topic, new TextDecoder().decode(message.payload));
});

// background shows a browser notification per message while the tab is open. A browser
// cannot hold a socket once the tab closes, so there is no true background mode.
const orders = await push.subscribe('orders/#', (m) => console.log(m.topic), {
  background: true,
  title: 'Orders',
  reDeliverIfMissed: false,
});

orders.update({ background: false });
orders.update({ reDeliverIfMissed: true });

sub.unsubscribe();
push.close();

Apple

let client = Client()
    .setEndpoint("https://<region>.cloud.appwrite.io/v1")
    .setProject("<projectId>")
    .setJWT(jwt)

client.setPushEndpoint("mqtts://<region>.cloud.appwrite.io:8883") // ?tlsInsecure=true to skip cert checks
client.setPushClientId("device-42")

let push = Push(client)

push.onOpen { print("connected") }
push.onClose { print("closed") }
push.onError { error in print("error: \(error)") }

// Suspends until SUBACK. reDeliverIfMissed defaults to true (QoS 1).
let sub = try await push.subscribe("user/123/#") { message in
    print("\(message.topic): \(message.string)")
}

// background posts a local notification per message via UserNotifications.
let orders = try await push.subscribe(
    "orders/#",
    background: true,
    title: "Orders",
    reDeliverIfMissed: false
) { message in
    print(message.string)
}

orders.update(background: false)
orders.update(reDeliverIfMissed: true)

sub.unsubscribe()
push.close()

Android

val client = Client(context)
    .setEndpoint("https://<region>.cloud.appwrite.io/v1")
    .setProject("<projectId>")
    .setJWT(jwt)

client.setPushEndpoint("mqtts://<region>.cloud.appwrite.io:8883") // ?tlsInsecure=true to skip cert checks
client.setPushClientId("device-42")

val push = Push(client)

push.onOpen { println("connected") }
push.onClose { println("closed") }
push.onError { error -> println("error: $error") }

// Blocks until SUBACK (foreground). reDeliverIfMissed defaults to true.
val sub = push.subscribe("user/123/#") { message ->
    println("${message.topic}: ${message.string}")
}

// Background runs a foreground Service. It needs POST_NOTIFICATIONS on Android 13+ and a
// Context to start the service the first time.
Push.requestNotificationPermission(activity)
val orders = push.subscribe(
    "orders/#",
    background = true,
    title = "Orders",
    reDeliverIfMissed = false,
    context = context,
) { message ->
    println(message.string)
}

orders.update(background = false)
orders.update(reDeliverIfMissed = true)

sub.unsubscribe()
push.close()

Unity

client.SetEndpoint("https://<region>.cloud.appwrite.io/v1")
      .SetProject("<projectId>")
      .SetJWT(jwt);

client.SetPushEndpoint("mqtts://<region>.cloud.appwrite.io:8883"); // ?tlsInsecure=true to skip cert checks
client.SetPushClientId("device-42");

// Push is a MonoBehaviour, created through the manager.
var push = AppwriteManager.Instance.Push;

push.OnOpen(() => Debug.Log("connected"));
push.OnClose(() => Debug.Log("closed"));
push.OnError(error => Debug.LogError(error));

// Awaits SUBACK. reDeliverIfMissed defaults to true (QoS 1).
var sub = await push.Subscribe("user/123/#", message => {
    Debug.Log($"{message.Topic}: {message.Text}");
});

// QoS 0 for this subscription. Unity has no background or notification mode, so it delivers
// on the main thread while the app runs and the handle exposes Unsubscribe and Update only.
var lossy = await push.Subscribe("orders/#", m => Debug.Log(m.Text), reDeliverIfMissed: false);

lossy.Update(reDeliverIfMissed: true);

sub.Unsubscribe();
push.Close();

Background delivery per platform

Android and Flutter host the connection in a foreground service (Flutter uses a background isolate) while any subscription wants background, so delivery survives backgrounding and swipe-away while the process is alive. The single connection relocates there when background is wanted and back in-process when none is, so the broker never sees two sessions with the same client id. A hard process kill is not recovered.

On iOS (Apple and React Native) a background subscription delivers only while the app runs or is briefly backgrounded. iOS suspends the app and its socket within seconds and kills it on swipe-away, and there is no API to keep a raw socket alive. Reliable background delivery on iOS needs APNs, which this MQTT channel does not use. This is a platform limit, not a bug, and worth stating plainly in the docs.

Web shows a browser notification while the tab is open. There is no delivery once the tab closes. Unity has no background or notification mode.

Dependencies

Each SDK pulls in one MQTT 5 client, and the optional background mode adds a few more. Nothing bumps a language or runtime floor.

SDK	MQTT client	Background (optional)	Declared as
Flutter	mqtt5_client, typed_data	flutter_background_service, flutter_local_notifications, path_provider	pubspec deps
React Native	mqtt (+ buffer, readable-stream, process, expo-file-system); react-native-tcp-socket (optional peer)	react-native-background-actions, expo-notifications, @expo/config-plugins (all optional peers)	deps + optional peerDependencies
Web	mqtt	none (browser Notification API)	package.json dep
Android	com.hivemq:hivemq-mqtt-client	none (foreground Service is built in)	Gradle implementation
Apple	swift-server-community/mqtt-nio (MQTTNIO)	none (UserNotifications)	SPM
Unity	MQTTnet 4.3.7, bundled as a netstandard2.0 plugin DLL	none	vendored DLL + lockfile entry

React Native peers a consumer acts on: react-native-tcp-socket is the native socket the client runs over (optional so importing the SDK without it does not break Metro, required for Push to connect). react-native-background-actions and expo-notifications are only needed for a background subscription. @expo/config-plugins is an optional peer so the shipped app.plugin.js resolves at Expo prebuild against the consumer's Expo-managed copy, which fixes resolution under pnpm and Yarn PnP.

Downstream, not in this repo: MQTTNIO is SPM-only, so the Apple SDK ships through Swift Package Manager. If that repo still carries a CocoaPods podspec, that path needs a look with the Apple SDK maintainers, since MQTTNIO has no CocoaPods support.

Test plan

A minimal MQTT broker (utopia-php/mqtt) runs in the mock server as the mqtt service on the mockapi network, serving both transports the client uses, TCP on 1883 and WebSocket on 8083, and starts with the existing e2e setUp(). The broker is server-initiated: on SUBSCRIBE it delivers a message on the subscribed topic, mirroring production, so the e2e subscribes and awaits with no client publish.

Push e2e runs for Flutter (TCP), Flutter web (WebSocket), Apple, Android, Unity and Web (WebSocket), driven through Client.setPushEndpoint. Each asserts subscribe, receive, and that a default subscription is delivered at QoS 1. Not covered by the broker e2e: Kotlin (the server SDK has no Push, like Realtime) and React Native (the browser harness has no raw TCP socket); both need instrumented or device runners.

Note for the broker team: MQTT 5 clients that use a challenge/response enhanced-auth mechanism (HiveMQ, used by the Android SDK) require the CONNACK to echo the authenticationMethod. The mock does this; the production broker returns a bare CONNACK today, so it should echo the method for browser and HiveMQ clients.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the only outstanding finding from the previous review is fixed by deriving Web Push from the regular API endpoint.

Summary

Adds native Push services across the supported client SDKs, backed by MQTT 5 transports and a dedicated mock broker for end-to-end coverage.

• Implements subscription lifecycle, reconnect behavior, reliability options, and platform-specific background delivery.
• Adds Push endpoint and stable client-ID configuration to generated clients.
• Adds transport dependencies, platform packaging/configuration, and cross-SDK behavioral tests.
• Corrects Web Push broker derivation to use the regular API endpoint rather than the independently configured Realtime endpoint.

_{Reviews (47) · Last reviewed commit: "fix(web): derive the default push host f..."}

[ChiragAgg5k]

[P1] Reconnect and restore subscriptions after an unexpected disconnect

The disconnect listener only reports lifecycle events, and buildPushClient() never enables HiveMQ automatic reconnect. After a network interruption, the existing subscriptions therefore stop receiving indefinitely unless application code explicitly intervenes. Keeping the client ID stable does not help if no new connection is attempted. The same missing recovery exists in Apple (Push.swift.twig, addCloseListener) and Unity (Push.cs.twig, DisconnectedAsync): their handlers only notify callers.

I reproduced this with locally generated SDKs at dac7a5ffa: subscribe, successfully receive a QoS 1 message, force the broker's TCP connection closed, wait four seconds, then publish again. Android, Apple, and Unity each emitted only one CONNECT total and received no second message; a Web control reconnected and resumed delivery. Android was tested under Robolectric, Apple on macOS, and Unity using the generated Push.cs plus the bundled MQTTnet DLL with minimal engine/configuration stubs—not a Unity player. I rechecked these connection paths at the current head b39d41c9; automatic reconnect is still absent.

Please add reconnect/backoff and resubscription for unexpected disconnects in all three SDKs, while ensuring explicit close() disables recovery. A forced-disconnect regression test should verify that an existing subscription resumes delivery without another application-level subscribe() call.

[ArnabChatterjee20k]

Fixed in 6981da2. Android now enables HiveMQ automaticReconnectWithDefaultConfig(); with clean start off and a stable client id the broker resumes the session, so delivery continues after a drop without resubscribing (resubscribing would stack a second per-subscription HiveMQ callback). Apple (MQTTNIO) and Unity (MQTTnet) have no built-in reconnect, so their close/disconnect handlers now run a backoff loop (1s..30s) that reconnects and resubscribes every active filter at its effective QoS. A deliberate close() disables recovery in all three via a closing flag (and HiveMQ does not reconnect after a user-initiated disconnect).

Not yet added: an in-repo forced-disconnect regression test. The mock broker (utopia-php/mqtt Swoole server) can't drop a client's socket on command, so a real forced-disconnect e2e needs broker support or a per-SDK instrumented harness like the one you used locally. Happy to follow up on that separately — flagging so it isn't assumed covered.

[ArnabChatterjee20k]

@greptile I think the bugs are fixed now and you can give a 5/5