litellm-rs 0.9.0

//! Runtime wiring decisions for exported `core` modules.
//!
//! This registry is the guardrail for declaration-execution drift: a module
//! exported from `src/core/mod.rs` must either be referenced by the gateway
//! runtime or have an explicit non-runtime classification here.

/// Current gateway-runtime decision for a `core` module.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubsystemDecision {
    /// The gateway server or binary constructs the module, mounts routes, or
    /// registers middleware for it.
    Wired,
    /// Library API or shared domain code intentionally has no direct gateway
    /// route, middleware, or startup path.
    LibraryOnly,
    /// Shared support code used below wired modules rather than exposed as its
    /// own gateway subsystem.
    InternalDependency,
    /// Module is hidden from the default build behind a default-off feature.
    FeatureGated,
    /// Parsed configuration exists but validation rejects enabling it until the
    /// runtime path lands.
    ConfigRejected,
}

impl CoreSubsystem {
    /// Returns true when a module can be absent from direct server/main
    /// references without creating a new declaration-execution gap.
    pub fn has_gateway_reference_exemption(&self) -> bool {
        self.decision != SubsystemDecision::Wired
    }
}

/// Explicit runtime status for one exported `core` module.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CoreSubsystem {
    pub name: &'static str,
    pub decision: SubsystemDecision,
    pub runtime_path: Option<&'static str>,
    pub note: &'static str,
}

/// Exhaustive matrix for modules exported from `src/core/mod.rs`.
pub const CORE_SUBSYSTEMS: &[CoreSubsystem] = &[
    CoreSubsystem {
        name: "a2a",
        decision: SubsystemDecision::FeatureGated,
        runtime_path: Some("Cargo feature: a2a"),
        note: "Opt-in A2A 1.0 JSON-RPC HTTP gateway with caller-bound tasks and Streamable events; ownership is process-local.",
    },
    CoreSubsystem {
        name: "audio",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("/v1/audio/* routes"),
        note: "Audio request paths are mounted by server AI routes.",
    },
    CoreSubsystem {
        name: "audit",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState AuditLogger and AuditMiddleware"),
        note: "enterprise.audit_logging explicitly enables request lifecycle audit events; the default remains disabled.",
    },
    CoreSubsystem {
        name: "batch",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "The HTTP /v1/batches surface is a provider proxy; batch domain records and async batch execution remain library APIs.",
    },
    CoreSubsystem {
        name: "budget",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState budget limits and budget routes"),
        note: "Budget state and reservation paths are constructed by the server.",
    },
    CoreSubsystem {
        name: "cache",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState response_cache and /admin/cache"),
        note: "Deterministic response cache is constructed when cache.enabled=true.",
    },
    CoreSubsystem {
        name: "completion",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "Library completion API is separate from gateway route handlers.",
    },
    CoreSubsystem {
        name: "cost",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: None,
        note: "Cost helpers back providers and spend calculation rather than a standalone route.",
    },
    CoreSubsystem {
        name: "embedding",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "Library embedding API is separate from gateway route handlers.",
    },
    CoreSubsystem {
        name: "fine_tuning",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("/v1/fine_tuning/jobs routes"),
        note: "Fine-tuning route handlers use the core provider adapters.",
    },
    CoreSubsystem {
        name: "function_calling",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "Function-calling helpers are library/provider support code.",
    },
    CoreSubsystem {
        name: "guardrails",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState GuardrailEngine and canonical chat request/response paths"),
        note: "Prompt-injection checks run before provider execution and on non-streaming output.",
    },
    CoreSubsystem {
        name: "health",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "Server health routes are implemented under src/server/routes/health.rs.",
    },
    CoreSubsystem {
        name: "http",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: None,
        note: "Shared outbound HTTP profile used by providers and integrations.",
    },
    CoreSubsystem {
        name: "integrations",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState callback dispatcher and LLM request lifecycle"),
        note: "Configured Langfuse, OpenTelemetry, and Datadog callbacks are initialized and receive real request lifecycle events.",
    },
    CoreSubsystem {
        name: "ip_access",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("IpAccessMiddleware outer HTTP policy layer"),
        note: "Configured IP policies short-circuit before auth, handlers, or providers.",
    },
    CoreSubsystem {
        name: "keys",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState key_manager and /v1/keys routes"),
        note: "Key management is constructed in AppState and exposed through server routes.",
    },
    CoreSubsystem {
        name: "mcp",
        decision: SubsystemDecision::FeatureGated,
        runtime_path: Some("Cargo feature: mcp"),
        note: "Opt-in authenticated stateless Streamable HTTP proxy for configured servers; requests can move between instances.",
    },
    CoreSubsystem {
        name: "models",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("server route request/response models"),
        note: "OpenAI-compatible models are used by gateway routes and auth context.",
    },
    CoreSubsystem {
        name: "net",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: None,
        note: "Network safety helpers are consumed by config/provider support code.",
    },
    CoreSubsystem {
        name: "observability",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState RuntimeObservability callback dispatcher"),
        note: "RuntimeObservability is the canonical callback dispatcher; retained redaction helpers protect provider configuration output.",
    },
    CoreSubsystem {
        name: "pricing",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: Some("spend route pricing normalization"),
        note: "Shared pricing helpers support runtime spend calculations.",
    },
    CoreSubsystem {
        name: "pricing_service",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState pricing service and pricing routes"),
        note: "PricingService is initialized at startup and shared with handlers.",
    },
    CoreSubsystem {
        name: "providers",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("UnifiedRouter provider factory"),
        note: "Gateway startup builds providers through the unified router.",
    },
    CoreSubsystem {
        name: "rate_limiter",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("RateLimitMiddleware"),
        note: "Global rate limiter is initialized by the server app factory.",
    },
    CoreSubsystem {
        name: "request_ledger",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState RequestLedgerRuntime and AuditMiddleware"),
        note: "storage.request_ledger persists one metadata-only terminal row per request when enabled; the default remains disabled.",
    },
    CoreSubsystem {
        name: "rerank",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("/v1/rerank route"),
        note: "Rerank requests are mounted in the AI route scope.",
    },
    CoreSubsystem {
        name: "router",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState UnifiedRouter"),
        note: "Gateway startup constructs UnifiedRouter from provider config.",
    },
    CoreSubsystem {
        name: "secret_managers",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "Secret manager adapters are available as library support code.",
    },
    CoreSubsystem {
        name: "security",
        decision: SubsystemDecision::LibraryOnly,
        runtime_path: None,
        note: "Core security filters are library support; server security middleware is separate.",
    },
    CoreSubsystem {
        name: "streaming",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("chat/completions/responses SSE routes"),
        note: "Streaming event types are used by mounted SSE handlers.",
    },
    CoreSubsystem {
        name: "subsystem_registry",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: None,
        note: "This guardrail registry classifies the exported core modules.",
    },
    CoreSubsystem {
        name: "teams",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState team_manager and team routes"),
        note: "Team management is constructed in AppState and exposed through server routes.",
    },
    CoreSubsystem {
        name: "traits",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: None,
        note: "Trait definitions support providers, integrations, and storage abstractions.",
    },
    CoreSubsystem {
        name: "types",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("server route request context and response types"),
        note: "Gateway handlers use shared context, response, model, and media types.",
    },
    CoreSubsystem {
        name: "user_management",
        decision: SubsystemDecision::InternalDependency,
        runtime_path: None,
        note: "User/team domain records back current auth and storage paths; the unused legacy manager has been removed.",
    },
    CoreSubsystem {
        name: "virtual_keys",
        decision: SubsystemDecision::Wired,
        runtime_path: Some("AppState canonical RuntimeVirtualKeyManager"),
        note: "The virtual-keys runtime facade resolves to the canonical KeyManager used by auth and /v1/keys; storage record types remain in use.",
    },
];

/// Look up the recorded decision for an exported core module.
pub fn subsystem_for(name: &str) -> Option<&'static CoreSubsystem> {
    CORE_SUBSYSTEMS
        .iter()
        .find(|subsystem| subsystem.name == name)
}

#[cfg(test)]
mod tests;