maintenance_mode is configurable and reported by the healthcheck but does not affect any request #71

New Issue

2026-08-09T03:45:38+02:00

clawbot commented

2026-08-09 03:45:38 +02:00

Verified against main at 61f42e6.

maintenance_mode is a real config key (config.example.yml:6, internal/config/config.go:38,103), it is reported in the healthcheck JSON (internal/healthcheck/healthcheck.go:79), and Server.MaintenanceMode() exists (internal/server/server.go:148-151).

Server.MaintenanceMode() has no callers — grep across internal/ and cmd/ finds only the definition and test references. No route, middleware, or handler consults it.

So turning on maintenance mode changes exactly one thing: the healthcheck JSON says true. Every request is still served normally. An operator who sets it believing traffic will be drained gets no such behavior, silently — the failure mode is that they find out during the maintenance they were trying to perform.

Definition of done

When maintenance_mode is true, image-serving routes return 503 Service Unavailable with a Retry-After header and the standard JSON error body used elsewhere.
The healthcheck endpoint keeps responding (it must stay reachable to report the state), and /metrics likewise — decide deliberately and state the choice in the PR.
Decide whether the auth UI (/, /generate) stays available during maintenance; recommend yes, so an operator can still work.
Implemented as middleware in internal/server/routes.go rather than a check sprinkled through handlers.
Failing tests first: with the flag on, an image request returns 503 with Retry-After, and the healthcheck still returns 200 reporting maintenance: true.
make check green.

Alternative

If maintenance mode is only ever meant as a signal for an external load balancer to drain, then the code is already correct and the gap is documentation. In that case: document it in README.md and config.example.yml as advisory-only, and remove the unused Server.MaintenanceMode() accessor. Pick one — the current state (a real-looking accessor nobody calls) reads as an unfinished feature.

Verified against `main` at `61f42e6`. `maintenance_mode` is a real config key (`config.example.yml:6`, `internal/config/config.go:38,103`), it is reported in the healthcheck JSON (`internal/healthcheck/healthcheck.go:79`), and `Server.MaintenanceMode()` exists (`internal/server/server.go:148-151`). `Server.MaintenanceMode()` has **no callers** — grep across `internal/` and `cmd/` finds only the definition and test references. No route, middleware, or handler consults it. So turning on maintenance mode changes exactly one thing: the healthcheck JSON says `true`. Every request is still served normally. An operator who sets it believing traffic will be drained gets no such behavior, silently — the failure mode is that they find out during the maintenance they were trying to perform. ## Definition of done 1. When `maintenance_mode` is true, image-serving routes return `503 Service Unavailable` with a `Retry-After` header and the standard JSON error body used elsewhere. 2. The healthcheck endpoint keeps responding (it must stay reachable to report the state), and `/metrics` likewise — decide deliberately and state the choice in the PR. 3. Decide whether the auth UI (`/`, `/generate`) stays available during maintenance; recommend yes, so an operator can still work. 4. Implemented as middleware in `internal/server/routes.go` rather than a check sprinkled through handlers. 5. Failing tests first: with the flag on, an image request returns 503 with `Retry-After`, and the healthcheck still returns 200 reporting `maintenance: true`. 6. `make check` green. ## Alternative If maintenance mode is only ever meant as a signal for an external load balancer to drain, then the code is already correct and the gap is documentation. In that case: document it in `README.md` and `config.example.yml` as advisory-only, and remove the unused `Server.MaintenanceMode()` accessor. Pick one — the current state (a real-looking accessor nobody calls) reads as an unfinished feature.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:45:38 +02:00

clawbot referenced this issue

2026-08-09 16:10:39 +02:00

Tracking: 1.0.0 sequencing and critical path #103

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/pixa#71