Greatest: serve catalog covers from a local copy (BL-0053)

The page hotlinked ~100 AniList CDN covers per load and some failed at random.
The reader now downloads each catalog cover once (sequential, ~1/s, stops on
401/403/429, images up to 2 MB) into data/greatest-covers/ and serves it from
/api/greatest-cover with a year-long browser cache; until a copy exists the
route redirects to the catalog URL. The page also accepts the server's
relative cover URLs, so owned titles show their library cover again.
GREATEST_COVER_WARM=0 turns the downloads off (tests, offline installs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

test/admin-role.test.js

@@ -21,7 +21,8 @@ test('only admins can promote or demote, nobody can demote themselves, and chang
     const port = await freePort(), output = [];
     child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
       env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
-        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '' } });
+        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
+        GREATEST_COVER_WARM: '0' } });
     child.stdout.on('data', d => output.push(String(d)));
     child.stderr.on('data', d => output.push(String(d)));
     const base = `http://127.0.0.1:${port}`;

test/backup.test.js

@@ -251,7 +251,7 @@ test('reader and scraper: admin backup API pauses and resumes the real queue', {
     const base = `http://127.0.0.1:${rp}`, token = 'backup-test-only';
     const env = { ...process.env, DATA: f.data, LIBRARY: library, SCRAPER_DATA: path.join(f.data, 'scraper'), BACKUP: f.target,
       PORT: String(rp), SCRAPER_PORT: String(sp), SCRAPER_HOST: '127.0.0.1', SCRAPER_URL: `http://127.0.0.1:${sp}`, SENTINEL_URL: 'http://127.0.0.1:9',
-      SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0' };
+      SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0', GREATEST_COVER_WARM: '0' };
     for (const script of ['server.js', 'scraper/daemon.js']) {
       const child = spawn(process.execPath, [script], { cwd: root, env, windowsHide: true }); children.push(child);
       for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => output.push(chunk.toString()));

test/discovery-server.test.js

@@ -81,7 +81,7 @@ async function startReader({ anilist, discovery = {}, mangaMeta = null, scraperU
   const child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
     env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
       SCRAPER_URL: scraperUrl, SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
-      DISCOVERY_ANILIST_URL: anilist ? anilist.url : 'http://127.0.0.1:9/', DISCOVERY_HARVEST_AT: '' } });
+      DISCOVERY_ANILIST_URL: anilist ? anilist.url : 'http://127.0.0.1:9/', DISCOVERY_HARVEST_AT: '', GREATEST_COVER_WARM: '0' } });
   child.stdout.on('data', d => output.push(String(d)));
   child.stderr.on('data', d => output.push(String(d)));
   const base = `http://127.0.0.1:${port}`;

test/greatest-cover-route.test.js

@@ -0,0 +1,75 @@
+'use strict';
+// BL-0053: Greatest covers are served from the reader's own copy, with a redirect until one exists.
+const test = require('node:test'), assert = require('node:assert/strict');
+const fs = require('fs'), os = require('os'), path = require('path'), net = require('net'), crypto = require('crypto');
+const { spawn } = require('child_process');
+const { loadCatalog } = require('../greatest');
+const { GreatestCovers } = require('../greatest/covers');
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+const hashPw = pw => { const salt = crypto.randomBytes(16).toString('hex'); return salt + ':' + crypto.scryptSync(pw, salt, 32).toString('hex'); };
+const sha = s => crypto.createHash('sha256').update(s).digest('hex');
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+
+async function freePort() {
+  const listener = net.createServer();
+  await new Promise(resolve => listener.listen(0, '127.0.0.1', resolve));
+  const port = listener.address().port;
+  await new Promise(resolve => listener.close(resolve));
+  return port;
+}
+
+test('Greatest covers come from the local copy, else redirect to the catalog URL', async t => {
+  const entries = loadCatalog().entries.filter(entry => entry.cover);
+  const [cached, missing] = entries;
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mc-greatest-cover-'));
+  const library = path.join(root, 'library'), data = path.join(root, 'data');
+  fs.mkdirSync(library, { recursive: true });
+  fs.mkdirSync(path.join(data, 'greatest-covers'), { recursive: true });
+  const version = new GreatestCovers(path.join(data, 'greatest-covers')).version(cached.cover);
+  fs.writeFileSync(path.join(data, 'greatest-covers', `${version}.png`), PNG);
+  const token = crypto.randomBytes(32).toString('base64url');
+  fs.writeFileSync(path.join(data, 'db.json'), JSON.stringify({
+    users: { reader: { name: 'reader', hash: hashPw('reader-password'), admin: false, created: Date.now(), settings: {} } },
+    sessions: { [sha(token)]: { u: 'reader', t: Date.now() } } }));
+
+  const port = await freePort(), output = [];
+  const child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
+    env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
+      SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', BACKUP: '',
+      GREATEST_COVER_WARM: '0' } });
+  child.stdout.on('data', d => output.push(String(d)));
+  child.stderr.on('data', d => output.push(String(d)));
+  t.after(async () => {
+    await new Promise(resolve => { if (child.exitCode !== null) return resolve(); child.once('exit', resolve); child.kill(); });
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+  const base = `http://127.0.0.1:${port}`;
+  let ready = false;
+  for (let n = 0; n < 100 && !ready; n++) {
+    ready = await fetch(base + '/health').then(r => r.ok).catch(() => false);
+    if (!ready) await sleep(50);
+  }
+  assert.ok(ready, output.join(''));
+  const get = (url, cookie = `sid=${token}`) => fetch(base + '/' + url, { headers: cookie ? { cookie } : {}, redirect: 'manual' });
+
+  const listing = await (await get('api/greatest')).json();
+  const coverOf = id => listing.entries.find(entry => entry.id === id).cover;
+  assert.equal(coverOf(cached.id), `api/greatest-cover?id=${encodeURIComponent(cached.id)}&v=${version}`);
+  assert.match(coverOf(missing.id), /^api\/greatest-cover\?id=.+&v=[0-9a-f]{16}$/);
+
+  const hit = await get(coverOf(cached.id));
+  assert.equal(hit.status, 200);
+  assert.equal(hit.headers.get('content-type'), 'image/png');
+  assert.equal(hit.headers.get('cache-control'), 'private, max-age=31536000, immutable');
+  assert.deepEqual(Buffer.from(await hit.arrayBuffer()), PNG);
+
+  const miss = await get(coverOf(missing.id));
+  assert.equal(miss.status, 302);
+  assert.equal(miss.headers.get('location'), missing.cover);
+  assert.equal(miss.headers.get('cache-control'), 'no-store');
+
+  assert.equal((await get(coverOf(cached.id), null)).status, 401);
+  assert.equal((await get('api/greatest-cover?id=not-in-the-catalog')).status, 404);
+  assert.equal((await get('api/greatest-cover?id=../../db.json')).status, 404);
+});

test/greatest-covers.test.js

@@ -0,0 +1,84 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { GreatestCovers } = require('../greatest/covers');
+
+const PNG = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const image = (body = PNG, type = 'image/png') => new Response(body, { status: 200, headers: { 'content-type': type } });
+
+function setup(t, responses, options = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mc-greatest-covers-'));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  const calls = [];
+  const fetchImpl = async (url, init) => {
+    calls.push({ url, init });
+    const next = responses[url];
+    if (next instanceof Error) throw next;
+    return typeof next === 'function' ? next() : next || new Response('missing', { status: 404 });
+  };
+  const sleeps = [];
+  const covers = new GreatestCovers(dir, { fetchImpl, sleep: async ms => { sleeps.push(ms); }, ...options });
+  return { dir, calls, sleeps, covers };
+}
+
+test('warm downloads each cover once and serves it from disk afterwards', async t => {
+  const a = 'https://img.example/a.png', b = 'https://img.example/b.jpg';
+  const { dir, calls, sleeps, covers } = setup(t, { [a]: () => image(), [b]: () => image(PNG, 'image/jpeg') });
+  const result = await covers.warm([a, b, a]);
+  assert.deepEqual(result, { fetched: 2, skipped: 1, failed: 0, stopped: null });
+  assert.equal(calls.length, 2);
+  assert.deepEqual(sleeps, [1000], 'one pause between two downloads, none before the first');
+  assert.ok(covers.file(a).endsWith('.png') && fs.existsSync(covers.file(a)));
+  assert.ok(covers.file(b).endsWith('.jpg'));
+  assert.equal(covers.file('https://img.example/other.png'), null);
+
+  // A restarted reader finds the stored files and asks nobody.
+  const reopened = new GreatestCovers(dir, { fetchImpl: async () => { throw new Error('must not fetch'); } });
+  assert.deepEqual(await reopened.warm([a, b]), { fetched: 0, skipped: 2, failed: 0, stopped: null });
+  assert.equal(reopened.file(a), covers.file(a));
+});
+
+test('a changed cover URL is a new file', async t => {
+  const { covers } = setup(t, { 'https://img.example/v1.png': () => image(), 'https://img.example/v2.png': () => image() });
+  await covers.warm(['https://img.example/v1.png', 'https://img.example/v2.png']);
+  assert.notEqual(covers.file('https://img.example/v1.png'), covers.file('https://img.example/v2.png'));
+  assert.notEqual(covers.version('https://img.example/v1.png'), covers.version('https://img.example/v2.png'));
+});
+
+test('non-images, oversized files, plain http and errors are skipped', async t => {
+  const html = 'https://img.example/page', big = 'https://img.example/big.png', declaredBig = 'https://img.example/declared.png';
+  const broken = 'https://img.example/broken.png', gone = 'https://img.example/gone.png';
+  const { covers, calls } = setup(t, {
+    [html]: () => new Response('<html>', { status: 200, headers: { 'content-type': 'text/html' } }),
+    [big]: () => image(Buffer.alloc(64)),
+    [declaredBig]: () => new Response(PNG, { status: 200, headers: { 'content-type': 'image/png', 'content-length': '999999' } }),
+    [broken]: new TypeError('fetch failed'),
+  }, { maxBytes: 32 });
+  const result = await covers.warm([html, big, declaredBig, broken, gone, 'http://img.example/plain.png', '', null]);
+  assert.deepEqual(result, { fetched: 0, skipped: 0, failed: 5, stopped: null });
+  assert.equal(calls.length, 5, 'plain http and empty URLs are never requested');
+  for (const url of [html, big, declaredBig, broken, gone]) assert.equal(covers.file(url), null);
+  assert.deepEqual(fs.readdirSync(covers.dir).filter(name => !name.startsWith('.')), []);
+});
+
+test('429 and 403 stop the run at once', async t => {
+  for (const status of [429, 403]) {
+    const first = 'https://img.example/1.png', second = 'https://img.example/2.png';
+    const { covers, calls } = setup(t, { [first]: () => new Response('', { status }), [second]: () => image() });
+    const result = await covers.warm([first, second]);
+    assert.equal(result.stopped, `HTTP ${status}`);
+    assert.equal(calls.length, 1);
+    assert.equal(covers.file(second), null);
+  }
+});
+
+test('requests carry a timeout and a fixed user agent', async t => {
+  const a = 'https://img.example/a.png';
+  const { covers, calls } = setup(t, { [a]: () => image() });
+  await covers.warm([a]);
+  assert.ok(calls[0].init.signal instanceof AbortSignal);
+  assert.match(calls[0].init.headers['user-agent'], /^MangaCircus/);
+});

test/library-index.test.js

@@ -78,7 +78,7 @@ test('reader serves a saved index immediately after restart and verifies it in b
     const output = [];
     child = spawn(process.execPath, ['server.js'], { cwd: path.resolve(__dirname, '..'), windowsHide: true,
       env: { ...process.env, LIBRARY: library, DATA: data, PORT: String(port), SCAN_INTERVAL: '0', FULL_SCAN_INTERVAL: '0',
-        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '' } });
+        SCRAPER_URL: 'http://127.0.0.1:9', SCRAPER_TOKEN: 'fixture-token', SCRAPER_TOKEN_FILE: '', GREATEST_COVER_WARM: '0' } });
     child.stdout.on('data', data => output.push(String(data)));
     child.stderr.on('data', data => output.push(String(data)));
     const base = `http://127.0.0.1:${port}`;

test/services.test.js

@@ -29,7 +29,7 @@ test('three services integrate collections, auth, custom covers and private heal
     const token = 'integration-test-only';
     const env = { ...process.env, DATA: data, LIBRARY: library, SCRAPER_DATA: path.join(data, 'scraper'),
       PORT: String(rp), SCRAPER_PORT: String(sp), SCRAPER_HOST: '127.0.0.1',
-      READER_URL: base, SCRAPER_URL: scraper, SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0', COOKIE_SECURE: '0' };
+      READER_URL: base, SCRAPER_URL: scraper, SCRAPER_TOKEN: token, SCRAPER_TOKEN_FILE: '', SCAN_INTERVAL: '0', COOKIE_SECURE: '0', GREATEST_COVER_WARM: '0' };
     for (const script of ['server.js', 'scraper/daemon.js']) {
       const child = spawn(process.execPath, [script], { cwd: root, env, windowsHide: true }); children.push(child);
       for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => output.push(chunk.toString()));