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, conextra="forbid": una variable desconocida o mal escrita impide arrancar. ENVIRONMENTes obligatoria y sólo admitelocaloproduction. Sin valor por defecto: un despliegue que la olvide no se trata comolocal.DEBUG,DATABASE_ECHOyDATABASE_USE_NULL_POOLsólo conlocal. Enproductionel servicio no arranca si alguna está activa.JWT_JWKS_URLes obligatoria y debe usarhttpsfuera delocal.DATABASE_URLesSecretStr, exigepostgresql+asyncpg, host y base, y ningún mensaje de error la incluye (hide_input_in_errors=True).DATABASE_SCHEMASse normaliza a minúsculas y rechazapublic,information_schema,pg_*e identificadores inválidos o de más de 63 caracteres./docs,/redocy/openapi.jsonsólo se publican enlocal.- La aplicación se construye con
create_app(settings); las dependencias leenapp.state.settings, noget_settings().
Alternativas descartadas¶
- Leer
os.environdonde 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
.envcon 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
Settingsexplí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.