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:
@@ -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. |
|
||||
|
||||
88
modules/surf/assemble_router_mcp_test.go
Normal file
88
modules/surf/assemble_router_mcp_test.go
Normal 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)
|
||||
}
|
||||
}
|
||||
60
modules/surf/assemble_router_test.go
Normal file
60
modules/surf/assemble_router_test.go
Normal 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)
|
||||
}
|
||||
})
|
||||
}
|
||||
@@ -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 {
|
||||
|
||||
@@ -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
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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 {
|
||||
|
||||
Reference in New Issue
Block a user