De status is één resource: de publieke GET en de PUT van de beheerder delen het pad; de PUT geeft de bijgewerkte resource terug. De vrijstelling van de poort geldt nu alleen voor GET en HEAD, zodat de PUT als beheerroute gewoon achter de poort blijft. De oude route verdwijnt zonder alias, dus API en admin-app moeten als één release uit. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
5.2 KiB
5.2 KiB
Code Generation Plan — CMS-U7 availability-restful-status
Phase 2, on the rebased branch. Decision (Bryan via SLS): no /admin segment in API routes; POST /api/v1/Availability/admin/status becomes PUT /api/v1/Availability/status (AdminOnly), same resource as the public GET .../status. The last open admin-segment route (checked in CMS-U0: it was the only one left).
Findings (merged master, all callers checked)
- Backend:
AvailabilityController—[HttpGet("status")] [AllowAnonymous]and[HttpPost("admin/status")] [Authorize(Policy="AdminOnly")]with bodyUpdateStatusRequest { NewStatus, Reason }; answers200(empty),400(unsupported service),409ProblemDetails when the status is master-controlled. - Callers of the old route (repository-wide search for
admin/status, code, docs, CI, configs): only the admin frontend —frontend/src/features/availability/services/useAvailability.ts(mutation),frontend/src/features/availability/mocks/handlers.ts, and two msw handlers infrontend/src/features/settings/pages/SettingsPage.test.tsx. No server-side caller: the master pushes status to slaves withPOST /Master/status, slaves readGET /SlaveStatus, instances poll the master — none of them usesAvailability/admin/status. No proxy (nginx/IIS), deploy script, workflow or README references the old route (the README mentions onlyGET .../status). Historicaidlc-docsentries are history and stay as they are. - Gate:
AvailabilityMiddlewarelets/api/v1/Availability/statusthrough for every method (path-prefix bypass). After the change that would also exemptPUT, an admin route, from the gate for callers without a token (they would get401instead of503) — harmless in effect but contrary to "admin routes are never exempted". The bypass must therefore apply toGET(andHEAD) only. - The frontend
Settingspage changes the status;useAvailabilityStatus(GET) is used on login, sidebar, dashboard.
Behaviour
PUT /api/v1/Availability/status, body{ "newStatus": "Available"|"Maintenance"|"NotAvailable", "reason": string|null }(unchanged), AdminOnly. Success:200with the same JSON asGET /Availability/status(the updated resource), so the UI can refresh its cache from the response.409problem+json when the status is master-controlled (unchanged);400for an invalidnewStatus(framework validation);401/403as for all admin routes.- The old route
POST /Availability/admin/statusis removed, no alias: API and admin app are deployed together (decision of Bryan for the other routes too). Consequence to accept: during a deploy window an old browser bundle calling the old route gets404; the next page load fixes it. AvailabilityMiddleware: theAvailability/statusbypass is limited toGET/HEAD; every other method follows the normal gate (a verified Owner/Administrator passes, expired token =401, others503). Minimal change in that file (ASF-owned file, small diff).- Frontend:
useUpdateAvailabilityusesPUTand updates the cached status from the response; mocks and the two Settings tests change toPUT.
Steps
- Step 1 — Controller:
[HttpPut("status")]replacesadmin/status; returns the updated status object (shared builder with GET); remove the old route. - Step 2 — Middleware: method-aware bypass for
Availability/status(small, isolated diff); comment explains why. - Step 3 — Frontend:
useAvailability.tsmutation (PUT + cache update),availability/mocks/handlers.ts,SettingsPage.test.tsx(2 handlers); no other change. - Step 4 — Docs/contract: regenerate
openapi/slpsoftware.v1.json; updatephase-1-handoff.md; README mention only if it names the route (it does not). - Step 5 — Tests: controller (PUT 200 body equals GET shape, 409 master-controlled, 400 invalid status, GET unchanged and anonymous); route-table test: the only anonymous action on the controller is
GetStatus,UpdateStatusisAdminOnly, no route containsadmin, old route absent; middleware:PUT /api/v1/Availability/statuswithout token is blocked by the gate while the CMS is off (not bypassed),GETstill open, a verified administrator canPUTwhile the CMS is disabled (existing guarantee), expired token on PUT =401; pipeline on the real host: login as administrator,PUTMaintenance →GETshows it, visitors get503on a gated route,PUTback to Available; oldPOST admin/status=404; frontend: Settings page test uses PUT and shows the new status. - Step 6 — Verification (automatic): build; all test projects incl. pipeline tests (temporary MariaDB, removed afterwards);
pnpm lint,npx tsc -b,pnpm test; real output reported. - Step 7 — Commit: one commit; no push.
Explicitly NOT touched
Master/slave endpoints (Master/*, SlaveStatus, CmsInstances/{id}/status), the gate logic for any other route, GET /Availability/status behaviour, polling/circuit-breaker code.
Risk / notes
- Order of deploy with the SLP production release: this unit changes an API route and the admin app together; it must go out as one release (no alias). Do not deploy only one half.
CmsInstances/{id}/status(PUT, master-side, per instance) is unrelated and stays.