"""Runtime configuration read from environment variables (12-factor style). Non-secret settings have safe defaults. Connection strings with passwords are read from files (`DATABASE_URL_FILE`, `CACHE_URL_FILE` → Docker secrets in /run/secrets), so they never appear in `docker inspect`, compose files or logs. Invalid values stop the process at startup with a clear message. """ from __future__ import annotations import os import re import socket from dataclasses import dataclass from pathlib import Path class ConfigError(ValueError): pass INSTANCE_ID_RE = re.compile(r"[A-Za-z0-9._-]{1,64}") def _instance_id() -> str: """X-Instance-Id of this process: INSTANCE_ID or the container hostname. Docker sets the hostname of a container to its short container ID, so the value is unique per replica, stable for the life of the process and maps 1:1 to a real container (`docker inspect`), which scripts/stop-one.sh relies on. """ value = os.environ.get("INSTANCE_ID", "").strip() or socket.gethostname() if INSTANCE_ID_RE.fullmatch(value) is None: raise ConfigError("INSTANCE_ID must match [A-Za-z0-9._-]{1,64}") return value def _int(name: str, default: int, low: int, high: int) -> int: raw = os.environ.get(name) if raw is None or raw.strip() == "": return default try: value = int(raw.strip()) except ValueError: raise ConfigError(f"{name} must be an integer, got {raw!r}") from None if not low <= value <= high: raise ConfigError(f"{name} must be in [{low}, {high}], got {value}") return value def _float(name: str, default: float, low: float, high: float) -> float: raw = os.environ.get(name) if raw is None or raw.strip() == "": return default try: value = float(raw.strip()) except ValueError: raise ConfigError(f"{name} must be a number, got {raw!r}") from None if not low <= value <= high: raise ConfigError(f"{name} must be in [{low}, {high}], got {value}") return value def _bool(name: str, default: bool) -> bool: raw = os.environ.get(name, "").strip().lower() if raw == "": return default if raw not in {"true", "false", "1", "0"}: raise ConfigError(f"{name} must be true/false, got {raw!r}") return raw in {"true", "1"} def _choice(name: str, default: str, allowed: set[str]) -> str: value = os.environ.get(name, "").strip().lower() or default if value not in allowed: raise ConfigError(f"{name} must be one of {sorted(allowed)}, got {value!r}") return value def _secret(name: str, required: bool) -> str: """Value of _FILE (preferred, Docker secret) or (local runs/tests).""" path = os.environ.get(f"{name}_FILE", "").strip() if path: try: value = Path(path).read_text(encoding="utf-8").strip() except OSError as exc: # The message names the file, never its content. raise ConfigError(f"{name}_FILE={path} cannot be read: {exc.strerror}") from None else: value = os.environ.get(name, "").strip() if required and not value: raise ConfigError(f"{name}_FILE (or {name}) must be set") return value @dataclass(frozen=True) class Settings: host: str port: int env: str log_level: str shutdown_timeout: float max_body_bytes: int docs_enabled: bool = True database_url: str = "" session_store: str = "postgres" cache_url: str = "" session_ttl_seconds: int = 3600 db_pool_min: int = 1 db_pool_max: int = 10 db_timeout_seconds: float = 3.0 cache_timeout_seconds: float = 0.5 hash_concurrency: int = 2 instance_id: str = "local" drain_seconds: float = 0.0 idempotency_ttl_seconds: int = 86400 stats_log_seconds: float = 0.0 message_write_path: str = "function" @property def db_statement_timeout_ms(self) -> int: # The server stops a statement a bit before the client-side deadline fires. return max(100, int(self.db_timeout_seconds * 1000) - 500) @classmethod def from_env(cls) -> "Settings": log_level = os.environ.get("LOG_LEVEL", "info").strip().lower() or "info" if log_level not in {"debug", "info", "warning", "error"}: raise ConfigError(f"LOG_LEVEL must be debug/info/warning/error, got {log_level!r}") session_store = os.environ.get("SESSION_STORE", "postgres").strip().lower() or "postgres" if session_store == "redis": session_store = "valkey" # same protocol; the course allows Redis OR Valkey if session_store not in {"postgres", "valkey"}: raise ConfigError(f"SESSION_STORE must be postgres or valkey, got {session_store!r}") db_pool_min = _int("DB_POOL_MIN", 1, 0, 50) db_pool_max = _int("DB_POOL_MAX", 10, 1, 100) if db_pool_min > db_pool_max: raise ConfigError("DB_POOL_MIN must not exceed DB_POOL_MAX") return cls( host=os.environ.get("APP_HOST", "0.0.0.0").strip() or "0.0.0.0", port=_int("APP_PORT", 8080, 1, 65535), env=os.environ.get("APP_ENV", "lab").strip() or "lab", log_level=log_level, # DRAIN_SECONDS + SHUTDOWN_TIMEOUT_SECONDS must stay below compose stop_grace_period. shutdown_timeout=_float("SHUTDOWN_TIMEOUT_SECONDS", 8.0, 0.0, 30.0), max_body_bytes=_int("MAX_BODY_BYTES", 64 * 1024, 1024, 1024 * 1024), docs_enabled=_bool("DOCS_ENABLED", True), database_url=_secret("DATABASE_URL", required=True), session_store=session_store, cache_url=_secret("CACHE_URL", required=session_store == "valkey"), # Contract name. Minimum 1 s so the expiry test can use 2 s. session_ttl_seconds=_int("SESSION_TTL_SECONDS", 3600, 1, 30 * 24 * 3600), db_pool_min=db_pool_min, db_pool_max=db_pool_max, db_timeout_seconds=_float("DB_TIMEOUT_SECONDS", 3.0, 0.5, 30.0), cache_timeout_seconds=_float("CACHE_TIMEOUT_SECONDS", 0.5, 0.05, 10.0), hash_concurrency=_int("PASSWORD_HASH_CONCURRENCY", 2, 1, 16), instance_id=_instance_id(), # After SIGTERM: readiness is 503 but requests are still served for this long, # so the load balancer stops routing here before the listener closes. drain_seconds=_float("DRAIN_SECONDS", 0.0, 0.0, 10.0), # Contract: a replay within 24 h returns the original result. idempotency_ttl_seconds=_int("IDEMPOTENCY_TTL_SECONDS", 86400, 86400, 30 * 24 * 3600), # Experiments (bench/track1): log DB pool counters and process CPU every N s; 0 = off. stats_log_seconds=_float("STATS_LOG_SECONDS", 0.0, 0.0, 60.0), # Track 1: `function` = one SQL call per send (migration 0003), `multi` = the previous # multi-statement transaction; both have identical semantics (A/B on one image). message_write_path=_choice("MESSAGE_WRITE_PATH", "function", {"function", "multi"}), )