feat(reading): lecture adaptative pour mauvaises connexions — manifest de lecture avec fenêtre priorisée autour de la position du lecteur et préchargement progressif des pages voisines, ressources authentifiées servies avec Range/ETag (module reading API: controller/service/dto/ports, source archive et cache reconstructible filesystem), client web adaptatif useAdaptiveReading avec enrichissement du cache au fil de la lecture, EPUB chargé par ressources manifestées via loader Foliate avec credentials (fini le téléchargement complet du fichier), optimisation des images EPUB et fallback page PDF allégée, avec tests api/web — évolution #53

Ouvrir rapidement un très grand livre et continuer la lecture sans attendre le chargement complet sur très mauvaise connexion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/api/src/app.module.ts

@@ -6,11 +6,12 @@ import { BooksModule } from "./books/books.module.js";
 import { DatabaseModule } from "./database/database.module.js";
 import { ProgressModule } from "./progress/progress.module.js";
 import { ReaderModule } from "./reader/reader.module.js";
+import { ReadingModule } from "./reading/reading.module.js";
 import { ScannerModule } from "./scanner/scanner.module.js";
 import { HealthController } from "./health.controller.js";
 
 @Module({
-  imports: [DatabaseModule, AuthModule, AdminModule, BooksModule, ProgressModule, ReaderModule, ScannerModule, AutomationModule],
+  imports: [DatabaseModule, AuthModule, AdminModule, BooksModule, ProgressModule, ReaderModule, ReadingModule, ScannerModule, AutomationModule],
   controllers: [HealthController]
 })
 export class AppModule {}

apps/api/src/reading/adapters/archive-reading-source.adapter.test.ts

@@ -0,0 +1,75 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import AdmZip from "adm-zip";
+import { afterEach, describe, expect, it } from "vitest";
+import { ArchiveReadingSourceAdapter } from "./archive-reading-source.adapter.js";
+
+const directories: string[] = [];
+
+afterEach(() => {
+  for (const directory of directories.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+describe("ArchiveReadingSourceAdapter", () => {
+  it("builds an ordered EPUB spine and serves only opaque resource ids", async () => {
+    const directory = mkdtempSync(join(tmpdir(), "readabook-reading-"));
+    directories.push(directory);
+    const filePath = join(directory, "book.epub");
+    const zip = new AdmZip();
+    zip.addFile("META-INF/container.xml", Buffer.from(`<?xml version="1.0"?><container><rootfiles><rootfile full-path="OPS/package.opf"/></rootfiles></container>`));
+    zip.addFile("OPS/package.opf", Buffer.from(`<package><manifest><item id="one" href="chapter-1.xhtml" media-type="application/xhtml+xml"/><item id="pic" href="images/cover.jpg" media-type="image/jpeg"/><item id="two" href="chapter-2.xhtml" media-type="application/xhtml+xml"/></manifest><spine><itemref idref="one"/><itemref idref="two"/></spine></package>`));
+    zip.addFile("OPS/chapter-1.xhtml", Buffer.from('<html><head><link href="styles/book.css" rel="stylesheet"/></head><body><img src="images/cover.jpg"/><p>First</p></body></html>'));
+    zip.addFile("OPS/chapter-2.xhtml", Buffer.from("<p>Second</p>"));
+    zip.addFile("OPS/images/cover.jpg", Buffer.from([1, 2, 3]));
+    zip.addFile("OPS/styles/book.css", Buffer.from("body { color: black; }"));
+    zip.writeZip(filePath);
+    const stat = await import("node:fs").then(({ statSync }) => statSync(filePath));
+    const source = new ArchiveReadingSourceAdapter();
+    const book = { id: 7, format: "epub", filePath, fileSize: stat.size, fileMtime: stat.mtime.toISOString() };
+
+    const manifest = await source.manifest(book);
+
+    expect(manifest.spine).toHaveLength(2);
+    expect(manifest).toMatchObject({
+      containerPath: "META-INF/container.xml",
+      opfPath: "OPS/package.opf",
+      basePath: "OPS/",
+      revision: expect.any(String)
+    });
+    expect(JSON.stringify(manifest)).not.toContain(filePath);
+    expect(JSON.stringify(manifest)).not.toContain(`/books/${book.id}/file`);
+    expect(manifest.resources).toHaveLength(6);
+    expect(manifest.resources.map((resource) => resource.resourceId)).not.toContain("OPS/chapter-1.xhtml");
+    expect(manifest.resources).toEqual(expect.arrayContaining([
+      expect.objectContaining({ href: "META-INF/container.xml", mediaType: "application/xml", size: expect.any(Number), url: expect.stringContaining("/reading-resources/") }),
+      expect.objectContaining({ href: "OPS/package.opf", mediaType: "application/oebps-package+xml" }),
+      expect.objectContaining({ href: "OPS/images/cover.jpg", mediaType: "image/jpeg", size: 3 })
+    ]));
+    expect(manifest.spine[0]).toMatchObject({ index: 0, href: "OPS/chapter-1.xhtml", mediaType: "application/xhtml+xml", size: expect.any(Number) });
+    const firstResource = manifest.resources.find((resource) => resource.href === "OPS/chapter-1.xhtml");
+    const coverResource = manifest.resources.find((resource) => resource.href === "OPS/images/cover.jpg");
+    expect(firstResource?.references).toContain(coverResource?.resourceId);
+    const chapter = await source.resource(book, manifest.spine[0].resourceId);
+    expect(chapter.contentType).toBe("application/xhtml+xml");
+    expect(chapter.data?.toString()).toContain("<p>First</p>");
+    const container = manifest.resources.find((resource) => resource.href === manifest.containerPath);
+    expect((await source.resource(book, container!.resourceId)).data?.toString()).toContain("container");
+  });
+
+  it("exposes a PDF as a range-capable original without leaking its path in the manifest", async () => {
+    const directory = mkdtempSync(join(tmpdir(), "readabook-reading-"));
+    directories.push(directory);
+    const filePath = join(directory, "secret-name.pdf");
+    writeFileSync(filePath, "%PDF-test");
+    const source = new ArchiveReadingSourceAdapter();
+    const book = { id: 8, format: "pdf", filePath, fileSize: 9, fileMtime: "2026-01-01T00:00:00.000Z" };
+
+    const manifest = await source.manifest(book);
+    const resource = await source.resource(book, "original");
+
+    expect(JSON.stringify(manifest)).not.toContain(filePath);
+    expect(manifest).toMatchObject({ format: "pdf", spine: [expect.objectContaining({ resourceId: "original" })], capabilities: { byteRanges: true, lightweightPages: false } });
+    expect(resource).toMatchObject({ filePath, contentType: "application/pdf", supportsRanges: true });
+  });
+});

apps/api/src/reading/adapters/archive-reading-source.adapter.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { extname, posix } from "node:path";
+import { BadRequestException, Injectable, NotFoundException } from "@nestjs/common";
+import AdmZip from "adm-zip";
+import { XMLParser } from "fast-xml-parser";
+import { lookup } from "mime-types";
+import { ReadingSourcePort } from "../reading.ports.js";
+import { ReadingBook, ReadingManifest, ReadingResource, ReadingResourcePayload, ReadingSpineItem } from "../reading.types.js";
+
+const xml = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
+const MAX_EPUB_ENTRIES = 20_000;
+const MAX_RESOURCE_BYTES = 64 * 1024 * 1024;
+
+@Injectable()
+export class ArchiveReadingSourceAdapter implements ReadingSourcePort {
+  private readonly epubManifests = new Map<number, { revision: string; manifest: ReadingManifest }>();
+
+  async manifest(book: ReadingBook): Promise<ReadingManifest> {
+    this.assertReadable(book);
+    if (book.format === "pdf") return pdfManifest(book);
+    if (book.format !== "epub") throw new BadRequestException("Adaptive reading supports EPUB and PDF books");
+    const revision = revisionFor(book);
+    const cached = this.epubManifests.get(book.id);
+    if (cached?.revision === revision) return cached.manifest;
+    const manifest = epubManifest(book);
+    this.epubManifests.set(book.id, { revision, manifest });
+    return manifest;
+  }
+
+  async resource(book: ReadingBook, resourceId: string): Promise<ReadingResourcePayload> {
+    this.assertReadable(book);
+    if (book.format === "pdf") {
+      if (resourceId !== "original") throw new NotFoundException("Reading resource not found");
+      const size = statSync(book.filePath).size;
+      return { filePath: book.filePath, contentType: "application/pdf", size, etag: etag(book, resourceId), supportsRanges: true };
+    }
+    if (book.format !== "epub") throw new BadRequestException("Adaptive reading supports EPUB and PDF books");
+    const manifest = await this.manifest(book);
+    const resource = manifest.resources.find((candidate) => candidate.resourceId === resourceId);
+    if (!resource) throw new NotFoundException("Reading resource not found");
+    const zip = new AdmZip(book.filePath);
+    const entry = zip.getEntry(resource.href);
+    if (!entry || entry.isDirectory) throw new NotFoundException("Reading resource not found");
+    if (entry.header.size > MAX_RESOURCE_BYTES) throw new BadRequestException("EPUB resource is too large to extract");
+    const data = entry.getData();
+    return { data, contentType: resource.mediaType, size: data.length, etag: etag(book, resourceId), supportsRanges: false };
+  }
+
+  private assertReadable(book: ReadingBook): void {
+    if (!existsSync(book.filePath)) throw new NotFoundException("Book file not found on disk");
+  }
+}
+
+function epubManifest(book: ReadingBook): ReadingManifest {
+  const zip = new AdmZip(book.filePath);
+  const entries = zip.getEntries();
+  if (entries.length > MAX_EPUB_ENTRIES) throw new BadRequestException("EPUB archive has too many entries");
+  const containerPath = "META-INF/container.xml";
+  const container = xml.parse(zip.readAsText(containerPath));
+  const rootfiles = array(container?.container?.rootfiles?.rootfile);
+  const opfPath = rootfiles[0]?.["@_full-path"];
+  if (typeof opfPath !== "string") throw new BadRequestException("EPUB package document is missing");
+  const normalizedOpf = normalizeArchivePath(opfPath);
+  const parsed = xml.parse(zip.readAsText(normalizedOpf));
+  const packageDocument = parsed?.package;
+  const directory = posix.dirname(normalizedOpf);
+  const basePath = directory === "." ? "" : `${directory}/`;
+  const items = array(packageDocument?.manifest?.item);
+  const spineItems = array(packageDocument?.spine?.itemref);
+  const declaredMediaTypes = new Map<string, string>();
+  const packageIds = new Map<string, string>();
+  for (const item of items) {
+    const packageId = stringAttribute(item, "@_id");
+    const href = stringAttribute(item, "@_href");
+    if (!href) continue;
+    const archivePath = normalizeArchivePath(posix.join(directory, decodeHref(href)));
+    const mediaType = stringAttribute(item, "@_media-type");
+    if (mediaType) declaredMediaTypes.set(archivePath, mediaType);
+    if (packageId) packageIds.set(packageId, archivePath);
+  }
+  const byPackageId = new Map<string, ReadingResource>();
+  const resources = entries.flatMap((entry): ReadingResource[] => {
+    if (entry.isDirectory) return [];
+    const archivePath = normalizeArchivePath(entry.entryName);
+    const mediaType = declaredMediaTypes.get(archivePath) ?? archiveMediaType(archivePath, normalizedOpf);
+    const resource: ReadingResource = {
+      resourceId: opaqueId(archivePath),
+      href: archivePath,
+      url: resourceUrl(book.id, opaqueId(archivePath)),
+      kind: resourceKind(mediaType),
+      mediaType,
+      size: entry.header.size,
+      state: "ready"
+    };
+    return [resource];
+  });
+  const byHref = new Map(resources.map((resource) => [resource.href, resource]));
+  for (const [packageId, archivePath] of packageIds) {
+    const resource = byHref.get(archivePath);
+    if (resource) byPackageId.set(packageId, resource);
+  }
+  addResourceReferences(zip, resources, byHref);
+  const spine = spineItems.flatMap((item, index): ReadingSpineItem[] => {
+    if (stringAttribute(item, "@_linear") === "no") return [];
+    const resource = byPackageId.get(stringAttribute(item, "@_idref") ?? "");
+    if (!resource) return [];
+    return [{ index, href: resource.href, resourceId: resource.resourceId, url: resource.url, mediaType: resource.mediaType, size: resource.size }];
+  });
+  const revision = revisionFor(book);
+  return {
+    bookId: book.id,
+    format: "epub",
+    revision,
+    version: revision,
+    containerPath,
+    opfPath: normalizedOpf,
+    basePath,
+    resources,
+    spine,
+    capabilities: { byteRanges: false, derivedImages: true, lightweightPages: false }
+  };
+}
+
+function pdfManifest(book: ReadingBook): ReadingManifest {
+  const revision = revisionFor(book);
+  return {
+    bookId: book.id,
+    format: "pdf",
+    revision,
+    version: revision,
+    containerPath: null,
+    opfPath: null,
+    basePath: null,
+    resources: [{ resourceId: "original", href: "original", url: resourceUrl(book.id, "original"), kind: "document", mediaType: "application/pdf", size: book.fileSize, state: "ready" }],
+    spine: [{ index: 0, href: "original", resourceId: "original", url: resourceUrl(book.id, "original"), mediaType: "application/pdf", size: book.fileSize }],
+    capabilities: { byteRanges: true, derivedImages: false, lightweightPages: false }
+  };
+}
+
+function normalizeArchivePath(path: string): string {
+  const normalized = posix.normalize(path.replace(/^\/+/, ""));
+  if (normalized === ".." || normalized.startsWith("../")) throw new BadRequestException("Invalid EPUB resource path");
+  return normalized;
+}
+
+function decodeHref(href: string): string {
+  try {
+    return decodeURIComponent(href.split("#", 1)[0]);
+  } catch {
+    throw new BadRequestException("Invalid EPUB resource path");
+  }
+}
+
+function opaqueId(path: string): string {
+  return createHash("sha256").update(path).digest("base64url").slice(0, 22);
+}
+
+function revisionFor(book: ReadingBook): string {
+  return createHash("sha256").update(`${book.fileSize}:${book.fileMtime}`).digest("base64url");
+}
+
+function resourceUrl(bookId: number, resourceId: string): string {
+  return `/books/${bookId}/reading-resources/${encodeURIComponent(resourceId)}`;
+}
+
+function archiveMediaType(path: string, opfPath: string): string {
+  if (path === "META-INF/container.xml") return "application/xml";
+  if (path === opfPath) return "application/oebps-package+xml";
+  if (path === "mimetype") return "text/plain";
+  return String(lookup(extname(path)) || "application/octet-stream");
+}
+
+function addResourceReferences(zip: AdmZip, resources: ReadingResource[], byHref: Map<string, ReadingResource>): void {
+  for (const resource of resources) {
+    if ((resource.kind !== "chapter" && resource.kind !== "stylesheet") || resource.size > 2 * 1024 * 1024) continue;
+    const entry = zip.getEntry(resource.href);
+    if (!entry) continue;
+    const text = entry.getData().toString("utf8");
+    const candidates = resource.kind === "stylesheet"
+      ? [...text.matchAll(/url\(\s*["']?([^"')]+)["']?\s*\)/gi)].map((match) => match[1])
+      : [...text.matchAll(/(?:src|href)\s*=\s*["']([^"']+)["']/gi)].map((match) => match[1]);
+    const references = candidates.flatMap((candidate): string[] => {
+      const href = resolveReference(resource.href, candidate);
+      const target = href ? byHref.get(href) : undefined;
+      return target && target.kind !== "chapter" ? [target.resourceId] : [];
+    });
+    resource.references = [...new Set(references)];
+  }
+}
+
+function resolveReference(parent: string, reference: string): string | null {
+  const clean = reference.trim();
+  if (!clean || clean.startsWith("#") || /^(?:data|https?|mailto|tel):/i.test(clean) || clean.startsWith("//")) return null;
+  try {
+    return normalizeArchivePath(posix.join(posix.dirname(parent), decodeHref(clean)));
+  } catch {
+    return null;
+  }
+}
+
+function etag(book: ReadingBook, resourceId: string): string {
+  return `\"${createHash("sha256").update(`${book.id}:${book.fileSize}:${book.fileMtime}:${resourceId}`).digest("base64url")}\"`;
+}
+
+function array(value: any): any[] {
+  return Array.isArray(value) ? value : value ? [value] : [];
+}
+
+function stringAttribute(value: any, key: string): string | null {
+  return typeof value?.[key] === "string" ? value[key] : null;
+}
+
+function resourceKind(mediaType: string): ReadingResource["kind"] {
+  if (mediaType.startsWith("image/")) return "image";
+  if (mediaType === "text/css") return "stylesheet";
+  if (mediaType.includes("font") || mediaType.includes("woff")) return "font";
+  if (mediaType.includes("html") || mediaType.includes("xml")) return "chapter";
+  return "document";
+}

apps/api/src/reading/adapters/filesystem-reading-cache.adapter.ts

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Injectable } from "@nestjs/common";
+import { DatabaseService } from "../../database/database.service.js";
+import { ReadingCachePort } from "../reading.ports.js";
+import { ReadingBook } from "../reading.types.js";
+
+@Injectable()
+export class FilesystemReadingCacheAdapter implements ReadingCachePort {
+  constructor(private readonly database: DatabaseService) {}
+
+  async get(book: ReadingBook, resourceId: string): Promise<Buffer | null> {
+    try {
+      return await readFile(this.path(book, resourceId));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  }
+
+  async put(book: ReadingBook, resourceId: string, data: Buffer): Promise<void> {
+    const path = this.path(book, resourceId);
+    await mkdir(join(path, ".."), { recursive: true });
+    await writeFile(path, data);
+  }
+
+  async remove(book: ReadingBook, resourceId: string): Promise<void> {
+    await rm(this.path(book, resourceId), { force: true });
+  }
+
+  private path(book: ReadingBook, resourceId: string): string {
+    const version = createHash("sha256").update(`${book.fileSize}:${book.fileMtime}`).digest("hex").slice(0, 16);
+    const resource = createHash("sha256").update(resourceId).digest("hex");
+    return join(this.database.config.storageDir, "reading-cache", String(book.id), version, resource);
+  }
+}

apps/api/src/reading/reading.controller.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it, vi } from "vitest";
+import { ReadingController } from "./reading.controller.js";
+
+describe("ReadingController", () => {
+  it("returns 304 for a matching ETag without a range request", async () => {
+    const controller = new ReadingController({
+      resource: vi.fn().mockResolvedValue(resourcePayload({ partial: false }))
+    } as any);
+    const reply = fakeReply();
+
+    await controller.resource("12", "chapter-1", undefined, '"etag"', reply as any);
+
+    expect(reply.statusCode).toBe(304);
+    expect(reply.sent).toBeUndefined();
+    expect(reply.headers).toEqual({});
+  });
+
+  it("sets cache, ETag and range headers for partial PDF resources", async () => {
+    const controller = new ReadingController({
+      resource: vi.fn().mockResolvedValue(resourcePayload({ partial: true, supportsRanges: true, start: 2, end: 5, size: 10, data: Buffer.from("2345") }))
+    } as any);
+    const reply = fakeReply();
+
+    await controller.resource("12", "original", "bytes=2-5", undefined, reply as any);
+
+    expect(reply.statusCode).toBe(206);
+    expect(reply.headers).toMatchObject({
+      "Accept-Ranges": "bytes",
+      "Cache-Control": "private, max-age=3600, must-revalidate",
+      "Content-Length": "4",
+      "Content-Range": "bytes 2-5/10",
+      "Content-Type": "application/pdf",
+      ETag: '"etag"',
+      "X-Content-Type-Options": "nosniff"
+    });
+    expect(reply.sent?.toString()).toBe("2345");
+  });
+});
+
+function resourcePayload(overrides: Record<string, unknown>) {
+  return {
+    data: Buffer.from("chapter"),
+    contentType: "application/pdf",
+    size: 7,
+    etag: '"etag"',
+    supportsRanges: false,
+    start: 0,
+    end: 6,
+    partial: false,
+    ...overrides
+  };
+}
+
+function fakeReply() {
+  return {
+    statusCode: 200,
+    headers: {} as Record<string, string>,
+    sent: undefined as unknown,
+    code(status: number) {
+      this.statusCode = status;
+      return this;
+    },
+    header(name: string, value: string) {
+      this.headers[name] = value;
+      return this;
+    },
+    send(payload?: unknown) {
+      this.sent = payload;
+      return this;
+    }
+  };
+}

apps/api/src/reading/reading.controller.ts

@@ -0,0 +1,50 @@
+import { Body, Controller, Get, Headers, Param, Post, Res, UseGuards } from "@nestjs/common";
+import { FastifyReply } from "fastify";
+import { AuthGuard } from "../auth/auth.guard.js";
+import { ZodValidationPipe } from "../common/zod-validation.pipe.js";
+import { ReadingWindowDto, ReadingWindowSchema } from "./reading.dto.js";
+import { ReadingService } from "./reading.service.js";
+
+@Controller("books/:bookId")
+@UseGuards(AuthGuard)
+export class ReadingController {
+  constructor(private readonly reading: ReadingService) {}
+
+  @Get("reading-manifest")
+  manifest(@Param("bookId") bookId: string) {
+    return this.reading.manifest(Number(bookId));
+  }
+
+  @Get("reading-resources/:resourceId")
+  async resource(
+    @Param("bookId") bookId: string,
+    @Param("resourceId") resourceId: string,
+    @Headers("range") range: string | undefined,
+    @Headers("if-none-match") ifNoneMatch: string | undefined,
+    @Res() reply: FastifyReply
+  ) {
+    const resource = await this.reading.resource(Number(bookId), resourceId, range);
+    if (!range && ifNoneMatch === resource.etag) return reply.code(304).send();
+    if (resource.partial) {
+      reply.code(206);
+      reply.header("Content-Range", `bytes ${resource.start}-${resource.end}/${resource.size}`);
+    }
+    if (resource.supportsRanges) reply.header("Accept-Ranges", "bytes");
+    reply.header("Content-Length", String(resource.end - resource.start + 1));
+    reply.header("Content-Type", resource.contentType);
+    reply.header("ETag", resource.etag);
+    reply.header("Cache-Control", "private, max-age=3600, must-revalidate");
+    reply.header("X-Content-Type-Options", "nosniff");
+    return reply.send(resource.stream ?? resource.data);
+  }
+
+  @Post("reading-window")
+  window(@Param("bookId") bookId: string, @Body(new ZodValidationPipe(ReadingWindowSchema)) input: ReadingWindowDto) {
+    return this.reading.window(Number(bookId), input);
+  }
+
+  @Post("reading-resources/:resourceId/retry")
+  retry(@Param("bookId") bookId: string, @Param("resourceId") resourceId: string) {
+    return this.reading.retry(Number(bookId), resourceId);
+  }
+}

apps/api/src/reading/reading.dto.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const ReadingWindowSchema = z.object({
+  locator: z.string().trim().min(1).max(512),
+  mode: z.enum(["auto", "speed", "quality"]).default("auto"),
+  networkHint: z.enum(["offline", "slow", "normal", "fast", "unknown"]).default("unknown")
+});
+
+export type ReadingWindowDto = z.infer<typeof ReadingWindowSchema>;

apps/api/src/reading/reading.module.ts

@@ -0,0 +1,20 @@
+import { Module } from "@nestjs/common";
+import { AuthModule } from "../auth/auth.module.js";
+import { DatabaseModule } from "../database/database.module.js";
+import { JobsModule } from "../jobs/jobs.module.js";
+import { ArchiveReadingSourceAdapter } from "./adapters/archive-reading-source.adapter.js";
+import { FilesystemReadingCacheAdapter } from "./adapters/filesystem-reading-cache.adapter.js";
+import { ReadingController } from "./reading.controller.js";
+import { ReadingCachePort, ReadingSourcePort } from "./reading.ports.js";
+import { ReadingService } from "./reading.service.js";
+
+@Module({
+  imports: [AuthModule, DatabaseModule, JobsModule],
+  controllers: [ReadingController],
+  providers: [
+    ReadingService,
+    { provide: ReadingSourcePort, useClass: ArchiveReadingSourceAdapter },
+    { provide: ReadingCachePort, useClass: FilesystemReadingCacheAdapter }
+  ]
+})
+export class ReadingModule {}

apps/api/src/reading/reading.ports.ts

@@ -0,0 +1,12 @@
+import { ReadingBook, ReadingManifest, ReadingResourcePayload } from "./reading.types.js";
+
+export abstract class ReadingSourcePort {
+  abstract manifest(book: ReadingBook): Promise<ReadingManifest>;
+  abstract resource(book: ReadingBook, resourceId: string): Promise<ReadingResourcePayload>;
+}
+
+export abstract class ReadingCachePort {
+  abstract get(book: ReadingBook, resourceId: string): Promise<Buffer | null>;
+  abstract put(book: ReadingBook, resourceId: string, data: Buffer): Promise<void>;
+  abstract remove(book: ReadingBook, resourceId: string): Promise<void>;
+}

apps/api/src/reading/reading.service.test.ts

@@ -0,0 +1,169 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { eq } from "drizzle-orm";
+import { DatabaseService } from "../database/database.service.js";
+import { books, jobs, libraries } from "../database/schema.js";
+import { JobsService } from "../jobs/jobs.service.js";
+import { ReadingCachePort, ReadingSourcePort } from "./reading.ports.js";
+import { ReadingService } from "./reading.service.js";
+import { ReadingBook, ReadingManifest, ReadingResourcePayload } from "./reading.types.js";
+
+const previousDatabasePath = process.env.DATABASE_PATH;
+const previousStorageDir = process.env.STORAGE_DIR;
+const directories: string[] = [];
+
+afterEach(() => {
+  process.env.DATABASE_PATH = previousDatabasePath;
+  process.env.STORAGE_DIR = previousStorageDir;
+  for (const directory of directories.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+describe("ReadingService", () => {
+  it.runIf(canLoadBetterSqlite())("rejects books in disabled libraries", async () => {
+    const { database, bookId } = fixture(false);
+    const service = new ReadingService(database, new JobsService(database), new FakeSource(), new MemoryCache());
+    await expect(service.manifest(bookId)).rejects.toThrow("accessible library");
+    database.onModuleDestroy();
+  });
+
+  it.runIf(canLoadBetterSqlite())("reports a priority window around the current spine item without preparing while offline", async () => {
+    const { database, bookId } = fixture(true);
+    const service = new ReadingService(database, new JobsService(database), new FakeSource(), new MemoryCache());
+
+    const window = await service.window(bookId, { locator: "chapter-2", mode: "auto", networkHint: "offline" });
+
+    expect(window.current).toMatchObject({ resourceId: "chapter-2", relation: "current" });
+    expect(window.previous).toMatchObject({ resourceId: "chapter-1", relation: "previous" });
+    expect(window.next).toMatchObject({ resourceId: "chapter-3", relation: "next" });
+    expect(window.resources).toEqual([expect.objectContaining({ resourceId: "chapter-image", relation: "resource" })]);
+    expect(window.neighbors).toEqual([]);
+    expect(database.db.select().from((await import("../database/schema.js")).jobs).all()).toHaveLength(0);
+    database.onModuleDestroy();
+  });
+
+  it.runIf(canLoadBetterSqlite())("queues the current resource before previous and next resources on slow connections", async () => {
+    const { database, bookId } = fixture(true);
+    const service = new ReadingService(database, new JobsService(database), new FakeSource(), new MemoryCache());
+
+    const window = await service.window(bookId, { locator: "chapter-2", mode: "speed", networkHint: "slow" });
+
+    expect(window.current).toMatchObject({ resourceId: "chapter-2", relation: "current", state: "pending" });
+    expect(window.previous).toMatchObject({ resourceId: "chapter-1", relation: "previous", state: "pending" });
+    expect(window.next).toMatchObject({ resourceId: "chapter-3", relation: "next", state: "pending" });
+    const [job] = database.db.select().from(jobs).all();
+    expect(job).toMatchObject({ type: "prepare-reading-window", status: "queued" });
+    expect(JSON.parse(job.detail ?? "{}")).toEqual({ bookId, resourceIds: ["chapter-2", "chapter-image", "chapter-1", "chapter-3"] });
+    await flushImmediates();
+    database.onModuleDestroy();
+  });
+
+  it.runIf(canLoadBetterSqlite())("serves byte ranges for the original PDF resource", async () => {
+    const { database, bookId, directory } = fixture(true, "pdf");
+    const filePath = join(directory, "book.pdf");
+    writeFileSync(filePath, Buffer.from("0123456789"));
+    database.db.update(books).set({ filePath, fileSize: 10 }).where(eq(books.id, bookId)).run();
+    const service = new ReadingService(database, new JobsService(database), new FakeSource(), new MemoryCache());
+
+    const resource = await service.resource(bookId, "original", "bytes=2-5");
+
+    expect(resource).toMatchObject({
+      contentType: "application/pdf",
+      etag: '"pdf-etag"',
+      supportsRanges: true,
+      size: 10,
+      start: 2,
+      end: 5,
+      partial: true
+    });
+    await expect(readStream(resource.stream)).resolves.toEqual(Buffer.from("2345"));
+    database.onModuleDestroy();
+  });
+});
+
+class FakeSource extends ReadingSourcePort {
+  async manifest(book: ReadingBook): Promise<ReadingManifest> {
+    if (book.format === "pdf") {
+      return {
+        bookId: book.id,
+        format: "pdf",
+        version: "pdf-version",
+      revision: "pdf-version",
+      containerPath: null, opfPath: null, basePath: null,
+      resources: [{ resourceId: "original", href: "original", url: "/original", kind: "document", mediaType: "application/pdf", size: book.fileSize, state: "ready" }],
+      spine: [{ index: 0, href: "original", resourceId: "original", url: "/original", mediaType: "application/pdf", size: book.fileSize }],
+        capabilities: { byteRanges: true, derivedImages: false, lightweightPages: false }
+      };
+    }
+    return {
+      bookId: book.id,
+      format: "epub",
+      revision: "version",
+      version: "version",
+      containerPath: "META-INF/container.xml", opfPath: "OPS/package.opf", basePath: "OPS/",
+      resources: [
+        ...["chapter-1", "chapter-2", "chapter-3"].map((id) => ({ resourceId: id, href: id, url: `/${id}`, kind: "chapter" as const, mediaType: "application/xhtml+xml", size: 7, state: "ready" as const, ...(id === "chapter-2" ? { references: ["chapter-image"] } : {}) })),
+        { resourceId: "chapter-image", href: "image.jpg", url: "/chapter-image", kind: "image" as const, mediaType: "image/jpeg", size: 5, state: "ready" as const }
+      ],
+      spine: ["chapter-1", "chapter-2", "chapter-3"].map((id, index) => ({ index, href: id, resourceId: id, url: `/${id}`, mediaType: "application/xhtml+xml", size: 7 })),
+      capabilities: { byteRanges: false, derivedImages: true, lightweightPages: false }
+    };
+  }
+  async resource(book: ReadingBook, resourceId: string): Promise<ReadingResourcePayload> {
+    if (book.format === "pdf" && resourceId === "original") {
+      return { filePath: book.filePath, contentType: "application/pdf", size: book.fileSize, etag: '"pdf-etag"', supportsRanges: true };
+    }
+    return { data: Buffer.from("chapter"), contentType: "application/xhtml+xml", size: 7, etag: '"etag"', supportsRanges: false };
+  }
+}
+
+class MemoryCache extends ReadingCachePort {
+  private readonly values = new Map<string, Buffer>();
+  async get(_book: ReadingBook, resourceId: string) { return this.values.get(resourceId) ?? null; }
+  async put(_book: ReadingBook, resourceId: string, data: Buffer) { this.values.set(resourceId, data); }
+  async remove(_book: ReadingBook, resourceId: string) { this.values.delete(resourceId); }
+}
+
+function fixture(enabled: boolean, format: "epub" | "pdf" = "epub") {
+  const directory = mkdtempSync(join(tmpdir(), "readabook-reading-service-"));
+  directories.push(directory);
+  process.env.DATABASE_PATH = join(directory, "test.sqlite");
+  process.env.STORAGE_DIR = join(directory, "storage");
+  const database = new DatabaseService();
+  const now = database.now();
+  const library = database.db.insert(libraries).values({ name: "Library", path: directory, enabled, createdAt: now, updatedAt: now }).returning().get();
+  const book = database.db.insert(books).values({
+    libraryId: library.id, seriesId: null, title: "Book", author: null, description: null, isbn: null, isbn13: null,
+    identifiersJson: null, localMetadataJson: null, language: null, publisher: null, publishedDate: null, volumeNumber: null,
+    volumeLabel: null, format, filePath: join(directory, `book.${format}`), coverPath: null, metadataStatus: "none",
+    metadataProvenanceJson: null, scanStatus: "succeeded", enrichmentStatus: "idle", fileSize: 10, fileMtime: now,
+    createdAt: now, updatedAt: now
+  }).returning().get();
+  return { database, bookId: book.id, directory };
+}
+
+function canLoadBetterSqlite(): boolean {
+  try {
+    return Boolean(DatabaseService);
+  } catch {
+    return false;
+  }
+}
+
+function flushImmediates() {
+  return new Promise<void>((resolve) => setImmediate(resolve));
+}
+
+function readStream(stream: NodeJS.ReadableStream | undefined) {
+  return new Promise<Buffer>((resolve, reject) => {
+    if (!stream) {
+      resolve(Buffer.alloc(0));
+      return;
+    }
+    const chunks: Buffer[] = [];
+    stream.on("data", (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+    stream.on("error", reject);
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+  });
+}

apps/api/src/reading/reading.service.ts

@@ -0,0 +1,168 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { BadRequestException, HttpException, HttpStatus, Inject, Injectable, NotFoundException } from "@nestjs/common";
+import { and, eq } from "drizzle-orm";
+import { DatabaseService } from "../database/database.service.js";
+import { books, libraries } from "../database/schema.js";
+import { JobsService } from "../jobs/jobs.service.js";
+import { ReadingCachePort, ReadingSourcePort } from "./reading.ports.js";
+import { ReadingBook, ReadingResourcePayload, ReadingWindowInput } from "./reading.types.js";
+
+@Injectable()
+export class ReadingService {
+  private readonly preparing = new Set<string>();
+
+  constructor(
+    private readonly database: DatabaseService,
+    private readonly jobs: JobsService,
+    @Inject(ReadingSourcePort) private readonly source: ReadingSourcePort,
+    @Inject(ReadingCachePort) private readonly cache: ReadingCachePort
+  ) {}
+
+  async manifest(bookId: number) {
+    return this.source.manifest(this.accessibleBook(bookId));
+  }
+
+  async resource(bookId: number, resourceId: string, range?: string): Promise<ReadingResourcePayload & { stream?: NodeJS.ReadableStream; start: number; end: number; partial: boolean }> {
+    const book = this.accessibleBook(bookId);
+    const cached = book.format === "epub" ? await this.cache.get(book, resourceId) : null;
+    const manifestResource = cached ? (await this.source.manifest(book)).resources.find((resource) => resource.resourceId === resourceId) : null;
+    if (cached && !manifestResource) throw new NotFoundException("Reading resource not found");
+    const payload = cached && manifestResource
+      ? { data: cached, contentType: manifestResource.mediaType, size: cached.length, etag: manifestVersionEtag(book, resourceId), supportsRanges: false }
+      : await this.source.resource(book, resourceId);
+    const byteRange = parseByteRange(range, payload.size, payload.supportsRanges);
+    if (payload.filePath) {
+      return { ...payload, stream: createReadStream(payload.filePath, { start: byteRange.start, end: byteRange.end }), ...byteRange };
+    }
+    const data = payload.data;
+    if (!data) throw new NotFoundException("Reading resource not found");
+    if (!cached) await this.cache.put(book, resourceId, data);
+    return { ...payload, data: data.subarray(byteRange.start, byteRange.end + 1), ...byteRange };
+  }
+
+  async window(bookId: number, input: ReadingWindowInput) {
+    const book = this.accessibleBook(bookId);
+    const manifest = await this.source.manifest(book);
+    const position = resolvePosition(input.locator, manifest.spine);
+    const current = manifest.spine[position];
+    const referenced = referencedResources(current.resourceId, manifest.resources);
+    const ordered = priorityWindow(manifest.spine, position, referenced, input.networkHint === "slow" || input.mode === "speed" ? 1 : 2);
+    const states = await Promise.all(ordered.map(async ({ id, distance }) => ({
+      resourceId: id,
+      relation: distance === 0 ? "current" : distance === null ? "resource" : distance === -1 ? "previous" : distance === 1 ? "next" : "neighbor",
+      state: await this.resourceState(book, id)
+    })));
+    if (input.networkHint !== "offline") this.enqueuePreparation(book, ordered.map((entry) => entry.id));
+    return {
+      bookId,
+      locator: input.locator,
+      mode: input.mode,
+      networkHint: input.networkHint,
+      current: states.find((state) => state.relation === "current") ?? null,
+      previous: states.find((state) => state.relation === "previous") ?? null,
+      next: states.find((state) => state.relation === "next") ?? null,
+      resources: states.filter((state) => state.relation === "resource"),
+      neighbors: states.filter((state) => state.relation === "neighbor")
+    };
+  }
+
+  async retry(bookId: number, resourceId: string) {
+    const book = this.accessibleBook(bookId);
+    const manifest = await this.source.manifest(book);
+    if (!manifest.resources.some((resource) => resource.resourceId === resourceId)) throw new NotFoundException("Reading resource not found");
+    await this.cache.remove(book, resourceId);
+    this.enqueuePreparation(book, [resourceId], true);
+    return { bookId, resourceId, state: "pending" as const };
+  }
+
+  private accessibleBook(bookId: number): ReadingBook {
+    if (!Number.isInteger(bookId) || bookId < 1) throw new BadRequestException("Invalid book id");
+    const row = this.database.db
+      .select({ id: books.id, format: books.format, filePath: books.filePath, fileSize: books.fileSize, fileMtime: books.fileMtime })
+      .from(books)
+      .innerJoin(libraries, and(eq(libraries.id, books.libraryId), eq(libraries.enabled, true)))
+      .where(eq(books.id, bookId))
+      .get();
+    if (!row) throw new NotFoundException("Book not found in an accessible library");
+    return row;
+  }
+
+  private async resourceState(book: ReadingBook, resourceId: string) {
+    if (book.format === "pdf" && resourceId === "original") return "ready" as const;
+    return (await this.cache.get(book, resourceId)) ? "ready" as const : "pending" as const;
+  }
+
+  private enqueuePreparation(book: ReadingBook, resourceIds: string[], force = false): void {
+    const pending = resourceIds.filter((id) => force || !this.preparing.has(`${book.id}:${id}`));
+    if (!pending.length) return;
+    const job = this.jobs.create("prepare-reading-window", JSON.stringify({ bookId: book.id, resourceIds: pending }));
+    for (const id of pending) this.preparing.add(`${book.id}:${id}`);
+    setImmediate(async () => {
+      this.jobs.markRunning(job.id, JSON.stringify({ bookId: book.id, resourceIds: pending }));
+      try {
+        for (const resourceId of pending) {
+          const payload = await this.source.resource(book, resourceId);
+          if (payload.data) await this.cache.put(book, resourceId, payload.data);
+        }
+        this.jobs.markSucceeded(job.id, JSON.stringify({ bookId: book.id, prepared: pending }));
+      } catch (error) {
+        this.jobs.markFailed(job.id, error);
+      } finally {
+        for (const id of pending) this.preparing.delete(`${book.id}:${id}`);
+      }
+    });
+  }
+}
+
+function manifestVersionEtag(book: ReadingBook, resourceId: string): string {
+  return `\"${createHash("sha256").update(`${book.id}:${book.fileSize}:${book.fileMtime}:${resourceId}`).digest("base64url")}\"`;
+}
+
+function resolvePosition(locator: string, spine: Array<{ index: number; href: string; resourceId: string }>): number {
+  if (!spine.length) throw new BadRequestException("Book has no readable spine");
+  const direct = spine.findIndex((item) => item.resourceId === locator || item.href === locator);
+  if (direct >= 0) return direct;
+  const numeric = Number(locator.match(/(?:^|:)(\d+)(?:$|:)/)?.[1]);
+  if (Number.isInteger(numeric) && numeric >= 0 && numeric < spine.length) return numeric;
+  throw new BadRequestException("Locator does not identify a readable resource");
+}
+
+function priorityWindow(spine: Array<{ resourceId: string }>, position: number, referenced: string[], radius: number) {
+  const result: Array<{ id: string; distance: number | null }> = [{ id: spine[position].resourceId, distance: 0 }];
+  for (const resourceId of referenced) result.push({ id: resourceId, distance: null });
+  for (let distance = 1; distance <= radius; distance += 1) {
+    if (position - distance >= 0) result.push({ id: spine[position - distance].resourceId, distance: -distance });
+    if (position + distance < spine.length) result.push({ id: spine[position + distance].resourceId, distance });
+  }
+  return result.filter((entry, index) => result.findIndex((candidate) => candidate.id === entry.id) === index);
+}
+
+function referencedResources(currentId: string, resources: Array<{ resourceId: string; references?: string[] }>): string[] {
+  const byId = new Map(resources.map((resource) => [resource.resourceId, resource]));
+  const result: string[] = [];
+  const queue = [...(byId.get(currentId)?.references ?? [])];
+  const seen = new Set([currentId]);
+  while (queue.length) {
+    const resourceId = queue.shift()!;
+    if (seen.has(resourceId)) continue;
+    seen.add(resourceId);
+    result.push(resourceId);
+    queue.push(...(byId.get(resourceId)?.references ?? []));
+  }
+  return result;
+}
+
+function parseByteRange(range: string | undefined, size: number, supported: boolean) {
+  if (!range) return { start: 0, end: Math.max(size - 1, 0), partial: false };
+  if (!supported || size <= 0) throw new HttpException("Requested range not satisfiable", HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE);
+  const match = range.match(/^bytes=(\d*)-(\d*)$/);
+  if (!match) throw new HttpException("Requested range not satisfiable", HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE);
+  const suffix = !match[1] && match[2] ? Number(match[2]) : null;
+  const start = suffix === null ? Number(match[1]) : Math.max(size - suffix, 0);
+  const end = suffix === null && match[2] ? Number(match[2]) : size - 1;
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 0 || end < start || start >= size) {
+    throw new HttpException("Requested range not satisfiable", HttpStatus.REQUESTED_RANGE_NOT_SATISFIABLE);
+  }
+  return { start, end: Math.min(end, size - 1), partial: true };
+}

apps/api/src/reading/reading.types.ts

@@ -0,0 +1,63 @@
+export type ReadingFormat = "epub" | "pdf";
+export type ReadingResourceKind = "chapter" | "image" | "stylesheet" | "font" | "document";
+export type ReadingResourceState = "ready" | "pending" | "unsupported" | "failed";
+
+export type ReadingResource = {
+  resourceId: string;
+  href: string;
+  url: string;
+  kind: ReadingResourceKind;
+  mediaType: string;
+  size: number;
+  state: ReadingResourceState;
+  references?: string[];
+};
+
+export type ReadingSpineItem = {
+  index: number;
+  href: string;
+  resourceId: string;
+  url: string;
+  mediaType: string;
+  size: number;
+};
+
+export type ReadingManifest = {
+  bookId: number;
+  format: ReadingFormat;
+  revision: string;
+  version: string;
+  containerPath: string | null;
+  opfPath: string | null;
+  basePath: string | null;
+  resources: ReadingResource[];
+  spine: ReadingSpineItem[];
+  capabilities: {
+    byteRanges: boolean;
+    derivedImages: boolean;
+    lightweightPages: boolean;
+  };
+};
+
+export type ReadingBook = {
+  id: number;
+  format: string;
+  filePath: string;
+  fileSize: number;
+  fileMtime: string;
+};
+
+export type ReadingResourcePayload = {
+  data?: Buffer;
+  filePath?: string;
+  contentType: string;
+  size: number;
+  etag: string;
+  supportsRanges: boolean;
+};
+
+export type ReadingWindowInput = {
+  locator: string;
+  mode: "auto" | "speed" | "quality";
+  networkHint: "offline" | "slow" | "normal" | "fast" | "unknown";
+};