42 lines
1.8 KiB
Markdown
42 lines
1.8 KiB
Markdown
# SPEC — F-004 Typed config and feature flags
|
||
|
||
## Problem
|
||
Risky features need activation separate from deployment; env access must be typed.
|
||
Today env access is ad-hoc (`process.env.X ?? fallback` scattered in entrypoints)
|
||
and there is no activation mechanism distinct from deploy.
|
||
|
||
## Goal
|
||
Fail-fast typed config plus a simple feature flag module behind an interface.
|
||
|
||
## Scope IN
|
||
- Typed env config loader in `src/infrastructure/config`, fail fast on missing/invalid required vars (all problems reported in one clear message)
|
||
- `FeatureFlagProvider` interface with simple in-memory store implementation (`src/modules/flags`)
|
||
- Deployment ≠ activation: flags seed from `FLAG_*` env vars at boot and can be mutated at runtime without redeploy
|
||
- DB pool refactor to consume config instead of sniffing env itself
|
||
|
||
## Scope OUT
|
||
- No external flag service
|
||
- No per-user segmentation
|
||
- No admin HTTP endpoint for flags yet (first consumer decides shape; store API is runtime-mutable already)
|
||
|
||
## Required vs optional vars
|
||
| Var | Required | Default |
|
||
|---|---|---|
|
||
| DATABASE_URL | yes | — |
|
||
| PORT | no | 3000 (valid: integer 1–65535) |
|
||
| HOST | no | 0.0.0.0 |
|
||
| LOG_LEVEL | no | info |
|
||
| NODE_ENV | no | development (valid: development/test/production) |
|
||
| REDIS_URL | no | undefined |
|
||
| FLAG_<NAME> | no | parsed as true/false |
|
||
|
||
## Acceptance criteria
|
||
1. Given a missing required env var When the app starts Then startup fails with a clear message naming the var.
|
||
2. Given flag off When a code path guarded by the flag runs Then the path is skipped.
|
||
3. Flag state change does not require redeploy (runtime `setEnabled` on the store).
|
||
4. `./scripts/verify.sh` green.
|
||
|
||
## Non-functional
|
||
- No new dependencies: hand-rolled validation is small, explicit and boring.
|
||
- Config loader is a pure function of an env object (testable without touching process.env).
|