feat(apple): deliver push through a Notification Service Extension

[ArnabChatterjee20k]

What does this PR do?

Delivers push to an iOS app that was swiped away from recents, without the message content passing through APNs.

A silent push (#2000, appwrite/appwrite#14302) wakes a suspended app, but iOS never launches an app the user swiped away: "the system does not automatically launch your app if the user has force-quit it" (Apple). A visible push with mutable-content: 1 always shows, and iOS runs the app's Notification Service Extension for it first, even after a swipe-away. This PR makes that extension a one-line class:

• APNs carries a placeholder only.
• The extension fetches the real message over MQTT with the app's session, and shows it in the placeholder's place.

APNs { aps: { alert: { title: "New message" }, mutable-content: 1 } }    no content, no id
  → AppwriteNotificationService runs (even if the app was swiped away)
      app live?  yes → replace the app's latest banner with this one   (one banner)
                 no  → connect MQTT with the app's session → broker replays the backlog
                       → show one, queue the rest, hand all to the app
  → iOS shows the banner

Usage

1. Add a Notification Service Extension target:

   import Appwrite
   
   class NotificationService: AppwriteNotificationService {}

2. Put the app and the extension in one App Group, and set it in both Info.plists:

   <key>AppwritePushAppGroup</key>
   <string>group.com.example.app</string>

3. Nothing else changes in the app: push.subscribe(…, background: true) as before.

How

• Shared session (App Group):
  • Push keeps the endpoint, push endpoint, project, client id, and background topics with their titles, while it has background subscriptions.
  • The session secret or JWT goes in the Keychain, under the App Group's access group.
• No duplicate content:
  • The broker delivers each message once per session (user + client id).
  • The app and the extension share that session and the delivered-message store, which now re-reads the shared store, since two processes write it.
• App live: Push stamps a heartbeat every 3 s while connected; a suspended app stops. While the stamp is fresh (< 10 s), the extension doesn't connect, since the session allows one connection. Instead it replaces the app's latest banner, which Push now posts under the message id and marks as its own, so the user sees one banner.
• Several waiting messages: the extension shows one per push, and queues the rest for the pushes that follow.
• Hand-off: on its next subscribe, Push delivers the messages the extension fetched to the matching callbacks without banners, since iOS already showed them.
• Time limit: stops collecting once the replay goes quiet (1.5 s), or after 20 s. On iOS's ~30 s limit, the placeholder shows.

Server

The SDK side works with any visible mutable-content push. The server half is on appwrite/appwrite#14302, still to do:

• Send the placeholder visible push to Apple devices instead of (or as well as) the silent wake.
• Send it only when that device's session hasn't acknowledged the message after a short wait, so a live app gets no push at all. The banner replacement here covers the race when the acknowledgement is late.

Test Plan

• Unit tests (20 in total, 5 new):
  • shared session round-trip;
  • heartbeat window;
  • hand-off by topic, taken once;
  • pending queue order;
  • two delivered-message stores, standing in for the app and the extension, seeing each other's writes.
• swift build on macOS, iOS Simulator, and Linux (Swift 6.1, the CI image); swift format lint --strict.
• Rector, Twig lint, Generation suite.
• iOS Simulator, real APNs sandbox placeholder pushes, against the mock MQTT broker. SpringBoard logged "Service extension delivered mutated notification content" in each case:
  • App suspended: the extension fetched the message and the banner showed it in 2.5 s; the app logged nothing.
  • App swiped away (terminated): the same, with the app not running.
  • App swiped away from the App Switcher by hand, the user force-quit that blocks silent pushes: the extension still ran and the banner showed the fetched message (apns-unique-id 812409cc-…), with no app process running.
  • App relaunched: the two messages the extension fetched reached the callback with no banner, before the broker's live message, which got its banner.
  • App open: the extension didn't connect. SpringBoard logged "Removing delivered notifications" for the app's banner, and the push's banner showed that message instead.
• Real device. Visible pushes and mutable-content work in the Simulator, unlike silent pushes, so nothing here is Simulator-only, but the extension's memory and time limits should be checked on a device.

Related PRs and Issues

• Stacked on feat(apple): background push through APNs #2000.
• Server half: feat(messaging): wake APNS/FCM devices for Appwrite (MQTT) push appwrite#14302.
• Not yet: appwrite init apns adding the extension target and App Group.

[hansi-codes]

🟢 Tier S · Ready to merge

Adds an Apple Notification Service Extension base class that fetches pending push messages over MQTT and substitutes them into visible placeholder notifications. It also persists shared session, heartbeat, pending-message, and handoff state for coordination between the app and extension, and updates the Apple SDK generator and tests accordingly.

Verdict	New comments	Fixed	Still open
✅ Approved	0	0	0

📂 Walkthrough · 4

File	Change
src/SDK/Language/Apple.php	Registers the new generated Notification Service Extension source file.
templates/apple/Sources/Services/Push.swift.twig	Adds heartbeat and shared handoff integration, and stores delivered-message state in shared defaults.
templates/apple/Sources/Services/PushServiceExtension.swift.twig	Implements shared state, credential storage, MQTT backlog fetching, and notification-content replacement.
templates/apple/Tests/PushTests.swift.twig	Adds tests for shared session state, heartbeat, handoff, queue behavior, and cross-store delivery deduplication.

🔇 Filtered out · 1

Findings Hansi considered but did not post.

Finding

Why

Use a Keychain Sharing group for the shared credential

Verifier: The premise is incorrect for iOS: groups granted through the com.apple.security.application-groups entitlement are also valid keychain access groups. Both targets enabling the same App Group, as required by the documentation at lines 249–250, permits using its identifier directly as kSecAttrAccessGroup at line 232; a separate Keychain Sharing group is not required. Ignoring SecItemAdd's status does not establish the claimed entitlement failure under that setup.

---

_{Reviewed 0565e9a · Details · Comment @hansi-codes review to re-run, or mention @hansi-codes with a question.}

[hansi-codes]

🔵 Tier A · See the inline comments. Summary

[hansi-codes]

🟡 Tier B · See the inline comments. Summary

[ArnabChatterjee20k]

@hansi-codes review

[hansi-codes]

🟢 Tier S · Looks good to merge. Summary