opds

package
v0.0.49 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 25, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AtomNS     = "http://www.w3.org/2005/Atom"
	DCNS       = "http://purl.org/dc/terms/"
	OPDSNS     = "http://opds-spec.org/2010/catalog"
	OpenSearch = "http://a9.com/-/spec/opensearch/1.1/"
)

OPDS namespaces.

View Source 
const (
	RelSelf        = "self"
	RelStart       = "start"
	RelUp          = "up"
	RelSubsection  = "subsection"
	RelNext        = "next"
	RelPrevious    = "previous"
	RelFirst       = "first"
	RelLast        = "last"
	RelSearch      = "search"
	RelAcquisition = "http://opds-spec.org/acquisition"
	RelImage       = "http://opds-spec.org/image"
	RelThumbnail   = "http://opds-spec.org/image/thumbnail"
)

Link relation types.

View Source 
const (
	MimeTypeAtom        = "application/atom+xml"
	MimeTypeNavigation  = "application/atom+xml;profile=opds-catalog;kind=navigation"
	MimeTypeAcquisition = "application/atom+xml;profile=opds-catalog;kind=acquisition"
	MimeTypeOpenSearch  = "application/opensearchdescription+xml"
	MimeTypeEPUB        = "application/epub+zip"
	MimeTypeKepub       = "application/kepub+zip"
	MimeTypeCBZ         = "application/vnd.comicbook+zip"
	MimeTypeM4B         = "audio/mp4"
	MimeTypePDF         = "application/pdf"
	MimeTypeJPEG        = "image/jpeg"
	MimeTypePNG         = "image/png"
	MimeTypeWebP        = "image/webp"
)

MIME types.

Variables

This section is empty.

Functions

func CoverMimeType 

func CoverMimeType(ext string) string

CoverMimeType returns the MIME type for a given cover extension.

func FileTypeMimeType 

func FileTypeMimeType(fileType string) string

FileTypeMimeType returns the MIME type for a given file type.

func RegisterRoutes 

func RegisterRoutes(e *echo.Echo, db *bun.DB, cfg *config.Config, authMiddleware *auth.Middleware)

RegisterRoutes registers all OPDS routes.

Types

type Author 

type Author struct {
	Name string `xml:"name"`
	URI  string `xml:"uri,omitempty"`
}

Author represents an Atom author element.

type AuthorInfo 

type AuthorInfo struct {
	Name      string
	BookCount int
}

AuthorInfo holds aggregated author information.

type Content 

type Content struct {
	Type  string `xml:"type,attr,omitempty"`
	Value string `xml:",chardata"`
}

Content represents entry content with type attribute.

type Entry 

type Entry struct {
	ID        string    `xml:"id"`
	Title     string    `xml:"title"`
	Updated   time.Time `xml:"updated"`
	Published time.Time `xml:"published,omitempty"`
	Authors   []Author  `xml:"author,omitempty"`
	Summary   string    `xml:"summary,omitempty"`
	Content   *Content  `xml:"content,omitempty"`
	Links     []Link    `xml:"link"`
	// Dublin Core elements
	Language   string `xml:"dc:language,omitempty"`
	Publisher  string `xml:"dc:publisher,omitempty"`
	Identifier string `xml:"dc:identifier,omitempty"`
}

Entry represents an OPDS entry (book or navigation item).

func NewEntry 

func NewEntry(id, title string) Entry

NewEntry creates a new OPDS entry. 

func (e *Entry) AddAcquisitionLink(href, mimeType string)

AddAcquisitionLink adds a download link for a file. 

func (e *Entry) AddImageLink(href, mimeType string)

AddImageLink adds a cover image link. 

func (e *Entry) AddLink(rel, href, linkType string)

AddLink adds a link to the entry. 

func (e *Entry) AddThumbnailLink(href, mimeType string)

AddThumbnailLink adds a thumbnail image link.

type Feed 

type Feed struct {
	XMLName   xml.Name  `xml:"feed"`
	Xmlns     string    `xml:"xmlns,attr"`
	XmlnsDC   string    `xml:"xmlns:dc,attr,omitempty"`
	XmlnsOPDS string    `xml:"xmlns:opds,attr,omitempty"`
	ID        string    `xml:"id"`
	Title     string    `xml:"title"`
	Updated   time.Time `xml:"updated"`
	Author    *Author   `xml:"author,omitempty"`
	Links     []Link    `xml:"link"`
	Entries   []Entry   `xml:"entry"`
}

Feed represents an OPDS Atom feed.

func NewFeed 

func NewFeed(id, title string) *Feed

NewFeed creates a new OPDS feed with default namespaces.

func (*Feed) AddEntry 

func (f *Feed) AddEntry(entry Entry)

AddEntry adds an entry to the feed. 

func (f *Feed) AddLink(rel, href, linkType string)

AddLink adds a link to the feed. 

type Link struct {
	Rel         string `xml:"rel,attr,omitempty"`
	Href        string `xml:"href,attr"`
	Type        string `xml:"type,attr,omitempty"`
	Title       string `xml:"title,attr,omitempty"`
	FacetGroup  string `xml:"opds:facetGroup,attr,omitempty"`
	ActiveFacet bool   `xml:"opds:activeFacet,attr,omitempty"`
}

Link represents an Atom link element.

type OpenSearchDescription 

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"`
	URLs           []OpenSearchURL `xml:"Url"`
}

OpenSearchDescription represents an OpenSearch description document.

func NewOpenSearchDescription 

func NewOpenSearchDescription(shortName, description, searchTemplate string) *OpenSearchDescription

NewOpenSearchDescription creates a new OpenSearch description.

type OpenSearchURL 

type OpenSearchURL struct {
	Type     string `xml:"type,attr"`
	Template string `xml:"template,attr"`
}

OpenSearchURL represents an OpenSearch URL template.

type PaginationQuery 

type PaginationQuery struct {
	Limit  int `query:"limit"`
	Offset int `query:"offset"`
}

PaginationQuery represents pagination query parameters.

type SearchQuery 

type SearchQuery struct {
	Q      string `query:"q"`
	Limit  int    `query:"limit"`
	Offset int    `query:"offset"`
}

SearchQuery represents search query parameters.

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service handles OPDS feed generation.

func NewService 

func NewService(db *bun.DB) *Service

NewService creates a new OPDS service.

func (*Service) BuildCatalogFeed 

func (svc *Service) BuildCatalogFeed(ctx context.Context, baseURL, fileTypes string, libraryIDs []int) (*Feed, error)

BuildCatalogFeed builds the root navigation feed listing all libraries. If libraryIDs is non-nil, only libraries with those IDs are included.

func (*Service) BuildLibraryAllBooksFeed 

func (svc *Service) BuildLibraryAllBooksFeed(ctx context.Context, baseURL, fileTypes string, libraryID, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibraryAllBooksFeed builds an acquisition feed with all books in a library.

func (*Service) BuildLibraryAllBooksFeedKepub 

func (svc *Service) BuildLibraryAllBooksFeedKepub(ctx context.Context, baseURL, fileTypes string, libraryID, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibraryAllBooksFeedKepub builds an acquisition feed with all books using KePub download links.

func (*Service) BuildLibraryAuthorBooksFeed 

func (svc *Service) BuildLibraryAuthorBooksFeed(ctx context.Context, baseURL, fileTypes string, libraryID int, authorName string, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibraryAuthorBooksFeed builds an acquisition feed with books by an author.

func (*Service) BuildLibraryAuthorBooksFeedKepub 

func (svc *Service) BuildLibraryAuthorBooksFeedKepub(ctx context.Context, baseURL, fileTypes string, libraryID int, authorName string, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibraryAuthorBooksFeedKepub builds an acquisition feed with books by an author using KePub download links.

func (*Service) BuildLibraryAuthorsListFeed 

func (svc *Service) BuildLibraryAuthorsListFeed(ctx context.Context, baseURL, fileTypes string, libraryID, limit, offset int) (*Feed, error)

BuildLibraryAuthorsListFeed builds a navigation feed listing all authors in a library.

func (*Service) BuildLibraryCatalogFeed 

func (svc *Service) BuildLibraryCatalogFeed(ctx context.Context, baseURL, fileTypes string, libraryID int) (*Feed, error)

BuildLibraryCatalogFeed builds a navigation feed for a specific library.

func (*Service) BuildLibraryOpenSearchDescription 

func (svc *Service) BuildLibraryOpenSearchDescription(baseURL, fileTypes string, libraryID int) *OpenSearchDescription

BuildLibraryOpenSearchDescription builds an OpenSearch description for a library.

func (*Service) BuildLibrarySearchFeed 

func (svc *Service) BuildLibrarySearchFeed(ctx context.Context, baseURL, fileTypes string, libraryID int, query string, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibrarySearchFeed builds an acquisition feed with search results.

func (*Service) BuildLibrarySearchFeedKepub 

func (svc *Service) BuildLibrarySearchFeedKepub(ctx context.Context, baseURL, fileTypes string, libraryID int, query string, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibrarySearchFeedKepub builds an acquisition feed with search results using KePub download links.

func (*Service) BuildLibrarySeriesBooksFeed 

func (svc *Service) BuildLibrarySeriesBooksFeed(ctx context.Context, baseURL, fileTypes string, libraryID, seriesID, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibrarySeriesBooksFeed builds an acquisition feed with books in a series.

func (*Service) BuildLibrarySeriesBooksFeedKepub 

func (svc *Service) BuildLibrarySeriesBooksFeedKepub(ctx context.Context, baseURL, fileTypes string, libraryID, seriesID, limit, offset int, sort []sortspec.SortLevel) (*Feed, error)

BuildLibrarySeriesBooksFeedKepub builds an acquisition feed with books in a series using KePub download links.

func (*Service) BuildLibrarySeriesListFeed 

func (svc *Service) BuildLibrarySeriesListFeed(ctx context.Context, baseURL, fileTypes string, libraryID, limit, offset int) (*Feed, error)

BuildLibrarySeriesListFeed builds a navigation feed listing all series in a library.

func (*Service) ListAuthorsInLibrary 

func (svc *Service) ListAuthorsInLibrary(ctx context.Context, libraryID, limit, offset int) ([]AuthorInfo, int, error)

ListAuthorsInLibrary lists distinct authors in a library with book counts.

func (*Service) ListBooksByAuthor 

func (svc *Service) ListBooksByAuthor(ctx context.Context, libraryID int, authorName string, fileTypes []string, limit, offset int, sort []sortspec.SortLevel) ([]*models.Book, int, error)

ListBooksByAuthor lists books by a specific author in a library.

Implementation note: the original version queried for unsorted book IDs, paginated those IDs in Go, then fetched the entire library's books with sort applied and filtered down to the paginated IDs. That pattern broke pagination (page 1 wasn't "first N in sort order") and scaled poorly. We now look up the person row (library-scoped via peopleService.RetrievePerson) and delegate to the books service's PersonID filter, which lets SQL apply the sort, limit, and offset together.

Name-match semantics change: the old implementation used `p.name = ?` (case-sensitive under SQLite's default BINARY collation), whereas peopleService.RetrievePerson uses `LOWER(p.name) = LOWER(?)`. This aligns with the creation-side invariant — `persons` has a UNIQUE index on (name COLLATE NOCASE, library_id), so there's at most one person per (library, name) regardless of case, and the canonical casing is whatever was first inserted. Any author URL Shisho generates itself is already canonical; the change only affects OPDS clients that hand-craft URLs with non-canonical casing — those now resolve instead of 404ing.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.