Saltar a contenido

0003. Configuración validada al arrancar y dos entornos: local y production

Estado: Parcialmente reemplazado por ADR 0013 Fecha: 2026-10-05 Autor: David Garcia Módulo(s) afectado(s): app/core/config.py, app/main.py, .env.example Modificado por: ADR 0013 — extra="forbid" pasa a extra="ignore"

Contexto

Un error de configuración (una variable mal escrita, DEBUG encendido en producción, un JWKS por http) no falla al arrancar: aparece después, en producción, como una fuga de datos o un servicio que responde 401 a todo. Hace falta que la configuración inválida impida arrancar.

Decisión

  • Toda la configuración vive en Settings (pydantic-settings), leída del entorno o de .env, con extra="forbid": una variable desconocida o mal escrita impide arrancar.
  • ENVIRONMENT es obligatoria y sólo admite local o production. Sin valor por defecto: un despliegue que la olvide no se trata como local.
  • DEBUG, DATABASE_ECHO y DATABASE_USE_NULL_POOL sólo con local. En production el servicio no arranca si alguna está activa.
  • JWT_JWKS_URL es obligatoria y debe usar https fuera de local.
  • DATABASE_URL es SecretStr, exige postgresql+asyncpg, host y base, y ningún mensaje de error la incluye (hide_input_in_errors=True).
  • DATABASE_SCHEMAS se normaliza a minúsculas y rechaza public, information_schema, pg_* e identificadores inválidos o de más de 63 caracteres.
  • /docs, /redoc y /openapi.json sólo se publican en local.
  • La aplicación se construye con create_app(settings); las dependencias leen app.state.settings, no get_settings().

Alternativas descartadas

  • Leer os.environ donde se necesite — los errores aparecen en el primer uso, no al arrancar.
  • Más entornos (staging, test) — no cambian ninguna regla; si un entorno necesita otra, se agrega cuando exista.
  • Publicar OpenAPI en todos los entornos — expone el mapa de la API sin autenticación.

Consecuencias

  • Un .env con una variable de más (por ejemplo, las del contenedor de PostgreSQL) no arranca: esas van en .env.docker.example.
  • Los tests construyen la app con Settings explícitos, sin tocar el entorno.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.