fix(surf): close the rate-limit store a router created (quick-261118-lbt)

- MemoryStore.Close stops the sweep goroutine; Attempt keeps working
- Router.Close runs what the router owns (the fallback MemoryStore of
  BuildRouter), never a store published on the app
- BuildRouter closes the router on every error return
- serve closes its router and installCooler's fallback store on exit;
  route:list closes its router
- README and rate-limiting docs describe the ownership
This commit is contained in:
Jakub Zych
2026-11-18 15:41:05 +01:00
parent ea1befdd6c
commit d9e21ad019
8 changed files with 281 additions and 48 deletions

View File

@@ -29,7 +29,7 @@ Use cases:
- Raw groups (`surf.Router.GroupRaw`) for routes that must not be wrapped in house middleware, such as webhooks or file streams: house middleware is refused there, the default body limit is skipped and a panic returns a bare 500.
- Built-in middleware names: `throttle:<bucket>` or `throttle:<max>,<minutes>`, `body.limit:<bytes>`, `cors:<profile>`, `turnstile:open` and `turnstile:closed` (Cloudflare Turnstile through `bouncer.Turnstile`, built from `turnstile.secret`, with the client IP from `surf.ClientIP` and refusals written by a published `bouncer.TurnstileWriter` when there is one), `locale.from-principal`, plus `backend` (the admin guard) when the admin is enabled.
- Named CORS profiles: `cors:<profile>` applies `http.cors_profiles.<profile>` (read by `surf.LoadCORSProfiles`, validated like `http.cors`) to a route or route group. The profile wraps every other layer of the route, whatever its position in the list or the group nesting, so every response carries its headers: guard refusals (401, 403), throttle (429), Turnstile (422, 503), the body limit (413) and recovered panics (500) included. A handler's own `Vary` is merged with the profile's `Vary: Origin`, not replacing it. surf registers an `OPTIONS` route for each such path that answers the preflight from the profile, since ServeMux would answer it with 405 before the middleware runs. An unknown profile, two profiles on one path and a profiled path that `http.cors.paths` also matches fail boot.
- Fixed-window rate limiting (`surf.FixedWindowLimiter`): named buckets from plugins that implement `surf.BucketProvider`, or inline limits keyed by the signed-in user, or by client IP for guests. Rejected requests get a 429 with `Retry-After` and `X-RateLimit-*` headers. The in-process `surf.MemoryStore` sits behind the `surf.Store` interface; `surf.BuildRouter` uses a `surf.Store` published on the app instead when there is one, which is how `serve` shares counters across instances through [cooler](../cooler/README.md)'s Redis store (`http.rate_limit.store: redis`).
- Fixed-window rate limiting (`surf.FixedWindowLimiter`): named buckets from plugins that implement `surf.BucketProvider`, or inline limits keyed by the signed-in user, or by client IP for guests. Rejected requests get a 429 with `Retry-After` and `X-RateLimit-*` headers. The in-process `surf.MemoryStore` sits behind the `surf.Store` interface; `surf.BuildRouter` uses a `surf.Store` published on the app instead when there is one, which is how `serve` shares counters across instances through [cooler](../cooler/README.md)'s Redis store (`http.rate_limit.store: redis`). When nothing is published, the router creates the fallback `surf.MemoryStore` itself, owns it and stops its background sweep on `surf.Router.Close`; a published store is never closed by the router.
- Client IP resolution for limiter keys (`surf.ClientIP`) that only trusts `X-Forwarded-For` hops when the direct peer is inside a configured trusted proxy range (`surf.TrustedProxies`).
- Every non-raw route runs inside JSON panic recovery (an opaque 500 via [wire](../wire/README.md)), gets the request locale from a published `surf.LocaleResolver` when one exists or from the `Accept-Language` header otherwise (see [towel](../towel/README.md)), and a request body cap. Responses are buffered until the handler returns, so a panic never leaves a half-written body.
- Branded error pages for browsers: a top-level browser navigation (`Sec-Fetch-Mode: navigate` when the header is sent, otherwise GET or HEAD; no `X-Requested-With`; an `Accept` header that names `text/html` or `application/xhtml+xml` with a higher q than any JSON type; not `/api`, `/api/...`, `/_<name>/...` or the admin prefix) that hits a framework-generated error gets a self-contained SummerCMS HTML page with the same status. Covered: unmatched routes (404), wrong methods (405, `Allow` kept), failed `Where`/`WhereIn` constraints and overlap-family misses (404, 405), the uploads route while its bucket or database is unpublished (404), and recovered panics in normal and raw groups (500; the panic value is never shown). Every other request keeps the exact stdlib or [wire](../wire/README.md) body. Method, path and `X-Request-Id` appear on the page only when `app.debug` is true or outside the production environment. The page sends `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, `Vary: Accept, Sec-Fetch-Mode, X-Requested-With` and a `Content-Security-Policy` that allows no script. An application or plugin replaces the page by publishing a `surf.ErrorPageRenderer`; `http.error_pages.enabled: false` turns the feature off. Handlers' own error bodies and middleware refusals are not touched.
@@ -131,6 +131,7 @@ The generated application `main` wires surf in with `surf.ServeCommand` and `sur
| `surf.Router.Handler` | Returns the compiled middleware chain of one registered route by method and pattern, for an in-process dispatch that must run the same guards, throttles, body limit, locale and recovery as an HTTP request. False for an unknown route or before `surf.BuildRouter` compiled the routes. |
| `surf.Router.MountStream` | Registers one streaming route (raw, unbuffered, `http.Flusher` passed through) under the bound plugin with the given middleware names; a route another plugin registered for the method and path fails naming it. |
| `surf.MCPBuildTag` | `summercms_mcp`: the build tag that links the MCP module; without it `mcp.enabled` true fails boot. |
| `surf.Router.Close` | Releases what the router created itself (the fallback `surf.MemoryStore` of `surf.BuildRouter`), never a `surf.Store` published on the app; nil-safe and idempotent, and the compiled handler keeps serving. `surf.BuildRouter` closes the router on every error return; `serve` and `route:list` close theirs on exit. |
| `surf.Router.AdminPrefix` | The admin mount path and true when `surf.BuildRouter` mounted the cabana admin; false when no plugin registers an admin controller. |
| `surf.RouteInfo` | Method, pattern, owning plugin, middleware and raw flag of one route. |
| `surf.Use` | Builds a middleware name list for a group. |
@@ -140,6 +141,7 @@ The generated application `main` wires surf in with `surf.ServeCommand` and `sur
| `surf.BucketProvider` | Implemented by plugins that declare named buckets. |
| `surf.FixedWindowLimiter` | The rate limiter behind the `throttle` middleware; `surf.NewFixedWindowLimiter` creates one. |
| `surf.Store` | Atomic fixed-window admission; `surf.NewMemoryStore` is the in-process implementation. |
| `surf.MemoryStore` | The in-process `surf.Store`. `surf.MemoryStore.Close` stops its background sweep (nil-safe, idempotent); `surf.MemoryStore.Attempt` keeps counting after Close. |
| `surf.ClientIP` | Resolves the client IP, honouring trusted proxies. |
| `surf.TrustedProxies` | Parses `http.trusted_proxies` into CIDR prefixes. |
| `surf.CORSConfig` | CORS settings; `surf.LoadCORSConfig` reads them from config. |
@@ -218,4 +220,4 @@ The `serve` command also opens the database through [lagoon](../lagoon/README.md
go test ./modules/surf/...
```
The tests use `net/http/httptest` and in-memory stores. `TestRateLimitAcrossInstancesSmoke` starts a Redis container and `TestServeLifecycle` a Postgres container (it runs `serve`, sends one request and stops it) through testcontainers-go; both need Docker, and `go test -short ./modules/surf/...` skips them. `TestServeSummarySmoke` and `TestShutdownReportSmoke` check the summary and report builders without a database.
The tests use `net/http/httptest` and in-memory stores. `TestRateLimitAcrossInstancesSmoke` starts a Redis container and `TestServeLifecycle` a Postgres container (it runs `serve`, sends one request and stops it) through testcontainers-go; both need Docker, and `go test -short ./modules/surf/...` skips them. `TestServeSummarySmoke` and `TestShutdownReportSmoke` check the summary and report builders without a database. The close tests (`close_test.go`) check that `surf.MemoryStore.Close` stops the sweep, that `surf.Router.Close` stops the fallback store but never a published one, and that closing 20 routers brings the goroutine count back to its baseline.