Names quak builds from server data fit in 255 bytes (closes #205)

The default names of `quak get`, `quak get-thumb`, `downloadFile` and `downloadThumbnail`, and the album folders of `backup-metadata`, could be over 255 bytes, which a file system refuses. `defaultFileName` and `shortenKeepingExtension` in `src/filename.ts` now cut such a name short, keeping its extension when it fits; a live photo's image and video get their own extension before the cut. A cut name never starts with a dot and is never a Windows device name. `--out` and `outPath` are kept as given. A `backup-metadata` folder keeps its `<id>-`. `safeExtension` gives `.bin` for an extension of more than 16 letters and digits, so a save path's name always fits.

Model: opus-5-5

src/backup.ts

@@ -82,6 +82,7 @@ import { describeError } from "./errors.js";
 import {
     MAX_NAME_BYTES,
     sanitizeFileName,
+    shortenKeepingExtension,
     shortenToBytes,
     withExtension,
 } from "./filename.js";
@@ -289,9 +290,10 @@ const rebuildSymlink = (linkPath: string, target: string): void => {
 // case (two names that differ only in case are one entry on a case-insensitive
 // file system), or it is too long for a file name; then it gets ` (<id>)`,
 // right before the extension when `beforeExtension` is set. To fit, the part
-// before the ID is cut short as far as it must be. When the extension alone
-// leaves no room for the ID, the extension is cut short and the part before
-// the ID keeps only the bytes that cut leaves over. With `withJSON`, each
+// before the ID is cut short as far as it must be. When the extension leaves
+// no room for the ID and the first character of the name, the extension is
+// cut short, and the part before the ID keeps that character and any bytes
+// the cut leaves over (see `shortenKeepingExtension`). With `withJSON`, each
 // entry also has the JSON file `<name>.json` beside it, as an album does: a
 // name then leaves room for `.json`, and one that is another entry's JSON name
 // gets its ID added too.
@@ -305,11 +307,9 @@ const uniqueNames = (
     const maxBytes = MAX_NAME_BYTES - (opts.withJSON ? ".json".length : 0);
     const withID = (id: number, name: string): string => {
         const tag = ` (${id})`;
-        const fullExt = opts.beforeExtension ? extname(name) : "";
-        const stem = name.slice(0, name.length - fullExt.length);
-        const ext = shortenToBytes(fullExt, maxBytes - Buffer.byteLength(tag));
-        const room = maxBytes - Buffer.byteLength(tag + ext);
-        return shortenToBytes(stem, room) + tag + ext;
+        return opts.beforeExtension
+            ? shortenKeepingExtension(name, maxBytes, tag)
+            : shortenToBytes(name, maxBytes - Buffer.byteLength(tag)) + tag;
     };
     const names = entries.map((e) => e.name);
     const suffixed = new Set<number>();

src/cli-commands.ts

@@ -332,8 +332,8 @@ export const getCommand = async (
         const result = await photo.original();
         // Default name is the file's own title, as the pre-library CLI used
         // (not the editedName-preferring projection title) (issue #52).
-        const outPath = opts.out ?? originalName(file);
         if (result.videoPath === undefined) {
+            const outPath = opts.out ?? originalName(file);
             copyFileSync(result.path, outPath);
             ctx.stderr.write(`${result.bytes} bytes -> ${outPath}\n`);
             return 0;
@@ -341,9 +341,13 @@ export const getCommand = async (
         // A live photo is written as its image and its video, each named after
         // the title with its own extension, as Ente's clients name them. With
         // --out, the image goes there and the video beside it.
-        const imageOut =
-            opts.out ?? withExtension(outPath, extname(result.path));
-        const videoOut = withExtension(outPath, extname(result.videoPath));
+        const imageExt = extname(result.path);
+        const videoExt = extname(result.videoPath);
+        const imageOut = opts.out ?? originalName(file, imageExt);
+        const videoOut =
+            opts.out === undefined
+                ? originalName(file, videoExt)
+                : withExtension(opts.out, videoExt);
         if (imageOut.toLowerCase() === videoOut.toLowerCase()) {
             ctx.stderr.write(
                 `File ${fileID} is a live photo, and its video would also be written to ${imageOut}\n`,

src/cli-output.ts

@@ -9,7 +9,7 @@
 // `metadata.title`, and issue #52 requires that output stay byte-identical, so
 // the commands shape their output from the raw `EnteFile` through here.
 
-import { sanitizeFileName } from "./filename.js";
+import { defaultFileName } from "./filename.js";
 import type { EnteFile, FileType, Microseconds } from "./model/types.js";
 
 // One row of `quak files --json`.
@@ -33,11 +33,13 @@ export const fileListRow = (file: EnteFile): FileListRow => ({
 export const fileListLine = (file: EnteFile): string =>
     `${file.id}\t${file.metadata.fileType}\t${file.metadata.title}`;
 
-// Default output path for `quak get` when `--out` is not given. The title comes
-// from the server, so it is sanitized; `--out` is the user's and is used as is.
-export const originalName = (file: EnteFile): string =>
-    sanitizeFileName(file.metadata.title, `file-${file.id}`);
+// Default output path for `quak get` when `--out` is not given, made from the
+// title (see `defaultFileName`), with `ext` in place of its extension for a
+// live photo's image or video; `--out` is the user's and is used as is.
+export const originalName = (file: EnteFile, ext?: string): string =>
+    defaultFileName(file.metadata.title, file.id, { ext });
 
-// Default output path for `quak get-thumb` when `--out` is not given.
+// Default output path for `quak get-thumb` when `--out` is not given: `thumb_`
+// and the title.
 export const thumbnailName = (file: EnteFile): string =>
-    `thumb_${originalName(file)}`;
+    defaultFileName(file.metadata.title, file.id, { prefix: "thumb_" });

src/download/index.ts

@@ -16,7 +16,7 @@ import {
     streamTagFinal,
 } from "../crypto/index.js";
 import { TruncatedStreamError } from "../errors.js";
-import { safeExtension, sanitizeFileName, withExtension } from "../filename.js";
+import { defaultFileName, safeExtension, withExtension } from "../filename.js";
 import { withRetry } from "../retry.js";
 import type { ApiClient } from "../api/client.js";
 import type { EnteFile } from "../model/types.js";
@@ -365,10 +365,14 @@ const openPart = async (
 // name starts with `image` as the image and the one whose name starts with
 // `video` as the video, and refuses a ZIP holding a second of either. It is
 // written unpacked: each part is named `destination` with the extension
-// replaced by its own entry's, and the two must differ ignoring case. When the
-// file records a hash, `<imageHash>:<videoHash>` must match it, each over that
-// part's own bytes. Only then are the image, then the video, renamed into
-// place; on any failure neither is stored.
+// replaced by its own entry's, and the two must differ ignoring case. When
+// `defaultName` is set, `destination` is the name `defaultFileName` made from
+// the title rather than a path the caller gave, and each part is named as
+// `defaultFileName` names it with its own extension, so that the name is cut
+// short to fit with that extension. When the file records a hash,
+// `<imageHash>:<videoHash>` must match it, each over that part's own bytes.
+// Only then are the image, then the video, renamed into place; on any failure
+// neither is stored.
 //
 // The ZIP is chosen by its uploader and may expand enormously, so each part is
 // written as it decompresses and never held, and the ZIP is refused once the
@@ -388,6 +392,7 @@ const decryptLivePhoto = async (
     key: Uint8Array,
     onProgress: ProgressCallback | undefined,
     file: EnteFile,
+    defaultName: boolean,
 ): Promise<DownloadResult> => {
     const sliceSize = 4096;
     const dir = dirname(destination);
@@ -486,8 +491,12 @@ const decryptLivePhoto = async (
                 `live photo's image and video have the same extension, ${video.ext}`,
             );
         }
-        const path = withExtension(destination, image.ext);
-        const videoPath = withExtension(destination, video.ext);
+        const partPath = (ext: string): string =>
+            defaultName
+                ? defaultFileName(file.metadata.title, file.id, { ext })
+                : withExtension(destination, ext);
+        const path = partPath(image.ext);
+        const videoPath = partPath(video.ext);
         for (const part of parts) {
             await part.handle.sync();
             await part.handle.close();
@@ -531,6 +540,9 @@ const decryptLivePhoto = async (
 // and then removes its own temp file, and only the attempt that reaches
 // TAG_FINAL renames one into place, so a download that needed three tries still
 // performs exactly one rename over the destination.
+//
+// `defaultName` says `destination` is the name `defaultFileName` made, not a
+// path the caller gave (see `decryptLivePhoto`).
 const fetchAndDecrypt = async (
     api: ApiClient,
     openStream: () => Promise<ReadableStream<Uint8Array>>,
@@ -539,6 +551,7 @@ const fetchAndDecrypt = async (
     destination: string,
     onProgress?: ProgressCallback,
     original?: EnteFile,
+    defaultName = false,
 ): Promise<DownloadResult> =>
     withRetry(async () => {
         const stream = await openStream();
@@ -551,6 +564,7 @@ const fetchAndDecrypt = async (
                     key,
                     onProgress,
                     original,
+                    defaultName,
                 );
             }
             const bytesWritten = await decryptToTemp(
@@ -582,10 +596,11 @@ export const downloadFile = async (
     outPath?: string,
     onProgress?: ProgressCallback,
 ): Promise<DownloadResult> => {
-    // `outPath` is the caller's and is used as is; the title is the server's
-    // and is sanitized so it can only name a file in the current directory.
+    // `outPath` is the caller's and is used as is. Without it, the file is
+    // written in the current directory under the name `defaultFileName` makes
+    // from the title, which is the server's.
     const resolvedPath =
-        outPath ?? sanitizeFileName(file.metadata.title, `file-${file.id}`);
+        outPath ?? defaultFileName(file.metadata.title, file.id);
     const header = fromBase64(file.file.decryptionHeader);
     return fetchAndDecrypt(
         api,
@@ -595,6 +610,7 @@ export const downloadFile = async (
         resolvedPath,
         onProgress,
         file,
+        outPath === undefined,
     );
 };
 
@@ -604,9 +620,10 @@ export const downloadThumbnail = async (
     outPath?: string,
     onProgress?: ProgressCallback,
 ): Promise<DownloadResult> => {
+    // As in `downloadFile`, with `thumb_` before the title.
     const resolvedPath =
         outPath ??
-        `thumb_${sanitizeFileName(file.metadata.title, `file-${file.id}`)}`;
+        defaultFileName(file.metadata.title, file.id, { prefix: "thumb_" });
     const header = fromBase64(file.thumbnail.decryptionHeader);
     return fetchAndDecrypt(
         api,

src/filename.ts

@@ -5,7 +5,9 @@
 // used on disk goes through here, so it can only ever name one file inside the
 // directory the caller chose: never a path, never `..`, never hidden, never a
 // Windows device name. Such a name can still be too long for a file name, and
-// `shortenToBytes` cuts one short.
+// `shortenToBytes` or `shortenKeepingExtension` cuts one short.
+// `defaultFileName` does both for the name a file is saved under when the
+// caller gives no path.
 //
 // A path the user typed (`--out`, `outPath`) is not passed through here: the
 // caller is trusted, the server is not.
@@ -30,11 +32,11 @@ export const sanitizeFileName = (name: string, fallback: string): string => {
     return RESERVED_DEVICE_NAME.test(cleaned) ? `_${cleaned}` : cleaned;
 };
 
-// The extension of `title` (".jpg"), or ".bin" when it has none or it holds
-// anything but letters and digits.
+// The extension of `title` (".jpg"), or ".bin" when it has none, it holds
+// anything but letters and digits, or it is more than 16 of them long.
 export const safeExtension = (title: string): string => {
     const ext = extname(title);
-    return /^\.[A-Za-z0-9]+$/.test(ext) ? ext : ".bin";
+    return /^\.[A-Za-z0-9]{1,16}$/.test(ext) ? ext : ".bin";
 };
 
 // `name` with its extension, if it has one, replaced by `ext` (".mov").
@@ -57,3 +59,53 @@ export const shortenToBytes = (name: string, maxBytes: number): string => {
     }
     return name.slice(0, end);
 };
+
+// `name` cut short to fit in `maxBytes` bytes with `insert` put right before
+// its extension (`IMG_0001 (12).jpg`), each cut made as `shortenToBytes`
+// makes it. The part before the extension is cut first, so the extension is
+// kept whenever it fits, but that part always keeps its first character:
+// when the extension leaves no room for `insert` and that character, the
+// extension is cut short too, and the part before it keeps the bytes that cut
+// leaves over. So a name that does not start with a dot never comes back
+// starting with one, which would hide it. `insert` is never cut. With no
+// `insert`, a name that fits comes back unchanged.
+export const shortenKeepingExtension = (
+    name: string,
+    maxBytes: number,
+    insert = "",
+): string => {
+    const fullExt = extname(name);
+    const stem = name.slice(0, name.length - fullExt.length);
+    const first = Array.from(stem)[0] ?? "";
+    const ext = shortenToBytes(
+        fullExt,
+        maxBytes - Buffer.byteLength(insert + first),
+    );
+    const room = maxBytes - Buffer.byteLength(insert + ext);
+    return shortenToBytes(stem, room) + insert + ext;
+};
+
+// The name a file is saved under in the working directory when the caller
+// gives no path (`quak get` without `--out`, `downloadFile` without
+// `outPath`): `prefix` (`thumb_` for a thumbnail), then the file's title with
+// unsafe characters replaced, or `file-<id>` when the title is empty, cut
+// short so that the whole fits in a file name, keeping the title's extension
+// whenever it fits. `ext` (".mov"), when given, takes the place of the
+// title's extension before the name is cut short; a live photo's image and
+// video are each named with their own. The cut can leave a device name
+// (`CONSOLE.<long extension>` becomes `CON.<long extension>`); that name gets
+// a leading `_`, as `sanitizeFileName` gives one, and is cut a byte shorter to
+// leave room for it.
+export const defaultFileName = (
+    title: string,
+    fileID: number,
+    opts: { prefix?: string; ext?: string } = {},
+): string => {
+    const { prefix = "", ext } = opts;
+    const safe = sanitizeFileName(title, `file-${fileID}`);
+    const name = ext === undefined ? safe : withExtension(safe, ext);
+    const room = MAX_NAME_BYTES - Buffer.byteLength(prefix);
+    const cut = prefix + shortenKeepingExtension(name, room);
+    if (!RESERVED_DEVICE_NAME.test(cut)) return cut;
+    return `_${prefix}${shortenKeepingExtension(name, room - 1)}`;
+};

src/metadata-backup.ts

@@ -5,7 +5,11 @@ import type { Client } from "./client.js";
 import { describeError } from "./errors.js";
 import { readExifTags } from "./exif.js";
 import type { Library, Photo } from "./library/index.js";
-import { sanitizeFileName } from "./filename.js";
+import {
+    MAX_NAME_BYTES,
+    sanitizeFileName,
+    shortenToBytes,
+} from "./filename.js";
 import {
     fetchMLDataBatch,
     MLDATA_BATCH_SIZE,
@@ -127,7 +131,15 @@ export const runMetadataBackup = async (
         const col = lib.getCollection(album.collectionID);
         if (!col) continue;
 
-        const dirName = `${col.id}-${sanitizeFileName(col.name, "unnamed")}`;
+        // The album's ID keeps the folders apart, so the name after it can be
+        // cut short to fit in a file name.
+        const prefix = `${col.id}-`;
+        const dirName =
+            prefix +
+            shortenToBytes(
+                sanitizeFileName(col.name, "unnamed"),
+                MAX_NAME_BYTES - prefix.length,
+            );
         const colDir = join(outDir, "collections", dirName);
         mkdirSync(colDir, { recursive: true });