Remote manifest items support

[vers-one]

Description

EPUB 3 standard supports remote manifest items and metadata links (i.e. files referenced by absolute URLs like http://example.com/book/123/font.ttf as opposed to local files like Content/font.ttf which are packaged within the EPUB file). EpubReader doesn't support remote manifest items and treats all absolute URLs as file names within the EPUB file.

Most of EPUB books don't contain references to remote resources.

Proposed solution

1. Replace the implementation of the EpubContentFile / EpubContentFileRef classes and the classes derived from them with the following class hierarchy:

   EpubContentFile
   |-EpubLocalContentFile
   | |-EpubLocalTextContentFile
   | |-EpubLocalByteContentFile
   |-EpubRemoteContentFile
   | |-EpubRemoteTextContentFile
   | |-EpubRemoteByteContentFile
   
   EpubContentFileRef
   |-EpubLocalContentFileRef
   | |-EpubLocalTextContentFileRef
   | |-EpubLocalByteContentFileRef
   |-EpubRemoteContentFileRef
   | |-EpubRemoteTextContentFileRef
   | |-EpubRemoteByteContentFileRef
   

2. Add ContentLocation property to the base classes with the following type: enum EpubContentLocation { LOCAL, REMOTE }.

3. Add ContentFileType property to the base classes with the following type: enum EpubContentFileType { TEXT, BYTE_ARRAY }.

4. Implement EpubContentCollection and EpubContentCollectionRef classes with two properties: Local and Remote which contain local and remote files / file references respectively. Use these classes for Html, Css, Images, Fonts, and AllFiles properties in the EpubContent / EpubContentRef classes.

5. Implement content downloader for remote content files.

6. Add ContentDownloaderOptions class to enable / disable downloading remote content and to let the application to supply its own content downloader.

7. Extract the code to load local content and download remote content out of the EpubContentFileRef class into two separate classes: EpubLocalContentLoader and EpubRemoteContentLoader. Pass the reference to the content loader through the constructor parameter in the EpubContentFileRef class.

8. Even though EPUB specification restricts types of remote resources to just audio, video, and font files, it would be better to relax this restriction in the EpubReader to allow all types of files to be remote resources to make the overall design simpler for the consumer of the library. However, EpubReader should still check that all HTML files in the EPUB spine, as well as the cover image and the EPUB 2 NCX / EPUB 3 navigation documents are local resources since these files are essential for constructing the parsed EPUB schema of the book.

Breaking changes

This solution introduces a breaking change: application will have to replace book.Content.<property> (where <property> is one of the following properties: Html, Css, Images, Fonts, or AllFiles) with book.Content.<property>.Local (unless application needs to handle remote items too).

Additionally, if application stores references to content files, then the following type replacement will be required:

• EpubContentFile → EpubLocalContentFile
• EpubTextContentFile → EpubLocalTextContentFile
• EpubByteContentFile → EpubLocalByteContentFile
• EpubContentFileRef → EpubLocalContentFileRef
• EpubTextContentFileRef → EpubLocalTextContentFileRef
• EpubByteContentFileRef → EpubLocalByteContentFileRef

Additional context

• href attribute in the EPUB 3 specification: https://www.w3.org/publishing/epub32/epub-packages.html#attrdef-href
• File type restrictions for the remote content: https://www.w3.org/publishing/epub32/epub-spec.html#sec-resource-locations