Maintenance mode toggles but never actually blocks traffic

Nobody has started this yet — be first.

Business impact

A planned maintenance window (upstream migration, a scheduled Redis failover, a config change that needs a moment of "do not send anything through yet") currently has no clean way to pause traffic at the gateway without actually tearing down routes one by one or stopping the process. A single, fast, reversible kill switch is the kind of thing that is much better to have before the first time it is needed under pressure than to improvise in the moment.

Problem

POST /admin/maintenance (body {"enabled": true/false}) and GET /admin/maintenance both work today -- they really do flip app.state.maintenance_mode and reflect it back. But nothing in the actual proxy request pipeline (app/routers/proxy.py::proxy_endpoint) ever reads that flag.

Current behavior

Turning maintenance mode "on" via the admin endpoint changes app.state.maintenance_mode to True, but a proxied request sent immediately afterward still goes through routing, auth, rate limiting, and the upstream call exactly as if maintenance mode were off.

Expected behavior

While app.state.maintenance_mode is True, every proxied request (everything the catch-all proxy_endpoint handles) is rejected with 503 immediately -- before route matching, auth, rate limiting, or any upstream call. /healthz, , , and every endpoint are unaffected.

Steps to reproduce

POST /admin/maintenance with {"enabled": true}.
Send any proxied request, e.g. curl localhost:8080/echo/hello.
Observe: the request is proxied normally (200), not rejected with 503.

Why this matters

proxy_endpoint already has a Request parameter it can read request.app.state.maintenance_mode from directly -- the flag exists and is correctly toggled, the pipeline just never consults it. The check needs to run before any of the other pipeline stages do any work at all, and it must live only inside the catch-all proxy router, never in app/main.py's router registration, so the other admin/health endpoints stay reachable regardless.

Suggested approach

Think about exactly where in the existing pipeline (match route -> check method -> auth -> rate limit -> breaker -> forward) this check belongs, given that it should reject a request before any of the other stages do any work at all.

Acceptance criteria

With maintenance mode off (the default), proxied requests behave exactly as before
With maintenance mode on, every proxied request gets 503 immediately, even for a route that would otherwise 401/429/503-from-breaker
/healthz, /readyz, and every /admin/* endpoint keep working normally while maintenance mode is on
Turning maintenance mode back off immediately restores normal proxying, no restart needed

Verification

pytest practice_tickets/tests/test_ticket_08_maintenance_mode_not_enforced.py -v

Hints (0/2)

Try it without hints first — the reading is the exercise.

Working on this ticket

Work on a branch named for the ticket — that's what you'll submit.

Branch off your fork

$git checkout -b feat/maintenance-mode-not-enforced

Fix it and commit

Meet every acceptance criterion, and add a test that would have caught this.

Push the branch

$git push -u origin feat/maintenance-mode-not-enforced

Submit it below

Paste your fork URL and the branch name, with a short write-up of the root cause.

Submit your fix

Questions

Stuck on something?

Ask about anything unclear in the ticket — the maintainer and anyone who has solved it can answer. Please don't post full solutions.

No questions yet. If something in this ticket reads ambiguously, you are probably not the only one — ask.

The project

Dynamic API Gateway & Reverse Proxy

A FastAPI reverse proxy that streams every request and response without ever buffering a body in full, with hot-reloadable routing, per-route auth, Redis token-bucket rate limiting, and a per-upstream circuit breaker.

Fork on GitHub

Download

Setup

Dynamic API Gateway & Reverse Proxy

git clone <your-fork>
cd FastAPIDevTraining/gateway_proxy
cp .env.example .env   # adjust GATEWAY_ADMIN_TOKEN etc. if you like
docker compose up --build   # Redis + the gateway (uvicorn --reload) + 2 demo upstreams

The gateway is reachable at . Two demo upstreams come up alongside it — (low-latency JSON echo at , plus for the streaming-passthrough demo) and (, , for timeout and circuit-breaker demos) — and wires five example routes against them, one per feature. Verify the stack with (liveness only) and (pings Redis, which every rate-limited route depends on). Every endpoint (route CRUD, reload, persist, breaker snapshot) requires .