3.0 KiB
3.0 KiB
Contact feature - prerequisites (read before building)
Status: not started. Written 2026-11-09 so a new session finds what was decided in conversations. Not part of the identity-email-notifications release.
1. Decision (Bryan): availability statuses block the CMS only, never the public site
- Both the master status and the instance's own status (disabled / maintenance) block CMS actions only: changing data or settings, and the admin.
- Public routes must never answer 503: public offerings, contact token, contact submit,
System/capabilitiesfor guests,Availability/status. - The maintenance status stays queryable (open
GET /api/v1/Availability/status), so the front-end decides what to do with it. - A status that also switches the public site off may come later. Not now.
- Admin routes are never exempted.
2. Current gate and proposed change
- Now (
AvailabilityMiddleware): everything under/api/is gated except a bypass list (Availability/status,Auth/,Setup/status,master/,SlaveStatus,/health). A verified Owner/Administrator token passes. Master status is checked first, then the own status; both answer 503. Since85d0f6aan expired token on a blocked route answers 401 so the app refreshes its session. - Proposed: keep deny-by-default and mark public routes explicitly as open. Preferred: a marker attribute (e.g.
[PublicSiteEndpoint], defined in Core) read from endpoint metadata - needs the middleware to run after routing; fallback: a second prefix list next to the bypass list. A forgotten or new admin route then stays closed. - Tests affected (Availability.Tests, roughly 6-10):
AvailabilityGateScopeTests(move public paths from "still blocked" to "open", add a negative check that admin routes stay blocked),AvailabilityMiddlewareMasterGateTestsandAvailabilityMiddlewareTests(public route stays 200 under master-down, Disabled and Maintenance). With the attribute approach add a test that lists all public actions so none is added silently. - No migration. Behaviour change: public offerings no longer 503 on a disabled CMS.
3. Evidence that this is needed
GET /api/v1/System/capabilities returns 503 to a guest while the CMS is off (ASF test journal, 2026-11-09 ~23:33 local; the gate logs "Request blocked by master gate"). The login page reads it, so a guest on a disabled CMS sees failed requests.
4. Deferred items (decide with Bryan, not part of the release)
- Own rate-limit policy for
Setup/status(e.g. 60/min): it now shares therefreshpolicy (20 per 60 s per client IP), and one admin page load costs two permits. - Judge the admin token only when a request would really be blocked: today every gated API call evaluates it, so any normal User call logs a "bypass rejected" security event (log noise).
- A visible error state with a "Reload" button as a safety net for the admin app, and a fetch timeout in the API client (a hanging request currently means an endless spinner; start-up retries can also wait up to ~45 s on a 429 with Retry-After).