httpp 0.6.0__tar.gz → 0.7.0__tar.gz

{httpp-0.6.0 → httpp-0.7.0}/.github/workflows/cmake.yml

@@ -79,7 +79,7 @@ jobs:
         cmake -B build \
           -DHTTPP_BUILD_TESTS=ON \
           -DHTTPP_BUILD_PYTHON=ON \
-          -DCMAKE_CXX_FLAGS="--coverage -O0 -g" \
+          -DCMAKE_CXX_FLAGS="--coverage -fprofile-update=atomic -O0 -g" \
           -DCMAKE_EXE_LINKER_FLAGS="--coverage"
 
     - name: Build and run C++ tests

{httpp-0.6.0 → httpp-0.7.0}/.github/workflows/orchestrator.yml

@@ -67,8 +67,15 @@ jobs:
           path: dist
           merge-multiple: true
 
+      # Safety net: the publish steps need only flat *.whl / *.tar.gz files in dist/.
+      - name: Check dist layout
+        run: |
+          if find dist -mindepth 1 -type d | grep -q .; then
+            echo "::error::unexpected sub-directories in dist/"; find dist; exit 1
+          fi
+
       - name: List dist directory
-        run: tree --du -shaC .
+        run: ls -lh dist
 
       - name: create release body
         uses: softprops/action-gh-release@v3
@@ -87,3 +94,7 @@ jobs:
         with:
           password: ${{ secrets.PYPI_PASSWORD }}
           user: ${{ secrets.PYPI_USERNAME }}
+          packages-dir: dist
+          skip-existing: true
+          # attestations need Trusted Publishing; they are ignored when a password is used
+          attestations: false

httpp-0.7.0/.github/workflows/wheels.yml

@@ -0,0 +1,103 @@
+name: python build wheels
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  pull_request:
+    branches: [ master ]
+
+env:
+  FORCE_COLOR: 3
+
+concurrency:
+  group: wheels-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_sdist:
+    name: Build SDist
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        submodules: false
+
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.11"
+        cache: "pip"
+
+    - name: Build SDist
+      run: pipx run build --sdist
+
+    - name: Check metadata
+      run: pipx run twine check dist/*
+
+    - uses: actions/upload-artifact@v7
+      with:
+        name: wheelhouse-sdist
+        path: dist/*.tar.gz
+        overwrite: true
+
+  build_wheels:
+    name: Wheels on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    # A hung test used to keep this job running for the default 6 hours.
+    timeout-minutes: 90
+    strategy:
+      fail-fast: true
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        submodules: recursive
+
+    - name: Build wheels
+      uses: pypa/cibuildwheel@v4.3.1
+      env:
+        MACOSX_DEPLOYMENT_TARGET: "10.13"
+        CIBW_ARCHS_MACOS: universal2
+        # Wheel layout (one build per platform for each row):
+        #   cp39-abi3        every GIL-enabled Python from 3.9 up (the cp39-* selector;
+        #                    see py-api = "cp39" in pyproject.toml).
+        #   cp313t / cp314t  free-threaded 3.13 and 3.14: abi3 cannot be loaded by
+        #                    free-threaded builds, so each gets a version-specific
+        #                    wheel (this is where the no-GIL speed comes from).
+        #                    cp313t is built by the separate cibuildwheel 3.x step below,
+        #                    because cibuildwheel 4.x dropped 3.13 free-threading.
+        #   cp315t           free-threaded 3.15: abi3t (PEP 803, wheel.py-api =
+        #                    "cp315.cp315t" in scikit-build-core >= 1.0) would replace
+        #                    this and all later cpXXXt wheels, but it needs the PEP 793
+        #                    export hook, which released Cython versions do not generate
+        #                    yet. Until then 3.15t keeps a version-specific wheel.
+        #
+        # Free-threaded builds are enabled by default since cibuildwheel 4 (the old
+        # "cpython-freethreading" enable group no longer exists), and 3.15 is built
+        # without any prerelease flag.
+        CIBW_BUILD: "cp39-* cp314t-* cp315t-*"
+        # rpds-py (needed by jsonschema at build time) has no free-threaded wheel in its newest release; prefer an older
+        # binary over compiling the newest sdist with Rust.
+        CIBW_ENVIRONMENT: PIP_PREFER_BINARY=1
+
+    # cibuildwheel 4.x no longer supports free-threaded 3.13 (cp313t), so that one wheel
+    # comes from the 3.x series. Same wheelhouse/ folder: cibuildwheel never clears the
+    # output dir and the filenames differ by tag, so the artifact below stays flat.
+    - name: Build wheels (free-threaded 3.13)
+      uses: pypa/cibuildwheel@v3.4.1
+      env:
+        MACOSX_DEPLOYMENT_TARGET: "10.13"
+        CIBW_ARCHS_MACOS: universal2
+        CIBW_BUILD: "cp313t-*"
+        CIBW_ENABLE: cpython-freethreading
+        CIBW_ENVIRONMENT: PIP_PREFER_BINARY=1
+        CIBW_SKIP: pp*
+
+    - uses: actions/upload-artifact@v7
+      with:
+        name: wheelhouse-${{ matrix.os }}
+        # A single path keeps the artifact flat (several paths would preserve
+        # their parent folders and end up as dist/wheelhouse/... after download).
+        path: wheelhouse/*.whl
+        overwrite: false

{httpp-0.6.0 → httpp-0.7.0}/.gitmodules

@@ -4,3 +4,6 @@
 [submodule "src/third_party/liburlparser"]
 	path = src/third_party/liburlparser
 	url = https://github.com/mohammadraziei/liburlparser.git
+[submodule "src/third_party/asio"]
+	path = src/third_party/asio
+	url = https://github.com/chriskohlhoff/asio.git

httpp-0.7.0/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog
+
+All notable changes to httpp are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/) (while the major version is 0, a minor release may still change an API;
+such changes are listed under **Changed**).
+
+## [0.7.0] - 2026-10-17
+
+The biggest release so far: a native async client and server, a FastAPI-style Python layer with OpenAPI and Swagger
+UI, and a download that verifies, locks and times out.
+
+### Added
+
+#### Client
+- **Async client** (`Client.run_async()`, `AsyncClient`) running on the library's own non-blocking network thread
+  (Asio) with the vendored `llhttp` parser, instead of a shared thread pool. Keep-alive connection pooling and reuse
+  across requests, redirect handling, TLS and proxy support.
+- **Streaming responses** and **structured errors** (`httpp.errors`, with an error kind such as `timeout`) for both
+  the blocking and the async client; extra URL helpers in `httpp/url.hpp`.
+
+#### Server (C++ and Python)
+- **Async HTTP/HTTPS server** (`async_server`, with a worker pool). TLS (Mbed TLS) with session caching: TLS contexts
+  for identical (verify, CA file) settings are built once and reused.
+- **Python handlers:** route handlers with path parameters, `async def` handlers, and `listen()` that blocks and
+  returns a status (0.6.1); new in this release: `ResponseHead`, `file()`, `redirect()`, `set_cookie()`,
+  `ServerRequest.cookies`, streaming responses from generators and async generators, `@app.before_request`,
+  `@app.after_request`, error and exception handlers, startup and shutdown hooks, and `handler_timeout` (60 s by
+  default) that cancels a hanging async route and answers 504. Header values are checked against injection.
+- **OpenAPI 3.1 and Swagger UI for Python.** Schema generation with Pydantic v2 models, per-route options (`summary`,
+  `tags`, `response_model`, ...), and `Query`, `Path`, `Header`, `Cookie`, `Body` and `Depends` (dependencies with their
+  own scopes and caching) that drive both the request handling and the generated document, so the docs cannot drift
+  from the behaviour.
+- **`httpp::mount_swagger_ui(server, docs_path = "/docs", openapi_url = "/openapi.json", title = "API")`** in C++:
+  serves the page and the Swagger UI files (`swagger-ui-bundle.js`, `swagger-ui.css`, `swagger-api-icon.svg`) from
+  bytes compiled into the library, with `Cache-Control: public, max-age=86400`. Title and URL are escaped; an invalid
+  path throws `std::invalid_argument`. The Python server's `/docs` is now served from C++, without the GIL, and there
+  is no CDN or data directory involved.
+- **`cmake/EmbedFile.cmake`** (`embed_files()`): compiles data files into a header at configure time (`constexpr`
+  data in `.rodata`, binary-safe, 32 bytes per source line).
+
+#### Downloads
+- **`download::sha256(hex)` and `download::sha256_url(url = "")`**: verify the finished file against a SHA-256 digest
+  (any letter case) or against a checksum file in `sha256sum` format (default `<url>.sha256`). The checksum file is
+  fetched first, so a missing or malformed one (an HTML error page, a name for another file, several lines) fails the
+  call before any download. A mismatch deletes the file, returns `ok = false` and says what the digest actually was.
+  With `resume()`, a complete-looking but corrupt file is downloaded again once from byte 0. `download_result` has a
+  new `sha256` field.
+- **`httpp/sha256.hpp`**: `sha256_hex()`, `sha256_file()` (chunked) and `parse_sha256_checksum()`, on top of the
+  Mbed TLS already linked for HTTPS. About 165 MB/s on the machine it was measured on (130 MB file in 0.8 s).
+- **`download::set_timeout(seconds)`**: connect, read and write timeouts of the transfer (like
+  `Client::set_timeout`), and also how long to wait for another process that holds the same file's lock.
+- **`download::set_max_wait(milliseconds)`**: how long a lock that is *not being updated* is waited for before its
+  owner is taken for dead (default 2 s; the wait is `min(max_wait, timeout)`).
+- **Cross-process lock, always on.** A download takes the directory `<dest>.lock` and its owner rewrites
+  `<dest>.lock/alive` every 200 ms at most; a lock that keeps being updated is waited for as long as it lives, one that
+  stops is taken over after `min(max_wait, timeout)`. A waiter that finds the file finished and matching `sha256()` /
+  `sha256_url()` uses it without a request (`skipped = true`). If the lock directory cannot be created the download
+  goes ahead unlocked. Written with `mkdir`/`rmdir` and plain files, no `<filesystem>`.
+
+#### Library and tooling
+- **Logging** through the vendored AixLog, with a `set_log_*` API in C, C++ and Python.
+- **Python wheels:** one `cp39-abi3` wheel per platform for every GIL-enabled Python from 3.9 up, plus version-specific
+  free-threaded wheels (`cp313t`, `cp314t`, `cp315t`), because free-threaded builds cannot load abi3 wheels.
+- **Documentation:** `docs/Architecture.md` (design, goals and test strategy), `docs/agent.md`, Python micro-benchmark
+  for the validators, and README sections for streaming, files, hooks, error handling and the client's new
+  capabilities.
+
+### Changed
+- **Mbed TLS 4.2.0** (release tag), with threading support switched on (`MBEDTLS_THREADING_C`, via
+  `cmake/httpp_mbedtls_config.h`): pthread on POSIX, a small `SRWLOCK`/`CONDITION_VARIABLE` layer on Windows, or on
+  every platform with `-DHTTPP_MBEDTLS_THREADING_ALT=ON`. `MBEDTLS_SELF_TEST` is off.
+- **`HTTPP_EMBED_AS_ARRAY` is `ON` on every platform** (it was MSVC only). One code path everywhere and no
+  `-Woverlength-strings` warning for the 1.5 MB Swagger UI bundle. Cost: compiling that translation unit takes about
+  4.6 s instead of 0.9 s with GCC, once per build. `-DHTTPP_EMBED_AS_ARRAY=OFF` gives string literals again.
+- The Swagger UI tab icon is a real SVG file served at `/docs/swagger-api-icon.svg`; the PNG favicon is gone.
+- `<filesystem>` is not used any more (macOS 10.13 compatibility); `download.cpp` and the lock use `std::ifstream`,
+  `std::remove` and platform calls.
+- Asio now drives both server loops and the async client (documentation and build comments updated).
+- Build requirement: `scikit-build-core[pyproject]>=1.1`; the version is read through the standard
+  `[[tool.dynamic-metadata]]` table instead of the deprecated `tool.scikit-build.metadata`.
+- A download creates (and removes again) `<dest>.lock` next to the destination file; the destination's directory must
+  be writable for the lock to work (otherwise the download is not locked).
+
+### Fixed
+- Concurrent TLS handshakes shared Mbed TLS's global random generator without a lock; two handshakes could draw the
+  same random bytes. Found with ThreadSanitizer, fixed by the threading support above.
+- Async `after`/`error` hooks, or a slow client, could block the event loop and deadlock concurrent requests; the
+  Python adapter now dispatches synchronous work directly when no async hook is registered.
+- **Windows:** a finished download did not replace an existing file (`std::rename` fails when the target exists); it is
+  now an atomic `MoveFileExA(MOVEFILE_REPLACE_EXISTING)`. `ws2_32` is linked for `send()`/`WSAGetLastError()`, and the
+  `EmbedFile` generator no longer emits a zero-size array for an empty file (MSVC `C2466`).
+- **macOS:** link the Keychain frameworks for the C++ tests; a URL-encoding test relied on `std::isalnum` being false
+  for non-ASCII bytes.
+- Coverage builds use atomic profile counters (the server is multi-threaded, lcov saw negative counts); free-threaded
+  wheel builds prefer binary wheels so `rpds-py` is not built from source.
+- Tests for concurrent async downloads measure event-loop ticks and overlapping streams instead of wall-clock time.
+- **Release pipeline:** wheels are uploaded as one flat artifact, so `dist/` holds only `.whl` and `.tar.gz` files and
+  the PyPI upload no longer fails on a `wheelhouse` sub-directory. Windows wheels are not run through `delvewheel`
+  (`httpp_core.dll` is loaded from `httpp/lib/` at import time), and the PyPI step uses `skip-existing`.
+
+### Known limitations
+- The async client has no timeout yet, and async hooks hold a thread while they run.
+- `download::set_timeout`, `set_max_wait`, `sha256` and `sha256_url` are not exposed in the Python binding yet.
+- A lock whose owner stops updating it for more than `max_wait` (heavy load, a suspended process) is taken over, and two
+  downloads can then run at once. Two waiters taking over the same dead lock in the same instant, or writing the same
+  destination, can write it together; use `sha256()` so a damaged result is caught and deleted. Keep `max_wait`
+  at 1 s or more.
+- The Windows and macOS changes of this release were checked by CI only; the lock was not run under ThreadSanitizer.
+- `/docs` has been looked at in Chromium only.
+
+## [0.6.1] - 2026-10-03
+
+### Added
+- Python route handlers with path parameters and `async def` handlers; native async support for Python and C++
+  handlers.
+- `listen()` blocks and returns a status in the C++ and Python bindings.
+- Runnable standalone Python examples: server basics, routing, request and response handling, async handlers, static
+  files, error handling.
+
+### Changed
+- Asio 1.34.2 is a git submodule (no system dependency, better scalability).
+- README rewritten with a clearer description and structure; the Asio documentation was consolidated.
+
+### Fixed
+- Windows: winsock type redefinition and missing socket headers in the tests; a Ctrl+C listener test that cannot run
+  there (Popen) is skipped and the SIGINT test was replaced with an `interrupt_main` variant.
+
+## [0.6.0] - 2026-09-16
+
+### Added
+- Resumable downloads with skip-if-complete.
+
+### Changed
+- **Breaking:** `download_file` was renamed to `download` and folded into one fluent builder.
+
+## [0.5.1] - 2026-09-16
+
+### Added
+- `max_response_size` for the client and `follow_redirects` for downloads.
+- `abi3` wheels in CI.
+
+### Changed
+- `std::filesystem::remove` replaced by `std::remove` in downloads.
+
+## [0.5.0] - 2026-09-15
+
+### Added
+- HTTPS support through Mbed TLS (documented in the API docs).
+
+### Changed
+- Mbed TLS sources are generated before CMake configures; `jinja2` is a build dependency; submodules are no longer
+  fetched recursively by default.
+- macOS: the Keychain frameworks are linked into `httpp_core`.
+- Vendored-code warnings are suppressed and class-level exports avoided.
+- Linux wheels are repaired with `auditwheel`.
+
+## [0.4.0] - 2026-09-14
+
+### Fixed
+- Linux wheels are repaired with `auditwheel` in cibuildwheel builds.
+
+## [0.3.0] - 2026-09-14
+
+Release only; no functional change recorded in the history.
+
+## [0.2.0] - 2026-09-13
+
+### Added
+- curl-compatible API and CLI commands.
+
+## [0.1.1] - 2026-09-13
+
+### Fixed
+- Linux wheels are repaired with `auditwheel` instead of copying libraries.
+
+## [0.1.0] - 2026-09-12
+
+First release.
+
+### Added
+- C++17 core: client, server and URL parsing (`liburlparser`, IPv4, IPv6 and Public Suffix List aware).
+- Downloads with a progress bar (vendored `indicators`).
+- Python package with `httpp_core` as a shared library bundled in the wheel; macOS rpath handling.
+- CMake package: consumers find httpp through `httpp.get_cmake_dir()`; `HTTPP_BUILDING_DLL` for the shared core.
+- Single umbrella header `include/httpp.h` that carries the version, and `version.py` for tagging and releases.
+- CMake and wheels workflows in CI.
+
+[0.7.0]: https://github.com/MohammadRaziei/httpp/compare/v0.6.1...v0.7.0
+[0.6.1]: https://github.com/MohammadRaziei/httpp/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/MohammadRaziei/httpp/compare/v0.5.1...v0.6.0
+[0.5.1]: https://github.com/MohammadRaziei/httpp/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/MohammadRaziei/httpp/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/MohammadRaziei/httpp/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/MohammadRaziei/httpp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/MohammadRaziei/httpp/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/MohammadRaziei/httpp/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/MohammadRaziei/httpp/releases/tag/v0.1.0

{httpp-0.6.0 → httpp-0.7.0}/CMakeLists.txt

@@ -34,6 +34,20 @@ set(HTTPP_SOURCE_DIR ${PROJECT_SOURCE_DIR})
 # they never leak into the httpp .so/.a's public symbols.
 file(GLOB HTTPP_CORE_SOURCES ${PROJECT_SOURCE_DIR}/src/core/*.cpp)
 
+# Swagger UI (vendored in src/third_party/swagger-ui) is compiled into the library: at CONFIGURE time its three
+# files become a generated header (cmake/EmbedFile.cmake), so /docs needs no data files at run time.
+include(EmbedFile)
+set(HTTPP_GENERATED_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated)
+set(HTTPP_SWAGGER_UI_DIR ${PROJECT_SOURCE_DIR}/src/third_party/swagger-ui)
+embed_files(
+    OUTPUT    ${HTTPP_GENERATED_DIR}/httpp_swagger_ui_data.hpp
+    NAMESPACE httpp::embedded
+    FILES
+        swagger_ui_bundle_js    ${HTTPP_SWAGGER_UI_DIR}/swagger-ui-bundle.js
+        swagger_ui_css          ${HTTPP_SWAGGER_UI_DIR}/swagger-ui.css
+        swagger_ui_icon_svg     ${HTTPP_SWAGGER_UI_DIR}/swagger-api-icon.svg
+)
+
 # liburlparser (git submodule, built from source — no system package) does
 # the real URL parsing (scheme/host/port/path, IPv4/IPv6, PSL-aware). It is
 # linked PRIVATE into httpp_core, same as cpp-httplib: consumers of
@@ -84,8 +98,38 @@ endif()
 # httpp links it in statically and never re-exports its headers/libs, so
 # nothing from mbedtls itself belongs in the installed wheel.
 set(DISABLE_PACKAGE_CONFIG_AND_INSTALL ON CACHE BOOL "" FORCE)
+# Thread safety of Mbed TLS: its process-wide state (PSA random generator, key slots) is only locked when the
+# threading layer is enabled, and httpp does TLS on many threads. See cmake/httpp_mbedtls_config.h.
+option(HTTPP_MBEDTLS_THREADING_ALT "Use the alt threading layer (always on for Windows) instead of pthread" OFF)
+if(HTTPP_MBEDTLS_THREADING_ALT)
+    add_compile_definitions(HTTPP_MBEDTLS_THREADING_ALT)
+endif()
+set(TF_PSA_CRYPTO_USER_CONFIG_FILE ${PROJECT_SOURCE_DIR}/cmake/httpp_mbedtls_config.h CACHE FILEPATH "" FORCE)
+find_package(Threads REQUIRED)
+set(LINK_WITH_PTHREAD ON CACHE BOOL "" FORCE)
+# threading_alt.h (the alt layer's types) must be found by every Mbed TLS source (it builds several object libraries
+# that do not see each other's include paths) and by everything that includes its headers: a directory-level include
+# path, inherited by the subdirectories added below, reaches all of them.
+if(WIN32 OR HTTPP_MBEDTLS_THREADING_ALT)
+    include_directories(${PROJECT_SOURCE_DIR}/src/core/mbedtls_alt)
+endif()
 add_subdirectory(${PROJECT_SOURCE_DIR}/src/third_party/mbedtls)
 
+# llhttp (vendored release C sources, kept in src/ not third_party/: it is an interim parser for the async client and goes away with cpp-httplib, no Node needed): the HTTP/1.x parser for
+# the async client. Own C static target so the generated code is built without
+# httpp's -Wall -Wextra -Wpedantic; see src/llhttp/VENDORED.md.
+enable_language(C)
+add_library(httpp_llhttp STATIC
+    ${PROJECT_SOURCE_DIR}/src/llhttp/src/llhttp.c
+    ${PROJECT_SOURCE_DIR}/src/llhttp/src/api.c
+    ${PROJECT_SOURCE_DIR}/src/llhttp/src/http.c)
+target_include_directories(httpp_llhttp PUBLIC
+    ${PROJECT_SOURCE_DIR}/src/llhttp/include)
+set_target_properties(httpp_llhttp PROPERTIES
+    LINKER_LANGUAGE C POSITION_INDEPENDENT_CODE ON C_VISIBILITY_PRESET hidden)
+target_compile_options(httpp_llhttp PRIVATE
+    $<IF:$<C_COMPILER_ID:MSVC>,/w,-w>)
+
 add_library(httpp_core SHARED ${HTTPP_CORE_SOURCES})
 add_library(httpp::core ALIAS httpp_core)
 
@@ -116,14 +160,16 @@ target_include_directories(httpp_core
 # warnings (e.g. indicators.hpp's narrowing-conversion C4244/C4267 on MSVC)
 # aren't ours to fix and shouldn't surface under our own -Wall/-Wextra/-W4
 # below — without patching vendored code to silence its own warnings.
+target_include_directories(httpp_core PRIVATE ${HTTPP_GENERATED_DIR})
 target_include_directories(httpp_core SYSTEM PRIVATE
     ${CMAKE_CURRENT_SOURCE_DIR}/src/third_party/cpp-httplib
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/third_party/aixlog
     ${CMAKE_CURRENT_SOURCE_DIR}/src/third_party
 )
 
 find_package(Threads REQUIRED)
 target_link_libraries(httpp_core PUBLIC Threads::Threads)
-target_link_libraries(httpp_core PRIVATE url::base)
+target_link_libraries(httpp_core PRIVATE url::base httpp_llhttp)
 
 # HTTPS support: mbedtls is linked PRIVATE and CPPHTTPLIB_MBEDTLS_SUPPORT is
 # only ever defined in src/core/internal/httplib_common.hpp (never in a
@@ -131,6 +177,53 @@ target_link_libraries(httpp_core PRIVATE url::base)
 # include/link path — see that file for the shared httplib.h include.
 target_link_libraries(httpp_core PRIVATE mbedtls mbedx509)
 target_compile_definitions(httpp_core PRIVATE CPPHTTPLIB_MBEDTLS_SUPPORT)
+# Asio (standalone, header-only, vendored) runs the async engines: the server's
+# connection loop and the non-blocking client (epoll on Linux, kqueue on macOS,
+# IOCP on Windows). It is only ever included from src/core/async_server.cpp and
+# src/core/async_http.cpp, never together with httplib.h.
+# Where Asio comes from, in order:
+#   1. -DHTTPP_ASIO_INCLUDE_DIR=<directory containing asio.hpp>  (offline builds, packagers)
+#   2. src/third_party/asio, if it holds a copy: a git submodule (<dir>/asio/include)
+#      or a plain copy (<dir>/include)
+#   3. downloaded at configure time, pinned by version and SHA-256 (about 3 MB)
+set(HTTPP_ASIO_VERSION 1.34.2)
+set(HTTPP_ASIO_SHA256 f3bac015305fbb700545bd2959fbc52d75a1ec2e05f9c7f695801273ceb78cf5)
+set(HTTPP_ASIO_INCLUDE_DIR "" CACHE PATH "Directory containing asio.hpp (empty: auto-detect, else download)")
+if(NOT HTTPP_ASIO_INCLUDE_DIR)
+    foreach(_candidate
+            ${CMAKE_CURRENT_SOURCE_DIR}/src/third_party/asio/asio/include
+            ${CMAKE_CURRENT_SOURCE_DIR}/src/third_party/asio/include)
+        if(EXISTS "${_candidate}/asio.hpp")
+            set(HTTPP_ASIO_INCLUDE_DIR "${_candidate}" CACHE PATH "" FORCE)
+            break()
+        endif()
+    endforeach()
+endif()
+if(NOT HTTPP_ASIO_INCLUDE_DIR)
+    include(FetchContent)
+    if(POLICY CMP0135)
+        cmake_policy(SET CMP0135 NEW) # extracted files get the time of extraction
+    endif()
+    string(REPLACE "." "-" _asio_tag "asio-${HTTPP_ASIO_VERSION}")
+    FetchContent_Declare(httpp_asio
+        URL https://codeload.github.com/chriskohlhoff/asio/tar.gz/refs/tags/${_asio_tag}
+        URL_HASH SHA256=${HTTPP_ASIO_SHA256})
+    FetchContent_MakeAvailable(httpp_asio) # Asio has no CMakeLists.txt: this only downloads and extracts
+    set(HTTPP_ASIO_INCLUDE_DIR "${httpp_asio_SOURCE_DIR}/asio/include" CACHE PATH "" FORCE)
+endif()
+message(STATUS "Asio ${HTTPP_ASIO_VERSION}: ${HTTPP_ASIO_INCLUDE_DIR}")
+
+target_include_directories(httpp_core SYSTEM PRIVATE ${HTTPP_ASIO_INCLUDE_DIR})
+target_compile_definitions(httpp_core PRIVATE ASIO_STANDALONE ASIO_NO_DEPRECATED)
+if(WIN32)
+    # Asio wants the target Windows version spelled out (Windows 10 and later).
+    target_compile_definitions(httpp_core PRIVATE _WIN32_WINNT=0x0A00)
+    target_link_libraries(httpp_core PRIVATE ws2_32 mswsock crypt32)
+endif()
+if(MSVC)
+    # Asio's templates produce very large object files.
+    set_source_files_properties(${PROJECT_SOURCE_DIR}/src/core/async_http.cpp ${PROJECT_SOURCE_DIR}/src/core/async_server.cpp PROPERTIES COMPILE_OPTIONS "/bigobj")
+endif()
 
 # macOS: cpp-httplib (src/third_party/cpp-httplib/httplib.h) reads the
 # system trust store via the Keychain APIs (CPPHTTPLIB_USE_CERTS_FROM_MACOSX_KEYCHAIN),