Files
pipelines/app/notes/android-background-delivery-reliability.md
T
alan 5c41474e6a Make Android notification delivery survive idle
Schedule reconnects with idle-tolerant alarms, keep a watchdog and wake lock, and restart after task removal so delivery continues while the app is closed. Request battery exemption, stop retrying on expired sessions, persist connection diagnostics, and expose the status in Settings.
2026-11-12 02:21:48 +00:00

5.1 KiB

Android background delivery: survive Doze, sign-in, battery, diagnosis

Stage 01-implement, run 20261112-0157. Source only; not committed, not installed.

What changed

  • Reconnects are alarms, not handler delays. ReconnectAlarms schedules setExactAndAllowWhileIdle when canScheduleExactAlarms(), otherwise setAndAllowWhileIdle. The alarm PendingIntent is a foreground-service intent to NotificationService (ACTION_RECONNECT). The Handler.postDelayed reconnect is gone.
  • Watchdog. NotificationWatchdog (JobScheduler, periodic 15 min, persisted) restarts the service when delivery is enabled and the socket is down with no reconnect pending. It does not restart while signed out or waiting for a network. Also scheduled by NotificationService.start.
  • Connect wake lock. ConnectWakeLock holds a partial wake lock for 30 s from connect() until the socket opens or fails.
  • Swipe away. onTaskRemoved logs and queues a watchdog check 2 s later.
  • Battery exemption. SettingsDeviceDeliverySection shows a persistent warning row while delivery is on and the exemption is missing, with the Samsung "Never sleeping apps" note. setEnabled(true) requests the exemption before starting the service. Opening Settings with delivery already on and the exemption missing asks once per open (NotificationServiceController.open); resume refreshes never ask again.
  • HTTP 401/403. The retry loop stops, status becomes sign_in_required, and a "Sign in to Pipelines again to keep notifications" notice is posted (channel pipelines.account, id 2). configure with a fresh cookie restarts the service.
  • Connection log. ConnectionLog keeps the last 50 events (time, event, error, HTTP code) in the service preferences. The channel method connectionEvents returns them. Settings shows them in an expandable "Connection log" row.

Files

  • Kotlin (new): ReconnectPolicy.kt, ReconnectAlarms.kt, NotificationWatchdog.kt, ConnectWakeLock.kt, ConnectionLog.kt
  • Kotlin (changed): NotificationService.kt, NotificationPresenter.kt, NotificationServiceChannel.kt, ServiceSettings.kt, AndroidManifest.xml (WAKE_LOCK, SCHEDULE_EXACT_ALARM, watchdog service)
  • Kotlin tests (new): ConnectionLogTest.kt (5), ReconnectPolicyTest.kt (3)
  • Dart (new): lib/features/notification_service/notification_service_events.dart
  • Dart (changed): notification_service_bridge.dart, notification_service_controller.dart, notification_service_status.dart, lib/features/settings/settings_device_delivery_section.dart
  • Dart tests (changed): test/features/settings/settings_device_delivery_section_test.dart (+8 cases), test/features/notification_service/notification_service_bridge_test.dart (+3 cases), test/features/notification_service/fake_notification_service.dart

Focused results

  • Kotlin: gradle :app:testDebugUnitTest --tests 'net.awan.pipelines_app.notify.*' BUILD SUCCESSFUL. 28 of 28 pass: ConnectionLogTest 5, ReconnectPolicyTest 3, DeliveryLedgerTest 8, NotificationProtocolTest 12. Includes main-source compile.
  • Flutter: tool/memwatch/full.sh on the four files below, PASS 35 passed, 0 failed (run twice, once after formatting):
    • test/features/settings/settings_device_delivery_section_test.dart
    • test/features/notification_service/notification_service_bridge_test.dart
    • test/features/notification_service/notification_service_handoff_test.dart
    • test/features/attention/notify/notification_delivery_test.dart
  • tool/analyze.sh: clean (run twice).

Affected UI states (for ui-review, not captured here)

  • Delivery on, exemption missing: warning row visible with Samsung note.
  • Delivery on, exemption granted: warning row gone; battery row says "Allowed".
  • Delivery off: no battery row, no warning row.
  • Status "Sign in to Pipelines again to keep notifications".
  • Connection log collapsed, expanded with events, expanded empty ("No connection events yet"). Expansion needs an interactive check.

Limitations and decisions

  • Not verified on a device. Doze timing, alarm delivery, the foreground-start exemption from alarms and the watchdog job, the swipe restart, and the sign-in notice were not run. The Fold was not touched.
  • Exact alarms. SCHEDULE_EXACT_ALARM is declared, but the app does not send the user to grant it. Without the grant, reconnects use idle-tolerant alarms.
  • Upgrade users are prompted when Settings opens, not at app start. The exemption is requested on switch-on, and on opening Settings while delivery is on and the exemption is missing. The prompt is not fired from app start because the section is the only place with the request context. A user who declines is prompted again the next time Settings opens, then sees the warning row. Users who never open Settings are not prompted.
  • JobScheduler is deferred in Doze, so the watchdog is a backstop; the alarms are the primary path.
  • NotificationService.kt is 387 lines (aim is under 250; it was 293 before). The reconnect alarms, watchdog, wake lock and log are in separate files, but the socket state machine remains in the service; splitting it further is a follow-up.