Add WithNotFoundHandler option for custom 404 responses on Router

Allows configuring a custom handler for unmatched routes, enabling
consistent JSON error responses instead of ServeMux's default plain
text. NewRouter now accepts RouterOption functional options.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

server/route.go

@@ -9,16 +9,31 @@ import (
 // groups and sub-router mounting. It leverages Go 1.22+ enhanced patterns
 // like "GET /users/{id}".
 type Router struct {
-	mux        *http.ServeMux
-	prefix     string
-	middlewares []Middleware
+	mux             *http.ServeMux
+	prefix          string
+	middlewares     []Middleware
+	notFoundHandler http.Handler
+}
+
+// RouterOption configures a Router.
+type RouterOption func(*Router)
+
+// WithNotFoundHandler sets a custom handler for requests that don't match
+// any registered pattern. This is useful for returning JSON 404/405 responses
+// instead of the default plain text.
+func WithNotFoundHandler(h http.Handler) RouterOption {
+	return func(r *Router) { r.notFoundHandler = h }
 }
 
 // NewRouter creates a new Router backed by a fresh http.ServeMux.
-func NewRouter() *Router {
-	return &Router{
+func NewRouter(opts ...RouterOption) *Router {
+	r := &Router{
 		mux: http.NewServeMux(),
 	}
+	for _, opt := range opts {
+		opt(r)
+	}
+	return r
 }
 
 // Handle registers a handler for the given pattern. The pattern follows
@@ -63,6 +78,14 @@ func (r *Router) Mount(prefix string, handler http.Handler) {
 
 // ServeHTTP implements http.Handler, making Router usable as a handler.
 func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request) {
+	if r.notFoundHandler != nil {
+		// Use the mux to check for a match. If none, use the custom handler.
+		_, pattern := r.mux.Handler(req)
+		if pattern == "" {
+			r.notFoundHandler.ServeHTTP(w, req)
+			return
+		}
+	}
 	r.mux.ServeHTTP(w, req)
 }