5.7 KiB
Code Generation Plan — CMS-U2 gate-and-limiter
Phase 1, base: current branch (master d9cc539 + CMS-U0/U1/U1b). Decisions: D6 (the availability gate blocks only the CMS/admin; public site endpoints stay reachable), D9 (marker attribute, deny-by-default), FR-B1 (429 with Retry-After and ProblemDetails), SLS remarks (route-table style test: the marker only on the three allowed public routes; every other endpoint stays behind the gate). Keep the diffs in AvailabilityMiddleware and the rate-limiter file minimal (R3: both are files the ASF session also changes).
Findings on master that shape the plan
AddCmsRateLimiting(Core/Hosting/ServiceCollectionExtensions.cs):OnRejectedcurrently only logs a security event; no body, noRetry-After. Policies are plainAddFixedWindowLimiter/AddSlidingWindowLimiter(login, refresh, Sentry tunnel, offerings-public).UseRateLimiterruns beforeUseCorsand the module middleware.AvailabilityMiddlewareis registered by the module viaUseMiddlewareafter the implicitUseRouting, socontext.GetEndpoint()is available there (the rate limiter already relies on endpoint metadata the same way).- Master has no
ClientPartitionKeyand noContactmodule yet; the contact routes join the allowlist in CMS-U3. The 3 public routes of the decision are:GET /offerings(exists now),GET /contact-messages/tokenandPOST /contact-messages(CMS-U3).
Behaviour
- 429 response (all existing and future policies): status 429, header
Retry-After: <whole seconds, at least 1>taken from the limiter lease (MetadataName.RetryAfter), falling back to 60 s when the lease does not report one; bodyapplication/problem+json{ type: "https://www.rfc-editor.org/rfc/rfc6585#section-4", title: "Too many requests", status: 429 }. The security event call stays exactly as it is. Policy numbers are not changed. - Marker
[PublicSiteEndpoint](sealed attribute,AttributeTargets.Method, inSlpModularCms.Core.Availability): an endpoint carrying it is let throughAvailabilityMiddlewarebefore the master/local gate is evaluated. Everything else stays deny-by-default, including all admin routes. Existing prefix bypasses (/api/v1/Availability/status, Auth, Setup/status, master, SlaveStatus,/health) and the verified-admin-token bypass are untouched. - Marked now: only
OfferingsController.GetOfferings. (U3 adds the two contact routes.)
Steps
- Step 1 — Core: add
Core/Availability/PublicSiteEndpointAttribute.cs. - Step 2 — Middleware (minimal diff): in
AvailabilityMiddleware.InvokeAsync, right after the prefix-bypass block, add the endpoint-metadata check (4 lines + comment). No other change. - Step 3 — OnRejected (minimal diff): make the lambda
async, keep the security event call, then setRetry-Afterand write the ProblemDetails JSON. - Step 4 — Mark
GetOfferingswith[PublicSiteEndpoint](Offerings module). - Step 5 — Tests:
- Core.Tests:
OnRejected(resolved fromIOptions<RateLimiterOptions>afterAddCmsRateLimiting, called with a fake lease): setsRetry-Afterrounded up from the lease value (e.g. 0.2 s -> 1, 61.5 s -> 62), falls back to 60 without lease metadata, writesapplication/problem+jsonwith status 429, still logs the security event with policy name and path, status code is 429. - Api.Tests (existing real-pipeline test
Sentry_tunnel_rate_limiter_engages_after_the_configured_permit_limit): additionally assert theRetry-Afterheader and the problem+json content type on the 429 (needs the local database; run with the container). - Availability.Tests (middleware): marked endpoint passes while the system is disabled, in maintenance, and with the master gate closed; an unmarked endpoint with the same state still gets 503; a marked endpoint does not bypass anything else (a request without endpoint metadata is still blocked);
/api/v1/Availability/statusstays open. - Availability.Tests (route-table style, SLS request): reflection over the controllers of the referenced modules (Availability, Identity, Master, Offerings; test-only project references): (a) the set of actions carrying the marker is exactly
{ OfferingsController.GetOfferings }(the test names the allowlist so CMS-U3 extends it deliberately); (b) for every other controller action the middleware, given an endpoint with that action's attributes and a closed gate, answers 503 — which covers all admin routes, and the marker is never on anAdminOnly/[Authorize]action. - Offerings.Tests:
GetOfferingshas the marker and[AllowAnonymous]; no other action of the controller has the marker.
- Core.Tests:
- Step 6 — Verification (automatic): build solution; Core, Availability, Offerings, Identity, Master tests; Api.Tests with a temporary MariaDB container (started for the run and removed afterwards, as agreed); report real output.
- Step 7 — Docs/commit:
construction/cms-u2-gate-and-limiter/code/summary.mdincl. handoff note (public routes stay reachable when the CMS is disabled/maintenance; frontend 503 fallback now only applies to admin calls); one commit, no push.
Explicitly NOT touched
Policy numbers and partitioning (no ClientPartitionKey here; that is the ASF branch), ForwardedHeaders, host config, Email, Identity, Master, bypass-prefix list, other controllers' routes, POST admin/status (CMS-U7, phase 2).
Rebase notes (for after the ASF merge)
Expected conflicts: AvailabilityMiddleware.cs and AddCmsRateLimiting; both edits are small and isolated (one block each), so they should merge by hand without redesign. Re-run the marker/route-table tests after the rebase.
Traceability
D6, D9, FR-B1/B2, requirements R3; Security Baseline: deny-by-default, no information leak in the 429 body, no PII.