Add Server::CustomRoute() for HTTP methods outside the built-in set (#2553)

* Add Server::CustomRoute() for HTTP methods outside the built-in set

parse_request_line validates the request method against a fixed whitelist and
rejects anything else with 400 before routing runs. That blocks WebDAV, where
PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK and UNLOCK are ordinary methods
defined by RFC 4918, and it blocks extension methods such as UPnP's SUBSCRIBE.
The need has been open since #847.

Registering a handler is now what makes the server accept a method:

    svr.CustomRoute("PROPFIND", "/dav/:id", handler);

Because custom methods go through the normal dispatch path, patterns work the
way they do for Get() and friends, and the request body is available in
req.body. Serving these methods through set_pre_routing_handler was never
enough: the body has not been read at that point, so PROPPATCH and LOCK, which
require one, could not be implemented at all.

A HandlerWithContentReader overload is available too. The content reader gate
in routing() also fires when a custom method carries no body, matching what
expect_content() does unconditionally for POST/PUT/PATCH/DELETE, so a body-less
PROPFIND (RFC 4918 treats one as allprop) reaches its handler instead of
falling through to 404.

Method names are validated as RFC 9110 tokens, and the ten built-in methods are
refused. Seven of them are dispatched by the if/else chain in routing() before
the custom tables are consulted, so a route registered for one could never
fire; CONNECT, TRACE and PRI carry protocol-level meaning this library does not
route. A refused registration makes is_valid() return false, so listen() fails
rather than starting a server holding a handler that would never run. This is
also why SSLServer::is_valid() now chains to Server::is_valid() instead of only
checking ctx_.

Servers that never call CustomRoute() keep the previous per-request cost: the
built-in method set is checked first and short-circuits, and the custom lookup
returns early on an empty map.

* Add cookbook recipe for custom HTTP methods

The CustomRoute() docs were a section inside S01, which pushed that page to 90
lines, the longest in the cookbook, and mixed a separate feature into a page
about registering GET/POST/PUT/DELETE handlers. Move the section into its own
recipe and give it room for the part that was missing: the OPTIONS handler
returning DAV: and Allow, which WebDAV clients probe for before anything else.
S01 goes back to 68 lines and keeps a pointer to the new page.

The recipe is titled after the API rather than after WebDAV, and says outright
that generating the 207 Multi-Status XML, interpreting Depth and managing locks
are the reader's job. Routing the method is all the library does.

S23 takes order 42, so the TLS, SSE and WebSocket recipes shift to 43-57. That
only moves the sort key. Filenames, the T01/E01/W01 labels, the published URLs
and every cross-reference are untouched.

docs-src/pages/en/cookbook/e01-sse-server.md

@@ -1,6 +1,6 @@
 ---
 title: "E01. Implement an SSE Server"
-order: 47
+order: 48
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/e02-sse-event-names.md

@@ -1,6 +1,6 @@
 ---
 title: "E02. Use Named Events in SSE"
-order: 48
+order: 49
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/e03-sse-reconnect.md

@@ -1,6 +1,6 @@
 ---
 title: "E03. Handle SSE Reconnection"
-order: 49
+order: 50
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/e04-sse-client.md

@@ -1,6 +1,6 @@
 ---
 title: "E04. Receive SSE on the Client"
-order: 50
+order: 51
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/index.md

@@ -73,6 +73,9 @@ A collection of recipes that answer "How do I...?" questions. Each recipe is sel
 - [S21. Configure the thread pool](s21-thread-pool)
 - [S22. Talk over a Unix domain socket](s22-unix-socket)
 
+### Protocol Extensions
+- [S23. Handle custom HTTP methods](s23-custom-methods)
+
 ## TLS / Security
 
 - [T01. Choosing between OpenSSL, mbedTLS, and wolfSSL](t01-tls-backends)

docs-src/pages/en/cookbook/s01-handlers.md

@@ -4,7 +4,7 @@ order: 20
 status: "draft"
 ---
 
-With `httplib::Server`, you register a handler per HTTP method. Just pass a pattern and a lambda to `Get()`, `Post()`, `Put()`, or `Delete()`.
+With `httplib::Server`, you register a handler per HTTP method. Just pass a pattern and a lambda to `Get()`, `Post()`, `Put()`, or `Delete()`. For methods outside the built-in set, such as WebDAV's `PROPFIND`, use `CustomRoute()`.
 
 ## Basic usage
 
@@ -64,3 +64,5 @@ To add a response header, use `res.set_header("Name", "Value")`.
 > **Note:** `listen()` is a blocking call. To run it on a different thread, wrap it in `std::thread`. If you need non-blocking startup, see [S18. Control startup order with `listen_after_bind`](../s18-listen-after-bind).
 
 > To use path parameters like `/users/:id`, see [S03. Use path parameters](../s03-path-params).
+
+> For methods outside the built-in set, such as WebDAV's `PROPFIND`, see [S23. Handle custom HTTP methods](../s23-custom-methods).

docs-src/pages/en/cookbook/s23-custom-methods.md

@@ -0,0 +1,59 @@
+---
+title: "S23. Handle custom HTTP methods"
+order: 42
+status: "draft"
+---
+
+The server rejects HTTP methods it does not know with `400 Bad Request`. To accept an extension method, such as the WebDAV methods of RFC 4918 (`PROPFIND`, `PROPPATCH`, `MKCOL` and friends) or UPnP's `SUBSCRIBE`, register a handler with `CustomRoute()`. Registering the handler is what makes the server accept the method.
+
+## Basic usage
+
+```cpp
+svr.CustomRoute("PROPFIND", "/dav/:id",
+                [](const httplib::Request &req, httplib::Response &res) {
+                  // The request body is available as usual
+                  auto id = req.path_params.at("id");
+                  res.status = httplib::StatusCode::MultiStatus_207;
+                  res.set_content(build_multistatus(req.body), "application/xml");
+                });
+```
+
+Patterns work the same way as they do for `Get()`. Regular expressions and path parameters are both available.
+
+## Advertise your methods with OPTIONS
+
+A WebDAV client asks the server about its capabilities with `OPTIONS` before doing anything else. cpp-httplib generates neither the `DAV:` header nor `Allow`, so return them yourself. Forget this and clients will turn you away even though your `PROPFIND` works.
+
+```cpp
+svr.Options("/dav/.*", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_header("DAV", "1");
+  res.set_header("Allow", "OPTIONS, GET, HEAD, PROPFIND, PROPPATCH, MKCOL");
+});
+```
+
+## Read the body as a stream
+
+There is a content reader overload, just like the one on `Post()`. Use it when you would rather not hold a large XML document in memory all at once.
+
+```cpp
+svr.CustomRoute("REPORT", "/dav/.*",
+                [](const httplib::Request &req, httplib::Response &res,
+                   const httplib::ContentReader &content_reader) {
+                  content_reader([&](const char *data, size_t data_length) {
+                    // Process it a chunk at a time
+                    return true;
+                  });
+                  res.status = httplib::StatusCode::MultiStatus_207;
+                });
+```
+
+## Things to keep in mind
+
+- The method name has to be a valid HTTP method token (RFC 9110), and it must be registered before you call `listen()`
+- `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` and `PRI` cannot be registered here. Use the dedicated methods for those
+- A rejected registration makes `is_valid()` return `false` and `listen()` fail, so the server never starts holding a handler that would never run
+- Static file serving and WebSocket upgrades stay `GET`/`HEAD` only
+
+> **Note:** cpp-httplib takes you as far as routing the method. If you want to call it WebDAV, generating the `207 Multi-Status` XML, interpreting the `Depth` header and managing locks are all yours to implement. The protocol itself lives outside the library.
+
+> For the basics of registering handlers, see [S01. Register GET / POST / PUT / DELETE handlers](../s01-handlers).

docs-src/pages/en/cookbook/t01-tls-backends.md

@@ -1,6 +1,6 @@
 ---
 title: "T01. Choosing Between OpenSSL, mbedTLS, and wolfSSL"
-order: 42
+order: 43
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/t02-cert-verification.md

@@ -1,6 +1,6 @@
 ---
 title: "T02. Control SSL Certificate Verification"
-order: 43
+order: 44
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/t03-ssl-server.md

@@ -1,6 +1,6 @@
 ---
 title: "T03. Start an SSL/TLS Server"
-order: 44
+order: 45
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/t04-mtls.md

@@ -1,6 +1,6 @@
 ---
 title: "T04. Configure mTLS"
-order: 45
+order: 46
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/t05-peer-cert.md

@@ -1,6 +1,6 @@
 ---
 title: "T05. Access the Peer Certificate on the Server Side"
-order: 46
+order: 47
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/w01-websocket-echo.md

@@ -1,6 +1,6 @@
 ---
 title: "W01. Implement a WebSocket Echo Server and Client"
-order: 51
+order: 52
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/w02-websocket-ping.md

@@ -1,6 +1,6 @@
 ---
 title: "W02. Set a WebSocket Heartbeat"
-order: 52
+order: 53
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/w03-websocket-close.md

@@ -1,6 +1,6 @@
 ---
 title: "W03. Handle Connection Close"
-order: 53
+order: 54
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/w04-websocket-binary.md

@@ -1,6 +1,6 @@
 ---
 title: "W04. Send and Receive Binary Frames"
-order: 54
+order: 55
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/w05-websocket-tls.md

@@ -1,6 +1,6 @@
 ---
 title: "W05. Configure TLS for wss:// Connections"
-order: 55
+order: 56
 status: "draft"
 ---
 

docs-src/pages/en/cookbook/w06-websocket-timeouts.md

@@ -1,6 +1,6 @@
 ---
 title: "W06. Set Timeouts"
-order: 56
+order: 57
 status: "draft"
 ---