fix(osm): stop using public Overpass by default (#648) (#742)

Traffic roads come from OpenFreeMap vector tiles, or TomTom flow tiles with a
key (Hybrid by default). Military areas use OpenFreeMap polygons with a bundled
worldwide name index; wide views show named points. ALPR reads an hourly
OpenStreetMap extract. Cockpit place context and country, state and US county
outlines use bundled Natural Earth and US Census data. Overpass is used only
when an operator configures their own endpoint.

Also: camera arrivals no longer land below ground, keyless terrain retries on
429, bounded relation geometry for configured Overpass, one shared
OpenStreetMap credit, and separate tile and API transports for embedders.

Co-authored-by: theGaryLarson <[email protected]>
Co-authored-by: Milan Khanal <[email protected]>

src/services/groundFloor.js

@@ -547,7 +547,10 @@ export function createGroundFloor({ terrain, signal }) {
     ]);
   }
 
-  async function resolveGroundFloorCells(points) {
+  async function resolveGroundFloorCells(
+    points,
+    { signal: consumerSignal } = {},
+  ) {
     if (!Array.isArray(points) || !points.length) return;
     const cells = new Map();
     for (const p of points) {
@@ -560,7 +563,9 @@ export function createGroundFloor({ terrain, signal }) {
     }
     if (!cells.size) return;
     try {
-      await resolveEllipsoidalGround([...cells.values()]);
+      await resolveEllipsoidalGround([...cells.values()], {
+        signal: consumerSignal,
+      });
     } catch {
       /* best-effort — unresolved cells simply don't clamp */
     }

src/services/requests.js

@@ -1,3 +1,4 @@
+import { isUnavailableCapability } from '../sources/capability.js';
 import { createOverpassFeatureSource } from '../sources/overpassFeatures.js';
 /** Parse bounded retry information from a service response. */
 function retryAfterMs(value) {
@@ -15,6 +16,7 @@ export function createApplicationRequestServices({
   signal: lifetime,
   endpoints = {},
   features,
+  boundaryProbe = { timeoutMs: 3000, retryMs: 30_000 },
 } = {}) {
   const urls = {
     boundaries: '/api/overpass',
@@ -64,17 +66,70 @@ export function createApplicationRequestServices({
       throw new Error(`${label} unavailable (${response.status})`);
     return response.data;
   }
+  // Learn once per page whether the server has an Overpass instance, so an
+  // unconfigured server is never asked (and never answers with an error).
+  // Discovery is bounded; a failed or timed-out probe is forgotten and not
+  // retried for a short backoff, during which queries go to the server as
+  // they would against an older server without the probe.
+  let boundaryCapability = null;
+  let boundaryProbeRetryAt = 0;
+  function boundariesConfigured() {
+    if (boundaryCapability) return boundaryCapability;
+    if (Date.now() < boundaryProbeRetryAt) return Promise.resolve(null);
+    boundaryCapability = request(`${urls.boundaries}/status`, {
+      signal: AbortSignal.timeout(boundaryProbe.timeoutMs),
+    }).then(
+      (response) =>
+        response.ok && typeof response.data?.configured === 'boolean'
+          ? response.data.configured
+          : null, // an older server: fall back to asking per query
+      (error) => {
+        boundaryCapability = null;
+        if (lifetime?.aborted) throw error;
+        boundaryProbeRetryAt = Date.now() + boundaryProbe.retryMs;
+        return null;
+      },
+    );
+    return boundaryCapability;
+  }
+  /** Wait for a shared promise, but give up when this caller's signal aborts. */
+  function untilAborted(promise, signal) {
+    if (!signal) return promise;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+      const abort = () => reject(signal.reason);
+      signal.addEventListener('abort', abort, { once: true });
+      promise
+        .then(resolve, reject)
+        .finally(() => signal.removeEventListener('abort', abort));
+    });
+  }
   const services = {
     boundaries: {
       async query(query, { signal } = {}) {
+        if ((await untilAborted(boundariesConfigured(), signal)) === false) {
+          signal?.throwIfAborted();
+          return {
+            unavailable: true,
+            code: 'OVERPASS_NOT_CONFIGURED',
+            retryable: false,
+          };
+        }
         const response = await request(urls.boundaries, {
           method: 'POST',
           signal,
           headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
           body: `data=${encodeURIComponent(query)}`,
         });
+        if (isUnavailableCapability(response.data))
+          return {
+            unavailable: true,
+            code: 'OVERPASS_NOT_CONFIGURED',
+            retryable: false,
+          };
         const retry = response.headers?.get?.('Retry-After');
         if (
+          response.status === 406 ||
           response.status === 429 ||
           (response.status === 503 && retry != null)
         )

src/services/requests.test.mjs

@@ -42,3 +42,55 @@ test('boundary throttle status survives empty or invalid error bodies', async ()
     assert.deepEqual(await services.boundaries.query('fixture'), { rateLimited: true, retryAfterMs: 5000 });
   }
 });
+
+/** A transport whose status probe behaves as told; queries answer with no elements. */
+function probeTransport(status) {
+  const seen = [];
+  const fetchImpl = (url, init = {}) => {
+    seen.push(`${init.method || 'GET'} ${url}`);
+    if (!String(url).endsWith('/status')) return Promise.resolve(Response.json({ elements: [] }));
+    return status(init);
+  };
+  return { seen, fetchImpl };
+}
+const stalled = (init) => new Promise((_, reject) => init.signal.addEventListener('abort', () => reject(init.signal.reason)));
+
+test('a stalled capability probe times out and queries proceed; no re-probe during backoff', async () => {
+  const { seen, fetchImpl } = probeTransport(stalled);
+  const services = createApplicationRequestServices({ fetchImpl, boundaryProbe: { timeoutMs: 20, retryMs: 60_000 } });
+  const started = Date.now();
+  assert.deepEqual(await services.boundaries.query('fixture'), []);
+  assert.ok(Date.now() - started < 1000);
+  assert.deepEqual(await services.boundaries.query('fixture'), []);
+  assert.deepEqual(seen, ['GET /api/overpass/status', 'POST /api/overpass', 'POST /api/overpass']);
+});
+
+test('a caller cancelled while the probe is pending stops waiting at once', async () => {
+  const { seen, fetchImpl } = probeTransport(stalled);
+  const services = createApplicationRequestServices({ fetchImpl, boundaryProbe: { timeoutMs: 60_000, retryMs: 60_000 } });
+  const caller = new AbortController();
+  const pending = services.boundaries.query('fixture', { signal: caller.signal });
+  setTimeout(() => caller.abort(), 10);
+  await assert.rejects(pending, { name: 'AbortError' });
+  assert.deepEqual(seen, ['GET /api/overpass/status']);
+});
+
+test('a failed probe is retried after its backoff, not on every query', async () => {
+  let failures = 1;
+  const { seen, fetchImpl } = probeTransport(async () => {
+    if (failures-- > 0) throw new TypeError('network');
+    return Response.json({ configured: false });
+  });
+  const services = createApplicationRequestServices({ fetchImpl, boundaryProbe: { timeoutMs: 1000, retryMs: 30 } });
+  assert.deepEqual(await services.boundaries.query('fixture'), []);
+  assert.deepEqual(await services.boundaries.query('fixture'), []);
+  await new Promise((resolve) => setTimeout(resolve, 50));
+  assert.equal((await services.boundaries.query('fixture')).code, 'OVERPASS_NOT_CONFIGURED');
+  assert.equal((await services.boundaries.query('fixture')).code, 'OVERPASS_NOT_CONFIGURED');
+  assert.deepEqual(seen, [
+    'GET /api/overpass/status',
+    'POST /api/overpass',
+    'POST /api/overpass',
+    'GET /api/overpass/status',
+  ]);
+});

src/services/terrainHeights.js

@@ -172,12 +172,12 @@ export function createTerrainHeights({
    * @param {Array<{key: string, lat: number, lon: number}>} chunk
    * @returns {Promise<Map<string, number>>} key -> ellipsoid height (m)
    */
-  async function fetchChunk(chunk) {
+  async function fetchChunk(chunk, requestSignal = signal) {
     // lon,lat order (matches the proxy's documented `points=lon,lat;…` contract
     // and Task 2's implementation).
     const results = await source.getHeights(chunk, {
-      signal: signal
-        ? AbortSignal.any([signal, AbortSignal.timeout(30000)])
+      signal: requestSignal
+        ? AbortSignal.any([requestSignal, AbortSignal.timeout(30000)])
         : AbortSignal.timeout(30000),
     });
     const body = { results };
@@ -239,8 +239,15 @@ export function createTerrainHeights({
    * @returns {Promise<Array<{ellipsoid:number, source:'reearth'|'geoid-fallback'}>>}
    *   Same length and order as `coords`.
    */
-  async function resolveEllipsoidalGround(coords) {
-    signal?.throwIfAborted();
+  async function resolveEllipsoidalGround(
+    coords,
+    { signal: consumerSignal } = {},
+  ) {
+    const requestSignal =
+      signal && consumerSignal
+        ? AbortSignal.any([signal, consumerSignal])
+        : consumerSignal || signal;
+    requestSignal?.throwIfAborted();
     if (!Array.isArray(coords) || coords.length === 0) return [];
 
     // Build the per-input work list (key + original index) up front so the
@@ -293,8 +300,8 @@ export function createTerrainHeights({
     for (let i = 0; i < uncached.length; i += CHUNK_SIZE) {
       const chunk = uncached.slice(i, i + CHUNK_SIZE);
       try {
-        const resolved = await fetchChunk(chunk);
-        signal?.throwIfAborted();
+        const resolved = await fetchChunk(chunk, requestSignal);
+        requestSignal?.throwIfAborted();
         for (const item of chunk) {
           const ellipsoid = resolved.get(item.key);
           // Round 6: only a FINITE value may be cached as 'reearth'. A point
@@ -310,13 +317,13 @@ export function createTerrainHeights({
           }
         }
       } catch {
-        signal?.throwIfAborted();
+        requestSignal?.throwIfAborted();
         // Proxy down (or cold cache had nothing to serve-stale) — fall back to
         // geoid math for every point in this chunk. `ensureGeoidReady()` is
         // awaited lazily, only on the fallback path, so the common (proxy
         // healthy) case never pays for the geoid grid's dynamic import.
         await ensureGeoidReady();
-        signal?.throwIfAborted();
+        requestSignal?.throwIfAborted();
         for (const item of chunk) {
           const ellipsoid = geoidFallback(
             item.lat,