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