Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
/**
* Structured Logger — FASE-05 Code Quality
*
* Lightweight structured logging wrapper with JSON output for production
* and human-readable output for development. Replaces scattered console.log
* calls with consistent, parseable log entries.
*
* When APP_LOG_TO_FILE is enabled, log entries are also appended as JSON lines
* to the application log file for the Console Log Viewer.
*
* @module shared/utils/structuredLogger
*/
import { getCorrelationId } from "../middleware/correlationId";
import { appendFileSync, existsSync, mkdirSync } from "fs";
import { dirname, resolve } from "path";
import { getAppLogFilePath, getAppLogLevel, getAppLogToFile } from "@/lib/logEnv";
const LOG_LEVELS: Record<string, number> = {
debug: 10,
info: 20,
warn: 30,
error: 40,
fatal: 50,
};
const currentLevel = LOG_LEVELS[getAppLogLevel("info").toLowerCase() || ""] || LOG_LEVELS.info;
const isProduction = process.env.NODE_ENV === "production";
// File logging configuration
const logToFile = getAppLogToFile();
const logFilePath = resolve(getAppLogFilePath());
// Ensure log directory exists once at module load
if (logToFile) {
try {
const dir = dirname(logFilePath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
} catch {
// silently ignore — will retry on each write
}
}
/**
* Append a JSON log line to the log file (non-blocking best-effort).
*/
function writeToFile(entry: Record<string, unknown>) {
if (!logToFile) return;
try {
appendFileSync(logFilePath, JSON.stringify(entry) + "\n");
} catch {
// Silently fail — file logging should never break the app
}
}
function formatEntry(
level: string,
component: string,
message: string,
meta?: Record<string, unknown>
) {
const entry: Record<string, unknown> = {
timestamp: new Date().toISOString(),
level,
component,
message,
...meta,
};
// Add correlation ID if available
const correlationId = getCorrelationId() as string | undefined;
if (correlationId) {
entry.correlationId = correlationId;
}
if (isProduction) {
return JSON.stringify(entry);
}
// Human-readable for development
const metaStr = meta && Object.keys(meta).length > 0 ? ` ${JSON.stringify(meta)}` : "";
const corrStr = correlationId ? ` [${correlationId.slice(0, 8)}]` : "";
return `[${entry.timestamp}] ${level.toUpperCase().padEnd(5)} [${component}]${corrStr} ${message}${metaStr}`;
}
function buildEntry(
level: string,
component: string,
message: string,
meta?: Record<string, unknown>
) {
const entry: Record<string, unknown> = {
timestamp: new Date().toISOString(),
level,
component,
message,
...meta,
};
const correlationId = getCorrelationId() as string | undefined;
if (correlationId) {
entry.correlationId = correlationId;
}
return entry;
}
// EPIPE-safe error deduplication + rate limiting (#1006)
const _recentErrors = new Map<string, { count: number; firstSeen: number }>();
const DEDUP_WINDOW_MS = 5_000;
const MAX_WRITES_PER_SECOND = 50;
// Hard cap on tracked distinct error messages. The age-based cleanup only removes entries
// older than DEDUP_WINDOW_MS, so a burst of >100 *unique* messages within a single 5s window
// (e.g. messages embedding request ids / urls / timestamps) could outpace it and grow the map.
// This bound evicts the oldest entries (Map preserves insertion order) as a backstop.
const MAX_TRACKED_ERRORS = 500;
let _writeCount = 0;
let _writeWindowStart = Date.now();
function pruneRecentErrors(now: number): void {
// Age-based cleanup of expired entries.
if (_recentErrors.size > 100) {
for (const [key, entry] of _recentErrors) {
if (now - entry.firstSeen > DEDUP_WINDOW_MS) _recentErrors.delete(key);
}
}
// Hard size cap: evict oldest (insertion-order) entries if a unique-message burst outpaced
// the age-based cleanup.
if (_recentErrors.size >= MAX_TRACKED_ERRORS) {
const overflow = _recentErrors.size - MAX_TRACKED_ERRORS + 1;
let removed = 0;
for (const key of _recentErrors.keys()) {
if (removed >= overflow) break;
_recentErrors.delete(key);
removed++;
}
}
}
function shouldSuppressError(message: string): boolean {
const now = Date.now();
// Rate limit: max writes per second
if (now - _writeWindowStart > 1000) {
_writeCount = 0;
_writeWindowStart = now;
}
if (_writeCount >= MAX_WRITES_PER_SECOND) return true;
// Dedup: suppress identical messages within window
const existing = _recentErrors.get(message);
if (existing && now - existing.firstSeen < DEDUP_WINDOW_MS) {
existing.count++;
return true;
}
pruneRecentErrors(now);
_recentErrors.set(message, { count: 1, firstSeen: now });
_writeCount++;
return false;
}
/** Test-only internals for verifying the dedup-map bound. */
export const __structuredLoggerInternals = {
recentErrors: _recentErrors,
pruneRecentErrors,
MAX_TRACKED_ERRORS,
isStreamWritable,
};
/**
* True when a stream can still accept a write.
*
* Exported via __structuredLoggerInternals for tests: the real process.stderr cannot be
* destroyed in-process to exercise this, because the test runner writes its own output there.
*/
function isStreamWritable(stream: { destroyed?: boolean; writableEnded?: boolean }): boolean {
return stream.destroyed !== true && stream.writableEnded !== true;
}
/**
* Write a line to stderr, skipping the write entirely when the stream is already known-bad.
*
* The `try {} catch {}` this replaces could only ever catch a *synchronous* failure. On a
* broken pipe the write fails asynchronously and surfaces as an 'error' event on the stream,
* which — with no listener attached — Node re-throws as an uncaughtException. That is the
* ignition point of the #8181 log-flood loop, and it fires from the very line whose comment
* says raw stderr writes are used to *avoid* EPIPE loops.
*
* consoleInterceptor now attaches the listener that stops the loop; this guard is defence in
* depth, so a dead stream is not written to in the first place. The catch is retained for the
* synchronous cases it always covered.
*/
function safeStderrWrite(text: string): void {
if (!isStreamWritable(process.stderr)) return;
try {
process.stderr.write(text);
} catch {
/* synchronous write failures remain non-fatal, as before */
}
}
export function createLogger(component: string) {
return {
debug(message: string, meta?: Record<string, unknown>) {
if (currentLevel <= LOG_LEVELS.debug) {
const entry = buildEntry("debug", component, message, meta);
console.debug(formatEntry("debug", component, message, meta));
writeToFile(entry);
}
},
info(message: string, meta?: Record<string, unknown>) {
if (currentLevel <= LOG_LEVELS.info) {
const entry = buildEntry("info", component, message, meta);
console.info(formatEntry("info", component, message, meta));
writeToFile(entry);
}
},
warn(message: string, meta?: Record<string, unknown>) {
if (currentLevel <= LOG_LEVELS.warn) {
const entry = buildEntry("warn", component, message, meta);
console.warn(formatEntry("warn", component, message, meta));
writeToFile(entry);
}
},
error(message: string, meta?: Record<string, unknown>) {
if (currentLevel <= LOG_LEVELS.error) {
if (shouldSuppressError(message)) return;
const entry = buildEntry("error", component, message, meta);
// Use stderr.write to avoid Next.js console patching that triggers EPIPE loops.
// Guarded: an unguarded write here is the ignition point of #8181.
safeStderrWrite(formatEntry("error", component, message, meta) + "\n");
writeToFile(entry);
}
},
fatal(message: string, meta?: Record<string, unknown>) {
if (shouldSuppressError(message)) return;
const entry = buildEntry("fatal", component, message, meta);
safeStderrWrite(formatEntry("fatal", component, message, meta) + "\n");
writeToFile(entry);
},
child(defaultMeta: Record<string, unknown>) {
return createLogger(component);
},
};
}
export { LOG_LEVELS };