fix(android): visible backup notification on API 31+ background runs #1339

Merged
chris merged 2 commits from fix/android-notification into main 2026-10-23 22:04:59 +02:00
Owner

Problem

On Android 12+ (API 31+) a periodic backup run starts from true background, where WorkManager's setForeground (which calls startForegroundService) throws ForegroundServiceStartNotAllowedException. BackupWorker swallowed that into the trace log and the run continued with no foreground service and no notification. The manifest deliberately had no POST_NOTIFICATIONS flow.

Changes (apps/android/app only — :core untouched)

  • sync/BackupNotifications.kt (new) — single owner of the notification surface: channel setup, the shared ongoing "backup running" builder, NotificationManager fallback (postFallback/cancelFallback), and the API 31+ foreground-promotion gate (foregroundPromotionEligible) reading this process's importance via getRunningAppProcesses() (public API; the dedicated getMyMemoryState getter is hidden from app code).
  • sync/BackupWorker.kt — when the gate says promotion is not allowed (periodic background runs): skip the doomed setForeground, trace once, post the ongoing notification directly; when promotion fails from an eligible state: same fallback. The fallback is cancelled in a finally only if this path posted it (a promoted FGS notification is torn down by the system). All existing BackupRunTrace breadcrumbs kept.
  • AndroidManifest.xml — adds POST_NOTIFICATIONS; stale "No POST_NOTIFICATIONS flow" comment rewritten; FOREGROUND_SERVICE_TYPE_DATA_SYNC wiring untouched.
  • ui/backup/BackupScreen.kt — third step of the existing ask-once permission chain: one-time short rationale dialog (what the notification shows; swiping it away doesn't stop the backup), then the system prompt on API 33+ only. Declining never gates backup. No new design system — reuses the screen's AlertDialog idiom. Strings in de (default), en, da.
  • Tests — BackupNotificationsTest: 11 Robolectric tests (channel idempotency + low importance, ongoing flag, fallback post→cancel, below-O behavior, promotion gate across importances/SDKs). Shadow APIs verified against the exact Robolectric 4.17 jar before use.
  • KNOWN_ISSUES.md — appended ISSUE-176 (med/mitigated, area:android) documenting the fix and the accepted limitation that the fallback carries no FGS process protections.

Notable fix found on the way

The old builder used the API 26+ two-arg Notification.Builder(context, channel) unconditionally, so on the Android 7.1 device (minSdk 25) every notification build threw NoSuchMethodError, silently swallowed by the promotion runCatching — no notification ever appeared there. The consolidated builder is now channel-less below O.

Verification

cd apps/android
rtk ./gradlew :app:assembleDebug        → BUILD SUCCESSFUL
rtk ./gradlew :app:testDebugUnitTest    → 535 tests, 0 failures/errors

Merged manifest confirmed to contain android.permission.POST_NOTIFICATIONS after the merge.

Scope note for reviewers: a local.properties (SDK path) was created locally to build; it is gitignored and not part of this PR.

## Problem On Android 12+ (API 31+) a periodic backup run starts from true background, where WorkManager's `setForeground` (which calls `startForegroundService`) throws `ForegroundServiceStartNotAllowedException`. `BackupWorker` swallowed that into the trace log and the run continued with **no foreground service and no notification**. The manifest deliberately had no `POST_NOTIFICATIONS` flow. ## Changes (`apps/android/app` only — `:core` untouched) - **`sync/BackupNotifications.kt` (new)** — single owner of the notification surface: channel setup, the shared ongoing "backup running" builder, `NotificationManager` fallback (`postFallback`/`cancelFallback`), and the API 31+ foreground-promotion gate (`foregroundPromotionEligible`) reading this process's importance via `getRunningAppProcesses()` (public API; the dedicated `getMyMemoryState` getter is hidden from app code). - **`sync/BackupWorker.kt`** — when the gate says promotion is not allowed (periodic background runs): skip the doomed `setForeground`, trace once, post the ongoing notification directly; when promotion fails from an eligible state: same fallback. The fallback is cancelled in a `finally` only if this path posted it (a promoted FGS notification is torn down by the system). All existing `BackupRunTrace` breadcrumbs kept. - **`AndroidManifest.xml`** — adds `POST_NOTIFICATIONS`; stale "No POST_NOTIFICATIONS flow" comment rewritten; `FOREGROUND_SERVICE_TYPE_DATA_SYNC` wiring untouched. - **`ui/backup/BackupScreen.kt`** — third step of the existing ask-once permission chain: one-time short rationale dialog (what the notification shows; swiping it away doesn't stop the backup), then the system prompt on API 33+ only. Declining never gates backup. No new design system — reuses the screen's `AlertDialog` idiom. Strings in de (default), en, da. - **Tests** — `BackupNotificationsTest`: 11 Robolectric tests (channel idempotency + low importance, ongoing flag, fallback post→cancel, below-O behavior, promotion gate across importances/SDKs). Shadow APIs verified against the exact Robolectric 4.17 jar before use. - **`KNOWN_ISSUES.md`** — appended ISSUE-176 (med/mitigated, area:android) documenting the fix and the accepted limitation that the fallback carries no FGS process protections. ## Notable fix found on the way The old builder used the API 26+ two-arg `Notification.Builder(context, channel)` unconditionally, so on the Android 7.1 device (minSdk 25) every notification build threw `NoSuchMethodError`, silently swallowed by the promotion `runCatching` — no notification ever appeared there. The consolidated builder is now channel-less below O. ## Verification ``` cd apps/android rtk ./gradlew :app:assembleDebug → BUILD SUCCESSFUL rtk ./gradlew :app:testDebugUnitTest → 535 tests, 0 failures/errors ``` Merged manifest confirmed to contain `android.permission.POST_NOTIFICATIONS` after the merge. Scope note for reviewers: a `local.properties` (SDK path) was created locally to build; it is gitignored and not part of this PR.
fix(android): visible backup notification on API 31+ background runs
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Deploy review instance (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 6s
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Android unit tests and debug APK (push) Successful in 3m57s
88423fdbdf
On Android 12+ a periodic backup run starts from true background, where
WorkManager's setForeground (startForegroundService) throws
ForegroundServiceStartNotAllowedException. The old runCatching swallowed
that into the trace log and the run continued with no foreground service
and no notification at all.

- BackupNotifications (new): single owner of the notification surface —
  channel, the shared running-notification builder (now channel-less
  below O, which the old two-arg Builder call never handled), a
  NotificationManager fallback (post/cancel), and the API 31+
  promotion gate reading this process's importance via
  getRunningAppProcesses.
- BackupWorker: gate the doomed setForeground call on that gate; when
  promotion is not allowed (periodic background runs) trace once and
  post the ongoing notification directly; on a failed promotion from an
  eligible state, fall back to the same notification. Only cancel what
  the fallback actually posted. Trace logging unchanged.
- Manifest: add POST_NOTIFICATIONS (runtime, API 33+); rewrite the stale
  "No POST_NOTIFICATIONS flow" comment for the new behavior.
- BackupScreen: third step of the existing ask-once permission chain —
  a one-time short rationale dialog, then the system prompt on API 33+.
  Declining never gates backup. Strings in de/en/da.
- Tests: BackupNotificationsTest (11 Robolectric tests: channel,
  builder, fallback post/cancel, promotion gate across SDKs).
- KNOWN_ISSUES: append ISSUE-176 (mitigated) documenting the fix and
  the accepted limitation that the fallback carries no FGS protection.

Verified: :app:assembleDebug and :app:testDebugUnitTest
(535 tests, 0 failures) with the Gradle wrapper in apps/android.
docs: renumber android notification issue to ISSUE-177 (176 taken by api fix branch)
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Deploy review instance (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 1m52s
90598eb7e4
chris force-pushed fix/android-notification from 90598eb7e4
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Deploy review instance (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 5s
Build and Deploy / Android unit tests and debug APK (push) Successful in 1m52s
to bc4fb4a78a
All checks were successful
Wiki Sync / Sync wiki from docs (push) Has been skipped
Build and Deploy / Detect changed services and test scopes (push) Successful in 3s
Build and Deploy / Smoke API and media worker (push) Has been skipped
Build and Deploy / Smoke web (push) Has been skipped
Build and Deploy / Smoke ML worker (push) Has been skipped
Build and Deploy / Smoke people worker (push) Has been skipped
Build and Deploy / Build postgres image (push) Has been skipped
Build and Deploy / Build Android CI image (push) Has been skipped
Build and Deploy / Build plants worker image (push) Has been skipped
Build and Deploy / Build converter worker image (push) Has been skipped
Build and Deploy / Deploy postgres (push) Has been skipped
Build and Deploy / Build API image (push) Has been skipped
Build and Deploy / Build media worker image (push) Has been skipped
Build and Deploy / Build ML worker image (push) Has been skipped
Build and Deploy / Build people worker image (push) Has been skipped
Build and Deploy / Build web image (push) Has been skipped
Build and Deploy / Deploy API (push) Has been skipped
Build and Deploy / Deploy web (push) Has been skipped
Build and Deploy / Deploy media worker (push) Has been skipped
Build and Deploy / Deploy ML worker (push) Has been skipped
Build and Deploy / Deploy plants worker (push) Has been skipped
Build and Deploy / Deploy people worker (push) Has been skipped
Build and Deploy / Deploy converter worker (push) Has been skipped
Build and Deploy / Deploy review instance (push) Has been skipped
Build and Deploy / Clean Docker build artifacts (push) Has been skipped
Build and Deploy / Run scoped PR tests (push) Successful in 12s
Build and Deploy / Android unit tests and debug APK (push) Successful in 2m1s
2026-10-23 22:02:36 +02:00
Compare
chris merged commit 011e29d6ea into main 2026-10-23 22:04:59 +02:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
chris/memories!1339
No description provided.