refactor(opds): align feed generation with RFC5005 and OpenSearch specs (#1611)

* refactor(opds): align feed generation with RFC5005 and OpenSearch specs

This commit refactors the OPDS feed generation to strictly adhere to official specifications for search and pagination.

Previously, OpenSearch response elements (totalResults, itemsPerPage, startIndex) were incorrectly included in all acquisition feeds. According to the OPDS 1.2 and OpenSearch 1.1 specifications, these elements should only be present in feeds that are a direct response to a search query. This change restricts their inclusion to search result feeds only, ensuring spec compliance.

Additionally, pagination link relations were not fully implemented as per RFC 5005. This commit enhances all paginated feeds to include `first` and `last` links, in addition to the existing `prev` and `next` links. This provides a complete and standard-compliant navigation experience for OPDS clients.

- `FeedBuilderInternal` now accepts an `isSearchFeed` flag to conditionally add OpenSearch elements.
- All feed generation methods in `OpdsFeedBuilder` and `OpdsV1Controller` now correctly identify search contexts.
- RFC 5005 pagination links (`first`, `last`, `prev`, `next`) are now generated for all paginated feeds.
- Added necessary link relation constants to `OpdsConstants`.

* feat(opds): improve pagination navigation and code organization

server/src/main/kotlin/suwayomi/tachidesk/opds/impl/FeedBuilderInternal.kt

@@ -9,20 +9,22 @@ import suwayomi.tachidesk.opds.model.OpdsLinkXml
 import suwayomi.tachidesk.opds.util.OpdsDateUtil
 import suwayomi.tachidesk.server.serverConfig
 import java.util.Locale
+import kotlin.math.ceil
 
 /**
- * Clase de ayuda para construir un OpdsFeedXml.
+ * Helper class to build an OpdsFeedXml.
  */
 class FeedBuilderInternal(
-    val baseUrl: String,
-    val idPath: String,
-    val title: String,
-    val locale: Locale,
-    val feedType: String,
-    var pageNum: Int? = 1,
-    var explicitQueryParams: String? = null,
-    val currentSort: String? = null,
-    val currentFilter: String? = null,
+    private val baseUrl: String,
+    private val idPath: String,
+    private val title: String,
+    private val locale: Locale,
+    private val feedType: String,
+    private val pageNum: Int? = 1,
+    private val explicitQueryParams: String? = null,
+    private val currentSort: String? = null,
+    private val currentFilter: String? = null,
+    private val isSearchFeed: Boolean = false,
 ) {
     private val opdsItemsPerPageBounded: Int
         get() = serverConfig.opdsItemsPerPage.value.coerceIn(10, 5000)
@@ -55,8 +57,7 @@ class FeedBuilderInternal(
     }
 
     fun build(): OpdsFeedXml {
-        val actualPageNum = pageNum ?: 1
-        val selfLinkHref = buildUrlWithParams(idPath, if (pageNum != null) actualPageNum else null)
+        val selfLinkHref = buildUrlWithParams(idPath, if (pageNum != null) pageNum else null)
         val feedLinks = mutableListOf<OpdsLinkXml>()
         feedLinks.addAll(this.links)
 
@@ -80,24 +81,54 @@ class FeedBuilderInternal(
             ),
         )
 
+        // Add pagination links if needed
         if (pageNum != null) {
-            if (actualPageNum > 1) {
+            val totalPages = ceil(totalResults.toDouble() / opdsItemsPerPageBounded).toInt()
+
+            if (totalPages > 1) {
+                val currentPage = pageNum.coerceAtLeast(1)
+
+                // Always add 'first' link when there are multiple pages
                 feedLinks.add(
                     OpdsLinkXml(
-                        OpdsConstants.LINK_REL_PREV,
-                        buildUrlWithParams(idPath, actualPageNum - 1),
+                        OpdsConstants.LINK_REL_FIRST,
+                        buildUrlWithParams(idPath, 1),
                         feedType,
-                        MR.strings.opds_linktitle_previous_page.localized(locale),
+                        MR.strings.opds_linktitle_first_page.localized(locale),
                     ),
                 )
-            }
-            if (totalResults > actualPageNum * opdsItemsPerPageBounded) {
+
+                // Add 'prev' link if not on first page
+                if (currentPage > 1) {
+                    feedLinks.add(
+                        OpdsLinkXml(
+                            OpdsConstants.LINK_REL_PREV,
+                            buildUrlWithParams(idPath, currentPage - 1),
+                            feedType,
+                            MR.strings.opds_linktitle_previous_page.localized(locale),
+                        ),
+                    )
+                }
+
+                // Add 'next' link if not on last page
+                if (currentPage < totalPages) {
+                    feedLinks.add(
+                        OpdsLinkXml(
+                            OpdsConstants.LINK_REL_NEXT,
+                            buildUrlWithParams(idPath, currentPage + 1),
+                            feedType,
+                            MR.strings.opds_linktitle_next_page.localized(locale),
+                        ),
+                    )
+                }
+
+                // Always add 'last' link when there are multiple pages
                 feedLinks.add(
                     OpdsLinkXml(
-                        OpdsConstants.LINK_REL_NEXT,
-                        buildUrlWithParams(idPath, actualPageNum + 1),
+                        OpdsConstants.LINK_REL_LAST,
+                        buildUrlWithParams(idPath, totalPages),
                         feedType,
-                        MR.strings.opds_linktitle_next_page.localized(locale),
+                        MR.strings.opds_linktitle_last_page.localized(locale),
                     ),
                 )
             }
@@ -111,7 +142,7 @@ class FeedBuilderInternal(
         currentFilter?.let { urnParams.add("filter_$it") }
         val urnSuffix = if (urnParams.isNotEmpty()) ":${urnParams.joinToString(":")}" else ""
 
-        val showPaginationFields = pageNum != null && totalResults > 0
+        val showOpenSearchFields = isSearchFeed && pageNum != null && totalResults > 0
 
         return OpdsFeedXml(
             id = "urn:suwayomi:feed:${idPath.replace('/',':')}$urnSuffix",
@@ -121,9 +152,9 @@ class FeedBuilderInternal(
             author = feedAuthor,
             links = feedLinks,
             entries = entries,
-            totalResults = totalResults.takeIf { showPaginationFields },
-            itemsPerPage = if (showPaginationFields) opdsItemsPerPageBounded else null,
-            startIndex = if (showPaginationFields) ((actualPageNum - 1) * opdsItemsPerPageBounded + 1) else null,
+            totalResults = totalResults.takeIf { showOpenSearchFields },
+            itemsPerPage = if (showOpenSearchFields) opdsItemsPerPageBounded else null,
+            startIndex = if (showOpenSearchFields) ((pageNum - 1) * opdsItemsPerPageBounded) + 1 else null,
         )
     }
 }