Guided navigation EPUB implementation (#100)

Author: chocolatkey

.github/workflows/build.yml

@@ -16,7 +16,8 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v5
       with:
-        go-version: '>=1.22.0'
+        go-version: '>=1.23.0'
+        cache: false
 
     - name: Build
       run: go build -v ./...

.github/workflows/release.yml

@@ -24,7 +24,8 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '>=1.22.0'
+          go-version: '>=1.23.0'
+          cache: false
       - name: Build release
         uses: goreleaser/goreleaser-action@v5
         with:

cmd/rwp/cmd/serve/api.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"slices"
 	"strconv"
 	"strings"
 	"syscall"
@@ -196,9 +197,15 @@ func (s *Server) getAsset(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusNotFound)
 		return
 	}
+	finalLink := *link
+
+	// Expand templated links to include URL query parameters
+	if finalLink.Templated {
+		finalLink = finalLink.ExpandTemplate(convertURLValuesToMap(r.URL.Query()))
+	}
 
 	// Get the asset from the publication
-	res := publication.Get(*link)
+	res := publication.Get(finalLink)
 	defer res.Close()
 
 	// Get asset length in bytes
@@ -214,6 +221,9 @@ func (s *Server) getAsset(w http.ResponseWriter, r *http.Request) {
 	if sub, ok := mimeSubstitutions[contentType]; ok {
 		contentType = sub
 	}
+	if slices.Contains(utfCharsetNeeded, contentType) {
+		contentType += "; charset=utf-8"
+	}
 	w.Header().Set("content-type", contentType)
 	w.Header().Set("cache-control", "private, max-age=86400, immutable")
 	w.Header().Set("content-length", strconv.FormatInt(l, 10))

cmd/rwp/cmd/serve/helpers.go

@@ -2,14 +2,24 @@ package serve
 
 import (
 	"net/http"
+	"net/url"
 	"strings"
 
 	"github.com/readium/go-toolkit/pkg/manifest"
+	"github.com/readium/go-toolkit/pkg/mediatype"
 )
 
 var mimeSubstitutions = map[string]string{
-	"application/vnd.ms-opentype":          "font/otf",                                            // Not just because it's sane, but because CF will compress it!
-	"application/vnd.readium.content+json": "application/vnd.readium.content+json; charset=utf-8", // Need utf-8 encoding
+	"application/vnd.ms-opentype": "font/otf", // Not just because it's sane, but because CF will compress it!
+}
+
+var utfCharsetNeeded = []string{
+	mediatype.ReadiumWebpubManifest.String(),
+	mediatype.ReadiumDivinaManifest.String(),
+	mediatype.ReadiumAudiobookManifest.String(),
+	mediatype.ReadiumPositionList.String(),
+	mediatype.ReadiumContentDocument.String(),
+	mediatype.ReadiumGuidedNavigationDocument.String(),
 }
 
 var compressableMimes = []string{
@@ -19,11 +29,11 @@ var compressableMimes = []string{
 	"text/css",
 	"text/html",
 	"application/xhtml+xml",
-	"application/webpub+json",
-	"application/divina+json",
-	"application/vnd.readium.position-list+json",
-	"application/vnd.readium.content+json",
-	"application/audiobook+json",
+	mediatype.ReadiumWebpubManifest.String(),
+	mediatype.ReadiumDivinaManifest.String(),
+	mediatype.ReadiumPositionList.String(),
+	mediatype.ReadiumContentDocument.String(),
+	mediatype.ReadiumAudiobookManifest.String(),
 	"font/ttf",
 	"application/ttf",
 	"application/x-ttf",
@@ -50,12 +60,12 @@ func makeRelative(link manifest.Link) manifest.Link {
 }
 
 func conformsToAsMimetype(conformsTo manifest.Profiles) string {
-	mime := "application/webpub+json"
+	mime := mediatype.ReadiumWebpubManifest.String()
 	for _, profile := range conformsTo {
 		if profile == manifest.ProfileDivina {
-			mime = "application/divina+json"
+			mime = mediatype.ReadiumDivinaManifest.String()
 		} else if profile == manifest.ProfileAudiobook {
-			mime = "application/audiobook+json"
+			mime = mediatype.ReadiumAudiobookManifest.String()
 		} else {
 			continue
 		}
@@ -88,3 +98,13 @@ func parseCoding(s string) (coding string) {
 	coding = strings.ToLower(strings.TrimSpace(s[:p]))
 	return
 }
+
+func convertURLValuesToMap(values url.Values) map[string]string {
+	result := make(map[string]string)
+	for key, val := range values {
+		if len(val) > 0 {
+			result[key] = val[0] // Take the first value for each key
+		}
+	}
+	return result
+}

pkg/manifest/guided_navigation.go

@@ -0,0 +1,23 @@
+package manifest
+
+// Readium Guided Navigation Document
+// https://readium.org/guided-navigation/schema/document.schema.json
+type GuidedNavigationDocument struct {
+	Links  []Link                   `json:"links,omitempty"` // References to other resources that are related to the current Guided Navigation Document.
+	Guided []GuidedNavigationObject `json:"guided"`          // A sequence of resources and/or media fragments into these resources, meant to be presented sequentially to the user.
+}
+
+// Readium Guided Navigation Object
+// https://readium.org/guided-navigation/schema/object.schema.json
+// TODO: Role should be typed
+type GuidedNavigationObject struct {
+	AudioRef string                   `json:"audioref,omitempty"` // References an audio resource or a fragment of it.
+	ImgRef   string                   `json:"imgref,omitempty"`   // References an image or a fragment of it.
+	TextRef  string                   `json:"textref,omitempty"`  // References a textual resource or a fragment of it.
+	Text     string                   `json:"text,omitempty"`     // Textual equivalent of the resources or fragment of the resources referenced by the current Guided Navigation Object.
+	Role     []string                 `json:"role,omitempty"`     // Convey the structural semantics of a publication
+	Children []GuidedNavigationObject `json:"children,omitempty"` // Items that are children of the containing Guided Navigation Object.
+}
+
+// TODO: functions for objects to get e.g. audio time, audio file, text file, fragment id, audio "clip", image xywh, etc.
+// This will come after the URL utility revamp to avoid implementation twice

pkg/manifest/link.go

@@ -229,6 +229,12 @@ type LinkList []Link
 // Returns the first [Link] with the given [href], or null if not found.
 func (ll LinkList) IndexOfFirstWithHref(href string) int {
 	for i, link := range ll {
+		if link.Templated {
+			if strings.TrimPrefix(link.ExpandTemplate(nil).Href, "/") == href {
+				// TODO: remove trimming when href utils are updated
+				return i
+			}
+		}
 		if link.Href == href {
 			return i
 		}
@@ -244,6 +250,12 @@ func (ll LinkList) IndexOfFirstWithHref(href string) int {
 // Finds the first link matching the given HREF.
 func (ll LinkList) FirstWithHref(href string) *Link {
 	for _, link := range ll {
+		if link.Templated {
+			if strings.TrimPrefix(link.ExpandTemplate(nil).Href, "/") == href {
+				// TODO: remove trimming when href utils are updated
+				return &link
+			}
+		}
 		if link.Href == href {
 			return &link
 		}

pkg/manifest/media_overlay.go

@@ -0,0 +1,7 @@
+package manifest
+
+// EPUB profile extension for WebPub Manifest for media overlay features.
+type MediaOverlay struct {
+	ActiveClass         string `json:"activeClass,omitempty"`         // Author-defined CSS class name to apply to the currently-playing EPUB Content Document element.
+	PlaybackActiveClass string `json:"playbackActiveClass,omitempty"` // Author-defined CSS class name to apply to the EPUB Content Document's document element when playback is active.
+}

pkg/manifest/metadata.go

@@ -5,6 +5,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/go-viper/mapstructure/v2"
 	"github.com/pkg/errors"
 	"github.com/readium/go-toolkit/pkg/internal/util"
 )
@@ -52,8 +53,9 @@ type Metadata struct {
 	NumberOfPages      *uint                  `json:"numberOfPages,omitempty"`
 	BelongsTo          map[string]Collections `json:"belongsTo,omitempty"`
 	Presentation       *Presentation          `json:"presentation,omitempty"`
+	MediaOverlay       *MediaOverlay          `json:"mediaOverlay,omitempty"`
 
-	OtherMetadata map[string]interface{} `json:"-"` // Extension point for other metadata. TODO implement
+	OtherMetadata map[string]interface{} `json:"-"` // Extension point for other metadata.
 }
 
 func (m Metadata) Title() string {
@@ -351,7 +353,31 @@ func MetadataFromJSON(rawJson map[string]interface{}, normalizeHref LinkHrefNorm
 	}
 
 	// Presentation
-	// TODO custom presentation unmarshalling
+	if presentation, ok := rawJson["presentation"].(map[string]interface{}); ok {
+		metadata.Presentation = &Presentation{}
+
+		decoder, _ := mapstructure.NewDecoder(&mapstructure.DecoderConfig{
+			TagName: "json",
+			Result:  metadata.Presentation,
+		})
+		if err := decoder.Decode(presentation); err != nil {
+			return nil, errors.Wrap(err, "failed parsing 'presentation'")
+		}
+		metadata.Presentation.setDefaults()
+	}
+
+	// Media Overlay
+	if mediaOverlay, ok := rawJson["mediaOverlay"].(map[string]interface{}); ok {
+		metadata.MediaOverlay = &MediaOverlay{}
+
+		decoder, _ := mapstructure.NewDecoder(&mapstructure.DecoderConfig{
+			TagName: "json",
+			Result:  metadata.MediaOverlay,
+		})
+		if err := decoder.Decode(mediaOverlay); err != nil {
+			return nil, errors.Wrap(err, "failed parsing 'mediaOverlay'")
+		}
+	}
 
 	// Delete above vals so that we can put everything else in OtherMetadata
 	for _, v := range []string{
@@ -378,6 +404,7 @@ func MetadataFromJSON(rawJson map[string]interface{}, normalizeHref LinkHrefNorm
 		"numberOfPages",
 		"penciler",
 		"presentation",
+		"mediaOverlay",
 		"published",
 		"publisher",
 		"readingProgression",
@@ -423,6 +450,9 @@ func (m Metadata) MarshalJSON() ([]byte, error) {
 	if m.Presentation != nil {
 		j["presentation"] = m.Presentation
 	}
+	if m.MediaOverlay != nil {
+		j["mediaOverlay"] = m.MediaOverlay
+	}
 
 	if m.Identifier != "" {
 		j["identifier"] = m.Identifier

pkg/mediatype/mediatype.go

@@ -14,8 +14,8 @@ import (
 
 // MediaType represents a document format, identified by a unique RFC 6838 media type.
 // [MediaType] handles:
-//  - components parsing – eg. type, subtype and parameters,
-//  - media types comparison.
+//   - components parsing – eg. type, subtype and parameters,
+//   - media types comparison.
 //
 // Comparing media types is more complicated than it looks, since they can contain parameters,
 // such as `charset=utf-8`. We can't ignore them because some formats use parameters in their
@@ -287,13 +287,13 @@ func (mt MediaType) IsVideo() bool {
 
 // Returns whether this media type is of a Readium Web Publication Manifest.
 func (mt MediaType) IsRwpm() bool {
-	return mt.Matches(&ReadiumAudiobookManifest, &DivinaManifest, &ReadiumWebpubManifest)
+	return mt.Matches(&ReadiumAudiobookManifest, &ReadiumDivinaManifest, &ReadiumWebpubManifest)
 }
 
 // Returns whether this media type is of a publication file.
 func (mt MediaType) IsPublication() bool {
 	return mt.Matches(
-		&ReadiumAudiobook, &ReadiumAudiobookManifest, &CBZ, &Divina, &DivinaManifest, &EPUB, &LCPProtectedAudiobook,
+		&ReadiumAudiobook, &ReadiumAudiobookManifest, &CBZ, &ReadiumDivina, &ReadiumDivinaManifest, &EPUB, &LCPProtectedAudiobook,
 		&LCPProtectedPDF, &LPF, &PDF, &W3CWPUBManifest, &ReadiumWebpub, &ReadiumWebpubManifest, &ZAB,
 	)
 }

pkg/mediatype/sniffer.go

@@ -184,10 +184,10 @@ func SniffWebpub(context SnifferContext) *MediaType {
 	}
 
 	if context.HasFileExtension("divina") || context.HasMediaType("application/divina+zip") {
-		return &Divina
+		return &ReadiumDivina
 	}
 	if context.HasMediaType("application/divina+json") {
-		return &DivinaManifest
+		return &ReadiumDivinaManifest
 	}
 
 	if context.HasFileExtension("webpub") || context.HasMediaType("application/webpub+zip") {
@@ -281,8 +281,12 @@ func SniffLPF(context SnifferContext) *MediaType {
 // Authorized extensions for resources in a CBZ archive.
 // Reference: https://wiki.mobileread.com/wiki/CBR_and_CBZ
 var cbz_extensions = map[string]struct{}{
-	"bmp": {}, "dib": {}, "gif": {}, "jif": {}, "jfi": {}, "jfif": {}, "jpg": {}, "jpeg": {}, "png": {}, "tif": {}, "tiff": {}, "webp": {}, // Bitmap. Note there's no AVIF or JXL
-	"acbf": {}, "xml": {}, "txt": {}, // Metadata
+	// Bitmaps
+	"bmp": {}, "dib": {}, "gif": {}, "jif": {}, "jfi": {}, "jfif": {}, "jpg": {},
+	"jpeg": {}, "png": {}, "tif": {}, "tiff": {}, "webp": {}, "avif": {}, "jxl": {},
+
+	// Metadata
+	"acbf": {}, "xml": {}, "txt": {},
 }
 
 // Authorized extensions for resources in a ZAB archive (Zipped Audio Book).

pkg/mediatype/sniffer_test.go

@@ -124,14 +124,14 @@ func TestSniffCBZ(t *testing.T) {
 }
 
 func TestSniffDiViNa(t *testing.T) {
-	assert.Equal(t, &Divina, OfExtension("divina"))
-	assert.Equal(t, &Divina, OfString("application/divina+zip"))
+	assert.Equal(t, &ReadiumDivina, OfExtension("divina"))
+	assert.Equal(t, &ReadiumDivina, OfString("application/divina+zip"))
 	// TODO needs webpub heavy parsing. See func SniffWebpub in sniffer.go for details.
 	// assert.Equal(t, &DIVINA, OfFileOnly("divina-package.unknown"))
 }
 
 func TestSniffDiViNaManifest(t *testing.T) {
-	assert.Equal(t, &DivinaManifest, OfString("application/divina+json"))
+	assert.Equal(t, &ReadiumDivinaManifest, OfString("application/divina+json"))
 	// TODO needs webpub heavy parsing. See func SniffWebpub in sniffer.go for details.
 	// assert.Equal(t, &DIVINA_MANIFEST, OfFileOnly("divina.json"))
 }