The wake a worker sent when it started a job only shortened the wait of a
backlog from at most 10 ms, and needed an atomic flag and a second enqueue
try to be safe. The 10 ms retry, which works with any TaskQueue, now does
it alone, and one submit() decides who may enter the queue. The listen
retries use the same interval, and the park failure is logged in one
place. The zero-timeout test sends its request before the server accepts,
which removes its race with the 10 ms floor.
The backlog test queued two jobs before a worker could take the first,
which a queue with room for one turns away. The zero-timeout test now
tries a few connections, since one can miss the 10 ms floor on a busy
machine.
- A keep-alive timeout of 0 closed every new connection before its first
request. The wait now has the same 10 ms floor as keep_alive().
- An established connection in the backlog could wait for an unrelated
event although the queue had room. A worker woke the loop when it
finished a job, before ThreadPool made room by taking the next one, and
the loop announced the backlog only after the failed try. A worker now
wakes the loop when it starts a job, the loop announces the backlog
before a second try, and retries it every 10 ms while it is not empty,
for task queues that make room later.
- A new connection could take the room the backlog waited for. It is now
turned away while the backlog is not empty.
- A failed arm() of the listening socket stopped accepting for good, and
one of a connection left it unwatched. The first is retried after 10 ms,
the second closes the connection.
Before 3.0.14, 3.1.6, 3.2.2 and 3.3.1, SSL_free_buffers() could free the
read buffer while a record whose header had been read still waited for its
body. A client can bring that about before its connection is parked, since
writing a response peeks at the socket. Check the OpenSSL that runs, not
the one built against.
An idle parked TLS connection took about 24 KB, most of it OpenSSL's read
and write buffers. SSL_free_buffers() before parking brings it to about
15 KB; OpenSSL keeps them when a record is pending and makes new ones on
the next read. The request rate is unchanged. BoringSSL, LibreSSL, Mbed TLS
and wolfSSL are left as they are.
SSLServer::TlsConnection plugs the TLS session into the parked connection.
A worker runs the handshake when the event loop sees the ClientHello, so a
connection that has not started it, or has gone quiet after it, waits in
the event loop instead of holding a worker. The handshake counts as having
read what the loop saw, and a connection that has finished it waits for
room like a served one when the queue is full. close_notify sent from the
event loop does not block.
SSLServer::start_session() holds the session setup and handshake that both
the blocking path and TlsConnection use, and supports_keep_alive_parking()
goes away.
KeepAliveConnection becomes a base that parking_loop() and
resume_connection() drive without knowing the transport. PlainConnection
holds the SocketStream, and Server::new_keep_alive_connection() makes one
for each accepted socket, so that SSLServer can add a TLS connection next.
A connection now counts as established for a full queue once a worker has
opened it, which for plain HTTP is when it has been served, as before.
Closing happens explicitly in the event loop and on the worker; the
destructor is only a net. No change in behaviour.
KqueuePoller keeps the Poller contract with EV_ONESHOT, which deletes an
event once it is delivered, so arm() adds it each time. wake() uses the
socket pair that PollPoller uses, since EVFILT_USER is not on every BSD.
make_poller() picks it on macOS and FreeBSD and falls back to poll()
elsewhere.
The contract tests now run on it as well.
EpollPoller keeps the Poller contract with EPOLLONESHOT: a delivered
descriptor stays registered but disabled, so arm() modifies it, and adds
it when it was closed in between. wake() writes to an eventfd that stays
armed. make_poller() picks it on Linux and falls back to poll().
poll() goes over every parked connection on each wait, and epoll only
over the ready ones. With 10000 idle keep-alive connections parked, 10
active clients got 95k requests per second instead of 2.4k, at 0.1 ms
instead of 4 ms each. With few connections nothing changed.
The contract tests now run on both backends.
SocketStream now allocates its 4KB read buffer on the first read that
needs it, and a connection gives the buffer back when it is parked. An
idle connection that has sent nothing never allocates one. With 10000
idle keep-alive connections parked, the server's RSS went from 47MB to
8MB; requests per second did not change.
A kept-alive connection holds a worker thread while it waits for its
next request, so connections beyond the thread count wait for one to be
closed, and with a pool smaller than the number of clients some clients
get nothing until the keep-alive timeout or the max count ends another
connection.
With keep-alive parking, listen() runs an event loop on the detail::Poller
instead of the blocking accept loop. A connection waiting for its next
request is parked there, and goes back to a worker through the TaskQueue
when the request arrives. The handlers, content providers and WebSocket
keep their blocking API and still hold a thread while they run.
It is opt-in and off by default. With it on:
- consecutive requests on a connection may run on different threads;
- when the queue is full, a connection that has not been served yet is
closed as before, but an established one waits in a backlog instead of
losing its request;
- the loop owns the listening socket while it watches it, and stop()
hands it over instead of closing it under the poller;
- SSLServer ignores the setting for now, and an override of
process_and_close_socket() is not called.
On two CPUs with two workers, 50 keep-alive clients of a 2.7 ms handler
were all served evenly (the slowest response took 70 ms instead of 5 s
with 10 clients getting nothing), light requests from 50 clients went
from 82k to 248k per second, and 10 clients were served after 10000
idle connections that had stopped the old loop. With no more clients
than workers, handing the connection over costs about half of the
requests per second of a very light handler.
The old accept loop moved unchanged into accept_loop().
process_server_socket_core() now takes the stream, and
drain_and_close_socket() takes how long to wait for the peer.
wait() cleared the pending flag before reading the wake byte. A wake()
landing in between sent a second byte, the read took both, and the flag
stayed set with nothing left to read, so every later wake() was skipped
and the waiting thread slept on. Clear the flag after the read instead,
as libuv does for uv_async_send(): a wake() that lands in between finds
the flag still set and sends nothing, which loses nothing because the
caller looks at its shared state after wait() returns.
process_server_socket_core() now takes the function that waits for the
next request and the number of requests served so far, instead of
calling keep_alive() and counting on its own stack. Both callers pass
keep_alive() and a fresh counter, so nothing changes yet; this lets a
caller stop waiting and resume the same connection later without losing
track of keep_alive_max_count.
Groundwork for an opt-in reactor that parks idle keep-alive connections
instead of blocking a worker thread on each of them.
detail::Poller delivers readiness once per arm(), so a descriptor is
either armed (owned by the poller) or owned by whoever got the event.
The same contract maps onto poll(), epoll, kqueue and Windows' AFD_POLL,
so a backend can be added without touching its users. wake() ends a
wait() from any thread; an armed descriptor must be disarmed before it
is closed, which the poll() backend asserts.
detail::PollPoller is the portable backend (poll() / WSAPoll()), and
detail::create_socket_pair() emulates socketpair() on Windows with
sockets that child processes do not inherit.
Nothing uses them yet.
parse_url rejected any scheme containing an uppercase letter, so
Client("HTTPS://..."), WebSocketClient("WSS://...") and a redirect to
"Location: HTTPS://..." failed, although the scheme is case-insensitive
(RFC 3986 3.1). Lowercase the scheme in parse_url so that every caller
compares one canonical form and selects TLS for it.
SSLClient verifies the server certificate chain with CryptoAPI on
Windows by default, while WebSocketClient always left it to the TLS
backend, whose snapshot of the Windows store lacks the roots Windows
fetches on demand. A wss:// connection could fail against a host that
SSLClient connects to.
WebSocketClient now makes the same decision through a shared helper,
and gets enable_windows_certificate_verification() to turn it off.
Fix#2685
A read timeout set with set_read_timeout() was reported only on a frame
boundary. One that elapsed inside a frame, or between the fragments of a
message, failed the read and closed the connection, as what had been read
could not be resumed. A small frame written in pieces often arrives in
pieces on Linux, so a server polling with a short timeout lost the
connection on its first message.
A frame is now read by ws::impl::FrameReader, which keeps what it has read
across a timeout, and WebSocket keeps the message being assembled, so
read() returns Timeout wherever the timeout lands and goes on from there at
the next call. close() waits for the peer's Close through the same reader.
read_websocket_frame() keeps its one-shot meaning.
write_websocket_frame() writes the header with the payload's first chunk
in one write, and WebSocket connections set TCP_NODELAY unless
CPPHTTPLIB_WEBSOCKET_TCP_NODELAY is false: on Linux, small messages each
way otherwise waited on Nagle's algorithm for the peer's delayed ACK, a
few in fifty around 30-40 ms late.
ClientImpl::redirect() resolved a Location with resolve_relative_location(), which hands a value with a ':' in its first segment back unchanged as having a scheme, and then parsed it with parse_url(), which also accepts a bare host[:port] so that Client("localhost:8080") works. A Location such as "internal:8080" or "127.0.0.1:6379" therefore came out with an empty scheme and a host, slipped past the http/https check, and was followed as a cross-host redirect to that host and port. A value such as "localhost:8080/x" was sent to the same host as a path without a leading '/'.
Follow only http/https URLs and references starting with '/', and refuse anything else, as an unsupported scheme already was. Network-path references such as "//host:port/x" are still followed.
A read() assembling a fragmented message looped over continuation
frames without looking at closed_, which the loop over frames checks.
A peer that kept sending fragments, empty ones included, never let the
read reach a wait, so a close() from another thread could not end it.
The read now ends with Fail once the connection is closed.
stop() takes the listening socket away, and listen() then waits for every
handler to return. A WebSocket handler waiting in read() on a client that
stays connected never learned of the stop: with no read timeout it waited
for the 300 s backstop, and with one it got Timeout back on an open
connection, so a `while (ws.read(msg) != Fail)` loop went on forever and
listen() with it.
The server now hands each WebSocket a predicate for its own stop, and the
WebSocket's read interrupt answers to it as it does to a pong timeout. A
read cut short while the server stops, between messages or in the middle
of a fragmented one, sends a Close with 1001 Going Away and returns Fail.
That close does not wait for the peer's reply, so a stop is not held up
per connection.
A server WebSocket's reads now wait in the interruptible slices whatever
the heartbeat settings, as keep-alive connections already do for the same
check.
* Let ClientImpl::stop() end a connect or a TLS handshake
stop() took socket_mutex_, which send_() and open_stream() hold while
they open the connection, so a stop() made during a connect, a TLS
handshake or the CONNECT of a proxy tunnel waited for the connection
to open or to time out, 300 seconds by default, for a server that
never answers.
stop() no longer waits for the mutex while a connection opens: it
cancels the connection phase by a compare-exchange from Connecting,
and the end of the phase reads the cancel in the same exchange that
takes the state back to Idle, so a cancel stop() accepts is never
lost. stop() also sets stop_requested_: the wait of the connect and
the waits of the handshake, in every TLS backend, poll it in slices of
100 ms, as do the reads of the CONNECT of a proxy tunnel. A request or
a stream canceled there reports Error::Canceled, before it sends
anything or takes the socket. A request opened after stop() clears the
flag as before, and a stream now does too. A negative connection
timeout still waits without end in the interruptible connect wait.
* Add ClientImpl::set_interrupt(), a stop the caller holds
stop() ends what is in flight, and a request or a stream opened after
it clears the flag, so a stop() made just before a request goes out is
lost.
set_interrupt() gives the client a predicate its caller owns, polled
wherever stop_requested_ is: the connect, the TLS handshake, the
CONNECT of a proxy tunnel and the reads of a request, and the head of
a stream too. The client of a cross-host redirect keeps it. A request
or a stream refuses to go out once it holds, so a stop the caller
holds is never lost, whenever it comes. A call blocked in the system,
a send() of a large body or a TLS read inside a record, still ends
through stop() alone, which shuts the socket down.
A timeout past what the clock reaches now waits without end instead of
expiring at once, so such a wait still ends on the interrupt.
* test: create the backlog sockets with SOCK_NONBLOCK
detail::set_nonblocking lives in httplib.cc in the split build, so
test_split did not compile. The test only runs on Linux, where
SOCK_NONBLOCK makes the socket nonblocking at creation.
* Open the connection without socket_mutex_ instead
Rework the change so that send_() and open_stream_() open the
connection without holding socket_mutex_, as requests are already
serialized by request_mutex_. stop() then never waits for a connection
being opened: it always sets stop_requested_, which the connect wait,
the TLS handshake, the CONNECT and the wait for the head of a stream
poll, and the call ends with Error::Canceled before it sends anything.
This replaces the connection state machine and the try_lock loop in
stop().
The flag is cleared once, as a send() or an open_stream() starts, so a
retry inside the call no longer drops a stop() it already got.
Drop set_interrupt() for now: a predicate held per client cannot be
shared, e.g. by an SSEClient that borrows the caller's Client. Also drop
StopEndsATlsReadInsideARecord, which checked existing behavior that
does not hold on Windows, and share the listener setup of the tests.
Keep the deadline_after() fix: a timeout past what the clock reaches
waits forever instead of overflowing into an immediate timeout.
---------
Co-authored-by: yhirose <yuji.hirose.bug@gmail.com>
* drop a passed-through Content-Length when the client reframes the body
send_with_content_provider_and_receiver() kept a Content-Length the
caller passed through after the library reframed the body: it compresses
a buffered body under set_compress(true), or streams a provider without a
length as chunked. prepare_default_headers() only adds a Content-Length
when none is present, so the stale value went out describing the original
body. With compression the server reads only that many bytes of the
longer gzip stream and the rest desyncs the next request on a kept-alive
connection; with a chunked provider the client emits both Content-Length
and Transfer-Encoding. Erase it once the library owns the framing so
write_request() emits the matching length, or none for a chunked body.
A plain, uncompressed body keeps the caller's value.
* Document the dropped Content-Length and tidy the new tests
Note in the README that a per-request Content-Length is dropped when the library compresses or chunks the body; a default header is not. Shorten the comments, use HOST like the neighbouring tests, and start the chunked test's Content-Length count at a value the handler has to overwrite.
---------
Co-authored-by: yhirose <yuji.hirose.bug@gmail.com>
gen-certs.sh and test/CMakeLists.txt chose between -x509v1 and -x509 by the
openssl version. When the default openssl changed (macOS runner image
20261112), the root was generated as v3 without basicConstraints, openssl
rejected it as 'invalid CA certificate', and every client certificate test
failed. Add basicConstraints CA:TRUE to test.rootCA.conf, drop the version
branching, and verify the client certs against the root in gen-certs.sh.
close() waited for the peer's Close reply with a read timeout that
applied to each read, so a peer that kept sending other frames, or sent
one frame a byte at a time, held close() for as long as it liked.
Bound the wait as a whole. close() sets the stream's max timeout, which
shortens each wait to what is left, and stops reading frames at the
deadline, which matters when the peer keeps the socket full and no wait
happens at all. WebSocketSSLStream gains set_max_timeout(), the one
stream a WebSocket uses that lacked it.
A read() running on another thread when close() is called still waits
for the reply up to its own read timeout, as documented. The docs now
say how to bound it.
Server::process_and_close_socket() half-closes the socket and drains what
the peer is still sending before the final close (#2534), so that a close
with unread data, or with bytes still in flight, is not answered with a
RST. A RST can make the peer's stack discard a response it has received
but not yet read, as Windows does.
SSLServer::process_and_close_socket() still closed outright. After a
completed handshake, shut down TLS as before (sending close_notify when
the exchange completed) and then drain the same way. A failed handshake
closes outright as before.
Fix#2672
A kept-alive connection was reused while bytes that belong to no
request were waiting on it, and the next request read them as its
response. Such bytes are not a response (RFC 9112 9.2). A server may,
for one, send a 408 before it closes an idle connection.
Close the connection when they show up: after a response, if bytes
past it are already buffered in the stream or the TLS library, and
before reuse, if anything is readable on the socket. As in curl, the
reuse check no longer asks the TLS library whether the peer closed, so
it is the same for every TLS backend. A TLS message on an idle
connection, such as a late session ticket, now costs a new connection.
SSLClient::setup_proxy_connection() left the socket open when the TLS
handshake inside the CONNECT tunnel failed, so the client kept a
connection with no TLS session on it. Only the next request's reuse
check closed it, because tls::is_peer_closed() reports a missing
session as closed. Close it where the handshake fails, as
ensure_socket_connection() does for a direct connection.
* take the request lock in open_stream_ before reusing the socket
* Hold the request lock only while open_stream_ takes the socket
The handle owns the connection once the socket is transferred to it, so
holding request_mutex_ while the stream wrote its request and read the
response head only made requests on other threads wait for the stream.
Also shorten the comments.
---------
Co-authored-by: yhirose <yuji.hirose.bug@gmail.com>
* resolve junctions and symlinks in canonicalize_path on Windows
* Shorten the canonicalize_path comment
---------
Co-authored-by: yhirose <yuji.hirose.bug@gmail.com>
Fuzz Server::handle_file_request through a mount point backed by a temporary directory that holds symlinks escaping the mount root, one of them into a sibling directory sharing its name prefix. Abort if a token stored outside the root appears in a response. The seeds are based on those of #2661.
Move FuzzedStream into fuzzed_stream.h so that both server fuzzers share it, and add FuzzableServer::MarkAsRunning(), without which a server that is not listening writes no file.
Feed the event stream to the parser in chunks and abort if the reported events, ids and retries differ from parsing it in one piece. Also run with a length limit to cover the early-stop path.
Add websocket_fuzzer covering frame reading, UTF-8 and close payload validation, and the upgrade response parser. Add websocket_fuzzer.options to raise max_len above the 64 KiB frame length boundary.
Move the SSE parsing tests from a fixture that started a server and an
SSEClient for every case to unit tests of detail::SSEParser, and turn
NonDigitRetryFieldIgnored, which slept for 500ms, into one of them. Add
tests that feed each stream split at every position and byte by byte,
and that cover the max event length and an event left incomplete at the
end of the stream.
Move the line splitting and event assembly out of
SSEClient::run_event_loop() into a parser that is fed chunks and reports
events, ids and retry values through handlers. The event loop is left
with I/O and reconnection, and the parser can be driven without a
server, which the following test and fuzzer changes rely on.
No behavior change.
ThreadPool::enqueue constructed the dynamic thread without handling
std::system_error. When thread creation failed (e.g. EAGAIN under a
pids limit), the exception escaped the accept loop and destroying the
pool's joinable threads called std::terminate. Treat the failure as
"no spare capacity" and leave the job for an existing worker.
A client using set_address_family(AF_UNIX) took the host of an absolute Location as a socket path, so a redirect to http://localhost/next failed and one to http://other.sock/next went to ./other.sock. Every hop now stays on the client's socket, as with curl's --unix-socket.
The same host is still decided from the Location, as curl does: only localhost (the Host this client sends) counts as this client, so a redirect to any other host goes through the cross-host client and drops Authorization and Cookie. That client reaches the original socket through addr_map_, and a host the caller mapped with set_direct_hostname_addr_map keeps its mapping. An https Location runs TLS over the socket with the Location's host.
The mapped-target lookup shared with make_connect_request_target is factored into detail::addr_map_target.
A request sent with send(Request) and params got those params appended
to the Location of a redirect that had no query, on the same origin or
another one. The Location alone names the next target, as it already
did for Get/Post(path, params).
RFC 9110 14.2 says an origin server MUST ignore a Range header field
with a range unit it does not understand. parse_range_header() accepts
only bytes=, so a request such as "Range: items=1-2" got a 416 instead
of the full response. The unit is now checked first, and only a bytes
range is parsed and answered with a 416 when it is invalid.
* Cap a send() or wolfSSL_read() length at INT_MAX
On 64-bit Windows SocketStream::write() handed size to send(), whose
length is an int, so a single write of 4 GiB or more went out as its low
32 bits: a 4 GiB + 1 byte write sent one byte, and write_data() then
retried the remaining 4 GiB as zero-byte sends forever. The INT_MAX cap
that read() has was limited to 32-bit Windows in df20c27 (#1294), when
the body was still written with one unchecked write(); write_data() now
sends the rest, so the cap applies to every Windows build again.
The wolfSSL tls::read() had the same cast, so a read into a buffer over
INT_MAX failed. Cap it as the OpenSSL backend has done since f80864c.
* Drop the 4 GiB write test and shorten comments
The Windows-only test allocated 4 GiB and took about 5 s, which is too
heavy for CI.
---------
Co-authored-by: yhirose <yuji.hirose.bug@gmail.com>
* keep a relative Location on its host in resolve_relative_location
* Shorten the comment on on_this_host in resolve_relative_location
---------
Co-authored-by: yhirose <yuji.hirose.bug@gmail.com>
stop() shuts the socket down to end a request in flight, but on Windows
that does not wake a read waiting in WSAPoll (#1396). The request then
waited until the server answered, the read timeout passed, or the OS
dropped the connection.
stop() now also sets a flag, and send_() gives the request's stream an
interrupt check that reads it, as SSEClient::stop() does since 801bf2e.
The wait for data then ends within 100 ms on every platform. A request
started after stop() clears the flag. A redirect or a digest retry sent
inside the request keeps it.
select_read_interruptible() now rounds its last wait up to a whole
millisecond. poll() takes milliseconds, and the wait ended up to 1 ms
before the deadline, which MaxTimeoutTest caught once every client
request waited through this function.
2026-10-30 13:40:50 -04:00
37 changed files with 4827 additions and 954 deletions
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))`.
`Timeout` is only returned for a read timeout you set yourself with `set_read_timeout()`. It means the timeout elapsed and the connection is still open, so you can send on it and read again. It can land anywhere, inside a message too: what was read of the message is kept, and the next `read()` goes on from there. 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:
| `CPPHTTPLIB_WEBSOCKET_MAX_MISSED_PONGS` | `0` (disabled) | Close the connection after N consecutive unacked pings |
| `CPPHTTPLIB_WEBSOCKET_TCP_NODELAY` | `true` | Set TCP_NODELAY on WebSocket connections, so small messages do not wait on Nagle's algorithm |
### Runtime Ping Interval
@@ -568,7 +572,7 @@ Choose sizes that account for both your expected HTTP load and the maximum numbe
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.
**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. That thread's `read()` keeps waiting for the reply until its own read timeout (by default none on a client, 300 seconds on a server); to bound it, set one with `set_read_timeout()` before the read starts. 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.
`WebSocketClient` does not use CryptoAPI; the TLS backend always verifies its chain.
`WebSocketClient` verifies the same way and has the same `enable_windows_certificate_verification()`.
> [!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.
@@ -919,6 +919,23 @@ svr.set_keep_alive_max_count(2); // Default is 100, 0 for no limit
svr.set_keep_alive_timeout(10);// Default is 5
```
#### Keep-alive parking
```cpp
svr.set_keep_alive_parking(true);// Call it before listen()
```
By default, a kept-alive connection holds a worker thread while it waits for its next request, so connections beyond the thread count wait for one to be closed. With keep-alive parking, a connection waiting for its next request is handed to an event loop instead, and goes back to a worker when the request arrives. An idle connection then costs a socket and a few kilobytes instead of a thread, and connections that outnumber the threads take turns.
With it:
- Consecutive requests on a connection may run on different threads.
- When the [max queued requests](#max-queued-requests) limit is reached, only a connection that has not been served yet (or, with `SSLServer`, has not finished its TLS handshake) is closed. An established one waits for room.
- Handing the connection over to a worker adds roughly 10-20 µs to each request. It only shows when the client is as near as loopback and the handlers are very light: in our measurements, 2 connections on 2 threads served about a third fewer requests per second over loopback, but only a few percent fewer with a 250 µs round trip.
- A handler, a content provider and a WebSocket still hold their thread while they run.
- A subclass that overrides the private `process_and_close_socket()` is bypassed.
-`SSLServer` runs the TLS handshake on a worker when the client starts it. Until then the connection waits in the event loop and is closed at the keep-alive timeout, not the read timeout, and `ssl_last_error()` is not set for it.
### Client address behind a reverse proxy
```cpp
@@ -962,7 +979,7 @@ Please see [Server example](https://github.com/yhirose/cpp-httplib/blob/master/e
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.
A connection holds its thread while it is served: between requests up to the keep-alive timeout (unless [keep-alive parking](#keep-alive-parking) is on), 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:
@@ -1172,7 +1189,7 @@ 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.
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. One passed with the request is dropped when the library compresses the body or sends it chunked. 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.
This library automatically sets the Host header to "localhost" for Unix socket connections, similar to curl's behavior.
With `set_follow_location(true)`, a redirect is followed over the same socket, whatever host the `Location` names, as curl's `--unix-socket` does. A host mapped with `set_direct_hostname_addr_map` goes to its mapped socket instead. Only a `Location` naming `localhost` counts as the same host; any other host is treated as cross-host, so `Authorization` and `Cookie` are not sent to it.
@@ -56,4 +56,4 @@ When you call `stop()`, new connections are refused, but handlers that are alrea
> **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`.
> **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`. The handler's `read()` then waits for the peer's Close reply up to its read timeout (300 seconds by default). To shorten that, call `set_read_timeout()` in the handler before the loop; `read()` then also returns `Timeout` whenever the peer stays idle that long, so the loop has to handle it.
Shorten the timeout so idle connections drop and release their worker threads.
Shorten the timeout so idle connections drop and release their worker threads. If you want to keep them open, turn on keep-alive parking instead (see below).
```cpp
svr.set_keep_alive_timeout(2s);
@@ -52,6 +52,22 @@ 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. 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).
By default, 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).
## Keep idle connections off the threads
```cpp
svr.set_keep_alive_parking(true);// call it before listen()
```
With keep-alive parking, a connection waiting for its next request is handed to an event loop instead of keeping its worker thread, and goes back to a worker when the request arrives. An idle connection then costs a socket and some memory (a few kilobytes, more with TLS) instead of a thread, and connections that outnumber the threads take turns instead of waiting for one to close. `SSLServer` supports it too.
What changes with it:
- Consecutive requests on one connection may run on different threads, so don't keep per-connection state in `thread_local` variables.
- Handing the connection over to a worker adds roughly 10-20 µs to each request. It only shows with very light handlers and a client as near as loopback.
- A handler, a content provider and a WebSocket still hold their thread while they run.
The full list is in the [README](https://github.com/yhirose/cpp-httplib/blob/master/README.md#keep-alive-parking).
> **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.
`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.
`set_read_timeout()` applies to a single `read()` call. If no whole message arrives within that time, `read()` returns `ReadResult::Timeout`: **the connection is still open**, and what was read of a message is kept for the next `read()`, 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:
@@ -67,7 +67,7 @@ Without a read timeout, `read()` blocks until a message arrives, so the thread h
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`.
- It can land anywhere, partway through a message too. What was read of the message is kept, and the next `read()` goes on from there, so a message that arrives slowly or in fragments still comes out whole.
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.