feat: add new ways to work with multiple teapot routers

Author: mallardduck

docs/ROUTES-LISTING.md

@@ -24,6 +24,22 @@ http.ListenAndServe(":8080", router)
 
 Visit `http://localhost:8080/.internal/routes` to see all routes.
 
+### Aggregated Route List
+
+If you have multiple routers (e.g., an app router on port 80 and an admin router on port 8080), you can merge their routes for a unified listing:
+
+```go
+appRouter := setupApp()
+adminRouter := setupAdmin()
+
+// Aggregate routes from both
+combined := teapot.AggregateRoutes(appRouter, adminRouter)
+
+// Create a handler for the aggregated routes
+handler := teapot.NewListRoutesHandlerWithRoutes(combined, nil)
+appRouter.GET("/.internal/routes", handler).Name("all.routes")
+```
+
 ### Response Formats
 
 The debug endpoint supports both JSON and HTML:
@@ -76,6 +92,13 @@ router.RegisterDebugRoute("/.internal/routes", "debug.routes")
 router.GET("/.internal/routes", router.RoutesHandler()).
 Name("debug.routes").
 With(authMiddleware)
+
+// Option 5: Custom filtering
+// Only show routes that don't start with /.internal/
+filter := func(route teapot.RouteInfo) bool {
+    return !strings.HasPrefix(route.Pattern, "/.internal/")
+}
+router.GET("/routes", teapot.NewListRoutesHandler(router, filter))
 ```
 
 ## CLI Route Listing
@@ -195,6 +218,15 @@ routes := router.Routes()
 err := teapot.FormatRoutesTable(os.Stdout, routes)
 ```
 
+### AggregateRoutes
+
+Merge routes from multiple routers for unified output:
+
+```go
+allRoutes := teapot.AggregateRoutes(mainRouter, adminRouter, internalRouter)
+err := teapot.FormatRoutesTable(os.Stdout, allRoutes)
+```
+
 ### FormatRoutesJSON
 
 JSON output with count and sorted routes:

docs/USAGE.md

@@ -160,27 +160,91 @@ key := teapot.URLParam(r, "key")
 
 ---
 
-## Route Groups
+## Route Groups and Sub-Routers
+
+### Path and Name Groups
 
 Group routes with path and name prefixes:
 
 ```go
 // Path prefix only
 r.Group("/api/v1", func (r *teapot.Router) {
-r.GET("/users", listUsers).Name("users.list")
+    r.GET("/users", listUsers).Name("users.list")
 })
 
 // Path + name prefix
 r.NamedGroup("/{bucket}", "bucket", func (r *teapot.Router) {
-r.GET("", listObjects).Name("list") // name: "bucket.list"
-r.GET("", getBucketAcl).Name("acl").Query("acl") // name: "bucket.acl"
+    r.GET("", listObjects).Name("list") // name: "bucket.list"
+    r.GET("", getBucketAcl).Name("acl").Query("acl") // name: "bucket.acl"
 
-r.NamedGroup("/{key:.*}", "object", func (r *teapot.Router) {
-r.GET("", getObject).Name("get") // name: "bucket.object.get"
-})
+    r.NamedGroup("/{key:.*}", "object", func (r *teapot.Router) {
+        r.GET("", getObject).Name("get") // name: "bucket.object.get"
+    })
 })
 ```
 
+### Sub-Routers (Live Propagation)
+
+`SubRouter(prefix)` creates a new child router whose routes are automatically visible in the parent router with the prefix prepended. 
+
+Unlike `Group()`, `SubRouter()` returns a separate `Router` instance that can be used independently (e.g., as its own HTTP server) while still reporting its routes to the parent for unified listing and URL generation.
+
+```go
+adminRouter := r.SubRouter("/admin")
+adminRouter.GET("/dashboard", dashHandler).Name("dashboard")
+// "dashboard" route is now visible in both adminRouter and r (as "/admin/dashboard")
+```
+
+---
+
+## Mounting Handlers
+
+### Mounting standard http.Handlers
+
+Use `Mount(prefix, handler)` to attach any `http.Handler` to a path prefix:
+
+```go
+r.Mount("/static", http.FileServer(http.Dir("./static")))
+```
+
+### Mounting teapot Routers (Route Propagation)
+
+If the handler being mounted is also a `*teapot.Router`, all its existing routes are automatically propagated to the parent router with the prefix prepended. This enables unified route listing and URL generation even when routers are developed independently.
+
+```go
+apiRouter := teapot.New()
+apiRouter.GET("/users", listUsers).Name("users.list")
+
+// Mount propagates all apiRouter's current routes to r
+r.Mount("/api/v1", apiRouter)
+// r now knows about "/api/v1/users" with name "users.list"
+```
+
+---
+
+## Direct Handler Registration
+
+Assign standard `http.Handler` (including `http.HandlerFunc` via `http.HandlerFunc(fn)`) to a method and pattern:
+
+```go
+r.Handle("GET", "/health", healthHandler).Name("health")
+```
+
+This is a more flexible alternative to `GET()`, `POST()`, etc. when you already have an `http.Handler` instance.
+
+---
+
+## Phantom Routes (External Services)
+
+Use `RegisterExternal(method, pattern, name, action)` to add "phantom" routes to the router. These routes appear in documentation (route lists) and work with the URL builder, but do not dispatch requests locally. This is useful for documenting external services or third-party handlers that you cannot convert to teapot.
+
+```go
+r.RegisterExternal("GET", "https://auth.example.com/login", "auth.login", "auth:Login")
+
+// Use for URL generation:
+loginURL := r.MustURL("auth.login") // "https://auth.example.com/login"
+```
+
 ---
 
 ## Middleware

internal/core/route.go

@@ -58,6 +58,23 @@ func TranslatePattern(pattern string) (string, map[string]bool) {
 			break // Only one wildcard per pattern is supported by Chi
 		}
 
+		// Check for Go 1.22+ exact match operator {$}
+		if paramDef == "$" {
+			// Chi handles exact matches with the standard trailing slash / pattern.
+			// We translate /{ $ } to / so that Chi routes correctly.
+			// Example: /users/{$} becomes /users/
+			prefix := result[:idx]
+			suffix := result[endIdx+1:]
+
+			// If we have something like /admin/{$}, we want it to be /admin/
+			// If it's just /{$}, it becomes /
+			result = prefix + suffix
+
+			// Don't advance start, re-scan from where suffix begins
+			start = idx
+			continue
+		}
+
 		start = endIdx + 1
 	}
 

pkg/teapot/router.go

@@ -212,6 +212,33 @@ func (r *Router) QueryOPTIONS(pattern string, handler http.Handler) *RouteBuilde
 	return r.handleQuery("OPTIONS", pattern, handler)
 }
 
+// Handle registers an arbitrary http.Handler with a pattern and method
+// Supports both direct registration and query-based multiplexing via RouteBuilder
+func (r *Router) Handle(method, pattern string, handler http.Handler) *RouteBuilder {
+	return r.handleDirect(method, pattern, handler)
+}
+
+// RegisterExternal adds a "phantom" route to the router.
+// Phantom routes are only for documentation and do not dispatch requests.
+// They appear in the Routes() listing and can be used for URL generation.
+func (r *Router) RegisterExternal(method, pattern, name, action string) {
+	// Create a dummy route metadata
+	rt := &core.Route{
+		Method:  method,
+		Pattern: r.pathPrefix + pattern,
+		Name:    r.namePrefix + name,
+		Action:  action,
+	}
+
+	// Add to routes list for listing
+	*r.routes = append(*r.routes, rt)
+
+	// Add to name index for URL generation
+	if rt.Name != "" {
+		r.nameIndex[rt.Name] = rt
+	}
+}
+
 // handleDirect registers a route directly with Chi (no dispatcher, best performance)
 // This is used by GET, POST, PUT, DELETE, etc.
 // Automatically promotes to dispatcher-based routing if multiple routes exist on same method+pattern
@@ -250,7 +277,7 @@ func (r *Router) handleDirect(method, pattern string, handler http.Handler) *Rou
 
 	// Check if another direct route already exists
 	if existingRoute, exists := r.directRoutes[dispatcherKey]; exists {
-		r.debugLogf("Auto-promoting to dispatcher: %s %s (multiple routes on same path)", method, fullPattern)
+		r.debugLogf("Auto-promoting to dispatcher: %s %s (chi: %s) (multiple routes on same path)", method, fullPattern, chiPattern)
 		// Promote to dispatcher!
 		disp := &core.Dispatcher{Routes: make([]*core.Route, 0)}
 		disp.AddRoute(existingRoute) // Old route becomes fallback
@@ -271,6 +298,7 @@ func (r *Router) handleDirect(method, pattern string, handler http.Handler) *Rou
 	}
 	*r.optimizedHandlers = append(*r.optimizedHandlers, optHandler)
 
+	r.debugLogf("Registering direct route with Chi: %s %s (chi: %s)", method, fullPattern, chiPattern)
 	r.mux.Method(method, chiPattern, optHandler)
 	r.directRoutes[dispatcherKey] = rt
 
@@ -432,6 +460,68 @@ func (r *Router) Use(middlewares ...func(http.Handler) http.Handler) {
 	r.mux.Use(middlewares...)
 }
 
+// Mount attaches another http.Handler (typically a router) to a prefix.
+// If the handler is a *teapot.Router, all its routes are propagated to the
+// parent router with the prefix prepended for unified listing and URL generation.
+func (r *Router) Mount(pattern string, handler http.Handler) {
+	fullPattern := r.pathPrefix + pattern
+	r.mux.Mount(pattern, handler)
+
+	r.propagateRoutes(fullPattern, handler)
+}
+
+func (r *Router) propagateRoutes(prefix string, handler http.Handler) {
+	// Propagate routes if it's a teapot Router
+	if subRouter, ok := handler.(*Router); ok {
+		for _, rt := range *subRouter.routes {
+			// Create a copy of the route with updated pattern and name
+			newRoute := &core.Route{
+				Method:         rt.Method,
+				Pattern:        prefix + rt.Pattern,
+				ChiPattern:     prefix + rt.ChiPattern,
+				Handler:        rt.Handler,
+				Name:           r.namePrefix + rt.Name,
+				Action:         rt.Action,
+				QueryMatchers:  rt.QueryMatchers,
+				Middlewares:    rt.Middlewares,
+				WildcardParams: rt.WildcardParams,
+			}
+			*r.routes = append(*r.routes, newRoute)
+
+			// Update name index for URL generation
+			if newRoute.Name != "" {
+				r.nameIndex[newRoute.Name] = newRoute
+			}
+		}
+	}
+}
+
+// SubRouter creates a new child router whose routes are automatically
+// visible in the parent router with the prefix prepended.
+//
+// Unlike Group(), SubRouter() returns a separate Router instance that
+// can be used independently (e.g., as its own HTTP server) but still
+// reports its routes to the parent.
+func (r *Router) SubRouter(prefix string) *Router {
+	subRouter := New()
+	// Create a proxy that notifies the parent when routes are added
+	// Actually, easier to just wrap the subRouter's routes slice
+	// but that might be messy with patterns.
+
+	// Instead, we can make SubRouter aware of its parent
+	// or just rely on the fact that SubRouter is empty now,
+	// and we want it to propagate FUTURE routes too.
+
+	// Let's change the approach for SubRouter to support live propagation.
+	subRouter.routes = r.routes
+	subRouter.nameIndex = r.nameIndex
+	subRouter.pathPrefix = r.pathPrefix + prefix
+	subRouter.namePrefix = r.namePrefix // SubRouter usually doesn't prefix names unless told
+
+	r.mux.Mount(prefix, subRouter)
+	return subRouter
+}
+
 // findMatchingRoute manually matches a request against registered routes
 // This is used as a fallback when Chi's RouteContext isn't available (e.g., in global middleware)
 func (r *Router) findMatchingRoute(method, path string) *core.Route {
@@ -576,6 +666,9 @@ func (r *Router) URL(name string, params ...string) (string, error) {
 		url = strings.ReplaceAll(url, "{"+key+":.*}", value)
 	}
 
+	// Remove Go 1.22+ exact match operator {$} for URL generation
+	url = strings.ReplaceAll(url, "{$}", "")
+
 	// Check if any parameters remain unreplaced
 	if strings.Contains(url, "{") {
 		return "", fmt.Errorf("missing parameters for route %q", name)
@@ -625,31 +718,45 @@ type HeaderParam struct {
 func (r *Router) Routes() []RouteInfo {
 	var infos []RouteInfo
 	for _, rt := range *r.routes {
-		var queryParams []QueryParam
-		var headerParams []HeaderParam
-		for _, matcher := range rt.QueryMatchers {
-			switch m := matcher.(type) {
-			case dispatch.QueryExistsMatcher:
-				queryParams = append(queryParams, QueryParam{Key: m.Key})
-			case dispatch.QueryValueMatcher:
-				queryParams = append(queryParams, QueryParam{Key: m.Key, Value: m.Value})
-			case dispatch.HeaderExistsMatcher:
-				headerParams = append(headerParams, HeaderParam{Key: m.Key})
-			case dispatch.HeaderValueMatcher:
-				headerParams = append(headerParams, HeaderParam{Key: m.Key, Value: m.Value})
-			}
+		infos = append(infos, transformRoute(rt))
+	}
+	return infos
+}
+
+// AggregateRoutes merges routes from multiple routers into a single slice.
+// This is useful for unified route listings across routers on different ports.
+func AggregateRoutes(routers ...*Router) []RouteInfo {
+	var allRoutes []RouteInfo
+	for _, r := range routers {
+		allRoutes = append(allRoutes, r.Routes()...)
+	}
+	return allRoutes
+}
+
+func transformRoute(rt *core.Route) RouteInfo {
+	var queryParams []QueryParam
+	var headerParams []HeaderParam
+	for _, matcher := range rt.QueryMatchers {
+		switch m := matcher.(type) {
+		case dispatch.QueryExistsMatcher:
+			queryParams = append(queryParams, QueryParam{Key: m.Key})
+		case dispatch.QueryValueMatcher:
+			queryParams = append(queryParams, QueryParam{Key: m.Key, Value: m.Value})
+		case dispatch.HeaderExistsMatcher:
+			headerParams = append(headerParams, HeaderParam{Key: m.Key})
+		case dispatch.HeaderValueMatcher:
+			headerParams = append(headerParams, HeaderParam{Key: m.Key, Value: m.Value})
 		}
+	}
 
-		infos = append(infos, RouteInfo{
-			Method:       rt.Method,
-			Pattern:      rt.Pattern,
-			Name:         rt.Name,
-			Action:       rt.Action,
-			QueryParams:  queryParams,
-			HeaderParams: headerParams,
-		})
+	return RouteInfo{
+		Method:       rt.Method,
+		Pattern:      rt.Pattern,
+		Name:         rt.Name,
+		Action:       rt.Action,
+		QueryParams:  queryParams,
+		HeaderParams: headerParams,
 	}
-	return infos
 }
 
 // GetAction retrieves the S3 action from the request context