mirror of
https://github.com/yhirose/cpp-httplib.git
synced 2026-10-19 11:19:36 +00:00
Fix README and docs pages that no longer match the code
Bring the READMEs and the docs pages (en and ja) in line with the current header: - Fix the client sample that does not compile, the Transfer-Encoding statement for default headers, the verifier callback comment, the thread pool spawn rule, the sanitize_filename description, and the inverted Accept-Encoding sentence. - Describe recent behaviour: TLS errors behind Read/Write failures, Host validation, Connection: close for a body without length, content_reader rules, refused CONNECT, WebSocketClient proxies, CPPHTTPLIB_INTERIM_RESPONSE_MAX_COUNT, the SSE event size limit, and the payload limit of the Stream API. - Complete the API references of WebSocket, WebSocketClient and the stream:: helpers, and the SSE reconnect rules. - Fix cookbook pages: keychain loading on every backend, received Close status, a multipart sample that trusted the client's file name, an echo sample that sent binary as text, SNI, pre-request handler scope, stop() with WebSocket handlers, and the thread pool notes. - Restore the mutex in the LLM app's Chapter 5 code.
This commit is contained in:
1 parent
94cf1b5c9a
commit
9bfd2ddf1c
77 files changed
+378
-145
No files matched your search
+39
-2
@@ -14,7 +14,7 @@ The streaming API allows you to process HTTP response bodies chunk by chunk usin
|
||||
|
||||
- **LLM/AI streaming responses** (e.g., ChatGPT, Claude, Ollama)
|
||||
- **Server-Sent Events (SSE)**
|
||||
- **Large file downloads** with progress tracking
|
||||
- **Large file downloads** with progress tracking (mind the [payload size limit](#payload-size-limit))
|
||||
- **Reverse proxy implementations**
|
||||
|
||||
## Quick Start
|
||||
@@ -62,7 +62,7 @@ cpp-httplib provides multiple API layers for different use cases:
|
||||
| Use Case | Recommended API |
|
||||
|----------|----------------|
|
||||
| SSE with auto-reconnect | `SSEClient` (see [README-sse.md](README-sse.md)) |
|
||||
| LLM streaming (JSON Lines) | `stream::Get()` |
|
||||
| LLM streaming (JSON Lines) | `stream::Post()` or `stream::Get()` |
|
||||
| Large file download | `stream::Get()` or `open_stream()` |
|
||||
| Reverse proxy | `open_stream()` |
|
||||
| Small responses with Keep-Alive | `Client::Get()` |
|
||||
@@ -106,6 +106,8 @@ if (handle.is_valid()) {
|
||||
| `get_read_error()` | `Error` | Get the last read error |
|
||||
| `has_read_error()` | `bool` | Check if a read error occurred |
|
||||
|
||||
For a chunked response, the trailers are in `response->trailers` once `read()` has reached the end of the body.
|
||||
|
||||
### High-Level API: `stream::Get()` and `stream::Result`
|
||||
|
||||
The `httplib.h` header provides a more ergonomic iterator-style API.
|
||||
@@ -137,6 +139,30 @@ if (result2) {
|
||||
}
|
||||
```
|
||||
|
||||
#### Helpers
|
||||
|
||||
There is a helper for each HTTP method. The arguments in brackets can be left out, and every helper takes a trailing `size_t chunk_size = 8192`, the most bytes one `next()` returns.
|
||||
|
||||
| Helper | Arguments |
|
||||
|--------|-----------|
|
||||
| `stream::Get()` | `(cli, path, [params], [headers], [chunk_size])` |
|
||||
| `stream::Head()` | `(cli, path, [params], [headers], [chunk_size])` |
|
||||
| `stream::Options()` | `(cli, path, [params], [headers], [chunk_size])` |
|
||||
| `stream::Post()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
|
||||
| `stream::Put()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
|
||||
| `stream::Patch()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
|
||||
| `stream::Delete()` | `(cli, path, [params], [headers], [chunk_size])` |
|
||||
| `stream::Delete()` | `(cli, path, [params], [headers], body, content_type, [chunk_size])` |
|
||||
|
||||
`params` is a `Params`, `headers` a `Headers`, and `body` and `content_type` are `std::string`s.
|
||||
|
||||
```cpp
|
||||
// POST a JSON body and stream the response in 4KB chunks
|
||||
auto result3 = httplib::stream::Post(cli, "/api/generate", headers,
|
||||
R"({"prompt": "hello"})",
|
||||
"application/json", 4096);
|
||||
```
|
||||
|
||||
#### stream::Result Members
|
||||
|
||||
| Member | Type | Description |
|
||||
@@ -216,6 +242,7 @@ int main() {
|
||||
|
||||
int main() {
|
||||
httplib::Client cli("http://example.com");
|
||||
cli.set_payload_max_length(0); // No limit (the default is 100MB)
|
||||
auto result = httplib::stream::Get(cli, "/large-file.zip");
|
||||
|
||||
if (!result || result.status() != 200) {
|
||||
@@ -232,6 +259,12 @@ int main() {
|
||||
std::cout << "\rDownloaded: " << (total / 1024) << " KB" << std::flush;
|
||||
}
|
||||
|
||||
if (result.has_read_error()) {
|
||||
std::cerr << "\nDownload failed: "
|
||||
<< httplib::to_string(result.read_error()) << "\n";
|
||||
return 1;
|
||||
}
|
||||
|
||||
std::cout << "\nComplete!\n";
|
||||
return 0;
|
||||
}
|
||||
@@ -316,6 +349,10 @@ while (result.next()) { /* ... */ }
|
||||
auto res = cli.Get("/api/data"); // Connection can be reused
|
||||
```
|
||||
|
||||
### Payload Size Limit
|
||||
|
||||
`open_stream()` and the `stream::` helpers apply the client's `set_payload_max_length()` (100MB by default, `CPPHTTPLIB_PAYLOAD_MAX_LENGTH`) to the body, both as received and after decompression. Past the limit, `read()` and `next()` stop, and the read error is `Error::ExceedMaxPayloadSize`. To download something larger, raise the limit, or call `cli.set_payload_max_length(0)` for no limit.
|
||||
|
||||
## Related
|
||||
|
||||
- [Issue #2269](https://github.com/yhirose/cpp-httplib/issues/2269) - Original feature request
|
||||
|
||||
Reference in new issue
Block a user