Files
slp-modular-cms/aidlc-docs/features/contact-forms-module/construction/plans/cms-u2-gate-and-limiter-code-generation-plan.md
T
SluijsensandClaude Sonnet 5.5 a58374abeb Beschikbaarheidspoort laat publieke site-endpoints door en 429 geeft Retry-After met ProblemDetails
Nieuwe marker [PublicSiteEndpoint] (deny-by-default): alleen GET /offerings blijft bereikbaar als het CMS uit staat of in onderhoud is; alle andere acties, adminroutes inbegrepen, blijven 503. OnRejected zet Retry-After en schrijft application/problem+json met alleen type, title en status. Op master zijn de limiet-policies nog globale buckets: de contactroutes mogen pas live na de per-client-partitionering van de ASF-branch.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-10 13:07:18 +01:00

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): OnRejected currently only logs a security event; no body, no Retry-After. Policies are plain AddFixedWindowLimiter/AddSlidingWindowLimiter (login, refresh, Sentry tunnel, offerings-public). UseRateLimiter runs before UseCors and the module middleware.
  • AvailabilityMiddleware is registered by the module via UseMiddleware after the implicit UseRouting, so context.GetEndpoint() is available there (the rate limiter already relies on endpoint metadata the same way).
  • Master has no ClientPartitionKey and no Contact module 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/token and POST /contact-messages (CMS-U3).

Behaviour

  1. 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; body application/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.
  2. Marker [PublicSiteEndpoint] (sealed attribute, AttributeTargets.Method, in SlpModularCms.Core.Availability): an endpoint carrying it is let through AvailabilityMiddleware before 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.
  3. 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 set Retry-After and write the ProblemDetails JSON.
  • Step 4 — Mark GetOfferings with [PublicSiteEndpoint] (Offerings module).
  • Step 5 — Tests:
    • Core.Tests: OnRejected (resolved from IOptions<RateLimiterOptions> after AddCmsRateLimiting, called with a fake lease): sets Retry-After rounded up from the lease value (e.g. 0.2 s -> 1, 61.5 s -> 62), falls back to 60 without lease metadata, writes application/problem+json with 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 the Retry-After header 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/status stays 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 an AdminOnly/[Authorize] action.
    • Offerings.Tests: GetOfferings has the marker and [AllowAnonymous]; no other action of the controller has the marker.
  • 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.md incl. 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.