postrust_core/

config.rs

//! Configuration for Postrust.
//!
//! Mirrors PostgREST's configuration options.

use serde::{Deserialize, Serialize};
use std::collections::HashMap;

const EXPECTED_BOOLEAN: &str = "one of: true, false, 1, 0, yes, no, on, off";
const EXPECTED_SQLSTATES: &str = "true, false, or a comma-separated list of SQLSTATEs \
     (P0001) and prefixes ending in * (PT*)";

/// An environment variable contains a value that cannot be used safely.
#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[error("invalid value for {variable}: {value:?}; expected {expected}")]
pub struct ConfigError {
    variable: &'static str,
    value: String,
    expected: &'static str,
}

/// Main application configuration.
#[derive(Clone, Debug, Serialize, Deserialize)]
#[non_exhaustive]
pub struct AppConfig {
    // ========================================================================
    // Database Settings
    // ========================================================================
    /// PostgreSQL connection URI
    #[serde(default = "default_db_uri")]
    pub db_uri: String,

    /// Schemas to expose via the API
    #[serde(default = "default_db_schemas")]
    pub db_schemas: Vec<String>,

    /// Role for unauthenticated requests
    pub db_anon_role: Option<String>,

    /// Connection pool size
    #[serde(default = "default_pool_size")]
    pub db_pool_size: u32,

    /// Pool acquisition timeout in seconds
    #[serde(default = "default_pool_timeout")]
    pub db_pool_timeout: u64,

    /// Isolation level for the transaction every request runs in.
    ///
    /// `READ COMMITTED` unless set, which is PostgreSQL's own default; a
    /// stricter level is issued as `SET TRANSACTION ISOLATION LEVEL` on the
    /// request's transaction.
    #[serde(default = "default_tx_isolation")]
    pub db_tx_isolation: IsolationLevel,

    /// Use prepared statements
    #[serde(default = "default_true")]
    pub db_prepared_statements: bool,

    /// Schemas added to the `search_path` of every request, after the
    /// request's own schema.
    ///
    /// These are not exposed as API endpoints; they are where a function an
    /// exposed one calls, or a type it references, is allowed to live. An
    /// aggregate returning a domain declared elsewhere cannot resolve that
    /// domain without this. `public` by default, as in PostgREST.
    #[serde(default = "default_extra_search_path")]
    pub db_extra_search_path: Vec<String>,

    /// LISTEN/NOTIFY channel for schema reload
    #[serde(default = "default_db_channel")]
    pub db_channel: String,

    /// Enable NOTIFY-based schema cache reload
    #[serde(default)]
    pub db_channel_enabled: bool,

    /// Function called on the request's transaction before its own query,
    /// after every setting is applied. Anything it raises aborts the request.
    pub db_pre_request: Option<String>,

    /// Maximum rows allowed in a response
    pub db_max_rows: Option<i64>,

    /// Enable aggregate functions in `select`.
    ///
    /// Off by default, as in PostgREST: an aggregate over a large table costs
    /// far more than the request looks like it asks for.
    #[serde(default)]
    pub db_aggregates_enabled: bool,

    // ========================================================================
    // Server Settings
    // ========================================================================
    /// Server host to bind
    #[serde(default = "default_host")]
    pub server_host: String,

    /// Server port
    #[serde(default = "default_port")]
    pub server_port: u16,

    /// Origins allowed by CORS.
    ///
    /// Empty means every origin is allowed, which is the default and what
    /// `PGRST_SERVER_CORS_ORIGINS="*"` selects explicitly. A non-empty list
    /// restricts the `Access-Control-Allow-Origin` response to exactly those
    /// origins; anything else gets no CORS headers and is refused by the
    /// browser.
    #[serde(default)]
    pub server_cors_origins: Vec<String>,

    /// Maximum accepted request body, in bytes.
    ///
    /// The REST handler applies this when it reads the body; the routes that
    /// take a body extractor get it through axum's `DefaultBodyLimit`. Before
    /// this was read, the limit in force was a 10 MiB constant in the request
    /// handler, whatever the variable said.
    #[serde(default = "default_max_body_size")]
    pub max_body_size: usize,

    /// Listen on a Unix domain socket instead of host and port.
    pub server_unix_socket: Option<String>,

    /// Serve liveness and readiness on a second port of their own.
    pub admin_server_port: Option<u16>,

    // ========================================================================
    // JWT Settings
    // ========================================================================
    /// JWT secret: an HMAC secret, or a JSON Web Key or JWK Set.
    pub jwt_secret: Option<String>,

    /// JWT secret as base64
    #[serde(default)]
    pub jwt_secret_is_base64: bool,

    /// JWT audience claim to validate
    pub jwt_aud: Option<String>,

    /// The issuer a token's `iss` claim must name (`PGRST_JWT_ISS`). Unset,
    /// `iss` is not checked.
    pub jwt_iss: Option<String>,

    /// JWT claim that contains the role
    #[serde(default = "default_jwt_role_claim")]
    pub jwt_role_claim_key: String,

    /// Cache validated tokens, so a repeated token is not verified again.
    #[serde(default = "default_true")]
    pub jwt_cache_enabled: bool,

    /// How long a cached validation may be reused, in seconds.
    ///
    /// A token's own `exp` bounds this; the cache never answers with a token
    /// past its expiry. `0` turns the cache off, as in PostgREST.
    #[serde(default = "default_jwt_cache_max")]
    pub jwt_cache_max_lifetime: u64,

    /// Where to fetch a JSON Web Key Set from (`PGRST_JWT_JWKS_URL`), and
    /// keep fetching it as the identity provider rotates its keys.
    ///
    /// `https`, or `http` to a loopback host; checked when the server is
    /// built. With `jwt_secret` also set, a token either one verifies is
    /// accepted. See docs/authentication.md.
    pub jwt_jwks_url: Option<String>,

    /// How often to fetch `jwt_jwks_url` again, in seconds, when its response
    /// carries no `Cache-Control: max-age` (`PGRST_JWT_JWKS_REFRESH`).
    #[serde(default = "default_jwt_jwks_refresh")]
    pub jwt_jwks_refresh: u64,

    // ========================================================================
    // Hasura Authentication
    // ========================================================================
    /// The shared secret that authenticates an administrator, and the switch
    /// that makes `x-hasura-*` headers mean anything at all.
    ///
    /// Unset, this server ignores those headers and reads session variables
    /// only from a verified token -- because honouring a header nothing
    /// authenticated would let any caller name its own identity, and a policy
    /// reading a value the caller chose is not a policy. Hasura instead treats
    /// an unsecured deployment as wholly administrative; the divergence is
    /// deliberate and is recorded in `postrust_auth::hasura`.
    pub hasura_admin_secret: Option<String>,

    /// The role a request falls to when nothing authenticated it. Hasura's
    /// `HASURA_GRAPHQL_UNAUTHORIZED_ROLE`; unset means such a request is
    /// refused rather than answered as a stranger.
    pub hasura_unauthorized_role: Option<String>,

    // ========================================================================
    // OpenAPI Settings
    // ========================================================================
    /// Address to advertise in the specification's `servers`, for when the
    /// server sits behind a reverse proxy and its own address is not the one
    /// clients use.
    pub openapi_server_proxy_uri: Option<String>,

    /// OpenAPI mode: disabled, follow-privileges, ignore-privileges
    #[serde(default = "default_openapi_mode")]
    pub openapi_mode: OpenApiMode,

    // ========================================================================
    // Logging Settings
    // ========================================================================
    /// Log level: crit, error, warn, info, debug
    #[serde(default = "default_log_level")]
    pub log_level: LogLevel,

    /// How log lines are written: `text` for a person at a terminal, `json`
    /// for a log shipper. JSON lines carry the fields of every span the event
    /// happened in, so each one names its `request_id` and `trace_id`.
    ///
    /// Like `log_level`, the binaries read the variable themselves before the
    /// configuration is loaded -- the subscriber has to exist first to report
    /// what loading it rejects -- and this field is that same value, kept for
    /// anything that reads the configuration afterwards.
    #[serde(default)]
    pub log_format: LogFormat,

    /// Record the SQL of a request's main query on its `db.query` span, as
    /// OpenTelemetry's `db.query.text`.
    ///
    /// Off by default. The statement is parameterized, so the values a client
    /// sent are not in it -- but the table, column and function names are,
    /// and whatever collects traces may be read by more people than the
    /// schema is meant for. Formatting it costs nothing while it is off.
    #[serde(default)]
    pub otel_db_statement: bool,

    // ========================================================================
    // Role Settings
    // ========================================================================
    /// Per-role settings (isolation level, timeout)
    #[serde(default)]
    pub role_settings: HashMap<String, RoleSettings>,

    /// App-level settings to expose via GUC
    #[serde(default)]
    pub app_settings: HashMap<String, String>,

    // ========================================================================
    // GraphQL Settings
    // ========================================================================
    /// Expose the GraphQL API as an Apollo Federation subgraph.
    #[serde(default)]
    pub graphql_federation: bool,

    /// Namespace applied to generated GraphQL table types and root fields.
    #[serde(default)]
    pub graphql_type_prefix: Option<String>,

    // ========================================================================
    // Compatibility Settings
    // ========================================================================
    /// PostgREST compatibility mode.
    ///
    /// When enabled, the REST surface is also served at the root (so canonical
    /// PostgREST paths like `/rpc/<name>` and `/<table>` work in addition to
    /// the `/api`-prefixed paths), and RPC responses are un-wrapped to match
    /// PostgREST's shape (bare object/scalar for non-set-returning functions,
    /// a top-level array for set-returning ones) instead of the array-wrapped,
    /// function-name-keyed default.
    #[serde(default)]
    pub compat_mode: bool,

    /// The SQLSTATEs whose database errors are answered in the database's own
    /// words -- its code, message, detail and hint -- rather than as
    /// `"Database error"`.
    ///
    /// Each entry is a five-character SQLSTATE (`P0001`) or a prefix ending in
    /// `*` (`PT*`); `*` alone is every one. Empty by default, because most of
    /// what PostgreSQL says describes the schema rather than the request: a
    /// constraint's name, a missing table. What a function raises on purpose
    /// for the person using the app is the exception worth listing.
    /// Compatibility mode passes every database error through regardless.
    #[serde(default, deserialize_with = "deserialize_sqlstate_patterns")]
    pub db_errors_verbatim: Vec<String>,
}

impl Default for AppConfig {
    fn default() -> Self {
        Self {
            db_uri: default_db_uri(),
            db_schemas: default_db_schemas(),
            db_anon_role: None,
            db_pool_size: default_pool_size(),
            db_pool_timeout: default_pool_timeout(),
            db_tx_isolation: default_tx_isolation(),
            db_prepared_statements: true,
            db_extra_search_path: default_extra_search_path(),
            db_channel: default_db_channel(),
            db_channel_enabled: false,
            db_pre_request: None,
            db_max_rows: None,
            db_aggregates_enabled: false,
            server_host: default_host(),
            server_port: default_port(),
            server_cors_origins: Vec::new(),
            max_body_size: default_max_body_size(),
            server_unix_socket: None,
            admin_server_port: None,
            jwt_secret: None,
            jwt_secret_is_base64: false,
            jwt_aud: None,
            jwt_iss: None,
            jwt_role_claim_key: default_jwt_role_claim(),
            jwt_cache_enabled: true,
            jwt_cache_max_lifetime: default_jwt_cache_max(),
            jwt_jwks_url: None,
            jwt_jwks_refresh: default_jwt_jwks_refresh(),
            hasura_admin_secret: None,
            hasura_unauthorized_role: None,
            openapi_server_proxy_uri: None,
            openapi_mode: OpenApiMode::FollowPrivileges,
            log_level: default_log_level(),
            log_format: LogFormat::Text,
            otel_db_statement: false,
            role_settings: HashMap::new(),
            app_settings: HashMap::new(),
            graphql_federation: false,
            graphql_type_prefix: None,
            compat_mode: false,
            db_errors_verbatim: Vec::new(),
        }
    }
}

/// Say that a variable was set to something unusable, rather than silently
/// applying the default. A rejected value and an unset one are different
/// mistakes and the operator can only fix the one they are told about.
fn warn_ignored(var: &str, value: &str, expected: &str) {
    tracing::warn!("Ignoring {}={:?}: expected {}", var, value, expected);
}

/// Parse the explicit spellings accepted for boolean environment variables.
fn parse_bool(value: &str) -> Option<bool> {
    match value.trim().to_ascii_lowercase().as_str() {
        "true" | "1" | "yes" | "on" => Some(true),
        "false" | "0" | "no" | "off" => Some(false),
        _ => None,
    }
}

/// Report a variable set to a value that cannot be used, and return the
/// error that stops start-up.
fn invalid(variable: &'static str, value: &str, expected: &'static str) -> ConfigError {
    let error = ConfigError {
        variable,
        value: value.to_string(),
        expected,
    };
    tracing::warn!("{error}");
    error
}

fn env_bool(variable: &'static str, value: &str) -> Result<bool, ConfigError> {
    parse_bool(value).ok_or_else(|| invalid(variable, value, EXPECTED_BOOLEAN))
}

/// Parse `PGRST_DB_ERRORS_VERBATIM`: a boolean, where `true` is every
/// SQLSTATE and `false` none, or a list of SQLSTATEs and `*`-ended prefixes.
/// Upper-cased, since PostgreSQL reports SQLSTATEs in capitals and `p0001`
/// is plainly meant as `P0001`. `None` for anything else -- a typo here would
/// otherwise go on sanitising the very errors it was set to let through.
fn parse_sqlstate_patterns(value: &str) -> Option<Vec<String>> {
    match parse_bool(value) {
        Some(true) => return Some(vec!["*".to_string()]),
        Some(false) => return Some(Vec::new()),
        None => {}
    }
    let sqlstate_chars = |s: &str| s.chars().all(|c| c.is_ascii_alphanumeric());
    value
        .split(',')
        .map(|s| s.trim().to_ascii_uppercase())
        .filter(|s| !s.is_empty())
        .map(|s| {
            let valid = match s.strip_suffix('*') {
                Some(prefix) => prefix.len() < 5 && sqlstate_chars(prefix),
                None => s.len() == 5 && sqlstate_chars(&s),
            };
            valid.then_some(s)
        })
        .collect()
}

/// `db_errors_verbatim` as configuration spells it, checked and upper-cased
/// as `PGRST_DB_ERRORS_VERBATIM` is: a file that says `["p0001"]` or
/// `["true"]` means what the variable would.
fn deserialize_sqlstate_patterns<'de, D: serde::Deserializer<'de>>(
    deserializer: D,
) -> Result<Vec<String>, D::Error> {
    let raw = Vec::<String>::deserialize(deserializer)?.join(",");
    parse_sqlstate_patterns(&raw).ok_or_else(|| {
        serde::de::Error::custom(format!(
            "invalid db_errors_verbatim {raw:?}: expected {EXPECTED_SQLSTATES}"
        ))
    })
}

/// Whether `code` is the SQLSTATE `pattern` names, or begins with the prefix
/// a `*`-ended one does.
fn sqlstate_matches(pattern: &str, code: &str) -> bool {
    match pattern.strip_suffix('*') {
        Some(prefix) => code.starts_with(prefix),
        None => pattern == code,
    }
}

/// Validate a namespace before it becomes part of generated GraphQL names.
fn parse_graphql_type_prefix(value: &str) -> Result<Option<String>, &'static str> {
    let value = value.trim();
    if value.is_empty() {
        return Ok(None);
    }

    let mut chars = value.chars();
    let valid_first = chars
        .next()
        .is_some_and(|c| c == '_' || c.is_ascii_alphabetic());
    if !valid_first || !chars.all(|c| c == '_' || c.is_ascii_alphanumeric()) {
        return Err("a GraphQL identifier beginning with a letter or underscore");
    }

    Ok(Some(value.to_string()))
}

/// The name an environment variable is looked up by. Windows environment
/// names are case-insensitive, and `std::env::var("PGRST_DB_URI")` finds
/// `pgrst_db_uri` there; the names collected for [`AppConfig::try_from_vars`]
/// are matched exactly, so on Windows they are upper-cased to keep that.
/// App settings lose nothing by it: their names are lower-cased anyway.
fn env_name(name: String) -> String {
    if cfg!(windows) {
        upper_env_name(name)
    } else {
        name
    }
}

fn upper_env_name(mut name: String) -> String {
    name.make_ascii_uppercase();
    name
}

impl AppConfig {
    /// Load configuration from environment variables.
    ///
    /// # Panics
    ///
    /// Panics if a boolean environment variable has an unsupported value. Use
    /// [`Self::try_from_env`] when the caller can propagate a startup error.
    pub fn from_env() -> Self {
        Self::try_from_env().unwrap_or_else(|error| panic!("{error}"))
    }

    /// Load configuration from environment variables, rejecting invalid
    /// boolean values.
    pub fn try_from_env() -> Result<Self, ConfigError> {
        // A variable whose name or value is not UTF-8 is skipped, as
        // `std::env::var` would have refused it.
        Self::try_from_vars(
            std::env::vars_os().filter_map(|(k, v)| {
                Some((env_name(k.into_string().ok()?), v.into_string().ok()?))
            }),
        )
    }

    /// Load configuration from name/value pairs spelled as the environment
    /// variables are, for a host with no process environment -- a Cloudflare
    /// Worker reads its bindings instead. Where a name appears twice, the last
    /// one wins. Names are matched exactly, case included.
    pub fn try_from_vars<I, K, V>(vars: I) -> Result<Self, ConfigError>
    where
        I: IntoIterator<Item = (K, V)>,
        K: Into<String>,
        V: Into<String>,
    {
        // Kept in the order given as well as looked up by name: the app
        // settings are found by walking the pairs, and two of them that differ
        // only in case name the same setting, so which one wins has to depend
        // on that order and not on a hash.
        let pairs: Vec<(String, String)> = vars
            .into_iter()
            .map(|(k, v)| (k.into(), v.into()))
            .collect();
        let vars: HashMap<&str, &str> = pairs
            .iter()
            .map(|(k, v)| (k.as_str(), v.as_str()))
            .collect();
        let get = |key: &str| vars.get(key).map(|v| v.to_string()).ok_or(());
        let mut config = Self::default();

        if let Ok(uri) = get("PGRST_DB_URI") {
            config.db_uri = uri;
        }
        if let Ok(uri) = get("DATABASE_URL") {
            config.db_uri = uri;
        }
        if let Ok(schemas) = get("PGRST_DB_SCHEMAS") {
            config.db_schemas = schemas.split(',').map(|s| s.trim().to_string()).collect();
        }
        if let Ok(role) = get("PGRST_DB_ANON_ROLE") {
            config.db_anon_role = Some(role);
        }
        // `PGRST_DB_POOL` is PostgREST's own name; `PGRST_DB_POOL_SIZE` is the
        // one this project's documentation has always given, including the
        // production checklist in docs/deployment.md. Only the former was read,
        // so anybody who followed our own instructions silently kept the
        // default pool.
        for var in ["PGRST_DB_POOL", "PGRST_DB_POOL_SIZE"] {
            if let Ok(size) = get(var) {
                match size.parse::<u32>() {
                    Ok(n) if n > 0 => config.db_pool_size = n,
                    _ => warn_ignored(var, &size, "a positive integer"),
                }
            }
        }
        if let Ok(secs) = get("PGRST_DB_POOL_TIMEOUT") {
            match secs.parse::<u64>() {
                Ok(n) if n > 0 => config.db_pool_timeout = n,
                _ => warn_ignored("PGRST_DB_POOL_TIMEOUT", &secs, "a positive integer"),
            }
        }
        if let Ok(level) = get("PGRST_DB_TX_ISOLATION") {
            match IsolationLevel::parse_config(&level) {
                Some(l) => config.db_tx_isolation = l,
                None => warn_ignored(
                    "PGRST_DB_TX_ISOLATION",
                    &level,
                    "one of: read committed, repeatable read, serializable",
                ),
            }
        }
        if let Ok(v) = get("PGRST_DB_EXTRA_SEARCH_PATH") {
            config.db_extra_search_path = v
                .split(',')
                .map(|s| s.trim().to_string())
                .filter(|s| !s.is_empty())
                .collect();
        }

        if let Ok(v) = get("PGRST_DB_AGGREGATES_ENABLED") {
            config.db_aggregates_enabled = env_bool("PGRST_DB_AGGREGATES_ENABLED", &v)?;
        }
        if let Ok(v) = get("PGRST_DB_PREPARED_STATEMENTS") {
            config.db_prepared_statements = env_bool("PGRST_DB_PREPARED_STATEMENTS", &v)?;
        }
        if let Ok(v) = get("PGRST_DB_PRE_REQUEST") {
            if !v.trim().is_empty() {
                config.db_pre_request = Some(v.trim().to_string());
            }
        }
        if let Ok(v) = get("PGRST_DB_CHANNEL") {
            if !v.trim().is_empty() {
                config.db_channel = v.trim().to_string();
            }
        }
        if let Ok(v) = get("PGRST_DB_CHANNEL_ENABLED") {
            config.db_channel_enabled = env_bool("PGRST_DB_CHANNEL_ENABLED", &v)?;
        }

        // `PGRST_DB_MAX_ROWS` mirrors PostgREST's `db-max-rows`. Accept both.
        for var in ["PGRST_DB_MAX_ROWS", "PGRST_MAX_ROWS"] {
            if let Ok(max_rows) = get(var) {
                match max_rows.parse::<i64>() {
                    Ok(n) if n >= 0 => config.db_max_rows = Some(n),
                    _ => warn_ignored(var, &max_rows, "a non-negative integer"),
                }
            }
        }
        if let Ok(secret) = get("PGRST_JWT_SECRET") {
            config.jwt_secret = Some(secret);
        }
        if let Ok(aud) = get("PGRST_JWT_AUD") {
            config.jwt_aud = Some(aud);
        }
        // Not a PostgREST setting. Empty is read as unset rather than as an
        // issuer nobody can name, which would refuse every token.
        if let Ok(iss) = get("PGRST_JWT_ISS") {
            if !iss.trim().is_empty() {
                config.jwt_iss = Some(iss);
            }
        }
        // Both of these reach the JWT layer already -- `JwtConfig` is built
        // from them in every binary. Only the environment read was missing, so
        // a base64 secret was verified against its own text and a role claim
        // outside `role` was never found.
        if let Ok(v) = get("PGRST_JWT_SECRET_IS_BASE64") {
            config.jwt_secret_is_base64 = env_bool("PGRST_JWT_SECRET_IS_BASE64", &v)?;
        }
        if let Ok(key) = get("PGRST_JWT_ROLE_CLAIM_KEY") {
            if !key.trim().is_empty() {
                config.jwt_role_claim_key = key;
            }
        }
        if let Ok(v) = get("PGRST_JWT_CACHE_ENABLED") {
            config.jwt_cache_enabled = env_bool("PGRST_JWT_CACHE_ENABLED", &v)?;
        }
        // Zero is meaningful here -- it turns the cache off, as in PostgREST --
        // so unlike the other durations it is not rejected.
        if let Ok(v) = get("PGRST_JWT_CACHE_MAX_LIFETIME") {
            match v.parse::<u64>() {
                Ok(n) => config.jwt_cache_max_lifetime = n,
                Err(_) => warn_ignored(
                    "PGRST_JWT_CACHE_MAX_LIFETIME",
                    &v,
                    "a non-negative integer number of seconds",
                ),
            }
        }
        // Not PostgREST settings. Empty is unset, as for the issuer.
        if let Ok(url) = get("PGRST_JWT_JWKS_URL") {
            if !url.trim().is_empty() {
                config.jwt_jwks_url = Some(url.trim().to_string());
            }
        }
        if let Ok(secs) = get("PGRST_JWT_JWKS_REFRESH") {
            match secs.parse::<u64>() {
                Ok(n) if n > 0 => config.jwt_jwks_refresh = n,
                _ => warn_ignored(
                    "PGRST_JWT_JWKS_REFRESH",
                    &secs,
                    "a positive integer number of seconds",
                ),
            }
        }
        // Hasura's own spelling is accepted beside ours, because a deployment
        // migrating from it has these in a compose file already and the point
        // of the mode is that the client does not have to be rewritten. The
        // `PGRST_` name wins where both are set, on the grounds that it is the
        // more specific instruction to this server.
        for var in ["HASURA_GRAPHQL_ADMIN_SECRET", "PGRST_HASURA_ADMIN_SECRET"] {
            if let Ok(secret) = get(var) {
                if !secret.is_empty() {
                    config.hasura_admin_secret = Some(secret);
                }
            }
        }
        for var in [
            "HASURA_GRAPHQL_UNAUTHORIZED_ROLE",
            "PGRST_HASURA_UNAUTHORIZED_ROLE",
        ] {
            if let Ok(role) = get(var) {
                if !role.is_empty() {
                    config.hasura_unauthorized_role = Some(role);
                }
            }
        }
        if let Ok(host) = get("PGRST_SERVER_HOST") {
            config.server_host = host;
        }
        if let Ok(port) = get("PGRST_SERVER_PORT") {
            if let Ok(p) = port.parse() {
                config.server_port = p;
            }
        }
        if let Ok(port) = get("PORT") {
            if let Ok(p) = port.parse() {
                config.server_port = p;
            }
        }
        // A bare `*` is the documented way to spell "any origin", and is the
        // default. An empty list means the same thing, so a value of only
        // separators does not accidentally lock everybody out.
        if let Ok(origins) = get("PGRST_SERVER_CORS_ORIGINS") {
            config.server_cors_origins = if origins.trim() == "*" {
                Vec::new()
            } else {
                origins
                    .split(',')
                    .map(|s| s.trim().to_string())
                    .filter(|s| !s.is_empty())
                    .collect()
            };
        }
        if let Ok(bytes) = get("PGRST_MAX_BODY_SIZE") {
            match bytes.parse::<usize>() {
                Ok(n) if n > 0 => config.max_body_size = n,
                _ => warn_ignored("PGRST_MAX_BODY_SIZE", &bytes, "a positive integer"),
            }
        }
        if let Ok(level) = get("PGRST_LOG_LEVEL") {
            match LogLevel::parse_config(&level) {
                Some(l) => config.log_level = l,
                None => warn_ignored(
                    "PGRST_LOG_LEVEL",
                    &level,
                    "one of: crit, error, warn, info, debug",
                ),
            }
        }
        if let Ok(format) = get("PGRST_LOG_FORMAT") {
            match LogFormat::parse_config(&format) {
                Some(f) => config.log_format = f,
                None => warn_ignored("PGRST_LOG_FORMAT", &format, "one of: text, json"),
            }
        }
        if let Ok(v) = get("PGRST_OTEL_DB_STATEMENT") {
            config.otel_db_statement = env_bool("PGRST_OTEL_DB_STATEMENT", &v)?;
        }
        if let Ok(path) = get("PGRST_SERVER_UNIX_SOCKET") {
            if !path.trim().is_empty() {
                config.server_unix_socket = Some(path.trim().to_string());
            }
        }
        if let Ok(port) = get("PGRST_ADMIN_SERVER_PORT") {
            match port.parse::<u16>() {
                Ok(p) if p > 0 => config.admin_server_port = Some(p),
                _ => warn_ignored("PGRST_ADMIN_SERVER_PORT", &port, "a port number"),
            }
        }
        if let Ok(uri) = get("PGRST_OPENAPI_SERVER_PROXY_URI") {
            if !uri.trim().is_empty() {
                config.openapi_server_proxy_uri = Some(uri.trim().to_string());
            }
        }
        if let Ok(mode) = get("PGRST_OPENAPI_MODE") {
            match OpenApiMode::parse_config(&mode) {
                Some(m) => config.openapi_mode = m,
                None => warn_ignored(
                    "PGRST_OPENAPI_MODE",
                    &mode,
                    "one of: disabled, follow-privileges, ignore-privileges",
                ),
            }
        }

        // `PGRST_ROLE_SETTINGS` is JSON rather than a per-role variable,
        // because a PostgreSQL role name may hold characters an environment
        // variable name cannot.
        if let Ok(raw) = get("PGRST_ROLE_SETTINGS") {
            match serde_json::from_str::<HashMap<String, RoleSettings>>(&raw) {
                Ok(settings) => config.role_settings = settings,
                Err(e) => warn_ignored(
                    "PGRST_ROLE_SETTINGS",
                    &raw,
                    &format!("a JSON object of role to settings ({e})"),
                ),
            }
        }

        if let Ok(value) = get("PGRST_GRAPHQL_FEDERATION") {
            config.graphql_federation = env_bool("PGRST_GRAPHQL_FEDERATION", &value)?;
        }
        if let Ok(value) = get("PGRST_GRAPHQL_TYPE_PREFIX") {
            match parse_graphql_type_prefix(&value) {
                Ok(prefix) => config.graphql_type_prefix = prefix,
                Err(expected) => warn_ignored("PGRST_GRAPHQL_TYPE_PREFIX", &value, expected),
            }
        }

        // `PGRST_APP_SETTINGS_<NAME>` becomes `app.settings.<name>`, which is
        // where PostgREST puts it and where a policy expects to read it back.
        // Names that differ only in case (`..._Tenant`, `..._TENANT`) are the
        // same setting; the one that comes later in the pairs wins, as the
        // later of two equal names does.
        for (key, value) in &pairs {
            if let Some(name) = key.strip_prefix("PGRST_APP_SETTINGS_") {
                if !name.is_empty() {
                    config
                        .app_settings
                        .insert(name.to_ascii_lowercase(), value.clone());
                }
            }
        }
        // Accept either the PGRST_-prefixed name (for parity with other options)
        // or a POSTRUST_-prefixed alias.
        for var in ["PGRST_COMPAT_MODE", "POSTRUST_COMPAT_MODE"] {
            if let Ok(v) = get(var) {
                config.compat_mode = env_bool(var, &v)?;
            }
        }

        if let Ok(v) = get("PGRST_DB_ERRORS_VERBATIM") {
            config.db_errors_verbatim = parse_sqlstate_patterns(&v)
                .ok_or_else(|| invalid("PGRST_DB_ERRORS_VERBATIM", &v, EXPECTED_SQLSTATES))?;
        }

        Ok(config)
    }

    /// Whether `error` is answered in the database's own words: a database
    /// error, in compatibility mode or with a SQLSTATE
    /// [`db_errors_verbatim`](Self::db_errors_verbatim) lists.
    pub fn verbatim_db_error(&self, error: &crate::Error) -> bool {
        match error {
            crate::Error::Database(db) => {
                self.compat_mode
                    || self
                        .db_errors_verbatim
                        .iter()
                        .any(|pattern| sqlstate_matches(pattern, &db.code))
            }
            _ => false,
        }
    }

    /// Whether any database error can be answered in its own words, which is
    /// what decides if a custom route's errors need rendering again.
    pub fn any_verbatim_db_errors(&self) -> bool {
        self.compat_mode || !self.db_errors_verbatim.is_empty()
    }

    /// Get the default schema (first in the list).
    pub fn default_schema(&self) -> &str {
        self.db_schemas
            .first()
            .map(|s| s.as_str())
            .unwrap_or("public")
    }
}

// Serialized as the spelling configuration uses, not as the Rust variant name,
// so that what this writes is what `parse_config` reads back. Deriving
// `Serialize` here instead emits `"ReadCommitted"`, which then fails to
// deserialize -- and `Serializable` happens to survive the round trip, which
// makes the breakage look intermittent rather than total.
impl Serialize for IsolationLevel {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_config_str())
    }
}

impl<'de> Deserialize<'de> for IsolationLevel {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = String::deserialize(deserializer)?;
        Self::parse_config(&raw).ok_or_else(|| {
            serde::de::Error::custom(format!(
                "unknown isolation level {raw:?}: expected one of \
                 read committed, repeatable read, serializable"
            ))
        })
    }
}

impl Serialize for OpenApiMode {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_config_str())
    }
}

impl<'de> Deserialize<'de> for OpenApiMode {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = String::deserialize(deserializer)?;
        Self::parse_config(&raw).ok_or_else(|| {
            serde::de::Error::custom(format!(
                "unknown OpenAPI mode {raw:?}: expected one of \
                 disabled, follow-privileges, ignore-privileges"
            ))
        })
    }
}

impl Serialize for LogLevel {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_config_str())
    }
}

impl<'de> Deserialize<'de> for LogLevel {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = String::deserialize(deserializer)?;
        Self::parse_config(&raw).ok_or_else(|| {
            serde::de::Error::custom(format!(
                "unknown log level {raw:?}: expected one of \
                 crit, error, warn, info, debug"
            ))
        })
    }
}

impl Serialize for LogFormat {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_config_str())
    }
}

impl<'de> Deserialize<'de> for LogFormat {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let raw = String::deserialize(deserializer)?;
        Self::parse_config(&raw).ok_or_else(|| {
            serde::de::Error::custom(format!(
                "unknown log format {raw:?}: expected one of text, json"
            ))
        })
    }
}

/// Per-role settings.
#[derive(Clone, Debug, Default, Serialize, Deserialize)]
#[non_exhaustive]
pub struct RoleSettings {
    /// Isolation level for this role
    pub isolation_level: Option<IsolationLevel>,
    /// Statement timeout in milliseconds
    pub statement_timeout: Option<u64>,
}

/// Transaction isolation levels.
///
/// Deserialized from the spelling the documentation uses (`"serializable"`,
/// `"read committed"`), not from the Rust variant name, so a `role_settings`
/// entry reads the same as the environment variable.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum IsolationLevel {
    /// PostgreSQL's default. A statement sees rows committed before it began.
    ReadCommitted,
    /// Every statement in the transaction sees the same snapshot.
    RepeatableRead,
    /// As `RepeatableRead`, and concurrent transactions are additionally
    /// guaranteed to be equivalent to some serial order. May abort with a
    /// serialization failure, which the client is expected to retry.
    Serializable,
}

impl IsolationLevel {
    /// The spelling PostgreSQL's `SET TRANSACTION ISOLATION LEVEL` expects.
    pub fn to_sql(&self) -> &'static str {
        match self {
            Self::ReadCommitted => "READ COMMITTED",
            Self::RepeatableRead => "REPEATABLE READ",
            Self::Serializable => "SERIALIZABLE",
        }
    }

    /// Parse the spelling used in configuration.
    ///
    /// Case-insensitive, and a hyphen, underscore or space separates the words
    /// equally -- the documentation writes `read committed` and an environment
    /// file is as likely to carry `read-committed`.
    pub fn parse_config(s: &str) -> Option<Self> {
        match s
            .trim()
            .to_ascii_lowercase()
            .replace(['-', '_'], " ")
            .as_str()
        {
            "read committed" => Some(Self::ReadCommitted),
            "repeatable read" => Some(Self::RepeatableRead),
            "serializable" => Some(Self::Serializable),
            _ => None,
        }
    }

    /// The inverse of [`parse_config`](Self::parse_config).
    pub fn as_config_str(&self) -> &'static str {
        match self {
            Self::ReadCommitted => "read committed",
            Self::RepeatableRead => "repeatable read",
            Self::Serializable => "serializable",
        }
    }
}

/// OpenAPI generation mode.
///
/// PostgREST also has a `security-definer` mode, where the specification comes
/// from a user-supplied `SECURITY DEFINER` function. There is no configuration
/// here for naming that function, so the variant is absent rather than present
/// and behaving as one of the others.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum OpenApiMode {
    /// No OpenAPI document is served.
    Disabled,
    /// The document describes only what the requesting role may reach, so two
    /// roles asking are answered differently.
    FollowPrivileges,
    /// The document describes the whole exposed schema, whoever is asking.
    IgnorePrivileges,
}

impl OpenApiMode {
    /// Parse the spelling used in configuration. Case-insensitive, and a
    /// hyphen or an underscore separates the words equally.
    pub fn parse_config(s: &str) -> Option<Self> {
        match s
            .trim()
            .to_ascii_lowercase()
            .replace(['-', '_'], " ")
            .as_str()
        {
            "disabled" => Some(Self::Disabled),
            "follow privileges" => Some(Self::FollowPrivileges),
            "ignore privileges" => Some(Self::IgnorePrivileges),
            _ => None,
        }
    }

    /// The inverse of [`parse_config`](Self::parse_config).
    pub fn as_config_str(&self) -> &'static str {
        match self {
            Self::Disabled => "disabled",
            Self::FollowPrivileges => "follow-privileges",
            Self::IgnorePrivileges => "ignore-privileges",
        }
    }
}

/// Log levels.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum LogLevel {
    /// Only failures that stop the server. Mapped onto `ERROR`, which is the
    /// least severe level `tracing` offers.
    Crit,
    /// Requests that failed, and faults that did not stop the server.
    Error,
    /// Configuration that was ignored, and conditions worth noticing.
    Warn,
    /// Start-up and schema reloads. Every line logged while a request is
    /// being served names its `request_id` and `trace_id`.
    Info,
    /// One line per request with its status and latency, the generated SQL,
    /// and the decisions behind it.
    Debug,
}

impl LogLevel {
    /// The `tracing` level this maps onto.
    ///
    /// `Crit` and `Error` both become `ERROR`: PostgREST distinguishes them
    /// and `tracing` has nothing more severe to map `Crit` onto.
    pub fn to_tracing(&self) -> tracing::Level {
        match self {
            Self::Crit | Self::Error => tracing::Level::ERROR,
            Self::Warn => tracing::Level::WARN,
            Self::Info => tracing::Level::INFO,
            Self::Debug => tracing::Level::DEBUG,
        }
    }

    /// Parse the spelling used in configuration. Case-insensitive.
    pub fn parse_config(s: &str) -> Option<Self> {
        match s.trim().to_ascii_lowercase().as_str() {
            "crit" | "critical" => Some(Self::Crit),
            "error" => Some(Self::Error),
            "warn" | "warning" => Some(Self::Warn),
            "info" => Some(Self::Info),
            "debug" => Some(Self::Debug),
            _ => None,
        }
    }

    /// The inverse of [`parse_config`](Self::parse_config).
    pub fn as_config_str(&self) -> &'static str {
        match self {
            Self::Crit => "crit",
            Self::Error => "error",
            Self::Warn => "warn",
            Self::Info => "info",
            Self::Debug => "debug",
        }
    }
}

/// How log lines are written.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum LogFormat {
    /// One human-readable line per event, with the fields of the spans it
    /// happened in. The default.
    #[default]
    Text,
    /// One JSON object per line, for a log shipper: the event's fields, and
    /// the current span and every span above it with their fields.
    Json,
}

impl LogFormat {
    /// Parse the spelling used in configuration. Case-insensitive.
    pub fn parse_config(s: &str) -> Option<Self> {
        match s.trim().to_ascii_lowercase().as_str() {
            "text" => Some(Self::Text),
            "json" => Some(Self::Json),
            _ => None,
        }
    }

    /// The inverse of [`parse_config`](Self::parse_config).
    pub fn as_config_str(&self) -> &'static str {
        match self {
            Self::Text => "text",
            Self::Json => "json",
        }
    }
}

// Default value functions
fn default_db_uri() -> String {
    "postgresql://localhost/postgres".to_string()
}

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

fn default_pool_size() -> u32 {
    10
}

fn default_pool_timeout() -> u64 {
    10
}

fn default_tx_isolation() -> IsolationLevel {
    IsolationLevel::ReadCommitted
}

fn default_max_body_size() -> usize {
    10 * 1024 * 1024
}

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

fn default_db_channel() -> String {
    "pgrst".to_string()
}

fn default_host() -> String {
    "127.0.0.1".to_string()
}

fn default_port() -> u16 {
    3000
}

fn default_jwt_role_claim() -> String {
    "role".to_string()
}

fn default_jwt_cache_max() -> u64 {
    3600
}

fn default_jwt_jwks_refresh() -> u64 {
    300
}

fn default_openapi_mode() -> OpenApiMode {
    OpenApiMode::FollowPrivileges
}

// `info`, not `error`. The documentation has always said `info`, and the
// server's own fallback filter is `postrust=info`, so `error` was a third
// answer that agreed with neither -- harmless only for as long as nothing
// read the field.
fn default_log_level() -> LogLevel {
    LogLevel::Info
}

fn default_true() -> bool {
    true
}

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

    #[test]
    fn test_default_config() {
        let config = AppConfig::default();
        assert_eq!(config.server_port, 3000);
        assert_eq!(config.db_pool_size, 10);
        assert!(config.db_prepared_statements);
        assert!(!config.graphql_federation);
        assert_eq!(config.graphql_type_prefix, None);
    }

    #[test]
    fn db_errors_verbatim_takes_sqlstates_prefixes_and_booleans() {
        let parse = |v: &str| {
            AppConfig::try_from_vars([("PGRST_DB_ERRORS_VERBATIM", v)])
                .map(|c| c.db_errors_verbatim)
        };
        assert_eq!(parse("P0001, pt*").unwrap(), ["P0001", "PT*"]);
        assert_eq!(parse("true").unwrap(), ["*"]);
        assert_eq!(parse("off").unwrap(), Vec::<String>::new());
        assert_eq!(parse("").unwrap(), Vec::<String>::new());
        for bad in ["P001", "P00011", "P0*01", "P0001*", "4250!"] {
            assert!(parse(bad).is_err(), "{bad:?}");
        }

        // A configuration file is held to the same spellings.
        let from_json = |v: &str| {
            serde_json::from_str::<AppConfig>(&format!(r#"{{"db_errors_verbatim": {v}}}"#))
                .map(|c| c.db_errors_verbatim)
        };
        assert_eq!(from_json(r#"["p0001", "PT*"]"#).unwrap(), ["P0001", "PT*"]);
        assert_eq!(from_json(r#"["true"]"#).unwrap(), ["*"]);
        assert!(from_json(r#"["P001"]"#).is_err());
    }

    #[test]
    fn verbatim_db_error_matches_only_listed_database_errors() {
        let db = |code: &str| {
            crate::Error::Database(crate::error::DatabaseError {
                code: code.to_string(),
                message: String::new(),
                details: None,
                hint: None,
                constraint: None,
                table: None,
                column: None,
            })
        };
        let mut config = AppConfig::default();
        assert!(!config.verbatim_db_error(&db("P0001")));
        assert!(!config.any_verbatim_db_errors());

        config.db_errors_verbatim = vec!["P0001".to_string(), "PT*".to_string()];
        assert!(config.any_verbatim_db_errors());
        assert!(config.verbatim_db_error(&db("P0001")));
        assert!(config.verbatim_db_error(&db("PT402")));
        assert!(!config.verbatim_db_error(&db("23505")));
        assert!(!config.verbatim_db_error(&crate::Error::NotFound("t".to_string())));

        config.db_errors_verbatim = vec!["*".to_string()];
        assert!(config.verbatim_db_error(&db("42P01")));

        config.db_errors_verbatim.clear();
        config.compat_mode = true;
        assert!(config.verbatim_db_error(&db("23505")));
    }

    #[test]
    fn test_default_schema() {
        let mut config = AppConfig::default();
        assert_eq!(config.default_schema(), "public");

        config.db_schemas = vec!["api".to_string(), "public".to_string()];
        assert_eq!(config.default_schema(), "api");
    }

    #[test]
    fn test_isolation_level_sql() {
        assert_eq!(IsolationLevel::ReadCommitted.to_sql(), "READ COMMITTED");
        assert_eq!(IsolationLevel::Serializable.to_sql(), "SERIALIZABLE");
    }

    #[test]
    fn isolation_level_accepts_the_documented_spellings() {
        // The documentation writes `read committed`; an environment file is as
        // likely to carry either separator, or capitals.
        for s in [
            "read committed",
            "READ COMMITTED",
            "read-committed",
            " Read_Committed ",
        ] {
            assert_eq!(
                IsolationLevel::parse_config(s),
                Some(IsolationLevel::ReadCommitted),
                "{s:?}"
            );
        }
        assert_eq!(
            IsolationLevel::parse_config("serializable"),
            Some(IsolationLevel::Serializable)
        );
        assert_eq!(
            IsolationLevel::parse_config("repeatable read"),
            Some(IsolationLevel::RepeatableRead)
        );
        // Not a level. Rejected rather than resolved to a default, so the
        // caller can say so.
        assert_eq!(IsolationLevel::parse_config("dirty read"), None);
        assert_eq!(IsolationLevel::parse_config(""), None);
    }

    #[test]
    fn log_level_accepts_the_documented_spellings() {
        assert_eq!(LogLevel::parse_config("INFO"), Some(LogLevel::Info));
        assert_eq!(LogLevel::parse_config("warning"), Some(LogLevel::Warn));
        assert_eq!(LogLevel::parse_config("crit"), Some(LogLevel::Crit));
        // `trace` was listed in the documentation and is not a level this
        // server has. It is rejected rather than silently read as `debug`.
        assert_eq!(LogLevel::parse_config("trace"), None);
    }

    #[test]
    fn default_log_level_matches_the_documented_one() {
        // The struct default disagreed with both the documentation and the
        // server's own fallback filter for as long as nothing read it.
        assert_eq!(AppConfig::default().log_level, LogLevel::Info);
    }

    #[test]
    fn parse_bool_accepts_only_the_supported_spellings() {
        for s in ["true", "TRUE", "1", "yes", "on", " On "] {
            assert_eq!(parse_bool(s), Some(true), "{s:?}");
        }
        for s in ["false", "FALSE", "0", "no", "off", " Off "] {
            assert_eq!(parse_bool(s), Some(false), "{s:?}");
        }
        for s in ["", "maybe", "enabled", "2"] {
            assert_eq!(parse_bool(s), None, "{s:?}");
        }
    }

    #[test]
    fn graphql_federation_configuration_is_read() {
        let config = with_env(&[
            ("PGRST_GRAPHQL_FEDERATION", "true"),
            ("PGRST_GRAPHQL_TYPE_PREFIX", " test "),
        ]);

        assert!(config.graphql_federation);
        assert_eq!(config.graphql_type_prefix.as_deref(), Some("test"));
    }

    #[test]
    fn graphql_federation_accepts_an_explicit_false() {
        assert!(!with_env(&[("PGRST_GRAPHQL_FEDERATION", "false")]).graphql_federation);
    }

    #[test]
    fn malformed_graphql_federation_configuration_is_rejected() {
        let error = with_env_result(&[("PGRST_GRAPHQL_FEDERATION", "sometimes")])
            .expect_err("an invalid boolean must reject the configuration");

        assert_eq!(
            error.to_string(),
            "invalid value for PGRST_GRAPHQL_FEDERATION: \"sometimes\"; expected one of: true, false, 1, 0, yes, no, on, off"
        );
    }

    #[test]
    fn an_empty_graphql_prefix_means_unset() {
        let config = with_env(&[("PGRST_GRAPHQL_TYPE_PREFIX", "   ")]);

        assert_eq!(config.graphql_type_prefix, None);
    }

    // `from_env` reads process-global state, so these run one at a time.
    static ENV_LOCK: std::sync::Mutex<()> = std::sync::Mutex::new(());

    /// Set the given variables, load, then remove them again.
    fn with_env(vars: &[(&str, &str)]) -> AppConfig {
        with_env_result(vars).expect("test configuration should be valid")
    }

    fn with_env_result(vars: &[(&str, &str)]) -> Result<AppConfig, ConfigError> {
        let _guard = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
        for (k, v) in vars {
            std::env::set_var(k, v);
        }
        let config = AppConfig::try_from_env();
        for (k, _) in vars {
            std::env::remove_var(k);
        }
        config
    }

    #[test]
    fn documented_variables_are_read() {
        // Every one of these was documented and read by nothing. The features
        // behind them already worked -- only the environment read was missing.
        let config = with_env(&[
            ("PGRST_DB_POOL_SIZE", "42"),
            ("PGRST_DB_POOL_TIMEOUT", "7"),
            ("PGRST_DB_TX_ISOLATION", "serializable"),
            ("PGRST_JWT_SECRET_IS_BASE64", "true"),
            ("PGRST_JWT_ROLE_CLAIM_KEY", "user.role"),
            ("PGRST_LOG_LEVEL", "warn"),
            ("PGRST_MAX_BODY_SIZE", "1024"),
            (
                "PGRST_SERVER_CORS_ORIGINS",
                "https://a.example, https://b.example",
            ),
        ]);

        assert_eq!(config.db_pool_size, 42);
        assert_eq!(config.db_pool_timeout, 7);
        assert_eq!(config.db_tx_isolation, IsolationLevel::Serializable);
        assert!(config.jwt_secret_is_base64);
        assert_eq!(config.jwt_role_claim_key, "user.role");
        assert_eq!(config.log_level, LogLevel::Warn);
        assert_eq!(config.max_body_size, 1024);
        assert_eq!(
            config.server_cors_origins,
            vec![
                "https://a.example".to_string(),
                "https://b.example".to_string()
            ]
        );
    }

    #[test]
    fn the_jwt_issuer_is_read_and_an_empty_one_is_unset() {
        let read = |value: &str| {
            AppConfig::try_from_vars([("PGRST_JWT_ISS", value)])
                .unwrap()
                .jwt_iss
        };
        assert_eq!(
            read("https://issuer.example").as_deref(),
            Some("https://issuer.example")
        );
        assert_eq!(read("  "), None);
        assert_eq!(
            AppConfig::try_from_vars(Vec::<(String, String)>::new())
                .unwrap()
                .jwt_iss,
            None
        );
    }

    #[test]
    fn the_jwks_url_and_its_refresh_interval_are_read() {
        let read = |vars: &[(&str, &str)]| AppConfig::try_from_vars(vars.to_vec()).unwrap();
        let config = read(&[
            ("PGRST_JWT_JWKS_URL", " https://idp.example/jwks "),
            ("PGRST_JWT_JWKS_REFRESH", "60"),
        ]);
        assert_eq!(
            config.jwt_jwks_url.as_deref(),
            Some("https://idp.example/jwks")
        );
        assert_eq!(config.jwt_jwks_refresh, 60);

        let defaults = read(&[("PGRST_JWT_JWKS_URL", ""), ("PGRST_JWT_JWKS_REFRESH", "0")]);
        assert_eq!(defaults.jwt_jwks_url, None);
        assert_eq!(defaults.jwt_jwks_refresh, 300);
        assert_eq!(
            read(&[("PGRST_JWT_JWKS_REFRESH", "soon")]).jwt_jwks_refresh,
            300
        );
    }

    #[test]
    fn variables_can_come_from_somewhere_other_than_the_environment() {
        // What a Cloudflare Worker does with its bindings: nothing here is in
        // the process environment, and the app settings, which are found by
        // prefix rather than by name, arrive all the same.
        let config = AppConfig::try_from_vars([
            ("PGRST_DB_SCHEMAS", "api, extra"),
            ("PGRST_DB_ANON_ROLE", "web_anon"),
            ("PGRST_JWT_SECRET", "a-secret"),
            ("PGRST_DB_MAX_ROWS", "100"),
            ("PGRST_APP_SETTINGS_Tenant", "acme"),
        ])
        .unwrap();

        assert_eq!(config.db_schemas, ["api", "extra"]);
        assert_eq!(config.db_anon_role.as_deref(), Some("web_anon"));
        assert_eq!(config.jwt_secret.as_deref(), Some("a-secret"));
        assert_eq!(config.db_max_rows, Some(100));
        assert_eq!(
            config.app_settings.get("tenant").map(String::as_str),
            Some("acme")
        );

        let refused = AppConfig::try_from_vars([("PGRST_DB_AGGREGATES_ENABLED", "maybe")]);
        assert!(refused.is_err());
    }

    #[test]
    fn app_settings_differing_only_in_case_take_the_later_value() {
        // Both name `app.settings.tenant`. Run it a few times: with the pairs
        // in a hash map the winner changed from one run to the next.
        for _ in 0..16 {
            let config = AppConfig::try_from_vars([
                ("PGRST_APP_SETTINGS_Tenant", "first"),
                ("PGRST_APP_SETTINGS_TENANT", "second"),
                ("PGRST_APP_SETTINGS_tenant", "third"),
            ])
            .unwrap();
            assert_eq!(
                config.app_settings.get("tenant").map(String::as_str),
                Some("third")
            );

            let config = AppConfig::try_from_vars([
                ("PGRST_APP_SETTINGS_tenant", "third"),
                ("PGRST_APP_SETTINGS_TENANT", "second"),
            ])
            .unwrap();
            assert_eq!(
                config.app_settings.get("tenant").map(String::as_str),
                Some("second")
            );
        }
    }

    #[test]
    fn windows_environment_names_are_matched_whatever_their_case() {
        // What `env_name` does on Windows, where `std::env::var` ignored case.
        let config = AppConfig::try_from_vars([
            (upper_env_name("pgrst_db_schemas".into()), "api"),
            (upper_env_name("Pgrst_App_Settings_Tenant".into()), "acme"),
        ])
        .unwrap();
        assert_eq!(config.db_schemas, ["api"]);
        assert_eq!(
            config.app_settings.get("tenant").map(String::as_str),
            Some("acme")
        );
        assert_eq!(env_name("PGRST_DB_URI".into()), "PGRST_DB_URI");
        assert_eq!(
            env_name("pgrst_db_uri".into()) == "PGRST_DB_URI",
            cfg!(windows)
        );
    }

    #[test]
    fn pool_size_accepts_postgrests_own_name() {
        assert_eq!(with_env(&[("PGRST_DB_POOL", "5")]).db_pool_size, 5);
    }

    #[test]
    fn a_star_origin_means_any_origin() {
        // Empty is how "any" is carried, so `*` must not become a literal
        // origin that matches nothing.
        assert!(with_env(&[("PGRST_SERVER_CORS_ORIGINS", "*")])
            .server_cors_origins
            .is_empty());
        assert!(with_env(&[("PGRST_SERVER_CORS_ORIGINS", " , ")])
            .server_cors_origins
            .is_empty());
    }

    #[test]
    fn an_unusable_value_leaves_the_default() {
        let config = with_env(&[
            ("PGRST_DB_POOL_SIZE", "lots"),
            ("PGRST_DB_POOL_TIMEOUT", "0"),
            ("PGRST_MAX_BODY_SIZE", "-1"),
            ("PGRST_DB_TX_ISOLATION", "dirty read"),
            ("PGRST_LOG_LEVEL", "shout"),
        ]);

        let d = AppConfig::default();
        assert_eq!(config.db_pool_size, d.db_pool_size);
        assert_eq!(config.db_pool_timeout, d.db_pool_timeout);
        assert_eq!(config.max_body_size, d.max_body_size);
        assert_eq!(config.db_tx_isolation, d.db_tx_isolation);
        assert_eq!(config.log_level, d.log_level);
    }

    #[test]
    fn the_formerly_dead_fields_are_read() {
        // Every one of these was a public field that nothing set and nothing
        // consumed.
        let config = with_env(&[
            ("PGRST_DB_PREPARED_STATEMENTS", "false"),
            ("PGRST_DB_PRE_REQUEST", "auth.check"),
            ("PGRST_DB_CHANNEL", "my_channel"),
            ("PGRST_DB_CHANNEL_ENABLED", "yes"),
            ("PGRST_JWT_CACHE_ENABLED", "false"),
            ("PGRST_JWT_CACHE_MAX_LIFETIME", "60"),
            ("PGRST_SERVER_UNIX_SOCKET", "/tmp/postrust.sock"),
            ("PGRST_ADMIN_SERVER_PORT", "3001"),
            ("PGRST_OPENAPI_SERVER_PROXY_URI", "https://api.example.com"),
            ("PGRST_OPENAPI_MODE", "ignore-privileges"),
        ]);

        assert!(!config.db_prepared_statements);
        assert_eq!(config.db_pre_request.as_deref(), Some("auth.check"));
        assert_eq!(config.db_channel, "my_channel");
        assert!(config.db_channel_enabled);
        assert!(!config.jwt_cache_enabled);
        assert_eq!(config.jwt_cache_max_lifetime, 60);
        assert_eq!(
            config.server_unix_socket.as_deref(),
            Some("/tmp/postrust.sock")
        );
        assert_eq!(config.admin_server_port, Some(3001));
        assert_eq!(
            config.openapi_server_proxy_uri.as_deref(),
            Some("https://api.example.com")
        );
        assert_eq!(config.openapi_mode, OpenApiMode::IgnorePrivileges);
    }

    #[test]
    fn tracing_settings_are_read() {
        let d = AppConfig::default();
        assert_eq!(d.log_format, LogFormat::Text);
        assert!(!d.otel_db_statement);

        let config = with_env(&[
            ("PGRST_LOG_FORMAT", "JSON"),
            ("PGRST_OTEL_DB_STATEMENT", "on"),
        ]);
        assert_eq!(config.log_format, LogFormat::Json);
        assert!(config.otel_db_statement);

        // A format nobody can write is ignored with a warning; a boolean that
        // is not one fails, as every boolean setting does.
        assert_eq!(
            with_env(&[("PGRST_LOG_FORMAT", "yaml")]).log_format,
            LogFormat::Text
        );
        assert!(with_env_result(&[("PGRST_OTEL_DB_STATEMENT", "maybe")]).is_err());
    }

    #[test]
    fn a_zero_jwt_cache_lifetime_is_kept_because_it_turns_the_cache_off() {
        // Unlike the other durations, 0 is a meaningful value here and must
        // not be rejected as unusable.
        assert_eq!(
            with_env(&[("PGRST_JWT_CACHE_MAX_LIFETIME", "0")]).jwt_cache_max_lifetime,
            0
        );
    }

    #[test]
    fn app_settings_come_from_a_prefix() {
        let config = with_env(&[
            ("PGRST_APP_SETTINGS_JWT_LIFETIME", "3600"),
            ("PGRST_APP_SETTINGS_TenantName", "acme"),
        ]);
        // Lower-cased, because that is the name a policy reads back with
        // `current_setting('app.settings.<name>')`.
        assert_eq!(
            config.app_settings.get("jwt_lifetime").map(String::as_str),
            Some("3600")
        );
        assert_eq!(
            config.app_settings.get("tenantname").map(String::as_str),
            Some("acme")
        );
    }

    #[test]
    fn role_settings_parse_from_json_using_the_documented_spellings() {
        let config = with_env(&[(
            "PGRST_ROLE_SETTINGS",
            r#"{"web_user":{"isolation_level":"serializable","statement_timeout":5000}}"#,
        )]);
        let web_user = config.role_settings.get("web_user").expect("role present");
        assert_eq!(web_user.isolation_level, Some(IsolationLevel::Serializable));
        assert_eq!(web_user.statement_timeout, Some(5000));
    }

    #[test]
    fn unparseable_role_settings_leave_the_map_empty() {
        assert!(with_env(&[("PGRST_ROLE_SETTINGS", "{not json")])
            .role_settings
            .is_empty());
        // A valid JSON object naming a level that does not exist is refused
        // as a whole rather than half-applied.
        assert!(with_env(&[(
            "PGRST_ROLE_SETTINGS",
            r#"{"r":{"isolation_level":"dirty"}}"#
        )])
        .role_settings
        .is_empty());
    }

    #[test]
    fn openapi_mode_accepts_the_documented_spellings() {
        assert_eq!(
            OpenApiMode::parse_config("follow-privileges"),
            Some(OpenApiMode::FollowPrivileges)
        );
        assert_eq!(
            OpenApiMode::parse_config("IGNORE_PRIVILEGES"),
            Some(OpenApiMode::IgnorePrivileges)
        );
        assert_eq!(
            OpenApiMode::parse_config("disabled"),
            Some(OpenApiMode::Disabled)
        );
        // PostgREST's fourth mode needs a function this server has no
        // configuration for, so it is not accepted rather than aliased.
        assert_eq!(OpenApiMode::parse_config("security-definer"), None);
    }

    #[test]
    fn the_config_enums_round_trip_through_json() {
        // Deriving `Serialize` emits the Rust variant name while the
        // hand-written `Deserialize` reads the configuration spelling, so a
        // value this type writes could not be read back. `Serializable`
        // survived by coincidence -- its variant name lowercases to the
        // accepted spelling -- which made the breakage look intermittent.
        for level in [
            IsolationLevel::ReadCommitted,
            IsolationLevel::RepeatableRead,
            IsolationLevel::Serializable,
        ] {
            let json = serde_json::to_string(&level).unwrap();
            let back: IsolationLevel = serde_json::from_str(&json).unwrap();
            assert_eq!(back, level, "{json}");
        }

        for mode in [
            OpenApiMode::Disabled,
            OpenApiMode::FollowPrivileges,
            OpenApiMode::IgnorePrivileges,
        ] {
            let json = serde_json::to_string(&mode).unwrap();
            assert_eq!(serde_json::from_str::<OpenApiMode>(&json).unwrap(), mode);
        }

        for level in [
            LogLevel::Crit,
            LogLevel::Error,
            LogLevel::Warn,
            LogLevel::Info,
            LogLevel::Debug,
        ] {
            let json = serde_json::to_string(&level).unwrap();
            assert_eq!(serde_json::from_str::<LogLevel>(&json).unwrap(), level);
        }
    }

    #[test]
    fn a_whole_config_round_trips_through_json() {
        // The struct derives both, which invites persisting it.
        let mut config = AppConfig::default();
        config.role_settings.insert(
            "web_user".to_string(),
            RoleSettings {
                isolation_level: Some(IsolationLevel::RepeatableRead),
                statement_timeout: Some(5000),
            },
        );

        let json = serde_json::to_string(&config).unwrap();
        let back: AppConfig = serde_json::from_str(&json).expect("config should round trip");

        assert_eq!(back.db_tx_isolation, config.db_tx_isolation);
        assert_eq!(back.log_level, config.log_level);
        assert_eq!(back.openapi_mode, config.openapi_mode);
        assert_eq!(
            back.role_settings["web_user"].isolation_level,
            Some(IsolationLevel::RepeatableRead)
        );
    }

    #[test]
    fn the_serialized_spelling_is_the_configuration_spelling() {
        // Not the Rust variant name: what is written should be what an
        // operator could paste into the environment.
        assert_eq!(
            serde_json::to_string(&IsolationLevel::ReadCommitted).unwrap(),
            "\"read committed\""
        );
        assert_eq!(
            serde_json::to_string(&OpenApiMode::FollowPrivileges).unwrap(),
            "\"follow-privileges\""
        );
        assert_eq!(serde_json::to_string(&LogLevel::Warn).unwrap(), "\"warn\"");
    }

    #[test]
    fn an_empty_role_claim_key_is_not_accepted() {
        // An empty key would look up nothing and every request would fall to
        // the anonymous role.
        assert_eq!(
            with_env(&[("PGRST_JWT_ROLE_CLAIM_KEY", "  ")]).jwt_role_claim_key,
            AppConfig::default().jwt_role_claim_key
        );
    }
}