Refactor streaming API: Replace open_stream_direct() with open_stream() and update related tests

Author: yhirose

README20.md

@@ -1,10 +1,10 @@
 # cpp-httplib C++20 Streaming API
 
-This document describes the C++20 streaming extensions for cpp-httplib, providing a generator-like API for handling HTTP responses incrementally.
+This document describes the C++20 streaming extensions for cpp-httplib, providing a generator-like API for handling HTTP responses incrementally with **true socket-level streaming**.
 
 ## Overview
 
-The C++20 streaming API allows you to process HTTP response bodies chunk by chunk using C++20 coroutines, similar to Python's generators or C++23's `std::generator`. This is particularly useful for:
+The C++20 streaming API allows you to process HTTP response bodies chunk by chunk using C++20 coroutines, similar to Python's generators or C++23's `std::generator`. Data is read directly from the network socket, enabling low-memory processing of large responses. This is particularly useful for:
 
 - **LLM/AI streaming responses** (e.g., ChatGPT, Claude, Ollama)
 - **Server-Sent Events (SSE)**
@@ -42,10 +42,12 @@ int main() {
 
 ### Low-Level API: `StreamHandle`
 
-The `StreamHandle` struct provides direct control over streaming responses.
+The `StreamHandle` struct provides direct control over streaming responses. It takes ownership of the socket connection and reads data directly from the network.
+
+> **Note:** When using `open_stream()`, the connection is dedicated to streaming and **Keep-Alive is not supported**. For Keep-Alive connections, use `client.Get()` instead.
 
 ```cpp
-// Open a stream
+// Open a stream (takes ownership of socket)
 httplib::Client cli("http://localhost:8080");
 auto handle = cli.open_stream("/path");
 
@@ -74,7 +76,8 @@ if (handle.is_valid()) {
 | `response` | `std::unique_ptr<Response>` | HTTP response with headers |
 | `error` | `Error` | Error code if request failed |
 | `is_valid()` | `bool` | Returns true if response is valid |
-| `read(buf, len)` | `ssize_t` | Read up to `len` bytes, returns bytes read (0 at EOF, -1 on error) |
+| `is_socket_direct_mode()` | `bool` | Returns true (always direct socket reading) |
+| `read(buf, len)` | `ssize_t` | Read up to `len` bytes directly from socket |
 | `read_all()` | `std::string` | Read all remaining content |
 
 ### High-Level API: `GetStream()` and `StreamingResult`
@@ -257,20 +260,39 @@ int main() {
 | Feature | `Client::Get()` | `open_stream()` | `GetStream()` |
 |---------|----------------|-----------------|---------------|
 | Headers available | After complete | Immediately | Immediately |
-| Body reading | All at once | Incremental | Generator-based |
-| Memory usage | Full body in RAM | Controlled | Controlled |
+| Body reading | All at once | Direct from socket | Generator-based |
+| Memory usage | Full body in RAM | Minimal (controlled) | Minimal (controlled) |
+| Keep-Alive support | ✅ Yes | ❌ No | ❌ No |
+| Compression | Auto-handled | Auto-handled | Auto-handled |
 | C++ standard | C++11 | C++11 | C++20 |
-| Best for | Small responses | Low-level control | Modern streaming |
+| Best for | Small responses, Keep-Alive | Low-level streaming | Modern streaming |
+
+## Features
+
+- **True socket-level streaming**: Data is read directly from the network socket
+- **Low memory footprint**: Only the current chunk is held in memory
+- **Compression support**: Automatic decompression for gzip, brotli, and zstd
+- **Chunked transfer**: Full support for chunked transfer encoding
+- **SSL/TLS support**: Works with HTTPS connections
+- **C++23 ready**: `Generator<T>` is compatible with `std::generator` interface
+
+## Important Notes
 
-## Current Limitations
+### Keep-Alive Behavior
 
-> **Note:** The current implementation loads the entire response body into memory before streaming. True socket-level streaming (reading directly from the network) is planned for a future release.
+The streaming API (`GetStream()` / `open_stream()`) takes ownership of the socket connection for the duration of the stream. This means:
 
-This means:
+- **Keep-Alive is not supported** for streaming connections
+- The socket is closed when `StreamHandle` is destroyed
+- For Keep-Alive scenarios, use the standard `client.Get()` API instead
 
-- Memory usage is similar to `Client::Get()` for now
-- The API is ready for future optimization
-- Useful for header-first processing and chunked iteration patterns
+```cpp
+// Use for streaming (no Keep-Alive)
+auto stream = httplib::GetStream(cli, "/large-stream");
+
+// Use for Keep-Alive connections
+auto result = cli.Get("/api/data");  // Connection can be reused
+```
 
 ## Building
 

httplib.h

@@ -1674,14 +1674,10 @@ class ClientImpl {
   // clang-format on
 
   // Streaming API: Open a stream for reading response body incrementally
+  // Socket ownership is transferred to StreamHandle for true streaming
   StreamHandle open_stream(const std::string &path);
   StreamHandle open_stream(const std::string &path, const Headers &headers);
 
-  // True streaming API: Socket ownership transferred to StreamHandle
-  StreamHandle open_stream_direct(const std::string &path);
-  StreamHandle open_stream_direct(const std::string &path,
-                                  const Headers &headers);
-
   bool send(Request &req, Response &res, Error &error);
   Result send(const Request &req);
 
@@ -2051,15 +2047,11 @@ class Client {
   // clang-format on
 
   // Streaming API: Open a stream for reading response body incrementally
+  // Socket ownership is transferred to StreamHandle for true streaming
   ClientImpl::StreamHandle open_stream(const std::string &path);
   ClientImpl::StreamHandle open_stream(const std::string &path,
                                        const Headers &headers);
 
-  // True streaming API: Socket ownership transferred to StreamHandle
-  ClientImpl::StreamHandle open_stream_direct(const std::string &path);
-  ClientImpl::StreamHandle open_stream_direct(const std::string &path,
-                                              const Headers &headers);
-
   bool send(Request &req, Response &res, Error &error);
   Result send(const Request &req);
 
@@ -9328,31 +9320,6 @@ ClientImpl::open_stream(const std::string &path) {
 inline ClientImpl::StreamHandle
 ClientImpl::open_stream(const std::string &path, const Headers &headers) {
   StreamHandle handle;
-
-  Request req;
-  req.method = "GET";
-  req.path = path;
-  req.headers = headers;
-
-  // Use content_receiver to receive body into response
-  handle.response = detail::make_unique<Response>();
-  handle.error = Error::Success;
-
-  auto ret = send(req, *handle.response, handle.error);
-  if (!ret) { handle.response.reset(); }
-
-  return handle;
-}
-
-inline ClientImpl::StreamHandle
-ClientImpl::open_stream_direct(const std::string &path) {
-  return open_stream_direct(path, Headers{});
-}
-
-inline ClientImpl::StreamHandle
-ClientImpl::open_stream_direct(const std::string &path,
-                               const Headers &headers) {
-  StreamHandle handle;
   handle.response = detail::make_unique<Response>();
   handle.error = Error::Success;
 
@@ -12733,15 +12700,6 @@ inline ClientImpl::StreamHandle Client::open_stream(const std::string &path,
   return cli_->open_stream(path, headers);
 }
 
-inline ClientImpl::StreamHandle
-Client::open_stream_direct(const std::string &path) {
-  return cli_->open_stream_direct(path);
-}
-inline ClientImpl::StreamHandle
-Client::open_stream_direct(const std::string &path, const Headers &headers) {
-  return cli_->open_stream_direct(path, headers);
-}
-
 inline bool Client::send(Request &req, Response &res, Error &error) {
   return cli_->send(req, res, error);
 }

httplib20.h

@@ -7,26 +7,67 @@
 //  Copyright (c) 2025 Yuji Hirose. All rights reserved.
 //  MIT License
 //
+//  C++23 Migration Notes:
+//  ----------------------
+//  When C++23 is adopted, this header can be simplified:
+//  - Replace custom Generator<T> with std::generator<T> from <generator>
+//  - The Generator interface is designed to be compatible with std::generator
+//  - StreamingResult and GetStream() can remain unchanged
+//
 
 #ifndef CPPHTTPLIB_HTTPLIB20_H
 #define CPPHTTPLIB_HTTPLIB20_H
 
+// Version check: requires C++20 or later
 #if __cplusplus < 202002L
 #error "httplib20.h requires C++20 or later"
 #endif
 
 #include "httplib.h"
+
 #include <coroutine>
 #include <cstring>
 #include <iterator>
 #include <string_view>
 #include <utility>
 
+// C++23 feature detection for std::generator
+// When available, prefer std::generator over custom implementation
+#if defined(__cpp_lib_generator) && __cpp_lib_generator >= 202207L
+#include <generator>
+#define CPPHTTPLIB_USE_STD_GENERATOR 1
+#endif
+
 namespace httplib {
 
 //------------------------------------------------------------------------------
-// Generator<T> - A C++20 coroutine-based generator (similar to std::generator)
+// Generator<T> - A C++20 coroutine-based generator
 //------------------------------------------------------------------------------
+//
+// This is a simplified implementation compatible with C++23's std::generator.
+// Key features:
+//   - Lazy evaluation: values computed on-demand
+//   - Range-based for loop support via iterators
+//   - Move-only semantics (non-copyable)
+//   - Exception propagation from coroutine body
+//
+// Usage:
+//   Generator<int> range(int start, int end) {
+//     for (int i = start; i < end; ++i) {
+//       co_yield i;
+//     }
+//   }
+//
+//   for (int value : range(0, 10)) {
+//     std::cout << value << '\n';
+//   }
+//
+// C++23 Migration:
+//   Replace with: using Generator = std::generator;
+//   Or: #include <generator> and use std::generator directly
+//
+
+#ifndef CPPHTTPLIB_USE_STD_GENERATOR
 
 template <typename T> class Generator {
 public:
@@ -102,10 +143,11 @@ template <typename T> class Generator {
     Handle handle_;
   };
 
+  // Constructors
   Generator() noexcept : handle_(nullptr) {}
-
   explicit Generator(Handle handle) noexcept : handle_(handle) {}
 
+  // Move-only semantics
   Generator(Generator &&other) noexcept : handle_(other.handle_) {
     other.handle_ = nullptr;
   }
@@ -126,6 +168,7 @@ template <typename T> class Generator {
     if (handle_) { handle_.destroy(); }
   }
 
+  // Range interface
   Iterator begin() {
     if (handle_) {
       handle_.resume();
@@ -146,13 +189,21 @@ template <typename T> class Generator {
   Handle handle_;
 };
 
+#else // CPPHTTPLIB_USE_STD_GENERATOR
+
+// C++23: Use std::generator directly
+template <typename T> using Generator = std::generator<T>;
+
+#endif // CPPHTTPLIB_USE_STD_GENERATOR
+
 //------------------------------------------------------------------------------
 // Streaming client functions using Generator
 //------------------------------------------------------------------------------
 
 namespace detail {
 
 // Coroutine that yields chunks from StreamHandle
+// Works with both memory buffer mode and socket direct mode
 inline Generator<std::string_view> stream_body(ClientImpl::StreamHandle handle,
                                                size_t chunk_size = 8192) {
   if (!handle.is_valid()) { co_return; }
@@ -168,8 +219,20 @@ inline Generator<std::string_view> stream_body(ClientImpl::StreamHandle handle,
 } // namespace detail
 
 //------------------------------------------------------------------------------
-// StreamingResult - Wrapper for streaming response with Generator support
+// StreamingResult - High-level wrapper for streaming HTTP responses
 //------------------------------------------------------------------------------
+//
+// Provides a convenient interface for streaming HTTP response bodies.
+// Supports both memory-buffered and socket-direct streaming modes.
+//
+// Usage:
+//   auto result = httplib::GetStream(client, "/large-file");
+//   if (result) {
+//     for (auto chunk : result.body()) {
+//       process(chunk);
+//     }
+//   }
+//
 
 class StreamingResult {
 public:
@@ -178,17 +241,17 @@ class StreamingResult {
   explicit StreamingResult(ClientImpl::StreamHandle &&handle)
       : handle_(std::move(handle)) {}
 
+  // Move-only semantics
   StreamingResult(StreamingResult &&) = default;
   StreamingResult &operator=(StreamingResult &&) = default;
-
   StreamingResult(const StreamingResult &) = delete;
   StreamingResult &operator=(const StreamingResult &) = delete;
 
-  // Check if result is valid
+  // Validity check
   bool is_valid() const { return handle_.is_valid(); }
   explicit operator bool() const { return is_valid(); }
 
-  // Access response metadata
+  // Response metadata access
   int status() const {
     return handle_.response ? handle_.response->status : -1;
   }
@@ -210,26 +273,43 @@ class StreamingResult {
 
   Error error() const { return handle_.error; }
 
-  // Get body as Generator for streaming reads
+  // Get read error (socket direct mode only)
+  Error read_error() const { return handle_.get_read_error(); }
+
+  // Streaming body access - returns Generator for lazy iteration
   Generator<std::string_view> body(size_t chunk_size = 8192) {
     return detail::stream_body(std::move(handle_), chunk_size);
   }
 
   // Read entire body at once (convenience method)
-  std::string read_all() {
-    if (!handle_.is_valid()) { return {}; }
-    return handle_.response ? std::move(handle_.response->body) : std::string{};
-  }
+  // Note: For large responses, prefer body() for memory efficiency
+  std::string read_all() { return handle_.read_all(); }
 
 private:
   ClientImpl::StreamHandle handle_;
 };
 
 //------------------------------------------------------------------------------
-// Free functions for streaming requests
+// Free functions for streaming HTTP requests
 //------------------------------------------------------------------------------
+//
+// GetStream reads response body directly from the socket without buffering
+// the entire response in memory. This is ideal for:
+//   - Large file downloads
+//   - Server-Sent Events (SSE)
+//   - Any streaming API
+//
+// Note: The connection is not reused (Keep-Alive disabled) since socket
+// ownership is transferred to StreamHandle. For repeated small requests
+// where connection reuse matters, use client.Get() instead.
+//
+// Usage:
+//   auto result = httplib::GetStream(client, "/huge-file");
+//   for (auto chunk : result.body()) {
+//     write_to_file(chunk);
+//   }
+//
 
-// GET request with streaming response
 inline StreamingResult GetStream(Client &cli, const std::string &path) {
   return StreamingResult{cli.open_stream(path)};
 }
@@ -239,7 +319,7 @@ inline StreamingResult GetStream(Client &cli, const std::string &path,
   return StreamingResult{cli.open_stream(path, headers)};
 }
 
-// Overloads for ClientImpl
+// Overloads for ClientImpl (direct use without Client wrapper)
 inline StreamingResult GetStream(ClientImpl &cli, const std::string &path) {
   return StreamingResult{cli.open_stream(path)};
 }