dwara_core/config/

mod.rs

//! Configuration schema v1 for the gateway (frozen domain vocabulary).
//!
//! The types in this module model the source form of a dwara configuration
//! file. Compilation into a runtime snapshot is a later concern
//! (config-compile pipeline); here we define strict, self-describing types:
//!
//! - every struct rejects unknown fields (`deny_unknown_fields`),
//! - field order follows declaration order on serialization,
//! - the root type [`Gateway`] exports a JSON Schema via `schemars`.
//!
//! YAML <-> typed conversions are provided by [`parse_gateway`] (YAML text to
//! typed value, with path-precise error messages) and [`gateway_to_yaml`]
//! (typed value back to normalized YAML text). Round-trip guarantee:
//! `parse_gateway(gateway_to_yaml(cfg))` always succeeds and yields a value
//! that serializes to the identical normalized text (stable normalization,
//! not byte-identity with the original input).
//!
//! Submodules carry the parts of the config CONTRACT that are more than
//! serde shapes: [`credentials`] defines the credential selector/stored-hash
//! formats every credential holder must agree on plus the `${...}`
//! secret-reference grammar (DW-045), [`limits`] the numeric
//! bounds validation enforces, [`net`] the trusted-proxy IP/CIDR
//! grammar shared by validation and the runtime matchers,
//! [`versioning`] the HTTP-date and media-type grammar of the API
//! versioning aids (DW-048), and [`transforms`] the JSON-pointer
//! grammar and shapes of the request/response transforms and
//! security-header injection (DW-028). [`cache`] carries the
//! route-scoped response-caching grammar (DW-037), and [`ai`] the
//! AI provider/model grammar of the provider-adapter pack (DW-075).

pub mod ai;
pub mod cache;
pub mod credentials;
pub mod includes;
pub mod limits;
pub mod mesh;
pub mod net;
pub mod quotas;
pub mod ssrf;
pub mod transforms;
pub mod versioning;

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

use cache::RouteCache;
use transforms::{Masking, SecurityHeaders, Transforms};

/// Error produced when a configuration document fails to parse.
///
/// Carries the dotted path of the offending node (e.g. `listeners[0].port`)
/// and the underlying serde message.
#[derive(Debug)]
pub struct ConfigError {
    pub path: String,
    pub message: String,
}

impl std::fmt::Display for ConfigError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "config error at {}: {}", self.path, self.message)
    }
}

impl std::error::Error for ConfigError {}

/// CFG-03 (#239): the current config schema version. Increment when
/// the schema gains a breaking change (removed fields, renamed
/// fields, changed semantics). The `dwara lint` command warns when a
/// config's `version` is older than this; `dwara migrate` upgrades
/// configs to this version.
pub const CURRENT_CONFIG_VERSION: u32 = 1;

/// Default config version (assumed when `version` is absent from the
/// YAML). The initial schema is version 1.
fn default_config_version() -> u32 {
    1
}

/// Whether the config version is the default (1). Used by
/// `skip_serializing_if` to omit the field when it's the default.
fn is_default_config_version(v: &u32) -> bool {
    *v == 1
}

/// Root of a dwara configuration: one gateway process, N listeners, and one
/// compiled config generation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Gateway {
    /// CFG-03 (#239): config schema version. Defaults to 1 when
    /// absent (the initial schema). The `dwara lint` command warns
    /// when the version is older than the current schema version; the
    /// `dwara migrate` command upgrades the config to the current
    /// version.
    #[serde(
        default = "default_config_version",
        skip_serializing_if = "is_default_config_version"
    )]
    pub version: u32,
    /// Entry points the gateway binds.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub listeners: Vec<Listener>,
    /// Match rules routing requests to services.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub routes: Vec<Route>,
    /// Logical APIs being exposed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub services: Vec<Service>,
    /// Load-balancing pools.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub upstreams: Vec<Upstream>,
    /// API caller identities.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub consumers: Vec<Consumer>,
    /// Named reusable rule bundles.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<Policy>,
    /// Gateway-level (global) policy attachment (#123): names of policies
    /// from the `policies` list that apply to EVERY request the gateway
    /// serves — the LEAST specific link of the frozen precedence chain
    /// consumer > route > service > listener > global. Named
    /// `global_policies` (not `policies`, which is the policy REGISTRY at
    /// this level) so the two roles cannot be confused. All applicable
    /// levels' rules AND together (see the rate-limiter module docs), so a
    /// global policy is an additional constraint on every request, not a
    /// default that more specific levels replace. Global policies also
    /// apply to UNROUTED traffic: a request whose path matches no route
    /// is rate-limited by them before the 404 is answered (the reserved
    /// paths /healthz, /readyz, and /metrics stay exempt).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub global_policies: Vec<String>,
    /// Gateway-level (global) authorization rules (#123): the least
    /// specific link of the authorization precedence chain
    /// consumer > route > service > listener > global (see [`Authz`] for
    /// the rule semantics and the `authz` module for the merge: a deny at
    /// ANY level wins; otherwise the most specific level with rules
    /// governs). Applies to every request that resolved a route
    /// (authorization runs after route resolution per the documented
    /// request-path order). Same validation rules as route-level
    /// authorization; see [`Authz`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authorization: Option<Authz>,
    /// Gateway-level default security headers baseline (SEC-09, #213):
    /// applied to EVERY route that does not carry its own
    /// `security_headers` block and has not set
    /// `security_headers_opt_out: true`. Fail-secure defaults: a
    /// route with no `security_headers` block inherits this posture
    /// rather than shipping without HSTS/nosniff. A route that needs
    /// to disable a header from the default sets its own
    /// `security_headers` block (which fully replaces the default
    /// for that route), or sets `security_headers_opt_out: true` to
    /// opt out entirely. See [`SecurityHeaders`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default_security_headers: Option<SecurityHeaders>,
    /// SEC-08 (#212): Global WAF policy with CRS-compatible rules.
    /// When enabled, the rules are evaluated on every request
    /// (regardless of route-level WAF config). The anomaly score is
    /// accumulated across all matching rules; the request is blocked
    /// when the score exceeds the threshold. See [`GlobalWaf`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub waf: Option<GlobalWaf>,
    /// IP addresses / CIDR ranges of proxies whose `X-Forwarded-For` claims
    /// are trusted (gateway-level; the direct connection peer must be in
    /// this list for an inbound XFF chain to be preserved and extended).
    /// Each entry must be an IP address (e.g. `10.1.2.3`) or a CIDR
    /// (e.g. `10.0.0.0/8`); anything else fails validation. Empty (the
    /// default) trusts nobody: every proxied request carries an XFF of
    /// exactly the direct peer, and inbound XFF values are discarded.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub trusted_proxies: Vec<String>,
    /// Gateway-level concurrency cap (DW-015): the maximum number of
    /// requests admitted concurrently across the WHOLE gateway. Absent
    /// (the default) is unlimited; 0 is invalid (validation rejects it —
    /// omit the field for unlimited). Over-cap requests are rejected
    /// immediately with 503 "gateway saturated" (no queueing). A slot is
    /// reserved at request admission and released when the response body
    /// completes (or the connection drops). The reserved paths
    /// `/healthz` and `/readyz` bypass the cap so liveness/readiness
    /// probes still answer under saturation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_concurrent_requests: Option<u32>,
    /// Monitor mode (DW-041) for the gateway concurrency cap's load
    /// shedding: when the cap is saturated and a request would be shed,
    /// the would-shed is LOGGED and counted
    /// (`dwara_policy_dry_run_total{phase="load_shed"}` + a
    /// `dwara::policy` warn event) and the request is ADMITTED over the
    /// cap instead — deliberately exceeding `max_concurrent_requests` so
    /// an operator can observe what a cap would shed (and at which
    /// priorities) before enforcing it. Only meaningful with a cap set;
    /// validation rejects it on an uncapped gateway (it would be a
    /// no-op flag that reads as coverage).
    #[serde(default, skip_serializing_if = "is_false")]
    pub load_shed_dry_run: bool,
    /// JWT verification providers (DW-019): trusted token issuers whose
    /// keys are fetched from a JWKS endpoint. Each provider independently
    /// verifies `Authorization: Bearer` tokens (alg allowlist, iss/aud,
    /// exp with leeway) and maps the token to a consumer — via the
    /// provider's explicit `consumer` binding, or by matching a
    /// consumer's `jwt` credential `issuer` against the token's `iss`
    /// claim. Empty (the default): the gateway does not interpret Bearer
    /// tokens and forwards `Authorization` upstream untouched.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub jwt_providers: Vec<JwtProvider>,
    /// Admin API listener (DW-022, decision 6): mTLS-ONLY management
    /// endpoint. Absent (the default): no admin listener is started at
    /// all — the gateway is admin-silent until an operator configures
    /// one. When present, `tls` must carry all three files (server
    /// cert, key, and the CA that client certificates must chain to);
    /// a missing `client_ca_file` is rejected by validation — plaintext
    /// admin is not a supported production shape. The dev fallback
    /// (`DWARA_ADMIN_DEV=1`, dwara-bin) allows loopback-only plaintext
    /// and is loudly dev-only. The admin listener's bind set is fixed
    /// at startup; changes take effect on restart.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub admin: Option<AdminConfig>,
    /// Deliberate opt-in to running a gateway with ZERO routes (#129,
    /// maintainer decision). Default false: validation rejects a
    /// route-less config. An empty route set is schema-valid (every
    /// collection defaults empty), and a truncated or torn config
    /// write (truncate-then-save, common in naive editors) is
    /// schema-valid too — publishing it would drop ALL routing
    /// mid-run (every request 404s while the file "looks fine"). The
    /// guard applies to cold start AND hot reload alike; a rejected
    /// reload keeps the running generation serving. Set this to true
    /// only for deliberate route-less shapes (e.g. a gateway whose
    /// sole job is the admin API): with the flag set, unrouted
    /// requests answer 404 after listener/global policy checks, per
    /// the documented request-path order.
    #[serde(default, skip_serializing_if = "is_false")]
    pub allow_empty_routes: bool,
    /// HMAC request-signing verification policy (DW-036): the
    /// gateway-wide clock-skew window applied to the
    /// `X-Dwara-Timestamp` header of every signed request. Absent
    /// (the default) = [`DEFAULT_HMAC_CLOCK_SKEW_SECS`] (±5 minutes).
    /// See the `security::authn` module docs for the full
    /// signing contract (canonical string, headers, replay window).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hmac_auth: Option<HmacAuth>,
    /// Alert/event webhook targets (DW-044): every gateway event whose
    /// kind appears in a target's `events` list is POSTed to that
    /// target's `url` as one JSON envelope (id, kind, timestamp,
    /// gateway instance, payload). Delivery runs on a background task,
    /// never on the request path; emission is a bounded non-blocking
    /// hand-off (a full queue drops the event and counts the drop), so
    /// webhook failures can never stall the dataplane. Header values
    /// may be inline or `${...}` secret references (DW-045) — inline
    /// values are redacted in every config echo. See the `events`
    /// module docs for the envelope, the retry/budget shape, and the
    /// egress posture. Empty (the default): no webhooks, and events
    /// are still counted (emitted/dropped) but delivered nowhere.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub webhooks: Vec<Webhook>,
    /// The embedded analytics store (DW-043). Absent (the default):
    /// no analytics database, request records go nowhere beyond the
    /// Prometheus families and the sampled access log, and the admin
    /// API's analytics endpoints answer 404. When present, the
    /// gateway opens a SEPARATE SQLite file (never the state store's
    /// database) at `path`, feeds every completed request's access
    /// record to it on a fire-and-forget channel (a full channel
    /// DROPS and counts — analytics can never slow the dataplane),
    /// rolls raw records up through 1m/5m/1h/1d additive tables with
    /// per-granularity retention, and serves the dashboard/Top-N/
    /// structured-query endpoints from the admin listener. See the
    /// `analytics` module docs for the write path and the bounded-disk
    /// story. Part of startup wiring (the database opens once); the
    /// DIMENSIONS list is read live from the current generation so a
    /// reload can add or rename dimensions without a restart.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub analytics: Option<AnalyticsConfig>,
    /// Real-time access-record stream (DW-121, the opt-in firehose out):
    /// every completed request's access record — not rollups, not the
    /// discrete DW-044 ops events — streamed to an external sink in
    /// flushed batches. Complements, never replaces, the embedded
    /// analytics store: the two are configured independently and a
    /// deployment can run either, both, or neither. Absent (the
    /// default): no stream. The pipeline is fire-and-forget end to end
    /// (a bounded channel that drops and counts — it can never slow or
    /// block the dataplane). See the `events::stream` module docs for
    /// the wire format, the batching contract, and the failure
    /// isolation story. Startup wiring arms the pipeline (the channel
    /// capacity is fixed at boot); the sink set — including the
    /// enabled/disabled state — is live per config generation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub analytics_stream: Option<AnalyticsStreamConfig>,
    /// The GeoIP database (DW-050): MaxMind-format .mmdb file backing
    /// `authorization.geoip` country/ASN predicates. Absent: geo rules
    /// are rejected by validation (an unevaluable gate is an authoring
    /// error, not a silent pass).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub geoip: Option<GeoipConfig>,
    /// Bounded admission queues (DW-053): when the gateway concurrency
    /// cap (`max_concurrent_requests`) is saturated, requests WAIT for a
    /// permit up to `queue_timeout_ms` instead of being immediately
    /// shed. This produces a graceful degradation curve (latency rises
    /// before shedding begins) rather than the cliff of immediate
    /// shedding. Absent (the default): the DW-016 behavior stands —
    /// over-cap requests are shed immediately with 503. Requires
    /// `max_concurrent_requests` (validation rejects an enabled queue
    /// on an uncapped gateway, the same rule as `load_shed_dry_run`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub admission_queue: Option<AdmissionQueue>,
    /// mTLS client-certificate consumer mapping (DW-035): maps a
    /// VERIFIED client certificate (its SHA-256 fingerprint or subject
    /// CN) to a consumer name, so a client presenting a valid mTLS
    /// certificate is authenticated WITHOUT an API key, JWT, or other
    /// header credential — the certificate IS the credential. The
    /// certificate must still chain to a listener's `client_ca_file`
    /// (verified at the TLS layer); this mapping only resolves an
    /// ALREADY-VERIFIED certificate to a consumer. Distinct from the
    /// per-consumer `mtls` credential (which binds a cert to ONE
    /// consumer's credential list): this is a gateway-level table that
    /// can map certificates independent of the consumer credential
    /// registry. Absent (the default): mTLS certificates are matched
    /// only through consumers' `mtls` credentials (the DW-019 path).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mtls_consumer_mapping: Option<MtlsConsumerMapping>,
    /// Identity-forwarding headers (DW-035): when mTLS client auth is
    /// used, the gateway forwards client certificate metadata to the
    /// upstream as `X-Client-Cert-*` headers. These headers are
    /// GATEWAY-SET: any inbound headers with these names are STRIPPED
    /// from the client request before the gateway adds its own
    /// (spoofing prevention — the "without headers spoofing" part of
    /// the done-when). Absent (the default): no `X-Client-Cert-*`
    /// headers are forwarded.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mtls_forward_headers: Option<MtlsForwardHeaders>,
    /// Enterprise license configuration (DW-032). Absent (the default):
    /// the gateway runs in OSS mode — all features available are
    /// OSS-only and no license verification occurs. When present, the
    /// gateway verifies the license file at startup (if compiled with
    /// the `ent` cargo feature) and gates enterprise features behind
    /// the license's feature claims. The public key is NOT configured
    /// here — it comes from the `DWARA_LICENSE_PUBLIC_KEY` env var (or
    /// the compiled-in development key when unset), never
    /// user-configurable, so an operator cannot substitute their own
    /// key to forge a license. When the `ent` feature is NOT compiled
    /// in, the block is accepted but inert (the gate is always
    /// `LicenseGate::none()`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub license: Option<LicenseConfig>,
    /// OIDC providers (DW-034): trusted OpenID Connect issuers whose
    /// Bearer tokens are validated by token introspection (RFC 7662)
    /// rather than local JWT signature verification. Each provider
    /// independently introspects `Authorization: Bearer` tokens that did
    /// not verify against any JWT provider (DW-019) and maps the
    /// introspection result to a consumer via the provider's explicit
    /// `consumer` binding. The gateway also supports the
    /// authorization-code + PKCE flow (acting as an OIDC relying party),
    /// token exchange (RFC 8693), and token revocation (RFC 7009). Empty
    /// (the default): the gateway does not introspect Bearer tokens and
    /// OIDC is inert. See the `security::oidc` module docs for the full
    /// flow, caching, and fail-open/fail-closed posture.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub oidc_providers: Vec<OidcProvider>,
    /// Distributed Redis rate limiter (DW-031). Absent (the default):
    /// the local in-memory GCRA limiter is used (one limit per
    /// process). When present, the `ent` cargo feature is compiled in,
    /// AND a valid license with the `redis_rate_limiter` feature claim
    /// is loaded, the gateway uses a Redis-backed GCRA limiter so two
    /// or more instances share one rate limit. The same GCRA algorithm
    /// runs, but the bucket state lives in Redis and is updated
    /// atomically via a Lua script in a single round-trip. When the
    /// `ent` feature is NOT compiled in, or the license lacks the
    /// claim, the block is accepted but inert (the local limiter is
    /// used and a warning is logged). When Redis is unreachable,
    /// `fail_open` (default true) lets requests through; `false`
    /// rejects with 429.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub redis_rate_limiter: Option<RedisRateLimiterConfig>,
    /// Distributed Redis-backed consumer request quotas (DW-155, ent
    /// feature). Absent (the default): the local SQLite-backed quota
    /// checker is used (one counter per instance, so a fleet of N
    /// instances enforces N x the configured cap). When present, the
    /// `ent` cargo feature is compiled in, AND a valid license with the
    /// `redis_quotas` feature claim is loaded, the gateway uses a
    /// Redis-backed quota checker so two or more instances share one
    /// counter per (consumer, budget, window) — a fleet of N instances
    /// enforces the CONFIGURED cap. The same daily/monthly budget
    /// semantics run, but the counters live in Redis and are updated
    /// atomically via a Lua script in a single round-trip. When the
    /// `ent` feature is NOT compiled in, or the license lacks the
    /// claim, the block is accepted but inert (the local SQLite checker
    /// is used and a warning is logged). When Redis is unreachable,
    /// `fail_open` (default true) lets requests through; `false`
    /// rejects with 429.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub redis_quotas: Option<RedisQuotaConfig>,
    /// Distributed Redis-backed response cache (SCALE-04, #183, ent
    /// feature). Absent (the default): the local in-memory moka cache
    /// is used (one cache per instance, so a fleet of N instances has
    /// N x cold caches). When present, the `ent` cargo feature is
    /// compiled in, AND a valid license with the `redis_cache` feature
    /// claim is loaded, the gateway uses a Redis-backed response cache
    /// so two or more instances share one cache — fleet-wide hit
    /// ratios. A local moka tier can front Redis (two-tier with Pub/Sub
    /// invalidation) or be disabled for a pure Redis cache. When the
    /// `ent` feature is NOT compiled in, or the license lacks the
    /// claim, the block is accepted but inert (the local moka cache is
    /// used and a one-line notice is logged at startup).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub redis_cache: Option<RedisCacheConfig>,
    /// Config convergence (DW-054, enterprise feature). Absent (the
    /// default): each gateway instance serves only its local config
    /// generation and never watches remote instances. When present,
    /// the `ent` cargo feature is compiled in, AND a valid license
    /// with the `config_convergence` feature claim is loaded, the
    /// gateway publishes its config generation to a shared backend
    /// (Redis in v1; etcd/Consul are deferred behind the
    /// `ConfigConvergenceBackend` trait) and polls for generations
    /// published by other instances, converging to the highest
    /// generation within the poll interval. A drift report is emitted
    /// at `drift_check_interval_ms` when instances diverge. When the
    /// `ent` feature is NOT compiled in, or the license lacks the
    /// claim, the block is accepted but inert (the local file watcher
    /// runs alone) and a one-line notice is logged at startup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub config_convergence: Option<ConfigConvergenceConfig>,
    /// Proxy-wasm plugin definitions (DW-055). Each plugin is a .wasm
    /// module loaded and compiled with every config generation
    /// (checksum-keyed hot-swap) and run on the request pipeline
    /// phases it declares. Routes reference plugins by name via their
    /// `plugins` field; the dataplane dispatches them through the
    /// unified plugin chain (DW-157). A plugin whose .wasm cannot be
    /// read or compiled is marked crashed at load time (logged) and
    /// routes referencing it answer 500 fail-closed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub plugins: Vec<PluginConfig>,
    /// SCALE-12 (#192): remote/signed plugin registry configuration.
    /// When present, plugin `source.url` references are resolved
    /// against the registry's base URL and signatures are verified
    /// against the registry's pinned public keys. See
    /// [`PluginRegistryConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub plugin_registry: Option<PluginRegistryConfig>,
    /// SCALE-12 (#191): global filter-chain ordering and dry-run
    /// configuration. Per-route `filter_chain` overrides take
    /// precedence. See [`FilterChainConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub filter_chain: Option<FilterChainConfig>,
    /// The AI provider-adapter pack (DW-075): the provider pool and the
    /// model alias table behind every `ai` route action. Absent (the
    /// default): no AI surface — an `ai` route action is rejected by
    /// validation. When present, clients send OpenAI chat-completions
    /// shaped requests to an `ai` route and the gateway translates to
    /// the target provider's wire format (OpenAI, Anthropic, Gemini),
    /// normalizing responses (and streaming deltas) back to the OpenAI
    /// shape. See [`ai::AiConfig`] and the `ai` domain docs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ai: Option<ai::AiConfig>,
    /// Fleet operations (DW-098, enterprise feature). Absent (the
    /// default): no fleet skew policy is enforced — the controller
    /// accepts edges regardless of version. When present, the `ent`
    /// cargo feature is compiled in, AND a valid license with the
    /// `fleet_operations` feature claim is loaded, the controller
    /// checks each connecting edge's version against the skew policy
    /// and the admin API exposes `GET /fleet/skew` (per-edge skew
    /// status) and `GET /fleet/status` (fleet-wide convergence +
    /// version distribution). When the `ent` feature is NOT compiled
    /// in, or the license lacks the claim, the block is accepted but
    /// inert (the controller accepts all edges).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fleet: Option<FleetConfig>,
    /// API lifecycle management (DW-110): the developer portal
    /// (auto-generated from OpenAPI specs), environment profiles
    /// (dev/staging/prod config overlays), and the API journey
    /// recorder (request flow visualization for debugging). Absent
    /// (the default): no lifecycle surface. The portal serving, profile
    /// overlay application, and journey recording are scaffolded: the
    /// block is accepted in every build and is inert until the runtime
    /// wiring lands (validation
    /// warns). See [`LifecycleConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub lifecycle: Option<LifecycleConfig>,
    /// Service mesh mode (DW-107, enterprise feature). Absent (the
    /// default): the gateway runs as a regular reverse proxy. When
    /// present, the `mesh` cargo feature is compiled in, AND a valid
    /// license with the `service_mesh` feature claim is loaded, the
    /// gateway runs as a sidecar in each pod: an init container
    /// configures iptables/TPROXY redirects so all traffic to and from
    /// the local application flows through the sidecar, which
    /// terminates mTLS (inbound) and wraps mTLS (outbound) using
    /// SPIFFE/SPIRE X.509 SVIDs fetched from the SPIRE Workload API.
    /// When the `mesh` feature is NOT compiled in, or the license
    /// lacks the claim, the block is accepted but inert (validation
    /// warns, no sidecar listeners or SPIFFE client are wired). Ent-
    /// only: validation warns when mesh is configured without the
    /// `ent` feature. See [`mesh::MeshConfig`] and the `mesh` domain
    /// module docs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mesh: Option<mesh::MeshConfig>,
    /// SSRF egress filter (SEC-13): when enabled, outbound connections
    /// from webhook deliveries and OPA callouts are checked against a
    /// deny set of private/loopback/link-local/metadata IP ranges.
    /// An optional allowlist exempts specific CIDRs. Default disabled
    /// (the v1 posture trusts operator-configured endpoints). See
    /// [`ssrf::SsrfFilterConfig`] and [`ssrf::SsrfFilter`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ssrf_filter: Option<ssrf::SsrfFilterConfig>,
}

/// Bounded admission queue config (DW-053, `gateway.admission_queue`).
///
/// When enabled and the concurrency cap is full, requests wait for a
/// permit up to `queue_timeout_ms` instead of being immediately shed.
/// The queue depth is bounded by `max_queue_size`; once full, further
/// requests are shed immediately with 503 (the `queue_full` outcome).
/// Per-priority splitting (`per_priority: true`, the default) reserves
/// a fraction of queue capacity for high-priority requests so they are
/// not starved by a low-priority queue fill.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdmissionQueue {
    /// Master switch. Default false: the queue is inert and the
    /// gateway sheds immediately on cap saturation (DW-016 behavior).
    /// Requires `max_concurrent_requests` (validation rejects an
    /// enabled queue on an uncapped gateway).
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Total number of requests that may wait for a permit across all
    /// priority classes (1..=10000). Once the queue is at capacity,
    /// further over-cap requests are shed immediately with 503
    /// (the `queue_full` outcome).
    pub max_queue_size: u32,
    /// Maximum time a request waits for a permit, in milliseconds
    /// (1..=10000). If the timeout expires before a permit becomes
    /// available, the request is shed with 503 (the `timeout`
    /// outcome) and a `Retry-After` header.
    pub queue_timeout_ms: u64,
    /// Split queue capacity across priority classes (default true).
    /// When true, a fraction of `max_queue_size` is reserved for
    /// high-priority requests (priority >= 8) so they are not starved
    /// by a low-priority queue fill. When false, the queue is a single
    /// shared pool (first-come-first-served).
    #[serde(default = "default_true", skip_serializing_if = "is_false")]
    pub per_priority: bool,
}

fn default_true() -> bool {
    true
}

/// Default freshness target for live sketches (DW-092): 500 ms —
/// sub-second freshness for the in-process rolling window.
fn default_freshness_target() -> u64 {
    500
}

/// Default baseline window count for the insights engine (DW-092):
/// 1440 = 24 hours of 1-minute windows (one minute-of-day seasonal
/// cycle).
fn default_baseline_windows() -> u64 {
    1440
}

/// mTLS client-certificate consumer mapping (DW-035,
/// `gateway.mtls_consumer_mapping`).
///
/// Maps a VERIFIED client certificate to a consumer name by its
/// SHA-256 fingerprint (lowercase colon-separated hex of the DER) or
/// by subject CommonName. When enabled and a client presents a
/// certificate that chains to a listener's `client_ca_file` but
/// matches NO entry in this table, the gateway returns 401
/// `mtls_consumer_not_mapped` (the certificate was verified but is not
/// a known caller). A client that presents NO certificate on a
/// listener with this mapping enabled falls through to the other
/// authentication families (or 401 if the route requires auth and no
/// family resolves).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct MtlsConsumerMapping {
    /// Master switch. Default false: the mapping is inert and mTLS
    /// certificates are matched only through consumers' `mtls`
    /// credentials (the DW-019 path).
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Fingerprint-to-consumer entries. Each `fingerprint` is the
    /// SHA-256 of the client certificate DER as lowercase
    /// colon-separated hex (e.g. `ab:cd:ef:...`). The fingerprint is
    /// the EXACT bytes the gateway computes from the presented
    /// certificate, so a re-issued certificate needs a new entry.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub consumers: Vec<MtlsFingerprintMapping>,
    /// Subject-CN-to-consumer mapping (alternative to `consumers`):
    /// maps the certificate's subject CommonName to a consumer name.
    /// Binding by subject CN survives certificate re-issue under the
    /// same CN; the certificate must still chain to a listener's
    /// `client_ca_file`. Keys are exact, case-sensitive CN strings.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub subject_cn_mapping: std::collections::BTreeMap<String, String>,
}

/// One fingerprint-to-consumer mapping entry (DW-035,
/// `mtls_consumer_mapping.consumers[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct MtlsFingerprintMapping {
    /// SHA-256 fingerprint of the client certificate DER as lowercase
    /// colon-separated hex (e.g. `ab:cd:ef:...`). Validated to be
    /// 64 hex digits with optional colon separators.
    pub fingerprint: String,
    /// The consumer name this certificate resolves to. Must reference
    /// a consumer in the `consumers` list (validation rejects an
    /// unknown name).
    pub consumer: String,
}

/// Identity-forwarding headers for mTLS client auth (DW-035,
/// `gateway.mtls_forward_headers`).
///
/// When enabled, the gateway adds `X-Client-Cert-*` headers to the
/// upstream request carrying metadata from the VERIFIED client
/// certificate. These headers are GATEWAY-SET: any inbound headers
/// whose names match the configured prefix are STRIPPED from the
/// client request before the gateway adds its own, so a client cannot
/// spoof certificate identity upstream.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct MtlsForwardHeaders {
    /// Master switch. Default false: no `X-Client-Cert-*` headers are
    /// forwarded.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Header name prefix (default `X-Client-Cert`). The gateway adds
    /// `<prefix>-Fingerprint`, `<prefix>-Subject-CN`, `<prefix>-Issuer-CN`,
    /// and `<prefix>-Not-After`. Inbound headers starting with this
    /// prefix (case-insensitive) are stripped before injection.
    #[serde(
        default = "default_mtls_forward_prefix",
        skip_serializing_if = "is_default_mtls_forward_prefix"
    )]
    pub prefix: String,
}

fn default_mtls_forward_prefix() -> String {
    "X-Client-Cert".to_string()
}

fn is_default_mtls_forward_prefix(p: &str) -> bool {
    p == "X-Client-Cert"
}

/// Enterprise license configuration (DW-032, `gateway.license`).
///
/// When present, the gateway verifies the license file at startup (if
/// compiled with the `ent` cargo feature) and gates enterprise features
/// behind the license's feature claims. The public key is NOT in this
/// block — it comes from the `DWARA_LICENSE_PUBLIC_KEY` env var (or the
/// compiled-in development key when unset), never user-configurable, so
/// an operator cannot substitute their own key to forge a license. When
/// the `ent` feature is NOT compiled in, the block is accepted but inert
/// (the gate is always `LicenseGate::none()`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct LicenseConfig {
    /// Filesystem path of the license file (JSON: claims + Ed25519
    /// signature). The file is read and verified at startup and on
    /// every config reload. A missing file refuses to start at cold
    /// start (exit 1); on reload, a missing file keeps the running
    /// generation serving.
    pub file: String,
    /// Grace period in days after the license expires before the gate
    /// degrades to OSS (default 7; validated to 0..=30). During the
    /// grace window enterprise features still work and a warning is
    /// logged. 0 means no grace (immediate degradation on expiry).
    #[serde(
        default = "default_license_grace_period_days",
        skip_serializing_if = "is_default_license_grace_period_days"
    )]
    pub grace_period_days: u32,
}

fn default_license_grace_period_days() -> u32 {
    crate::config::limits::DEFAULT_LICENSE_GRACE_PERIOD_DAYS
}

fn is_default_license_grace_period_days(v: &u32) -> bool {
    *v == crate::config::limits::DEFAULT_LICENSE_GRACE_PERIOD_DAYS
}

/// Redis deployment topology (SCALE-11, #248). Controls how the
/// gateway connects to Redis for the distributed rate limiter,
/// quotas, and shared cache. The default `single` mode uses one
/// Redis URL (the existing behavior). `sentinel` mode resolves the
/// master through a Sentinel deployment. `cluster` mode connects
/// to a Redis Cluster.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase", deny_unknown_fields)]
pub enum RedisTopology {
    /// Single Redis instance (the default). Uses the `url` field
    /// directly. No HA — if the instance is down, the fail-open
    /// policy applies.
    #[default]
    Single,
    /// Redis Sentinel: resolves the master via the Sentinel nodes
    /// listed in `nodes`, using `master_name` to identify the
    /// monitored instance. The gateway connects to the resolved
    /// master via a `ConnectionManager` (automatic reconnection on
    /// failover is handled by re-resolving on disconnect).
    Sentinel,
    /// Redis Cluster: connects to the cluster via the node URLs in
    /// `nodes` (or `url` if `nodes` is empty). Uses the redis crate's
    /// `ClusterClient` which handles slot mapping, MOVED/ASK
    /// redirections, and cross-slot routing automatically. Lua
    /// scripts use hash tags (`{key}`) to ensure all keys in a script
    /// land on the same slot.
    Cluster,
}

/// Redis HA and multi-region config (SCALE-11, #248). Embedded in
/// each Redis-backed config block (rate limiter, quotas, cache) to
/// control the connection topology and per-request timeout.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RedisHaConfig {
    /// Deployment topology (default `single`).
    #[serde(default, skip_serializing_if = "is_default_redis_topology")]
    pub topology: RedisTopology,
    /// Additional node URLs for `sentinel` or `cluster` mode. For
    /// `sentinel`, these are the Sentinel node URLs (e.g.
    /// `redis://sentinel-1:26379`). For `cluster`, these are the
    /// cluster node URLs (any subset of the cluster's nodes; the
    /// client discovers the rest). When empty, the `url` field on
    /// the parent config is used as the sole node.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub nodes: Vec<String>,
    /// The master name for `sentinel` mode (the `master_name` in
    /// Sentinel config). Required when `topology = sentinel`; ignored
    /// otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub master_name: Option<String>,
    /// Per-request timeout in milliseconds (default 500; validated to
    /// 50..=30 000). Applied to each Redis command (Lua script calls,
    /// GET/SET for cache). A timed-out command is treated as a backend
    /// error and the fail-open policy applies. 0 means no per-request
    /// timeout (use the connection's default).
    #[serde(
        default = "default_redis_request_timeout_ms",
        skip_serializing_if = "is_default_redis_request_timeout_ms"
    )]
    pub request_timeout_ms: u64,
}

impl Default for RedisHaConfig {
    fn default() -> Self {
        RedisHaConfig {
            topology: RedisTopology::Single,
            nodes: Vec::new(),
            master_name: None,
            request_timeout_ms: default_redis_request_timeout_ms(),
        }
    }
}

fn is_default_redis_topology(t: &RedisTopology) -> bool {
    *t == RedisTopology::default()
}

fn default_redis_request_timeout_ms() -> u64 {
    500
}

fn is_default_redis_request_timeout_ms(v: &u64) -> bool {
    *v == default_redis_request_timeout_ms()
}

/// Distributed Redis-backed GCRA rate limiter config (DW-031,
/// `gateway.redis_rate_limiter`).
///
/// When present and the `ent` cargo feature is compiled in AND a valid
/// license with the `redis_rate_limiter` feature claim is loaded, the gateway
/// uses a Redis-backed GCRA rate limiter instead of the local in-memory
/// one — so two or more gateway instances share one rate limit per key. The
/// same stacked-window GCRA semantics run, but the per-key TAT lives in
/// Redis and is updated atomically via a Lua script in a single round-trip.
/// When the `ent` feature is NOT compiled in, or the license lacks the
/// claim, the block is accepted but inert (the local GCRA limiter is used).
/// When Redis is unreachable, `fail_open` (default true) lets requests
/// through; set it to false to reject with 429 instead.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RedisRateLimiterConfig {
    /// Redis connection URL (e.g. `redis://127.0.0.1:6379` or
    /// `redis-cluster://...`). The connection is established once at
    /// startup and pooled via a multiplexed `ConnectionManager`.
    pub url: String,
    /// Fail-open behavior when Redis is unreachable (default true):
    /// `true` allows the request (no rate limiting); `false` rejects
    /// with 429. Fail-open is the safer default for availability — a
    /// Redis outage should not take down the gateway — but operators
    /// who need hard limits can set this to `false`.
    #[serde(default = "default_true", skip_serializing_if = "is_true")]
    pub fail_open: bool,
    /// Prefix for rate-limit keys in Redis (default `dwara:rl:`). Each
    /// rule's per-key bucket is stored as `{prefix}{key}:{window_index}`.
    #[serde(
        default = "default_redis_key_prefix",
        skip_serializing_if = "is_default_redis_key_prefix"
    )]
    pub key_prefix: String,
    /// Connection timeout in milliseconds (default 1000; validated to
    /// 100..=30 000). The timeout applies to the initial connection
    /// establishment at startup, not to per-request Lua script calls
    /// (those use the pooled connection's own timeout).
    #[serde(
        default = "default_redis_connection_timeout_ms",
        skip_serializing_if = "is_default_redis_connection_timeout_ms"
    )]
    pub connection_timeout_ms: u64,
    /// TTL for rate-limit keys in Redis, in seconds (default 3600).
    /// Stale keys auto-expire so a key that stops receiving traffic
    /// does not accumulate forever. The per-window GCRA Lua script
    /// also sets an EXPIRE based on the burst tolerance; this value is
    /// a floor that ensures cleanup even for long-burst windows.
    #[serde(
        default = "default_redis_key_ttl_s",
        skip_serializing_if = "is_default_redis_key_ttl_s"
    )]
    pub key_ttl_s: u64,
    /// HA and topology config (SCALE-11, #248). Controls whether the
    /// gateway connects to a single Redis, a Sentinel deployment, or a
    /// Redis Cluster. Defaults to single-instance mode (the existing
    /// behavior).
    #[serde(default, skip_serializing_if = "is_default_redis_ha")]
    pub ha: RedisHaConfig,
}

/// Sentinel: returns true when the `RedisHaConfig` is at its default
/// (single topology, no nodes, no master name, default request
/// timeout). Used by `skip_serializing_if` to keep the config output
/// clean for the common single-Redis case.
fn is_default_redis_ha(ha: &RedisHaConfig) -> bool {
    ha == &RedisHaConfig::default()
}

/// Distributed Redis-backed consumer request quotas config (DW-155,
/// `gateway.redis_quotas`).
///
/// When present and the `ent` cargo feature is compiled in AND a valid
/// license with the `redis_quotas` feature claim is loaded, the gateway
/// uses a Redis-backed quota checker instead of the local SQLite-backed
/// one — so two or more gateway instances share one quota counter per
/// (consumer, budget, window). The same daily/monthly budget semantics
/// run, but the counters live in Redis and are updated atomically via a
/// Lua script in a single round-trip. When the `ent` feature is NOT
/// compiled in, or the license lacks the claim, the block is accepted
/// but inert (the local SQLite checker is used). When Redis is
/// unreachable, `fail_open` (default true) lets requests through; set
/// it to false to reject with 429 instead.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RedisQuotaConfig {
    /// Redis connection URL (e.g. `redis://127.0.0.1:6379` or
    /// `redis-cluster://...`). The connection is established once at
    /// startup and pooled via a multiplexed `ConnectionManager`.
    /// May be the same Redis instance as the rate limiter
    /// (`redis_rate_limiter.url`) — the key prefixes are distinct.
    pub url: String,
    /// Fail-open behavior when Redis is unreachable (default true):
    /// `true` allows the request (no quota enforcement); `false`
    /// rejects with 429. Fail-open is the safer default for
    /// availability — a Redis outage should not take down the gateway
    /// — but operators who need hard quotas can set this to `false`.
    #[serde(default = "default_true", skip_serializing_if = "is_true")]
    pub fail_open: bool,
    /// Prefix for quota keys in Redis (default `dwara:quota:`). Each
    /// (consumer, budget, window) counter is stored as
    /// `{prefix}{consumer_id}:{budget}:{window_start}`.
    #[serde(
        default = "default_redis_quota_key_prefix",
        skip_serializing_if = "is_default_redis_quota_key_prefix"
    )]
    pub key_prefix: String,
    /// Connection timeout in milliseconds (default 1000; validated to
    /// 100..=30 000). The timeout applies to the initial connection
    /// establishment at startup, not to per-request Lua script calls.
    #[serde(
        default = "default_redis_connection_timeout_ms",
        skip_serializing_if = "is_default_redis_connection_timeout_ms"
    )]
    pub connection_timeout_ms: u64,
    /// HA and topology config (SCALE-11, #248). Same shape as
    /// `redis_rate_limiter.ha`.
    #[serde(default, skip_serializing_if = "is_default_redis_ha")]
    pub ha: RedisHaConfig,
}

fn default_redis_quota_key_prefix() -> String {
    "dwara:quota:".to_string()
}

fn is_default_redis_quota_key_prefix(p: &str) -> bool {
    p == "dwara:quota:"
}

fn default_redis_key_prefix() -> String {
    "dwara:rl:".to_string()
}

fn is_default_redis_key_prefix(p: &str) -> bool {
    p == "dwara:rl:"
}

fn default_redis_connection_timeout_ms() -> u64 {
    1000
}

fn is_default_redis_connection_timeout_ms(v: &u64) -> bool {
    *v == 1000
}

fn default_redis_key_ttl_s() -> u64 {
    3600
}

fn is_default_redis_key_ttl_s(v: &u64) -> bool {
    *v == 3600
}

/// Distributed Redis-backed response cache config (SCALE-04, #183,
/// `gateway.redis_cache`, ent feature).
///
/// When present and the `ent` cargo feature is compiled in AND a valid
/// license with the `redis_cache` feature claim is loaded, the gateway
/// uses a Redis-backed response cache instead of (or in addition to)
/// the local in-memory moka cache — so two or more gateway instances
/// share one response cache. Fleet-wide cache hit ratios replace N x
/// per-instance cold caches, particularly impactful for canary and
/// rolling-deploy scenarios where new instances start empty. When the
/// `ent` feature is NOT compiled in, or the license lacks the claim,
/// the block is accepted but inert (the local moka cache is used and a
/// one-line notice is logged at startup).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RedisCacheConfig {
    /// Redis connection URL (e.g. `redis://127.0.0.1:6379` or
    /// `redis-cluster://...`). The connection is established once at
    /// startup with the configured timeout.
    pub url: String,
    /// Prefix for cache keys in Redis (default `dwara:cache:`). Each
    /// cached response is stored as `{prefix}{key}`.
    #[serde(
        default = "default_redis_cache_key_prefix",
        skip_serializing_if = "is_default_redis_cache_key_prefix"
    )]
    pub key_prefix: String,
    /// Connection timeout in milliseconds (default 1000; validated to
    /// 100..=30 000).
    #[serde(
        default = "default_redis_connection_timeout_ms",
        skip_serializing_if = "is_default_redis_connection_timeout_ms"
    )]
    pub connection_timeout_ms: u64,
    /// Whether to keep a local fronting cache (two-tier: local moka +
    /// Redis). Default true: the local cache fronts Redis for hot keys,
    /// and Redis Pub/Sub invalidation evicts local entries when another
    /// instance purges a key. Set to false for a pure Redis cache (no
    /// local tier).
    #[serde(default = "default_true", skip_serializing_if = "is_true")]
    pub local_tier: bool,
    /// HA and topology config (SCALE-11, #248). Same shape as
    /// `redis_rate_limiter.ha`.
    #[serde(default, skip_serializing_if = "is_default_redis_ha")]
    pub ha: RedisHaConfig,
}

fn default_redis_cache_key_prefix() -> String {
    "dwara:cache:".to_string()
}

fn is_default_redis_cache_key_prefix(p: &str) -> bool {
    p == "dwara:cache:"
}

/// Config convergence config (DW-054, `gateway.config_convergence`).
///
/// When present and the `ent` cargo feature is compiled in AND a valid
/// license with the `config_convergence` feature claim is loaded, the
/// gateway publishes its config generation to a shared backend and
/// polls for generations published by other instances, converging to
/// the highest generation within `poll_interval_ms`. The backend is
/// the seam for etcd/Consul (deferred); v1 ships a Redis
/// implementation. The coordinator runs ALONGSIDE the local file
/// watcher: a local file change triggers a local reload plus a publish
/// to the backend; a remote change (detected by polling) triggers a
/// remote reload. Both go through `compile_and_publish`. When the
/// `ent` feature is NOT compiled in, or the license lacks the claim,
/// the block is accepted but inert (the local file watcher runs
/// alone).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ConfigConvergenceConfig {
    /// Master switch. Default false: convergence is inert and the
    /// gateway serves only its local config (the local file watcher
    /// still runs). When true (and licensed), the coordinator
    /// publishes and polls.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Convergence backend type. v1 ships `"redis"`; etcd and Consul
    /// are deferred behind the `ConfigConvergenceBackend` trait (the
    /// value is the seam a future backend plugs into). Validation
    /// rejects any value other than `"redis"`.
    pub backend: String,
    /// Redis connection URL (e.g. `redis://127.0.0.1:6379`), required
    /// when `backend = "redis"`. The connection is established once at
    /// startup and pooled via a multiplexed `ConnectionManager`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub redis_url: Option<String>,
    /// Prefix for convergence keys in Redis (default `dwara:config`).
    /// Instance generations live under `{prefix}:instances` and config
    /// bodies under `{prefix}:config`.
    #[serde(
        default = "default_config_convergence_key_prefix",
        skip_serializing_if = "is_default_config_convergence_key_prefix"
    )]
    pub key_prefix: String,
    /// How often to poll the backend for generations published by
    /// other instances, in milliseconds (default 1000; validated to
    /// 100..=60 000). The done-when targets sub-second convergence;
    /// lower values converge faster at the cost of backend load.
    #[serde(
        default = "default_config_convergence_poll_interval_ms",
        skip_serializing_if = "is_default_config_convergence_poll_interval_ms"
    )]
    pub poll_interval_ms: u64,
    /// How often to read all instances' generations and report drift,
    /// in milliseconds (default 5000; validated to 1 000..=300 000).
    /// Drift is reported (structured log + metric) when instances
    /// serve different config hashes.
    #[serde(
        default = "default_config_convergence_drift_check_interval_ms",
        skip_serializing_if = "is_default_config_convergence_drift_check_interval_ms"
    )]
    pub drift_check_interval_ms: u64,
    /// Fail-open behavior when the convergence backend is unreachable
    /// (default true): `true` keeps serving the local config
    /// generation (convergence pauses until the backend recovers);
    /// `false` refuses to start at cold start when the backend cannot
    /// be reached. Fail-open is the safer default for availability --
    /// a backend outage should not take down the gateway.
    #[serde(default = "default_true", skip_serializing_if = "is_true")]
    pub fail_open: bool,
}

fn default_config_convergence_key_prefix() -> String {
    "dwara:config".to_string()
}

fn is_default_config_convergence_key_prefix(p: &str) -> bool {
    p == "dwara:config"
}

fn default_config_convergence_poll_interval_ms() -> u64 {
    1000
}

fn is_default_config_convergence_poll_interval_ms(v: &u64) -> bool {
    *v == 1000
}

fn default_config_convergence_drift_check_interval_ms() -> u64 {
    5000
}

fn is_default_config_convergence_drift_check_interval_ms(v: &u64) -> bool {
    *v == 5000
}

/// Fleet operations config (DW-098, `gateway.fleet`).
///
/// Configures the version-skew policy and rolling-upgrade order for a
/// fleet of edge instances managed by a controller (CP/DP split,
/// DW-066). When present and the `ent` cargo feature is compiled in
/// AND a valid license with the `fleet_operations` feature claim is
/// loaded, the controller checks each connecting edge's version
/// against the skew policy and the admin API exposes fleet status
/// endpoints. When the `ent` feature is NOT compiled in, or the
/// license lacks the claim, the block is accepted but inert.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FleetConfig {
    /// Master switch. Default false: fleet operations are inert and
    /// the controller accepts edges regardless of version. When true
    /// (and licensed), the skew policy is enforced.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The rolling-upgrade and version-skew policy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub upgrade: Option<FleetUpgradeConfig>,
    /// The controller's own version (the reference version edges are
    /// checked against). When absent, the gateway binary's
    /// `CARGO_PKG_VERSION` is used.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub controller_version: Option<String>,
    /// How long an edge can go without being seen (no ack, no
    /// re-registration) before it is flagged stale, in seconds
    /// (default 60; validated to 5..=3600). Stale edges are reported
    /// by `GET /fleet/status` but are NOT automatically removed — the
    /// operator decides whether to drain or wait.
    #[serde(
        default = "default_fleet_stale_timeout_secs",
        skip_serializing_if = "is_default_fleet_stale_timeout_secs"
    )]
    pub stale_timeout_secs: u64,
}

/// API lifecycle management config (DW-110, `gateway.lifecycle`).
///
/// Three sub-concerns, each additive and independently enabled:
///
/// - `portal` -- the developer portal: a read-only static HTML page
///   auto-generated from the configured OpenAPI spec sources, served
///   at a reserved path.
/// - `profiles` -- environment profiles: dev/staging/prod config
///   overlays. The profile is selected via the `DWARA_PROFILE` env
///   var; the selected profile's patch is merged onto the base config
///   at load time.
/// - `journey` -- the API journey recorder: records the request flow
///   through the gateway as a JSON document for debugging, stored via
///   the existing analytics raw table.
///
/// The block is accepted in every build and is inert until the
/// runtime wiring lands (validation warns).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct LifecycleConfig {
    /// The developer portal config. Absent (the default): no portal.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub portal: Option<LifecyclePortalConfig>,
    /// Environment profile overlays. Absent (the default): no
    /// overlays; the base config is used as-is.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub profiles: Option<LifecycleProfilesConfig>,
    /// The journey recorder config. Absent (the default): no
    /// journeys are recorded.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub journey: Option<LifecycleJourneyConfig>,
}

/// Developer portal config (DW-110, `gateway.lifecycle.portal`).
///
/// The portal is a read-only static HTML page that aggregates the
/// configured OpenAPI specs. `enabled` defaults to false: even with
/// the `api_lifecycle` feature compiled in, the portal is inert until
/// `enabled: true`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct LifecyclePortalConfig {
    /// Master switch. Default false: the portal is not served.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The URL path the portal is served at (a reserved HTTP path,
    /// shadowing any configured route, like `/healthz`). Must start
    /// with `/`. Default `/portal`.
    #[serde(
        default = "default_lifecycle_portal_path",
        skip_serializing_if = "is_default_lifecycle_portal_path"
    )]
    pub path: String,
    /// The OpenAPI spec sources to aggregate. Each source is either a
    /// `file` path or a `url` (an upstream `/openapi.json` endpoint).
    /// Empty (the default): the portal renders an empty listing.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub specs: Vec<LifecyclePortalSpec>,
}

fn default_lifecycle_portal_path() -> String {
    "/portal".to_string()
}

fn is_default_lifecycle_portal_path(p: &String) -> bool {
    p == "/portal"
}

/// One OpenAPI spec source for the developer portal (DW-110,
/// `gateway.lifecycle.portal.specs[]`).
///
/// Either a `file` path (read from disk) or a `url` (an upstream
/// `/openapi.json` endpoint, fetched at render time). Exactly one of
/// `file`/`url` must be set; validation rejects a spec with neither
/// or both.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct LifecyclePortalSpec {
    /// A file path to an OpenAPI 3.x JSON document on disk. The file
    /// must exist and be readable (validation checks this at config
    /// publish time).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub file: Option<String>,
    /// An upstream `/openapi.json` endpoint URL (http or https). The
    /// portal fetches the spec from this URL at render time. NOT
    /// fetched at validation time (the upstream may be down at publish
    /// time but up at render time).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub url: Option<String>,
    /// An optional display name for the spec. When absent, the portal
    /// derives the name from the spec's `info.title` (or the file name
    /// / URL host when the spec cannot be parsed).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
}

/// Environment profile overlays config (DW-110,
/// `gateway.lifecycle.profiles`).
///
/// Carries a base config (as a YAML string) plus per-profile config
/// patches. The profile is selected via the `DWARA_PROFILE` env var;
/// the selected profile's patch is merged onto the base at load time.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct LifecycleProfilesConfig {
    /// The base config, as a YAML string. This is the config that
    /// applies when no profile is selected (or the selected profile
    /// has no patch).
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub base_config: String,
    /// Per-profile config patches, keyed by profile name (`dev`,
    /// `staging`, `prod`). Each value is a YAML string merged onto the
    /// base config when that profile is selected.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub profile_overrides: std::collections::BTreeMap<String, String>,
    /// Directory of file-based profile patches (CFG-01, #180). When
    /// set, the selected profile's patch is loaded from
    /// `<profiles_dir>/<profile>.yaml` instead of the inline
    /// `profile_overrides` map. Relative paths resolve against the
    /// config file's directory. Takes precedence over
    /// `profile_overrides` when both are set.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub profiles_dir: Option<String>,
}

/// Journey recorder config (DW-110, `gateway.lifecycle.journey`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct LifecycleJourneyConfig {
    /// Master switch. Default false: no journeys are recorded.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The retention window for in-memory journeys, in hours. Must be
    /// greater than 0 (validation rejects 0). The durable copy's
    /// retention is the raw table's own retention; this cap only bounds
    /// the in-memory ring buffer. Default 24.
    #[serde(
        default = "default_lifecycle_journey_retention",
        skip_serializing_if = "is_default_lifecycle_journey_retention"
    )]
    pub retention_hours: u64,
}

fn default_lifecycle_journey_retention() -> u64 {
    24
}

fn is_default_lifecycle_journey_retention(h: &u64) -> bool {
    *h == 24
}

/// Rolling-upgrade and version-skew policy (DW-098,
/// `gateway.fleet.upgrade`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FleetUpgradeConfig {
    /// The version-skew policy: how tolerant the controller is of
    /// edges running a different version.
    ///
    /// - `"allow"` — accept any version (no skew check).
    /// - `"allow_minor_skew"` (default) — edges must match the
    ///   controller's major version and be within 1 minor version
    ///   (N-1 or N+1).
    /// - `"require_exact"` — edges must match the controller's version
    ///   exactly.
    #[serde(default, skip_serializing_if = "is_default_version_skew_policy")]
    pub skew: VersionSkewPolicyConfig,
    /// The upgrade order: which edges to upgrade first, identified by
    /// label selector. Edges matching earlier entries are upgraded
    /// before edges matching later entries. An edge matches an entry
    /// when it has ALL the labels in the entry's `labels` map. Empty
    /// (the default) means no ordering — all edges are upgraded
    /// simultaneously (canary/zone-based rollouts are configured by
    /// adding entries here).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub order: Vec<FleetUpgradeOrderEntry>,
    /// The maximum number of edges that may be upgraded
    /// simultaneously (a rolling-upgrade concurrency cap). 0 (the
    /// default) means no cap — all matching edges are upgraded at
    /// once. A typical canary rollout sets this to 1.
    #[serde(default, skip_serializing_if = "is_zero_u32")]
    pub max_concurrent: u32,
    /// Whether to fail the rollout if any edge reports a failed ack
    /// (applied: false). Default true: the controller stops pushing
    /// to further edges when one fails. false: the controller
    /// continues pushing to all matching edges regardless of
    /// individual failures (the operator monitors and rolls back
    /// manually).
    #[serde(default = "default_true", skip_serializing_if = "is_true")]
    pub halt_on_failure: bool,
}

/// A label-selector entry in the upgrade order list.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FleetUpgradeOrderEntry {
    /// A name for this upgrade wave (for logging and the status
    /// endpoint). Must be non-empty.
    pub name: String,
    /// The label selector: an edge matches this entry when it has
    /// ALL of these labels (key=value). Must be non-empty.
    #[serde(default, skip_serializing_if = "std::collections::HashMap::is_empty")]
    pub labels: std::collections::HashMap<String, String>,
}

/// The version-skew policy, mirroring the CP/DP
/// `cluster_sync::VersionSkewPolicy` but living in the config schema
/// (so the gateway config carries it, not just the controller
/// runtime).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "snake_case", deny_unknown_fields)]
pub enum VersionSkewPolicyConfig {
    /// Allow any version skew. The edge accepts the config regardless
    /// of version.
    Allow,
    /// Allow skew within a minor version (e.g. 1.2.x can talk to
    /// 1.3.x, but not 2.0.x). This is the default.
    #[default]
    AllowMinorSkew,
    /// Require exact version match. The edge rejects the config if
    /// its version differs from the controller's.
    RequireExact,
}

fn default_fleet_stale_timeout_secs() -> u64 {
    60
}

fn is_default_fleet_stale_timeout_secs(v: &u64) -> bool {
    *v == 60
}

fn is_default_version_skew_policy(p: &VersionSkewPolicyConfig) -> bool {
    *p == VersionSkewPolicyConfig::AllowMinorSkew
}

fn is_zero_u32(v: &u32) -> bool {
    *v == 0
}

/// The embedded analytics store config (DW-043, `gateway.analytics`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsConfig {
    /// Filesystem path of the analytics SQLite database. The file is
    /// created (and migrated) on first open. A separate file from the
    /// state store on purpose: retention deletes and incremental
    /// vacuum churn must never compact the identity store.
    pub path: String,
    /// Maximum batch latency of the background writer, in
    /// milliseconds (default 1000; validated to [100, 60 000]). Not a
    /// correctness knob — the rollup grace covers multiples of this.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub flush_ms: Option<u64>,
    /// Per-store retention, in milliseconds (defaults: raw 24 h, 1m
    /// 48 h, 5m 7 d, 1h 30 d, 1d 365 d). Validation enforces each
    /// floor (a granularity must outlive its own window comfortably)
    /// and monotonicity (no coarser table may expire before a finer
    /// one).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub retention: Option<AnalyticsRetention>,
    /// Custom dimensions (DW-043): request-header-sourced tags that
    /// become analytics dimensions — `x-plan` as dimension `plan`,
    /// for consumer tier / plan / feature-flag style cuts the fixed
    /// dimensions cannot express. Extracted at request completion
    /// capture; analytics-only (never added to the access log). At
    /// most 16 (cardinality guard); values are capped at 128 bytes
    /// (longer values are skipped for that request).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub dimensions: Vec<AnalyticsDimension>,
    /// Scheduled usage-report exports (DW-120): durable CSV/JSON
    /// dumps of the per-consumer usage statement, one file set per
    /// closed UTC calendar window, written by a background worker
    /// that reuses the analytics store's scheduling machinery. Absent
    /// (the default): no exports run and the admin export endpoints
    /// answer that exports are not configured. See the
    /// `analytics::exports` module docs for the schedule, the
    /// statement's reconciliation contract with the query API, and
    /// the quota-column window-alignment rule.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exports: Option<AnalyticsExports>,
    /// Live in-process sketches (DW-092): sub-second-freshness
    /// aggregation maintained synchronously on the request-completion
    /// hot path (per-route rolling window with counts, errors, and
    /// latency samples). Never blocks the dataplane — the sketch is
    /// updated in place under atomics and a short mutex over a capped
    /// sample vector. Absent (the default): no live sketches; the
    /// `GET /analytics/live` endpoint answers
    /// `analytics_not_configured`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub live_sketches: Option<AnalyticsLiveSketches>,
    /// ML traffic insights (DW-092): EWMA-based capacity forecasting
    /// and seasonal-baseline anomaly detection over the live sketch
    /// window rotations. The insights engine is in-process and
    /// hand-rolled (no ML crates): a minute-of-day ring buffer holds
    /// the seasonal pattern, an EWMA over recent windows carries the
    /// trend, and anomaly detection compares the current window's
    /// shape to the seasonal baseline. Absent (the default): no
    /// forecasting or anomaly detection; the
    /// `GET /analytics/forecast` and `GET /analytics/anomalies`
    /// endpoints answer `analytics_not_configured`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub insights: Option<AnalyticsInsights>,
    /// Replay time-travel debugging capture (DW-102): opt-in capture of
    /// request detail (redacted headers, auth identity) into the raw
    /// analytics table for offline replay against candidate configs.
    /// Absent (the default): no replay capture; the raw table's
    /// `request_headers_redacted` and `auth_identity` columns stay
    /// NULL. When present with `enabled: true`, the fire-and-forget
    /// analytics writer records the redacted headers and auth identity
    /// alongside the existing access fields, bounded by `retain_hours`.
    /// See [`AnalyticsReplayCapture`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub replay_capture: Option<AnalyticsReplayCapture>,
    /// REL-10 (#221): sampled degradation under channel pressure. When
    /// the analytics channel's fill ratio exceeds `high_watermark`,
    /// the offer path probabilistically drops records (keeping 1 in
    /// `sample_rate`) BEFORE the channel fills, so a sustained burst
    /// degrades to sampled telemetry rather than a hard drop cliff.
    /// Below `low_watermark` every record is kept. Defaults to off
    /// (no sampling); when enabled, `high_watermark` must be >
    /// `low_watermark` and both are in (0.0, 1.0].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sampled_degradation: Option<AnalyticsSampledDegradation>,
}

/// Sampled degradation config (REL-10, #221). See
/// [`AnalyticsConfig::sampled_degradation`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsSampledDegradation {
    /// Channel fill ratio above which sampling kicks in. Must be in
    /// (0.0, 1.0) and > `low_watermark`.
    #[serde(default = "default_sampled_high_watermark")]
    pub high_watermark: f64,
    /// Channel fill ratio below which sampling stops (every record
    /// kept). Must be in (0.0, 1.0) and < `high_watermark`.
    #[serde(default = "default_sampled_low_watermark")]
    pub low_watermark: f64,
    /// Fraction of records to KEEP when sampling (1 in N). 1.0 keeps
    /// all (no sampling); 0.1 keeps 10%. Must be in (0.0, 1.0].
    #[serde(default = "default_sampled_keep_rate")]
    pub keep_rate: f64,
}

fn default_sampled_high_watermark() -> f64 {
    0.8
}

fn default_sampled_low_watermark() -> f64 {
    0.5
}

fn default_sampled_keep_rate() -> f64 {
    0.1
}

/// Live in-process sketches config (DW-092, `analytics.live_sketches`).
///
/// The sketches are maintained inside the embedded analytics runtime
/// and updated on every `record()` call — a per-route rolling window
/// (size = `freshness_target_ms`) with request/error counts and a capped
/// latency-sample vector. Percentiles are computed at snapshot time
/// (sort-and-pick, O(n log n) with n capped at 1000), never on the hot
/// path. No new dependencies: the sketches are hand-rolled with atomics
/// and a short mutex, the same approach as the load-generator's
/// histogram.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsLiveSketches {
    /// Whether live sketches are maintained (default true when the
    /// block is present). Setting false disables the in-process
    /// sketches while keeping the block present (a no-op shape that
    /// reads as coverage).
    #[serde(default = "default_true", skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The rolling window size in milliseconds (default 500). Also the
    /// freshness target: a snapshot reflects at most this much
    /// staleness. Validated to [100, 5000] — below 100 is timer churn,
    /// above 5000 is no longer "live".
    #[serde(
        default = "default_freshness_target",
        skip_serializing_if = "is_default_freshness_target"
    )]
    pub freshness_target_ms: u64,
}

fn is_default_freshness_target(v: &u64) -> bool {
    *v == 500
}

/// ML traffic insights config (DW-092, `analytics.insights`).
///
/// The insights engine is hand-rolled (no ML crates): an EWMA over
/// recent sketch-window rotations carries the trend, a minute-of-day
/// ring buffer (1440 entries) holds the seasonal baseline, and anomaly
/// detection compares the current window's shape to the seasonal
/// baseline with a configurable factor. Forecasting combines the
/// seasonal average for the next minute with the EWMA trend
/// adjustment.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsInsights {
    /// Whether capacity forecasting is enabled (default false). When
    /// true, the `GET /analytics/forecast` endpoint returns a
    /// prediction for the next window.
    #[serde(default, skip_serializing_if = "is_false")]
    pub forecast: bool,
    /// Whether seasonal-baseline anomaly detection is enabled (default
    /// false). When true, the `GET /analytics/anomalies` endpoint
    /// returns the current window's anomaly status.
    #[serde(default, skip_serializing_if = "is_false")]
    pub anomaly_baseline: bool,
    /// The number of recent windows retained for the EWMA trend and
    /// the seasonal baseline ring (default 1440 = 24 hours of 1-minute
    /// windows). Validated to be > 0 when forecast or anomaly_baseline
    /// is enabled.
    #[serde(
        default = "default_baseline_windows",
        skip_serializing_if = "is_default_baseline_windows"
    )]
    pub baseline_windows: u64,
}

fn is_default_baseline_windows(v: &u64) -> bool {
    *v == 1440
}

/// Replay time-travel debugging capture config (DW-102,
/// `analytics.replay_capture`). Opt-in capture of request detail
/// (redacted headers, auth identity) into the raw analytics table for
/// offline replay against candidate configs. The capture reuses the
/// existing fire-and-forget analytics writer path and the existing PII
/// redaction patterns (`ai::redaction`); body capture is OFF by
/// default (PII risk).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsReplayCapture {
    /// Whether replay capture is active (default false — opt-in). When
    /// false the raw table's `request_headers_redacted` and
    /// `auth_identity` columns stay NULL even when the block is
    /// present (a no-op shape that reads as coverage).
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Time-bounded retention for replay-captured raw rows, in hours
    /// (default 24). Rows older than the retention window are deleted
    /// by the existing raw retention sweep. Validated to be > 0.
    #[serde(
        default = "default_replay_retain_hours",
        skip_serializing_if = "is_default_replay_retain_hours"
    )]
    pub retain_hours: u64,
    /// Whether to capture redacted request headers (default true when
    /// the block is present). Headers are scrubbed via the existing PII
    /// redaction patterns before storage.
    #[serde(default = "default_true", skip_serializing_if = "is_true")]
    pub capture_headers: bool,
    /// Whether to capture the request body (default false — PII risk).
    /// Body capture is off by default; enabling it is an explicit
    /// operator decision to accept the PII exposure of stored bodies
    /// (even redacted bodies may carry residual sensitive content).
    #[serde(default, skip_serializing_if = "is_false")]
    pub capture_body: bool,
}

fn default_replay_retain_hours() -> u64 {
    24
}

fn is_default_replay_retain_hours(v: &u64) -> bool {
    *v == 24
}

/// Scheduled usage-report exports (DW-120, `analytics.exports`).
///
/// The exports worker ticks on the same background machinery as the
/// rollup cascade, closes each UTC calendar window of the configured
/// [`AnalyticsExportWindow`] kind once its data has settled, and
/// writes one file per configured format into `directory` (created on
/// demand; unwritable directories fail the run LOUD in the run record
/// and logs — never the dataplane). Parquet is deliberately NOT a v1
/// format: the arrow/parquet dependency weight is deferred (see the
/// DW-156 backlog issue).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsExports {
    /// Directory the export files are written into (created on demand
    /// if missing). One deterministic file per (window, format); a
    /// re-export of the same window overwrites it (idempotent output,
    /// the rollup recompute philosophy).
    pub directory: String,
    /// The schedule/window kind (fixed UTC calendar windows). Default
    /// `daily` (midnight-to-midnight UTC — aligned with the quota
    /// daily budget's window, so a daily statement's quota column is
    /// exactly that day's counter).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub window: Option<AnalyticsExportWindow>,
    /// Output formats, a subset of `csv`/`json`; omitted or empty
    /// means BOTH csv and json (the default). Validation rejects only
    /// duplicates.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub formats: Vec<AnalyticsExportFormat>,
}

/// One export schedule kind (DW-120, `analytics.exports.window`).
/// Closed set; fixed UTC calendar windows.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum AnalyticsExportWindow {
    Hourly,
    Daily,
    Monthly,
}

/// One export output format (DW-120, `analytics.exports.formats[]`).
/// Closed set: `csv`, `json`, `parquet_csv`.
///
/// SCALE-12 (#190): `parquet_csv` writes a CSV file with a
/// `.parquet.csv` extension and a JSON metadata header describing
/// the schema in Parquet-compatible terms. The operator converts it
/// to true Parquet using an external tool (e.g., `duckdb -c "COPY
/// input.parquet.csv TO output.parquet (FORMAT PARQUET)"`). This
/// avoids adding the heavy `arrow`/`parquet` crate stack while
/// providing a clear path to Parquet output.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum AnalyticsExportFormat {
    Csv,
    Json,
    /// SCALE-12 (#190): CSV with Parquet-compatible metadata header.
    /// The file extension is `.parquet.csv`.
    ParquetCsv,
}

/// Per-granularity retention (DW-043, `analytics.retention`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsRetention {
    /// Raw access records.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub raw_ms: Option<i64>,
    /// The 1-minute rollup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub m1_ms: Option<i64>,
    /// The 5-minute rollup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub m5_ms: Option<i64>,
    /// The 1-hour rollup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub h1_ms: Option<i64>,
    /// The 1-day rollup.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub d1_ms: Option<i64>,
}

/// Default per-granularity retention (ms), indexed [raw, 1m, 5m, 1h,
/// 1d] — a week of traffic at every granularity a week query wants,
/// bounded disk at the 1-minute grain (DW-043). Lives in `config`
/// (the lowest consuming domain) so both validation and the analytics
/// store read ONE definition.
pub const ANALYTICS_DEFAULT_RETENTION_MS: [i64; 5] = [
    86_400_000,     // raw
    172_800_000,    // 1m
    604_800_000,    // 5m
    2_592_000_000,  // 1h
    31_536_000_000, // 1d
];

impl AnalyticsRetention {
    /// Resolve to the effective [raw, m1, m5, h1, d1] millisecond
    /// set, defaulting absent entries (and clamping each to its
    /// floor so programmatic builders cannot under-retain below a
    /// window's own lifetime).
    pub fn effective(&self) -> [i64; 5] {
        let d = ANALYTICS_DEFAULT_RETENTION_MS;
        let floors = [
            5 * 60_000,      // raw: five fine windows
            10 * 60_000,     // m1
            60 * 60_000,     // m5
            24 * 3_600_000,  // h1
            30 * 86_400_000, // d1
        ];
        [
            self.raw_ms.unwrap_or(d[0]).max(floors[0]),
            self.m1_ms.unwrap_or(d[1]).max(floors[1]),
            self.m5_ms.unwrap_or(d[2]).max(floors[2]),
            self.h1_ms.unwrap_or(d[3]).max(floors[3]),
            self.d1_ms.unwrap_or(d[4]).max(floors[4]),
        ]
    }
}

/// GeoIP allow/deny rules on the effective client IP (DW-050,
/// `authorization.geoip`). Countries are ISO 3166-1 alpha-2 codes
/// (case-insensitive in config, compared uppercase); ASNs are plain
/// numbers. Evaluation mirrors `allowed_consumers`/`denied_consumers`:
/// a denied match rejects (403) regardless of the allow lists; a
/// NON-EMPTY allow list admits only matches; empty allow lists
/// constrain nothing. The UNKNOWN case (unresolvable address, no
/// database) matches neither side.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GeoipRules {
    /// Countries allowed (empty = any not denied).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_countries: Vec<String>,
    /// Countries rejected, even when otherwise allowed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub denied_countries: Vec<String>,
    /// Autonomous system numbers allowed (empty = any not denied).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_asns: Vec<u32>,
    /// Autonomous system numbers rejected.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub denied_asns: Vec<u32>,
}

/// The GeoIP database config (DW-050, `gateway.geoip`). One MaxMind-
/// format database serves both country and ASN predicates (a
/// GeoLite2-Country, GeoLite2-ASN, or combined database — whichever
/// subtrees it carries are the ones the rules can use). The file is
/// opened at startup (a failed open is LOUD but non-fatal: the gateway
/// serves with geo lookups resolving UNKNOWN) and hot-reloaded: the
/// watcher swaps the reader when the file changes, with no restart.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GeoipConfig {
    /// Path to the .mmdb database file.
    pub path: String,
}

/// The source of a custom analytics dimension value (DW-093). The
/// default (when `source` is absent) is [`DimensionSource::Header`],
/// preserving the original DW-043 header-only config shape.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum DimensionSource {
    /// Read the value from a request header (the original DW-043
    /// source; requires the `header` field).
    Header,
    /// Read the value from a verified JWT claim (requires the `claim`
    /// field; the claim must be present in the resolved `Identity`'s
    /// claims map — only string- and number-valued top-level claims
    /// are available, the same subset authn exposes).
    Claim,
    /// Read the value from the request body via an RFC 6901 JSON
    /// pointer (requires the `body_path` field; only works when the
    /// body is buffered — retries, hedging, request transforms, or
    /// request validation opt the route into buffering; the
    /// zero-buffering default skips body-path dimensions).
    BodyPath,
}

/// One custom analytics dimension (DW-043,
/// `analytics.dimensions[]`).
///
/// DW-093 extends the source beyond headers: a `source` of `claim`
/// extracts from the verified JWT's claims, and `body_path` extracts
/// from the request body via a JSON pointer (only when the body is
/// buffered). The original header-only shape (`header` without
/// `source`) is preserved for backward compatibility.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsDimension {
    /// The dimension name: lowercase `[a-z0-9_]`, at most 32 bytes —
    /// it becomes the rollup table's `dim` key and the query field.
    pub name: String,
    /// The dimension source (DW-093). Absent defaults to `header`
    /// (the original DW-043 behavior). When `header`, the `header`
    /// field is required; when `claim`, the `claim` field is
    /// required; when `body_path`, the `body_path` field is required.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<DimensionSource>,
    /// The request header whose value is captured (case-insensitive,
    /// as HTTP header names are). Required when `source` is `header`
    /// (or absent). The FIRST value of a repeated header wins;
    /// non-UTF-8 and over-128-byte values are skipped.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub header: Option<String>,
    /// The JWT claim name whose value is captured (DW-093). Required
    /// when `source` is `claim`. The claim must be a string- or
    /// number-valued top-level claim in the verified token; other
    /// types and absent claims are skipped for that request.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub claim: Option<String>,
    /// An RFC 6901 JSON pointer into the request body (DW-093).
    /// Required when `source` is `body_path`. Only works when the
    /// body is buffered (retries, hedging, request transforms, or
    /// request validation); the zero-buffering default skips
    /// body-path dimensions silently. The body must be valid JSON;
    /// non-JSON bodies and unresolved pointers are skipped.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body_path: Option<String>,
}

impl AnalyticsDimension {
    /// The effective source (defaults to [`DimensionSource::Header`]
    /// when `source` is absent — the backward-compatible DW-043
    /// behavior).
    pub fn effective_source(&self) -> DimensionSource {
        self.source.unwrap_or(DimensionSource::Header)
    }
}

/// One alert/event webhook target (DW-044, `gateway.webhooks[]`).
/// Compiled per generation into an `events::webhook::WebhookTarget`
/// (secret references resolved at compile time, URL decomposed); see
/// that module for the delivery contract.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Webhook {
    /// Absolute `http://` or `https://` URL the envelope is POSTed to.
    /// Host and port come from the URL; the path (and query, if any) is
    /// preserved. `https://` verifies against the public webpki root set
    /// (no `trusted_ca_file` override for webhooks in v1).
    pub url: String,
    /// Event kinds this target receives (subset of the kinds the gateway
    /// emits; validation rejects unknown kinds). At least one entry.
    pub events: Vec<String>,
    /// Extra headers sent on every delivery. Values may be inline or
    /// `${ENV_NAME}` / `${file:/path}` secret references (DW-045),
    /// resolved at config-compile time; inline values are redacted in
    /// every config echo. Use a reference for bearer tokens and signing
    /// secrets.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub headers: std::collections::BTreeMap<String, String>,
    /// TOTAL budget for one delivery (all retry attempts share it):
    /// connect, write, and response-head read per attempt plus the
    /// backoff waits between attempts. A slow or hung target can never
    /// occupy more than this. Default 2000; validation enforces
    /// 1..=[`limits::MAX_WEBHOOK_TIMEOUT_MS`].
    #[serde(
        default = "default_webhook_timeout_ms",
        skip_serializing_if = "is_default_webhook_timeout_ms"
    )]
    pub timeout_ms: u64,
    /// Total attempts per delivery (the first try plus retries). Retries
    /// happen for transport failures and the transient status set
    /// (429/502/503/504), honoring a seconds-form `Retry-After` when the
    /// target sends one. Default 3; validation enforces
    /// 1..=[`limits::MAX_WEBHOOK_ATTEMPTS`].
    #[serde(
        default = "default_webhook_attempts",
        skip_serializing_if = "is_default_webhook_attempts"
    )]
    pub max_attempts: u32,
    /// First backoff between delivery attempts, doubling per retry up to
    /// `backoff_cap_ms` (a `Retry-After` answer replaces the computed
    /// value for that wait). Default 100.
    #[serde(
        default = "default_webhook_backoff_base_ms",
        skip_serializing_if = "is_default_webhook_backoff_base_ms"
    )]
    pub backoff_base_ms: u64,
    /// Upper bound on the computed backoff. Default 1000; must be >=
    /// `backoff_base_ms`.
    #[serde(
        default = "default_webhook_backoff_cap_ms",
        skip_serializing_if = "is_default_webhook_backoff_cap_ms"
    )]
    pub backoff_cap_ms: u64,
}

/// Default `gateway.webhooks[].timeout_ms` (DW-044): one shared
/// delivery budget, generous for a remote alerting endpoint, small
/// enough that a hung target cannot pile up deliveries.
pub const DEFAULT_WEBHOOK_TIMEOUT_MS: u64 = 2_000;
/// Default `gateway.webhooks[].max_attempts` (DW-044).
pub const DEFAULT_WEBHOOK_ATTEMPTS: u32 = 3;
/// Default `gateway.webhooks[].backoff_base_ms` (DW-044).
pub const DEFAULT_WEBHOOK_BACKOFF_BASE_MS: u64 = 100;
/// Default `gateway.webhooks[].backoff_cap_ms` (DW-044).
pub const DEFAULT_WEBHOOK_BACKOFF_CAP_MS: u64 = 1_000;

fn default_webhook_timeout_ms() -> u64 {
    DEFAULT_WEBHOOK_TIMEOUT_MS
}
fn default_webhook_attempts() -> u32 {
    DEFAULT_WEBHOOK_ATTEMPTS
}
fn default_webhook_backoff_base_ms() -> u64 {
    DEFAULT_WEBHOOK_BACKOFF_BASE_MS
}
fn default_webhook_backoff_cap_ms() -> u64 {
    DEFAULT_WEBHOOK_BACKOFF_CAP_MS
}
fn is_default_webhook_timeout_ms(v: &u64) -> bool {
    *v == DEFAULT_WEBHOOK_TIMEOUT_MS
}
fn is_default_webhook_attempts(v: &u32) -> bool {
    *v == DEFAULT_WEBHOOK_ATTEMPTS
}
fn is_default_webhook_backoff_base_ms(v: &u64) -> bool {
    *v == DEFAULT_WEBHOOK_BACKOFF_BASE_MS
}
fn is_default_webhook_backoff_cap_ms(v: &u64) -> bool {
    *v == DEFAULT_WEBHOOK_BACKOFF_CAP_MS
}

/// Real-time access-record stream (DW-121,
/// `gateway.analytics_stream`).
///
/// Every completed request's access record is copied onto a bounded
/// channel at request completion (drop-and-count on full — the stream
/// can never slow the dataplane), and a background flusher turns the
/// queue into ordered batches delivered to the configured sink: one
/// delivery per flushed BATCH, not per record. The channel capacity is
/// fixed at boot; the sink set, flush cadence, and batch bound are read
/// live from the current generation, so a reload can retarget or
/// disable the stream without a restart.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsStreamConfig {
    /// Where flushed batches go. One sink in v1 (`type: webhook`); the
    /// set is closed so a second implementation (a Kafka producer is
    /// the documented slot) is an additive config change, not a silent
    /// behavior change.
    pub sink: AnalyticsStreamSink,
    /// Capacity of the bounded record channel (default 8192; validated
    /// to [64, 65536]). The queue's entire memory story: every queued
    /// record is an owned copy, and a full queue DROPS (and counts)
    /// rather than blocking the request path. Startup wiring: the
    /// capacity is fixed when the gateway boots (a live reload changes
    /// the sink and the cadence, not this).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub buffer: Option<u64>,
    /// Maximum batch latency in milliseconds (default 1000; validated
    /// to [100, 60000]): a batch is flushed when it holds
    /// `batch_max` records, reaches the batch byte cap, or this much
    /// time has passed since its first record — whichever comes first.
    /// Read live per flush cycle.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub flush_ms: Option<u64>,
    /// Maximum records per flushed batch (default 512; validated to
    /// [1, 4096]). With the batch byte cap, whichever comes first. One
    /// batch is one delivery, so this is also the largest single
    /// delivery's record count.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub batch_max: Option<u64>,
}

/// The access-record stream's sink (DW-121,
/// `gateway.analytics_stream.sink`). Closed set, internally tagged
/// (`type: webhook` or `type: kafka`): `webhook` ships today; `kafka`
/// (SCALE-08, #187) produces NDJSON batches to a Kafka topic via a
/// Kafka REST Proxy (HTTP-based, no native client dependency). The
/// variant payloads carry their own `deny_unknown_fields`, so a
/// misspelled knob inside a sink is still a rejected config.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum AnalyticsStreamSink {
    /// POST each flushed batch as one NDJSON body (one JSON object per
    /// line, one line per record) to the configured URL, reusing the
    /// DW-044 webhook delivery engine's retry/budget shape — one
    /// delivery (with its retries) per batch.
    Webhook(AnalyticsStreamWebhook),
    /// Produce each flushed batch as NDJSON messages to a Kafka topic
    /// via a Kafka REST Proxy (SCALE-08, #187). The REST Proxy
    /// endpoint receives the batch as an HTTP POST with the
    /// `Content-Type: application/vnd.kafka.binary.v2+json` media
    /// type; each NDJSON line becomes a Kafka message value (base64
    /// encoded per the REST Proxy spec). TLS is via `https://`; SASL
    /// auth is via headers. This avoids the native `rdkafka`
    /// dependency while providing a production-usable Kafka
    /// integration.
    Kafka(AnalyticsStreamKafka),
}

/// The webhook batch sink (DW-121,
/// `gateway.analytics_stream.sink.webhook`). Same URL/header/retry
/// grammar as `gateway.webhooks[]` (DW-044) — the delivery engine is
/// shared — minus the `events` filter (a record stream has no kinds to
/// filter: every record goes to the sink).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsStreamWebhook {
    /// Absolute `http://` or `https://` URL the batch is POSTed to.
    /// `https://` verifies against the public webpki root set (no
    /// `trusted_ca_file` override — v1 scope, same as alert webhooks).
    pub url: String,
    /// Headers sent on every batch delivery (e.g. the collector's auth
    /// token). Values may be inline or `${ENV_NAME}` / `${file:/path}`
    /// secret references (DW-045), resolved at config-compile time;
    /// inline values are redacted in every config echo. Use a
    /// reference for bearer tokens and signing secrets.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub headers: std::collections::BTreeMap<String, String>,
    /// TOTAL budget for one batch delivery (all retry attempts share
    /// it), in milliseconds. Default 5000: a BATCH is heavier than a
    /// single alert envelope, and the flusher delivers batches strictly
    /// in order, so this bounds how long one unlucky batch can hold
    /// back the queue. Validation enforces
    /// 1..=[`limits::MAX_WEBHOOK_TIMEOUT_MS`] (the shared engine's
    /// bound).
    #[serde(
        default = "default_stream_webhook_timeout_ms",
        skip_serializing_if = "is_default_stream_webhook_timeout_ms"
    )]
    pub timeout_ms: u64,
    /// Total attempts per batch delivery (first try plus retries);
    /// retries cover transport failures and the transient status set
    /// (429/502/503/504), honoring a seconds-form `Retry-After`.
    /// Default 3; validation enforces
    /// 1..=[`limits::MAX_WEBHOOK_ATTEMPTS`].
    #[serde(
        default = "default_stream_webhook_attempts",
        skip_serializing_if = "is_default_stream_webhook_attempts"
    )]
    pub max_attempts: u32,
    /// First backoff between batch attempts, doubling per retry up to
    /// `backoff_cap_ms` (a `Retry-After` answer replaces the computed
    /// value for that wait). Default 250 — a batch retry is heavier
    /// than an alert retry, so it starts slower.
    #[serde(
        default = "default_stream_webhook_backoff_base_ms",
        skip_serializing_if = "is_default_stream_webhook_backoff_base_ms"
    )]
    pub backoff_base_ms: u64,
    /// Upper bound on the computed backoff. Default 4000; must be >=
    /// `backoff_base_ms`.
    #[serde(
        default = "default_stream_webhook_backoff_cap_ms",
        skip_serializing_if = "is_default_stream_webhook_backoff_cap_ms"
    )]
    pub backoff_cap_ms: u64,
}

/// The Kafka batch sink (SCALE-08, #187,
/// `gateway.analytics_stream.sink.kafka`). Produces each flushed
/// batch as NDJSON messages to a Kafka topic via a Kafka REST Proxy
/// (HTTP-based, no native client dependency). The REST Proxy
/// endpoint receives the batch as an HTTP POST with the
/// `Content-Type: application/vnd.kafka.binary.v2+json` media type;
/// each NDJSON line becomes a Kafka message value (base64 encoded
/// per the REST Proxy spec). TLS is via `https://`; SASL auth is via
/// headers (e.g. `Authorization: Basic ...`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnalyticsStreamKafka {
    /// Absolute `http://` or `https://` URL of the Kafka REST Proxy
    /// endpoint for producing to the topic, e.g.
    /// `https://kafka-rest:8082/topics/<topic>`. `https://` verifies
    /// against the public webpki root set.
    pub rest_proxy_url: String,
    /// Headers sent on every batch delivery (e.g. the REST Proxy's
    /// auth token, `Authorization: Basic ...` for SASL). Values may
    /// be inline or `${ENV_NAME}` / `${file:/path}` secret references
    /// (DW-045), resolved at config-compile time; inline values are
    /// redacted in every config echo.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub headers: std::collections::BTreeMap<String, String>,
    /// TOTAL budget for one batch delivery (all retry attempts share
    /// it), in milliseconds. Default 5000. Validation enforces
    /// 1..=[`limits::MAX_WEBHOOK_TIMEOUT_MS`] (the shared engine's
    /// bound).
    #[serde(
        default = "default_stream_webhook_timeout_ms",
        skip_serializing_if = "is_default_stream_webhook_timeout_ms"
    )]
    pub timeout_ms: u64,
    /// Max delivery attempts per batch. Default 3.
    #[serde(
        default = "default_stream_webhook_attempts",
        skip_serializing_if = "is_default_stream_webhook_attempts"
    )]
    pub max_attempts: u32,
    /// First backoff between batch attempts, doubling per retry up to
    /// `backoff_cap_ms`. Default 250.
    #[serde(
        default = "default_stream_webhook_backoff_base_ms",
        skip_serializing_if = "is_default_stream_webhook_backoff_base_ms"
    )]
    pub backoff_base_ms: u64,
    /// Upper bound on the computed backoff. Default 4000; must be >=
    /// `backoff_base_ms`.
    #[serde(
        default = "default_stream_webhook_backoff_cap_ms",
        skip_serializing_if = "is_default_stream_webhook_backoff_cap_ms"
    )]
    pub backoff_cap_ms: u64,
}

/// Default `analytics_stream.buffer` (DW-121): the bounded record
/// channel's capacity when the block is absent at boot (the stream is
/// always constructed so a live reload can arm it). Lives in `config`
/// with the retention defaults — the lowest consuming domain — so
/// validation docs, the stream, and the binary read one definition.
pub const DEFAULT_STREAM_BUFFER: u64 = 8_192;
/// Default `analytics_stream.flush_ms` (DW-121): maximum batch latency.
pub const DEFAULT_STREAM_FLUSH_MS: u64 = 1_000;
/// Default `analytics_stream.batch_max` (DW-121): records per flushed
/// batch.
pub const DEFAULT_STREAM_BATCH_MAX: u64 = 512;
/// Default `analytics_stream.sink.webhook.timeout_ms` (DW-121): a
/// batch carries up to `batch_max` records, so its budget starts
/// heavier than the alert webhook's 2000 but stays far under the
/// one-minute ceiling.
pub const DEFAULT_STREAM_WEBHOOK_TIMEOUT_MS: u64 = 5_000;
/// Default `analytics_stream.sink.webhook.max_attempts` (DW-121).
pub const DEFAULT_STREAM_WEBHOOK_ATTEMPTS: u32 = 3;
/// Default `analytics_stream.sink.webhook.backoff_base_ms` (DW-121).
pub const DEFAULT_STREAM_WEBHOOK_BACKOFF_BASE_MS: u64 = 250;
/// Default `analytics_stream.sink.webhook.backoff_cap_ms` (DW-121).
pub const DEFAULT_STREAM_WEBHOOK_BACKOFF_CAP_MS: u64 = 4_000;

fn default_stream_webhook_timeout_ms() -> u64 {
    DEFAULT_STREAM_WEBHOOK_TIMEOUT_MS
}
fn default_stream_webhook_attempts() -> u32 {
    DEFAULT_STREAM_WEBHOOK_ATTEMPTS
}
fn default_stream_webhook_backoff_base_ms() -> u64 {
    DEFAULT_STREAM_WEBHOOK_BACKOFF_BASE_MS
}
fn default_stream_webhook_backoff_cap_ms() -> u64 {
    DEFAULT_STREAM_WEBHOOK_BACKOFF_CAP_MS
}
fn is_default_stream_webhook_timeout_ms(v: &u64) -> bool {
    *v == DEFAULT_STREAM_WEBHOOK_TIMEOUT_MS
}
fn is_default_stream_webhook_attempts(v: &u32) -> bool {
    *v == DEFAULT_STREAM_WEBHOOK_ATTEMPTS
}
fn is_default_stream_webhook_backoff_base_ms(v: &u64) -> bool {
    *v == DEFAULT_STREAM_WEBHOOK_BACKOFF_BASE_MS
}
fn is_default_stream_webhook_backoff_cap_ms(v: &u64) -> bool {
    *v == DEFAULT_STREAM_WEBHOOK_BACKOFF_CAP_MS
}

/// Gateway-wide HMAC request-signing policy (DW-036). The credential
/// itself (key id + secret) lives on a consumer
/// (`credentials: [{type: hmac, ...}]`); this block carries the
/// VERIFICATION policy that applies to every signed request.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct HmacAuth {
    /// Maximum accepted absolute difference, in seconds, between the
    /// request's `X-Dwara-Timestamp` and the gateway clock. A timestamp
    /// outside the window is rejected 401 BEFORE any HMAC computation
    /// (an expired window is not a MAC problem). The window is also the
    /// replay window: nonces are remembered for twice this duration.
    /// Default 300 (±5 minutes, the §4.6 recommendation); validation
    /// enforces 1..=3600 (a sub-second window rejects every request
    /// with any clock drift; an unbounded one pins nonce-cache memory
    /// forever).
    #[serde(default = "default_hmac_clock_skew_secs")]
    pub max_clock_skew_secs: u64,
}

/// Default `hmac_auth.max_clock_skew_secs` (±5 minutes, DW-036 §4.6).
pub const DEFAULT_HMAC_CLOCK_SKEW_SECS: u64 = 300;

fn default_hmac_clock_skew_secs() -> u64 {
    DEFAULT_HMAC_CLOCK_SKEW_SECS
}

impl Gateway {
    /// A display-safe copy of this config (DW-045): every INLINE
    /// `api_key` value is replaced by the
    /// [`credentials::redact_inline_secret`] placeholder
    /// (`${redacted:sha256:<prefix>}`); `${...}` references pass through
    /// unchanged (an env-var name or file path is not secret bytes —
    /// the config file itself carries it). This is the TYPED redaction
    /// behind every surface that echoes configuration (admin
    /// `GET /config`); it is deliberately a transform, not a custom
    /// serializer, so it cannot drift from the schema — a future
    /// secret-bearing field fails visibly (its value reaches the dump
    /// unredacted) instead of silently escaping an allowlist regex.
    pub fn redacted(&self) -> Gateway {
        let mut redacted = self.clone();
        for consumer in &mut redacted.consumers {
            for credential in &mut consumer.credentials {
                match credential {
                    Credential::ApiKey { key } => {
                        *key = credentials::redact_inline_secret(key);
                    }
                    // DW-036: the HMAC secret is inline secret material
                    // exactly like an api key — same placeholder, same
                    // unresolvable-by-design round-trip rejection.
                    Credential::Hmac { secret, .. } => {
                        *secret = credentials::redact_inline_secret(secret);
                    }
                    Credential::Jwt { .. } | Credential::Mtls { .. } => {}
                }
            }
        }
        // DW-044: webhook header values are secret-bearing config fields
        // exactly like api keys (bearer tokens, signing secrets) — the
        // same placeholder, the same reference passthrough, the same
        // unresolvable-by-design round-trip rejection.
        for webhook in &mut redacted.webhooks {
            for value in webhook.headers.values_mut() {
                *value = credentials::redact_inline_secret(value);
            }
        }
        // DW-075: AI provider auth values are inline secret material
        // exactly like api keys — the same placeholder, the same
        // reference passthrough.
        if let Some(ai) = &mut redacted.ai {
            for provider in &mut ai.providers {
                if let Some(auth) = &mut provider.auth {
                    auth.value = credentials::redact_inline_secret(&auth.value);
                }
                // DW-080: redact credential pool entry values too.
                if let Some(pool) = &mut provider.credential_pool {
                    for cred in &mut pool.credentials {
                        cred.value = credentials::redact_inline_secret(&cred.value);
                    }
                }
            }
        }
        redacted
    }
}

/// Admin listener configuration (DW-022).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminConfig {
    /// Bind address of the admin listener. Default `127.0.0.1:2019`
    /// (loopback-only; frozen decision 6) — override only to place the
    /// admin API on a dedicated management interface, and rely on mTLS
    /// for access control: there is no token layer in v1 (the client
    /// certificate IS the auth).
    #[serde(default = "default_admin_bind")]
    pub bind: String,
    /// mTLS material for the admin listener; all three files are
    /// required.
    pub tls: AdminTlsConfig,
    /// SEC-01: RBAC bindings for mTLS-authenticated admin clients.
    /// Maps client certificate fingerprints (SHA-256 of the cert
    /// DER) to roles. When present, a valid client certificate with
    /// NO binding is denied (fail-closed: no implicit admin). When
    /// absent (the default), any CA-valid client certificate is
    /// treated as full admin (the v1 behavior — backward compatible).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub rbac: Option<AdminRbacConfig>,
    /// SEC-01: API token authentication. When present, the admin API
    /// accepts an `Authorization: Bearer <token>` header in addition
    /// to mTLS. Tokens are hashed (SHA-256) at rest; the config lists
    /// token hashes, not plaintext tokens. When absent (the default),
    /// only mTLS is accepted (the v1 behavior).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub api_tokens: Option<AdminApiTokensConfig>,
    /// SEC-01: Admin audit log. When present, all mutating admin
    /// actions (PATCH /config, purge) are recorded in an append-only
    /// audit table in the state store. Each entry includes the actor
    /// (cert fingerprint or token hash), the action, the before/after
    /// config hash, and a timestamp. When absent (the default), no
    /// audit log is kept.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub audit: Option<AdminAuditConfig>,
}

/// SEC-01: Admin RBAC configuration. Maps client certificate
/// fingerprints to roles. A valid certificate with no binding is
/// denied (fail-closed).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminRbacConfig {
    /// Certificate-fingerprint-to-role bindings. Each entry maps one
    /// SHA-256 fingerprint (lowercase hex, 64 chars) to a role.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub bindings: Vec<AdminRbacBinding>,
}

/// One certificate-fingerprint-to-role binding.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminRbacBinding {
    /// SHA-256 fingerprint of the client certificate (lowercase hex,
    /// 64 chars). Computed over the full DER encoding of the cert.
    pub cert_fingerprint: String,
    /// The role assigned to this certificate: `admin` (full access)
    /// or `readonly` (GET only; PATCH/purge denied).
    pub role: AdminRole,
}

/// Admin roles.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "lowercase")]
pub enum AdminRole {
    /// Full admin access: all admin API endpoints.
    #[default]
    Admin,
    /// Read-only access: GET endpoints only. PATCH /config and purge
    /// are denied (403).
    Readonly,
}

/// SEC-01: API token authentication for the admin API. Tokens are
/// hashed (SHA-256) at rest; the config lists token hashes, not
/// plaintext tokens. A client presents a token via
/// `Authorization: Bearer <token>`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminApiTokensConfig {
    /// The hashed API tokens (SHA-256 of the plaintext token, as
    /// lowercase hex, 64 chars). A request with a matching bearer
    /// token is authenticated as the token's role.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tokens: Vec<AdminApiToken>,
}

/// One hashed API token with a role.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminApiToken {
    /// SHA-256 hash of the plaintext token (lowercase hex, 64 chars).
    pub token_hash: String,
    /// The role assigned to this token.
    pub role: AdminRole,
}

/// SEC-01: Admin audit log configuration.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminAuditConfig {
    /// Whether the audit log is enabled. Default true (when the block
    /// is present, the audit log is on).
    #[serde(
        default = "default_audit_enabled",
        skip_serializing_if = "is_default_audit_enabled"
    )]
    pub enabled: bool,
}

fn default_audit_enabled() -> bool {
    true
}

fn is_default_audit_enabled(b: &bool) -> bool {
    *b
}

/// mTLS material for the admin listener (DW-022). Unlike dataplane
/// listeners there is no mode: the admin listener always terminates TLS
/// and always requires a client certificate chaining to `client_ca_file`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdminTlsConfig {
    /// Path to the PEM certificate chain the admin server presents.
    pub cert_file: String,
    /// Path to the PEM private key for `cert_file`.
    pub key_file: String,
    /// Path to the PEM CA bundle client certificates must chain to.
    /// Required (mTLS-only): validation rejects an admin block without
    /// it rather than silently serving no-auth TLS.
    pub client_ca_file: String,
}

fn default_admin_bind() -> String {
    "127.0.0.1:2019".to_string()
}

/// One JWT verification provider (DW-019).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct JwtProvider {
    pub name: String,
    /// JWKS endpoint (`http://` or `https://`). Keys are fetched lazily on
    /// the first Bearer request, refreshed after `refresh_secs`, and
    /// re-fetched on an unknown `kid` (key rotation mid-flight).
    pub jwks_url: String,
    /// Path to a PEM file of CA certificates the JWKS fetcher trusts for
    /// its `https://` connection INSTEAD of the default public (webpki)
    /// root set (#121): for JWKS endpoints served over TLS by a private
    /// CA. The file may carry several certificates (a typical CA bundle).
    /// Only meaningful with an `https://` jwks_url — no TLS is negotiated
    /// toward an `http://` endpoint, so validation rejects that
    /// combination. The file must exist and be readable at config compile
    /// time; validation names this field otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trusted_ca_file: Option<String>,
    /// Required token issuer (`iss` claim). Absent: any issuer accepted.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub issuer: Option<String>,
    /// Required audience (`aud` claim). Audience is validated ONLY when
    /// this is configured (#124, maintainer decision): a provider
    /// without an `audience` ACCEPTS tokens that carry any (or no) `aud`
    /// claim — `aud` is not interpreted unless the provider names one.
    /// All other validations (exp, nbf, iss when configured, the
    /// algorithm allowlist) are identical either way.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub audience: Option<String>,
    /// Allowed signature algorithms (default `["RS256", "ES256"]`).
    /// `none` and HMAC (`HS*`) algorithms are never allowed implicitly —
    /// they must not appear in this list; validation rejects them
    /// (asymmetric verification only: the gateway holds no shared
    /// secrets with issuers).
    #[serde(default = "default_jwt_algorithms")]
    pub algorithms: Vec<String>,
    /// JWKS cache staleness bound in seconds (default 300): a cached key
    /// set older than this is refreshed before use.
    #[serde(
        default = "default_jwt_refresh_secs",
        skip_serializing_if = "is_default_jwt_refresh_secs"
    )]
    pub refresh_secs: u64,
    /// exp/nbf clock-skew leeway in seconds (default 30).
    #[serde(
        default = "default_jwt_leeway_secs",
        skip_serializing_if = "is_default_jwt_leeway_secs"
    )]
    pub leeway_secs: u64,
    /// Consumer this provider's tokens authenticate. Absent: the token's
    /// `iss` claim is matched against consumers' `jwt` credentials.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub consumer: Option<String>,
    /// How long a key REMOVED from a fresh JWKS fetch keeps verifying
    /// (DW-046), in seconds (default 86400 = 24 h; 0 disables). The
    /// dual-validity window for JWKS rotation: issuers drop the old
    /// key from their JWKS the moment the new one appears, while
    /// previously-issued tokens still carry the old `kid` — during
    /// this grace the gateway honors the immediately-previous key set
    /// for kids the fresh set no longer carries. Only ONE previous set
    /// is retained (rotation is one step at a time). Validation caps
    /// the value at 7 days (604800).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub retired_key_grace_secs: Option<u64>,
    /// How long to serve stale (cached) keys after a JWKS fetch failure
    /// (SEC-12, #215), in seconds (default: same as `refresh_secs`,
    /// capped at 300). When a JWKS fetch fails, the cached key set
    /// keeps serving for this duration before a new fetch is attempted,
    /// so a transient JWKS provider outage does not cascade into auth
    /// failures. 0 disables stale-on-error (a fetch failure surfaces
    /// immediately when the cache is empty; when the cache is non-empty
    /// the existing degraded-mode behavior applies).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stale_on_error_secs: Option<u64>,
}

impl JwtProvider {
    /// `retired_key_grace_secs` resolved to its effective value
    /// (default 86 400; the DW-046 dual-validity window).
    pub fn retired_key_grace_secs(&self) -> u64 {
        self.retired_key_grace_secs.unwrap_or(86_400)
    }
    /// `stale_on_error_secs` resolved to its effective value (SEC-12,
    /// #215): the default is `min(refresh_secs, 300)` — a failed fetch
    /// backs off for at most one refresh interval (capped at 5 min) so
    /// a down JWKS endpoint does not chain every Bearer request through
    /// a doomed fetch attempt.
    pub fn stale_on_error_secs(&self) -> u64 {
        self.stale_on_error_secs
            .unwrap_or_else(|| self.refresh_secs.min(300))
    }
}

fn default_jwt_algorithms() -> Vec<String> {
    vec!["RS256".to_string(), "ES256".to_string()]
}

fn default_jwt_refresh_secs() -> u64 {
    300
}

fn default_jwt_leeway_secs() -> u64 {
    30
}

fn is_default_jwt_refresh_secs(v: &u64) -> bool {
    *v == 300
}

fn is_default_jwt_leeway_secs(v: &u64) -> bool {
    *v == 30
}

/// One OIDC provider (DW-034): an OpenID Connect issuer whose Bearer
/// tokens are validated by token introspection (RFC 7662) rather than
/// local JWT signature verification. The gateway fetches the issuer's
/// discovery document (`{issuer}/.well-known/openid-configuration`) to
/// learn the introspection, revocation, authorization, and token
/// endpoints, then introspects presented Bearer tokens (caching the
/// result keyed by token hash with a configurable TTL). The provider
/// also backs the authorization-code + PKCE relying-party flow, token
/// exchange (RFC 8693), and token revocation (RFC 7009).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OidcProvider {
    pub name: String,
    /// The OIDC issuer URL (e.g. `https://idp.example.com`). The
    /// discovery document is fetched from
    /// `{issuer}/.well-known/openid-configuration`. Must be an absolute
    /// `http(s)://` URL; validation rejects anything else. The
    /// introspection result's `iss` (when present) is checked against
    /// this issuer for defense against token confusion.
    pub issuer: String,
    /// The gateway's client identifier at the IdP (RFC 6749 section
    /// 2.2). Sent as the username of the HTTP Basic auth header to the
    /// introspection and token endpoints, and as `client_id` in the
    /// authorization-code and token-exchange request bodies.
    pub client_id: String,
    /// The gateway's client secret (RFC 6749 section 2.3.1). Either the
    /// value INLINE (redacted in every config echo, DW-045) or a
    /// `${...}` secret reference (env or file) resolved at config-compile
    /// time and re-read on every reload. Sent as the password of the
    /// HTTP Basic auth header. SECRET: never logged, never in Debug.
    pub client_secret: String,
    /// Path to a PEM file of CA certificates the OIDC HTTP client
    /// trusts for its `https://` connections INSTEAD of the default
    /// public (webpki) root set: for an IdP served over TLS by a private
    /// CA. The file may carry several certificates (a typical CA bundle).
    /// Only meaningful with an `https://` issuer; validation rejects the
    /// combination with an `http://` issuer. The file must exist and be
    /// readable at config compile time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trusted_ca_file: Option<String>,
    /// Scopes to request (default `["openid"]`). Sent in the
    /// authorization-code flow's authorization request and the
    /// token-exchange request body (space-joined).
    #[serde(
        default = "default_oidc_scopes",
        skip_serializing_if = "is_default_oidc_scopes"
    )]
    pub scopes: Vec<String>,
    /// Cache TTL for introspection results, in seconds (default 60). A
    /// cached `active: true` result short-circuits the IdP call for this
    /// duration; a cached `active: false` result is NOT cached (it is
    /// re-checked on the next request so a revoked token is noticed
    /// promptly). Must be > 0; validation rejects 0.
    #[serde(
        default = "default_oidc_introspection_cache_ttl_s",
        skip_serializing_if = "is_default_oidc_introspection_cache_ttl_s"
    )]
    pub introspection_cache_ttl_s: u64,
    /// Override the discovery-discovered introspection endpoint. Absent
    /// (the default): the endpoint is taken from the discovery document.
    /// Useful when the IdP's discovery document is incorrect or the
    /// endpoint is behind a different host.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub introspection_endpoint: Option<String>,
    /// Override the discovery-discovered revocation endpoint. Absent
    /// (the default): the endpoint is taken from the discovery document.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub revocation_endpoint: Option<String>,
    /// Consumer this provider's tokens authenticate (like
    /// [`JwtProvider::consumer`]). Absent: the introspection result's
    /// `sub` claim is used as the consumer name. When set, every
    /// successfully introspected token resolves to this consumer
    /// regardless of the `sub` claim.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub consumer: Option<String>,
    /// Fail-open posture when the IdP is unreachable (network error,
    /// non-2xx, malformed response). Default false (fail closed = 401):
    /// the gateway refuses to authenticate a token it cannot introspect.
    /// When true, the gateway treats an IdP failure as anonymous
    /// (pass-through) rather than rejecting the request. Fail-open
    /// trades security for availability; use with care.
    #[serde(default, skip_serializing_if = "is_false")]
    pub fail_open: bool,
}

fn default_oidc_scopes() -> Vec<String> {
    vec!["openid".to_string()]
}

fn is_default_oidc_scopes(v: &[String]) -> bool {
    v.len() == 1 && v[0] == "openid"
}

fn default_oidc_introspection_cache_ttl_s() -> u64 {
    60
}

fn is_default_oidc_introspection_cache_ttl_s(v: &u64) -> bool {
    *v == 60
}

/// Entry point: bind address + port + TLS termination (or passthrough) config.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Listener {
    pub name: String,
    /// Bind address, e.g. `0.0.0.0` or `127.0.0.1`.
    pub address: String,
    pub port: u16,
    #[serde(default = "default_listener_protocol")]
    pub protocol: ListenerProtocol,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tls: Option<ListenerTls>,
    /// Accept a PROXY protocol v1 or v2 header as the FIRST bytes of
    /// every connection on this listener (DW-030), replacing the peer
    /// address the gateway uses everywhere the socket peer is used
    /// today: the authz IP ACL's effective-client-IP base, rate-limit
    /// keying, `X-Forwarded-For` / `X-Real-IP` on the forwarded
    /// request. OPT-IN (default false): a plaintext listener that does
    /// not expect a PROXY line must never interpret the first request
    /// bytes as one, and a client that spoofs a PROXY line on a listener
    /// without this flag is simply serving garbage to the HTTP parser.
    /// The header is read BEFORE the TLS handshake (the L4 LB in front
    /// wraps the whole stream, TLS included) and a MALFORMED header
    /// fails closed: the connection is answered with a `400` error
    /// envelope and closed, never handed to HTTP parsing. A v2 `LOCAL`
    /// command or a v1 `UNKNOWN` line keeps the real peer address (the
    /// spec's own fallback for connections the LB did not originate).
    /// Validation rejects the combination with `tls.mode passthrough`:
    /// a passthrough listener splices raw bytes and never runs the
    /// HTTP pipeline that consumes the client address. Part of the
    /// restart-only bind set (like address/port) — toggling it takes a
    /// restart, not a reload.
    #[serde(default, skip_serializing_if = "is_false")]
    pub proxy_protocol: bool,
    /// Policies attached to this listener (#123): names from the
    /// gateway's `policies` list, applying to every request the listener
    /// accepts (the second-least specific link of the frozen chain
    /// consumer > route > service > listener > global; all applicable
    /// levels' rules AND together — see the rate-limiter module docs).
    /// Listener policies also apply to UNROUTED traffic accepted by this
    /// listener: a request whose path matches no route is rate-limited by
    /// them before the 404 is answered (reserved paths stay exempt).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<String>,
    /// Listener-level authorization rules (#123): applies to every
    /// request this listener accepts that resolved a route (authorization
    /// runs after route resolution per the documented request-path
    /// order). Link of the frozen chain consumer > route > service >
    /// listener > global; see [`Authz`] for the rule semantics and the
    /// `authz` module for the merge.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authorization: Option<Authz>,
    /// Alt-Svc header value advertised on H1/H2 responses for this
    /// listener (DW-088). When set, an `Alt-Svc` response header is
    /// added telling clients that HTTP/3 is available. The value is
    /// the alt-svc payload (e.g. `h3=":8443"; ma=86400`). Only
    /// meaningful on `http` and `https` listeners (an H3 listener
    /// advertising itself is a no-op and rejected by validation).
    /// The header is added after all other response processing (it
    /// is a transport-level advertisement, not a route-level
    /// transform).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub alt_svc: Option<String>,
    /// L4 proxying configuration (DW-103). Only meaningful on
    /// `protocol: tcp` and `protocol: udp` listeners; rejected by
    /// validation on other protocols. The `upstream` field names the
    /// upstream that receives the spliced stream (or, when
    /// `sni_routing` is true, the upstream selected by the TLS
    /// ClientHello SNI via the upstream's `tls.sni_routes` -- reusing
    /// the SNI extraction from DW-008 TLS passthrough). Compiled into
    /// every build (no cargo feature).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub l4: Option<L4Config>,
    /// HTTP/2 flow-control tuning for this listener (PERF-11, #244).
    /// When set, the h2 server builder uses these values instead of
    /// the process-wide defaults from `DWARA_H2_*` env vars. Only
    /// meaningful on `http` and `https` listeners (h2 is negotiated
    /// via ALPN or prior knowledge); ignored on `h3` (HTTP/3 has its
    /// own transport-level flow control) and `tcp`/`udp`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub http2: Option<Http2ListenerConfig>,
}

/// HTTP/2 flow-control tuning for a listener (PERF-11, #244,
/// `listeners[].http2`). Every field is optional; an omitted field
/// keeps the process-wide default from `DWARA_H2_*` env vars. This
/// allows per-listener tuning for streaming (SSE) workloads where
/// larger windows reduce flow-control stalls on long-lived streams.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Http2ListenerConfig {
    /// Initial stream-level window size in bytes (hyper
    /// `initial_stream_window_size`). Absent: process default
    /// (1 MiB via `DWARA_H2_STREAM_WINDOW_KIB`). Larger values
    /// reduce stalls on streaming responses but increase memory
    /// per stream. Bounds: at most 16 MiB.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub initial_stream_window_size: Option<u32>,
    /// Initial connection-level window size in bytes (hyper
    /// `initial_connection_window_size`). Absent: process default
    /// (4 MiB via `DWARA_H2_CONNECTION_WINDOW_KIB`). Bounds: at
    /// most 64 MiB.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub initial_connection_window_size: Option<u32>,
    /// Enable adaptive flow-control window (hyper
    /// `adaptive_window`). Absent: false. When true, the
    /// connection window grows and shrinks based on throughput,
    /// which helps streaming workloads on high-BDP paths.
    #[serde(default, skip_serializing_if = "is_false")]
    pub adaptive_window: bool,
    /// Maximum number of concurrent streams per connection (hyper
    /// `max_concurrent_streams`). Absent: process default (128 via
    /// `DWARA_H2_MAX_CONCURRENT_STREAMS`). Bounds: at most 1_000_000.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_concurrent_streams: Option<u32>,
}

fn default_listener_protocol() -> ListenerProtocol {
    ListenerProtocol::Http
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ListenerProtocol {
    Http,
    Https,
    /// HTTP/3 (QUIC) ingress (DW-088). A UDP socket is bound on the
    /// listener's address:port; the QUIC handshake uses the `tls`
    /// block's certificates (terminate mode only — passthrough is
    /// rejected). Compiled into every build (no cargo feature; QUIC
    /// via the unconditional `quinn`/`h3` deps). The `alt_svc` field on
    /// sibling H1/H2 listeners advertises this listener's H3 port to
    /// clients for protocol upgrade discovery.
    H3,
    /// L4 TCP proxying (DW-103). A raw TCP socket is bound on the
    /// listener's address:port; accepted connections are spliced
    /// byte-for-byte to an upstream endpoint (optionally selected by
    /// peeking the TLS ClientHello SNI, reusing the SNI extraction
    /// from DW-008 TLS passthrough). Compiled into every build (no
    /// cargo feature). The `l4` block configures the
    /// upstream and SNI-routing flag.
    Tcp,
    /// L4 UDP proxying (DW-103). A UDP socket is bound on the
    /// listener's address:port; datagrams are forwarded to an upstream
    /// endpoint. STUBBED: the UDP dispatcher returns Unimplemented --
    /// UDP session semantics and NAT timeouts are a follow-up. Compiled
    /// into every build (no cargo feature). The `l4` block configures
    /// the upstream.
    Udp,
}

/// TLS handling for a listener: terminate at the edge or pass through.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ListenerTls {
    #[serde(default = "default_tls_mode")]
    pub mode: TlsMode,
    /// Path to the PEM certificate chain (termination mode only). Serves as
    /// the default/fallback certificate when `certificates` is also set.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub cert_file: Option<String>,
    /// Path to the PEM private key (termination mode only).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub key_file: Option<String>,
    /// Additional SNI-scoped certificate pairs (termination mode only).
    /// Each entry serves the listed `server_names`; the single
    /// cert_file/key_file pair (if present) is the fallback for unmatched
    /// or absent SNI. With no single pair, the first entry is the fallback.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub certificates: Vec<TlsCertificate>,
    /// SNI routing rules for passthrough mode: each entry maps its
    /// `server_names` to an upstream (by name) that receives the raw TLS
    /// bytes. Rejected in terminate mode.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub sni_routes: Vec<SniRoute>,
    /// PEM file of CA certificates that CLIENT certificates must chain
    /// to (#124, termination mode only). When set, the listener
    /// REQUESTS a client certificate and verifies any presented one
    /// against this bundle; a connection without a certificate is still
    /// accepted (other credential families apply) — the verified
    /// certificate is matched against consumers' `mtls` credentials to
    /// resolve an identity, and an UNVERIFIED certificate fails the
    /// handshake (mTLS authn never sees it). Rejected in passthrough
    /// mode (the TLS layer is not terminated, so client certificates
    /// cannot be verified). The file must exist and be readable at
    /// config compile time; validation names this field otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub client_ca_file: Option<String>,
    /// 0-RTT (early data) policy for HTTP/3 listeners (DW-088). When
    /// `accept`, the QUIC handshake accepts 0-RTT early data from
    /// clients with a saved session ticket — at the cost of replay
    /// risk. Non-idempotent requests (POST, PUT, PATCH, DELETE) are
    /// rejected under 0-RTT with a 425 Too Early response (the client
    /// retries over a 1-RTT connection). When `reject` (the default),
    /// 0-RTT early data is refused and the client must complete a
    /// full 1-RTT handshake before sending a request. Only meaningful
    /// on `protocol: h3` listeners; ignored (and rejected by
    /// validation) on H1/H2 listeners.
    #[serde(default, skip_serializing_if = "is_default_zero_rtt")]
    pub zero_rtt: ZeroRttPolicy,
    /// DW-105: opt in to post-quantum hybrid key exchange
    /// (X25519+ML-KEM) for this listener. When `true`, the
    /// X25519+ML-KEM hybrid kx group is
    /// prepended to the rustls provider's kx group list, PREFERRING
    /// the hybrid group while keeping the classical X25519 fallback
    /// for non-PQ clients. Compiled into every build (no cargo
    /// feature). EXPERIMENTAL: the rustls PQ
    /// API is not yet stable. Rejected when combined with FIPS mode
    /// (ML-KEM is not on the FIPS-validated list for aws-lc-rs).
    /// Terminate mode only (passthrough does not terminate TLS, so
    /// the kx group list is irrelevant); validation rejects `pq: true`
    /// on a passthrough listener.
    #[serde(default, skip_serializing_if = "is_false")]
    pub pq: bool,
    /// SEC-02: ACME / Let's Encrypt automation. When present, the
    /// gateway automatically obtains and renews certificates for the
    /// configured domains from the ACME directory. Terminates mode
    /// only (passthrough does not terminate TLS). When `acme` is
    /// present, `cert_file`/`key_file`/`certificates` are optional
    /// (ACME-managed certs serve as the fallback); manual certs still
    /// take precedence for their SNI names. See [`AcmeConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub acme: Option<AcmeConfig>,
}

/// SEC-02: ACME (Let's Encrypt) certificate automation configuration.
/// The gateway acts as an ACME client: orders certificates for the
/// configured domains, completes the challenge (HTTP-01 or TLS-ALPN-01),
/// and installs the issued certificates into the hot-reloadable TLS
/// termination/SNI resolver. Renewal runs automatically before expiry.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AcmeConfig {
    /// The domains to obtain certificates for. At least one must be
    /// present (validation rejects an empty list).
    pub domains: Vec<String>,
    /// The ACME directory URL. Defaults to Let's Encrypt production
    /// (`https://acme-v02.api.letsencrypt.org/directory`). Set to the
    /// staging directory (`https://acme-staging-v02.api.letsencrypt.org/directory`)
    /// for testing to avoid rate limits.
    #[serde(
        default = "default_acme_directory",
        skip_serializing_if = "is_default_acme_directory"
    )]
    pub directory_url: String,
    /// Contact email addresses registered with the ACME account. Let's
    /// Encrypt requires at least one for production issuance.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub contact: Vec<String>,
    /// Challenge type: `http-01` (serves a token over HTTP on port 80)
    /// or `tls-alpn-01` (serves a challenge cert over TLS-ALPN on port
    /// 443). Default `tls-alpn-01` (no separate HTTP listener needed).
    #[serde(
        default = "default_acme_challenge",
        skip_serializing_if = "is_default_acme_challenge"
    )]
    pub challenge: AcmeChallenge,
    /// Use the staging directory instead of production. When true,
    /// `directory_url` is overridden to the Let's Encrypt staging
    /// endpoint. Staging certs are NOT trusted by browsers — use for
    /// testing only. Default false.
    #[serde(default, skip_serializing_if = "is_false")]
    pub staging: bool,
    /// Path to the directory where ACME state is persisted (account
    /// key, issued certificates). The gateway must have read/write
    /// access. Defaults to `./acme-state`.
    #[serde(
        default = "default_acme_state_dir",
        skip_serializing_if = "is_default_acme_state_dir"
    )]
    pub state_dir: String,
}

/// ACME challenge type.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "kebab-case")]
pub enum AcmeChallenge {
    /// HTTP-01 challenge: serves a token over HTTP on port 80. Requires
    /// a separate HTTP listener bound to port 80 (or port forwarding).
    Http01,
    /// TLS-ALPN-01 challenge: serves a challenge certificate over TLS
    /// with the `acme-tls/1` ALPN protocol on port 443. No separate
    /// listener needed (the default). Default.
    #[default]
    TlsAlpn01,
}

fn default_acme_directory() -> String {
    "https://acme-v02.api.letsencrypt.org/directory".to_string()
}

fn is_default_acme_directory(s: &str) -> bool {
    s == default_acme_directory()
}

fn default_acme_challenge() -> AcmeChallenge {
    AcmeChallenge::TlsAlpn01
}

fn is_default_acme_challenge(c: &AcmeChallenge) -> bool {
    *c == AcmeChallenge::TlsAlpn01
}

fn default_acme_state_dir() -> String {
    "./acme-state".to_string()
}

fn is_default_acme_state_dir(s: &str) -> bool {
    s == default_acme_state_dir()
}

fn is_default_zero_rtt(p: &ZeroRttPolicy) -> bool {
    *p == ZeroRttPolicy::Reject
}

/// 0-RTT (early data) acceptance policy for HTTP/3 (DW-088).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "lowercase")]
pub enum ZeroRttPolicy {
    /// Accept 0-RTT early data. Non-idempotent requests are rejected
    /// with 425 Too Early (replay-safe).
    Accept,
    /// Reject 0-RTT early data (default). The client must complete a
    /// full 1-RTT handshake before sending a request.
    #[default]
    Reject,
}

/// One SNI-scoped certificate pair for TLS termination.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct TlsCertificate {
    /// Server names (SNI values) this certificate answers. Exact match,
    /// case-insensitive per rustls.
    pub server_names: Vec<String>,
    /// Path to the PEM certificate chain.
    pub cert_file: String,
    /// Path to the PEM private key.
    pub key_file: String,
}

/// One SNI-to-upstream routing rule for TLS passthrough.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SniRoute {
    /// Server names (SNI values) routed to `upstream`. Exact match.
    pub server_names: Vec<String>,
    /// Name of the upstream that receives the spliced TLS stream.
    pub upstream: String,
}

/// L4 proxying configuration for a `tcp` or `udp` listener (DW-103).
///
/// The listener accepts raw L4 connections and splices them byte-for-byte
/// to an upstream endpoint. When `sni_routing` is true (TCP only), the
/// dispatcher peeks the TLS ClientHello SNI (reusing the SNI extraction
/// from DW-008 TLS passthrough) and selects the upstream from the
/// listener's `tls.sni_routes` -- the same routing table passthrough
/// uses. When `sni_routing` is false, the configured `upstream` receives
/// every connection.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct L4Config {
    /// Name of the upstream that receives the spliced stream. Required
    /// when `sni_routing` is false; when `sni_routing` is true the
    /// upstream is selected per-connection from `tls.sni_routes`, and
    /// this field is the fallback for connections with no SNI or an
    /// unmatched name (absent = close the connection on no match).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub upstream: Option<String>,
    /// Peek the TLS ClientHello SNI and route the connection to the
    /// upstream matched by the listener's `tls.sni_routes` (reusing the
    /// SNI extraction from DW-008 TLS passthrough). TCP only; rejected
    /// on UDP listeners by validation (UDP has no byte-stream handshake
    /// to peek). When false, every connection is spliced to the
    /// configured `upstream`.
    #[serde(default, skip_serializing_if = "is_false")]
    pub sni_routing: bool,
    /// Idle timeout in seconds for an established splice. When neither
    /// side sends data for this duration, the splice is closed. Absent
    /// (or 0) means no idle timeout (the splice runs until either side
    /// closes). Bounded by validation to at most 1 hour.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub idle_timeout_s: Option<u64>,
    /// DP-01 (#234): UDP session idle timeout in seconds. A UDP session
    /// (per-client upstream socket) that receives no datagrams for this
    /// duration is evicted from the session table. Default 30s. UDP
    /// only; ignored for TCP listeners.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_timeout_s: Option<u64>,
    /// DP-01 (#234): maximum concurrent UDP sessions. When the session
    /// table is full, the oldest idle session is evicted (LRU). Default
    /// 4096. UDP only; ignored for TCP listeners.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_sessions: Option<usize>,
}

fn default_tls_mode() -> TlsMode {
    TlsMode::Terminate
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum TlsMode {
    Terminate,
    Passthrough,
}

/// Match rules (path/host/method/header) plus action and attached policies.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Route {
    pub name: String,
    /// Name of the service this route targets.
    pub service: String,
    pub r#match: RouteMatch,
    pub action: RouteAction,
    /// Attached policy names. All applicable levels' rules AND together
    /// (see the rate-limiter module docs); the resolution order is
    /// consumer > route > service > listener > global.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<String>,
    /// Request priority class for load shedding (DW-016): 0 (lowest) to 10
    /// (highest); absent means the default 5. When the gateway concurrency
    /// cap is saturated, requests at `high_priority` (>= 8) draw from a
    /// small reserved sub-allowance of the cap that lower-priority traffic
    /// cannot use (see `proxy` module docs); preemption is impossible, so
    /// normal traffic is shed first rather than displaced. Validation
    /// rejects values above 10.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub priority: Option<u8>,
    /// Require authenticated requests (DW-019): a request that arrives
    /// WITHOUT a recognized credential (or with an invalid one) is
    /// rejected with 401 and a `WWW-Authenticate` challenge. Absent
    /// (the default) allows anonymous traffic through; note that an
    /// INVALID presented credential is always rejected with 401
    /// regardless of this flag.
    #[serde(default, skip_serializing_if = "is_false")]
    pub auth_required: bool,
    /// Route-scoped CORS policy (DW-027, feature analysis 4.14): controls
    /// how the gateway answers browser cross-origin requests on this
    /// route. When present, a CORS PREFLIGHT (`OPTIONS` carrying both
    /// `Origin` and `Access-Control-Request-Method`) is answered by the
    /// gateway itself, before authentication and never forwarded
    /// upstream; actual (non-preflight) responses carry the policy's
    /// CORS headers. Non-CORS requests are untouched. A preflight on a
    /// route whose `match.methods` list excludes `OPTIONS` never matches
    /// the route (the documented request-path order applies first) —
    /// include `OPTIONS` in the method list of CORS routes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cors: Option<Cors>,
    /// Route-scoped response compression (DW-027, feature analysis 4.13):
    /// negotiates gzip/brotli/zstd against the request's `Accept-Encoding`
    /// and compresses the response body per policy. Streaming-safe: the
    /// body is compressed chunk-by-chunk with a per-chunk flush, never
    /// buffered whole. Disabled (absent) by default — the dataplane
    /// forwards bytes untouched.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub compression: Option<Compression>,
    /// Route-scoped request size limits (DW-027, feature analysis 4.16):
    /// per-route body and header caps enforced after route resolution.
    /// Over-limit requests are rejected by the gateway with the JSON
    /// error envelope (413 for bodies, 431 for headers) before any
    /// upstream contact when the size is declared up front
    /// (`Content-Length`); streaming bodies of unknown length are
    /// aborted as soon as they cross the cap.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limits: Option<RequestLimits>,
    /// Route-level authorization rules (DW-020, feature analysis 4.7).
    /// Absent (the default) imposes no authorization on the route. A
    /// PRESENT-but-entirely-empty block (no consumers, groups, scopes,
    /// claims, or `ip_acl`) is likewise a no-op at evaluation time —
    /// it imposes nothing, exactly like an absent one — but it is
    /// always a config-authoring mistake (a rule block with no rules),
    /// so validation REJECTS it: omit the block instead of emptying it.
    /// When present (and non-empty), the rules are evaluated after
    /// authentication and BEFORE
    /// rate limiting; see [`Authz`] for the rule semantics. Presence of
    /// any identity rule implies authentication (an anonymous request is
    /// rejected 401); an `ip_acl`-only block is the one case that can
    /// permit anonymous access (from an allowed IP). Precedence across
    /// levels (consumer > route > service > listener > global) is
    /// resolved by the `authz` module's resolver; every level has a
    /// config attachment point (`consumers[].authorization`,
    /// `services[].authorization`, `listeners[].authorization`, and the
    /// gateway-level `authorization`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authorization: Option<Authz>,
    /// API deprecation policy (DW-048): emits the standard deprecation
    /// signal headers on this route's responses. See [`Deprecation`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub deprecation: Option<Deprecation>,
    /// Route maintenance mode (DW-041): when present, every request the
    /// route matches is answered by the GATEWAY with a 503 carrying
    /// `Retry-After` and the JSON error envelope (`maintenance` code) —
    /// before route limits, CORS preflight handling (preflights
    /// themselves are exempt, see [`Maintenance`]), authentication, and
    /// the route action (proxy, redirect, and respond actions alike
    /// never run). Toggled by config reload like every route field:
    /// publish a generation with the block to enter maintenance and one
    /// without it to leave. See [`Maintenance`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub maintenance: Option<Maintenance>,
    /// Request/response transforms (DW-028, feature analysis 4.12):
    /// header and query manipulation on the forwarded request and the
    /// route's responses, plus the size-capped JSON-pointer body
    /// transform — the transforms surface's ONE explicitly buffering
    /// piece. Absent (the default): bytes and headers flow untouched.
    /// See [`Transforms`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub transforms: Option<Transforms>,
    /// Security-header injection (DW-028, feature analysis 5-Security):
    /// HSTS, `X-Content-Type-Options: nosniff`,
    /// `Content-Security-Policy`, and `X-Frame-Options`, stamped on
    /// EVERY response the route emits (action responses and gateway
    /// short-circuits alike), replacing any upstream-sent values — the
    /// gateway is the source of truth at its edge. See
    /// [`SecurityHeaders`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub security_headers: Option<SecurityHeaders>,
    /// Opt out of the gateway-level `default_security_headers`
    /// baseline (SEC-09, #213): when true, a route with no
    /// `security_headers` block ships WITHOUT the gateway's default
    /// security headers. A route that carries its own
    /// `security_headers` block always uses it (the block fully
    /// replaces the default); this flag is for the rare route that
    /// deliberately needs no security headers at all. Default:
    /// false (inherit the default when present).
    #[serde(default, skip_serializing_if = "is_false")]
    pub security_headers_opt_out: bool,
    /// Response field masking (DW-029, feature analysis 5-Security):
    /// redacts the named RFC 6901 JSON pointers from the route's
    /// responses — the floor `fields` for every consumer, plus the
    /// `groups` additions for members of each consumer group — before
    /// any other body-handling stage. The redaction is fail-closed: a
    /// response the gateway cannot prove clean (encoded, non-JSON,
    /// over the cap, unparseable, or missing a configured pointer)
    /// answers 502, never a passthrough. See [`Masking`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub masking: Option<Masking>,
    /// Route-scoped response caching (DW-037, feature analysis
    /// 5-Protocol): opts the route's cacheable GET traffic into the
    /// local response cache behind the `CacheStore` extension seam.
    /// Absent (the default): responses are never cached or buffered.
    /// The cache key folds in the route, the consumer, the inbound
    /// path + query, and the effective vary set — masked (DW-029) and
    /// consumer-group-specific variants never cross consumers. Stored
    /// bodies are the POST-masking/transform bytes (replay consistency
    /// under route-scoped policies), stored identity (never compressed;
    /// compression re-negotiates per request), and the decoration tail
    /// (compression onward) re-runs on every replay. See
    /// [`RouteCache`] and `dataplane::response_cache`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache: Option<RouteCache>,
    /// Per-route METHOD ALLOWLIST (DW-030): when non-empty, a request
    /// that resolved this route but whose method is not in the list is
    /// answered by the gateway with `405 Method Not Allowed` plus an
    /// `Allow` header listing the configured methods (RFC 9110 10.2.1).
    /// Distinct from `match.methods`, which gates ROUTE RESOLUTION (a
    /// miss falls through to 404 / other routes); this list gates the
    /// ALREADY-matched route. Placement (frozen): after route
    /// resolution and the maintenance 503, before the route limits and
    /// CORS preflight short-circuit and authentication — the allowlist
    /// is a statement about the route, not the request's shape (the
    /// DW-041 maintenance ordering argument), and a CORS PREFLIGHT
    /// (`OPTIONS` + preflight markers) is exempt exactly like the
    /// maintenance 503 (the preflight asks about the GATEWAY's
    /// cross-origin policy, not the resource; failing it would hide the
    /// CORS answer from the browser). Matching is case-insensitive, the
    /// same comparison `match.methods` uses. HEAD is NOT implicitly
    /// granted by GET — a route supporting HEAD alongside GET lists
    /// both (the allowlist is exhaustive by design; implicit grants
    /// would leak methods the operator never named). Empty (the
    /// default) allows every method, exactly like pre-DW-030.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub methods: Vec<String>,
    /// Service-level objectives (DW-052, feature analysis 4.17): the
    /// route's availability target and optional latency objective,
    /// exported as `dwara_slo_burn_rate` / `dwara_slo_target` metrics
    /// over process-local 5m and 1h sliding windows for multiwindow
    /// burn-rate alerting. Availability counts a request BAD only when
    /// the GATEWAY answers 5xx (client errors are the caller's policy,
    /// not this route's availability). Absent (the default): the route
    /// records nothing and exports no SLO series. See [`RouteSlo`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub slo: Option<RouteSlo>,
    /// WebSocket policy (DW-039, feature analysis 4.13): origin
    /// allowlisting before an upgrade is offered and post-upgrade
    /// frame-rate policing on the tunneled connection. Absent (the
    /// default): upgrades are transparent — any origin, unlimited
    /// frame rate, the generic 101 tunnel unchanged. See
    /// [`RouteWebsocket`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub websocket: Option<RouteWebsocket>,
    /// WAF-lite heuristic filtering (DW-051): pattern-matching
    /// inspection of the request path, query string, selected
    /// headers, and body (when JSON or form-urlencoded) for common
    /// SQL-injection, XSS, and path-traversal signatures. Absent (the
    /// default): no inspection. When `enabled` is true, the WAF runs
    /// after the route method allowlist and before the route limits —
    /// a content filter that rejects malicious requests before any
    /// resource is spent on auth or rate limiting. `dry_run` evaluates
    /// and logs matches without blocking (audit-log-only mode). See
    /// [`RouteWaf`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub waf: Option<RouteWaf>,
    /// GraphQL awareness (DW-099): query depth/complexity limits and
    /// optional persisted-query enforcement for routes that front a
    /// GraphQL server. When enabled, the gateway rejects abusive
    /// queries before the route limits and authentication. Absent
    /// (the default): no GraphQL checks. Compiled into every build
    /// (no cargo feature). See [`RouteGraphql`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub graphql: Option<RouteGraphql>,
    /// gRPC-Web framing translation + JSON-to-gRPC transcoding (DW-101):
    /// when enabled, the gateway translates gRPC-Web framing to native
    /// gRPC for the upstream and wraps the response back. When
    /// transcoding is enabled, JSON requests are translated to/from
    /// protobuf using .proto descriptors supplied via config. Absent
    /// (the default): no translation. The block parses and validates in
    /// every build (no cargo feature); the runtime translation is
    /// scaffolded and not yet dispatched from the request path. See
    /// [`GrpcWeb`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub grpc_web: Option<GrpcWeb>,
    /// Protocol translation (DW-100): translates the request/response
    /// bodies between two wire protocols on this route's forward and
    /// response paths. When enabled, the gateway converts the client's
    /// body to the upstream's wire format and the upstream's response
    /// back to the client's wire format. Absent (the default): no
    /// translation. The block parses and validates in every build (no
    /// cargo feature); the runtime translation is scaffolded and not
    /// yet dispatched from the request path.
    /// See [`Translation`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub translation: Option<Translation>,
    /// Request validation (DW-047): an optional JSON-schema block the
    /// gateway validates the request body against before the route
    /// action runs. A mismatch answers 400 `validation_failed` with the
    /// offending paths in the JSON error envelope; a match proceeds to
    /// the action (proxy, mock, ...). This is a SIMPLER surface than
    /// full OpenAPI parameter/header/query validation — it covers the
    /// body only, the common case for write endpoints. The schema is a
    /// minimal JSON-Schema subset (type, required, properties, items,
    /// enum, minimum, maximum, minLength, maxLength); `$ref` is not
    /// supported. See [`RequestValidation`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub request_validation: Option<RequestValidation>,
    /// OpenAPI import metadata (DW-047): when this route was generated
    /// by `dwara import openapi`, this block records the source
    /// operation's `operationId`, `summary`, and `tags` for
    /// traceability. It has no runtime effect — the gateway ignores it
    /// — but it survives round-trips so the operator can audit which
    /// spec operation a route came from. Absent for hand-authored
    /// routes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub openapi: Option<OpenApiMeta>,
    /// Shadow traffic mirroring (DW-062): fire-and-forget duplicate
    /// requests to a mirror upstream. The mirror response is discarded
    /// and never impacts the primary request's latency. A percentage
    /// controls sampling (0 = never, 100 = always). Absent (the
    /// default): no mirroring. See [`MirrorConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mirror: Option<MirrorConfig>,
    /// Fault injection (DW-062): percentage-based delays and aborts for
    /// chaos testing. A delay injects a fixed latency before the
    /// request is forwarded; an abort short-circuits with a configured
    /// status without contacting the upstream. Both are sampled by
    /// percentage (0 = never, 100 = always). Absent (the default): no
    /// fault injection. See [`FaultInjection`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fault_injection: Option<FaultInjection>,
    /// Plugin names to run on this route (DW-055). Each name must
    /// reference a plugin defined in the top-level `plugins` list.
    /// Plugins run in declaration order at their declared phases
    /// (request-path dispatch, DW-157). Routes without plugins take
    /// the untouched fast path.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub plugins: Vec<String>,
    /// SCALE-12 (#191): per-route filter-chain ordering and dry-run
    /// overrides. When absent, the global `filter_chain` config (or
    /// the default order) applies. See [`FilterChainConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub filter_chain: Option<FilterChainConfig>,
    /// SEC-05: OIDC browser login flow as a route auth mode. When
    /// present, the gateway acts as an OIDC relying party: unauthenticated
    /// browser requests are redirected to the IdP's authorization
    /// endpoint, and the callback (`redirect_uri`) exchanges the
    /// authorization code for tokens, sets a session cookie, and
    /// redirects the user back to the original URL. Subsequent requests
    /// carry the session cookie (validated by the gateway). Absent (the
    /// default): no browser login flow (the route uses its normal auth
    /// mode). See [`OidcLoginConfig`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub oidc_login: Option<OidcLoginConfig>,
}

/// SEC-05: OIDC browser login flow configuration for a route. The
/// gateway redirects unauthenticated browser requests to the IdP,
/// exchanges the authorization code for tokens, sets a session cookie,
/// and validates the cookie on subsequent requests.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OidcLoginConfig {
    /// The OIDC provider name (must match an entry in
    /// `gateway.oidc_providers`).
    pub provider: String,
    /// The redirect URI the IdP sends the authorization code to. This
    /// must be a path on the gateway (e.g. `/auth/callback`) and must
    /// be registered with the IdP. The gateway handles the callback
    /// automatically when this route is matched.
    pub redirect_uri: String,
    /// The session cookie name. Default `dwara_session`. The cookie is
    /// `HttpOnly`, `Secure` (when the listener is TLS), `SameSite=Lax`,
    /// and carries a signed session ID.
    #[serde(
        default = "default_oidc_session_cookie",
        skip_serializing_if = "is_default_oidc_session_cookie"
    )]
    pub session_cookie: String,
    /// Session lifetime in seconds (default 3600 = 1 hour). After this
    /// duration the cookie expires and the user must re-authenticate.
    #[serde(
        default = "default_oidc_session_ttl_s",
        skip_serializing_if = "is_default_oidc_session_ttl_s"
    )]
    pub session_ttl_s: u64,
    /// The post-logout redirect URL. When the user visits the logout
    /// path (the redirect URI with `/logout` appended, e.g.
    /// `/auth/callback/logout`), the session cookie is cleared and the
    /// user is redirected to this URL. Default: the IdP's
    /// `end_session_endpoint` (from discovery) with
    /// `post_logout_redirect_uri` set to the gateway's root.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub post_logout_url: Option<String>,
}

fn default_oidc_session_cookie() -> String {
    "dwara_session".to_string()
}

fn is_default_oidc_session_cookie(s: &str) -> bool {
    s == default_oidc_session_cookie()
}

fn default_oidc_session_ttl_s() -> u64 {
    3600
}

fn is_default_oidc_session_ttl_s(v: &u64) -> bool {
    *v == 3600
}

/// OpenAPI import metadata attached to a route (DW-047). No runtime
/// effect; purely for traceability from the generated config back to
/// the source spec operation.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OpenApiMeta {
    /// The `operationId` from the source OpenAPI operation (may be
    /// absent if the operation had none — the route name is then a
    /// path+method fallback).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub operation_id: Option<String>,
    /// The `summary` from the source OpenAPI operation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub summary: Option<String>,
    /// The `tags` from the source OpenAPI operation.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// The HTTP method of the source operation (uppercased).
    pub method: String,
    /// The path template from the source OpenAPI spec (e.g.
    /// `/pets/{id}`).
    pub path: String,
}

/// Shadow traffic mirroring configuration (DW-062,
/// `routes[].mirror`). Fire-and-forget duplicate requests to a named
/// mirror upstream; the mirror response is discarded and never impacts
/// the primary request's latency. A percentage controls sampling.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct MirrorConfig {
    /// Name of the upstream to receive mirrored (shadow) requests. The
    /// mirror upstream is separate from the route's service upstream —
    /// it exists solely to receive shadow traffic. The upstream must
    /// exist in the `upstreams` list.
    pub upstream: String,
    /// Percentage of requests to mirror (0..=100). 0 mirrors nothing;
    /// 100 mirrors every request. The sampling is per-request (a
    /// random draw against this percentage).
    pub percentage: u8,
    /// Hard timeout for the mirror request in milliseconds. If the
    /// mirror upstream does not respond within this duration, the
    /// mirror request is abandoned. Default 2000 (2 seconds). The
    /// mirror is fire-and-forget, so this timeout never affects the
    /// primary request.
    #[serde(
        default = "default_mirror_timeout_ms",
        skip_serializing_if = "is_default_mirror_timeout_ms"
    )]
    pub timeout_ms: u64,
}

fn default_mirror_timeout_ms() -> u64 {
    2000
}

fn is_default_mirror_timeout_ms(v: &u64) -> bool {
    *v == 2000
}

/// Fault injection configuration (DW-062, `routes[].fault_injection`).
/// Percentage-based delays and aborts for chaos testing. A delay
/// injects a fixed latency before the request is forwarded; an abort
/// short-circuits with a configured status without contacting the
/// upstream. Both may be present simultaneously — the abort is
/// evaluated first, and if it does not fire, the delay is applied.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FaultInjection {
    /// Abort injection: return a configured status without forwarding.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub abort: Option<FaultAbort>,
    /// Delay injection: inject a fixed delay before forwarding.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub delay: Option<FaultDelay>,
}

/// Abort fault injection (DW-062): short-circuit the request with a
/// configured HTTP status, sampled by percentage.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FaultAbort {
    /// Percentage of requests to abort (0..=100).
    pub percentage: u8,
    /// HTTP status code to return (100..=599).
    pub status: u16,
}

/// Delay fault injection (DW-062): inject a fixed delay before
/// forwarding the request, sampled by percentage.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FaultDelay {
    /// Percentage of requests to delay (0..=100).
    pub percentage: u8,
    /// Fixed delay in milliseconds (1..=300000, i.e. up to 5 minutes).
    pub fixed_ms: u64,
}

/// Route-scoped request-body validation (DW-047,
/// `routes[].request_validation`).
///
/// A minimal JSON-Schema subset the gateway validates the request body
/// against before the route action runs. A mismatch answers 400
/// `validation_failed` (the JSON error envelope carries the offending
/// instance paths); a match proceeds normally. The schema is compiled
/// at config publish time (an invalid schema fails validation); the
/// body is buffered up to the route's `limits.max_body_bytes` (or a
/// 1 MiB default when no limit is set) for validation, then replayed
/// to the action. See [`JsonSchema`] for the supported keywords.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RequestValidation {
    /// The JSON Schema the request body must satisfy. A minimal subset
    /// of JSON Schema Draft 2020-12 is supported: `type`, `required`,
    /// `properties`, `items`, `enum`, `minimum`, `maximum`,
    /// `minLength`, `maxLength`, and `additionalProperties` (bool or a
    /// schema). `$ref` is NOT supported (inline your schemas). An
    /// invalid schema fails config validation at publish time.
    pub body_schema: BodySchema,
    /// SEC-14: dry-run mode. When true, the gateway evaluates the
    /// schema and records violations (log + metric) but does NOT reject
    /// the request — the body is forwarded to the upstream even when it
    /// fails validation. Useful for rolling out a new schema without
    /// breaking existing callers. Default false (reject on mismatch).
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
}

/// A minimal JSON-Schema subset (DW-047) for request-body validation.
///
/// Supports the keywords sufficient for typical OpenAPI-derived body
/// schemas: `type`, `required`, `properties`, `items`, `enum`,
/// `minimum`, `maximum`, `minLength`, `maxLength`, and
/// `additionalProperties`. Nested objects and arrays compose
/// recursively. Unknown keywords are IGNORED (forward compatibility
/// with richer specs) EXCEPT at the root `RequestValidation.body_schema`
/// where `deny_unknown_fields` on the surrounding config struct already
/// rejects typos in the wrapper; this struct itself is permissive so a
/// real-world schema carrying `description`, `example`, or `$schema`
/// does not fail to parse.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
pub struct BodySchema {
    /// The JSON type: `object`, `array`, `string`, `number`,
    /// `integer`, `boolean`, or `null`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub r#type: Option<String>,
    /// For `object`: the required property names.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub required: Vec<String>,
    /// For `object`: named property schemas.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub properties: std::collections::BTreeMap<String, BodySchema>,
    /// For `object`: `true` (default, allows extra properties), `false`
    /// (rejects any property not in `properties`), or a schema every
    /// extra property must satisfy.
    #[serde(
        default,
        skip_serializing_if = "Option::is_none",
        rename = "additionalProperties"
    )]
    pub additional_properties: Option<Box<AdditionalProperties>>,
    /// For `array`: the schema every element must satisfy.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub items: Option<Box<BodySchema>>,
    /// An enum of allowed values (compared by JSON equality).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub r#enum: Vec<serde_json::Value>,
    /// Inclusive numeric minimum (for `number`/`integer`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub minimum: Option<f64>,
    /// Inclusive numeric maximum (for `number`/`integer`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub maximum: Option<f64>,
    /// Minimum string length (for `string`).
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "minLength")]
    pub min_length: Option<u64>,
    /// Maximum string length (for `string`).
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "maxLength")]
    pub max_length: Option<u64>,
}

/// The `additionalProperties` keyword accepts either a boolean or a
/// nested schema; this union models both.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(untagged)]
pub enum AdditionalProperties {
    /// A boolean: `true` allows any extra property, `false` rejects
    /// any property not listed in `properties`.
    Bool(bool),
    /// A schema every extra property must satisfy.
    Schema(BodySchema),
}

/// Route-scoped WAF-lite config (DW-051, `routes[].waf`).
///
/// A lightweight, heuristic-based web application filter: regex pattern
/// matching for SQL injection, XSS, and path traversal signatures across
/// the request path, query string, selected headers (User-Agent, Referer,
/// Cookie, X-Forwarded-For), and body (when the content type is JSON or
/// form-urlencoded, up to `max_body_inspect_bytes`). This is NOT a full
/// WAF — it is a first-line traffic filter that rejects obvious attack
/// signatures before authentication or rate limiting. Per-route opt-in;
/// routes without a `waf` block are never inspected.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RouteWaf {
    /// Master switch. Default false: the WAF block is inert even when
    /// present (allows staged rollout). When true, the configured
    /// filter categories run on every request the route matches.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Audit-log-only mode (dry-run synergy, DW-041): when true, the
    /// WAF evaluates every filter and LOGS matches (a `dwara::policy`
    /// warn event + the `dwara_waf_total{outcome="logged"}` counter)
    /// but does NOT block — the request continues to the upstream.
    /// Lets an operator observe what the WAF would catch before
    /// enforcing it. Default false: matches are blocked with 403.
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
    /// Which filter categories to run. An empty or absent list
    /// defaults to all three (`sqli`, `xss`, `path_traversal`).
    /// Validation rejects an enabled WAF with an explicit non-empty
    /// list containing an unknown category name.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub filters: Vec<String>,
    /// Maximum number of body bytes to inspect (0 = do not inspect
    /// the body at all; 1..=1048576 = inspect up to this many bytes).
    /// Default 131072 (128 KiB). Bodies larger than this limit are
    /// inspected only up to the limit (a malicious payload beyond the
    /// limit is not caught — the trade-off for a bounded inspection
    /// cost). Validation rejects values > 1048576 (1 MiB).
    #[serde(
        default = "default_waf_max_body_inspect_bytes",
        skip_serializing_if = "is_default_waf_max_body_inspect_bytes"
    )]
    pub max_body_inspect_bytes: u64,
    /// Optional custom regex pattern overrides (additional patterns
    /// appended to the built-in signatures for each filter category).
    /// Each entry is a regex string compiled at config publish time;
    /// an invalid regex fails validation. When absent, only the
    /// built-in signatures are used.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub custom_patterns: Vec<String>,
}

fn default_waf_max_body_inspect_bytes() -> u64 {
    131_072
}

fn is_default_waf_max_body_inspect_bytes(v: &u64) -> bool {
    *v == 131_072
}

/// SEC-08 (#212): A single OWASP CRS-compatible WAF rule. Each rule
/// has a numeric ID (CRS convention: 9xxxx), a severity level, a
/// phase (1 = request headers, 2 = request body), a list of tags, a
/// regex pattern, and the inspection targets to apply the pattern
/// to. Rules are evaluated in order; matching rules add their
/// severity to the request's anomaly score. The request is blocked
/// when the score exceeds the configured threshold.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CrsRule {
    /// Unique rule ID (CRS convention: 9xxxx). Used for exclusions
    /// and logging.
    pub id: u32,
    /// Rule severity: 1 = critical, 2 = warning, 3 = notice, 4 = info.
    /// Higher severity contributes more to the anomaly score.
    #[serde(default = "default_crs_severity")]
    pub severity: u8,
    /// Evaluation phase: 1 = request headers (path, query, headers),
    /// 2 = request body. Default 1.
    #[serde(default = "default_crs_phase")]
    pub phase: u8,
    /// Tags for grouping and exclusion (e.g. "OWASP_CRS", "SQL_INJECTION").
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tags: Vec<String>,
    /// The regex pattern to match against the target values.
    pub pattern: String,
    /// Which request parts to inspect: "path", "query", "header",
    /// "headers" (all selected headers), "body". Default: ["path", "query"].
    #[serde(default = "default_crs_targets")]
    pub targets: Vec<String>,
    /// Optional list of transformations to apply before matching
    /// (e.g. "lowercase", "url_decode", "html_entity_decode"). Default: [].
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub transformations: Vec<String>,
}

fn default_crs_severity() -> u8 {
    2
}

fn default_crs_phase() -> u8 {
    1
}

fn default_crs_targets() -> Vec<String> {
    vec!["path".into(), "query".into()]
}

/// SEC-08 (#212): Global WAF policy with CRS-compatible rules. When
/// enabled, the rules are evaluated on every request (regardless of
/// route-level WAF config). The anomaly score is accumulated across
/// all matching rules; the request is blocked when the score exceeds
/// the threshold. Rule exclusions can disable specific rules by ID or
/// tag. The paranoia level controls which rules are active (1 =
/// default, 2 = more aggressive, 3 = paranoid, 4 = very paranoid).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GlobalWaf {
    /// Master switch. Default false.
    #[serde(default = "default_false", skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Audit-log-only mode (same semantics as RouteWaf::dry_run).
    #[serde(default = "default_false", skip_serializing_if = "is_false")]
    pub dry_run: bool,
    /// Paranoia level (1-4). Rules with a higher paranoia level than
    /// this are skipped. Default 1.
    #[serde(
        default = "default_crs_paranoia",
        skip_serializing_if = "is_default_crs_paranoia"
    )]
    pub paranoia_level: u8,
    /// Anomaly score threshold for blocking. A request is blocked
    /// when the sum of matching rule severities reaches this value.
    /// Default 5 (critical rules block immediately, warnings need
    /// multiple hits).
    #[serde(
        default = "default_crs_threshold",
        skip_serializing_if = "is_default_crs_threshold"
    )]
    pub anomaly_threshold: u32,
    /// Maximum body bytes to inspect (same semantics as
    /// RouteWaf::max_body_inspect_bytes). Default 131072.
    #[serde(
        default = "default_waf_max_body_inspect_bytes",
        skip_serializing_if = "is_default_waf_max_body_inspect_bytes"
    )]
    pub max_body_inspect_bytes: u64,
    /// CRS-compatible rules to evaluate.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub rules: Vec<CrsRule>,
    /// Rule IDs to exclude (skip even if the rule is in the rules
    /// list). Useful for tuning false positives.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub exclude_rule_ids: Vec<u32>,
    /// Tags to exclude (skip all rules carrying any of these tags).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub exclude_tags: Vec<String>,
}

fn default_crs_paranoia() -> u8 {
    1
}

fn is_default_crs_paranoia(v: &u8) -> bool {
    *v == 1
}

fn default_crs_threshold() -> u32 {
    5
}

fn is_default_crs_threshold(v: &u32) -> bool {
    *v == 5
}

/// Route-scoped GraphQL awareness config (DW-099, `routes[].graphql`).
///
/// When enabled (compiled into every build; no cargo feature), the
/// gateway enforces query depth/complexity limits and optional
/// persisted-query enforcement on every request the route matches,
/// BEFORE the route limits and authentication. A query whose depth or
/// complexity exceeds the configured limits is rejected with 400
/// (`graphql_depth_exceeded` or `graphql_complexity_exceeded`); a
/// query whose SHA-256 hash is not in the persisted-query store is
/// rejected with 400 (`graphql_persisted_query_required`).
///
/// The check is compiled into every build (no cargo feature): a
/// config carrying the block behaves identically in any build.
///
/// Depth is the maximum brace-nesting level of the query (the
/// top-level operation body is depth 1). Complexity is the sum of
/// per-field costs: each field's cost is looked up in
/// `cost_per_field`, falling back to `complexity_coefficient` (default
/// 1) when the field name is not in the map.
///
/// Both are computed by a
/// bounded hand-rolled scanner (no external GraphQL parser dependency).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RouteGraphql {
    /// Master switch. Default false: the GraphQL block is inert even
    /// when present (allows staged rollout). When true, the depth and
    /// complexity checks run on every request the route matches.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// Maximum query depth (max brace-nesting level). A query whose
    /// depth exceeds this is rejected with 400
    /// `graphql_depth_exceeded`. Must be > 0 when the block is
    /// enabled (validation rejects 0 or absent). The top-level
    /// operation body is depth 1, so a value of 1 permits only a
    /// flat selection set with no nested fields.
    pub depth_limit: usize,
    /// Maximum query complexity (sum of per-field costs). A query
    /// whose complexity exceeds this is rejected with 400
    /// `graphql_complexity_exceeded`. Must be > 0 when the block is
    /// enabled.
    pub complexity_limit: u64,
    /// Default cost per field when the field name is not in
    /// `cost_per_field` (default 1). The complexity total is
    /// `sum(cost_per_field[name].unwrap_or(complexity_coefficient))`.
    #[serde(
        default = "default_graphql_complexity_coefficient",
        skip_serializing_if = "is_default_graphql_complexity_coefficient"
    )]
    pub complexity_coefficient: u64,
    /// Per-field cost overrides. Maps a field name to its explicit
    /// cost; any field not in this map uses
    /// `complexity_coefficient`. Empty (the default): every field
    /// costs `complexity_coefficient`.
    #[serde(default, skip_serializing_if = "is_graphql_cost_per_field_empty")]
    pub cost_per_field: std::collections::HashMap<String, u64>,
    /// Persisted-query enforcement (Apollo APQ + GET-by-hash variant).
    /// When enabled, every request's query SHA-256 hash must be in the
    /// configured `store` (a map of hash -> query text). A hash not in
    /// the store is rejected with 400
    /// `graphql_persisted_query_required`. Absent (the default): no
    /// persisted-query enforcement.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub persisted_queries: Option<GraphqlPersistedQueries>,
    /// Federation passthrough config (DP-11, #256). When enabled, the
    /// gateway treats the route as a federation passthrough: it
    /// forwards GraphQL requests to a single federated upstream
    /// (subgraph or supergraph router) while preserving
    /// federation-specific headers and allowing introspection queries
    /// (`_service`, `__schema`) to bypass depth/complexity checks.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub federation: Option<GraphqlFederation>,
}

/// Federation passthrough config (DP-11, #256,
/// `routes[].graphql.federation`).
///
/// When `passthrough` is true, the gateway:
/// - Preserves Apollo federation headers on the proxied request
///   (`Apollo-Require-Preflight`, `x-apollo-operation-name`,
///   `graphql-preflight`, `x-apollo-operation-id`).
/// - Allows federation introspection queries (`_service { sdl }`,
///   `__schema`, `__type`) to bypass depth and complexity checks.
/// - Still applies persisted-query enforcement if configured.
///
/// This is **passthrough mode**: the gateway does NOT implement query
/// planning or subgraph stitching. It proxies to a single upstream
/// that is expected to be either a federation router (subgraph-aware)
/// or a single subgraph.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GraphqlFederation {
    /// Master switch. Default false.
    #[serde(default, skip_serializing_if = "is_false")]
    pub passthrough: bool,
}

/// Persisted-query enforcement config (DW-099,
/// `routes[].graphql.persisted_queries`).
///
/// When enabled, the gateway enforces that every request's query
/// SHA-256 hash is in the config-supplied `store`. This is the Apollo
/// APQ (Automatic Persisted Queries) + GET-by-hash variant: the
/// client sends the query text, the gateway computes its SHA-256, and
/// verifies the hash is known. An external store (Redis, etc.) is a
/// future extension point; v1 uses a config-supplied map.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GraphqlPersistedQueries {
    /// Master switch. Default false: the persisted-query block is
    /// inert even when present.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The persisted-query store: a map of SHA-256 hash (lowercase
    /// hex) to query text. Every key must be a non-empty string
    /// (validation rejects empty keys). The query text is stored for
    /// future use (e.g. GET-by-hash resolution); v1 only checks hash
    /// membership.
    #[serde(default, skip_serializing_if = "is_graphql_persisted_store_empty")]
    pub store: std::collections::HashMap<String, String>,
}

fn default_graphql_complexity_coefficient() -> u64 {
    1
}

fn is_default_graphql_complexity_coefficient(v: &u64) -> bool {
    *v == 1
}

fn is_graphql_cost_per_field_empty(v: &std::collections::HashMap<String, u64>) -> bool {
    v.is_empty()
}

fn is_graphql_persisted_store_empty(v: &std::collections::HashMap<String, String>) -> bool {
    v.is_empty()
}

/// Route-scoped gRPC-Web policy (DW-101, `routes[].grpc_web`).
///
/// When enabled, the gateway translates gRPC-Web framing (the browser-
/// friendly variant that replaces HTTP/2 trailers with a trailing
/// frame) to native gRPC for the upstream, and wraps the native gRPC
/// response back into gRPC-Web framing for the browser. Streaming
/// (server-streaming and bidi) is supported: each upstream data chunk
/// becomes its own gRPC-Web data frame, and the trailers become a
/// final gRPC-Web trailer frame.
///
/// When `transcoding` is enabled, the gateway additionally accepts
/// plain JSON requests (Content-Type: application/json) and translates
/// them to protobuf wire bytes for the upstream, and translates the
/// protobuf response back to JSON. The mapping is driven by .proto
/// descriptors supplied via config.
///
/// The block parses and validates in every build (no cargo feature);
/// the runtime framing/transcoding translation is scaffolded and not
/// yet dispatched from the request path. See [`GrpcWebTranscoding`] and
/// [`GrpcWebDescriptor`].
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GrpcWeb {
    /// Master switch. Default false: the gRPC-Web block is inert even
    /// when present (allows staged rollout). When true, the gateway
    /// translates gRPC-Web framing to native gRPC on the forward path
    /// and back on the response path.
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// JSON-to-gRPC transcoding configuration. When enabled, the
    /// gateway accepts JSON requests and translates them to protobuf
    /// using the supplied .proto descriptors. Absent (the default):
    /// only gRPC-Web framing translation runs (no JSON transcoding).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub transcoding: Option<GrpcWebTranscoding>,
}

/// gRPC-Web JSON transcoding configuration (DW-101,
/// `routes[].grpc_web.transcoding`).
///
/// Supplies the .proto descriptor files that map HTTP/JSON requests to
/// gRPC methods. Each descriptor names a file (a FileDescriptorSet in
/// binary protobuf format), a package, and a service. At config publish
/// the gateway loads the descriptors, resolves the service's methods,
/// and builds a method map keyed by the fully-qualified gRPC method
/// path. The google.api.http annotation on each RPC maps an HTTP path +
/// verb to the gRPC method.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GrpcWebTranscoding {
    /// Master switch for transcoding. Default false: even when the
    /// `transcoding` block is present, transcoding is inert unless
    /// this is true. (Allows the descriptor list to be staged before
    /// activation.)
    #[serde(default, skip_serializing_if = "is_false")]
    pub enabled: bool,
    /// The .proto descriptor files to load. Each entry names a
    /// FileDescriptorSet file (binary protobuf format, as produced by
    /// `protoc --descriptor_set_out=...`), the package, and the
    /// service within that package. At least one descriptor is
    /// required when transcoding is enabled.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub descriptors: Vec<GrpcWebDescriptor>,
}

/// A .proto descriptor file entry (DW-101,
/// `routes[].grpc_web.transcoding.descriptors[]`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GrpcWebDescriptor {
    /// Path to the FileDescriptorSet file (binary protobuf format, as
    /// produced by `protoc --descriptor_set_out=...`). The file must
    /// exist and be readable at config publish time; a missing or
    /// unparseable file fails validation.
    pub file: String,
    /// The protobuf package name (e.g. `my.api`). Used to locate the
    /// service's methods in the descriptor set.
    pub package: String,
    /// The service name within the package (e.g. `MyService`).
    pub service: String,
}

/// Route-scoped protocol translation policy (DW-100,
/// `routes[].translation`).
///
/// When enabled, the gateway translates the request/response bodies
/// between two wire protocols on this route's forward and response
/// paths. The `kind` selects the translation direction; the `graphql`
/// and `soap` sub-blocks carry the direction-specific config.
///
/// The block parses and validates in every build (no cargo feature);
/// the runtime translators are scaffolded and not yet dispatched from
/// the request path.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Translation {
    /// The translation direction. Selects which translator runs and
    /// which sub-block (`graphql` or `soap`) carries the config.
    pub kind: TranslationKind,
    /// REST <-> GraphQL translation config. Required when `kind` is
    /// `rest_to_graphql` or `graphql_to_rest`; ignored otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub graphql: Option<GraphqlTranslation>,
    /// SOAP/XML translation config. Required when `kind` is
    /// `rest_to_soap` or `soap_to_rest`; ignored otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub soap: Option<SoapTranslation>,
}

/// The protocol translation direction (DW-100,
/// `routes[].translation.kind`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TranslationKind {
    /// A REST/JSON client -> GraphQL upstream. The gateway builds a
    /// GraphQL query from a config-supplied query template and the
    /// REST JSON body.
    RestToGraphql,
    /// A GraphQL client -> REST upstream. The gateway unwraps the
    /// GraphQL `data` envelope into a REST JSON body on the response
    /// path.
    GraphqlToRest,
    /// A REST/JSON client -> SOAP/XML upstream. The gateway wraps the
    /// JSON body in a SOAP envelope with the configured operation name
    /// and namespace.
    RestToSoap,
    /// A SOAP/XML client -> REST/JSON upstream. The gateway parses the
    /// SOAP envelope and converts the Body's payload element to JSON.
    SoapToRest,
}

/// REST <-> GraphQL translation config (DW-100,
/// `routes[].translation.graphql`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct GraphqlTranslation {
    /// The GraphQL query template. `$variable` references are resolved
    /// from the REST JSON body's top-level fields and substituted into
    /// the query (the resolved values are also sent as the GraphQL
    /// `variables` map). Required for `rest_to_graphql`; ignored for
    /// `graphql_to_rest` (which only unwraps the response envelope).
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub query_template: String,
    /// The path to send the GraphQL upstream (REST-to-GraphQL rewrites
    /// every request to this path). Default `/graphql`.
    #[serde(
        default = "default_graphql_upstream_path",
        skip_serializing_if = "is_default_graphql_upstream_path"
    )]
    pub upstream_path: String,
}

fn default_graphql_upstream_path() -> String {
    "/graphql".to_string()
}

fn is_default_graphql_upstream_path(s: &str) -> bool {
    s == "/graphql"
}

/// SOAP/XML translation config (DW-100, `routes[].translation.soap`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SoapTranslation {
    /// The SOAP operation name: the Body's first child element name
    /// (e.g. `GetUser`). Required for both directions.
    pub operation: String,
    /// The XML namespace for the operation element
    /// (e.g. `http://example.com/api`). Required for `rest_to_soap`
    /// (the envelope's payload element carries the namespace); used
    /// for `soap_to_rest` only to validate the payload element's
    /// namespace when present.
    #[serde(default, skip_serializing_if = "String::is_empty")]
    pub namespace: String,
}

/// Route-scoped WebSocket policy (DW-039, `routes[].websocket`).
///
/// Both knobs are opt-in and independent: an `origins` list gates the
/// upgrade handshake (403 before any upstream contact), and
/// `max_frames_per_sec` polices the ESTABLISHED tunnel (a client
/// sending data frames faster than the allowance is closed with a
/// 1008 policy-violation close frame and disconnected). The policing
/// works on the client-to-upstream direction only — the gateway
/// protects upstreams from abusive clients, not the reverse (an
/// abusive upstream is the operator's backend problem).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RouteWebsocket {
    /// Allowed `Origin` header values for the upgrade handshake
    /// (case-sensitive exact match, e.g. `https://app.example.com`).
    /// Empty or absent: every origin is allowed (the transparent
    /// default). Non-empty: ONLY listed origins upgrade — a missing
    /// `Origin` header is DENIED (browsers always send one on
    /// WebSocket handshakes; a request without one is not a browser
    /// and must be named explicitly or fail closed). The literal
    /// string `null` matches the sandboxed-document origin by exact
    /// match.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub origins: Vec<String>,
    /// Post-upgrade policing: the sustained allowance of DATA frames
    /// (text, binary, continuation — control frames are free) the
    /// CLIENT may send per second, with a one-second burst of the same
    /// size. A client past its allowance is closed with close code
    /// 1008 (policy violation) and disconnected. Absent: no policing
    /// (unlimited, the transparent default). Validation enforces
    /// 1..=[`limits::MAX_WEBSOCKET_FRAMES_PER_SEC`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_frames_per_sec: Option<u64>,
    /// Post-upgrade idle timeout in seconds (DP-05, #253). If no data
    /// flows in either direction for this duration, the tunnel is
    /// closed. Absent: no idle timeout (the tunnel stays open until
    /// one side closes, the prior default). Validation enforces
    /// 1..=86400 (1 second to 24 hours).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub idle_timeout_s: Option<u64>,
    /// Maximum payload size of a single WebSocket DATA frame in bytes
    /// (DP-05, #253). A frame exceeding this limit causes the
    /// connection to be closed with close code 1009 (message too big).
    /// Absent: no frame size limit (the prior default). Validation
    /// enforces 1..=16777216 (1 byte to 16 MiB).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_frame_size_bytes: Option<u64>,
}

/// Per-route SLO objectives (DW-052, `routes[].slo`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RouteSlo {
    /// Availability target as a PERCENTAGE in (0, 100]: the share of
    /// requests the gateway must answer outside the 5xx class.
    /// `99.9` allows one bad request per thousand.
    pub availability: f64,
    /// Latency objective threshold in milliseconds: a request is BAD
    /// for the latency objective when its end-to-end duration exceeds
    /// this. Absent: no latency objective (only availability is
    /// exported for the route).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub latency_ms: Option<f64>,
    /// Latency target as a PERCENTAGE in (0, 100): the share of
    /// requests that must complete within `latency_ms` (default 99).
    /// Requires `latency_ms`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub latency_target: Option<f64>,
}

/// Route maintenance mode (DW-041): a per-route availability state that
/// short-circuits every matched request with a gateway-generated 503.
///
/// Frozen semantics (enforcement lives in `dataplane::proxy`):
///
/// - Checked IMMEDIATELY after route resolution, BEFORE the route's
///   request limits: maintenance is a statement about the route's
///   availability, not about any one request's shape, so every matched
///   request gets the same 503 + `Retry-After` answer (an over-limit
///   request during maintenance is told "we're down", not "your headers
///   are too big" — fixing the headers would still leave it refused).
/// - The response is `503` with `Retry-After: <retry_after_secs>` (a
///   whole-seconds delay-suggestion, NOT a promise of recovery) and the
///   uniform JSON error envelope; `message` replaces the envelope's
///   default human text (it never leaks upstream internals — it is
///   operator-authored).
/// - CORS: an actual (non-preflight) request on a CORS-configured route
///   gets the policy's actual-response headers on the 503, so a browser
///   client can READ the maintenance envelope cross-origin. A CORS
///   PREFLIGHT is exempt: it still answers 204 exactly as without
///   maintenance. The preflight is a Fetch-protocol handshake about the
///   GATEWAY's cross-origin policy, answered from static config and sent
///   without credentials — failing it would surface in the browser as an
///   opaque CORS error and hide the very 503 the operator wants clients
///   to see on the subsequent actual request.
/// - Reserved paths (`/healthz`, `/readyz`, `/metrics`) never match a
///   route, so probes and scrapes keep answering through maintenance —
///   an orchestrator must not restart a deliberately idling gateway.
/// - Unrouted traffic is unaffected (maintenance is per-route; a 404
///   stays a 404).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Maintenance {
    /// `Retry-After` value, in whole seconds, sent with the 503. Absent:
    /// 60 (one minute — long enough to shed load, short enough that a
    /// client polling for recovery notices the route return). Validation
    /// rejects 0 (it would invite an immediate retry stampede against a
    /// route the operator just took down).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub retry_after_secs: Option<u64>,
    /// Human-readable text for the error envelope's `message` field.
    /// Absent: "route under maintenance". Validation rejects an
    /// empty/whitespace string (omit the field for the default).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub message: Option<String>,
}

/// Default `maintenance.retry_after_secs` (DW-041).
pub const DEFAULT_MAINTENANCE_RETRY_AFTER_SECS: u64 = 60;

impl Maintenance {
    /// The `Retry-After` seconds to send (the configured value or the
    /// default; validation has rejected 0, so this is always >= 1).
    pub fn retry_after(&self) -> u64 {
        self.retry_after_secs
            .unwrap_or(DEFAULT_MAINTENANCE_RETRY_AFTER_SECS)
            .max(1)
    }

    /// The envelope `message` text (the configured value or the default).
    pub fn message(&self) -> &str {
        self.message.as_deref().unwrap_or("route under maintenance")
    }
}

/// Route-level API deprecation policy (DW-048): automates the RFC
/// deprecation signal headers on every response of the route.
///
/// What the block emits (computed once at snapshot compile; see
/// [`CompiledDeprecation`] and `dataplane::versioning`):
///
/// - `since` (header emitted only when set): `Deprecation:
///   @<unix-seconds>` — the RFC 9745 structured-date form (RFC 9651
///   dates). RFC 9745 carries no URI inside the `Deprecation` field;
///   the human-readable notice travels in the `Link` below.
/// - `sunset` (optional): `Sunset: <HTTP-date>` verbatim — RFC 8594
///   requires an HTTP-date, and validation accepts exactly the
///   IMF-fixdate form generators must send (see `config::versioning`).
/// - `uri` (optional, requires `since`): `Link: <uri>;
///   rel="deprecation"` appended — the RFC 9745 companion link to the
///   migration documentation.
///
/// Semantics (frozen):
///
/// - Headers are stamped on the route's ACTION responses (proxy,
///   redirect, respond) in the response decoration tail — after
///   compression wrapping (the codec only rewrites `Content-Length`,
///   `Content-Encoding`, and `Vary`, so these headers pass through
///   verbatim) and beside the CORS headers (independent families).
///   Gateway-generated short-circuits on the route (413/431 limit
///   rejections, CORS preflights, authn/authz/rate-limit rejections,
///   503 sheds) do NOT carry them: those responses describe the
///   gateway's opinion of the REQUEST, not the route's lifecycle.
///   (The eager HMAC body-digest 401 is an action-path response and
///   DOES carry them.) Unrouted traffic (404) never matches the route
///   at all.
/// - The gateway is the source of truth for the headers it is configured
///   to emit: an upstream-sent `Deprecation`/`Sunset` on a route WITH a
///   `deprecation` block is replaced; on a route WITHOUT one, upstream
///   values pass through untouched. `Link` is appended (a list header —
///   upstream links survive).
/// - Validation rejects: a block with neither `since` nor `sunset` (no
///   effect — omit it), dates that are not IMF-fixdate, a `sunset`
///   already in the past (advertising a removal that already happened;
///   remove the route or extend the date — this also stops a long-lived
///   generation from silently re-publishing a stale sunset), a `sunset`
///   before `since` (removed before deprecated), and a `uri` without
///   `since` (the link documents the `Deprecation` header).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Deprecation {
    /// When this API version was (or will be) deprecated, as an
    /// IMF-fixdate HTTP-date (`Sun, 06 Nov 1994 08:49:37 GMT`). Emits
    /// `Deprecation: @<unix-seconds>` (RFC 9745). A past date is normal
    /// (the deprecation is in effect); a date before 1970 cannot form
    /// the structured date and is rejected.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub since: Option<String>,
    /// When this API version is expected to stop working, as an
    /// IMF-fixdate HTTP-date. Emits `Sunset` (RFC 8594) verbatim.
    /// Validation rejects a date already in the past and a date before
    /// `since`.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub sunset: Option<String>,
    /// URI of the deprecation/migration notice (absolute `http(s)` URL).
    /// Requires `since` — the RFC 9745 `Link; rel="deprecation"` it
    /// emits documents the `Deprecation` header.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub uri: Option<String>,
}

/// Snapshot-compiled form of a [`Deprecation`] block (DW-048): the
/// emitted header VALUES, precomputed at snapshot-compile time — the
/// HTTP-date strings are parsed once here (never per response) and the
/// RFC 9745 structured date is rendered from the parsed seconds. Lives
/// in `config` beside [`CompiledCorsOrigins`] for the same reason:
/// `snapshot` builds it into the route table and `dataplane::versioning`
/// consumes it. Validation has already rejected unparseable dates, so
/// compilation drops nothing on any publishable config; entries that
/// would fail are skipped exactly like the CORS matcher's fallback.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompiledDeprecation {
    deprecation: Option<String>,
    sunset: Option<String>,
    link: Option<String>,
}

impl CompiledDeprecation {
    /// Compile a (validated) policy's header values.
    pub fn compile(dep: &Deprecation) -> Self {
        CompiledDeprecation {
            deprecation: dep
                .since
                .as_deref()
                .and_then(versioning::parse_http_date)
                .filter(|d| d.unix_seconds() >= 0)
                .map(|d| format!("@{}", d.unix_seconds())),
            sunset: dep
                .sunset
                .as_deref()
                .filter(|s| versioning::parse_http_date(s).is_some())
                .map(str::to_string),
            link: dep
                .uri
                .as_deref()
                .map(|uri| format!("<{uri}>; rel=\"deprecation\"")),
        }
    }

    /// The `Deprecation` header value (`@<unix-seconds>`), if the policy
    /// sets `since`.
    pub fn deprecation_header(&self) -> Option<&str> {
        self.deprecation.as_deref()
    }

    /// The `Sunset` header value (the validated config string, verbatim),
    /// if the policy sets `sunset`.
    pub fn sunset_header(&self) -> Option<&str> {
        self.sunset.as_deref()
    }

    /// The `Link` header value (`<uri>; rel="deprecation"`), if the
    /// policy sets `uri`.
    pub fn link_header(&self) -> Option<&str> {
        self.link.as_deref()
    }
}

/// Route-level authorization rules (DW-020, feature analysis 4.7).
///
/// Rule semantics (frozen here; evaluation lives in the `authz` module):
///
/// - `denied_consumers` / `denied_groups` beat `allowed_*` at the SAME
///   level: within one [`Authz`], a deny always wins a tie.
/// - `allowed_consumers`, when non-empty, is a closed set: the
///   authenticated consumer must be listed. Empty = any authenticated
///   consumer passes the consumer rule.
/// - `allowed_groups`, when non-empty, requires the consumer to be a
///   member of at least one listed group. Group membership comes from
///   the CONFIG consumer's `groups` field; store-only consumers
///   (DWARA_STATE_DB deployments whose consumer has no config entry)
///   have no groups and therefore never satisfy an `allowed_groups`
///   rule (documented limitation until the state store carries groups).
/// - `required_scopes`: every listed scope must appear in the JWT
///   `scope` claim. The claim may be a space-separated string
///   (`"read write"`, the OAuth convention) or a JSON array of strings
///   (`["read", "write"]`, joined to its space-separated form when the
///   identity's claims are captured in `authn`); non-JWT identities
///   (API key / Basic) carry no claims and never satisfy scope rules.
/// - `required_claims`: exact string equality on the stringified claim
///   value; a claim absent from the token fails the match. Only
///   string- and number-valued claims are captured on the identity
///   (see `authn`), so a claim that is a JSON `true`/`false`, `null`,
///   object, or nested structure can NEVER satisfy a `required_claims`
///   entry — there is no stringified form to compare. Comparisons are
///   CASE-SENSITIVE throughout: consumer names, groups, scopes, and
///   claim values must match byte-for-byte.
/// - `ip_acl`: evaluated against the EFFECTIVE client IP — the
///   `X-Forwarded-For`-resolved client when the direct peer is inside
///   `gateway.trusted_proxies` (DW-009 chain), otherwise the direct
///   peer. See [`IpAcl`].
///
/// Authentication implication: an [`Authz`] carrying ANY identity rule
/// (consumer/group/scope/claim) rejects anonymous requests with 401; an
/// `ip_acl`-only [`Authz`] is the one authorization shape that can
/// ADMIT anonymous traffic (from an IP the ACL allows). A denial of an
/// AUTHENTICATED request is 403 (forbidden), never 401.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Authz {
    /// Consumers allowed to call the route (empty = any authenticated).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_consumers: Vec<String>,
    /// Consumers explicitly rejected, even when otherwise allowed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub denied_consumers: Vec<String>,
    /// Groups allowed to call the route (empty = no group constraint).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_groups: Vec<String>,
    /// Groups explicitly rejected, even when otherwise allowed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub denied_groups: Vec<String>,
    /// JWT scopes (from the `scope` claim) every request must carry.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub required_scopes: Vec<String>,
    /// Claims (name -> exact stringified value) every request must
    /// carry. A listed claim absent from the token's claims fails.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub required_claims: std::collections::BTreeMap<String, String>,
    /// IP allow/deny gate on the effective client IP.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ip_acl: Option<IpAcl>,
    /// GeoIP gate on the effective client IP (DW-050): country/ASN
    /// allow and deny lists resolved through `gateway.geoip`'s
    /// database. An address the database does not resolve (private
    /// ranges, not-in-DB, no database loaded) is UNKNOWN and matches
    /// NEITHER list: deny-lists keep passing unknowns, allow-lists
    /// keep rejecting them. Requires a `gateway.geoip` block —
    /// validation rejects the predicate without one. See
    /// [`GeoipRules`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub geoip: Option<GeoipRules>,
    /// Monitor mode (DW-041): evaluate this block's rules, LOG and count
    /// every would-be denial (the `dwara_policy_dry_run_total{phase=
    /// "authz"}` counter plus a `dwara::policy` warn event), but let the
    /// request PROCEED as if allowed. The flag is per ATTACHMENT and
    /// mutes only this block's OWN denials: a LIVE deny at any other
    /// level of the chain still enforces (dry run never makes
    /// enforcement more permissive — the resolver walks past a dry deny
    /// and stops only at a live one). Route `auth_required` is an
    /// authentication-phase check, not an authorization rule, and is
    /// never muted by this flag.
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
}

/// IP access control on the effective client IP (DW-020, feature
/// analysis 4.15). Entries are IP addresses (e.g. `10.1.2.3`) or CIDRs
/// (e.g. `10.0.0.0/8`); anything else fails config validation (the same
/// parser as `gateway.trusted_proxies`). Evaluation order: the `deny`
/// list first (a match rejects with 403 regardless of the allow list),
/// then the `allow` list, then `default` for IPs matched by neither.
///
/// A `/0` (all-addresses) entry such as `0.0.0.0/0` or `::/0` is
/// REJECTED by validation in the `allow` list: an allow-all entry
/// filters nothing and is always a mistake — the intended shape is an
/// empty allow list with `default: allow` (the ACL's default mode).
/// A `/0` in the `deny` list is meaningful (deny-all) and is accepted.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct IpAcl {
    /// CIDRs/IPs allowed through the gate.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allow: Vec<String>,
    /// CIDRs/IPs rejected; a deny match wins over any allow match.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub deny: Vec<String>,
    /// What happens to an IP matched by NEITHER list: `allow` (the
    /// default — the lists are exceptions) or `deny` (closed mode — only
    /// allow-listed IPs pass).
    #[serde(
        default = "default_ip_acl_default",
        skip_serializing_if = "is_default_ip_acl_default"
    )]
    pub default: IpAclDefault,
}

/// Fallback decision of an [`IpAcl`] for IPs matched by neither list.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum IpAclDefault {
    /// Unmatched IPs pass the IP gate (the default).
    Allow,
    /// Unmatched IPs are rejected: only the allow list passes.
    Deny,
}

fn default_ip_acl_default() -> IpAclDefault {
    IpAclDefault::Allow
}

fn is_default_ip_acl_default(d: &IpAclDefault) -> bool {
    *d == IpAclDefault::Allow
}

/// Route-scoped CORS policy (DW-027, feature analysis 4.14).
///
/// Semantics (frozen; evaluation lives in `dataplane::cors`):
///
/// - `allowed_origins` is a closed set of exact origins
///   (`https://api.example.com`, scheme + host + optional port, compared
///   in normalized form: lowercase scheme/host, default port dropped) or
///   the single entry `*` (any origin). It must be non-empty; `*`
///   combined with `allow_credentials: true` is rejected by validation
///   (the Fetch spec forbids wildcard-credentialed responses).
/// - A PREFLIGHT (`OPTIONS` + `Origin` + `Access-Control-Request-Method`)
///   on a CORS-configured route is answered 204 by the gateway —
///   validated against the policy, never forwarded upstream, and never
///   subject to authn/authz/rate limiting (browsers send preflights
///   without credentials). A preflight that fails validation (origin,
///   method, or requested headers not allowed) still short-circuits:
///   204 with NO CORS headers, which the browser reads as a failed
///   preflight. A plain `OPTIONS` without the preflight markers is NOT
///   intercepted; it proxies normally.
/// - ACTUAL responses on the route carry `Access-Control-Allow-Origin`
///   (`*`, or the echoed request origin when the list is specific),
///   `Access-Control-Allow-Credentials: true` when configured,
///   `Access-Control-Expose-Headers` when configured, and `Vary: Origin`
///   (merged into any existing `Vary`). A request whose `Origin` is not
///   allowed simply gets no CORS headers — the response passes through
///   as-is (same-origin reads do not consult CORS at all).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Cors {
    /// Origins allowed to call this route cross-origin: exact origin
    /// strings (`https://api.example.com`, `http://localhost:8080`) or
    /// `*` (any origin; never together with `allow_credentials`).
    pub allowed_origins: Vec<String>,
    /// Methods allowed for cross-origin requests (preflight echo and
    /// actual-request check). Default: the common API set
    /// GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS. Each entry must be a
    /// valid HTTP method token; comparison is case-insensitive.
    #[serde(default = "default_cors_methods")]
    pub allowed_methods: Vec<String>,
    /// Request headers clients may send: exact header names, or `*` to
    /// allow any requested header (never `*` together with
    /// `allow_credentials`). Validated against the preflight's
    /// `Access-Control-Request-Headers` list; empty means no headers
    /// beyond the CORS-safelisted set are permitted in preflight checks.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_headers: Vec<String>,
    /// Response headers exposed to the browser (readable by cross-origin
    /// client script). Absent: only the CORS-safelisted response headers
    /// are exposed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub expose_headers: Vec<String>,
    /// Allow credentialed cross-origin requests (cookies, TLS client
    /// certificates). Default false. When true, the origin list must be
    /// specific (`*` is rejected by validation) and responses echo the
    /// request origin rather than sending `*`.
    #[serde(default, skip_serializing_if = "is_false")]
    pub allow_credentials: bool,
    /// `Access-Control-Max-Age` for preflight responses, in seconds (how
    /// long the browser may cache the preflight result). Absent: the
    /// header is omitted (each preflight hits the gateway).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_age_secs: Option<u64>,
}

fn default_cors_methods() -> Vec<String> {
    ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]
        .iter()
        .map(|s| s.to_string())
        .collect()
}

/// Canonical form of one origin (DW-027): lowercase scheme and host,
/// default port dropped, no userinfo, no path/query — the exact string
/// the runtime CORS matcher compares request `Origin` values against
/// and validation checks config entries with. `None` when the input is
/// not a well-formed `http(s)` origin. Lives in `config` (the lowest
/// consuming domain) so validation (`snapshot::validate`) and matching
/// (`dataplane::cors`) share one grammar, the same way `net.rs` owns the
/// IP/CIDR grammar.
pub fn normalize_origin(origin: &str) -> Option<String> {
    let uri: hyper::Uri = origin.parse().ok()?;
    let scheme = uri.scheme()?;
    if !matches!(scheme.as_str(), "http" | "https") {
        return None;
    }
    // Browsers never serialize userinfo into an Origin (the grammar is
    // scheme "://" host [":" port]); authority userinfo is a config
    // authoring error or a smuggle attempt, never a real origin.
    if uri.authority().is_some_and(|a| a.as_str().contains('@')) {
        return None;
    }
    let host = uri.host()?;
    let default_port = match scheme.as_str() {
        "http" => 80,
        _ => 443,
    };
    let port = uri
        .port_u16()
        .and_then(|p| (p != default_port).then_some(p));
    // An origin carries no path, query, or fragment; tolerate only the
    // empty path "/" (browsers serialize the origin WITHOUT it, but
    // configs hand-writing "https://host/" are unambiguous).
    match uri.path_and_query() {
        None => {}
        Some(pq) if pq.as_str() == "/" => {}
        _ => return None,
    }
    Some(match port {
        Some(p) => format!("{}://{}:{}", scheme.as_str(), host.to_lowercase(), p),
        None => format!("{}://{}", scheme.as_str(), host.to_lowercase()),
    })
}

/// Snapshot-compiled form of a `cors.allowed_origins` list (DW-027): the
/// wildcard flag plus the normalized form of every specific entry,
/// computed once at snapshot-compile time so the request path never
/// re-parses config strings (per-request work is the request's own
/// origin only). Lives in `config` beside [`normalize_origin`] because
/// the compiled set is the grammar's runtime consumer: `snapshot`
/// builds it into the route table (`snapshot::RouteTable`) and
/// `dataplane::cors` matches against it. Validation has already
/// rejected entries that do not normalize, so compilation drops
/// nothing on any publishable config; entries that would fail
/// normalization are skipped exactly as the pre-compiled matcher was.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompiledCorsOrigins {
    wildcard: bool,
    origins: Vec<String>,
}

impl CompiledCorsOrigins {
    /// Compile a (validated) policy's origin list.
    pub fn compile(cors: &Cors) -> Self {
        CompiledCorsOrigins {
            wildcard: cors.allowed_origins.iter().any(|o| o == "*"),
            origins: cors
                .allowed_origins
                .iter()
                .filter(|o| *o != "*")
                .filter_map(|o| normalize_origin(o))
                .collect(),
        }
    }

    /// Does a request `Origin` value match this set? `*` matches any
    /// origin string; otherwise normalized exact match (the same
    /// comparison the pre-compiled matcher ran, without re-normalizing
    /// the config side per request).
    pub fn allows(&self, origin: &str) -> bool {
        if self.wildcard {
            return true;
        }
        let Some(request_origin) = normalize_origin(origin) else {
            return false;
        };
        self.origins.iter().any(|o| o == &request_origin)
    }

    /// Was the list the single entry `*`?
    pub fn wildcard(&self) -> bool {
        self.wildcard
    }
}

/// Route-scoped response compression policy (DW-027, feature analysis
/// 4.13).
///
/// Semantics (frozen; negotiation and encoding live in
/// `dataplane::compression`):
///
/// - `algorithms` is the PREFERENCE order: the first entry the request's
///   `Accept-Encoding` accepts wins. `q=0` entries in `Accept-Encoding`
///   are treated as refusal.
/// - `level` is clamped per algorithm at encode time (gzip 0-9, brotli
///   0-11, zstd 0-22; validation bounds the field to 0-22). Absent: the
///   algorithm's library default.
/// - `min_size` skips compression of responses whose size is known and
///   below it — a declared `Content-Length` or the exact size of the
///   gateway's own respond/redirect bodies. Responses of UNKNOWN length
///   (streaming) are always candidates.
/// - `content_types` (when non-empty) restricts compression to responses
///   whose `Content-Type` starts with one of the entries; entries are
///   lowercase prefix matches (e.g. `text/`). `excluded_content_types`
///   is checked after the include list and wins (the way to express
///   "compress everything text/ except `text/event-stream`").
/// - Responses carrying an existing `Content-Encoding`, 1xx/204/304
///   statuses, zero-length bodies, and 101 upgrade responses are never
///   compressed. `Vary: Accept-Encoding` is merged into every response
///   on a compression-configured route that is not already encoded —
///   compressed or not — so caches key correctly.
/// - The compressed body streams chunk-by-chunk with a flush per chunk
///   (streaming/SSE-friendly, at a small compression-ratio cost); the
///   gateway never buffers the whole body to compress it. The frame
///   codec's internal buffer is bounded by the chunk size.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Compression {
    /// Enabled algorithms in preference order (default gzip, brotli,
    /// zstd). Must be non-empty and duplicate-free (validation).
    #[serde(default = "default_compression_algorithms")]
    pub algorithms: Vec<CompressionAlgorithm>,
    /// Compression level; clamped per algorithm (gzip <= 9, brotli <= 11,
    /// zstd <= 22). Absent: library default per algorithm.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub level: Option<u8>,
    /// Minimum response size (bytes) to compress, applied whenever the
    /// size is known: a declared `Content-Length` or the body's exact
    /// size (the gateway's own respond/redirect bodies, which carry no
    /// `Content-Length`). Below it the response passes through (still
    /// carrying `Vary: Accept-Encoding`). Default 1024. Responses of
    /// unknown length (streaming) are always candidates.
    #[serde(default = "default_compression_min_size")]
    pub min_size: u64,
    /// Content-Type prefix include list (lowercase, e.g. `text/`,
    /// `application/json`); empty = every content type is a candidate.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub content_types: Vec<String>,
    /// Content-Type prefix exclude list, checked after `content_types`;
    /// a match passes the response through uncompressed.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub excluded_content_types: Vec<String>,
}

fn default_compression_algorithms() -> Vec<CompressionAlgorithm> {
    vec![
        CompressionAlgorithm::Gzip,
        CompressionAlgorithm::Brotli,
        CompressionAlgorithm::Zstd,
    ]
}

fn default_compression_min_size() -> u64 {
    1024
}

/// One response compression algorithm (DW-027).
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "lowercase")]
pub enum CompressionAlgorithm {
    Gzip,
    Brotli,
    Zstd,
}

impl CompressionAlgorithm {
    /// The `Accept-Encoding` / `Content-Encoding` token of the algorithm.
    pub fn encoding_token(self) -> &'static str {
        match self {
            CompressionAlgorithm::Gzip => "gzip",
            CompressionAlgorithm::Brotli => "br",
            CompressionAlgorithm::Zstd => "zstd",
        }
    }
}

/// Snapshot-compiled form of a compression policy's content-type prefix
/// lists (DW-027): every include/exclude entry trimmed and lowercased
/// once at snapshot-compile time; the request path compares the
/// response's (lowercased) media type against the precomputed prefixes
/// instead of re-normalizing config strings per response. Same
/// placement rationale as [`CompiledCorsOrigins`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CompiledContentTypeFilter {
    include: Vec<String>,
    exclude: Vec<String>,
}

impl CompiledContentTypeFilter {
    /// Compile a (validated) policy's prefix lists.
    pub fn compile(policy: &Compression) -> Self {
        fn normalize_list(list: &[String]) -> Vec<String> {
            list.iter().map(|p| p.trim().to_lowercase()).collect()
        }
        CompiledContentTypeFilter {
            include: normalize_list(&policy.content_types),
            exclude: normalize_list(&policy.excluded_content_types),
        }
    }

    /// Is `media_type` (lowercase, parameters stripped) a compression
    /// candidate? An empty include list admits every type; the exclude
    /// list is checked after it and wins.
    pub fn allows(&self, media_type: &str) -> bool {
        (self.include.is_empty() || self.include.iter().any(|p| media_type.starts_with(p)))
            && !self.exclude.iter().any(|p| media_type.starts_with(p))
    }
}

/// Route-scoped request size limits (DW-027, feature analysis 4.16).
///
/// Semantics (frozen; enforcement lives in `dataplane::hardening`):
///
/// - Header limits (`max_header_count`, `max_header_bytes`) are checked
///   immediately after route resolution, before CORS preflight handling
///   and authentication; a violation answers 431 with the JSON error
///   envelope. `max_header_bytes` is the SUM of all header name and
///   value bytes of the request (hyper's per-connection buffer limits
///   still apply beneath this, process-wide).
/// - `max_body_bytes`: a request whose `Content-Length` declares more is
///   rejected 413 before any upstream contact. A body of UNKNOWN length
///   (chunked / h2 without content-length) is wrapped in a counting
///   guard: crossing the cap aborts the request (the upstream attempt
///   fails; the client receives 413 when the failure precedes the
///   upstream's response headers, a torn stream otherwise).
/// - A block with NO field set is rejected by validation (always an
///   authoring mistake; omit the block).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RequestLimits {
    /// Maximum request body size in bytes (declared via `Content-Length`
    /// or enforced streaming). Absent: unlimited.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_body_bytes: Option<u64>,
    /// Maximum number of header fields on the request. Absent:
    /// unlimited (hyper's parser bound applies).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_header_count: Option<u32>,
    /// Maximum total size of request headers (names + values, bytes).
    /// Absent: unlimited.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_header_bytes: Option<u64>,
    /// Monitor mode (DW-041): evaluate the limits, LOG and count every
    /// would-be rejection (`dwara_policy_dry_run_total{phase="route_
    /// limits"}` + a `dwara::policy` warn event), but let the request
    /// PROCEED — including its body: the streaming `max_body_bytes` guard
    /// is not armed, so a chunked body that would have been aborted mid-
    /// stream streams through (only the cheap up-front checks — header
    /// count/bytes, a declared `Content-Length` — are observable in dry
    /// run). The staging tool for turning limits on against live traffic
    /// without breaking clients.
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
}

/// Matching rules for incoming requests.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RouteMatch {
    pub path: PathMatch,
    /// Exact host match (e.g. `api.example.com`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub host: Option<String>,
    /// Allowed HTTP methods; empty means all methods.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub methods: Vec<String>,
    /// Exact header matches.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub headers: std::collections::BTreeMap<String, String>,
    /// Query-parameter matches; every entry must match (AND). Name-only
    /// entries match on presence; a `value` requires an exact raw match (no
    /// percent-decoding in v1).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub query: Vec<NameValueMatch>,
    /// Cookie matches (parsed from the `Cookie` header); every entry must
    /// match (AND). Name-only entries match on presence; a `value` requires
    /// an exact match (no cookie-unquoting in v1).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub cookies: Vec<NameValueMatch>,
    /// Media-type version selection (DW-048): a bare `type/subtype` the
    /// request's `Accept` header must name explicitly, e.g.
    /// `application/vnd.acme.v2+json`. A comma-separated Accept list
    /// matches on ANY entry; parameters and q-values on the request side
    /// are ignored; wildcard entries (`*/*`, `type/*`) and a missing
    /// Accept header never match — version selection requires the client
    /// to NAME the version, so unconstrained clients fall through to the
    /// route without this criterion (the unversioned default). Like every
    /// non-path criterion this is AND-ed and applied AFTER path
    /// resolution: a miss does not fall through to another route (404),
    /// and two routes cannot share one path to offer multiple versions —
    /// version families use distinct paths (`/v1/`, `/v2/`) or this
    /// criterion on a versioned path. Validation rejects anything but a
    /// bare lowercase-able `type/subtype` (`config::versioning` owns the
    /// grammar). Responses of a matched route carry `Vary: Accept`
    /// (merged), so shared caches key on the negotiated representation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub accept: Option<String>,
}

/// One query-parameter or cookie criterion: the parameter/cookie must be
/// present; when `value` is given it must equal that exact string.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct NameValueMatch {
    pub name: String,
    /// Exact value required; `None` means "present is enough".
    #[serde(skip_serializing_if = "Option::is_none")]
    pub value: Option<String>,
}

/// How a route's path pattern is interpreted.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PathMatch {
    #[serde(rename = "type")]
    pub kind: PathMatchKind,
    /// The pattern value, e.g. `/v1/users` or `/v1/.*`.
    pub value: String,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum PathMatchKind {
    Exact,
    Prefix,
    Regex,
}

/// What the gateway does when a route matches.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum RouteAction {
    /// Forward to the route's service (its upstream).
    ///
    /// `rewrite` (at most ONE per action in v1) is applied to the inbound
    /// path before the request is sent upstream; the query string is always
    /// preserved verbatim.
    Proxy {
        #[serde(skip_serializing_if = "Option::is_none")]
        rewrite: Option<PathRewrite>,
    },
    Redirect {
        #[serde(skip_serializing_if = "Option::is_none")]
        scheme: Option<String>,
        #[serde(skip_serializing_if = "Option::is_none")]
        host: Option<String>,
        #[serde(skip_serializing_if = "Option::is_none")]
        path: Option<String>,
        status: u16,
    },
    Respond {
        status: u16,
        #[serde(skip_serializing_if = "Option::is_none")]
        body: Option<String>,
        /// Extra response headers (name -> value), emitted verbatim.
        #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
        headers: std::collections::BTreeMap<String, String>,
    },
    /// Serve a canned response without contacting any upstream (DW-047
    /// mock mode). The route's `service` is still required by the
    /// schema (the frozen vocabulary), but a mock route never dials
    /// it — the whole point is serving without a backend. Pair with
    /// `request_validation` to mock a write endpoint that still
    /// rejects malformed bodies. See [`MockAction`].
    Mock {
        #[serde(flatten)]
        mock: MockAction,
    },
    /// AI provider translation (DW-075): the request body is parsed as
    /// an OpenAI chat-completions request, its `model` resolved through
    /// the gateway's `ai:` block to a provider, translated to that
    /// provider's wire format (OpenAI/Anthropic/Gemini), sent through
    /// the provider's upstream, and the response translated back to the
    /// OpenAI shape. The route's `service` is still required by the
    /// schema but never dialed. Requires an `ai:` block (validation
    /// rejects the pairing otherwise). `stream: true` requests are
    /// served via zero-buffer SSE pass-through (DW-077).
    ///
    /// AI-02: the `endpoint` field selects which AI endpoint the route
    /// serves. The default is `chat` (the existing behavior). Other
    /// endpoints (`embeddings`, `images`, `audio`, `moderation`) are
    /// proxied as a passthrough: the request body is forwarded to the
    /// provider's upstream as-is (no adapter translation), and the
    /// response is returned as-is. Model governance (allowlist check)
    /// still applies using the `model` field from the request body.
    Ai {
        #[serde(default)]
        endpoint: AiEndpoint,
        /// AI-05 (#195): The client-facing request dialect. Defaults
        /// to `openai` (the historical behavior). When set to
        /// `anthropic` or `gemini`, the gateway parses the incoming
        /// request using that dialect's native format and translates
        /// to the canonical `ChatRequest`. When set to `passthrough`,
        /// the request body is forwarded to the provider as-is (no
        /// translation, still metered/governed).
        #[serde(default)]
        dialect: AiIngressDialect,
    },
    /// WASM route handler (nano-service, DW-106): instead of proxying
    /// to an upstream, the route action runs a WASM module that
    /// generates the response directly. The module implements a simple
    /// request->response handler ABI over the existing wasmtime runtime
    /// (compiled into every build; no cargo feature). The route's
    /// `service` is still
    /// required by the schema (the frozen vocabulary) but never dialed
    /// -- the whole point is serving without a backend. See
    /// [`NanoServiceAction`].
    NanoService {
        #[serde(flatten)]
        nano: NanoServiceAction,
    },
}

/// AI-05 (#195): The client-facing request dialect for an AI route.
/// Determines how the gateway parses the incoming request body.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiIngressDialect {
    /// OpenAI chat-completions shape (the historical default). The
    /// request is parsed by `openai_compat::parse_chat_request`.
    #[default]
    Openai,
    /// Anthropic Messages API shape. The request is parsed by
    /// `ingress::parse_anthropic_request` and translated to the
    /// canonical `ChatRequest`.
    Anthropic,
    /// Gemini generateContent shape. The request is parsed by
    /// `ingress::parse_gemini_request` and translated to the
    /// canonical `ChatRequest`.
    Gemini,
    /// Passthrough mode: the request body is forwarded to the
    /// provider as-is (no translation, still metered/governed).
    /// The response is returned as-is.
    Passthrough,
}

/// AI-02: which AI endpoint a route serves. The `chat` endpoint (the
/// default) uses the full adapter translation pipeline (DW-075). The
/// other endpoints are proxied as a passthrough: the request body is
/// forwarded to the provider's upstream as-is, and the response is
/// returned as-is. Model governance (allowlist check) still applies
/// using the `model` field from the request body.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AiEndpoint {
    /// OpenAI chat-completions (`POST /v1/chat/completions`). The
    /// full adapter translation pipeline applies (DW-075). This is the
    /// default.
    #[default]
    Chat,
    /// OpenAI embeddings (`POST /v1/embeddings`). Proxied as a
    /// passthrough; the request body `{model, input}` is forwarded
    /// as-is. Token usage from the response is recorded for budget
    /// accounting.
    Embeddings,
    /// OpenAI images (`POST /v1/images/generations`). Proxied as a
    /// passthrough; no token usage (image generation is priced per
    /// image, not per token).
    Images,
    /// OpenAI audio (TTS `POST /v1/audio/speech`, transcription
    /// `POST /v1/audio/transcriptions`). Proxied as a passthrough.
    Audio,
    /// OpenAI moderation (`POST /v1/moderations`). Proxied as a
    /// passthrough.
    Moderation,
    /// AI-04 (#194): OpenAI Batch API (`POST /v1/batches`). Proxied
    /// as a passthrough for batch creation/status/cancel. When batch
    /// results are retrieved (`GET /v1/batches/{id}/output`), the
    /// JSONL result file is parsed and each line's `usage` is metered
    /// at the batch (50% discount) rate.
    Batch,
}

/// A WASM route handler (nano-service) action (DW-106,
/// `routes[].action` with `type: nano_service`). The gateway loads the
/// named WASM module, calls its `handle` export with the serialized
/// request (method, path, headers, body), and returns the response the
/// module produces (status, headers, body). No upstream is contacted.
///
/// `module` is the filesystem path to the `.wasm` module (checked for
/// existence and readability at config publish time). `memory_limit` is
/// the maximum linear memory in bytes the module may allocate (must be
/// positive and at most 64 MiB). `execution_timeout_ms` is the maximum
/// wall-clock time the `handle` call may run (must be positive and at
/// most 5000ms); a module that exceeds it is interrupted and the route
/// answers 504.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct NanoServiceAction {
    /// Filesystem path to the `.wasm` module. Must exist and be
    /// readable at config publish time.
    pub module: String,
    /// Maximum linear memory the module may allocate, in bytes. Must be
    /// > 0 and <= 67108864 (64 MiB). Default: 1048576 (1 MiB).
    #[serde(default = "default_nano_memory_limit")]
    pub memory_limit: usize,
    /// Maximum wall-clock execution time for the `handle` call, in
    /// milliseconds. Must be > 0 and <= 5000. Default: 100.
    #[serde(default = "default_nano_execution_timeout_ms")]
    pub execution_timeout_ms: u64,
}

fn default_nano_memory_limit() -> usize {
    1_048_576
}

fn default_nano_execution_timeout_ms() -> u64 {
    100
}

/// A canned response served without any upstream contact (DW-047,
/// `routes[].action.mock`). The body comes from either `body` (an
/// inline string) or `body_file` (a path relative to the config file
/// directory); exactly one of the two may be set, or neither for an
/// empty body. `delay_ms` simulates latency (useful for testing
/// timeouts and retries against a mock). Validation rejects a status
/// outside 100..=599, a `delay_ms` above 30000, and setting both
/// `body` and `body_file`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct MockAction {
    /// HTTP status code (100..=599).
    pub status: u16,
    /// Extra response headers (name -> value), emitted verbatim. When
    /// `content-type` is not set here, the gateway defaults it to
    /// `application/json` if the body parses as JSON, else `text/plain`.
    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]
    pub headers: std::collections::BTreeMap<String, String>,
    /// Inline response body. Mutually exclusive with `body_file`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body: Option<String>,
    /// Path to a file whose contents are served as the body, read at
    /// config publish time (the bytes are held in the snapshot). The
    /// path is relative to the config file directory. Mutually
    /// exclusive with `body`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub body_file: Option<String>,
    /// Simulated latency in milliseconds (0..=30000). The response is
    /// delayed by this long before the status/headers/body are sent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub delay_ms: Option<u32>,
}

/// Path rewrite applied before proxying (DW-010). Exactly one variant per
/// proxy action; there is no rewrite chaining in v1. All variants operate
/// on the path component only — the inbound query string is re-attached
/// untouched.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum PathRewrite {
    /// Strip the route's matched prefix (the `match.path.value` with
    /// trailing slashes trimmed) from the front of the request path.
    /// Meaningful for prefix-kind routes; for other kinds it strips the
    /// pattern's byte length when the path starts with the pattern value
    /// and is a no-op otherwise. If nothing remains (or the remainder
    /// lacks a leading `/`), the result is normalized to `/rest`.
    StripPrefix {},
    /// Replace a literal prefix: when the request path starts with
    /// `prefix`, that prefix is replaced by `replacement`; otherwise this
    /// rewrite is a no-op (the path is forwarded unchanged).
    ReplacePrefix { prefix: String, replacement: String },
    /// Replace the FIRST regex match on the request path with
    /// `substitution`. Substitution references: `$1`..`$9` / `${n}` for
    /// capture groups of `pattern`; `$name` / `${name}` for named capture
    /// groups of `pattern`, falling back to path parameters captured by
    /// the route's `{param}` template. Unknown references expand to the
    /// empty string. The pattern must compile — checked at config compile
    /// time, never at request time.
    Regex {
        pattern: String,
        substitution: String,
    },
}

/// The logical API being exposed: base path, version, default policies;
/// targets exactly one upstream, or a weighted split of upstreams
/// since DW-040 (canary / blue-green).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Service {
    pub name: String,
    /// Name of the upstream this service targets. Exactly one of
    /// `upstream` and [`Service::split`] must be set: a single-target
    /// service names its pool here; a canary/blue-green service uses
    /// `split` instead and leaves this unset. Optional since DW-040
    /// (it was the only shape before).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub upstream: Option<String>,
    /// Weighted traffic split across upstreams (DW-040, canary and
    /// blue-green): requests for this service are dispatched to one of
    /// the named upstreams by a deterministic weighted pick (the
    /// sticky cookie's value when [`Service::sticky`] is configured
    /// and the request carries one — sessions stay on their branch;
    /// otherwise the request id — per-request distribution whose
    /// ratios converge on the weights statistically). A weight of 0
    /// parks an upstream in the split without serving traffic (the
    /// blue-green switch: flip the weights and re-publish — the next
    /// request dispatches by the new generation, no restart). Ramp
    /// rule: change weights by RE-BALANCING (keep the total constant,
    /// e.g. 95/5 -> 90/10) — growing one side alone changes the pick's
    /// modulus and reshuffles every session's branch.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub split: Option<ServiceSplit>,
    /// Cookie affinity (DW-040): when set, the gateway sets a cookie
    /// on responses for this service whose VALUE consistently selects
    /// the split branch (and, when the branch upstream runs the
    /// `ip_hash` balancer, the endpoint — the cookie value becomes the
    /// ring key, reusing the consistent-hash machinery). The value is
    /// an opaque affinity handle: not a secret, carrying no identity,
    /// and never trusted as one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub sticky: Option<StickyAffinity>,
    /// Base path prefix the API is served under (e.g. `/v1`).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub base_path: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub version: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<String>,
    /// Service-level authorization rules (#123): applies to every request
    /// whose route targets this service. Link of the frozen chain
    /// consumer > route > service > listener > global (a deny at any
    /// level wins; otherwise the most specific level with rules governs —
    /// see [`Authz`] and the `authz` module). Same validation rules as
    /// route-level authorization.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authorization: Option<Authz>,
}

/// Weighted traffic split across upstreams (DW-040,
/// `services[].split`): canary releases and blue-green switches at the
/// SERVICE level — each target is a full upstream (its own endpoints,
/// protocol, health, and balancer), so a canary pool is isolated from
/// the stable one by construction. The pick is a deterministic
/// weighted hash (see [`Service::split`]): ratios hold statistically
/// per request and exactly per session when sticky affinity is on.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ServiceSplit {
    /// The weighted targets. Validation enforces 2..=8 entries (one
    /// target is what `services[].upstream` expresses), existing
    /// upstream names, no duplicates, and a positive total weight (a
    /// total of 0 would route nowhere; individual zeros are the
    /// parked side of a blue-green pair).
    pub targets: Vec<SplitTarget>,
    /// Auto-canary analysis (DW-091): when set, a background
    /// controller compares the canary (second target) vs the baseline
    /// (first target) on error rate or latency and adjusts the split
    /// weights automatically. Only valid when the split has exactly 2
    /// targets (baseline + canary). Weight changes are transient
    /// (Generation swap) and revert on config reload.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub canary_analysis: Option<CanaryAnalysis>,
}

/// One weighted target of a service split (DW-040).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct SplitTarget {
    /// Name of an upstream in this config.
    pub upstream: String,
    /// Relative share of requests (default 1). `0` parks the target
    /// (compiled, validated, serving nothing — the blue-green
    /// shape); validation caps the sum at a sane bound.
    #[serde(
        default = "default_split_weight",
        skip_serializing_if = "is_default_split_weight"
    )]
    pub weight: u32,
}

fn default_split_weight() -> u32 {
    1
}
fn is_default_split_weight(w: &u32) -> bool {
    *w == 1
}

/// Auto-canary analysis (DW-091): metrics-driven promotion/rollback of
/// canary split weights. A background controller compares the canary
/// side against the baseline on error rate or latency; on regression it
/// rolls the canary weight back (toward 0), on success it promotes
/// (toward the total weight). Severe regression (>2x the rollback
/// threshold) triggers an immediate rollback to 0. The total weight
/// stays constant: when the canary weight changes, the baseline
/// absorbs the difference, preserving the hash distribution for
/// existing sessions (the DW-040 invariant). Weight changes are
/// TRANSIENT (a Generation swap) and revert on config reload.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CanaryAnalysis {
    /// Master switch. Default true: an analysis block is active unless
    /// explicitly disabled.
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Look-back window for metrics, in seconds. The controller
    /// evaluates canary health over the recent window of observations.
    pub window_seconds: u64,
    /// Weight delta per adjustment (in weight units). Promote:
    /// increase canary weight by `step`. Rollback: decrease by `step`.
    /// Severe regression (>2x the rollback threshold) rolls back to 0
    /// immediately, ignoring the step.
    pub step: u32,
    /// Minimum total requests (baseline + canary) before the
    /// controller acts. Prevents acting on insufficient data.
    pub min_requests: u64,
    /// Cooldown between adjustments, in seconds. Prevents rapid
    /// oscillation: after one adjustment, the next is suppressed until
    /// the cooldown elapses.
    pub cooldown_seconds: u64,
    /// The promotion rule: when the canary metric is BELOW this
    /// threshold (good), the controller promotes (increases canary
    /// weight by `step`).
    pub promote: CanaryRule,
    /// The rollback rule: when the canary metric is ABOVE this
    /// threshold (bad), the controller rolls back (decreases canary
    /// weight by `step`). When the canary metric exceeds 2x this
    /// threshold (severe regression), the controller rolls back to 0
    /// immediately.
    pub rollback: CanaryRule,
}

/// One canary analysis rule (DW-091): a metric to compare and the
/// threshold that triggers the rule.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CanaryRule {
    /// The metric to compare canary vs baseline.
    pub metric: CanaryMetric,
    /// The threshold. For `promote`: the canary metric must be BELOW
    /// this (good) to promote. For `rollback`: the canary metric must
    /// be ABOVE this (bad) to roll back.
    pub threshold: f64,
}

/// The metric a canary rule compares (DW-091).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum CanaryMetric {
    /// HTTP error rate (status >= 500 / total requests).
    ErrorRate,
    /// P99 latency in milliseconds.
    LatencyP99,
    /// P95 latency in milliseconds.
    LatencyP95,
    /// P50 (median) latency in milliseconds.
    LatencyP50,
}

/// Cookie affinity for a service (DW-040, `services[].sticky`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct StickyAffinity {
    /// The cookie name the gateway reads and sets. Must be a valid
    /// cookie-name token (RFC 6265: the RFC 2616 `token` grammar);
    /// validation rejects anything else.
    pub cookie: String,
    /// `Max-Age` of the set cookie, in seconds (default 3600 — one
    /// hour; validated to 1..=2_592_000, 30 days).
    #[serde(
        default = "default_sticky_ttl_s",
        skip_serializing_if = "is_default_sticky_ttl_s"
    )]
    pub ttl_s: u64,
}

fn default_sticky_ttl_s() -> u64 {
    3_600
}
fn is_default_sticky_ttl_s(t: &u64) -> bool {
    *t == 3_600
}

/// DNS-based dynamic upstream discovery (DW-042): when present on an
/// upstream, a background discovery task resolves `hostname` via DNS,
/// watches the record TTL, and re-resolves when the TTL expires (or at
/// `refresh_interval_s`, whichever comes first), updating the upstream's
/// endpoint set live — without a restart. The `endpoints` field becomes
/// the INITIAL/fallback set: used until the first resolution completes
/// and as a fallback when DNS fails and `fail_open` is true. When
/// absent, endpoints remain static (the current behavior — no change).
///
/// Only A and SRV records are supported. A records pair each resolved
/// address with `port`; SRV records carry their own port. Consul watch
/// and Kubernetes EndpointSlice watch are deferred to a future
/// milestone — DNS is the first discovery source.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct DnsDiscovery {
    /// The DNS hostname to resolve (e.g. `my-service.example.com`).
    pub hostname: String,
    /// The port to pair with each resolved A-record address. Ignored
    /// for SRV records (they carry their own port).
    pub port: u16,
    /// How often to re-resolve, in seconds (default 30; bounded to
    /// 1..=3600). The actual refresh interval is
    /// `min(refresh_interval_s, record_ttl)` so a short-TTL record is
    /// refreshed sooner.
    #[serde(
        default = "default_dns_discovery_refresh_s",
        skip_serializing_if = "is_default_dns_discovery_refresh_s"
    )]
    pub refresh_interval_s: u64,
    /// DNS record type: `"A"` (default) or `"SRV"`.
    #[serde(
        default = "default_dns_discovery_record_type",
        skip_serializing_if = "is_default_dns_discovery_record_type"
    )]
    pub record_type: String,
    /// If true (default), keep the last resolved endpoint set when DNS
    /// fails. If false, clear endpoints on failure (the upstream
    /// answers 503 until DNS recovers).
    #[serde(
        default = "default_dns_discovery_fail_open",
        skip_serializing_if = "is_default_dns_discovery_fail_open"
    )]
    pub fail_open: bool,
    /// Minimum endpoints to keep serving (default 1). If a resolution
    /// yields fewer than this, the previous set is kept (the upstream
    /// does not shrink below the floor).
    #[serde(
        default = "default_dns_discovery_min_endpoints",
        skip_serializing_if = "is_default_dns_discovery_min_endpoints"
    )]
    pub min_endpoints: u32,
}

fn default_dns_discovery_refresh_s() -> u64 {
    30
}
fn is_default_dns_discovery_refresh_s(v: &u64) -> bool {
    *v == 30
}
fn default_dns_discovery_record_type() -> String {
    "A".to_string()
}
fn is_default_dns_discovery_record_type(v: &String) -> bool {
    v == "A"
}
fn default_dns_discovery_fail_open() -> bool {
    true
}
fn is_default_dns_discovery_fail_open(v: &bool) -> bool {
    *v
}
fn default_dns_discovery_min_endpoints() -> u32 {
    1
}
fn is_default_dns_discovery_min_endpoints(v: &u32) -> bool {
    *v == 1
}

/// Load-balancing pool: algorithm, protocol, endpoints.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Upstream {
    pub name: String,
    #[serde(default = "default_load_balancer")]
    pub load_balancer: LoadBalancer,
    /// DP-07 (#236): what to hash for consistent-hash load balancers
    /// (`ip_hash` and `maglev`). Defaults to `client_ip` (the pre-#236
    /// behavior). When set to `cookie` or `header`, the gateway extracts
    /// the value from the request and uses it as the hash key; if the
    /// cookie/header is absent, it falls back to the client IP.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hash_on: Option<HashOn>,
    /// Protocol used toward upstream endpoints.
    #[serde(default = "default_upstream_protocol")]
    pub protocol: UpstreamProtocol,
    /// Path to a PEM file of CA certificates this upstream's TLS
    /// connections trust INSTEAD of the default public (webpki) root set
    /// (#121): the way to proxy an `https`/`http2` upstream whose server
    /// certificate chains to a private CA. The file may carry several
    /// certificates (a typical CA bundle). Only meaningful for the TLS
    /// protocols — no TLS is negotiated toward `http1` endpoints, so
    /// validation rejects that combination. Active `http` health probes
    /// for this upstream verify against the same roots. The file must
    /// exist and be readable at config compile time; validation names
    /// this field otherwise.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trusted_ca_file: Option<String>,
    /// REL-08 (#219): when true, the upstream's TLS connections trust the
    /// OS-native root CA store (loaded via `rustls-native-certs`) INSTEAD
    /// of the bundled webpki root set. Useful in deployments whose
    /// private CAs are provisioned through the host's trust store (e.g.
    /// corporate PKI, cloud metadata CAs). Mutually exclusive with
    /// `trusted_ca_file` (validation rejects a configuration that sets
    /// both). Only meaningful for the TLS protocols (`https`/`http2`/`h3`)
    /// — no TLS is negotiated toward `http1` endpoints, so validation
    /// rejects that combination. Active health probes for this upstream
    /// verify against the same roots. Defaults to `false` (webpki roots).
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub use_system_roots: bool,
    /// Static endpoint list for this upstream. When `dns_discovery` is
    /// present, this becomes the initial/fallback set (used until the
    /// first DNS resolution completes and as a fallback when DNS fails
    /// and `fail_open` is true); it may be empty. When `dns_discovery`
    /// is absent, this is the complete endpoint set and must be
    /// non-empty (validation rejects an empty list).
    #[serde(default)]
    pub endpoints: Vec<Endpoint>,
    /// Maximum number of concurrent outbound connections to this upstream
    /// (active plus pooled idle). Defaults to 256 when absent. Enforced by
    /// the upstream client (DW-008); excess connection attempts wait for a
    /// slot rather than fail. Raised from 64 to 256 (#270) to avoid
    /// unbounded memory growth under high concurrency.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub connection_cap: Option<u32>,
    /// Slow-start window in milliseconds (DW-011): an endpoint entering the
    /// upstream's set ramps its effective load-balancing weight from ~0 up
    /// to its configured weight over this window. Absent (or 0) disables
    /// the ramp. Applies to the weighted algorithms (round_robin; ip_hash
    /// vnode counts stay fixed so ring consistency is preserved).
    /// Validation bounds the value to at most 10 minutes.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub slow_start_ms: Option<u64>,
    /// Passive health checking / outlier detection (DW-012): eject
    /// endpoints that fail real traffic (transport errors and 5xx), let
    /// them back via half-open trial probes after `eject_ms`. Absent
    /// disables passive health entirely (no ejections).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub health: Option<PassiveHealth>,
    /// Active health checks (DW-013): synthetic HTTP/TCP probes per
    /// endpoint on a fixed interval with full jitter. Probe results report
    /// into the SAME per-endpoint ejection machinery as passive health, so
    /// an endpoint failing its probes leaves load-balancer rotation and a
    /// success streak returns it. Requires the passive `health` block
    /// (which owns the ejection/recovery windows); rejected by validation
    /// otherwise. Absent disables active probing.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub active_health: Option<ActiveHealth>,
    /// Upstream retries (DW-014): bounded per-request retry attempts with
    /// exponential backoff + full jitter, a retry budget, and opt-in
    /// size-capped request-body buffering. Absent (or `attempts` left at
    /// its default 0) disables retries entirely: every request gets exactly
    /// one attempt and the proxy path keeps its zero-copy streaming body.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub retries: Option<RetryConfig>,
    /// Per-upstream circuit breaker (DW-015): opens the WHOLE upstream on
    /// consecutive failures or a rolling error ratio, fails fast with 503
    /// while open, probes half-open after `breaker.open_ms`. Absent
    /// disables the breaker entirely (no fail-fast, behavior identical to
    /// pre-DW-015).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub breaker: Option<BreakerConfig>,
    /// Maximum number of requests WAITING for an outbound connection slot
    /// to this upstream (DW-015). 0/absent (the default) means a bounded
    /// queue of 256 — the default bounds memory under high concurrency
    /// (#270). A positive value rejects excess requests IMMEDIATELY with
    /// 503 "upstream saturated" instead of letting them wait. To restore
    /// the pre-#270 unbounded queueing behavior, set a very large value.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_pending: Option<u32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timeouts: Option<Timeouts>,
    /// OAuth2 client-credentials proxying (DW-035): the gateway acts as
    /// an OAuth2 client itself, obtaining an access token from an
    /// external token endpoint via the client-credentials flow and
    /// forwarding it to this upstream as a `Bearer` token (replacing
    /// any client-supplied `Authorization` header). For service-to-
    /// service calls where the gateway authenticates to the upstream
    /// with a token it obtains from an OAuth2 token endpoint. Absent
    /// (the default): no token acquisition; the upstream sees whatever
    /// `Authorization` the client sent (subject to the authn family's
    /// pass-through rules). See the `security::oauth2` module docs for
    /// the flow, caching, and the mTLS-to-the-token-endpoint option.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub oauth2_client_credentials: Option<OAuth2ClientCredentials>,
    /// DNS-based dynamic upstream discovery (DW-042): when present, a
    /// background task resolves `hostname` via DNS and updates the
    /// endpoint set live as records change. The `endpoints` field
    /// becomes the initial/fallback set. Absent (the default): endpoints
    /// remain static (the current behavior — no change).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub dns_discovery: Option<DnsDiscovery>,
    /// Peak-EWMA tuning (DW-090): only meaningful when
    /// `load_balancer: peak_ewma`. Absent (the default) uses the built-in
    /// defaults (10 s decay tau, 250 ms initial cost). Ignored for the
    /// other algorithms.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub peak_ewma: Option<PeakEwmaConfig>,
    /// DW-094 (Ent): locality-aware routing and data residency. When
    /// present, the balancer filters or prefers endpoints by region/zone
    /// before applying the configured `load_balancer` algorithm. Ent-only:
    /// rejected at validation when the `ent` cargo feature is off.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub locality: Option<UpstreamLocality>,
    /// DW-105: opt in to post-quantum hybrid key exchange
    /// (X25519+ML-KEM) for this upstream's TLS connections. When
    /// `true`, the X25519+ML-KEM
    /// hybrid kx group is prepended to the rustls client config's kx
    /// group list, PREFERRING the hybrid group while keeping the
    /// classical X25519 fallback for non-PQ upstreams. Compiled into
    /// every build (no cargo feature).
    /// EXPERIMENTAL: the rustls PQ API is not yet stable. Only
    /// meaningful for the TLS protocols (`https`, `http2`); validation
    /// rejects `pq: true` on an `http1` upstream (no TLS is
    /// negotiated). Rejected when combined with FIPS mode (ML-KEM is
    /// not on the FIPS-validated list for aws-lc-rs).
    #[serde(default, skip_serializing_if = "is_false")]
    pub pq: bool,
    /// DW-109 / SEC-04: upstream TLS certificate pinning by SPKI
    /// SHA-256 hash. When present, the gateway's outbound TLS client
    /// installs a custom certificate verifier that extracts the peer
    /// cert's SubjectPublicKeyInfo, computes its SHA-256, and compares
    /// against the configured pins. A mismatch rejects the connection
    /// (fail-closed: no fallback to CA-based verification). Compiled
    /// into every build (no cargo feature). Only meaningful for the
    /// TLS protocols
    /// (`https`, `http2`); validation rejects it on an `http1`
    /// upstream.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cert_pinning: Option<CertPinningConfig>,
    /// SEC-03: upstream mTLS client certificates. When present, the
    /// gateway presents this client certificate to the upstream during
    /// the TLS handshake (in addition to verifying the upstream's
    /// server cert against `trusted_ca_file` or the public roots).
    /// Required for upstreams that demand client authentication
    /// (banking/payment APIs, mesh-internal services). Only meaningful
    /// for the TLS protocols (`https`, `http2`); validation rejects it
    /// on an `http1` upstream.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mtls: Option<UpstreamMtls>,
    /// DP-03: hyper connection-pool and HTTP/2 tuning for this
    /// upstream's outbound client. Absent (the default): every knob
    /// falls back to hyper-util's built-in defaults (the prior
    /// behavior — only the pool timer was wired). When present, the
    /// configured knobs are applied to the per-upstream hyper-util
    /// legacy client builder; omitted sub-fields keep their hyper
    /// defaults. The pool timer is ALWAYS installed (it is required
    /// for idle-timeout eviction to fire), so this block only needs to
    /// carry the knobs an operator wants to change. Meaningful for
    /// every protocol: `http1`/`https` connections reuse the pool's
    /// idle-timeout and max-idle-per-host knobs, while `http2`
    /// connections additionally honor the keep-alive and
    /// concurrent-streams knobs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pool: Option<UpstreamPoolConfig>,
}

/// DP-03: hyper connection-pool and HTTP/2 tuning for an upstream
/// (`upstreams[].pool`). Every field is optional; an omitted field
/// keeps hyper-util's built-in default (the same value the gateway
/// used before this block existed), so the block is purely additive.
/// Validation rejects zero/negative-forbidden values; the runtime
/// clamps nothing beyond the documented bounds.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct UpstreamPoolConfig {
    /// How long an idle connection may sit in the pool before it is
    /// closed (hyper-util `pool_idle_timeout`). In milliseconds.
    /// Absent: hyper-util's default (90 s). `0` is rejected at
    /// validation (use a very small positive value to evict
    /// aggressively, or omit the block for the default). Bounds: at
    /// most 10 minutes (600000 ms).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pool_idle_timeout_ms: Option<u64>,
    /// Maximum number of idle connections retained per host
    /// (hyper-util `pool_max_idle_per_host`). Absent: hyper-util's
    /// default. The per-upstream `connection_cap` still bounds the
    /// total (active + idle) connections, so this only shapes the
    /// idle fraction. Bounds: at most 1024.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pool_max_idle_per_host: Option<u32>,
    /// HTTP/2 PING keep-alive interval (hyper-util
    /// `http2_keep_alive_interval`). In milliseconds. Absent: disabled
    /// (hyper's default — no PINGs). A positive value sends a PING
    /// this often on an otherwise-idle h2 connection so proxies/ALB
    /// in front of the upstream do not reap it. Only meaningful for
    /// the `http2` protocol; ignored for `http1`/`https`. Bounds: at
    /// most 10 minutes (600000 ms).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub http2_keep_alive_interval_ms: Option<u64>,
    /// HTTP/2 keep-alive timeout (hyper-util
    /// `http2_keep_alive_timeout`): the time the client waits for a
    /// PING ACK before closing the connection. In milliseconds.
    /// Absent: hyper's default (20 s). Does nothing when
    /// `http2_keep_alive_interval_ms` is absent. Only meaningful for
    /// the `http2` protocol. Bounds: at most 10 minutes (600000 ms).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub http2_keep_alive_timeout_ms: Option<u64>,
    /// Enable HTTP/2 adaptive flow-control window (hyper-util
    /// `http2_adaptive_window`). Absent: false (hyper's default —
    /// fixed initial window). When true, the connection window grows
    /// and shrinks based on throughput, which helps large/long
    /// responses on high-BDP paths. Only meaningful for the `http2`
    /// protocol; ignored otherwise.
    #[serde(default, skip_serializing_if = "is_false")]
    pub http2_adaptive_window: bool,
    /// Initial cap on the number of concurrent HTTP/2 streams the
    /// client will send over a single connection (hyper-util
    /// `http2_initial_max_send_streams`). This is an *initial* value
    /// only: hyper-util's default is 100, and the effective cap is
    /// further bounded by the server's advertised
    /// SETTINGS_MAX_CONCURRENT_STREAMS once the peer's SETTINGS frame
    /// arrives. A finite value bounds head-of-line blocking when one
    /// stream stalls. Only meaningful for the `http2` protocol.
    /// Bounds: at least 1, at most 1_000_000.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_concurrent_streams: Option<u32>,
    /// SCALE-10 (#189): number of connections to pre-establish per
    /// endpoint on startup/reload. Pre-warming removes cold-start
    /// latency spikes after reloads and upgrade hand-offs. `0` or
    /// absent: no pre-warming (the default — connections are
    /// established on first use). Bounds: at most 64 per endpoint.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pre_warm: Option<u32>,
    /// SCALE-10 (#189): per-endpoint connection cap, bounding
    /// concurrent connections to a SINGLE endpoint (address:port)
    /// within the upstream. The per-upstream `connection_cap` still
    /// bounds the total across all endpoints; this knob prevents one
    /// busy endpoint from monopolizing the upstream's connection
    /// budget. Absent: no per-endpoint cap (only the per-upstream
    /// cap applies). Bounds: at least 1, at most 1024.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub per_endpoint_cap: Option<u32>,
    /// SCALE-10 (#189): maximum age of a pooled connection before it
    /// is recycled. In milliseconds. Absent: no max-age (connections
    /// live until the idle timeout or a peer-initiated close). A
    /// positive value sets the pool idle timeout to the minimum of
    /// this and `pool_idle_timeout_ms`, so connections are evicted
    /// before they become stale. Bounds: at most 10 minutes
    /// (600000 ms).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_connection_age_ms: Option<u64>,
    /// Initial stream-level window size in bytes for the upstream h2
    /// client (hyper `http2_initial_stream_window_size`). Absent:
    /// hyper's default. Larger values reduce flow-control stalls on
    /// streaming (SSE) responses from the upstream but increase
    /// memory per stream. Only meaningful for the `http2` protocol.
    /// Bounds: at most 16 MiB. (PERF-11, #244)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub http2_initial_stream_window_size: Option<u32>,
    /// Initial connection-level window size in bytes for the upstream
    /// h2 client (hyper `http2_initial_connection_window_size`).
    /// Absent: hyper's default. Bounds: at most 64 MiB.
    /// (PERF-11, #244)
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub http2_initial_connection_window_size: Option<u32>,
}

/// SEC-03: upstream mTLS client certificate configuration. Reuses the
/// two-path shape (cert file + key file) proven by the OAuth2 mTLS
/// config (`OAuth2Mtls`).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct UpstreamMtls {
    /// Path to the PEM client certificate chain to present to the
    /// upstream during the TLS handshake.
    pub client_cert_file: String,
    /// Path to the PEM private key for `client_cert_file`.
    pub client_key_file: String,
}

/// DW-109 / SEC-04: certificate pinning configuration for an upstream.
/// Holds a list of allowed SPKI SHA-256 hashes (lowercase hex, 64
/// chars). A peer cert whose SPKI hash matches ANY entry is accepted;
/// otherwise the connection is rejected (fail-closed).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CertPinningConfig {
    /// The allowed SPKI SHA-256 hashes (lowercase hex, 64 chars each).
    /// Must be non-empty (validation rejects an empty pin list — a
    /// pin-less pinning block is an authoring mistake, not "pin
    /// nothing").
    pub pins: Vec<CertPin>,
}

/// A single certificate pin: the SHA-256 hash of the upstream
/// certificate's SubjectPublicKeyInfo (SPKI), as lowercase hex (64
/// chars). Pinning the SPKI (rather than the full certificate) allows
/// rotation of the leaf certificate as long as the key pair is
/// unchanged.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CertPin {
    /// The SHA-256 hash of the SPKI, as lowercase hex (64 chars).
    pub spki_sha256: String,
}

/// DW-094 (Ent): locality-aware routing and data residency configuration
/// for an upstream. Controls how the balancer uses endpoint `region`/
/// `zone` fields to filter or prefer endpoints.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct UpstreamLocality {
    /// The routing mode (DW-094):
    /// - `prefer`: prefer endpoints in the edge's region; fall back to
    ///   other regions if none are available (healthy).
    /// - `strict`: only route to endpoints in the edge's region; fail
    ///   with 503 if none are available (no cross-region fallback).
    /// - `failover`: prefer the edge's region, fall back to other
    ///   regions only when all local endpoints are ejected (like
    ///   `prefer` but with a stricter local-first policy — local
    ///   endpoints are always tried first even if unhealthy).
    #[serde(default)]
    pub mode: LocalityMode,
    /// Data residency enforcement: when true, the balancer drops
    /// endpoints whose `region` is not in `allowed_regions` BEFORE
    /// applying the locality mode. This is a hard constraint —
    /// endpoints outside the allowed set are never used, even as a
    /// fallback. Use this to comply with data sovereignty requirements
    /// (e.g. EU traffic must stay in EU regions).
    #[serde(default)]
    pub enforce_data_residency: bool,
    /// The allowed regions when `enforce_data_residency` is true. An
    /// endpoint with no `region` field is always allowed (locality-
    /// agnostic). An endpoint with a `region` not in this list is
    /// dropped. Must be non-empty when `enforce_data_residency` is true.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed_regions: Vec<String>,
    /// The denied regions (optional). An endpoint with a `region` in
    /// this list is always dropped, regardless of other settings. Use
    /// this to exclude specific regions without enumerating all
    /// allowed ones.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub denied_regions: Vec<String>,
}

/// DW-094 (Ent): locality routing mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema, Default)]
#[serde(rename_all = "snake_case")]
pub enum LocalityMode {
    /// Prefer endpoints in the edge's region; fall back to other
    /// regions if none are available (healthy). The default.
    #[default]
    Prefer,
    /// Only route to endpoints in the edge's region; fail with 503 if
    /// none are available (no cross-region fallback).
    Strict,
    /// Prefer the edge's region, fall back to other regions only when
    /// all local endpoints are ejected (local-first with failover).
    Failover,
}

/// DW-094 (Ent): the edge's locality context — its region and zone.
/// Threaded into the balancer at request time to enable locality-aware
/// endpoint selection. When both `region` and `zone` are `None`, the
/// balancer skips locality filtering (the OSS behavior).
///
/// The context is set from `EdgeState.labels` (the `region` and `zone`
/// keys) when running as an edge, or from the `DWARA_REGION`/
/// `DWARA_ZONE` environment variables in embedded mode.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct LocalityContext {
    /// The edge's region (e.g. `us-east-1`).
    pub region: Option<String>,
    /// The edge's zone (e.g. `us-east-1a`).
    pub zone: Option<String>,
}

impl LocalityContext {
    /// Create a new locality context.
    pub fn new(region: Option<String>, zone: Option<String>) -> Self {
        Self { region, zone }
    }

    /// Whether locality-aware routing should be applied (at least one
    /// of region/zone is set).
    pub fn is_set(&self) -> bool {
        self.region.is_some() || self.zone.is_some()
    }

    /// Whether an endpoint region matches this context's region.
    /// An endpoint with no region is always a match (locality-agnostic).
    pub fn region_matches(&self, endpoint_region: Option<&str>) -> bool {
        match (&self.region, endpoint_region) {
            (Some(ctx_region), Some(ep_region)) => ctx_region == ep_region,
            _ => true,
        }
    }

    /// Whether an endpoint zone matches this context's zone.
    /// An endpoint with no zone is always a match (zone-agnostic).
    pub fn zone_matches(&self, endpoint_zone: Option<&str>) -> bool {
        match (&self.zone, endpoint_zone) {
            (Some(ctx_zone), Some(ep_zone)) => ctx_zone == ep_zone,
            _ => true,
        }
    }

    /// Load the locality context from environment variables
    /// (`DWARA_REGION`, `DWARA_ZONE`). Returns a context with `None`
    /// values when the variables are not set.
    pub fn from_env() -> Self {
        Self {
            region: std::env::var("DWARA_REGION").ok(),
            zone: std::env::var("DWARA_ZONE").ok(),
        }
    }
}

/// Peak-EWMA load-balancing tuning (DW-090, `upstreams[].peak_ewma`).
/// Only consulted when `load_balancer: peak_ewma`; ignored otherwise.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PeakEwmaConfig {
    /// Decay tau in milliseconds (default 10 000 = 10 s). The EWMA weight
    /// is `exp(-td / tau)` where `td` is the time since the last update.
    /// A larger tau makes the cost track slow endpoints more sluggishly
    /// (more stable, less reactive); a smaller tau reacts faster to
    /// latency changes. Must be > 0.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub decay_ms: Option<u64>,
    /// Initial cost in milliseconds (default 250). A fresh endpoint's
    /// EWMA cost starts here (converted to nanoseconds) so the first
    /// picks have a reasonable baseline before any real RTT is observed.
    /// Must be > 0.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub default_rtt_ms: Option<u64>,
}

/// OAuth2 client-credentials configuration for an upstream (DW-035,
/// `upstreams[].oauth2_client_credentials`).
///
/// The gateway obtains an access token from `token_endpoint` using the
/// client-credentials grant (RFC 6749 section 4.4) and forwards it to
/// the upstream as `Authorization: Bearer <token>`. The client
/// authenticates to the token endpoint with HTTP Basic auth
/// (`client_id:client_secret`, RFC 6749 section 2.3.1). Tokens are
/// cached per upstream (keyed by upstream name on the dataplane) and
/// refreshed lazily on the first request after expiry — no background
/// refresh task. An optional `mtls` block configures a client
/// certificate for the TLS handshake to the token endpoint itself
/// (RFC 8705, the `tls_client_auth` method).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OAuth2ClientCredentials {
    /// The token endpoint URL (RFC 6749 section 3.2). Must be an
    /// absolute `http(s)://` URL; validation rejects anything else.
    pub token_endpoint: String,
    /// The client identifier presented to the token endpoint
    /// (RFC 6749 section 2.2). Sent as the username of the HTTP Basic
    /// auth header.
    pub client_id: String,
    /// The client secret presented to the token endpoint (RFC 6749
    /// section 2.3.1). Either the value INLINE (redacted in every
    /// config echo, DW-045) or a `${...}` secret reference (env or
    /// file) resolved at config-compile time and re-read on every
    /// reload. Sent as the password of the HTTP Basic auth header.
    pub client_secret: String,
    /// Optional scope string (RFC 6749 section 3.3): a space-delimited
    /// list of requested scopes sent in the token request body. Absent
    /// = no scope parameter (the endpoint's default scopes apply).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub scopes: Vec<String>,
    /// Optional mTLS client certificate for the TLS handshake to the
    /// token endpoint itself (RFC 8705 `tls_client_auth`). Absent: the
    /// token endpoint's TLS is negotiated with no client certificate
    /// (the default webpki root set, or a `trusted_ca_file` when the
    /// token endpoint is behind a private CA — note the token endpoint
    /// trust is NOT the upstream's `trusted_ca_file`; the token
    /// endpoint is a separate entity).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub mtls: Option<OAuth2Mtls>,
    /// Token cache TTL override in seconds. Absent (the default): use
    /// the token's own `expires_in` (minus a refresh skew margin). When
    /// set, the cache TTL is `min(token_expires_in - skew,
    /// token_cache_ttl_s)` so a shorter override never extends a
    /// token's real lifetime. Must be > 0.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token_cache_ttl_s: Option<u64>,
}

/// mTLS client certificate for an OAuth2 token endpoint (DW-035,
/// `oauth2_client_credentials.mtls`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct OAuth2Mtls {
    /// Path to a PEM file containing the client certificate chain.
    pub client_cert: String,
    /// Path to a PEM file containing the matching private key.
    pub client_key: String,
}

/// Upstream retry knobs (DW-014). All fields default; a `retries:` block
/// with no keys is equivalent to retries off (`attempts` defaults to 0).
///
/// Frozen semantics (see `upstream`/`proxy`/`retries` module docs):
/// - `attempts` is the maximum number of RETRIES beyond the first attempt
///   (0 = off). Validation caps it at 10.
/// - Only requests whose body was fully buffered within `buffer_max_bytes`
///   may be retried; an over-cap body streams without retry. Buffering is
///   opt-in: the default (0) buffers only empty bodies, so the default
///   proxy path stays unbuffered.
/// - Retries happen strictly BEFORE response headers arrive on the final
///   attempt; a response body that dies mid-stream is never retried (its
///   failure is reported to passive health instead).
/// - Every retried attempt is charged against the upstream's rolling-window
///   retry budget (`budget_percent`).
/// - `total_deadline_ms` (REL-01) caps the wall-clock time from the first
///   attempt to the last, INCLUDING backoff delays between attempts. Absent
///   leaves the cross-attempt budget unbounded (the v1 default, kept for
///   backwards compatibility). When set, a retry whose backoff would cross
///   the deadline is aborted and the last response/error is returned to the
///   client; the per-attempt `read_ms` timeout still bounds each individual
///   attempt. Standard in Envoy and NGINX.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RetryConfig {
    /// Maximum retries beyond the first attempt (default 0 = off).
    #[serde(default = "default_retry_attempts")]
    pub attempts: u32,
    /// Retry non-idempotent POST requests. Default false: POST is never
    /// retried unless an operator explicitly opts in here (a retried POST
    /// may replay a body the upstream already partially processed).
    #[serde(default = "default_retry_post", skip_serializing_if = "is_false")]
    pub retry_post: bool,
    /// Exponential backoff base in milliseconds (default 25): the nominal
    /// delay before retry n is `min(base * 2^(n-1), backoff_cap_ms)`.
    #[serde(default = "default_retry_backoff_base_ms")]
    pub backoff_base_ms: u64,
    /// Exponential backoff ceiling in milliseconds (default 250). Must be
    /// >= `backoff_base_ms`.
    #[serde(default = "default_retry_backoff_cap_ms")]
    pub backoff_cap_ms: u64,
    /// Response statuses that trigger a retry when received as the upstream
    /// response status (default `[502, 503, 504]`). Each entry must be a
    /// valid 4xx/5xx status. An empty list disables status-based retries.
    #[serde(default = "default_retry_statuses")]
    pub retry_statuses: Vec<u16>,
    /// Retry on transport errors (connect timeout/refusal/reset/framing)
    /// and per-attempt read timeouts (default true).
    #[serde(default = "default_retry_transport", skip_serializing_if = "is_true")]
    pub retry_transport: bool,
    /// Retry budget: the maximum percentage of requests to this upstream,
    /// in a rolling window, that may be retries (default 10). Must be in
    /// (0, 100]. When the budget is exhausted, failing requests fail
    /// through to the client instead of retrying.
    #[serde(default = "default_retry_budget_percent")]
    pub budget_percent: u32,
    /// Request-body buffering cap in bytes (default 0 = no buffering). A
    /// request body is buffered (and becomes replayable) only while it fits
    /// within this cap; larger bodies stream and are never retried.
    #[serde(default)]
    pub buffer_max_bytes: u64,
    /// Request hedging (DW-063): after `hedge_after_ms` milliseconds
    /// without a response, a speculative duplicate request is sent to a
    /// different endpoint; the first response wins and the loser is
    /// cancelled. Requires `buffer_max_bytes > 0` (the body must be
    /// replayable to send a hedge copy) and idempotent methods (GET,
    /// HEAD, OPTIONS, TRACE, PUT) — POST is hedged only when
    /// `retry_post` is also true. Absent (or `hedge_after_ms` = 0)
    /// disables hedging. At most `hedge_max` speculative copies are
    /// sent per request (default 1).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub hedge: Option<HedgeConfig>,
    /// Cross-attempt total retry deadline in milliseconds (REL-01): caps
    /// the wall-clock time from the first attempt to the last, INCLUDING
    /// backoff delays between attempts. Absent leaves the cross-attempt
    /// budget unbounded (the v1 default, kept for backwards
    /// compatibility). When set, a retry whose backoff would cross the
    /// deadline is aborted and the last response/error is returned to the
    /// client; the per-attempt `read_ms` timeout still bounds each
    /// individual attempt. Must be in (0, `MAX_RETRY_TOTAL_DEADLINE_MS`];
    /// `0` is rejected (omit the field for unbounded).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub total_deadline_ms: Option<u64>,
    /// Streaming failover first-frame buffer cap in bytes (REL-05, #216).
    /// When > 0, the proxy buffers up to this many bytes of the upstream
    /// response body BEFORE forwarding any bytes to the client. If the
    /// upstream fails (connection reset, read timeout, framing error)
    /// before the buffer fills or the body completes, the proxy can
    /// still retry the request to a different endpoint — the client has
    /// not yet received any bytes, so the response is not committed.
    /// Once the buffer fills (or the body completes), the buffered
    /// prefix is flushed to the client and the rest of the body streams
    /// frame-by-frame (the stream is then committed; a later mid-body
    /// failure is terminal, as in v1). Default 0 = no first-frame
    /// buffering (v1 behavior: the response is committed as soon as
    /// headers resolve). Requires `attempts > 0` and
    /// `buffer_max_bytes > 0` (the request body must be replayable).
    #[serde(default)]
    pub buffer_first_frame_bytes: u64,
}

impl Default for RetryConfig {
    fn default() -> Self {
        RetryConfig {
            attempts: default_retry_attempts(),
            retry_post: default_retry_post(),
            backoff_base_ms: default_retry_backoff_base_ms(),
            backoff_cap_ms: default_retry_backoff_cap_ms(),
            retry_statuses: default_retry_statuses(),
            retry_transport: default_retry_transport(),
            budget_percent: default_retry_budget_percent(),
            buffer_max_bytes: 0,
            hedge: None,
            total_deadline_ms: None,
            buffer_first_frame_bytes: 0,
        }
    }
}

/// Request hedging configuration (DW-063, `upstreams[].retries.hedge`).
///
/// After `hedge_after_ms` without a response, a speculative duplicate
/// request is sent to a different endpoint. The first response (headers
/// resolved) wins; the loser is cancelled. Hedging requires a replayable
/// body (`buffer_max_bytes > 0`) and idempotent semantics (POST is hedged
/// only when `retry_post` is true).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct HedgeConfig {
    /// Milliseconds to wait before sending a hedge copy (the "tail
    /// latency" threshold). Must be > 0. A typical value is the p90
    /// latency of the upstream — requests slower than this get a
    /// speculative parallel copy.
    pub hedge_after_ms: u64,
    /// Maximum number of speculative hedge copies per request (default
    /// 1). Must be in [1, 4]. Hedge copies are NOT charged against the
    /// retry budget — the budget prevents retry storms after failures,
    /// while hedging is a proactive performance optimization.
    #[serde(default = "default_hedge_max")]
    pub hedge_max: u32,
}

fn default_hedge_max() -> u32 {
    1
}

fn default_retry_attempts() -> u32 {
    0
}

fn default_retry_post() -> bool {
    false
}

fn default_retry_backoff_base_ms() -> u64 {
    25
}

fn default_retry_backoff_cap_ms() -> u64 {
    250
}

fn default_retry_statuses() -> Vec<u16> {
    vec![502, 503, 504]
}

fn default_retry_transport() -> bool {
    true
}

fn default_retry_budget_percent() -> u32 {
    10
}

fn is_false(b: &bool) -> bool {
    !*b
}

/// Per-upstream circuit breaker knobs (DW-015). All fields default; a
/// `breaker:` block with no keys enables the breaker with the defaults.
///
/// Frozen semantics (see the `breaker` module docs):
/// - The breaker gates the WHOLE upstream (all endpoints); per-endpoint
///   ejection (DW-012) is an independent layer beneath it.
/// - It opens on `consecutive_failures` consecutive failures (5xx or
///   transport) OR an in-window error ratio >= `error_ratio` once at least
///   `error_volume` observations are in the 60 s window.
/// - While open, requests fail fast with 503 and a `Retry-After` header
///   (seconds until half-open); in-flight requests complete normally.
/// - After `open_ms` a half-open probe (`half_open_probes` concurrent
///   trials) closes the breaker on success or re-opens it on failure.
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct BreakerConfig {
    /// Consecutive failures (5xx + transport) that open the breaker
    /// (default 5).
    #[serde(default = "default_breaker_consecutive_failures")]
    pub consecutive_failures: u32,
    /// In-window error ratio in (0, 1] that opens the breaker once
    /// `error_volume` observations exist (default 0.5).
    #[serde(default = "default_breaker_error_ratio")]
    pub error_ratio: f64,
    /// Minimum observations in the 60 s window before the ratio is
    /// evaluated (default 20).
    #[serde(default = "default_breaker_error_volume")]
    pub error_volume: u32,
    /// Cooling-off period in milliseconds before a half-open probe is
    /// admitted (default 30000).
    #[serde(default = "default_breaker_open_ms")]
    pub open_ms: u64,
    /// Concurrent trial requests admitted in half-open (default 1).
    #[serde(default = "default_breaker_half_open_probes")]
    pub half_open_probes: u32,
}

impl Default for BreakerConfig {
    fn default() -> Self {
        BreakerConfig {
            consecutive_failures: default_breaker_consecutive_failures(),
            error_ratio: default_breaker_error_ratio(),
            error_volume: default_breaker_error_volume(),
            open_ms: default_breaker_open_ms(),
            half_open_probes: default_breaker_half_open_probes(),
        }
    }
}

fn default_breaker_consecutive_failures() -> u32 {
    5
}

fn default_breaker_error_ratio() -> f64 {
    0.5
}

fn default_breaker_error_volume() -> u32 {
    20
}

fn default_breaker_open_ms() -> u64 {
    30_000
}

fn default_breaker_half_open_probes() -> u32 {
    1
}

fn is_true(b: &bool) -> bool {
    *b
}

fn default_false() -> bool {
    false
}

/// Passive health / outlier detection knobs (DW-012). All fields default;
/// a `health:` block with no keys enables ejection with the defaults.
///
/// Failure classification: transport errors (connect timeout, refusal,
/// reset) and HTTP statuses >= 500 are failures; 1xx-4xx are successes.
/// 429/408 are deliberately successes in v1 (they describe the caller or
/// queueing, not endpoint health).
#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PassiveHealth {
    /// Rolling observation window for the failure ratio, in milliseconds
    /// (default 60000).
    #[serde(default = "default_health_window_ms")]
    pub window_ms: u64,
    /// Eject after this many consecutive failures (default 5).
    #[serde(default = "default_health_consecutive_failures")]
    pub consecutive_failures: u32,
    /// Eject when the in-window failure share is >= this ratio AND volume
    /// is >= `failure_min_volume`. Must be in (0, 1] (default 0.5).
    #[serde(default = "default_health_failure_ratio")]
    pub failure_ratio: f64,
    /// Minimum observations in the window before `failure_ratio` applies
    /// (default 20).
    #[serde(default = "default_health_failure_min_volume")]
    pub failure_min_volume: u32,
    /// How long an ejected endpoint stays out of rotation, in milliseconds
    /// (default 30000).
    #[serde(default = "default_health_eject_ms")]
    pub eject_ms: u64,
    /// Trial requests allowed through per half-open recovery attempt
    /// (default 1). A successful probe restores health; a failed probe
    /// re-ejects for another `eject_ms`.
    #[serde(default = "default_health_half_open_probes")]
    pub half_open_probes: u32,
    /// Recovery ramp window in milliseconds (REL-06, #217). When > 0,
    /// an endpoint that recovers from ejection (a half-open probe
    /// succeeds) does NOT immediately return to full traffic. Instead
    /// it ramps its effective weight from a floor (1) to its
    /// configured weight over this window, reducing the blast radius
    /// of a partial recovery (the endpoint may still be slow or
    /// partially degraded). Default 0 = no ramp (v1 behavior: a
    /// successful probe restores full weight immediately).
    #[serde(default)]
    pub recovery_ramp_ms: u64,
    /// Whether the in-flight counter is held until the response body
    /// completes (REL-06, #217). Default false: the in-flight counter
    /// is released when response headers resolve (v1 behavior). When
    /// true, the counter is held until the body stream ends or is
    /// dropped, giving `least_requests`, `random`, and `peak_ewma` a
    /// more accurate view of actual endpoint load. The trade-off is a
    /// slightly higher in-flight count under streaming workloads.
    #[serde(default = "default_false", skip_serializing_if = "is_false")]
    pub body_completion_inflight: bool,
}

impl Default for PassiveHealth {
    fn default() -> Self {
        PassiveHealth {
            window_ms: 60_000,
            consecutive_failures: 5,
            failure_ratio: 0.5,
            failure_min_volume: 20,
            eject_ms: 30_000,
            half_open_probes: 1,
            recovery_ramp_ms: 0,
            body_completion_inflight: false,
        }
    }
}

fn default_health_window_ms() -> u64 {
    60_000
}

fn default_health_consecutive_failures() -> u32 {
    5
}

fn default_health_failure_ratio() -> f64 {
    0.5
}

fn default_health_failure_min_volume() -> u32 {
    20
}

fn default_health_eject_ms() -> u64 {
    30_000
}

fn default_health_half_open_probes() -> u32 {
    1
}

/// Active health check knobs (DW-013). A block with no keys enables HTTP
/// probes with the defaults.
///
/// Probe semantics (frozen):
/// - `http` probes issue `GET {path}` over HTTP/1.1 DIRECTLY to the
///   endpoint (bypassing load balancing and the pooled client); success is
///   a 2xx status. Redirects (3xx) are NOT followed — a health endpoint
///   answering 3xx is treated as a failure (a load balancer must not chase
///   redirects to decide health).
/// - `tcp` probes succeed when a TCP connection completes within
///   `timeout_ms`.
/// - Full jitter: each loop sleeps `interval_ms` plus a uniform random
///   `0..jitter_ms` before the next probe.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ActiveHealth {
    /// Probe kind (default `http`).
    #[serde(default = "default_probe_kind")]
    pub kind: ProbeKind,
    /// Path probed by `http` checks (default `/healthz`). Ignored by `tcp`.
    #[serde(
        default = "default_probe_path",
        skip_serializing_if = "is_default_probe_path"
    )]
    pub path: String,
    /// Time between probe attempts in milliseconds (default 5000). Must be
    /// >= `timeout_ms` and >= `jitter_ms`.
    #[serde(default = "default_probe_interval_ms")]
    pub interval_ms: u64,
    /// Per-probe timeout in milliseconds (default 2000), covering connect
    /// plus the response for http probes.
    #[serde(default = "default_probe_timeout_ms")]
    pub timeout_ms: u64,
    /// Consecutive probe SUCCESSES required to (re)admit an ejected
    /// endpoint (default 2).
    #[serde(default = "default_probe_success_threshold")]
    pub success_threshold: u32,
    /// Consecutive probe FAILURES required to eject a healthy endpoint
    /// (default 3). Reports the same per-endpoint streak the passive
    /// checker uses; see the active-health module docs for precedence.
    #[serde(default = "default_probe_failure_threshold")]
    pub failure_threshold: u32,
    /// Full-jitter bound in milliseconds (default 500): each loop sleeps a
    /// uniform random `0..jitter_ms` in addition to `interval_ms`. Must be
    /// <= `interval_ms`.
    #[serde(default = "default_probe_jitter_ms")]
    pub jitter_ms: u64,
}

impl Default for ActiveHealth {
    fn default() -> Self {
        ActiveHealth {
            kind: default_probe_kind(),
            path: default_probe_path(),
            interval_ms: default_probe_interval_ms(),
            timeout_ms: default_probe_timeout_ms(),
            success_threshold: default_probe_success_threshold(),
            failure_threshold: default_probe_failure_threshold(),
            jitter_ms: default_probe_jitter_ms(),
        }
    }
}

fn default_probe_kind() -> ProbeKind {
    ProbeKind::Http
}

fn default_probe_path() -> String {
    "/healthz".to_string()
}

fn is_default_probe_path(p: &str) -> bool {
    p == "/healthz"
}

fn default_probe_interval_ms() -> u64 {
    5_000
}

fn default_probe_timeout_ms() -> u64 {
    2_000
}

fn default_probe_success_threshold() -> u32 {
    2
}

fn default_probe_failure_threshold() -> u32 {
    3
}

fn default_probe_jitter_ms() -> u64 {
    500
}

/// Kind of active health probe.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum ProbeKind {
    /// HTTP/1.1 GET to `path`; success = 2xx.
    Http,
    /// HTTP/2 GET to `path` over a pooled H2 connection (REL-07, #218);
    /// for HTTP/2-only and gRPC upstreams that refuse HTTP/1.1 on a
    /// separate connection. Success = 2xx.
    Http2,
    /// TCP connect within the timeout.
    Tcp,
}

fn default_load_balancer() -> LoadBalancer {
    LoadBalancer::RoundRobin
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum LoadBalancer {
    RoundRobin,
    LeastRequests,
    Random,
    IpHash,
    /// Maglev consistent hashing (DP-07, #236): Google's Maglev algorithm
    /// uses a fixed-size lookup table (default 65537 entries) populated
    /// by each endpoint's permutation. Provides better distribution than
    /// ketama for large endpoint pools with tight balance bounds. The
    /// hash key is determined by `hash_on` (client IP, cookie, or header).
    Maglev,
    /// Peak-EWMA latency-aware load balancing (DW-090, Finagle-style):
    /// favors low-latency endpoints and degrades outliers. Each endpoint
    /// carries an atomic EWMA cost tracker (nanosecond resolution) updated
    /// with the Finagle peak-EWMA formula: a new RTT that EXCEEDS the
    /// current cost replaces it outright (the "peak"), otherwise the cost
    /// decays toward the new RTT at rate `exp(-td / tau)`. Selection picks
    /// the endpoint with the lowest `cost_ns * (inflight + 1)` score, so a
    /// slow endpoint with few in-flight requests can still win a pick
    /// while a fast one is saturated. Tunable via `upstreams[].peak_ewma`
    /// (decay tau and the initial cost); defaults are 10 s decay and a
    /// 250 ms initial cost. Carried across rebuilds by `address:port`,
    /// exactly like in-flight counters and health trackers.
    PeakEwma,
}

/// What to hash for consistent-hash load balancers (`ip_hash` and
/// `maglev`). DP-07 (#236): extends the hash key source beyond the
/// client IP to support cookie-based sticky sessions and header-based
/// affinity.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum HashOn {
    /// Hash the client IP (the default behavior, backward-compatible
    /// with pre-#236 configs).
    #[default]
    ClientIp,
    /// Hash a cookie value. If the cookie is not present in the request,
    /// the gateway falls back to the client IP. Used for sticky sessions
    /// without the `services[].sticky` split mechanism.
    Cookie {
        /// The cookie name to read.
        cookie: String,
    },
    /// Hash a request header value. If the header is not present, falls
    /// back to the client IP. Common for routing by `X-User-Id` or
    /// `X-Session-Id` for session affinity.
    Header {
        /// The header name to read (case-insensitive).
        header: String,
    },
}

fn default_upstream_protocol() -> UpstreamProtocol {
    UpstreamProtocol::Http1
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum UpstreamProtocol {
    Http1,
    Http2,
    /// Cleartext HTTP/2 with prior knowledge (h2c, DP-02 #235). No TLS;
    /// the client speaks HTTP/2 directly over TCP. Common for internal
    /// east-west gRPC traffic without TLS.
    H2c,
    Https,
    /// HTTP/3 over QUIC (DW-108). QUIC mandates TLS 1.3, so an `h3`
    /// upstream always negotiates TLS with ALPN `h3`; the
    /// `trusted_ca_file` field selects the trust roots (the default
    /// webpki public set, or a private-CA bundle). Requires the `h3`
    /// cargo feature on dwara-bin to actually proxy: when the feature is
    /// off the protocol is accepted at validation but the upstream is
    /// inert (every dispatch fails closed with a clear error rather than
    /// silently falling back to a wrong transport).
    H3,
}

/// One `address:port` inside an upstream.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Endpoint {
    pub address: String,
    pub port: u16,
    /// Relative traffic weight (default 1 for all endpoints).
    #[serde(
        default = "default_endpoint_weight",
        skip_serializing_if = "is_default_weight"
    )]
    pub weight: u32,
    /// DW-094 (Ent): the region this endpoint belongs to (e.g.
    /// `us-east-1`, `eu-west-1`). Used by locality-aware load balancing
    /// and data residency enforcement. Optional — endpoints without a
    /// region are treated as locality-agnostic (always eligible).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub region: Option<String>,
    /// DW-094 (Ent): the zone within a region (e.g. `us-east-1a`).
    /// Used for zone-aware routing within a region. Optional.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub zone: Option<String>,
}

fn default_endpoint_weight() -> u32 {
    1
}

fn is_default_weight(w: &u32) -> bool {
    *w == 1
}

/// Timeout hints, in milliseconds.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Timeouts {
    /// Connect timeout in milliseconds.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub connect_ms: Option<u64>,
    /// Read timeout in milliseconds.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub read_ms: Option<u64>,
    /// Write timeout in milliseconds.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub write_ms: Option<u64>,
    /// Happy-eyeballs inter-connection delay in milliseconds (DW-030,
    /// RFC 8305): when an endpoint's address resolves to multiple
    /// addresses, the first is dialed immediately and each subsequent
    /// address — alternating address families after the resolver's
    /// first — is diailed this long after the previous START; the first
    /// successful connection wins and cancels the losers. Absent: the
    /// RFC 8305 recommended 250 ms. `0` disables racing (addresses are
    /// tried strictly in resolver order, one at a time). The upstream's
    /// `connect_ms` remains the bound over the WHOLE dial: resolution
    /// plus every interleaved attempt plus, for TLS upstreams, the
    /// handshake. Only the overall dial's single outcome reaches
    /// breaker/passive-health accounting — the losing arms of one dial
    /// are never counted as endpoint failures. Validation bounds the
    /// value to at most 10 minutes.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub happy_eyeballs_ms: Option<u64>,
}

/// The principal kind of a consumer (DW-113): `user` (the default —
/// a human or application calling the gateway) or `agent` (a bot
/// principal with bot credentials, per-agent quotas/token budgets,
/// tool allowlists, and a session audit trail). Agent traffic is
/// identifiable, governable, and billable; the type threads through
/// Identity into analytics for typed attribution.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ConsumerType {
    /// A human or application caller (the default).
    #[default]
    User,
    /// A bot principal: tool allowlists, per-agent token budgets,
    /// and typed analytics attribution apply.
    Agent,
}

/// Identity of an API caller (app/team/user); owns credentials, quotas, and
/// the analytics identity.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Consumer {
    pub name: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub credentials: Vec<Credential>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub policies: Vec<String>,
    /// The principal kind (DW-113): `user` (default) or `agent`.
    /// Agent consumers gain a tool allowlist, a per-agent token
    /// budget, and typed analytics attribution. The field is renamed
    /// to `type` in YAML (`type` is a Rust keyword).
    #[serde(default, rename = "type")]
    pub consumer_type: ConsumerType,
    /// MCP tool allowlist (DW-113): when non-empty, the consumer may
    /// only call the named tools through the MCP gateway. Empty (the
    /// default) = no restriction. Validation checks that every name
    /// references a configured `ai.mcp.tools` entry.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub tool_allowlist: Vec<String>,
    /// Per-agent AI token budget (DW-113): when set, this consumer's
    /// AI traffic is bounded by this budget BEFORE the policy chain
    /// (the most-specific budget). Same shape as a policy's
    /// `token_budget`. `None` (the default) = no per-agent budget;
    /// the policy chain governs as before.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token_budget: Option<TokenBudget>,
    /// Consumer priority class for load shedding (DW-016): 0 (lowest) to 10
    /// (highest). Stored and validated now; it takes effect only once
    /// authentication (DW-019/DW-020) identifies the consumer on a request —
    /// until then, shedding priority comes from the matched route (or the
    /// default 5). Consumer priority overrides the route's when known, but
    /// it does NOT trigger reserved-bucket carving today — only a
    /// high-priority route does.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub priority: Option<u8>,
    /// Consumer group memberships (DW-020): group names this consumer
    /// belongs to, consulted by authorization `allowed_groups` /
    /// `denied_groups` rules. Empty (the default) = no groups. Group
    /// names are free-form strings; validation checks that authorization
    /// rules referencing groups resolve against at least one consumer's
    /// membership. Store-managed consumers carry their own groups in the
    /// state store (#124) — the group NAMESPACE is shared, but
    /// config-time validation can only see config consumers, so a rule
    /// referencing a group that exists solely on store consumers is
    /// flagged (grant at least one config consumer the same group name,
    /// or accept the issue is a false positive for store-only groups).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub groups: Vec<String>,
    /// Consumer-level authorization rules (#123): the MOST specific link
    /// of the frozen chain consumer > route > service > listener >
    /// global — applies to every request authenticated as this consumer
    /// (naturally only once authentication has identified it). A deny at
    /// any level wins; otherwise the most specific level with rules
    /// governs (see [`Authz`] and the `authz` module). Same validation
    /// rules as route-level authorization.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub authorization: Option<Authz>,
    /// Request budgets for this consumer (DW-033): a daily and/or
    /// monthly request cap counted in fixed UTC calendar windows
    /// (midnight-to-midnight UTC; the first through the last instant of
    /// the UTC month). Budgets are DISTINCT from rate limits: a rate
    /// limit shapes traffic inside seconds or minutes, a budget bounds
    /// total volume across a day or month, and the two mechanisms run
    /// independently (both apply when both are configured). Enforcement
    /// needs the state store (`DWARA_STATE_DB`) for durable counters —
    /// without one, quota config is inert (logged at request time, see
    /// the `state::quotas` module docs). Store-managed consumers have no
    /// config record, so budgets are config-consumer-only in this
    /// edition; a distributed shared-counter variant is the Ent
    /// follow-up (issue "DW-155").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub quotas: Option<ConsumerQuotas>,
    /// AI prompt/response logging override (DW-081). None = inherit
    /// the global `ai.logging.enabled` setting; Some(false) = disable
    /// capture for this consumer even if global is on; Some(true) =
    /// enable capture for this consumer even if global is off
    /// (requires the `ai.logging` block to exist — the redactor and
    /// retention are always needed). The per-consumer toggle respects
    /// tenant preference: a consumer with capture disabled produces
    /// no stored prompts/responses.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ai_logging: Option<bool>,
    /// AI-16 (#204): agent principal metadata. Only meaningful when
    /// `consumer_type` is `agent`; ignored otherwise. Carries the
    /// agent's display name, description, owner, and permission level
    /// for first-class agent principal attribution.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub agent: Option<AgentPrincipal>,
}

/// AI-16 (#204): First-class agent principal metadata. Attached to a
/// `Consumer` with `consumer_type: agent` to carry agent-specific
/// attribution and permission data.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AgentPrincipal {
    /// The agent's display name (human-readable). Defaults to the
    /// consumer name when not set.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub display_name: Option<String>,
    /// A human-readable description of the agent's purpose.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,
    /// The owner of this agent (a user or team name). Used for
    /// attribution and audit.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub owner: Option<String>,
    /// The agent's permission level. One of: `read_only`,
    /// `read_write`, `admin`. Default `read_only`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub permissions: Option<AgentPermissionLevel>,
}

/// AI-16 (#204): Agent permission levels for first-class agent
/// principals. Mirrors the `Permission` enum in the MCP module but
/// lives in config for declarative assignment.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AgentPermissionLevel {
    /// Read-only access (list, get, stats, health, config).
    #[default]
    ReadOnly,
    /// Read-write access (read + create, update, delete).
    ReadWrite,
    /// Full admin access (all tools including purge).
    Admin,
}

/// Per-consumer request budgets (DW-033): daily and/or monthly request
/// caps in fixed UTC calendar windows, counted by the state store's
/// quota counters. At least one budget must be set and every set budget
/// must be > 0 (validation); a budget of 0 would deny the consumer's
/// first request and is expressed by omitting the field instead.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ConsumerQuotas {
    /// Maximum requests per UTC calendar day (midnight to midnight).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub daily_requests: Option<u64>,
    /// Maximum requests per UTC calendar month.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub monthly_requests: Option<u64>,
    /// SEC-14 / CFG-14: dry-run mode. When true, quota counters are
    /// evaluated and would-be rejections are recorded
    /// (`dwara_policy_dry_run_total{phase="quota"}` + a structured
    /// log) but the request is NOT rejected — it proceeds even when
    /// the quota is exceeded. Useful for calibrating quota limits
    /// before enforcing. Default false (reject on quota exceeded).
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
}

/// One authenticator bound to a consumer: API key, JWT issuer/audience
/// binding, mTLS client-certificate match, or HMAC signing key (DW-036).
///
/// `Debug` is manual (DW-045): the api-key and hmac-secret values are
/// SECRET and a derived impl would print them — this keeps the config
/// tree safe to Debug-log as a whole (`Gateway` and every holder derive
/// `Debug` over this type).
#[derive(Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]
pub enum Credential {
    ApiKey {
        /// The API key; hashed at rest by the state layer, never logged.
        /// Either the value INLINE (accepted, but redacted to a
        /// `${redacted:...}` placeholder in every config echo — admin
        /// `GET /config`, DW-045) or a reference resolved at
        /// config-compile time: `${ENV_NAME}` (an environment variable)
        /// or `${file:/path/to/secret}` (one trailing newline trimmed).
        /// References are re-read on every reload; an unresolvable
        /// reference fails validation naming this field.
        key: String,
    },
    /// HMAC request-signing credential (DW-036): the consumer presents
    /// per-request signatures over the canonical string documented in
    /// the `security::authn` module docs, carried in the
    /// `X-Dwara-Signature` header family. Unlike API keys the secret
    /// cannot be hash-at-rest stored — recomputing an HMAC needs the
    /// RAW key bytes — so this credential is config-declared only (the
    /// state store's hashed rows cannot serve it) and the resolved
    /// bytes live solely in the authenticator's memory, zeroized on
    /// drop. The pepper (#124) deliberately does NOT apply here: it
    /// guards stored hashes, and there is no stored hash to guard.
    Hmac {
        /// Public key identifier: the `X-Dwara-Key-Id` header value the
        /// client presents to SELECT this credential (the AWS
        /// access-key-id shape — it names the key, it is not secret).
        /// Non-empty visible ASCII, at most 128 bytes; unique across
        /// every consumer (validation rejects duplicates — an ambiguous
        /// selector cannot pick a consumer deterministically).
        key_id: String,
        /// The HMAC-SHA256 signing secret. INLINE values are accepted
        /// (redacted in every config echo, like api keys) but
        /// `${ENV_NAME}` / `${file:/path/to/secret}` references are the
        /// recommended shape; resolved at config-compile time and
        /// re-read on every reload. Must be non-empty; use at least 32
        /// bytes of entropy (shorter keys weaken the MAC construction
        /// — documented, not enforced, the same posture as the pepper).
        secret: String,
    },
    Jwt {
        issuer: String,
        #[serde(default, skip_serializing_if = "Vec::is_empty")]
        audiences: Vec<String>,
    },
    Mtls {
        /// SHA-256 fingerprint (lowercase hex of the DER) of the client
        /// certificate. Optional when `subject` is set (#124); a
        /// fingerprint match binds the credential to ONE exact
        /// certificate (a re-issued cert needs a new credential).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        fingerprint: Option<String>,
        /// Subject CommonName of the client certificate (#124): the
        /// credential matches any verified client certificate whose
        /// subject CN is exactly this string (case-sensitive). Binding
        /// by subject survives certificate re-issue under the same CN;
        /// the certificate must still chain to a listener's
        /// `client_ca_file` (or be otherwise verified) at the TLS layer
        /// — the matcher only maps an ALREADY-VERIFIED certificate to a
        /// consumer. Exactly one of `subject` / `fingerprint` must be
        /// set (validation rejects both-empty and both-set).
        #[serde(default, skip_serializing_if = "Option::is_none")]
        subject: Option<String>,
    },
}

impl std::fmt::Debug for Credential {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        // DW-045: the api-key and hmac-secret values are the inline
        // secret material in the schema; everything else is binding
        // metadata (issuer, fingerprint, subject, key id) that
        // validation matches, not a secret. Redact exactly the secrets
        // and keep the variant shape so debug output stays useful.
        match self {
            Credential::ApiKey { .. } => f
                .debug_struct("ApiKey")
                .field("key", &"[redacted]")
                .finish(),
            Credential::Hmac { key_id, .. } => f
                .debug_struct("Hmac")
                .field("key_id", key_id)
                .field("secret", &"[redacted]")
                .finish(),
            Credential::Jwt { issuer, audiences } => f
                .debug_struct("Jwt")
                .field("issuer", issuer)
                .field("audiences", audiences)
                .finish(),
            Credential::Mtls {
                subject,
                fingerprint,
            } => f
                .debug_struct("Mtls")
                .field("subject", subject)
                .field("fingerprint", fingerprint)
                .finish(),
        }
    }
}

/// Named reusable rule bundle (rate limit, timeouts, ...); attachable at
/// several scopes. Plugin-backed phases arrive with the M3 plugin system.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct Policy {
    pub name: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub rate_limit: Option<RateLimit>,
    /// Stacked GCRA rate-limit rules (DW-017). Each rule stacks one or
    /// more windows (e.g. `s` AND `hour`); a request is admitted only if
    /// EVERY window of EVERY applicable rule allows it. The legacy
    /// single-window `rate_limit` field above still applies when set (see
    /// its mapping in the rate-limiter module docs); use `rate_limits`
    /// for new configs.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub rate_limits: Vec<RateLimitRule>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub timeouts: Option<Timeouts>,
    /// Monitor mode (DW-041) for this bundle's rate-limit rules: they
    /// still EVALUATE (their GCRA buckets advance exactly as if
    /// enforcing, so denial rates reflect what enforcement would do),
    /// but a request they would deny is LOGGED and counted
    /// (`dwara_policy_dry_run_total{phase="rate_limit"}` + a
    /// `dwara::policy` warn event) and PROCEEDS — no 429, and none of
    /// the rule's `X-RateLimit-*` headers on the response. LIVE policies
    /// attached to the same request still enforce: the flag mutes only
    /// this bundle's own denials. The flag sits on the named bundle (not
    /// on each `policies: [...]` attachment list entry) because rate
    /// limits attach BY NAME at the five precedence levels — marking the
    /// bundle dries every attachment of it uniformly. Timeouts carry no
    /// rejection and are unaffected.
    #[serde(default, skip_serializing_if = "is_false")]
    pub dry_run: bool,
    /// AI token budget (DW-078): caps provider-reported tokens per
    /// minute and/or priced cost per UTC day for the budget holder.
    /// Distinct from every rule above: those count REQUESTS, this
    /// counts TOKENS. Resolution follows the frozen precedence chain
    /// (consumer > route > service > listener > global) with the MOST
    /// SPECIFIC level's budget governing (a limit-of-totals, not an
    /// AND-composed rule). `scope: consumer` (default) keys the budget
    /// to each attaching consumer; `scope: policy` makes one SHARED
    /// (team) budget keyed by the policy name. Consumers with no
    /// binding budget are unlimited.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token_budget: Option<TokenBudget>,
    /// Anomaly scoring (DW-090): lightweight statistical detection of
    /// abusive request patterns (header entropy, request-shape outliers).
    /// When enabled, every matched request is scored against the
    /// configured signals; a score at or above `threshold` is blocked
    /// (403 `anomaly_blocked`) unless `dry_run` is set (scored and
    /// logged, request proceeds). Resolution follows the frozen
    /// precedence chain (consumer > route > service > listener > global);
    /// every level with an attachment applies and the applicable rules
    /// AND together. Absent (the default): no anomaly scoring.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub anomaly: Option<AnomalyPolicy>,
    /// Adaptive + origin-driven rate-limit tuning (DW-089): an EWMA of
    /// upstream error rate and latency dynamically scales this policy's
    /// rate-limit quotas, and upstream-originated signals (`Retry-After`)
    /// trigger an immediate backoff for the advertised window. The
    /// adaptive factor is bounded `[min_factor, max_factor]` (never 0,
    /// never unbounded); tightening under stress is faster than relaxing
    /// when healthy (asymmetric). Absent (the default): no adaptive
    /// tuning, the policy's quotas apply as configured.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub adaptive: Option<AdaptiveRateLimit>,
}

/// An AI token budget (DW-078, `policies[].token_budget`): limits of
/// TOTALS over windows — provider-reported tokens per minute and/or
/// cost per UTC calendar day, enforced per consumer or shared per
/// policy (team). See the `ai::budget` module docs for the
/// check-then-spend contract.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct TokenBudget {
    /// Maximum provider-reported tokens per fixed 60-second window
    /// (epoch-minute aligned). Spent tokens come from the provider's
    /// own usage reports — the gateway never estimates.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tokens_per_min: Option<u64>,
    /// Maximum spend per UTC calendar day, in integer micro-USD
    /// (1_000_000 = $1.00 — no floating-point money). Enforced end to
    /// end; the pricing input arrives with the DW-079 pricing tables,
    /// so the cost window is enforced-but-inert until then.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cost_per_day_micros: Option<u64>,
    /// Whose budget this is: `consumer` (default — each attaching
    /// consumer gets its own window) or `policy` (one SHARED team
    /// budget keyed by the policy name).
    #[serde(
        default = "default_token_budget_scope",
        skip_serializing_if = "is_default_token_budget_scope"
    )]
    pub scope: TokenBudgetScope,
}

/// The budget's key scope (DW-078).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum TokenBudgetScope {
    /// One budget per attaching consumer.
    Consumer,
    /// One shared (team) budget per policy.
    Policy,
}

fn default_token_budget_scope() -> TokenBudgetScope {
    TokenBudgetScope::Consumer
}

fn is_default_token_budget_scope(s: &TokenBudgetScope) -> bool {
    *s == TokenBudgetScope::Consumer
}

/// One rate-limit rule (DW-017): a key selector plus one or more stacked
/// windows. `selector` names the request attributes that form the
/// counter key (all listed attributes are joined into ONE key, so
/// `[ip, route]` limits each (client IP, route) pair independently);
/// `requests_per` carries the sustained rates per window (at least one
/// window must be present); `burst` is the bucket size (defaults to the
/// window's request count).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RateLimitRule {
    /// Optional label (documentation only; not part of the key).
    #[serde(skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,
    /// Key components: `ip`, `credential`, and/or `route` (at least one;
    /// order does not matter). `credential` falls back to the client IP
    /// until authentication (DW-019) identifies consumers.
    pub selector: Vec<RateLimitSelector>,
    pub requests_per: RateRequestsPer,
    /// Bucket size (burst capacity); must be >= 1 when present. Defaults
    /// to the window's request count.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub burst: Option<u32>,
}

/// One attribute of a rate-limit key (DW-017).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "lowercase")]
pub enum RateLimitSelector {
    /// The direct connection peer (the same IP used for X-Real-IP).
    Ip,
    /// The authenticated consumer; until DW-019 this falls back to `ip`.
    Credential,
    /// The matched route's name.
    Route,
}

/// Sustained rates per window (DW-017). At least one field must be set
/// and every set field must be > 0; each set field becomes one stacked
/// GCRA cell (a request must satisfy ALL set windows).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RateRequestsPer {
    /// Requests per second.
    #[serde(rename = "s", skip_serializing_if = "Option::is_none")]
    pub per_second: Option<u32>,
    /// Requests per minute.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub minute: Option<u32>,
    /// Requests per hour.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub hour: Option<u32>,
}

/// Local GCRA-style rate limit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct RateLimit {
    /// Maximum requests allowed per window.
    pub requests: u64,
    /// Window length in seconds.
    pub window_seconds: u64,
}

/// Parse a YAML configuration document into a [`Gateway`], rejecting invalid
/// input with path-precise error messages.
///
/// Error-path guarantee: serde-level failures (type mismatches, unknown
/// fields, missing fields) carry a precise dotted path from
/// `serde_path_to_error`, e.g. `routes[0].action`. Raw YAML syntax errors
/// are detected by the scanner before path tracking applies, so their path
/// is coarse (often the root); the precise location is still available as
/// line/column inside the message text itself.
pub fn parse_gateway(text: &str) -> Result<Gateway, ConfigError> {
    let de = serde_path_to_error::deserialize(serde_yaml_ng::Deserializer::from_str(text))
        .map_err(|e| ConfigError {
            path: e.path().to_string(),
            message: e.inner().to_string(),
        })?;
    Ok(de)
}

/// Serialize a [`Gateway`] to normalized YAML text.
///
/// Field order follows struct declaration order; defaulted-empty collections
/// are omitted, so output is stable for a given typed value.
pub fn gateway_to_yaml(gateway: &Gateway) -> Result<String, serde_yaml_ng::Error> {
    serde_yaml_ng::to_string(gateway)
}

/// Build the JSON Schema for the root [`Gateway`] type.
pub fn json_schema() -> schemars::Schema {
    schemars::schema_for!(Gateway)
}

// --- DW-055: proxy-wasm plugin config -------------------------------------

/// A plugin definition (DW-055 / DW-119). Each plugin is either a
/// proxy-wasm `.wasm` module loaded at startup (`wasm`) or a compiled-in
/// native Rust filter (`native`), run on the request pipeline phases it
/// declares. Routes reference plugins by name. Exactly one of `wasm` or
/// `native` must be set (validation enforces this).
#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PluginConfig {
    /// Unique plugin name. Referenced by routes' `plugins` field.
    pub name: String,
    /// Path to the .wasm module file. Must be readable at startup.
    /// Mutually exclusive with `native`; exactly one of the two must be
    /// set. Absent when this is a native filter.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wasm: Option<String>,
    /// Registered native filter implementation name (DW-119). The
    /// `plugins` cargo feature must be enabled and a factory registered
    /// under this name at startup. Mutually exclusive with `wasm`;
    /// exactly one of the two must be set. Absent when this is a WASM
    /// plugin.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub native: Option<String>,
    /// SCALE-12 (#192)/DW-165: remote source for this plugin. When
    /// set, the gateway resolves the artifact at every publish
    /// (startup and reload): cache-first, downloading on a miss, then
    /// verifying the mandatory SHA-256 digest and any configured
    /// Ed25519 signature BEFORE the wasm load step. A source that
    /// cannot be resolved or fails verification never loads (the
    /// plugin reads Crashed; its routes fail closed). Mutually
    /// exclusive with `native` and `wasm`. See
    /// [`PluginSourceConfig`] and the plugin registry guide for the
    /// cache layout and the registry spec.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source: Option<PluginSourceConfig>,
    /// Phases this plugin hooks. Must be a non-empty subset of:
    /// `request_headers`, `request_body`, `response_headers`,
    /// `response_body`. The host calls the plugin's corresponding
    /// `proxy_on_*` export at each declared phase (WASM) or the
    /// `NativeFilter` trait method (native).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub phases: Vec<PluginPhase>,
    /// Plugin-specific configuration, passed to the plugin's
    /// `proxy_on_configure` as a byte string (WASM) or to the native
    /// filter's factory (native). Typically a JSON or YAML blob the
    /// plugin parses itself.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub config: Option<String>,
    /// Resource limits for this plugin (fuel, memory, time). Absent
    /// uses the defaults: 1M fuel, 32MB memory, 100ms timeout. Only
    /// meaningful for WASM plugins (native filters run in-process and
    /// are bounded by the gateway's own resource limits).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub limits: Option<PluginLimitsConfig>,
}

/// SCALE-12 (#192)/DW-165: remote/signed plugin source configuration.
/// The gateway resolves the .wasm artifact at every publish: cache
/// lookup first, then a download from `url` on a miss, then SHA-256
/// `digest` verification (mandatory) and Ed25519 `signature`
/// verification (when configured) — only then is the artifact loaded.
/// Resolution failures are fail-closed per plugin (Crashed at publish,
/// its routes answer 500), never a partial load.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PluginSourceConfig {
    /// The registry URL to fetch the .wasm artifact from. Must be
    /// `https://`; fetched with one HTTP/1.1 GET (redirects are not
    /// followed — configure the artifact's final URL). `oci://`
    /// references are not supported in this version: publish the
    /// artifact over https or pre-fetch it with `dwara-cli plugin
    /// install` and reference the local file with `wasm`.
    pub url: String,
    /// Expected SHA-256 digest of the artifact, hex-encoded (64
    /// chars, case-insensitive). Verified against the cached AND the
    /// downloaded bytes before loading; a mismatch fails the plugin
    /// (never a partial load). Required — there are no unsigned
    /// remote artifacts (digest-pinning is the floor; signatures are
    /// the ceiling).
    pub digest: String,
    /// Optional Ed25519 signature over the artifact bytes, hex-encoded
    /// (64 bytes / 128 chars). When set, it must verify against
    /// `public_key` and, when `plugin_registry.public_keys` pins
    /// keys, against a pinned key too. Absent means digest-only
    /// verification — rejected when the registry pins public keys.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub signature: Option<String>,
    /// Ed25519 public key (32 bytes, hex-encoded) for signature
    /// verification. Required when `signature` is set unless
    /// `plugin_registry.public_keys` pins keys. A `public_key` set
    /// WITHOUT a `signature` is rejected (a key that verifies nothing
    /// is a config mistake — sign the artifact or remove the key).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub public_key: Option<String>,
    /// Local cache path for the resolved artifact. When absent, the
    /// artifact is cached content-addressed as
    /// `<cache_dir>/<digest>.wasm` (`plugin_registry.cache_dir`,
    /// default `./plugin-cache`). When set, the path must be a
    /// RELATIVE path under the cache dir with no `..` parent
    /// segments (containment: the resolver creates directories and
    /// writes artifact bytes at this path, so it must not be able to
    /// point outside the cache). The cached file is re-verified
    /// (digest and signature) on every publish; a cached file that
    /// does not match the pinned digest fails closed instead of being
    /// silently re-fetched.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_path: Option<String>,
}

impl PluginSourceConfig {
    /// Why a `cache_path` value violates cache containment, or `None`
    /// when it is acceptable. The rule is deliberately simple: a
    /// non-empty RELATIVE path with no `..` parent segments — the
    /// resolver creates directories and writes artifact bytes at this
    /// path, so it must stay inside `plugin_registry.cache_dir`.
    /// Shared by snapshot validation (the operator-facing, earliest
    /// rejection) and the resolver (defense in depth); lives here
    /// because both may import `config` and nothing below it.
    pub fn cache_path_violation(cache_path: &str) -> Option<&'static str> {
        if cache_path.trim().is_empty() {
            Some("the path is empty")
        } else if std::path::Path::new(cache_path).is_absolute() {
            Some("the path is absolute")
        } else if std::path::Path::new(cache_path)
            .components()
            .any(|c| matches!(c, std::path::Component::ParentDir))
        {
            Some("the path contains '..' parent segments")
        } else {
            None
        }
    }
}

/// SCALE-12 (#192)/DW-165: plugin registry configuration. When
/// present, signatures of `source:`-referenced artifacts are verified
/// against the registry's pinned public keys and resolved artifacts
/// are cached in the registry's cache directory. This enables
/// fleet-consistent plugin pinning: all gateways in a fleet reference
/// the same registry and get the same signed artifacts.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PluginRegistryConfig {
    /// Registry base URL (e.g., `https://registry.example.com/plugins`).
    /// Informational for fleet tooling (`dwara-cli plugin
    /// search/install` default); each plugin's `source.url` is a full
    /// URL.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub base_url: Option<String>,
    /// Pinned Ed25519 public keys (hex-encoded, 32 bytes each). When
    /// set, plugin signatures are verified against these keys in
    /// addition to any per-plugin `public_key`, and a plugin with no
    /// signature is rejected (unsigned artifacts cannot ride a
    /// pinned-key registry).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub public_keys: Vec<String>,
    /// Local cache directory for resolved artifacts, content-addressed
    /// as `<cache_dir>/<digest>.wasm`. Default: `./plugin-cache`
    /// (relative to the gateway working directory, the same posture
    /// as the ACME state directory).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub cache_dir: Option<String>,
}

/// The phases a plugin can hook (DW-055, §9.3 phase contract).
#[derive(
    Clone,
    Copy,
    Debug,
    PartialEq,
    Eq,
    std::hash::Hash,
    serde::Serialize,
    serde::Deserialize,
    schemars::JsonSchema,
)]
#[serde(rename_all = "snake_case")]
pub enum PluginPhase {
    /// After route resolution, before authn.
    RequestHeaders,
    /// After authn/authz/rate-limit, before upstream.
    RequestBody,
    /// After the upstream responds, before masking.
    ResponseHeaders,
    /// After masking, before compression.
    ResponseBody,
}

impl PluginPhase {
    /// The phase's stable wire label (the serde name), for the plugin
    /// status surface (`GET /plugins`, DW-158).
    pub fn as_str(self) -> &'static str {
        match self {
            PluginPhase::RequestHeaders => "request_headers",
            PluginPhase::RequestBody => "request_body",
            PluginPhase::ResponseHeaders => "response_headers",
            PluginPhase::ResponseBody => "response_body",
        }
    }
}

/// SCALE-12 (#191): formalized request-pipeline filter phases. The
/// default order is the order the variants are declared (the same
/// order the dataplane has always executed them). Per-route
/// `filter_chain` overrides can reorder a subset of these phases;
/// phases not listed in an override keep their default relative
/// order.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize, JsonSchema,
)]
#[serde(rename_all = "snake_case")]
pub enum FilterPhase {
    /// IP ACL and consumer ACL checks.
    Acl,
    /// Rate limiting (per-consumer and per-route limiters).
    RateLimit,
    /// Authentication (API key, JWT, OIDC, mTLS).
    Authn,
    /// Authorization (route/service/listener/global policy chain).
    Authz,
    /// Request body validation (JSON schema, size limits).
    Validate,
    /// Request transforms (path rewrite, header/query transforms).
    Transform,
    /// Response cache lookup.
    Cache,
    /// Route dispatch (proxy, redirect, respond, ai, etc.).
    Route,
}

impl FilterPhase {
    /// The default pipeline order (the order the dataplane has
    /// always executed the phases).
    pub const DEFAULT_ORDER: [FilterPhase; 8] = [
        FilterPhase::Acl,
        FilterPhase::RateLimit,
        FilterPhase::Authn,
        FilterPhase::Authz,
        FilterPhase::Validate,
        FilterPhase::Transform,
        FilterPhase::Cache,
        FilterPhase::Route,
    ];

    pub fn as_str(self) -> &'static str {
        match self {
            FilterPhase::Acl => "acl",
            FilterPhase::RateLimit => "rate_limit",
            FilterPhase::Authn => "authn",
            FilterPhase::Authz => "authz",
            FilterPhase::Validate => "validate",
            FilterPhase::Transform => "transform",
            FilterPhase::Cache => "cache",
            FilterPhase::Route => "route",
        }
    }
}

/// SCALE-12 (#191): per-phase dry-run configuration. When dry-run is
/// enabled for a phase, the phase executes its checks but does NOT
/// enforce (reject/block). Failures are logged as warnings and the
/// request continues. This enables safe policy rollout: enable a
/// phase in dry-run mode, observe the would-be rejections, then
/// switch to enforcement.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FilterChainConfig {
    /// Phases to run in dry-run mode (log but don't enforce). Each
    /// entry is a phase name from [`FilterPhase`]. A phase in
    /// dry-run mode still executes its logic; the difference is that
    /// a rejection is logged as a warning and the request continues.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub dry_run: Vec<FilterPhase>,
    /// Optional ordering override: a list of phase names in the
    /// order they should execute. Phases not listed keep their
    /// default relative order. The override must contain exactly the
    /// same set of phases as the default (no duplicates, no unknown
    /// phases); validation rejects invalid overrides.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub order: Option<Vec<FilterPhase>>,
}

/// Resource limits for a proxy-wasm plugin (DW-055 decision 4; §9.3).
#[derive(Clone, Debug, PartialEq, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct PluginLimitsConfig {
    /// Maximum fuel (wasmtime operations). Default: 1,000,000.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fuel: Option<u64>,
    /// Maximum linear memory in MB. Default: 32.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub memory_mb: Option<usize>,
    /// Maximum execution time in milliseconds. Default: 100.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub timeout_ms: Option<u64>,
}

/// Anomaly scoring policy (DW-090, `policies[].anomaly`): lightweight
/// statistical detection of abusive request patterns. Each enabled
/// signal produces a normalized [0, 1] score from the request shape
/// (header entropy, header count/bytes, path length/depth, query count,
/// body size, unusual method); the overall score is the average of the
/// configured signals' scores. A score at or above `threshold` is
/// blocked (403 `anomaly_blocked`) unless `dry_run` is set.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AnomalyPolicy {
    /// Whether anomaly scoring is enabled (default true). A `policies[].anomaly`
    /// block with `enabled: false` is a no-op (the scorer is not compiled).
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// Monitor mode (DW-041 synergy): the score is computed and the
    /// would-block is logged + counted, but the request proceeds. Default
    /// false (enforce).
    #[serde(default)]
    pub dry_run: bool,
    /// The signals to score. Must be non-empty when `enabled` is true.
    /// Each signal contributes one normalized [0, 1] sub-score; the
    /// overall score is their average.
    pub signals: Vec<AnomalySignal>,
    /// Block threshold in [0, 1] (default 0.8). A score >= threshold is
    /// blocked (or logged in dry-run mode). Must be in (0, 1].
    #[serde(default = "default_anomaly_threshold")]
    pub threshold: f64,
    /// Maximum body bytes to inspect for the `body_size` signal (default
    /// 4096). The signal scores `min(body_len, cap) / cap`, so a body
    /// at or beyond the cap scores 1.0. Must be > 0.
    #[serde(default = "default_max_body_inspect")]
    pub max_body_inspect_bytes: u64,
}

/// One anomaly signal (DW-090). Each produces a normalized [0, 1]
/// sub-score from one request-shape dimension.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum AnomalySignal {
    /// Shannon entropy of concatenated header values (normalized by 8,
    /// the max entropy for byte values). High entropy can indicate
    /// randomized/obfuscated header payloads.
    HeaderEntropy,
    /// Header count outlier: `count / 50`, capped at 1.0.
    HeaderCount,
    /// Total header bytes outlier: `bytes / 8192`, capped at 1.0.
    HeaderBytes,
    /// Path length outlier: `len / 1024`, capped at 1.0.
    PathLength,
    /// Path depth outlier: segment count / 20, capped at 1.0.
    PathDepth,
    /// Query parameter count outlier: `count / 50`, capped at 1.0.
    QueryCount,
    /// Body size outlier: `min(body_len, cap) / cap`, capped at 1.0.
    BodySize,
    /// Unusual HTTP method: 1.0 if the method is not one of GET, POST,
    /// PUT, DELETE, PATCH, HEAD, OPTIONS; 0.0 otherwise.
    MethodUnusual,
}

fn default_anomaly_threshold() -> f64 {
    0.8
}

fn default_max_body_inspect() -> u64 {
    4096
}

// --- DW-089: adaptive + origin-driven rate-limit tuning -------------------

/// Adaptive + origin-driven rate-limit tuning (DW-089,
/// `policies[].adaptive`): an EWMA of upstream error rate and latency
/// dynamically scales this policy's rate-limit quotas at check time
/// (the factor multiplies the effective cost of each request against
/// the GCRA bucket), and upstream-originated signals trigger an
/// immediate backoff. The factor is bounded `[min_factor, max_factor]`
/// (never 0, never unbounded); tightening under stress is faster than
/// relaxing when healthy (asymmetric, so the gateway errs toward
/// protecting upstreams). `origin_signals` selects which upstream
/// response signals the controller honors (currently `retry_after`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct AdaptiveRateLimit {
    /// Whether adaptive tuning is enabled (default true). A
    /// `policies[].adaptive` block with `enabled: false` is a no-op
    /// (the controller is not compiled for that policy).
    #[serde(default = "default_true")]
    pub enabled: bool,
    /// EWMA decay window in seconds for error-rate and latency tracking
    /// (default 60). A larger window smooths transient spikes; a smaller
    /// window reacts faster. Must be > 0.
    #[serde(default = "default_ewma_window_secs")]
    pub ewma_window_secs: u64,
    /// Minimum adaptive factor (default 0.1): the tightest the quotas
    /// can shrink to (10% of the configured rate). Must be > 0 and <=
    /// `max_factor`. The factor is never 0.
    #[serde(default = "default_adaptive_min_factor")]
    pub min_factor: f64,
    /// Maximum adaptive factor (default 2.0): the loosest the quotas
    /// can grow to (200% of the configured rate). Must be > 0 and >=
    /// `min_factor`. The factor is never unbounded.
    #[serde(default = "default_adaptive_max_factor")]
    pub max_factor: f64,
    /// Error-rate EWMA threshold that triggers tightening (default 0.05
    /// = 5% 5xx rate). When the error EWMA exceeds this, the factor
    /// decreases toward `min_factor`. Must be in (0, 1].
    #[serde(default = "default_adaptive_error_threshold")]
    pub error_threshold: f64,
    /// Latency EWMA threshold in milliseconds that triggers tightening
    /// (default 500). When the latency EWMA exceeds this, the factor
    /// decreases toward `min_factor`. Must be > 0.
    #[serde(default = "default_adaptive_latency_threshold_ms")]
    pub latency_threshold_ms: u64,
    /// Upstream-originated signals the controller honors (default
    /// empty: EWMA-only tuning). Currently supported: `retry_after`
    /// (parse the upstream `Retry-After` header and back off for the
    /// advertised window).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub origin_signals: Vec<OriginSignal>,
}

/// One upstream-originated signal the adaptive controller honors
/// (DW-089).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum OriginSignal {
    /// Parse the upstream `Retry-After` header (integer seconds or
    /// HTTP-date) and back off for the advertised window: the factor
    /// drops to `min_factor` immediately and stays there until the
    /// window elapses.
    RetryAfter,
}

fn default_ewma_window_secs() -> u64 {
    60
}

fn default_adaptive_min_factor() -> f64 {
    0.1
}

fn default_adaptive_max_factor() -> f64 {
    2.0
}

fn default_adaptive_error_threshold() -> f64 {
    0.05
}

fn default_adaptive_latency_threshold_ms() -> u64 {
    500
}