add ability for late propagation of sub-routers

Author: mallardduck

docs/USAGE.md

@@ -207,19 +207,43 @@ Use `Mount(prefix, handler)` to attach any `http.Handler` to a path prefix:
 r.Mount("/static", http.FileServer(http.Dir("./static")))
 ```
 
-### Mounting teapot Routers (Route Propagation)
+### Mounting teapot Routers (Late Propagation & Homing)
 
-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.
+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. 
+
+Furthermore, **"Homing"** is established: any future routes added to the sub-router after it has been mounted will also be automatically propagated to the parent. This enables flexible router composition where routers can be developed independently or even after mounting.
 
 ```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"
+
+// Homing: even routes added LATER are visible in the parent
+apiRouter.GET("/profile", profileHandler).Name("users.profile")
+
+// r now knows about both:
+// "/api/v1/users" (name: "users.list")
+// "/api/v1/profile" (name: "users.profile")
+```
+
+#### Custom Name Prefixes for Mounted Routers
+
+When mounting a router, you can control the name prefix applied to its routes using `MountNamed` or the fluent `.Name()` method on the mount builder:
+
+```go
+// Using MountNamed
+r.MountNamed("/api/v1", "v1", apiRouter)
+// apiRouter route "users.list" becomes "v1.users.list" in r
+
+// Using fluent API
+r.Mount("/api/v2", apiRouter).Name("v2")
+// apiRouter route "users.list" becomes "v2.users.list" in r
 ```
 
+If a name is assigned via the fluent `.Name()` after mounting, any already-propagated routes will be renamed throughout the hierarchy automatically.
+
 ---
 
 ## Direct Handler Registration

internal/core/route.go

@@ -18,6 +18,7 @@ type Route struct {
 	QueryMatchers  []dispatch.Matcher
 	Middlewares    []func(http.Handler) http.Handler
 	WildcardParams map[string]bool // Track which params are wildcards (e.g., "key" -> true)
+	OriginalRoute  *Route          // Pointer to original route if this is a propagated copy
 }
 
 // TranslatePattern converts our {key:.*} syntax to Chi's wildcard syntax

pkg/teapot/router.go

@@ -25,6 +25,54 @@ type Router struct {
 	optimizedHandlers *[]*optimizedHandler // for finalization optimization
 	finalized         bool
 	debugLog          bool // enable debug logging for auto-promotion
+
+	// Homing support for late propagation
+	parents []parentRouter // parent routers to notify of new routes
+}
+
+type parentRouter struct {
+	router     *Router
+	pathPrefix string
+	namePrefix string
+}
+
+// MountBuilder provides a fluent API for building mounted routers
+type MountBuilder struct {
+	router     *Router
+	subRouter  *Router
+	pathPrefix string
+	namePrefix string
+}
+
+// Name assigns a name prefix to all routes in the mounted sub-router
+func (mb *MountBuilder) Name(name string) *MountBuilder {
+	if mb.subRouter == nil {
+		return mb
+	}
+
+	if name != "" && !strings.HasSuffix(name, ".") {
+		name += "."
+	}
+
+	// Update the prefix for all future routes
+	newNamePrefix := mb.router.namePrefix + name
+
+	// Find the parent entry in the subRouter and update it
+	for i := range mb.subRouter.parents {
+		p := &mb.subRouter.parents[i]
+		if p.router == mb.router && p.pathPrefix == mb.pathPrefix {
+			// Found it! Update the prefix
+			oldNamePrefix := p.namePrefix
+			p.namePrefix = newNamePrefix
+
+			// Now we MUST also update any ALREADY propagated routes' names.
+			// This is because propagateRoutes was called with the old prefix during Mount.
+			mb.router.propagateRouteNames(oldNamePrefix, newNamePrefix, mb.subRouter)
+		}
+	}
+
+	mb.namePrefix = newNamePrefix
+	return mb
 }
 
 // RouteBuilder provides a fluent API for building routes
@@ -72,6 +120,11 @@ func (rb *RouteBuilder) Name(name string) *RouteBuilder {
 	// Register in name index
 	rb.router.nameIndex[fullName] = rb.route
 
+	// Update parents if name was added late (homing)
+	for _, p := range rb.router.parents {
+		p.router.propagateRouteName(p.namePrefix, rb.route)
+	}
+
 	return rb
 }
 
@@ -265,6 +318,11 @@ func (r *Router) handleDirect(method, pattern string, handler http.Handler) *Rou
 
 	*r.routes = append(*r.routes, rt)
 
+	// Propagate to parents (Homing)
+	for _, p := range r.parents {
+		p.router.propagateRoute(p.pathPrefix, p.namePrefix, rt)
+	}
+
 	dispatcherKey := method + ":" + chiPattern
 
 	// Check if dispatcher already exists (from QueryGET/etc)
@@ -330,6 +388,11 @@ func (r *Router) handleQuery(method, pattern string, handler http.Handler) *Rout
 
 	*r.routes = append(*r.routes, rt)
 
+	// Propagate to parents (Homing)
+	for _, p := range r.parents {
+		p.router.propagateRoute(p.pathPrefix, p.namePrefix, rt)
+	}
+
 	// Get or create dispatcher for this method+pattern
 	dispatcherKey := method + ":" + chiPattern
 	disp, exists := r.dispatchers[dispatcherKey]
@@ -460,40 +523,152 @@ func (r *Router) Use(middlewares ...func(http.Handler) http.Handler) {
 	r.mux.Use(middlewares...)
 }
 
+// MountNamed is like Mount, but allows specifying a name prefix for the sub-router's routes.
+// The provided namePrefix will be prepended to all routes in the sub-router.
+func (r *Router) MountNamed(pattern, namePrefix string, handler http.Handler) *MountBuilder {
+	fullPattern := r.pathPrefix + pattern
+
+	if namePrefix != "" && !strings.HasSuffix(namePrefix, ".") {
+		namePrefix += "."
+	}
+	fullNamePrefix := r.namePrefix + namePrefix
+
+	var subRouter *Router
+	if sr, ok := handler.(*Router); ok {
+		subRouter = sr
+
+		// Check if we are already mounted at this pattern
+		alreadyMounted := false
+		for _, p := range subRouter.parents {
+			if p.router == r && p.pathPrefix == fullPattern {
+				alreadyMounted = true
+				break
+			}
+		}
+
+		if !alreadyMounted {
+			r.mux.Mount(pattern, handler)
+
+			// Late propagation of existing routes
+			r.propagateRoutes(fullPattern, fullNamePrefix, subRouter)
+
+			// Set up "Homing" for future routes
+			subRouter.parents = append(subRouter.parents, parentRouter{
+				router:     r,
+				pathPrefix: fullPattern,
+				namePrefix: fullNamePrefix,
+			})
+		}
+	} else {
+		r.mux.Mount(pattern, handler)
+	}
+
+	return &MountBuilder{
+		router:     r,
+		subRouter:  subRouter,
+		pathPrefix: fullPattern,
+		namePrefix: fullNamePrefix,
+	}
+}
+
 // 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,
+// Furthermore, future routes added to the sub-router will also be propagated.
+func (r *Router) Mount(pattern string, handler http.Handler) *MountBuilder {
+	return r.MountNamed(pattern, "", handler)
+}
+
+func (r *Router) propagateRoutes(pathPrefix, namePrefix string, subRouter *Router) {
+	for _, rt := range *subRouter.routes {
+		r.propagateRoute(pathPrefix, namePrefix, rt)
+	}
+}
+
+func (r *Router) propagateRoute(pathPrefix, namePrefix string, rt *core.Route) {
+	// Create a copy of the route with updated pattern and name
+	newRoute := &core.Route{
+		Method:         rt.Method,
+		Pattern:        pathPrefix + rt.Pattern,
+		ChiPattern:     pathPrefix + rt.ChiPattern,
+		Handler:        rt.Handler,
+		Name:           namePrefix + rt.Name,
+		Action:         rt.Action,
+		QueryMatchers:  rt.QueryMatchers,
+		Middlewares:    rt.Middlewares,
+		WildcardParams: rt.WildcardParams,
+		OriginalRoute:  rt, // Link to original for name updates
+	}
+	*r.routes = append(*r.routes, newRoute)
+
+	// Update name index for URL generation
+	if newRoute.Name != "" {
+		r.nameIndex[newRoute.Name] = newRoute
+	}
+
+	// Propagate further up if this router also has parents
+	for _, p := range r.parents {
+		p.router.propagateRoute(p.pathPrefix, p.namePrefix, newRoute)
+	}
+}
+
+func (r *Router) propagateRouteName(namePrefix string, originalRt *core.Route) {
+	for _, rt := range *r.routes {
+		if rt.OriginalRoute == originalRt {
+			rt.Name = namePrefix + originalRt.Name
+			if rt.Name != "" {
+				r.nameIndex[rt.Name] = rt
 			}
-			*r.routes = append(*r.routes, newRoute)
 
-			// Update name index for URL generation
-			if newRoute.Name != "" {
-				r.nameIndex[newRoute.Name] = newRoute
+			// Propagate further up
+			for _, p := range r.parents {
+				p.router.propagateRouteName(p.namePrefix, rt)
+			}
+			return
+		}
+	}
+}
+
+func (r *Router) propagateRouteNames(oldPrefix, newPrefix string, subRouter *Router) {
+	for _, rt := range *r.routes {
+		if rt.OriginalRoute != nil && strings.HasPrefix(rt.Name, oldPrefix) {
+			// Check if this route actually belongs to the subRouter tree
+			if r.belongsTo(rt, subRouter) {
+				// Remove old name from index
+				if rt.Name != "" {
+					delete(r.nameIndex, rt.Name)
+				}
+
+				// Update name
+				suffix := strings.TrimPrefix(rt.Name, oldPrefix)
+				rt.Name = newPrefix + suffix
+
+				// Re-add to index
+				if rt.Name != "" {
+					r.nameIndex[rt.Name] = rt
+				}
+
+				// Propagate further up
+				for _, p := range r.parents {
+					p.router.propagateRouteNames(p.namePrefix+oldPrefix, p.namePrefix+newPrefix, subRouter)
+				}
+			}
+		}
+	}
+}
+
+func (r *Router) belongsTo(rt *core.Route, subRouter *Router) bool {
+	// Follow OriginalRoute chain to see if it leads to one of subRouter's routes
+	curr := rt.OriginalRoute
+	for curr != nil {
+		for _, subRt := range *subRouter.routes {
+			if curr == subRt {
+				return true
 			}
 		}
+		curr = curr.OriginalRoute
 	}
+	return false
 }
 
 // SubRouter creates a new child router whose routes are automatically

tests/exact_match_test.go

@@ -16,12 +16,12 @@ func TestExactMatch(t *testing.T) {
 
 	r.GET("/{$}", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
 		w.WriteHeader(http.StatusOK)
-		w.Write([]byte("root"))
+		_, _ = w.Write([]byte("root"))
 	}))
 
 	r.GET("/{path}", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
 		w.WriteHeader(http.StatusOK)
-		w.Write([]byte("child"))
+		_, _ = w.Write([]byte("child"))
 	}))
 
 	t.Run("root match", func(t *testing.T) {
@@ -57,11 +57,11 @@ func TestExactMatchInGroups(t *testing.T) {
 	r.Group("/admin", func(r *teapot.Router) {
 		r.GET("/{$}", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
 			w.WriteHeader(http.StatusOK)
-			w.Write([]byte("admin-root"))
+			_, _ = w.Write([]byte("admin-root"))
 		}))
 		r.GET("/{path}", http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) {
 			w.WriteHeader(http.StatusOK)
-			w.Write([]byte("admin-child"))
+			_, _ = w.Write([]byte("admin-child"))
 		}))
 	})