Content reader options to handle missing files

vers-one · vers-one · commit 4cf06c6768d3 · 2022-08-26T14:38:41.000-04:00
diff --git a/Documentation/malformed-epub/index.md b/Documentation/malformed-epub/index.md
@@ -34,6 +34,63 @@ EpubReaderOptions options = new()
 };
 ```
 
+## Missing content files
+
+The [`item` element](https://www.w3.org/publishing/epub32/epub-packages.html#sec-item-elem) within the EPUB manifest has a required `href` attribute which points to a content file in the EPUB archive. There are [some EPUB books](https://github.com/vers-one/EpubReader/issues/25) that declare content files in the EPUB manifest which do not exist in the actual EPUB archive. This causes EpubReader to throw the *"EPUB parsing error: file ... was not found in the EPUB file"* exception. Such exception is thrown immediately, if application uses [`EpubReader.ReadBook`](xref:VersOne.Epub.EpubReader#VersOne_Epub_EpubReader_ReadBook_System_IO_Stream_VersOne_Epub_Options_EpubReaderOptions_) / [`EpubReader.ReadBookAsync`](xref:VersOne.Epub.EpubReader#VersOne_Epub_EpubReader_ReadBookAsync_System_IO_Stream_VersOne_Epub_Options_EpubReaderOptions_) methods because they try to load the whole content of the book into memory. [`EpubReader.OpenBook`](xref:VersOne.Epub.EpubReader#VersOne_Epub_EpubReader_OpenBook_System_IO_Stream_VersOne_Epub_Options_EpubReaderOptions_) and [`EpubReader.OpenBookAsync`](xref:VersOne.Epub.EpubReader#VersOne_Epub_EpubReader_OpenBookAsync_System_IO_Stream_VersOne_Epub_Options_EpubReaderOptions_) methods don't load the content, so the exception will be thrown only during an attempt to call any of those methods for a missing file:
+* [`EpubContentFileRef`](xref:VersOne.Epub.EpubContentFileRef) class:
+  * [`GetContentStream`](xref:VersOne.Epub.EpubContentFileRef#VersOne_Epub_EpubContentFileRef_GetContentStream)
+  * [`ReadContentAsBytes`](xref:VersOne.Epub.EpubContentFileRef#VersOne_Epub_EpubContentFileRef_ReadContentAsBytes)
+  * [`ReadContentAsBytesAsync`](xref:VersOne.Epub.EpubContentFileRef#VersOne_Epub_EpubContentFileRef_ReadContentAsBytesAsync)
+  * [`ReadContentAsText`](xref:VersOne.Epub.EpubContentFileRef#VersOne_Epub_EpubContentFileRef_ReadContentAsText)
+  * [`ReadContentAsTextAsync`](xref:VersOne.Epub.EpubContentFileRef#VersOne_Epub_EpubContentFileRef_ReadContentAsTextAsync)
+* [`EpubByteContentFileRef`](xref:VersOne.Epub.EpubByteContentFileRef) class:
+  * [`ReadContent`](xref:VersOne.Epub.EpubByteContentFileRef#VersOne_Epub_EpubByteContentFileRef_ReadContent)
+  * [`ReadContentAsync`](xref:VersOne.Epub.EpubByteContentFileRef#VersOne_Epub_EpubByteContentFileRef_ReadContentAsync)
+* [`EpubTextContentFileRef`](xref:VersOne.Epub.EpubTextContentFileRef) class:
+  * [`ReadContent`](xref:VersOne.Epub.EpubTextContentFileRef#VersOne_Epub_EpubTextContentFileRef_ReadContent)
+  * [`ReadContentAsync`](xref:VersOne.Epub.EpubTextContentFileRef#VersOne_Epub_EpubTextContentFileRef_ReadContentAsync)
+
+[`ContentReaderOptions.ContentFileMissing`](xref:VersOne.Epub.Options.ContentReaderOptions#VersOne_Epub_Options_ContentReaderOptions_ContentFileMissing) event can be used to detect those issues and to instruct EpubReader how to handle missing content files. Application can choose one of the following options:
+
+### 1. Get notified about missing content files
+
+```csharp
+EpubReaderOptions options = new();
+options.ContentReaderOptions.ContentFileMissing += (sender, e) =>
+{
+    Console.WriteLine($"Content file is missing: content file name = '{e.FileName}', content file path in the EPUB archive = '{e.FilePathInEpubArchive}', content type = {e.ContentType}, MIME type = {e.ContentMimeType}.");
+};
+```
+
+This will let application to be notified about the missing content file but will not prevent the exception from being thrown by the EpubReader.
+
+### 2. Suppress exceptions
+
+```csharp
+EpubReaderOptions options = new();
+options.ContentReaderOptions.ContentFileMissing += (sender, e) =>
+{
+    e.SuppressException = true;
+};
+```
+
+This will suppress all missing content file exceptions from being thrown. The EpubReader will treat missing content files as existing but empty files.
+
+### 3. Provide a replacement content
+
+```csharp
+EpubReaderOptions options = new();
+options.ContentReaderOptions.ContentFileMissing += (sender, e) =>
+{
+    if (e.FileName == "chapter1.html")
+    {
+        e.ReplacementContentStream = new FileStream(@"C:\Temp\chapter1-replacement.html", FileMode.Open);
+    }
+};
+```
+
+This will let application to substitute the content of a missing file with another content. The value of the [`ReplacementContentStream`](xref:VersOne.Epub.Options.ContentFileMissingEventArgs#VersOne_Epub_Options_ContentFileMissingEventArgs_ReplacementContentStream) property can be any [`Stream`](xref:System.IO.Stream). The content of the stream is read only once, after which it will be cached in the EPUB content reader. The stream will be closed after its content is fully read.
+
 ## Missing content attribute for EPUB 2 NCX navigation points
 
 The `navPoint` element within the [EPUB 2 NCX navigation document](https://daisy.org/activities/standards/daisy/daisy-3/z39-86-2005-r2012-specifications-for-the-digital-talking-book/#NCX) must contain a nested `content` element pointing to a content file associated with this navigation item. There are some EPUB 2 books that have navigation points without a nested `content` element which causes EpubReader to throw the *"EPUB parsing error: navigation point X should contain content"* exception.
diff --git a/Documentation/templates/default/partials/class.tmpl.partial b/Documentation/templates/default/partials/class.tmpl.partial
@@ -101,21 +101,7 @@
 <h5 class="propertyValue">Property type: {{{type.specName.0.value}}}</h5>
 {{/propertyValue}}
 {{#eventType}}
-<h5 class="eventType">{{__global.eventType}}</h5>
-<table class="table table-bordered table-striped table-condensed">
-  <thead>
-    <tr>
-      <th>{{__global.type}}</th>
-      <th>{{__global.description}}</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>{{{type.specName.0.value}}}</td>
-      <td>{{{description}}}</td>
-    </tr>
-  </tbody>
-</table>
+<h5 class="eventType">Event type: {{{type.specName.0.value}}}</h5>
 {{/eventType}}
 {{/syntax}}
 {{#overridden}}
diff --git a/Source/VersOne.Epub.WpfDemo/Models/BookModel.cs b/Source/VersOne.Epub.WpfDemo/Models/BookModel.cs
@@ -1,6 +1,7 @@
 ﻿using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
+using VersOne.Epub.Options;
 using VersOne.Epub.WpfDemo.Entities;
 using VersOne.Epub.WpfDemo.ViewModels;
 
@@ -17,7 +18,12 @@ public BookModel()
 
         public async Task<EpubBook> OpenBookAsync(int bookId)
         {
-            EpubBook epubBook = await EpubReader.ReadBookAsync(settings.Books.First(book => book.Id == bookId).FilePath);
+            EpubReaderOptions epubReaderOptions = new EpubReaderOptions();
+            epubReaderOptions.ContentReaderOptions.ContentFileMissing += (sender, e) =>
+            {
+                e.SuppressException = true;
+            };
+            EpubBook epubBook = await EpubReader.ReadBookAsync(settings.Books.First(book => book.Id == bookId).FilePath, epubReaderOptions);
             return epubBook;
         }
 
diff --git a/Source/VersOne.Epub/Environment/Implementation/ZipFile.cs b/Source/VersOne.Epub/Environment/Implementation/ZipFile.cs
@@ -20,7 +20,8 @@ public ZipFile(ZipArchive zipArchive)
 
         public IZipFileEntry GetEntry(string entryName)
         {
-            return new ZipFileEntry(zipArchive.GetEntry(entryName));
+            ZipArchiveEntry zipArchiveEntry = zipArchive.GetEntry(entryName);
+            return zipArchiveEntry != null ? new ZipFileEntry(zipArchiveEntry) : null;
         }
 
         public void Dispose()
diff --git a/Source/VersOne.Epub/EpubReader.cs b/Source/VersOne.Epub/EpubReader.cs
@@ -114,16 +114,20 @@ public static async Task<EpubBook> ReadBookAsync(Stream stream, EpubReaderOption
         private static async Task<EpubBookRef> OpenBookAsync(IZipFile zipFile, string filePath, EpubReaderOptions epubReaderOptions)
         {
             EpubBookRef result = null;
+            if (epubReaderOptions == null)
+            {
+                epubReaderOptions = new EpubReaderOptions();
+            }
             try
             {
                 result = new EpubBookRef(zipFile);
                 result.FilePath = filePath;
-                result.Schema = await SchemaReader.ReadSchemaAsync(zipFile, epubReaderOptions ?? new EpubReaderOptions()).ConfigureAwait(false);
+                result.Schema = await SchemaReader.ReadSchemaAsync(zipFile, epubReaderOptions).ConfigureAwait(false);
                 result.Title = result.Schema.Package.Metadata.Titles.FirstOrDefault() ?? String.Empty;
                 result.AuthorList = result.Schema.Package.Metadata.Creators.Select(creator => creator.Creator).ToList();
                 result.Author = String.Join(", ", result.AuthorList);
                 result.Description = result.Schema.Package.Metadata.Description;
-                result.Content = await Task.Run(() => ContentReader.ParseContentMap(result)).ConfigureAwait(false);
+                result.Content = await Task.Run(() => ContentReader.ParseContentMap(result, epubReaderOptions.ContentReaderOptions)).ConfigureAwait(false);
                 return result;
             }
             catch
diff --git a/Source/VersOne.Epub/Options/ContentFileMissingEventArgs.cs b/Source/VersOne.Epub/Options/ContentFileMissingEventArgs.cs
@@ -0,0 +1,64 @@
+﻿using System;
+using System.IO;
+
+namespace VersOne.Epub.Options
+{
+    /// <summary>
+    /// Provides data for the <see cref="ContentReaderOptions.ContentFileMissing" /> event.
+    /// </summary>
+    public class ContentFileMissingEventArgs : EventArgs
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ContentFileMissingEventArgs" /> class with a specified file name, an absolute file path, a content type of the file,
+        /// and a MIME type of the file's content.
+        /// </summary>
+        /// <param name="fileName">Relative file path of the missing content file (as it is specified in the EPUB manifest).</param>
+        /// <param name="filePathInEpubArchive">Absolute file path of the missing content file in the EPUB archive.</param>
+        /// <param name="contentType">The type of the content of the missing file.</param>
+        /// <param name="contentMimeType">The MIME type of the content of the missing file.</param>
+        public ContentFileMissingEventArgs(string fileName, string filePathInEpubArchive, EpubContentType contentType, string contentMimeType)
+        {
+            FileName = fileName;
+            FilePathInEpubArchive = filePathInEpubArchive;
+            ContentType = contentType;
+            ContentMimeType = contentMimeType;
+            SuppressException = false;
+        }
+
+        /// <summary>
+        /// Gets the relative file path of the missing content file (as it is specified in the EPUB manifest).
+        /// </summary>
+        public string FileName { get; }
+
+        /// <summary>
+        /// Gets the absolute file path of the missing content file in the EPUB archive.
+        /// </summary>
+        public string FilePathInEpubArchive { get; }
+
+        /// <summary>
+        /// Gets the type of the content of the missing file.
+        /// </summary>
+        public EpubContentType ContentType { get; }
+
+        /// <summary>
+        /// Gets the MIME type of the content of the missing file.
+        /// </summary>
+        public string ContentMimeType { get; }
+
+        /// <summary>
+        /// Gets or sets a value indicating whether the EPUB content reader should suppress the exception for the missing file. If it is set to <c>true</c>
+        /// and the replacement content stream is not provided (via the <see cref="ReplacementContentStream" /> property), then the EPUB content reader will treat
+        /// the missing file as an existing but empty file.
+        /// Default value is <c>false</c>.
+        /// </summary>
+        public bool SuppressException { get; set; }
+
+        /// <summary>
+        /// Gets or sets the replacement content stream. This property allows the application to provide a replacement content for the missing file in the form of
+        /// a <see cref="Stream" />. When the content stream is provided, the EPUB content reader will not throw an exception for the missing file,
+        /// regardless of the value of the <see cref="SuppressException" /> property. The content of the stream is read only once, after which it will be cached
+        /// in the EPUB content reader. The stream will be closed after its content is fully read.
+        /// </summary>
+        public Stream ReplacementContentStream { get; set; }
+    }
+}
diff --git a/Source/VersOne.Epub/Options/ContentReaderOptions.cs b/Source/VersOne.Epub/Options/ContentReaderOptions.cs
@@ -0,0 +1,21 @@
+﻿using System;
+
+namespace VersOne.Epub.Options
+{
+    /// <summary>
+    /// Various options to configure the behavior of the EPUB content reader.
+    /// </summary>
+    public class ContentReaderOptions
+    {
+        /// <summary>
+        /// Occurs when a content file is listed in the EPUB manifest but the content reader is unable to find it in the EPUB archive.
+        /// This event lets the application to be notified of such errors and to decide how EPUB content reader should handle the missing file.
+        /// </summary>
+        public event EventHandler<ContentFileMissingEventArgs> ContentFileMissing;
+
+        internal void RaiseContentFileMissingEvent(ContentFileMissingEventArgs contentFileMissingEventArgs)
+        {
+            ContentFileMissing?.Invoke(this, contentFileMissingEventArgs);
+        }
+    }
+}
diff --git a/Source/VersOne.Epub/Options/EpubReaderOptions.cs b/Source/VersOne.Epub/Options/EpubReaderOptions.cs
@@ -11,6 +11,7 @@ public class EpubReaderOptions
         public EpubReaderOptions()
         {
             PackageReaderOptions = new PackageReaderOptions();
+            ContentReaderOptions = new ContentReaderOptions();
             Epub2NcxReaderOptions = new Epub2NcxReaderOptions();
             XmlReaderOptions = new XmlReaderOptions();
         }
@@ -20,6 +21,11 @@ public EpubReaderOptions()
         /// </summary>
         public PackageReaderOptions PackageReaderOptions { get; set; }
 
+        /// <summary>
+        /// Gets or sets EPUB content reader options.
+        /// </summary>
+        public ContentReaderOptions ContentReaderOptions { get; set; }
+
         /// <summary>
         /// Gets or sets EPUB 2 NCX navigation document reader options.
         /// </summary>
diff --git a/Source/VersOne.Epub/Readers/ContentReader.cs b/Source/VersOne.Epub/Readers/ContentReader.cs
@@ -1,11 +1,12 @@
 ﻿using System.Collections.Generic;
+using VersOne.Epub.Options;
 using VersOne.Epub.Schema;
 
 namespace VersOne.Epub.Internal
 {
     internal static class ContentReader
     {
-        public static EpubContentRef ParseContentMap(EpubBookRef bookRef)
+        public static EpubContentRef ParseContentMap(EpubBookRef bookRef, ContentReaderOptions contentReaderOptions)
         {
             EpubContentRef result = new EpubContentRef
             {
@@ -29,7 +30,7 @@ public static EpubContentRef ParseContentMap(EpubBookRef bookRef)
                     case EpubContentType.XML:
                     case EpubContentType.DTBOOK:
                     case EpubContentType.DTBOOK_NCX:
-                        EpubTextContentFileRef epubTextContentFile = new EpubTextContentFileRef(bookRef, fileName, contentType, contentMimeType);
+                        EpubTextContentFileRef epubTextContentFile = new EpubTextContentFileRef(bookRef, fileName, contentType, contentMimeType, contentReaderOptions);
                         switch (contentType)
                         {
                             case EpubContentType.XHTML_1_1:
@@ -46,7 +47,7 @@ public static EpubContentRef ParseContentMap(EpubBookRef bookRef)
                         result.AllFiles[fileName] = epubTextContentFile;
                         break;
                     default:
-                        EpubByteContentFileRef epubByteContentFile = new EpubByteContentFileRef(bookRef, fileName, contentType, contentMimeType);
+                        EpubByteContentFileRef epubByteContentFile = new EpubByteContentFileRef(bookRef, fileName, contentType, contentMimeType, contentReaderOptions);
                         switch (contentType)
                         {
                             case EpubContentType.IMAGE_GIF:
diff --git a/Source/VersOne.Epub/RefEntities/EpubByteContentFileRef.cs b/Source/VersOne.Epub/RefEntities/EpubByteContentFileRef.cs
@@ -1,4 +1,5 @@
 ﻿using System.Threading.Tasks;
+using VersOne.Epub.Options;
 
 namespace VersOne.Epub
 {
@@ -16,8 +17,9 @@ public class EpubByteContentFileRef : EpubContentFileRef
         /// <param name="fileName">Relative file path of the content file (as it is specified in the EPUB manifest).</param>
         /// <param name="contentType">The type of the content of the file.</param>
         /// <param name="contentMimeType">The MIME type of the content of the file.</param>
-        public EpubByteContentFileRef(EpubBookRef epubBookRef, string fileName, EpubContentType contentType, string contentMimeType)
-            : base(epubBookRef, fileName, contentType, contentMimeType)
+        /// <param name="contentReaderOptions">Optional content reader options determining how to handle missing content files.</param>
+        public EpubByteContentFileRef(EpubBookRef epubBookRef, string fileName, EpubContentType contentType, string contentMimeType, ContentReaderOptions contentReaderOptions = null)
+            : base(epubBookRef, fileName, contentType, contentMimeType, contentReaderOptions)
         {
         }
 
diff --git a/Source/VersOne.Epub/RefEntities/EpubContentFileRef.cs b/Source/VersOne.Epub/RefEntities/EpubContentFileRef.cs
diff --git a/Source/VersOne.Epub/RefEntities/EpubTextContentFileRef.cs b/Source/VersOne.Epub/RefEntities/EpubTextContentFileRef.cs

Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,8 @@ public ZipFile(ZipArchive zipArchive)`
`20`	`20`
`21`	`21`	`public IZipFileEntry GetEntry(string entryName)`
`22`	`22`	`{`
`23`		`- return new ZipFileEntry(zipArchive.GetEntry(entryName));`
	`23`	`+ ZipArchiveEntry zipArchiveEntry = zipArchive.GetEntry(entryName);`
	`24`	`+ return zipArchiveEntry != null ? new ZipFileEntry(zipArchiveEntry) : null;`
`24`	`25`	`}`
`25`	`26`
`26`	`27`	`public void Dispose()`
Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,12 @@`
`1`	`1`	`using System.Collections.Generic;`
	`2`	`+using VersOne.Epub.Options;`
`2`	`3`	`using VersOne.Epub.Schema;`
`3`	`4`
`4`	`5`	`namespace VersOne.Epub.Internal`
`5`	`6`	`{`
`6`	`7`	`internal static class ContentReader`
`7`	`8`	`{`
`8`		`- public static EpubContentRef ParseContentMap(EpubBookRef bookRef)`
	`9`	`+ public static EpubContentRef ParseContentMap(EpubBookRef bookRef, ContentReaderOptions contentReaderOptions)`
`9`	`10`	`{`
`10`	`11`	`EpubContentRef result = new EpubContentRef`
`11`	`12`	`{`
`@@ -29,7 +30,7 @@ public static EpubContentRef ParseContentMap(EpubBookRef bookRef)`
`29`	`30`	`case EpubContentType.XML:`
`30`	`31`	`case EpubContentType.DTBOOK:`
`31`	`32`	`case EpubContentType.DTBOOK_NCX:`
`32`		`- EpubTextContentFileRef epubTextContentFile = new EpubTextContentFileRef(bookRef, fileName, contentType, contentMimeType);`
	`33`	`+ EpubTextContentFileRef epubTextContentFile = new EpubTextContentFileRef(bookRef, fileName, contentType, contentMimeType, contentReaderOptions);`
`33`	`34`	`switch (contentType)`
`34`	`35`	`{`
`35`	`36`	`case EpubContentType.XHTML_1_1:`
`@@ -46,7 +47,7 @@ public static EpubContentRef ParseContentMap(EpubBookRef bookRef)`
`46`	`47`	`result.AllFiles[fileName] = epubTextContentFile;`
`47`	`48`	`break;`
`48`	`49`	`default:`
`49`		`- EpubByteContentFileRef epubByteContentFile = new EpubByteContentFileRef(bookRef, fileName, contentType, contentMimeType);`
	`50`	`+ EpubByteContentFileRef epubByteContentFile = new EpubByteContentFileRef(bookRef, fileName, contentType, contentMimeType, contentReaderOptions);`
`50`	`51`	`switch (contentType)`
`51`	`52`	`{`
`52`	`53`	`case EpubContentType.IMAGE_GIF:`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`using System.Threading.Tasks;`
	`2`	`+using VersOne.Epub.Options;`
`2`	`3`
`3`	`4`	`namespace VersOne.Epub`
`4`	`5`	`{`
`@@ -16,8 +17,9 @@ public class EpubByteContentFileRef : EpubContentFileRef`
`16`	`17`	`/// <param name="fileName">Relative file path of the content file (as it is specified in the EPUB manifest).</param>`
`17`	`18`	`/// <param name="contentType">The type of the content of the file.</param>`
`18`	`19`	`/// <param name="contentMimeType">The MIME type of the content of the file.</param>`
`19`		`- public EpubByteContentFileRef(EpubBookRef epubBookRef, string fileName, EpubContentType contentType, string contentMimeType)`
`20`		`- : base(epubBookRef, fileName, contentType, contentMimeType)`
	`20`	`+ /// <param name="contentReaderOptions">Optional content reader options determining how to handle missing content files.</param>`
	`21`	`+ public EpubByteContentFileRef(EpubBookRef epubBookRef, string fileName, EpubContentType contentType, string contentMimeType, ContentReaderOptions contentReaderOptions = null)`
	`22`	`+ : base(epubBookRef, fileName, contentType, contentMimeType, contentReaderOptions)`
`21`	`23`	`{`
`22`	`24`	`}`
`23`	`25`