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

92 lines
5.1 KiB
Markdown

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