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).
///
/// Every config type is `#[non_exhaustive]`, so a new setting is not a
/// breaking change. Build one in code from its `Default` (or its constructor
/// when a field has no default) and set the fields you need, or use the
/// `ProxyServer::with_*` builder methods.
///
/// # Examples
///
/// ```
/// use structured_proxy::config::{DescriptorSource, ProxyConfig, UpstreamConfig};
///
/// static DESCRIPTORS: &[u8] = &[];
/// let mut config = ProxyConfig::default();
/// config.upstream = Some(UpstreamConfig::new("http://127.0.0.1:50051"));
/// config.descriptors = vec![DescriptorSource::Embedded { bytes: DESCRIPTORS }];
/// config.service.name = "embedded".into();
/// config.validate().unwrap();
/// ```
#[derive(Debug, Clone, Deserialize)]
#[non_exhaustive]
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. `x-forwarded-for`,
    /// `x-real-ip`, `forwarded` and the headers named in
    /// `client_address.forward` carry what that forwarding policy wrote,
    /// listed or not.
    #[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,

    /// How the client's address is resolved: the proxies trusted to report
    /// it, and the header they report it in.
    #[serde(default)]
    pub client_address: ClientAddressConfig,
}

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(),
            client_address: ClientAddressConfig::default(),
        }
    }
}

/// How the client's address is resolved, for every consumer of it at once
/// (the rate limits, the hooks, the fallback, the upstream), and what the
/// upstream receives of it.
///
/// ```yaml
/// client_address:
///   trusted_proxies: ["10.0.0.0/8", "192.0.2.10"]
///   header: x_forwarded_for
///   required: false
///   forward:
///     x_forwarded_for: verified
///     client_header: x-real-ip
///     audit_header: null
/// ```
///
/// The connection's peer is the client unless it is a trusted proxy; only
/// then is `header` read, so an address a client asserts itself never
/// counts. The defaults trust no proxy: the right setting for a proxy that
/// faces its clients directly. Resolution and [`forward`](Self::forward) are
/// independent: the rate limits and the hooks always use the resolved
/// address, whatever is forwarded.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct ClientAddressConfig {
    /// Proxies trusted to report the client's address: CIDR ranges, or bare
    /// addresses for one host. An IPv4-mapped IPv6 peer (`::ffff:10.0.0.1`)
    /// matches its IPv4 range. An entry that is neither stops the proxy at
    /// startup.
    #[serde(default)]
    pub trusted_proxies: Vec<String>,
    /// The header trusted proxies report the client's address in.
    #[serde(default)]
    pub header: ForwardingHeader,
    /// Refuse a request whose client address cannot be resolved: no
    /// connection information (`INTERNAL`, 500), or a trusted proxy's report
    /// that cannot be read (`INVALID_ARGUMENT`, 400). Off: such a request
    /// goes on with no address.
    #[serde(default)]
    pub required: bool,
    /// What the upstream receives of the client's address.
    #[serde(default)]
    pub forward: ForwardConfig,
}

/// What the upstream (and the fallback) receives of the client's address.
///
/// The defaults give an upstream nothing a client can forge: a verified
/// `X-Forwarded-For` whose first element is the client, and the address in
/// `X-Real-IP`. Every header named here is written by the proxy alone; a
/// guard (JWT claim headers, ext_authz, the auth decider) cannot set it.
///
/// | Behind | Setting |
/// |---|---|
/// | nginx, `$proxy_add_x_forwarded_for` and `X-Real-IP` | `x_forwarded_for: append`, `client_header: x-real-ip` |
/// | Envoy, `use_remote_address` | `append`, `client_header: x-envoy-external-address` |
/// | HAProxy, `option forwardfor` | `append` |
/// | AWS ALB `append` / `preserve` / `remove` | the mode of the same name |
/// | Cloudflare | `append`, `client_header: cf-connecting-ip` |
/// | Traefik, Caddy | `verified` (stricter), or `append` |
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
pub struct ForwardConfig {
    /// What `X-Forwarded-For` carries upstream.
    #[serde(default)]
    pub x_forwarded_for: XForwardedFor,
    /// The header the resolved address is written to, replacing any value
    /// the request carried; absent when no address resolved. `None` (`null`
    /// in YAML) writes none. A text gRPC metadata key (not ending in `-bin`)
    /// other than `x-forwarded-for` and `forwarded`. Default: `x-real-ip`.
    #[serde(default = "default_client_header")]
    pub client_header: Option<String>,
    /// A header receiving the `X-Forwarded-For` field lines exactly as the
    /// request carried them, before any change: for logs and audits only,
    /// since nothing in it is verified. Off by default. A text gRPC metadata
    /// key (not ending in `-bin`) other than `x-forwarded-for`, `x-real-ip`,
    /// `forwarded` and `client_header`, e.g. `x-original-forwarded-for`.
    #[serde(default)]
    pub audit_header: Option<String>,
}

fn default_client_header() -> Option<String> {
    Some("x-real-ip".into())
}

impl Default for ForwardConfig {
    fn default() -> Self {
        Self {
            x_forwarded_for: XForwardedFor::default(),
            client_header: default_client_header(),
            audit_header: None,
        }
    }
}

/// What `X-Forwarded-For` carries upstream. `X-Real-IP` and `Forwarded`
/// (RFC 7239) from the request reach the upstream only with `preserve`; in
/// every other mode they are removed, since they would contradict it.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum XForwardedFor {
    /// The verified part of the chain: the resolved client, the trusted
    /// proxies between it and this proxy, then this proxy's peer
    /// (`203.0.113.7, 10.0.0.2, 10.0.0.1`). Whatever the client wrote left of
    /// its own address is dropped, so the first element is always the
    /// client, and an upstream walking the list from the right reaches the
    /// same client. Absent when no address resolved.
    #[default]
    Verified,
    /// The resolved address alone; absent when none resolved.
    Resolved,
    /// The request's list as it arrived, then this proxy's peer, as nginx,
    /// Envoy, HAProxy and most load balancers append. Its first element is
    /// whatever the client wrote.
    Append,
    /// The request's `X-Forwarded-For`, `X-Real-IP` and `Forwarded` as they
    /// arrived, nothing added. Its first element is whatever the client
    /// wrote.
    Preserve,
    /// No `X-Forwarded-For`.
    Remove,
}

/// The header trusted proxies report the client's address in.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum ForwardingHeader {
    /// `X-Forwarded-For`, every field line in order, read right to left
    /// through the trusted proxies to the first address outside them.
    #[default]
    XForwardedFor,
    /// `X-Real-IP`: one address, the trusted proxy's own peer.
    XRealIp,
}

/// Which annotated RPCs are transcoded.
///
/// ```yaml
/// transcode:
///   only: ["acme.v1.Orders", "acme.v1.Users/GetUser"]
/// ```
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
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(parse_yaml(yaml)?)
}

/// The YAML reader of every config path, with the YAML 1.2 core schema's
/// types: a boolean is `true` or `false` in any letter case (`True`, `TRUE`),
/// while `yes`, `no`, `on` and `off` are refused; an unquoted number or
/// boolean where text is expected is an error, not the text it spells, so
/// `name: true` does not start a service called "true". Errors stay on one
/// line, without a snippet of the document, so a log record holds the whole
/// message.
pub(crate) fn parse_yaml<T: serde::de::DeserializeOwned>(yaml: &str) -> Result<T, YamlError> {
    let mut path = None;
    serde_saphyr::with_deserializer_from_str_with_options(
        yaml,
        serde_saphyr::options! {
            // Matches `true`/`false` ignoring case, the core schema's spellings.
            strict_booleans: true,
            no_schema: true,
            with_snippet: false,
        },
        |de| {
            serde_path_to_error::deserialize(de).map_err(|e| {
                if e.path().iter().next().is_some() {
                    path = Some(e.path().to_string());
                }
                e.into_inner()
            })
        },
    )
    .map_err(|e| {
        YamlError(match path {
            Some(path) => format!("{path}: {e}"),
            // The document as a whole is at fault (not YAML, not a map).
            None => e.to_string(),
        })
    })
}

/// A YAML document that does not read as the config it should be, naming the
/// key at fault the way the document spells its path (`runtime.worker_threads`).
#[derive(Debug, thiserror::Error)]
#[error("{0}")]
pub(crate) struct YamlError(String);

/// How gRPC-Web calls reach the upstream.
#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields)]
#[non_exhaustive]
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-proto".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)]
#[non_exhaustive]
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",
    "client_address",
];

/// 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(ConfigKeys { top, streaming }) = parse_yaml(yaml) else {
        return Vec::new();
    };
    let mut unknown: Vec<String> = top
        .into_iter()
        .filter(|key| !KNOWN_TOP_LEVEL_KEYS.contains(&key.as_str()))
        .collect();
    // `streaming:` is split between StreamingConfig and StreamingFileConfig,
    // so neither can deny unknown fields; its keys are checked here instead.
    unknown.extend(
        streaming
            .iter()
            .filter(|key| !KNOWN_STREAMING_KEYS.contains(&key.as_str()))
            .map(|key| format!("streaming.{key}")),
    );
    unknown
}

/// The keys of a config document in their order: the top-level ones and those
/// of `streaming:`. A document that is empty or not a map has none.
#[derive(Default)]
struct ConfigKeys {
    top: Vec<String>,
    streaming: Vec<String>,
}

impl<'de> Deserialize<'de> for ConfigKeys {
    fn deserialize<D: serde::Deserializer<'de>>(de: D) -> Result<Self, D::Error> {
        struct Visitor;
        impl<'de> serde::de::Visitor<'de> for Visitor {
            type Value = ConfigKeys;
            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("a config map")
            }
            fn visit_unit<E>(self) -> Result<ConfigKeys, E> {
                Ok(ConfigKeys::default())
            }
            fn visit_none<E>(self) -> Result<ConfigKeys, E> {
                Ok(ConfigKeys::default())
            }
            fn visit_map<A: serde::de::MapAccess<'de>>(
                self,
                mut map: A,
            ) -> Result<ConfigKeys, A::Error> {
                let mut keys = ConfigKeys::default();
                while let Some(TextKey(key)) = map.next_key()? {
                    match key {
                        Some(key) if key == "streaming" => {
                            keys.streaming = map.next_value::<MapKeys>()?.0;
                            keys.top.push(key);
                        }
                        Some(key) => {
                            map.next_value::<serde::de::IgnoredAny>()?;
                            keys.top.push(key);
                        }
                        None => {
                            map.next_value::<serde::de::IgnoredAny>()?;
                        }
                    }
                }
                Ok(keys)
            }
        }
        de.deserialize_any(Visitor)
    }
}

/// The keys of a map in their order; an empty value has none.
struct MapKeys(Vec<String>);

impl<'de> Deserialize<'de> for MapKeys {
    fn deserialize<D: serde::Deserializer<'de>>(de: D) -> Result<Self, D::Error> {
        struct Visitor;
        impl<'de> serde::de::Visitor<'de> for Visitor {
            type Value = MapKeys;
            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("a map")
            }
            fn visit_unit<E>(self) -> Result<MapKeys, E> {
                Ok(MapKeys(Vec::new()))
            }
            fn visit_none<E>(self) -> Result<MapKeys, E> {
                Ok(MapKeys(Vec::new()))
            }
            fn visit_map<A: serde::de::MapAccess<'de>>(
                self,
                mut map: A,
            ) -> Result<MapKeys, A::Error> {
                let mut keys = Vec::new();
                while let Some(TextKey(key)) = map.next_key()? {
                    map.next_value::<serde::de::IgnoredAny>()?;
                    keys.extend(key);
                }
                Ok(MapKeys(keys))
            }
        }
        de.deserialize_any(Visitor)
    }
}

/// A map key as text; `None` for a key that is a number or a boolean, which
/// no setting is named by and which the reader refuses to take for text.
struct TextKey(Option<String>);

impl<'de> Deserialize<'de> for TextKey {
    fn deserialize<D: serde::Deserializer<'de>>(de: D) -> Result<Self, D::Error> {
        struct Visitor;
        impl serde::de::Visitor<'_> for Visitor {
            type Value = TextKey;
            fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                f.write_str("a scalar key")
            }
            fn visit_str<E>(self, key: &str) -> Result<TextKey, E> {
                Ok(TextKey(Some(key.to_owned())))
            }
            fn visit_string<E>(self, key: String) -> Result<TextKey, E> {
                Ok(TextKey(Some(key)))
            }
            fn visit_bool<E>(self, _: bool) -> Result<TextKey, E> {
                Ok(TextKey(None))
            }
            fn visit_i64<E>(self, _: i64) -> Result<TextKey, E> {
                Ok(TextKey(None))
            }
            fn visit_u64<E>(self, _: u64) -> Result<TextKey, E> {
                Ok(TextKey(None))
            }
            fn visit_f64<E>(self, _: f64) -> Result<TextKey, E> {
                Ok(TextKey(None))
            }
        }
        de.deserialize_any(Visitor)
    }
}

/// The error for a config that sets `shield.trusted_proxies`, which became
/// `client_address.trusted_proxies`: the parse error alone would name an
/// unknown field, not where its value belongs now.
fn moved_setting(yaml: &str) -> Option<anyhow::Error> {
    /// The settings that moved, each `true` when the document names it.
    #[derive(Deserialize)]
    struct Moved {
        #[serde(default)]
        shield: Option<MovedFromShield>,
    }
    #[derive(Deserialize)]
    struct MovedFromShield {
        #[serde(default, deserialize_with = "named")]
        trusted_proxies: bool,
    }
    /// A key that is present, whatever its value, even `null`.
    fn named<'de, D: serde::Deserializer<'de>>(de: D) -> Result<bool, D::Error> {
        serde::de::IgnoredAny::deserialize(de).map(|_| true)
    }

    let moved: Moved = parse_yaml(yaml).ok()?;
    moved.shield?.trusted_proxies.then(|| {
        anyhow::anyhow!(
            "shield.trusted_proxies is now client_address.trusted_proxies: the client \
             address is resolved once for the rate limits, the hooks and the upstream"
        )
    })
}

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)]
#[non_exhaustive]
pub struct UpstreamConfig {
    /// gRPC upstream address (e.g., "http://localhost:4180").
    pub default: String,
}

impl UpstreamConfig {
    /// The upstream at `address` (e.g. `http://localhost:4180`).
    pub fn new(address: impl Into<String>) -> Self {
        Self {
            default: address.into(),
        }
    }
}

/// Descriptor loading source.
#[derive(Debug, Clone)]
#[non_exhaustive]
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)]
#[non_exhaustive]
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)]
#[non_exhaustive]
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,
}

impl ListenTlsConfig {
    /// TLS with the certificate chain and private key in these PEM files, no
    /// client certificates, and the default handshake timeout.
    pub fn new(cert_file: impl Into<PathBuf>, key_file: impl Into<PathBuf>) -> Self {
        Self {
            cert_file: cert_file.into(),
            key_file: key_file.into(),
            client_ca_file: None,
            client_auth: None,
            handshake_timeout_secs: default_tls_handshake_timeout_secs(),
        }
    }
}

/// Whether a TLS client must present a certificate.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
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)]
#[non_exhaustive]
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,
}

impl AliasConfig {
    /// Serve the routes under `to` at `from` as well, e.g. `/oauth2/{path}`
    /// for `/v1/oauth2/{path}`.
    pub fn new(from: impl Into<String>, to: impl Into<String>) -> Self {
        Self {
            from: from.into(),
            to: to.into(),
        }
    }
}

/// 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)]
#[non_exhaustive]
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")]
#[non_exhaustive]
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)]
#[non_exhaustive]
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>,
}

impl ConcurrencyConfig {
    /// At most `max_in_flight` requests at once, over the default traffic.
    pub fn new(max_in_flight: usize) -> Self {
        Self {
            max_in_flight,
            scope: None,
        }
    }

    /// The same limit over the traffic `scope` names.
    #[must_use]
    pub fn with_scope(mut self, scope: ScopeConfig) -> Self {
        self.scope = Some(scope);
        self
    }
}

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>,
    /// 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 {
    /// The client address the proxy resolved (see
    /// [`ClientAddressConfig`]). `{ 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 = match parse_yaml(yaml) {
            Ok(config) => config,
            Err(error) => return Err(moved_setting(yaml).map_or_else(|| error.into(), Into::into)),
        };
        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"
            );
        }
        crate::client_address::Resolver::build(&self.client_address)
            .map_err(|e| anyhow::anyhow!("invalid client_address config: {e}"))?;
        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;