From bb09bcfae736b5e5315a1157e88b8a444cfe5ac3 Mon Sep 17 00:00:00 2001
From: jing <jing@JING5.local>
Date: Mon, 13 Jul 2026 23:51:57 +1000
Subject: [PATCH] =?UTF-8?q?harden=20ADSBx=20quota=20guard:=205-min=20?=
 =?UTF-8?q?=E2=86=92=2010-min=20single-flight=20cache?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The $10 ADSBx BASIC tier has NO hard limit and bills $0.0015/request over
10k/month, so the cache TTL must guarantee we stay under. Widened the cache
window 5→10 min: since proxy_cache_lock coalesces all requests into ONE upstream
call per window, this caps upstream at ~144 calls/day (~4.4k/month, <half the
10k cap) regardless of visitors or poll rate. Prod nginx also got
proxy_cache_lock_timeout/age for a hard single-flight guarantee even under a slow
upstream. Dev serve.py ADSBX_CACHE_SEC 300→600 to match. Frontend poll stays
5 min for display freshness (cheap cache hits; the server cache governs quota).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 js/config.js | 11 +++++++----
 serve.py     |  7 ++++---
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/js/config.js b/js/config.js
index 2904679..5121bbf 100644
--- a/js/config.js
+++ b/js/config.js
@@ -89,12 +89,15 @@ export const CONFIG = {
   },
 
   // Military aircraft — ADS-B Exchange /v2/mil/ (REAL unfiltered military, the
-  // OSINT prize OpenSky hides). Paid RapidAPI feed; the same-origin proxy injects
-  // the key server-side AND 5-min-caches it, so poll cadence == cache TTL keeps
-  // the ~10k/month quota safe (~8.6k/month worst case).
+  // OSINT prize OpenSky hides). Paid RapidAPI feed with OVERAGE billing over
+  // 10k/month (no hard block), so the same-origin proxy injects the key
+  // server-side AND single-flight-caches /v2/mil/ for 10 min: the *cache TTL*
+  // (not this poll) governs the upstream quota → max ~144 calls/day (~4.4k/mo,
+  // <half the cap). The browser polls faster only for display freshness (cheap
+  // cache hits).
   adsbx: {
     proxyMil: 'proxy/adsbx-mil', // RELATIVE — works at "/" and "/godsigh/"
-    pollMs: 300_000,             // 5 min
+    pollMs: 300_000,             // 5 min display refresh (server 10-min cache is the quota guard)
   },
 
   // Optional live AIS. Leave blank to use the demo fleet only (roadmap feature).
diff --git a/serve.py b/serve.py
index 943db3b..bc241c8 100644
--- a/serve.py
+++ b/serve.py
@@ -53,10 +53,11 @@ HISTORY_TOLERANCE_SEC = 600
 
 # ---- ADS-B Exchange military feed (paid RapidAPI, ~10k req/month) ------------
 # proxy/adsbx-mil injects the RapidAPI key server-side (never in the browser) and
-# HARD-caches the /v2/mil/ response for 5 min — the quota guard: even with many
-# open tabs, at most ~288 upstream calls/day (~8.6k/month) are spent.
+# HARD-caches the /v2/mil/ response — the quota guard. The $10 BASIC tier bills
+# $0.0015/request OVER 10k/month with NO hard block, so the cache TTL must keep
+# us safely under: 10 min → at most ~144 calls/day (~4.4k/month, <half the cap).
 ADSBX_CREDS = Path(__file__).resolve().parent / "adsbxcredentials.json"
-ADSBX_CACHE_SEC = 300
+ADSBX_CACHE_SEC = 600
 _adsbx_cache = {"body": None, "ts": 0.0}