How the Node.js Runtime Environment Powers God's Eye View

God's Eye View uses Node.js to run the Vite development server, execute secure proxy middleware for external APIs, and manage environment variables during both development and build processes.

God's Eye View is a browser-based visualization application that relies heavily on the Node.js runtime environment during development, build, and server-side operations. While the final application runs in the browser, the development workflow and data fetching architecture depend on Node.js to serve the SPA, proxy external requests, and manage sensitive credentials securely.

Node.js Engine Requirements and Version Constraints

The repository enforces strict Node version requirements in package.json to ensure compatibility with modern ES modules and native APIs:

"engines": {
  "node": ">=24.14.0 <25 || >=26 <27"
}

These specific version ranges are required because the codebase depends on modern ES-module features such as import.meta.env and native Node APIs that are only stable in these releases. Running the application outside these ranges will cause module resolution errors or missing API exceptions during the Vite initialization phase.

Environment Variable Management and Snapshotting

The Node.js runtime handles sensitive configuration through a three-stage environment pipeline that prevents credential leakage during runtime updates.

Loading via Pinokio Scripts

The scripts/pinokio-environment.mjs module reads .env files and populates process.env before Vite evaluates its configuration. This ensures that all environment variables are available when vite.config.js executes:

// scripts/pinokio-start.mjs (excerpt)
const envPath = resolve(process.cwd(), '.env');
if (fs.existsSync(envPath)) {
  const raw = readFileSync(envPath, 'utf8');
  raw.split('\n').forEach(line => {
    const [k, v] = line.split('=');
    if (k) process.env[k.trim()] = v?.trim();
  });
}
process.env.GEV_LAUNCHER = 'pinokio-start';

Environment Snapshotting

Inside vite.config.js, the runtime captures a snapshot of all known environment keys at module load time using a constant like PROVIDER_ENV_AT_BOOT. This mechanism prevents the key-setup UI from mistakenly marking internal Node.js keys as external when users update credentials on-the-fly later in the application lifecycle.

Opt-In Rate Limiting

The runtime creates per-minute rate limiters based on environment variables such as GEV_RATELIMIT_OPENAI_PER_MIN. When the variable is unset or zero, the limiter becomes a no-op, preserving original behavior:

function makeOptInRateLimiter(envValue) {
  const max = Number(envValue);
  if (!Number.isFinite(max) || max <= 0) return null; // unlimited
  return makeRateLimiter({ windowMs: 60_000, max, globalMax: max * 20 });
}

Vite Configuration and Proxy Architecture

The vite.config.js file serves as the heart of the Node.js runtime, importing native modules (fs, os, crypto, dns/promises) to handle file reading, UUID generation, cache key hashing, and DNS resolution. This configuration sets up dedicated proxy middleware for each external service (OpenSky, Overpass, Radio Browser) that runs in-process with the Vite dev server.

Adaptive Caching Implementation

The proxy layer implements intelligent caching based on downstream API limits. For example, the OpenSky proxy adjusts TTL dynamically:

function openskyAdaptiveTtlMs(remaining) {
  if (!Number.isFinite(remaining)) return OPENSKY_CACHE_MS;
  if (remaining > 2400) return OPENSKY_CACHE_MS;      // full freshness
  if (remaining > 1200) return 30_000;                // 30 s
  if (remaining > 400)  return 90_000;                // 90 s
  return 300_000;                                    // 5 min
}

Request Validation and Safety

Each middleware enforces hard caps on request and response sizes through constants like OVERPASS_MAX_BODY_BYTES and OVERPASS_MAX_RESPONSE_BYTES. The proxies also sanitize request bodies (e.g., sanitizeOverpassBody) and emit 429 responses when opt-in rate limiters block calls, preventing runaway memory usage and hostile payloads.

Security and Isolation Mechanisms

The Node.js runtime implements several security layers to safely proxy external data without exposing the client to direct API access.

DNS Pinning for Anti-Rebinding

Proxy modules resolve target hostnames using dns.promises.lookup and force HTTP requests to use the resolved IP address via the lookup option in https.request. This DNS-pinning technique mitigates DNS-rebinding attacks by ensuring requests cannot be redirected to malicious internal addresses after initial resolution:

function fetchPinnedRadioResponse(url, options, addresses) {
  const address = addresses[0];
  return new Promise((resolve, reject) => {
    const request = https.request(url, {
      method: 'GET',
      headers: options.headers,
      signal: options.signal,
      lookup(_hostname, lookupOptions, callback) {
        if (lookupOptions?.all) callback(null, addresses);
        else callback(null, address.address, address.family);
      },
    }, response => { /* … */ });
    // ...
  });
}

CORS and Authentication Injection

The Vite dev server adds CORS headers to responses and injects OAuth tokens (such as OpenSky credentials) only when the environment provides them through the secure variable pipeline established at startup.

Startup Flow and Process Architecture

The Node.js runtime follows a specific boot sequence that separates environment preparation from server execution:

1. Pinokio Initialization – scripts/pinokio-start.mjs loads dotenv values, sets the GEV_LAUNCHER identifier, and spawns the Vite dev server.
2. Vite Boot – The vite command reads vite.config.js, registers all proxy middlewares, and begins listening on http://localhost:5173.
3. Client Connection – The browser loads the SPA from src/main.js, which then communicates with the Node-hosted proxies for live data feeds from OpenSky, Overpass, and Radio Browser.

This architecture means the same Node process serves the static assets and handles data-fetching duties, creating a unified development environment where browser code never directly contacts third-party APIs.

Summary

• God's Eye View requires Node.js versions 24.14.0+ or 26.x to support modern ES modules and native APIs used in vite.config.js.
• Environment variables are snapshotted at boot time in the Node runtime to prevent credential leakage during UI-based configuration updates.
• Proxy middleware runs in-process with the Vite dev server, handling external API requests for OpenSky, Overpass, and Radio Browser while the browser client remains isolated.
• Security measures include DNS pinning, request/response byte caps, and opt-in rate limiting to prevent abuse and attacks.
• Pinokio scripts (pinokio-start.mjs and pinokio-environment.mjs) manage the development lifecycle by loading configuration and spawning the Vite server with the correct environment context.

Frequently Asked Questions

What version of Node.js is required to run God's Eye View?

God's Eye View requires Node.js version 24.14.0 or higher (but below 25) or version 26 or higher (but below 27). These constraints are defined in package.json to ensure compatibility with the ES module features and native APIs (like import.meta.env) used throughout the Vite configuration and Pinokio scripts.

How does God's Eye View handle sensitive API keys in development?

API keys are loaded from .env files by scripts/pinokio-environment.mjs into process.env before the Vite server starts. The runtime captures a snapshot of these variables at module load time in vite.config.js, ensuring that subsequent changes to the Node environment during the key-setup UI workflow do not expose internal system variables or corrupt the credential store.

Why does the application use Node.js proxies instead of calling APIs directly from the browser?

The Node.js runtime in vite.config.js implements security controls that browsers cannot enforce, including DNS pinning to prevent rebinding attacks, hard byte limits on request/response sizes to prevent memory exhaustion, and rate limiting. These proxies also handle authentication token injection and CORS headers, keeping the browser client sandboxed from direct external API access.

What is the purpose of the Pinokio scripts in the runtime?

The Pinokio scripts (pinokio-start.mjs and pinokio-environment.mjs) serve as the entry point for the Node.js runtime during development. They initialize the environment by loading configuration files, set launcher metadata flags (like GEV_LAUNCHER), and spawn the Vite dev server with the correct working directory and environment context, effectively bridging the gap between the host system and the Vite build tooling.

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