Files
gods-eye-view/src/sources/nominatimOutlines.js
T
Manjunath ecaddd838b Merge feat/voice-geometry onto main
Both stack parents (#837, #842) are on main, so the voice geometry branch
now builds on main directly. Conflict resolutions keep main's behaviour and
add the geometry work on top: osm_query gating on every provider, restored
admin identity for Nominatim outlines, merged analyst follow-up memory, and
the cancelled Globe View reset instruction ahead of the generic cancellation.
2026-11-03 14:33:34 +05:30

181 lines
5.8 KiB
JavaScript

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,
adminArea: body.outline.adminArea || null,
adminLevel: body.outline.adminLevel || 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 };
}