Author SHA1 Message Date
sneak 94bef69403 README: a backup's first line is still Starting backup...
check / check (push) Waiting to run
The README said a backup run starts with the `Started at` line. The run
prints `Starting backup...` first, and `Started at` second.

Model: opus-5-5
2026-11-19 07:00:48 +00:00
sneak ab236dc162 quak backup: print the date and time a run starts and finishes (closes #245)
check / check (push) Waiting to run
Adds a `Started at` line after `Starting backup...` and a `Finished at`
line after `--- Backup complete ---`, in local time with the UTC offset.
No existing line changes. The clock comes in through `CliContext.now`.

The README's crontab now pipes the output to `logger`, which adds its own
time to each line; appending to a file remains as the alternative.

Model: opus-5-5
2026-11-19 06:48:42 +00:00
8 changed files with 143 additions and 151 deletions

No files matched your search

+25 -21
View File
@@ -172,14 +172,21 @@ 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 "The session file").
Then add the backup to that user's crontab with `crontab -e`. These two lines
back up the account to `~/photos-backup` at 03:30 every night and append all
output to `~/quak-backup.log`. Sunday's run adds `--verify`:
back up the account to `~/photos-backup` at 03:30 every night and send all
output to the system log with `logger`. Sunday's run adds `--verify`:
```
30 3 * * 1-6 $HOME/bin/quak backup $HOME/photos-backup >> $HOME/quak-backup.log 2>&1
30 3 * * 0 $HOME/bin/quak backup --verify $HOME/photos-backup >> $HOME/quak-backup.log 2>&1
30 3 * * 1-6 $HOME/bin/quak backup $HOME/photos-backup 2>&1 | logger -t quak
30 3 * * 0 $HOME/bin/quak backup --verify $HOME/photos-backup 2>&1 | logger -t quak
```
On Linux with systemd, `logger` writes to the journal, and `journalctl -t quak`
shows the runs. The system log adds the time to each line.
To keep the output in a file instead, end each line with
`>> $HOME/quak-backup.log 2>&1` in place of the pipe. Each run's `Started at`
and `Finished at` lines then show when it ran.
A run with `--verify` does all a plain run does. It also hashes each original
already in the backup and compares the result with the content hash. The content
hash is the hash of the file's bytes that Ente recorded at upload. The run
@@ -276,13 +283,8 @@ factor at that point, login fails.
On success it logs `Logged in as <email> (user <id>)` and
`Session saved to <path>`. On failure it logs `Login failed: <reason>`, and the
exit status is 1. Two reasons are given in words:
- a wrong password: `Login failed: incorrect email or password`
- an email with no account on the server:
`Login failed: no account with this email on the server`
`login` is the only command that prompts, and its prompts go to stdout.
exit status is 1. `login` is the only command that prompts, and its prompts go
to stdout.
#### `quak whoami`
@@ -368,10 +370,12 @@ once, however many collections hold it. An original the cache already holds is
copied from there instead.
Progress goes to stderr: one line per original fetched, and a `FAILED` line for
each original or album that failed. The run ends with a summary of counts and,
when any file failed, a `Failed files:` list of every failed file. With
`--json`, the summary and the list are replaced by one JSON object on stdout.
Its fields are:
each original or album that failed. The run starts with `Starting backup...` and
a `Started at` line giving the local date and time, such as
`Started at 2026-11-11 03:30:00 +0100`. It ends with a summary: a `Finished at`
line in the same form, the counts and, when any file failed, a `Failed files:`
list of every failed file. With `--json`, the summary and the list are replaced
by one JSON object on stdout. Its fields are:
- `totalFiles`: how many distinct files the run covered, however many
collections hold each;
@@ -560,12 +564,12 @@ output, run `yarn --silent quak files --json` or
`node dist/bin/quak.js files --json` instead.
With `--json`, a command's JSON on stdout takes the place of its summary on
stderr. For `backup`, that is the `--- Backup complete ---` line, the counts and
the `Failed files:` list. For `list-missing-thumbnails`, it is
`No missing thumbnails found.` or `<n> file(s) with missing thumbnails:`. For
`fix-missing-thumbnails`, it is the `--- Done ---` line, the counts, the
`Skipped:` list and the `Failed files:` list. Every other line is logged as
without `--json`.
stderr. For `backup`, that is the `--- Backup complete ---` line, the
`Finished at` line, the counts and the `Failed files:` list. For
`list-missing-thumbnails`, it is `No missing thumbnails found.` or
`<n> file(s) with missing thumbnails:`. For `fix-missing-thumbnails`, it is the
`--- Done ---` line, the counts, the `Skipped:` list and the `Failed files:`
list. Every other line is logged as without `--json`.
### Exit codes
+1
View File
@@ -81,6 +81,7 @@ const context = (): CliContext => ({
}),
prompt: (message) => input({ message }),
promptSecret: (message) => password({ message, mask: true }),
now: () => new Date(),
});
const run = (command: Promise<number>): Promise<void> =>
+11 -45
View File
@@ -1,5 +1,5 @@
import { SRP, SrpClient } from "fast-srp-hap";
import { ApiError, type ApiClient } from "../api/client.js";
import type { ApiClient } from "../api/client.js";
import { deriveKEK, deriveLoginSubkey, fromBase64 } from "../crypto/index.js";
import type {
AuthorizationResponse,
@@ -10,14 +10,6 @@ import type {
// Ente uses the 4096-bit SRP group. Both client and server must agree.
const SRP_PARAMS = SRP.params["4096"];
// The same error, with a message that says in words what the server refused.
const withMessage = (err: ApiError, message: string): ApiError =>
new ApiError(message, err.status, {
code: err.code,
requestID: err.requestID,
body: err.body,
});
// Wrap fast-srp-hap's callback-based genKey into a Promise.
const genKey = (): Promise<Buffer> => SRP.genKey();
@@ -71,20 +63,13 @@ const srpHandshake = async (
srpClient.setB(Buffer.from(srpB, "base64"));
const srpM1 = srpClient.computeM1().toString("base64");
type VerifyResponse = AuthorizationResponse & { srpM2: string };
let verifyResponse: VerifyResponse;
try {
verifyResponse = await api.postJSON<VerifyResponse>(
"/users/srp/verify-session",
{ sessionID, srpUserID: srpAttributes.srpUserID, srpM1 },
);
} catch (err) {
// The server answers 401 when the password does not match.
if (err instanceof ApiError && err.status === 401) {
throw withMessage(err, "incorrect email or password");
}
throw err;
}
const verifyResponse = await api.postJSON<
AuthorizationResponse & { srpM2: string }
>("/users/srp/verify-session", {
sessionID,
srpUserID: srpAttributes.srpUserID,
srpM1,
});
srpClient.checkM2(Buffer.from(verifyResponse.srpM2, "base64"));
@@ -116,28 +101,9 @@ export const beginLogin = async (
email: string,
password: string,
): Promise<LoginChallenge> => {
let attributes: SRPAttributes;
try {
({ attributes } = await api.getJSON<{ attributes: SRPAttributes }>(
"/users/srp/attributes",
{ email },
));
} catch (err) {
// The Ente server answers 404 with `{}` when no account has the email.
// It answers 404 with the code NOT_FOUND when the account exists but
// has no SRP attributes. A server address that points somewhere else
// answers 404 without JSON. Those two errors stay as they are.
if (
err instanceof ApiError &&
err.status === 404 &&
typeof err.body === "object" &&
err.body !== null &&
err.code === undefined
) {
throw withMessage(err, "no account with this email on the server");
}
throw err;
}
const { attributes } = await api.getJSON<{
attributes: SRPAttributes;
}>("/users/srp/attributes", { email });
if (attributes.isEmailMFAEnabled) {
return { kind: "emailOTP" };
+20
View File
@@ -68,11 +68,29 @@ export interface CliContext {
prompt: (message: string) => Promise<string>;
// Like `prompt`, but the answer is masked as it is typed.
promptSecret: (message: string) => Promise<string>;
// The current time. The CLI passes `() => new Date()`; tests pass fixed
// times.
now: () => Date;
}
const sessionPath = (ctx: CliContext): string =>
join(ctx.sessionDir, "session.json");
const pad = (n: number): string => String(n).padStart(2, "0");
// `date` in local time with its offset from UTC, such as
// `2026-11-11 03:30:00 +0100`.
const localTime = (date: Date): string => {
const offset = -date.getTimezoneOffset();
const sign = offset < 0 ? "-" : "+";
const abs = Math.abs(offset);
return (
`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
`${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())} ` +
`${sign}${pad(Math.floor(abs / 60))}${pad(abs % 60)}`
);
};
// Write the session readable by its owner only, in a directory only its owner
// can enter.
export const saveSession = (
@@ -468,6 +486,7 @@ export const backupCommand = async (
if (!client) return 3;
ctx.log("info", "Starting backup...");
ctx.log("info", `Started at ${localTime(ctx.now())}`);
// The lock is taken before the library opens and starts its refresh, so a
// run refused while another backup of `dir` runs sends no request.
let lock: BackupLock;
@@ -504,6 +523,7 @@ export const backupCommand = async (
ctx.stdout.write(JSON.stringify(result, null, 2) + "\n");
} else {
ctx.log("info", "\n--- Backup complete ---");
ctx.log("info", `Finished at ${localTime(ctx.now())}`);
ctx.log("info", ` Total files: ${result.totalFiles}`);
ctx.log("info", ` Downloaded: ${result.downloaded}`);
ctx.log("info", ` Skipped: ${result.skipped}`);
+6 -80
View File
@@ -30,7 +30,7 @@
import sodium from "libsodium-wrappers-sumo";
import { SRP, SrpServer } from "fast-srp-hap";
import { beforeAll, describe, expect, it } from "vitest";
import { ApiClient, ApiError } from "../../src/api/client.js";
import { ApiClient } from "../../src/api/client.js";
import {
init,
toBase64,
@@ -142,15 +142,10 @@ const buildServerFixture = async (password: string) => {
*
* @param fixture The server fixture from buildServerFixture
* @param opts.requireTOTP If true, verify-session returns a 2FA challenge
* @param opts.unknownEmail If true, the server has no account with the email
*/
const buildMockFetch = (
fixture: Awaited<ReturnType<typeof buildServerFixture>>,
opts?: {
requireTOTP?: boolean;
requirePasskeyAndTOTP?: boolean;
unknownEmail?: boolean;
},
opts?: { requireTOTP?: boolean; requirePasskeyAndTOTP?: boolean },
) => {
let srpServer: SrpServer;
const sessionID = "test-session-id";
@@ -168,15 +163,7 @@ const buildMockFetch = (
const parsed = new URL(url);
const path = parsed.pathname;
// The Ente server answers its refusals with an empty JSON object.
const refusal = (status: number) =>
new Response("{}", {
status,
headers: { "content-type": "application/json" },
});
if (path === "/users/srp/attributes") {
if (opts?.unknownEmail) return refusal(404);
return new Response(
JSON.stringify({ attributes: fixture.srpAttributes }),
{
@@ -210,11 +197,7 @@ const buildMockFetch = (
if (path === "/users/srp/verify-session") {
const body = JSON.parse(init?.body as string);
try {
srpServer.checkM1(Buffer.from(body.srpM1, "base64"));
} catch {
return refusal(401);
}
srpServer.checkM1(Buffer.from(body.srpM1, "base64"));
const M2 = srpServer.computeM2();
// IMPORTANT: the museum server's EmailAuthorizationResponse
@@ -382,70 +365,13 @@ describe("beginLogin via SRP", () => {
}
});
it("says a wrong password is incorrect (SRP M1 verification fails)", async () => {
it("rejects a wrong password (SRP M1 verification fails)", async () => {
const fixture = await buildServerFixture(TEST_PASSWORD);
const api = new ApiClient({ fetch: buildMockFetch(fixture) });
const err = await beginLogin(api, TEST_EMAIL, "wrong password").catch(
(e: unknown) => e,
);
expect(err).toBeInstanceOf(ApiError);
expect((err as ApiError).message).toBe("incorrect email or password");
expect((err as ApiError).status).toBe(401);
});
it("says the server has no account with an unknown email", async () => {
const fixture = await buildServerFixture(TEST_PASSWORD);
const api = new ApiClient({
fetch: buildMockFetch(fixture, { unknownEmail: true }),
});
const err = await beginLogin(api, TEST_EMAIL, TEST_PASSWORD).catch(
(e: unknown) => e,
);
expect(err).toBeInstanceOf(ApiError);
expect((err as ApiError).message).toBe(
"no account with this email on the server",
);
expect((err as ApiError).status).toBe(404);
});
// The Ente server's answer for an account that has no SRP attributes.
it("does not call an account with no SRP attributes missing", async () => {
const api = new ApiClient({
fetch: (async () =>
new Response(
JSON.stringify({ code: "NOT_FOUND", message: "" }),
{
status: 404,
headers: { "content-type": "application/json" },
},
)) as typeof globalThis.fetch,
});
const err = await beginLogin(api, TEST_EMAIL, TEST_PASSWORD).catch(
(e: unknown) => e,
);
expect(err).toBeInstanceOf(ApiError);
expect((err as ApiError).code).toBe("NOT_FOUND");
expect((err as ApiError).message).not.toBe(
"no account with this email on the server",
);
});
// A server address that points somewhere other than an Ente server.
it("keeps the bare status of a 404 that is not JSON", async () => {
const api = new ApiClient({
fetch: (async () =>
new Response("404 page not found", {
status: 404,
headers: { "content-type": "text/plain" },
})) as typeof globalThis.fetch,
});
await expect(
beginLogin(api, TEST_EMAIL, TEST_PASSWORD),
).rejects.toThrow(/^HTTP 404$/);
beginLogin(api, TEST_EMAIL, "wrong password"),
).rejects.toThrow();
});
});
+17 -2
View File
@@ -77,8 +77,17 @@ const PASSWORD = "backup-password";
const USER_ID = 42;
const FRIEND_ID = 99;
// Noon on 1 March 2024 in the time zone of the machine running the test, the
// one quak dates save paths in, in microseconds, as Ente records times.
// quak prints the time a backup starts, and dates save paths, in local time.
// The zone is pinned here, before any fixture is dated, and restored after
// the last test.
const savedTZ = process.env.TZ;
process.env.TZ = "Europe/Berlin";
// The time every backup's clock reads, 03:30 in Berlin.
const NOW = new Date(Date.UTC(2026, 10, 11, 2, 30));
const STARTED = "Started at 2026-11-11 03:30:00 +0100\n";
// Noon on 1 March 2024 in local time, the one quak dates save paths in, in
// microseconds, as Ente records times.
const TAKEN = new Date(2024, 2, 1, 12).getTime() * 1000;
// The date folder every original is saved in.
const DAY = "2024/2024-03/2024-03-01";
@@ -278,6 +287,8 @@ beforeAll(async () => {
afterAll(() => {
rmSync(root, { recursive: true, force: true });
if (savedTZ === undefined) delete process.env.TZ;
else process.env.TZ = savedTZ;
});
// Run `quak backup <dir>` as `bin/quak.ts` runs it, sending its requests
@@ -326,6 +337,7 @@ const backup = async (
login: prompted,
prompt: prompted,
promptSecret: prompted,
now: () => NOW,
};
const code = await new Promise<number>((resolve) => {
void run(backupCommand(ctx, dir, opts), stdout, stderr, log, resolve);
@@ -698,6 +710,7 @@ describe("quak backup", () => {
expect(code).toBe(3);
expect(stderr).toBe(
"Starting backup...\n" +
STARTED +
"Refreshing library...\n" +
`quak: the saved session is no longer valid; run "quak login"\n`,
);
@@ -725,6 +738,7 @@ describe("quak backup", () => {
expect(code).toBe(1);
expect(stderr).toBe(
"Starting backup...\n" +
STARTED +
"Refreshing library...\n" +
`quak: ${reason}\n`,
);
@@ -1117,6 +1131,7 @@ describe("a backup whose lock is lost", () => {
expect(code).toBe(1);
expect(stderr).toBe(
"Starting backup...\n" +
STARTED +
"Fetched the files of 1 of 3 collections\n" +
"Fetched the files of 2 of 3 collections\n" +
"Fetched the files of 3 of 3 collections\n" +
+1
View File
@@ -319,6 +319,7 @@ const context = (ente: FakeEnte): CliContext => {
promptSecret: async () => {
throw new Error("prompt not expected");
},
now: () => new Date(Date.UTC(2026, 10, 11, 2, 30)),
};
};
+62 -3
View File
@@ -33,6 +33,7 @@ import {
vi,
beforeAll,
beforeEach,
afterAll,
afterEach,
} from "vitest";
@@ -194,6 +195,12 @@ const FETCHED_BOTH_ALBUMS =
"Fetched the files of 1 of 2 collections\n" +
"Fetched the files of 2 of 2 collections\n";
// The time every context's clock reads. `backup` prints it in local time, and
// the tests pin the zone to Europe/Berlin, where it is 03:30.
const NOW = new Date(Date.UTC(2026, 10, 11, 2, 30));
const STARTED = "Started at 2026-11-11 03:30:00 +0100\n";
const FINISHED = "Finished at 2026-11-11 03:30:00 +0100\n";
// Collects everything written to it.
class Output {
text = "";
@@ -223,11 +230,18 @@ const context = (client: Client | null = fakeClient()): CliContext => ({
promptSecret: async () => {
throw new Error("prompt not expected");
},
now: () => NOW,
});
const savedTZ = process.env.TZ;
beforeAll(async () => {
process.env.TZ = "Europe/Berlin";
await init();
});
afterAll(() => {
if (savedTZ === undefined) delete process.env.TZ;
else process.env.TZ = savedTZ;
});
beforeEach(() => {
root = mkdtempSync(join(tmpdir(), "quak-cli-test-"));
@@ -959,6 +973,7 @@ describe("backup", () => {
expect(await backupCommand(context(), dir, {})).toBe(0);
expect(stderr.text).toContain(
"\n--- Backup complete ---\n" +
FINISHED +
" Total files: 3\n" +
" Downloaded: 3\n" +
" Skipped: 0\n" +
@@ -968,6 +983,43 @@ describe("backup", () => {
expect(existsSync(join(dir, "backup.lock"))).toBe(false);
});
// A log of many nights' runs shows when each started and finished, in
// local time with the offset from UTC.
it("prints the local date and time the run started and finished", async () => {
const start = new Date(Date.UTC(2026, 10, 11, 2, 30, 5));
const end = new Date(Date.UTC(2026, 10, 11, 3, 4, 9));
const zones = [
{
zone: "Europe/Berlin",
started: "2026-11-11 03:30:05 +0100",
finished: "2026-11-11 04:04:09 +0100",
},
{
zone: "Asia/Kolkata",
started: "2026-11-11 08:00:05 +0530",
finished: "2026-11-11 08:34:09 +0530",
},
{
zone: "America/New_York",
started: "2026-11-10 21:30:05 -0500",
finished: "2026-11-10 22:04:09 -0500",
},
];
for (const { zone, started, finished } of zones) {
process.env.TZ = zone;
stderr.text = "";
const times = [start, end];
const ctx = { ...context(), now: () => times.shift()! };
expect(await backupCommand(ctx, join(root, zone), {})).toBe(0);
const begin = `Starting backup...\nStarted at ${started}\n`;
expect(stderr.text.slice(0, begin.length)).toBe(begin);
expect(stderr.text).toContain(
`--- Backup complete ---\nFinished at ${finished}\n`,
);
}
process.env.TZ = "Europe/Berlin";
});
// The backup opens its library with the precache off: it fetches the
// originals it needs into the backup, and must not also fetch every
// thumbnail in the account, or keep originals, in the per-user cache.
@@ -1049,6 +1101,7 @@ describe("backup", () => {
it("counts on stderr each album whose files its first refresh fetched, with --json too", async () => {
const start =
"Starting backup...\n" +
STARTED +
FETCHED_BOTH_ALBUMS +
"Refreshing library...\n";
for (const json of [false, true]) {
@@ -1168,7 +1221,9 @@ describe("backup", () => {
const { code, runText } = await backupThroughRun(context(client), dir);
expect(code).toBe(1);
expect(runText).toBe("quak: HTTP 503 from server\n");
expect(stderr.text).toBe("Starting backup...\nRefreshing library...\n");
expect(stderr.text).toBe(
"Starting backup...\n" + STARTED + "Refreshing library...\n",
);
expect(readdirSync(dir)).toEqual([]);
});
@@ -1199,7 +1254,9 @@ describe("backup", () => {
expect(runText).toBe(
`quak: the saved session is no longer valid; run "quak login"\n`,
);
expect(stderr.text).toBe("Starting backup...\nRefreshing library...\n");
expect(stderr.text).toBe(
"Starting backup...\n" + STARTED + "Refreshing library...\n",
);
expect(readdirSync(dir)).toEqual([]);
});
@@ -1227,7 +1284,9 @@ describe("backup", () => {
expect(await backupCommand(context(client), dir, {})).toBe(2);
expect(requests).toBe(0);
expect(stderr.text).toBe(
`Starting backup...\nquak: another backup of ${dir} is running\n`,
"Starting backup...\n" +
STARTED +
`quak: another backup of ${dir} is running\n`,
);
expect(readdirSync(dir)).toEqual(["backup.lock"]);
// Opening the library would have made its cache directory.