Files
pipelines/app/notes/android-background-delivery.md
alan 826e420423 Deliver server notifications from the Android app itself
A native foreground service keeps an authenticated websocket to the
connected server (handed over by the app on every connect), subscribes with
a replay cursor, shows each notification with kind-based channels and
grouping, opens pipelines:// links on tap, and clears taps, dismissals and
cross-device clears. It starts at boot and app launch, backs off and follows
network changes. Settings gains the delivery switch, status, notification
and battery-exemption actions, and the server's optional ntfy_enabled
toggle.
2026-11-01 02:21:22 +00:00

2.0 KiB

Android background delivery (notifications without ntfy)

Design

  • android/app/src/main/kotlin/net/awan/pipelines_app/notify/: native foreground service (specialUse, no Flutter engine), OkHttp websocket with the app's session cookie, exponential backoff (1 s .. 5 min) rotating through the server's trusted addresses, default-network callback (reconnect on network change, "waiting for network" when none), quiet "Pipelines is connected" notification. It starts at boot or after an app update (BootReceiver) and at app launch.
  • Protocol: subscribe_notifications with after = last received id; notifications_subscribed (notifications, plus recently cleared ids that are dismissed), notification ({"notification": N}), notifications_cleared. Taps (MainActivity) and dismissals (NotificationDismissReceiver) queue clear_notifications durably until the socket is connected.
  • DeliveryLedger: cursor, bounded shown-id dedupe, pending clears; reset when the server changes. Stable notification id = FNV-1a of the server id.
  • Channels per kind (and non-default priority), grouped by kind; importance from kind because the server sends priority 3. Android groups by group, with a summary.
  • Dart: lib/features/notification_service/ (MethodChannel bridge pipelines/notification_service, handoff of the connected server and cookie on every connect, Settings controller); Settings section settings_device_delivery_section.dart; the server's optional ntfy_enabled appears as "Also send to ntfy".

Checks

  • Kotlin JVM tests: cd android && ./gradlew :app:testDebugUnitTest (needs a JDK Gradle supports, e.g. Android Studio's JBR via JAVA_HOME).
  • On-device check against a loopback stand-in server: python3 -I tool/fake_notification_server.py --port 18765 --log /tmp/notify.log, connect the emulator app to ws://10.0.2.2:18765/connect, then curl -X POST 'http://127.0.0.1:18765/push?id=run:1:0:failed&click=pipelines://run/1'.