feat(surf): AssembleRouter builds the router and handler once; the router stops the MCP endpoint it mounted (quick-261118-lbt)

- surf.AssembleRouter returns the router and the compiled handler from
  one build, so an mcp.enabled app is not built twice; Assemble keeps
  its signature and is implemented on top of it
- serve uses AssembleRouter with a deferred Router.Close
- pier.Pier.Close stops the session reaper and the Redis warm-up; the
  router that mounted the endpoint owns it
- ExampleAssembleRouter, routing/testing docs and the surf/pier READMEs
This commit is contained in:
Jakub Zych
2026-11-18 15:44:56 +01:00
parent d9e21ad019
commit 38f7f3a777
11 changed files with 257 additions and 16 deletions

View File

@@ -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