Files
OmniRoute/scripts/build/runtime-env.mjs
Diego Rodrigues de Sa e Souza 191dce8d53 Release v3.8.53
Release v3.8.53 — 1,189 documented changes from 1,162 cycle commits and 208 contributor rows; full changelog in CHANGELOG.md → [3.8.53].

Merged by explicit owner decision at STOP #1 on head 6cc69650, without --admin (main has no required checks). Gate / CI passed on this head: 8 unit shards, Coverage and Quality Ratchet. Security: 0 npm, 0 CodeQL high, 0 Dependabot high.

Red at merge, accepted by the owner:
- Gate / Quality and Fast Quality Gates: complexity-ratchets and dead-code compare the whole cycle against main (11 dead exports; total complexity fell from 1,921 to 1,873). Cleanup follows in v3.8.54.
- dast-smoke: advisory.
- Release-Green: FAIL on `unit-6 no result` (cancelled at the 30-minute limit, cause not identified). Pack, boot and the other 64 commands passed on 7e640dee; there is no complete run on this head.

SonarQube is off (SONARQUBE_ENABLED=false). ⚠️ base-red inherited: #18791, #17267.
2026-11-06 04:21:00 -03:00

298 lines
12 KiB
JavaScript

import { spawn } from "node:child_process";
export function parsePort(value, fallback) {
const parsed = Number.parseInt(String(value), 10);
return Number.isFinite(parsed) && parsed > 0 && parsed <= 65535 ? parsed : fallback;
}
/**
* Resolve the V8 heap ceiling (MB) for the server process from
* `OMNIROUTE_MEMORY_MB`, mirroring `omniroute serve`. Clamped to [64, 16384];
* invalid/unset → fallback (512). The standalone launcher uses this so
* OMNIROUTE_MEMORY_MB can override the Docker image's NODE_OPTIONS fallback
* without clobbering any other runtime flags (#2939).
* @param {string | number | undefined | null} value
* @param {number} [fallback]
*/
export function resolveMaxOldSpaceMb(value, fallback = 512) {
const parsed = Number.parseInt(String(value), 10);
return Number.isFinite(parsed) && parsed >= 64 && parsed <= 16384 ? parsed : fallback;
}
/**
* Derive a sane DEFAULT V8 heap ceiling (MB) from the host's physical RAM, used
* when `OMNIROUTE_MEMORY_MB` is unset. A fixed 512MB default crashed boxes with
* plenty of RAM under load (65 providers / 2600 models → "Ineffective
* mark-compacts near heap limit ~500MB"); see #5172 / #5160 / #5152. Targets
* ~35% of total RAM, clamped to [512, 4096]. Invalid/zero totalmem → 512.
* Pass the result as the `fallback` of {@link resolveMaxOldSpaceMb} so an
* explicit OMNIROUTE_MEMORY_MB override always wins.
* @param {number | undefined | null} totalmemBytes — typically `os.totalmem()`
*/
export function calibrateHeapFallbackMb(totalmemBytes) {
const totalMb = Number(totalmemBytes) / (1024 * 1024);
if (!Number.isFinite(totalMb) || totalMb <= 0) return 512;
const target = Math.floor(totalMb * 0.35);
return Math.min(4096, Math.max(512, target));
}
const MAX_OLD_SPACE_FLAG = "--max-old-space-size";
/**
* True when the caller already pinned the V8 heap via NODE_OPTIONS
* (`--max-old-space-size=…`). Used to decide whether `omniroute serve` may
* append/inject the calibrated default — a user-set value must always win.
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
*/
export function envHasExplicitHeapFlag(env) {
const sourceEnv = arguments.length === 0 ? process.env : env;
return String(sourceEnv?.NODE_OPTIONS || "").includes(MAX_OLD_SPACE_FLAG);
}
/** Last `--max-old-space-size=` value in NODE_OPTIONS, or null if absent. */
export function parseNodeOptionsHeapMb(nodeOptions) {
const matches = [...String(nodeOptions || "").matchAll(/--max-old-space-size=(\d+)/g)];
if (matches.length === 0) return null;
const parsed = Number.parseInt(matches[matches.length - 1][1], 10);
return Number.isFinite(parsed) ? parsed : null;
}
/**
* True when OMNIROUTE_MEMORY_MB is an explicit in-range integer (not the
* unset/invalid fallback). Docker images set this; Compose may also set
* NODE_OPTIONS — #10353 needs to know both knobs were intentionally present.
*/
export function envHasExplicitOmnirouteMemoryMb(env) {
const sourceEnv = arguments.length === 0 ? process.env : env;
const parsed = Number.parseInt(String(sourceEnv?.OMNIROUTE_MEMORY_MB ?? ""), 10);
return Number.isFinite(parsed) && parsed >= 64 && parsed <= 16384;
}
/**
* Docker `run-standalone.mjs` appends `--max-old-space-size` from
* OMNIROUTE_MEMORY_MB. V8 last-flag semantics mean that appended value wins
* over an earlier NODE_OPTIONS heap. Warn once when both are set and disagree
* so env dumps stop looking like NODE_OPTIONS is in effect (#10353).
*
* @returns {boolean} true when a warn was emitted
*/
export function warnConflictingHeapLimits(env, omnirouteMb, log = console.warn) {
const nodeMb = parseNodeOptionsHeapMb(env?.NODE_OPTIONS);
if (nodeMb == null || !envHasExplicitOmnirouteMemoryMb(env)) return false;
if (nodeMb === omnirouteMb) return false;
log(
`[omniroute] heap limit conflict: OMNIROUTE_MEMORY_MB=${omnirouteMb} disagrees with NODE_OPTIONS --max-old-space-size=${nodeMb}. ` +
`run-standalone.mjs / Docker appends OMNIROUTE_MEMORY_MB last, so the effective V8 heap is ${omnirouteMb} MB. ` +
`Set only OMNIROUTE_MEMORY_MB (recommended) or make both values match.`
);
return true;
}
/**
* NODE_OPTIONS string for Docker / run-standalone.mjs.
* Explicit OMNIROUTE_MEMORY_MB always appends (wins). Otherwise keep an
* existing NODE_OPTIONS heap flag (#5238). Otherwise append the fallback.
*/
export function buildStandaloneNodeOptions(env = process.env, omnirouteMb) {
const existing = String(env?.NODE_OPTIONS || "").trim();
if (envHasExplicitOmnirouteMemoryMb(env)) {
return `${existing} ${MAX_OLD_SPACE_FLAG}=${omnirouteMb}`.trim();
}
if (existing.includes(MAX_OLD_SPACE_FLAG)) return existing;
return `${existing} ${MAX_OLD_SPACE_FLAG}=${omnirouteMb}`.trim();
}
/**
* Assemble the NODE_OPTIONS string for the spawned server, preserving any flags
* the user already exported. #5238: `omniroute serve` used to UNCONDITIONALLY
* overwrite NODE_OPTIONS with the calibrated `--max-old-space-size`, silently
* discarding a user-set `NODE_OPTIONS=--max-old-space-size=8192` (reporter set
* 8192 and still OOM'd at ~505MB). Mirrors the Electron (electron/main.js) and
* standalone (scripts/dev/run-standalone.mjs) launchers:
* - if NODE_OPTIONS already contains `--max-old-space-size`, keep it as-is
* (the user's value wins);
* - otherwise append the calibrated `--max-old-space-size=<memoryLimit>` to
* the existing NODE_OPTIONS, preserving unrelated flags (e.g.
* `--enable-source-maps`).
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
* @param {number} memoryLimit — calibrated V8 heap ceiling (MB)
* @returns {string} the NODE_OPTIONS value to pass to the child process
*/
export function buildServerNodeOptions(env = process.env, memoryLimit) {
const existing = String(env?.NODE_OPTIONS || "").trim();
if (existing.includes(MAX_OLD_SPACE_FLAG)) return existing;
return `${existing} ${MAX_OLD_SPACE_FLAG}=${memoryLimit}`.trim();
}
/**
* Build the leading `node` CLI args that pin the V8 heap. When the user already
* pinned the heap via NODE_OPTIONS, return `[]` so we do NOT inject a
* conflicting/shadowing CLI `--max-old-space-size` (CLI args override
* NODE_OPTIONS, which would re-introduce #5238). Otherwise return the calibrated
* flag — NODE_OPTIONS already carries the same value, so this stays redundant
* (identical value), never conflicting.
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
* @param {number} memoryLimit — calibrated V8 heap ceiling (MB)
* @returns {string[]}
*/
export function buildNodeHeapArgs(env = process.env, memoryLimit) {
return envHasExplicitHeapFlag(env) ? [] : [`${MAX_OLD_SPACE_FLAG}=${memoryLimit}`];
}
/**
* Build the complete argument list for spawning the Node.js server runtime.
* Prefer IPv4 DNS results before starting the application so undici does not
* stall on hosts whose IPv6 route silently drops outbound connections.
*
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [env]
* @param {number} memoryLimit — calibrated V8 heap ceiling (MB)
* @param {string} serverPath — standalone server entrypoint
* @returns {string[]}
*/
export function buildNodeRuntimeArgs(env = process.env, memoryLimit, serverPath) {
return ["--dns-result-order=ipv4first", ...buildNodeHeapArgs(env, memoryLimit), serverPath];
}
/**
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} [fromEnv]
* Defaults to process.env. Pass bootstrap `merged` so project `.env` PORT applies before spawn.
*/
export function resolveRuntimePorts(fromEnv = process.env) {
const basePort = parsePort(fromEnv.PORT || "20128", 20128);
const apiPort = parsePort(fromEnv.API_PORT || String(basePort), basePort);
const dashboardPort = parsePort(fromEnv.DASHBOARD_PORT || String(basePort), basePort);
return { basePort, apiPort, dashboardPort };
}
export function withRuntimePortEnv(env, runtimePorts) {
const { basePort, apiPort, dashboardPort } = runtimePorts;
return {
...env,
OMNIROUTE_PORT: String(basePort),
PORT: String(dashboardPort),
DASHBOARD_PORT: String(dashboardPort),
API_PORT: String(apiPort),
HOSTNAME: env.OMNIROUTE_HOSTNAME || "0.0.0.0",
};
}
export function sanitizeColorEnv(env = {}) {
const sanitized = { ...env };
// Node warns when both FORCE_COLOR and NO_COLOR are set.
// Prefer NO_COLOR in test tooling to avoid noisy process warnings.
if (typeof sanitized.FORCE_COLOR !== "undefined" && typeof sanitized.NO_COLOR !== "undefined") {
delete sanitized.FORCE_COLOR;
}
return sanitized;
}
export function spawnWithForwardedSignals(command, args, options = {}) {
const child = spawn(command, args, options);
child.on("exit", (code, signal) => {
if (signal) {
process.kill(process.pid, signal);
return;
}
process.exit(code ?? 0);
});
process.on("SIGINT", () => child.kill("SIGINT"));
process.on("SIGTERM", () => child.kill("SIGTERM"));
return child;
}
const SELF_PING_DEFAULT_PATH = "/api/monitoring/health";
const SELF_PING_DEFAULT_INTERVAL_SECONDS = 180;
const SELF_PING_MIN_INTERVAL_SECONDS = 30;
const SELF_PING_FIRST_DELAY_MS = 60_000; // give the server time to boot
const SELF_PING_TIMEOUT_MS = 15_000;
/**
* Resolve the self-pinger config. Inert ("off") unless SELF_PING_URL or RENDER_EXTERNAL_URL is set,
* so local, docker-compose and npm installs are unchanged. SELF_PING_PATH must be a path on that
* URL: an absolute or protocol-relative value would otherwise replace the host.
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} env
* @returns {{ status: "off" } | { status: "invalid" } | { status: "on", target: URL, intervalSeconds: number }}
*/
export function resolveSelfPingConfig(env) {
const flag = String(env.SELF_PING_ENABLED ?? "")
.trim()
.toLowerCase();
if (["0", "false", "off", "no"].includes(flag)) return { status: "off" };
const baseUrl = String(env.SELF_PING_URL || env.RENDER_EXTERNAL_URL || "").trim();
if (!baseUrl) return { status: "off" };
const path = String(env.SELF_PING_PATH || SELF_PING_DEFAULT_PATH).trim();
if (!path.startsWith("/") || path.startsWith("//")) return { status: "invalid" };
let target;
try {
target = new URL(path, baseUrl);
} catch {
return { status: "invalid" };
}
if (target.protocol !== "https:" && target.protocol !== "http:") return { status: "invalid" };
const requested = Number.parseInt(String(env.SELF_PING_INTERVAL_SECONDS ?? ""), 10);
const intervalSeconds =
Number.isFinite(requested) && requested >= SELF_PING_MIN_INTERVAL_SECONDS
? requested
: SELF_PING_DEFAULT_INTERVAL_SECONDS;
return { status: "on", target, intervalSeconds };
}
/**
* Keep a Render free web service awake. Render spins these down after about 15 minutes without
* INBOUND traffic, and pinging localhost would not count, so this requests the service's own PUBLIC
* URL: the request travels through Render's edge and registers as real traffic. Runs in the
* launcher, never in the Next server. Logs only when the status changes, to stay out of the way.
* @param {NodeJS.ProcessEnv | Record<string, string | undefined>} env
* @param {typeof fetch} [fetchImpl]
*/
export function startSelfPinger(env, fetchImpl = fetch) {
const config = resolveSelfPingConfig(env);
if (config.status === "invalid") {
console.warn("[self-pinger] invalid SELF_PING_URL/RENDER_EXTERNAL_URL or path; disabled");
return;
}
if (config.status !== "on") return;
const { target, intervalSeconds } = config;
let lastOutcome = null;
const report = (outcome, log) => {
if (outcome !== lastOutcome) log(`[self-pinger] GET ${target.pathname} -> ${outcome}`);
lastOutcome = outcome;
};
const ping = async () => {
try {
const res = await fetchImpl(target, {
method: "GET",
headers: { "user-agent": "omniroute-self-pinger" },
signal: AbortSignal.timeout(SELF_PING_TIMEOUT_MS),
});
await res.body?.cancel();
// Any HTTP status means the request reached the service through Render's edge.
report(res.status, console.log);
} catch (err) {
report(err?.name === "TimeoutError" ? "timeout" : "failed", console.warn);
}
};
console.log(
`[self-pinger] enabled: ${target.origin}${target.pathname} every ${intervalSeconds}s`
);
// unref() so the timers never keep the launcher alive on their own; the spawned server child does
// that, and the launcher exits with it.
setTimeout(() => {
void ping();
setInterval(ping, intervalSeconds * 1000).unref();
}, SELF_PING_FIRST_DELAY_MS).unref();
}