How the OpenSky Credit Governor Manages API Rate Limits and Caching in the Dev Proxy

The OpenSky credit governor in the Gods Eye View development proxy prevents API quota exhaustion through OAuth token reuse, adaptive TTL caching based on remaining quota, and cooldown periods that gracefully serve stale data when rate limits are hit.

The Gods Eye View repository (bilawalsidhu/gods-eye-view) implements a sophisticated credit governor within its Vite development server to protect OpenSky API credentials during local development. Located in vite.config.js, this middleware layer intelligently balances real-time flight data freshness against strict rate limiting constraints through token management and quota-aware caching strategies.

OAuth Token Management and Reuse

The proxy authenticates to OpenSky using client-credentials OAuth flow and implements aggressive token reuse to minimize authentication requests.

A single OAuth token is cached until expiry (approximately 30 minutes) and reused across all requests. The implementation stores the token acquisition promise in _openskyTokenPromise, ensuring that concurrent requests wait for the same fetch operation rather than issuing duplicate token requests simultaneously. This pattern prevents thundering-herd problems during proxy startup or cache invalidation events.

The token refresh logic checks if the current time is at least one minute before expiry before attempting renewal. According to the source in vite.config.js lines 1422‑1484, the proxy obtains credentials defined in src/keySetupCore.mjs (with id: 'opensky') and manages warning resets around lines 1454‑1497.

Adaptive Cache TTL Based on API Quota

Rather than using static cache durations, the governor implements adaptive TTL that responds to the OpenSky API's remaining quota headers.

When the proxy receives a response from OpenSky, it extracts the remaining header value indicating available API calls. The function openskyAdaptiveTtlMs calculates a dynamic time-to-live value stored in _openskyTtlMs (see lines 3249‑3250). When the quota is high, the cache lifetime extends to conserve credits; when the quota dwindles, the TTL shortens to provide fresher data while still protecting the remaining allowance.

This quota-aware approach ensures the proxy maximizes cache efficiency during periods of abundant credits while minimizing staleness when approaching rate limits.

Rate Limit Cooldown and 429 Handling

When the upstream OpenSky API returns a 429 Too Many Requests status, the proxy enters a protective cooldown state rather than continuing to hammer the exhausted endpoint.

The implementation sets _openskyCooldownUntil to a future timestamp based on the configurable cooldownMs period. During this cooldown window, the proxy serves cached data even if the entry is technically stale, attaching a retry-after hint to the response metadata. This logic appears around lines 3025‑3065, with the cooldown timestamp update at line 3163.

The middleware first checks if the current time is before _openskyCooldownUntil or if a fresh cache entry exists (now - _openskyCacheTime < _openskyTtlMs) at lines 3029‑3058. If either condition is true, it returns the cached body immediately without contacting the upstream API.

Cache Storage and Metadata Structure

The governor maintains a comprehensive cache state to support intelligent fallback decisions. The proxy stores:

• _openskyCacheBody: The last successful response payload
• _openskyCacheStatus: HTTP status code of cached response
• _openskyCacheTime: Timestamp when the entry was stored
• _openskyCacheSourceEpochMs: Source epoch for data validity
• _openskyCacheMeta: Metadata object describing the cache entry context

The metadata object records which mode was requested by the client, which mode was actually used to serve the request, and descriptive fallback reasons such as "stale", "cooldown", or "regional fallback". This diagnostic information helps developers understand why they are receiving cached versus live data during development.

Fallback Mechanisms for Graceful Degradation

When upstream OpenSky requests fail and no cache exists, the proxy implements a secondary fallback to ADS-B Lol (serveAdsbLolPointFallback). This degradation path ensures continuous flight data availability even during complete OpenSky outages or credential failures.

If a cached body exists when the upstream call fails, the proxy serves the stale data while marking the response with appropriate metadata indicating the fallback reason. This approach preserves the local development experience while clearly signaling data freshness issues. The fallback handling logic is visible around lines 3065‑3085.

Inspecting Governor Diagnostics

You can inspect the credit governor's decision-making through the response metadata:

fetch('/api/opensky')
  .then(r => r.json())
  .then(({ meta, ...payload }) => {
    console.log('Cache TTL used:', meta.ttlMs);
    console.log('Cooldown active?', meta.retryAfterSeconds > 0);
    console.log('Why this response?', meta.reason);
    // payload holds the actual flight state data
  });

Forcing Token Refresh

While the proxy automatically manages token lifecycle, you can manually clear the cached token for debugging purposes:

fetch('/api/opensky/clear-token', { method: 'POST' });

Summary

• Token Efficiency: The _openskyTokenPromise pattern prevents concurrent OAuth requests by sharing a single authentication promise across parallel connections.
• Quota Awareness: The openskyAdaptiveTtlMs function adjusts cache lifetimes dynamically based on the OpenSky API's remaining quota header.
• 429 Resilience: When rate limits trigger a 429 response, _openskyCooldownUntil blocks upstream requests for a configurable period, serving cached data with retry-after metadata.
• Diagnostic Transparency: The _openskyCacheMeta object exposes the governor's decision logic, indicating whether responses are fresh, stale, or fallback data.
• Graceful Degradation: Failed upstream requests trigger serveAdsbLolPointFallback when no cache exists, or return stale cached data with explanatory metadata.

Frequently Asked Questions

How does the proxy prevent duplicate OAuth token requests?

The proxy stores the token acquisition promise in _openskyTokenPromise (lines 1422‑1484). When multiple requests arrive simultaneously before the initial token fetch completes, they all await the same shared promise rather than initiating separate authentication calls. This pattern ensures only one token request reaches OpenSky regardless of concurrent demand.

What happens when the OpenSky API returns a 429 status code?

The proxy enters a cooldown period tracked by _openskyCooldownUntil (lines 3025‑3065). During this window, the middleware skips upstream requests and serves cached responses—even stale ones—while attaching retry-after hints in the metadata. The cooldown timestamp is updated at line 3163 to prevent immediate retry attempts.

How does the adaptive TTL calculation work?

The openskyAdaptiveTtlMs function calculates cache duration based on the remaining quota value in OpenSky's response headers (lines 3249‑3250). When the remaining quota is high, the cache TTL extends to maximize efficiency; as the quota depletes, the TTL shortens to balance freshness with rate limit protection. The calculated value is stored in _openskyTtlMs and applied to subsequent requests.

Can I force a cache refresh during development?

While the governor automatically manages cache invalidation based on adaptive TTL and cooldown states, you can manually clear the OAuth token cache by posting to /api/opensky/clear-token. This forces new token acquisition on the next request but does not clear flight data caches. For complete refresh, you would need to restart the Vite dev server or wait for the adaptive TTL to expire naturally.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}