merge main a16eb07 into feat/voice-outlines

src/data/cctvA22.test.mjs

@@ -0,0 +1,226 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  a22WebcamToSource,
+  loadA22SourcesFromOpenDataHub,
+} from '../../server/providers/cctv/sources.js';
+import {
+  A22_DEFAULT_GROUND_ELEVATION_M,
+  A22_IMAGE_ORIGIN,
+  DEFAULT_A22_CCTV_URL,
+} from '../../server/providers/cctv/constants.js';
+import { createCctvCatalog } from '../../server/providers/cctv/catalog.js';
+import { fetchWithinHost } from '../../server/providers/cctv/media.js';
+import { staticFrameRefreshMs } from './cctvLod.js';
+
+/** One Open Data Hub `WebcamInfo` item, shaped like the live a22 payload. */
+const item = (
+  patch = {},
+  { km = '68', lat = 46.53591, lon = 11.49772 } = {},
+) => ({
+  Id: `A22_${km}`,
+  Active: true,
+  Source: 'a22',
+  Shortname: 'ADS Sciliar',
+  Webcamname: { it: 'ADS Sciliar' },
+  Webcamurl: `https://www.autobrennero.it/WebCamImg/km${km}.jpg`,
+  Mapping: { a22: { km } },
+  GpsInfo: [{ Gpstype: 'position', Latitude: lat, Longitude: lon }],
+  LicenseInfo: {
+    ClosedData: false,
+    LicenseHolder: 'https://www.autobrennero.it/',
+  },
+  ...patch,
+});
+
+test('an A22 webcam maps to a source on the pinned operator frame', () => {
+  const source = a22WebcamToSource(item());
+  assert.equal(source.id, 'it-a22-km68');
+  assert.equal(source.name, 'A22 ADS Sciliar (km 68)');
+  assert.equal(source.city, 'A22 Brennero');
+  assert.equal(source.cityId, 'a22');
+  assert.equal(source.provider, 'Autostrada del Brennero');
+  assert.equal(source.lat, 46.53591);
+  assert.equal(source.lon, 11.49772);
+  assert.equal(source.headingConfidence, 'low');
+  assert.equal(source.feedType, 'image');
+  assert.equal(source.sourceKind, 'a22-opendatahub');
+  assert.equal(source.code, 'ADS SCILIAR');
+  assert.equal(source.url, `${A22_IMAGE_ORIGIN}km68.jpg`);
+  assert.equal(source.snapshotUrl, source.url);
+});
+
+test('ground elevation follows the motorway from the Brenner Pass to the Po', () => {
+  const brenner = a22WebcamToSource(
+    item({ Shortname: 'Brennero' }, { km: '1', lat: 46.99682, lon: 11.50218 }),
+  );
+  const ponte = a22WebcamToSource(
+    item(
+      { Shortname: 'Ponte Po' },
+      { km: '272', lat: 45.03145, lon: 10.85369 },
+    ),
+  );
+  assert.ok(brenner.groundElevationM > 1300);
+  assert.ok(ponte.groundElevationM < 50);
+  // A kilometre the table does not know falls back to the corridor prior.
+  const unknown = a22WebcamToSource(
+    item({}, { km: '150', lat: 45.95, lon: 11.05 }),
+  );
+  assert.equal(unknown.groundElevationM, A22_DEFAULT_GROUND_ELEVATION_M);
+});
+
+test('inactive cameras, off-host frames and bad geometry are dropped', () => {
+  assert.equal(a22WebcamToSource(item({ Active: false })), null);
+  assert.equal(a22WebcamToSource(item({ Source: 'other' })), null);
+  assert.equal(
+    a22WebcamToSource(
+      item({ Webcamurl: 'https://evil.test/WebCamImg/km68.jpg' }),
+    ),
+    null,
+  );
+  // The frame must be exactly the camera's own kilometre image.
+  assert.equal(
+    a22WebcamToSource(
+      item({ Webcamurl: 'https://www.autobrennero.it/WebCamImg/km1.jpg' }),
+    ),
+    null,
+  );
+  assert.equal(
+    a22WebcamToSource(item({ Mapping: { a22: { km: '../x' } } })),
+    null,
+  );
+  // Milan: plausible, but off the Brenner–Modena corridor.
+  assert.equal(
+    a22WebcamToSource(item({}, { km: '68', lat: 45.46, lon: 9.19 })),
+    null,
+  );
+  assert.equal(a22WebcamToSource(item({ GpsInfo: [] })), null);
+  assert.equal(a22WebcamToSource(null), null);
+});
+
+test('the loader dedupes, orders north to south, and degrades to empty', async (t) => {
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  const requested = [];
+  const fetchMock = t.mock.method(globalThis, 'fetch', async (url) => {
+    requested.push(String(url));
+    return Response.json({
+      TotalResults: 3,
+      Items: [
+        item(
+          { Shortname: 'Ponte Po' },
+          { km: '272', lat: 45.03145, lon: 10.85369 },
+        ),
+        item(),
+        item(),
+        item(
+          { Shortname: 'Brennero' },
+          { km: '1', lat: 46.99682, lon: 11.50218 },
+        ),
+      ],
+    });
+  });
+  const cameras = await loadA22SourcesFromOpenDataHub();
+  assert.deepEqual(requested, [DEFAULT_A22_CCTV_URL]);
+  assert.deepEqual(
+    cameras.map((c) => c.id),
+    ['it-a22-km1', 'it-a22-km68', 'it-a22-km272'],
+  );
+
+  fetchMock.mock.mockImplementation(
+    async () => new Response('nope', { status: 503 }),
+  );
+  assert.deepEqual(await loadA22SourcesFromOpenDataHub(), []);
+  fetchMock.mock.mockImplementation(
+    async () =>
+      new Response(null, {
+        status: 302,
+        headers: { Location: 'https://evil.test/' },
+      }),
+  );
+  assert.deepEqual(await loadA22SourcesFromOpenDataHub(), []);
+  fetchMock.mock.mockImplementation(async () => {
+    throw new Error('offline');
+  });
+  assert.deepEqual(await loadA22SourcesFromOpenDataHub(), []);
+});
+
+const runCatalog = async (t) => {
+  const requested = [];
+  t.mock.method(console, 'log', () => {});
+  t.mock.method(console, 'warn', () => {});
+  t.mock.method(globalThis, 'fetch', async (url) => {
+    const href = String(url);
+    requested.push(href);
+    if (href === DEFAULT_A22_CCTV_URL) {
+      return Response.json({ Items: [item()] });
+    }
+    return Response.json([]);
+  });
+  const sources = await createCctvCatalog({ sourceRoot: '/nonexistent' })();
+  return { requested, sources };
+};
+
+const withEnv = async (patch, fn) => {
+  const saved = { ...process.env };
+  try {
+    delete process.env.CCTV_SOURCES_FILE;
+    delete process.env.CCTV_SOURCES_JSON;
+    delete process.env.CCTV_A22_ENABLED;
+    Object.assign(process.env, patch);
+    await fn();
+  } finally {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in saved)) delete process.env[key];
+    }
+    Object.assign(process.env, saved);
+  }
+};
+
+test('the A22 lane is wired into the catalog', async (t) => {
+  await withEnv({}, async () => {
+    const { requested, sources } = await runCatalog(t);
+    assert.ok(requested.includes(DEFAULT_A22_CCTV_URL));
+    assert.deepEqual(
+      sources.filter((s) => s.cityId === 'a22').map((s) => s.id),
+      ['it-a22-km68'],
+    );
+  });
+});
+
+test('CCTV_A22_ENABLED=0 keeps the lane from being loaded', async (t) => {
+  await withEnv({ CCTV_A22_ENABLED: '0' }, async () => {
+    const { requested, sources } = await runCatalog(t);
+    assert.equal(requested.includes(DEFAULT_A22_CCTV_URL), false);
+    assert.deepEqual(
+      sources.filter((s) => s.cityId === 'a22'),
+      [],
+    );
+  });
+});
+
+test('a redirect on the A22 frame host stays inside WebCamImg/', async () => {
+  const frame = `${A22_IMAGE_ORIGIN}km68.jpg`;
+  const redirectTo = (location) => async (url) =>
+    url === frame
+      ? new Response(null, { status: 302, headers: { location } })
+      : new Response('frame', { headers: { 'content-type': 'image/jpeg' } });
+  for (const location of ['/it/area-riservata/', '/WebCamImg/../x.jpg'])
+    assert.equal(
+      await fetchWithinHost(frame, {}, redirectTo(location)),
+      null,
+      location,
+    );
+  const followed = await fetchWithinHost(
+    frame,
+    {},
+    redirectTo('/WebCamImg/km77.jpg'),
+  );
+  assert.equal(await followed.text(), 'frame');
+});
+
+test('A22 ambient cards refresh on the highway cadence, not the default', () => {
+  const source = a22WebcamToSource(item());
+  assert.equal(staticFrameRefreshMs(source), 3 * 60 * 1000);
+});

src/data/cctvLod.js

@@ -42,6 +42,9 @@ const PROVIDER_STATIC_REFRESH_MS = Object.freeze({
   // every 20s showed no change inside 64s but a new frame by ~90-150s later —
   // matches the other highway packs' 3-minute cadence.
   'servei català de trànsit': 3 * 60 * 1000,
+  // Autobrennero (A22) refreshes its stills about once a minute (Last-Modified
+  // tracks the minute); 3 min matches the other highway packs.
+  'autostrada del brennero': 3 * 60 * 1000,
 });
 
 /**

src/data/dataCredits.js

@@ -343,6 +343,13 @@ export const DATA_CREDITS = [
     key: 'panoramax',
     html: 'Street Level: imagery © <a href="https://panoramax.fr" target="_blank" rel="noopener">Panoramax</a> contributors, licence per picture',
   },
+  {
+    key: 'a22-cctv',
+    html:
+      'Motorway webcams (A22 Brennero–Modena): images © ' +
+      '<a href="https://www.autobrennero.it/" target="_blank" rel="noopener">Autostrada del Brennero S.p.A.</a>, ' +
+      'camera list via the <a href="https://opendatahub.com/" target="_blank" rel="noopener">Open Data Hub</a> (NOI Techpark)',
+  },
   {
     key: 'gbfs',
     html:

src/data/firmsProxy.test.mjs

@@ -1,7 +1,18 @@
 import assert from 'node:assert/strict';
 import fs from 'node:fs';
 import test from 'node:test';
+import { EventEmitter } from 'node:events';
+import dns from 'node:dns/promises';
+import https from 'node:https';
+import net from 'node:net';
+import { Readable } from 'node:stream';
 import { filterTrailing24h, parseFirmsCsv } from './firmsCsv.js';
+import {
+  describeFetchError,
+  fetchFirms,
+  fetchIpv4,
+  isAddressSelectionFailure,
+} from '../../server/providers/firms.js';
 
 const config = fs.readFileSync(new URL('../../server/providers/firms.js', import.meta.url), 'utf8');
 const start = config.indexOf('  async function refreshUpstream(key) {');
@@ -17,8 +28,8 @@ const recent = { acqDate: '2026-09-11', acqTime: '1100' };
 // Inject only its upstream, clock and filter dependencies; keep its aggregation
 // and source-status code intact, including failures while consuming records.
 function createRefresh(fetchSource, filter = filterTrailing24h) {
-  return new Function('SOURCES', 'fetchSource', 'filterTrailing24h', 'Date', 'console',
-    `return (${refreshSource});`)(SOURCES, fetchSource, filter, { now: () => NOW }, { warn() {} });
+  return new Function('SOURCES', 'fetchSource', 'filterTrailing24h', 'describeFetchError', 'Date', 'console',
+    `return (${refreshSource});`)(SOURCES, fetchSource, filter, describeFetchError, { now: () => NOW }, { warn() {} });
 }
 
 test('FIRMS retains large sources in order and filters expired rows', async () => {
@@ -78,3 +89,216 @@ test('FIRMS distinguishes all-source failure from successful empty sources', asy
   assert.deepEqual(result.fires, []);
   assert.deepEqual(result.sources, SOURCES.map(source => ({ source, count: 0, ok: true })));
 });
+
+// #68: Node's network-family auto-selection gives each address a short attempt
+// timeout, abandons a slow IPv4 handshake for an unreachable IPv6 address, and
+// reports only `fetch failed`. This is the shape Node 24 throws for it.
+function addressSelectionFailure() {
+  const v4 = Object.assign(new Error('connect ETIMEDOUT 198.118.194.34:443'), { code: 'ETIMEDOUT' });
+  const v6 = Object.assign(new Error('connect ENETUNREACH 2001:4d0:241a:40c0::34:443'), { code: 'ENETUNREACH' });
+  const cause = Object.assign(new AggregateError([v4, v6]), { code: 'ETIMEDOUT' });
+  return new TypeError('fetch failed', { cause });
+}
+// Node 26's fetch wraps the same AggregateError in a ConnectTimeoutError.
+function wrappedAddressSelectionFailure() {
+  const inner = addressSelectionFailure().cause;
+  const cause = Object.assign(new Error('Connect Timeout Error (attempted addresses: 198.118.194.34:443, 2001:4d0:241a:40c0::34:443, timeout: 10000ms)'),
+    { name: 'ConnectTimeoutError', code: 'UND_ERR_CONNECT_TIMEOUT', cause: inner });
+  return new TypeError('fetch failed', { cause });
+}
+const URL_WITH_KEY = 'https://firms.modaps.eosdis.nasa.gov/api/area/csv/SECRET/VIIRS_SNPP_NRT/world/2';
+
+test('FIRMS failures log the socket cause, never the keyed URL', () => {
+  const described = describeFetchError(addressSelectionFailure());
+  assert.equal(described,
+    'fetch failed (connect ETIMEDOUT 198.118.194.34:443; connect ENETUNREACH 2001:4d0:241a:40c0::34:443)');
+  assert.ok(!described.includes('SECRET'));
+  assert.equal(describeFetchError(wrappedAddressSelectionFailure()), described, 'Node 26 reports the same attempts');
+  const single = new TypeError('fetch failed', { cause: Object.assign(new Error('getaddrinfo ENOTFOUND x'), { code: 'ENOTFOUND' }) });
+  assert.equal(describeFetchError(single), 'fetch failed (getaddrinfo ENOTFOUND x)');
+  assert.equal(describeFetchError(new Error('HTTP 503')), 'HTTP 503');
+});
+
+test('FIRMS retries once over IPv4 when every address fails to connect', async () => {
+  for (const shape of [addressSelectionFailure, wrappedAddressSelectionFailure]) {
+    const retried = [];
+    await fetchFirms(URL_WITH_KEY, {}, {
+      fetchImpl: async () => { throw shape(); },
+      fetchIpv4Impl: async (url) => { retried.push(url); return new Response('csv'); },
+      warn() {},
+    });
+    assert.deepEqual(retried, [URL_WITH_KEY], `${shape.name} is retried`);
+  }
+  const signal = new AbortController().signal;
+  const ok = new Response('csv');
+  const retried = [];
+  const warnings = [];
+  const response = await fetchFirms(URL_WITH_KEY, { signal }, {
+    fetchImpl: async () => { throw addressSelectionFailure(); },
+    fetchIpv4Impl: async (url, options) => { retried.push([url, options]); return ok; },
+    warn: (message) => warnings.push(message),
+  });
+  assert.equal(response, ok);
+  assert.deepEqual(retried, [[URL_WITH_KEY, { signal }]], 'one retry, same URL and deadline');
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /ETIMEDOUT 198\.118\.194\.34:443; .*ENETUNREACH .* retrying over IPv4/);
+  assert.ok(!warnings[0].includes('SECRET'));
+
+  const failure = new Error('connect ETIMEDOUT 198.118.194.34:443');
+  await assert.rejects(fetchFirms(URL_WITH_KEY, {}, {
+    fetchImpl: async () => { throw addressSelectionFailure(); },
+    fetchIpv4Impl: async () => { throw failure; },
+    warn() {},
+  }), (err) => err === failure, 'a failed retry reports its own error');
+});
+
+test('FIRMS does not retry anything but an address-selection failure', async () => {
+  const deps = (fetchImpl) => ({
+    fetchImpl,
+    fetchIpv4Impl: async () => assert.fail('must not retry'),
+    warn: () => assert.fail('must not warn'),
+  });
+  const serverError = new Response('down', { status: 503 });
+  assert.equal(await fetchFirms(URL_WITH_KEY, {}, deps(async () => serverError)), serverError);
+  for (const thrown of [
+    new TypeError('fetch failed', { cause: Object.assign(new Error('getaddrinfo ENOTFOUND x'), { code: 'ENOTFOUND' }) }),
+    new TypeError('fetch failed', { cause: new AggregateError([]) }),
+    new TypeError('fetch failed'),
+    new DOMException('The operation was aborted due to timeout', 'TimeoutError'),
+  ]) {
+    await assert.rejects(fetchFirms(URL_WITH_KEY, {}, deps(async () => { throw thrown; })), (err) => err === thrown);
+  }
+  const controller = new AbortController();
+  controller.abort();
+  const aborted = addressSelectionFailure();
+  await assert.rejects(fetchFirms(URL_WITH_KEY, { signal: controller.signal },
+    deps(async () => { throw aborted; })), (err) => err === aborted, 'an expired deadline is not retried');
+});
+
+test('the IPv4 retry connects to an IPv4 address only', async (t) => {
+  // `localhost` resolves to both ::1 and 127.0.0.1. Listen on both with the
+  // same port and record which one the retry reaches; the TLS handshake then
+  // fails against a plain socket, which is fine — only the connection matters.
+  const reached = [];
+  const listen = (host, port) => new Promise((resolve, reject) => {
+    const server = net.createServer((socket) => { reached.push(host); socket.destroy(); });
+    server.once('error', reject).listen(port, host, () => resolve(server));
+  });
+  const v4 = await listen('127.0.0.1', 0);
+  t.after(() => v4.close());
+  const { port } = v4.address();
+  let v6;
+  try {
+    v6 = await listen('::1', port);
+  } catch {
+    t.skip('no IPv6 loopback on this host, so IPv4-only cannot be told apart');
+    return;
+  }
+  t.after(() => v6.close());
+  const order = await dns.lookup('localhost', { all: true });
+  if (order[0]?.family !== 6) {
+    t.skip('localhost resolves IPv4 first here, so IPv4-only cannot be told apart');
+    return;
+  }
+  await assert.rejects(fetchIpv4(`https://localhost:${port}/`, { signal: AbortSignal.timeout(5_000) }));
+  assert.deepEqual(reached, ['127.0.0.1']);
+});
+
+// Answer the IPv4 retry with `status`, invoking the response callback
+// asynchronously as `https.request` does, outside the caller's promise.
+// The returned promise rejects on an uncaught exception, so a regression fails
+// the race at once instead of crashing the test runner.
+function mockIpv4Status(t, status, statusMessage = '') {
+  let crash;
+  const crashed = new Promise((_resolve, reject) => (crash = reject));
+  const onUncaught = (error) =>
+    crash(new Error(`uncaught exception: ${error.message}`));
+  process.on('uncaughtException', onUncaught);
+  t.after(() => process.off('uncaughtException', onUncaught));
+  t.mock.method(https, 'request', (_url, _options, callback) => {
+    const request = new EventEmitter();
+    request.end = () =>
+      setImmediate(() =>
+        callback(
+          Object.assign(Readable.from([]), {
+            statusCode: status,
+            statusMessage,
+            headers: { 'content-type': 'text/csv' },
+          }),
+        ),
+      );
+    return request;
+  });
+  return crashed;
+}
+
+for (const status of [204, 205, 304]) {
+  test(`the IPv4 retry answering null-body status ${status} resolves instead of crashing`, async (t) => {
+    const crashed = mockIpv4Status(t, status);
+    const response = await Promise.race([fetchIpv4(URL_WITH_KEY), crashed]);
+    assert.equal(response.status, status);
+    assert.equal(response.body, null);
+  });
+}
+
+for (const status of [600, 999]) {
+  test(`the IPv4 retry answering out-of-range status ${status} rejects instead of crashing`, async (t) => {
+    const crashed = mockIpv4Status(t, status);
+    await assert.rejects(
+      Promise.race([fetchIpv4(URL_WITH_KEY), crashed]),
+      new RegExp(`unsupported status ${status}`),
+    );
+  });
+}
+
+test('the IPv4 retry answering an invalid reason phrase rejects instead of crashing', async (t) => {
+  const crashed = mockIpv4Status(t, 200, 'OK\x7f');
+  await assert.rejects(Promise.race([fetchIpv4(URL_WITH_KEY), crashed]), TypeError);
+});
+
+// The fixtures above copy Node's error shape; check it against a real fetch so
+// a Node or undici change that stops matching fails here instead of silently
+// disabling the retry. A closed port on `localhost` refuses both addresses.
+test('a real all-addresses connect failure is recognised as address selection', async (t) => {
+  const probe = net.createServer();
+  try {
+    await new Promise((resolve, reject) => probe.once('error', reject).listen(0, '::1', resolve));
+  } catch {
+    t.skip('no IPv6 loopback on this host');
+    return;
+  }
+  const { port } = probe.address();
+  await new Promise((resolve) => probe.close(resolve));
+  const v4 = net.createServer();
+  await new Promise((resolve, reject) => v4.once('error', reject).listen(port, '127.0.0.1', resolve));
+  await new Promise((resolve) => v4.close(resolve));
+  const err = await fetch(`http://localhost:${port}/`).then(() => null, (error) => error);
+  assert.ok(err, 'a closed port refuses the connection');
+  assert.equal(isAddressSelectionFailure(err), true, describeFetchError(err));
+  assert.match(describeFetchError(err), /ECONNREFUSED .*; .*ECONNREFUSED/);
+});
+
+// #68 only stays fixed while both upstream calls go through fetchFirms; the
+// refresh harness injects fetchSource, so guard the call sites directly.
+test('every FIRMS upstream request goes through the IPv4 fallback', async () => {
+  assert.doesNotMatch(config, /await fetch\(/, 'no FIRMS request bypasses fetchFirms');
+  const fetchStart = config.indexOf('  async function fetchSource(key, source) {');
+  assert.notEqual(fetchStart, -1, 'FIRMS fetchSource exists');
+  const fetchSourceText = config.slice(fetchStart, config.indexOf('\n  }', fetchStart) + 4);
+  const calls = [];
+  const response = new Response('latitude,longitude\n');
+  const fetchSource = new Function('fetchFirms', 'readResponseTextCapped', 'parseFirmsCsv',
+    'FIRMS_MAX_RESPONSE_BYTES', 'AbortSignal', 'fetch', `return (${fetchSourceText});`)(
+    async (url, options) => { calls.push(['fetchFirms', url, options.signal]); return response; },
+    async (res, cap, signal) => { calls.push(['read', res, signal]); return 'csv'; },
+    () => [],
+    1024,
+    AbortSignal,
+    () => assert.fail('fetchSource must call fetchFirms, not fetch'),
+  );
+  assert.deepEqual(await fetchSource('SECRET', 'MODIS_NRT'), []);
+  assert.equal(calls.length, 2);
+  assert.equal(calls[0][0], 'fetchFirms');
+  assert.ok(calls[0][2] instanceof AbortSignal);
+  assert.deepEqual(calls[1], ['read', response, calls[0][2]], 'the body read shares the request deadline');
+});