Compare commits
3
Commits
v1.0.0-rc1
...
4388e799db
| Author | SHA1 | Date | |
|---|---|---|---|
 sneak
|
4388e799db | ||
 clawbot
|
d016dbfaa7 | ||
|
clawbot
|
5a940d4e4e |
@@ -19,6 +19,10 @@ encrypting and uploading them back to the server.
|
||||
|
||||
## Getting Started
|
||||
|
||||
The commands below need git, node 22 or later, and yarn. `make install`, which
|
||||
builds the single binary that "Running the backup from cron" uses, also needs
|
||||
[nix](https://nixos.org/download).
|
||||
|
||||
```bash
|
||||
git clone https://git.eeqj.de/sneak/quak.git
|
||||
cd quak
|
||||
@@ -86,9 +90,12 @@ enumeration/download calls) is exported too and documented under Design below.
|
||||
## Running the backup from cron
|
||||
|
||||
`quak backup` never prompts, so cron can run it. `make install` builds quak as a
|
||||
single binary and copies it to `~/bin/quak`. Log in once with it, as the user
|
||||
the cron job will run as; the session is saved in that user's data directory
|
||||
(see "Session handling"):
|
||||
single binary and copies it to `~/bin/quak`. Besides what Getting Started needs,
|
||||
it needs [nix](https://nixos.org/download), even where bun is already installed:
|
||||
`make install` runs `make build-bin`, which bundles the built `dist/` with bun
|
||||
run through `nix-shell -p bun`. Log in once with `~/bin/quak`, as the user the
|
||||
cron job will run as; the session is saved in that user's data directory (see
|
||||
"Session handling"):
|
||||
|
||||
```bash
|
||||
~/bin/quak login
|
||||
@@ -127,12 +134,24 @@ matters.
|
||||
|
||||
### Exit codes
|
||||
|
||||
| Code | Meaning |
|
||||
| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `0` | The backup is complete: every original is at its save path, and no file failed. |
|
||||
| `1` | The run finished with files in `failures.json` or an album it could not decrypt, or it stopped on another error, printed as one line `quak: <message>`. The next run tries again. |
|
||||
| `2` | Another backup of the same directory is running. This run sent no request and changed nothing. |
|
||||
| `3` | There is no usable session: none is saved, the saved one is corrupt, or the server no longer accepts it. Run `quak login` as the user the cron job runs as. |
|
||||
| Code | Meaning |
|
||||
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `0` | The backup is complete: every original is at its save path, and no file failed. |
|
||||
| `1` | The run finished with files in `failures.json` or albums it could not decrypt or write (see "Backup layout"), or it stopped on another error, printed as one line `quak: <message>`. The next run tries again. |
|
||||
| `2` | Another backup of the same directory is running. This run sent no request and changed nothing. |
|
||||
| `3` | There is no usable session: none is saved, the saved one is corrupt, or the server no longer accepts it. Run `quak login` as the user the cron job runs as. |
|
||||
|
||||
`<message>` is the error's message, followed by the message of each error that
|
||||
caused it. Under Node, as `yarn quak` runs quak, `fetch` reports every failure
|
||||
below HTTP as just `fetch failed` and gives the reason as its cause, so a run
|
||||
that could not reach the server prints, for example,
|
||||
`quak: fetch failed: connect ECONNREFUSED 1.2.3.4:443`. When the server has
|
||||
several addresses and none of them could be reached, the line gives the reason
|
||||
for each, separated by `, `. A file whose download failed that way is in
|
||||
`failures.json` with that error, as a transient failure. So is each file with no
|
||||
ML data cached when the ML data fetch failed that way, its error starting
|
||||
`ML data: `. The `~/bin/quak` that `make install` builds runs under bun, and
|
||||
prints bun's own wording for such a failure.
|
||||
|
||||
After a `1`, the next run fetches each missing original again, fetches the ML
|
||||
data that is not cached, and rebuilds the album links. An album quak could not
|
||||
@@ -347,7 +366,8 @@ quak/
|
||||
exif.ts EXIF read from an image's bytes with exifreader
|
||||
mldata-fetch.ts fetch + decrypt per-file ML data
|
||||
filename.ts safe file names from server metadata
|
||||
errors.ts error types shared across layers
|
||||
errors.ts error types shared across layers, and how an error
|
||||
is described
|
||||
retry.ts retry classifier + exponential backoff with jitter
|
||||
thumbnails.ts detect + regenerate missing thumbnails
|
||||
client.ts high-level Client class assembled from the above
|
||||
@@ -790,8 +810,22 @@ after the file's title, both with unsafe characters replaced. When two
|
||||
collections would get the same name, or two symlinks in one collection the same
|
||||
name (ignoring case in both), each of them gets its ID added: two albums named
|
||||
`Trip` become `Trip (10)/` and `Trip (11)/`, and two files titled `IMG_0001.JPG`
|
||||
become `IMG_0001 (12345).JPG` and `IMG_0001 (12346).JPG`. IDs never change, so a
|
||||
name stays the same from run to run until such a clash appears or goes away.
|
||||
become `IMG_0001 (12345).JPG` and `IMG_0001 (12346).JPG`. A collection whose
|
||||
directory would have the name of another collection's JSON, again ignoring case,
|
||||
gets its ID added as well: beside an album `x`, whose JSON is `x.json`, an album
|
||||
named `x.json` gets the directory `x.json (12)/`. A name too long for a file
|
||||
name, which most file systems limit to 255 bytes, gets its ID added too. A name
|
||||
with its ID added is cut short between two characters, just far enough that it
|
||||
fits: first the part before the ID, and once nothing is left of that, a
|
||||
symlink's extension. A collection's directory name also leaves room for the
|
||||
`.json` its JSON adds. IDs never change, so a name stays the same from run to
|
||||
run until such a clash appears or goes away.
|
||||
|
||||
A collection whose directory or JSON cannot be written, such as one whose
|
||||
directory name is taken by a file you put in `collections/`, does not stop the
|
||||
run. A run without `--json` prints `FAILED album <name>: <reason>` for it,
|
||||
`--json` and the `BackupResult` list its ID in `failedAlbums`, and the exit code
|
||||
is 1. The other collections and `failures.json` are still written.
|
||||
|
||||
A live photo, which Ente stores as one ZIP of its image and its video, is stored
|
||||
as those two files, which a photo viewer can open: each is
|
||||
@@ -1085,9 +1119,10 @@ photos newest first). `lib.subscribe({ onChange })` delivers a `LibraryChange`
|
||||
`downloadDirectory` (falls back to the library's), `includeOriginals` (default
|
||||
`true`), `includeThumbnails` (default `false`), `onlyAlbumNames`, `verify`
|
||||
(default `false`), `onProgress`, and `lock`. See Backup layout above for the
|
||||
tree it writes. Whether the backup took the lock or its caller did, once the
|
||||
lock is lost the backup rejects with `lost the lock on <dir>: <reason>` before
|
||||
it starts another file.
|
||||
tree it writes, and for the albums `BackupResult` lists in
|
||||
`undecryptableAlbums` and `failedAlbums`. Whether the backup took the lock or
|
||||
its caller did, once the lock is lost the backup rejects with
|
||||
`lost the lock on <dir>: <reason>` before it starts another file.
|
||||
|
||||
### Request pools
|
||||
|
||||
|
||||
@@ -17,7 +17,10 @@ pre-1.0
|
||||
|
||||
# Next Step
|
||||
|
||||
None: no implementation work is open. The check of quak against a live Ente
|
||||
Four bugs are open: https://git.eeqj.de/sneak/quak/issues/198,
|
||||
https://git.eeqj.de/sneak/quak/issues/199,
|
||||
https://git.eeqj.de/sneak/quak/issues/205 and
|
||||
https://git.eeqj.de/sneak/quak/issues/206. The check of quak against a live Ente
|
||||
account, https://git.eeqj.de/sneak/quak/issues/187, needs an account only sneak
|
||||
has, so it waits on him.
|
||||
|
||||
@@ -26,6 +29,31 @@ declares one.
|
||||
|
||||
# Completed Steps
|
||||
|
||||
- 2026-10-15: An album whose folder or JSON `quak backup` cannot write no longer
|
||||
ends the run before the other albums and `failures.json` are written (issue
|
||||
197). The run prints `FAILED album <name>: <reason>`, lists the album's ID in
|
||||
`failedAlbums` in the result and in `--json`, goes on, and exits 1. An album
|
||||
whose folder would have the name of another album's JSON, as `x.json` beside
|
||||
`x` would, gets its ID added. A folder or link name over 255 bytes is cut
|
||||
short between two characters, by `shortenToBytes` in `src/filename.ts`, and
|
||||
gets the ID.
|
||||
|
||||
- 2026-10-15: A network failure is printed and recorded with its reason, not as
|
||||
just `fetch failed` (issue 196). `describeError` in `src/errors.ts` gives an
|
||||
error's message followed by the message of each error on its `cause` chain,
|
||||
such as `fetch failed: connect ECONNREFUSED 1.2.3.4:443`, and each address's
|
||||
reason when a host has several and none could be reached. `run` prints that,
|
||||
and the backup logs it and records it in `failures.json`, where `classify` now
|
||||
calls the failure transient when the chain holds an errno that
|
||||
`hasTransportCode` in `src/retry.ts` recognises, for a failed ML data fetch
|
||||
too. The walk along the chain moved from `src/retry.ts` to `src/errors.ts`,
|
||||
which both use. Tests refuse every connection of a backup, then only one
|
||||
file's download, and fail the ML data fetch.
|
||||
|
||||
- 2026-10-15: The README says that `make install` needs nix (issue 200), in
|
||||
Getting Started and in "Running the backup from cron": `make build-bin` runs
|
||||
bun through `nix-shell -p bun`. The `Makefile` is unchanged.
|
||||
|
||||
- 2026-10-14: `lib.backup()`, and so `quak backup`, works on up to the content
|
||||
pool's limit of originals at once, 5 by default, instead of one at a time
|
||||
(issue 182). That many workers take files from one shared list, each doing all
|
||||
|
||||
+109
-68
@@ -50,7 +50,9 @@
|
||||
// running attempt count, and the last-tried time, and the run continues.
|
||||
// A file the library could not decrypt is recorded there too, unless a copy of
|
||||
// it in another album decrypted; an album it could not decrypt is logged by ID
|
||||
// and listed in `result.undecryptableAlbums`, as its name is not known.
|
||||
// and listed in `result.undecryptableAlbums`, as its name is not known. An
|
||||
// album whose folder or JSON cannot be written is logged by name and
|
||||
// listed in `result.failedAlbums`, and the run goes on to the next album.
|
||||
// `result.failed` — and thus the CLI's exit code — stays non-zero while any
|
||||
// failure remains unresolved and clears once every one succeeds. Each run
|
||||
// reconciles the ledger against the files it attempted, so an entry for a file
|
||||
@@ -82,7 +84,13 @@ import {
|
||||
init,
|
||||
} from "./crypto/index.js";
|
||||
import { removeLeftoverTempFiles } from "./download/index.js";
|
||||
import { sanitizeFileName, withExtension } from "./filename.js";
|
||||
import { describeError } from "./errors.js";
|
||||
import {
|
||||
MAX_NAME_BYTES,
|
||||
sanitizeFileName,
|
||||
shortenToBytes,
|
||||
withExtension,
|
||||
} from "./filename.js";
|
||||
import {
|
||||
copyAtomic,
|
||||
placeOriginal,
|
||||
@@ -94,6 +102,7 @@ import type { Undecryptable } from "./library/store.js";
|
||||
import { extractImageMetadata } from "./metadata-backup.js";
|
||||
import type { MLData } from "./mldata-fetch.js";
|
||||
import type { Collection, EnteFile, FileMetadata } from "./model/types.js";
|
||||
import { hasTransportCode } from "./retry.js";
|
||||
|
||||
export type ProgressCallback = (message: string) => void;
|
||||
|
||||
@@ -158,6 +167,9 @@ export interface BackupResult {
|
||||
// The IDs of the albums the library could not decrypt, whose files it
|
||||
// could not list; the CLI exits non-zero while there are any.
|
||||
undecryptableAlbums: number[];
|
||||
// The IDs of the albums whose folder or JSON this run could not write;
|
||||
// the CLI exits non-zero while there are any.
|
||||
failedAlbums: number[];
|
||||
}
|
||||
|
||||
// The slice of the library that backup drives. `Library` implements it; a test
|
||||
@@ -219,11 +231,13 @@ const isPresent = (path: string): boolean => {
|
||||
|
||||
// Best-effort classification for the ledger. Retryable server/network problems
|
||||
// are transient; refusals and local filesystem/decrypt errors are permanent;
|
||||
// anything else is unknown. Both the error code and message are inspected.
|
||||
// anything else is unknown. The error code and the error as `describeError`
|
||||
// gives it are inspected, and so is each errno on the error's cause chain,
|
||||
// where Node's `fetch` puts it.
|
||||
const classify = (err: unknown): FailureClass => {
|
||||
if (hasTransportCode(err)) return "transient";
|
||||
const e = err as NodeJS.ErrnoException;
|
||||
const text =
|
||||
`${e?.code ?? ""} ${err instanceof Error ? err.message : String(err)}`.toLowerCase();
|
||||
const text = `${e?.code ?? ""} ${describeError(err)}`.toLowerCase();
|
||||
if (
|
||||
/timeout|timed out|econnreset|econnrefused|econnaborted|network|socket|eai_again|throttl|temporarily|429|500|502|503|504/.test(
|
||||
text,
|
||||
@@ -241,9 +255,6 @@ const classify = (err: unknown): FailureClass => {
|
||||
return "unknown";
|
||||
};
|
||||
|
||||
const errorMessage = (err: unknown): string =>
|
||||
err instanceof Error ? err.message : String(err);
|
||||
|
||||
// Ensure `linkPath` is a symlink to `target`, rebuilding a missing, wrong, or
|
||||
// non-symlink entry. Throws on failure (a directory in the way, no permission)
|
||||
// so the caller records it and moves on rather than aborting the run.
|
||||
@@ -263,31 +274,45 @@ const rebuildSymlink = (linkPath: string, target: string): void => {
|
||||
// The on-disk names for the entries of one directory, in entry order. Each
|
||||
// name is used as is unless another entry would get the same name, ignoring
|
||||
// case (two names that differ only in case are one entry on a case-insensitive
|
||||
// file system); then every entry sharing it gets ` (<id>)`, before the
|
||||
// extension when `beforeExtension` is set. A name with an ID added can match
|
||||
// another entry's own name (`IMG (6).JPG`), so this repeats until no name is
|
||||
// shared. IDs are stable, so the names are too.
|
||||
// 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, and once nothing is left of
|
||||
// it, so is the extension. 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.
|
||||
// Two names with different IDs added never match, but one can match another
|
||||
// entry's own name (`IMG (6).JPG`), so this repeats until no name is shared.
|
||||
// IDs are stable, so the names are too.
|
||||
const uniqueNames = (
|
||||
entries: { id: number; name: string }[],
|
||||
beforeExtension: boolean,
|
||||
opts: { beforeExtension?: boolean; withJSON?: boolean },
|
||||
): string[] => {
|
||||
const maxBytes = MAX_NAME_BYTES - (opts.withJSON ? ".json".length : 0);
|
||||
const withID = (id: number, name: string): string => {
|
||||
const ext = beforeExtension ? extname(name) : "";
|
||||
const stem = name.slice(0, name.length - ext.length);
|
||||
return `${stem} (${id})${ext}`;
|
||||
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;
|
||||
};
|
||||
const names = entries.map((e) => e.name);
|
||||
const suffixed = new Set<number>();
|
||||
for (;;) {
|
||||
const counts = new Map<string, number>();
|
||||
for (const name of names) {
|
||||
const count = (name: string): void => {
|
||||
const key = name.toLowerCase();
|
||||
counts.set(key, (counts.get(key) ?? 0) + 1);
|
||||
};
|
||||
for (const name of names) {
|
||||
count(name);
|
||||
if (opts.withJSON) count(`${name}.json`);
|
||||
}
|
||||
let changed = false;
|
||||
for (const [i, { id, name }] of entries.entries()) {
|
||||
if (suffixed.has(i)) continue;
|
||||
if (counts.get(name.toLowerCase()) === 1) continue;
|
||||
const fits = Buffer.byteLength(name) <= maxBytes;
|
||||
if (fits && counts.get(name.toLowerCase()) === 1) continue;
|
||||
names[i] = withID(id, name);
|
||||
suffixed.add(i);
|
||||
changed = true;
|
||||
@@ -470,7 +495,7 @@ const imageMetadataFor = async (
|
||||
const bytes = await readFile(originalPath);
|
||||
return { imageMetadata: extractImageMetadata(bytes) ?? {} };
|
||||
} catch (err) {
|
||||
return { imageMetadataError: errorMessage(err) };
|
||||
return { imageMetadataError: describeError(err) };
|
||||
}
|
||||
};
|
||||
|
||||
@@ -610,7 +635,7 @@ const runLockedBackup = async (
|
||||
// and thumbnail both fail this run must not double its attempt count
|
||||
// or appear twice in errors.
|
||||
if (failedThisRun.has(fileID)) return;
|
||||
const error = errorMessage(err);
|
||||
const error = describeError(err);
|
||||
errors.push({ fileID, title, collection, error });
|
||||
const prior = ledger.get(fileID);
|
||||
ledger.set(fileID, {
|
||||
@@ -681,7 +706,7 @@ const runLockedBackup = async (
|
||||
}
|
||||
} catch (err) {
|
||||
log(
|
||||
`FAILED verifying original ${file.metadata.title}: ${errorMessage(err)}`,
|
||||
`FAILED verifying original ${file.metadata.title}: ${describeError(err)}`,
|
||||
);
|
||||
recordFailure(
|
||||
file.id,
|
||||
@@ -717,7 +742,9 @@ const runLockedBackup = async (
|
||||
}
|
||||
downloaded++;
|
||||
} catch (err) {
|
||||
log(`FAILED original ${file.metadata.title}: ${errorMessage(err)}`);
|
||||
log(
|
||||
`FAILED original ${file.metadata.title}: ${describeError(err)}`,
|
||||
);
|
||||
recordFailure(
|
||||
file.id,
|
||||
file.metadata.title,
|
||||
@@ -785,12 +812,14 @@ const runLockedBackup = async (
|
||||
// instead and is recorded as failed. The next run fetches its ML data
|
||||
// again because none is cached.
|
||||
if (includeOriginals) {
|
||||
let mlDataFailure: unknown;
|
||||
let mlDataError: string | undefined;
|
||||
try {
|
||||
log("Fetching ML data...");
|
||||
await lib.fetchMLData();
|
||||
} catch (err) {
|
||||
mlDataError = errorMessage(err);
|
||||
mlDataFailure = err;
|
||||
mlDataError = describeError(err);
|
||||
log(`FAILED ML data: ${mlDataError}`);
|
||||
}
|
||||
for (const file of distinct.values()) {
|
||||
@@ -814,7 +843,7 @@ const runLockedBackup = async (
|
||||
file.id,
|
||||
file.metadata.title,
|
||||
collectionName.get(file.collectionID) ?? "",
|
||||
new Error(`ML data: ${mlDataError}`),
|
||||
new Error("ML data", { cause: mlDataFailure }),
|
||||
);
|
||||
} else {
|
||||
writeSidecar(path, file, { mlData }, image);
|
||||
@@ -833,7 +862,7 @@ const runLockedBackup = async (
|
||||
id: c.id,
|
||||
name: sanitizeFileName(c.name, `collection-${c.id}`),
|
||||
})),
|
||||
false,
|
||||
{ withJSON: true },
|
||||
);
|
||||
const albumDirNames = new Map(
|
||||
allCollections.map((c, i) => [c.id, dirNames[i]!]),
|
||||
@@ -846,61 +875,72 @@ const runLockedBackup = async (
|
||||
downloadDirectory,
|
||||
);
|
||||
} catch (err) {
|
||||
log(`FAILED removing old album directories: ${errorMessage(err)}`);
|
||||
log(`FAILED removing old album directories: ${describeError(err)}`);
|
||||
}
|
||||
|
||||
// An album whose folder or JSON cannot be written, such as one whose
|
||||
// folder name is taken by a file the user put there, is logged and listed
|
||||
// in the result, and the run goes on to the next album.
|
||||
const failedAlbums: number[] = [];
|
||||
for (const c of collections) {
|
||||
if (lock.lost) throw lock.lost;
|
||||
const colDirName = albumDirNames.get(c.id)!;
|
||||
const colDir = join(collectionsDir, colDirName);
|
||||
mkdirSync(colDir, { recursive: true });
|
||||
|
||||
// Every album links the one original, saved from the file's entry in
|
||||
// `distinct`.
|
||||
const files = filesByCollection.get(c.id) ?? [];
|
||||
const links = files.flatMap((f) =>
|
||||
linksFor(
|
||||
f,
|
||||
storedAtSavePath(downloadDirectory, distinct.get(f.id)!),
|
||||
),
|
||||
);
|
||||
const linkNames = uniqueNames(links, true);
|
||||
try {
|
||||
removeStaleLinks(colDir, new Set(linkNames), downloadDirectory);
|
||||
} catch (err) {
|
||||
log(`FAILED removing old links in ${c.name}: ${errorMessage(err)}`);
|
||||
}
|
||||
const colDirName = albumDirNames.get(c.id)!;
|
||||
const colDir = join(collectionsDir, colDirName);
|
||||
mkdirSync(colDir, { recursive: true });
|
||||
|
||||
const metaFiles = files.map((f) => ({
|
||||
id: f.id,
|
||||
metadata: f.metadata,
|
||||
}));
|
||||
for (const [i, link] of links.entries()) {
|
||||
if (!includeOriginals || link.target === undefined) continue;
|
||||
const linkName = linkNames[i]!;
|
||||
// Every album links the one original, saved from the file's entry
|
||||
// in `distinct`.
|
||||
const files = filesByCollection.get(c.id) ?? [];
|
||||
const links = files.flatMap((f) =>
|
||||
linksFor(
|
||||
f,
|
||||
storedAtSavePath(downloadDirectory, distinct.get(f.id)!),
|
||||
),
|
||||
);
|
||||
const linkNames = uniqueNames(links, { beforeExtension: true });
|
||||
try {
|
||||
rebuildSymlink(
|
||||
join(colDir, linkName),
|
||||
relative(colDir, link.target),
|
||||
);
|
||||
removeStaleLinks(colDir, new Set(linkNames), downloadDirectory);
|
||||
} catch (err) {
|
||||
log(
|
||||
`FAILED symlink ${c.name}/${linkName}: ${errorMessage(err)}`,
|
||||
);
|
||||
recordFailure(
|
||||
link.file.id,
|
||||
link.file.metadata.title,
|
||||
c.name,
|
||||
err,
|
||||
`FAILED removing old links in ${c.name}: ${describeError(err)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
writeAlbumJSON(
|
||||
join(collectionsDir, `${colDirName}.json`),
|
||||
c,
|
||||
metaFiles,
|
||||
);
|
||||
const metaFiles = files.map((f) => ({
|
||||
id: f.id,
|
||||
metadata: f.metadata,
|
||||
}));
|
||||
for (const [i, link] of links.entries()) {
|
||||
if (!includeOriginals || link.target === undefined) continue;
|
||||
const linkName = linkNames[i]!;
|
||||
try {
|
||||
rebuildSymlink(
|
||||
join(colDir, linkName),
|
||||
relative(colDir, link.target),
|
||||
);
|
||||
} catch (err) {
|
||||
log(
|
||||
`FAILED symlink ${c.name}/${linkName}: ${describeError(err)}`,
|
||||
);
|
||||
recordFailure(
|
||||
link.file.id,
|
||||
link.file.metadata.title,
|
||||
c.name,
|
||||
err,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
writeAlbumJSON(
|
||||
join(collectionsDir, `${colDirName}.json`),
|
||||
c,
|
||||
metaFiles,
|
||||
);
|
||||
} catch (err) {
|
||||
log(`FAILED album ${c.name}: ${describeError(err)}`);
|
||||
failedAlbums.push(c.id);
|
||||
}
|
||||
}
|
||||
|
||||
// Reconcile the ledger against what this run actually attempted: an entry
|
||||
@@ -926,6 +966,7 @@ const runLockedBackup = async (
|
||||
failed: ledger.size,
|
||||
errors,
|
||||
undecryptableAlbums,
|
||||
failedAlbums,
|
||||
};
|
||||
};
|
||||
|
||||
|
||||
+3
-1
@@ -470,7 +470,9 @@ export const backupCommand = async (
|
||||
}
|
||||
}
|
||||
|
||||
return result.failed > 0 || result.undecryptableAlbums.length > 0
|
||||
return result.failed > 0 ||
|
||||
result.undecryptableAlbums.length > 0 ||
|
||||
result.failedAlbums.length > 0
|
||||
? 1
|
||||
: 0;
|
||||
} finally {
|
||||
|
||||
+7
-6
@@ -2,14 +2,17 @@
|
||||
|
||||
import type { Writable } from "node:stream";
|
||||
import { ApiError } from "./api/client.js";
|
||||
import { describeError } from "./errors.js";
|
||||
|
||||
// Run a command and exit with its code once stdout/stderr have drained.
|
||||
// Exiting before the drain can truncate piped output, and the library can keep
|
||||
// the event loop alive after a command returns, so a plain return could hang.
|
||||
// An error the command throws is printed as one `quak: MESSAGE` line, without
|
||||
// the stack trace, and exits 1. A 401 from the server means it no longer
|
||||
// accepts the saved session: that prints one line saying to log in again and
|
||||
// exits 3, as a missing or corrupt session file does.
|
||||
// the stack trace, and exits 1. MESSAGE is the error as `describeError` gives
|
||||
// it, so it carries the reason Node's `fetch` puts on `cause`. A 401 from the
|
||||
// server means it no longer accepts the saved session: that prints one line
|
||||
// saying to log in again and exits 3, as a missing or corrupt session file
|
||||
// does.
|
||||
export const run = async (
|
||||
command: Promise<number>,
|
||||
stdout: Writable,
|
||||
@@ -26,9 +29,7 @@ export const run = async (
|
||||
);
|
||||
code = 3;
|
||||
} else {
|
||||
stderr.write(
|
||||
`quak: ${err instanceof Error ? err.message : String(err)}\n`,
|
||||
);
|
||||
stderr.write(`quak: ${describeError(err)}\n`);
|
||||
code = 1;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -135,15 +135,17 @@ const streamDecrypt = async (
|
||||
// cannot tell a partial chunk from a corrupt one, so this
|
||||
// is reported as the truncation it almost always is, with
|
||||
// the authentication failure kept as the error's cause.
|
||||
// Only the pull is guarded: a sink failure on a chunk
|
||||
// that did authenticate is a disk error, not a
|
||||
// The message leaves that failure to the cause, which
|
||||
// `describeError` appends to what `quak backup` prints and
|
||||
// records. Only the pull is guarded: a sink failure on a
|
||||
// chunk that did authenticate is a disk error, not a
|
||||
// truncation.
|
||||
let pulled;
|
||||
try {
|
||||
pulled = pullStreamChunk(state, buffer);
|
||||
} catch (err) {
|
||||
throw new TruncatedStreamError(
|
||||
`download: stream truncated: response body ended with ${buffer.length} trailing bytes that did not authenticate as a final chunk (transfer stopped mid-chunk, or the data is corrupt)`,
|
||||
`download: stream truncated: response body ended with ${buffer.length} trailing bytes (transfer stopped mid-chunk, or the data is corrupt)`,
|
||||
{ cause: err },
|
||||
);
|
||||
}
|
||||
|
||||
+71
-3
@@ -1,10 +1,13 @@
|
||||
// Error types that more than one layer of quak needs to recognise.
|
||||
// Error types that more than one layer of quak needs to recognise, and how an
|
||||
// error is described in what quak prints and in `failures.json`.
|
||||
//
|
||||
// They live here rather than beside the code that throws them so that the
|
||||
// The types live here rather than beside the code that throws them so that the
|
||||
// retry classifier can identify them without importing the HTTP client or the
|
||||
// download layer — both of which import the classifier. `ApiError` is
|
||||
// re-exported from `src/api/client.ts`, which is where callers have always
|
||||
// imported it from and where it still belongs conceptually.
|
||||
// imported it from and where it still belongs conceptually. The walk along an
|
||||
// error's `cause` chain is here too, because the retry classifier reads the
|
||||
// chain for errnos and `describeError` for messages.
|
||||
|
||||
export class ApiError extends Error {
|
||||
readonly status: number;
|
||||
@@ -43,3 +46,68 @@ export class TruncatedStreamError extends Error {
|
||||
this.name = "TruncatedStreamError";
|
||||
}
|
||||
}
|
||||
|
||||
// `cause` is an arbitrary user-settable property and nothing prevents it from
|
||||
// forming a cycle, so the walk is bounded. Hanging the process would be worse
|
||||
// than misclassifying an error or describing only part of it.
|
||||
const MAX_CAUSE_DEPTH = 8;
|
||||
|
||||
// The error and each error on its `cause` chain, top first, at most
|
||||
// `MAX_CAUSE_DEPTH` of them. `complete` is false when the walk stopped at the
|
||||
// depth limit with more of the chain still below it.
|
||||
export const causeChain = (
|
||||
err: unknown,
|
||||
): { chain: object[]; complete: boolean } => {
|
||||
const chain: object[] = [];
|
||||
let current: unknown = err;
|
||||
for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
|
||||
if (current === null || typeof current !== "object") {
|
||||
return { chain, complete: true };
|
||||
}
|
||||
chain.push(current);
|
||||
const { cause } = current as { cause?: unknown };
|
||||
if (cause === current) return { chain, complete: true };
|
||||
current = cause;
|
||||
}
|
||||
return { chain, complete: current === null || typeof current !== "object" };
|
||||
};
|
||||
|
||||
// An error as quak prints it and records it in `failures.json`: its message,
|
||||
// then the message of each error on its `cause` chain, joined with ": ". Node's
|
||||
// `fetch` rejects with just "fetch failed" and puts the reason on `cause`, so
|
||||
// this gives "fetch failed: connect ECONNREFUSED 1.2.3.4:443". When the host
|
||||
// has several addresses and every one fails, the cause is an `AggregateError`
|
||||
// with an empty message and one error per address in `errors`, so an
|
||||
// `AggregateError` is given as the messages of its errors, joined with ", ".
|
||||
// A cause that is not an object, such as a thrown string, is given as
|
||||
// `String(cause)`. Each message is trimmed of the white space around it, as
|
||||
// OpenSSL ends its own with a newline. A message the text already holds is
|
||||
// left out.
|
||||
export const describeError = (err: unknown): string => {
|
||||
if (!(err instanceof Error)) return String(err);
|
||||
const { chain } = causeChain(err);
|
||||
const messages = chain
|
||||
.slice(1)
|
||||
.map((cause) =>
|
||||
cause instanceof AggregateError
|
||||
? cause.errors
|
||||
.map((e: unknown) =>
|
||||
(e instanceof Error ? e.message : String(e)).trim(),
|
||||
)
|
||||
.join(", ")
|
||||
: (cause as { message?: unknown }).message,
|
||||
);
|
||||
// `causeChain` stops at a cause that is not an object, so that one is read
|
||||
// from the last error on the chain.
|
||||
const last = chain[chain.length - 1] as { cause?: unknown };
|
||||
if (last.cause !== undefined && typeof last.cause !== "object") {
|
||||
messages.push(String(last.cause));
|
||||
}
|
||||
let text = err.message.trim();
|
||||
for (const message of messages) {
|
||||
if (typeof message !== "string") continue;
|
||||
const trimmed = message.trim();
|
||||
if (!text.includes(trimmed)) text += `: ${trimmed}`;
|
||||
}
|
||||
return text;
|
||||
};
|
||||
|
||||
+19
-1
@@ -4,7 +4,8 @@
|
||||
// hands us, and quak does not trust the server. Any name taken from them and
|
||||
// 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.
|
||||
// Windows device name. Such a name can still be too long for a file name, and
|
||||
// `shortenToBytes` cuts one short.
|
||||
//
|
||||
// A path the user typed (`--out`, `outPath`) is not passed through here: the
|
||||
// caller is trusted, the server is not.
|
||||
@@ -39,3 +40,20 @@ export const safeExtension = (title: string): string => {
|
||||
// `name` with its extension, if it has one, replaced by `ext` (".mov").
|
||||
export const withExtension = (name: string, ext: string): string =>
|
||||
name.slice(0, name.length - extname(name).length) + ext;
|
||||
|
||||
// The longest file name, in bytes, that ext4 and most other file systems allow.
|
||||
export const MAX_NAME_BYTES = 255;
|
||||
|
||||
// `name` cut short to at most `maxBytes` bytes of UTF-8, the encoding a file
|
||||
// name is written to disk in, between two characters, never inside one. A name
|
||||
// that fits comes back unchanged.
|
||||
export const shortenToBytes = (name: string, maxBytes: number): string => {
|
||||
let bytes = 0;
|
||||
let end = 0;
|
||||
for (const character of name) {
|
||||
bytes += Buffer.byteLength(character);
|
||||
if (bytes > maxBytes) break;
|
||||
end += character.length;
|
||||
}
|
||||
return name.slice(0, end);
|
||||
};
|
||||
|
||||
+12
-16
@@ -10,7 +10,7 @@
|
||||
// declining to retry a transient one costs a single file that the next run
|
||||
// picks up anyway. When the evidence is ambiguous, fail fast.
|
||||
|
||||
import { ApiError, TruncatedStreamError } from "./errors.js";
|
||||
import { ApiError, causeChain, TruncatedStreamError } from "./errors.js";
|
||||
|
||||
export interface RetryOptions {
|
||||
// Total calls, not retries: `attempts: 1` disables retrying.
|
||||
@@ -89,11 +89,6 @@ const TRANSPORT_CODES = new Set([
|
||||
// narrowed. See `isSafeToReplay`.
|
||||
const CONNECT_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED"]);
|
||||
|
||||
// `cause` is an arbitrary user-settable property and nothing prevents it from
|
||||
// forming a cycle, so the walk is bounded. Hanging the process would be a
|
||||
// worse outcome than any misclassification.
|
||||
const MAX_CAUSE_DEPTH = 8;
|
||||
|
||||
// Collect every `code` in an error's cause chain. undici does not put the
|
||||
// errno on the error it throws — it hangs the underlying socket error off
|
||||
// `cause`, sometimes more than one level down — so a classifier that only read
|
||||
@@ -101,20 +96,21 @@ const MAX_CAUSE_DEPTH = 8;
|
||||
// connection permanent. `complete` is false when the walk stopped at the
|
||||
// depth limit with more of the chain still below it.
|
||||
const causeCodes = (err: unknown): { codes: string[]; complete: boolean } => {
|
||||
const { chain, complete } = causeChain(err);
|
||||
const codes: string[] = [];
|
||||
let current: unknown = err;
|
||||
for (let depth = 0; depth < MAX_CAUSE_DEPTH; depth++) {
|
||||
if (current === null || typeof current !== "object") {
|
||||
return { codes, complete: true };
|
||||
}
|
||||
const { code, cause } = current as { code?: unknown; cause?: unknown };
|
||||
for (const link of chain) {
|
||||
const { code } = link as { code?: unknown };
|
||||
if (typeof code === "string") codes.push(code);
|
||||
if (cause === current) return { codes, complete: true };
|
||||
current = cause;
|
||||
}
|
||||
return { codes, complete: current === null || typeof current !== "object" };
|
||||
return { codes, complete };
|
||||
};
|
||||
|
||||
// Does the error's cause chain hold the errno of a transport failure, one of
|
||||
// `TRANSPORT_CODES`? `isRetryable` retries such an error, and `classify` in
|
||||
// `src/backup.ts` calls it transient.
|
||||
export const hasTransportCode = (err: unknown): boolean =>
|
||||
causeCodes(err).codes.some((code) => TRANSPORT_CODES.has(code));
|
||||
|
||||
const isAbort = (err: unknown): boolean => {
|
||||
if (err === null || typeof err !== "object") return false;
|
||||
const { name } = err as { name?: unknown };
|
||||
@@ -158,7 +154,7 @@ export const isRetryable = (err: unknown): boolean => {
|
||||
// have succeeded; the cost of the imprecision is bounded by the attempt
|
||||
// count.
|
||||
if (err instanceof TypeError) return true;
|
||||
return causeCodes(err).codes.some((code) => TRANSPORT_CODES.has(code));
|
||||
return hasTransportCode(err);
|
||||
};
|
||||
|
||||
// Could the first attempt already have taken effect on the server?
|
||||
|
||||
@@ -274,15 +274,15 @@ afterAll(() => {
|
||||
|
||||
// Run `quak backup <dir>` as `bin/quak.ts` runs it, sending its requests
|
||||
// through `fetch`, and return its exit code and everything it printed on
|
||||
// stderr. Its requests are retried as those of `quak backup` are, except that
|
||||
// a retry does not wait. Its cache is beside `dir`, so each run of one
|
||||
// directory finds the cache the run before it left, as cron's runs find the
|
||||
// user's.
|
||||
// stderr and on stdout. Its requests are retried as those of `quak backup`
|
||||
// are, except that a retry does not wait. Its cache is beside `dir`, so each
|
||||
// run of one directory finds the cache the run before it left, as cron's runs
|
||||
// find the user's.
|
||||
const backup = async (
|
||||
dir: string,
|
||||
opts: { verify?: boolean } = {},
|
||||
opts: { verify?: boolean; json?: boolean } = {},
|
||||
fetch = server,
|
||||
): Promise<{ code: number; stderr: string }> => {
|
||||
): Promise<{ code: number; stderr: string; stdout: string }> => {
|
||||
let printed = "";
|
||||
const stderr = new Writable({
|
||||
write(chunk: Buffer, _encoding, done) {
|
||||
@@ -290,8 +290,10 @@ const backup = async (
|
||||
done();
|
||||
},
|
||||
});
|
||||
let output = "";
|
||||
const stdout = new Writable({
|
||||
write(_chunk, _encoding, done) {
|
||||
write(chunk: Buffer, _encoding, done) {
|
||||
output += chunk.toString();
|
||||
done();
|
||||
},
|
||||
});
|
||||
@@ -316,7 +318,7 @@ const backup = async (
|
||||
const code = await new Promise<number>((resolve) => {
|
||||
void run(backupCommand(ctx, dir, opts), stdout, stderr, resolve);
|
||||
});
|
||||
return { code, stderr: printed };
|
||||
return { code, stderr: printed, stdout: output };
|
||||
};
|
||||
|
||||
// The ID of the file whose original a request downloads, or undefined for any
|
||||
@@ -329,6 +331,41 @@ const downloadOf = (input: RequestInfo | URL): number | undefined => {
|
||||
: undefined;
|
||||
};
|
||||
|
||||
// The error Node gives for a connection to `address` that was refused.
|
||||
const refusedAt = (address: string): Error =>
|
||||
Object.assign(new Error(`connect ECONNREFUSED ${address}`), {
|
||||
code: "ECONNREFUSED",
|
||||
});
|
||||
|
||||
// What Node's `fetch` rejects with when the server refuses the connection, as
|
||||
// for every failure below HTTP: a TypeError that says only "fetch failed",
|
||||
// with the reason, and its errno, as its cause. When the server has several
|
||||
// addresses and each one refuses, the cause is an AggregateError with an empty
|
||||
// message, one error per address and the errno of the first. `reason` is the
|
||||
// error as quak prints it and records it in `failures.json`.
|
||||
const REFUSED = [
|
||||
{
|
||||
addresses: "its one address",
|
||||
error: (): TypeError =>
|
||||
new TypeError("fetch failed", { cause: refusedAt("1.2.3.4:443") }),
|
||||
reason: "fetch failed: connect ECONNREFUSED 1.2.3.4:443",
|
||||
},
|
||||
{
|
||||
addresses: "each of its two addresses",
|
||||
error: (): TypeError =>
|
||||
new TypeError("fetch failed", {
|
||||
cause: Object.assign(
|
||||
new AggregateError([
|
||||
refusedAt("2001:db8::1:443"),
|
||||
refusedAt("1.2.3.4:443"),
|
||||
]),
|
||||
{ code: "ECONNREFUSED" },
|
||||
),
|
||||
}),
|
||||
reason: "fetch failed: connect ECONNREFUSED 2001:db8::1:443, connect ECONNREFUSED 1.2.3.4:443",
|
||||
},
|
||||
];
|
||||
|
||||
// The fake server, pushing onto `downloads` the ID of each file whose original
|
||||
// is downloaded.
|
||||
const recordingDownloads =
|
||||
@@ -592,6 +629,40 @@ describe("quak backup", () => {
|
||||
).toEqual([]);
|
||||
});
|
||||
|
||||
// The user has put a file in collections/ with the name of the Trips
|
||||
// folder, so quak cannot make that folder. It says so on one line, writes
|
||||
// the two albums after it, and exits 1, and --json lists the album's ID
|
||||
// in `failedAlbums`. No file failed, so there is no failures.json.
|
||||
it("exits 1 when an album's folder cannot be made, writes the other albums, and lists it in --json", async () => {
|
||||
const dir = mkdtempSync(join(root, "backup-"));
|
||||
mkdirSync(join(dir, "collections"));
|
||||
writeFileSync(join(dir, "collections", "Trips"), "mine");
|
||||
|
||||
const first = await backup(dir);
|
||||
const { code, stdout } = await backup(dir, { json: true });
|
||||
|
||||
expect(first.code).toBe(1);
|
||||
expect(first.stderr).toMatch(/^FAILED album Trips: EEXIST: /m);
|
||||
expect(code).toBe(1);
|
||||
expect(JSON.parse(stdout)).toMatchObject({
|
||||
failed: 0,
|
||||
undecryptableAlbums: [],
|
||||
failedAlbums: [10],
|
||||
});
|
||||
const collections = join(dir, "collections");
|
||||
expect(readJSON(join(collections, "Family.json")).id).toBe(20);
|
||||
expect(readdirSync(join(collections, "Family")).sort()).toEqual([
|
||||
"IMG_0002.heic",
|
||||
"IMG_0002.mov",
|
||||
"beach.jpg",
|
||||
]);
|
||||
expect(readJSON(join(collections, "Friend's Wedding.json")).id).toBe(
|
||||
30,
|
||||
);
|
||||
expect(existsSync(join(collections, "Trips.json"))).toBe(false);
|
||||
expect(existsSync(join(dir, "failures.json"))).toBe(false);
|
||||
});
|
||||
|
||||
// The server no longer accepts the saved session's token, as after
|
||||
// `quak logout` elsewhere, and answers every request with 401. The run
|
||||
// stops at the refresh it starts with, says to log in again, and exits 3.
|
||||
@@ -619,6 +690,115 @@ describe("quak backup", () => {
|
||||
expect(readdirSync(dir)).toEqual([]);
|
||||
});
|
||||
|
||||
// The server refuses every connection, at its one address or at each of
|
||||
// several. quak tries each request again, here without waiting, and then
|
||||
// the run stops at the refresh it starts with. The line it prints gives
|
||||
// the reason Node's `fetch` put on the error's cause, so a cron log tells
|
||||
// a refused connection from a name that did not resolve, and the exit
|
||||
// code is 1.
|
||||
it.each(REFUSED)(
|
||||
"prints why the refresh could not reach the server at $addresses, and exits 1",
|
||||
async ({ error, reason }) => {
|
||||
const dir = mkdtempSync(join(root, "backup-"));
|
||||
const fetch: typeof globalThis.fetch = async () => {
|
||||
throw error();
|
||||
};
|
||||
|
||||
const { code, stderr } = await backup(dir, {}, fetch);
|
||||
|
||||
expect(code).toBe(1);
|
||||
expect(stderr).toBe(
|
||||
"Starting backup...\n" +
|
||||
"Refreshing library...\n" +
|
||||
`quak: ${reason}\n`,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
// The files CDN refuses every connection for toast.mp4, at its one
|
||||
// address or at each of several. Once its retries are spent, the file
|
||||
// goes into `failures.json` with the reason, as a transient failure,
|
||||
// since a later run may well reach the CDN, and the lines the backup
|
||||
// prints for it give the same reason. The rest of the account is backed
|
||||
// up, and the exit code is 1.
|
||||
it.each(REFUSED)(
|
||||
"records why a download could not reach the server at $addresses in failures.json, as transient, and exits 1",
|
||||
async ({ error, reason }) => {
|
||||
let attempts = 0;
|
||||
const fetch: typeof globalThis.fetch = async (input, init) => {
|
||||
if (downloadOf(input) === 200) {
|
||||
attempts++;
|
||||
throw error();
|
||||
}
|
||||
return server(input, init);
|
||||
};
|
||||
const dir = mkdtempSync(join(root, "backup-"));
|
||||
|
||||
const { code, stderr } = await backup(dir, {}, fetch);
|
||||
|
||||
expect(code).toBe(1);
|
||||
expect(attempts).toBe(UNATTENDED_RETRY_OPTIONS.attempts);
|
||||
const failures = readJSON(join(dir, "failures.json"));
|
||||
expect(Object.keys(failures.files)).toEqual(["200"]);
|
||||
expect(failures.files["200"]).toMatchObject({
|
||||
fileID: 200,
|
||||
title: "toast.mp4",
|
||||
classification: "transient",
|
||||
attempts: 1,
|
||||
error: reason,
|
||||
});
|
||||
expect(stderr).toContain(`FAILED original toast.mp4: ${reason}\n`);
|
||||
expect(stderr).toContain(
|
||||
`[Friend's Wedding] toast.mp4 (id 200): ${reason}\n`,
|
||||
);
|
||||
expect(readFileSync(join(dir, DAY, "2024-03-01.100.jpg"))).toEqual(
|
||||
Buffer.from(JPEG_WITH_EXIF),
|
||||
);
|
||||
expect(existsSync(join(dir, DAY, "2024-03-01.200.mp4"))).toBe(
|
||||
false,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
// The name of Ente's API server does not resolve when quak fetches the ML
|
||||
// data, after every original has been backed up. No file has ML data
|
||||
// cached yet, so each goes into `failures.json` with the reason, as a
|
||||
// transient failure, as a download that could not reach the server does,
|
||||
// and the exit code is 1.
|
||||
it("records why the ML data fetch could not reach the server in failures.json, as transient, and exits 1", async () => {
|
||||
const fetch: typeof globalThis.fetch = async (input, init) => {
|
||||
if (new URL(String(input)).pathname === "/files/data/fetch") {
|
||||
throw new TypeError("fetch failed", {
|
||||
cause: Object.assign(
|
||||
new Error("getaddrinfo ENOTFOUND api.ente.io"),
|
||||
{ code: "ENOTFOUND" },
|
||||
),
|
||||
});
|
||||
}
|
||||
return server(input, init);
|
||||
};
|
||||
const dir = mkdtempSync(join(root, "backup-"));
|
||||
|
||||
const { code, stderr } = await backup(dir, {}, fetch);
|
||||
|
||||
expect(code).toBe(1);
|
||||
const error =
|
||||
"ML data: fetch failed: getaddrinfo ENOTFOUND api.ente.io";
|
||||
expect(stderr).toContain(`FAILED ${error}\n`);
|
||||
const failures = readJSON(join(dir, "failures.json"));
|
||||
expect(
|
||||
Object.values(failures.files).map((f) => [
|
||||
f.fileID,
|
||||
f.classification,
|
||||
f.error,
|
||||
]),
|
||||
).toEqual([
|
||||
[100, "transient", error],
|
||||
[200, "transient", error],
|
||||
[300, "transient", error],
|
||||
]);
|
||||
});
|
||||
|
||||
// Something changed beach.jpg on disk after it was backed up. A run with
|
||||
// --verify hashes every stored original, finds that one no longer matches
|
||||
// the hash Ente recorded, says so, and downloads it again; it put back the
|
||||
|
||||
+194
-1
@@ -1498,13 +1498,15 @@ describe("backup album folders", () => {
|
||||
files: EnteFile[];
|
||||
}
|
||||
|
||||
const libraryOf = (albums: Album[]): BackupLibrary => ({
|
||||
// The original of the file `notFound`, if given, always fails to download.
|
||||
const libraryOf = (albums: Album[], notFound?: number): BackupLibrary => ({
|
||||
refresh: async () => {},
|
||||
listCollections: () => albums.map((a) => a.collection),
|
||||
listFiles: (id) =>
|
||||
albums.find((a) => a.collection.id === id)?.files ?? [],
|
||||
undecryptable: () => [],
|
||||
original: async (fileID) => {
|
||||
if (fileID === notFound) throw new Error("HTTP 404");
|
||||
const path = join(root, `source-${fileID}`);
|
||||
writeFileSync(path, `original ${fileID}`);
|
||||
return { path };
|
||||
@@ -1600,6 +1602,197 @@ describe("backup album folders", () => {
|
||||
expect(albumID(outDir, "Trip (11) (12).json")).toBe(12);
|
||||
});
|
||||
|
||||
// The next three tests end with the album "ok" (14), whose one file
|
||||
// always fails to download, so each run has a failure to record in
|
||||
// failures.json after the album folders are written.
|
||||
const ok: Album = {
|
||||
collection: collection(14, "ok"),
|
||||
files: [file(5, 14, "e.jpg")],
|
||||
};
|
||||
|
||||
// The folder of an album named "x.json" would be the JSON file of the
|
||||
// album "x", and once ended every run there. Two runs, as on two nights,
|
||||
// write the same tree, and the failed file's attempt count goes up.
|
||||
it("adds the ID to an album whose folder would have another album's JSON name", async () => {
|
||||
const outDir = join(root, "backup");
|
||||
const lib = libraryOf(
|
||||
[
|
||||
{
|
||||
collection: collection(10, "x"),
|
||||
files: [file(1, 10, "a.jpg")],
|
||||
},
|
||||
{
|
||||
collection: collection(11, "x.json"),
|
||||
files: [file(2, 11, "b.jpg")],
|
||||
},
|
||||
{
|
||||
collection: collection(12, "Trip"),
|
||||
files: [file(3, 12, "c.jpg")],
|
||||
},
|
||||
{
|
||||
collection: collection(13, "TRIP.json"),
|
||||
files: [file(4, 13, "d.jpg")],
|
||||
},
|
||||
ok,
|
||||
],
|
||||
5,
|
||||
);
|
||||
|
||||
await runBackup(lib, { downloadDirectory: outDir });
|
||||
const result = await runBackup(lib, { downloadDirectory: outDir });
|
||||
|
||||
expect(result.failedAlbums).toEqual([]);
|
||||
expect(tree(outDir)).toEqual([
|
||||
"TRIP.json (13)/",
|
||||
`TRIP.json (13)/d.jpg -> ${linkTo("4.jpg")}`,
|
||||
"TRIP.json (13).json",
|
||||
"Trip/",
|
||||
`Trip/c.jpg -> ${linkTo("3.jpg")}`,
|
||||
"Trip.json",
|
||||
"ok/",
|
||||
"ok.json",
|
||||
"x/",
|
||||
`x/a.jpg -> ${linkTo("1.jpg")}`,
|
||||
"x.json",
|
||||
"x.json (11)/",
|
||||
`x.json (11)/b.jpg -> ${linkTo("2.jpg")}`,
|
||||
"x.json (11).json",
|
||||
]);
|
||||
expect(albumID(outDir, "x.json")).toBe(10);
|
||||
expect(albumID(outDir, "x.json (11).json")).toBe(11);
|
||||
expect(albumID(outDir, "TRIP.json (13).json")).toBe(13);
|
||||
expect(albumID(outDir, "ok.json")).toBe(14);
|
||||
expect(result.failed).toBe(1);
|
||||
expect(readLedger(outDir).files["5"]).toMatchObject({ attempts: 2 });
|
||||
});
|
||||
|
||||
// A name over 255 bytes is refused as a file name, and an album folder's
|
||||
// name leaves room for `.json` in its JSON's. "é" takes two bytes, and a
|
||||
// name is cut between two characters.
|
||||
it("cuts an album name and a title too long for a file name short and adds the ID", async () => {
|
||||
const outDir = join(root, "backup");
|
||||
const lib = libraryOf(
|
||||
[
|
||||
{
|
||||
collection: collection(10, "L".repeat(300)),
|
||||
files: [file(1, 10, `${"é".repeat(150)}.jpg`)],
|
||||
},
|
||||
ok,
|
||||
],
|
||||
5,
|
||||
);
|
||||
|
||||
await runBackup(lib, { downloadDirectory: outDir });
|
||||
const result = await runBackup(lib, { downloadDirectory: outDir });
|
||||
|
||||
const folder = `${"L".repeat(245)} (10)`;
|
||||
const link = `${"é".repeat(123)} (1).jpg`;
|
||||
expect(Buffer.byteLength(`${folder}.json`)).toBe(255);
|
||||
expect(Buffer.byteLength(link)).toBe(254);
|
||||
expect(result.failedAlbums).toEqual([]);
|
||||
expect(tree(outDir)).toEqual([
|
||||
`${folder}/`,
|
||||
`${folder}/${link} -> ${linkTo("1.jpg")}`,
|
||||
`${folder}.json`,
|
||||
"ok/",
|
||||
"ok.json",
|
||||
]);
|
||||
expect(albumID(outDir, `${folder}.json`)).toBe(10);
|
||||
expect(albumID(outDir, "ok.json")).toBe(14);
|
||||
expect(result.failed).toBe(1);
|
||||
expect(readLedger(outDir).files["5"]).toMatchObject({ attempts: 2 });
|
||||
});
|
||||
|
||||
// The user has put a file in collections/ with the name of the album
|
||||
// Trip's folder, so the folder cannot be made.
|
||||
it("goes on to the next album when an album's folder cannot be made, and lists it as failed", async () => {
|
||||
const outDir = join(root, "backup");
|
||||
const lib = libraryOf(
|
||||
[
|
||||
{
|
||||
collection: collection(10, "Trip"),
|
||||
files: [file(1, 10, "a.jpg")],
|
||||
},
|
||||
ok,
|
||||
],
|
||||
5,
|
||||
);
|
||||
mkdirSync(join(outDir, "collections"), { recursive: true });
|
||||
writeFileSync(join(outDir, "collections", "Trip"), "mine");
|
||||
const logged: string[] = [];
|
||||
|
||||
const result = await runBackup(lib, {
|
||||
downloadDirectory: outDir,
|
||||
onProgress: (message) => logged.push(message),
|
||||
});
|
||||
|
||||
expect(result.failedAlbums).toEqual([10]);
|
||||
expect(logged).toContainEqual(
|
||||
expect.stringMatching(/^FAILED album Trip: EEXIST: /),
|
||||
);
|
||||
expect(tree(outDir)).toEqual(["Trip", "ok/", "ok.json"]);
|
||||
expect(albumID(outDir, "ok.json")).toBe(14);
|
||||
expect(existsSync(saved(outDir, "1.jpg"))).toBe(true);
|
||||
expect(result.failed).toBe(1);
|
||||
expect(readLedger(outDir).files["5"]).toMatchObject({ attempts: 1 });
|
||||
});
|
||||
|
||||
// The extension of this title is 303 bytes, so it leaves no room for the
|
||||
// ID: nothing is left of the name before the ID, and the extension is cut
|
||||
// short after it. The extension holds a "-", so the original is saved
|
||||
// with `.bin`, a name that fits.
|
||||
it("cuts the extension of a title short when it leaves no room for the ID", async () => {
|
||||
const outDir = join(root, "backup");
|
||||
const lib = libraryOf([
|
||||
{
|
||||
collection: collection(10, "Trip"),
|
||||
files: [file(1, 10, `a.${"L".repeat(300)}-x`)],
|
||||
},
|
||||
]);
|
||||
|
||||
const result = await runBackup(lib, { downloadDirectory: outDir });
|
||||
|
||||
const link = ` (1).${"L".repeat(250)}`;
|
||||
expect(Buffer.byteLength(link)).toBe(255);
|
||||
expect(result.failed).toBe(0);
|
||||
expect(tree(outDir)).toEqual([
|
||||
"Trip/",
|
||||
`Trip/${link} -> ${linkTo("1.bin")}`,
|
||||
"Trip.json",
|
||||
]);
|
||||
});
|
||||
|
||||
// Files 1 and 3 share a title, so each gets its ID before the
|
||||
// extension. File 2's title is too long, and its extension leaves no
|
||||
// room for the ID. Were the ID put at the end of file 2's title cut
|
||||
// short, its link would have file 1's name, and the link made second
|
||||
// would replace the first.
|
||||
it("keeps names unique when a title's extension leaves no room for the ID", async () => {
|
||||
const outDir = join(root, "backup");
|
||||
const shared = `x.${"Q".repeat(245)} (2)`;
|
||||
const lib = libraryOf([
|
||||
{
|
||||
collection: collection(10, "Trip"),
|
||||
files: [
|
||||
file(1, 10, shared),
|
||||
file(2, 10, `x (1).${"Q".repeat(250)}-`),
|
||||
file(3, 10, shared),
|
||||
],
|
||||
},
|
||||
]);
|
||||
|
||||
const result = await runBackup(lib, { downloadDirectory: outDir });
|
||||
|
||||
expect(result.failed).toBe(0);
|
||||
expect(tree(outDir)).toEqual([
|
||||
"Trip/",
|
||||
`Trip/ (2).${"Q".repeat(250)} -> ${linkTo("2.bin")}`,
|
||||
`Trip/x (1).${"Q".repeat(245)} (2) -> ${linkTo("1.bin")}`,
|
||||
`Trip/x (3).${"Q".repeat(245)} (2) -> ${linkTo("3.bin")}`,
|
||||
"Trip.json",
|
||||
]);
|
||||
});
|
||||
|
||||
it("changes nothing on a second run over an unchanged account", async () => {
|
||||
const outDir = join(root, "backup");
|
||||
const lib = libraryOf([
|
||||
|
||||
@@ -48,6 +48,78 @@ describe("run", () => {
|
||||
);
|
||||
});
|
||||
|
||||
// Node's `fetch` rejects every failure below HTTP with a TypeError that
|
||||
// says only "fetch failed", and hangs the reason, with its errno, off
|
||||
// `cause`. The printed line carries the reason, so a cron log tells a
|
||||
// refused connection from a name that did not resolve.
|
||||
it("prints the reason a fetch failed, from the error's cause", async () => {
|
||||
const refused = new TypeError("fetch failed", {
|
||||
cause: Object.assign(
|
||||
new Error("connect ECONNREFUSED 1.2.3.4:443"),
|
||||
{ code: "ECONNREFUSED" },
|
||||
),
|
||||
});
|
||||
const result = await runToExit(Promise.reject(refused));
|
||||
expect(result).toEqual({
|
||||
code: 1,
|
||||
stdout: "",
|
||||
stderr: "quak: fetch failed: connect ECONNREFUSED 1.2.3.4:443\n",
|
||||
});
|
||||
});
|
||||
|
||||
// When the host has several addresses and every one refuses, Node's
|
||||
// `fetch` gives as the cause an AggregateError with an empty message and
|
||||
// one error per address. The printed line gives each address's reason.
|
||||
it("prints the reason for each address a fetch could not reach", async () => {
|
||||
const refusedAt = (address: string): Error =>
|
||||
Object.assign(new Error(`connect ECONNREFUSED ${address}`), {
|
||||
code: "ECONNREFUSED",
|
||||
});
|
||||
const refused = new TypeError("fetch failed", {
|
||||
cause: Object.assign(
|
||||
new AggregateError([
|
||||
refusedAt("2001:db8::1:443"),
|
||||
refusedAt("1.2.3.4:443"),
|
||||
]),
|
||||
{ code: "ECONNREFUSED" },
|
||||
),
|
||||
});
|
||||
const result = await runToExit(Promise.reject(refused));
|
||||
expect(result).toEqual({
|
||||
code: 1,
|
||||
stdout: "",
|
||||
stderr: "quak: fetch failed: connect ECONNREFUSED 2001:db8::1:443, connect ECONNREFUSED 1.2.3.4:443\n",
|
||||
});
|
||||
});
|
||||
|
||||
// An error that already quotes its cause's message is printed as it is.
|
||||
it("does not print a cause's message twice", async () => {
|
||||
const reset = new Error("read ECONNRESET");
|
||||
const wrapped = new Error(`download: file 7: ${reset.message}`, {
|
||||
cause: reset,
|
||||
});
|
||||
const result = await runToExit(Promise.reject(wrapped));
|
||||
expect(result.stderr).toBe("quak: download: file 7: read ECONNRESET\n");
|
||||
});
|
||||
|
||||
// OpenSSL ends its message for a failed TLS connection, such as one to a
|
||||
// server that answers in plain HTTP, with a newline. The printed line is
|
||||
// still one line.
|
||||
it("prints a cause's message without the white space around it", async () => {
|
||||
const wrongVersion = new TypeError("fetch failed", {
|
||||
cause: Object.assign(
|
||||
new Error(
|
||||
"C0B73A55A47F0000:error:0A00010B:SSL routines:ssl3_get_record:wrong version number:../deps/openssl/openssl/ssl/record/ssl3_record.c:354:\n",
|
||||
),
|
||||
{ code: "ERR_SSL_WRONG_VERSION_NUMBER" },
|
||||
),
|
||||
});
|
||||
const result = await runToExit(Promise.reject(wrongVersion));
|
||||
expect(result.stderr).toBe(
|
||||
"quak: fetch failed: C0B73A55A47F0000:error:0A00010B:SSL routines:ssl3_get_record:wrong version number:../deps/openssl/openssl/ssl/record/ssl3_record.c:354:\n",
|
||||
);
|
||||
});
|
||||
|
||||
it("prints a thrown value that is not an Error", async () => {
|
||||
const result = await runToExit(Promise.reject("offline"));
|
||||
expect(result).toEqual({
|
||||
@@ -57,6 +129,14 @@ describe("run", () => {
|
||||
});
|
||||
});
|
||||
|
||||
// A cause that is not an Error, such as a thrown string, is printed as a
|
||||
// thrown value that is not an Error is.
|
||||
it("prints a cause that is not an Error", async () => {
|
||||
const wrapped = new Error("ML data", { cause: "offline" });
|
||||
const result = await runToExit(Promise.reject(wrapped));
|
||||
expect(result.stderr).toBe("quak: ML data: offline\n");
|
||||
});
|
||||
|
||||
it("on a 401 from the server says to run quak login, on one line, and exits 3", async () => {
|
||||
const result = await runToExit(
|
||||
Promise.reject(new ApiError("unauthorized", 401)),
|
||||
|
||||
@@ -74,7 +74,11 @@ import {
|
||||
} from "vitest";
|
||||
import { init, toBase64, STREAM_CHUNK_SIZE } from "../../src/crypto/index.js";
|
||||
import { ApiClient } from "../../src/api/client.js";
|
||||
import { ApiError, TruncatedStreamError } from "../../src/errors.js";
|
||||
import {
|
||||
ApiError,
|
||||
describeError,
|
||||
TruncatedStreamError,
|
||||
} from "../../src/errors.js";
|
||||
import type { RetryOptions } from "../../src/retry.js";
|
||||
import {
|
||||
downloadFile,
|
||||
@@ -834,6 +838,11 @@ describe.each(entryPoints)(
|
||||
expect(((err as Error).cause as Error).message).toMatch(
|
||||
/authentication failed/i,
|
||||
);
|
||||
// As quak prints it and records it in `failures.json`, the error
|
||||
// states the authentication failure once, from its cause.
|
||||
expect(describeError(err)).toMatch(
|
||||
/^download: stream truncated: response body ended with \d+ trailing bytes \(transfer stopped mid-chunk, or the data is corrupt\): secretstream chunk authentication failed$/,
|
||||
);
|
||||
|
||||
// And, as with every other failure, the destination is untouched
|
||||
// and no staged temp file survives.
|
||||
|
||||
@@ -14,7 +14,11 @@
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import { safeExtension, sanitizeFileName } from "../../src/filename.js";
|
||||
import {
|
||||
safeExtension,
|
||||
sanitizeFileName,
|
||||
shortenToBytes,
|
||||
} from "../../src/filename.js";
|
||||
|
||||
const FALLBACK = "file-42";
|
||||
|
||||
@@ -91,3 +95,26 @@ describe("safeExtension", () => {
|
||||
expect(safeExtension("x.jpg\0")).toBe(".bin");
|
||||
});
|
||||
});
|
||||
|
||||
describe("shortenToBytes", () => {
|
||||
it("returns a name that fits unchanged", () => {
|
||||
expect(shortenToBytes("beach", 5)).toBe("beach");
|
||||
expect(shortenToBytes("café", 5)).toBe("café");
|
||||
expect(shortenToBytes("", 0)).toBe("");
|
||||
});
|
||||
|
||||
it("cuts a name to the number of bytes given", () => {
|
||||
expect(shortenToBytes("L".repeat(300), 255)).toBe("L".repeat(255));
|
||||
});
|
||||
|
||||
// In UTF-8 "é" takes two bytes and an emoji four, which a JavaScript
|
||||
// string holds as two halves.
|
||||
it("cuts between two characters, never inside one", () => {
|
||||
expect(shortenToBytes("ééé", 5)).toBe("éé");
|
||||
expect(shortenToBytes("a\u{1F600}b", 4)).toBe("a");
|
||||
expect(shortenToBytes("a\u{1F600}b", 5)).toBe("a\u{1F600}");
|
||||
expect(Buffer.byteLength(shortenToBytes("é".repeat(200), 255))).toBe(
|
||||
254,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user