httpp 0.7.0__tar.gz → 0.8.0__tar.gz

httpp-0.8.0/.github/workflows/autobahn.yml

@@ -0,0 +1,52 @@
+name: autobahn
+
+# Called by the orchestrator after its `init` job (which clears the __beta__ assets), so the summary is uploaded after the clean-up
+# and never deleted by it. It can also be run by hand. ADR-0028.
+# WebSocket conformance (RFC 6455) with the Autobahn test suite against the Python echo server. Cases 12.* and 13.* (permessage-deflate) are excluded.
+on:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: write
+
+jobs:
+  autobahn:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        submodules: recursive
+    - uses: actions/setup-python@v6
+      with:
+        python-version: "3.12"
+    - name: Build and install httpp
+      run: pip install .
+    - name: Start the echo server
+      run: |
+        python tools/autobahn/echo_server.py 9001 &
+        sleep 2
+    - name: Run the Autobahn fuzzing client
+      working-directory: tools/autobahn
+      run: |
+        mkdir -p reports
+        docker run --rm --net=host -v "$PWD:/config" -v "$PWD/reports:/reports" crossbario/autobahn-testsuite wstest -m fuzzingclient -s /config/fuzzingclient.json
+    - name: Summarise the report
+      id: summary
+      run: python tools/autobahn/check_report.py tools/autobahn/reports/index.json autobahn-report.md
+      continue-on-error: true
+    - name: Publish the summary to the __beta__ release
+      if: always()
+      env:
+        GH_TOKEN: ${{ github.token }}
+      run: |
+        gh release view __beta__ >/dev/null 2>&1 || gh release create __beta__ --prerelease --title __beta__ --notes "pre-release builds"
+        gh release upload __beta__ autobahn-report.md --clobber
+    - uses: actions/upload-artifact@v4
+      if: always()
+      with:
+        name: autobahn-report
+        path: tools/autobahn/reports
+    - name: Fail if a case FAILED
+      if: steps.summary.outcome == 'failure'
+      run: exit 1

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

@@ -44,7 +44,7 @@ jobs:
 
     - name: Run tests (Linux/macOS)
       if: runner.os != 'Windows'
-      run: ctest --test-dir build --output-on-failure --extra-verbose
+      run: ctest --test-dir build --output-on-failure --extra-verbose --timeout 900
 
   build-coverage:
     runs-on: ubuntu-latest
@@ -85,7 +85,7 @@ jobs:
     - name: Build and run C++ tests
       run: |
         cmake --build build --target test_httpp_cpp -j4
-        ctest --test-dir build -R test_httpp_cpp --output-on-failure
+        ctest --test-dir build -R test_httpp_cpp --output-on-failure --timeout 900
 
     - name: Capture coverage
       run: |

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

@@ -56,6 +56,13 @@ jobs:
     uses: ./.github/workflows/wheels.yml
     needs: [init]
 
+  # Informational: release-wheels does not wait for it, a FAILED case must not block publishing the wheels (ADR-0028).
+  autobahn:
+    uses: ./.github/workflows/autobahn.yml
+    needs: [init]
+    permissions:
+      contents: write
+
   release-wheels:
     needs: [wheel, init]
     runs-on: ubuntu-latest

{httpp-0.7.0 → httpp-0.8.0}/.gitignore

@@ -134,4 +134,4 @@ ehthumbs.db
 Thumbs.db
 
 # Build directory
-build/
+*build*/

httpp-0.8.0/CHANGELOG.md

@@ -0,0 +1,442 @@
+# 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**).
+
+## [Unreleased]
+
+### Added
+
+- **`httpp.testclient.TestClient`** (ADR-0042): a Starlette-shaped client for testing your app. It serves the app on a free loopback port of its own and goes through httpp's client, so tests meet the real routing, middleware and error paths. Cookies, redirects, `base_url`/`Host`, `raise_server_exceptions`, startup and shutdown hooks (`with TestClient(app)`). Not yet: `websocket_connect`, multipart `files=`, an in-memory mode.
+
+### Changed (breaking)
+
+- The command line is a native executable now (ADR-0041): `httpp server`, `httpp browse`, `httpp download`, `httpp curl` and `httpp --version` run without Python and without the GIL (new `--shutdown-timeout` on
+  `server` and `browse`). The Python commands moved behind `py`: **`httpp run ...` is now `httpp py run ...`, and `httpp path ...` is now `httpp py path ...`** (`python -m httpp ...` is the same program as `httpp ...`, so it is `python -m httpp py run ...` too). The old spelling
+  fails with exit 2 and says what to type. Everything after `py` goes to Python untouched.
+- **The wheel keeps its C++ parts in `httpp/sdk/`** (`sdk/bin/httpp`, `sdk/include/`, `sdk/lib/`, CMake config in `sdk/lib/cmake/httpp/`; on Windows the DLL is in `sdk/bin`, next to `httpp.exe`): the shape of an SDK install prefix. `httpp.get_include_dir()`, `get_lib_dir()` and `get_cmake_dir()` return the new places, so code that uses them is unaffected; anything that hard-coded `httpp/lib` or `httpp/include` must change. `find_package(httpp)` also works with `CMAKE_PREFIX_PATH` set to that `sdk` folder.
+- The native executable is inside the package (`httpp/sdk/bin/httpp`, `httpp.exe` on Windows); the `httpp` console script is `httpp_cli.py` (a module next to the package, so a native command does not import it: 25 ms to start, not 80), which finds it (restoring its execute bit if an installer dropped it) and runs it. `python -m httpp ARGS` is the same program as `httpp ARGS`
+  (it calls the launcher). C++: CMake target `httpp_cli` (`-DHTTPP_BUILD_CLI=OFF` to skip), installed to `bin/` with the SDK. `HTTPP_PYTHON` names the interpreter the executable starts for `py` when it is run on its own.
+
+### Removed
+
+- `httpp install` and `httpp uninstall` are gone (they were never released); `httpp path` (`--include-dir`, `--lib-dir`, `--cmake-dir`) is the only SDK helper.
+
+### Added
+
+- C++: `server::use(before, after)` for middleware next to the application's own hooks, `httpp::add_cors` and `httpp::add_trusted_host` (`httpp/middleware.hpp`) (ADR-0037).
+- Python: `Server.add_middleware(CORSMiddleware | TrustedHostMiddleware | GZipMiddleware, **options)`, shaped like Starlette's; the work runs in C++ without the GIL.
+- C++: `httpp::mount_file_browser(server&, base, root, file_browser_options)`, a read-only file browser (list, navigate, preview, download; theme, accent, filter, hidden files, entry limit) with its own
+  embedded page and no dependencies (ADR-0032).
+- Python: `Server.mount_file_browser(base, root, **options)` (same options as C++) and the `httpp browse [DIRECTORY]` command.
+- C++: `server::directory_options` and `serve_directory(mount, dir, options)`: `index`, `hidden` and `download_active` (nosniff, attachment for active types). The defaults keep the old behaviour.
+
+- TLS for the server (ADR-0040): C++ `server::set_tls(cert, key, password)`, `request::secure` / `scheme()`, `add_https_redirect`; Python `Server.set_tls`, `request.secure` / `request.scheme`, `HTTPSRedirectMiddleware`,
+  `run(ssl_certfile=, ssl_keyfile=, ssl_keyfile_password=)` and `httpp py run --ssl-certfile --ssl-keyfile --ssl-keyfile-password` (also with `--workers` and `--reload`). https and wss; TLS 1.2/1.3; no client certificates.
+- Python: `httpp py run --reload` (`--reload-dir`, `--reload-pattern`, `run(reload=True, ...)`): restarts the app when a source file changes, development only (ADR-0039).
+- C++: `server::shutdown(grace)`; Python: `Server.shutdown(grace)`, `Server.shutdown_timeout`, `run(shutdown_timeout=...)` and `httpp py run --shutdown-timeout` (ADR-0038).
+
+### Fixed
+
+- Server: a NUL byte in a path under a mounted directory is refused.
+- Server: a late answer through the `after` hook, error handler or compression no longer reads the server object after the server is destroyed, and a refused job runs on the current thread
+  instead of using a moved-from response (ADR-0035). No API change.
+
+### Changed
+
+- Ctrl+C and SIGTERM in `httpp py run` / `Server.listen` now drain: requests in progress finish (answered with `Connection: close`) within `shutdown_timeout` (default 10 s) instead of being cut; a second Ctrl+C cuts at once (ADR-0038).
+- Server: the method and target are compared with string literals through `std::string_view` (no `strlen`; about 0.8 percent fewer instructions per request, ADR-0033 addendum). No API change.
+- Server: the 16 KiB read buffer of a connection is no longer zero-filled when the connection is made (ADR-0036). No API change.
+- Server: with several I/O threads (`set_io_threads`), new connections go to the I/O thread with the fewest connections instead of wherever the kernel's `SO_REUSEPORT` hash put them (ADR-0034). No API change.
+- Server: about 23 percent fewer instructions per `route_io` request (ADR-0033, items 9 to 12): no shared reference count per answer when no hook or compression is set, the response head
+  is written without `strlen`, responses are moved once instead of once per layer, a request answered on the spot is not entered in the 504 list. One visible detail: the 504 deadline of
+  an unanswered asynchronous request starts when its handler returns, not at arrival. No API change.
+
+## [0.8.0] - 2026-11-01
+
+WebSocket in the C++ core and in Python, checked with the Autobahn conformance suite, and a benchmark suite built by CMake that
+now sets httpp next to Drogon. One public C++ type changed: `swagger_ui_asset` (see the first entry).
+
+- **Autobahn result** (second run, after [ADR-0029](docs/adr/0029-incremental-utf8-validation.md)): no FAILED case, 589 OK, 7 NON-STRICT and 6 INFORMATIONAL.
+  The `permessage-deflate` cases (12 and 13) are left out on purpose. The NON-STRICT cases (3.2, 3.3, 4.1.3, 4.1.4, 4.2.3, 4.2.4, 5.15) are behaviour the RFC leaves open.
+- **Build**: `embed_files(... COMPRESS)` embeds gzip-compressed bytes (same bytes on every build), with `<name>_raw_size` and `<name>_is_gzip`; `-DHTTPP_EMBED_COMPRESS=OFF` turns it off. Swagger UI uses it: `libhttpp_core.so` is about 1.3 MB smaller, and `/docs` files are sent as stored (`Content-Encoding: gzip`, `Vary: Accept-Encoding`) to clients that accept gzip and inflated for the others. **Changed:** `httpp::swagger_ui_asset::data` holds the stored bytes (gzip unless built with `HTTPP_EMBED_COMPRESS=OFF`); new fields `raw_size` and `gzip`. See [ADR-0031](docs/adr/0031-compressed-embedded-files.md).
+- **WebSocket (RFC 6455) in the C++ core**: `server::route_ws(path, ws_handler)` with a `websocket` handle (`send_text`, `send_binary`, `ping`, `close`,
+  `pause_reading`, `buffered_amount`). Callbacks run on the I/O thread; sends are thread-safe and the send queue is bounded (`max_buffered`, `status::full`,
+  `on_drain`). Text, binary, fragmentation, ping/pong, close handshake, UTF-8 and size limits, optional keep-alive pings; no extensions (no `permessage-deflate`).
+  The engine got a generic upgrade "tunnel". See [ADR-0026](docs/adr/0026-websocket.md).
+- **WebSocket in Python**: `@app.websocket("/ws/{room}")` with an `async def` handler taking `websocket` (`accept`, `receive*`, `async for`, `send_*`, `ping`, `close`,
+  `WebSocketDisconnect`). One task per connection on the lane's loop; the I/O thread fills a per-connection mailbox without the GIL. Receiving is bounded (`max_queued`, the socket
+  is not read past it) and `await send_*` waits when the send queue is full. Browsers' `Origin` must match the host unless `origins=` says otherwise. The C++ handshake is now
+  asynchronous (`ws_acceptor`, `websocket::user()`, `on_close` exactly once per accepted upgrade). See [ADR-0027](docs/adr/0027-websocket-python-and-async-handshake.md).
+- WebSocket text messages are checked for UTF-8 as the bytes arrive: a bad byte closes with 1007 at once (also in the middle of a frame or a fragment), instead of at the end of the message. First Autobahn run: no FAILED case; this was the only real finding ([ADR-0029](docs/adr/0029-incremental-utf8-validation.md)).
+- **Benchmarks are a CMake project** (`cmake -S benchmarks -B build-bench`, targets `bench`, `bench_quick`, `bench_check`; the Makefile is gone). New: a WebSocket echo benchmark with its own load generator (`ws_load`), a memory table for many idle WebSocket connections, and Drogon (fetched and built by CMake) next to the httpp C++ API ([ADR-0030](docs/adr/0030-benchmarks-built-by-cmake.md)).
+- Autobahn runs as a job of the orchestrator, after its clean-up of the `__beta__` release ([ADR-0028](docs/adr/0028-autobahn-called-by-the-orchestrator.md)).
+- Fixed a data race with several I/O threads (`set_io_threads`, Python `io_threads`): the cached `Date` header text was shared by all of them, so two threads could
+  write and read it together. ThreadSanitizer reported it, and in the benchmarks two runs out of about 150 lost the server (a round with zero answers). The cache is now per thread.
+- Answers from other threads are batched into one Asio post per burst, which cuts the cost of the thread hop.
+- An `async def` handler that cannot suspend (no `await`, `async with` or `async for`, no `Depends`; Python 3.12+) runs on the I/O thread when the
+  loop thread is asleep and no `def` handler is running, so it skips the hop to the asyncio loop: 54.7k to 71.5k req/s on the `hello` benchmark
+  (2 cores, one box, interleaved). Handlers that await are unchanged. See [ADR-0023](docs/adr/0023-inline-async-handlers.md).
+- `async def` and `route_async` / `route_io` requests allocate about 8 fewer objects (30 to 22 per request): `responder` keeps its state in plain members, and that state is released on the I/O thread with the answer. About 4 percent more req/s and 8 percent less CPU for an awaiting `async def`.
+
+### Fixed
+- **A failing timing assertion could hang CI for ever.** The `worker_pool` gate tests returned early when an assertion failed, the gate stayed closed and the
+  pool's destructor joined blocked threads without end (a 14 minute macOS step). The tests now open the gate from an RAII guard, wait in bounded loops, and the
+  CMake workflow runs `ctest --timeout 900`. The growth test no longer depends on a tight wall-clock bound (`help_after` 10 ms, limit 250 ms).
+- WebSocket tests poll with a timeout instead of sleeping for a fixed time.
+
+### Changed
+- **Less work per request in the engine ([ADR-0033](docs/adr/0033-engine-per-request-cost.md))**: the Asio reactor runs without locking (sockets and timers were already
+  used on the loop thread only); an answer made on the loop thread (`route_io`, an inline handler) is sent at once instead of going through the poster; connection timers
+  are armed lazily (one deadline per connection, no timer work per keep-alive request); the response head is built without temporaries. About 27 percent fewer
+  instructions per `route_io` request (counted with callgrind: 25.5k to 18.3k; wall-clock gain not measured on a many-core machine). ThreadSanitizer is clean on the whole C++ suite.
+- The 504 backstop for async requests keeps one list per I/O thread instead of one shared list under one mutex, so I/O threads no longer contend on it (`route_io` and Python `async def` with several I/O threads).
+- **`keep_alive_max` (C++ `set_keep_alive_max`, `Server(keep_alive_max=...)`) now defaults to 1000 and `0` means no limit.** It defaulted to 100, and `0` meant 1.
+- **Defaults from the first 16-thread measurement ([ADR-0025](docs/adr/0025-measured-defaults-on-16-threads.md))**: `Server(io_threads=None)` now
+  means `min(4, CPUs // 4)` with a GIL (1 on a free-threaded Python and on Windows); the inline `async def` path of ADR-0023 is on by default only
+  with 2 CPUs or fewer (`Server(inline_async=True/False)` forces it): on a machine with cores to spare it was 20 percent slower at saturation.
+- **`set_thread_pool(base, max, grow_after)`** (Python: `grow_after_ms`): how long a job waits for a free worker before the pool grows. A step adds one thread per 500 us of that wait
+  (so one thread with the default wait, as before).
+- With a GIL the worker pool starts with one thread and grows after a 10 ms wait (the maximum is unchanged): on 16 threads one worker gave 16.7k req/s on
+  a CPU-bound `def` handler, sixteen 10.6k (ADR-0025).
+
+### Added
+- Benchmark suite: JSON and FastAPI rows, `io_threads` 1, 2, 4, 8 for Python too, library versions and compiler in the header, standard deviation, a fixed-rate
+  latency phase (p99.9 at half of each maximum), efficiency cores for the load generator.
+- **`server::set_io_threads(n)`, `Server(io_threads=N)` and `httpp run --io-threads N`**: several I/O threads share the port (one engine and
+  one acceptor each, `SO_REUSEPORT`; not on Windows, which keeps one). On a free-threaded Python every I/O thread also gets its own asyncio
+  loop thread, so `async def` handlers use several cores; with a GIL there is still one loop. Default 1. See
+  [ADR-0024](docs/adr/0024-io-threads-and-lanes.md). Not yet measured on a many-core machine: `benchmarks/Makefile`.
+- **`benchmarks/Makefile`** (`make bench`): builds venvs for 3.13, 3.14 and 3.14t, the C++ benchmark server and `oha`, then compares
+  uvicorn, httpp `def` / `async def` / `await` and the C++ API at several I/O thread counts into one text file.
+- **`server::set_body_timeout(seconds)` and `Server(body_timeout=...)`**: the whole request body must arrive within this time after
+  its head (default 120 s, `0` = no limit). Before, a body dripped one byte at a time was held only by the per-read `read_timeout`.
+- **`server::set_compression(min_size, level = 1)` and `Server(compression=..., compression_level=...)`**: gzip for text answers
+  (`text/*`, JSON, XML, JavaScript, SVG) when the client sends `Accept-Encoding: gzip`. Off by default. It runs after the hooks, adds
+  `Vary: Accept-Encoding`, and leaves files, streams, partial answers, already encoded bodies and bodies it cannot shrink alone. On a
+  `route_io` answer the work moves to a worker, never the I/O thread. Uses the vendored deflate: no new dependency.
+- **Routers**: `httpp::router` and `server::include(router, prefix)` in C++, `APIRouter` and `Server.include` (alias `include_router`) in
+  Python. Same rules in both: outer prefix, the router's own prefix, then the path; `/` under a prefix is the prefix. Nesting works.
+  No request-time cost: prefixes are joined when the router is included.
+- **`response::after_send`** (C++) and, in Python, the injected **`response`** argument and **`BackgroundTasks`**: a job that runs on a
+  worker thread after the answer was written, for work the client should not wait for. The injected `response` adds a status,
+  headers and cookies to a handler's answer. A throwing job is logged and ignored.
+- **Forms and uploads**: `request::form()` in C++ (`form_data`, `upload_file`) parses urlencoded and `multipart/form-data` bodies, only when a
+  handler asks. Python: `request.form()` (a malformed body answers 400), and FastAPI-style `Form()`, `File()` and `UploadFile` parameters
+  with 422 errors and OpenAPI request bodies. `percent_decode` and `parse_query` moved to one internal header.
+- `ServerRequest.header()`, `.query_param()`, `.path_param()` and `.cookie()`: the lookups the C++ `request` already had, same names,
+  `""` when absent (a second argument sets another default).
+- ADR-0022: the dual C++/Python rule and the decisions the owner delegated.
+
+### Changed
+- A failing `done()` of an `async def` route (for example a bad header) now answers a 500 at once instead of leaving the client to the 504.
+- **The worker pool wakes threads last-in first-out, and does not wake a second thread until a job has waited 500 us** (a scout
+  thread watches the queue), so light `def` handlers run on one hot thread instead of passing the Python lock around. On two cores,
+  `def` `hello` went from 16k to 36k req/s (3.13) and from 19k to 33k (3.14t); `item` from 12k to 25k and from 17k to 30k. A
+  blocked handler delays queued requests by about 500 us. New `tests/cpp/test_worker_pool.cpp` (also run under ThreadSanitizer).
+
+### Changed (async)
+- **`async def` routes are about 30 percent faster:** one shared timer for `handler_timeout` instead of a timer per request, and a prebuilt JSON
+  encoder (same output as `json.dumps`; CPython only, a circular structure now ends in a RecursionError, still a 500).
+- **`async def` handlers start eagerly on Python 3.12+:** a handler that never waits finishes inside `dispatch` without a trip through the
+  loop's ready queue (2 to 8 percent on `hello` / `item`).
+- **The `async def` inbox is drained in batches:** one lock per batch of queued requests instead of one per request (about 12 percent on
+  `hello`, 17 percent on `item`, 2 cores).
+- **Faster answers for `str`, `dict` and `list` results,** and no `handler_timeout` bookkeeping for a handler that finishes at once
+  (together with the eager start about 20 percent on `hello` / `item`, 2 cores).
+
+### Fixed
+- **`Server.listen()` could hang for ever after Ctrl+C on free-threaded Python (seen on the macOS 3.15t wheel test):** it waited on a
+  `threading.Event`, and an interrupt that lands inside `Event.wait()` can leave that Event's internal lock taken (or released twice), after which
+  `listen()` and the serving thread both block on it. It now polls a plain flag every 50 ms (`time.sleep` holds no lock). Two tests: Ctrl+C at
+  many different moments, and a deterministic one that `listen()` never creates an `Event` or `Condition`.
+- **The macOS wheel build works again:** `serve_directory` checked symlinks with `std::filesystem`, which needs macOS 10.15 while the
+  wheels target 10.13. It now uses `realpath` on Linux and macOS (`std::filesystem` stays on Windows only). The tests also cover a sibling
+  directory whose name starts like the mounted one, and a mounted directory given with a trailing slash.
+- **`def` handlers were slow: a Python thread state was created and destroyed for every request.** Each pool thread now keeps
+  its state (`httpp_py_pin_thread`). Measured on 2 cores, `oha`, 32 connections, plain `hello` route: CPython 3.13 9.4k -> 17.9k
+  req/s, free-threaded 3.14.6t 1.9k -> 24.6k req/s. A CPU-bound `def` handler on 3.14t now scales with the cores
+  (conc 1: 382, conc 8: 734 req/s) while 3.13 stays at about 330. A client that hangs up now closes a sync streaming generator
+  at once (its `finally` runs), because on free-threaded CPython an object released from another thread is freed only when
+  the thread that created it next runs Python.
+- **A dependency without parameters failed on a route with path parameters** (`TypeError: dep() got an unexpected keyword argument 'n'`):
+  every dependency was handed all the path parameters of the route, not only the ones it declares. Found by a stress test; it
+  happened on every Python version.
+- **405 instead of 404 for a wrong method.** A path that has a route for another method answers 405 with an `Allow` header
+  (a GET route also allows HEAD). A path with no route at all is still 404. (Changed: code that checked for 404 on a wrong method.)
+- **Static files no longer follow a symlink out of the mounted directory.** Such a link answers 404; a link that stays inside is served.
+- **A path parameter that does not parse** (`n: int`, `x: float`) answers 422 with the FastAPI body
+  `{"detail": [{"type": "int_parsing", "loc": ["path", "n"], ...}]}` instead of the old hand-made `{"error": ...}`.
+- **abi3 wheel build.** `sha256_hex` took a typed memoryview, which needs `Py_buffer`; the stable ABI has it only from Python 3.11,
+  and the cp39-abi3 wheel failed to compile (CI only). It now takes any bytes-like object without one (`bytes` in place, others copied
+  once). `tests/python/test_abi3_safe.py` guards against typed memoryviews coming back.
+
+### Added
+- **Slowloris guard and a connection limit.** The whole request head (request line and headers) must now arrive within
+  `header_timeout` seconds (default 10, `0` = no limit); before, a client sending one byte every few seconds kept the connection
+  forever because only each single read had a timeout. `set_max_connections(n)` (C++) and `Server(max_connections=n)` refuse
+  the connection over the limit with a 503 and close it (default: no limit). A slowly dripped request **body** is still only
+  covered by `read_timeout` per read.
+- **`HTTPException`, response classes, `httpp.status`.** `raise httpp.HTTPException(404)` (or `(status, detail, headers)`) in a
+  handler or a dependency answers `{"detail": ...}` with that status; override it with `@app.exception_handler(HTTPException)`.
+  `JSONResponse`, `PlainTextResponse`, `HTMLResponse`, `RedirectResponse` (307 by default), `StreamingResponse` and `FileResponse`
+  can be returned from a handler and skip `response_model`. `httpp.status.HTTP_404_NOT_FOUND` and the rest. See ADR-0020.
+- **gzip / deflate in the client, no system zlib.** Both the blocking and the async client send `Accept-Encoding: gzip, deflate`
+  (unless you set the header yourself) and undo `Content-Encoding: gzip`, `x-gzip`, `deflate` (zlib, or raw as some servers send it)
+  and chains of them, so `response.body` is always the real body. Headers are left as received, like requests and httpx. A
+  coding we do not advertise (`br`, `zstd`) leaves the body untouched. `max_response_size` limits the **decoded** size
+  (a zip bomb ends as `too_large`, status 413); corrupt data ends as `error_kind::other`, never as garbage. Set
+  `Accept-Encoding: identity` to ask the server not to compress. `download()` is unchanged in what it sends but now saves a compressed response exactly as received, instead of failing with 415. Built on two vendored decoders/encoders, extracted unmodified:
+  `src/third_party/stb_inflate` (the decoder of stb_image.h) and `src/third_party/stb_deflate` (the compressor of libstb), wrapped
+  by the internal `httpp::detail::inflate` / `deflate` (zlib, gzip and raw; levels 0 to 9; Adler-32 and CRC-32 checked), and tested
+  against Python's zlib and gzip in both directions. The compressor is ready for the server side (a GZip middleware) and for
+  compressing request bodies; neither is wired yet.
+- **Access log.** At the `info` log level the server writes one line per answered request (`GET /items/1 200`),
+  including the answers the server makes itself (404, 413, ...). It goes through the library's own logging
+  (AixLog), so `set_log_level`, `set_log_file` and `set_log_callback` apply to it. Nothing is built or written
+  while the level is higher.
+- **"Listening" line.** After a successful bind the server logs `listening on http://host:port` at `info`
+  (also for `bind_to_any_port`, with the real port). A port that is already taken only produces the existing
+  `cannot listen` error.
+
+- **Python parity for downloads and hashing.** `Download.sha256()`, `Download.sha256_url()`, `Download.set_timeout()`,
+  `Download.set_max_wait(seconds)` and `DownloadResult.sha256`; `httpp.utils.sha256_hex()`, `httpp.utils.sha256_file()` and
+  `httpp.utils.parse_sha256_checksum()` (they raise `RuntimeError` where the C++ functions throw). `Client(keep_alive=False)`
+  mirrors `httpp::client::set_keep_alive`.
+- **Parity test.** `tests/python/test_cpp_python_parity.py` fails when a public C++ name has no Python counterpart and no documented reason.
+
+### Changed
+- **The C++ log goes through Python's `logging` automatically.** Lines arrive in `logging.getLogger("httpp")`, and that logger's level
+  decides what C++ produces: `logging.getLogger("httpp").setLevel(logging.INFO)` (or `logging.config.dictConfig`) now also turns on the access
+  log and the `listening on ...` line. `httpp.set_log_level(...)` sets the same logger level. `httpp run` still prints to stderr when the
+  application configured no logging. An explicit `set_log_callback`/`set_log_file` replaces the bridge. See ADR-0018.
+- `Client`/`AsyncClient` encode query strings and forms with the C++ `url::build_query` instead of `urllib` (identical output, about 4x
+  faster for that step). One path-template parser in Python instead of two; one shared option block for `Client` and `AsyncClient`.
+- **`httpp.run`, `app.run()` and `httpp run` log at `info` by default** (startup line and one line per request on
+  stderr, like uvicorn). Use `log_level="warning"` or `--log-level warning` to keep only problems, `off` for
+  nothing. `app.listen()` and the C++ API keep the default `warning`, so an embedded server stays quiet until you
+  call `set_log_level`. Benchmarks should run at `warning`.
+- **llhttp moved to `src/third_party/llhttp`** (it was `src/llhttp`). The files are unmodified: they match the checksums in
+  `VENDORED.md` and the upstream `release/v9.4.3` tag byte for byte. Only the path changed.
+- The `starting on ...` line printed by `run` before binding is gone; the `listening on ...` line replaces it and
+  only appears once the port is really bound.
+- **`httpp run` wins over a `listen` in the file.** While `httpp run module:app` imports the module, `app.listen()`
+  and `app.run()` calls at import time (without an `if __name__ == "__main__":` guard) are skipped with a warning
+  (`httpp: ignoring app.listen('127.0.0.1', 8001): ...`), so `--host`, `--port` and `--workers` apply. Before, the
+  file's `listen` blocked the import, the CLI options were silently ignored, and `--workers` failed with a bind
+  error. Running the file with `python file.py` is unchanged. Only a string target (`"module:app"`) is affected.
+
+### Measured
+First WebSocket and Drogon numbers, from the full `bench` target on a 16 thread machine (medians of 3 rounds of 5 s, 64 connections, `powersave` governor, one box,
+so compare rows of this run only):
+- WebSocket echo, 64 byte messages: Python 3.14 httpp 287k msg/s (1 I/O thread) against 122k for uvicorn and 111k for the `websockets` library; 3.14t with
+  4 I/O threads 715k msg/s. C++: httpp 339k, 648k, 1.05M and 973k msg/s with 1, 2, 4 and 8 I/O threads against 373k, 755k, 1.06M and 974k for Drogon.
+- `hello` on Python 3.14: `def` 241k req/s with 1 I/O thread and 521k with 4, against 78k for uvicorn and 22k for FastAPI with uvicorn (run after the engine changes).
+- 0 errors in every row (3 rounds each), which is the first full run without a lost server since the `Date` cache fix.
+
+### Known limitations
+- WebSocket: no `permessage-deflate`, and no TLS of its own (`wss` needs a TLS proxy in front; not tried). On WebSocket routes there are no dependencies,
+  no injected `response`, no background tasks, no OpenAPI entry and no `APIRouter.websocket` yet. The engine closes with a lingering close (up to 2 s), so the final
+  close code can arrive after the close frames.
+- Memory per idle WebSocket connection is higher than in Drogon and in the `websockets` library: about 20 KiB (C++) and 24 KiB (Python) against 8.5 KiB and
+  12 KiB (10,000 connections, one run).
+- Plain HTTP in C++ is still slower than Drogon at the same number of I/O threads, by 7 to 17 percent after the changes above (`hello`, `route_io`: 256k, 460k and 630k
+  req/s with 1, 2 and 4 threads against 281k, 496k and 760k; a later run than the one in "Measured", same machine). WebSocket echo is about 9 to 14 percent behind with 1 or 2 threads and level with 4 or more.
+- A free-threaded Python still defaults to one I/O thread (`io_threads`), which is about 2.4 times slower than 4 on the `hello` benchmark; set it by hand.
+- The WebSocket code was run on Linux; Windows and macOS were covered by CI only. ThreadSanitizer is clean on the whole C++ suite (384 test cases); the Python layer was not run under it.
+
+## [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 server** (`async_server`, with a worker pool). It speaks plain HTTP: the server has no TLS yet. TLS (Mbed TLS)
+  is in the async client, 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.
+
+[Unreleased]: https://github.com/MohammadRaziei/httpp/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/MohammadRaziei/httpp/compare/v0.7.0...v0.8.0
+[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