Release v0.62.0

open_stream(), and with it stream::Get() and SSEClient, wrote its own
request head and left out what a buffered request gets: the
Authorization from set_basic_auth() or set_bearer_token_auth(), and
through a plain HTTP proxy the absolute-form target (RFC 9112 3.2.2)
and Proxy-Authorization. A proxy refused such a request, and an origin
that needs credentials answered 401.

Move the two decisions out of write_request() and handle_request() into
add_credential_headers() and proxy_target_prefix(), and use them in
open_stream() too, after connecting as a buffered request does. A
Digest challenge or a redirect is still handed to the caller.

.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

@@ -4,7 +4,7 @@ A simple, EventSource-like SSE client for C++11.
 
 ## Features
 
-- **Auto-reconnect**: Automatically reconnects on connection loss
+- **Auto-reconnect**: Automatically reconnects on connection loss or an error status (except 204, 403 and 404)
 - **Last-Event-ID**: Sends last received ID on reconnect for resumption
 - **retry field**: Respects server's reconnect interval
 - **Event types**: Supports custom event types via `on_event()`
@@ -52,7 +52,7 @@ SSEClient(Client &client, const std::string &path, const Headers &headers);
 #### Event Handlers
 
 ```cpp
-// Called for all events (or events without a specific handler)
+// Called for events whose type has no on_event() handler
 sse.on_message([](const SSEMessage &msg) { });
 
 // Called for specific event types
@@ -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)
@@ -79,6 +79,10 @@ sse.set_max_reconnect_attempts(10);
 sse.set_headers({{"Authorization", "Bearer new_token"}});
 ```
 
+The client reconnects when it cannot connect or the stream ends. A status other than `200` calls `on_error(Error::Connection)`; a `204`, `403` or `404` then stops the client, and any other status, `401` included, reconnects, so an `on_error` handler can refresh credentials with `set_headers()`. `set_max_reconnect_attempts()` counts reconnect attempts in a row: the count starts over after each successful connection. Each attempt that fails to connect is also reported to the `Client`'s error logger.
+
+An event, or a line still waiting for its end, longer than `CPPHTTPLIB_SSE_MAX_EVENT_LENGTH` (16MB by default, `0` for no limit) ends the connection with `Error::ExceedMaxPayloadSize`, and the client stops rather than reconnect to the same event. The client's `set_payload_max_length()` does not apply to the stream as a whole, which has no end.
+
 #### Control
 
 ```cpp
@@ -157,6 +161,8 @@ httplib::sse::SSEClient sse(cli, "/events", headers);
 sse.start();
 ```
 
+The `Client`'s `set_basic_auth()` and `set_bearer_token_auth()` apply too; an `Authorization` header passed like this takes precedence.
+
 ### Refreshing Auth Token on Reconnect
 
 ```cpp
@@ -191,7 +197,7 @@ sse.start();
 
 ## SSE Protocol
 
-The client parses SSE format according to the [W3C specification](https://html.spec.whatwg.org/multipage/server-sent-events.html):
+The client parses SSE format according to the [WHATWG HTML Living Standard](https://html.spec.whatwg.org/multipage/server-sent-events.html):
 
 ```
 event: custom-type

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.
 
@@ -14,7 +14,7 @@ The streaming API allows you to process HTTP response bodies chunk by chunk usin
 
 - **LLM/AI streaming responses** (e.g., ChatGPT, Claude, Ollama)
 - **Server-Sent Events (SSE)**
-- **Large file downloads** with progress tracking
+- **Large file downloads** with progress tracking (mind the [payload size limit](#payload-size-limit))
 - **Reverse proxy implementations**
 
 ## Quick Start
@@ -62,7 +62,7 @@ cpp-httplib provides multiple API layers for different use cases:
 | Use Case | Recommended API |
 |----------|----------------|
 | SSE with auto-reconnect | `SSEClient` (see [README-sse.md](README-sse.md)) |
-| LLM streaming (JSON Lines) | `stream::Get()` |
+| LLM streaming (JSON Lines) | `stream::Post()` or `stream::Get()` |
 | Large file download | `stream::Get()` or `open_stream()` |
 | Reverse proxy | `open_stream()` |
 | Small responses with Keep-Alive | `Client::Get()` |
@@ -106,6 +106,8 @@ if (handle.is_valid()) {
 | `get_read_error()` | `Error` | Get the last read error |
 | `has_read_error()` | `bool` | Check if a read error occurred |
 
+For a chunked response, the trailers are in `response->trailers` once `read()` has reached the end of the body.
+
 ### High-Level API: `stream::Get()` and `stream::Result`
 
 The `httplib.h` header provides a more ergonomic iterator-style API.
@@ -114,7 +116,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
@@ -138,6 +139,30 @@ if (result2) {
 }
 ```
 
+#### Helpers
+
+There is a helper for each HTTP method. The arguments in brackets can be left out, and every helper takes a trailing `size_t chunk_size = 8192`, the most bytes one `next()` returns.
+
+| Helper | Arguments |
+|--------|-----------|
+| `stream::Get()` | `(cli, path, [params], [headers], [chunk_size])` |
+| `stream::Head()` | `(cli, path, [params], [headers], [chunk_size])` |
+| `stream::Options()` | `(cli, path, [params], [headers], [chunk_size])` |
+| `stream::Post()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
+| `stream::Put()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
+| `stream::Patch()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
+| `stream::Delete()` | `(cli, path, [params], [headers], [chunk_size])` |
+| `stream::Delete()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
+
+`params` is a `Params`, `headers` a `Headers`, and `body` and `content_type` are `std::string`s.
+
+```cpp
+// POST a JSON body and stream the response in 4KB chunks
+auto result3 = httplib::stream::Post(cli, "/api/generate", headers,
+                                     R"({"prompt": "hello"})",
+                                     "application/json", 4096);
+```
+
 #### stream::Result Members
 
 | Member | Type | Description |
@@ -217,6 +242,7 @@ int main() {
 
 int main() {
     httplib::Client cli("http://example.com");
+    cli.set_payload_max_length(0);  // No limit (the default is 100MB)
     auto result = httplib::stream::Get(cli, "/large-file.zip");
     
     if (!result || result.status() != 200) {
@@ -233,6 +259,12 @@ int main() {
         std::cout << "\rDownloaded: " << (total / 1024) << " KB" << std::flush;
     }
     
+    if (result.has_read_error()) {
+        std::cerr << "\nDownload failed: "
+                  << httplib::to_string(result.read_error()) << "\n";
+        return 1;
+    }
+
     std::cout << "\nComplete!\n";
     return 0;
 }
@@ -243,23 +275,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;
@@ -311,6 +349,14 @@ while (result.next()) { /* ... */ }
 auto res = cli.Get("/api/data");  // Connection can be reused
 ```
 
+### Payload Size Limit
+
+`open_stream()` and the `stream::` helpers apply the client's `set_payload_max_length()` (100MB by default, `CPPHTTPLIB_PAYLOAD_MAX_LENGTH`) to the body, both as received and after decompression. Past the limit, `read()` and `next()` stop, and the read error is `Error::ExceedMaxPayloadSize`. To download something larger, raise the limit, or call `cli.set_payload_max_length(0)` for no limit.
+
+### Authentication and Proxies
+
+A stream request carries the same credentials as `client.Get()`: `set_basic_auth()` and `set_bearer_token_auth()` for the origin, and the proxy's own through `set_proxy()`, over HTTP or through a CONNECT tunnel. It does not answer a Digest challenge or follow a redirect: the `401` or `3xx` response is handed to you.
+
 ## Related
 
 - [Issue #2269](https://github.com/yhirose/cpp-httplib/issues/2269) - Original feature request

README-websocket.md

@@ -6,7 +6,7 @@ A simple, blocking WebSocket implementation for C++11.
 > This is a blocking I/O WebSocket implementation using a thread-per-connection model (plus one heartbeat thread per connection). It is intended for small- to mid-scale workloads; handling large numbers of simultaneous WebSocket connections is outside the design target of this library. If you need high-concurrency WebSocket support with non-blocking/async I/O (e.g., thousands of simultaneous connections), this is not the one that you want.
 
 > [!NOTE]
-> WebSocket extensions (`permessage-deflate` and others defined by RFC 6455) are **not supported**. If a client proposes an extension via `Sec-WebSocket-Extensions`, the server silently declines it — the negotiated connection always runs without extensions.
+> WebSocket extensions (such as `permessage-deflate`, RFC 7692) are **not supported**. If a client proposes an extension via `Sec-WebSocket-Extensions`, the server silently declines it — the negotiated connection always runs without extensions.
 
 ## Features
 
@@ -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,14 +119,14 @@ 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)
 
 Passed to the handler registered with `Server::WebSocket()`. The handler runs in a dedicated thread per connection.
 
 ```cpp
-// Read next message (blocks until received, returns Fail/Text/Binary)
+// Read next message (blocks until received, returns Fail/Text/Binary/Timeout)
 ReadResult read(std::string &msg);
 
 // Send messages
@@ -126,18 +142,25 @@ const Request &request() const;
 
 // Check if the connection is still open
 bool is_open() const;
+
+// Bound how long read() waits before returning Timeout (0 waits forever).
+// Safe to call while another thread is in read().
+void set_read_timeout(time_t sec, time_t usec = 0);
+template <class Rep, class Period>
+void set_read_timeout(const std::chrono::duration<Rep, Period> &duration);
 ```
 
 ### WebSocketClient
 
 ```cpp
-// Constructor - accepts ws:// or wss:// URL
+// Constructor - accepts ws:// or wss:// URL. Any other scheme, or wss:// in a
+// build without SSL, throws std::invalid_argument (with
+// CPPHTTPLIB_NO_EXCEPTIONS, is_valid() returns false instead).
 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;
@@ -148,15 +171,20 @@ struct PemMemory {
 explicit WebSocketClient(const std::string &scheme_host_port_path,
                          const PemMemory &pem, const Headers &headers = {});
 
-// Check if the URL was parsed successfully
+// Check if the URL was parsed successfully. For wss://, also false when the
+// TLS context or the client certificate cannot be loaded.
 bool is_valid() const;
 
 // Connect (performs HTTP upgrade handshake). The returned Result is truthy
 // only when the handshake fully succeeded; on failure it describes what went
 // wrong:
 //   res.error()             httplib::Error identifying the failing layer
-//   res.status()            HTTP status of the upgrade response (-1 if none)
+//   res.status()            HTTP status of the upgrade response (-1 if none),
-//   res.headers()           headers of the upgrade response
+//                           or of the proxy's CONNECT reply when error() is
+//                           Error::ProxyConnection
+//   res.headers()           headers of that same response
+//   res.get_header_value(key, def), res.has_header(key)
+//                           look up one of those headers
 //   res.ssl_error()         TLS error detail (wss://, SSL builds only)
 //   res.ssl_backend_error() backend-specific TLS error code (SSL builds only)
 Result connect();
@@ -172,6 +200,18 @@ void close(CloseStatus status = CloseStatus::Normal,
            const std::string &reason = "");
 bool is_open() const;
 
+// Proxy - the same setters Client has. connect() opens a CONNECT tunnel
+// through the proxy for ws:// as well as wss:// (RFC 6455 4.1); the proxy
+// credentials are sent only on the CONNECT request, never through the tunnel.
+// Hosts matching set_no_proxy() are connected to directly.
+void set_proxy(const std::string &host, int port);
+void set_proxy_basic_auth(const std::string &username,
+                          const std::string &password);
+void set_proxy_bearer_token_auth(const std::string &token);
+void set_no_proxy(const std::vector<std::string> &patterns);
+void set_proxy_digest_auth(const std::string &username,
+                           const std::string &password); // SSL builds only
+
 // Timeouts
 void set_read_timeout(time_t sec, time_t usec = 0);
 void set_write_timeout(time_t sec, time_t usec = 0);
@@ -183,12 +223,30 @@ 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)
+// Heartbeat (see Runtime Ping Interval and Unresponsive-Peer Detection below)
+void set_websocket_ping_interval(time_t sec);
+void set_websocket_max_missed_pongs(int count);
+
+// Socket - the same setters Client has
+void set_tcp_nodelay(bool on);
+void set_address_family(int family);
+void set_ipv6_v6only(bool on);
+void set_socket_options(SocketOptions socket_options);
+void set_interface(const std::string &intf);
+void set_hostname_addr_map(std::map<std::string, std::string> addr_map);
+
+// 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);
+void load_ca_cert_store(const char *ca_cert, std::size_t size);
 void enable_server_certificate_verification(bool enabled);
 void enable_server_hostname_verification(bool enabled);
+void enable_system_ca(bool enabled);
+// The same verifiers as SSLClient's, e.g. to pin the server's certificate
+void set_server_certificate_verifier(tls::VerifyCallback verifier);
+void set_session_verifier(
+    std::function<SSLVerifierResponse(tls::session_t)> verifier);
 ```
 
 ## Examples
@@ -233,17 +291,21 @@ if (ws.connect()) {
 
 `connect()` returns a `Result` that tells you why a connection attempt failed.
 `error()` distinguishes network problems (`Connection`, `ConnectionTimeout`),
-TLS problems (`SSLConnection`, `SSLServerVerification`,
+proxy problems (`ProxyConnection`), TLS problems (`SSLConnection`,
-`SSLServerHostnameVerification`), and upgrade rejections
+`SSLServerVerification`, `SSLServerHostnameVerification`), and upgrade
-(`WebSocketHandshake`). When the server answered with something other than
+rejections (`WebSocketHandshake`). `WebSocketHandshake` covers a status other
-`101 Switching Protocols`, `status()` and `headers()` carry that response:
+than `101 Switching Protocols` as well as a `101` that fails validation (for
+example a wrong `Sec-WebSocket-Accept`); either way `status()` and `headers()`
+carry the server's response. When a proxy refuses the `CONNECT` request, the
+error is `ProxyConnection` and they carry the proxy's reply instead (e.g. 407):
 
 ```cpp
 auto res = ws.connect();
 if (!res) {
     std::cerr << "connect failed: " << httplib::to_string(res.error()) << std::endl;
     if (res.status() != -1) {
-        // The server responded but refused the upgrade (e.g. 401, 404)
+        // The server refused the upgrade (e.g. 401, 404, or an invalid 101),
+        // or, with ProxyConnection, the proxy refused CONNECT (e.g. 407)
         std::cerr << "HTTP status: " << res.status() << std::endl;
     }
 }
@@ -327,6 +389,20 @@ 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;
+});
+```
+
+The server accepts a handshake from any `Origin`. A browser sends its cookies with a handshake another site starts, so if cookies authenticate the connection, also check `req.get_header_value("Origin")` against your own origins in one of these handlers (cross-site WebSocket hijacking).
+
 ### Custom Headers and Timeouts
 
 ```cpp
@@ -408,8 +484,9 @@ if (ws.connect()) {
 
 | Macro                                       | Default           | Description                                              |
 |---------------------------------------------|-------------------|----------------------------------------------------------|
-| `CPPHTTPLIB_WEBSOCKET_MAX_PAYLOAD_LENGTH`   | `16777216` (16MB) | Maximum payload size per message                         |
+| `CPPHTTPLIB_WEBSOCKET_MAX_PAYLOAD_LENGTH`   | `16777216` (16MB) | Maximum payload size per message (`0` means no limit)    |
-| `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,13 +521,13 @@ 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
 
-WebSocket connections share the same thread pool as HTTP requests. Each WebSocket connection occupies one thread for its entire lifetime.
+WebSocket connections share the same thread pool as HTTP requests. Each WebSocket connection occupies one thread for its entire lifetime, so a client opening many of them can leave none for HTTP requests. Reject the upgrades you do not want in `set_pre_request_handler()`, before the connection takes a thread for good.
 
 The default thread pool uses dynamic scaling: it maintains a base thread count of `CPPHTTPLIB_THREAD_POOL_COUNT` (8 or `std::thread::hardware_concurrency() - 1`, whichever is greater) and can scale up to 4x that count under load (`CPPHTTPLIB_THREAD_POOL_MAX_COUNT`). When all base threads are busy, temporary threads are spawned automatically up to the maximum. These dynamic threads exit after an idle timeout (`CPPHTTPLIB_THREAD_POOL_IDLE_TIMEOUT`, default 3 seconds).
 
@@ -466,6 +543,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,9 @@ 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()` or `set_ca_cert_store()`. Certificates loaded through `set_ca_cert_path()` or system certificates (`load_system_certs`) are not enumerable.
+>
+> A wolfSSL server that verifies client certificates does not resume TLS sessions: wolfSSL shares its session cache between contexts, so a resumed session could carry a certificate checked against another server's client CA.
 
 > [!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 +88,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
@@ -99,12 +101,17 @@ cli.enable_server_certificate_verification(false);
 cli.enable_server_hostname_verification(false);
 ```
 
+> [!NOTE]
+> The CA certificates are loaded when the client makes its first connection. Changing `set_ca_cert_path()` or `enable_system_ca()` after that has no effect, so make the settings before the first request, or use a new client. `set_ca_cert_store()` and `load_ca_cert_store()` take effect at once. `WebSocketClient` works the same way.
+
 ### SSL Error Handling
 
 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`. `CertVerifyFailed` comes from Mbed TLS and wolfSSL. OpenSSL checks the chain and the host name after the handshake, so a failure there leaves this `0`
-- `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. On Windows, when CryptoAPI verifies the chain, a failure there reports the CryptoAPI error code here
+
+A request that fails after the handshake with `Error::Read` or `Error::Write` also carries the TLS error behind it in both values, such as a TLS 1.3 "certificate required" alert from the server. Both values are reset for each request.
 
 ```c++
 #define CPPHTTPLIB_OPENSSL_SUPPORT  // or CPPHTTPLIB_MBEDTLS_SUPPORT or CPPHTTPLIB_WOLFSSL_SUPPORT
@@ -163,11 +170,13 @@ cli.set_server_certificate_verifier(
         std::cout << "SAN: " << san.value << std::endl;
       }
 
-      // Return true to accept, false to reject
+      // Return false to reject
       return ctx.preverify_ok;
     });
 ```
 
+Returning `false`, or throwing, rejects the certificate. The callback runs alongside the built-in verification, so to accept a certificate that verification rejects, such as a self-signed one, also call `enable_server_certificate_verification(false)`; the callback is then the only check.
+
 ### Mutual TLS (mTLS)
 
 Regular TLS only verifies the server certificate. With mTLS, the client also presents a certificate that the server verifies.
@@ -230,16 +239,20 @@ 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:
+On Windows, the CryptoAPI check can also be turned off at runtime. The TLS backend then verifies the chain instead, as on other platforms:
 
 ```c++
 cli.enable_windows_certificate_verification(false);
 ```
 
+`WebSocketClient` does not use CryptoAPI; the TLS backend always verifies its chain.
+
 > [!NOTE]
 > When using SSL, it seems impossible to avoid SIGPIPE in all cases, since on some operating systems, SIGPIPE can only be suppressed on a per-message basis, but there is no way to make the OpenSSL library do so for its internal communications. If your program needs to avoid being terminated on SIGPIPE, the only fully general way might be to set up a signal handler for SIGPIPE to handle or ignore it yourself.
+>
+> On systems other than Windows, the `Server` constructor does this already: it calls `signal(SIGPIPE, SIG_IGN)`, which affects the whole process. A program that only uses clients has to do it itself.
 
 ## Server
 
@@ -307,6 +320,41 @@ 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 `Get` (which also serves `HEAD`), `Post`, `Put`, `Delete`, `Options` or `Patch` instead. There are no handlers for `CONNECT`, `TRACE` and `PRI`; such requests get `400 Bad Request`.
+* 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.
+
+The request line and the `Host` header are read strictly, as RFC 9112 asks: a single space between the three parts of the request line, `HTTP/1.0` or `HTTP/1.1` as the version, no fragment (`#...`) in the target, and exactly one valid `Host` header (an HTTP/1.0 request may have none). Anything else gets `400 Bad Request`.
+
 ### Bind a socket to multiple interfaces and any available port
 
 ```cpp
@@ -314,6 +362,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
@@ -344,6 +411,8 @@ svr.set_file_extension_and_mimetype_mapping("cpp", "text/x-c");
 svr.set_file_extension_and_mimetype_mapping("hh", "text/x-h");
 ```
 
+Extensions match regardless of case, so `photo.JPG` is served as `image/jpeg`. A user mapping is looked up by the exact extension first, then by the extension in lowercase.
+
 The following are built-in mappings:
 
 | Extension  |          MIME Type          | Extension  |          MIME Type          |
@@ -386,13 +455,15 @@ svr.set_file_request_handler([](const Request &req, Response &res) {
 });
 ```
 
+It is not called for `HEAD` requests or `304 Not Modified` responses, so do not use it for access control; use `set_pre_routing_handler()`.
+
 ### Logging
 
 cpp-httplib provides separate logging capabilities for access logs and error logs, similar to web servers like Nginx and Apache.
 
 #### Access Logging
 
-Access loggers capture successful HTTP requests and responses:
+Access loggers capture each request and the response written for it, including the error responses the library writes itself, such as `400`, `404`, `413` or `500`:
 
 ```cpp
 svr.set_logger([](const httplib::Request& req, const httplib::Response& res) {
@@ -400,6 +471,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:
@@ -412,7 +486,9 @@ 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.
+The pre-compression logger is only called when the server compresses `res.body` or a static file. It is not called for a response without compression, nor for a chunked content provider, whose body is compressed as it is written; for those, 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
 
@@ -442,7 +518,7 @@ svr.set_error_handler([](const auto& req, auto& res) {
 ```
 
 ### Exception handler
-The exception handler gets called if a user routing handler throws an error.
+The exception handler gets called if a user routing handler throws an error. This covers the pre-routing handler, the file request handler, the pre-request handler, route handlers and content readers. An exception from the post-routing handler, the error handler, the `Expect: 100-continue` handler, a content provider, a logger or a WebSocket handler does not reach it: the connection is dropped, and the error logger receives `Error::UserCallbackException`.
 
 ```cpp
 svr.set_exception_handler([](const auto& req, auto& res, std::exception_ptr ep) {
@@ -461,7 +537,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,28 +586,34 @@ 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)
+  │     └─ a mount point answered → go straight to post_routing_handler
   │
   ├─ 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
 ```
 
-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.
+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. A request that a mount point answers never reaches route matching or `pre_request_handler`, so reject such a request in `pre_routing_handler`.
+
+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
 
@@ -549,7 +631,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;
@@ -653,7 +735,10 @@ svr.Post("/multipart", [&](const Request& req, Response& res) {
 auto safe = httplib::sanitize_filename(file.filename);
 ```
 
-This function strips path separators (`/`, `\`), null bytes, leading/trailing whitespace, and rejects `.` and `..`. Returns an empty string if the filename is unsafe.
+This function keeps only the part after the last `/` or `\`, removes null bytes, and trims leading and trailing spaces and tabs. It returns an empty string if what is left is empty, `.` or `..`.
+
+> [!NOTE]
+> `name` and `filename` are read as quoted-strings (RFC 9110 §5.6.4), where `\"` and `\\` stand for `"` and `\`. Browsers send a backslash as it is, so from a browser, a value with `\\` in it arrives with a single `\`, and one that ends in `\` is not read correctly.
 
 ### Receive content with a content receiver
 
@@ -695,6 +780,18 @@ svr.Post("/content_receiver",
   });
 ```
 
+`content_reader` reads the body once per request; a second call returns `false`.
+When a callback returns `false`, reading stops, `content_reader` returns `false`,
+and `res.status` is set to `400` unless the handler sets another status. The
+rest of the body is left unread, so the connection is closed after the response.
+
+`CPPHTTPLIB_MULTIPART_FORM_DATA_FILE_MAX_COUNT` (default 1024, `0` for no limit)
+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
@@ -715,6 +812,8 @@ svr.Get("/stream", [&](const Request &req, Response &res) {
 });
 ```
 
+Write at most `length` bytes per call. Anything past it is not sent, and the response fails. The response also fails if a call returns `true` without writing anything, or if `sink.done()` is called before the whole content length is written.
+
 Without content length:
 
 ```cpp
@@ -734,6 +833,8 @@ svr.Get("/stream", [&](const Request &req, Response &res) {
 });
 ```
 
+Such a body ends where the connection does, so the server sends `Connection: close` and closes the connection after the response. Use `set_chunked_content_provider()` to keep the connection open.
+
 ### Chunked transfer encoding
 
 ```cpp
@@ -786,7 +887,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.
@@ -805,7 +908,7 @@ svr.set_expect_100_continue_handler([](const Request &req, Response &res) {
 ### Keep-Alive connection
 
 ```cpp
-svr.set_keep_alive_max_count(2); // Default is 100
+svr.set_keep_alive_max_count(2); // Default is 100, 0 for no limit
 svr.set_keep_alive_timeout(10);  // Default is 5
 ```
 
@@ -821,14 +924,18 @@ svr.set_read_timeout(std::chrono::seconds(5));
 svr.set_keep_alive_timeout(std::chrono::seconds(10));
 ```
 
+The read timeout bounds the request line and headers as a whole, and each read of a request body.
+
 ### Set maximum payload length for reading a request body
 
 ```c++
 svr.set_payload_max_length(1024 * 1024 * 512); // 512MB
 ```
 
+The default is `CPPHTTPLIB_PAYLOAD_MAX_LENGTH` (100MB), and `0` means no limit. A request with a larger body gets `413 Payload Too Large`.
+
 > [!NOTE]
-> When the request body content type is 'www-form-urlencoded', the actual payload length shouldn't exceed `CPPHTTPLIB_FORM_URL_ENCODED_PAYLOAD_MAX_LENGTH`.
+> When the request body content type is `application/x-www-form-urlencoded`, the body must not exceed `CPPHTTPLIB_FORM_URL_ENCODED_PAYLOAD_MAX_LENGTH` (8192 bytes by default, `0` for no limit). A larger one gets `413 Payload Too Large`.
 
 ### Server-Sent Events
 
@@ -838,7 +945,9 @@ 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 a new task arrives and the queued tasks outnumber the idle threads, 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`.
+
+A connection holds its thread while it is served: between requests up to the keep-alive timeout, through a request body sent slowly but within the read timeout, and for the whole life of a WebSocket. Enough of them leave no thread for anyone else, so in front of untrusted clients, put a reverse proxy that limits connections per client, and reject unwanted WebSocket upgrades in the pre-request handler.
 
 If you want to set the thread counts at runtime:
 
@@ -909,7 +1018,7 @@ int main(void)
   httplib::Client cli("localhost", 1234);
 
   if (auto res = cli.Get("/hi")) {
-    if (res->status == StatusCode::OK_200) {
+    if (res->status == httplib::StatusCode::OK_200) {
       std::cout << res->body << std::endl;
     }
   } else {
@@ -972,6 +1081,8 @@ enum class Error {
   HTTPParsing,
   InvalidRangeHeader,
   UnsupportedContentEncoding,
+  WebSocketHandshake,
+  UserCallbackException,
 };
 ```
 
@@ -1020,6 +1131,8 @@ cli.set_error_logger([](const httplib::Error& err, const httplib::Request* req)
 });
 ```
 
+Each failed request is reported once, with the request you made, also when it failed on a redirect or was a stream that failed to open (`open_stream()`, `stream::Get()`).
+
 ### GET with HTTP headers
 
 ```c++
@@ -1044,6 +1157,8 @@ cli.set_default_headers({
 auto res = cli.Get("/hi");
 ```
 
+A `Content-Length` among these headers is sent in place of the one the library would send, so it has to match the body as written. A `Transfer-Encoding` is sent in addition to the library's own framing, so leave it out. Leave both out when passing on the headers of another message, as a proxy does.
+
 ### POST
 
 ```c++
@@ -1137,7 +1252,7 @@ cli.set_connection_timeout(0, 300000); // 300 milliseconds
 cli.set_read_timeout(5, 0); // 5 seconds
 cli.set_write_timeout(5, 0); // 5 seconds
 
-// This method works the same as curl's `--max-time` option
+// A deadline for the whole request (see below)
 cli.set_max_timeout(5000); // 5 seconds
 
 // std::chrono is also supported
@@ -1147,12 +1262,16 @@ cli.set_write_timeout(std::chrono::seconds(5));
 cli.set_max_timeout(std::chrono::seconds(5));
 ```
 
+`set_max_timeout()` is similar to curl's `--max-time` option, but the deadline only shortens the waits for reading the response. Connecting and writing are bounded by the connection and write timeouts.
+
 ### Set maximum payload length for reading a response body
 
 ```c++
 cli.set_payload_max_length(1024 * 1024 * 512); // 512MB
 ```
 
+A response body over the limit, also once decompressed, fails the request with `Error::ExceedMaxPayloadSize`.
+
 ### Receive content with a content receiver
 
 ```c++
@@ -1171,8 +1290,8 @@ std::string body;
 auto res = cli.Get(
   "/stream", Headers(),
   [&](const Response &response) {
-    EXPECT_EQ(StatusCode::OK_200, response.status);
+    // return 'false' if you want to cancel the request.
-    return true; // return 'false' if you want to cancel the request.
+    return response.status == StatusCode::OK_200;
   },
   [&](const char *data, size_t data_length) {
     body.append(data, data_length);
@@ -1187,13 +1306,15 @@ 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.
   },
   "text/plain");
 ```
 
+As on the server, write at most `length` bytes per call. The request fails with `Error::Write` if a call writes more, returns `true` without writing anything, or calls `sink.done()` before the whole content length is written.
+
 ### Chunked transfer encoding
 
 ```cpp
@@ -1240,7 +1361,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 +1379,14 @@ 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.
+
+When the proxy refuses the `CONNECT` of an HTTPS request, the request fails with `Error::ProxyConnection`. Only a `407 Proxy Authentication Required` comes back as the response, since any other answer from the proxy could be taken for the origin's.
 
 #### 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.
@@ -1271,6 +1394,10 @@ Hostname matching is case-insensitive with a dot-boundary rule. See the
 [NO_PROXY cookbook](https://yhirose.github.io/cpp-httplib/en/cookbook/c16-proxy)
 for details and for reading the variable from the environment.
 
+`set_proxy()`, `set_proxy_basic_auth()`, `set_proxy_bearer_token_auth()`,
+`set_proxy_digest_auth()` and `set_no_proxy()` are also available on
+`httplib::ws::WebSocketClient`.
+
 ### Range
 
 ```cpp
@@ -1316,10 +1443,16 @@ res = cli.Get("/");
 res->status; // 200
 ```
 
+A URL with userinfo (`http://user:pass@host/`) is not supported, neither for a `Client` nor in a `Location`; use `set_basic_auth()` for the credentials. A `Client` constructed from a URL it cannot use, such as one with userinfo, a backslash in the authority or an invalid port, is not valid: `is_valid()` returns `false`, and every request fails with `Error::Connection`.
+
+On a redirect to another origin (a different scheme, host or port), `Authorization`, `Cookie` and `Proxy-Authorization` are dropped along with the credentials set with `set_basic_auth()`, `set_bearer_token_auth()` and `set_digest_auth()`, and the client certificate is not presented. Other headers, the default ones included, go along (RFC 9110 §15.4), and so do the timeouts, the payload limit and the TLS verification settings. A `303` that turns a request into a `GET` drops its headers and body; only on the same origin are the default headers sent again.
+
+Up to `CPPHTTPLIB_REDIRECT_MAX_COUNT` (20 by default) redirects are followed for a request; one more fails it with `Error::ExceedRedirectCount`. Interim `1xx` responses before the final response are skipped, up to `CPPHTTPLIB_INTERIM_RESPONSE_MAX_COUNT` (100 by default); one more fails the request with `Error::Read`.
+
 ### Use a specific network interface
 
 > [!NOTE]
-> This feature is not available on Windows, yet.
+> This feature is not available on Windows, Android, AIX and z/OS. The setting is ignored there.
 
 ```cpp
 cli.set_interface("eth0"); // Interface name, IP address or host name
@@ -1368,13 +1501,15 @@ auto res = cli.Get("/path with spaces/file.txt"); // Automatically encodes space
 
 // Disable automatic path encoding
 cli.set_path_encode(false);
-auto res = cli.Get("/already%20encoded/path"); // Use pre-encoded paths
+res = cli.Get("/already%20encoded/path"); // Use pre-encoded paths
 ```
 
 - `set_path_encode(bool on)` - Controls automatic encoding of special characters in URL paths
   - `true` (default): Automatically encodes spaces, plus signs, newlines, and other special characters
   - `false`: Sends paths as-is without encoding (useful for pre-encoded URLs)
 
+A fragment (`#...`) in the path is never sent, whatever the setting.
+
 ### Performance Note for Local Connections
 
 > [!WARNING]
@@ -1408,8 +1543,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 +1554,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. The [Stream API](#stream-api) is limited either way.
 
 ## Compression
 
@@ -1428,10 +1563,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
 
@@ -1449,14 +1628,14 @@ Please see https://github.com/facebook/zstd for more detail.
 
 ### Default `Accept-Encoding` value
 
-The default `Accept-Encoding` value contains all possible compression types. So, the following two examples are same.
+The default `Accept-Encoding` value lists the compression types the library is built with. It is not added to a request made with a content receiver. So, with Brotli, zlib and Zstd support all enabled, the following two examples are the same.
 
 ```c++
 res = cli.Get("/resource/foo");
 res = cli.Get("/resource/foo", httplib::Headers{{"Accept-Encoding", "br, gzip, deflate, zstd"}});
 ```
 
-If we don't want a response without compression, we have to set `Accept-Encoding` to an empty string. This behavior is similar to curl.
+If we want a response without compression, we have to set `Accept-Encoding` to an empty string. This behavior is similar to curl.
 
 ```c++
 res = cli.Get("/resource/foo", httplib::Headers{{"Accept-Encoding", ""}});
@@ -1469,7 +1648,7 @@ cli.set_compress(true);
 res = cli.Post("/resource/foo", "...", "text/plain");
 ```
 
-### Compress response body on client
+### Keep response body compressed on client
 
 ```c++
 cli.set_decompress(false);
@@ -1481,7 +1660,6 @@ res->body; // Compressed data
 Unix Domain Socket Support
 --------------------------
 
-Unix Domain Socket support is available on Linux and macOS.
 
 ```c++
 // Server
@@ -1495,7 +1673,7 @@ cli.set_address_family(AF_UNIX);
 
 "my-socket.sock" can be a relative path or an absolute path. Your application must have the appropriate permissions for the path. You can also use an abstract socket address on Linux. To use an abstract socket address, prepend a null byte ('\x00') to the path.
 
-This library automatically sets the Host header to "localhost" for Unix socket connections, similar to curl's behavior:
+This library automatically sets the Host header to "localhost" for Unix socket connections, similar to curl's behavior.
 
 
 URI Encoding/Decoding Utilities
@@ -1518,8 +1696,8 @@ std::string decoded_component = httplib::decode_uri_component(encoded_component)
 ### Functions
 
 - `encode_uri(const std::string &value)` - Encodes a full URI, preserving reserved characters like `://`, `?`, `&`, `=`
-- `decode_uri(const std::string &value)` - Decodes a URI-encoded string
+- `decode_uri(const std::string &value)` - Decodes a URI-encoded string, but leaves escapes of the reserved characters that `encode_uri()` preserves (e.g. `%2F`, `%3F`) as they are, like JavaScript's `decodeURI()`
-- `encode_uri_component(const std::string &value)` - Encodes a URI component (query parameter, path segment), encoding all reserved characters
+- `encode_uri_component(const std::string &value)` - Encodes a URI component (query parameter, path segment), encoding all reserved characters except `!`, `*`, `'`, `(` and `)`, like JavaScript's `encodeURIComponent()`
 - `decode_uri_component(const std::string &value)` - Decodes a URI component
 
 Use `encode_uri()` for full URLs and `encode_uri_component()` for individual query parameters or path segments.
@@ -1530,7 +1708,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");
@@ -1549,6 +1726,8 @@ if (result2) {
 
 All HTTP methods are supported: `stream::Get`, `Post`, `Put`, `Patch`, `Delete`, `Head`, `Options`.
 
+Unlike a content receiver, the Stream API is bounded by the client's `set_payload_max_length()` (100MB by default). Reading past it stops with `read_error() == Error::ExceedMaxPayloadSize`.
+
 See [README-stream.md](README-stream.md) for more details.
 
 ## SSE Client
@@ -1610,7 +1789,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 +1798,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 +1834,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 +1846,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,20 +1860,16 @@ 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
 > ```
+>
+> The limit is no guarantee on a thread with a small stack, such as one of musl's 128KB threads, where a pattern like `(\w|-)+` can already overflow on a shorter path; lower the limit there. Nor does it bound the time a pattern with nested repetition, such as `((\w+-?)+)`, can take to fail on a few dozen characters. Keep regex routes simple.
 
 ### 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.62.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/c03-default-headers.md

@@ -50,6 +50,6 @@ httplib::Headers headers = {
 auto res = cli.Get("/users", headers);
 ```
 
-Per-request headers are **added** on top of the defaults. Both are sent to the server.
+Per-request headers are **added** on top of the defaults, and both are sent to the server. If a per-request header has the same name as a default one, only the per-request one is sent.
 
 > For details on Bearer token auth, see [C06. Call an API with a Bearer token](../c06-bearer-token).

docs-src/pages/en/cookbook/c04-follow-location.md

@@ -33,6 +33,8 @@ auto res = cli.Get("/");
 
 Many sites redirect HTTP traffic to HTTPS. With `set_follow_location(true)` on, this case is handled transparently — the client follows redirects even when the scheme or host changes.
 
+When a redirect goes to another origin (a different scheme, host, or port), the client drops the `Authorization`, `Cookie`, and `Proxy-Authorization` headers, along with the credentials set with `set_basic_auth()` and the like, and doesn't present the client certificate. Other headers, default ones included, go along, and so do the timeouts, the payload limit, and the TLS verification settings.
+
 > **Warning:** To follow redirects to HTTPS, you need to build cpp-httplib with OpenSSL (or another TLS backend). Without TLS support, redirects to HTTPS will fail.
 
 > **Note:** Following redirects adds to the total request time. See [C12. Set timeouts](../c12-timeouts) for timeout configuration.

docs-src/pages/en/cookbook/c08-post-file-body.md

@@ -12,7 +12,7 @@ Sometimes you want to send a file's contents as the request body directly — no
 httplib::Client cli("https://storage.example.com");
 
 auto [size, provider] = httplib::make_file_body("backup.tar.gz");
-if (size == 0) {
+if (!provider) {
   std::cerr << "Failed to open file" << std::endl;
   return 1;
 }
@@ -27,7 +27,7 @@ The `ContentProvider` reads the file in chunks, so even huge files never sit ful
 
 ## When the file can't be opened
 
-If the file can't be opened, `make_file_body()` returns `size` as `0` and `provider` as an empty function object. Sending that would produce garbage — always check `size` first.
+If the file can't be opened, `make_file_body()` returns `size` as `0` and `provider` as an empty function object. Sending that would upload an empty body — always check `provider` first. Checking `size` won't do: an empty file also gives `0`, with a working `provider`.
 
 > **Warning:** `make_file_body()` needs to fix the Content-Length up front, so it reads the file size ahead of time. If the file size might change mid-upload, this API isn't the right fit.
 

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/c12-timeouts.md

@@ -12,6 +12,8 @@ The client has three kinds of timeouts, each set independently.
 | Read | `set_read_timeout` | 300s | Time to wait for a single `recv` when receiving the response |
 | Write | `set_write_timeout` | 5s | Time to wait for a single `send` when sending the request |
 
+Over HTTPS, the connection timeout also bounds the whole TLS handshake. A handshake that doesn't finish in time fails with `Error::SSLConnection`.
+
 ## Basic usage
 
 ```cpp

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

@@ -4,7 +4,7 @@ order: 13
 status: "draft"
 ---
 
-The three timeouts from [C12. Set timeouts](../c12-timeouts) all apply to a single `send` or `recv` call. To cap the total time a request can take, use `set_max_timeout()`.
+The three timeouts from [C12. Set timeouts](../c12-timeouts) each cover only one step: the read and write timeouts apply to a single `recv` or `send` call, and the connection timeout to connecting. To cap the total time a request can take, use `set_max_timeout()`.
 
 ## Basic usage
 
@@ -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, PUT, or PATCH 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

@@ -17,6 +17,8 @@ auto res = cli.Get("/users");
 
 The request goes through the proxy. For HTTPS, the client uses the CONNECT method to tunnel through — no extra setup required.
 
+If the proxy refuses the tunnel, the request fails with `Error::ProxyConnection`. The exception is a 407: it comes back as the response, so `res` is truthy and `res->status` is 407, while `res.error()` still returns `Error::ProxyConnection`.
+
 ## Proxy authentication
 
 If the proxy itself requires authentication, use `set_proxy_basic_auth()` or `set_proxy_bearer_token_auth()`.
@@ -55,7 +57,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:
@@ -69,6 +71,20 @@ Hostname matching is case-insensitive and uses a dot-boundary rule, so an entry
 
 Malformed entries are silently dropped. Port-specific entries such as `example.com:8080` are not supported (cpp-httplib's other host-keyed APIs are also keyed on hostname only).
 
+## Use a proxy for WebSocket
+
+`ws::WebSocketClient` has the same proxy setters.
+
+```cpp
+httplib::ws::WebSocketClient cli("wss://ws.example.com/chat");
+cli.set_proxy("proxy.internal", 8080);
+cli.set_proxy_basic_auth("user", "password");
+
+auto res = cli.connect();
+```
+
+For both `ws://` and `wss://`, the client opens a tunnel with the CONNECT method and then performs the WebSocket handshake through it. `set_no_proxy()` works the same way.
+
 ## Read proxy settings from the environment
 
 cpp-httplib doesn't touch `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` on its own — the config API is always explicit, the same way `set_ca_cert_path()` is. If you'd like that behavior, read the variables in your application and feed them to `set_proxy()` and `set_no_proxy()`.

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

@@ -4,7 +4,7 @@ order: 17
 status: "draft"
 ---
 
-`cli.Get()`, `cli.Post()`, and friends return a `Result`. When the request fails — can't reach the server, times out, etc. — the result is "falsy". To get the specific reason, use `Result::error()`.
+`cli.Get()`, `cli.Post()`, and friends return a `Result`. When the request fails — can't reach the server, times out, etc. — the result is "falsy", with one exception noted in the table below. To get the specific reason, use `Result::error()`.
 
 ## Basic check
 
@@ -27,14 +27,16 @@ Use `if (res)` to check success. On failure, `res.error()` returns a `httplib::E
 
 | Value | Meaning |
 | --- | --- |
-| `Error::Connection` | Couldn't connect to the server |
+| `Error::Connection` | Couldn't connect to the server, or the `Client` was built from a URL it can't use (userinfo or a backslash in the authority, a bad port). In the latter case `cli.is_valid()` is `false` |
 | `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::ExceedMaxPayloadSize` | The response body is larger than `set_payload_max_length()` allows, also once decompressed |
+| `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 |
-| `Error::Canceled` | A progress callback returned `false` |
+| `Error::ProxyConnection` | The proxy refused the CONNECT tunnel. A 407 is the exception: `res` is truthy with `res->status == 407`, and `res.error()` is still `Error::ProxyConnection` |
+| `Error::Canceled` | A progress callback, a `ContentReceiver`, a `ResponseHandler`, or an upload content provider returned `false` |
 
 ## Network errors vs. HTTP errors
 

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

@@ -17,26 +17,34 @@ if (!res) {
   std::cerr << "error: " << httplib::to_string(err) << std::endl;
 
   if (err == httplib::Error::SSLConnection ||
-      err == httplib::Error::SSLServerVerification) {
+      err == httplib::Error::SSLServerVerification ||
+      err == httplib::Error::Read || err == httplib::Error::Write) {
     std::cerr << "ssl_error: " << res.ssl_error() << std::endl;
     std::cerr << "ssl_backend_error: " << res.ssl_backend_error() << std::endl;
   }
 }
 ```
 
-`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 or a later read or write failed, and the verify result (`X509_V_ERR_*`) when certificate verification failed.
+
+A request that fails after the handshake reports `Error::Read` or `Error::Write`. Even then, `ssl_error()` and `ssl_backend_error()` carry the TLS error behind it. For example, if the server requires a client certificate you didn't send, OpenSSL's error reads "tlsv13 alert certificate required". Both values are reset for each request and are `0` when no TLS error was involved.
 
 ## 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/c19-client-logger.md

@@ -35,7 +35,7 @@ cli.set_error_logger([](const httplib::Error &err, const httplib::Request *req)
 });
 ```
 
-The second argument `req` can be null — it happens when the failure occurred before the request was built. Always null-check before dereferencing.
+Each failed request is reported once, with the request you made, also when it failed on a redirect. A stream that fails to open with `open_stream()` or `stream::Get()` is reported the same way; errors while reading its body come back through `read_error()` instead. `req` is null only in a server's error logger, for errors that belong to no request.
 
 ## Use both together
 

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,9 @@ 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. It stops after a 204, 403, or 404 response, or once the attempts set with `set_max_reconnect_attempts()` run out.
+
+It also stops when an event, or a line still waiting for its end, grows past `CPPHTTPLIB_SSE_MAX_EVENT_LENGTH` (16MB by default, 0 for no limit). The error handler then gets `Error::ExceedMaxPayloadSize`. The client's `set_payload_max_length()` doesn't apply to the stream as a whole, since an event stream has no end.
 
 ## Run asynchronously
 
@@ -88,6 +90,8 @@ If the server sends a `retry:` field, that takes precedence.
 
 `SSEClient` tracks the `id` of each received event internally and sends it back as `Last-Event-ID` on reconnect. As long as the server sends events with `id:`, this all works automatically.
 
+An empty `id:` clears the stored id. An `id:` that can't be sent as a header value (one with NUL or other control characters, or with leading or trailing whitespace) is ignored, and the previous id stays.
+
 ```cpp
 std::cout << "last id: " << sse.last_event_id() << std::endl;
 ```

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/s03-path-params.md

@@ -44,6 +44,8 @@ svr.Get(R"(/users/(\d+))", [](const httplib::Request &req, httplib::Response &re
 
 Parentheses in the pattern become captures in `req.matches`. `req.matches[0]` is the full match; `req.matches[1]` onward are the captures.
 
+A regex route isn't applied to a path longer than `CPPHTTPLIB_REGEX_ROUTE_PATH_MAX_LENGTH` (256 by default); such a path is treated as no match. This keeps `std::regex` from overflowing the stack on long input. If your routes need longer paths, define the macro with a larger value.
+
 ## Which to use
 
 - For plain IDs or slugs, `:name` is enough — readable, and the shape is obvious

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

@@ -10,12 +10,19 @@ To serve static files like HTML, CSS, and images, use `set_mount_point()`. Just
 
 ```cpp
 httplib::Server svr;
-svr.set_mount_point("/", "./public");
+if (!svr.set_mount_point("/", "./public")) {
+  // ./public doesn't exist
+  return 1;
+}
 svr.listen("0.0.0.0", 8080);
 ```
 
+`set_mount_point()` returns `false` when the directory doesn't exist, so check the return value.
+
 `./public/index.html` is now reachable at `http://localhost:8080/index.html`, and `./public/css/style.css` at `http://localhost:8080/css/style.css`. The directory layout maps directly to URLs.
 
+A request for a directory serves its `index.html`, and one without the trailing slash (`/docs`) is redirected (301) to `/docs/`. A symlink that resolves outside the mounted directory gets a 403.
+
 ## Multiple mount points
 
 You can register more than one mount point.
@@ -30,7 +37,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

@@ -48,24 +48,64 @@ svr.Post("/upload",
      const httplib::ContentReader &content_reader) {
     std::ofstream ofs;
 
-    content_reader(
+    auto ok = content_reader(
       [&](const httplib::FormData &file) {
-        if (!file.filename.empty()) {
+        if (ofs.is_open()) { ofs.close(); }         // done with the previous file
-          ofs.open("uploads/" + file.filename, std::ios::binary);
+        if (file.filename.empty()) { return true; } // a plain field, skip it
-        }
+
-        return static_cast<bool>(ofs);
+        auto name = httplib::sanitize_filename(file.filename);
+        if (name.empty()) { return false; }         // reject an unsafe name
+
+        ofs.open("uploads/" + name, std::ios::binary);
+        return ofs.is_open();
       },
       [&](const char *data, size_t len) {
+        if (!ofs.is_open()) { return true; }        // not part of a file
         ofs.write(data, len);
         return static_cast<bool>(ofs);
       });
 
+    if (!ok) { return; } // the status is already set
     res.set_content("uploaded", "text/plain");
   });
 ```
 
+The header callback runs at the start of every part, so it closes the previous file before opening the next one. `file.filename` is whatever the client sent, so always pass it through `httplib::sanitize_filename()`. An empty result means the name is unsafe.
+
 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/s09-pre-routing.md

@@ -16,7 +16,7 @@ svr.set_pre_routing_handler(
   });
 ```
 
-The pre-routing handler runs **before routing**. It catches every request — including ones that don't match any handler.
+The pre-routing handler runs **before routing**. It catches every request — including ones that don't match any handler. The exception is a request rejected while its request line and headers are parsed (400 for a malformed request, 414 for an overlong URI, 416 for a malformed `Range`); the server answers those before this handler runs.
 
 The `HandlerResponse` return value is key:
 

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

@@ -38,6 +38,8 @@ svr.Options("/.*", [](const auto &req, auto &res) {
 });
 ```
 
+`/.*` is a regex route, so it isn't applied to paths longer than `CPPHTTPLIB_REGEX_ROUTE_PATH_MAX_LENGTH` (256 by default). If your paths can be longer, handle `OPTIONS` in the pre-routing handler instead.
+
 ## Bundle your security headers
 
 Manage browser security headers in one spot.

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

@@ -17,6 +17,8 @@ In a pre-request handler, `req.matched_route` holds the **pattern string** that
 
 Because the body has not been read when the pre-request handler runs, you can reject a request — for example on a failed auth check — without consuming a (potentially large) request body. Note that this also means `req.body` and form fields parsed from the body are not available here; inspect headers, the path, query parameters, or `req.matched_route` instead.
 
+The pre-request handler runs only for requests that match a route. Files served by `set_mount_point()` are answered before route matching, so guard static files in the pre-routing handler.
+
 ## Switch auth per route
 
 ```cpp
@@ -37,6 +39,10 @@ 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.
+
+The server accepts a handshake from any `Origin`. A browser sends its cookies even with a handshake that another site starts, so if cookies authenticate the connection, also check `req.get_header_value("Origin")` against your own origins here.
+
 ## 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/s13-error-handler.md

@@ -4,7 +4,7 @@ order: 32
 status: "draft"
 ---
 
-To customize the response for 4xx or 5xx errors, use `set_error_handler()`. You can replace the plain default error page with your own HTML or JSON.
+To customize the response for 4xx or 5xx errors, use `set_error_handler()`. By default, an error response has an empty body; an error handler lets you fill it with your own HTML or JSON.
 
 ## Basic usage
 

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

@@ -4,7 +4,7 @@ order: 34
 status: "draft"
 ---
 
-To log the requests the server receives and the responses it returns, use `Server::set_logger()`. The callback fires once per completed request, making it the foundation for access logs and metrics collection.
+To log the requests the server receives and the responses it returns, use `Server::set_logger()`. The callback fires once per request, right before the response is written, making it the foundation for access logs and metrics collection.
 
 ## Basic usage
 
@@ -18,6 +18,8 @@ svr.set_logger([](const httplib::Request &req, const httplib::Response &res) {
 
 The log callback receives both the `Request` and the `Response`. You can grab the method, path, status, client IP, headers, body — whatever you need.
 
+`req.path` is percent-decoded, so it may contain control characters such as CR/LF. Escape it before writing it to a log file, or a crafted request can forge log lines.
+
 ## Access-log style format
 
 Here's an Apache/Nginx-ish access log format.
@@ -38,6 +40,8 @@ svr.set_logger([](const auto &req, const auto &res) {
 });
 ```
 
+For a response sent through a content provider, such as a file served from a mount point, `res.body` is empty here, so the size shows `0B`.
+
 ## Measure request time
 
 To include request duration in the log, stash a start timestamp in `res.user_data` from a pre-routing handler, then subtract in the logger.
@@ -48,7 +52,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>(
@@ -59,6 +63,8 @@ svr.set_logger([](const auto &req, const auto &res) {
 });
 ```
 
+Since the logger runs before the response is written, the time doesn't include sending the body.
+
 For more on `user_data`, see [S12. Pass data between handlers with `res.user_data`](../s12-user-data).
 
-> **Note:** The logger runs synchronously on the same thread as request processing. Heavy work inside it hurts throughput — push it to a queue and process asynchronously if you need anything expensive.
+> **Note:** The logger runs synchronously on the same thread as request processing, and all logger calls on a server share one lock. Heavy work inside it hurts throughput — push it to a queue and process asynchronously if you need anything expensive.

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,8 @@ 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.
+
+> **Note:** `stop()` doesn't interrupt WebSocket handlers. A handler looping on `read()` keeps running as long as its peer stays connected, and `listen()` doesn't return until it ends. Keep track of open WebSocket connections and `close()` them on shutdown, e.g. with `CloseStatus::GoingAway`.

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

@@ -10,7 +10,7 @@ status: "draft"
 
 | API | Default | Meaning |
 | --- | --- | --- |
-| `set_keep_alive_max_count` | 100 | Max requests served over a single connection |
+| `set_keep_alive_max_count` | 100 | Max requests served over a single connection (0 for no limit) |
 | `set_keep_alive_timeout` | 5s | How long an idle connection is kept before closing |
 
 ## Basic usage
@@ -52,6 +52,6 @@ Set `set_keep_alive_max_count(1)` and every request gets its own connection. Mos
 
 ## Relationship with the thread pool
 
-A Keep-Alive connection holds a worker thread for its entire lifetime. If `connections × concurrent requests` exceeds the thread pool size, new requests wait. For thread counts, see [S21. Configure the thread pool](../s21-thread-pool).
+A Keep-Alive connection holds a worker thread for its entire lifetime. The pool adds threads under load, up to its maximum thread count (4× the base count by default). If open connections outnumber that maximum, new connections wait in the queue until one closes. For thread counts, see [S21. Configure the thread pool](../s21-thread-pool).
 
 > **Note:** For the client side, see [C14. Understand connection reuse and Keep-Alive behavior](../c14-keep-alive). Even when the server closes the connection on timeout, the client reconnects automatically.

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

@@ -66,4 +66,4 @@ You can set the defaults with macros if you want compile-time configuration.
 #include <httplib.h>
 ```
 
-> **Note:** A WebSocket connection holds a worker thread for its entire lifetime. For lots of simultaneous WebSocket connections, enable dynamic scaling (e.g. `ThreadPool(8, 64)`).
+> **Note:** A WebSocket connection holds a worker thread for its entire lifetime. For lots of simultaneous WebSocket connections, raise the maximum thread count (e.g. `ThreadPool(8, 64)`).

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"
 ---
 
@@ -46,4 +46,4 @@ Certificate verification control, standing up an SSLServer, reading the peer cer
 - [T03. Start an SSL/TLS server](../t03-ssl-server)
 - [T05. Access the peer certificate on the server](../t05-peer-cert)
 
-> **Note:** On macOS with an OpenSSL-family backend, cpp-httplib automatically loads root certificates from the system keychain (via `CPPHTTPLIB_USE_CERTS_FROM_MACOSX_KEYCHAIN`, on by default). To disable this, define `CPPHTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES`.
+> **Note:** On macOS, with any of the three backends, cpp-httplib automatically loads root certificates from the system keychain (via `CPPHTTPLIB_USE_CERTS_FROM_MACOSX_KEYCHAIN`, on by default). To disable this, define `CPPHTTPLIB_DISABLE_MACOSX_AUTOMATIC_ROOT_CERTIFICATES`.

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"
 ---
 
@@ -19,6 +19,8 @@ auto res = cli.Get("/");
 
 The first argument is the CA certificate file; the second is an optional CA directory. With the OpenSSL backend, you can also pass an `X509_STORE*` directly via `set_ca_cert_store()`.
 
+Once you set a custom CA, the client trusts only that CA and skips the OS store. To trust both, also call `cli.enable_system_ca(true)`. CA certificates are loaded once, on the client's first connection, so make these settings before the first request.
+
 ## Disable certificate verification (not recommended)
 
 For development servers or self-signed certificates, you can skip verification entirely.
@@ -46,7 +48,7 @@ The certificate itself is still validated, so this is safer than fully disabling
 
 ## Use the OS cert store as-is
 
-On most Linux distributions, root certificates live in a single file like `/etc/ssl/certs/ca-certificates.crt`. cpp-httplib reads the OS default store at startup, so for most servers you don't need to configure anything.
+On most Linux distributions, root certificates live in a single file like `/etc/ssl/certs/ca-certificates.crt`. cpp-httplib loads the OS default store on the client's first connection, so for most servers you don't need to configure anything.
 
 > The same APIs work on the mbedTLS and wolfSSL backends. For choosing between backends, see [T01. Choosing between OpenSSL, mbedTLS, and wolfSSL](../t01-tls-backends).
 

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"
 ---
 
@@ -60,7 +60,7 @@ Before a certificate expires, you may want to swap it out without restarting the
 svr.update_certs_pem(new_cert_pem, new_key_pem);
 ```
 
-Existing connections keep using the old cert; new connections use the new one.
+Existing connections keep using the old cert; new connections use the new one. It waits for handshakes in progress to finish, at most the read timeout, and new connections wait until it returns. So don't call it from a TLS callback that runs during a handshake: it would wait for that handshake.
 
 ## Generating a test certificate
 

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"
 ---
 
@@ -44,7 +44,7 @@ for (const auto &san : sans) {
 }
 ```
 
-There's also a helper to check if a hostname is covered by the SAN list:
+There's also a helper that checks whether the certificate covers a hostname. It follows the rules of TLS hostname verification: an IP address is matched against the IP address SANs, a name against the DNS SANs, and the CN is used only when there's no DNS SAN.
 
 ```cpp
 if (cert.check_hostname("alice.corp.example.com")) {
@@ -81,7 +81,7 @@ Combined with a pre-request handler, you can keep all authorization logic in one
 
 ## SNI (Server Name Indication)
 
-cpp-httplib handles SNI automatically. If one server hosts multiple domains, SNI is used under the hood — but normally handlers don't need to care.
+Clients send SNI automatically. On the server, `req.sni()` returns the name the client asked for. `SSLServer` presents the same certificate whatever that name is, though, so to host several domains on one server, use a certificate that covers all of them. To choose a certificate per name, hook into the TLS backend yourself — with OpenSSL, for example, set a servername callback through the `SSLServer` constructor that takes a context setup callback.
 
 > **Warning:** `req.peer_cert()` only returns a meaningful value when mTLS is enabled and the client actually presented a certificate. For plain TLS, you get an empty `PeerCert`. Always do the `bool` check before using it.
 

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"
 ---
 
@@ -21,7 +21,12 @@ int main() {
       if (result == httplib::ws::ReadResult::Fail) {
         break;
       }
-      ws.send(msg); // echo back what we received
+      // echo back what we received, in the same frame type
+      if (result == httplib::ws::ReadResult::Binary) {
+        ws.send(msg.data(), msg.size());
+      } else {
+        ws.send(msg);
+      }
     }
   });
 
@@ -29,13 +34,14 @@ int main() {
 }
 ```
 
-Register a WebSocket handler with `svr.WebSocket()`. By the time the handler runs, the WebSocket handshake is already complete. Inside the loop, just `ws.read()` and `ws.send()` to get a working echo.
+Register a WebSocket handler with `svr.WebSocket()`. By the time the handler runs, the WebSocket handshake is already complete. Inside the loop, just `ws.read()` and `ws.send()` to get a working echo. A binary message goes back through the `data()` + `size()` overload so it stays binary (more on that below).
 
 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
 
@@ -75,7 +81,7 @@ The `std::string` overload sends as **text**; the `const char*` + size overload
 
 ## Thread pool implications
 
-A WebSocket handler holds its worker thread for the entire life of the connection — one connection per thread. For many concurrent clients, configure a dynamic thread pool.
+A WebSocket handler holds its worker thread for the entire life of the connection — one connection per thread. The default pool already grows under load, up to 4× its base thread count. For many concurrent clients, raise that maximum.
 
 ```cpp
 svr.new_task_queue = [] {

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"
 ---
 
@@ -43,7 +43,7 @@ The default interval is set by the build-time macro `CPPHTTPLIB_WEBSOCKET_PING_I
 
 ## What about Pong?
 
-The WebSocket protocol requires that Ping frames are answered with Pong frames. cpp-httplib responds to Pings automatically — you don't need to think about it in application code.
+The WebSocket protocol requires that Ping frames are answered with Pong frames. cpp-httplib answers Pings automatically inside `read()` — as long as your code keeps calling `read()`, you don't need to think about it.
 
 ## Picking an interval
 
@@ -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"
 ---
 
@@ -67,7 +67,7 @@ To notify in-flight clients that the server is going down, use `GoingAway`.
 ws.close(httplib::ws::CloseStatus::GoingAway, "server restarting");
 ```
 
-The client can inspect that status and decide whether to reconnect.
+On the client, `read()` just returns `Fail`; the status and reason it received aren't exposed. If the client needs to tell a restart from other closures, send it a message first (say, `ws.send("restarting")`), then call `close()`.
 
 ## Example: a tiny chat with quit
 

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;
 }
 ```
 
@@ -82,4 +85,4 @@ if (cli.read(buf) == httplib::ws::ReadResult::Binary) {
 
 You can mix text and binary in the same connection. A common pattern: JSON for control messages, binary for the actual data — you get efficient handling of metadata and payload both.
 
-> **Note:** WebSocket frames don't have an infinite size limit. For very large data, chunk it in your application code. cpp-httplib can handle a big frame in one shot, but it does load it all into memory at once.
+> **Note:** An incoming message can be at most `CPPHTTPLIB_WEBSOCKET_MAX_PAYLOAD_LENGTH` (16MB by default, 0 for no limit). A larger one makes `read()` return `Fail` and ends the connection. Within that limit, a message is held in memory whole, so for very large data, chunk it in your application code.

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"
 ---
 
@@ -26,6 +26,8 @@ if (ws.connect()) {
 
 To disable certificate verification entirely, use `enable_server_certificate_verification(false)`. For details on that behavior, see [T02. Control SSL Certificate Verification](../t02-cert-verification).
 
+`WebSocketClient` also has `set_server_certificate_verifier()` and `set_session_verifier()` for custom checks, plus the proxy setters (`set_proxy()`, `set_proxy_basic_auth()`, `set_proxy_bearer_token_auth()`, `set_proxy_digest_auth()`, `set_no_proxy()`). CA certificates are loaded on the first `connect()`, so set them before that.
+
 ## Presenting a client certificate (mTLS)
 
 `ws::WebSocketClient` has a constructor overload that takes a `PemMemory` struct, letting `wss://` connections present a client certificate.

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/index.md

@@ -9,7 +9,7 @@ When you need a quick HTTP server or client in C++, you want something that just
 
 The API uses a lambda-based design that feels natural. It runs anywhere you have a C++11 or later compiler. Windows, macOS, Linux — use whatever environment you already have.
 
-HTTPS works too. Just link OpenSSL or mbedTLS, and both server and client gain TLS support. Content-Encoding (gzip, Brotli, etc.), file uploads, and other features you actually need in real-world development are all included. WebSocket is also supported.
+HTTPS works too. Just link OpenSSL, Mbed TLS, or wolfSSL, and both server and client gain TLS support. Content-Encoding (gzip, Brotli, etc.), file uploads, and other features you actually need in real-world development are all included. WebSocket is also supported.
 
 Under the hood, it uses blocking I/O with a thread pool. It's not built for handling massive numbers of simultaneous connections. But for API servers, embedded HTTP in tools, mock servers for testing, and many other use cases, it delivers solid performance.
 

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

@@ -76,7 +76,7 @@ Defining `CPPHTTPLIB_OPENSSL_SUPPORT` enables `httplib::Client("https://...")` t
 
 ## 4.2 Defining the Model List
 
-Let's define the list of models that the app can handle. Here are four models we've verified for translation tasks.
+Let's define the list of models that the app can handle. Here are three models we've verified for translation tasks.
 
 ```cpp
 struct ModelInfo {
@@ -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

@@ -875,6 +875,7 @@ The only server-side change is the single `set_mount_point` line. Add it before
 #include <filesystem>
 #include <fstream>
 #include <iostream>
+#include <mutex>
 
 using json = nlohmann::json;
 
@@ -934,12 +935,11 @@ std::filesystem::path get_models_dir() {
 // Model download
 // -------------------------------------------------------------------------
 
-// Abort the download if progress_cb returns false
+// If progress_cb returns false, the download is aborted
 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_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;
@@ -949,12 +949,12 @@ bool download_model(const ModelInfo &model,
   if (!ofs) { return false; }
 
   auto res = cli.Get(url,
-    // content_receiver: receive chunks and write to file
+    // content_receiver: receive data chunk by chunk and write to file
     [&](const char *data, size_t len) {
       ofs.write(data, len);
       return ofs.good();
     },
-    // progress: report download progress (return false to abort)
+    // progress: report download progress (returning false aborts)
     [&, last_pct = -1](size_t current, size_t total) mutable {
       int pct = total ? (int)(current * 100 / total) : 0;
       if (pct == last_pct) return true; // Skip if same value
@@ -988,11 +988,11 @@ void signal_handler(int sig) {
 }
 
 int main() {
-  // Create model storage directory
+  // Create the model storage directory
   auto models_dir = get_models_dir();
   std::filesystem::create_directories(models_dir);
 
-  // Auto-download default model if not present
+  // Automatically download the default model if not yet present
   std::string selected_model = MODELS[0].filename;
   auto path = models_dir / selected_model;
   if (!std::filesystem::exists(path)) {
@@ -1007,10 +1007,7 @@ int main() {
     std::cout << std::endl;
   }
   auto llm = llamalib::Llama{path};
-
+  std::mutex llm_mutex; // Protect access during model switching
-  // 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
@@ -1025,6 +1022,7 @@ int main() {
 
   svr.Post("/translate",
            [&](const httplib::Request &req, httplib::Response &res) {
+    // JSON parsing and validation (see Chapter 2 for details)
     auto input = json::parse(req.body, nullptr, false);
     if (input.is_discarded()) {
       res.status = 400;
@@ -1048,6 +1046,7 @@ int main() {
                   ". Output only the translation, nothing else.\n\n" + text;
 
     try {
+      std::lock_guard<std::mutex> lock(llm_mutex);
       auto translation = llm.chat(prompt);
       res.set_content(json{{"translation", translation}}.dump(),
                       "application/json");
@@ -1057,7 +1056,7 @@ int main() {
     }
   });
 
-  // --- SSE streaming translation (Chapter 3) --------------------------------
+  // --- SSE streaming translation (Chapter 3) -------------------------------
 
   svr.Post("/translate/stream",
            [&](const httplib::Request &req, httplib::Response &res) {
@@ -1086,6 +1085,7 @@ int main() {
     res.set_chunked_content_provider(
         "text/event-stream",
         [&, prompt](size_t, httplib::DataSink &sink) {
+          std::lock_guard<std::mutex> lock(llm_mutex);
           try {
             llm.chat(prompt, [&](std::string_view token) {
               sink.os << "data: "
@@ -1103,7 +1103,7 @@ int main() {
         });
   });
 
-  // --- Model list (Chapter 4) -----------------------------------------------
+  // --- Model list (Chapter 4) ----------------------------------------------
 
   svr.Get("/models",
           [&](const httplib::Request &, httplib::Response &res) {
@@ -1122,7 +1122,7 @@ int main() {
     res.set_content(json{{"models", arr}}.dump(), "application/json");
   });
 
-  // --- Model selection (Chapter 4) ------------------------------------------
+  // --- Model selection (Chapter 4) -----------------------------------------
 
   svr.Post("/models/select",
            [&](const httplib::Request &req, httplib::Response &res) {
@@ -1148,16 +1148,16 @@ int main() {
 
     const auto &model = *it;
 
-    // Always respond with SSE (same format whether downloaded or not)
+    // Always respond with SSE (same format whether already downloaded or not)
     res.set_chunked_content_provider(
         "text/event-stream",
         [&, model](size_t, httplib::DataSink &sink) {
-          // SSE event send helper
+          // SSE event sending helper
           auto send = [&](const json &event) {
             sink.os << "data: " << event.dump() << "\n\n";
           };
 
-          // Download if not yet downloaded (report progress via SSE)
+          // Download if not yet present (report progress via SSE)
           auto path = get_models_dir() / model.filename;
           if (!std::filesystem::exists(path)) {
             bool ok = download_model(model, [&](int pct) {
@@ -1173,8 +1173,11 @@ int main() {
 
           // Load and switch to the model
           send({{"status", "loading"}});
-          llm = llamalib::Llama{path};
+          {
-          selected_model = model.filename;
+            std::lock_guard<std::mutex> lock(llm_mutex);
+            llm = llamalib::Llama{path};
+            selected_model = model.filename;
+          }
 
           send({{"status", "ready"}});
           sink.done();
@@ -1182,11 +1185,11 @@ int main() {
         });
   });
 
-  // --- Static file serving (Chapter 5) --------------------------------------
+  // --- Static file serving (Chapter 5) -------------------------------------
 
   svr.set_mount_point("/", "./public");
 
-  // Allow graceful shutdown via `Ctrl+C` (`SIGINT`) or `kill` (`SIGTERM`)
+  // Allow the server to be stopped with `Ctrl+C` (`SIGINT`) or `kill` (`SIGTERM`)
   signal(SIGINT, signal_handler);
   signal(SIGTERM, signal_handler);
 

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;
@@ -680,9 +675,10 @@ int main() {
 To summarize the changes from Chapter 5:
 
 - `#include <csignal>` replaced with `#include <thread>`, `<cpp-embedlib-httplib.h>`, `"WebAssets.h"`, `"webview/webview.h"`
-- Removed the `signal_handler` function
+- Removed the `signal_handler` function and moved `svr` into `main()`
 - `svr.set_mount_point("/", "./public")` replaced with `httplib::mount(svr, Web::FS)`
 - `svr.listen("127.0.0.1", 8080)` replaced with `bind_to_any_port` + `listen_after_bind` + WebView event loop
+- Added `setup_macos_edit_menu()` and its `<objc/objc-runtime.h>` include (macOS only)
 
 Not a single line of handler code has changed. The REST API, SSE streaming, and model management built through Chapter 5 all work as-is.
 

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
 
@@ -55,7 +59,7 @@ Compatibility with existing tools and libraries is a big design decision. We des
 
 ## 7.3 Concurrent Request Handling
 
-Our server processes requests one at a time. If another request arrives while a translation is in progress, it waits until the previous inference finishes. This is fine for a desktop app used by one person, but it becomes a problem for a server shared by multiple users.
+Our server runs inference one request at a time. If another request arrives while a translation is in progress, it waits until the previous inference finishes. This is fine for a desktop app used by one person, but it becomes a problem for a server shared by multiple users.
 
 `llama-server` handles concurrent requests through a mechanism called **slots**.
 
@@ -63,7 +67,7 @@ Our server processes requests one at a time. If another request arrives while a
 
 The key point is that tokens from each slot are not inferred **one by one in sequence**, but rather **all at once in a single batch**. GPUs excel at parallel processing, so processing two users simultaneously takes almost the same time as processing one. This is called "continuous batching."
 
-In our server, cpp-httplib's thread pool assigns one thread per request, but the inference itself runs single-threaded inside `llm.chat()`. `llama-server` consolidates this inference step into a shared batch processing loop.
+In our server, cpp-httplib's thread pool serves each connection on its own worker thread, so requests on different connections are handled concurrently. Inference, however, is serialized by `llm_mutex`, so only one `llm.chat()` runs at a time. `llama-server` consolidates this inference step into a shared batch processing loop.
 
 ## 7.4 Differences in SSE Format
 
@@ -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

@@ -21,7 +21,9 @@ if (result) {
 }
 ```
 
-You can also pass a `content_receiver` callback to `Get()`. This approach works with Keep-Alive.
+Note that `stream::Get()` reads no more of the body than the client's `set_payload_max_length()` allows, which is 100MB by default. For larger downloads, raise it, or set it to 0 for no limit.
+
+You can also pass a `content_receiver` callback to `Get()`. This approach works with Keep-Alive, and it has no size limit unless you set one with `set_payload_max_length()`.
 
 ```cpp
 httplib::Client cli("http://localhost:8080");
@@ -50,7 +52,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 +157,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 +170,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 +207,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/c03-default-headers.md

@@ -50,6 +50,6 @@ httplib::Headers headers = {
 auto res = cli.Get("/users", headers);
 ```
 
-リクエスト単位で渡したヘッダーはデフォルトヘッダーに**追加**されます。両方がサーバーに送られます。
+リクエスト単位で渡したヘッダーはデフォルトヘッダーに**追加**され、両方がサーバーに送られます。デフォルトヘッダーと同じ名前のヘッダーを渡した場合は、リクエスト単位のものだけが送られます。
 
 > Bearerトークンを使った認証の詳細は[C06. BearerトークンでAPIを呼ぶ](../c06-bearer-token)を参照してください。

docs-src/pages/ja/cookbook/c04-follow-location.md

@@ -33,6 +33,8 @@ auto res = cli.Get("/");
 
 多くのサイトはHTTPアクセスをHTTPSへリダイレクトします。`set_follow_location(true)`を有効にしておけば、こうしたケースも透過的に扱えます。スキームやホストが変わっても自動で追従します。
 
+リダイレクト先が別のオリジン（スキーム、ホスト、ポートのどれかが違う）の場合、`Authorization`、`Cookie`、`Proxy-Authorization`ヘッダーは外され、`set_basic_auth()`などで設定した認証情報も送られません。クライアント証明書も提示しません。それ以外のヘッダーはデフォルトヘッダーも含めてそのまま送られ、タイムアウト、ペイロードの上限、TLSの検証設定も引き継がれます。
+
 > **Warning:** HTTPSへのリダイレクトを追従するには、cpp-httplibをOpenSSL（または他のTLSバックエンド）付きでビルドしておく必要があります。TLSサポートがないと、HTTPSへのリダイレクトは失敗します。
 
 > **Note:** リダイレクトを追従すると、リクエストの実行時間は伸びます。タイムアウトの設定は[C12. タイムアウトを設定する](../c12-timeouts)を参照してください。

docs-src/pages/ja/cookbook/c08-post-file-body.md

@@ -12,7 +12,7 @@ status: "draft"
 httplib::Client cli("https://storage.example.com");
 
 auto [size, provider] = httplib::make_file_body("backup.tar.gz");
-if (size == 0) {
+if (!provider) {
   std::cerr << "Failed to open file" << std::endl;
   return 1;
 }
@@ -27,7 +27,7 @@ auto res = cli.Put("/bucket/backup.tar.gz", size,
 
 ## ファイルが開けなかったとき
 
-`make_file_body()`は開けなかった場合、`size`を`0`、`provider`を空の関数オブジェクトとして返します。そのまま送信するとおかしな結果になるので、必ず`size`をチェックしてください。
+`make_file_body()`は開けなかった場合、`size`を`0`、`provider`を空の関数オブジェクトとして返します。そのまま送信すると空のボディが送られてしまうので、必ず`provider`をチェックしてください。`size`では判定できません。空のファイルでも`size`は`0`になり、そのときの`provider`は正しく使えるからです。
 
 > **Warning:** `make_file_body()`はContent-Lengthを最初に確定させる必要があるため、ファイルサイズをあらかじめ取得します。送信中にファイルサイズが変わる可能性がある場合は、このAPIには向きません。
 

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/c12-timeouts.md

@@ -12,6 +12,8 @@ status: "draft"
 | 読み取りタイムアウト | `set_read_timeout` | 300秒 | レスポンスを受信する際の1回の`recv`待ち時間 |
 | 書き込みタイムアウト | `set_write_timeout` | 5秒 | リクエストを送信する際の1回の`send`待ち時間 |
 
+HTTPSでは、接続タイムアウトがTLSハンドシェイク全体の制限時間にもなります。時間内にハンドシェイクが終わらないと、`Error::SSLConnection`で失敗します。
+
 ## 基本の使い方
 
 ```cpp

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

@@ -4,7 +4,7 @@ order: 13
 status: "draft"
 ---
 
-[C12. タイムアウトを設定する](../c12-timeouts)で紹介した3種類のタイムアウトは、いずれも「1回の`send`や`recv`」に対するものです。リクエスト全体の所要時間に上限を設けたい場合は、`set_max_timeout()`を使います。
+[C12. タイムアウトを設定する](../c12-timeouts)で紹介した3種類のタイムアウトは、どれも一部の待ち時間にしか効きません。読み取りと書き込みのタイムアウトは「1回の`recv`や`send`」に、接続タイムアウトは接続の確立に対するものです。リクエスト全体の所要時間に上限を設けたい場合は、`set_max_timeout()`を使います。
 
 ## 基本の使い方
 
@@ -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、PATCHのリクエストボディが圧縮されて送信されます。圧縮方式は、ビルドで有効にしたもののうち、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

@@ -17,6 +17,8 @@ auto res = cli.Get("/users");
 
 プロキシ経由でリクエストが送られます。HTTPSの場合はCONNECTメソッドでトンネルが張られるので、cpp-httplib側で特別な設定は要りません。
 
+プロキシがトンネルを拒否すると、リクエストは`Error::ProxyConnection`で失敗します。ただし407だけは例外で、レスポンスとして返ってきます。`res`はtruthyで`res->status`は407ですが、`res.error()`は`Error::ProxyConnection`のままです。
+
 ## プロキシに認証を設定する
 
 プロキシ自体が認証を要求する場合は、`set_proxy_basic_auth()`や`set_proxy_bearer_token_auth()`を使います。
@@ -55,7 +57,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"});
 ```
 
 エントリは次のいずれかです。
@@ -69,6 +71,20 @@ cli.set_no_proxy({"internal.corp", "10.0.0.0/8", "*.dev.local"});
 
 不正な書式のエントリは黙って捨てられます。`example.com:8080`のようなポート指定エントリはサポート外です（cpp-httplibの他のホストキーAPIもホスト名のみを扱う設計のため）。
 
+## WebSocketでもプロキシを使う
+
+`ws::WebSocketClient`にも同じプロキシ設定があります。
+
+```cpp
+httplib::ws::WebSocketClient cli("wss://ws.example.com/chat");
+cli.set_proxy("proxy.internal", 8080);
+cli.set_proxy_basic_auth("user", "password");
+
+auto res = cli.connect();
+```
+
+`ws://`でも`wss://`でも、CONNECTメソッドでトンネルを張ってからWebSocketのハンドシェイクを行います。`set_no_proxy()`も同じように使えます。
+
 ## 環境変数からプロキシ設定を読み込む
 
 cpp-httplib本体は`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`を読みません。`set_ca_cert_path()`と同じで、設定APIは常に明示的にしています。環境変数を反映させたい場合は、アプリ側で読んで`set_proxy()`や`set_no_proxy()`に渡してください。

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

@@ -4,7 +4,7 @@ order: 17
 status: "draft"
 ---
 
-`cli.Get()`や`cli.Post()`は`Result`型を返します。リクエストが失敗したとき（サーバーに到達できなかった、タイムアウトしたなど）、返り値は「falsy」になります。詳しい原因を知りたい場合は`Result::error()`を使います。
+`cli.Get()`や`cli.Post()`は`Result`型を返します。リクエストが失敗したとき（サーバーに到達できなかった、タイムアウトしたなど）、返り値は「falsy」になります（例外が1つあり、下の表で説明します）。詳しい原因を知りたい場合は`Result::error()`を使います。
 
 ## 基本の判定
 
@@ -27,18 +27,20 @@ if (res) {
 
 | 値 | 意味 |
 | --- | --- |
-| `Error::Connection` | サーバーに接続できなかった |
+| `Error::Connection` | サーバーに接続できなかった。または、使えないURL（authorityにuserinfoやバックスラッシュがある、ポートが不正など）から`Client`を作った。後者の場合は`cli.is_valid()`が`false`になる |
 | `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::ExceedMaxPayloadSize` | レスポンスボディが`set_payload_max_length()`の上限を超えた（解凍後に超えた場合も含む） |
+| `Error::Timeout` | `stream::Get()`や`SSEClient`で、ボディの読み取りがタイムアウトした |
 | `Error::ExceedRedirectCount` | リダイレクト回数が上限を超えた |
 | `Error::SSLConnection` | TLSハンドシェイクに失敗 |
 | `Error::SSLServerVerification` | サーバー証明書の検証に失敗 |
-| `Error::Canceled` | 進捗コールバックから`false`が返された |
+| `Error::ProxyConnection` | プロキシがCONNECTのトンネルを拒否した。ただし407は例外で、`res`はtruthyかつ`res->status == 407`になり、`res.error()`は`Error::ProxyConnection`のまま |
+| `Error::Canceled` | 進捗コールバック、`ContentReceiver`、`ResponseHandler`、アップロード用のコンテンツプロバイダのいずれかから`false`が返された |
 
 ## ステータスコードとの使い分け
 
-`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

@@ -17,26 +17,34 @@ if (!res) {
   std::cerr << "error: " << httplib::to_string(err) << std::endl;
 
   if (err == httplib::Error::SSLConnection ||
-      err == httplib::Error::SSLServerVerification) {
+      err == httplib::Error::SSLServerVerification ||
+      err == httplib::Error::Read || err == httplib::Error::Write) {
     std::cerr << "ssl_error: " << res.ssl_error() << std::endl;
     std::cerr << "ssl_backend_error: " << res.ssl_backend_error() << std::endl;
   }
 }
 ```
 
-`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_*`）が入ります。
+
+ハンドシェイクのあとで失敗したリクエストは、`Error::Read`や`Error::Write`を返します。その場合も、`ssl_error()`と`ssl_backend_error()`には原因となったTLSのエラーが入ります。たとえば、サーバーが要求するクライアント証明書を送らなかった場合、OpenSSLのエラーは「tlsv13 alert certificate required」になります。どちらの値もリクエストごとにリセットされ、TLSのエラーが絡んでいなければ`0`です。
 
 ## 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/c19-client-logger.md

@@ -35,7 +35,7 @@ cli.set_error_logger([](const httplib::Error &err, const httplib::Request *req)
 });
 ```
 
-第2引数の`req`はヌルポインタのこともあります。リクエストを組み立てる前の段階で失敗した場合です。使う前に必ずヌルチェックしてください。
+失敗したリクエストは、送ったリクエストと一緒に1回だけ報告されます。リダイレクト先で失敗した場合も同じです。`open_stream()`や`stream::Get()`でストリームを開くのに失敗した場合も同じように報告され、ボディを読む途中のエラーは`read_error()`で返ります。`req`がヌルポインタになるのは、どのリクエストにも属さないエラーをサーバーのエラーロガーが受け取るときだけです。
 
 ## 両方を組み合わせる
 

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,9 @@ sse.on_error([](httplib::Error err) {
 });
 ```
 
-接続確立時やエラー発生時にもフックを挟めます。エラーハンドラが呼ばれても、`SSEClient`は内部で再接続を試みます。
+接続確立時やエラー発生時にもフックを挟めます。エラーハンドラが呼ばれても、`SSEClient`は内部で再接続を試みます。ただし、サーバーが204、403、404のいずれかを返したときや、`set_max_reconnect_attempts()`で決めた回数を使い切ったときは再接続しません。
+
+また、1つのイベントや、まだ改行が来ていない行が`CPPHTTPLIB_SSE_MAX_EVENT_LENGTH`（デフォルトは16MB、0なら無制限）を超えたときも止まります。このときエラーハンドラには`Error::ExceedMaxPayloadSize`が渡されます。イベントストリームには終わりがないので、クライアントの`set_payload_max_length()`はストリーム全体には適用されません。
 
 ## 非同期で動かす
 
@@ -88,6 +90,8 @@ sse.set_max_reconnect_attempts(10);  // 10回まで（0=無制限）
 
 `SSEClient`は受信したイベントの`id`を内部で保持していて、再接続時に`Last-Event-ID`ヘッダーとして送ってくれます。この挙動はサーバー側で`id:`付きイベントを送っていれば自動で有効になります。
 
+空の`id:`を受け取ると、保持しているIDはクリアされます。ヘッダーの値として送れない`id:`（NULなどの制御文字を含むものや、前後に空白があるもの）は無視され、それまでのIDがそのまま残ります。
+
 ```cpp
 std::cout << "last id: " << sse.last_event_id() << std::endl;
 ```

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/s03-path-params.md

@@ -44,6 +44,8 @@ svr.Get(R"(/users/(\d+))", [](const httplib::Request &req, httplib::Response &re
 
 パターンに括弧を使うと、マッチした部分が`req.matches`に入ります。`req.matches[0]`はパス全体、`req.matches[1]`以降がキャプチャです。
 
+正規表現のルートは、`CPPHTTPLIB_REGEX_ROUTE_PATH_MAX_LENGTH`（デフォルトは256）より長いパスには適用されず、マッチしなかったものとして扱われます。長い入力で`std::regex`がスタックを使い果たさないための制限です。もっと長いパスを扱いたい場合は、このマクロに大きな値を定義してください。
+
 ## どちらを使うか
 
 - 単純なIDやスラッグなら`:name`でじゅうぶん。読みやすく、型が自明です

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

@@ -10,11 +10,18 @@ HTML、CSS、画像などの静的ファイルを配信したいときは、`set
 
 ```cpp
 httplib::Server svr;
-svr.set_mount_point("/", "./public");
+if (!svr.set_mount_point("/", "./public")) {
+  // ./publicが存在しない
+  return 1;
+}
 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に反映されます。
+`set_mount_point()`はディレクトリが存在しないと`false`を返すので、戻り値を確認しておきましょう。
+
+`./public/index.html`には`http://localhost:8080/index.html`で、`./public/css/style.css`には`http://localhost:8080/css/style.css`でアクセスできます。ディレクトリ構造がそのままURLに反映されます。
+
+ディレクトリへのリクエストには、その中の`index.html`を返します。末尾のスラッシュがないリクエスト（`/docs`）は、`/docs/`へリダイレクト（301）されます。マウントしたディレクトリの外を指すシンボリックリンクには403を返します。
 
 ## 複数のマウントポイント
 
@@ -26,11 +33,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 +51,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

@@ -48,24 +48,64 @@ svr.Post("/upload",
      const httplib::ContentReader &content_reader) {
     std::ofstream ofs;
 
-    content_reader(
+    auto ok = content_reader(
       [&](const httplib::FormData &file) {
-        if (!file.filename.empty()) {
+        if (ofs.is_open()) { ofs.close(); }         // 前のファイルを閉じる
-          ofs.open("uploads/" + file.filename, std::ios::binary);
+        if (file.filename.empty()) { return true; } // 普通のフィールドは読み飛ばす
-        }
+
-        return static_cast<bool>(ofs);
+        auto name = httplib::sanitize_filename(file.filename);
+        if (name.empty()) { return false; }         // 安全でない名前は拒否
+
+        ofs.open("uploads/" + name, std::ios::binary);
+        return ofs.is_open();
       },
       [&](const char *data, size_t len) {
+        if (!ofs.is_open()) { return true; }        // ファイルのパートではない
         ofs.write(data, len);
         return static_cast<bool>(ofs);
       });
 
+    if (!ok) { return; } // ステータスは設定済み
     res.set_content("uploaded", "text/plain");
   });
 ```
 
+ヘッダーのコールバックはパートごとに呼ばれるので、次のファイルを開く前に前のファイルを閉じています。`file.filename`はクライアントが送ってきた値そのままなので、必ず`httplib::sanitize_filename()`を通してください。空文字列が返ったら、安全でない名前です。
+
 メモリには常に小さなチャンクしか載らないので、ギガバイト級のファイルでも扱えます。
 
+## パート数は自分で数える
+
+`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/s09-pre-routing.md

@@ -16,7 +16,7 @@ svr.set_pre_routing_handler(
   });
 ```
 
-Pre-routingハンドラは、**ルーティングよりも前**に呼ばれます。どのハンドラにもマッチしないリクエストも含めて、すべてのリクエストを捕まえられます。
+Pre-routingハンドラは、**ルーティングよりも前**に呼ばれます。どのハンドラにもマッチしないリクエストも含めて、すべてのリクエストを捕まえられます。ただし、リクエストラインやヘッダーの解析中に拒否されたリクエスト（不正なリクエストの400、長すぎるURIの414、不正な`Range`の416）には、このハンドラが呼ばれる前にサーバーが応答します。
 
 戻り値の`HandlerResponse`がポイントです。
 

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

@@ -38,6 +38,8 @@ svr.Options("/.*", [](const auto &req, auto &res) {
 });
 ```
 
+`/.*`は正規表現のルートなので、`CPPHTTPLIB_REGEX_ROUTE_PATH_MAX_LENGTH`（デフォルトは256）より長いパスには適用されません。パスがそれより長くなりうるなら、pre-routingハンドラで`OPTIONS`を処理してください。
+
 ## セキュリティヘッダーをまとめて付ける
 
 ブラウザ向けのセキュリティヘッダーを一箇所で管理できます。

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

@@ -17,6 +17,8 @@ Pre-requestハンドラなら、`req.matched_route`に「マッチしたパタ
 
 Pre-requestハンドラが呼ばれる時点ではボディがまだ読まれていないので、認証に失敗したリクエストなどを、（巨大かもしれない）ボディを読み込む前に拒否できます。その代わり、`req.body`やボディから解析されるフォームフィールドはこの時点では参照できません。ヘッダ・パス・クエリパラメータ・`req.matched_route`を使って判断してください。
 
+Pre-requestハンドラが呼ばれるのは、ルートにマッチしたリクエストだけです。`set_mount_point()`で配信するファイルはルートのマッチングより前に返されるので、静的ファイルを守りたいときはPre-routingハンドラでチェックしてください。
+
 ## ルートごとに認証を切り替える
 
 ```cpp
@@ -37,6 +39,10 @@ svr.set_pre_request_handler(
 
 `matched_route`はパスパラメーターを展開する**前**のパターン文字列（例: `/admin/users/:id`）です。特定の値ではなく、ルート定義のパターンで判定できるので、IDや名前に左右されません。
 
+`svr.WebSocket()`で登録したルートでも、Pre-requestハンドラは呼ばれます。呼ばれるのは`101 Switching Protocols`を返す前なので、`Handled`を返すとそのHTTPレスポンス（403など）がそのまま返り、WebSocketへのアップグレードは行われません。
+
+サーバーはどの`Origin`からのハンドシェイクも受け付けます。ブラウザは別のサイトが始めたハンドシェイクにもCookieを付けて送るので、Cookieで接続を認証している場合は、`req.get_header_value("Origin")`が自分のオリジンかどうかもここで確認してください。
+
 ## 戻り値の意味
 
 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/s13-error-handler.md

@@ -4,7 +4,7 @@ order: 32
 status: "draft"
 ---
 
-404や500のような**ハンドラが返したエラーレスポンス**を加工したいときは、`set_error_handler()`を使います。デフォルトの味気ないエラーページを、独自のHTMLやJSONに差し替えられます。
+404や500のような**ハンドラが返したエラーレスポンス**を加工したいときは、`set_error_handler()`を使います。エラーレスポンスのボディはデフォルトでは空ですが、エラーハンドラで独自のHTMLやJSONを入れられます。
 
 ## 基本の使い方
 

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

@@ -4,7 +4,7 @@ order: 34
 status: "draft"
 ---
 
-サーバーが受け取ったリクエストと返したレスポンスをログに残したいときは、`Server::set_logger()`を使います。各リクエストの処理が完了するたびに呼ばれるので、アクセスログやメトリクス収集の土台になります。
+サーバーが受け取ったリクエストと返したレスポンスをログに残したいときは、`Server::set_logger()`を使います。リクエストごとに、レスポンスを書き出す直前に呼ばれるので、アクセスログやメトリクス収集の土台になります。
 
 ## 基本の使い方
 
@@ -18,6 +18,8 @@ svr.set_logger([](const httplib::Request &req, const httplib::Response &res) {
 
 ログコールバックには`Request`と`Response`が渡ります。メソッド、パス、ステータスコード、クライアントIP、ヘッダー、ボディなど、好きな情報を取り出せます。
 
+`req.path`はパーセントデコード済みなので、CR/LFのような制御文字を含むことがあります。ログファイルに書き出す前にエスケープしてください。そうしないと、細工したリクエストでログの行を偽造されてしまいます。
+
 ## アクセスログ風のフォーマット
 
 Apache / Nginxのアクセスログに似た形式で残す例です。
@@ -38,6 +40,8 @@ svr.set_logger([](const auto &req, const auto &res) {
 });
 ```
 
+マウントポイントから配信するファイルのように、コンテンツプロバイダで送るレスポンスでは、この時点の`res.body`は空なので、サイズは`0B`になります。
+
 ## 処理時間を測る
 
 ログで処理時間を出したいときは、pre-routingハンドラで開始時刻を`res.user_data`に保存しておき、ロガーで差分を取ります。
@@ -48,7 +52,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>(
@@ -59,6 +63,8 @@ svr.set_logger([](const auto &req, const auto &res) {
 });
 ```
 
+ロガーはレスポンスを書き出す前に呼ばれるので、この時間にボディの送信時間は含まれません。
+
 `user_data`の使い方は[S12. `res.user_data`でハンドラ間データを渡す](../s12-user-data)も参照してください。
 
-> **Note:** ロガーはリクエスト処理と同じスレッドで同期的に呼ばれます。重い処理を直接入れると全体のスループットが落ちるので、必要ならキューに流して非同期で処理しましょう。
+> **Note:** ロガーはリクエスト処理と同じスレッドで同期的に呼ばれ、サーバー内のすべてのロガー呼び出しが1つのロックを共有します。重い処理を直接入れると全体のスループットが落ちるので、必要ならキューに流して非同期で処理しましょう。