feat: enhance book caching and MiniPlayer flexibility, and improve accessibility

Author: Surjit Kumar Sahoo

.agent/rules/project-context.md

@@ -15,7 +15,7 @@ This is an offline first Android client app for the [audiobookshelf](https://git
 - The app should watch the network changes, such as connecting to a new wifi network, or lan network, or disconnecting from a network and connecting to a new network, disconnecting from wifi and connecting to celular network etc, and try to ping or reachout the audiobook server to check whether the server is reachable.
 - If the server is reachable, the app should sync the local progress to the server and pull the latest progress updates from the server to the local database, it should merge the updates from both.
 - If the server is reachable, and some chapters of any audiobook is download, i.e. available offline, then offline track should be given priority for playback.
-- If the offline track is deleted / cleared while the book is being played, it should fallback to the online URL if the server is reachable, else it should pause the playback, and make sure to correctly store the last
+- If the offline track is deleted / cleared while the book is being played, the player should attempt to fallback to the online URL if the server is reachable, otherwise pause playback and persist the last playback state (track ID, playback position/timestamp, current chapter/index, and playback status) plus a flag indicating offline content was removed; ensure the rule notes that these persisted fields are used to resume or report playback state and are written atomically to the player state store.
 - The app must be fully functional for downloaded content when offline.
 
 ## Ensure Stability
@@ -28,7 +28,7 @@ This is an offline first Android client app for the [audiobookshelf](https://git
 - When the app loads, it should load the offline available book content immediately, then in the background reach out to the server (if the server is reachable) and fetch the full list of the books, continue listening section books and update the UI seemlessly.
 - The app should cache all the book's metadata in local database to optimise the app load time, Only the chapters / audio tracks should not be cached automatically / by default. Chapters should be downloaded and cached on demand by the user, using the download chapters/book functionality.
 - When the app loads, if the server is not reachable, it shouldn't show long loading screen, trying to fetch the books from the server, it should load the book's list from the local database, however it should only show the books whos' chapters are downloaded and available offline can be played.
-- When the server becomes reachable, it should update the books list, as now all the books can be played from local cahce or online from the server.
+- When the server becomes reachable, it should update the books list, as now all the books can be played from local cache or online from the server.
 - When the network is switched, the app should trigger checking whether the server is still reachable or not, if not reachable, it should update the UI to only show offline available ready to play books.
 
 ## General Guidelines and Standards

app/src/main/kotlin/org/grakovne/lissen/channel/audiobookshelf/podcast/converter/PodcastPageResponseConverter.kt

@@ -25,6 +25,7 @@ class PodcastPageResponseConverter
             subtitle = null,
             series = null,
             author = it.media.metadata.author,
+            // Duration is unavailable from the API
             duration = 0.0,
             libraryId = libraryId,
           )

app/src/main/kotlin/org/grakovne/lissen/common/NetworkService.kt

@@ -11,6 +11,7 @@ import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
@@ -92,18 +93,19 @@ class NetworkService
 
           val hostUrl = preferences.getHost()
           if (hostUrl.isNullOrBlank()) {
-            _isServerAvailable.emit(isConnectedToInternet)
+            _isServerAvailable.emit(false)
             return@launch
           }
 
           try {
             val url = java.net.URL(hostUrl)
             val port = if (url.port == -1) url.defaultPort else url.port
-            val socket = java.net.Socket()
             val address = java.net.InetSocketAddress(url.host, port)
 
-            socket.connect(address, 2000)
-            socket.close()
+            java.net.Socket().use { socket ->
+              socket.connect(address, 2000)
+            }
+
             _isServerAvailable.emit(true)
           } catch (e: Exception) {
             Timber.e(e, "Server reachability check failed for $hostUrl")
@@ -156,4 +158,8 @@ class NetworkService
       cachedNetworkHandle = network.networkHandle
       return cachedSsid
     }
+
+    override fun onDestroy() {
+      scope.cancel()
+    }
   }

app/src/main/kotlin/org/grakovne/lissen/common/RunningComponent.kt

@@ -2,4 +2,6 @@ package org.grakovne.lissen.common
 
 interface RunningComponent {
   fun onCreate()
+
+  fun onDestroy() {}
 }

app/src/main/kotlin/org/grakovne/lissen/content/AuthRepository.kt

@@ -25,7 +25,7 @@ class AuthRepository
       username: String,
       password: String,
     ): OperationResult<UserAccount> {
-      Timber.d("Authorizing for $username@$host")
+      Timber.d("Authorizing for host: $host")
       return provideAuthService().authorize(host, username, password) { onPostLogin(host, it) }
     }
 

app/src/main/kotlin/org/grakovne/lissen/content/BookRepository.kt

@@ -5,6 +5,7 @@ import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.combine
 import org.grakovne.lissen.channel.audiobookshelf.AudiobookshelfChannelProvider
 import org.grakovne.lissen.channel.common.MediaChannel
+import org.grakovne.lissen.channel.common.OperationError
 import org.grakovne.lissen.channel.common.OperationResult
 import org.grakovne.lissen.common.NetworkService
 import org.grakovne.lissen.content.cache.persistent.LocalCacheRepository
@@ -46,12 +47,20 @@ class BookRepository
         }
 
       Timber.d("Local URI miss for $libraryItemId / $chapterId. Falling back to REMOTE.")
-      return providePreferredChannel()
-        .provideFileUri(libraryItemId, chapterId)
-        .let {
-          Timber.d("Providing REMOTE URI for $libraryItemId / $chapterId: $it")
-          OperationResult.Success(it)
+
+      return try {
+        val uri = providePreferredChannel().provideFileUri(libraryItemId, chapterId)
+
+        if (uri == null) {
+          OperationResult.Error(OperationError.InternalError, "Remote URI is null")
+        } else {
+          Timber.d("Providing REMOTE URI for $libraryItemId / $chapterId: $uri")
+          OperationResult.Success(uri)
         }
+      } catch (e: Exception) {
+        Timber.e(e, "Failed to provide file URI for $libraryItemId and $chapterId")
+        OperationResult.Error(OperationError.InternalError, e.message ?: "Unknown error occurred")
+      }
     }
 
     suspend fun syncProgress(

app/src/main/kotlin/org/grakovne/lissen/content/LissenMediaProvider.kt

@@ -50,12 +50,14 @@ class LissenMediaProvider
         }
 
       Timber.d("Local URI miss for $libraryItemId / $chapterId. Falling back to REMOTE.")
-      return providePreferredChannel()
-        .provideFileUri(libraryItemId, chapterId)
-        .let {
-          Timber.d("Providing REMOTE URI for $libraryItemId / $chapterId: $it")
-          OperationResult.Success(it)
-        }
+      return try {
+        val uri = providePreferredChannel().provideFileUri(libraryItemId, chapterId)
+        Timber.d("Providing REMOTE URI for $libraryItemId / $chapterId: $uri")
+        OperationResult.Success(uri)
+      } catch (e: Exception) {
+        Timber.e(e, "Failed to provide file URI for $libraryItemId and $chapterId")
+        OperationResult.Error(OperationError.InternalError, e.message)
+      }
     }
 
     suspend fun syncProgress(

app/src/main/kotlin/org/grakovne/lissen/content/cache/persistent/ContentCachingManager.kt

@@ -110,7 +110,7 @@ class ContentCachingManager
 
       findRequestedFiles(item, listOf(chapter))
         .forEach { file ->
-          val binaryContent = properties.provideMediaCachePatch(item.id, file.id)
+          val binaryContent = properties.provideMediaCachePath(item.id, file.id)
 
           if (binaryContent.exists()) {
             binaryContent.delete()
@@ -171,7 +171,7 @@ class ContentCachingManager
           }
 
           val body = response.body
-          val dest = properties.provideMediaCachePatch(bookId, file.id)
+          val dest = properties.provideMediaCachePath(bookId, file.id)
           dest.parentFile?.mkdirs()
 
           try {

app/src/main/kotlin/org/grakovne/lissen/content/cache/persistent/LocalCacheRepository.kt

@@ -121,7 +121,7 @@ class LocalCacheRepository
 
     suspend fun fetchRecentListenedBooks(
       libraryId: String,
-      downloadedOnly: Boolean,
+      downloadedOnly: Boolean = false,
     ): OperationResult<List<RecentBook>> =
       cachedBookRepository
         .fetchRecentBooks(
@@ -161,24 +161,24 @@ class LocalCacheRepository
 
     suspend fun cacheBookMetadata(book: DetailedItem) {
       try {
-        val restoredChapters =
+        val (restoredChapters, droppedChapters) =
           book
             .chapters
-            .filter { chapter ->
+            .partition { chapter ->
               val files = findRelatedFiles(chapter, book.files)
-              if (files.isEmpty()) return@filter false
+              if (files.isEmpty()) return@partition false
 
               files.all { file ->
                 storageProperties
-                  .provideMediaCachePatch(book.id, file.id)
+                  .provideMediaCachePath(book.id, file.id)
                   .exists()
               }
             }
 
         cachedBookRepository.cacheBook(
           book = book,
           fetchedChapters = restoredChapters,
-          droppedChapters = emptyList(),
+          droppedChapters = droppedChapters,
         )
         Timber.d("Successfully cached book metadata for ${book.id}")
       } catch (e: Exception) {

app/src/main/kotlin/org/grakovne/lissen/content/cache/persistent/OfflineBookStorageProperties.kt

@@ -27,7 +27,7 @@ class OfflineBookStorageProperties
 
     fun provideBookCache(bookId: String): File = baseFolder().resolve(bookId)
 
-    fun provideMediaCachePatch(
+    fun provideMediaCachePath(
       bookId: String,
       fileId: String,
     ): File =