Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u7-availability-restful-status-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 728fc08db8 PUT /availability/status vervangt POST /availability/admin/status; de poort sluit alleen het lezen van de status vrij
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>
2026-11-10 13:39:40 +01:00

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 body UpdateStatusRequest { NewStatus, Reason }; answers 200 (empty), 400 (unsupported service), 409 ProblemDetails 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 in frontend/src/features/settings/pages/SettingsPage.test.tsx. No server-side caller: the master pushes status to slaves with POST /Master/status, slaves read GET /SlaveStatus, instances poll the master — none of them uses Availability/admin/status. No proxy (nginx/IIS), deploy script, workflow or README references the old route (the README mentions only GET .../status). Historic aidlc-docs entries are history and stay as they are.
  • Gate: AvailabilityMiddleware lets /api/v1/Availability/status through for every method (path-prefix bypass). After the change that would also exempt PUT, an admin route, from the gate for callers without a token (they would get 401 instead of 503) — harmless in effect but contrary to "admin routes are never exempted". The bypass must therefore apply to GET (and HEAD) only.
  • The frontend Settings page changes the status; useAvailabilityStatus (GET) is used on login, sidebar, dashboard.

Behaviour

  1. PUT /api/v1/Availability/status, body { "newStatus": "Available"|"Maintenance"|"NotAvailable", "reason": string|null } (unchanged), AdminOnly. Success: 200 with the same JSON as GET /Availability/status (the updated resource), so the UI can refresh its cache from the response. 409 problem+json when the status is master-controlled (unchanged); 400 for an invalid newStatus (framework validation); 401/403 as for all admin routes.
  2. The old route POST /Availability/admin/status is 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 gets 404; the next page load fixes it.
  3. AvailabilityMiddleware: the Availability/status bypass is limited to GET/HEAD; every other method follows the normal gate (a verified Owner/Administrator passes, expired token = 401, others 503). Minimal change in that file (ASF-owned file, small diff).
  4. Frontend: useUpdateAvailability uses PUT and updates the cached status from the response; mocks and the two Settings tests change to PUT.

Steps

  • Step 1 — Controller: [HttpPut("status")] replaces admin/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.ts mutation (PUT + cache update), availability/mocks/handlers.ts, SettingsPage.test.tsx (2 handlers); no other change.
  • Step 4 — Docs/contract: regenerate openapi/slpsoftware.v1.json; update phase-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, UpdateStatus is AdminOnly, no route contains admin, old route absent; middleware: PUT /api/v1/Availability/status without token is blocked by the gate while the CMS is off (not bypassed), GET still open, a verified administrator can PUT while the CMS is disabled (existing guarantee), expired token on PUT = 401; pipeline on the real host: login as administrator, PUT Maintenance → GET shows it, visitors get 503 on a gated route, PUT back to Available; old POST 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.