Last of the Year - Page Offset, Device-bound Reading Profiles, and more! (#4313)

Co-authored-by: Amelia <77553571+Fesaa@users.noreply.github.com>
Co-authored-by: DieselTech <30128380+DieselTech@users.noreply.github.com>
Co-authored-by: Alex George <xzeroknightx@gmail.com>
Co-authored-by: Lucas Winther <lucasw89@live.dk>
Co-authored-by: Toni Kielo <toni.kielo@gmail.com>
Co-authored-by: Patrick Orave <oravep@gmail.com>

API/Controllers/BaseApiController.cs

@@ -1,9 +1,13 @@
-using API.Middleware;
+using System;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
 using API.Services.Store;
-using Microsoft.AspNetCore.Authentication.JwtBearer;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
 using Microsoft.Extensions.DependencyInjection;
+using MimeTypes;
 
 namespace API.Controllers;
 
@@ -32,4 +36,65 @@ public class BaseApiController : ControllerBase
     /// <remarks>Warning! Username's can contain .. and /, do not use folders or filenames explicitly with the Username</remarks>
     protected string? Username => UserContext.GetUsername();
 
+    /// <summary>
+    /// Returns a physical file with proper HTTP caching headers and ETag support.
+    /// Automatically handles conditional requests (If-None-Match) returning 304 Not Modified when appropriate.
+    /// </summary>
+    /// <param name="path">The absolute path to the file on disk.</param>
+    /// <param name="maxAge">Cache duration in seconds. Default is 86400 (1 day).</param>
+    /// <returns>
+    /// <see cref="NotFoundResult"/> if path is null/empty or file doesn't exist.
+    /// <see cref="StatusCodeResult"/> with 304 if client's cached version is current.
+    /// <see cref="PhysicalFileResult"/> with the file content and caching headers otherwise.
+    /// </returns>
+    protected ActionResult CachedFile(string? path, int maxAge = 86400)
+    {
+        if (string.IsNullOrEmpty(path) || !System.IO.File.Exists(path))
+            return NotFound();
+
+        var lastWrite = System.IO.File.GetLastWriteTimeUtc(path);
+        var etag = $"\"{lastWrite.Ticks:x}-{path.GetHashCode():x}\"";
+
+        if (Request.Headers.IfNoneMatch.ToString() == etag)
+            return StatusCode(304);
+
+        Response.Headers.ETag = etag;
+        Response.Headers.CacheControl = $"private, max-age={maxAge}";
+
+        var contentType = MimeTypeMap.GetMimeType(Path.GetExtension(path));
+        return PhysicalFile(path, contentType, Path.GetFileName(path), enableRangeProcessing: true);
+    }
+
+    /// <summary>
+    /// Returns a file from byte[] content with proper HTTP caching headers and ETag support.
+    /// ETag is generated from SHA256 hash of the content.
+    /// Automatically handles conditional requests (If-None-Match) returning 304 Not Modified when appropriate.
+    /// </summary>
+    /// <param name="content">The file content as byte array.</param>
+    /// <param name="contentType">The MIME type of the content.</param>
+    /// <param name="fileName">Optional filename for Content-Disposition header.</param>
+    /// <param name="maxAge">Cache duration in seconds. Default is 86400 (1 day).</param>
+    /// <returns>
+    /// <see cref="NotFoundResult"/> if content is null or empty.
+    /// <see cref="StatusCodeResult"/> with 304 if client's cached version is current.
+    /// <see cref="FileContentResult"/> with the content and caching headers otherwise.
+    /// </returns>
+    protected ActionResult CachedContent(byte[]? content, string contentType, string? fileName = null, int maxAge = 86400)
+    {
+        if (content is not { Length: > 0 })
+            return NotFound();
+
+        var etag = $"\"{Convert.ToHexString(SHA256.HashData(content))}\"";
+
+        if (Request.Headers.IfNoneMatch.ToString() == etag)
+            return StatusCode(304);
+
+        Response.Headers.ETag = etag;
+        Response.Headers.CacheControl = $"private, max-age={maxAge}";
+
+        return fileName is not null
+            ? File(content, contentType, fileName)
+            : File(content, contentType);
+    }
+
 }