Files
pipelines/app/notes/android-background-delivery.md
T
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

33 lines
2.0 KiB
Markdown

# 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'`.