chore(1.4.1): ops polish — health version, cache stampede protection, input length guards, doc updates

[Copilot]

Applies the remaining 1.4.1 ops-polish changes across server.js, openapi.yaml, tests, and docs.

server.js

• APP_VERSION — destructured from package.json; used in User-Agent (Zscaler-Datacenter-Lookup/1.4.1) and health response
• Top-level constants — MAX_TRACE_IPS = 50 and MAX_PARAM_LENGTH = 256 promoted out of inline usage
• Cache stampede protection — fetchZscalerData now uses a pendingFetches: Map<string, Promise> to coalesce concurrent requests for the same un-cached cloud into a single in-flight fetch:

  if (pendingFetches.has(cloud)) return pendingFetches.get(cloud);
  const fetchPromise = (async () => { /* fetch → cache → finally delete */ })();
  pendingFetches.set(cloud, fetchPromise);
  return fetchPromise;

• Input length guards — GET /api/lookup returns 400 when cloud, ip, or sourceIp exceeds 256 chars; POST /api/trace adds the same check for cloud
• /api/health — includes version: APP_VERSION in response

openapi.yaml

• info.version → 1.4.1
• /api/health schema includes version string property

Tests

• Health test asserts res.body.version === require('../../package.json').version
• New test: GET /api/lookup with a 257-char ip returns 400 with "Parameter too long"

Docs

• CHANGELOG.md — [1.4.1] section added
• TODO.md — marks done: cache stampede, length guards, MAX_TRACE_IPS, author field, .nvmrc, health version, CONTRIBUTING tree
• CONTRIBUTING.md — utils/distance.js added to project tree
• .env.example — ALLOWED_ORIGINS documented

Original prompt

Branch chore/1.4.1-ops-polish already has package.json bumped to 1.4.1 (author set, engines >=20) and .nvmrc added.

Apply the remaining 1.4.1 ops polish changes exactly:

1) server.js

A. After const { calculateDistance } = require('./utils/distance'); add:

const { version: APP_VERSION } = require('./package.json');

B. After const CACHE_DURATION = process.env.CACHE_DURATION || 3600000; // 1 hour default add:

const MAX_TRACE_IPS = 50;
const MAX_PARAM_LENGTH = 256; // max length for cloud / single IP query params

C. Replace the dataCache + fetchZscalerData block with promise-coalescing version:

• Keep const dataCache = new Map();
• Add const pendingFetches = new Map();
• In fetchZscalerData: if valid cache return it; if pendingFetches.has(cloud) return that promise; otherwise create async IIFE that fetches CENR, sets cache, on error serves stale cache if present, and in finally deletes pendingFetches entry; set pendingFetches before returning the promise
• User-Agent must be `Zscaler-Datacenter-Lookup/${APP_VERSION}`

D. In GET /api/lookup after the typeof string guard, add length check:

  if (cloud.length > MAX_PARAM_LENGTH || ip.length > MAX_PARAM_LENGTH ||
      (sourceIp && sourceIp.length > MAX_PARAM_LENGTH)) {
    return res.status(400).json({
      success: false,
      error: `Parameter too long (max ${MAX_PARAM_LENGTH} characters)`
    });
  }

E. In POST /api/trace: remove the local const MAX_TRACE_IPS = 50; (use top-level). Before empty-ips check, add cloud length guard using MAX_PARAM_LENGTH.

F. In GET /api/health include version: APP_VERSION in the JSON response.

2) openapi.yaml

• info.version: 1.4.1
• /api/health response: add version string property example 1.4.1

3) tests/integration/api.test.js

• Health test: expect typeof res.body.version === 'string' and equals require('../../package.json').version
• Add test: returns 400 when parameter exceeds max length (long ip string)

4) CHANGELOG.md - add [1.4.1] - 2026-08-01 section covering health version, cache stampede, input length guards, .nvmrc, User-Agent version, author/engines, MAX_TRACE_IPS constant, CONTRIBUTING/.env.example

5) TODO.md mark done: cache stampede, input length guards, MAX_TRACE_IPS, author field, .nvmrc, health version, CONTRIBUTING distance.js

6) CONTRIBUTING.md - add utils/distance.js to project tree

7) .env.example - document ALLOWED_ORIGINS

Do not change unrelated files. Match existing code style.