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

> Discover how the Node.js runtime environment powers God's Eye View. Learn its role in running Vite, secure proxy middleware, and managing environment variables for development and builds.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: internals
- Published: 2026-09-06

---

**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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json) to ensure compatibility with modern ES modules and native APIs:

```json
"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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/vite.config.js) executes:

```js
// 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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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:

```js
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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:

```js
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:

```js
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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/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.