Add the news report model, markers and source

The pure half of a news layer: validated records for a news server's
`/api/news/hotspots|feed|outline` contract, a presentation model and canvas
markers and picture cards, and a fetch client.

- Colour carries severity only (0 no physical event, 1 minor, 2 significant,
  3 major), never a side; the category is the icon, the rim is attestation
  (confirmed, a claim, one side's own press), size grows with sources and
  markers fade with age.
- Cards say "Reported by {side} sources" and mark official channels; a
  machine-read English headline is labelled as such.
- `createNewsSource` reads same-origin routes with a 15 s timeout, a 4 MiB cap
  and record-by-record validation; `NEWS_API_PATHS` and `newsQueryAllowed`
  let a host proxy exactly what the client sends. A 503 marked unavailable
  means "not configured": no retries.
- Exported as `./layers/news/source`, with its own package boundary.
This commit is contained in:
Denis Groshev committed 2026-11-06 00:45:22 +01:00
1 parent dd83812a21
commit 2d9d518946
21 files changed
+2653

No files matched your search

+162
View File
@@ -0,0 +1,162 @@
import { readResponseJsonCapped } from '../../sources/httpBody.js';
import { isUnavailableCapability } from '../../sources/capability.js';
import {
normalizeFeedPayload,
normalizeHotspotsPayload,
normalizeOutlinePayload,
} from './records.js';
// A portable export (package.json): no i18n here. Failures stay English data;
// the layer shows them translated.
const msg = (text) => text;
const MAX_BYTES = 4 * 1024 * 1024;
const BASE_PATH = '/api/news';
// The outline geometry version the client draws (disputed areas included).
const OUTLINE_VERSION = '3';
/** The three read routes the news layer calls, for a host's path allowlist. */
export const NEWS_API_PATHS = Object.freeze([
`${BASE_PATH}/hotspots`,
`${BASE_PATH}/feed`,
`${BASE_PATH}/outline`,
]);
const FEED_KEYS = Object.freeze([
'hotspot',
'before',
'since',
'limit',
'category',
'relevance',
]);
const FLAG_KEYS = Object.freeze(['geo', 'today', 'events']);
const ISO = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/;
const LIST = /^[a-z][a-z,-]{0,127}$/;
const FEED_VALUE = {
hotspot: (v) => /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(v),
before: (v) => ISO.test(v),
since: (v) => ISO.test(v),
limit: (v) => /^\d{1,3}$/.test(v) && Number(v) >= 1 && Number(v) <= 500,
category: (v) => LIST.test(v),
relevance: (v) => LIST.test(v),
};
/** Feed query string from a plain object; unknown keys and empty values are dropped. */
export function newsFeedQuery(query = {}) {
const params = new URLSearchParams();
for (const key of FEED_KEYS) {
const value = query[key];
if (value !== undefined && value !== null && value !== '')
params.set(key, String(value));
}
for (const key of FLAG_KEYS) if (query[key]) params.set(key, '1');
return params.toString();
}
/**
* Whether a request URL is one this client sends: a known route, known keys
* only, each value in its form. A host proxying the routes can admit exactly
* these and refuse the rest.
* @param {URL} url
*/
export function newsQueryAllowed(url) {
const params = [...url.searchParams];
if (new Set(params.map(([key]) => key)).size !== params.length) return false;
if (url.pathname === `${BASE_PATH}/hotspots`) return params.length === 0;
if (url.pathname === `${BASE_PATH}/outline`) {
const keys = params.map(([key]) => key).sort();
const value = url.searchParams;
return (
params.length === 2 &&
keys[1] === 'v' &&
value.get('v') === OUTLINE_VERSION &&
((keys[0] === 'hotspot' && FEED_VALUE.hotspot(value.get('hotspot'))) ||
(keys[0] === 'country' &&
/^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/.test(value.get('country'))))
);
}
if (url.pathname !== `${BASE_PATH}/feed`) return false;
return params.every(([key, value]) =>
FLAG_KEYS.includes(key)
? value === '1'
: Object.hasOwn(FEED_VALUE, key) && FEED_VALUE[key](value),
);
}
/** A failed read: a server without the news routes is a permanent miss. */
async function responseError(response) {
let body = null;
try {
body = await readResponseJsonCapped(response, 16 * 1024);
} catch {
await response.body?.cancel?.().catch?.(() => {});
}
const unavailable =
response.status === 404 ||
(response.status === 503 && isUnavailableCapability(body));
return Object.assign(
new Error(
unavailable
? msg('News feed not configured on this server')
: msg('News feed unavailable'),
),
{
status: response.status,
code: unavailable ? 'unavailable' : 'http',
unavailable,
retryable: !unavailable,
},
);
}
/** Read hotspots, reports and outlines from the server's /api/news routes. */
export function createNewsSource({
fetchImpl = (...args) => globalThis.fetch(...args),
timeoutMs = 15_000,
} = {}) {
async function get(path, { signal } = {}) {
signal?.throwIfAborted();
const timeout = AbortSignal.timeout(timeoutMs);
const request = signal ? AbortSignal.any([signal, timeout]) : timeout;
const response = await fetchImpl(`${BASE_PATH}${path}`, {
signal: request,
cache: 'no-store',
redirect: 'error',
});
if (!response.ok) throw await responseError(response);
return readResponseJsonCapped(response, MAX_BYTES, request);
}
return {
async getHotspots({ signal } = {}) {
const payload = normalizeHotspotsPayload(
await get('/hotspots', { signal }),
);
if (!payload) throw new Error(msg('Malformed news hotspots response'));
return payload;
},
async getOutline(hotspotId, { signal } = {}) {
return normalizeOutlinePayload(
await get(
`/outline?hotspot=${encodeURIComponent(hotspotId)}&v=${OUTLINE_VERSION}`,
{ signal },
),
);
},
async getCountryOutline(country, { signal } = {}) {
return normalizeOutlinePayload(
await get(
`/outline?country=${encodeURIComponent(country)}&v=${OUTLINE_VERSION}`,
{ signal },
),
);
},
async getFeed(query = {}, { signal } = {}) {
const payload = normalizeFeedPayload(
await get(`/feed?${newsFeedQuery(query)}`, { signal }),
);
if (!payload) throw new Error(msg('Malformed news feed response'));
return payload;
},
};
}