dynamo-runtime 1.0.2

// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

//! Environment variable name constants for centralized management across the codebase
//!
//! This module provides centralized environment variable name constants to ensure
//! consistency and avoid duplication across the codebase, similar to how
//! `prometheus_names.rs` manages metric names.
//!
//! ## Organization
//!
//! Environment variables are organized by functional area:
//! - **Logging**: Log level, configuration, and OTLP tracing
//! - **Runtime**: Tokio runtime configuration and system server settings
//! - **NATS**: NATS client connection and authentication
//! - **ETCD**: ETCD client connection and authentication
//! - **Event Plane**: Event transport selection (NATS)
//! - **KVBM**: Key-Value Block Manager configuration
//! - **LLM**: Language model inference configuration
//! - **Model**: Model loading and caching
//! - **Worker**: Worker lifecycle and shutdown
//! - **Testing**: Test-specific configuration
//! - **Mocker**: Mocker (mock scheduler/KV manager) configuration

/// Logging and tracing environment variables
pub mod logging {
    /// Log level (e.g., "debug", "info", "warn", "error")
    pub const DYN_LOG: &str = "DYN_LOG";

    /// Path to logging configuration file
    pub const DYN_LOGGING_CONFIG_PATH: &str = "DYN_LOGGING_CONFIG_PATH";

    /// Enable JSONL logging format
    pub const DYN_LOGGING_JSONL: &str = "DYN_LOGGING_JSONL";

    /// Disable ANSI terminal colors in logs
    pub const DYN_SDK_DISABLE_ANSI_LOGGING: &str = "DYN_SDK_DISABLE_ANSI_LOGGING";

    /// Use local timezone for logging timestamps (default is UTC)
    pub const DYN_LOG_USE_LOCAL_TZ: &str = "DYN_LOG_USE_LOCAL_TZ";

    /// Enable span event logging (create/close events)
    pub const DYN_LOGGING_SPAN_EVENTS: &str = "DYN_LOGGING_SPAN_EVENTS";

    /// OTLP (OpenTelemetry Protocol) tracing configuration
    pub mod otlp {
        /// Enable OTLP trace exporting (set to "1" to enable)
        pub const OTEL_EXPORT_ENABLED: &str = "OTEL_EXPORT_ENABLED";

        /// OTLP exporter endpoint URL
        /// Spec: https://opentelemetry.io/docs/specs/otel/protocol/exporter/
        pub const OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: &str = "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT";

        /// Service name for OTLP traces
        pub const OTEL_SERVICE_NAME: &str = "OTEL_SERVICE_NAME";
    }
}

/// Runtime configuration environment variables
///
/// These control the Tokio runtime, system health/metrics server, and worker behavior
pub mod runtime {
    /// Number of async worker threads for Tokio runtime
    pub const DYN_RUNTIME_NUM_WORKER_THREADS: &str = "DYN_RUNTIME_NUM_WORKER_THREADS";

    /// Maximum number of blocking threads for Tokio runtime
    pub const DYN_RUNTIME_MAX_BLOCKING_THREADS: &str = "DYN_RUNTIME_MAX_BLOCKING_THREADS";

    /// System status server configuration
    pub mod system {
        /// Enable system status server for health and metrics endpoints
        /// ⚠️ DEPRECATED: will be removed soon
        pub const DYN_SYSTEM_ENABLED: &str = "DYN_SYSTEM_ENABLED";

        /// System status server host
        pub const DYN_SYSTEM_HOST: &str = "DYN_SYSTEM_HOST";

        /// System status server port
        pub const DYN_SYSTEM_PORT: &str = "DYN_SYSTEM_PORT";

        /// Use endpoint health status for system health
        /// ⚠️ DEPRECATED: No longer used
        pub const DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS: &str =
            "DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS";

        /// Starting health status for the system
        pub const DYN_SYSTEM_STARTING_HEALTH_STATUS: &str = "DYN_SYSTEM_STARTING_HEALTH_STATUS";

        /// Health check endpoint path
        pub const DYN_SYSTEM_HEALTH_PATH: &str = "DYN_SYSTEM_HEALTH_PATH";

        /// Liveness check endpoint path
        pub const DYN_SYSTEM_LIVE_PATH: &str = "DYN_SYSTEM_LIVE_PATH";
    }

    /// Compute configuration
    pub mod compute {
        /// Prefix for compute-related environment variables
        pub const PREFIX: &str = "DYN_COMPUTE_";
    }

    /// Canary deployment configuration
    pub mod canary {
        /// Wait time in seconds for canary deployments
        pub const DYN_CANARY_WAIT_TIME: &str = "DYN_CANARY_WAIT_TIME";
    }
}

/// Worker lifecycle environment variables
pub mod worker {
    /// Graceful shutdown timeout in seconds
    pub const DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT: &str = "DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT";
}

/// NATS transport environment variables
pub mod nats {
    /// NATS server address (e.g., "nats://localhost:4222")
    pub const NATS_SERVER: &str = "NATS_SERVER";

    /// NATS authentication environment variables (checked in priority order)
    pub mod auth {
        /// Username for NATS authentication (use with NATS_AUTH_PASSWORD)
        pub const NATS_AUTH_USERNAME: &str = "NATS_AUTH_USERNAME";

        /// Password for NATS authentication (use with NATS_AUTH_USERNAME)
        pub const NATS_AUTH_PASSWORD: &str = "NATS_AUTH_PASSWORD";

        /// Token for NATS authentication
        pub const NATS_AUTH_TOKEN: &str = "NATS_AUTH_TOKEN";

        /// NKey for NATS authentication
        pub const NATS_AUTH_NKEY: &str = "NATS_AUTH_NKEY";

        /// Path to NATS credentials file
        pub const NATS_AUTH_CREDENTIALS_FILE: &str = "NATS_AUTH_CREDENTIALS_FILE";
    }

    /// NATS stream configuration
    pub mod stream {
        /// Maximum age for messages in NATS stream (in seconds)
        pub const DYN_NATS_STREAM_MAX_AGE: &str = "DYN_NATS_STREAM_MAX_AGE";
    }
}

/// ETCD transport environment variables
pub mod etcd {
    /// ETCD endpoints (comma-separated list of URLs)
    pub const ETCD_ENDPOINTS: &str = "ETCD_ENDPOINTS";

    /// ETCD authentication environment variables
    pub mod auth {
        /// Username for ETCD authentication
        pub const ETCD_AUTH_USERNAME: &str = "ETCD_AUTH_USERNAME";

        /// Password for ETCD authentication
        pub const ETCD_AUTH_PASSWORD: &str = "ETCD_AUTH_PASSWORD";

        /// Path to CA certificate for ETCD TLS
        pub const ETCD_AUTH_CA: &str = "ETCD_AUTH_CA";

        /// Path to client certificate for ETCD TLS
        pub const ETCD_AUTH_CLIENT_CERT: &str = "ETCD_AUTH_CLIENT_CERT";

        /// Path to client key for ETCD TLS
        pub const ETCD_AUTH_CLIENT_KEY: &str = "ETCD_AUTH_CLIENT_KEY";
    }
}

/// Key-Value Block Manager (KVBM) environment variables
pub mod kvbm {
    /// Enable KVBM metrics endpoint
    pub const DYN_KVBM_METRICS: &str = "DYN_KVBM_METRICS";

    /// KVBM metrics endpoint port
    pub const DYN_KVBM_METRICS_PORT: &str = "DYN_KVBM_METRICS_PORT";

    /// Enable KVBM recording for debugging.
    pub const DYN_KVBM_ENABLE_RECORD: &str = "DYN_KVBM_ENABLE_RECORD";

    /// Disable disk offload filter
    pub const DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER: &str = "DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER";

    /// CPU cache configuration
    pub mod cpu_cache {
        /// CPU cache size in GB
        pub const DYN_KVBM_CPU_CACHE_GB: &str = "DYN_KVBM_CPU_CACHE_GB";

        /// CPU cache size in number of blocks (override)
        pub const DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS: &str =
            "DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS";
    }

    /// Disk cache configuration
    pub mod disk_cache {
        /// Disk cache size in GB
        pub const DYN_KVBM_DISK_CACHE_GB: &str = "DYN_KVBM_DISK_CACHE_GB";

        /// Disk cache size in number of blocks (override)
        pub const DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS: &str =
            "DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS";
    }

    /// Object storage configuration
    pub mod object_storage {
        /// Enable object storage. Set to "1" to enable.
        pub const DYN_KVBM_OBJECT_ENABLED: &str = "DYN_KVBM_OBJECT_ENABLED";

        /// Bucket name for object storage cache
        /// Supports `{worker_id}` template for per-worker buckets
        /// Example: "kv-cache-{worker_id}"
        pub const DYN_KVBM_OBJECT_BUCKET: &str = "DYN_KVBM_OBJECT_BUCKET";

        /// Endpoint for object storage
        pub const DYN_KVBM_OBJECT_ENDPOINT: &str = "DYN_KVBM_OBJECT_ENDPOINT";

        /// Region for object storage
        pub const DYN_KVBM_OBJECT_REGION: &str = "DYN_KVBM_OBJECT_REGION";

        /// Access key for authentication
        pub const DYN_KVBM_OBJECT_ACCESS_KEY: &str = "DYN_KVBM_OBJECT_ACCESS_KEY";

        /// Secret key for authentication
        pub const DYN_KVBM_OBJECT_SECRET_KEY: &str = "DYN_KVBM_OBJECT_SECRET_KEY";

        /// Number of blocks to store in object storage
        pub const DYN_KVBM_OBJECT_NUM_BLOCKS: &str = "DYN_KVBM_OBJECT_NUM_BLOCKS";
    }
    /// Transfer configuration
    pub mod transfer {
        /// Maximum number of blocks per transfer batch
        pub const DYN_KVBM_TRANSFER_BATCH_SIZE: &str = "DYN_KVBM_TRANSFER_BATCH_SIZE";
    }

    /// KVBM leader (distributed mode) configuration
    pub mod leader {
        /// Timeout in seconds for KVBM leader and worker initialization
        pub const DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS: &str =
            "DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS";

        /// ZMQ host for KVBM leader
        pub const DYN_KVBM_LEADER_ZMQ_HOST: &str = "DYN_KVBM_LEADER_ZMQ_HOST";

        /// ZMQ publish port for KVBM leader
        pub const DYN_KVBM_LEADER_ZMQ_PUB_PORT: &str = "DYN_KVBM_LEADER_ZMQ_PUB_PORT";

        /// ZMQ acknowledgment port for KVBM leader
        pub const DYN_KVBM_LEADER_ZMQ_ACK_PORT: &str = "DYN_KVBM_LEADER_ZMQ_ACK_PORT";
    }

    /// NIXL backend configuration
    pub mod nixl {
        /// Prefix for NIXL backend environment variables
        /// Pattern: DYN_KVBM_NIXL_BACKEND_<backend>=true/false
        /// Example: DYN_KVBM_NIXL_BACKEND_UCX=true
        pub const PREFIX: &str = "DYN_KVBM_NIXL_BACKEND_";
    }
}

/// LLM (Language Model) inference environment variables
pub mod llm {
    /// HTTP body size limit in MB
    pub const DYN_HTTP_BODY_LIMIT_MB: &str = "DYN_HTTP_BODY_LIMIT_MB";

    pub const DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS: &str =
        "DYN_HTTP_GRACEFUL_SHUTDOWN_TIMEOUT_SECS";

    /// Enable LoRA adapter support (set to "true" to enable)
    pub const DYN_LORA_ENABLED: &str = "DYN_LORA_ENABLED";

    /// LoRA cache directory path
    pub const DYN_LORA_PATH: &str = "DYN_LORA_PATH";

    /// Enable the experimental Anthropic Messages API endpoint (/v1/messages)
    pub const DYN_ENABLE_ANTHROPIC_API: &str = "DYN_ENABLE_ANTHROPIC_API";

    /// Metrics configuration
    pub mod metrics {
        /// Custom metrics prefix (overrides default "dynamo_frontend")
        pub const DYN_METRICS_PREFIX: &str = "DYN_METRICS_PREFIX";

        /// Histogram bucket configuration (pattern: <PREFIX>_MIN, <PREFIX>_MAX, <PREFIX>_COUNT)
        /// Example: DYN_HISTOGRAM_TTFT_MIN, DYN_HISTOGRAM_TTFT_MAX, DYN_HISTOGRAM_TTFT_COUNT
        pub const HISTOGRAM_PREFIX: &str = "DYN_HISTOGRAM_";
    }
}

/// Model loading and caching environment variables
pub mod model {
    /// Model Express configuration
    pub mod model_express {
        /// Model Express server endpoint URL
        pub const MODEL_EXPRESS_URL: &str = "MODEL_EXPRESS_URL";

        /// Model Express cache path
        pub const MODEL_EXPRESS_CACHE_PATH: &str = "MODEL_EXPRESS_CACHE_PATH";
    }

    /// Hugging Face configuration
    pub mod huggingface {
        /// Hugging Face authentication token
        pub const HF_TOKEN: &str = "HF_TOKEN";

        /// Hugging Face Hub cache directory
        pub const HF_HUB_CACHE: &str = "HF_HUB_CACHE";

        /// Hugging Face home directory
        pub const HF_HOME: &str = "HF_HOME";

        /// Offline mode - skip API calls when model is cached
        /// Set to "1" or "true" to enable
        pub const HF_HUB_OFFLINE: &str = "HF_HUB_OFFLINE";
    }
}

/// Event Plane transport environment variables
pub mod event_plane {
    /// Event transport selection: "zmq" or "nats". Default: "nats"
    pub const DYN_EVENT_PLANE: &str = "DYN_EVENT_PLANE";

    /// Event plane codec selection: "json" or "msgpack".
    pub const DYN_EVENT_PLANE_CODEC: &str = "DYN_EVENT_PLANE_CODEC";
}

/// ZMQ Broker environment variables
pub mod zmq_broker {
    /// Explicit ZMQ broker URL (takes precedence over discovery)
    /// Format: "xsub=<url1>[;<url2>...] , xpub=<url1>[;<url2>...]"
    /// Example: "xsub=tcp://broker:5555 , xpub=tcp://broker:5556"
    pub const DYN_ZMQ_BROKER_URL: &str = "DYN_ZMQ_BROKER_URL";

    /// Enable ZMQ broker discovery mode
    pub const DYN_ZMQ_BROKER_ENABLED: &str = "DYN_ZMQ_BROKER_ENABLED";

    /// XSUB bind address (broker binary only)
    pub const ZMQ_BROKER_XSUB_BIND: &str = "ZMQ_BROKER_XSUB_BIND";

    /// XPUB bind address (broker binary only)
    pub const ZMQ_BROKER_XPUB_BIND: &str = "ZMQ_BROKER_XPUB_BIND";

    /// Namespace for broker discovery registration
    pub const ZMQ_BROKER_NAMESPACE: &str = "ZMQ_BROKER_NAMESPACE";
}

/// CUDA and GPU environment variables
pub mod cuda {
    /// Path to custom CUDA fatbin file.
    ///
    /// Note: build.rs files cannot import this constant at build time,
    /// so they must define local constants with the same value.
    pub const DYN_FATBIN_PATH: &str = "DYN_FATBIN_PATH";
}

/// Build-time environment variables
pub mod build {
    /// Cargo output directory for build artifacts
    ///
    /// Note: This constant cannot be used with the `env!()` macro,
    /// which requires a string literal at compile time.
    /// Build scripts (build.rs) also cannot import this constant.
    pub const OUT_DIR: &str = "OUT_DIR";
}

/// Mocker (mock scheduler/KV manager) environment variables
pub mod mocker {
    /// Enable structured KV cache allocation/eviction trace logs (set to "1" or "true" to enable)
    pub const DYN_MOCKER_KV_CACHE_TRACE: &str = "DYN_MOCKER_KV_CACHE_TRACE";

    /// Use the original direct() code path in the mocker request dispatch.
    ///
    /// This path is race-prone during startup; prefer leaving it unset unless you are
    /// explicitly trying to reproduce the original behavior.
    pub const DYN_MOCKER_SYNC_DIRECT: &str = "DYN_MOCKER_SYNC_DIRECT";
}

/// Testing environment variables
pub mod testing {
    /// Enable queued-up request processing in tests
    pub const DYN_QUEUED_UP_PROCESSING: &str = "DYN_QUEUED_UP_PROCESSING";

    /// Soak test run duration (e.g., "3s", "5m")
    pub const DYN_SOAK_RUN_DURATION: &str = "DYN_SOAK_RUN_DURATION";

    /// Soak test batch load size
    pub const DYN_SOAK_BATCH_LOAD: &str = "DYN_SOAK_BATCH_LOAD";
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_no_duplicate_env_var_names() {
        use std::collections::HashSet;

        let mut seen = HashSet::new();
        let vars = [
            // Logging
            logging::DYN_LOG,
            logging::DYN_LOGGING_CONFIG_PATH,
            logging::DYN_LOGGING_JSONL,
            logging::DYN_SDK_DISABLE_ANSI_LOGGING,
            logging::DYN_LOG_USE_LOCAL_TZ,
            logging::DYN_LOGGING_SPAN_EVENTS,
            logging::otlp::OTEL_EXPORT_ENABLED,
            logging::otlp::OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
            logging::otlp::OTEL_SERVICE_NAME,
            // Runtime
            runtime::DYN_RUNTIME_NUM_WORKER_THREADS,
            runtime::DYN_RUNTIME_MAX_BLOCKING_THREADS,
            runtime::system::DYN_SYSTEM_ENABLED,
            runtime::system::DYN_SYSTEM_HOST,
            runtime::system::DYN_SYSTEM_PORT,
            runtime::system::DYN_SYSTEM_USE_ENDPOINT_HEALTH_STATUS,
            runtime::system::DYN_SYSTEM_STARTING_HEALTH_STATUS,
            runtime::system::DYN_SYSTEM_HEALTH_PATH,
            runtime::system::DYN_SYSTEM_LIVE_PATH,
            runtime::canary::DYN_CANARY_WAIT_TIME,
            // Worker
            worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT,
            // NATS
            nats::NATS_SERVER,
            nats::auth::NATS_AUTH_USERNAME,
            nats::auth::NATS_AUTH_PASSWORD,
            nats::auth::NATS_AUTH_TOKEN,
            nats::auth::NATS_AUTH_NKEY,
            nats::auth::NATS_AUTH_CREDENTIALS_FILE,
            nats::stream::DYN_NATS_STREAM_MAX_AGE,
            // ETCD
            etcd::ETCD_ENDPOINTS,
            etcd::auth::ETCD_AUTH_USERNAME,
            etcd::auth::ETCD_AUTH_PASSWORD,
            etcd::auth::ETCD_AUTH_CA,
            etcd::auth::ETCD_AUTH_CLIENT_CERT,
            etcd::auth::ETCD_AUTH_CLIENT_KEY,
            // KVBM
            kvbm::DYN_KVBM_METRICS,
            kvbm::DYN_KVBM_METRICS_PORT,
            kvbm::DYN_KVBM_ENABLE_RECORD,
            kvbm::DYN_KVBM_DISABLE_DISK_OFFLOAD_FILTER,
            kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_GB,
            kvbm::cpu_cache::DYN_KVBM_CPU_CACHE_OVERRIDE_NUM_BLOCKS,
            kvbm::disk_cache::DYN_KVBM_DISK_CACHE_GB,
            kvbm::disk_cache::DYN_KVBM_DISK_CACHE_OVERRIDE_NUM_BLOCKS,
            kvbm::leader::DYN_KVBM_LEADER_WORKER_INIT_TIMEOUT_SECS,
            kvbm::leader::DYN_KVBM_LEADER_ZMQ_HOST,
            kvbm::leader::DYN_KVBM_LEADER_ZMQ_PUB_PORT,
            kvbm::leader::DYN_KVBM_LEADER_ZMQ_ACK_PORT,
            // LLM
            llm::DYN_HTTP_BODY_LIMIT_MB,
            llm::DYN_LORA_ENABLED,
            llm::DYN_LORA_PATH,
            llm::DYN_ENABLE_ANTHROPIC_API,
            llm::metrics::DYN_METRICS_PREFIX,
            // Model
            model::model_express::MODEL_EXPRESS_URL,
            model::model_express::MODEL_EXPRESS_CACHE_PATH,
            model::huggingface::HF_TOKEN,
            model::huggingface::HF_HUB_CACHE,
            model::huggingface::HF_HOME,
            model::huggingface::HF_HUB_OFFLINE,
            // Event Plane
            event_plane::DYN_EVENT_PLANE,
            event_plane::DYN_EVENT_PLANE_CODEC,
            // ZMQ Broker
            zmq_broker::DYN_ZMQ_BROKER_URL,
            zmq_broker::DYN_ZMQ_BROKER_ENABLED,
            zmq_broker::ZMQ_BROKER_XSUB_BIND,
            zmq_broker::ZMQ_BROKER_XPUB_BIND,
            zmq_broker::ZMQ_BROKER_NAMESPACE,
            // CUDA
            cuda::DYN_FATBIN_PATH,
            // Build
            build::OUT_DIR,
            // Mocker
            mocker::DYN_MOCKER_KV_CACHE_TRACE,
            mocker::DYN_MOCKER_SYNC_DIRECT,
            // Testing
            testing::DYN_QUEUED_UP_PROCESSING,
            testing::DYN_SOAK_RUN_DURATION,
            testing::DYN_SOAK_BATCH_LOAD,
        ];

        for var in &vars {
            if !seen.insert(var) {
                panic!("Duplicate environment variable name: {}", var);
            }
        }
    }

    #[test]
    fn test_naming_conventions() {
        // Dynamo-specific vars should start with DYN_
        assert!(runtime::DYN_RUNTIME_NUM_WORKER_THREADS.starts_with("DYN_"));
        assert!(runtime::system::DYN_SYSTEM_ENABLED.starts_with("DYN_"));
        assert!(kvbm::DYN_KVBM_METRICS.starts_with("DYN_"));
        assert!(worker::DYN_WORKER_GRACEFUL_SHUTDOWN_TIMEOUT.starts_with("DYN_"));

        // NATS vars should start with NATS_
        assert!(nats::NATS_SERVER.starts_with("NATS_"));
        assert!(nats::auth::NATS_AUTH_USERNAME.starts_with("NATS_AUTH_"));

        // ETCD vars should start with ETCD_
        assert!(etcd::ETCD_ENDPOINTS.starts_with("ETCD_"));
        assert!(etcd::auth::ETCD_AUTH_USERNAME.starts_with("ETCD_AUTH_"));

        // OpenTelemetry vars should start with OTEL_
        assert!(logging::otlp::OTEL_EXPORT_ENABLED.starts_with("OTEL_"));
        assert!(logging::otlp::OTEL_SERVICE_NAME.starts_with("OTEL_"));
    }
}