Add Cookbook S01-S22 (draft)

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

@@ -42,36 +42,36 @@ A collection of recipes that answer "How do I...?" questions. Each recipe is sel
 ## Server
 
 ### Basics
-- S01. Register GET / POST / PUT / DELETE handlers
+- [S01. Register GET / POST / PUT / DELETE handlers](s01-handlers)
-- S02. Receive JSON requests and return JSON responses
+- [S02. Receive JSON requests and return JSON responses](s02-json-api)
-- S03. Use path parameters (`/users/:id`)
+- [S03. Use path parameters](s03-path-params)
-- S04. Set up a static file server (`set_mount_point`)
+- [S04. Set up a static file server](s04-static-files)
 
 ### Streaming & Files
-- S05. Stream a large file in the response (`ContentProvider`)
+- [S05. Stream a large file in the response](s05-stream-response)
-- S06. Return a file download response (`Content-Disposition`)
+- [S06. Return a file download response](s06-download-response)
-- S07. Receive multipart data as a stream (`ContentReader`)
+- [S07. Receive multipart data as a stream](s07-multipart-reader)
-- S08. Compress responses (gzip)
+- [S08. Return a compressed response](s08-compress-response)
 
 ### Handler Chain
-- S09. Add pre-processing to all routes (Pre-routing handler)
+- [S09. Add pre-processing to all routes](s09-pre-routing)
-- S10. Add response headers with a Post-routing handler (CORS, etc.)
+- [S10. Add response headers with a post-routing handler](s10-post-routing)
-- S11. Authenticate per route with a Pre-request handler (`matched_route`)
+- [S11. Authenticate per route with a pre-request handler](s11-pre-request)
-- S12. Pass data between handlers with `res.user_data`
+- [S12. Pass data between handlers with `res.user_data`](s12-user-data)
 
 ### Error Handling & Debugging
-- S13. Return custom error pages (`set_error_handler`)
+- [S13. Return custom error pages](s13-error-handler)
-- S14. Catch exceptions (`set_exception_handler`)
+- [S14. Catch exceptions](s14-exception-handler)
-- S15. Log requests (Logger)
+- [S15. Log requests](s15-server-logger)
-- S16. Detect client disconnection (`req.is_connection_closed()`)
+- [S16. Detect client disconnection](s16-disconnect)
 
 ### Operations & Tuning
-- S17. Assign a port dynamically (`bind_to_any_port`)
+- [S17. Bind to any available port](s17-bind-any-port)
-- S18. Control startup order with `listen_after_bind`
+- [S18. Control startup order with `listen_after_bind`](s18-listen-after-bind)
-- S19. Shut down gracefully (`stop()` and signal handling)
+- [S19. Shut down gracefully](s19-graceful-shutdown)
-- S20. Tune Keep-Alive (`set_keep_alive_max_count` / `set_keep_alive_timeout`)
+- [S20. Tune Keep-Alive](s20-keep-alive)
-- S21. Configure the thread pool (`new_task_queue`)
+- [S21. Configure the thread pool](s21-thread-pool)
-- S22. Communicate over Unix domain sockets (`set_address_family(AF_UNIX)`)
+- [S22. Talk over a Unix domain socket](s22-unix-socket)
 
 ## TLS / Security
 

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

@@ -0,0 +1,66 @@
+---
+title: "S01. Register GET / POST / PUT / DELETE Handlers"
+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()`.
+
+## Basic usage
+
+```cpp
+#include <httplib.h>
+
+int main() {
+  httplib::Server svr;
+
+  svr.Get("/hello", [](const httplib::Request &req, httplib::Response &res) {
+    res.set_content("Hello, World!", "text/plain");
+  });
+
+  svr.Post("/api/items", [](const httplib::Request &req, httplib::Response &res) {
+    // req.body holds the request body
+    res.status = 201;
+    res.set_content("Created", "text/plain");
+  });
+
+  svr.Put("/api/items/1", [](const httplib::Request &req, httplib::Response &res) {
+    res.set_content("Updated", "text/plain");
+  });
+
+  svr.Delete("/api/items/1", [](const httplib::Request &req, httplib::Response &res) {
+    res.status = 204;
+  });
+
+  svr.listen("0.0.0.0", 8080);
+}
+```
+
+Handlers take `(const Request&, Response&)`. Use `res.set_content()` to set the body and Content-Type, and `res.status` for the status code. `listen()` starts the server and blocks.
+
+## Read query parameters
+
+```cpp
+svr.Get("/search", [](const httplib::Request &req, httplib::Response &res) {
+  auto q = req.get_param_value("q");
+  auto limit = req.get_param_value("limit");
+  res.set_content("q=" + q + ", limit=" + limit, "text/plain");
+});
+```
+
+`req.get_param_value()` pulls a value from the query string. Use `req.has_param("q")` if you want to check existence first.
+
+## Read request headers
+
+```cpp
+svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
+  auto ua = req.get_header_value("User-Agent");
+  res.set_content("UA: " + ua, "text/plain");
+});
+```
+
+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`.
+
+> To use path parameters like `/users/:id`, see S03. Use Path Parameters.

docs-src/pages/en/cookbook/s02-json-api.md

@@ -0,0 +1,74 @@
+---
+title: "S02. Receive a JSON Request and Return a JSON Response"
+order: 21
+status: "draft"
+---
+
+cpp-httplib doesn't include a JSON parser. On the server side, combine it with something like [nlohmann/json](https://github.com/nlohmann/json). The examples below use `nlohmann/json`.
+
+## Receive and return JSON
+
+```cpp
+#include <httplib.h>
+#include <nlohmann/json.hpp>
+
+int main() {
+  httplib::Server svr;
+
+  svr.Post("/api/users", [](const httplib::Request &req, httplib::Response &res) {
+    try {
+      auto in = nlohmann::json::parse(req.body);
+
+      nlohmann::json out = {
+        {"id", 42},
+        {"name", in["name"]},
+        {"created_at", "2026-04-10T12:00:00Z"},
+      };
+
+      res.status = 201;
+      res.set_content(out.dump(), "application/json");
+    } catch (const std::exception &e) {
+      res.status = 400;
+      res.set_content("{\"error\":\"invalid json\"}", "application/json");
+    }
+  });
+
+  svr.listen("0.0.0.0", 8080);
+}
+```
+
+`req.body` is a plain `std::string`, so you pass it straight to your JSON library. For the response, `dump()` to a string and set the Content-Type to `application/json`.
+
+## Check the Content-Type
+
+```cpp
+svr.Post("/api/users", [](const httplib::Request &req, httplib::Response &res) {
+  auto content_type = req.get_header_value("Content-Type");
+  if (content_type.find("application/json") == std::string::npos) {
+    res.status = 415; // Unsupported Media Type
+    return;
+  }
+  // ...
+});
+```
+
+When you strictly want JSON only, verify the Content-Type up front.
+
+## A helper for JSON responses
+
+If you're writing the same pattern repeatedly, a small helper saves typing.
+
+```cpp
+auto send_json = [](httplib::Response &res, int status, const nlohmann::json &j) {
+  res.status = status;
+  res.set_content(j.dump(), "application/json");
+};
+
+svr.Get("/api/health", [&](const auto &req, auto &res) {
+  send_json(res, 200, {{"status", "ok"}});
+});
+```
+
+> **Note:** A large JSON body ends up entirely in `req.body`, which means it all sits in memory. For huge payloads, consider streaming reception — see S07. Receive Multipart Data as a Stream.
+
+> For the client side, see C02. Send and Receive JSON.

docs-src/pages/en/cookbook/s03-path-params.md

@@ -0,0 +1,53 @@
+---
+title: "S03. Use Path Parameters"
+order: 22
+status: "draft"
+---
+
+For dynamic URLs like `/users/:id` — the staple of REST APIs — just put `:name` in the path pattern. The matched values end up in `req.path_params`.
+
+## Basic usage
+
+```cpp
+svr.Get("/users/:id", [](const httplib::Request &req, httplib::Response &res) {
+  auto id = req.path_params.at("id");
+  res.set_content("user id: " + id, "text/plain");
+});
+```
+
+A request to `/users/42` fills `req.path_params["id"]` with `"42"`. `path_params` is a `std::unordered_map<std::string, std::string>`, so use `at()` to read it.
+
+## Multiple parameters
+
+You can have as many as you need.
+
+```cpp
+svr.Get("/orgs/:org/repos/:repo", [](const httplib::Request &req, httplib::Response &res) {
+  auto org = req.path_params.at("org");
+  auto repo = req.path_params.at("repo");
+  res.set_content(org + "/" + repo, "text/plain");
+});
+```
+
+This matches paths like `/orgs/anthropic/repos/cpp-httplib`.
+
+## Regex patterns
+
+For more flexible matching, use a `std::regex`-based pattern.
+
+```cpp
+svr.Get(R"(/users/(\d+))", [](const httplib::Request &req, httplib::Response &res) {
+  auto id = req.matches[1];
+  res.set_content("user id: " + std::string(id), "text/plain");
+});
+```
+
+Parentheses in the pattern become captures in `req.matches`. `req.matches[0]` is the full match; `req.matches[1]` onward are the captures.
+
+## Which to use
+
+- For plain IDs or slugs, `:name` is enough — readable, and the shape is obvious
+- Use regex when you want to constrain the URL to, say, numbers only or a UUID format
+- Mixing both can get confusing — stick with one style per project
+
+> **Note:** Path parameters come in as strings. If you need an integer, convert with `std::stoi()` and don't forget to handle conversion errors.

docs-src/pages/en/cookbook/s04-static-files.md

@@ -0,0 +1,55 @@
+---
+title: "S04. Serve Static Files"
+order: 23
+status: "draft"
+---
+
+To serve static files like HTML, CSS, and images, use `set_mount_point()`. Just map a URL path to a local directory, and the whole directory becomes accessible.
+
+## Basic usage
+
+```cpp
+httplib::Server svr;
+svr.set_mount_point("/", "./public");
+svr.listen("0.0.0.0", 8080);
+```
+
+`./public/index.html` is now reachable at `http://localhost:8080/index.html`, and `./public/css/style.css` at `http://localhost:8080/css/style.css`. The directory layout maps directly to URLs.
+
+## Multiple mount points
+
+You can register more than one mount point.
+
+```cpp
+svr.set_mount_point("/", "./public");
+svr.set_mount_point("/assets", "./dist/assets");
+svr.set_mount_point("/uploads", "./var/uploads");
+```
+
+You can even mount multiple directories at the same path — they're searched in registration order, and the first hit wins.
+
+## Combine with API handlers
+
+Static files and API handlers coexist happily. Handlers registered with `Get()` and friends take priority; the mount points are searched only when nothing matches.
+
+```cpp
+svr.Get("/api/users", [](const auto &req, auto &res) {
+  res.set_content("[]", "application/json");
+});
+
+svr.set_mount_point("/", "./public");
+```
+
+This gives you an SPA-friendly setup: `/api/*` hits the handlers, everything else is served from `./public/`.
+
+## Add MIME types
+
+cpp-httplib ships with a built-in extension-to-Content-Type map, but you can add your own.
+
+```cpp
+svr.set_file_extension_and_mimetype_mapping("wasm", "application/wasm");
+```
+
+> **Warning:** The static file server methods are **not thread-safe**. Don't call them after `listen()` — configure everything before starting the server.
+
+> For download-style responses, see S06. Return a File Download Response.

docs-src/pages/en/cookbook/s05-stream-response.md

@@ -0,0 +1,63 @@
+---
+title: "S05. Stream a Large File in the Response"
+order: 24
+status: "draft"
+---
+
+When the response is a huge file or data generated on the fly, loading the whole thing into memory isn't realistic. Use `Response::set_content_provider()` to produce data in chunks as you send it.
+
+## When the size is known
+
+```cpp
+svr.Get("/download", [](const httplib::Request &req, httplib::Response &res) {
+  size_t total_size = get_file_size("large.bin");
+
+  res.set_content_provider(
+    total_size, "application/octet-stream",
+    [](size_t offset, size_t length, httplib::DataSink &sink) {
+      auto data = read_range_from_file("large.bin", offset, length);
+      sink.write(data.data(), data.size());
+      return true;
+    });
+});
+```
+
+The lambda is called repeatedly with `offset` and `length`. Read just that range and write it to `sink`. Only a small chunk sits in memory at any given time.
+
+## Just send a file
+
+If you only want to serve a file, `set_file_content()` is far simpler.
+
+```cpp
+svr.Get("/download", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_file_content("large.bin", "application/octet-stream");
+});
+```
+
+It streams internally, so even huge files are safe. Omit the Content-Type and it's guessed from the extension.
+
+## When the size is unknown — chunked transfer
+
+For data generated on the fly, where you don't know the total size up front, use `set_chunked_content_provider()`. It's sent with HTTP chunked transfer encoding.
+
+```cpp
+svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_chunked_content_provider(
+    "text/plain",
+    [](size_t offset, httplib::DataSink &sink) {
+      auto chunk = produce_next_chunk();
+      if (chunk.empty()) {
+        sink.done(); // done sending
+        return true;
+      }
+      sink.write(chunk.data(), chunk.size());
+      return true;
+    });
+});
+```
+
+Call `sink.done()` to signal the end.
+
+> **Note:** The provider lambda is called multiple times. Watch out for the lifetime of captured variables — wrap them in a `std::shared_ptr` if needed.
+
+> To serve the file as a download, see S06. Return a File Download Response.

docs-src/pages/en/cookbook/s06-download-response.md

@@ -0,0 +1,50 @@
+---
+title: "S06. Return a File Download Response"
+order: 25
+status: "draft"
+---
+
+To force a browser to show a **download dialog** instead of rendering inline, send a `Content-Disposition` header. There's no special cpp-httplib API for this — it's just a header.
+
+## Basic usage
+
+```cpp
+svr.Get("/download/report", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_header("Content-Disposition", "attachment; filename=\"report.pdf\"");
+  res.set_file_content("reports/2026-04.pdf", "application/pdf");
+});
+```
+
+`Content-Disposition: attachment` makes the browser pop up a "Save As" dialog. The `filename=` parameter becomes the default save name.
+
+## Non-ASCII file names
+
+For file names with non-ASCII characters or spaces, use the RFC 5987 `filename*` form.
+
+```cpp
+svr.Get("/download/report", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_header(
+    "Content-Disposition",
+    "attachment; filename=\"report.pdf\"; "
+    "filename*=UTF-8''%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88.pdf");
+  res.set_file_content("reports/2026-04.pdf", "application/pdf");
+});
+```
+
+The part after `filename*=UTF-8''` is URL-encoded UTF-8. Keep the ASCII `filename=` too, as a fallback for older browsers.
+
+## Download dynamically generated data
+
+You don't need a real file — you can serve a generated string as a download directly.
+
+```cpp
+svr.Get("/export.csv", [](const httplib::Request &req, httplib::Response &res) {
+  std::string csv = build_csv();
+  res.set_header("Content-Disposition", "attachment; filename=\"export.csv\"");
+  res.set_content(csv, "text/csv");
+});
+```
+
+This is the classic pattern for CSV exports.
+
+> **Note:** Some browsers will trigger a download based on Content-Type alone, even without `Content-Disposition`. Conversely, setting `inline` tries to render the content in the browser when possible.

docs-src/pages/en/cookbook/s07-multipart-reader.md

@@ -0,0 +1,71 @@
+---
+title: "S07. Receive Multipart Data as a Stream"
+order: 26
+status: "draft"
+---
+
+A naive upload handler puts the whole request into `req.body`, which blows up memory for large files. Use `HandlerWithContentReader` to receive the body chunk by chunk.
+
+## Basic usage
+
+```cpp
+svr.Post("/upload",
+  [](const httplib::Request &req, httplib::Response &res,
+     const httplib::ContentReader &content_reader) {
+    if (req.is_multipart_form_data()) {
+      content_reader(
+        // headers of each part
+        [&](const httplib::FormData &file) {
+          std::cout << "name: " << file.name
+                    << ", filename: " << file.filename << std::endl;
+          return true;
+        },
+        // body of each part (called multiple times)
+        [&](const char *data, size_t len) {
+          // write to disk here, for example
+          return true;
+        });
+    } else {
+      // plain request body
+      content_reader([&](const char *data, size_t len) {
+        return true;
+      });
+    }
+
+    res.set_content("ok", "text/plain");
+  });
+```
+
+The `content_reader` has two call shapes. For multipart data, pass two callbacks (one for headers, one for body). For plain bodies, pass just one.
+
+## Write directly to disk
+
+Here's how to stream an uploaded file to disk.
+
+```cpp
+svr.Post("/upload",
+  [](const httplib::Request &req, httplib::Response &res,
+     const httplib::ContentReader &content_reader) {
+    std::ofstream ofs;
+
+    content_reader(
+      [&](const httplib::FormData &file) {
+        if (!file.filename.empty()) {
+          ofs.open("uploads/" + file.filename, std::ios::binary);
+        }
+        return static_cast<bool>(ofs);
+      },
+      [&](const char *data, size_t len) {
+        ofs.write(data, len);
+        return static_cast<bool>(ofs);
+      });
+
+    res.set_content("uploaded", "text/plain");
+  });
+```
+
+Only a small chunk sits in memory at any moment, so gigabyte-scale files are no problem.
+
+> **Warning:** When you use `HandlerWithContentReader`, `req.body` stays **empty**. Handle the body yourself inside the callbacks.
+
+> For the client side of multipart uploads, see C07. Upload a File as Multipart Form Data.

docs-src/pages/en/cookbook/s08-compress-response.md

@@ -0,0 +1,53 @@
+---
+title: "S08. Return a Compressed Response"
+order: 27
+status: "draft"
+---
+
+cpp-httplib automatically compresses response bodies when the client indicates support via `Accept-Encoding`. The handler doesn't need to do anything special. Supported encodings are gzip, Brotli, and Zstd.
+
+## Build-time setup
+
+To enable compression, define the relevant macros before including `httplib.h`:
+
+```cpp
+#define CPPHTTPLIB_ZLIB_SUPPORT     // gzip
+#define CPPHTTPLIB_BROTLI_SUPPORT   // brotli
+#define CPPHTTPLIB_ZSTD_SUPPORT     // zstd
+#include <httplib.h>
+```
+
+You'll also need to link `zlib`, `brotli`, and `zstd` respectively. Enable only what you need.
+
+## Usage
+
+```cpp
+svr.Get("/api/data", [](const httplib::Request &req, httplib::Response &res) {
+  std::string body = build_large_response();
+  res.set_content(body, "application/json");
+});
+```
+
+That's it. If the client sent `Accept-Encoding: gzip`, cpp-httplib compresses the response with gzip automatically. `Content-Encoding: gzip` and `Vary: Accept-Encoding` are added for you.
+
+## Encoding priority
+
+When the client accepts multiple encodings, cpp-httplib picks in this order (among those enabled at build time): Brotli → Zstd → gzip. Your code doesn't need to care — you always get the most efficient option available.
+
+## Streaming responses are compressed too
+
+Streaming responses via `set_chunked_content_provider()` get the same automatic compression.
+
+```cpp
+svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_chunked_content_provider(
+    "text/plain",
+    [](size_t offset, httplib::DataSink &sink) {
+      // ...
+    });
+});
+```
+
+> **Note:** Tiny responses barely benefit from compression and just waste CPU time. cpp-httplib skips compression for bodies that are too small to bother with.
+
+> For the client-side counterpart, see C15. Enable Compression.

docs-src/pages/en/cookbook/s09-pre-routing.md

@@ -0,0 +1,54 @@
+---
+title: "S09. Add Pre-Processing to All Routes"
+order: 28
+status: "draft"
+---
+
+Sometimes you want the same logic to run before every request — auth checks, logging, rate limiting. Register those with `set_pre_routing_handler()`.
+
+## Basic usage
+
+```cpp
+svr.set_pre_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    std::cout << req.method << " " << req.path << std::endl;
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+```
+
+The pre-routing handler runs **before routing**. It catches every request — including ones that don't match any handler.
+
+The `HandlerResponse` return value is key:
+
+- Return `Unhandled` → continue normally (routing and the actual handler run)
+- Return `Handled` → the response is considered complete, skip the rest
+
+## Use it for authentication
+
+Put your shared auth check in one place.
+
+```cpp
+svr.set_pre_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    if (req.path.rfind("/public", 0) == 0) {
+      return httplib::Server::HandlerResponse::Unhandled; // no auth needed
+    }
+
+    auto auth = req.get_header_value("Authorization");
+    if (auth.empty()) {
+      res.status = 401;
+      res.set_content("unauthorized", "text/plain");
+      return httplib::Server::HandlerResponse::Handled;
+    }
+
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+```
+
+If auth fails, return `Handled` to respond with 401 immediately. If it passes, return `Unhandled` and let routing take over.
+
+## For per-route auth
+
+If you want different auth rules per route rather than a single global check, `set_pre_request_handler()` is a better fit. See S11. Authenticate Per Route with a Pre-Request Handler.
+
+> **Note:** If all you want is to modify the response, `set_post_routing_handler()` is the right tool. See S10. Add Response Headers with a Post-Routing Handler.

docs-src/pages/en/cookbook/s10-post-routing.md

@@ -0,0 +1,56 @@
+---
+title: "S10. Add Response Headers with a Post-Routing Handler"
+order: 29
+status: "draft"
+---
+
+Sometimes you want to add shared headers to the response after the handler has run — CORS headers, security headers, a request ID, and so on. That's what `set_post_routing_handler()` is for.
+
+## Basic usage
+
+```cpp
+svr.set_post_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    res.set_header("X-Request-ID", generate_request_id());
+  });
+```
+
+The post-routing handler runs **after the route handler, before the response is sent**. From here you can call `res.set_header()` or `res.headers.erase()` to add or remove headers across every response in one place.
+
+## Add CORS headers
+
+CORS is a classic use case.
+
+```cpp
+svr.set_post_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    res.set_header("Access-Control-Allow-Origin", "*");
+    res.set_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.set_header("Access-Control-Allow-Headers", "Content-Type, Authorization");
+  });
+```
+
+For the preflight `OPTIONS` requests, register a separate handler — or handle them in the pre-routing handler.
+
+```cpp
+svr.Options("/.*", [](const auto &req, auto &res) {
+  res.status = 204;
+});
+```
+
+## Bundle your security headers
+
+Manage browser security headers in one spot.
+
+```cpp
+svr.set_post_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    res.set_header("X-Content-Type-Options", "nosniff");
+    res.set_header("X-Frame-Options", "DENY");
+    res.set_header("Referrer-Policy", "strict-origin-when-cross-origin");
+  });
+```
+
+No matter which handler produced the response, the same headers get attached.
+
+> **Note:** The post-routing handler also runs for responses that didn't match any route and for responses from error handlers. That's exactly what you want when you need certain headers on every response, guaranteed.

docs-src/pages/en/cookbook/s11-pre-request.md

@@ -0,0 +1,47 @@
+---
+title: "S11. Authenticate Per Route with a Pre-Request Handler"
+order: 30
+status: "draft"
+---
+
+The `set_pre_routing_handler()` from S09 runs **before routing**, so it has no idea which route matched. When you want per-route behavior, `set_pre_request_handler()` is what you need.
+
+## Pre-routing vs. pre-request
+
+| Hook | When it runs | Route info |
+| --- | --- | --- |
+| `set_pre_routing_handler` | Before routing | Not available |
+| `set_pre_request_handler` | After routing, right before the route handler | Available via `req.matched_route` |
+
+In a pre-request handler, `req.matched_route` holds the **pattern string** that matched. You can vary behavior based on the route definition itself.
+
+## Switch auth per route
+
+```cpp
+svr.set_pre_request_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    // require auth for routes starting with /admin
+    if (req.matched_route.rfind("/admin", 0) == 0) {
+      auto token = req.get_header_value("Authorization");
+      if (!is_admin_token(token)) {
+        res.status = 403;
+        res.set_content("forbidden", "text/plain");
+        return httplib::Server::HandlerResponse::Handled;
+      }
+    }
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+```
+
+`matched_route` is the pattern **before** path parameters are expanded (e.g. `/admin/users/:id`). You compare against the route definition, not the actual request path, so IDs or names don't throw you off.
+
+## Return values
+
+Same as pre-routing — return `HandlerResponse`.
+
+- `Unhandled`: continue (the route handler runs)
+- `Handled`: we're done, skip the route handler
+
+## Passing auth info to the route handler
+
+To pass decoded user info into the route handler, use `res.user_data`. See S12. Pass Data Between Handlers with `res.user_data`.

docs-src/pages/en/cookbook/s12-user-data.md

@@ -0,0 +1,56 @@
+---
+title: "S12. Pass Data Between Handlers with res.user_data"
+order: 31
+status: "draft"
+---
+
+Say your pre-request handler decodes an auth token and you want the route handler to use the result. That "data handoff between handlers" is what `res.user_data` is for — it holds values of arbitrary types.
+
+## Basic usage
+
+```cpp
+struct AuthUser {
+  std::string id;
+  std::string name;
+  bool is_admin;
+};
+
+svr.set_pre_request_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    auto token = req.get_header_value("Authorization");
+    auto user = decode_token(token); // decode the auth token
+    res.user_data.set("user", user);
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+
+svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
+  auto *user = res.user_data.get<AuthUser>("user");
+  if (!user) {
+    res.status = 401;
+    return;
+  }
+  res.set_content("Hello, " + user->name, "text/plain");
+});
+```
+
+`user_data.set()` stores a value of any type, and `user_data.get<T>()` retrieves it. If you give the wrong type you get `nullptr` back — so be careful.
+
+## Typical value types
+
+Strings, numbers, structs, `std::shared_ptr` — anything copyable or movable works.
+
+```cpp
+res.user_data.set("user_id", std::string{"42"});
+res.user_data.set("is_admin", true);
+res.user_data.set("started_at", std::chrono::steady_clock::now());
+```
+
+## Where to set, where to read
+
+The usual flow is: set it in `set_pre_routing_handler()` or `set_pre_request_handler()`, read it in the route handler. Pre-request runs after routing, so you can combine it with `req.matched_route` to set values only for specific routes.
+
+## A gotcha
+
+`user_data` lives on `Response`, not `Request`. That's because handlers get `Response&` (mutable) but only `const Request&`. It looks odd at first, but it makes sense once you think of it as "the mutable context shared between handlers."
+
+> **Warning:** `user_data.get<T>()` returns `nullptr` when the type doesn't match. Use the exact same type on set and get. Storing as `AuthUser` and fetching as `const AuthUser` won't work.

docs-src/pages/en/cookbook/s13-error-handler.md

@@ -0,0 +1,51 @@
+---
+title: "S13. Return a Custom Error Page"
+order: 32
+status: "draft"
+---
+
+To customize the response for 4xx or 5xx errors, use `set_error_handler()`. You can replace the plain default error page with your own HTML or JSON.
+
+## Basic usage
+
+```cpp
+svr.set_error_handler([](const httplib::Request &req, httplib::Response &res) {
+  auto body = "<h1>Error " + std::to_string(res.status) + "</h1>";
+  res.set_content(body, "text/html");
+});
+```
+
+The error handler runs right before an error response is sent — any time `res.status` is 4xx or 5xx. Replace the body with `res.set_content()` and every error response uses the same template.
+
+## Branch by status code
+
+```cpp
+svr.set_error_handler([](const httplib::Request &req, httplib::Response &res) {
+  if (res.status == 404) {
+    res.set_content("<h1>Not Found</h1><p>" + req.path + "</p>", "text/html");
+  } else if (res.status >= 500) {
+    res.set_content("<h1>Server Error</h1>", "text/html");
+  }
+});
+```
+
+Checking `res.status` lets you show a custom message for 404s and a "contact support" link for 5xx errors.
+
+## JSON error responses
+
+For an API server, you probably want errors as JSON.
+
+```cpp
+svr.set_error_handler([](const httplib::Request &req, httplib::Response &res) {
+  nlohmann::json j = {
+    {"error", true},
+    {"status", res.status},
+    {"path", req.path},
+  };
+  res.set_content(j.dump(), "application/json");
+});
+```
+
+Now every error comes back in a consistent JSON shape.
+
+> **Note:** `set_error_handler()` also fires for 500 responses caused by exceptions thrown from a route handler. To get at the exception itself, combine it with `set_exception_handler()`. See S14. Catch Exceptions.

docs-src/pages/en/cookbook/s14-exception-handler.md

@@ -0,0 +1,67 @@
+---
+title: "S14. Catch Exceptions"
+order: 33
+status: "draft"
+---
+
+When a route handler throws, cpp-httplib keeps the server running and responds with 500. By default, though, very little of the error information reaches the client. `set_exception_handler()` lets you intercept exceptions and build your own response.
+
+## Basic usage
+
+```cpp
+svr.set_exception_handler(
+  [](const httplib::Request &req, httplib::Response &res,
+     std::exception_ptr ep) {
+    try {
+      std::rethrow_exception(ep);
+    } catch (const std::exception &e) {
+      res.status = 500;
+      res.set_content(std::string("error: ") + e.what(), "text/plain");
+    } catch (...) {
+      res.status = 500;
+      res.set_content("unknown error", "text/plain");
+    }
+  });
+```
+
+The handler receives a `std::exception_ptr`. The idiomatic move is to rethrow it with `std::rethrow_exception()` and catch by type. You can vary status code and message based on the exception type.
+
+## Branch on custom exception types
+
+If you throw your own exception types, you can map them to 400 or 404 responses.
+
+```cpp
+struct NotFound : std::runtime_error {
+  using std::runtime_error::runtime_error;
+};
+struct BadRequest : std::runtime_error {
+  using std::runtime_error::runtime_error;
+};
+
+svr.set_exception_handler(
+  [](const auto &req, auto &res, std::exception_ptr ep) {
+    try {
+      std::rethrow_exception(ep);
+    } catch (const NotFound &e) {
+      res.status = 404;
+      res.set_content(e.what(), "text/plain");
+    } catch (const BadRequest &e) {
+      res.status = 400;
+      res.set_content(e.what(), "text/plain");
+    } catch (const std::exception &e) {
+      res.status = 500;
+      res.set_content("internal error", "text/plain");
+    }
+  });
+```
+
+Now throwing `NotFound("user not found")` inside a handler is enough to return 404. No per-handler try/catch needed.
+
+## Relationship with set_error_handler
+
+`set_exception_handler()` runs the moment the exception is thrown. After that, if `res.status` is 4xx or 5xx, `set_error_handler()` also runs. The order is `exception_handler` → `error_handler`. Think of their roles as:
+
+- **Exception handler**: interpret the exception, set the status and message
+- **Error handler**: see the status and wrap it in the shared template
+
+> **Note:** Without an exception handler, cpp-httplib returns a default 500 response and the exception details never make it to logs. Always set one for anything you want to debug.

docs-src/pages/en/cookbook/s15-server-logger.md

@@ -0,0 +1,64 @@
+---
+title: "S15. Log Requests on the Server"
+order: 34
+status: "draft"
+---
+
+To log the requests the server receives and the responses it returns, use `Server::set_logger()`. The callback fires once per completed request, making it the foundation for access logs and metrics collection.
+
+## Basic usage
+
+```cpp
+svr.set_logger([](const httplib::Request &req, const httplib::Response &res) {
+  std::cout << req.remote_addr << " "
+            << req.method << " " << req.path
+            << " -> " << res.status << std::endl;
+});
+```
+
+The log callback receives both the `Request` and the `Response`. You can grab the method, path, status, client IP, headers, body — whatever you need.
+
+## Access-log style format
+
+Here's an Apache/Nginx-ish access log format.
+
+```cpp
+svr.set_logger([](const auto &req, const auto &res) {
+  auto now = std::time(nullptr);
+  char timebuf[32];
+  std::strftime(timebuf, sizeof(timebuf), "%Y-%m-%d %H:%M:%S",
+                std::localtime(&now));
+
+  std::cout << timebuf << " "
+            << req.remote_addr << " "
+            << "\"" << req.method << " " << req.path << "\" "
+            << res.status << " "
+            << res.body.size() << "B"
+            << std::endl;
+});
+```
+
+## Measure request time
+
+To include request duration in the log, stash a start timestamp in `res.user_data` from a pre-routing handler, then subtract in the logger.
+
+```cpp
+svr.set_pre_routing_handler([](const auto &req, auto &res) {
+  res.user_data.set("start", std::chrono::steady_clock::now());
+  return httplib::Server::HandlerResponse::Unhandled;
+});
+
+svr.set_logger([](const auto &req, const auto &res) {
+  auto *start = res.user_data.get<std::chrono::steady_clock::time_point>("start");
+  auto elapsed = start
+    ? std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now() - *start).count()
+    : 0;
+  std::cout << req.method << " " << req.path
+            << " " << res.status << " " << elapsed << "ms" << std::endl;
+});
+```
+
+For more on `user_data`, see S12. Pass Data Between Handlers with `res.user_data`.
+
+> **Note:** The logger runs synchronously on the same thread as request processing. Heavy work inside it hurts throughput — push it to a queue and process asynchronously if you need anything expensive.

docs-src/pages/en/cookbook/s16-disconnect.md

@@ -0,0 +1,55 @@
+---
+title: "S16. Detect When the Client Has Disconnected"
+order: 35
+status: "draft"
+---
+
+During a long-running response, the client might close the connection. There's no point continuing to do work no one's waiting for. In cpp-httplib, check `req.is_connection_closed()`.
+
+## Basic usage
+
+```cpp
+svr.Get("/long-task", [](const httplib::Request &req, httplib::Response &res) {
+  for (int i = 0; i < 1000; ++i) {
+    if (req.is_connection_closed()) {
+      std::cout << "client disconnected" << std::endl;
+      return;
+    }
+
+    do_heavy_work(i);
+  }
+
+  res.set_content("done", "text/plain");
+});
+```
+
+`is_connection_closed` is a `std::function<bool()>`, so call it with `()`. It returns `true` when the client is gone.
+
+## With a streaming response
+
+The same check works inside `set_chunked_content_provider()`. Capture the request by reference.
+
+```cpp
+svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_chunked_content_provider(
+    "text/event-stream",
+    [&req](size_t offset, httplib::DataSink &sink) {
+      if (req.is_connection_closed()) {
+        sink.done();
+        return true;
+      }
+
+      auto event = generate_next_event();
+      sink.write(event.data(), event.size());
+      return true;
+    });
+});
+```
+
+When you detect a disconnect, call `sink.done()` to stop the provider from being called again.
+
+## How often should you check?
+
+The call itself is cheap, but calling it in a tight inner loop doesn't add much value. Check at **boundaries where interrupting is safe** — after producing a chunk, after a database query, etc.
+
+> **Warning:** `is_connection_closed()` is not guaranteed to reflect reality instantly. Because of how TCP works, sometimes you only notice the disconnect when you try to send. Don't expect pixel-perfect real-time detection — think of it as "we'll notice eventually."

docs-src/pages/en/cookbook/s17-bind-any-port.md

@@ -0,0 +1,52 @@
+---
+title: "S17. Bind to Any Available Port"
+order: 36
+status: "draft"
+---
+
+Standing up a test server often hits port conflicts. With `bind_to_any_port()`, you let the OS pick a free port and then read back which one it gave you.
+
+## Basic usage
+
+```cpp
+httplib::Server svr;
+
+svr.Get("/", [](const auto &req, auto &res) {
+  res.set_content("hello", "text/plain");
+});
+
+int port = svr.bind_to_any_port("0.0.0.0");
+std::cout << "listening on port " << port << std::endl;
+
+svr.listen_after_bind();
+```
+
+`bind_to_any_port()` is equivalent to passing `0` as the port — the OS assigns a free one. The return value is the port actually used.
+
+After that, call `listen_after_bind()` to start accepting. You can't combine bind and listen into a single call here, so you work in two steps.
+
+## Useful in tests
+
+This pattern is great for tests that spin up a server and hit it.
+
+```cpp
+httplib::Server svr;
+svr.Get("/ping", [](const auto &, auto &res) { res.set_content("pong", "text/plain"); });
+
+int port = svr.bind_to_any_port("127.0.0.1");
+std::thread t([&] { svr.listen_after_bind(); });
+
+// run the test while the server is up on another thread
+httplib::Client cli("127.0.0.1", port);
+auto res = cli.Get("/ping");
+assert(res && res->body == "pong");
+
+svr.stop();
+t.join();
+```
+
+Because the port is assigned at runtime, parallel test runs don't collide.
+
+> **Note:** `bind_to_any_port()` returns `-1` on failure (permission errors, no available ports, etc.). Always check the return value.
+
+> To stop the server, see S19. Shut Down Gracefully.

docs-src/pages/en/cookbook/s18-listen-after-bind.md

@@ -0,0 +1,57 @@
+---
+title: "S18. Control Startup Order with listen_after_bind"
+order: 37
+status: "draft"
+---
+
+Normally `svr.listen("0.0.0.0", 8080)` handles bind and listen in one shot. When you need to do something between the two, split them into two calls.
+
+## Separate bind and listen
+
+```cpp
+httplib::Server svr;
+
+svr.Get("/", [](const auto &, auto &res) { res.set_content("ok", "text/plain"); });
+
+if (!svr.bind_to_port("0.0.0.0", 8080)) {
+  std::cerr << "bind failed" << std::endl;
+  return 1;
+}
+
+// bind is done here. accept hasn't started yet.
+drop_privileges();
+signal_ready_to_parent_process();
+
+svr.listen_after_bind(); // start the accept loop
+```
+
+`bind_to_port()` reserves the port; `listen_after_bind()` actually starts accepting. Splitting them gives you a window between the two steps.
+
+## Common use cases
+
+**Privilege drop**: Binding to a port under 1024 requires root. Bind as root, drop to a normal user, and all subsequent request handling runs with reduced privileges.
+
+```cpp
+svr.bind_to_port("0.0.0.0", 80);
+drop_privileges();
+svr.listen_after_bind();
+```
+
+**Startup notification**: Tell the parent process or systemd "I'm ready" before starting to accept connections.
+
+**Test synchronization**: In tests, you can reliably catch "the moment the server is bound" and start the client after that.
+
+## Check the return values
+
+`bind_to_port()` returns `false` on failure — typically when the port is already taken. Always check it.
+
+```cpp
+if (!svr.bind_to_port("0.0.0.0", 8080)) {
+  std::cerr << "port already in use" << std::endl;
+  return 1;
+}
+```
+
+`listen_after_bind()` blocks until the server stops and returns `true` on a clean shutdown.
+
+> **Note:** To auto-pick a free port, see S17. Bind to Any Available Port. Under the hood, that's just `bind_to_any_port()` + `listen_after_bind()`.

docs-src/pages/en/cookbook/s19-graceful-shutdown.md

@@ -0,0 +1,57 @@
+---
+title: "S19. Shut Down Gracefully"
+order: 38
+status: "draft"
+---
+
+To stop the server, call `Server::stop()`. It's safe to call even while requests are in flight, so you can wire it to SIGINT or SIGTERM for a graceful shutdown.
+
+## Basic usage
+
+```cpp
+httplib::Server svr;
+
+svr.Get("/", [](const auto &, auto &res) { res.set_content("ok", "text/plain"); });
+
+std::thread t([&] { svr.listen("0.0.0.0", 8080); });
+
+// wait for input on the main thread, or whatever
+std::cin.get();
+
+svr.stop();
+t.join();
+```
+
+`listen()` blocks, so the typical pattern is: run the server on a background thread and call `stop()` from the main thread. After `stop()`, `listen()` returns and you can `join()`.
+
+## Shut down on a signal
+
+Here's how to stop the server on SIGINT (Ctrl+C) or SIGTERM.
+
+```cpp
+#include <csignal>
+
+httplib::Server svr;
+
+// global so the signal handler can reach it
+httplib::Server *g_svr = nullptr;
+
+int main() {
+  svr.Get("/", [](const auto &, auto &res) { res.set_content("ok", "text/plain"); });
+
+  g_svr = &svr;
+  std::signal(SIGINT,  [](int) { if (g_svr) g_svr->stop(); });
+  std::signal(SIGTERM, [](int) { if (g_svr) g_svr->stop(); });
+
+  svr.listen("0.0.0.0", 8080);
+  std::cout << "server stopped" << std::endl;
+}
+```
+
+`stop()` is thread-safe and signal-safe — you can call it from a signal handler. Even when `listen()` is running on the main thread, the signal pulls it out cleanly.
+
+## What happens to in-flight requests
+
+When you call `stop()`, new connections are refused, but requests already being processed are **allowed to finish**. Once all workers drain, `listen()` returns. That's what makes it graceful.
+
+> **Warning:** There's a wait between calling `stop()` and `listen()` returning — it's the time in-flight requests take to finish. To enforce a timeout, you'll need to add your own shutdown timer in application code.

docs-src/pages/en/cookbook/s20-keep-alive.md

@@ -0,0 +1,57 @@
+---
+title: "S20. Tune Keep-Alive"
+order: 39
+status: "draft"
+---
+
+`httplib::Server` enables HTTP/1.1 Keep-Alive automatically. From the client's perspective, connections are reused — so they don't pay the TCP handshake cost on every request. When you need to tune the behavior, there are two setters.
+
+## What you can configure
+
+| API | Default | Meaning |
+| --- | --- | --- |
+| `set_keep_alive_max_count` | 100 | Max requests served over a single connection |
+| `set_keep_alive_timeout` | 5s | How long an idle connection is kept before closing |
+
+## Basic usage
+
+```cpp
+httplib::Server svr;
+
+svr.set_keep_alive_max_count(20);
+svr.set_keep_alive_timeout(10); // 10 seconds
+
+svr.listen("0.0.0.0", 8080);
+```
+
+`set_keep_alive_timeout()` also has a `std::chrono` overload.
+
+```cpp
+using namespace std::chrono_literals;
+svr.set_keep_alive_timeout(10s);
+```
+
+## Tuning ideas
+
+**Too many idle connections eating resources**  
+Shorten the timeout so idle connections drop and release their worker threads.
+
+```cpp
+svr.set_keep_alive_timeout(2s);
+```
+
+**API is hammered and you want max reuse**  
+Raising the per-connection request cap improves benchmark numbers.
+
+```cpp
+svr.set_keep_alive_max_count(1000);
+```
+
+**Never reuse connections**  
+Set `set_keep_alive_max_count(1)` and every request gets its own connection. Mostly only useful for debugging or compatibility testing.
+
+## Relationship with the thread pool
+
+A Keep-Alive connection holds a worker thread for its entire lifetime. If `connections × concurrent requests` exceeds the thread pool size, new requests wait. For thread counts, see S21. Configure the Thread Pool.
+
+> **Note:** For the client side, see C14. Understand Connection Reuse and Keep-Alive Behavior. Even when the server closes the connection on timeout, the client reconnects automatically.

docs-src/pages/en/cookbook/s21-thread-pool.md

@@ -0,0 +1,69 @@
+---
+title: "S21. Configure the Thread Pool"
+order: 40
+status: "draft"
+---
+
+cpp-httplib serves requests from a thread pool. By default, the base thread count is the greater of `std::thread::hardware_concurrency() - 1` and `8`, and it can scale up dynamically to 4× that. To set thread counts explicitly, provide your own factory via `new_task_queue`.
+
+## Set thread counts
+
+```cpp
+httplib::Server svr;
+
+svr.new_task_queue = [] {
+  return new httplib::ThreadPool(/*base_threads=*/8, /*max_threads=*/64);
+};
+
+svr.listen("0.0.0.0", 8080);
+```
+
+The factory is a lambda returning a `TaskQueue*`. Pass `base_threads` and `max_threads` to `ThreadPool` and the pool scales between them based on load. Idle threads exit after a timeout (3 seconds by default).
+
+## Also cap the queue
+
+The pending queue can eat memory if it grows unchecked. You can cap it too.
+
+```cpp
+svr.new_task_queue = [] {
+  return new httplib::ThreadPool(
+    /*base_threads=*/12,
+    /*max_threads=*/0,   // disable dynamic scaling
+    /*max_queued_requests=*/18);
+};
+```
+
+`max_threads=0` disables dynamic scaling — you get a fixed `base_threads`. Requests that don't fit in `max_queued_requests` are rejected.
+
+## Use your own thread pool
+
+You can plug in a fully custom thread pool by subclassing `TaskQueue` and returning it from the factory.
+
+```cpp
+class MyTaskQueue : public httplib::TaskQueue {
+public:
+  MyTaskQueue(size_t n) { pool_.start_with_thread_count(n); }
+  bool enqueue(std::function<void()> fn) override { return pool_.post(std::move(fn)); }
+  void shutdown() override { pool_.shutdown(); }
+
+private:
+  MyThreadPool pool_;
+};
+
+svr.new_task_queue = [] { return new MyTaskQueue(12); };
+```
+
+Handy when you already have a thread pool in your project and want to keep thread management unified.
+
+## Compile-time tuning
+
+You can set the defaults with macros if you want compile-time configuration.
+
+```cpp
+#define CPPHTTPLIB_THREAD_POOL_COUNT 16       // base thread count
+#define CPPHTTPLIB_THREAD_POOL_MAX_COUNT 128   // max thread count
+#define CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT 5  // seconds before idle threads exit
+#include <httplib.h>
+```
+
+> **Note:** A WebSocket connection holds a worker thread for its entire lifetime. For lots of simultaneous WebSocket connections, enable dynamic scaling (e.g. `ThreadPool(8, 64)`).

docs-src/pages/en/cookbook/s22-unix-socket.md

@@ -0,0 +1,64 @@
+---
+title: "S22. Talk Over a Unix Domain Socket"
+order: 41
+status: "draft"
+---
+
+When you want to talk only to other processes on the same host, a Unix domain socket is a nice fit. It avoids TCP overhead and uses filesystem permissions for access control. Local IPC and services sitting behind a reverse proxy are classic use cases.
+
+## Server side
+
+```cpp
+httplib::Server svr;
+svr.set_address_family(AF_UNIX);
+
+svr.Get("/", [](const auto &, auto &res) {
+  res.set_content("hello from unix socket", "text/plain");
+});
+
+svr.listen("/tmp/httplib.sock", 80);
+```
+
+Call `set_address_family(AF_UNIX)` first, then pass the socket file path as the first argument to `listen()`. The port number is unused but required by the signature — pass any value.
+
+## Client side
+
+```cpp
+httplib::Client cli("/tmp/httplib.sock");
+cli.set_address_family(AF_UNIX);
+
+auto res = cli.Get("/");
+if (res) {
+  std::cout << res->body << std::endl;
+}
+```
+
+Pass the socket file path to the `Client` constructor and call `set_address_family(AF_UNIX)`. Everything else works like a normal HTTP request.
+
+## When to use it
+
+- **Behind a reverse proxy**: An nginx-to-backend setup over a Unix socket is faster than TCP and sidesteps port management
+- **Local-only APIs**: IPC between tools that shouldn't be reachable from outside
+- **In-container IPC**: Process-to-process communication within the same pod or container
+- **Dev environments**: No more worrying about port conflicts
+
+## Clean up the socket file
+
+A Unix domain socket creates a real file in the filesystem. It doesn't get removed on shutdown, so delete it before starting if needed.
+
+```cpp
+std::remove("/tmp/httplib.sock");
+svr.listen("/tmp/httplib.sock", 80);
+```
+
+## Permissions
+
+You control who can connect via the socket file's permissions.
+
+```cpp
+svr.listen("/tmp/httplib.sock", 80);
+// from another process or thread
+chmod("/tmp/httplib.sock", 0660); // owner and group only
+```
+
+> **Warning:** Some Windows versions support AF_UNIX, but the implementation and behavior differ by platform. Test thoroughly before running cross-platform in production.

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

@@ -42,36 +42,36 @@ status: "draft"
 ## サーバー
 
 ### 基本
-- S01. GET / POST / PUT / DELETEハンドラを登録する
+- [S01. GET / POST / PUT / DELETEハンドラを登録する](s01-handlers)
-- S02. JSONリクエストを受け取りJSONレスポンスを返す
+- [S02. JSONリクエストを受け取りJSONレスポンスを返す](s02-json-api)
-- S03. パスパラメーターを使う（`/users/:id`）
+- [S03. パスパラメーターを使う](s03-path-params)
-- S04. 静的ファイルサーバーを設定する（`set_mount_point`）
+- [S04. 静的ファイルサーバーを設定する](s04-static-files)
 
 ### ストリーミング・ファイル
-- S05. 大きなファイルをストリーミングで返す（`ContentProvider`）
+- [S05. 大きなファイルをストリーミングで返す](s05-stream-response)
-- S06. ファイルダウンロードレスポンスを返す（`Content-Disposition`）
+- [S06. ファイルダウンロードレスポンスを返す](s06-download-response)
-- S07. マルチパートデータをストリーミングで受け取る（`ContentReader`）
+- [S07. マルチパートデータをストリーミングで受け取る](s07-multipart-reader)
-- S08. レスポンスを圧縮して返す（gzip）
+- [S08. レスポンスを圧縮して返す](s08-compress-response)
 
 ### ハンドラチェーン
-- S09. 全ルートに共通の前処理をする（Pre-routing handler）
+- [S09. 全ルートに共通の前処理をする](s09-pre-routing)
-- S10. Post-routing handlerでレスポンスヘッダーを追加する（CORSなど）
+- [S10. Post-routing handlerでレスポンスヘッダーを追加する](s10-post-routing)
-- S11. Pre-request handlerでルート単位の認証を行う（`matched_route`）
+- [S11. Pre-request handlerでルート単位の認証を行う](s11-pre-request)
-- S12. `res.user_data`でハンドラ間データを渡す
+- [S12. `res.user_data`でハンドラ間データを渡す](s12-user-data)
 
 ### エラー処理・デバッグ
-- S13. カスタムエラーページを返す（`set_error_handler`）
+- [S13. カスタムエラーページを返す](s13-error-handler)
-- S14. 例外をキャッチする（`set_exception_handler`）
+- [S14. 例外をキャッチする](s14-exception-handler)
-- S15. リクエストをログに記録する（Logger）
+- [S15. リクエストをログに記録する](s15-server-logger)
-- S16. クライアントが切断したか検出する（`req.is_connection_closed()`）
+- [S16. クライアントが切断したか検出する](s16-disconnect)
 
 ### 運用・チューニング
-- S17. ポートを動的に割り当てる（`bind_to_any_port`）
+- [S17. ポートを動的に割り当てる](s17-bind-any-port)
-- S18. `listen_after_bind`で起動順序を制御する
+- [S18. `listen_after_bind`で起動順序を制御する](s18-listen-after-bind)
-- S19. グレースフルシャットダウンする（`stop()`とシグナルハンドリング）
+- [S19. グレースフルシャットダウンする](s19-graceful-shutdown)
-- S20. Keep-Aliveを調整する（`set_keep_alive_max_count` / `set_keep_alive_timeout`）
+- [S20. Keep-Aliveを調整する](s20-keep-alive)
-- S21. マルチスレッド数を設定する（`new_task_queue`）
+- [S21. マルチスレッド数を設定する](s21-thread-pool)
-- S22. Unix domain socketで通信する（`set_address_family(AF_UNIX)`）
+- [S22. Unix domain socketで通信する](s22-unix-socket)
 
 ## TLS / セキュリティ
 

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

@@ -0,0 +1,66 @@
+---
+title: "S01. GET / POST / PUT / DELETEハンドラを登録する"
+order: 20
+status: "draft"
+---
+
+`httplib::Server`では、HTTPメソッドごとにハンドラを登録します。`Get()`、`Post()`、`Put()`、`Delete()`の各メソッドにパターンとラムダを渡すだけです。
+
+## 基本の使い方
+
+```cpp
+#include <httplib.h>
+
+int main() {
+  httplib::Server svr;
+
+  svr.Get("/hello", [](const httplib::Request &req, httplib::Response &res) {
+    res.set_content("Hello, World!", "text/plain");
+  });
+
+  svr.Post("/api/items", [](const httplib::Request &req, httplib::Response &res) {
+    // req.bodyにリクエストボディが入っている
+    res.status = 201;
+    res.set_content("Created", "text/plain");
+  });
+
+  svr.Put("/api/items/1", [](const httplib::Request &req, httplib::Response &res) {
+    res.set_content("Updated", "text/plain");
+  });
+
+  svr.Delete("/api/items/1", [](const httplib::Request &req, httplib::Response &res) {
+    res.status = 204;
+  });
+
+  svr.listen("0.0.0.0", 8080);
+}
+```
+
+ハンドラは`(const Request&, Response&)`の2引数を受け取ります。`res.set_content()`でレスポンスボディとContent-Typeを設定し、`res.status`でステータスコードを指定します。`listen()`を呼ぶとサーバーが起動し、ブロックされます。
+
+## クエリパラメーターを取得する
+
+```cpp
+svr.Get("/search", [](const httplib::Request &req, httplib::Response &res) {
+  auto q = req.get_param_value("q");
+  auto limit = req.get_param_value("limit");
+  res.set_content("q=" + q + ", limit=" + limit, "text/plain");
+});
+```
+
+`req.get_param_value()`でクエリ文字列の値を取り出せます。存在するかどうかを先に調べたいなら`req.has_param("q")`を使います。
+
+## リクエストヘッダーを読む
+
+```cpp
+svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
+  auto ua = req.get_header_value("User-Agent");
+  res.set_content("UA: " + ua, "text/plain");
+});
+```
+
+レスポンスヘッダーを追加したいときは`res.set_header("Name", "Value")`です。
+
+> **Note:** `listen()`はブロックする関数です。別スレッドで動かしたいときは`std::thread`で包むか、ノンブロッキング起動が必要ならS18. `listen_after_bind`で起動順序を制御するを参照してください。
+
+> パスパラメーター（`/users/:id`）を使いたい場合はS03. パスパラメーターを使うを参照してください。

docs-src/pages/ja/cookbook/s02-json-api.md

@@ -0,0 +1,74 @@
+---
+title: "S02. JSONリクエストを受け取りJSONレスポンスを返す"
+order: 21
+status: "draft"
+---
+
+cpp-httplibにはJSONパーサーが含まれていません。サーバー側でも[nlohmann/json](https://github.com/nlohmann/json)などを組み合わせて使います。ここでは`nlohmann/json`を例に説明します。
+
+## JSONを受け取って返す
+
+```cpp
+#include <httplib.h>
+#include <nlohmann/json.hpp>
+
+int main() {
+  httplib::Server svr;
+
+  svr.Post("/api/users", [](const httplib::Request &req, httplib::Response &res) {
+    try {
+      auto in = nlohmann::json::parse(req.body);
+
+      nlohmann::json out = {
+        {"id", 42},
+        {"name", in["name"]},
+        {"created_at", "2026-04-10T12:00:00Z"},
+      };
+
+      res.status = 201;
+      res.set_content(out.dump(), "application/json");
+    } catch (const std::exception &e) {
+      res.status = 400;
+      res.set_content("{\"error\":\"invalid json\"}", "application/json");
+    }
+  });
+
+  svr.listen("0.0.0.0", 8080);
+}
+```
+
+`req.body`はそのまま`std::string`なので、JSONライブラリに渡してパースします。レスポンスは`dump()`で文字列にして、Content-Typeに`application/json`を指定して返します。
+
+## Content-Typeをチェックする
+
+```cpp
+svr.Post("/api/users", [](const httplib::Request &req, httplib::Response &res) {
+  auto content_type = req.get_header_value("Content-Type");
+  if (content_type.find("application/json") == std::string::npos) {
+    res.status = 415; // Unsupported Media Type
+    return;
+  }
+  // ...
+});
+```
+
+厳密にJSONだけを受け付けたいときは、Content-Typeを確認してから処理しましょう。
+
+## JSONを返すヘルパーを作る
+
+同じパターンを何度も書くなら、小さなヘルパーを用意すると楽です。
+
+```cpp
+auto send_json = [](httplib::Response &res, int status, const nlohmann::json &j) {
+  res.status = status;
+  res.set_content(j.dump(), "application/json");
+};
+
+svr.Get("/api/health", [&](const auto &req, auto &res) {
+  send_json(res, 200, {{"status", "ok"}});
+});
+```
+
+> **Note:** 大きなJSONボディを受け取ると、`req.body`がまるごとメモリに載ります。巨大なペイロードを扱うときはS07. マルチパートデータをストリーミングで受け取るのように、ストリーミング受信も検討しましょう。
+
+> クライアント側の書き方はC02. JSONを送受信するを参照してください。

docs-src/pages/ja/cookbook/s03-path-params.md

@@ -0,0 +1,53 @@
+---
+title: "S03. パスパラメーターを使う"
+order: 22
+status: "draft"
+---
+
+REST APIでよく使う`/users/:id`のような動的なパスは、パスパターンに`:name`を書くだけで使えます。マッチした値は`req.path_params`に入ります。
+
+## 基本の使い方
+
+```cpp
+svr.Get("/users/:id", [](const httplib::Request &req, httplib::Response &res) {
+  auto id = req.path_params.at("id");
+  res.set_content("user id: " + id, "text/plain");
+});
+```
+
+`/users/42`にアクセスすると、`req.path_params["id"]`に`"42"`が入ります。`path_params`は`std::unordered_map<std::string, std::string>`なので、`at()`で取り出します。
+
+## 複数のパラメーター
+
+パラメーターはいくつでも書けます。
+
+```cpp
+svr.Get("/orgs/:org/repos/:repo", [](const httplib::Request &req, httplib::Response &res) {
+  auto org = req.path_params.at("org");
+  auto repo = req.path_params.at("repo");
+  res.set_content(org + "/" + repo, "text/plain");
+});
+```
+
+`/orgs/anthropic/repos/cpp-httplib`のようなパスがマッチします。
+
+## 正規表現パターン
+
+もっと柔軟にマッチさせたいときは、`std::regex`ベースのパターンも使えます。
+
+```cpp
+svr.Get(R"(/users/(\d+))", [](const httplib::Request &req, httplib::Response &res) {
+  auto id = req.matches[1];
+  res.set_content("user id: " + std::string(id), "text/plain");
+});
+```
+
+パターンに括弧を使うと、マッチした部分が`req.matches`に入ります。`req.matches[0]`はパス全体、`req.matches[1]`以降がキャプチャです。
+
+## どちらを使うか
+
+- 単純なIDやスラッグなら`:name`でじゅうぶん。読みやすく、型が自明です
+- 数値のみ、UUIDのみといった形式をURLで絞りたいなら正規表現が便利
+- 両方を混ぜると混乱するので、プロジェクト内ではどちらかに統一するのがおすすめです
+
+> **Note:** パスパラメーターは文字列として入ってくるので、整数として使いたい場合は`std::stoi()`などで変換してください。変換失敗のハンドリングも忘れずに。

docs-src/pages/ja/cookbook/s04-static-files.md

@@ -0,0 +1,55 @@
+---
+title: "S04. 静的ファイルサーバーを設定する"
+order: 23
+status: "draft"
+---
+
+HTML、CSS、画像などの静的ファイルを配信したいときは、`set_mount_point()`を使います。URLパスとローカルディレクトリを結びつけるだけで、そのディレクトリの中身がまるごと配信されます。
+
+## 基本の使い方
+
+```cpp
+httplib::Server svr;
+svr.set_mount_point("/", "./public");
+svr.listen("0.0.0.0", 8080);
+```
+
+`./public/index.html`が`http://localhost:8080/index.html`で、`./public/css/style.css`が`http://localhost:8080/css/style.css`でアクセスできます。ディレクトリ構造がそのままURLに反映されます。
+
+## 複数のマウントポイント
+
+マウントポイントは複数登録できます。
+
+```cpp
+svr.set_mount_point("/", "./public");
+svr.set_mount_point("/assets", "./dist/assets");
+svr.set_mount_point("/uploads", "./var/uploads");
+```
+
+同じパスに複数のマウントを登録することもできます。その場合は登録順に探されて、見つかった最初のものが返ります。
+
+## APIハンドラと組み合わせる
+
+静的ファイルとAPIハンドラは共存できます。`Get()`などで登録したハンドラが優先され、マッチしなかったときにマウントポイントが探されます。
+
+```cpp
+svr.Get("/api/users", [](const auto &req, auto &res) {
+  res.set_content("[]", "application/json");
+});
+
+svr.set_mount_point("/", "./public");
+```
+
+これでSPAのように、`/api/*`はハンドラで、それ以外は`./public/`から配信、という構成が作れます。
+
+## MIMEタイプを追加する
+
+拡張子からContent-Typeを決めるマッピングは組み込みですが、カスタムの拡張子を追加できます。
+
+```cpp
+svr.set_file_extension_and_mimetype_mapping("wasm", "application/wasm");
+```
+
+> **Warning:** 静的ファイル配信系のメソッドは**スレッドセーフではありません**。起動後（`listen()`以降）には呼ばないでください。起動前にまとめて設定しましょう。
+
+> ダウンロード用のレスポンスを返したい場合はS06. ファイルダウンロードレスポンスを返すも参考になります。

docs-src/pages/ja/cookbook/s05-stream-response.md

@@ -0,0 +1,63 @@
+---
+title: "S05. 大きなファイルをストリーミングで返す"
+order: 24
+status: "draft"
+---
+
+巨大なファイルやリアルタイムに生成されるデータをレスポンスとして返したいとき、全体をメモリに載せるのは現実的ではありません。`Response::set_content_provider()`を使うと、データをチャンクごとに生成しながら送れます。
+
+## サイズがわかっている場合
+
+```cpp
+svr.Get("/download", [](const httplib::Request &req, httplib::Response &res) {
+  size_t total_size = get_file_size("large.bin");
+
+  res.set_content_provider(
+    total_size, "application/octet-stream",
+    [](size_t offset, size_t length, httplib::DataSink &sink) {
+      auto data = read_range_from_file("large.bin", offset, length);
+      sink.write(data.data(), data.size());
+      return true;
+    });
+});
+```
+
+ラムダが呼ばれるたびに`offset`と`length`が渡されるので、その範囲だけ読み込んで`sink.write()`で送ります。メモリには常に少量のチャンクしか載りません。
+
+## ファイルをそのまま返す
+
+ただファイルを返すだけなら、`set_file_content()`のほうがずっと簡単です。
+
+```cpp
+svr.Get("/download", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_file_content("large.bin", "application/octet-stream");
+});
+```
+
+内部でストリーミング送信をしてくれるので、大きなファイルでも安心です。Content-Typeを省略すれば、拡張子から自動で判定されます。
+
+## サイズが不明な場合はチャンク転送
+
+リアルタイムに生成されるデータなど、サイズが事前にわからないときは`set_chunked_content_provider()`を使います。HTTP chunked transfer-encodingとして送信されます。
+
+```cpp
+svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_chunked_content_provider(
+    "text/plain",
+    [](size_t offset, httplib::DataSink &sink) {
+      auto chunk = produce_next_chunk();
+      if (chunk.empty()) {
+        sink.done(); // 送信終了
+        return true;
+      }
+      sink.write(chunk.data(), chunk.size());
+      return true;
+    });
+});
+```
+
+データがもう無くなったら`sink.done()`を呼んで終了します。
+
+> **Note:** プロバイダラムダは複数回呼ばれます。キャプチャする変数のライフタイムに気をつけてください。必要なら`std::shared_ptr`などで包みましょう。
+
+> ファイルダウンロードとして扱いたい場合はS06. ファイルダウンロードレスポンスを返すを参照してください。

docs-src/pages/ja/cookbook/s06-download-response.md

@@ -0,0 +1,50 @@
+---
+title: "S06. ファイルダウンロードレスポンスを返す"
+order: 25
+status: "draft"
+---
+
+ブラウザで開いたときにインラインで表示するのではなく、**ダウンロードダイアログ**を出したいときは、`Content-Disposition`ヘッダーを付けます。cpp-httplib側の特別なAPIではなく、普通のヘッダー設定で実現します。
+
+## 基本の使い方
+
+```cpp
+svr.Get("/download/report", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_header("Content-Disposition", "attachment; filename=\"report.pdf\"");
+  res.set_file_content("reports/2026-04.pdf", "application/pdf");
+});
+```
+
+`Content-Disposition: attachment`を付けると、ブラウザが「保存しますか？」のダイアログを出します。`filename=`で保存時のデフォルト名を指定できます。
+
+## 日本語など非ASCIIのファイル名
+
+ファイル名に日本語やスペースが含まれる場合は、RFC 5987形式の`filename*`を使います。
+
+```cpp
+svr.Get("/download/report", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_header(
+    "Content-Disposition",
+    "attachment; filename=\"report.pdf\"; "
+    "filename*=UTF-8''%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88.pdf");
+  res.set_file_content("reports/2026-04.pdf", "application/pdf");
+});
+```
+
+`filename*=UTF-8''`の後ろはURLエンコード済みのUTF-8バイト列です。古いブラウザ向けにASCIIの`filename=`も併記しておくと安全です。
+
+## 動的に生成したデータをダウンロードさせる
+
+ファイルがなくても、生成した文字列をそのままダウンロードさせることもできます。
+
+```cpp
+svr.Get("/export.csv", [](const httplib::Request &req, httplib::Response &res) {
+  std::string csv = build_csv();
+  res.set_header("Content-Disposition", "attachment; filename=\"export.csv\"");
+  res.set_content(csv, "text/csv");
+});
+```
+
+CSVエクスポートなどでよく使うパターンです。
+
+> **Note:** ブラウザによっては`Content-Disposition`がなくても、Content-Typeを見て自動でダウンロード扱いにすることがあります。逆に、`inline`を付けるとできるだけブラウザ内で表示しようとします。

docs-src/pages/ja/cookbook/s07-multipart-reader.md

@@ -0,0 +1,71 @@
+---
+title: "S07. マルチパートデータをストリーミングで受け取る"
+order: 26
+status: "draft"
+---
+
+大きなファイルをアップロードするハンドラを普通に書くと、`req.body`にリクエスト全体が載ってしまいメモリを圧迫します。`HandlerWithContentReader`を使うと、ボディをチャンクごとに受け取れます。
+
+## 基本の使い方
+
+```cpp
+svr.Post("/upload",
+  [](const httplib::Request &req, httplib::Response &res,
+     const httplib::ContentReader &content_reader) {
+    if (req.is_multipart_form_data()) {
+      content_reader(
+        // 各パートのヘッダー
+        [&](const httplib::FormData &file) {
+          std::cout << "name: " << file.name
+                    << ", filename: " << file.filename << std::endl;
+          return true;
+        },
+        // 各パートのボディ（複数回呼ばれる）
+        [&](const char *data, size_t len) {
+          // ここでファイルに書き出すなど
+          return true;
+        });
+    } else {
+      // 普通のリクエストボディ
+      content_reader([&](const char *data, size_t len) {
+        return true;
+      });
+    }
+
+    res.set_content("ok", "text/plain");
+  });
+```
+
+`content_reader`は2通りの呼び方ができます。マルチパートのときは2つのコールバック（ヘッダー用とデータ用）を渡し、そうでないときは1つのコールバックだけを渡します。
+
+## ファイルに直接書き出す
+
+大きなファイルをそのままディスクに書き出す例です。
+
+```cpp
+svr.Post("/upload",
+  [](const httplib::Request &req, httplib::Response &res,
+     const httplib::ContentReader &content_reader) {
+    std::ofstream ofs;
+
+    content_reader(
+      [&](const httplib::FormData &file) {
+        if (!file.filename.empty()) {
+          ofs.open("uploads/" + file.filename, std::ios::binary);
+        }
+        return static_cast<bool>(ofs);
+      },
+      [&](const char *data, size_t len) {
+        ofs.write(data, len);
+        return static_cast<bool>(ofs);
+      });
+
+    res.set_content("uploaded", "text/plain");
+  });
+```
+
+メモリには常に小さなチャンクしか載らないので、ギガバイト級のファイルでも扱えます。
+
+> **Warning:** `HandlerWithContentReader`を使うと、`req.body`は**空のまま**です。ボディはコールバック内で自分で処理してください。
+
+> クライアント側でマルチパートを送る方法はC07. ファイルをマルチパートフォームとしてアップロードするを参照してください。

docs-src/pages/ja/cookbook/s08-compress-response.md

@@ -0,0 +1,53 @@
+---
+title: "S08. レスポンスを圧縮して返す"
+order: 27
+status: "draft"
+---
+
+cpp-httplibは、クライアントが`Accept-Encoding`で対応を表明していれば、レスポンスボディを自動で圧縮してくれます。ハンドラ側で特別なことをする必要はありません。対応しているのはgzip、Brotli、Zstdです。
+
+## ビルド時の準備
+
+圧縮機能を使うには、`httplib.h`をインクルードする前に対応するマクロを定義しておきます。
+
+```cpp
+#define CPPHTTPLIB_ZLIB_SUPPORT     // gzip
+#define CPPHTTPLIB_BROTLI_SUPPORT   // brotli
+#define CPPHTTPLIB_ZSTD_SUPPORT     // zstd
+#include <httplib.h>
+```
+
+それぞれ`zlib`、`brotli`、`zstd`をリンクする必要があります。必要な圧縮方式だけ有効にすればOKです。
+
+## 使い方
+
+```cpp
+svr.Get("/api/data", [](const httplib::Request &req, httplib::Response &res) {
+  std::string body = build_large_response();
+  res.set_content(body, "application/json");
+});
+```
+
+これだけです。クライアントが`Accept-Encoding: gzip`を送ってきていれば、cpp-httplibが自動でgzip圧縮して返します。レスポンスには`Content-Encoding: gzip`と`Vary: Accept-Encoding`が自動で付きます。
+
+## 圧縮の優先順位
+
+クライアントが複数の方式を受け入れる場合、Brotli → Zstd → gzipの順に選ばれます（ビルドで有効になっている中から）。クライアント側では気にせず、一番効率の良い方式で圧縮されます。
+
+## ストリーミングレスポンスも圧縮される
+
+`set_chunked_content_provider()`で返すストリーミングレスポンスも、同じように自動で圧縮されます。
+
+```cpp
+svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_chunked_content_provider(
+    "text/plain",
+    [](size_t offset, httplib::DataSink &sink) {
+      // ...
+    });
+});
+```
+
+> **Note:** 小さなレスポンスは圧縮しても効果が薄く、むしろCPU時間を無駄にすることがあります。cpp-httplibは小さすぎるボディは圧縮をスキップします。
+
+> クライアント側の挙動はC15. 圧縮を有効にするを参照してください。

docs-src/pages/ja/cookbook/s09-pre-routing.md

@@ -0,0 +1,54 @@
+---
+title: "S09. 全ルートに共通の前処理をする"
+order: 28
+status: "draft"
+---
+
+すべてのリクエストに対して共通の処理を走らせたいことがあります。認証チェック、ロギング、レート制限などです。こうした処理は`set_pre_routing_handler()`で登録します。
+
+## 基本の使い方
+
+```cpp
+svr.set_pre_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    std::cout << req.method << " " << req.path << std::endl;
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+```
+
+Pre-routingハンドラは、**ルーティングよりも前**に呼ばれます。どのハンドラにもマッチしないリクエストも含めて、すべてのリクエストを捕まえられます。
+
+戻り値の`HandlerResponse`がポイントです。
+
+- `Unhandled`を返す: 通常の処理を続行（ルーティングとハンドラ呼び出し）
+- `Handled`を返す: ここでレスポンスが完了したとみなし、以降の処理をスキップ
+
+## 認証チェックに使う
+
+全ルート共通の認証を一箇所でかけられます。
+
+```cpp
+svr.set_pre_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    if (req.path.rfind("/public", 0) == 0) {
+      return httplib::Server::HandlerResponse::Unhandled; // 認証不要
+    }
+
+    auto auth = req.get_header_value("Authorization");
+    if (auth.empty()) {
+      res.status = 401;
+      res.set_content("unauthorized", "text/plain");
+      return httplib::Server::HandlerResponse::Handled;
+    }
+
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+```
+
+認証が通らなければ`Handled`を返してその場で401を返し、通れば`Unhandled`を返して通常のルーティングに進ませます。
+
+## 特定ルートだけに認証をかけたい場合
+
+全ルート共通ではなく、ルート単位で認証を分けたいときは、S11. Pre-request handlerでルート単位の認証を行うのほうが適しています。
+
+> **Note:** レスポンスを加工したいだけなら、`set_post_routing_handler()`のほうが適切です。S10. Post-routing handlerでレスポンスヘッダーを追加するを参照してください。

docs-src/pages/ja/cookbook/s10-post-routing.md

@@ -0,0 +1,56 @@
+---
+title: "S10. Post-routing handlerでレスポンスヘッダーを追加する"
+order: 29
+status: "draft"
+---
+
+ハンドラが返したレスポンスに、あとから共通のヘッダーを追加したいことがあります。CORSヘッダー、セキュリティヘッダー、独自のリクエストIDなどです。こういうときは`set_post_routing_handler()`を使います。
+
+## 基本の使い方
+
+```cpp
+svr.set_post_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    res.set_header("X-Request-ID", generate_request_id());
+  });
+```
+
+Post-routingハンドラは、**ルートハンドラが実行された後、レスポンスが送信される前**に呼ばれます。ここで`res.set_header()`や`res.headers.erase()`を使えば、全レスポンスに対して一括でヘッダーの追加・削除ができます。
+
+## CORSヘッダーを付ける
+
+よくある用途がCORSです。
+
+```cpp
+svr.set_post_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    res.set_header("Access-Control-Allow-Origin", "*");
+    res.set_header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+    res.set_header("Access-Control-Allow-Headers", "Content-Type, Authorization");
+  });
+```
+
+プリフライトリクエスト（`OPTIONS`）には別途ハンドラを登録するか、pre-routingハンドラで処理します。
+
+```cpp
+svr.Options("/.*", [](const auto &req, auto &res) {
+  res.status = 204;
+});
+```
+
+## セキュリティヘッダーをまとめて付ける
+
+ブラウザ向けのセキュリティヘッダーを一箇所で管理できます。
+
+```cpp
+svr.set_post_routing_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    res.set_header("X-Content-Type-Options", "nosniff");
+    res.set_header("X-Frame-Options", "DENY");
+    res.set_header("Referrer-Policy", "strict-origin-when-cross-origin");
+  });
+```
+
+どのハンドラがレスポンスを作っても、同じヘッダーが付くようになります。
+
+> **Note:** Post-routingハンドラは、ルートにマッチしなかったリクエストや、エラーハンドラが返したレスポンスに対しても呼ばれます。ヘッダーをすべてのレスポンスに確実に付けたいときに便利です。

docs-src/pages/ja/cookbook/s11-pre-request.md

@@ -0,0 +1,47 @@
+---
+title: "S11. Pre-request handlerでルート単位の認証を行う"
+order: 30
+status: "draft"
+---
+
+S09で紹介した`set_pre_routing_handler()`はルーティングの**前**に呼ばれるので、「どのルートにマッチしたか」を知れません。ルートによって認証の有無を変えたい場合は、`set_pre_request_handler()`のほうが便利です。
+
+## Pre-routingとの違い
+
+| フック | 呼ばれるタイミング | ルート情報 |
+| --- | --- | --- |
+| `set_pre_routing_handler` | ルーティングの前 | 取得できない |
+| `set_pre_request_handler` | ルーティング後、ルートハンドラの直前 | `req.matched_route`で取得可能 |
+
+Pre-requestハンドラなら、`req.matched_route`に「マッチしたパターン文字列」が入っているので、ルートに応じて処理を変えられます。
+
+## ルートごとに認証を切り替える
+
+```cpp
+svr.set_pre_request_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    // /adminで始まるルートだけ認証を要求
+    if (req.matched_route.rfind("/admin", 0) == 0) {
+      auto token = req.get_header_value("Authorization");
+      if (!is_admin_token(token)) {
+        res.status = 403;
+        res.set_content("forbidden", "text/plain");
+        return httplib::Server::HandlerResponse::Handled;
+      }
+    }
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+```
+
+`matched_route`はパスパラメーターを展開する**前**のパターン文字列（例: `/admin/users/:id`）です。特定の値ではなく、ルート定義のパターンで判定できるので、IDや名前に左右されません。
+
+## 戻り値の意味
+
+Pre-routingハンドラと同じく、`HandlerResponse`を返します。
+
+- `Unhandled`: 通常の処理を続行（ルートハンドラが呼ばれる）
+- `Handled`: ここで完了、ルートハンドラはスキップされる
+
+## 認証情報を後続のハンドラに渡す
+
+認証で取り出したユーザー情報などをルートハンドラに渡したいときは、`res.user_data`を使います。詳しくはS12. `res.user_data`でハンドラ間データを渡すを参照してください。

docs-src/pages/ja/cookbook/s12-user-data.md

@@ -0,0 +1,56 @@
+---
+title: "S12. res.user_dataでハンドラ間データを渡す"
+order: 31
+status: "draft"
+---
+
+Pre-requestハンドラで認証トークンをデコードして、その結果をルートハンドラで使いたい。こういう「ハンドラ間のデータ受け渡し」は、`res.user_data`に任意の型を入れて解決します。
+
+## 基本の使い方
+
+```cpp
+struct AuthUser {
+  std::string id;
+  std::string name;
+  bool is_admin;
+};
+
+svr.set_pre_request_handler(
+  [](const httplib::Request &req, httplib::Response &res) {
+    auto token = req.get_header_value("Authorization");
+    auto user = decode_token(token); // 認証トークンをデコード
+    res.user_data.set("user", user);
+    return httplib::Server::HandlerResponse::Unhandled;
+  });
+
+svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
+  auto *user = res.user_data.get<AuthUser>("user");
+  if (!user) {
+    res.status = 401;
+    return;
+  }
+  res.set_content("Hello, " + user->name, "text/plain");
+});
+```
+
+`user_data.set()`で任意の型の値を保存し、`user_data.get<T>()`で取り出します。型を正しく指定しないと`nullptr`が返るので注意してください。
+
+## よくある型
+
+`std::string`、数値、構造体、`std::shared_ptr`など、コピーかムーブできる値なら何でも入れられます。
+
+```cpp
+res.user_data.set("user_id", std::string{"42"});
+res.user_data.set("is_admin", true);
+res.user_data.set("started_at", std::chrono::steady_clock::now());
+```
+
+## どこで設定し、どこで読むか
+
+設定する側は`set_pre_routing_handler()`か`set_pre_request_handler()`、読む側は通常のルートハンドラ、という流れが一般的です。Pre-requestのほうがルーティング後に呼ばれるので、`req.matched_route`と組み合わせて「このルートにマッチしたときだけセット」という書き方ができます。
+
+## 注意点
+
+`user_data`は`Response`に乗っています（`req.user_data`ではありません）。これは、ハンドラには`Response&`として可変参照が渡されるためです。一見不思議ですが、「ハンドラ間で共有する可変コンテキスト」として覚えておくと素直です。
+
+> **Warning:** `user_data.get<T>()`は型が一致しないと`nullptr`を返します。保存時と取得時で同じ型を指定してください。`AuthUser`で入れて`const AuthUser`で取ろうとすると失敗します。

docs-src/pages/ja/cookbook/s13-error-handler.md

@@ -0,0 +1,51 @@
+---
+title: "S13. カスタムエラーページを返す"
+order: 32
+status: "draft"
+---
+
+404や500のような**ハンドラが返したエラーレスポンス**を加工したいときは、`set_error_handler()`を使います。デフォルトの味気ないエラーページを、独自のHTMLやJSONに差し替えられます。
+
+## 基本の使い方
+
+```cpp
+svr.set_error_handler([](const httplib::Request &req, httplib::Response &res) {
+  auto body = "<h1>Error " + std::to_string(res.status) + "</h1>";
+  res.set_content(body, "text/html");
+});
+```
+
+エラーハンドラは、`res.status`が4xxまたは5xxでレスポンスが返る直前に呼ばれます。`res.set_content()`で差し替えれば、すべてのエラーレスポンスで同じテンプレートが使えます。
+
+## ステータスコード別の処理
+
+```cpp
+svr.set_error_handler([](const httplib::Request &req, httplib::Response &res) {
+  if (res.status == 404) {
+    res.set_content("<h1>Not Found</h1><p>" + req.path + "</p>", "text/html");
+  } else if (res.status >= 500) {
+    res.set_content("<h1>Server Error</h1>", "text/html");
+  }
+});
+```
+
+`res.status`を見て分岐すれば、404には専用のメッセージを、5xxにはサポート窓口のリンクを、といった使い分けができます。
+
+## JSON APIのエラーレスポンス
+
+APIサーバーなら、エラーもJSONで返したいことが多いはずです。
+
+```cpp
+svr.set_error_handler([](const httplib::Request &req, httplib::Response &res) {
+  nlohmann::json j = {
+    {"error", true},
+    {"status", res.status},
+    {"path", req.path},
+  };
+  res.set_content(j.dump(), "application/json");
+});
+```
+
+これで全エラーが統一されたJSONで返ります。
+
+> **Note:** `set_error_handler()`は、ルートハンドラが例外を投げた場合の500エラーにも呼ばれます。例外そのものの情報を取り出したい場合は`set_exception_handler()`を組み合わせましょう。S14. 例外をキャッチするを参照してください。

docs-src/pages/ja/cookbook/s14-exception-handler.md

@@ -0,0 +1,67 @@
+---
+title: "S14. 例外をキャッチする"
+order: 33
+status: "draft"
+---
+
+ルートハンドラの中で例外が投げられても、cpp-httplibはサーバー全体を落とさずに500を返してくれます。ただ、デフォルトではエラー情報をクライアントにほとんど伝えません。`set_exception_handler()`を使うと、例外をキャッチして独自のレスポンスを組み立てられます。
+
+## 基本の使い方
+
+```cpp
+svr.set_exception_handler(
+  [](const httplib::Request &req, httplib::Response &res,
+     std::exception_ptr ep) {
+    try {
+      std::rethrow_exception(ep);
+    } catch (const std::exception &e) {
+      res.status = 500;
+      res.set_content(std::string("error: ") + e.what(), "text/plain");
+    } catch (...) {
+      res.status = 500;
+      res.set_content("unknown error", "text/plain");
+    }
+  });
+```
+
+ハンドラは`std::exception_ptr`を受け取るので、いったん`std::rethrow_exception()`で投げ直してから`catch`でキャッチするのが定石です。例外の型によってステータスコードやメッセージを変えられます。
+
+## 自前の例外型で分岐する
+
+独自の例外クラスを投げている場合、それを見て400や404にマッピングできます。
+
+```cpp
+struct NotFound : std::runtime_error {
+  using std::runtime_error::runtime_error;
+};
+struct BadRequest : std::runtime_error {
+  using std::runtime_error::runtime_error;
+};
+
+svr.set_exception_handler(
+  [](const auto &req, auto &res, std::exception_ptr ep) {
+    try {
+      std::rethrow_exception(ep);
+    } catch (const NotFound &e) {
+      res.status = 404;
+      res.set_content(e.what(), "text/plain");
+    } catch (const BadRequest &e) {
+      res.status = 400;
+      res.set_content(e.what(), "text/plain");
+    } catch (const std::exception &e) {
+      res.status = 500;
+      res.set_content("internal error", "text/plain");
+    }
+  });
+```
+
+ルートハンドラの中で`throw NotFound("user not found")`を投げるだけで、404が返るようになります。try/catchをハンドラごとに書かずに済むので、コードがすっきりします。
+
+## set_error_handlerとの関係
+
+`set_exception_handler()`は例外が発生した瞬間に呼ばれます。その後、`res.status`が4xx/5xxなら`set_error_handler()`も呼ばれます。順番は`exception_handler` → `error_handler`です。役割分担は次のとおりです。
+
+- **例外ハンドラ**: 例外を解釈してステータスとメッセージを決める
+- **エラーハンドラ**: 決まったステータスを見て、共通のテンプレートに整形する
+
+> **Note:** 例外ハンドラを設定しないと、cpp-httplibはデフォルトの500レスポンスを返します。例外情報はログに残らないので、デバッグしたいなら必ず設定しましょう。

docs-src/pages/ja/cookbook/s15-server-logger.md

@@ -0,0 +1,64 @@
+---
+title: "S15. リクエストをログに記録する"
+order: 34
+status: "draft"
+---
+
+サーバーが受け取ったリクエストと返したレスポンスをログに残したいときは、`Server::set_logger()`を使います。各リクエストの処理が完了するたびに呼ばれるので、アクセスログやメトリクス収集の土台になります。
+
+## 基本の使い方
+
+```cpp
+svr.set_logger([](const httplib::Request &req, const httplib::Response &res) {
+  std::cout << req.remote_addr << " "
+            << req.method << " " << req.path
+            << " -> " << res.status << std::endl;
+});
+```
+
+ログコールバックには`Request`と`Response`が渡ります。メソッド、パス、ステータスコード、クライアントIP、ヘッダー、ボディなど、好きな情報を取り出せます。
+
+## アクセスログ風のフォーマット
+
+Apache / Nginxのアクセスログに似た形式で残す例です。
+
+```cpp
+svr.set_logger([](const auto &req, const auto &res) {
+  auto now = std::time(nullptr);
+  char timebuf[32];
+  std::strftime(timebuf, sizeof(timebuf), "%Y-%m-%d %H:%M:%S",
+                std::localtime(&now));
+
+  std::cout << timebuf << " "
+            << req.remote_addr << " "
+            << "\"" << req.method << " " << req.path << "\" "
+            << res.status << " "
+            << res.body.size() << "B"
+            << std::endl;
+});
+```
+
+## 処理時間を測る
+
+ログで処理時間を出したいときは、pre-routingハンドラで開始時刻を`res.user_data`に保存しておき、ロガーで差分を取ります。
+
+```cpp
+svr.set_pre_routing_handler([](const auto &req, auto &res) {
+  res.user_data.set("start", std::chrono::steady_clock::now());
+  return httplib::Server::HandlerResponse::Unhandled;
+});
+
+svr.set_logger([](const auto &req, const auto &res) {
+  auto *start = res.user_data.get<std::chrono::steady_clock::time_point>("start");
+  auto elapsed = start
+    ? std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now() - *start).count()
+    : 0;
+  std::cout << req.method << " " << req.path
+            << " " << res.status << " " << elapsed << "ms" << std::endl;
+});
+```
+
+`user_data`の使い方はS12. `res.user_data`でハンドラ間データを渡すも参照してください。
+
+> **Note:** ロガーはリクエスト処理と同じスレッドで同期的に呼ばれます。重い処理を直接入れると全体のスループットが落ちるので、必要ならキューに流して非同期で処理しましょう。

docs-src/pages/ja/cookbook/s16-disconnect.md

@@ -0,0 +1,55 @@
+---
+title: "S16. クライアントが切断したか検出する"
+order: 35
+status: "draft"
+---
+
+長時間のレスポンスを返している最中に、クライアントが接続を切ってしまうことがあります。無駄に処理を続けても意味がないので、適宜チェックして中断できるようにしておきましょう。cpp-httplibでは`req.is_connection_closed()`で確認できます。
+
+## 基本の使い方
+
+```cpp
+svr.Get("/long-task", [](const httplib::Request &req, httplib::Response &res) {
+  for (int i = 0; i < 1000; ++i) {
+    if (req.is_connection_closed()) {
+      std::cout << "client disconnected" << std::endl;
+      return;
+    }
+
+    do_heavy_work(i);
+  }
+
+  res.set_content("done", "text/plain");
+});
+```
+
+`is_connection_closed()`は`std::function<bool()>`なので、`()`を付けて呼び出します。切断されていれば`true`を返します。
+
+## ストリーミングレスポンスと組み合わせる
+
+`set_chunked_content_provider()`でストリーミング配信しているときも、同じ方法で切断を検出できます。ラムダにキャプチャしておくと便利です。
+
+```cpp
+svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
+  res.set_chunked_content_provider(
+    "text/event-stream",
+    [&req](size_t offset, httplib::DataSink &sink) {
+      if (req.is_connection_closed()) {
+        sink.done();
+        return true;
+      }
+
+      auto event = generate_next_event();
+      sink.write(event.data(), event.size());
+      return true;
+    });
+});
+```
+
+切断を検出したら`sink.done()`を呼んで、プロバイダの呼び出しを止めます。
+
+## どのくらいの頻度でチェックすべきか
+
+毎ループで呼んでも軽い処理ですが、あまりに細かい単位で呼ぶと意味が薄れます。「1チャンクを生成し終えたタイミング」や「データベースの1クエリが終わったタイミング」など、**中断しても安全な境目**で確認するのが現実的です。
+
+> **Warning:** `is_connection_closed()`の確認は即座に正確な値を返すとは限りません。TCPの特性上、送信が止まって初めて切断に気付くことも多いです。完璧なリアルタイム検出を期待せず、「そのうち気付ければいい」くらいの気持ちで使いましょう。

docs-src/pages/ja/cookbook/s17-bind-any-port.md

@@ -0,0 +1,52 @@
+---
+title: "S17. ポートを動的に割り当てる"
+order: 36
+status: "draft"
+---
+
+テスト用サーバーを立てるとき、ポート番号の衝突が面倒なことがあります。`bind_to_any_port()`を使うと、OSに空いているポートを選ばせて、そのポート番号を受け取れます。
+
+## 基本の使い方
+
+```cpp
+httplib::Server svr;
+
+svr.Get("/", [](const auto &req, auto &res) {
+  res.set_content("hello", "text/plain");
+});
+
+int port = svr.bind_to_any_port("0.0.0.0");
+std::cout << "listening on port " << port << std::endl;
+
+svr.listen_after_bind();
+```
+
+`bind_to_any_port()`は第2引数で`0`を渡したのと同じ動作で、OSが空きポートを割り当てます。返り値が実際に使われたポート番号です。
+
+その後、`listen_after_bind()`を呼んで待ち受けを開始します。`listen()`のように「bindとlistenをまとめて行う」ことはできないので、bindとlistenが分かれているこの2段階の書き方になります。
+
+## テストでの活用
+
+単体テストで「サーバーを立ててリクエストを投げる」パターンによく使います。
+
+```cpp
+httplib::Server svr;
+svr.Get("/ping", [](const auto &, auto &res) { res.set_content("pong", "text/plain"); });
+
+int port = svr.bind_to_any_port("127.0.0.1");
+std::thread t([&] { svr.listen_after_bind(); });
+
+// 別スレッドでサーバーが動いている間にテストを走らせる
+httplib::Client cli("127.0.0.1", port);
+auto res = cli.Get("/ping");
+assert(res && res->body == "pong");
+
+svr.stop();
+t.join();
+```
+
+ポート番号がテスト実行時に決まるので、複数のテストが並列実行されても衝突しません。
+
+> **Note:** `bind_to_any_port()`は失敗すると`-1`を返します。権限エラーや利用可能ポートが無いケースなので、返り値のチェックを忘れずに。
+
+> サーバーを止める方法はS19. グレースフルシャットダウンするを参照してください。

docs-src/pages/ja/cookbook/s18-listen-after-bind.md

@@ -0,0 +1,57 @@
+---
+title: "S18. listen_after_bindで起動順序を制御する"
+order: 37
+status: "draft"
+---
+
+普通は`svr.listen("0.0.0.0", 8080)`でbindとlistenをまとめて行いますが、bindした直後に何か処理を差し挟みたいときは、2つを分けて呼べます。
+
+## bindとlistenを分ける
+
+```cpp
+httplib::Server svr;
+
+svr.Get("/", [](const auto &, auto &res) { res.set_content("ok", "text/plain"); });
+
+if (!svr.bind_to_port("0.0.0.0", 8080)) {
+  std::cerr << "bind failed" << std::endl;
+  return 1;
+}
+
+// ここでbindは完了。まだacceptは始まっていない
+drop_privileges();
+signal_ready_to_parent_process();
+
+svr.listen_after_bind(); // acceptループを開始
+```
+
+`bind_to_port()`でポートの確保までを行い、`listen_after_bind()`で実際の待ち受けを開始します。この2段階に分けることで、bindとacceptの間に処理を挟めます。
+
+## よくある用途
+
+**特権降格**: 1023以下のポートにbindするにはroot権限が必要です。bindだけroot権限で行って、その後に一般ユーザーに降格すれば、以降のリクエスト処理は権限が落ちた状態で走ります。
+
+```cpp
+svr.bind_to_port("0.0.0.0", 80);
+drop_privileges();
+svr.listen_after_bind();
+```
+
+**起動完了通知**: 親プロセスやsystemdに「準備完了」を通知してからacceptを開始できます。
+
+**テストの同期**: テストコードで「サーバーがbindされた時点」を確実に捉えてからクライアントを動かせます。
+
+## 戻り値のチェック
+
+`bind_to_port()`は失敗すると`false`を返します。ポートが既に使われている場合などです。必ずチェックしてください。
+
+```cpp
+if (!svr.bind_to_port("0.0.0.0", 8080)) {
+  std::cerr << "port already in use" << std::endl;
+  return 1;
+}
+```
+
+`listen_after_bind()`はサーバーが停止するまでブロックし、正常終了なら`true`を返します。
+
+> **Note:** 空いているポートを自動で選びたいときはS17. ポートを動的に割り当てるを参照してください。こちらも内部では`bind_to_any_port()` + `listen_after_bind()`の組み合わせです。

docs-src/pages/ja/cookbook/s19-graceful-shutdown.md

@@ -0,0 +1,57 @@
+---
+title: "S19. グレースフルシャットダウンする"
+order: 38
+status: "draft"
+---
+
+サーバーを止めるには`Server::stop()`を呼びます。処理中のリクエストがある状態でも安全に呼べるので、SIGINTやSIGTERMを受け取ったときにこれを呼べば、グレースフルなシャットダウンが実現できます。
+
+## 基本の使い方
+
+```cpp
+httplib::Server svr;
+
+svr.Get("/", [](const auto &, auto &res) { res.set_content("ok", "text/plain"); });
+
+std::thread t([&] { svr.listen("0.0.0.0", 8080); });
+
+// メインスレッドで入力を待つなど
+std::cin.get();
+
+svr.stop();
+t.join();
+```
+
+`listen()`はブロックするので、別スレッドで動かして、メインスレッドから`stop()`を呼ぶのが典型的なパターンです。`stop()`後は`listen()`が戻ってくるので、`join()`できます。
+
+## シグナルでシャットダウンする
+
+SIGINT（Ctrl+C）やSIGTERMを受け取ったときに停止させる例です。
+
+```cpp
+#include <csignal>
+
+httplib::Server svr;
+
+// グローバル領域に置いてシグナルハンドラからアクセス
+httplib::Server *g_svr = nullptr;
+
+int main() {
+  svr.Get("/", [](const auto &, auto &res) { res.set_content("ok", "text/plain"); });
+
+  g_svr = &svr;
+  std::signal(SIGINT,  [](int) { if (g_svr) g_svr->stop(); });
+  std::signal(SIGTERM, [](int) { if (g_svr) g_svr->stop(); });
+
+  svr.listen("0.0.0.0", 8080);
+  std::cout << "server stopped" << std::endl;
+}
+```
+
+`stop()`はスレッドセーフで、シグナルハンドラの中から呼んでも安全です。`listen()`がメインスレッドで動いていても、シグナルを受けたら抜けてきます。
+
+## 処理中のリクエストの扱い
+
+`stop()`を呼ぶと、新しい接続は受け付けなくなりますが、すでに処理中のリクエストは**最後まで実行**されます。その後、スレッドプールのワーカーが順次終了し、`listen()`から戻ってきます。これがグレースフルシャットダウンと呼ばれる理由です。
+
+> **Warning:** `stop()`を呼んでから`listen()`が戻るまでには、処理中のリクエストが終わるのを待つ時間がかかります。タイムアウトを強制したい場合は、シャットダウン用のタイマーを別途用意するなど、アプリケーション側の工夫が必要です。

docs-src/pages/ja/cookbook/s20-keep-alive.md

@@ -0,0 +1,57 @@
+---
+title: "S20. Keep-Aliveを調整する"
+order: 39
+status: "draft"
+---
+
+`httplib::Server`はHTTP/1.1のKeep-Aliveを自動で有効にしています。クライアントから見ると接続が再利用されるので、TCPハンドシェイクのコストを毎回払わずに済みます。挙動を細かく調整したいときは、2つのセッターを使います。
+
+## 設定できる項目
+
+| API | デフォルト | 意味 |
+| --- | --- | --- |
+| `set_keep_alive_max_count` | 100 | 1本の接続で受け付けるリクエストの最大数 |
+| `set_keep_alive_timeout` | 5秒 | アイドル状態の接続を閉じるまでの秒数 |
+
+## 基本の使い方
+
+```cpp
+httplib::Server svr;
+
+svr.set_keep_alive_max_count(20);
+svr.set_keep_alive_timeout(10); // 10秒
+
+svr.listen("0.0.0.0", 8080);
+```
+
+`set_keep_alive_timeout()`は`std::chrono`の期間を取るオーバーロードもあります。
+
+```cpp
+using namespace std::chrono_literals;
+svr.set_keep_alive_timeout(10s);
+```
+
+## チューニングの目安
+
+**アイドル接続が多くてリソースを食う**  
+タイムアウトを短めに設定すると、遊んでいる接続がすぐに切れてスレッドが解放されます。
+
+```cpp
+svr.set_keep_alive_timeout(2s);
+```
+
+**APIが集中的に呼ばれて接続再利用の効果を最大化したい**  
+1接続あたりのリクエスト数を増やすと、ベンチマークの結果が良くなります。
+
+```cpp
+svr.set_keep_alive_max_count(1000);
+```
+
+**とにかく接続を使い回したくない**  
+`set_keep_alive_max_count(1)`にすると、1リクエストごとに接続が閉じます。デバッグや互換性検証以外ではあまりおすすめしません。
+
+## スレッドプールとの関係
+
+Keep-Aliveでつながりっぱなしの接続は、その間ずっとワーカースレッドを1つ占有します。接続数 × 同時リクエスト数がスレッドプールのサイズを超えると、新しいリクエストが待たされます。スレッド数の調整はS21. マルチスレッド数を設定するを参照してください。
+
+> **Note:** クライアント側の挙動はC14. 接続の再利用とKeep-Aliveの挙動を理解するを参照してください。サーバーがタイムアウトで接続を切っても、クライアントは自動で再接続します。

docs-src/pages/ja/cookbook/s21-thread-pool.md

@@ -0,0 +1,69 @@
+---
+title: "S21. マルチスレッド数を設定する"
+order: 40
+status: "draft"
+---
+
+cpp-httplibは、リクエストをスレッドプールで並行処理します。デフォルトでは`std::thread::hardware_concurrency() - 1`と`8`のうち大きいほうがベーススレッド数で、負荷に応じてその4倍まで動的にスケールします。スレッド数を明示的に調整したいときは、`new_task_queue`に自分でファクトリを設定します。
+
+## スレッド数を指定する
+
+```cpp
+httplib::Server svr;
+
+svr.new_task_queue = [] {
+  return new httplib::ThreadPool(/*base_threads=*/8, /*max_threads=*/64);
+};
+
+svr.listen("0.0.0.0", 8080);
+```
+
+ファクトリは`TaskQueue*`を返すラムダです。`ThreadPool`にベーススレッド数と最大スレッド数を渡すと、負荷に応じて間のスレッド数が自動で増減します。アイドルになったスレッドは一定時間（デフォルトは3秒）で終了します。
+
+## キューの上限も指定する
+
+キューが溜まりすぎるとメモリを食うので、キューの最大長も指定できます。
+
+```cpp
+svr.new_task_queue = [] {
+  return new httplib::ThreadPool(
+    /*base_threads=*/12,
+    /*max_threads=*/0,   // 動的スケーリング無効
+    /*max_queued_requests=*/18);
+};
+```
+
+`max_threads=0`にすると動的スケーリングが無効になり、固定の`base_threads`だけで処理します。`max_queued_requests`を超えるとリクエストが拒否されます。
+
+## 独自のスレッドプールを使う
+
+自前のスレッドプール実装を差し込むこともできます。`TaskQueue`を継承したクラスを作り、ファクトリから返します。
+
+```cpp
+class MyTaskQueue : public httplib::TaskQueue {
+public:
+  MyTaskQueue(size_t n) { pool_.start_with_thread_count(n); }
+  bool enqueue(std::function<void()> fn) override { return pool_.post(std::move(fn)); }
+  void shutdown() override { pool_.shutdown(); }
+
+private:
+  MyThreadPool pool_;
+};
+
+svr.new_task_queue = [] { return new MyTaskQueue(12); };
+```
+
+既存のスレッドプールライブラリがあるなら、そちらに委譲できるので、プロジェクト内でスレッド管理を統一したいときに便利です。
+
+## ビルド時の調整
+
+コンパイル時に変更したい場合は、マクロで初期値を設定できます。
+
+```cpp
+#define CPPHTTPLIB_THREAD_POOL_COUNT 16       // ベーススレッド数
+#define CPPHTTPLIB_THREAD_POOL_MAX_COUNT 128   // 最大スレッド数
+#define CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT 5  // アイドル終了までの秒数
+#include <httplib.h>
+```
+
+> **Note:** WebSocket接続はその生存期間中ずっと1スレッドを占有します。大量の同時WebSocket接続を扱うなら、動的スケーリングを有効にしておきましょう（`ThreadPool(8, 64)`のように）。