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

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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