Store live photos as their image and their video (closes #107)

A live photo, which Ente stores as one ZIP, is unpacked as it downloads
into its image and its video, each `<fileID>.<ext>` with its extension
from the ZIP, beside `<fileID>.livephoto.json`, which names the two.
Both are checked against the recorded hash and renamed into place only
when both are complete. A ZIP with a second image or video, or whose
parts come to more than 20 times its size plus 16 MiB, is refused. The
backup and the content cache count a live photo as stored only with both
files, album folders link both, `quak get` writes both, and the content
result gives the video as `videoPath`. A ZIP an earlier version stored
is replaced.

Model: opus-5-5

src/library/content.ts

@@ -1,11 +1,13 @@
 // 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.
+// `thumbnails/<fileID>.<ext>`, flat directories at 0700 with files at 0600. A
+// live photo's original is two files, its image and its video, with
+// `originals/<fileID>.livephoto.json` naming them. 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,
@@ -22,7 +24,14 @@
 // does; thumbnails have none. On top of that this module refuses to record a
 // stored file that came out empty.
 
-import { existsSync, statSync } from "node:fs";
+import {
+    closeSync,
+    existsSync,
+    openSync,
+    readFileSync,
+    readSync,
+    statSync,
+} from "node:fs";
 import {
     chmod,
     mkdir,
@@ -32,7 +41,7 @@ import {
     statfs,
     utimes,
 } from "node:fs/promises";
-import { dirname, extname, join } from "node:path";
+import { basename, dirname, extname, join } from "node:path";
 
 import type { ApiClient } from "../api/client.js";
 import {
@@ -40,6 +49,7 @@ import {
     downloadThumbnail,
     type ProgressCallback,
     removeLeftoverTempFiles,
+    writeAtomic,
 } from "../download/index.js";
 import { safeExtension } from "../filename.js";
 import type { EnteFile } from "../model/types.js";
@@ -77,6 +87,8 @@ const poolPriorityOf = (priority: ThumbnailPriority): Priority =>
 export interface ContentResult {
     path: string;
     bytes: number;
+    // A live photo's video. `path` and `bytes` are then its image's.
+    videoPath?: string;
 }
 
 // Progress for a single `original`/`thumbnail` call. A present file emits one
@@ -127,11 +139,14 @@ export interface ThumbnailsAPI {
 // 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 {
+    // Writes the original at `destination`. A live photo is written beside it
+    // as its image and its video instead, and their paths are returned, as
+    // `downloadFile` does.
     original(args: {
         file: EnteFile;
         destination: string;
         onProgress?: ProgressCallback;
-    }): Promise<{ bytesWritten: number }>;
+    }): Promise<{ bytesWritten: number; path?: string; videoPath?: string }>;
     thumbnail(args: {
         file: EnteFile;
         destination: string;
@@ -209,7 +224,9 @@ class AbortDrop extends Error {
     }
 }
 
-const originalName = (file: EnteFile): string =>
+// The name of a file's original in originals/: `<fileID><ext>`, the extension
+// taken from the title (or `.bin`). A backup names its originals the same way.
+export const nameInOriginals = (file: EnteFile): string =>
     `${file.id}${safeExtension(file.metadata.title)}`;
 
 // The fileID a cache filename encodes, or undefined when the name is not one
@@ -231,6 +248,92 @@ const fileSize = (path: string): number | undefined => {
     }
 };
 
+// Whether `path` is a regular file with content. A zero-byte file is the shape
+// an aborted write leaves, so it does not count.
+const hasContent = (path: string | undefined): boolean =>
+    path !== undefined && (fileSize(path) ?? 0) > 0;
+
+// Whether the file at `path` begins as a ZIP does, with `PK\x03\x04`. False
+// when it cannot be read.
+const isZip = (path: string): boolean => {
+    try {
+        const fd = openSync(path, "r");
+        try {
+            const head = Buffer.alloc(4);
+            return (
+                readSync(fd, head, 0, 4, 0) === 4 &&
+                head.toString("latin1") === "PK\x03\x04"
+            );
+        } finally {
+            closeSync(fd);
+        }
+    } catch {
+        return false;
+    }
+};
+
+// A live photo's image and video are named with the extensions from inside its
+// ZIP, so their names alone do not say which is which. Wherever the cache or a
+// backup stores one, a JSON file of this name beside them names both.
+const livePhotoJSONName = (fileID: number): string =>
+    `${fileID}.livephoto.json`;
+
+// The image and video that the live photo's JSON file in `dir` names, or
+// undefined when there is none. Only names of the form the cache writes are
+// taken, so the file cannot point outside `dir`.
+const readLivePhotoJSON = (
+    dir: string,
+    fileID: number,
+): { path: string; videoPath: string } | undefined => {
+    const valid = (name: unknown): name is string =>
+        typeof name === "string" && name === `${fileID}${safeExtension(name)}`;
+    try {
+        const { image, video } = JSON.parse(
+            readFileSync(join(dir, livePhotoJSONName(fileID)), "utf-8"),
+        );
+        if (valid(image) && valid(video)) {
+            return { path: join(dir, image), videoPath: join(dir, video) };
+        }
+    } catch {
+        // No such file, or not one the cache wrote.
+    }
+    return undefined;
+};
+
+// Write the JSON file naming a live photo's image and video, both in `dir`.
+export const writeLivePhotoJSON = (
+    dir: string,
+    fileID: number,
+    stored: { path: string; videoPath: string },
+): Promise<void> =>
+    writeAtomic(
+        join(dir, livePhotoJSONName(fileID)),
+        new TextEncoder().encode(
+            JSON.stringify({
+                image: basename(stored.path),
+                video: basename(stored.videoPath),
+            }),
+        ),
+    );
+
+// The original of `file` as the cache or a backup stored it in `dir`, when all
+// of it is there: `<fileID><ext>`, or a live photo's image and video.
+export const storedOriginal = (
+    dir: string,
+    file: EnteFile,
+): { path: string; videoPath?: string } | undefined => {
+    if (file.metadata.fileType !== "livePhoto") {
+        const path = join(dir, nameInOriginals(file));
+        return hasContent(path) ? { path } : undefined;
+    }
+    const stored = readLivePhotoJSON(dir, file.id);
+    return stored !== undefined &&
+        hasContent(stored.path) &&
+        hasContent(stored.videoPath)
+        ? stored
+        : undefined;
+};
+
 export class ContentCache implements PhotoContent, ThumbnailsAPI {
     private readonly pools: RequestPools;
     private readonly source: ContentSource;
@@ -238,10 +341,17 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
     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>();
+    // fileID -> absolute path of the cached bytes, and for a live photo's
+    // original its video's, seeded from the directory listing at open() and
+    // extended as fetches store new files.
+    private readonly originals = new Map<
+        number,
+        { path: string; videoPath?: string }
+    >();
+    private readonly thumbnails = new Map<
+        number,
+        { path: string; videoPath?: string }
+    >();
     private readonly maxOriginalsBytes: number;
     private readonly freeBelowBytes: number;
     private readonly isPinned: (fileID: number) => boolean;
@@ -277,11 +387,15 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
 
     // 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> {
+    // `isLivePhoto` says which files are live photos, whose original is only
+    // the image and video their JSON file names.
+    async open(
+        isLivePhoto: (fileID: number) => boolean = () => false,
+    ): 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);
+        await this.scan(this.originalsDir, this.originals, isLivePhoto);
+        await this.scan(this.thumbnailsDir, this.thumbnails, () => false);
         // Publish the current usage and limit without evicting; a restart
         // reuses whatever survived on disk. Eviction only ever fires on a write.
         await this.refreshOriginalsLimit();
@@ -301,9 +415,9 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
     pathsFor(fileID: number): CachedPaths {
         const out: CachedPaths = {};
         const original = this.originals.get(fileID);
-        if (original !== undefined) out.originalPath = original;
+        if (original !== undefined) out.originalPath = original.path;
         const thumbnail = this.thumbnails.get(fileID);
-        if (thumbnail !== undefined) out.thumbnailPath = thumbnail;
+        if (thumbnail !== undefined) out.thumbnailPath = thumbnail.path;
         return out;
     }
 
@@ -335,7 +449,11 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
             undefined,
             { destination },
         );
-        return { path: result.path, bytes: result.bytes };
+        return {
+            path: result.path,
+            bytes: result.bytes,
+            videoPath: result.videoPath,
+        };
     }
 
     async ensure(args: EnsureOptions): Promise<EnsureResult[]> {
@@ -434,52 +552,72 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
                 ? { status: "skipped", bytes: result.bytes }
                 : { status: "done", bytes: result.bytes },
         );
-        return { path: result.path, bytes: result.bytes };
+        return {
+            path: result.path,
+            bytes: result.bytes,
+            videoPath: result.videoPath,
+        };
     }
 
     // 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. A fetched original is stored at
-    // `opts.destination` when given, instead of in `originalsDir`.
+    // `opts.destination` when given, instead of in `originalsDir`. A live
+    // photo's original is present only with its video, and is returned with
+    // it.
     private async acquire(
         fileID: number,
         kind: Kind,
         priority: Priority,
         signal: AbortSignal | undefined,
         opts?: { onByte?: ProgressCallback; destination?: string },
-    ): Promise<{ path: string; bytes: number; cached: boolean }> {
+    ): Promise<{
+        path: string;
+        bytes: number;
+        videoPath?: string;
+        cached: boolean;
+    }> {
         const file = this.getFile(fileID);
         if (!file) throw new Error(`content cache: unknown file ${fileID}`);
+        const isLivePhoto =
+            kind === "original" && file.metadata.fileType === "livePhoto";
 
         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) {
+            const size = fileSize(cached.path);
+            if (
+                size !== undefined &&
+                size > 0 &&
+                (!isLivePhoto || hasContent(cached.videoPath))
+            ) {
                 // Returning an original's path is a use: bump its mtime so LRU
                 // order reflects it and survives a restart with no ledger.
                 if (
                     kind === "original" &&
-                    dirname(cached) === this.originalsDir
+                    dirname(cached.path) === this.originalsDir
                 )
-                    await this.touch(cached);
-                return { path: cached, bytes: size, cached: true };
+                    await this.touch(cached.path);
+                return { ...cached, bytes: size, cached: true };
             }
-            // A recorded file that has since gone re-fetches below.
+            // A recorded file that has since gone, or a live photo an earlier
+            // version stored as one ZIP, 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 stored = storedOriginal(
+                join(this.downloadDirectory, "originals"),
+                file,
             );
-            const size = fileSize(backupPath);
-            if (size !== undefined && size > 0) {
-                this.originals.set(fileID, backupPath);
-                return { path: backupPath, bytes: size, cached: true };
+            if (stored !== undefined) {
+                this.originals.set(fileID, stored);
+                return {
+                    ...stored,
+                    bytes: fileSize(stored.path) ?? 0,
+                    cached: true,
+                };
             }
         }
 
@@ -487,7 +625,7 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
             kind === "original" ? this.originalsDir : this.thumbnailsDir;
         const dest =
             kind === "original"
-                ? (opts?.destination ?? join(dir, originalName(file)))
+                ? (opts?.destination ?? join(dir, nameInOriginals(file)))
                 : join(dir, `${fileID}${THUMBNAIL_EXT}`);
         const pool =
             kind === "original" ? this.pools.content : this.pools.thumbnails;
@@ -508,21 +646,39 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
                         ? this.beginOriginalWrite(fileID)
                         : null;
                 try {
-                    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`,
-                        );
+                    const stored = await this.download(
+                        file,
+                        dest,
+                        kind,
+                        opts?.onByte,
+                    );
+                    for (const path of [stored.path, stored.videoPath]) {
+                        if (path === undefined) continue;
+                        await chmod(path, FILE_MODE);
+                        if ((await stat(path)).size === 0) {
+                            throw new Error(
+                                `content cache: ${kind} ${fileID} stored empty`,
+                            );
+                        }
                     }
-                    known.set(fileID, dest);
+                    // A backup records its own live photos.
+                    if (
+                        stored.videoPath !== undefined &&
+                        opts?.destination === undefined
+                    ) {
+                        await writeLivePhotoJSON(dir, fileID, {
+                            path: stored.path,
+                            videoPath: stored.videoPath,
+                        });
+                    }
+                    known.set(fileID, stored);
                     // A fresh original may have crossed the limit; make room by
                     // evicting least-recently-used originals. An over-budget
                     // fetch keeps the file it returns, and no overlapping
                     // sibling is evicted. Thumbnails are never bounded.
                     if (write) await this.enforceOriginalsLimit(write);
-                    return { path: dest, bytes: size, cached: false };
+                    const size = (await stat(stored.path)).size;
+                    return { ...stored, bytes: size, cached: false };
                 } finally {
                     if (write) this.inFlightOriginals.delete(write);
                 }
@@ -531,18 +687,24 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
         );
     }
 
+    // Fetch into `destination`, returning where the bytes landed: there, or
+    // for a live photo, its image and video beside it.
     private async download(
         file: EnteFile,
         destination: string,
         kind: Kind,
         onProgress: ProgressCallback | undefined,
-    ): Promise<number> {
+    ): Promise<{ path: string; videoPath?: string }> {
         const args = { file, destination, onProgress };
-        const result =
-            kind === "original"
-                ? await this.source.original(args)
-                : await this.source.thumbnail(args);
-        return result.bytesWritten;
+        if (kind === "thumbnail") {
+            await this.source.thumbnail(args);
+            return { path: destination };
+        }
+        const result = await this.source.original(args);
+        return {
+            path: result.path ?? destination,
+            videoPath: result.videoPath,
+        };
     }
 
     // Best-effort bump of a file's mtime to now; a failed touch must never fail
@@ -553,13 +715,14 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
     }
 
     // Every stored original that lives under `originalsDir` (a backup-directory
-    // hit recorded in the map is excluded), with its size and mtime. Entries
-    // whose file has vanished are dropped from the map. Backups and thumbnails
-    // are never counted.
+    // hit recorded in the map is excluded), with its size and mtime; a live
+    // photo's size includes its video. Entries whose file has vanished are
+    // dropped from the map. Backups and thumbnails are never counted.
     private async measureOriginals(): Promise<{
         entries: {
             fileID: number;
             path: string;
+            videoPath?: string;
             size: number;
             mtimeMs: number;
         }[];
@@ -568,21 +731,28 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
         const entries: {
             fileID: number;
             path: string;
+            videoPath?: string;
             size: number;
             mtimeMs: number;
         }[] = [];
         let used = 0;
-        for (const [fileID, path] of this.originals) {
+        for (const [fileID, { path, videoPath }] of this.originals) {
             if (dirname(path) !== this.originalsDir) continue;
             try {
                 const s = await stat(path);
+                const size =
+                    s.size +
+                    (videoPath === undefined
+                        ? 0
+                        : (await stat(videoPath)).size);
                 entries.push({
                     fileID,
                     path,
-                    size: s.size,
+                    videoPath,
+                    size,
                     mtimeMs: s.mtimeMs,
                 });
-                used += s.size;
+                used += size;
             } catch {
                 this.originals.delete(fileID);
             }
@@ -646,6 +816,18 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
                 for (const e of evictable) {
                     if (remaining <= limit) break;
                     await rm(e.path, { force: true });
+                    // A live photo goes whole: its video and the JSON file
+                    // naming the two go with its image.
+                    if (e.videoPath !== undefined) {
+                        await rm(e.videoPath, { force: true });
+                        await rm(
+                            join(
+                                this.originalsDir,
+                                livePhotoJSONName(e.fileID),
+                            ),
+                            { force: true },
+                        );
+                    }
                     this.originals.delete(e.fileID);
                     remaining -= e.size;
                 }
@@ -670,7 +852,11 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
         await chmod(dir, DIR_MODE);
     }
 
-    private async scan(dir: string, into: Map<number, string>): Promise<void> {
+    private async scan(
+        dir: string,
+        into: Map<number, { path: string; videoPath?: string }>,
+        isLivePhoto: (fileID: number) => boolean,
+    ): Promise<void> {
         // Another process sharing this cache may still be writing its temp
         // files, so only those whose process has exited are removed.
         removeLeftoverTempFiles(dir);
@@ -680,10 +866,29 @@ export class ContentCache implements PhotoContent, ThumbnailsAPI {
         } catch {
             return;
         }
+        const names = new Set(entries);
         for (const name of entries) {
             const id = fileIDFromName(name);
             const path = join(dir, name);
-            if (id !== undefined && existsSync(path)) into.set(id, path);
+            if (id === undefined || !existsSync(path)) continue;
+            // A live photo's image and video are one entry, as the JSON file
+            // beside them names them. A live photo's file with no such JSON
+            // file is not its original. If it is a ZIP, it is the one an
+            // earlier version stored under the image's name, and is removed.
+            // Any other is left alone: another process may have just stored
+            // it and not yet written the JSON file.
+            const livePhoto = names.has(livePhotoJSONName(id))
+                ? readLivePhotoJSON(dir, id)
+                : undefined;
+            if (livePhoto !== undefined) {
+                into.set(id, livePhoto);
+            } else if (isLivePhoto(id)) {
+                if (isZip(path)) {
+                    await rm(path, { force: true }).catch(() => undefined);
+                }
+            } else {
+                into.set(id, { path });
+            }
         }
     }
 }

src/library/index.ts

@@ -397,7 +397,8 @@ export class Library {
                 originalsDays: opts.precacheOriginalsDays,
                 onEvent: opts.onProgress,
             });
-            precache.update(deriveRecordsFromStore(store));
+            const records = deriveRecordsFromStore(store);
+            precache.update(records);
             const extraPinned = opts.isOriginalPinned;
             cache = new ContentCache({
                 pools,
@@ -411,7 +412,12 @@ export class Library {
                     precache!.isPinned(fileID) ||
                     (extraPinned?.(fileID) ?? false),
             });
-            await cache.open();
+            // The records say at once which files are live photos, where
+            // `getFileByID` would search every file for each one cached.
+            await cache.open(
+                (fileID) =>
+                    records.photos.get(fileID)?.fileType === "livePhoto",
+            );
             precache.bind(cache);
         }
 

src/library/read.ts

@@ -80,7 +80,8 @@ export class Photo {
     }
 
     // Fetch and cache the full-resolution original, returning its on-disk path
-    // and byte length. Served from the cache (or the backup download directory)
+    // and byte length; for a live photo, its image's, and its video's path as
+    // `videoPath`. 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);

src/library/records.ts

@@ -42,6 +42,7 @@ export interface PhotoRecord {
     isArchived: boolean;
     isHidden: boolean;
     // Local cache paths, set once a later phase caches the bytes; unset here.
+    // A live photo's `originalPath` is its image.
     thumbnailPath?: string;
     originalPath?: string;
 }