import { readResponseJsonCapped } from './httpBody.js'; import { createNominatimStatus } from './nominatimStatus.js'; /** * Browser client for the server's guarded outline route. The server owns the * endpoint, pacing, caps and caches; this client only asks once per explicit * voice ask and reads the tri-state answer the annotation resolver expects: * * - `{ polygons, name, class, type, osm }` — an accepted outline; * - `null` — the service answered and has no suitable polygon; * - `undefined` — a transient failure; a later retry may succeed; * - `{ rateLimited: true, retryAfterMs }` — busy; retry no sooner; * - `{ unavailable: true, retryable: false }` — disabled, capped for the * day, or no route: stop asking this session. */ const DEFAULT_ENDPOINT = '/api/geocode/outline'; const MAX_RESPONSE_BYTES = 3 * 1024 * 1024; const TIMEOUT_MS = 15_000; /** Ask kinds the route accepts. */ export const NOMINATIM_OUTLINE_KINDS = Object.freeze([ 'city', 'admin', 'neighborhood', 'landmark', 'building', ]); function validRing(ring) { if (!Array.isArray(ring) || ring.length < 4) return null; const out = []; for (const point of ring) { if (!Array.isArray(point)) return null; const [lon, lat] = point; if ( !Number.isFinite(lon) || !Number.isFinite(lat) || Math.abs(lon) > 180 || Math.abs(lat) > 90 ) return null; out.push([lon, lat]); } return out; } function validPolygons(value) { if (!Array.isArray(value) || !value.length) return null; const polygons = []; for (const rings of value) { if (!Array.isArray(rings) || !rings.length) return null; const clean = rings.map(validRing); // Never fill a malformed hole or silently discard a malformed part. if (clean.some((ring) => !ring)) return null; polygons.push(clean); } return polygons.length ? polygons : null; } export function createNominatimOutlineClient({ fetchImpl = (...args) => globalThis.fetch(...args), endpoint = DEFAULT_ENDPOINT, maxRemembered = 64, // The app's own route can say up front that Nominatim is not configured; // another endpoint is simply asked. configured = endpoint === DEFAULT_ENDPOINT ? createNominatimStatus({ fetchImpl }) : null, } = {}) { let unavailable = null; const remembered = new Map(); function remember(key, value) { remembered.delete(key); remembered.set(key, value); while (remembered.size > maxRemembered) remembered.delete(remembered.keys().next().value); } /** * `lat, lon` bias the search; `anchorLat, anchorLon` (the resolved place) * pick which same-name result answers. * * @param {{query: string, kind: string, lat?: number, lon?: number, anchorLat?: number, anchorLon?: number}} ask * @param {{signal?: AbortSignal}} [options] */ async function lookup( { query, kind, lat, lon, anchorLat, anchorLon }, { signal } = {}, ) { if (unavailable) return unavailable; const text = String(query || '').trim(); if (!text || text.length > 200 || !NOMINATIM_OUTLINE_KINDS.includes(kind)) return null; const params = new URLSearchParams({ q: text, kind }); if (Number.isFinite(lat) && Number.isFinite(lon)) { params.set('lat', lat.toFixed(3)); params.set('lon', lon.toFixed(3)); } if (Number.isFinite(anchorLat) && Number.isFinite(anchorLon)) { // Full anchor precision: rounding could cross a building's edge. params.set('alat', anchorLat.toFixed(6)); params.set('alon', anchorLon.toFixed(6)); } const key = params.toString(); if (remembered.has(key)) return remembered.get(key); // A cancelled ask spends nothing. signal?.throwIfAborted(); const capability = configured ? await configured() : null; // The probe may have waited: an ask cancelled meanwhile still spends nothing. signal?.throwIfAborted(); if (capability === false) { unavailable = { unavailable: true, retryable: false, code: 'NOMINATIM_DISABLED', }; return unavailable; } const controller = new AbortController(); const abort = () => controller.abort(); signal?.addEventListener('abort', abort, { once: true }); const timer = setTimeout(abort, TIMEOUT_MS); try { const response = await fetchImpl(`${endpoint}?${key}`, { signal: controller.signal, }); let body = null; try { body = await readResponseJsonCapped( response, MAX_RESPONSE_BYTES, controller.signal, ); } catch { body = null; } if (response.status === 404 || body?.retryable === false) { // No outline route here, disabled, or today's allowance is used. unavailable = { unavailable: true, retryable: false, code: body?.code }; return unavailable; } if (response.status === 429) { const seconds = Number(response.headers?.get?.('retry-after')); return { rateLimited: true, retryAfterMs: Number.isFinite(seconds) ? seconds * 1000 : null, }; } if (!response.ok || !body) return undefined; if (body.status === 'ZERO_RESULTS') { remember(key, null); return null; } const polygons = validPolygons(body.outline?.polygons); if (body.status !== 'OK' || !polygons) return undefined; const outline = { polygons, name: body.outline.name || null, class: body.outline.class || null, type: body.outline.type || null, osm: body.outline.osm || null, }; remember(key, outline); return outline; } catch { signal?.throwIfAborted(); return undefined; } finally { clearTimeout(timer); signal?.removeEventListener('abort', abort); } } return { lookup }; }