diff --git a/docs/plugins/testing.md b/docs/plugins/testing.md index 4df1e09b..ce1e0705 100644 --- a/docs/plugins/testing.md +++ b/docs/plugins/testing.md @@ -27,7 +27,9 @@ In an application with local plugins in a `go.work` workspace, run the tests of ## Unit tests without a database -Most plugin code runs without a database. Build a container with `backpack.New`, call your plugin's Register and Boot, and assert on what it published. Drive HTTP handlers with `net/http/httptest`: `surf.Assemble` builds the same handler `serve` uses, so a test can send requests to your routes without listening on a port. Call console commands in-process with `bonfire.Call`. +Most plugin code runs without a database. Build a container with `backpack.New`, call your plugin's Register and Boot, and assert on what it published. Drive HTTP handlers with `net/http/httptest`: `surf.AssembleRouter` builds the same handler `serve` uses, together with its route table and admin prefix from one build, so a test can send requests to your routes without listening on a port; `defer r.Close()` on the returned router so its rate-limit store stops. Call console commands in-process with `bonfire.Call`. + +Full-boot tests may call `t.Parallel()`: `party.Activate` gives each application its own plugin instances, so two applications booted in one test binary do not share plugin state, provided your plugin keeps its per-application state on its struct and not in package variables. Column-encryption keys are the exception: they are process-wide, and the last `lagoon.PublishEncryptionKeys` wins. ## Database tests diff --git a/docs/services/routing.md b/docs/services/routing.md index 4d22eff5..cf3a9f33 100644 --- a/docs/services/routing.md +++ b/docs/services/routing.md @@ -255,6 +255,32 @@ do("POST", "/api/blog/posts/7/comments", true) // POST /api/blog/posts/7/comments 429 {"message":"Too Many Attempts."} ``` +A test that needs the route table as well as the handler uses `surf.AssembleRouter`, which builds once and returns both. Building twice would fail with the MCP module enabled, because it publishes its endpoint once per application. The test owns the router and closes it with `surf.Router.Close`, which stops the router's in-process rate-limit store (and the MCP endpoint's background work); `surf.Assemble` drops the router, so its store is never stopped: + +```go src=modules/surf/example_test.go#ExampleAssembleRouter +app := backpack.New(nil) +plugin := &BlogPlugin{} +if err := plugin.Register(app); err != nil { // the runtime calls Register + fmt.Println(err) + return +} +// One build: the route table and the handler share one router. +r, h, err := surf.AssembleRouter(app, []party.Plugin{plugin}) +if err != nil { + fmt.Println(err) + return +} +defer r.Close() // stops the router's in-process rate-limit store +fmt.Println(len(r.Routes()), "routes") + +rec := httptest.NewRecorder() +h.ServeHTTP(rec, httptest.NewRequest("GET", "/api/blog/posts/7", nil)) +fmt.Println(rec.Code, strings.TrimSpace(rec.Body.String())) +// Output: +// 4 routes +// 200 {"id":7} +``` + `route:list` builds the router the way `serve` does, without opening the database or listening, and prints every route with its plugin and middleware: ```sh diff --git a/modules/pier/README.md b/modules/pier/README.md index f04c8d53..3a723f6b 100644 --- a/modules/pier/README.md +++ b/modules/pier/README.md @@ -99,7 +99,8 @@ An MCP client then connects to `https://example.com/mcp` with an OAuth access to | `pier.PluginID` | `summercms.pier`, the pseudo-plugin id of pier's routes in the route table. | | `pier.Config` | The loaded `mcp.*` configuration (see Configuration). | | `pier.LoadConfig` | Reads and validates the `mcp.*` keys; an invalid value fails with an error naming the key. | -| `pier.Pier` | The mounted endpoint; `pier.Pier.Handler` is its handler (Origin check, body limit, bearer verification, session router), `pier.Pier.Config` the loaded configuration and `pier.Pier.ToolNames` the exposed tool names. | +| `pier.Pier` | The mounted endpoint; `pier.Pier.Handler` is its handler (Origin check, body limit, bearer verification, session router), `pier.Pier.Config` the loaded configuration and `pier.Pier.ToolNames` the exposed tool names; `pier.Pier.Close` stops its background work. | +| `pier.Pier.Close` | Stops the session reaper and the Redis store warm-up `pier.Mount` started; connected sessions are not ended (serve's HTTP drain handles them). The surf router that mounted the endpoint calls it from `surf.Router.Close`. Nil-safe and idempotent. | | `pier.Identity` | Who one request acts as: `Frontend` and `Backend` subjects (`pact.MCPSubject`), `Scopes`, the session `Binding`, `ExpiresAt` and `TokenKind` (`pier.TokenKindOAuth` or `pier.TokenKindPersonal`). | | `pier.OAuthTokenPrefix` | `oas_at_`, the prefix of the tokens the published `pact.MCPTokenVerifier` verifies. | | `pier.BackendGuard` | `backend`, the name of the built-in guard provider for routes behind cabana's backend guard. | diff --git a/modules/pier/pier.go b/modules/pier/pier.go index bf368fbe..93705f82 100644 --- a/modules/pier/pier.go +++ b/modules/pier/pier.go @@ -61,12 +61,25 @@ type Pier struct { instance string // stopReap ends the session reaper (and a Redis store's warm-up) Mount - // starts. backpack.App has no shutdown hook yet, so in production the - // reaper runs for the life of the process, like the store subscription; - // when backpack gains one, Mount registers stopReap there. + // starts; Close calls it. The surf router that mounted the endpoint + // calls Close when it is closed. backpack.App still has no shutdown + // hook, so without a router Close the reaper runs for the life of the + // process, like the store subscription. stopReap context.CancelFunc } +// Close stops the session reaper and the Redis store warm-up Mount started. +// It does not end connected sessions; serve's HTTP drain handles those. +// Close is safe on a nil Pier and when called more than once; it always +// returns nil. +func (p *Pier) Close() error { + if p == nil || p.stopReap == nil { + return nil + } + p.stopReap() + return nil +} + // Mount reads the mcp.* keys and, when mcp.enabled is true, compiles every // plugin's MCP declaration against the host's route table, registers the // built-in backend guard provider, builds the session store and mounts diff --git a/modules/surf/README.md b/modules/surf/README.md index e04e71b0..80615d8f 100644 --- a/modules/surf/README.md +++ b/modules/surf/README.md @@ -115,14 +115,15 @@ func addComment(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.Sta Routes ported from a `routes.php` sometimes overlap: `GET /shelves/items/{id}` with `id` numeric and `GET /shelves/{shelfId}/follow` with `shelfId` numeric both match `/shelves/items/follow` as patterns, so ServeMux alone would refuse to register them. surf registers such routes as an overlap family and tries them in registration order, checking literal segments and `Where` constraints, so declare them in the same order as the PHP file. A request no member matches gets the bare 404. Overlapping routes must use literal segments and single-segment `{name}` wildcards; two routes of one method with the same shape, a `{name...}` wildcard in a family, or a more general route that would take a member's requests still fail at boot. `surf.Router.Routes` and `route:list` keep listing every route on its own. -The generated application `main` wires surf in with `surf.ServeCommand` and `surf.RouteListCommand`; tests can call `surf.Assemble(app, plugins)` and drive the returned handler with `net/http/httptest`. +The generated application `main` wires surf in with `surf.ServeCommand` and `surf.RouteListCommand`; tests call `surf.AssembleRouter(app, plugins)`, `defer r.Close()` on the returned router, read its route table and drive the returned handler with `net/http/httptest`. ## API reference | Identifier | Description | |------------|-------------| | `surf.BuildRouter` | Registers built-in and plugin middleware, buckets, routes and the admin, and validates every route without compiling. | -| `surf.Assemble` | `surf.BuildRouter` plus compilation into the final `http.Handler`. | +| `surf.Assemble` | `surf.BuildRouter` plus compilation into the final `http.Handler`; implemented on `surf.AssembleRouter`. The router is not returned, so it cannot be closed and its fallback store keeps sweeping. | +| `surf.AssembleRouter` | Builds once and returns the router (route table, admin prefix, `surf.Router.Handler`) and the compiled handler `serve` uses; the MCP endpoint publishes once per app, so a caller needing both must not build twice. The caller closes the router with `surf.Router.Close`; on an error it is already closed. | | `surf.Router` | The route builder; implements `pact.Router`. `surf.New` creates an empty one. | | `surf.Group` | A prefixed route collection with inherited middleware. | | `surf.Router.RegisterMiddleware` | Stores a named middleware; duplicates fail. | @@ -131,7 +132,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.Close` | Releases what the router created itself (the fallback `surf.MemoryStore` of `surf.BuildRouter`, and with MCP the `pier.Pier` endpoint it mounted, through `pier.Pier.Close`), never a `surf.Store` published on the app; nil-safe and idempotent, and the compiled handler keeps serving. `surf.BuildRouter` and `surf.AssembleRouter` close 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. | diff --git a/modules/surf/assemble_router_mcp_test.go b/modules/surf/assemble_router_mcp_test.go new file mode 100644 index 00000000..d76ad791 --- /dev/null +++ b/modules/surf/assemble_router_mcp_test.go @@ -0,0 +1,88 @@ +//go:build summercms_mcp + +package surf + +import ( + "net/http" + "runtime" + "testing" + "time" + + "git.golem15.com/golem15/summercms/modules/backpack" + "git.golem15.com/golem15/summercms/modules/party" + "git.golem15.com/golem15/summercms/modules/pier" +) + +func mcpApp(t *testing.T) *backpack.App { + t.Helper() + return transportApp(t, "development", map[string]string{ + "http.yaml": transportBodyLimits, + "app.yaml": "name: mount-test\nurl: http://acme.test\n", + "mcp.yaml": "enabled: true\n", + }) +} + +// TestAssembleRouterMCPOneBuild: pier publishes its endpoint once per app, +// so one AssembleRouter call must give the route table, the admin prefix and +// the handler of an mcp.enabled app. +func TestAssembleRouterMCPOneBuild(t *testing.T) { + app := mcpApp(t) + r, h, err := AssembleRouter(app, []party.Plugin{dispatchPlugin{}}) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = r.Close() }) + if h == nil { + t.Fatal("nil handler") + } + methods := map[string]bool{} + for _, ri := range r.Routes() { + if ri.Pattern == "/mcp" { + methods[ri.Method] = true + } + } + for _, m := range []string{http.MethodPost, http.MethodGet, http.MethodDelete} { + if !methods[m] { + t.Fatalf("%s /mcp missing from the route table", m) + } + } + _, _ = r.AdminPrefix() + if p, ok := app.Lookup[*pier.Pier](); !ok || p == nil { + t.Fatal("*pier.Pier not published") + } +} + +// TestRouterCloseStopsPierReaper: the router that mounted the MCP endpoint +// stops its session reaper on Close. +func TestRouterCloseStopsPierReaper(t *testing.T) { + baseline := runtime.NumGoroutine() + routers := make([]*Router, 0, 5) + for range 5 { + r, _, err := AssembleRouter(mcpApp(t), []party.Plugin{dispatchPlugin{}}) + if err != nil { + t.Fatal(err) + } + routers = append(routers, r) + } + if n := runtime.NumGoroutine(); n < baseline+5 { + t.Fatalf("5 MCP routers raised goroutines from %d to %d, want at least +5", baseline, n) + } + for _, r := range routers { + if err := r.Close(); err != nil { + t.Fatal(err) + } + } + if n := waitGoroutines(baseline+2, 2*time.Second); n > baseline+2 { + t.Fatalf("goroutines = %d after closing 5 MCP routers, want at most %d", n, baseline+2) + } + if err := (*pier.Pier)(nil).Close(); err != nil { + t.Fatalf("nil Pier Close: %v", err) + } + p, ok := routers[0].app.Lookup[*pier.Pier]() + if !ok { + t.Fatal("*pier.Pier not published") + } + if err := p.Close(); err != nil { + t.Fatalf("second Close: %v", err) + } +} diff --git a/modules/surf/assemble_router_test.go b/modules/surf/assemble_router_test.go new file mode 100644 index 00000000..a9597174 --- /dev/null +++ b/modules/surf/assemble_router_test.go @@ -0,0 +1,60 @@ +package surf + +import ( + "net/http" + "net/http/httptest" + "runtime" + "testing" + "time" + + "git.golem15.com/golem15/summercms/modules/backpack" + "git.golem15.com/golem15/summercms/modules/party" +) + +// TestAssembleRouterOneBuild: the router and the handler AssembleRouter +// returns come from one build, so they share one limiter and one store, and +// a failed build leaves no sweep goroutine behind. +func TestAssembleRouterOneBuild(t *testing.T) { + p := assemblePlugin{id: "golem15.demo", path: "/ping", use: []string{"throttle:2,1"}} + r, h, err := AssembleRouter(backpack.New(nil), []party.Plugin{p}) + if err != nil { + t.Fatal(err) + } + found := false + for _, ri := range r.Routes() { + if ri.Method == http.MethodGet && ri.Pattern == "/api/ping" { + found = true + } + } + if !found { + t.Fatalf("GET /api/ping not in %+v", r.Routes()) + } + for i, want := range []int{http.StatusOK, http.StatusOK, http.StatusTooManyRequests} { + rec := httptest.NewRecorder() + h.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/ping", nil)) + if rec.Code != want { + t.Fatalf("request %d = %d, want %d", i+1, rec.Code, want) + } + } + ms := routerStore(t, r) + if err := r.Close(); err != nil { + t.Fatal(err) + } + if !waitClosed(ms.done, 2*time.Second) { + t.Fatal("Router.Close left the store sweeping") + } + + t.Run("a failed build closes its store", func(t *testing.T) { + bad := assemblePlugin{id: "golem15.demo", use: []string{"jwt.auth"}} + baseline := runtime.NumGoroutine() + for range 10 { + r, h, err := AssembleRouter(backpack.New(nil), []party.Plugin{bad}) + if err == nil || r != nil || h != nil { + t.Fatalf("AssembleRouter = %v, %v, %v; want nil, nil and an error", r, h, err) + } + } + if n := waitGoroutines(baseline+2, 2*time.Second); n > baseline+2 { + t.Fatalf("goroutines = %d after 10 failed builds, want at most %d", n, baseline+2) + } + }) +} diff --git a/modules/surf/example_test.go b/modules/surf/example_test.go index be3e3816..6d381a70 100644 --- a/modules/surf/example_test.go +++ b/modules/surf/example_test.go @@ -188,6 +188,30 @@ func ExampleBuildRouter() { // POST /api/blog/posts/{id}/comments acme.blog [throttle:60,1 acme.auth throttle:blog.comments body.limit:65536] } +func ExampleAssembleRouter() { + app := backpack.New(nil) + plugin := &BlogPlugin{} + if err := plugin.Register(app); err != nil { // the runtime calls Register + fmt.Println(err) + return + } + // One build: the route table and the handler share one router. + r, h, err := surf.AssembleRouter(app, []party.Plugin{plugin}) + if err != nil { + fmt.Println(err) + return + } + defer r.Close() // stops the router's in-process rate-limit store + fmt.Println(len(r.Routes()), "routes") + + rec := httptest.NewRecorder() + h.ServeHTTP(rec, httptest.NewRequest("GET", "/api/blog/posts/7", nil)) + fmt.Println(rec.Code, strings.TrimSpace(rec.Body.String())) + // Output: + // 4 routes + // 200 {"id":7} +} + func ExampleClientIP() { cfg, err := compass.Open(compass.Options{Dir: "config", Env: "development", Environ: []string{}}) if err != nil { diff --git a/modules/surf/pier_on.go b/modules/surf/pier_on.go index 204e602d..e3d25366 100644 --- a/modules/surf/pier_on.go +++ b/modules/surf/pier_on.go @@ -20,7 +20,15 @@ import ( // handler lookup and the two mount kinds without pier importing surf. func init() { mountPier = func(r *Router, app *backpack.App, plugins []party.Plugin) error { - return pier.Mount(pierHost{r: r, trusted: TrustedProxies(app.Config)}, app, plugins) + if err := pier.Mount(pierHost{r: r, trusted: TrustedProxies(app.Config)}, app, plugins); err != nil { + return err + } + // The router mounted the endpoint, so its Close stops the + // endpoint's background work (also on a later BuildRouter error). + if p, ok := app.Lookup[*pier.Pier](); ok && p != nil { + r.own(p.Close) + } + return nil } } diff --git a/modules/surf/router.go b/modules/surf/router.go index ffb7cd01..819df014 100644 --- a/modules/surf/router.go +++ b/modules/surf/router.go @@ -568,12 +568,34 @@ func (r *Router) wrap(rt route) (http.Handler, error) { } // Assemble registers plugin middleware and routes, then compiles ServeMux. +// It is AssembleRouter without the router, so the router's fallback +// MemoryStore is never closed; code that builds many routers (tests) uses +// AssembleRouter and Router.Close instead. func Assemble(app *backpack.App, plugins []party.Plugin) (http.Handler, error) { - r, err := BuildRouter(app, plugins) + _, h, err := AssembleRouter(app, plugins) if err != nil { return nil, err } - return r.compile() + return h, nil +} + +// AssembleRouter builds the router once and compiles it: one build gives +// both the route table (Routes, AdminPrefix, Handler) and the handler serve +// uses. The MCP module publishes its endpoint once per app, so a caller that +// needs both must not build twice. The caller owns the router and calls +// Router.Close when the app stops; on an error nothing is returned and the +// router is already closed. +func AssembleRouter(app *backpack.App, plugins []party.Plugin) (*Router, http.Handler, error) { + r, err := BuildRouter(app, plugins) + if err != nil { + return nil, nil, err + } + h, err := r.compile() + if err != nil { + _ = r.Close() + return nil, nil, err + } + return r, h, nil } // BuildRouter registers plugin middleware and routes without compiling ServeMux, diff --git a/modules/surf/serve.go b/modules/surf/serve.go index fff349ed..11a0cc6e 100644 --- a/modules/surf/serve.go +++ b/modules/surf/serve.go @@ -86,15 +86,11 @@ clean stop and 1 when draining fails.`, } defer coolerHandle.Close() defer fallback.Close() - r, err := BuildRouter(app, plugins) + r, h, err := AssembleRouter(app, plugins) if err != nil { return err } defer r.Close() - h, err := r.compile() - if err != nil { - return err - } counter := newRequestCounter(h) ln, err := net.Listen("tcp", addr) if err != nil {