Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u7-availability-restful-status-code-generation-plan.md
T

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.