feat(mobile): keep downloads going in the background #143

Merged
joshuafhiggins merged 1 commits from t3/ios-background-downloads into main 2026-11-20 10:25:20 -05:00
Owner

Song downloads stopped when the app left the screen or the phone locked: iOS used a foreground URL session that dies on suspension, and Android froze the JS runtime.

iOS

  • Songs download with expo-file-system's DownloadTask in its background session, which keeps going while the app is suspended. When the app leaves the screen, every waiting song is handed to iOS at once, since downloads started from the background can be deferred until Wi-Fi and power.
  • On iOS 26+, tapping Download starts a continued processing task (react-native-continued-task) that keeps the app running with a Live Activity showing songs left. Songs then download 2 at a time through the regular session with fresh sign-in tokens. When the task ends, in-flight songs restart in the background session.
  • Background downloads send only the JWT, not the refresh token. Otherwise an expired JWT makes the server spend the refresh token and the app's next refresh trips Convex Auth reuse detection, signing the user out. A redirect to the sign-in page (HTML) now fails the song instead of saving it.
  • Keychain reads fall back to the last value seen, so a locked phone can't break a download.

Android

  • A small local module (modules/download-service) runs a dataSync foreground service with a "Downloading N songs" notification while songs are queued.

Known limits

  • Background-session downloads still running about an hour after leaving the app fail once the JWT expires; they show in the failure toast.
  • Cancel on the Live Activity is reported by iOS the same as expiry, so downloads continue in the background session.
  • Not verified on the Mac Catalyst build, and not yet tested on a device.

🤖 Generated with Claude Code, using Claude Opus 5.5 in T3 Code.

Song downloads stopped when the app left the screen or the phone locked: iOS used a foreground URL session that dies on suspension, and Android froze the JS runtime. **iOS** - Songs download with expo-file-system's `DownloadTask` in its background session, which keeps going while the app is suspended. When the app leaves the screen, every waiting song is handed to iOS at once, since downloads started from the background can be deferred until Wi-Fi and power. - On iOS 26+, tapping Download starts a continued processing task (`react-native-continued-task`) that keeps the app running with a Live Activity showing songs left. Songs then download 2 at a time through the regular session with fresh sign-in tokens. When the task ends, in-flight songs restart in the background session. - Background downloads send only the JWT, not the refresh token. Otherwise an expired JWT makes the server spend the refresh token and the app's next refresh trips Convex Auth reuse detection, signing the user out. A redirect to the sign-in page (HTML) now fails the song instead of saving it. - Keychain reads fall back to the last value seen, so a locked phone can't break a download. **Android** - A small local module (`modules/download-service`) runs a `dataSync` foreground service with a "Downloading N songs" notification while songs are queued. **Known limits** - Background-session downloads still running about an hour after leaving the app fail once the JWT expires; they show in the failure toast. - Cancel on the Live Activity is reported by iOS the same as expiry, so downloads continue in the background session. - Not verified on the Mac Catalyst build, and not yet tested on a device. 🤖 Generated with [Claude Code](https://claude.com/claude-code), using Claude Opus 5.5 in T3 Code.
joshuafhiggins added 1 commit 2026-11-20 10:25:12 -05:00
iOS songs download through a background URL session, and on iOS 26+ a
continued processing task keeps the app running with a Live Activity.
Android keeps the app alive with a dataSync foreground service while songs
are queued.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
joshuafhiggins force-pushed t3/ios-background-downloads from f02515b55a to ffafbdc7ad 2026-11-20 10:25:12 -05:00 Compare
joshuafhiggins merged commit d7d476e5ec into main 2026-11-20 10:25:20 -05:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: joshuafhiggins/otunes#143