fix(cctv): back off the Taiwan catalog when unreachable; review fixes

- taiwan.js: a failed download serves the last good table (up to 24 h)
  and is not retried for an hour. The table host does not answer from
  some networks outside Taiwan, and each attempt held the shared catalog
  refresh for the ~10 s connect timeout.
- Own server/providers/cctv/taiwan.js in package-boundaries.json
  (check:boundaries failed).
- Decode numeric character references; name falls back to the CCTVID
  when a row has no road details.
- Credit names the dataset and links the OGDL Taiwan licence.
- Document CCTV_TAIWAN_URL; list Taiwan in the CURRENT-STATE source table.
- Tests: isolate catalog env, reset loader state, cover the byte cap,
  failed fetch, backoff, last-good fallback, cap clamping, redirect with
  a valid body, name fallback, numeric entities and UUID camera ids.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

src/data/cctvTaiwan.test.mjs

@@ -1,14 +1,45 @@
-import { test } from 'node:test';
+import { afterEach, beforeEach, test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   loadTaiwanSources,
   parseTaiwanCctvXml,
+  resetTaiwanSourcesCache,
   taiwanCameraToSource,
   taiwanFrame,
   TAIWAN_FREEWAY_CCTV_URL,
+  TAIWAN_MAX_CATALOG_BYTES,
+  TAIWAN_RETRY_AFTER_FAILURE_MS,
 } from '../../server/providers/cctv/taiwan.js';
 import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
 
+// Settings that would steer the loader or the catalog away from the mocks.
+const ISOLATED_ENV = [
+  'CCTV_SOURCES_FILE',
+  'CCTV_SOURCES_JSON',
+  'CCTV_PREFER_AUSTIN',
+  'CCTV_FORCE_AUSTIN',
+  'CCTV_TAIWAN_ENABLED',
+  'CCTV_TAIWAN_URL',
+  'CCTV_TAIWAN_MAX_SOURCES',
+];
+
+let savedEnv = {};
+
+beforeEach(() => {
+  resetTaiwanSourcesCache();
+  savedEnv = Object.fromEntries(
+    ISOLATED_ENV.map((key) => [key, process.env[key]]),
+  );
+  for (const key of ISOLATED_ENV) delete process.env[key];
+});
+
+afterEach(() => {
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
 function cctvXml(...blocks) {
   return `<?xml version='1.0' encoding='utf-8'?>
 <CCTVList xmlns="http://traffic.transportdata.tw/standard/traffic/schema/">
@@ -158,27 +189,21 @@ test('a redirected or failed catalog contributes an empty pack', async (t) => {
       globalThis,
       'fetch',
       async () =>
-        new Response('', {
+        new Response(cctvXml(block()), {
           status,
           headers: status === 302 ? { location: 'https://evil.test/' } : {},
         }),
     );
+    resetTaiwanSourcesCache();
     assert.deepEqual(await loadTaiwanSources(), []);
   }
 });
 
 async function runCatalogWithTaiwanFlag(t, flag) {
   const requested = mockCatalog(t, cctvXml(block()));
-  const saved = process.env.CCTV_TAIWAN_ENABLED;
-  try {
-    if (flag === undefined) delete process.env.CCTV_TAIWAN_ENABLED;
-    else process.env.CCTV_TAIWAN_ENABLED = flag;
-    const sources = await createCctvCatalog({ sourceRoot: '/nonexistent' })();
-    return { requested, sources };
-  } finally {
-    if (saved === undefined) delete process.env.CCTV_TAIWAN_ENABLED;
-    else process.env.CCTV_TAIWAN_ENABLED = saved;
-  }
+  if (flag !== undefined) process.env.CCTV_TAIWAN_ENABLED = flag;
+  const sources = await createCctvCatalog({ sourceRoot: '/nonexistent' })();
+  return { requested, sources };
 }
 
 test('the Taiwan pack is in the catalog by default', async (t) => {
@@ -198,3 +223,120 @@ test('CCTV_TAIWAN_ENABLED=0 makes no Freeway Bureau request', async (t) => {
   );
   assert.ok(!sources.some((c) => c.cityId === 'taiwan'));
 });
+
+test('a catalog over the byte cap or a failed request contributes an empty pack', async (t) => {
+  t.mock.method(console, 'warn', () => {});
+  const padding = `<!--${'x'.repeat(TAIWAN_MAX_CATALOG_BYTES)}-->`;
+  t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response(cctvXml(block()) + padding),
+  );
+  assert.deepEqual(await loadTaiwanSources(), []);
+  resetTaiwanSourcesCache();
+  t.mock.method(globalThis, 'fetch', async () => {
+    throw new TypeError('fetch failed');
+  });
+  assert.deepEqual(await loadTaiwanSources(), []);
+});
+
+test('a failed download is not retried until the backoff ends', async (t) => {
+  t.mock.method(console, 'warn', () => {});
+  let calls = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    calls += 1;
+    throw new TypeError('fetch failed');
+  });
+  t.mock.method(Date, 'now', () => 1_000_000);
+  assert.deepEqual(await loadTaiwanSources(), []);
+  assert.deepEqual(await loadTaiwanSources(), []);
+  assert.equal(calls, 1, 'the second refresh made no request');
+  Date.now.mock.mockImplementation(
+    () => 1_000_000 + TAIWAN_RETRY_AFTER_FAILURE_MS + 1,
+  );
+  await loadTaiwanSources();
+  assert.equal(calls, 2, 'the backoff ends after an hour');
+});
+
+test('a failed download serves the last good table', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  const fetchMock = t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response(cctvXml(block())),
+  );
+  const first = await loadTaiwanSources();
+  assert.deepEqual(
+    first.map((c) => c.id),
+    ['tw-freeway-cctvn-10000'],
+  );
+  fetchMock.mock.mockImplementation(
+    async () => new Response('', { status: 503 }),
+  );
+  assert.deepEqual(
+    (await loadTaiwanSources()).map((c) => c.id),
+    ['tw-freeway-cctvn-10000'],
+  );
+});
+
+test('CCTV_TAIWAN_MAX_SOURCES is clamped to 1-2000', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  const rows = Array.from({ length: 3 }, (_, i) =>
+    block({
+      stream: `https://cctvn.freeway.gov.tw/abs2mjpg/bmjpg?camera=${i + 1}`,
+    }),
+  );
+  t.mock.method(
+    globalThis,
+    'fetch',
+    async () => new Response(cctvXml(...rows)),
+  );
+  for (const [value, expected] of [
+    ['0', 1],
+    ['2', 2],
+    ['5000', 3],
+    ['abc', 3],
+  ]) {
+    resetTaiwanSourcesCache();
+    process.env.CCTV_TAIWAN_MAX_SOURCES = value;
+    const sources = await loadTaiwanSources();
+    assert.equal(sources.length, expected, value);
+    assert.equal(sources.available, 3, value);
+  }
+});
+
+test('names fall back to the published ID when the row has no road details', () => {
+  const xml = cctvXml(block({ id: 'CCTV-N3-N-100-M' }))
+    .replace('<RoadName>國道1號</RoadName>', '<RoadName></RoadName>')
+    .replace('<LocationMile>0K+000</LocationMile>', '')
+    .replace('<Start>基隆端</Start><End>基隆交流道</End>', '');
+  const camera = taiwanCameraToSource(parseTaiwanCctvXml(xml)[0]);
+  assert.equal(camera.name, 'CCTV-N3-N-100-M');
+});
+
+test('numeric character references in the table are decoded', () => {
+  const xml = cctvXml(block()).replace(
+    '<RoadName>國道1號</RoadName>',
+    '<RoadName>&#22283;&#x9053;1號</RoadName>',
+  );
+  assert.equal(parseTaiwanCctvXml(xml)[0].roadName, '國道1號');
+});
+
+test('camera numbers that are UUIDs keep their case in the frame URL only', () => {
+  const camera = taiwanCameraToSource(
+    parseTaiwanCctvXml(
+      cctvXml(
+        block({
+          stream:
+            'https://cctvn5.freeway.gov.tw/abs2mjpg/bmjpg?camera=C3A580C9-0232-46A1-BFC6-927590758AB4',
+        }),
+      ),
+    )[0],
+  );
+  assert.equal(
+    camera.id,
+    'tw-freeway-cctvn5-c3a580c9-0232-46a1-bfc6-927590758ab4',
+  );
+  assert.match(camera.url, /camera=C3A580C9-0232-46A1-BFC6-927590758AB4$/);
+});

src/data/dataCredits.js

@@ -263,7 +263,8 @@ export const DATA_CREDITS = [
     html:
       'Freeway camera stills (Taiwan): ' +
       '<a href="https://www.freeway.gov.tw/" target="_blank" rel="noopener">Freeway Bureau, MOTC</a>, ' +
-      'Open Government Data License, Taiwan (Version 1.0)',
+      'CCTV static data (MOTC 2.0), released under the ' +
+      '<a href="https://data.gov.tw/license" target="_blank" rel="noopener">Open Government Data License, Taiwan (Version 1.0)</a>',
   },
   {
     key: 'calgary-cctv',