feat(opds): add OpenSearch pagination metadata and search description

Extend the OPDS feed model so clients can page through large catalogs and
discover how to search them.

Feed changes:
- Add the OpenSearch namespace (xmlns:opensearch) to all feeds.
- Add optional TotalResults/ItemsPerPage/StartIndex fields, serialized as
  <opensearch:totalResults>, <opensearch:itemsPerPage> and
  <opensearch:startIndex>, plus a SetPagination helper.
- Add OpenSearchDescription/OpenSearchUrl types and a NewSearchDescription
  constructor with GenerateXML/GenerateXMLString. This produces the
  OpenSearch description document (application/opensearchdescription+xml)
  that OPDS clients like KOReader fetch to learn the {searchTerms} search
  URL template.

These are building blocks; the handlers are wired up in a follow-up commit.

Tests cover SetPagination, omission when unset, XML emission of the
paging metadata, and OpenSearch description generation/serialization.

internal/opds/feed.go

@@ -9,15 +9,19 @@ import (
 // OPDS 1.2 Feed Structures
 
 type Feed struct {
-	XMLName xml.Name `xml:"feed"`
-	Xmlns   string   `xml:"xmlns,attr"`
-	OpdsNS  string   `xml:"xmlns:opds,attr"`
-	DcNS    string   `xml:"xmlns:dc,attr"`
-	ID      string   `xml:"id"`
-	Title   string   `xml:"title"`
-	Updated string   `xml:"updated"`
-	Links   []Link   `xml:"link"`
-	Entries []Entry  `xml:"entry"`
+	XMLName      xml.Name `xml:"feed"`
+	Xmlns        string   `xml:"xmlns,attr"`
+	OpdsNS       string   `xml:"xmlns:opds,attr"`
+	DcNS         string   `xml:"xmlns:dc,attr"`
+	OpenSearchNS string   `xml:"xmlns:opensearch,attr,omitempty"`
+	ID           string   `xml:"id"`
+	Title        string   `xml:"title"`
+	Updated      string   `xml:"updated"`
+	Links        []Link   `xml:"link"`
+	TotalResults *int     `xml:"opensearch:totalResults,omitempty"`
+	ItemsPerPage *int     `xml:"opensearch:itemsPerPage,omitempty"`
+	StartIndex   *int     `xml:"opensearch:startIndex,omitempty"`
+	Entries      []Entry  `xml:"entry"`
 }
 
 type Entry struct {
@@ -64,17 +68,29 @@ type Category struct {
 func NewFeed(feedID, title string) *Feed {
 	now := time.Now().Format(time.RFC3339)
 	return &Feed{
-		Xmlns:   "http://www.w3.org/2005/Atom",
-		OpdsNS:  "http://opds-spec.org/2010/",
-		DcNS:    "http://purl.org/dc/elements/1.1/",
-		ID:      feedID,
-		Title:   title,
-		Updated: now,
-		Links:   []Link{},
-		Entries: []Entry{},
+		Xmlns:        "http://www.w3.org/2005/Atom",
+		OpdsNS:       "http://opds-spec.org/2010/",
+		DcNS:         "http://purl.org/dc/elements/1.1/",
+		OpenSearchNS: "http://a9.com/-/spec/opensearch/1.1/",
+		ID:           feedID,
+		Title:        title,
+		Updated:      now,
+		Links:        []Link{},
+		Entries:      []Entry{},
 	}
 }
 
+// SetPagination populates the OpenSearch paging metadata (totalResults,
+// itemsPerPage, startIndex). startIndex is 1-based to match the page model.
+func (f *Feed) SetPagination(totalResults, itemsPerPage, startIndex int) {
+	tr := totalResults
+	ipp := itemsPerPage
+	si := startIndex
+	f.TotalResults = &tr
+	f.ItemsPerPage = &ipp
+	f.StartIndex = &si
+}
+
 // AddLink adds a link to the feed
 func (f *Feed) AddLink(href, linkType, rel string) {
 	f.Links = append(f.Links, Link{
@@ -178,6 +194,62 @@ func (f *Feed) GenerateXMLString() (string, error) {
 	return xml.Header + string(output), nil
 }
 
+// OpenSearchUrl is a single <Url> element in an OpenSearch description.
+type OpenSearchUrl struct {
+	XMLName  xml.Name `xml:"Url"`
+	Type     string   `xml:"type,attr"`
+	Template string   `xml:"template,attr"`
+}
+
+// OpenSearchDescription is an OpenSearch description document used by OPDS
+// clients (e.g. KOReader) to discover how to perform catalog searches. Clients
+// fetch this document at the catalog's rel="search" link, then substitute
+// {searchTerms} in the Url template to execute a query.
+type OpenSearchDescription struct {
+	XMLName        xml.Name      `xml:"OpenSearchDescription"`
+	Xmlns          string        `xml:"xmlns,attr"`
+	ShortName      string        `xml:"ShortName"`
+	Description    string        `xml:"Description"`
+	InputEncoding  string        `xml:"InputEncoding"`
+	OutputEncoding string        `xml:"OutputEncoding"`
+	Url            OpenSearchUrl `xml:"Url"`
+}
+
+// NewSearchDescription creates an OpenSearch description document whose Url
+// template points clients back to the search results endpoint. The template
+// must contain the {searchTerms} placeholder.
+func NewSearchDescription(shortName, description, template string) *OpenSearchDescription {
+	return &OpenSearchDescription{
+		Xmlns:          "http://a9.com/-/spec/opensearch/1.1/",
+		ShortName:      shortName,
+		Description:    description,
+		InputEncoding:  "UTF-8",
+		OutputEncoding: "UTF-8",
+		Url: OpenSearchUrl{
+			Type:     "application/atom+xml;profile=opds-catalog;kind=acquisition",
+			Template: template,
+		},
+	}
+}
+
+// GenerateXML generates the OpenSearch description XML
+func (d *OpenSearchDescription) GenerateXML() ([]byte, error) {
+	output, err := xml.MarshalIndent(d, "", "  ")
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal OpenSearch description: %w", err)
+	}
+	return output, nil
+}
+
+// GenerateXMLString generates the OpenSearch description XML as a string
+func (d *OpenSearchDescription) GenerateXMLString() (string, error) {
+	output, err := d.GenerateXML()
+	if err != nil {
+		return "", err
+	}
+	return xml.Header + string(output), nil
+}
+
 // NewErrorFeed creates an error feed
 func NewErrorFeed(message string) *Feed {
 	feed := NewFeed(