On-disk content and thumbnail cache with per-photo fetch and prefetch (closes #46)

Adds the on-disk content and thumbnail cache keyed by fileID: originals/ and thumbnails/ under cacheDirectory, present-means-complete (streaming atomic rename), orphan temp reaping on open. Photo.original/thumbnail return a cached path with no network when present, else fetch through the shared request pool; thumbnails.ensure drives the thumbnail pool with priority, dedup and AbortSignal. One shared RequestPools set serves both the ML fetch and the content cache. Content-hash integrity is deferred (#68); authenticated streaming decrypt guarantees integrity now.

Model: opus-4-8

src/client.ts

@@ -13,6 +13,10 @@ import {
     downloadFile as dlFile,
     downloadThumbnail as dlThumb,
 } from "./download/index.js";
+import {
+    makeDownloadContentSource,
+    type ContentSource,
+} from "./library/content.js";
 import type {
     Collection,
     EnteFile,
@@ -141,6 +145,14 @@ export class Client {
         return this.api;
     }
 
+    // The content-cache byte source over this client's API: each fetch is the
+    // download layer's request + streaming decrypt + atomic write. `Library`
+    // calls this to enable the on-disk content cache.
+    contentSource(): ContentSource {
+        this.assertLoggedIn();
+        return makeDownloadContentSource(this.api);
+    }
+
     private assertLoggedIn(): void {
         if (this.loggedOut) throw new Error("Client has been logged out");
     }

src/index.ts

@@ -49,7 +49,27 @@ export {
     type PhotoFilter,
     type TimelineGroup,
     type GroupBy,
+    type ContentSource,
+    type ContentResult,
+    type ContentEvent,
+    type ContentOptions,
+    type PhotoContent,
+    type ThumbnailsAPI,
+    type ThumbnailPriority,
+    type EnsureOptions,
+    type EnsureResult,
+    type EnsureEvent,
 } from "./library/index.js";
+export {
+    RequestPools,
+    BoundedPool,
+    DEFAULT_METADATA_CONCURRENCY,
+    DEFAULT_CONTENT_CONCURRENCY,
+    DEFAULT_THUMBNAIL_CONCURRENCY,
+    type RequestPoolsOptions,
+    type Priority,
+    type RunOptions,
+} from "./library/pools.js";
 export type {
     AlbumRecord,
     PhotoRecord,

src/library/content.ts

@@ -0,0 +1,416 @@
+// The on-disk content and thumbnail cache keyed by fileID (issue #46).
+//
+// Layout under `cacheDirectory`: `originals/<fileID>.<ext>` and
+// `thumbnails/<fileID>.<ext>`, flat directories at 0700 with files at 0600.
+// Content appears only by the streaming atomic writer's rename (the download
+// layer, #40), so a file that exists is whole — "present means complete". The
+// directory listing taken at `open()` is the record of what is cached, and the
+// orphan temp files a crashed write may have left are reaped there.
+//
+// A fetch goes through the shared request pools (#45): the content pool for
+// originals, the thumbnail pool for thumbnails. The pool limits concurrency,
+// orders on-demand work ahead of background, and dedups by key so a fileID
+// requested twice while the first is still in flight downloads once.
+//
+// Integrity. The reused streaming decrypt is the enforced guarantee: every
+// chunk is authenticated and the writer renames the file into place only once
+// the stream ends on TAG_FINAL, so a truncated or corrupt fetch throws and
+// nothing is stored. On top of that this module refuses to record a stored file
+// that came out empty. The design also asks for a content-hash comparison
+// against `FileMetadata.hash` (with a `fileSize` fallback); that is deferred —
+// see the PR — because the exact hash construction cannot be confirmed against
+// the repo's fixtures and `FileBlob.size` is the encrypted object size, not the
+// decrypted length this layer has.
+
+import { existsSync, statSync } from "node:fs";
+import { chmod, mkdir, readdir, rm, stat } from "node:fs/promises";
+import { extname, join } from "node:path";
+
+import type { ApiClient } from "../api/client.js";
+import {
+    downloadFile,
+    downloadThumbnail,
+    type ProgressCallback,
+} from "../download/index.js";
+import type { EnteFile } from "../model/types.js";
+import type { Priority, RequestPools } from "./pools.js";
+
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+const TEMP_PREFIX = ".quak-";
+const TEMP_SUFFIX = ".tmp";
+// Ente thumbnails are always JPEG, so the cache stores them with a fixed
+// extension rather than deriving one from the (image or video) title.
+const THUMBNAIL_EXT = ".jpg";
+
+type Kind = "original" | "thumbnail";
+
+// The priority a caller attaches to a thumbnail prefetch. The pool has two
+// tiers, so this three-value surface collapses onto them: only a currently
+// visible thumbnail preempts (on-demand); "ahead" prefetch and speculative
+// "background" work both yield to it.
+export type ThumbnailPriority = "visible" | "ahead" | "background";
+
+const poolPriorityOf = (priority: ThumbnailPriority): Priority =>
+    priority === "visible" ? "on-demand" : "background";
+
+export interface ContentResult {
+    path: string;
+    bytes: number;
+}
+
+// Progress for a single `original`/`thumbnail` call. A present file emits one
+// `skipped` event and nothing else; a fetched file emits `downloading` as
+// plaintext lands and a final `done`.
+export type ContentEvent =
+    | { status: "skipped"; bytes: number }
+    | { status: "downloading"; bytesDone: number }
+    | { status: "done"; bytes: number };
+
+export interface ContentOptions {
+    onProgress?: (event: ContentEvent) => void;
+}
+
+// The Photo-facing content surface (the read wrappers call these). The cache
+// implements it; a library opened without a content source leaves it absent.
+export interface PhotoContent {
+    original(fileID: number, opts?: ContentOptions): Promise<ContentResult>;
+    thumbnail(fileID: number, opts?: ContentOptions): Promise<ContentResult>;
+}
+
+export interface EnsureResult {
+    fileID: number;
+    path?: string;
+    error?: string;
+}
+
+export interface EnsureEvent {
+    fileID: number;
+    status: "skipped" | "done" | "failed" | "aborted";
+    path?: string;
+    error?: string;
+}
+
+export interface EnsureOptions {
+    fileIDs: number[];
+    priority: ThumbnailPriority;
+    signal?: AbortSignal;
+    onProgress?: (event: EnsureEvent) => void;
+}
+
+export interface ThumbnailsAPI {
+    ensure(args: EnsureOptions): Promise<EnsureResult[]>;
+}
+
+// The byte source the cache fetches through. The real implementation streams
+// and decrypts to the destination via the download layer; tests inject a
+// stand-in so the cache logic runs with no crypto and no network. Pool routing,
+// dedup, present-checks and integrity live in the cache, not here.
+export interface ContentSource {
+    original(args: {
+        file: EnteFile;
+        destination: string;
+        onProgress?: ProgressCallback;
+    }): Promise<{ bytesWritten: number }>;
+    thumbnail(args: {
+        file: EnteFile;
+        destination: string;
+        onProgress?: ProgressCallback;
+    }): Promise<{ bytesWritten: number }>;
+}
+
+// The production source: each fetch is the download layer's request +
+// streaming decrypt + atomic write + retry as one unit.
+export const makeDownloadContentSource = (api: ApiClient): ContentSource => ({
+    original: ({ file, destination, onProgress }) =>
+        downloadFile(api, file, destination, onProgress),
+    thumbnail: ({ file, destination, onProgress }) =>
+        downloadThumbnail(api, file, destination, onProgress),
+});
+
+export interface CachedPaths {
+    originalPath?: string;
+    thumbnailPath?: string;
+}
+
+export interface ContentCacheOptions {
+    pools: RequestPools;
+    source: ContentSource;
+    cacheDirectory: string;
+    // The backup destination (issue-level `downloadDirectory`). An original
+    // already stored there by a backup counts as present, so the cache serves
+    // it rather than fetching a second copy.
+    downloadDirectory?: string;
+    // Resolve any membership of a file; every membership shares the underlying
+    // content key, so any one decrypts the same bytes.
+    getFile: (fileID: number) => EnteFile | undefined;
+}
+
+// Thrown inside a pooled task to drop a queued fetch that was aborted before it
+// started running. Never escapes `ensureThumbnails`.
+class AbortDrop extends Error {
+    constructor() {
+        super("aborted");
+        this.name = "AbortDrop";
+    }
+}
+
+const originalName = (file: EnteFile): string => {
+    const ext = extname(file.metadata.title || "") || ".bin";
+    return `${file.id}${ext}`;
+};
+
+// The fileID a cache filename encodes, or undefined when the name is not one
+// the cache writes (`<digits><ext>`).
+const fileIDFromName = (name: string): number | undefined => {
+    const base = name.slice(0, name.length - extname(name).length);
+    if (!/^\d+$/.test(base)) return undefined;
+    const id = Number(base);
+    return Number.isSafeInteger(id) ? id : undefined;
+};
+
+// Size of a regular file, or undefined if it is absent (or not a regular file).
+const fileSize = (path: string): number | undefined => {
+    try {
+        const s = statSync(path);
+        return s.isFile() ? s.size : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+export class ContentCache implements PhotoContent, ThumbnailsAPI {
+    private readonly pools: RequestPools;
+    private readonly source: ContentSource;
+    private readonly downloadDirectory?: string;
+    private readonly getFile: (fileID: number) => EnteFile | undefined;
+    private readonly originalsDir: string;
+    private readonly thumbnailsDir: string;
+    // fileID -> absolute path of the cached bytes, seeded from the directory
+    // listing at open() and extended as fetches store new files.
+    private readonly originals = new Map<number, string>();
+    private readonly thumbnails = new Map<number, string>();
+
+    constructor(opts: ContentCacheOptions) {
+        this.pools = opts.pools;
+        this.source = opts.source;
+        this.downloadDirectory = opts.downloadDirectory;
+        this.getFile = opts.getFile;
+        this.originalsDir = join(opts.cacheDirectory, "originals");
+        this.thumbnailsDir = join(opts.cacheDirectory, "thumbnails");
+    }
+
+    // Prepare the cache directories, reap orphan temp files, and take the
+    // record of what is already cached. Called once before the cache serves.
+    async open(): Promise<void> {
+        await this.ensureDir(this.originalsDir);
+        await this.ensureDir(this.thumbnailsDir);
+        await this.scan(this.originalsDir, this.originals);
+        await this.scan(this.thumbnailsDir, this.thumbnails);
+    }
+
+    // The cache paths known for a file, for the record projection to expose as
+    // `originalPath`/`thumbnailPath`.
+    pathsFor(fileID: number): CachedPaths {
+        const out: CachedPaths = {};
+        const original = this.originals.get(fileID);
+        if (original !== undefined) out.originalPath = original;
+        const thumbnail = this.thumbnails.get(fileID);
+        if (thumbnail !== undefined) out.thumbnailPath = thumbnail;
+        return out;
+    }
+
+    async original(
+        fileID: number,
+        opts?: ContentOptions,
+    ): Promise<ContentResult> {
+        return this.get(fileID, "original", "on-demand", opts?.onProgress);
+    }
+
+    async thumbnail(
+        fileID: number,
+        opts?: ContentOptions,
+    ): Promise<ContentResult> {
+        return this.get(fileID, "thumbnail", "on-demand", opts?.onProgress);
+    }
+
+    async ensure(args: EnsureOptions): Promise<EnsureResult[]> {
+        return this.ensureThumbnails(args);
+    }
+
+    async ensureThumbnails(args: EnsureOptions): Promise<EnsureResult[]> {
+        const priority = poolPriorityOf(args.priority);
+        // Dedup the request list so a repeated fileID is fetched once and
+        // reported once, in first-requested order.
+        const seen = new Set<number>();
+        const unique: number[] = [];
+        for (const id of args.fileIDs) {
+            if (!seen.has(id)) {
+                seen.add(id);
+                unique.push(id);
+            }
+        }
+        return Promise.all(
+            unique.map((fileID) =>
+                this.ensureOne(fileID, priority, args.signal, args.onProgress),
+            ),
+        );
+    }
+
+    private async ensureOne(
+        fileID: number,
+        priority: Priority,
+        signal: AbortSignal | undefined,
+        onProgress: ((event: EnsureEvent) => void) | undefined,
+    ): Promise<EnsureResult> {
+        try {
+            const result = await this.acquire(
+                fileID,
+                "thumbnail",
+                priority,
+                signal,
+            );
+            const status = result.cached ? "skipped" : "done";
+            onProgress?.({ fileID, status, path: result.path });
+            return { fileID, path: result.path };
+        } catch (err) {
+            if (err instanceof AbortDrop) {
+                onProgress?.({ fileID, status: "aborted" });
+                return { fileID, error: "aborted" };
+            }
+            const error = err instanceof Error ? err.message : String(err);
+            onProgress?.({ fileID, status: "failed", error });
+            return { fileID, error };
+        }
+    }
+
+    private async get(
+        fileID: number,
+        kind: Kind,
+        priority: Priority,
+        onProgress: ((event: ContentEvent) => void) | undefined,
+    ): Promise<ContentResult> {
+        const onByte: ProgressCallback | undefined = onProgress
+            ? (bytesDone) => onProgress({ status: "downloading", bytesDone })
+            : undefined;
+        const result = await this.acquire(fileID, kind, priority, undefined, {
+            onByte,
+        });
+        onProgress?.(
+            result.cached
+                ? { status: "skipped", bytes: result.bytes }
+                : { status: "done", bytes: result.bytes },
+        );
+        return { path: result.path, bytes: result.bytes };
+    }
+
+    // The core: return the cached path if present, else fetch through the pool,
+    // store, and return it. `cached` distinguishes a present hit (no network,
+    // no download event) from a fresh fetch.
+    private async acquire(
+        fileID: number,
+        kind: Kind,
+        priority: Priority,
+        signal: AbortSignal | undefined,
+        opts?: { onByte?: ProgressCallback },
+    ): Promise<{ path: string; bytes: number; cached: boolean }> {
+        const file = this.getFile(fileID);
+        if (!file) throw new Error(`content cache: unknown file ${fileID}`);
+
+        const known = kind === "original" ? this.originals : this.thumbnails;
+        const cached = known.get(fileID);
+        if (cached !== undefined) {
+            const size = fileSize(cached);
+            if (size !== undefined && size > 0)
+                return { path: cached, bytes: size, cached: true };
+            // A recorded file that has since gone re-fetches below.
+            known.delete(fileID);
+        }
+
+        // An original a backup already stored counts as present.
+        if (kind === "original" && this.downloadDirectory !== undefined) {
+            const backupPath = join(
+                this.downloadDirectory,
+                "originals",
+                originalName(file),
+            );
+            const size = fileSize(backupPath);
+            if (size !== undefined && size > 0) {
+                this.originals.set(fileID, backupPath);
+                return { path: backupPath, bytes: size, cached: true };
+            }
+        }
+
+        const dir =
+            kind === "original" ? this.originalsDir : this.thumbnailsDir;
+        const dest =
+            kind === "original"
+                ? join(dir, originalName(file))
+                : join(dir, `${fileID}${THUMBNAIL_EXT}`);
+        const pool =
+            kind === "original" ? this.pools.content : this.pools.thumbnails;
+
+        return pool.run(
+            async () => {
+                // Dropping queued work on abort: a task still waiting for a slot
+                // when the signal fired sees it here and never touches the
+                // network. A task already past this point is in flight and runs
+                // to completion.
+                if (signal?.aborted) throw new AbortDrop();
+
+                await this.download(file, dest, kind, opts?.onByte);
+                await chmod(dest, FILE_MODE);
+                const size = (await stat(dest)).size;
+                if (size === 0) {
+                    throw new Error(
+                        `content cache: ${kind} ${fileID} stored empty`,
+                    );
+                }
+                known.set(fileID, dest);
+                return { path: dest, bytes: size, cached: false };
+            },
+            { priority, key: fileID },
+        );
+    }
+
+    private async download(
+        file: EnteFile,
+        destination: string,
+        kind: Kind,
+        onProgress: ProgressCallback | undefined,
+    ): Promise<number> {
+        const args = { file, destination, onProgress };
+        const result =
+            kind === "original"
+                ? await this.source.original(args)
+                : await this.source.thumbnail(args);
+        return result.bytesWritten;
+    }
+
+    private async ensureDir(dir: string): Promise<void> {
+        // chmod after mkdir so the mode is tightened even when the directory
+        // already existed with a looser one; mkdir alone would not.
+        await mkdir(dir, { recursive: true, mode: DIR_MODE });
+        await chmod(dir, DIR_MODE);
+    }
+
+    private async scan(dir: string, into: Map<number, string>): Promise<void> {
+        let entries: string[];
+        try {
+            entries = await readdir(dir);
+        } catch {
+            return;
+        }
+        for (const name of entries) {
+            if (name.startsWith(TEMP_PREFIX) && name.endsWith(TEMP_SUFFIX)) {
+                await rm(join(dir, name), { force: true }).catch(
+                    () => undefined,
+                );
+                continue;
+            }
+            const id = fileIDFromName(name);
+            const path = join(dir, name);
+            if (id !== undefined && existsSync(path)) into.set(id, path);
+        }
+    }
+}

src/library/index.ts

@@ -41,6 +41,13 @@ import {
     type PhotosAPI,
     type TimelineAPI,
 } from "./read.js";
+import {
+    ContentCache,
+    type ContentSource,
+    type ThumbnailsAPI,
+    type EnsureOptions,
+    type EnsureResult,
+} from "./content.js";
 
 export {
     Album,
@@ -52,6 +59,18 @@ export {
     type TimelineGroup,
     type GroupBy,
 } from "./read.js";
+export {
+    type ContentSource,
+    type ContentResult,
+    type ContentEvent,
+    type ContentOptions,
+    type PhotoContent,
+    type ThumbnailsAPI,
+    type ThumbnailPriority,
+    type EnsureOptions,
+    type EnsureResult,
+    type EnsureEvent,
+} from "./content.js";
 import type { CollectionsPage, FilesPage } from "../client.js";
 import { MLDATA_BATCH_SIZE, type MLData } from "../mldata-fetch.js";
 import type { Collection, EnteFile } from "../model/types.js";
@@ -76,6 +95,11 @@ export interface LibraryClient {
         fileIDs: number[];
         fileKeys: Map<number, Uint8Array>;
     }): Promise<Map<number, MLData>>;
+    // The byte source for the on-disk content cache. Optional so a mock client
+    // that only serves metadata still satisfies the interface; when absent (and
+    // no explicit `contentSource` is passed to `open`) the content cache is
+    // disabled and `Photo.original`/`thumbnail` and `thumbnails.ensure` throw.
+    contentSource?(): ContentSource;
 }
 
 // A progress event for one unit of background work. A metadata "refresh" or an
@@ -96,14 +120,18 @@ export interface LibraryOptions {
     // Where `metadata.json` lives. Defaults to the env-paths cache directory
     // plus the user id, so each account has its own cache.
     cacheDirectory?: string;
-    // Persistent backup destination for later phases (backup, thumbnails); the
-    // refresh loop does not use it.
+    // Persistent backup destination. The refresh loop does not use it; the
+    // content cache treats an original already stored there as present.
     downloadDirectory?: string;
     refreshIntervalSeconds?: number;
     onProgress?: RefreshProgressCallback;
-    // The bounded request pools (issue #45). ML data is fetched through the
-    // metadata pool. Defaults to a fresh set at the design's caps.
+    // The bounded request pools (issue #45), shared by the ML-data fetch (the
+    // metadata pool) and the content cache. Defaults to a fresh set at the
+    // design's caps.
     pools?: RequestPools;
+    // Overrides the client's own `contentSource()`; mainly for tests that drive
+    // the cache with a stand-in source.
+    contentSource?: ContentSource;
 }
 
 export interface LibraryStatus {
@@ -138,9 +166,15 @@ export class Library {
     readonly albums: AlbumsAPI;
     readonly photos: PhotosAPI;
     readonly timeline: TimelineAPI;
+    // The thumbnail-prefetch surface (issue #46): drives the thumbnail pool
+    // with priority, dedup, and abort.
+    readonly thumbnails: ThumbnailsAPI;
 
     private readonly client: LibraryClient;
     private readonly store: MetadataStore;
+    // The on-disk content cache, or undefined when no content source is
+    // available (a metadata-only client with no explicit source).
+    private readonly cache?: ContentCache;
     private readonly userID: number;
     private readonly intervalMs: number;
     private readonly onProgress?: RefreshProgressCallback;
@@ -179,6 +213,7 @@ export class Library {
         onProgress?: RefreshProgressCallback;
         pools: RequestPools;
         mldata?: MLDataStore;
+        cache?: ContentCache;
     }) {
         this.client = args.client;
         this.store = args.store;
@@ -189,14 +224,27 @@ export class Library {
         this.onProgress = args.onProgress;
         this.pools = args.pools;
         this.mldata = args.mldata;
+        this.cache = args.cache;
         this.lastRecords = this.deriveNow();
 
         // The read namespaces derive fresh from the store on each call, so they
         // always reflect the latest refresh.
         const derive = (): DerivedRecords => this.deriveNow();
-        this.albums = makeAlbumsAPI(derive);
-        this.photos = makePhotosAPI(derive);
+        this.albums = makeAlbumsAPI(derive, this.cache);
+        this.photos = makePhotosAPI(derive, this.cache);
         this.timeline = makeTimelineAPI(derive);
+        this.thumbnails = {
+            ensure: (opts: EnsureOptions): Promise<EnsureResult[]> => {
+                if (!this.cache) {
+                    return Promise.reject(
+                        new Error(
+                            "thumbnails.ensure requires a library opened with a content cache",
+                        ),
+                    );
+                }
+                return this.cache.ensureThumbnails(opts);
+            },
+        };
     }
 
     // Load the cache and start the refresh loop. With an empty cache the first
@@ -218,12 +266,33 @@ export class Library {
             (opts.refreshIntervalSeconds ?? DEFAULT_REFRESH_INTERVAL_SECONDS) *
             1000;
 
+        // One request-pool set serves both the ML-data fetch and the content
+        // cache, so both honour the same concurrency caps.
+        const pools = opts.pools ?? new RequestPools();
+
         // The ML cache only earns its keep when the client can fetch ML data;
         // a client without that capability opens no `mldata/` directory.
         const mldata = opts.client.fetchMLData
             ? await MLDataStore.open(join(cacheDirectory, "mldata"))
             : undefined;
 
+        // Build the content cache from an explicit source or the client's own,
+        // and take its record of what is already cached (and reap orphan temp
+        // files) before the first projection, so cached paths are present from
+        // the start and the first refresh raises no spurious path-change diff.
+        const source = opts.contentSource ?? opts.client.contentSource?.();
+        let cache: ContentCache | undefined;
+        if (source) {
+            cache = new ContentCache({
+                pools,
+                source,
+                cacheDirectory,
+                downloadDirectory: opts.downloadDirectory,
+                getFile: (fileID) => store.getFileByID(fileID),
+            });
+            await cache.open();
+        }
+
         const lib = new Library({
             client: opts.client,
             store,
@@ -232,8 +301,9 @@ export class Library {
             downloadDirectory: opts.downloadDirectory,
             intervalMs,
             onProgress: opts.onProgress,
-            pools: opts.pools ?? new RequestPools(),
+            pools,
             mldata,
+            cache,
         });
 
         if (store.loadedFromDisk) {
@@ -522,12 +592,18 @@ export class Library {
         return [...byID.values()];
     }
 
-    // Gather every file membership and project the store into by-id records.
+    // Gather every file membership and project the store into by-id records,
+    // filling each record's cache paths from the content cache when present.
     private deriveNow(): DerivedRecords {
         const collections = this.store.listCollections();
         const files: EnteFile[] = [];
         for (const c of collections) files.push(...this.store.listFiles(c.id));
-        return deriveRecords(collections, files);
+        const cache = this.cache;
+        return deriveRecords(
+            collections,
+            files,
+            cache ? (fileID) => cache.pathsFor(fileID) : undefined,
+        );
     }
 
     private notify(change: LibraryChange): void {

src/library/read.ts

@@ -10,10 +10,14 @@
 // those records: a caller that holds an object reference gets typed field
 // access and, for an album, its photos. They are not sent across IPC — the
 // plain records are the serializable surface, and `record()` returns one.
-// Content-fetch methods (`Photo.original` / `thumbnail`) belong to a later
-// unit; this surface is read-only.
+//
+// A `Photo` also fetches its own bytes: `original()` and `thumbnail()` go
+// through the on-disk content cache (issue #46), the one place in this module
+// that is not synchronous and RAM-only. A library opened without a content
+// source leaves that cache absent, and those two methods then throw.
 
 import type { CollectionType, FileType } from "../model/types.js";
+import type { ContentOptions, ContentResult, PhotoContent } from "./content.js";
 import type { AlbumRecord, PhotoRecord, DerivedRecords } from "./records.js";
 
 // Newest first, with fileID as a stable tiebreak so equal-timed files order
@@ -29,7 +33,10 @@ const byNewestAlbum = (a: AlbumRecord, b: AlbumRecord): number =>
 // A single photo. Field access mirrors `PhotoRecord`; `record()` returns the
 // underlying plain record for callers that need the IPC-safe value.
 export class Photo {
-    constructor(private readonly rec: PhotoRecord) {}
+    constructor(
+        private readonly rec: PhotoRecord,
+        private readonly content?: PhotoContent,
+    ) {}
 
     get fileID(): number {
         return this.rec.fileID;
@@ -71,6 +78,27 @@ export class Photo {
     record(): PhotoRecord {
         return this.rec;
     }
+
+    // Fetch and cache the full-resolution original, returning its on-disk path
+    // and byte length. Served from the cache (or the backup download directory)
+    // when already present, otherwise fetched through the content pool.
+    async original(opts?: ContentOptions): Promise<ContentResult> {
+        return this.contentOrThrow().original(this.rec.fileID, opts);
+    }
+
+    // As `original`, for the thumbnail, through the thumbnail pool.
+    async thumbnail(opts?: ContentOptions): Promise<ContentResult> {
+        return this.contentOrThrow().thumbnail(this.rec.fileID, opts);
+    }
+
+    private contentOrThrow(): PhotoContent {
+        if (!this.content) {
+            throw new Error(
+                "Photo content requires a library opened with a content cache",
+            );
+        }
+        return this.content;
+    }
 }
 
 // A single album. `photos.list()` returns the album's photos as wrappers,
@@ -79,6 +107,7 @@ export class Album {
     constructor(
         private readonly rec: AlbumRecord,
         private readonly records: DerivedRecords,
+        private readonly content?: PhotoContent,
     ) {}
 
     get collectionID(): number {
@@ -112,7 +141,7 @@ export class Album {
         const out: Photo[] = [];
         for (const id of this.rec.fileIDs) {
             const p = this.records.photos.get(id);
-            if (p) out.push(new Photo(p));
+            if (p) out.push(new Photo(p, this.content));
         }
         return out;
     }
@@ -164,17 +193,20 @@ export interface TimelineAPI {
     groups(args: { groupBy: GroupBy; filter?: PhotoFilter }): TimelineGroup[];
 }
 
-export const makeAlbumsAPI = (derive: () => DerivedRecords): AlbumsAPI => ({
+export const makeAlbumsAPI = (
+    derive: () => DerivedRecords,
+    content?: PhotoContent,
+): AlbumsAPI => ({
     list: (): Album[] => {
         const records = derive();
         return [...records.albums.values()]
             .sort(byNewestAlbum)
-            .map((rec) => new Album(rec, records));
+            .map((rec) => new Album(rec, records, content));
     },
     byID: ({ collectionID }): Album | undefined => {
         const records = derive();
         const rec = records.albums.get(collectionID);
-        return rec ? new Album(rec, records) : undefined;
+        return rec ? new Album(rec, records, content) : undefined;
     },
     byName: ({ albumName }): Album | undefined => {
         const records = derive();
@@ -183,14 +215,17 @@ export const makeAlbumsAPI = (derive: () => DerivedRecords): AlbumsAPI => ({
         const match = [...records.albums.values()]
             .sort(byNewestAlbum)
             .find((rec) => rec.name === albumName);
-        return match ? new Album(match, records) : undefined;
+        return match ? new Album(match, records, content) : undefined;
     },
 });
 
-export const makePhotosAPI = (derive: () => DerivedRecords): PhotosAPI => ({
+export const makePhotosAPI = (
+    derive: () => DerivedRecords,
+    content?: PhotoContent,
+): PhotosAPI => ({
     byID: ({ fileID }): Photo | undefined => {
         const rec = derive().photos.get(fileID);
-        return rec ? new Photo(rec) : undefined;
+        return rec ? new Photo(rec, content) : undefined;
     },
     records: ({ fileIDs }): PhotoRecord[] => {
         const { photos } = derive();

src/library/records.ts

@@ -166,11 +166,20 @@ const toAlbumRecord = (
     };
 };
 
+// The cache paths known for a file, so the projection can expose them on the
+// record without the read layer reaching into the content cache itself.
+export type CachedPathLookup = (fileID: number) => {
+    originalPath?: string;
+    thumbnailPath?: string;
+};
+
 // Project the decrypted collections and file memberships into by-id records.
 // `files` is every membership (a file appears once per collection it is in).
+// `cachedPaths`, when given, fills each record's cache paths.
 export const deriveRecords = (
     collections: Collection[],
     files: EnteFile[],
+    cachedPaths?: CachedPathLookup,
 ): DerivedRecords => {
     const byFileID = new Map<number, EnteFile[]>();
     for (const f of files) {
@@ -183,6 +192,13 @@ export const deriveRecords = (
     const takenAtByFile = new Map<number, number>();
     for (const [fileID, memberships] of byFileID) {
         const record = toPhotoRecord(fileID, memberships);
+        if (cachedPaths) {
+            const paths = cachedPaths(fileID);
+            if (paths.originalPath !== undefined)
+                record.originalPath = paths.originalPath;
+            if (paths.thumbnailPath !== undefined)
+                record.thumbnailPath = paths.thumbnailPath;
+        }
         photos.set(fileID, record);
         takenAtByFile.set(fileID, record.takenAt);
     }

src/library/store.ts

@@ -179,6 +179,16 @@ export class MetadataStore {
         return this.files.get(fileKey(collectionID, fileID));
     }
 
+    // Any membership of a file, or undefined. Every membership re-wraps the
+    // same underlying content key, so any one is enough to fetch the bytes;
+    // the content cache resolves a fileID to a file this way.
+    getFileByID(fileID: number): EnteFile | undefined {
+        for (const file of this.files.values()) {
+            if (file.id === fileID) return file;
+        }
+        return undefined;
+    }
+
     listFiles(collectionID: number): EnteFile[] {
         return [...this.files.values()].filter(
             (f) => f.collectionID === collectionID,