[BW-DL-05] Treat unavailable removable storage separately from corrupt downloads #20
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Classification
Active follow-up from #15 / GitHub PR #106.
Problem / opportunity
Current removable-volume support uses app-specific directories from
getExternalFilesDirs. Existing manifests hold absolutefile://URIs. When an SD/removable volume is removed, startup verification sees those paths as missing and marks previously complete files/books Failed. Reinserting the intact card does not automatically restore the manifest's Complete state.Separately, if the currently selected volume is absent, new downloads silently fall back to internal storage while the stored selection still names the missing UUID.
User value
Removing an SD card should read as storage unavailable, not download corrupt. Re-inserting an intact card should make existing books usable again without unnecessary re-download. New-download fallback should be visible rather than surprising.
Scope
Explicitly out of scope
Dependencies
Unavailablehas a clean presentation boundary, but the storage correctness can be designed independently.Architecture seams affected
StorageVolumes/DownloadRoots.DownloadedBookEntityif durable owning-volume identity is required.DownloadVerifier.Server / API assumptions
No server changes. This is local storage truth. Re-download remains available through existing Audiobookshelf media URLs when the active profile is authorized.
Storage / migration implications
Likely Medium.
The current global selected volume UUID is only the destination for future downloads; it is not enough to identify where an older physical copy belongs after volume changes. A robust solution may require storing an owning volume UUID (or an equivalent stable storage locator) per physical downloaded copy.
If a schema field is added:
Unknown/conservative identity unless ownership can be proven from existing URIs/platform data;Privacy / security
Storage volume identity is device-local implementation metadata. Do not expose filesystem paths or volume identifiers in ordinary UI/logs; user-facing copy should use platform volume labels where safe.
Automated-test level
DownloadVerifiertests proving absent volume does not mark files Failed.StorageVolumestests for selected missing volume and internal fallback without rewriting preference.Device / platform acceptance
Real removable-storage testing is required. JVM/Robolectric evidence is not enough.
Test:
Estimated effort
Medium to Large.
Implementation risk
High. Incorrect classification can make valid offline media unavailable or trigger needless re-download/storage churn.
Recommended sequence
After BW-DL-02/03/04 unless this becomes a blocking device defect sooner.
Acceptance criteria
Links
Canonical implementation-readiness update — unified Downloads branch
Shared branch:
mcp/downloads-coherent-experienceRefreshed implementation HEAD before #20 mutation:
0f55bc3d6078de070b05ae5d3b0ca191909cdef8Current main at investigation start:
f9f7feba8e7bb499c6001bf0cc19a38357b7494aThis supersedes provisional #20 assumptions for the unified #19/#20/#21/#22/#29 program.
Current failure, confirmed from source
Current removable support stores only:
file://URIs on each downloaded file.It does not persist which volume owns a physical book copy.
StorageVolumes.roots()silently falls back to internal storage when the selected removable UUID is absent.DownloadVerifierthen treats an absent file path exactly like a genuinely missing file and downgrades the manifest to Failed. This is the defect described by #20.There is a second correctness problem: because retries resolve the current selected root again, a physical
(server,item)copy can theoretically drift/split across volumes after the storage preference changes. Owning-volume identity therefore has to be a durable physical-copy fact, not inferred later from path text.Playback also needs this distinction.
OfflineSessionBuilderandDefaultPlaybackRepositorycurrently accept a complete manifest and substitute its committedfile://URIs without asking whether the owning volume is mounted. Preserving Complete in Room without a storage-availability playback gate would merely move the failure from verification to the player.Required state dimensions
#20 will add a transient storage-availability dimension independent of durable download state:
Unavailable is not Failed/Corrupt. Unknown is not permission to guess an owner.
A valid combination is therefore:
durable Complete + removable owner + storage Unavailableand it remains logically preserved until the volume returns.
Durable owning-volume identity
Add nullable
storageVolumeUuidto the physical downloaded-book row/model:null= Unknown legacy owner.""= internal storage (same semantic UUID already used byStorageVolumeOption.INTERNAL_UUID).This belongs on
DownloadedBookEntity/OfflineBook, not profile claims and not individual WorkManager state. One physical copy has one owner.Database version: 20 -> 21.
Migration:
ALTER TABLE downloaded_books ADD COLUMN storageVolumeUuid TEXT DEFAULT NULLThe migration deliberately leaves every existing row Unknown. It must not infer UUIDs by parsing absolute paths, because that would manufacture ownership that cannot be proven while a card is absent. No file is touched by migration.
Update exported schema and the migration test. A version-20 downloaded row must survive with
storageVolumeUuid IS NULL, all files/claims intact.New-copy and retry ownership
For a brand-new physical copy:
If the listener selected removable storage but that UUID is absent when a new copy is created:
When the selected card returns, future new copies automatically resolve to it again because the preference was never rewritten.
This also prevents one physical book from being split across roots by a preference change.
Storage capability seam
Extend the existing storage boundary without creating a second database:
StorageVolumesremains authority for selected UUID and currently mounted volumes.Mount/unmount observation must be aggregate/process-level (media mount/eject/removal), not one listener per download row.
Verification rules
DownloadVerifiermust classify the owner before classifying missing/corrupt files:Known owner + volume Unavailable:
Known owner + Available:
Unknown legacy owner:
When a previously absent known volume becomes available, trigger manifest re-verification. An intact Complete copy becomes usable again with no redownload.
Playback/localisation rules
Storage availability must also guard local playback:
This prevents an absent card from being described as corrupt while also preventing a dead
file://URL from being handed to Media3.Downloads UI
Each stored row receives a storage-availability presentation independent of download recovery/execution state.
Known unavailable removable copy:
Unknown legacy:
Selected missing destination:
Privacy
Never surface/log:
Generic facts such as Storage unavailable / Internal fallback are allowed.
Exact implementation surface
Expected changes:
core/model/.../OfflineDownload.kt: owning-volume field + storage-availability model as appropriate.core/database/.../Entities.kt: nullablestorageVolumeUuid.ShelfPlayerDatabase.kt/core/database/build.gradle.kts: version 21.Migrations.kt: explicit 20->21 additive nullable migration.DownloadMappers.kt: map owning UUID both directions where applicable.DownloadRepository/DefaultDownloadRepository: assign/read stable physical owner and avoid changing it for additional profile claims.DownloadRoots/StorageVolumes/DownloadStorage: resolve the known physical owner separately from the selected future destination; aggregate availability observation.BookDownloader/FileDownloader: every file/retry uses the physical copy's stored owner.DownloadVerifier: Unavailable/Unknown cannot be collapsed into Missing/Corrupt.OfflineSessionBuilder/ playback localisation: do not use local URIs whose storage is unavailable.DownloadsViewModel/ UI: storage state + selected-volume fallback disclosure.Required deterministic proof
At minimum:
Physical acceptance still mandatory
Real removable-storage acceptance remains exactly required by #20:
SAF remains out of scope.
#20 IMPLEMENTATION READY