fix: address GNSS integrity and aircraft emergency review findings

server/providers/gnssIntegrity.js

@@ -16,10 +16,13 @@ import { makeRateLimiter, clientKey } from './common/rate-limit.js';
 const RADIUS_NM = 250;
 const CACHE_MS = 60_000;
 const CACHE_MAX = 64;
-/** Cooldown after a 429 or 5xx when upstream sends no usable Retry-After. */
+/** Default 429 cooldown when upstream sends no usable Retry-After. */
 const COOLDOWN_MS = 60_000;
-/** Minimum backoff; a valid longer upstream deadline is never shortened. */
+/** Bound sane upstream deadlines to one hour; never shorten a deadline within that range. */
 const COOLDOWN_MIN_MS = 5_000;
+const COOLDOWN_MAX_MS = 60 * 60_000;
+const FAILURE_COOLDOWN_MS = 15_000;
+const MAX_IN_FLIGHT = 8;
 const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
 const TIMEOUT_MS = 10_000;
 
@@ -36,13 +39,14 @@ export function gnssIntegrityAnchor(url) {
 /** Cooldown (ms) an upstream 429 earns, honouring Retry-After when sane. */
 export function gnssRetryCooldownMs(raw, nowMs) {
   if (raw) {
-    const seconds = Number(raw);
+    const seconds = /^\d+(?:\.\d+)?$/.test(raw.trim()) ? Number(raw) : NaN;
     const ms = seconds * 1000;
-    if (Number.isFinite(ms) && seconds > 0)
-      return Math.max(COOLDOWN_MIN_MS, ms);
-    const at = Date.parse(raw);
+    if (Number.isFinite(seconds) && seconds > 0)
+      return Math.min(COOLDOWN_MAX_MS, Math.max(COOLDOWN_MIN_MS, ms));
+    const at =
+      Number.isNaN(seconds) && /[a-z]/i.test(raw) ? Date.parse(raw) : NaN;
     if (Number.isFinite(at) && at > nowMs)
-      return Math.max(COOLDOWN_MIN_MS, at - nowMs);
+      return Math.min(COOLDOWN_MAX_MS, Math.max(COOLDOWN_MIN_MS, at - nowMs));
   }
   return COOLDOWN_MS;
 }
@@ -51,77 +55,123 @@ export function gnssRetryCooldownMs(raw, nowMs) {
 export function gnssIntegrityProxy({
   fetchImpl = (...args) => globalThis.fetch(...args),
   now = () => Date.now(),
+  monotonicNow = () => performance.now(),
+  warn = (...args) => console.warn(...args),
 } = {}) {
   const cache = new Map();
   const inFlight = new Map();
   const allow = makeRateLimiter({ windowMs: 60_000, max: 30, globalMax: 600 });
   let cooldownUntil = 0;
+  let cooldownStatus = 429;
 
   async function load({ lat, lon }) {
-    if (now() < cooldownUntil)
-      throw Object.assign(new Error('cooling_down'), { status: 429 });
+    if (monotonicNow() < cooldownUntil)
+      throw Object.assign(new Error('cooling_down'), {
+        status: cooldownStatus,
+      });
     const signal = AbortSignal.timeout(TIMEOUT_MS);
-    const response = await fetchImpl(
-      `https://api.adsb.lol/v2/lat/${lat}/lon/${lon}/dist/${RADIUS_NM}`,
-      {
-        signal,
-        redirect: 'error',
-        headers: {
-          Accept: 'application/json',
-          'User-Agent': 'gods-eye-view-gnss-integrity/1.0',
+    try {
+      const response = await fetchImpl(
+        `https://api.adsb.lol/v2/lat/${lat}/lon/${lon}/dist/${RADIUS_NM}`,
+        {
+          signal,
+          redirect: 'error',
+          headers: {
+            Accept: 'application/json',
+            'User-Agent': 'gods-eye-view-gnss-integrity/1.0',
+          },
         },
-      },
-    );
-    if (!response.ok) {
-      await response.body?.cancel();
-      if (response.status === 429) {
-        const at = now();
-        cooldownUntil = Math.max(
-          cooldownUntil,
-          at + gnssRetryCooldownMs(response.headers.get('retry-after'), at),
-        );
-        throw Object.assign(new Error('upstream_rate_limited'), {
-          status: 429,
-        });
+      );
+      if (!response.ok) {
+        await response.body?.cancel();
+        if (response.status === 429) {
+          const at = monotonicNow();
+          const raw = response.headers.get('retry-after');
+          const delay = gnssRetryCooldownMs(raw, now());
+          if (delay === COOLDOWN_MAX_MS)
+            warn('[gnss-integrity] upstream cooldown capped at one hour');
+          cooldownStatus = 429;
+          cooldownUntil = Math.max(cooldownUntil, at + delay);
+          throw Object.assign(new Error('upstream_rate_limited'), {
+            status: 429,
+          });
+        }
+        throw new Error('upstream_unavailable');
       }
-      throw new Error('upstream_unavailable');
+      const payload = await readResponseJsonCapped(
+        response,
+        MAX_RESPONSE_BYTES,
+        signal,
+      );
+      const rows = normalizeGnssAircraft(payload);
+      if (!rows) throw new Error('invalid_snapshot');
+      const sourceNow = payload.now;
+      if (!Number.isFinite(sourceNow) || sourceNow <= 0)
+        throw new Error('undated_snapshot');
+      const fetchedAt = Math.min(
+        now(),
+        sourceNow > 10_000_000_000 ? sourceNow : sourceNow * 1000,
+      );
+      if (now() - fetchedAt > GNSS_WINDOW_MS)
+        throw new Error('expired_snapshot');
+      return {
+        fetchedAt,
+        anchor: { lat, lon },
+        radiusNm: RADIUS_NM,
+        // `degraded` on each row is this classifier's verdict, not gpsjam's.
+        classifier: GNSS_CLASSIFIER.id,
+        rows,
+      };
+    } catch (error) {
+      if (error.status !== 429) {
+        const until = monotonicNow() + FAILURE_COOLDOWN_MS;
+        if (until > cooldownUntil) {
+          cooldownUntil = until;
+          cooldownStatus = 502;
+        }
+      }
+      throw error;
     }
-    const payload = await readResponseJsonCapped(
-      response,
-      MAX_RESPONSE_BYTES,
-      signal,
-    );
-    const rows = normalizeGnssAircraft(payload);
-    if (!rows) throw new Error('invalid_snapshot');
-    return {
-      fetchedAt: now(),
-      anchor: { lat, lon },
-      radiusNm: RADIUS_NM,
-      // `degraded` on each row is this classifier's verdict, not gpsjam's.
-      classifier: GNSS_CLASSIFIER.id,
-      rows,
-    };
   }
 
-  async function acquire(anchor) {
+  function age(entry) {
+    if (!entry) return Infinity;
+    const elapsed = monotonicNow() - entry.savedAt;
+    // A backwards injected clock cannot rejuvenate a snapshot.
+    return elapsed < 0 ? Infinity : entry.ageAtReceipt + elapsed;
+  }
+
+  async function acquire(anchor, peer) {
     const key = `${anchor.lat},${anchor.lon}`;
     const previous = cache.get(key);
-    if (previous && now() - previous.fetchedAt < CACHE_MS)
-      return { value: previous, stale: false };
+    if (age(previous) < CACHE_MS)
+      return { value: previous.value, ageMs: age(previous), stale: false };
     try {
+      if (!inFlight.has(key) && inFlight.size >= MAX_IN_FLIGHT)
+        throw Object.assign(new Error('busy'), { status: 429, local: true });
       const { promise } = coalesceProxyRequest(inFlight, key, async () => {
+        if (monotonicNow() >= cooldownUntil && !allow(peer))
+          throw Object.assign(new Error('rate_limited'), {
+            status: 429,
+            local: true,
+          });
         const value = await load(anchor);
+        const entry = {
+          value,
+          savedAt: monotonicNow(),
+          ageAtReceipt: Math.max(0, now() - value.fetchedAt),
+        };
         cache.delete(key);
-        cache.set(key, value);
+        cache.set(key, entry);
         while (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
-        return value;
+        return entry;
       });
-      return { value: await promise, stale: false };
+      const entry = await promise;
+      const ageMs = age(entry);
+      return { value: entry.value, ageMs, stale: ageMs >= CACHE_MS };
     } catch (error) {
-      // A stale answer keeps its original fetchedAt so the layer can age it;
-      // past the layer's window it is no evidence at all, so it is not served.
-      if (previous && now() - previous.fetchedAt <= GNSS_WINDOW_MS)
-        return { value: previous, stale: true };
+      if (age(previous) <= GNSS_WINDOW_MS)
+        return { value: previous.value, ageMs: age(previous), stale: true };
       throw error;
     }
   }
@@ -133,7 +183,9 @@ export function gnssIntegrityProxy({
         'Content-Type': 'application/json',
         'Cache-Control': 'no-store',
         ...(status === 405 ? { Allow: 'GET' } : {}),
-        ...(status === 429 ? { 'Retry-After': String(retryAfterS) } : {}),
+        ...([429, 502].includes(status)
+          ? { 'Retry-After': String(retryAfterS) }
+          : {}),
         ...(stale ? { 'X-Data-Stale': 'true' } : {}),
       });
       res.end(JSON.stringify(value));
@@ -144,28 +196,33 @@ export function gnssIntegrityProxy({
       return json(404, { error: 'unknown_route' });
     const anchor = gnssIntegrityAnchor(req.url);
     if (!anchor) return json(400, { error: 'invalid_anchor' });
-    if (!allow(clientKey(req))) return json(429, { error: 'rate_limited' });
     try {
-      const { value, stale } = await acquire(anchor);
+      const { value, stale, ageMs } = await acquire(anchor, clientKey(req));
       // ageMs is measured on this server's clock, so the browser can date
       // the rows without comparing its clock to ours.
-      const ageMs = Math.max(0, now() - value.fetchedAt);
       json(200, { ...value, ageMs, ...(stale ? { stale: true } : {}) }, stale);
     } catch (error) {
       if (error.status === 429) {
         // Tell the browser how long the shared upstream cooldown has left.
         const retryAfterS = Math.max(
           1,
-          Math.ceil((cooldownUntil - now()) / 1000),
+          error.local ? 60 : Math.ceil((cooldownUntil - monotonicNow()) / 1000),
         );
         return json(
           429,
-          { error: 'gnss_integrity_rate_limited' },
+          {
+            error: error.local ? error.message : 'gnss_integrity_rate_limited',
+          },
           false,
           retryAfterS,
         );
       }
-      json(502, { error: 'gnss_integrity_unavailable' });
+      json(
+        502,
+        { error: 'gnss_integrity_unavailable' },
+        false,
+        Math.max(1, Math.ceil((cooldownUntil - monotonicNow()) / 1000)),
+      );
     }
   }
 

server/providers/openai/toolDescriptions.js

@@ -179,7 +179,7 @@ export const ACTION_DESCRIPTIONS = {
   },
   get_current_view_state: {
     description:
-      'Read the current camera, style, Context, Cockpit, HUD, detection, map stack, post-processing, scene-playback, tracked-entity, and layer state before choosing another action.',
+      'Read the current camera, style, Context, Cockpit, HUD, detection, map stack, post-processing, scene-playback, tracked-entity, and layer state before choosing another action. Tracked aircraft emergency status is a crowd-sourced transponder broadcast, not a confirmed incident: quote emergencyBroadcast and never infer a hijack or an incident ending from a code change.',
     $position: 1,
   },
   set_hud: {
@@ -543,7 +543,7 @@ export const ACTION_DESCRIPTIONS = {
   },
   analyst_query: {
     description:
-      'Counts, lists, superlatives and attribute filters over records loaded by ENABLED layers — "how many flights over Texas", "biggest fire near LA", "ships headed to Oakland", "next rocket launch". A requested list or ranking requires this tool even after set_context_mode returned a Contacts count; that count alone has no requested items. complete:false means the count is a floor ("at least") and rankings cover the records examined; partial names unanswered layers. Items carry lat/lon for a follow-up fly_to_location. ok:false codes: LAYER_OFF (offer to enable), NOT_READY (loading), FOLLOW_UP_MISMATCH (ask again without followUp), UNKNOWN_FIELD/UNKNOWN_SCOPE/BAD_VALUE (retry with the allowed values). Aircraft emergency fields describe broadcasts, not confirmed incidents: narrate emergencyBroadcast with emergencySource. lastContactAtMs is retained general aircraft-message contact and never a status-specific receipt timestamp.',
+      'Counts, lists, superlatives and attribute filters over records loaded by ENABLED layers — "how many flights over Texas", "biggest fire near LA", "ships headed to Oakland", "next rocket launch". A requested list or ranking requires this tool even after set_context_mode returned a Contacts count; that count alone has no requested items. complete:false means the count is a floor ("at least") and rankings cover the records examined; partial names unanswered layers. Items carry lat/lon for a follow-up fly_to_location. ok:false codes: LAYER_OFF (offer to enable), NOT_READY (loading), FOLLOW_UP_MISMATCH (ask again without followUp), UNKNOWN_FIELD/UNKNOWN_SCOPE/BAD_VALUE (retry with the allowed values). Aircraft emergency fields describe broadcasts, not confirmed incidents: narrate emergencyBroadcast with emergencySource. emergencyKind values are general, unlawful, nordo, downed, minfuel and lifeguard; GEV treats the last two as priorities (emergency:false). lastContactAtMs says when the transponder was last heard, not when the status arrived.',
     $position: 1,
     parameters: {
       properties: {