Release v0.61.0

SSEIntegrationTest.DigitRetryFieldApplied slept for 500ms and then
expected a second connection. The first connection, the 100ms wait and
the reconnect do not always fit in that window: the macOS Mbed TLS job
saw only one connection.

Wait until the second connection arrives, and check that it came at
least 100ms after the first one rather than counting connections. The
test no longer depends on how fast the runner is, and takes about 150ms
instead of 500ms.

.github/workflows/test.yaml

@@ -31,12 +31,19 @@ env:
 
 jobs:
   style-check:
-    runs-on: ubuntu-latest
+    # Uses the macOS runner's pre-installed Homebrew so clang-format tracks
+    # whatever version `brew install clang-format` currently resolves to on
+    # the maintainer's own Mac, instead of a version pinned in this file.
+    runs-on: macos-latest
     if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
     continue-on-error: true
     steps:
       - name: checkout
         uses: actions/checkout@v4
+      - name: install clang-format
+        run: |
+          brew update
+          brew install clang-format coreutils
       - name: run style check
         run: |
           clang-format --version
@@ -114,6 +121,9 @@ jobs:
       - name: build and run WebSocket heartbeat test
         if: matrix.tls_backend == 'openssl'
         run: cd test && make test_websocket_heartbeat && ./test_websocket_heartbeat
+      - name: build and run WebSocket TLS thread safety test
+        if: matrix.tls_backend == 'openssl'
+        run: cd test && make test_websocket_thread_safety && ./test_websocket_thread_safety
       - name: build and run ThreadPool test
         run: cd test && make test_thread_pool && ./test_thread_pool
 
@@ -414,6 +424,9 @@ jobs:
       - name: build and run WebSocket heartbeat test
         if: matrix.tls_backend == 'openssl'
         run: cd test && make test_websocket_heartbeat && ./test_websocket_heartbeat
+      - name: build and run WebSocket TLS thread safety test
+        if: matrix.tls_backend == 'openssl'
+        run: cd test && make test_websocket_thread_safety && ./test_websocket_thread_safety
       - name: build and run ThreadPool test
         run: cd test && make test_thread_pool && ./test_thread_pool
 
@@ -469,7 +482,6 @@ jobs:
     runs-on: windows-latest
     permissions:
       contents: read
-      issues: write
     if: >
       (github.event_name == 'push') ||
       (github.event_name == 'pull_request'  &&
@@ -518,7 +530,52 @@ jobs:
       run: vcpkg install gtest curl zlib brotli zstd
     - name: Install OpenSSL
       if: ${{ matrix.config.with_ssl }}
-      run: choco install openssl
+      shell: pwsh
+      run: |
+        # Chocolatey's openssl package hardcodes a versioned slproweb URL, and
+        # slproweb keeps only the newest build of each branch. The package
+        # therefore 404s on every OpenSSL release until someone respins it.
+        # Read slproweb's own manifest instead: it is updated at the same time
+        # as the downloads it points at, so the URL is always live.
+        $ErrorActionPreference = 'Stop'
+        $ProgressPreference = 'SilentlyContinue'  # Invoke-WebRequest is slow with it
+
+        $manifest = 'https://raw.githubusercontent.com/slproweb/opensslhashes/master/win32_openssl_hashes.json'
+        $entry = (Invoke-RestMethod $manifest).files.PSObject.Properties.Value |
+          Where-Object {
+            $_.bits -eq 64 -and $_.arch -eq 'INTEL' -and
+            -not $_.light -and $_.installer -eq 'exe' -and $_.basever -like '4.*'
+          } |
+          Sort-Object { [version]$_.basever } | Select-Object -Last 1
+        if (-not $entry) { throw 'No 64-bit OpenSSL 4.x installer found in the manifest' }
+        Write-Host "Installing OpenSSL $($entry.basever) from $($entry.url)"
+
+        $installer = Join-Path $env:RUNNER_TEMP 'Win64OpenSSL.exe'
+        Invoke-WebRequest $entry.url -OutFile $installer
+        $actual = (Get-FileHash $installer -Algorithm SHA512).Hash.ToLower()
+        if ($actual -ne $entry.sha512.ToLower()) {
+          throw "SHA512 mismatch: expected $($entry.sha512), got $actual"
+        }
+
+        # Same silent flags the Chocolatey package used. The installer is Inno
+        # Setup, so /DIR pins the location CMake already looks in. The inner
+        # quotes matter: ArgumentList joins on spaces, so an unquoted /DIR
+        # would install to C:\Program and only fail later, at load time.
+        $dir = 'C:\Program Files\OpenSSL'
+        $proc = Start-Process $installer -Wait -PassThru -ArgumentList `
+          '/VERYSILENT', '/SUPPRESSMSGBOXES', '/NORESTART', '/SP-', "/DIR=`"$dir`""
+        if ($proc.ExitCode -ne 0) { throw "Installer exited with $($proc.ExitCode)" }
+
+        # Catch a misplaced install here rather than at link or load time.
+        if (-not (Test-Path "$dir\lib\VC\x64\MD\libcrypto.lib")) {
+          throw "OpenSSL import libraries missing under $dir"
+        }
+        if (-not (Get-ChildItem "$dir\bin\libcrypto-*.dll" -ErrorAction SilentlyContinue)) {
+          throw "OpenSSL runtime DLLs missing under $dir\bin"
+        }
+
+        "$dir\bin" | Out-File $env:GITHUB_PATH -Append -Encoding utf8
+        "OPENSSL_CONF=$dir\bin\openssl.cfg" | Out-File $env:GITHUB_ENV -Append -Encoding utf8
     - name: Configure CMake ${{ matrix.config.name }}
       run: >
         cmake -B build -S .
@@ -566,30 +623,6 @@ jobs:
         }
         if ($failed) { exit 1 }
         Write-Host "All shards passed."
-    - name: Report flaky failure on issue #2533
-      if: failure() && matrix.config.name == 'without SSL' && github.event_name == 'push'
-      continue-on-error: true
-      shell: pwsh
-      working-directory: build/test
-      env:
-        GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      run: |
-        $summary = ""
-        for ($i = 0; $i -lt 4; $i++) {
-          $log = "shard_${i}.log"
-          if (Test-Path $log) {
-            $failedLines = Select-String -Path $log -Pattern "\[  FAILED  \]"
-            if ($failedLines) {
-              $summary += "**Shard ${i}:**`n" + (($failedLines | ForEach-Object { $_.Line }) -join "`n") + "`n`n"
-            }
-          }
-        }
-        if (-not $summary) {
-          $summary = "_Could not extract failed test name from shard logs; see the run for details._`n`n"
-        }
-        $runUrl = "$($env:GITHUB_SERVER_URL)/$($env:GITHUB_REPOSITORY)/actions/runs/$($env:GITHUB_RUN_ID)"
-        $body = "Reoccurred on push: $runUrl`n`nCommit: $($env:GITHUB_SHA)`n`n$summary"
-        gh issue comment 2533 --repo $env:GITHUB_REPOSITORY --body $body
 
     env:
       VCPKG_ROOT: "C:/vcpkg"

.gitignore

@@ -1,5 +1,6 @@
 tags
 AGENTS.md
+CLAUDE.md
 docs-src/pages/AGENTS.md
 plans/
 work/
@@ -54,6 +55,7 @@ test/test_split_mbedtls
 test/test_split_wolfssl
 test/test_split_no_tls
 test/test_websocket_heartbeat
+test/test_websocket_thread_safety
 test/test_thread_pool
 test/test_benchmark
 test/test.xcodeproj/xcuser*

.pre-commit-config.yaml

@@ -1,7 +1,12 @@
 repos:
-  - repo: https://github.com/pre-commit/mirrors-clang-format
+  - repo: local
-    rev: v18.1.8  # 最新バージョンを使用
     hooks:
       - id: clang-format
-        files: \.(cpp|cc|h)$
+        name: clang-format
-        args: [-i]  # インプレースで修正
+        # Uses whatever `clang-format` resolves to on PATH (the Homebrew
+        # install on macOS) instead of a version pinned here, so it tracks
+        # the same version CI installs via `brew install clang-format`.
+        entry: clang-format
+        language: system
+        files: ^(httplib\.h|(example|fuzzing|test)/[^/]+\.(cpp|cc|h))$
+        args: [-i]

CMakeLists.txt

@@ -15,7 +15,7 @@
 	* HTTPLIB_REQUIRE_BROTLI (default off)
 	* HTTPLIB_REQUIRE_ZSTD (default off)
 	* HTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES (default off)
-	* HTTPLIB_USE_NON_BLOCKING_GETADDRINFO (default on)
+	* HTTPLIB_USE_NON_BLOCKING_GETADDRINFO (default on when supported)
 	* HTTPLIB_COMPILE (default off)
 	* HTTPLIB_INSTALL (default on)
 	* HTTPLIB_SHARED (default off) builds as a shared library (if HTTPLIB_COMPILE is ON)
@@ -181,6 +181,24 @@ if(HTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES)
 	set(HTTPLIB_IS_USING_MACOSX_AUTOMATIC_ROOT_CERTIFICATES FALSE)
 endif()
 set(HTTPLIB_IS_USING_NON_BLOCKING_GETADDRINFO ${HTTPLIB_USE_NON_BLOCKING_GETADDRINFO})
+if(HTTPLIB_IS_USING_NON_BLOCKING_GETADDRINFO AND WIN32)
+	include(CheckCXXSymbolExists)
+
+	set(_httplib_cmake_required_definitions ${CMAKE_REQUIRED_DEFINITIONS})
+	set(_httplib_cmake_required_libraries ${CMAKE_REQUIRED_LIBRARIES})
+	list(APPEND CMAKE_REQUIRED_DEFINITIONS -D_WIN32_WINNT=0x0A00)
+	list(APPEND CMAKE_REQUIRED_LIBRARIES ws2_32)
+	check_cxx_symbol_exists(GetAddrInfoExCancel "winsock2.h;ws2tcpip.h" HTTPLIB_HAVE_GETADDRINFOEXCANCEL)
+	set(CMAKE_REQUIRED_DEFINITIONS ${_httplib_cmake_required_definitions})
+	set(CMAKE_REQUIRED_LIBRARIES ${_httplib_cmake_required_libraries})
+	unset(_httplib_cmake_required_definitions)
+	unset(_httplib_cmake_required_libraries)
+
+	if(NOT HTTPLIB_HAVE_GETADDRINFOEXCANCEL)
+		set(HTTPLIB_IS_USING_NON_BLOCKING_GETADDRINFO FALSE)
+		message(WARNING "GetAddrInfoExCancel is unavailable; disabling non-blocking getaddrinfo.")
+	endif()
+endif()
 
 # Threads needed for <thread> on some systems, and for <pthread.h> on Linux
 set(THREADS_PREFER_PTHREAD_FLAG TRUE)
@@ -367,7 +385,7 @@ target_link_libraries(${PROJECT_NAME} ${_INTERFACE_OR_PUBLIC}
 		# Needed for API from MacOS Security framework
 		"$<$<AND:$<PLATFORM_ID:Darwin>,$<BOOL:${HTTPLIB_IS_USING_OPENSSL}>,$<BOOL:${HTTPLIB_IS_USING_MACOSX_AUTOMATIC_ROOT_CERTIFICATES}>>:-framework CFNetwork -framework CoreFoundation -framework Security>"
 		# Needed for non-blocking getaddrinfo on MacOS
-		"$<$<AND:$<PLATFORM_ID:Darwin>,$<BOOL:${HTTPLIB_USE_NON_BLOCKING_GETADDRINFO}>>:-framework CFNetwork -framework CoreFoundation>"
+		"$<$<AND:$<PLATFORM_ID:Darwin>,$<BOOL:${HTTPLIB_IS_USING_NON_BLOCKING_GETADDRINFO}>>:-framework CFNetwork -framework CoreFoundation>"
 		# Can't put multiple targets in a single generator expression or it bugs out.
 		$<$<BOOL:${HTTPLIB_IS_USING_BROTLI}>:Brotli::common>
 		$<$<BOOL:${HTTPLIB_IS_USING_BROTLI}>:Brotli::encoder>
@@ -390,7 +408,7 @@ target_compile_definitions(${PROJECT_NAME} ${_INTERFACE_OR_PUBLIC}
 	$<$<BOOL:${HTTPLIB_IS_USING_WOLFSSL}>:CPPHTTPLIB_WOLFSSL_SUPPORT>
 	$<$<BOOL:${HTTPLIB_IS_USING_MBEDTLS}>:CPPHTTPLIB_MBEDTLS_SUPPORT>
 	$<$<AND:$<PLATFORM_ID:Darwin>,$<BOOL:${HTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES}>>:CPPHTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES>
-	$<$<BOOL:${HTTPLIB_USE_NON_BLOCKING_GETADDRINFO}>:CPPHTTPLIB_USE_NON_BLOCKING_GETADDRINFO>
+	$<$<BOOL:${HTTPLIB_IS_USING_NON_BLOCKING_GETADDRINFO}>:CPPHTTPLIB_USE_NON_BLOCKING_GETADDRINFO>
 )
 
 # CMake configuration files installation directory

README-sse.md

@@ -69,7 +69,7 @@ sse.on_error([](httplib::Error err) { });
 #### Configuration
 
 ```cpp
-// Set reconnect interval (default: 3000ms)
+// Set reconnect interval (default: 3000ms, minimum: 100ms)
 sse.set_reconnect_interval(5000);
 
 // Set max reconnect attempts (default: 0 = unlimited)

README-stream.md

@@ -4,7 +4,7 @@ This document describes the streaming extensions for cpp-httplib, providing an i
 
 > **Important Notes**:
 >
-> - **No Keep-Alive**: Each `stream::Get()` call uses a dedicated connection that is closed after the response is fully read. For connection reuse, use `Client::Get()`.
+> - **No Keep-Alive**: Each `stream::Get()` call uses a dedicated connection that is closed when the returned `stream::Result` is destroyed. For connection reuse, use `Client::Get()`.
 > - **Single iteration only**: The `next()` method can only iterate through the body once.
 > - **Result is not thread-safe**: While `stream::Get()` can be called from multiple threads simultaneously, the returned `stream::Result` must be used from a single thread only.
 
@@ -114,7 +114,6 @@ The `httplib.h` header provides a more ergonomic iterator-style API.
 #include "httplib.h"
 
 httplib::Client cli("http://localhost:8080");
-cli.set_follow_location(true);
 ...
 
 // Simple GET
@@ -243,23 +242,29 @@ int main() {
 ```cpp
 #include "httplib.h"
 
+// Keeps the client and its stream alive until the response has been sent.
+struct Upstream {
+    httplib::Client cli{"http://backend:8080"};
+    httplib::ClientImpl::StreamHandle handle;
+};
+
 httplib::Server svr;
 
 svr.Get("/proxy/(.*)", [](const httplib::Request& req, httplib::Response& res) {
-    httplib::Client upstream("http://backend:8080");
+    auto upstream = std::make_shared<Upstream>();
-    auto handle = upstream.open_stream("/" + req.matches[1].str());
+    upstream->handle = upstream->cli.open_stream("GET", "/" + req.matches[1].str());
 
-    if (!handle.is_valid()) {
+    if (!upstream->handle.is_valid()) {
         res.status = 502;
         return;
     }
 
-    res.status = handle.response->status;
+    res.status = upstream->handle.response->status;
     res.set_chunked_content_provider(
-        handle.response->get_header_value("Content-Type"),
+        upstream->handle.response->get_header_value("Content-Type"),
-        [handle = std::move(handle)](size_t, httplib::DataSink& sink) mutable {
+        [upstream](size_t, httplib::DataSink& sink) {
             char buf[8192];
-            auto n = handle.read(buf, sizeof(buf));
+            auto n = upstream->handle.read(buf, sizeof(buf));
             if (n > 0) {
                 sink.write(buf, static_cast<size_t>(n));
                 return true;

README-websocket.md

@@ -57,14 +57,30 @@ if (ws.connect()) {
 
 ```cpp
 enum ReadResult : int {
-    Fail   = 0,  // Connection closed or error
+    Fail    = 0,  // Connection closed or error
-    Text   = 1,  // UTF-8 text message
+    Text    = 1,  // UTF-8 text message
-    Binary = 2,  // Binary message
+    Binary  = 2,  // Binary message
+    Timeout = 3,  // Read timeout elapsed; connection still open
 };
 ```
 
 Returned by `read()`. Since `Fail` is `0`, the result works naturally in boolean contexts — `while (ws.read(msg))` continues until the connection closes. When you need to distinguish text from binary, check the return value directly.
 
+`Timeout` is only returned for a read timeout you set yourself with `set_read_timeout()`. It means the timeout elapsed on a message boundary: nothing was consumed and the connection is still open, so you can send on it and read again. The compile-time defaults (`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`, 300 seconds on the server; a client waits forever) are a backstop against a peer that has gone quiet, not a request for control: when one of them elapses, `read()` returns `Fail` and closes the connection, so code that never calls `set_read_timeout()` can keep using `while (ws.read(msg))`.
+
+**`msg` is left untouched on `Timeout`.** Because `Timeout` is non-zero, `while (ws.read(msg))` keeps looping — with the *previous* message still in `msg`. Once you set a read timeout, test the result instead:
+
+```cpp
+ws.set_read_timeout(std::chrono::milliseconds(100));
+std::string msg;
+while (ws.is_open()) {
+    auto r = ws.read(msg);
+    if (r == httplib::ws::Timeout) { continue; }  // nothing yet; send if you like
+    if (r == httplib::ws::Fail) { break; }
+    handle(msg);
+}
+```
+
 ### CloseStatus
 
 ```cpp
@@ -103,7 +119,7 @@ using SubProtocolSelector =
     std::function<std::string(const std::vector<std::string> &protocols)>;
 ```
 
-The `SubProtocolSelector` receives the list of subprotocols proposed by the client (from the `Sec-WebSocket-Protocol` header) and returns the selected one. Return an empty string to decline all proposed subprotocols.
+The `SubProtocolSelector` receives the list of subprotocols proposed by the client (from the `Sec-WebSocket-Protocol` header) and returns the selected one. Return an empty string to decline all proposed subprotocols. A returned value that the client did not propose is ignored.
 
 ### WebSocket (Server-side)
 
@@ -135,9 +151,8 @@ bool is_open() const;
 explicit WebSocketClient(const std::string &scheme_host_port_path,
                          const Headers &headers = {});
 
-// Constructor with a client certificate for mutual TLS (wss:// only,
+// Constructor with a client certificate for mutual TLS (wss:// only, SSL
-// requires CPPHTTPLIB_OPENSSL_SUPPORT). The certificate is ignored for
+// builds only). The certificate is ignored for ws:// URLs.
-// ws:// URLs.
 struct PemMemory {
   const char *cert_pem;
   size_t cert_pem_len;
@@ -183,7 +198,7 @@ void set_write_timeout(const std::chrono::duration<Rep, Period> &duration);
 template <class Rep, class Period>
 void set_connection_timeout(const std::chrono::duration<Rep, Period> &duration);
 
-// SSL configuration (wss:// only, requires CPPHTTPLIB_OPENSSL_SUPPORT)
+// SSL configuration (wss:// only, SSL builds only)
 void set_ca_cert_path(const std::string &ca_cert_file_path,
                       const std::string &ca_cert_dir_path = std::string());
 void set_ca_cert_store(tls::ca_store_t store);
@@ -327,6 +342,18 @@ svr.WebSocket("/ws", [](const httplib::Request &req, httplib::ws::WebSocket &ws)
 });
 ```
 
+The check above runs after the handshake, so the client sees a successful upgrade followed by a close frame. To refuse the upgrade itself with an HTTP status, use a pre-routing or pre-request handler. Both run before the `101 Switching Protocols` response, and `req.matched_route` is available in the pre-request handler:
+
+```cpp
+svr.set_pre_request_handler([](const httplib::Request &req, httplib::Response &res) {
+    if (req.matched_route == "/ws" && req.get_header_value("Authorization").empty()) {
+        res.status = httplib::StatusCode::Unauthorized_401;
+        return httplib::Server::HandlerResponse::Handled; // not upgraded
+    }
+    return httplib::Server::HandlerResponse::Unhandled;
+});
+```
+
 ### Custom Headers and Timeouts
 
 ```cpp
@@ -409,7 +436,8 @@ if (ws.connect()) {
 | Macro                                       | Default           | Description                                              |
 |---------------------------------------------|-------------------|----------------------------------------------------------|
 | `CPPHTTPLIB_WEBSOCKET_MAX_PAYLOAD_LENGTH`   | `16777216` (16MB) | Maximum payload size per message                         |
-| `CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND`  | `300`             | Read timeout for WebSocket connections (seconds)         |
+| `CPPHTTPLIB_WEBSOCKET_CLIENT_READ_TIMEOUT_SECOND` | `0`         | Client read timeout (seconds); `0` waits forever         |
+| `CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND` | `300`       | Server read timeout (seconds)                            |
 | `CPPHTTPLIB_WEBSOCKET_CLOSE_TIMEOUT_SECOND` | `5`               | Timeout for waiting peer's Close response (seconds)      |
 | `CPPHTTPLIB_WEBSOCKET_PING_INTERVAL_SECOND` | `30`              | Automatic Ping interval for heartbeat (seconds)          |
 | `CPPHTTPLIB_WEBSOCKET_MAX_MISSED_PONGS`     | `0` (disabled)    | Close the connection after N consecutive unacked pings   |
@@ -444,9 +472,9 @@ ws.set_websocket_max_missed_pongs(2); // close after 2 consecutive unacked pings
 
 The server side has the same `set_websocket_max_missed_pongs()`.
 
-With the default ping interval of 30 seconds, `max_missed_pongs = 2` detects a dead peer within ~60 seconds. The counter is reset every time a Pong frame is received, so the mechanism only works when your code is actively calling `read()` — exactly the pattern a normal WebSocket client already uses.
+With the default ping interval of 30 seconds, `max_missed_pongs = 2` detects a dead peer 60 to 90 seconds after it stops answering: the count is checked once per interval, just before the next ping goes out. A `read()` waiting on the peer at that moment returns `Fail`. The counter is reset every time a Pong frame is received, so the mechanism only works when your code is actively calling `read()`, which is exactly the pattern a normal WebSocket client already uses.
 
-**The default is `0`**, which means "never close the connection because of missing pongs." Pings are still sent on the heartbeat interval, but their responses are not checked. Even so, a dead connection does not linger forever: while your code is inside `read()`, `CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND` (default **300 seconds = 5 minutes**) acts as a backstop and `read()` fails if no frame arrives in time. `max_missed_pongs` is the knob for detecting an unresponsive peer faster than that 5-minute fallback.
+**The default is `0`**, which means "never close the connection because of missing pongs." Pings are still sent on the heartbeat interval, but their responses are not checked. On the server side a dead connection still does not linger: while a handler is inside `read()`, `CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND` (default **300 seconds = 5 minutes**) acts as a backstop. A client has no such backstop — it waits forever unless you set a read timeout — so there `max_missed_pongs` is what notices an unresponsive peer at all. On either side it is also the knob for noticing one *faster* than the 5-minute fallback.
 
 ## Threading Model
 
@@ -466,6 +494,14 @@ svr.new_task_queue = [] {
 
 Choose sizes that account for both your expected HTTP load and the maximum number of simultaneous WebSocket connections.
 
+### Calling from Multiple Threads
+
+A single `WebSocket` (server-side) or `WebSocketClient` handle is shared by three potential callers: the thread running your handler (or holding the client), the heartbeat thread, and, if your code does its own thing, a separate thread calling `send()`/`close()` while another thread is blocked in `read()`.
+
+**Supported**: calling `read()` from one thread while calling `send()`/`close()` from another. This is the common pattern for a client that reads incoming messages in a loop on one thread and sends from elsewhere (e.g. a UI thread). A message that is in flight when `close()` is called still arrives intact; `close()` sends the Close frame and returns, leaving the connection's read side to the thread that owns it, so it does not block waiting for the peer's Close reply in that case. The heartbeat thread's automatic pings use the same `send()` path internally, so they are safe to run concurrently with your `read()` loop too — for `wss://` this requires every TLS call on a connection to be serialized internally, which cpp-httplib does for you.
+
+**Not supported**: calling `read()` from two threads at the same time on the same handle. The calls are serialized rather than left to corrupt each other, but which thread receives which message is unspecified, so there is nothing useful to build on it.
+
 ## Protocol
 
 The implementation follows [RFC 6455](https://tools.ietf.org/html/rfc6455):

README.md

@@ -33,7 +33,7 @@ Learn more in the [official documentation](https://yhirose.github.io/cpp-httplib
 httplib::Server svr;
 
 // HTTPS
-httplib::SSLServer svr;
+httplib::SSLServer svr("./cert.pem", "./key.pem");
 
 svr.Get("/hi", [](const httplib::Request &, httplib::Response &res) {
   res.set_content("Hello World!", "text/plain");
@@ -71,7 +71,7 @@ cpp-httplib supports multiple TLS backends through an abstraction layer:
 | wolfSSL | `CPPHTTPLIB_WOLFSSL_SUPPORT` | `libwolfssl` | 5.x supported; must build with `--enable-opensslall` |
 
 > [!NOTE]
-> **Mbed TLS / wolfSSL limitation:** `get_ca_certs()` and `get_ca_names()` only reflect CA certificates loaded via `load_ca_cert_store()`. Certificates loaded through `set_ca_cert_path()` or system certificates (`load_system_certs`) are not enumerable.
+> **wolfSSL limitation:** `get_ca_certs()` and `get_ca_names()` only reflect CA certificates loaded via `load_ca_cert_store()`. Certificates loaded through `set_ca_cert_path()` or system certificates (`load_system_certs`) are not enumerable.
 
 > [!NOTE]
 > **BoringSSL (best-effort):** BoringSSL builds under `CPPHTTPLIB_OPENSSL_SUPPORT` and is exercised by CI against current upstream. Because BoringSSL does not guarantee API stability, support is best-effort — breakage may occasionally land. Two known behavioral differences vs OpenSSL: (1) BoringSSL's public headers require C++14 or later, so consumers must compile accordingly; (2) hostname verification is SAN-only per RFC 6125 §6.4.4 (no CN fallback).
@@ -86,7 +86,7 @@ httplib::SSLServer svr("./cert.pem", "./key.pem");
 
 // Client
 httplib::Client cli("https://localhost:1234"); // scheme + host
-httplib::SSLClient cli("localhost:1234"); // host
+httplib::SSLClient cli("localhost"); // host (port 443)
 httplib::SSLClient cli("localhost", 1234); // host, port
 
 // Use your CA bundle
@@ -103,8 +103,8 @@ cli.enable_server_hostname_verification(false);
 
 When SSL operations fail, cpp-httplib provides detailed error information through `ssl_error()` and `ssl_backend_error()`:
 
-- `ssl_error()` - Returns the TLS-level error code (e.g., `SSL_ERROR_SSL` for OpenSSL)
+- `ssl_error()` - Returns the TLS-level error as a backend-independent `httplib::tls::ErrorCode` value (e.g., `Fatal`, `CertVerifyFailed`), cast to `int`
-- `ssl_backend_error()` - Returns the backend-specific error code (e.g., `ERR_get_error()` for OpenSSL/wolfSSL, return value for Mbed TLS)
+- `ssl_backend_error()` - Returns the backend-specific error code (e.g., `ERR_get_error()` for OpenSSL/wolfSSL, return value for Mbed TLS). With OpenSSL, a certificate verification failure reports the verify result (`X509_V_ERR_*`) here instead
 
 ```c++
 #define CPPHTTPLIB_OPENSSL_SUPPORT  // or CPPHTTPLIB_MBEDTLS_SUPPORT or CPPHTTPLIB_WOLFSSL_SUPPORT
@@ -230,7 +230,7 @@ cpp-httplib automatically integrates with the OS certificate store on macOS and
 | Platform | Behavior | Disable (compile time) |
 | :------- | :------- | :--------------------- |
 | macOS | Loads system certs from Keychain (link `CoreFoundation` and `Security` with `-framework`). Requires Apple Clang; GCC is not supported for this feature. | `CPPHTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES` |
-| Windows | Verifies certs via CryptoAPI (`CertGetCertificateChain` / `CertVerifyCertificateChainPolicy`) with revocation checking | `CPPHTTPLIB_DISABLE_WINDOWS_AUTOMATIC_ROOT_CERTIFICATES_UPDATE` |
+| Windows | Verifies the certificate chain with CryptoAPI (`CertGetCertificateChain` / `CertVerifyCertificateChainPolicy`) instead of the TLS backend. Revocation checking is best-effort: a revoked server certificate is rejected, while one whose revocation status cannot be determined is accepted. Windows fetches missing roots and intermediates on demand. With a custom CA, the TLS backend verifies the chain instead; with `set_server_certificate_verifier()`, both do. | `CPPHTTPLIB_DISABLE_WINDOWS_AUTOMATIC_ROOT_CERTIFICATES_UPDATE` |
 
 On Windows, verification can also be disabled at runtime:
 
@@ -307,6 +307,39 @@ int main(void)
 
 `Post`, `Put`, `Patch`, `Delete` and `Options` methods are also supported.
 
+### Custom HTTP methods
+
+Methods outside the built-in set are rejected with `400 Bad Request` unless a handler is registered for them with `CustomRoute`. This covers the WebDAV methods of RFC 4918, `SUBSCRIBE` and friends from UPnP, and any other extension method.
+
+```c++
+svr.CustomRoute("PROPFIND", "/dav/:id", [](const Request& req, Response& res) {
+  // The request body is available as usual
+  auto id = req.path_params.at("id");
+  res.status = StatusCode::MultiStatus_207;
+  res.set_content(build_multistatus(req.body), "application/xml");
+});
+
+// A content reader overload is available too
+svr.CustomRoute("REPORT", "/dav/.*",
+                [](const Request& req, Response& res,
+                   const ContentReader& content_reader) {
+                  content_reader([&](const char* data, size_t data_length) {
+                    // ...
+                    return true;
+                  });
+                });
+```
+
+Patterns work exactly as they do for `Get` and the other methods, so regular expressions and path parameters are both available.
+
+Note the following:
+
+* The method name must be a valid HTTP method token (RFC 9110) and must be registered before `listen()` is called.
+* `GET`, `HEAD`, `POST`, `PUT`, `DELETE`, `CONNECT`, `OPTIONS`, `TRACE`, `PATCH` and `PRI` cannot be registered this way. Use the dedicated methods above instead.
+* A rejected registration makes `is_valid()` return `false`, and `listen()` then fails rather than starting a server with a route that would never fire.
+* Static file serving remains `GET`/`HEAD` only, and WebSocket upgrades `GET` only.
+* `Allow` and the WebDAV `DAV:` header are not generated automatically. Register an `Options` handler if clients need them.
+
 ### Bind a socket to multiple interfaces and any available port
 
 ```cpp
@@ -314,6 +347,25 @@ int port = svr.bind_to_any_port("0.0.0.0");
 svr.listen_after_bind();
 ```
 
+### Port sharing and exclusive binding
+
+By default, the server socket enables address/port reuse: `SO_REUSEPORT` where it is available (Linux, macOS), and `SO_REUSEADDR` otherwise (Windows). A restarted server can bind again immediately, but binding to a port that another server is already listening on also succeeds, and connections are distributed between them.
+
+If you want `listen()` to fail when the port is already in use, replace the default socket options with `set_socket_options`:
+
+```cpp
+svr.set_socket_options([](socket_t sock) {
+#ifdef _WIN32
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_EXCLUSIVEADDRUSE, 1);
+#else
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_REUSEADDR, 1);
+#endif
+});
+```
+
+> [!NOTE]
+> Setting only `SO_REUSEADDR` is not enough on Windows. There, `SO_REUSEADDR` allows two sockets that both set it to bind to the same port, so use `SO_EXCLUSIVEADDRUSE` instead.
+
 ### Static File Server
 
 ```cpp
@@ -400,6 +452,9 @@ svr.set_logger([](const httplib::Request& req, const httplib::Response& res) {
 });
 ```
 
+> [!NOTE]
+> `req.path` is percent-decoded and may contain control characters such as CR/LF. Escape request data before writing it to a log file (see [docker/main.cc](docker/main.cc) for an example).
+
 #### Pre-compression Logging
 
 You can also set a pre-compression logger to capture request/response data before compression is applied:
@@ -414,6 +469,8 @@ svr.set_pre_compression_logger([](const httplib::Request& req, const httplib::Re
 
 The pre-compression logger is only called when compression would be applied. For responses without compression, only the access logger is called.
 
+For a static file response (see [Static file compression](#static-file-compression)), `res.body` is empty when the logger runs. The bytes are still on disk at that point, not in memory.
+
 #### Error Logging
 
 Error loggers capture failed requests and connection issues. Unlike access loggers, error loggers only receive the Error and Request information, as errors typically occur before a meaningful Response can be generated.
@@ -461,7 +518,7 @@ svr.set_exception_handler([](const auto& req, auto& res, std::exception_ptr ep)
 ```
 
 > [!CAUTION]
-> if you don't provide the `catch (...)` block for a rethrown exception pointer, an uncaught exception will end up causing the server crash. Be careful!
+> If you don't provide the `catch (...)` block for a rethrown exception pointer, an exception that is not a `std::exception` escapes the handler. The server keeps running, but that connection is dropped without a response, and the error logger receives `Error::UserCallbackException`.
 
 ### Pre routing handler
 
@@ -510,22 +567,23 @@ svr.set_pre_request_handler([](const auto& req, auto& res) {
 
 ```
 Request received
-  │
-  ├─ pre_routing_handler          route not matched yet, body not read
-  │     └─ returns Handled → stop here
-  │
-  ├─ file_request_handler         (GET/HEAD, static file serving)
   │
   ├─ expect_100_continue_handler  (when the request has "Expect: 100-continue")
+  │     └─ returns a status other than 100 → go straight to post_routing_handler
+  │
+  ├─ pre_routing_handler          route not matched yet, body not read
+  │     └─ returns Handled → go straight to post_routing_handler
+  │
+  ├─ file_request_handler         when a static file is served (GET only)
   │
   ├─ route matching → req.matched_route is set
   │
   ├─ pre_request_handler          route matched, body NOT read yet
-  │     └─ returns Handled → stop here (route handler is skipped)
+  │     └─ returns Handled → go straight to post_routing_handler
   │
   ├─ route handler                Get/Post/...; the request body is read first
   │
-  └─ post_routing_handler         after routing completes
+  └─ post_routing_handler         just before the response is written
 
   On a thrown exception → exception_handler
   On an error status (4xx/5xx) → error_handler
@@ -533,6 +591,10 @@ Request received
 
 Use `pre_routing_handler` to reject a request as early as possible, before the route is known. Use `pre_request_handler` for route-specific checks, since `req.matched_route` is available and the body has not been read yet.
 
+For a request with `Expect: 100-continue`, the `100 Continue` response is not sent until the body is about to be read. A request rejected before that point (by `pre_routing_handler`, `pre_request_handler`, or because no route matched) gets its final response without `100 Continue`, so the client never sends the body.
+
+A WebSocket upgrade request that matches a route registered with `svr.WebSocket()` takes a shorter path: `pre_routing_handler`, then route matching (`req.matched_route` is set), then `pre_request_handler`, then the WebSocket handler. If either hook returns `Handled`, its response is sent as a regular HTTP response and the connection is not upgraded. Once the connection is upgraded, `post_routing_handler` does not run.
+
 ### Response user data
 
 `res.user_data` is a type-safe key-value store that lets pre-routing or pre-request handlers pass arbitrary data to route handlers.
@@ -549,7 +611,7 @@ svr.set_pre_routing_handler([](const auto& req, auto& res) {
   return Server::HandlerResponse::Unhandled;
 });
 
-svr.Get("/me", [](const auto& /*req*/, auto& res) {
+svr.Get("/me", [](const Request& /*req*/, Response& res) {
   auto* ctx = res.user_data.get<AuthContext>("auth");
   if (!ctx) {
     res.status = StatusCode::Unauthorized_401;
@@ -695,6 +757,12 @@ svr.Post("/content_receiver",
   });
 ```
 
+`CPPHTTPLIB_MULTIPART_FORM_DATA_FILE_MAX_COUNT` (default 1024) caps the number of
+form-data parts only on the buffered path, where every part is accumulated into
+`req.form`. The content receiver keeps nothing, so the cap does not apply here.
+If your handler needs an upper bound on the number of parts, count them yourself
+and return `false` from the callback to stop the parser.
+
 ### Send content with the content provider
 
 ```cpp
@@ -786,7 +854,9 @@ svr.Get("/content", [&](const Request &req, Response &res) {
 
 ### 'Expect: 100-continue' handler
 
-By default, the server sends a `100 Continue` response for an `Expect: 100-continue` header.
+By default, the server accepts an `Expect: 100-continue` header and sends a `100 Continue` response when it starts reading the request body. If the request is answered without reading the body, `100 Continue` is not sent and the connection is closed after the response.
+
+The handler runs before `pre_routing_handler`. Returning `100` lets the request proceed; returning any other status sends that status as the final response and closes the connection.
 
 ```cpp
 // Send a '417 Expectation Failed' response.
@@ -838,7 +908,7 @@ Please see [Server example](https://github.com/yhirose/cpp-httplib/blob/master/e
 
 `ThreadPool` is used as the **default** task queue, with dynamic scaling support. By default, it maintains a base thread count of 8 or `std::thread::hardware_concurrency() - 1` (whichever is greater), and can scale up to 4x that count under load. You can change these with `CPPHTTPLIB_THREAD_POOL_COUNT` and `CPPHTTPLIB_THREAD_POOL_MAX_COUNT`.
 
-When all threads are busy and a new task arrives, a temporary thread is spawned (up to the maximum). When a dynamic thread finishes its task and the queue is empty, or after an idle timeout, it exits automatically. The idle timeout defaults to 3 seconds, configurable via `CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT`.
+When all threads are busy and a new task arrives, a temporary thread is spawned (up to the maximum). A dynamic thread exits automatically once it has waited for the idle timeout without receiving a task. The idle timeout defaults to 3 seconds, configurable via `CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT`.
 
 If you want to set the thread counts at runtime:
 
@@ -972,6 +1042,8 @@ enum class Error {
   HTTPParsing,
   InvalidRangeHeader,
   UnsupportedContentEncoding,
+  WebSocketHandshake,
+  UserCallbackException,
 };
 ```
 
@@ -1187,7 +1259,7 @@ std::string body = ...;
 
 auto res = cli.Post(
   "/stream", body.size(),
-  [](size_t offset, size_t length, DataSink &sink) {
+  [&](size_t offset, size_t length, DataSink &sink) {
     sink.write(body.data() + offset, length);
     return true; // return 'false' if you want to cancel the request.
   },
@@ -1240,7 +1312,7 @@ cli.set_bearer_token_auth("token");
 ```
 
 > [!NOTE]
-> OpenSSL is required for Digest Authentication.
+> A TLS backend (OpenSSL, Mbed TLS, or wolfSSL) is required for Digest Authentication.
 
 ### Proxy server support
 
@@ -1258,12 +1330,12 @@ cli.set_proxy_bearer_token_auth("pass");
 ```
 
 > [!NOTE]
-> OpenSSL is required for Digest Authentication.
+> A TLS backend (OpenSSL, Mbed TLS, or wolfSSL) is required for Digest Authentication.
 
 #### Bypass the proxy for specific hosts (`NO_PROXY`)
 
 ```cpp
-cli.set_no_proxy({"internal.corp", "10.0.0.0/8", "*.dev.local"});
+cli.set_no_proxy({"internal.corp", "10.0.0.0/8", ".dev.local"});
 ```
 
 Each pattern is `*`, a hostname suffix, an IP literal, or a CIDR block.
@@ -1408,8 +1480,8 @@ for (auto it = req.headers.equal_range("Accept-Encoding").first;
   std::cout << it->second << std::endl;
 }
 
-// get_header_value(key, id) reaches a specific one directly.
+// get_header_value(key, def, id) reaches a specific one directly.
-auto second = req.get_header_value("Accept-Encoding", 1); // "br"
+auto second = req.get_header_value("Accept-Encoding", "", 1); // "br"
 ```
 
 `Headers` matches field names case-insensitively, as before. `Params`, `FormFields`, and `FormFiles` are case-sensitive.
@@ -1419,7 +1491,7 @@ auto second = req.get_header_value("Accept-Encoding", 1); // "br"
 
 ## Payload Limit
 
-The maximum payload body size is limited to 100MB by default for both server and client. You can change it with `set_payload_max_length()` or by defining `CPPHTTPLIB_PAYLOAD_MAX_LENGTH` at compile time. Setting it to `0` disables the limit entirely.
+The maximum payload body size is limited to 100MB by default for both server and client. You can change it with `set_payload_max_length()` or by defining `CPPHTTPLIB_PAYLOAD_MAX_LENGTH` at compile time. Setting it to `0` disables the limit entirely. On the client, a request made with a content receiver is not limited unless you call `set_payload_max_length()` yourself, so that a large download can be streamed without raising the limit first.
 
 ## Compression
 
@@ -1428,10 +1500,54 @@ The server can apply compression to the following MIME type contents:
 - all text types except text/event-stream
 - image/svg+xml
 - application/javascript
+- application/x-javascript
 - application/json
+- application/ld+json
 - application/xml
-- application/protobuf
 - application/xhtml+xml
+- application/rss+xml
+- application/atom+xml
+- application/xslt+xml
+- application/protobuf
+
+A response that already carries `Content-Encoding` is sent as it is. A handler serving content it encoded itself, an asset compressed at build time for instance, keeps its own coding and its own bytes:
+
+```c++
+svr.Get("/app.js", [](const Request & /*req*/, Response &res) {
+  res.set_header("Content-Encoding", "gzip");
+  res.set_content(gzipped_asset, "application/javascript");
+});
+```
+
+This holds for every kind of response, including the file-backed ones below.
+
+`Vary: Accept-Encoding` is added only to responses the server encoded itself. A handler that chooses between an encoded and an identity representation by reading `Accept-Encoding` should set the field itself, so that shared caches keep the two apart.
+
+### Static file compression
+
+Responses served from a file, whether through `set_mount_point()` or `Response::set_file_content()`, are sent as is by default. Turn compression on for them with:
+
+```c++
+svr.set_static_file_compression(true);
+```
+
+Only files within a size range are compressed, and both ends of it can be moved:
+
+```c++
+svr.set_static_file_compression_min_length(512);
+svr.set_static_file_compression_max_length(1024 * 1024);
+```
+
+The lower bound defaults to 1400 bytes. A response that already fits in a single 1500-byte MTU is not delivered any faster for being smaller, and a file of a few bytes comes back larger than it went in, since gzip's header and trailer outweigh what deflate saves. `0` compresses everything down to a single byte, and `CPPHTTPLIB_STATIC_FILE_COMPRESSION_MIN_LENGTH` sets the default at compile time. An empty file is never compressed regardless.
+
+The upper bound defaults to 4MB, and exists for a different reason: the file is compressed per request, and the compressed bytes are held in memory until the response has been written, so the peak cost scales with the number of requests in flight. It is a bound on what one request can cost, not a statement about how well large files compress, which is why raising it is reasonable when the files are known and the traffic is not. `0` removes the limit, and `CPPHTTPLIB_STATIC_FILE_COMPRESSION_MAX_LENGTH` sets the default at compile time.
+
+A compressed response keeps its `Content-Length`, so `HEAD` still reports the size a `GET` would return. Two details are worth knowing:
+
+- Range requests are answered from the uncompressed representation, so `Content-Range` keeps naming the file's own bytes.
+- The `ETag` carries the coding it belongs to (`W/"...-gzip"`), so a client that cached the compressed form revalidates against the right validator.
+
+Content providers registered with `set_content_provider()` are not covered. Feeding one through a compressor would hold each write back until the compressor's window filled, which breaks providers that produce their body incrementally. Use `set_chunked_content_provider()` to compress a generated body.
 
 ### Zlib Support
 
@@ -1481,7 +1597,6 @@ res->body; // Compressed data
 Unix Domain Socket Support
 --------------------------
 
-Unix Domain Socket support is available on Linux and macOS.
 
 ```c++
 // Server
@@ -1530,7 +1645,6 @@ Process large responses without loading everything into memory.
 
 ```c++
 httplib::Client cli("localhost", 8080);
-cli.set_follow_location(true);
 ...
 
 auto result = httplib::stream::Get(cli, "/large-file");
@@ -1610,7 +1724,7 @@ SSL is also supported via `wss://` scheme (e.g. `WebSocketClient("wss://example.
 
 > **WebSocket extensions are not supported.** `permessage-deflate` and other RFC 6455 extensions are not implemented. If a client proposes them via `Sec-WebSocket-Extensions`, the server silently declines them in its handshake response.
 
-> **Unresponsive-peer detection.** Heartbeat pings also serve as a liveness probe when `set_websocket_max_missed_pongs(n)` is set: if the client sends `n` consecutive pings without receiving a pong, it will close the connection. Disabled by default (`0`).
+> **Unresponsive-peer detection.** Heartbeat pings also serve as a liveness probe when `set_websocket_max_missed_pongs(n)` is set: once `n` consecutive pings have gone unanswered, the connection is closed and a `read()` waiting on it fails. Both `WebSocketClient` and `Server` have the setter. Disabled by default (`0`).
 
 See [README-websocket.md](README-websocket.md) for more details.
 
@@ -1619,12 +1733,14 @@ See [README-websocket.md](README-websocket.md) for more details.
 `set_socket_opt` is a convenience wrapper around `setsockopt` for setting integer socket options:
 
 ```cpp
-auto sock = svr.socket();
+svr.set_socket_options([](socket_t sock) {
-httplib::set_socket_opt(sock, IPPROTO_TCP, TCP_NODELAY, 1);
+  httplib::default_socket_options(sock);
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_KEEPALIVE, 1);
+});
 ```
 
 > [!TIP]
-> For most use cases, prefer `set_tcp_nodelay(true)` or `set_socket_options(callback)` on the Server/Client instead of calling `set_socket_opt` directly.
+> `set_socket_options` replaces the default socket options, so call `default_socket_options()` in the callback to keep them. For `TCP_NODELAY`, `set_tcp_nodelay(true)` is simpler.
 
 ## Split httplib.h into .h and .cc
 
@@ -1653,7 +1769,9 @@ Dockerfile for static HTTP server is available. Port number of this HTTP server
 ...
 
 > docker run --rm -it -p 8080:80 -v ./docker/html:/html cpp-httplib-server
-Serving HTTP on 0.0.0.0 port 80 ...
+Serving HTTP on 0.0.0.0:80
+Mount point: / -> ./html
+Press Ctrl+C to shutdown gracefully...
 192.168.65.1 - - [31/Aug/2024:21:33:56 +0000] "GET / HTTP/1.1" 200 599 "-" "curl/8.7.1"
 192.168.65.1 - - [31/Aug/2024:21:34:26 +0000] "GET / HTTP/1.1" 200 599 "-" "Mozilla/5.0 ..."
 192.168.65.1 - - [31/Aug/2024:21:34:26 +0000] "GET /favicon.ico HTTP/1.1" 404 152 "-" "Mozilla/5.0 ..."
@@ -1663,7 +1781,9 @@ From Docker Hub
 
 ```bash
 > docker run --rm -it -p 8080:80 -v ./docker/html:/html yhirose4dockerhub/cpp-httplib-server
-Serving HTTP on 0.0.0.0 port 80 ...
+Serving HTTP on 0.0.0.0:80
+Mount point: / -> ./html
+Press Ctrl+C to shutdown gracefully...
 192.168.65.1 - - [31/Aug/2024:21:33:56 +0000] "GET / HTTP/1.1" 200 599 "-" "curl/8.7.1"
 192.168.65.1 - - [31/Aug/2024:21:34:26 +0000] "GET / HTTP/1.1" 200 599 "-" "Mozilla/5.0 ..."
 192.168.65.1 - - [31/Aug/2024:21:34:26 +0000] "GET /favicon.ico HTTP/1.1" 404 152 "-" "Mozilla/5.0 ..."
@@ -1675,19 +1795,13 @@ NOTE
 ### Regular Expression Stack Overflow
 
 > [!CAUTION]
-> When using complex regex patterns in route handlers, be aware that certain patterns may cause stack overflow during pattern matching. This is a known issue with `std::regex` implementations and affects the `dispatch_request()` method.
+> `std::regex` implementations can overflow the stack while matching a long input, even with a pattern as simple as `.*`. To keep a request from triggering this, a regex route is never applied to a path longer than `CPPHTTPLIB_REGEX_ROUTE_PATH_MAX_LENGTH` (256 by default); such a path does not match the route. Raising the limit brings the risk back with it.
+>
+> Path parameters are matched without `std::regex` and have no such limit, so prefer them where they fit:
 >
 > ```cpp
-> // This pattern can cause stack overflow with large input
-> svr.Get(".*", handler);
-> ```
-> 
-> Consider using simpler patterns or path parameters to avoid this issue:
-> 
-> ```cpp
-> // Safer alternatives
 > svr.Get("/users/:id", handler);           // Path parameters
-> svr.Get(R"(/api/v\d+/.*)", handler);     // More specific patterns
+> svr.Get(R"(/api/v\d+/.*)", handler);     // Regex route, limited to short paths
 > ```
 
 ### g++

benchmark/ab.sh

@@ -3,7 +3,25 @@
 # A/B throughput comparison between two git refs.
 #
 # Usage: ./ab.sh [--base REF] [--head REF] [--rounds N] [--duration S]
-#                [--connections N] [--threads N]
+#                [--connections N] [--threads N] [--path PATH] [--tls]
+#                [--large-mib N] [--timeout S]
+#
+# --path selects the workload. The harness serves:
+#   /                  small body via set_content(); the response line, the
+#                      headers and the body already share a single write(), so
+#                      this is the least sensitive case
+#   /large             large body via set_content()
+#   /static/small.js   1 KiB file from a mount point, where the headers and the
+#                      body are two separate writes
+#   /static/large.bin  same, with the body large enough to dominate
+#
+# --large-mib sizes the two large workloads (default 1).
+#
+# --tls runs the same workload over HTTPS, which writes through
+# SSLSocketStream instead of SocketStream.
+#
+# --timeout is bombardier's per-request timeout. Its 2s default aborts large
+# TLS responses, and the run then fails on the non-2xx check.
 #
 # Absolute numbers from a single run are meaningless: on a quiet 8-core laptop
 # the same binary varies by +/-20% run to run, and shared CI runners are worse.
@@ -21,6 +39,10 @@ DURATION="5s"
 CONNECTIONS=10
 THREADS=""
 PORT=8080
+REQ_PATH="/"
+TLS=0
+LARGE_MIB=1
+TIMEOUT="30s"
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -30,6 +52,10 @@ while [ $# -gt 0 ]; do
     --duration) DURATION="$2"; shift 2 ;;
     --connections) CONNECTIONS="$2"; shift 2 ;;
     --threads) THREADS="$2"; shift 2 ;;
+    --path) REQ_PATH="$2"; shift 2 ;;
+    --large-mib) LARGE_MIB="$2"; shift 2 ;;
+    --timeout) TIMEOUT="$2"; shift 2 ;;
+    --tls) TLS=1; shift ;;
     *) echo "Unknown option: $1" >&2; exit 1 ;;
   esac
 done
@@ -62,6 +88,7 @@ HEAD_SHA=$(git -C "$REPO_ROOT" rev-parse --short "$HEAD_REF")
 echo "==> base: $BASE_REF ($BASE_SHA)"
 echo "==> head: $HEAD_REF ($HEAD_SHA)"
 echo "==> rounds=$ROUNDS duration=$DURATION connections=$CONNECTIONS threads=$THREADS"
+echo "==> path=$REQ_PATH tls=$TLS large=${LARGE_MIB}MiB"
 echo ""
 
 if [ "$BASE_SHA" = "$HEAD_SHA" ]; then
@@ -69,18 +96,49 @@ if [ "$BASE_SHA" = "$HEAD_SHA" ]; then
   echo ""
 fi
 
+# --- Toolchain bits that depend on --tls ---
+SCHEME="http"
+INSECURE=""
+TLS_CXXFLAGS=""
+TLS_LDFLAGS=""
+TLS_ARGS=""
+if [ "$TLS" = "1" ]; then
+  SCHEME="https"
+  INSECURE="-k"
+  TLS_CXXFLAGS="-DCPPHTTPLIB_OPENSSL_SUPPORT"
+  TLS_LDFLAGS="-lssl -lcrypto"
+  if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists openssl; then
+    TLS_CXXFLAGS="$TLS_CXXFLAGS $(pkg-config --cflags openssl)"
+    TLS_LDFLAGS="$(pkg-config --libs openssl)"
+  elif command -v brew >/dev/null 2>&1 && brew --prefix openssl >/dev/null 2>&1; then
+    OPENSSL_PREFIX=$(brew --prefix openssl)
+    TLS_CXXFLAGS="$TLS_CXXFLAGS -I$OPENSSL_PREFIX/include"
+    TLS_LDFLAGS="-L$OPENSSL_PREFIX/lib -lssl -lcrypto"
+  fi
+  if [ "$(uname -s)" = "Darwin" ]; then
+    TLS_LDFLAGS="$TLS_LDFLAGS -framework CoreFoundation -framework Security"
+  fi
+  TLS_ARGS="--cert $REPO_ROOT/test/cert.pem --key $REPO_ROOT/test/key.pem"
+  for f in "$REPO_ROOT/test/cert.pem" "$REPO_ROOT/test/key.pem"; do
+    [ -f "$f" ] || { echo "Error: $f not found" >&2; exit 1; }
+  done
+fi
+
 # --- Build both refs ---
+# The harness source always comes from the invoking worktree, so both refs run
+# an identical workload and a ref that predates a harness change stays
+# measurable. Only httplib.h varies, through -I.
+HARNESS="$REPO_ROOT/benchmark/cpp-httplib/main.cpp"
+[ -f "$HARNESS" ] || { echo "Error: $HARNESS not found" >&2; exit 1; }
+
 build() {
   local name=$1 ref=$2
   git -C "$REPO_ROOT" worktree add --detach --quiet "$WORKDIR/$name" "$ref"
-  if [ ! -f "$WORKDIR/$name/benchmark/cpp-httplib/main.cpp" ]; then
-    echo "Error: benchmark/cpp-httplib/main.cpp missing in $ref" >&2
-    exit 1
-  fi
   "$CXX" -o "$WORKDIR/$name/server-ab" -O2 -std=c++11 \
     -I"$WORKDIR/$name" \
     -DCPPHTTPLIB_THREAD_POOL_COUNT="$THREADS" \
-    "$WORKDIR/$name/benchmark/cpp-httplib/main.cpp" -lpthread
+    $TLS_CXXFLAGS \
+    "$HARNESS" -lpthread $TLS_LDFLAGS
 }
 
 echo "==> Building..."
@@ -92,7 +150,8 @@ measure() {
   local name=$1
   local json rc
 
-  "$WORKDIR/$name/server-ab" >/dev/null 2>&1 &
+  "$WORKDIR/$name/server-ab" --port "$PORT" --dir "$WORKDIR/$name-www" \
+    --large-mib "$LARGE_MIB" $TLS_ARGS >/dev/null 2>&1 &
   local pid=$!
 
   # Wait for the listener (no dependency on nc)
@@ -103,8 +162,8 @@ measure() {
   done
 
   set +e
-  json=$(bombardier -c "$CONNECTIONS" -d "$DURATION" -o json -p r \
+  json=$(bombardier -c "$CONNECTIONS" -d "$DURATION" -t "$TIMEOUT" -o json -p r $INSECURE \
-    "http://127.0.0.1:$PORT/" 2>/dev/null)
+    "$SCHEME://127.0.0.1:$PORT$REQ_PATH" 2>/dev/null)
   rc=$?
   set -e
 

benchmark/cpp-httplib/main.cpp

@@ -1,12 +1,139 @@
 #include "httplib.h"
+
+#include <cstdlib>
+#include <cstring>
+#include <fstream>
+#include <string>
+
+#ifndef _WIN32
+#include <sys/stat.h>
+#include <sys/types.h>
+#endif
+
 using namespace httplib;
 
-int main() {
+namespace {
-  Server svr;
 
+// The workloads differ in which part of the write path they exercise:
+//
+//   /                 small body set through set_content(); the response line,
+//                     the headers and the body already share a single write()
+//   /large            large body set through set_content(); the body is copied
+//                     into the header buffer before that single write().
+//                     --large-mib sets its size (and large.bin's).
+//   /static/small.js  small file served from a mount point, where the headers
+//                     and the body are two separate writes
+//   /static/large.bin same, with the body large enough to dominate
+//
+// Bodies are generated at startup so the repository carries no fixtures.
+
+const size_t SMALL_SIZE = 1024;
+const size_t LARGE_SIZE_DEFAULT_MIB = 1;
+
+std::string filler(size_t n) {
+  std::string s;
+  s.reserve(n);
+  while (s.size() < n) {
+    s += "0123456789abcdef";
+  }
+  s.resize(n);
+  return s;
+}
+
+bool write_file(const std::string &path, const std::string &content) {
+  std::ofstream f(path.c_str(), std::ios::binary);
+  f.write(content.data(), static_cast<std::streamsize>(content.size()));
+  return f.good();
+}
+
+std::string default_dir() {
+  const char *tmp = std::getenv("TMPDIR");
+  std::string base = tmp && *tmp ? tmp : "/tmp";
+  if (!base.empty() && base[base.size() - 1] == '/') {
+    base.erase(base.size() - 1);
+  }
+  return base + "/cpp-httplib-bench";
+}
+
+bool make_dir(const std::string &path) {
+#ifdef _WIN32
+  return _mkdir(path.c_str()) == 0 || errno == EEXIST;
+#else
+  return ::mkdir(path.c_str(), 0755) == 0 || errno == EEXIST;
+#endif
+}
+
+void setup(Server &svr, const std::string &large, const std::string &dir) {
   svr.Get("/", [](const Request &, Response &res) {
     res.set_content("Hello World!", "text/plain");
   });
 
-  svr.listen("0.0.0.0", 8080);
+  svr.Get("/large", [&large](const Request &, Response &res) {
+    res.set_content(large, "application/octet-stream");
+  });
+
+  svr.set_mount_point("/static", dir);
+}
+
+} // namespace
+
+int main(int argc, char *argv[]) {
+  int port = 8080;
+  std::string dir = default_dir();
+  std::string cert;
+  std::string key;
+  size_t large_mib = LARGE_SIZE_DEFAULT_MIB;
+
+  for (int i = 1; i < argc; i++) {
+    auto last = i + 1 < argc;
+    if (!std::strcmp(argv[i], "--port") && last) {
+      port = std::atoi(argv[++i]);
+    } else if (!std::strcmp(argv[i], "--large-mib") && last) {
+      large_mib = static_cast<size_t>(std::atoi(argv[++i]));
+    } else if (!std::strcmp(argv[i], "--dir") && last) {
+      dir = argv[++i];
+    } else if (!std::strcmp(argv[i], "--cert") && last) {
+      cert = argv[++i];
+    } else if (!std::strcmp(argv[i], "--key") && last) {
+      key = argv[++i];
+    } else {
+      std::fprintf(stderr,
+                   "usage: %s [--port N] [--dir PATH] [--large-mib N]"
+                   " [--cert PATH --key PATH]\n",
+                   argv[0]);
+      return 2;
+    }
+  }
+
+  if (!make_dir(dir)) {
+    std::fprintf(stderr, "cannot create %s\n", dir.c_str());
+    return 1;
+  }
+
+  auto large = filler(large_mib * 1024 * 1024);
+  if (!write_file(dir + "/small.js", filler(SMALL_SIZE)) ||
+      !write_file(dir + "/large.bin", large)) {
+    std::fprintf(stderr, "cannot write fixtures under %s\n", dir.c_str());
+    return 1;
+  }
+
+  if (!cert.empty()) {
+#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
+    SSLServer svr(cert.c_str(), key.c_str());
+    if (!svr.is_valid()) {
+      std::fprintf(stderr, "cannot load %s / %s\n", cert.c_str(), key.c_str());
+      return 1;
+    }
+    setup(svr, large, dir);
+    svr.listen("0.0.0.0", port);
+    return 0;
+#else
+    std::fprintf(stderr, "built without CPPHTTPLIB_OPENSSL_SUPPORT\n");
+    return 1;
+#endif
+  }
+
+  Server svr;
+  setup(svr, large, dir);
+  svr.listen("0.0.0.0", port);
 }

docker/main.cc

@@ -48,6 +48,23 @@ std::string get_error_time_format() {
   return ss.str();
 }
 
+// Escape a value for a log line the way NGINX does: '"', '\\', control
+// bytes and non-ASCII bytes become \xHH. Request fields are attacker-controlled
+// (e.g. a raw CR in the request target or a decoded %0D%0A in req.path), so
+// writing them verbatim would let a client forge extra log lines.
+std::string escape_log(const std::string &s) {
+  std::string out;
+  out.reserve(s.size());
+  for (unsigned char c : s) {
+    if (c == '"' || c == '\\' || c < 0x20 || c >= 0x7f) {
+      out += std::format("\\x{:02X}", c);
+    } else {
+      out += static_cast<char>(c);
+    }
+  }
+  return out;
+}
+
 // NGINX Combined log format:
 // $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent
 // "$http_referer" "$http_user_agent"
@@ -55,18 +72,22 @@ void nginx_access_logger(const Request &req, const Response &res) {
   std::string remote_user =
       "-"; // cpp-httplib doesn't have built-in auth user tracking
   auto time_local = get_time_format();
-  auto request = std::format("{} {} {}", req.method, req.path, req.version);
+  // $request is the original request line, so log the raw target rather than
+  // the percent-decoded req.path.
+  auto request = std::format("{} {} {}", req.method, req.target, req.version);
   auto status = res.status;
-  auto body_bytes_sent = res.body.size();
+  // A static file is sent by a content provider, which leaves res.body empty.
+  auto body_bytes_sent =
+      req.method == "HEAD" ? 0 : res.get_header_value_u64("Content-Length");
   auto http_referer = req.get_header_value("Referer");
   if (http_referer.empty()) http_referer = "-";
   auto http_user_agent = req.get_header_value("User-Agent");
   if (http_user_agent.empty()) http_user_agent = "-";
 
   std::cout << std::format("{} - {} [{}] \"{}\" {} {} \"{}\" \"{}\"",
-                           req.remote_addr, remote_user, time_local, request,
+                           req.remote_addr, remote_user, time_local,
-                           status, body_bytes_sent, http_referer,
+                           escape_log(request), status, body_bytes_sent,
-                           http_user_agent)
+                           escape_log(http_referer), escape_log(http_user_agent))
             << std::endl;
 }
 
@@ -79,14 +100,15 @@ void nginx_error_logger(const Error &err, const Request *req) {
 
   if (req) {
     auto request =
-        std::format("{} {} {}", req->method, req->path, req->version);
+        std::format("{} {} {}", req->method, req->target, req->version);
     auto host = req->get_header_value("Host");
     if (host.empty()) host = "-";
 
     std::cerr << std::format("{} [{}] {}, client: {}, request: "
                              "\"{}\", host: \"{}\"",
                              time_local, level, to_string(err),
-                             req->remote_addr, request, host)
+                             req->remote_addr, escape_log(request),
+                             escape_log(host))
               << std::endl;
   } else {
     // If no request context, just log the error

docs-src/config.toml

@@ -4,7 +4,7 @@ langs = ["en", "ja"]
 
 [site]
 title = "cpp-httplib"
-version = "0.53.0"
+version = "0.61.0"
 hostname = "https://yhirose.github.io"
 base_path = "/cpp-httplib"
 footer_message = "© 2026 Yuji Hirose. All rights reserved."

docs-src/pages/en/cookbook/c02-json.md

@@ -17,7 +17,7 @@ auto res = cli.Post("/api/users", j.dump(), "application/json");
 
 Pass the JSON string as the second argument to `Post()` and the Content-Type as the third. The same pattern works with `Put()` and `Patch()`.
 
-> **Warning:** If you omit the Content-Type (the third argument), the server may not recognize the body as JSON. Always specify `"application/json"`.
+> **Warning:** If the Content-Type (the third argument) is anything other than `"application/json"`, the server may not recognize the body as JSON. Always specify `"application/json"`.
 
 ## Receive a JSON response
 

docs-src/pages/en/cookbook/c11-progress-callback.md

@@ -21,7 +21,7 @@ auto res = cli.Get("/large-file",
 std::cout << std::endl;
 ```
 
-The callback fires each time data arrives. `total` comes from the Content-Length header — if the server doesn't send one, it may be `0`. In that case, you can't compute a percentage, so just display bytes received.
+The callback fires each time data arrives. `total` comes from the Content-Length header. For a response without one (chunked transfer, for example), the progress callback is not called at all.
 
 ## Upload progress
 
@@ -54,6 +54,8 @@ auto res = cli.Get("/large-file",
   });
 ```
 
+> **Note:** A response without Content-Length never calls the progress callback, so it cannot be cancelled this way. Return `false` from a `ContentReceiver` instead.
+
 > **Note:** `ContentReceiver` and the progress callback can be used together. When you want to stream to a file and show progress at the same time, pass both.
 
 > For a concrete example of saving to a file, see [C01. Get the response body / save to a file](../c01-get-response-body).

docs-src/pages/en/cookbook/c13-max-timeout.md

@@ -16,7 +16,7 @@ cli.set_max_timeout(5000); // 5 seconds (in milliseconds)
 auto res = cli.Get("/slow-endpoint");
 ```
 
-The value is in milliseconds. Connection, send, and receive together — the whole request is aborted if it exceeds the limit.
+The value is in milliseconds. Once that much time has passed since the request started, waiting for the response is cut off. The limit does not shorten the connection and write waits themselves, so bound those with `set_connection_timeout` and `set_write_timeout`.
 
 ## Use `std::chrono`
 

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

@@ -4,30 +4,29 @@ order: 14
 status: "draft"
 ---
 
-When you send multiple requests through the same `httplib::Client` instance, the TCP connection is reused automatically. HTTP/1.1 Keep-Alive does the work for you — you don't pay the TCP and TLS handshake cost on every call.
+By default, `httplib::Client` closes the connection after every request (it sends `Connection: close`). Call `set_keep_alive(true)` and the requests you send through the same instance share one TCP connection, so you don't pay the TCP and TLS handshake cost on every call.
 
-## Connections are reused automatically
+## Enable Keep-Alive
 
 ```cpp
 httplib::Client cli("https://api.example.com");
+cli.set_keep_alive(true);
 
 auto res1 = cli.Get("/users/1");
 auto res2 = cli.Get("/users/2"); // reuses the same connection
 auto res3 = cli.Get("/users/3"); // reuses the same connection
 ```
 
-No special config required. Just hold on to `cli` — internally, the socket stays open across calls. The effect is especially noticeable over HTTPS, where the TLS handshake is expensive.
+After that, just hold on to `cli`. Internally, the socket stays open across calls. The effect is especially noticeable over HTTPS, where the TLS handshake is expensive.
 
-## Disable Keep-Alive explicitly
+## Turn Keep-Alive back off
 
-To force a fresh connection every time, call `set_keep_alive(false)`. Mostly useful for testing.
+To go back to a fresh connection every time, call `set_keep_alive(false)`. This is the default behavior.
 
 ```cpp
 cli.set_keep_alive(false);
 ```
 
-For normal use, leave it on (the default).
-
 ## Don't create a `Client` per request
 
 If you create a `Client` inside a loop and let it fall out of scope each iteration, you lose the reuse benefit. Create the instance outside the loop.
@@ -36,11 +35,13 @@ If you create a `Client` inside a loop and let it fall out of scope each iterati
 // Bad: a new connection every iteration
 for (auto id : ids) {
   httplib::Client cli("https://api.example.com");
+  cli.set_keep_alive(true);
   cli.Get("/users/" + id);
 }
 
 // Good: the connection is reused
 httplib::Client cli("https://api.example.com");
+cli.set_keep_alive(true);
 for (auto id : ids) {
   cli.Get("/users/" + id);
 }
@@ -50,4 +51,4 @@ for (auto id : ids) {
 
 If you want to send requests in parallel from multiple threads, give each thread its own `Client` instance. A single `Client` uses a single TCP connection, so firing concurrent requests at the same instance ends up serializing them anyway.
 
-> **Note:** If the server closes the connection after its Keep-Alive timeout, cpp-httplib reconnects and retries transparently. You don't need to handle this in application code.
+> **Note:** If the server closes the connection after its Keep-Alive timeout, cpp-httplib notices before it sends the next request and reconnects. You don't need to handle this in application code.

docs-src/pages/en/cookbook/c15-compression.md

@@ -4,7 +4,7 @@ order: 15
 status: "draft"
 ---
 
-cpp-httplib supports compression when sending and decompression when receiving. You just need to build it with zlib or Brotli enabled.
+cpp-httplib supports compression when sending and decompression when receiving. You just need to build it with zlib, Brotli, or Zstd enabled.
 
 ## Build-time setup
 
@@ -13,10 +13,11 @@ To use compression, define these macros before including `httplib.h`:
 ```cpp
 #define CPPHTTPLIB_ZLIB_SUPPORT    // gzip / deflate
 #define CPPHTTPLIB_BROTLI_SUPPORT  // brotli
+#define CPPHTTPLIB_ZSTD_SUPPORT    // zstd
 #include <httplib.h>
 ```
 
-You'll also need to link against `zlib` or `brotli`.
+You'll also need to link against `zlib`, `brotli`, or `zstd`, whichever you enabled.
 
 ## Compress the request body
 
@@ -28,7 +29,7 @@ std::string big_payload = build_payload();
 auto res = cli.Post("/api/data", big_payload, "application/json");
 ```
 
-With `set_compress(true)`, the body of POST or PUT requests gets gzipped before sending. The server needs to handle compressed bodies too.
+With `set_compress(true)`, the body of POST or PUT requests is compressed before sending. The encoding is the first one enabled in your build, in the order Brotli, gzip, Zstd. The server needs to handle compressed bodies too.
 
 ## Decompress the response
 
@@ -44,4 +45,4 @@ With `set_decompress(true)`, the client automatically decompresses responses tha
 
 It's on by default, so normally you don't need to do anything. Set it to `false` only if you want the raw compressed bytes.
 
-> **Warning:** If you build without `CPPHTTPLIB_ZLIB_SUPPORT`, calling `set_compress()` or `set_decompress()` does nothing. If compression isn't working, check the macro definition first.
+> **Warning:** If you build without any compression library, `set_compress(true)` leaves the request uncompressed. And a response compressed with an encoding your build lacks makes the request fail with `Error::UnsupportedContentEncoding`. If compression isn't working, check the macro definitions first.

docs-src/pages/en/cookbook/c16-proxy.md

@@ -55,7 +55,7 @@ You often want internal endpoints to skip the proxy. Configure a bypass list wit
 
 ```cpp
 cli.set_proxy("proxy.internal", 8080);
-cli.set_no_proxy({"internal.corp", "10.0.0.0/8", "*.dev.local"});
+cli.set_no_proxy({"internal.corp", "10.0.0.0/8", ".dev.local"});
 ```
 
 Each entry is one of:

docs-src/pages/en/cookbook/c17-error-codes.md

@@ -29,8 +29,8 @@ Use `if (res)` to check success. On failure, `res.error()` returns a `httplib::E
 | --- | --- |
 | `Error::Connection` | Couldn't connect to the server |
 | `Error::ConnectionTimeout` | Connection timeout (`set_connection_timeout`) |
-| `Error::Read` / `Error::Write` | Error during send or receive |
+| `Error::Read` / `Error::Write` | Error during send or receive. A timeout from `set_read_timeout` or `set_max_timeout` is also reported as `Error::Read` |
-| `Error::Timeout` | Overall timeout set via `set_max_timeout` |
+| `Error::Timeout` | A body read timed out in `stream::Get()` or `SSEClient` |
 | `Error::ExceedRedirectCount` | Too many redirects |
 | `Error::SSLConnection` | TLS handshake failed |
 | `Error::SSLServerVerification` | Server certificate verification failed |

docs-src/pages/en/cookbook/c18-ssl-errors.md

@@ -24,19 +24,24 @@ if (!res) {
 }
 ```
 
-`ssl_error()` returns the error code from the SSL library (e.g., OpenSSL's `SSL_get_error()`). `ssl_backend_error()` gives you the backend's more detailed error value — for OpenSSL, that's `ERR_get_error()`.
+`ssl_error()` is a backend-independent TLS error category: an `httplib::tls::ErrorCode` cast to `int`. `ssl_backend_error()` gives you the backend's own error value. With OpenSSL that is `ERR_get_error()` when the handshake failed, and the verify result (`X509_V_ERR_*`) when certificate verification failed.
 
 ## Format OpenSSL errors as strings
 
-When you have a value from `ssl_backend_error()`, pass it to OpenSSL's `ERR_error_string()` to get a readable message.
+When you have a value from `ssl_backend_error()`, pass it to the OpenSSL function that matches the kind of failure to get a readable message.
 
 ```cpp
 #include <openssl/err.h>
+#include <openssl/x509.h>
 
-if (res.ssl_backend_error() != 0) {
+if (res.error() == httplib::Error::SSLConnection) {
   char buf[256];
   ERR_error_string_n(res.ssl_backend_error(), buf, sizeof(buf));
   std::cerr << "openssl: " << buf << std::endl;
+} else if (res.error() == httplib::Error::SSLServerVerification ||
+           res.error() == httplib::Error::SSLServerHostnameVerification) {
+  auto code = static_cast<long>(res.ssl_backend_error());
+  std::cerr << "openssl: " << X509_verify_cert_error_string(code) << std::endl;
 }
 ```
 

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"
 ---
 
@@ -41,7 +41,7 @@ sse.on_event("leave", [](const auto &msg) {
 });
 ```
 
-`on_message()` serves as a generic fallback for unnamed events (the default `message` type).
+`on_message()` is the generic fallback: it receives every event that has no handler registered through `on_event()`. With `on_event("message", ...)` registered as above, `message` events go there instead.
 
 ## Connection lifecycle and errors
 
@@ -55,7 +55,7 @@ sse.on_error([](httplib::Error err) {
 });
 ```
 
-Hook into connection open and error events. Even when the error handler fires, `SSEClient` keeps trying to reconnect in the background.
+Hook into connection open and error events. Even when the error handler fires, `SSEClient` keeps trying to reconnect in the background. The exceptions are a 204, 403, or 404 response, after which it stops.
 
 ## Run asynchronously
 

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/s04-static-files.md

@@ -30,7 +30,7 @@ You can even mount multiple directories at the same path — they're searched in
 
 ## 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.
+Static files and API handlers coexist happily. For GET and HEAD, the mount points are searched first; handlers registered with `Get()` and friends run only when no file is found.
 
 ```cpp
 svr.Get("/api/users", [](const auto &req, auto &res) {

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

@@ -15,14 +15,15 @@ svr.Get("/download", [](const httplib::Request &req, httplib::Response &res) {
   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);
+      auto n = std::min(length, size_t(64 * 1024));
+      auto data = read_range_from_file("large.bin", offset, n);
       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.
+The lambda is called repeatedly with `offset`, the position sent so far, and `length`, the number of bytes still to send. Cap how much you read per call and write it to `sink`, and only a small chunk sits in memory at any given time.
 
 ## Just send a file
 

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

@@ -66,6 +66,38 @@ svr.Post("/upload",
 
 Only a small chunk sits in memory at any moment, so gigabyte-scale files are no problem.
 
+## Count the parts yourself
+
+There is a cap on the number of parts, `CPPHTTPLIB_MULTIPART_FORM_DATA_FILE_MAX_COUNT` (1024 by default), but it only applies to the buffered path, where every part is accumulated into `req.form`. The `ContentReader` keeps nothing on the library side, so the cap does not apply here.
+
+If you want an upper bound, count the parts yourself and return `false` from the header callback. The parser stops right there.
+
+```cpp
+svr.Post("/upload",
+  [](const httplib::Request &req, httplib::Response &res,
+     const httplib::ContentReader &content_reader) {
+    size_t count = 0;
+
+    auto ok = content_reader(
+      [&](const httplib::FormData &file) {
+        if (++count > 100) { return false; } // stop here
+        return true;
+      },
+      [&](const char *data, size_t len) {
+        return true;
+      });
+
+    if (!ok) {
+      res.status = httplib::StatusCode::BadRequest_400;
+      return;
+    }
+
+    res.set_content("ok", "text/plain");
+  });
+```
+
+When `content_reader` returns `false`, the response status becomes 400 (413 if the body exceeded the size limit). Set it yourself if you want a different one. The rest of the body is left unread and the connection is closed, so a client that is still sending sees the connection drop.
+
 > **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](../c07-multipart-upload).

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

@@ -32,7 +32,7 @@ That's it. If the client sent `Accept-Encoding: gzip`, cpp-httplib compresses th
 
 ## 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.
+When the client accepts multiple encodings, cpp-httplib picks the one with the highest q-value in `Accept-Encoding`. On a tie the order is Brotli → gzip → Zstd (among those enabled at build time).
 
 ## Streaming responses are compressed too
 
@@ -48,6 +48,31 @@ svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
 });
 ```
 
-> **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.
+## Static files need to be opted in
+
+Files served as they are, through `set_mount_point()` or `Response::set_file_content()`, are not compressed by default. Turn it on with:
+
+```cpp
+svr.set_static_file_compression(true);
+```
+
+Only files within a size range are compressed, and both ends of it can be moved:
+
+```cpp
+svr.set_static_file_compression_min_length(512);
+svr.set_static_file_compression_max_length(1024 * 1024);
+```
+
+The lower bound defaults to 1400 bytes. A response that already fits in a single 1500-byte MTU is not delivered any faster for being smaller, and a file of a few bytes comes back larger than it went in, because gzip's header and trailer outweigh what deflate saves.
+
+The upper bound defaults to 4MB and exists for a different reason: the file is compressed on every request, and the compressed bytes stay in memory until the response has been written, so the peak cost scales with the number of requests in flight. It bounds what a single request can cost, and says nothing about how well large files compress, so raising it is reasonable when the files are known and the traffic is not.
+
+Either bound takes `0` to turn it off, and each has a compile-time default (`CPPHTTPLIB_STATIC_FILE_COMPRESSION_MIN_LENGTH`, `CPPHTTPLIB_STATIC_FILE_COMPRESSION_MAX_LENGTH`).
+
+A compressed response keeps its `Content-Length`, so `HEAD` reports the same size a `GET` would. Two details to know: Range requests are answered from the uncompressed representation, and the `ETag` carries the coding it belongs to, as in `W/"...-gzip"`.
+
+Content providers registered with `set_content_provider()` are not covered. Running one through a compressor holds each write back until the internal buffer fills, which stalls providers that build their body a piece at a time. To compress a generated body, use `set_chunked_content_provider()`.
+
+> **Note:** The size range covers static files only. A body passed to `set_content()` is compressed whenever the client accepts it and the MIME type is compressible, however small it is, so a response of a few bytes ends up larger than it started. Decide in the handler if you want to avoid that.
 
 > For the client-side counterpart, see [C15. Enable compression](../c15-compression).

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

@@ -37,6 +37,8 @@ svr.set_pre_request_handler(
 
 `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.
 
+The pre-request handler also runs for routes registered with `svr.WebSocket()`. It is called before the `101 Switching Protocols` response, so returning `Handled` sends your HTTP response (such as a 403) and the connection is never upgraded.
+
 ## Return values
 
 Same as pre-routing — return `HandlerResponse`.

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

@@ -37,7 +37,7 @@ svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
 
 ## Typical value types
 
-Strings, numbers, structs, `std::shared_ptr` — anything copyable or movable works.
+Strings, numbers, structs, `std::shared_ptr`: anything copyable works.
 
 ```cpp
 res.user_data.set("user_id", std::string{"42"});

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

@@ -48,7 +48,7 @@ svr.set_pre_routing_handler([](const auto &req, auto &res) {
   return httplib::Server::HandlerResponse::Unhandled;
 });
 
-svr.set_logger([](const auto &req, const auto &res) {
+svr.set_logger([](const httplib::Request &req, const httplib::Response &res) {
   auto *start = res.user_data.get<std::chrono::steady_clock::time_point>("start");
   auto elapsed = start
     ? std::chrono::duration_cast<std::chrono::milliseconds>(

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

@@ -43,15 +43,40 @@ svr.listen_after_bind();
 
 ## Check the return values
 
-`bind_to_port()` returns `false` on failure — typically when the port is already taken. Always check it.
+`bind_to_port()` returns `false` on failure, for example when you don't have permission to bind to the port. Always check it.
 
 ```cpp
 if (!svr.bind_to_port("0.0.0.0", 8080)) {
-  std::cerr << "port already in use" << std::endl;
+  std::cerr << "bind failed" << std::endl;
   return 1;
 }
 ```
 
 `listen_after_bind()` blocks until the server stops and returns `true` on a clean shutdown.
 
+## Detect a port that's already in use
+
+With the default settings, you can actually bind to a port another server is already using. That's because cpp-httplib sets `SO_REUSEPORT` (Linux, macOS) or `SO_REUSEADDR` (Windows) on the server socket. A restarted server can bind again right away. The flip side is that a second server on the same port starts without an error, and connections get split between the two.
+
+To make `bind_to_port()` fail on a port in use, replace the socket options with `set_socket_options()`.
+
+```cpp
+svr.set_socket_options([](socket_t sock) {
+#ifdef _WIN32
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_EXCLUSIVEADDRUSE, 1);
+#else
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_REUSEADDR, 1);
+#endif
+});
+
+if (!svr.bind_to_port("0.0.0.0", 8080)) {
+  std::cerr << "port already in use" << std::endl;
+  return 1;
+}
+```
+
+`set_socket_options()` replaces the defaults entirely. Setting `SO_REUSEADDR` on Linux and macOS keeps the "restarted server can bind again right away" behavior.
+
+> **Note:** `SO_REUSEADDR` alone isn't enough on Windows. Two sockets that both set it can bind to the same port, so use `SO_EXCLUSIVEADDRUSE` instead.
+
 > **Note:** To auto-pick a free port, see [S17. Bind to any available port](../s17-bind-any-port). Under the hood, that's just `bind_to_any_port()` + `listen_after_bind()`.

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

@@ -52,6 +52,6 @@ int main() {
 
 ## 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.
+When you call `stop()`, new connections are refused, but handlers that are already running are **allowed to finish**. A response still being sent by a content provider (a streaming response, for example) is cut short, though. 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/s22-unix-socket.md

@@ -19,7 +19,7 @@ svr.Get("/", [](const auto &, auto &res) {
 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.
+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 other than `0`, which makes `listen()` fail.
 
 ## Client side
 

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"
 ---
 
@@ -55,7 +55,7 @@ httplib::SSLClient cli("api.example.com", 443,
 auto res = cli.Get("/");
 ```
 
-Note you're using `SSLClient` directly, not `Client`. If the private key has a password, pass it as the fifth argument.
+If the certificate and key paths are all you need, `Client` takes them too: `httplib::Client cli("https://api.example.com", "client-cert.pem", "client-key.pem")`. When the private key has a password, use `SSLClient` and pass it as the fifth argument.
 
 The client side has the same `PemMemory` struct too, letting you set the client certificate from PEM in memory.
 

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"
 ---
 
@@ -36,6 +36,7 @@ The `read()` return value is a `ReadResult` enum:
 - `ReadResult::Text`: received a text message
 - `ReadResult::Binary`: received a binary message
 - `ReadResult::Fail`: error, or connection closed
+- `ReadResult::Timeout`: a read timeout you set with `set_read_timeout()` elapsed with nothing received; the connection is still open. The compile-time default timeout closes the connection and is reported as `Fail` instead — see [W06. Set Timeouts](../w06-websocket-timeouts)
 
 ## Client: talk to the echo server
 

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"
 ---
 
@@ -67,7 +67,7 @@ cli.set_websocket_max_missed_pongs(2); // close after 2 consecutive unacked ping
 
 The server side has the same `set_websocket_max_missed_pongs()`.
 
-With a 30-second ping interval and `max_missed_pongs = 2`, a dead peer is detected within roughly 60 seconds and the connection is closed with `CloseStatus::GoingAway` and the reason `"pong timeout"`.
+With a 30-second ping interval and `max_missed_pongs = 2`, a dead peer is detected 60 to 90 seconds after it stops answering, and the connection is closed with `CloseStatus::GoingAway` and the reason `"pong timeout"`. A `read()` waiting on the peer at that moment returns `Fail`.
 
 The counter is reset whenever `read()` consumes an incoming Pong frame, so this only works if your code is actively calling `read()` in a loop — which is what a normal WebSocket client does anyway.
 
@@ -75,6 +75,6 @@ The counter is reset whenever `read()` consumes an incoming Pong frame, so this
 
 `max_missed_pongs` defaults to `0`, which means "never close the connection because of missing pongs." Pings are still sent on the heartbeat interval, but their responses aren't checked. If you want unresponsive-peer detection, set it explicitly to `1` or higher.
 
-Even with `0`, a dead connection won't linger forever: while your code is inside `read()`, `CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND` (default **300 seconds = 5 minutes**) acts as a backstop and `read()` fails if no frame arrives in time. Think of `max_missed_pongs` as the knob for detecting an unresponsive peer **faster** than that.
+On the server side, even with `0`, a dead connection won't linger forever: while a handler is inside `read()`, `CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND` (default **300 seconds = 5 minutes**) acts as a backstop. A client has no backstop of its own — it waits forever unless you set a read timeout — so there `max_missed_pongs` is what notices an unresponsive peer at all. On either side, it is also how you notice one **faster** than that 5-minute fallback.
 
 > For handling a closed connection, see [W03. Handle connection close](../w03-websocket-close).

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"
 ---
 
@@ -42,6 +42,9 @@ switch (result) {
   case httplib::ws::ReadResult::Fail:
     // error or closed
     break;
+  case httplib::ws::ReadResult::Timeout:
+    // read timeout elapsed; the connection is still open
+    break;
 }
 ```
 

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"
 ---
 
@@ -9,7 +9,7 @@ status: "draft"
 | Kind | API | Default |
 | --- | --- | --- |
 | Connection | `set_connection_timeout` | 300s |
-| Read | `set_read_timeout` | 300s (`CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND`) |
+| Read | `set_read_timeout` | none — waits forever (`CPPHTTPLIB_WEBSOCKET_CLIENT_READ_TIMEOUT_SECOND`) |
 | Write | `set_write_timeout` | 5s |
 
 ## Basic usage
@@ -26,7 +26,7 @@ if (ws.connect()) {
 }
 ```
 
-Set these before calling `connect()`.
+Set the connection and write timeouts before calling `connect()`. The read timeout can be changed at any time — setting it on an open connection takes effect on the next `read()`.
 
 ## Use `std::chrono`
 
@@ -40,9 +40,44 @@ ws.set_read_timeout(30s);
 ws.set_write_timeout(10s);
 ```
 
-## Watch out for what the read timeout means
+## What the read timeout means
 
-`set_read_timeout()` applies to a single `read()` call. If no message arrives within that time, `read()` returns `ReadResult::Fail`. For connections where long idle periods are normal — waiting on notifications, for example — set a longer timeout, or reconnect from your application code when the read fails.
+`set_read_timeout()` applies to a single `read()` call. If no message arrives within that time, `read()` returns `ReadResult::Timeout`: **the connection is still open** and nothing was consumed, so you can send on it and read again. That is what separates it from `ReadResult::Fail`, which means the connection is gone.
+
+This is what lets one thread own a connection in both directions:
+
+```cpp
+using namespace std::chrono_literals;
+
+ws.set_read_timeout(100ms);
+std::string msg;
+while (ws.is_open()) {
+  auto r = ws.read(msg);
+  if (r == httplib::ws::Timeout) {
+    flush_outgoing(ws);  // nothing arrived — send whatever is queued
+    continue;
+  }
+  if (r == httplib::ws::Fail) { break; }
+  handle(msg);
+}
+```
+
+Without a read timeout, `read()` blocks until a message arrives, so the thread holding the connection never gets to its writes.
+
+Two things to know about `Timeout`:
+
+- It leaves `msg` untouched, and it is non-zero. So `while (ws.read(msg))` is not usable once a read timeout is set — the loop would keep running with the *previous* message still in `msg`.
+- It is only reported on a message boundary. If the timeout elapses partway through a fragmented message, that message cannot be resumed and `read()` returns `Fail`.
+
+For connections where long idle periods are normal — waiting on notifications, for example — either leave the read timeout unset, or treat `Timeout` as the no-op it is and keep looping.
+
+## On the server side
+
+A handler's `ws::WebSocket` has `set_read_timeout()` too, and the pattern above is how a handler relays between connections instead of parking in `read()`.
+
+The server default is 300s (`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`) rather than "forever": it is a backstop that reclaims a worker from a peer that has gone silent, since a WebSocket handler holds its worker for the life of the connection.
+
+Because it is a backstop rather than something the handler asked for, it does not surface as `Timeout`. When it elapses, `read()` returns `Fail` and closes the connection, so a handler written as `while (ws.read(msg))` ends the way it always has. Only a timeout the handler set itself with `set_read_timeout()` comes back as `Timeout`.
 
 > Unresponsive-peer detection via Ping/Pong is a separate mechanism. See [W02. Set a WebSocket Heartbeat](../w02-websocket-ping) for details.
 

docs-src/pages/en/llm-app/ch02-rest-api.md

@@ -18,10 +18,6 @@ Simply pass the path to a model file to `llamalib::Llama`, and model loading, co
 int main() {
   auto llm = llamalib::Llama{"models/gemma-2-2b-it-Q4_K_M.gguf"};
 
-  // LLM inference takes time, so set a longer timeout (default is 5 seconds)
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   // ... Build and start the HTTP server ...
 }
 ```
@@ -78,7 +74,7 @@ svr.Post("/translate",
 });
 ```
 
-`llm.chat()` can throw exceptions during inference (for example, when the context length is exceeded). By catching them with `try/catch` and returning the error as JSON, we prevent the server from crashing.
+`llm.chat()` can throw exceptions during inference (for example, when the context length is exceeded). We catch them with `try/catch` and return the error as JSON. Left uncaught, cpp-httplib would still answer with a 500, but the client would not learn the cause.
 
 ## 2.3 Complete Code
 
@@ -111,10 +107,6 @@ int main() {
   // Load the model downloaded in Chapter 1
   auto llm = llamalib::Llama{"models/gemma-2-2b-it-Q4_K_M.gguf"};
 
-  // LLM inference takes time, so set a longer timeout (default is 5 seconds)
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   // Log requests and responses
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status

docs-src/pages/en/llm-app/ch03-sse-streaming.md

@@ -73,7 +73,7 @@ A few key points:
 - After writing to `sink.os`, you can check whether the client is still connected with `sink.os.good()`. If the client has disconnected, it returns `false` to stop inference
 - Each token is escaped as a JSON string using `json(token).dump()` before sending. This is safe even for tokens containing newlines or quotes
 - The first three arguments of `dump(-1, ' ', false, ...)` are the defaults. What matters is the fourth argument, `json::error_handler_t::replace`. Since the LLM returns tokens at the subword level, multi-byte characters (such as Japanese) can be split mid-character across tokens. Passing an incomplete UTF-8 byte sequence directly to `dump()` would throw an exception, so `replace` safely substitutes them. The browser reassembles the bytes on its end, so everything displays correctly
-- The entire lambda is wrapped in `try/catch`. `llm.chat()` can throw exceptions for reasons such as exceeding the context window. If an exception goes uncaught inside the lambda, the server will crash, so we return the error as an SSE event instead
+- The entire lambda is wrapped in `try/catch`. `llm.chat()` can throw exceptions for reasons such as exceeding the context window. If an exception goes uncaught inside the lambda, cpp-httplib just drops the connection and the client never learns the cause, so we return the error as an SSE event instead
 - `data: [DONE]` follows the OpenAI API convention to signal the end of the stream to the client
 
 ## 3.4 Complete Code
@@ -107,10 +107,6 @@ int main() {
   // Load the GGUF model
   auto llm = llamalib::Llama{"models/gemma-2-2b-it-Q4_K_M.gguf"};
 
-  // LLM inference takes time, so set a longer timeout (default is 5 seconds)
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   // Log requests and responses
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status

docs-src/pages/en/llm-app/ch04-model-management.md

@@ -219,7 +219,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);
-  cli.set_read_timeout(std::chrono::hours(1));
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -469,7 +468,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);  // Hugging Face redirects to a CDN
-  cli.set_read_timeout(std::chrono::hours(1)); // Set a long timeout for large models
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -539,10 +537,6 @@ int main() {
   auto llm = llamalib::Llama{path};
   std::mutex llm_mutex; // Protect access during model switching
 
-  // Set a long timeout since LLM inference takes time (default is 5 seconds)
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status
               << std::endl;

docs-src/pages/en/llm-app/ch05-web-ui.md

@@ -939,7 +939,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);  // Hugging Face redirects to CDN
-  cli.set_read_timeout(std::chrono::hours(1)); // Long timeout for large models
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -1008,10 +1007,6 @@ int main() {
   }
   auto llm = llamalib::Llama{path};
 
-  // LLM inference takes time, so set a longer timeout (default is 5 seconds)
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status
               << std::endl;

docs-src/pages/en/llm-app/ch06-desktop-app.md

@@ -407,7 +407,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);  // Hugging Face redirects to a CDN
-  cli.set_read_timeout(std::chrono::hours(1)); // Long timeout for large models
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -469,10 +468,6 @@ int main() {
   auto llm = llamalib::Llama{path};
   std::mutex llm_mutex; // Protect access during model switching
 
-  // Set a long timeout since LLM inference takes time (default is 5 seconds)
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status
               << std::endl;

docs-src/pages/en/llm-app/ch07-code-reading.md

@@ -11,13 +11,17 @@ Over the course of six chapters, we built a translation desktop app from scratch
 ## 7.1 Source Code Location
 
 ```ascii
-llama.cpp/tools/server/
+llama.cpp/
-├── server.cpp           # Main server implementation
+├── tools/server/
-├── httplib.h            # cpp-httplib (bundled version)
+│   ├── server.cpp           # Entry point
-└── ...
+│   ├── server-http.cpp      # HTTP server (the layer that uses cpp-httplib)
+│   ├── server-context.cpp   # Inference and slot management
+│   └── ...
+└── vendor/cpp-httplib/
+    └── httplib.h            # cpp-httplib (bundled version)
 ```
 
-The code is contained in a single `server.cpp`. It runs to several thousand lines, but once you understand the structure, you can narrow down the parts worth reading.
+The implementation is split across several files by role. Together they run to more than 20,000 lines, but once you understand the structure, you can narrow down the parts worth reading.
 
 ## 7.2 OpenAI-Compatible API
 
@@ -141,7 +145,7 @@ Let's organize the differences we've covered.
 | SSE format | Tokens only | OpenAI-compatible JSON |
 | KV cache | Cleared each time | Prefix reuse |
 | Structured output | None | JSON Schema / grammar constraints |
-| Code size | ~200 lines | Several thousand lines |
+| Code size | ~200 lines | Over 20,000 lines |
 
 Our code is simple because of the assumption that "one person uses it as a desktop app." If you're building a server for multiple users or one that integrates with the existing ecosystem, `llama-server`'s design serves as a valuable reference.
 

docs-src/pages/en/tour/02-basic-client.md

@@ -200,8 +200,8 @@ auto res = cli.Post("/submit", httplib::Params{
 });
 if (res) {
     std::cout << res->body << std::endl;
-    // age = 30
     // name = Alice
+    // age = 30
 }
 ```
 
@@ -241,7 +241,7 @@ auto res = cli.Get("/hi");
 if (!res) {
     // Connection error
     std::cout << "Error: " << httplib::to_string(res.error()) << std::endl;
-    // Error: Connection
+    // Error: Could not establish connection
     return 1;
 }
 

docs-src/pages/en/tour/04-static-file-server.md

@@ -95,7 +95,7 @@ svr.set_mount_point("/", "./public");
 svr.listen("0.0.0.0", 8080);
 ```
 
-Handlers take priority. The handler responds to `/api/hello`. For every other path, the server looks for a file in `./public`.
+The server looks for a file in `./public` first and calls the handler when there is none. So the handler responds to `/api/hello` unless you put a file at `./public/api/hello`.
 
 ## Adding response headers
 

docs-src/pages/en/tour/08-websocket.md

@@ -107,6 +107,8 @@ svr.WebSocket("/ws", [](const httplib::Request &req, httplib::ws::WebSocket &ws)
 });
 ```
 
+A check inside the handler runs after the handshake has completed. To refuse the connection with an HTTP status such as 401 before it is upgraded, use `set_pre_request_handler()` instead. It also runs for WebSocket routes. See [S11. Authenticate per route with a pre-request handler](../../cookbook/s11-pre-request).
+
 ## Using WSS
 
 WebSocket over HTTPS (WSS) is also supported. On the server side, just register a WebSocket handler on `httplib::SSLServer`.

docs-src/pages/en/tour/09-whats-next.md

@@ -50,7 +50,7 @@ svr.Get("/stream", [](const auto &, auto &res) {
     res.set_chunked_content_provider("text/plain",
         [](size_t offset, httplib::DataSink &sink) {
             sink.write("chunk\n", 6);
-            return true;  // Return false to finish
+            return true;  // Call sink.done() to finish
         });
 });
 ```
@@ -155,7 +155,7 @@ svr.set_pre_routing_handler([](const auto &req, auto &res) {
 });
 
 svr.set_post_routing_handler([](const auto &req, auto &res) {
-    // Runs after the response is sent
+    // Runs just before the response is sent
     res.set_header("X-Server", "cpp-httplib");
 });
 ```
@@ -168,7 +168,7 @@ svr.set_pre_routing_handler([](const auto &req, auto &res) {
     return httplib::Server::HandlerResponse::Unhandled;
 });
 
-svr.Get("/me", [](const auto &req, auto &res) {
+svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
     auto *user = res.user_data.get<std::string>("auth_user");
     res.set_content("Hello, " + *user, "text/plain");
 });
@@ -205,7 +205,7 @@ In addition to TCP, we support Unix Domain Sockets. You can use them for inter-p
 // Server
 httplib::Server svr;
 svr.set_address_family(AF_UNIX);
-svr.listen("/tmp/httplib.sock", 0);
+svr.listen("/tmp/httplib.sock", 80);  // The port is unused, but must not be 0
 ```
 
 ```cpp

docs-src/pages/ja/cookbook/c02-json.md

@@ -17,7 +17,7 @@ auto res = cli.Post("/api/users", j.dump(), "application/json");
 
 `Post()`の第2引数にJSON文字列、第3引数にContent-Typeを渡します。`Put()`や`Patch()`でも同じ形です。
 
-> **Warning:** 第3引数のContent-Typeを省略すると、サーバー側でJSONとして認識されないことがあります。`"application/json"`を必ず指定しましょう。
+> **Warning:** 第3引数のContent-Typeが`"application/json"`でないと、サーバー側でJSONとして扱われないことがあります。忘れずに指定しましょう。
 
 ## JSONレスポンスを受け取る
 

docs-src/pages/ja/cookbook/c11-progress-callback.md

@@ -21,7 +21,7 @@ auto res = cli.Get("/large-file",
 std::cout << std::endl;
 ```
 
-コールバックはデータを受信するたびに呼ばれます。`total`はContent-Lengthから取得した値で、サーバーが送ってこない場合は`0`になることがあります。その場合は進捗率が計算できないので、受信済みバイト数だけを表示するのが無難です。
+コールバックはデータを受信するたびに呼ばれます。`total`はContent-Lengthの値です。chunked転送のようにContent-Lengthのないレスポンスでは、進捗コールバックは一度も呼ばれません。
 
 ## アップロードの進捗
 
@@ -54,6 +54,8 @@ auto res = cli.Get("/large-file",
   });
 ```
 
+> **Note:** Content-Lengthのないレスポンスでは進捗コールバックが呼ばれないため、この方法は使えません。代わりに`ContentReceiver`から`false`を返して中断します。
+
 > **Note:** `ContentReceiver`と進捗コールバックは同時に使えます。ファイルに書き出しながら進捗を表示したいときは、両方を渡しましょう。
 
 > ファイル保存と組み合わせる具体例は[C01. レスポンスボディを取得する / ファイルに保存する](../c01-get-response-body)も参照してください。

docs-src/pages/ja/cookbook/c13-max-timeout.md

@@ -16,11 +16,11 @@ cli.set_max_timeout(5000); // 5秒（ミリ秒単位）
 auto res = cli.Get("/slow-endpoint");
 ```
 
-ミリ秒単位で指定します。接続、送信、受信をすべて含めて、リクエスト全体が指定時間を超えたら打ち切られます。
+ミリ秒単位で指定します。リクエストを始めてからこの時間が過ぎると、レスポンスを待っている途中でも打ち切られます。ただし、接続や送信で待たされる時間まで短くなるわけではありません。そちらは`set_connection_timeout`と`set_write_timeout`で調整します。
 
 ## `std::chrono`で指定する
 
-こちらも`std::chrono`の期間を受け取るオーバーロードがあります。
+こちらにも、`std::chrono`の期間を受け取るオーバーロードがあります。
 
 ```cpp
 using namespace std::chrono_literals;

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

@@ -4,43 +4,44 @@ order: 14
 status: "draft"
 ---
 
-`httplib::Client`は同じインスタンスで複数回リクエストを送ると、TCP接続を自動的に再利用します。HTTP/1.1のKeep-Aliveが有効に働くので、TCPハンドシェイクやTLSハンドシェイクのオーバーヘッドを毎回払わずに済みます。
+`httplib::Client`は、デフォルトではリクエストのたびに接続を閉じます（`Connection: close`を送ります）。`set_keep_alive(true)`を呼んでおくと、同じインスタンスから送るリクエストは1本のTCP接続を使い回します。TCPやTLSのハンドシェイクを毎回やり直さずに済みます。
 
-## 接続は自動で使い回される
+## Keep-Aliveを有効にする
 
 ```cpp
 httplib::Client cli("https://api.example.com");
+cli.set_keep_alive(true);
 
 auto res1 = cli.Get("/users/1");
 auto res2 = cli.Get("/users/2"); // 同じ接続を再利用
 auto res3 = cli.Get("/users/3"); // 同じ接続を再利用
 ```
 
-特別な設定は要りません。`cli`を使い回すだけで、内部的には同じソケットで通信が続きます。とくにHTTPSでは、TLSハンドシェイクのコストが大きいので効果が顕著です。
+あとは`cli`を使い回すだけで、内部的には同じソケットで通信が続きます。とくにHTTPSでは、TLSハンドシェイクのコストが大きいので効果が顕著です。
 
-## Keep-Aliveを明示的にオフにする
+## Keep-Aliveをオフに戻す
 
-毎回新しい接続を張り直したい場合は、`set_keep_alive(false)`を呼びます。テスト目的などで使うことがあります。
+リクエストのたびに接続を張り直す動作（デフォルト）に戻すには、`set_keep_alive(false)`を呼びます。
 
 ```cpp
 cli.set_keep_alive(false);
 ```
 
-ただし、普段はオン（デフォルト）のままで問題ありません。
-
 ## リクエストごとに`Client`を作らない
 
-1回のリクエストのたびに`Client`をスコープから抜けて破棄すると、接続の再利用は効きません。ループの外でインスタンスを作り、中で使い回しましょう。
+リクエストのたびに`Client`を作っては破棄していると、接続は再利用されません。インスタンスはループの外で作り、中で使い回しましょう。
 
 ```cpp
 // NG: 毎回接続が切れる
 for (auto id : ids) {
   httplib::Client cli("https://api.example.com");
+  cli.set_keep_alive(true);
   cli.Get("/users/" + id);
 }
 
 // OK: 接続が再利用される
 httplib::Client cli("https://api.example.com");
+cli.set_keep_alive(true);
 for (auto id : ids) {
   cli.Get("/users/" + id);
 }
@@ -50,4 +51,4 @@ for (auto id : ids) {
 
 複数のスレッドから並行にリクエストを送りたいときは、スレッドごとに別々の`Client`インスタンスを持つのが無難です。1つの`Client`は1本のTCP接続を使い回すので、同じインスタンスに複数スレッドから同時にリクエストを投げると、結局どこかで直列化されます。
 
-> **Note:** サーバー側のKeep-Aliveタイムアウトを超えると、サーバーが接続を切ります。その場合cpp-httplibは自動で再接続して再試行するので、アプリケーションコードで気にする必要はありません。
+> **Note:** サーバー側のKeep-Aliveタイムアウトを超えると、サーバーが接続を切ります。cpp-httplibは次のリクエストを送る前にそれに気付いて接続し直すので、アプリケーション側で気にする必要はありません。

docs-src/pages/ja/cookbook/c15-compression.md

@@ -4,7 +4,7 @@ order: 15
 status: "draft"
 ---
 
-cpp-httplibは送信時の圧縮と受信時の解凍をサポートしています。ただし、zlibまたはBrotliを有効にしてビルドしておく必要があります。
+cpp-httplibは送信時の圧縮と受信時の解凍をサポートしています。ただし、zlib、Brotli、Zstdのいずれかを有効にしてビルドしておく必要があります。
 
 ## ビルド時の準備
 
@@ -13,10 +13,11 @@ cpp-httplibは送信時の圧縮と受信時の解凍をサポートしていま
 ```cpp
 #define CPPHTTPLIB_ZLIB_SUPPORT    // gzip / deflate
 #define CPPHTTPLIB_BROTLI_SUPPORT  // brotli
+#define CPPHTTPLIB_ZSTD_SUPPORT    // zstd
 #include <httplib.h>
 ```
 
-リンク時に`zlib`や`brotli`のライブラリも必要です。
+有効にした方式に応じて、`zlib`、`brotli`、`zstd`のライブラリもリンクします。
 
 ## リクエストボディを圧縮して送る
 
@@ -28,7 +29,7 @@ std::string big_payload = build_payload();
 auto res = cli.Post("/api/data", big_payload, "application/json");
 ```
 
-`set_compress(true)`を呼んでおくと、POSTやPUTのリクエストボディがgzipで圧縮されて送信されます。サーバー側が対応している必要があります。
+`set_compress(true)`を呼んでおくと、POSTやPUTのリクエストボディが圧縮されて送信されます。圧縮方式は、ビルドで有効にしたもののうち、Brotli、gzip、Zstdの順で最初に当てはまるものです。サーバー側もその方式に対応している必要があります。
 
 ## レスポンスを解凍する
 
@@ -44,4 +45,4 @@ std::cout << res->body << std::endl;
 
 デフォルトで有効なので、通常は何もしなくても解凍されます。あえて生の圧縮データを触りたいときだけ`set_decompress(false)`にしましょう。
 
-> **Warning:** `CPPHTTPLIB_ZLIB_SUPPORT`を定義せずにビルドすると、`set_compress()`や`set_decompress()`を呼んでも何も起こりません。マクロの定義を忘れていないか、最初に確認しましょう。
+> **Warning:** 圧縮ライブラリを1つも有効にしていないビルドでは、`set_compress(true)`を呼んでもリクエストは圧縮されません。また、ビルドで有効にしていない方式で圧縮されたレスポンスが返ってくると、リクエストは`Error::UnsupportedContentEncoding`で失敗します。うまく動かないときは、まずマクロの定義を確認しましょう。

docs-src/pages/ja/cookbook/c16-proxy.md

@@ -55,7 +55,7 @@ cli.set_bearer_token_auth("api-token"); // エンドサーバー向け
 
 ```cpp
 cli.set_proxy("proxy.internal", 8080);
-cli.set_no_proxy({"internal.corp", "10.0.0.0/8", "*.dev.local"});
+cli.set_no_proxy({"internal.corp", "10.0.0.0/8", ".dev.local"});
 ```
 
 エントリは次のいずれかです。

docs-src/pages/ja/cookbook/c17-error-codes.md

@@ -29,8 +29,8 @@ if (res) {
 | --- | --- |
 | `Error::Connection` | サーバーに接続できなかった |
 | `Error::ConnectionTimeout` | 接続タイムアウト（`set_connection_timeout`） |
-| `Error::Read` / `Error::Write` | 送受信中のエラー |
+| `Error::Read` / `Error::Write` | 送受信中のエラー。`set_read_timeout`や`set_max_timeout`によるタイムアウトも`Error::Read`になる |
-| `Error::Timeout` | `set_max_timeout`で設定した全体タイムアウト |
+| `Error::Timeout` | `stream::Get()`や`SSEClient`で、ボディの読み取りがタイムアウトした |
 | `Error::ExceedRedirectCount` | リダイレクト回数が上限を超えた |
 | `Error::SSLConnection` | TLSハンドシェイクに失敗 |
 | `Error::SSLServerVerification` | サーバー証明書の検証に失敗 |
@@ -38,7 +38,7 @@ if (res) {
 
 ## ステータスコードとの使い分け
 
-`res`が truthy でも、HTTPステータスコードが4xxや5xxのこともあります。この2つは別物です。
+`res`がtruthyでも、HTTPステータスコードが4xxや5xxのこともあります。この2つは別物です。
 
 ```cpp
 auto res = cli.Get("/api/data");

docs-src/pages/ja/cookbook/c18-ssl-errors.md

@@ -24,19 +24,24 @@ if (!res) {
 }
 ```
 
-`ssl_error()`はSSLライブラリが返したエラーコード（OpenSSLの`SSL_get_error()`の値など）、`ssl_backend_error()`はバックエンドがさらに詳しく提供するエラー値です。OpenSSLなら`ERR_get_error()`の値が入ります。
+`ssl_error()`は、どのTLSバックエンドでも共通のエラー種別（`httplib::tls::ErrorCode`）を`int`で返します。`ssl_backend_error()`は、バックエンドが返したエラー値そのものです。OpenSSLなら、ハンドシェイクの失敗では`ERR_get_error()`の値が、証明書検証の失敗では検証結果のコード（`X509_V_ERR_*`）が入ります。
 
 ## OpenSSLのエラーを文字列化する
 
-`ssl_backend_error()`で取得した値を、OpenSSLの`ERR_error_string()`で文字列にするとデバッグに便利です。
+`ssl_backend_error()`の値は、OpenSSLの関数で文字列にしておくとデバッグに便利です。使う関数は失敗の種類によって変わります。
 
 ```cpp
 #include <openssl/err.h>
+#include <openssl/x509.h>
 
-if (res.ssl_backend_error() != 0) {
+if (res.error() == httplib::Error::SSLConnection) {
   char buf[256];
   ERR_error_string_n(res.ssl_backend_error(), buf, sizeof(buf));
   std::cerr << "openssl: " << buf << std::endl;
+} else if (res.error() == httplib::Error::SSLServerVerification ||
+           res.error() == httplib::Error::SSLServerHostnameVerification) {
+  auto code = static_cast<long>(res.ssl_backend_error());
+  std::cerr << "openssl: " << X509_verify_cert_error_string(code) << std::endl;
 }
 ```
 

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

@@ -1,6 +1,6 @@
 ---
 title: "E01. SSEサーバーを実装する"
-order: 47
+order: 48
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "E02. SSEでイベント名を使い分ける"
-order: 48
+order: 49
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "E03. SSEの再接続を処理する"
-order: 49
+order: 50
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "E04. SSEをクライアントで受信する"
-order: 50
+order: 51
 status: "draft"
 ---
 
@@ -25,7 +25,7 @@ sse.start(); // ブロッキング
 
 ## イベント名で分岐する
 
-サーバー側で`event:`を付けて送られてくる場合は、`on_event()`で名前ごとにハンドラを登録できます。
+サーバーが`event:`を付けてイベントを送ってくる場合は、`on_event()`で名前ごとにハンドラを登録できます。
 
 ```cpp
 sse.on_event("message", [](const auto &msg) {
@@ -41,7 +41,7 @@ sse.on_event("leave", [](const auto &msg) {
 });
 ```
 
-`on_message()`は、名前なし（デフォルトの`message`イベント）を受け取る汎用ハンドラとして使えます。
+`on_message()`は、`on_event()`で登録していない名前のイベントをまとめて受け取る汎用ハンドラです。上の例のように`on_event("message", ...)`を登録した場合、`message`イベントは`on_message()`ではなくそちらに届きます。
 
 ## 接続イベントとエラーハンドリング
 
@@ -55,7 +55,7 @@ sse.on_error([](httplib::Error err) {
 });
 ```
 
-接続確立時やエラー発生時にもフックを挟めます。エラーハンドラが呼ばれても、`SSEClient`は内部で再接続を試みます。
+接続確立時やエラー発生時にもフックを挟めます。エラーハンドラが呼ばれても、`SSEClient`は内部で再接続を試みます。ただし、サーバーが204、403、404のいずれかを返したときは再接続しません。
 
 ## 非同期で動かす
 

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

@@ -73,6 +73,9 @@ status: "draft"
 - [S21. マルチスレッド数を設定する](s21-thread-pool)
 - [S22. Unix domain socketで通信する](s22-unix-socket)
 
+### プロトコル拡張
+- [S23. カスタムHTTPメソッドを扱う](s23-custom-methods)
+
 ## TLS / セキュリティ
 
 - [T01. OpenSSL・mbedTLS・wolfSSLの選択指針](t01-tls-backends)

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

@@ -4,7 +4,7 @@ order: 20
 status: "draft"
 ---
 
-`httplib::Server`では、HTTPメソッドごとにハンドラを登録します。`Get()`、`Post()`、`Put()`、`Delete()`の各メソッドにパターンとラムダを渡すだけです。
+`httplib::Server`では、HTTPメソッドごとにハンドラを登録します。`Get()`、`Post()`、`Put()`、`Delete()`の各メソッドにパターンとラムダを渡すだけです。WebDAVの`PROPFIND`のような組み込み以外のメソッドを扱いたいときは、`CustomRoute()`を使います。
 
 ## 基本の使い方
 
@@ -64,3 +64,5 @@ svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
 > **Note:** `listen()`はブロックする関数です。別スレッドで動かしたいときは`std::thread`で包むか、ノンブロッキング起動が必要なら[S18. `listen_after_bind`で起動順序を制御する](../s18-listen-after-bind)を参照してください。
 
 > パスパラメーター（`/users/:id`）を使いたい場合は[S03. パスパラメーターを使う](../s03-path-params)を参照してください。
+
+> WebDAVの`PROPFIND`のような組み込み以外のメソッドは[S23. カスタムHTTPメソッドを扱う](../s23-custom-methods)を参照してください。

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

@@ -14,7 +14,7 @@ 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に反映されます。
+`./public/index.html`には`http://localhost:8080/index.html`で、`./public/css/style.css`には`http://localhost:8080/css/style.css`でアクセスできます。ディレクトリ構造がそのままURLに反映されます。
 
 ## 複数のマウントポイント
 
@@ -26,11 +26,11 @@ svr.set_mount_point("/assets", "./dist/assets");
 svr.set_mount_point("/uploads", "./var/uploads");
 ```
 
-同じパスに複数のマウントを登録することもできます。その場合は登録順に探されて、見つかった最初のものが返ります。
+同じパスに複数のマウントを登録することもできます。その場合は登録した順に探し、最初に見つかったファイルを返します。
 
 ## APIハンドラと組み合わせる
 
-静的ファイルとAPIハンドラは共存できます。`Get()`などで登録したハンドラが優先され、マッチしなかったときにマウントポイントが探されます。
+静的ファイルとAPIハンドラは共存できます。GETとHEADのリクエストでは、まずマウントポイントからファイルを探し、見つからなければ`Get()`などで登録したハンドラを呼びます。
 
 ```cpp
 svr.Get("/api/users", [](const auto &req, auto &res) {
@@ -44,7 +44,7 @@ svr.set_mount_point("/", "./public");
 
 ## MIMEタイプを追加する
 
-拡張子からContent-Typeを決めるマッピングは組み込みですが、カスタムの拡張子を追加できます。
+拡張子からContent-Typeを決める対応表は組み込まれていますが、独自の拡張子を追加することもできます。
 
 ```cpp
 svr.set_file_extension_and_mimetype_mapping("wasm", "application/wasm");

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

@@ -15,14 +15,15 @@ svr.Get("/download", [](const httplib::Request &req, httplib::Response &res) {
   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);
+      auto n = std::min(length, size_t(64 * 1024));
+      auto data = read_range_from_file("large.bin", offset, n);
       sink.write(data.data(), data.size());
       return true;
     });
 });
 ```
 
-ラムダが呼ばれるたびに`offset`と`length`が渡されるので、その範囲だけ読み込んで`sink.write()`で送ります。メモリには常に少量のチャンクしか載りません。
+ラムダは繰り返し呼ばれ、そのたびに`offset`（ここまでに送った位置）と`length`（残りのバイト数）が渡されます。`length`は残り全部を指すので、上の例のように1回に読む量を自分で区切って`sink.write()`で送ります。こうすれば、メモリに載るのは常に小さなチャンクだけです。
 
 ## ファイルをそのまま返す
 

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

@@ -66,6 +66,38 @@ svr.Post("/upload",
 
 メモリには常に小さなチャンクしか載らないので、ギガバイト級のファイルでも扱えます。
 
+## パート数は自分で数える
+
+`CPPHTTPLIB_MULTIPART_FORM_DATA_FILE_MAX_COUNT`（デフォルト1024）というパート数の上限がありますが、これが効くのは`req.form`にすべてのパートを溜め込むバッファリング側だけです。`ContentReader`はライブラリ側で何も溜め込まないので、この上限は適用されません。
+
+パート数に上限をつけたいときは、自分で数えてヘッダーのコールバックから`false`を返してください。パースはその場で止まります。
+
+```cpp
+svr.Post("/upload",
+  [](const httplib::Request &req, httplib::Response &res,
+     const httplib::ContentReader &content_reader) {
+    size_t count = 0;
+
+    auto ok = content_reader(
+      [&](const httplib::FormData &file) {
+        if (++count > 100) { return false; } // ここで打ち切る
+        return true;
+      },
+      [&](const char *data, size_t len) {
+        return true;
+      });
+
+    if (!ok) {
+      res.status = httplib::StatusCode::BadRequest_400;
+      return;
+    }
+
+    res.set_content("ok", "text/plain");
+  });
+```
+
+`content_reader`が`false`を返した場合、何もしなければステータスは400になります（ボディがサイズ上限を超えていたときは413）。ほかのステータスを返したいときは自分でセットしてください。ボディの残りは読まずに接続を閉じるので、送信中のクライアントには接続が切れたように見えます。
+
 > **Warning:** `HandlerWithContentReader`を使うと、`req.body`は**空のまま**です。ボディはコールバック内で自分で処理してください。
 
 > クライアント側でマルチパートを送る方法は[C07. ファイルをマルチパートフォームとしてアップロードする](../c07-multipart-upload)を参照してください。

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

@@ -32,7 +32,7 @@ svr.Get("/api/data", [](const httplib::Request &req, httplib::Response &res) {
 
 ## 圧縮の優先順位
 
-クライアントが複数の方式を受け入れる場合、Brotli → Zstd → gzipの順に選ばれます（ビルドで有効になっている中から）。クライアント側では気にせず、一番効率の良い方式で圧縮されます。
+クライアントが複数の方式を受け入れる場合は、`Accept-Encoding`のq値がいちばん高い方式で圧縮します。q値が同じときは、ビルドで有効な方式の中からBrotli → gzip → Zstdの順に選びます。
 
 ## ストリーミングレスポンスも圧縮される
 
@@ -48,6 +48,31 @@ svr.Get("/events", [](const httplib::Request &req, httplib::Response &res) {
 });
 ```
 
-> **Note:** 小さなレスポンスは圧縮しても効果が薄く、むしろCPU時間を無駄にすることがあります。cpp-httplibは小さすぎるボディは圧縮をスキップします。
+## 静的ファイルは明示的に有効にする
+
+`set_mount_point()`や`Response::set_file_content()`でファイルをそのまま返す場合、デフォルトでは圧縮されません。有効にするには次を呼びます。
+
+```cpp
+svr.set_static_file_compression(true);
+```
+
+圧縮の対象になるのは一定のサイズ範囲に収まるファイルだけで、上下どちらの境界も変更できます。
+
+```cpp
+svr.set_static_file_compression_min_length(512);
+svr.set_static_file_compression_max_length(1024 * 1024);
+```
+
+下限のデフォルトは1400バイトです。1500バイトのMTUに収まるレスポンスは、小さくしたところで到達が速くなるわけではありません。さらに数バイトのファイルは、gzipのヘッダとトレーラがdeflateの削減分を上回るため、かえって大きくなって返ります。
+
+上限のデフォルトは4MBで、こちらは理由が違います。リクエストのたびに圧縮が走り、圧縮後のバイト列はレスポンスを書き終えるまでメモリに載るため、ピーク時のコストが同時処理中のリクエスト数に比例するからです。つまり1リクエストあたりのコストを抑えるための値であって、大きいファイルは圧縮しても無駄だという意味ではありません。配信するファイルが分かっていてトラフィックがそれほど多くないなら、引き上げて構いません。
+
+どちらの境界も`0`で無効にできます。コンパイル時のデフォルトは`CPPHTTPLIB_STATIC_FILE_COMPRESSION_MIN_LENGTH`と`CPPHTTPLIB_STATIC_FILE_COMPRESSION_MAX_LENGTH`で決まります。
+
+圧縮しても`Content-Length`は付いたままなので、`HEAD`は`GET`と同じサイズを返します。細かい点が2つあります。Rangeリクエストには圧縮前のデータから該当範囲を切り出して返します。また、`ETag`には`W/"...-gzip"`のように、使った圧縮方式が入ります。
+
+なお`set_content_provider()`で登録したコンテンツプロバイダは対象外です。圧縮器を通すと、内部バッファが埋まるまで書き込みが送出されず、ボディを少しずつ生成するプロバイダが止まってしまうためです。生成したボディを圧縮したい場合は`set_chunked_content_provider()`を使ってください。
+
+> **Note:** サイズ範囲が効くのは静的ファイルだけです。`set_content()`に渡したボディは、圧縮対象のMIMEタイプでクライアントが受け入れていれば、大きさによらず圧縮されます。数バイトのレスポンスはgzipのヘッダ分だけかえって大きくなるので、避けたい場合はハンドラ側で判断してください。
 
 > クライアント側の挙動は[C15. 圧縮を有効にする](../c15-compression)を参照してください。

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

@@ -37,6 +37,8 @@ svr.set_pre_request_handler(
 
 `matched_route`はパスパラメーターを展開する**前**のパターン文字列（例: `/admin/users/:id`）です。特定の値ではなく、ルート定義のパターンで判定できるので、IDや名前に左右されません。
 
+`svr.WebSocket()`で登録したルートでも、Pre-requestハンドラは呼ばれます。呼ばれるのは`101 Switching Protocols`を返す前なので、`Handled`を返すとそのHTTPレスポンス（403など）がそのまま返り、WebSocketへのアップグレードは行われません。
+
 ## 戻り値の意味
 
 Pre-routingハンドラと同じく、`HandlerResponse`を返します。

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

@@ -37,7 +37,7 @@ svr.Get("/me", [](const httplib::Request &req, httplib::Response &res) {
 
 ## よくある型
 
-`std::string`、数値、構造体、`std::shared_ptr`など、コピーかムーブできる値なら何でも入れられます。
+`std::string`、数値、構造体、`std::shared_ptr`など、コピーできる値なら何でも入れられます。
 
 ```cpp
 res.user_data.set("user_id", std::string{"42"});
@@ -51,6 +51,6 @@ res.user_data.set("started_at", std::chrono::steady_clock::now());
 
 ## 注意点
 
-`user_data`は`Response`に乗っています（`req.user_data`ではありません）。これは、ハンドラには`Response&`として可変参照が渡されるためです。一見不思議ですが、「ハンドラ間で共有する可変コンテキスト」として覚えておくと素直です。
+`user_data`は`Response`に乗っています（`req.user_data`ではありません）。これは、ハンドラには`Response&`として可変参照が渡されるためです。一見不思議ですが、「ハンドラ間で共有する可変コンテキスト」だと考えると納得がいきます。
 
 > **Warning:** `user_data.get<T>()`は型が一致しないと`nullptr`を返します。保存時と取得時で同じ型を指定してください。`AuthUser`で入れて`const AuthUser`で取ろうとすると失敗します。

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

@@ -48,7 +48,7 @@ svr.set_pre_routing_handler([](const auto &req, auto &res) {
   return httplib::Server::HandlerResponse::Unhandled;
 });
 
-svr.set_logger([](const auto &req, const auto &res) {
+svr.set_logger([](const httplib::Request &req, const httplib::Response &res) {
   auto *start = res.user_data.get<std::chrono::steady_clock::time_point>("start");
   auto elapsed = start
     ? std::chrono::duration_cast<std::chrono::milliseconds>(

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

@@ -43,15 +43,40 @@ svr.listen_after_bind();
 
 ## 戻り値のチェック
 
-`bind_to_port()`は失敗すると`false`を返します。ポートが既に使われている場合などです。必ずチェックしてください。
+`bind_to_port()`は失敗すると`false`を返します。ポートにbindする権限が無い場合などです。必ずチェックしてください。
 
 ```cpp
 if (!svr.bind_to_port("0.0.0.0", 8080)) {
-  std::cerr << "port already in use" << std::endl;
+  std::cerr << "bind failed" << std::endl;
   return 1;
 }
 ```
 
 `listen_after_bind()`はサーバーが停止するまでブロックし、正常終了なら`true`を返します。
 
+## 使用中のポートを検出する
+
+実は、デフォルトの設定では、ほかのサーバーが使っているポートにもbindできてしまいます。cpp-httplibがサーバーソケットに`SO_REUSEPORT`（Linux、macOS）か`SO_REUSEADDR`（Windows）を設定しているからです。再起動したサーバーはすぐにbindし直せます。その代わり、同じポートで2つ目のサーバーを起動してもエラーにならず、接続が両方に振り分けられます。
+
+使用中のポートで`bind_to_port()`を失敗させたいときは、`set_socket_options()`でソケットオプションを差し替えてください。
+
+```cpp
+svr.set_socket_options([](socket_t sock) {
+#ifdef _WIN32
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_EXCLUSIVEADDRUSE, 1);
+#else
+  httplib::set_socket_opt(sock, SOL_SOCKET, SO_REUSEADDR, 1);
+#endif
+});
+
+if (!svr.bind_to_port("0.0.0.0", 8080)) {
+  std::cerr << "port already in use" << std::endl;
+  return 1;
+}
+```
+
+`set_socket_options()`はデフォルトの設定を丸ごと置き換えます。Linux、macOSで`SO_REUSEADDR`を設定しているのは、再起動したサーバーがすぐにbindし直せるようにするためです。
+
+> **Note:** Windowsでは`SO_REUSEADDR`だけでは足りません。お互いに`SO_REUSEADDR`を設定したソケット同士は、同じポートにbindできてしまいます。`SO_EXCLUSIVEADDRUSE`を使ってください。
+
 > **Note:** 空いているポートを自動で選びたいときは[S17. ポートを動的に割り当てる](../s17-bind-any-port)を参照してください。こちらも内部では`bind_to_any_port()` + `listen_after_bind()`の組み合わせです。

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

@@ -52,6 +52,6 @@ int main() {
 
 ## 処理中のリクエストの扱い
 
-`stop()`を呼ぶと、新しい接続は受け付けなくなりますが、すでに処理中のリクエストは**最後まで実行**されます。その後、スレッドプールのワーカーが順次終了し、`listen()`から戻ってきます。これがグレースフルシャットダウンと呼ばれる理由です。
+`stop()`を呼ぶと、新しい接続は受け付けなくなりますが、すでに動いているハンドラは**最後まで実行**されます。ただし、ストリーミングのようにコンテンツプロバイダで送っている途中のレスポンスは、その場で打ち切られます。その後、スレッドプールのワーカーが順次終了し、`listen()`から戻ってきます。これがグレースフルシャットダウンと呼ばれる理由です。
 
 > **Warning:** `stop()`を呼んでから`listen()`が戻るまでには、処理中のリクエストが終わるのを待つ時間がかかります。タイムアウトを強制したい場合は、シャットダウン用のタイマーを別途用意するなど、アプリケーション側の工夫が必要です。

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

@@ -19,7 +19,7 @@ svr.Get("/", [](const auto &, auto &res) {
 svr.listen("/tmp/httplib.sock", 80);
 ```
 
-`set_address_family(AF_UNIX)`を呼んでから、`listen()`の第1引数にソケットファイルのパスを渡します。第2引数のポート番号は使われませんが、シグネチャの都合で何か渡す必要があります。
+`set_address_family(AF_UNIX)`を呼んでから、`listen()`の第1引数にソケットファイルのパスを渡します。第2引数のポート番号は使われませんが、省略はできません。`0`を渡すと`listen()`が失敗するので、`0`以外の適当な値を渡してください。
 
 ## クライアント側
 

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

@@ -0,0 +1,59 @@
+---
+title: "S23. カスタムHTTPメソッドを扱う"
+order: 42
+status: "draft"
+---
+
+サーバーは知らないHTTPメソッドを`400 Bad Request`で弾きます。RFC 4918のWebDAVメソッド（`PROPFIND`、`PROPPATCH`、`MKCOL`など）やUPnPの`SUBSCRIBE`のような拡張メソッドを受け付けたいときは、`CustomRoute()`でハンドラを登録してください。登録したことがそのまま「このメソッドを受け付ける」という意味になります。
+
+## 基本の使い方
+
+```cpp
+svr.CustomRoute("PROPFIND", "/dav/:id",
+                [](const httplib::Request &req, httplib::Response &res) {
+                  // リクエストボディも通常どおり読める
+                  auto id = req.path_params.at("id");
+                  res.status = httplib::StatusCode::MultiStatus_207;
+                  res.set_content(build_multistatus(req.body), "application/xml");
+                });
+```
+
+パターンの書き方は`Get()`などと同じです。正規表現もパスパラメーターもそのまま使えます。
+
+## OPTIONSで対応メソッドを知らせる
+
+WebDAVクライアントは接続すると、まず`OPTIONS`でサーバーの能力を問い合わせます。cpp-httplibは`DAV:`ヘッダーも`Allow`ヘッダーも自動生成しないので、自分で返してください。ここを忘れると、`PROPFIND`が正しく動いてもクライアントに拒否されます。
+
+```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");
+});
+```
+
+## ボディをストリーミングで受け取る
+
+`Post()`などと同じく、Content Reader版のオーバーロードがあります。大きなXMLを一度にメモリへ載せたくないときに使ってください。
+
+```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) {
+                    // 少しずつ処理する
+                    return true;
+                  });
+                  res.status = httplib::StatusCode::MultiStatus_207;
+                });
+```
+
+## 覚えておくこと
+
+- メソッド名はHTTPのトークン（RFC 9110）である必要があります。`listen()`より前に登録してください
+- `GET`、`HEAD`、`POST`、`PUT`、`DELETE`、`CONNECT`、`OPTIONS`、`TRACE`、`PATCH`、`PRI`は登録できません。これらには専用のメソッドを使ってください
+- 登録が拒否されると`is_valid()`が`false`になり、`listen()`が失敗します。呼ばれないハンドラを抱えたままサーバーが起動することはありません
+- 静的ファイルの配信とWebSocketのアップグレードは`GET`/`HEAD`のままです
+
+> **Note:** cpp-httplibが用意するのはメソッドのルーティングまでです。WebDAVを名乗るなら、`207 Multi-Status`のXML生成、`Depth`ヘッダーの解釈、ロックの管理は自分で実装することになります。プロトコルの本体はライブラリの外側です。
+
+> ハンドラ登録の基本は[S01. GET / POST / PUT / DELETEハンドラを登録する](../s01-handlers)を参照してください。

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

@@ -1,6 +1,6 @@
 ---
 title: "T01. OpenSSL・mbedTLS・wolfSSLの選択指針"
-order: 42
+order: 43
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "T02. SSL証明書の検証を制御する"
-order: 43
+order: 44
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "T03. SSL/TLSサーバーを立ち上げる"
-order: 44
+order: 45
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "T04. mTLSを設定する"
-order: 45
+order: 46
 status: "draft"
 ---
 
@@ -55,7 +55,7 @@ httplib::SSLClient cli("api.example.com", 443,
 auto res = cli.Get("/");
 ```
 
-`Client`ではなく`SSLClient`を直接使う点に注意してください。秘密鍵にパスワードがある場合は第5引数で渡せます。
+証明書と鍵のファイルを渡すだけなら、`httplib::Client cli("https://api.example.com", "client-cert.pem", "client-key.pem")`のように`Client`でも書けます。秘密鍵にパスワードがかかっている場合は`SSLClient`を使い、第5引数にパスワードを渡します。
 
 クライアント側にも同じ`PemMemory`構造体があり、メモリ上のPEMからクライアント証明書を設定できます。
 

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

@@ -1,6 +1,6 @@
 ---
 title: "T05. サーバー側でピア証明書を参照する"
-order: 46
+order: 47
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "W01. WebSocketエコーサーバー／クライアントを実装する"
-order: 51
+order: 52
 status: "draft"
 ---
 
@@ -31,11 +31,12 @@ int main() {
 
 `svr.WebSocket()`でWebSocket用のハンドラを登録します。ハンドラが呼ばれた時点で、すでにWebSocketのハンドシェイクは完了しています。ループの中で`ws.read()`して`ws.send()`するだけで、エコー動作が完成します。
 
-`read()`の返り値は`ReadResult`列挙値で、次の3種類です。
+`read()`の返り値は`ReadResult`列挙値で、次の4種類です。
 
 - `ReadResult::Text`: テキストメッセージを受信
 - `ReadResult::Binary`: バイナリメッセージを受信
 - `ReadResult::Fail`: エラー、または接続が閉じた
+- `ReadResult::Timeout`: `set_read_timeout()`で自分が設定した読み取りタイムアウトが、何も受信しないまま経過した。接続は開いたまま。コンパイル時のデフォルトのタイムアウトは接続を閉じ、`Fail`として返る（[W06. タイムアウトを設定する](../w06-websocket-timeouts)を参照）
 
 ## クライアント: エコーを叩く
 

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

@@ -1,6 +1,6 @@
 ---
 title: "W02. ハートビートを設定する"
-order: 52
+order: 53
 status: "draft"
 ---
 
@@ -41,7 +41,7 @@ cli.connect();
 
 デフォルトのPing間隔は、ビルド時のマクロ`CPPHTTPLIB_WEBSOCKET_PING_INTERVAL_SECOND`で決まります。通常はそのままで問題ありませんが、特別なプロキシ環境に合わせて短くしたい場合は調整してください。
 
-## PongはどうやってpIngに応答するか
+## Pingへの応答（Pong）
 
 WebSocketプロトコルでは、PingフレームにはPongフレームで応答することが決まっています。cpp-httplibは受信したPingに自動でPongを返すので、アプリケーションコード側で気にする必要はありません。
 
@@ -55,7 +55,7 @@ WebSocketプロトコルでは、PingフレームにはPongフレームで応答
 
 短すぎると無駄なトラフィックになり、長すぎると接続が切れます。だいたい**接続が切れる時間の半分**くらいが目安です。
 
-> **Warning:** Ping間隔を極端に短くすると、WebSocket接続ごとにバックグラウンドでスレッドが走るので、CPU負荷が上がります。接続数が多いサーバーでは控えめな値に設定しましょう。
+> **Warning:** WebSocket接続ごとにバックグラウンドでスレッドが走るので、Ping間隔を極端に短くするとCPU負荷が上がります。接続数が多いサーバーでは控えめな値に設定しましょう。
 
 ## 無応答のピアを検出する
 
@@ -67,14 +67,14 @@ cli.set_websocket_max_missed_pongs(2); // 2回連続でPongが返ってこなけ
 
 サーバー側にも同じ`set_websocket_max_missed_pongs()`があります。
 
-たとえばPing間隔が30秒で`max_missed_pongs = 2`なら、無応答のピアは約60秒で検出され、`CloseStatus::GoingAway`（理由は`"pong timeout"`）で接続が閉じられます。
+たとえばPing間隔が30秒で`max_missed_pongs = 2`なら、相手が応答しなくなってから60〜90秒で検出され、`CloseStatus::GoingAway`（理由は`"pong timeout"`）で接続が閉じられます。このとき`read()`で受信を待っていた場合は、`Fail`が返ります。
 
-この仕組みは`read()`を呼んでPongフレームを消費したタイミングでカウンタがリセットされます。つまり通常のWebSocketクライアントのように`read()`をループで回していれば、特に意識することなく動きます。
+カウンタは、`read()`がPongフレームを受け取ったタイミングでリセットされます。つまり、通常のWebSocketクライアントのように`read()`をループで回していれば、特に意識しなくても動きます。
 
 ### デフォルトは無効
 
 `max_missed_pongs`のデフォルトは`0`で、これは「Pongが何回返ってこなくてもこの仕組みでは切断しない」という意味です。Ping自体は送られ続けますが、応答の有無はチェックされません。無応答ピアを検出したい場合は明示的に`1`以上を設定してください。
 
-ただし`0`のままでも最終的に接続が残り続けることはありません。`read()`を呼んでいる間は`CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND`（デフォルト**300秒 = 5分**）が保険として働き、フレームが一定時間来なければ`read()`が失敗します。つまり`max_missed_pongs`は「**もっと速く**無応答を検出したい」ときに使うオプションだと考えてください。
+サーバー側は`0`のままでも接続が残り続けることはありません。ハンドラが`read()`を呼んでいる間は`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`（デフォルト**300秒 = 5分**）が保険として働きます。一方クライアント側にはこの保険がなく、読み取りタイムアウトを設定しない限り無期限に待つので、無応答ピアを検出する手段は`max_missed_pongs`だけです。どちらの側でも「**もっと速く**検出したい」ときに使うオプションでもあります。
 
 > 接続が閉じたときの処理は[W03. 接続クローズをハンドリングする](../w03-websocket-close)を参照してください。

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

@@ -1,6 +1,6 @@
 ---
 title: "W03. 接続クローズをハンドリングする"
-order: 53
+order: 54
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "W04. バイナリフレームを送受信する"
-order: 54
+order: 55
 status: "draft"
 ---
 
@@ -42,6 +42,9 @@ switch (result) {
   case httplib::ws::ReadResult::Fail:
     // エラーまたは切断
     break;
+  case httplib::ws::ReadResult::Timeout:
+    // 読み取りタイムアウト。接続は開いたまま
+    break;
 }
 ```
 

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

@@ -1,6 +1,6 @@
 ---
 title: "W05. wss接続でTLSを設定する"
-order: 55
+order: 56
 status: "draft"
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 title: "W06. タイムアウトを設定する"
-order: 56
+order: 57
 status: "draft"
 ---
 
@@ -9,7 +9,7 @@ status: "draft"
 | 種類 | API | デフォルト |
 | --- | --- | --- |
 | 接続タイムアウト | `set_connection_timeout` | 300秒 |
-| 読み取りタイムアウト | `set_read_timeout` | 300秒（`CPPHTTPLIB_WEBSOCKET_READ_TIMEOUT_SECOND`） |
+| 読み取りタイムアウト | `set_read_timeout` | なし。無期限に待つ（`CPPHTTPLIB_WEBSOCKET_CLIENT_READ_TIMEOUT_SECOND`） |
 | 書き込みタイムアウト | `set_write_timeout` | 5秒 |
 
 ## 基本の使い方
@@ -26,7 +26,7 @@ if (ws.connect()) {
 }
 ```
 
-`connect()`を呼ぶ前に設定してください。
+接続タイムアウトと書き込みタイムアウトは`connect()`を呼ぶ前に設定してください。読み取りタイムアウトはいつでも変更でき、接続済みの状態で設定した場合は次の`read()`から効きます。
 
 ## `std::chrono`で指定する
 
@@ -40,9 +40,44 @@ ws.set_read_timeout(30s);
 ws.set_write_timeout(10s);
 ```
 
-## 読み取りタイムアウトの意味に注意
+## 読み取りタイムアウトの意味
 
-`set_read_timeout()`は「1回の`read()`呼び出し」に対するタイムアウトです。メッセージが届かないまま指定時間が経過すると`read()`が`ReadResult::Fail`を返します。通知の待受のように長時間メッセージが来ないことが正常な接続では、意図せず切断されないよう長めに設定するか、切断されたらアプリケーション側で再接続してください。
+`set_read_timeout()`は「1回の`read()`呼び出し」に対するタイムアウトです。メッセージが届かないまま指定時間が経過すると`read()`は`ReadResult::Timeout`を返します。このとき**接続は開いたまま**で、1バイトも読み進めていないので、そのまま送信して読み直せます。接続が失われたことを意味する`ReadResult::Fail`とはここが違います。
+
+1本の接続を1つのスレッドで双方向に扱えるのはこのためです。
+
+```cpp
+using namespace std::chrono_literals;
+
+ws.set_read_timeout(100ms);
+std::string msg;
+while (ws.is_open()) {
+  auto r = ws.read(msg);
+  if (r == httplib::ws::Timeout) {
+    flush_outgoing(ws);  // 何も届いていない。溜まっている分を送る
+    continue;
+  }
+  if (r == httplib::ws::Fail) { break; }
+  handle(msg);
+}
+```
+
+読み取りタイムアウトを設定しないと`read()`はメッセージが届くまで戻らないので、接続を持っているスレッドは送信に手が回りません。
+
+`Timeout`について2点あります。
+
+- `msg`は書き換えられません。値も0以外なので、読み取りタイムアウトを設定した状態で`while (ws.read(msg))`と書くと、**前回のメッセージ**が`msg`に残ったままループが回り続けます。
+- 報告されるのはメッセージの境界だけです。分割されたメッセージの途中でタイムアウトした場合、そのメッセージは再開できないので`read()`は`Fail`を返します。
+
+通知の待受のように長時間メッセージが来ないことが正常な接続では、読み取りタイムアウトを設定しないままにするか、`Timeout`を「まだ何も来ていない」印として扱ってループを続けてください。
+
+## サーバ側
+
+ハンドラが受け取る`ws::WebSocket`にも`set_read_timeout()`があります。ハンドラが`read()`で止まったままにならないので、上と同じ書き方で複数の接続の間をメッセージが中継できます。
+
+サーバ側のデフォルトは「無期限」ではなく300秒（`CPPHTTPLIB_WEBSOCKET_SERVER_READ_TIMEOUT_SECOND`）です。WebSocketのハンドラは接続が続く限りワーカーを1つ占有するので、無言になったピアからワーカーを回収する保険として働きます。
+
+この保険はハンドラが求めたタイムアウトではないので、`Timeout`としては返りません。経過すると`read()`は`Fail`を返して接続を閉じるため、`while (ws.read(msg))`と書いたハンドラは従来どおりそこで終わります。`Timeout`が返るのは、ハンドラ自身が`set_read_timeout()`で設定したタイムアウトだけです。
 
 > Ping/Pongによる無応答ピア検出は別の仕組みです。詳しくは[W02. ハートビートを設定する](../w02-websocket-ping)を参照してください。
 

docs-src/pages/ja/index.md

@@ -3,7 +3,7 @@ title: "cpp-httplib"
 order: 0
 ---
 
-[cpp-httplib](https://github.com/yhirose/cpp-httplib)は、C++用のHTTP/HTTPSライブラリです。[`httplib.h`](https://github.com/yhirose/cpp-httplib/raw/refs/tags/latest/httplib.h) というヘッダーファイルを1枚コピーするだけで使えます。
+[cpp-httplib](https://github.com/yhirose/cpp-httplib)は、C++用のHTTP/HTTPSライブラリです。[`httplib.h`](https://github.com/yhirose/cpp-httplib/raw/refs/tags/latest/httplib.h)というヘッダーファイルを1枚コピーするだけで使えます。
 
 C++でちょっとしたHTTPサーバーやクライアントが必要になったとき、すぐに動くものが欲しいですよね。cpp-httplibはまさにそのために作られました。サーバーもクライアントも、数行のコードで書き始められます。
 

docs-src/pages/ja/llm-app/ch02-rest-api.md

@@ -18,10 +18,6 @@ llama.cppのAPIを直接扱うとコードが長くなるので、薄いラッ
 int main() {
   auto llm = llamalib::Llama{"models/gemma-2-2b-it-Q4_K_M.gguf"};
 
-  // LLM推論は時間がかかるのでタイムアウトを長めに設定（デフォルトは5秒）
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   // ... HTTPサーバーの構築・起動 ...
 }
 ```
@@ -78,7 +74,7 @@ svr.Post("/translate",
 });
 ```
 
-`llm.chat()`は推論中に例外を投げることがあります（コンテキスト長の超過など）。`try/catch`で捕捉してエラーをJSONで返すことで、サーバーがクラッシュするのを防ぎます。
+`llm.chat()`は推論中に例外を投げることがあります（コンテキスト長の超過など）。`try/catch`で捕捉して、エラーの内容をJSONで返します。捕捉しなくてもcpp-httplibが500を返してくれますが、何が起きたのかはクライアントに伝わりません。
 
 ## 2.3 全体のコード
 
@@ -111,10 +107,6 @@ int main() {
   // 1章でダウンロードしたモデルをロード
   auto llm = llamalib::Llama{"models/gemma-2-2b-it-Q4_K_M.gguf"};
 
-  // LLM推論は時間がかかるのでタイムアウトを長めに設定（デフォルトは5秒）
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   // リクエストとレスポンスをログに記録
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status

docs-src/pages/ja/llm-app/ch03-sse-streaming.md

@@ -73,7 +73,7 @@ svr.Post("/translate/stream",
 - `sink.os`に書き込んだ後、`sink.os.good()`でクライアントがまだ接続しているかを確認できます。切断されていたら`false`を返して推論を止めます
 - 各トークンは`json(token).dump()`でJSON文字列としてエスケープしてから送ります。改行やクォートを含むトークンでも安全です
 - `dump(-1, ' ', false, ...)`の最初の3つの引数はデフォルトと同じです。重要なのは第4引数の`json::error_handler_t::replace`です。LLMはトークンをサブワード単位で返すため、マルチバイト文字（日本語など）の途中でトークンが切れることがあります。不完全なUTF-8バイト列をそのまま`dump()`に渡すと例外が飛ぶので、`replace`で安全に置換します。ブラウザ側で結合されるため、表示上の問題はありません
-- `try/catch`でラムダ全体を囲んでいます。`llm.chat()`はコンテキストウィンドウの超過などで例外を投げることがあります。ラムダ内で例外が未捕捉だとサーバーがクラッシュするので、エラーをSSEイベントとして返します
+- `try/catch`でラムダ全体を囲んでいます。`llm.chat()`はコンテキストウィンドウの超過などで例外を投げることがあります。ラムダの中で例外を捕捉しないと、cpp-httplibは接続を切るだけなので、何が起きたのかクライアントにはわかりません。そこで、エラーをSSEイベントとして返します
 - `data: [DONE]`はOpenAI APIと同じ慣習で、ストリームの終了をクライアントに伝えます
 
 ## 3.4 全体のコード
@@ -107,10 +107,6 @@ int main() {
   // GGUFモデルをロード
   auto llm = llamalib::Llama{"models/gemma-2-2b-it-Q4_K_M.gguf"};
 
-  // LLM推論は時間がかかるのでタイムアウトを長めに設定（デフォルトは5秒）
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   // リクエストとレスポンスをログに記録
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status

docs-src/pages/ja/llm-app/ch04-model-management.md

@@ -219,7 +219,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);
-  cli.set_read_timeout(std::chrono::hours(1));
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -469,7 +468,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);  // Hugging FaceはCDNにリダイレクトする
-  cli.set_read_timeout(std::chrono::hours(1)); // 大きなモデルに備えて長めに
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -539,10 +537,6 @@ int main() {
   auto llm = llamalib::Llama{path};
   std::mutex llm_mutex; // モデル切り替え中のアクセスを保護する
 
-  // LLM推論は時間がかかるのでタイムアウトを長めに設定（デフォルトは5秒）
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status
               << std::endl;

docs-src/pages/ja/llm-app/ch05-web-ui.md

@@ -939,7 +939,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);  // Hugging FaceはCDNにリダイレクトする
-  cli.set_read_timeout(std::chrono::hours(1)); // 大きなモデルに備えて長めに
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -1008,10 +1007,6 @@ int main() {
   }
   auto llm = llamalib::Llama{path};
 
-  // LLM推論は時間がかかるのでタイムアウトを長めに設定（デフォルトは5秒）
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status
               << std::endl;

docs-src/pages/ja/llm-app/ch06-desktop-app.md

@@ -17,7 +17,7 @@ order: 6
 
 モデルは初回起動時に自動ダウンロードされるので、ユーザーに渡すのはバイナリ1つだけです。
 
-## 6.1 webview/webview を導入する
+## 6.1 webview/webviewを導入する
 
 [webview/webview](https://github.com/webview/webview)は、OS標準のWebViewコンポーネント（macOSならWKWebView、LinuxならWebKitGTK、WindowsならWebView2）をC/C++から使えるようにするライブラリです。Electronのように独自ブラウザを同梱するわけではないので、バイナリサイズへの影響はほぼありません。
 
@@ -78,7 +78,7 @@ int main() {
 
 5章の`signal_handler`は不要になります。デスクトップアプリではウインドウを閉じることがアプリの終了を意味するからです。
 
-## 6.3 cpp-embedlib で静的ファイルを埋め込む
+## 6.3 cpp-embedlibで静的ファイルを埋め込む
 
 5章では`public/`ディレクトリからファイルを配信していました。これだと配布時に`public/`も一緒に渡す必要があります。[cpp-embedlib](https://github.com/yhirose/cpp-embedlib)を使うと、HTML・CSS・JavaScriptをバイナリに埋め込んで、配布物をバイナリ1つにまとめられます。
 
@@ -108,7 +108,7 @@ target_link_libraries(translate-app PRIVATE
 
 `cpp_embedlib_add`は、`public/`配下のファイルをコンパイル時にバイナリに変換し、`WebAssets`という静的ライブラリを作ります。リンクすると`Web::FS`というオブジェクトから埋め込みファイルにアクセスできます。`cpp-embedlib-httplib`は`httplib::mount()`関数を提供するヘルパーライブラリです。
 
-### set_mount_point を httplib::mount に置き換える
+### set_mount_pointをhttplib::mountに置き換える
 
 5章の`set_mount_point`をcpp-embedlibの`httplib::mount`に置き換えるだけです。
 
@@ -407,7 +407,6 @@ bool download_model(const ModelInfo &model,
                     std::function<bool(int)> progress_cb) {
   httplib::Client cli("https://huggingface.co");
   cli.set_follow_location(true);  // Hugging FaceはCDNにリダイレクトする
-  cli.set_read_timeout(std::chrono::hours(1)); // 大きなモデルに備えて長めに
 
   auto url = "/" + model.repo + "/resolve/main/" + model.filename;
   auto path = get_models_dir() / model.filename;
@@ -469,10 +468,6 @@ int main() {
   auto llm = llamalib::Llama{path};
   std::mutex llm_mutex; // モデル切り替え中のアクセスを保護する
 
-  // LLM推論は時間がかかるのでタイムアウトを長めに設定（デフォルトは5秒）
-  svr.set_read_timeout(300);
-  svr.set_write_timeout(300);
-
   svr.set_logger([](const auto &req, const auto &res) {
     std::cout << req.method << " " << req.path << " -> " << res.status
               << std::endl;