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.