structured_proxy/

config.rs

//! YAML-based proxy configuration.
//!
//! All product-specific behavior is driven by config, not code.
//! Same binary, different YAML = different product proxy.

use serde::Deserialize;
use std::path::PathBuf;

/// Top-level proxy configuration (loaded from YAML).
///
/// This and the wiring structs below (`UpstreamConfig`, `ListenConfig`,
/// `ServiceConfig`, `DescriptorSource`) are intentionally NOT
/// `#[non_exhaustive]`: embedding consumers build them programmatically with
/// runtime values. The leaf auth/shield/oidc config structs are
/// `#[non_exhaustive]` instead, since those are deserialized, not hand-built.
#[derive(Debug, Clone, Deserialize)]
pub struct ProxyConfig {
    /// The remote gRPC upstream. Required by the standalone proxy and by
    /// [`ProxyServer::upstream`](crate::ProxyServer::upstream); an embedder
    /// whose upstream is in process
    /// ([`ProxyServer::service`](crate::ProxyServer::service)) leaves it out.
    #[serde(default)]
    pub upstream: Option<UpstreamConfig>,

    /// Proto descriptor sources.
    #[serde(default, deserialize_with = "deserialize_descriptor_sources")]
    pub descriptors: Vec<DescriptorSource>,

    /// Listen addresses.
    #[serde(default)]
    pub listen: ListenConfig,

    /// Service identity (for health endpoint, metrics namespace).
    #[serde(default)]
    pub service: ServiceConfig,

    /// Path aliases (e.g., /oauth2/* → /v1/oauth2/*).
    #[serde(default)]
    pub aliases: Vec<AliasConfig>,

    /// OpenAPI generation.
    #[serde(default)]
    pub openapi: Option<OpenApiConfig>,

    /// Auth configuration (JWT, forward auth, AuthZ).
    #[serde(default)]
    pub auth: Option<AuthConfig>,

    /// Rate limiting (Shield).
    #[serde(default)]
    pub shield: Option<ShieldConfig>,

    /// OIDC discovery (optional — for IdP proxies).
    #[serde(default)]
    pub oidc_discovery: Option<OidcDiscoveryConfig>,

    /// Health-probe endpoints (paths configurable; can be disabled).
    #[serde(default)]
    pub health: HealthConfig,

    /// Prometheus metrics endpoint (path configurable; can be disabled).
    #[serde(default)]
    pub metrics: MetricsConfig,

    /// Maintenance mode.
    #[serde(default)]
    pub maintenance: MaintenanceConfig,

    /// CORS configuration.
    #[serde(default)]
    pub cors: CorsConfig,

    /// Logging.
    #[serde(default)]
    pub logging: LoggingConfig,

    /// Metrics endpoint classification (path patterns → class labels).
    #[serde(default)]
    pub metrics_classes: Vec<MetricsClassConfig>,

    /// Headers to forward from HTTP to gRPC metadata.
    #[serde(default = "default_forwarded_headers")]
    pub forwarded_headers: Vec<String>,

    /// Server-streaming response behavior.
    #[serde(default)]
    pub streaming: StreamingConfig,

    /// Request concurrency limit.
    #[serde(default)]
    pub concurrency: Option<ConcurrencyConfig>,

    /// How gRPC-Web calls reach the upstream.
    #[serde(default)]
    pub grpc_web: GrpcWebConfig,

    /// Which annotated RPCs are transcoded.
    #[serde(default)]
    pub transcode: TranscodeConfig,
}

impl Default for ProxyConfig {
    /// The configuration of an empty YAML file: health and metrics endpoints
    /// on, everything else off.
    fn default() -> Self {
        Self {
            upstream: None,
            descriptors: Vec::new(),
            listen: ListenConfig::default(),
            service: ServiceConfig::default(),
            aliases: Vec::new(),
            openapi: None,
            auth: None,
            shield: None,
            oidc_discovery: None,
            health: HealthConfig::default(),
            metrics: MetricsConfig::default(),
            maintenance: MaintenanceConfig::default(),
            cors: CorsConfig::default(),
            logging: LoggingConfig::default(),
            metrics_classes: Vec::new(),
            forwarded_headers: default_forwarded_headers(),
            streaming: StreamingConfig::default(),
            concurrency: None,
            grpc_web: GrpcWebConfig::default(),
            transcode: TranscodeConfig::default(),
        }
    }
}

/// Which annotated RPCs are transcoded.
///
/// ```yaml
/// transcode:
///   only: ["acme.v1.Orders", "acme.v1.Users/GetUser"]
/// ```
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TranscodeConfig {
    /// Services (`package.Service`) and single methods
    /// (`package.Service/Method`) whose `google.api.http` rules become REST
    /// routes; empty transcodes every annotated RPC. A name the descriptors do
    /// not hold stops the proxy at startup.
    #[serde(default)]
    pub only: Vec<String>,
}

/// One config section from YAML, the way the config file reads it: for the
/// sections an embedder hands to a builder method, such as
/// [`ProxyServer::with_rate_limits`](crate::ProxyServer::with_rate_limits).
///
/// # Errors
///
/// YAML that is not that section.
///
/// # Examples
///
/// ```
/// use structured_proxy::config::{self, ShieldConfig};
///
/// let shield: ShieldConfig = config::from_yaml(
///     "enabled: true\nprofiles:\n  anon: { rate: \"60/min\" }\nrules:\n  - pattern: \"/**\"\n    key: { type: ip }\n    profile: anon\n",
/// )
/// .unwrap();
/// assert!(shield.enabled);
/// ```
pub fn from_yaml<T: serde::de::DeserializeOwned>(yaml: &str) -> anyhow::Result<T> {
    Ok(serde_yaml::from_str(yaml)?)
}

/// How gRPC-Web calls reach the upstream.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct GrpcWebConfig {
    /// Translate gRPC-Web (binary and text, over HTTP/1.1 too) to gRPC for an
    /// upstream that speaks only gRPC. Off: gRPC-Web passes through, for an
    /// upstream that translates it itself. Needs the proxy's CORS policy on
    /// gRPC-Web (`cors.grpc_web`), since the upstream then cannot answer a
    /// browser's preflight.
    #[serde(default)]
    pub translate: bool,
}

fn default_forwarded_headers() -> Vec<String> {
    vec![
        "authorization".into(),
        "dpop".into(),
        "x-request-id".into(),
        "x-forwarded-for".into(),
        "x-forwarded-proto".into(),
        "x-real-ip".into(),
        "accept-language".into(),
        "user-agent".into(),
        "idempotency-key".into(),
    ]
}

/// Server-streaming response behavior.
///
/// Server-streaming RPCs are exposed as NDJSON by default and as Server-Sent
/// Events when the client sends `Accept: text/event-stream`. The keep-alive
/// interval applies only to the SSE path.
#[derive(Debug, Clone, Deserialize)]
pub struct StreamingConfig {
    /// SSE keep-alive interval in seconds. Comment frames are emitted on idle
    /// streams to keep intermediaries (load balancers, nginx) from closing the
    /// connection on read timeout. Default: 15.
    #[serde(default = "default_sse_keep_alive_secs")]
    pub sse_keep_alive_secs: u64,
}

fn default_sse_keep_alive_secs() -> u64 {
    15
}

impl Default for StreamingConfig {
    fn default() -> Self {
        Self {
            sse_keep_alive_secs: default_sse_keep_alive_secs(),
        }
    }
}

/// Transcoding settings read from the same YAML document as [`ProxyConfig`] by
/// [`ProxyServer::from_yaml_str`](crate::ProxyServer::from_yaml_str) and
/// [`ProxyServer::from_file`](crate::ProxyServer::from_file):
///
/// ```yaml
/// error_details:
///   enabled: true
///   opaque: false
///   routes:
///     - pattern: "/v1/admin/**"
///       enabled: false
///     - pattern: "/v1/partner/**"
///       opaque: true
/// streaming:
///   ndjson_envelope: true
/// response_headers:
///   deny: ["x-debug-trace"]
/// ```
///
/// They live outside [`ProxyConfig`] so that embedders who build it as a
/// struct literal are not affected.
#[derive(Debug, Default, Deserialize)]
pub(crate) struct TranscodeFileConfig {
    #[serde(default)]
    error_details: Option<ErrorDetailsFileConfig>,
    #[serde(default)]
    streaming: StreamingFileConfig,
    #[serde(default)]
    response_headers: Option<ResponseHeadersFileConfig>,
}

/// `response_headers:`. A typo here would silently let an internal header
/// reach clients, so unknown keys are rejected.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ResponseHeadersFileConfig {
    /// Upstream response metadata keys kept off the HTTP response.
    #[serde(default)]
    deny: Vec<String>,
}

/// `error_details:`. A typo here would silently change what clients learn
/// about server-side failures, so unknown keys are rejected.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ErrorDetailsFileConfig {
    /// Default for routes no rule matches.
    #[serde(default = "default_true")]
    enabled: bool,
    /// Default for routes no rule matches: whether details of types no
    /// descriptor describes go to `opaqueDetails` instead of being withheld.
    #[serde(default)]
    opaque: bool,
    /// Per-route overrides; for each switch, the first matching rule that
    /// sets it wins.
    #[serde(default)]
    routes: Vec<ErrorDetailsRouteFileConfig>,
}

/// A rule sets `enabled`, `opaque` or both; one setting neither is rejected.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct ErrorDetailsRouteFileConfig {
    pattern: String,
    #[serde(default)]
    enabled: Option<bool>,
    #[serde(default)]
    opaque: Option<bool>,
}

/// The `streaming:` keys [`StreamingConfig`] does not hold. Both read the same
/// section, so neither can reject the other's keys; [`unknown_config_keys`]
/// reports the keys neither reads.
#[derive(Debug, Default, Deserialize)]
struct StreamingFileConfig {
    #[serde(default)]
    ndjson_envelope: bool,
}

/// Every top-level key a config file may use: the [`ProxyConfig`] fields, the
/// transcoding settings kept outside it, and `runtime`, which the standalone
/// binary reads to build its async runtime (an embedder brings its own).
pub(crate) const KNOWN_TOP_LEVEL_KEYS: &[&str] = &[
    "upstream",
    "descriptors",
    "listen",
    "service",
    "aliases",
    "openapi",
    "auth",
    "shield",
    "oidc_discovery",
    "health",
    "metrics",
    "maintenance",
    "cors",
    "logging",
    "metrics_classes",
    "forwarded_headers",
    "streaming",
    "error_details",
    "response_headers",
    "runtime",
    "concurrency",
    "grpc_web",
    "transcode",
];

/// Every `streaming:` key: the [`StreamingConfig`] fields plus the ones
/// [`StreamingFileConfig`] reads.
pub(crate) const KNOWN_STREAMING_KEYS: &[&str] = &["sse_keep_alive_secs", "ndjson_envelope"];

/// The keys of `yaml` that no setting reads, typically typos (`error_detail:`
/// for `error_details:`) that would otherwise leave a default silently in
/// force. They are reported, not rejected, so a file that loaded before keeps
/// loading.
pub(crate) fn unknown_config_keys(yaml: &str) -> Vec<String> {
    let Ok(serde_yaml::Value::Mapping(map)) = serde_yaml::from_str(yaml) else {
        return Vec::new();
    };
    let mut unknown: Vec<String> = map
        .keys()
        .filter_map(|key| key.as_str())
        .filter(|key| !KNOWN_TOP_LEVEL_KEYS.contains(key))
        .map(str::to_owned)
        .collect();
    // `streaming:` is split between StreamingConfig and StreamingFileConfig,
    // so neither can deny unknown fields; its keys are checked here instead.
    if let Some(serde_yaml::Value::Mapping(streaming)) = map.get("streaming") {
        unknown.extend(
            streaming
                .keys()
                .filter_map(|key| key.as_str())
                .filter(|key| !KNOWN_STREAMING_KEYS.contains(key))
                .map(|key| format!("streaming.{key}")),
        );
    }
    unknown
}

impl TranscodeFileConfig {
    /// Compile into the options the transcoded routes are built with.
    ///
    /// # Errors
    ///
    /// An `error_details` route pattern that is relative or not a valid glob,
    /// a route rule that sets neither `enabled` nor `opaque`, or a
    /// `response_headers.deny` entry that is not a header name.
    pub(crate) fn options(&self) -> Result<crate::transcode::TranscodeOptions, String> {
        use crate::transcode::error::ErrorDetailsPolicy;
        let mut options = crate::transcode::TranscodeOptions::default()
            .with_ndjson_envelope(self.streaming.ndjson_envelope);
        if let Some(cfg) = &self.response_headers {
            let deny = cfg
                .deny
                .iter()
                .map(|name| {
                    http::HeaderName::from_bytes(name.as_bytes()).map_err(|_| {
                        format!("response_headers.deny entry {name:?} is not a header name")
                    })
                })
                .collect::<Result<Vec<_>, _>>()?;
            options = options.with_denied_response_headers(deny);
        }
        if let Some(cfg) = &self.error_details {
            let base = if cfg.enabled {
                ErrorDetailsPolicy::default()
            } else {
                ErrorDetailsPolicy::disabled()
            }
            .with_opaque_details(cfg.opaque);
            let policy = cfg.routes.iter().try_fold(base, |policy, rule| {
                // A rule without a switch would match routes and change
                // nothing, which is a config mistake, not an intent.
                if rule.enabled.is_none() && rule.opaque.is_none() {
                    return Err(format!(
                        "error details route {:?} sets neither enabled nor opaque",
                        rule.pattern
                    ));
                }
                policy.rule(&rule.pattern, rule.enabled, rule.opaque)
            })?;
            options = options.with_error_details(policy);
        }
        Ok(options)
    }
}

/// Upstream gRPC service configuration.
#[derive(Debug, Clone, Deserialize)]
pub struct UpstreamConfig {
    /// gRPC upstream address (e.g., "http://localhost:4180").
    pub default: String,
}

/// Descriptor loading source.
#[derive(Debug, Clone)]
pub enum DescriptorSource {
    /// Pre-compiled descriptor file.
    File { file: PathBuf },
    /// gRPC server reflection (development mode).
    Reflection { reflection: String },
    /// Embedded bytes (set programmatically, not from YAML).
    Embedded { bytes: &'static [u8] },
}

/// Helper for YAML deserialization (only File and Reflection variants).
#[derive(Debug, Clone, Deserialize)]
#[serde(untagged)]
enum DescriptorSourceYaml {
    File { file: PathBuf },
    Reflection { reflection: String },
}

impl From<DescriptorSourceYaml> for DescriptorSource {
    fn from(yaml: DescriptorSourceYaml) -> Self {
        match yaml {
            DescriptorSourceYaml::File { file } => DescriptorSource::File { file },
            DescriptorSourceYaml::Reflection { reflection } => {
                DescriptorSource::Reflection { reflection }
            }
        }
    }
}

fn deserialize_descriptor_sources<'de, D>(
    deserializer: D,
) -> std::result::Result<Vec<DescriptorSource>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let yaml_sources: Vec<DescriptorSourceYaml> = Vec::deserialize(deserializer)?;
    Ok(yaml_sources.into_iter().map(Into::into).collect())
}

/// The listener [`ProxyServer::serve`](crate::ProxyServer::serve) runs.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ListenConfig {
    /// Listen address (default: "0.0.0.0:8080").
    #[serde(default = "default_http_listen")]
    pub http: String,
    /// Most connections served at once; past it the next connection is
    /// accepted when one closes. Unset: no limit.
    #[serde(default)]
    pub max_connections: Option<usize>,
    /// TLS on the listener, mTLS with `client_ca_file`. Unset: cleartext.
    #[serde(default)]
    pub tls: Option<ListenTlsConfig>,
    /// Seconds a connection may go without a request in flight before it is
    /// closed (HTTP/2 gets a GOAWAY), so idle clients do not hold
    /// `max_connections` slots. 0 keeps idle connections open. Default: 60.
    #[serde(default = "default_idle_timeout_secs")]
    pub idle_timeout_secs: u64,
    /// Seconds an HTTP/1.1 client has to send a request's headers. At least
    /// 1. Default: 30.
    #[serde(default = "default_header_read_timeout_secs")]
    pub header_read_timeout_secs: u64,
    /// Seconds a graceful shutdown waits for open connections to finish what
    /// they serve; the ones still open after it are closed. 0 waits for all.
    /// Default: 25, below the 30 s grace period Kubernetes gives by default.
    #[serde(default = "default_drain_timeout_secs")]
    pub drain_timeout_secs: u64,
}

fn default_drain_timeout_secs() -> u64 {
    25
}

fn default_idle_timeout_secs() -> u64 {
    60
}

fn default_header_read_timeout_secs() -> u64 {
    30
}

fn default_tls_handshake_timeout_secs() -> u64 {
    10
}

/// TLS for the listener.
///
/// ```yaml
/// tls:
///   cert_file: /etc/proxy/tls.crt      # PEM chain, leaf first
///   key_file: /etc/proxy/tls.key       # PEM private key
///   client_ca_file: /etc/proxy/ca.crt  # optional: verify client certificates
///   client_auth: required              # or `optional`
/// ```
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ListenTlsConfig {
    /// The server certificate chain, PEM, leaf first.
    pub cert_file: PathBuf,
    /// The server private key, PEM (PKCS#8, PKCS#1 or SEC1).
    pub key_file: PathBuf,
    /// CA certificates, PEM, that client certificates are verified against.
    /// Unset: clients present none.
    #[serde(default)]
    pub client_ca_file: Option<PathBuf>,
    /// Whether a client must present a certificate; `required` when
    /// `client_ca_file` is set and this is not. Setting it without
    /// `client_ca_file` is an error: nothing could verify the certificate.
    #[serde(default)]
    pub client_auth: Option<ClientAuth>,
    /// Seconds a client has to finish the TLS handshake. At least 1.
    /// Default: 10.
    #[serde(default = "default_tls_handshake_timeout_secs")]
    pub handshake_timeout_secs: u64,
}

/// Whether a TLS client must present a certificate.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ClientAuth {
    /// A client without a valid certificate is refused in the handshake.
    #[default]
    Required,
    /// A certificate is verified when presented; a client may present none.
    Optional,
}

fn default_http_listen() -> String {
    "0.0.0.0:8080".into()
}

impl Default for ListenConfig {
    fn default() -> Self {
        Self {
            http: default_http_listen(),
            max_connections: None,
            tls: None,
            idle_timeout_secs: default_idle_timeout_secs(),
            header_read_timeout_secs: default_header_read_timeout_secs(),
            drain_timeout_secs: default_drain_timeout_secs(),
        }
    }
}

/// Service identity.
#[derive(Debug, Clone, Deserialize)]
pub struct ServiceConfig {
    /// Service name (appears in /health response and metrics namespace).
    #[serde(default = "default_service_name")]
    pub name: String,
}

fn default_service_name() -> String {
    "structured-proxy".into()
}

impl Default for ServiceConfig {
    fn default() -> Self {
        Self {
            name: default_service_name(),
        }
    }
}

/// Path alias (rewrite before routing).
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct AliasConfig {
    pub from: String,
    pub to: String,
}

/// OpenAPI generation config.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct OpenApiConfig {
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Path for OpenAPI JSON spec (default: "/openapi.json").
    #[serde(default = "default_openapi_path")]
    pub path: String,
    /// Path for interactive API docs UI (default: "/docs").
    #[serde(default = "default_docs_path")]
    pub docs_path: String,
    #[serde(default)]
    pub title: Option<String>,
    #[serde(default)]
    pub version: Option<String>,
}

fn default_openapi_path() -> String {
    "/openapi.json".into()
}

fn default_docs_path() -> String {
    "/docs".into()
}

fn default_true() -> bool {
    true
}

/// Auth configuration.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct AuthConfig {
    /// Auth mode: "none", "jwt", "api_key".
    #[serde(default = "default_auth_mode")]
    pub mode: String,

    /// JWT validation config.
    #[serde(default)]
    pub jwt: Option<JwtConfig>,

    /// Forward auth endpoint.
    #[serde(default)]
    pub forward_auth: Option<ForwardAuthConfig>,

    /// AuthZ integration (optional gRPC call).
    #[serde(default)]
    pub authz: Option<AuthzConfig>,

    /// The traffic JWT authentication covers. Default: `transcoded` and
    /// `endpoints`; the forward-auth endpoint is never behind it.
    #[serde(default)]
    pub scope: Option<ScopeConfig>,
}

/// The traffic a guard covers, and optionally which paths and methods of it.
///
/// ```yaml
/// scope:
///   traffic: [transcoded, grpc]   # or [all]
///   paths: ["/v1/**", "/acme.v1.Orders/*"]
///   methods: ["POST"]
/// ```
///
/// Omitted keys keep the guard's own default traffic and cover every path and
/// method of it.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ScopeConfig {
    /// The classes of traffic covered; `all` names every class.
    #[serde(default)]
    pub traffic: Option<Vec<Traffic>>,
    /// Path globs (`*` within a segment, `**` across segments) the guard is
    /// narrowed to; empty covers every path. A native gRPC call's path is
    /// `/<package>.<Service>/<Method>`.
    #[serde(default)]
    pub paths: Vec<String>,
    /// Methods the guard is narrowed to; empty covers every method. Each is a
    /// standard method or one a route answers (a `custom` rule, an extra
    /// route); a scope covering the fallback takes any method token.
    #[serde(default)]
    pub methods: Vec<String>,
}

impl ScopeConfig {
    /// A scope covering every path and method of `traffic`.
    ///
    /// # Examples
    ///
    /// ```
    /// use structured_proxy::config::{ScopeConfig, Traffic};
    ///
    /// let scope = ScopeConfig::traffic([Traffic::Transcoded, Traffic::Grpc]);
    /// assert!(scope.paths.is_empty());
    /// ```
    pub fn traffic(traffic: impl IntoIterator<Item = Traffic>) -> Self {
        Self {
            traffic: Some(traffic.into_iter().collect()),
            paths: Vec::new(),
            methods: Vec::new(),
        }
    }
}

/// A class of traffic the proxy tells apart before any guard runs.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Traffic {
    /// REST calls the proxy transcodes to gRPC.
    Transcoded,
    /// The proxy's own endpoints: health, metrics, OpenAPI, OIDC, extra
    /// routes and forward-auth.
    Endpoints,
    /// Native gRPC and gRPC-Web calls passed through to the upstream.
    Grpc,
    /// Requests no route answers, handed to the fallback.
    Fallback,
    /// Every class above.
    All,
}

/// Request concurrency limit: requests past `max_in_flight` are answered
/// `UNAVAILABLE` (503) at once instead of queueing.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ConcurrencyConfig {
    /// Most requests in flight at once, counted until each response body
    /// ends, so a stream holds its slot for its whole life. At least 1.
    pub max_in_flight: usize,
    /// The traffic the limit covers, one budget shared by all of it.
    /// Default: `transcoded` and `grpc`; the proxy's own endpoints stay out,
    /// so health probes answer while the proxy is saturated.
    #[serde(default)]
    pub scope: Option<ScopeConfig>,
}

fn default_auth_mode() -> String {
    "none".into()
}

/// JWT validation config.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct JwtConfig {
    /// JWKS URI for key discovery.
    #[serde(default)]
    pub jwks_uri: Option<String>,
    /// Age in seconds after which the JWKS keys are fetched again, so a key
    /// the provider removed stops verifying tokens. At least 60, the minimum
    /// spacing of refreshes. Default: 300.
    #[serde(default = "default_jwks_max_age_secs")]
    pub jwks_max_age_secs: u64,
    /// Expected issuer.
    #[serde(default)]
    pub issuer: Option<String>,
    /// Expected audience.
    #[serde(default)]
    pub audience: Option<String>,
    /// Path to Ed25519 public key PEM file (alternative to JWKS URI).
    #[serde(default)]
    pub public_key_pem_file: Option<PathBuf>,
    /// Claims → HTTP headers mapping.
    #[serde(default)]
    pub claims_headers: std::collections::HashMap<String, String>,
    /// Claim holding the user's roles (array of strings). Supports a dotted
    /// path for nested claims, e.g. "realm_access.roles". Default: "roles".
    #[serde(default = "default_roles_claim")]
    pub roles_claim: String,
    /// Cache of verified tokens for the built-in verifier, so a client that
    /// sends the same token on every request pays for one signature check.
    #[serde(default)]
    pub cache: JwtCacheConfig,
}

/// `auth.jwt.cache`: verified claims are reused until the earlier of the
/// token's `exp` and `max_ttl_secs` after verification. Applies to the
/// built-in verifier only; an injected `TokenVerifier` is called every time.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct JwtCacheConfig {
    /// Cache verified tokens. Default: true.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Most tokens kept at once; once full with live entries, a new token is
    /// verified but not stored. Default: 10000.
    #[serde(default = "default_jwt_cache_max_entries")]
    pub max_entries: usize,
    /// Longest time a verification is reused, in seconds. With
    /// `jwks_max_age_secs` it bounds how long a token keeps passing after its
    /// signing key leaves the JWKS. Default: 60.
    #[serde(default = "default_jwt_cache_max_ttl_secs")]
    pub max_ttl_secs: u64,
    /// Longest token cached, in bytes; a longer one is verified on every
    /// request. With `max_entries` it bounds the memory the cache holds, since
    /// the claims kept are decoded from the token. Default: 4096.
    #[serde(default = "default_jwt_cache_max_token_bytes")]
    pub max_token_bytes: usize,
}

/// Default for [`JwtConfig::jwks_max_age_secs`].
pub(crate) fn default_jwks_max_age_secs() -> u64 {
    300
}

fn default_jwt_cache_max_entries() -> usize {
    10_000
}

fn default_jwt_cache_max_ttl_secs() -> u64 {
    60
}

fn default_jwt_cache_max_token_bytes() -> usize {
    4096
}

impl Default for JwtCacheConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            max_entries: default_jwt_cache_max_entries(),
            max_ttl_secs: default_jwt_cache_max_ttl_secs(),
            max_token_bytes: default_jwt_cache_max_token_bytes(),
        }
    }
}

/// Default for [`JwtConfig::roles_claim`]. Also applied by the auth builder when
/// an injected verifier makes the whole `auth.jwt` block optional.
pub(crate) fn default_roles_claim() -> String {
    "roles".into()
}

/// Forward auth config.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct ForwardAuthConfig {
    #[serde(default)]
    pub enabled: bool,
    #[serde(default = "default_forward_auth_path")]
    pub path: String,
    /// Route policies.
    #[serde(default)]
    pub policies: Vec<RoutePolicyConfig>,
    /// Login URL for 401 redirects.
    #[serde(default)]
    pub login_url: Option<String>,
    /// Applications YAML file path.
    #[serde(default)]
    pub applications_path: Option<PathBuf>,
}

fn default_forward_auth_path() -> String {
    "/auth/verify".into()
}

/// Route policy entry.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct RoutePolicyConfig {
    pub path: String,
    #[serde(default = "default_methods_all")]
    pub methods: Vec<String>,
    #[serde(default)]
    pub require_auth: bool,
    #[serde(default)]
    pub required_roles: Vec<String>,
}

fn default_methods_all() -> Vec<String> {
    vec!["*".into()]
}

/// External authorization via the Envoy ext_authz gRPC contract
/// (`envoy.service.auth.v3.Authorization/Check`). Interops with OPA and any
/// ext_authz server.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct AuthzConfig {
    /// Enable external authorization for proxied API requests.
    #[serde(default)]
    pub enabled: bool,
    /// gRPC address of the ext_authz server, e.g. `http://opa:9191`. Required
    /// when enabled; defaults to empty so a disabled block can omit it.
    #[serde(default)]
    pub endpoint: String,
    /// Per-request authorization call timeout, in milliseconds.
    #[serde(default = "default_authz_timeout_ms")]
    pub timeout_ms: u64,
    /// When the authz call itself fails (unreachable / timeout), allow the
    /// request through instead of denying. Defaults to false (fail closed).
    #[serde(default)]
    pub failure_mode_allow: bool,
    /// The traffic the check covers. Default: `transcoded`.
    #[serde(default)]
    pub scope: Option<ScopeConfig>,
}

fn default_authz_timeout_ms() -> u64 {
    200
}

/// Shield (rate limiting) configuration.
///
/// The proxy runs embedded on each service instance, so every limit decision is
/// made locally with a GCRA shaper (zero blocking latency). A shared store, when
/// configured via [`sync`](ShieldConfig::sync), is reconciled asynchronously off
/// the request path to approximate a fleet-wide limit; the request path never
/// blocks on it.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct ShieldConfig {
    #[serde(default)]
    pub enabled: bool,
    /// Named limit tiers referenced by rules and by tier-name resolution (JWT
    /// claim / limit service). Map of profile name → `{ rate, burst }`.
    #[serde(default)]
    pub profiles: std::collections::HashMap<String, LimitProfileConfig>,
    /// Rate-limit rules, evaluated in order; the first whose pattern matches the
    /// request path applies.
    #[serde(default)]
    pub rules: Vec<RateRuleConfig>,
    /// Profile name applied when a matched rule resolves no other limit (JWT and
    /// service resolution absent or empty, and the rule sets no explicit
    /// profile). Must name an entry in `profiles`.
    #[serde(default)]
    pub default_profile: Option<String>,
    /// Resolve a key's limit from claims in the validated JWT. Presence enables
    /// JWT-based resolution (tier name or explicit numbers).
    #[serde(default)]
    pub jwt_limits: Option<JwtLimitConfig>,
    /// Resolve a key's limit from an external service. The lookup is cached and
    /// refreshed in the background; the request path never blocks on it.
    #[serde(default)]
    pub limit_service: Option<LimitServiceConfig>,
    /// Asynchronous cross-instance reconciliation via a shared store. When unset,
    /// each instance limits locally (fleet limit ≈ N × per-instance).
    #[serde(default)]
    pub sync: Option<SyncConfig>,
    /// CIDR ranges of trusted reverse proxies / load balancers (e.g.
    /// "10.0.0.0/8"). `X-Forwarded-For` / `X-Real-IP` are honored only when the
    /// direct peer falls in one of these ranges; otherwise the peer socket
    /// address is used as the client identity. Empty (the default) means do not
    /// trust forwarding headers; set this behind a load balancer.
    #[serde(default)]
    pub trusted_proxies: Vec<String>,
    /// The traffic the rules apply to. Default: `transcoded` and `endpoints`.
    #[serde(default)]
    pub scope: Option<ScopeConfig>,
}

/// A named limit tier: a sustained rate plus an instantaneous burst capacity.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct LimitProfileConfig {
    /// Sustained rate as `"<count>/<unit>"` (e.g. `"100/min"`, units
    /// `s`/`min`/`hour`) or a bare count (interpreted per minute).
    pub rate: String,
    /// Maximum requests admitted back-to-back before throttling to the rate.
    /// Defaults to the per-window rate count (one full window of burst).
    #[serde(default)]
    pub burst: Option<u64>,
}

/// One rate-limit rule: a path pattern, how to key it, and an optional static
/// profile. The rule's *phase* (before or after auth) is derived from its key
/// alone: a `jwt_claim` key needs validated claims so it runs after auth; `ip`
/// and `header` keys run before auth so anonymous floods are shed before any
/// signature verification. (`jwt_limits` therefore only takes effect on
/// `jwt_claim` rules, the only ones running with claims available.)
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct RateRuleConfig {
    /// Glob path pattern (`*` within a segment, `**` across segments).
    pub pattern: String,
    /// How to derive the limit key (who is limited). Defaults to client IP.
    #[serde(default)]
    pub key: KeySourceConfig,
    /// Static profile name for this rule, used when JWT/service resolution does
    /// not apply or yields nothing. Must name an entry in `profiles`.
    #[serde(default)]
    pub profile: Option<String>,
}

/// How a rule derives its limit key. All sources fall back to the client IP when
/// their value is absent, so a limit can't be bypassed by omitting a header or
/// authenticating anonymously. Written as a tagged map, e.g.
/// `key: { type: jwt_claim, claim: sub }`; omitting `key` defaults to `ip`.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[non_exhaustive]
pub enum KeySourceConfig {
    /// Client IP (trusted-proxy `X-Forwarded-For` aware). `{ type: ip }`.
    #[default]
    Ip,
    /// Value of a named request header (e.g. an API key).
    /// `{ type: header, name: x-api-key }`.
    Header {
        /// Header whose value identifies the client.
        name: String,
    },
    /// Value of a claim from the validated JWT (provider-agnostic).
    /// `{ type: jwt_claim, claim: sub }`.
    JwtClaim {
        /// Claim whose value identifies the principal.
        claim: String,
    },
}

/// Flat wire form of a rule key. `deny_unknown_fields` rejects any field outside
/// this set, and the manual [`KeySourceConfig`] deserializer additionally rejects
/// a field that belongs to a *different* variant (e.g. `name` on an `ip` key), so
/// a copy-edit leftover can't silently downgrade the intended key source. serde
/// does not honour `deny_unknown_fields` on internally-tagged enums directly,
/// hence this intermediate.
#[derive(Deserialize)]
#[serde(deny_unknown_fields, rename_all = "snake_case")]
struct KeySourceRaw {
    #[serde(rename = "type")]
    kind: String,
    #[serde(default)]
    name: Option<String>,
    #[serde(default)]
    claim: Option<String>,
}

impl<'de> Deserialize<'de> for KeySourceConfig {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        use serde::de::Error;
        let raw = KeySourceRaw::deserialize(deserializer)?;
        match raw.kind.as_str() {
            "ip" => {
                if raw.name.is_some() || raw.claim.is_some() {
                    return Err(D::Error::custom("key type 'ip' takes no other fields"));
                }
                Ok(Self::Ip)
            }
            "header" => {
                if raw.claim.is_some() {
                    return Err(D::Error::custom(
                        "key type 'header' takes 'name', not 'claim'",
                    ));
                }
                let name = raw.name.ok_or_else(|| D::Error::missing_field("name"))?;
                Ok(Self::Header { name })
            }
            "jwt_claim" => {
                if raw.name.is_some() {
                    return Err(D::Error::custom(
                        "key type 'jwt_claim' takes 'claim', not 'name'",
                    ));
                }
                let claim = raw.claim.ok_or_else(|| D::Error::missing_field("claim"))?;
                Ok(Self::JwtClaim { claim })
            }
            other => Err(D::Error::unknown_variant(
                other,
                &["ip", "header", "jwt_claim"],
            )),
        }
    }
}

/// Claims that carry a key's limit inside the JWT itself. A tier-name claim maps
/// to a `profiles` entry (numbers stay tunable in config); direct numeric claims
/// set the limit explicitly.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct JwtLimitConfig {
    /// Claim naming a profile tier (e.g. `"premium"`). Default: `ratelimit_tier`.
    #[serde(default = "default_tier_claim")]
    pub tier_claim: String,
    /// Claim carrying an explicit sustained rate, requests per minute. Default:
    /// `ratelimit_rpm`.
    #[serde(default = "default_rpm_claim")]
    pub rpm_claim: String,
    /// Claim carrying an explicit burst capacity. Default: `ratelimit_burst`.
    #[serde(default = "default_burst_claim")]
    pub burst_claim: String,
}

fn default_tier_claim() -> String {
    "ratelimit_tier".to_string()
}
fn default_rpm_claim() -> String {
    "ratelimit_rpm".to_string()
}
fn default_burst_claim() -> String {
    "ratelimit_burst".to_string()
}

/// External limit-resolution service. The response names a tier or gives explicit
/// numbers; results are cached and refreshed asynchronously, never on the request
/// path.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct LimitServiceConfig {
    /// HTTP endpoint queried with the limit key; returns `{ tier }` or
    /// `{ rate_per_min, burst }`.
    pub endpoint: String,
    /// How long a resolved limit is cached before a background refresh, in
    /// seconds (default: 300).
    #[serde(default = "default_limit_ttl_secs")]
    pub ttl_secs: u64,
    /// Timeout for the background fetch, in milliseconds (default: 500).
    #[serde(default = "default_limit_timeout_ms")]
    pub timeout_ms: u64,
}

fn default_limit_ttl_secs() -> u64 {
    300
}
fn default_limit_timeout_ms() -> u64 {
    500
}

/// Asynchronous cross-instance reconciliation via a shared store.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct SyncConfig {
    /// Shared-store URL (e.g. `"redis://127.0.0.1/"`). Requires the `redis` build
    /// feature; without it the proxy logs a warning and stays local-only.
    pub redis_url: String,
    /// Background push/pull interval in milliseconds (default: 500). The
    /// worst-case fleet overshoot is bounded by `(N-1) × rate × interval`.
    #[serde(default = "default_sync_interval_ms")]
    pub interval_ms: u64,
}

fn default_sync_interval_ms() -> u64 {
    500
}

/// OIDC discovery config.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct OidcDiscoveryConfig {
    #[serde(default)]
    pub enabled: bool,
    pub issuer: String,
    #[serde(default)]
    pub authorization_endpoint: Option<String>,
    #[serde(default)]
    pub token_endpoint: Option<String>,
    #[serde(default)]
    pub userinfo_endpoint: Option<String>,
    #[serde(default)]
    pub jwks_uri: Option<String>,
    #[serde(default)]
    pub signing_key: Option<SigningKeyConfig>,
}

/// Signing key config for JWKS endpoint.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct SigningKeyConfig {
    #[serde(default = "default_algorithm")]
    pub algorithm: String,
    pub public_key_pem_file: PathBuf,
}

fn default_algorithm() -> String {
    "EdDSA".into()
}

/// Health-probe endpoint configuration.
///
/// Paths are configurable so an embedder can relocate the probes (e.g. behind a
/// `/internal/` prefix) or disable them when a fronting platform supplies its
/// own. Defaults match the conventional `/health*` layout.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct HealthConfig {
    /// Mount the health endpoints. Default: true.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Aggregate health endpoint. Default: `/health`.
    #[serde(default = "default_health_path")]
    pub path: String,
    /// Liveness probe. Default: `/health/live`.
    #[serde(default = "default_health_live_path")]
    pub live_path: String,
    /// Readiness probe (checks the upstream gRPC health). Default: `/health/ready`.
    #[serde(default = "default_health_ready_path")]
    pub ready_path: String,
    /// Startup probe. Default: `/health/startup`.
    #[serde(default = "default_health_startup_path")]
    pub startup_path: String,
}

fn default_health_path() -> String {
    "/health".into()
}
fn default_health_live_path() -> String {
    "/health/live".into()
}
fn default_health_ready_path() -> String {
    "/health/ready".into()
}
fn default_health_startup_path() -> String {
    "/health/startup".into()
}

impl Default for HealthConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            path: default_health_path(),
            live_path: default_health_live_path(),
            ready_path: default_health_ready_path(),
            startup_path: default_health_startup_path(),
        }
    }
}

/// Prometheus metrics endpoint configuration.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct MetricsConfig {
    /// Mount the metrics endpoint. Default: true.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Scrape path. Default: `/metrics`.
    #[serde(default = "default_metrics_path")]
    pub path: String,
}

fn default_metrics_path() -> String {
    "/metrics".into()
}

impl Default for MetricsConfig {
    fn default() -> Self {
        Self {
            enabled: true,
            path: default_metrics_path(),
        }
    }
}

/// Maintenance mode config.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct MaintenanceConfig {
    #[serde(default)]
    pub enabled: bool,
    /// Paths exempt from maintenance mode (glob patterns).
    #[serde(default = "default_exempt_paths")]
    pub exempt_paths: Vec<String>,
    #[serde(default = "default_maintenance_message")]
    pub message: String,
    /// The traffic maintenance mode turns away. Default: `transcoded` and
    /// `endpoints`.
    #[serde(default)]
    pub scope: Option<ScopeConfig>,
}

fn default_exempt_paths() -> Vec<String> {
    vec![
        "/health/**".into(),
        "/.well-known/**".into(),
        "/metrics".into(),
        "/auth/verify".into(),
    ]
}

fn default_maintenance_message() -> String {
    "Service is under maintenance. Please try again later.".into()
}

impl Default for MaintenanceConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            exempt_paths: default_exempt_paths(),
            message: default_maintenance_message(),
            scope: None,
        }
    }
}

/// CORS configuration.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct CorsConfig {
    /// Allowed origins. Empty = permissive (dev mode).
    #[serde(default)]
    pub origins: Vec<String>,
    /// Response headers a browser script may read on top of the ones the
    /// proxy always exposes (`grpc-status`, `grpc-message`,
    /// `grpc-status-details-bin` and the rate-limit headers): typically
    /// upstream metadata forwarded as a header, such as `x-request-id`.
    #[serde(default)]
    pub expose_headers: Vec<String>,
    /// How long a browser may cache a preflight answer, in seconds. Unset,
    /// the browser's own default applies.
    #[serde(default)]
    pub max_age_secs: Option<u64>,
    /// Apply this policy to gRPC-Web calls that pass through to the upstream
    /// and to their preflights, so a browser gets one policy for both (on by
    /// default). Off only for an upstream that sets CORS on gRPC-Web itself:
    /// its preflights then reach the upstream as well.
    #[serde(default = "default_true")]
    pub grpc_web: bool,
}

impl Default for CorsConfig {
    fn default() -> Self {
        Self {
            origins: Vec::new(),
            expose_headers: Vec::new(),
            max_age_secs: None,
            grpc_web: true,
        }
    }
}

/// Logging configuration.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct LoggingConfig {
    #[serde(default = "default_log_level")]
    pub level: String,
    #[serde(default = "default_log_format")]
    pub format: String,
}

fn default_log_level() -> String {
    "info".into()
}
fn default_log_format() -> String {
    "json".into()
}

impl Default for LoggingConfig {
    fn default() -> Self {
        Self {
            level: default_log_level(),
            format: default_log_format(),
        }
    }
}

/// Metrics endpoint classification.
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
pub struct MetricsClassConfig {
    /// Glob pattern for path matching.
    pub pattern: String,
    /// Label value for this class.
    pub class: String,
}

impl ProxyConfig {
    /// Load configuration from a YAML file.
    pub fn from_file(path: &std::path::Path) -> anyhow::Result<Self> {
        Self::from_yaml_str(&std::fs::read_to_string(path)?)
    }

    /// Parse configuration from a YAML string.
    ///
    /// Useful for embedding the proxy: load a baked-in config (e.g. via
    /// `include_str!`) without touching the filesystem.
    pub fn from_yaml_str(yaml: &str) -> anyhow::Result<Self> {
        let config: Self = serde_yaml::from_str(yaml)?;
        config.validate()?;
        Ok(config)
    }

    /// Validate cross-field constraints that the type system can't express.
    ///
    /// Called automatically by [`from_yaml_str`](Self::from_yaml_str); call it
    /// directly when building a [`ProxyConfig`] programmatically so the same
    /// invariants are enforced on the embedded path.
    pub fn validate(&self) -> anyhow::Result<()> {
        if self.streaming.sse_keep_alive_secs == 0 {
            anyhow::bail!("streaming.sse_keep_alive_secs must be greater than 0");
        }
        if self.grpc_web.translate && !self.cors.grpc_web {
            anyhow::bail!(
                "grpc_web.translate needs cors.grpc_web: an upstream that speaks only \
                 gRPC cannot answer a browser's preflight for a gRPC-Web call"
            );
        }
        self.validate_edge_paths()?;
        Ok(())
    }

    /// Reject malformed or duplicate built-in edge paths up front, so the router
    /// does not panic at construction (axum rejects a route that does not start
    /// with `/`, and panics on a path registered twice, e.g. setting
    /// `health.path` to the default `live_path`).
    fn validate_edge_paths(&self) -> anyhow::Result<()> {
        let mut seen = std::collections::HashSet::new();
        let mut check = |label: &str, path: &str| -> anyhow::Result<()> {
            if !path.starts_with('/') {
                anyhow::bail!("endpoint path {path:?} ({label}) must start with '/'");
            }
            if !seen.insert(path.to_string()) {
                anyhow::bail!("duplicate endpoint path {path:?} ({label}); each built-in endpoint must have a distinct path");
            }
            Ok(())
        };
        if self.health.enabled {
            check("health.path", &self.health.path)?;
            check("health.live_path", &self.health.live_path)?;
            check("health.ready_path", &self.health.ready_path)?;
            check("health.startup_path", &self.health.startup_path)?;
        }
        if self.metrics.enabled {
            check("metrics.path", &self.metrics.path)?;
        }
        if let Some(openapi) = self.openapi.as_ref().filter(|o| o.enabled) {
            check("openapi.path", &openapi.path)?;
            check("openapi.docs_path", &openapi.docs_path)?;
        }
        Ok(())
    }

    /// Parse rate string like "20/min" → requests per window.
    pub fn parse_rate(rate: &str) -> Option<u32> {
        let parts: Vec<&str> = rate.split('/').collect();
        if parts.len() != 2 {
            return None;
        }
        parts[0].trim().parse().ok()
    }
}

#[cfg(test)]
mod tests;