mcp-server-framework 1.0.0

package/build/config/config-cache.js

@@ -0,0 +1,310 @@
+/**
+ * Framework Config Cache
+ *
+ * Provides a cached, lazily-initialized accessor for the parsed
+ * framework environment configuration. Single source of truth —
+ * all modules delegate to this cache instead of caching locally.
+ *
+ * Config sources are applied in 12-Factor priority order (highest wins):
+ * 1. Defaults (from Zod schema)
+ * 2. `.env` file (parsed via `dotenv.parse()` — no `process.env` mutation)
+ * 3. Config file (config.toml / config.yaml / config.yml / config.json)
+ * 4. Environment variables (`process.env`)
+ * 5. Programmatic overrides (via `applyConfigOverrides()`)
+ *
+ * This follows the 12-Factor App methodology: environment variables
+ * always override config file values, enabling per-deploy overrides
+ * without touching configuration files.
+ *
+ * Derived caches in middleware (DNS rebinding, rate limiter) register
+ * their reset functions so `resetConfigCache()` invalidates everything.
+ *
+ * @module config/config-cache
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseDotenv } from "dotenv";
+import { parseFrameworkEnv, validateConfigConstraints } from "./env.js";
+import { resetConfigExtensions } from "./extensions.js";
+import { loadConfigFile, mapConfigToEnvKeys } from "./file/index.js";
+import { addStartupWarning, resetStartupWarnings } from "./startup-warnings.js";
+import { ConfigurationError } from "../errors/categories/validation.js";
+// ============================================================================
+// Deferred Logger (injected after logger initialization)
+// ============================================================================
+const LogMessages = {
+    INITIALIZED: "Configuration initialized (source: %s)",
+    INITIALIZED_FILE: "Configuration initialized from %s (%s format)",
+    DOTENV_LOADED: ".env file loaded: %d variable(s)",
+    DOTENV_NOT_FOUND: "No .env file found — using environment variables only",
+    CONFIG_FILE_DETECTED: "Config file detected: %s (format: %s)",
+    OVERRIDES_APPLIED: "Programmatic config overrides applied (%d key(s))",
+    CACHE_RESET: "Config cache reset (including %d satellite caches)",
+};
+/** Noop logger used before the real logger is injected */
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+};
+/** Injected logger instance */
+let logger = noopLogger;
+/**
+ * Inject the framework logger into the config module.
+ *
+ * Called once during server startup after the logger is initialized.
+ * Before injection, log calls are silently dropped (startup-critical
+ * warnings use `addStartupWarning()` which writes to stderr immediately).
+ *
+ * @param injectedLogger - A ConfigLogger instance (caller creates child logger)
+ * @internal
+ */
+export function setConfigLogger(injectedLogger) {
+    logger = injectedLogger;
+}
+// ============================================================================
+// Cached Config
+// ============================================================================
+/** Cached config instance (lazy initialization) */
+let cachedConfig;
+/** Metadata about how the config was loaded */
+let configSource;
+/** Registered satellite cache reset functions */
+const satelliteResets = [];
+/**
+ * Check whether the framework config has been initialized.
+ *
+ * Used by the extensions module to guard against late registration
+ * of config sections after config loading is complete.
+ *
+ * @returns `true` if `getFrameworkConfig()` has been called at least once
+ * @internal
+ */
+export function isConfigInitialized() {
+    return cachedConfig !== undefined;
+}
+/**
+ * Returns the parsed framework environment configuration.
+ *
+ * The config is lazily initialized on first access and cached
+ * for the lifetime of the process. This avoids re-parsing
+ * environment variables on every request.
+ *
+ * On first call, the initialization sequence is:
+ * 1. Parse environment variables (defaults + env)
+ * 2. Discover and load config file (if present)
+ * 3. Merge config file and overrides env config
+ * 4. Validate cross-field constraints on merged result
+ *
+ * @returns Parsed and validated framework environment configuration
+ */
+export function getFrameworkConfig() {
+    if (!cachedConfig) {
+        cachedConfig = Object.freeze(initializeConfig());
+    }
+    return cachedConfig;
+}
+/**
+ * Returns metadata about which config source is active.
+ *
+ * Useful for logging after the logger is initialized.
+ * Returns `undefined` if the config hasn't been loaded yet.
+ */
+export function getConfigSource() {
+    return configSource;
+}
+/**
+ * Registers a satellite cache reset function.
+ *
+ * Modules that derive cached values from the framework config
+ * (e.g., allowed hosts list, rate limiter instance) register their
+ * reset functions here so `resetConfigCache()` can invalidate them.
+ *
+ * @param resetFn - Function that clears the satellite cache
+ * @internal
+ */
+export function registerCacheReset(resetFn) {
+    if (!satelliteResets.includes(resetFn)) {
+        satelliteResets.push(resetFn);
+    }
+}
+/**
+ * Resets the framework config cache and all registered satellite caches.
+ *
+ * Intended for testing — forces re-parsing of environment
+ * variables on the next `getFrameworkConfig()` call and
+ * invalidates all derived caches.
+ *
+ * @internal
+ */
+export function resetConfigCache() {
+    cachedConfig = undefined;
+    configSource = undefined;
+    resetConfigExtensions();
+    resetStartupWarnings();
+    for (const reset of satelliteResets) {
+        reset();
+    }
+    logger.debug(LogMessages.CACHE_RESET, satelliteResets.length);
+}
+/**
+ * Applies programmatic overrides to the framework configuration cache.
+ *
+ * This bridges the gap between programmatic `createServer()` options and
+ * the environment-based framework configuration. Called early in the server
+ * startup sequence (before transport creation) to ensure all downstream
+ * modules see consistent configuration.
+ *
+ * Only non-undefined values are applied — environment variables remain
+ * the default source for any unspecified options.
+ *
+ * Automatically invalidates satellite caches (rate limiter, DNS rebinding, etc.)
+ * since the underlying config has changed.
+ *
+ * After merging, cross-field constraints are re-validated to catch
+ * invalid combinations (e.g., HTTPS mode without TLS paths).
+ *
+ * @param overrides - Partial config to merge into the cached configuration
+ */
+export function applyConfigOverrides(overrides) {
+    // Ensure base config is initialized from environment + config file
+    const base = getFrameworkConfig();
+    const merged = mergeConfigValues(base, overrides);
+    // Re-validate cross-field constraints after merge
+    validateMergedConfig(merged);
+    cachedConfig = Object.freeze(merged);
+    // Invalidate derived caches since underlying config changed
+    for (const reset of satelliteResets) {
+        reset();
+    }
+    const overrideCount = Object.values(overrides).filter((v) => v !== undefined).length;
+    logger.debug(LogMessages.OVERRIDES_APPLIED, overrideCount);
+}
+// ============================================================================
+// Initialization
+// ============================================================================
+/**
+ * Initialize the framework config from all sources.
+ *
+ * 12-Factor Priority: Defaults → .env → Config File → env vars
+ * (Programmatic overrides come later via `applyConfigOverrides()`)
+ *
+ * The `.env` file is read and parsed without mutating `process.env`.
+ * Config file values are serialized back to string key-value pairs
+ * and merged into the env source so that `process.env` always wins.
+ *
+ * This single-pass approach ensures Zod coercion (string → number,
+ * string → boolean) happens exactly once, on the final merged source.
+ */
+function initializeConfig() {
+    // Step 1: Read .env file into a plain object (no process.env mutation)
+    const dotenvValues = loadDotenvFile();
+    // Step 2: Try loading a config file
+    const fileResult = loadConfigFile();
+    if (fileResult) {
+        logger.debug(LogMessages.CONFIG_FILE_DETECTED, fileResult.sourcePath, fileResult.format);
+    }
+    // Step 3: Build merged env source in 12-Factor priority order:
+    //   .env (lowest) → config file → process.env (highest)
+    const fileEnvKeys = fileResult ? mapConfigToEnvKeys(fileResult.overrides) : {};
+    const envSource = { ...dotenvValues, ...fileEnvKeys, ...process.env };
+    // Step 4: Parse merged source through Zod schema (single pass)
+    const config = parseFrameworkEnv(envSource);
+    // Step 5: Validate cross-field constraints
+    if (fileResult) {
+        validateMergedConfig(config);
+    }
+    // Step 6: Record which config source is active
+    configSource = fileResult
+        ? {
+            type: "file",
+            path: fileResult.sourcePath,
+            format: fileResult.format,
+            dotenvLoaded: Object.keys(dotenvValues).length > 0,
+        }
+        : { type: "env", dotenvLoaded: Object.keys(dotenvValues).length > 0 };
+    // Log the initialization result
+    if (fileResult) {
+        logger.info(LogMessages.INITIALIZED_FILE, fileResult.sourcePath, fileResult.format);
+    }
+    else {
+        logger.info(LogMessages.INITIALIZED, "environment");
+    }
+    return config;
+}
+// ============================================================================
+// dotenv Loader (Side-Effect-Free)
+// ============================================================================
+/**
+ * Read and parse a `.env` file without mutating `process.env`.
+ *
+ * Uses `dotenv.parse()` (pure function) instead of `dotenv.config()`
+ * to avoid global side effects. The returned object is merged with
+ * `process.env` by the caller, ensuring real env vars always win.
+ *
+ * Silently returns an empty object when no `.env` file exists —
+ * this is the normal case in Docker / CI environments.
+ *
+ * Security:
+ * - Only reads `.env` in `process.cwd()` (no directory traversal)
+ * - `.env` files should not be committed to version control
+ *
+ * @returns Parsed key-value pairs from the `.env` file, or empty object
+ */
+function loadDotenvFile() {
+    const dotenvPath = join(process.cwd(), ".env");
+    if (!existsSync(dotenvPath)) {
+        logger.debug(LogMessages.DOTENV_NOT_FOUND);
+        return {};
+    }
+    try {
+        const content = readFileSync(dotenvPath, "utf-8");
+        const parsed = parseDotenv(content);
+        logger.debug(LogMessages.DOTENV_LOADED, Object.keys(parsed).length);
+        return parsed;
+    }
+    catch {
+        // .env exists but can't be read (e.g., permission denied)
+        addStartupWarning(`[config] .env file at ${dotenvPath} exists but could not be read — skipping`);
+        return {};
+    }
+}
+/**
+ * Merges override values into a base config.
+ *
+ * Only non-undefined values from the overrides are applied.
+ * Uses dynamic key access because the override source (env, file,
+ * programmatic) is not statically known at compile time.
+ *
+ * @param base - The base configuration to merge into
+ * @param overrides - Partial overrides to apply
+ * @returns Merged configuration
+ *
+ * @type-narrowing Dynamic key iteration requires `Record<string, unknown>` cast
+ * because `Object.entries()` erases the key type to `string`. The merged
+ * result is typed as `FrameworkEnvConfig` — callers must only pass valid keys.
+ */
+function mergeConfigValues(base, overrides) {
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value !== undefined) {
+            // @type-narrowing — Object.entries() erases key type; override keys are
+            // constrained by Partial<FrameworkEnvConfig> at the call site.
+            merged[key] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * Validate cross-field constraints on a merged configuration.
+ *
+ * @throws {ConfigurationError} If constraints are violated
+ */
+function validateMergedConfig(config) {
+    const violations = validateConfigConstraints(config);
+    if (violations.length > 0) {
+        const fields = violations.flatMap((v) => [...v.path]);
+        const messages = violations.map((v) => v.message).join("; ");
+        throw ConfigurationError.constraintViolation(messages, fields);
+    }
+}
+//# sourceMappingURL=config-cache.js.map

package/build/config/config-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-cache.js","sourceRoot":"","sources":["../../src/config/config-cache.ts"],"names":[],"mappings":"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"}