docs: add server router chapter

Add initial documentation for the Express.js-style router API covering:
- Handler signatures and return values
- Adding routes with add() and all()
- Fluent route() interface
- Dispatching requests
- Handler chaining
- Path patterns
- Router options

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: vinniefalco

doc/modules/ROOT/nav.adoc

@@ -7,6 +7,13 @@
 * Serializing
 * Parsing
 * xref:Message.adoc[]
+* Server
+** xref:server/router.adoc[Router]
+// ** xref:server/middleware.adoc[Middleware]
+// ** xref:server/errors.adoc[Error Handling]
+// ** xref:server/params.adoc[Route Parameters]
+// ** xref:server/advanced.adoc[Advanced Topics]
+// ** xref:server/cors.adoc[CORS]
 * Design Requirements
 ** xref:design_requirements/serializer.adoc[Serializer]
 ** xref:design_requirements/parser.adoc[Parser]

doc/modules/ROOT/pages/server/router.adoc

@@ -0,0 +1,310 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at https://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http_proto
+//
+
+= Server
+
+This library provides an Express.js-style request dispatcher for HTTP servers.
+The interface is Sans-I/O: it handles routing and response generation without
+performing network operations. A separate I/O framework such as Boost.Beast2
+manages connections and drives the protocol.
+
+== Router
+
+cpp:router[] is a class template that implements request routing. It stores a
+collection of routes, each with a path pattern, HTTP method, and one or more
+handlers. Callers (typically a framework) use the router to dispatch an HTTP
+request to a handler.
+
+=== Route Handler
+
+Route handlers have this signature:
+[source,cpp]
+----
+route_result handler( route_params& rp );
+----
+
+After this chapter you can: dispatch HTTP requests to handlers based on method
+and path, chain handlers together, and control request flow.
+
+== Overview
+
+The router is an Express.js-style request dispatcher. You register handlers
+for path patterns and HTTP methods, then dispatch incoming requests. The
+router matches the request against registered routes and invokes the
+appropriate handlers in order.
+
+[source,cpp]
+----
+#include <boost/http_proto.hpp>
+
+using namespace boost::http_proto;
+
+basic_router<route_params> router;
+
+router.add(method::get, "/hello",
+    [](route_params& p)
+    {
+        p.status(status::ok);
+        p.set_body("Hello, world!");
+        return route::send;
+    });
+----
+
+The library provides `route_params` as the standard parameters type. It
+contains the request, response, URL, and other context needed by handlers.
+
+== Handlers
+
+A handler is any callable that accepts a reference to the params object and
+returns a `route_result`:
+
+[source,cpp]
+----
+route_result handler(route_params& p);
+----
+
+The return value tells the router what to do next:
+
+[cols="1,3"]
+|===
+|Value |Meaning
+
+|`route::send`
+|Response is ready. Send it to the client.
+
+|`route::next`
+|Continue to the next handler in the chain.
+
+|`route::next_route`
+|Skip remaining handlers in this route, try the next route.
+
+|`route::close`
+|Close the connection after sending any response.
+
+|`route::complete`
+|Request fully handled; no response to send.
+
+|`route::detach`
+|Handler took ownership of the session (advanced).
+|===
+
+Most handlers return `route::send` when they produce a response, or
+`route::next` when they perform setup work and defer to later handlers.
+
+== Adding Routes
+
+Use `add()` to register a handler for a specific HTTP method and path:
+
+[source,cpp]
+----
+router.add(method::get, "/users", get_users);
+router.add(method::post, "/users", create_user);
+router.add(method::get, "/users/:id", get_user);
+router.add(method::put, "/users/:id", update_user);
+router.add(method::delete_, "/users/:id", delete_user);
+----
+
+Use `all()` to match any HTTP method:
+
+[source,cpp]
+----
+router.all("/status", check_status);
+----
+
+== Fluent Route Interface
+
+The `route()` method returns a fluent interface for registering multiple
+handlers on the same path:
+
+[source,cpp]
+----
+router.route("/users/:id")
+    .add(method::get, get_user)
+    .add(method::put, update_user)
+    .add(method::delete_, delete_user)
+    .all(log_access);
+----
+
+This is equivalent to calling `add()` separately for each method, but more
+concise when a path has multiple method handlers.
+
+== Dispatching Requests
+
+Call `dispatch()` to route a request:
+
+[source,cpp]
+----
+route_params p;
+// ... populate p.req, p.url from parsed request ...
+
+route_result rv = router.dispatch(method::get, p.url, p);
+
+if(rv == route::send)
+{
+    // p.res contains the response to send
+}
+else if(rv == route::next)
+{
+    // No handler matched; send 404
+}
+----
+
+The router tries each matching route in registration order. If a handler
+returns `route::next`, the router continues to the next handler. If all
+handlers return `route::next`, dispatch returns `route::next` to indicate
+no handler produced a response.
+
+== Handler Chaining
+
+Multiple handlers can be registered for the same route. They execute in
+order until one returns something other than `route::next`:
+
+[source,cpp]
+----
+router.add(method::get, "/admin",
+    [](route_params& p)
+    {
+        // Authentication check
+        if(!is_authenticated(p))
+        {
+            p.status(status::unauthorized);
+            p.set_body("Unauthorized");
+            return route::send;
+        }
+        return route::next;
+    },
+    [](route_params& p)
+    {
+        // Authorization check
+        if(!is_admin(p))
+        {
+            p.status(status::forbidden);
+            p.set_body("Forbidden");
+            return route::send;
+        }
+        return route::next;
+    },
+    [](route_params& p)
+    {
+        // Actual handler
+        p.status(status::ok);
+        p.set_body("Admin panel");
+        return route::send;
+    });
+----
+
+This pattern separates concerns: authentication, authorization, and business
+logic each have their own handler.
+
+== Path Patterns
+
+Route paths support named parameters and wildcards:
+
+[cols="1,2,2"]
+|===
+|Pattern |Example URL |Matches
+
+|`/users`
+|`/users`
+|Exact match
+
+|`/users/:id`
+|`/users/42`
+|Named parameter `id` = `"42"`
+
+|`/files/*`
+|`/files/docs/readme.txt`
+|Wildcard suffix
+|===
+
+Path matching is case-insensitive by default. Use `router_options` to change
+this behavior.
+
+== Router Options
+
+Configure matching behavior when constructing the router:
+
+[source,cpp]
+----
+basic_router<route_params> router(
+    router_options()
+        .case_sensitive(true)   // Paths are case-sensitive
+        .strict(true));         // Trailing slash matters
+----
+
+[cols="1,1,3"]
+|===
+|Option |Default |Description
+
+|`case_sensitive`
+|`false`
+|When true, `/Users` and `/users` are different routes.
+
+|`strict`
+|`false`
+|When true, `/api` and `/api/` are different routes.
+
+|`merge_params`
+|`false`
+|When true, inherit parameters from parent routers.
+|===
+
+== Complete Example
+
+[source,cpp]
+----
+#include <boost/http_proto.hpp>
+
+using namespace boost::http_proto;
+
+int main()
+{
+    basic_router<route_params> router;
+
+    // Health check endpoint
+    router.add(method::get, "/health",
+        [](route_params& p)
+        {
+            p.status(status::ok);
+            p.set_body("OK");
+            return route::send;
+        });
+
+    // API routes
+    router.route("/api/echo")
+        .add(method::post,
+            [](route_params& p)
+            {
+                p.status(status::ok);
+                // Echo back the request body
+                return route::send;
+            })
+        .add(method::get,
+            [](route_params& p)
+            {
+                p.status(status::method_not_allowed);
+                return route::send;
+            });
+
+    // Dispatch a request
+    route_params p;
+    auto rv = router.dispatch(
+        method::get,
+        urls::url_view("/health"),
+        p);
+
+    // rv == route::send, p.res contains "OK"
+}
+----
+
+== See Also
+
+* xref:server/middleware.adoc[Middleware] - Path-based handler chains
+* xref:server/errors.adoc[Error Handling] - Error and exception handlers
+* xref:server/params.adoc[Route Parameters] - The `route_params` object

include/boost/http_proto.hpp

@@ -28,7 +28,6 @@
 #include <boost/http_proto/request_parser.hpp>
 #include <boost/http_proto/response.hpp>
 #include <boost/http_proto/response_base.hpp>
-#include <boost/http_proto/response_parser.hpp>
 #include <boost/http_proto/serializer.hpp>
 #include <boost/http_proto/sink.hpp>
 #include <boost/http_proto/source.hpp>
@@ -37,7 +36,7 @@
 #include <boost/http_proto/status.hpp>
 #include <boost/http_proto/string_body.hpp>
 #include <boost/http_proto/version.hpp>
-
+ 
 #include <boost/http_proto/rfc/combine_field_values.hpp>
 #include <boost/http_proto/rfc/list_rule.hpp>
 //#include <boost/http_proto/rfc/media_type.hpp>
@@ -50,6 +49,7 @@
 #include <boost/http_proto/server/basic_router.hpp>
 #include <boost/http_proto/server/cors.hpp>
 #include <boost/http_proto/server/route_handler.hpp>
+#include <boost/http_proto/server/router.hpp>
 #include <boost/http_proto/server/router_types.hpp>
 
 #endif

include/boost/http_proto/server/router.hpp

@@ -0,0 +1,33 @@
+//
+// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+// Official repository: https://github.com/cppalliance/http_proto
+//
+
+#ifndef BOOST_HTTP_PROTO_SERVER_ROUTER_HPP
+#define BOOST_HTTP_PROTO_SERVER_ROUTER_HPP
+
+#include <boost/http_proto/detail/config.hpp>
+#include <boost/http_proto/server/basic_router.hpp>
+
+namespace boost {
+namespace http_proto {
+
+/** A router for HTTP servers
+
+    This is a specialization of `basic_router` using
+    `route_params` as the handler parameter type.
+
+    @see
+        @ref basic_router,
+        @ref route_params
+*/
+using router = basic_router<route_params>;
+
+} // http_proto
+} // boost
+
+#endif