Add ClientConnection and BodyReader structs with tests for socket streaming

Author: yhirose

httplib.h

@@ -1390,6 +1390,72 @@ class Result {
 #endif
 };
 
+// ClientConnection: Represents ownership of a socket connection
+// Used for true streaming where StreamHandle owns the connection
+struct ClientConnection {
+  socket_t sock = INVALID_SOCKET;
+#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
+  SSL *ssl = nullptr;
+#endif
+
+  bool is_open() const { return sock != INVALID_SOCKET; }
+
+  // Move-only semantics
+  ClientConnection() = default;
+  ~ClientConnection() = default;
+
+  ClientConnection(const ClientConnection &) = delete;
+  ClientConnection &operator=(const ClientConnection &) = delete;
+
+  ClientConnection(ClientConnection &&other) noexcept
+      : sock(other.sock)
+#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
+        ,
+        ssl(other.ssl)
+#endif
+  {
+    other.sock = INVALID_SOCKET;
+#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
+    other.ssl = nullptr;
+#endif
+  }
+
+  ClientConnection &operator=(ClientConnection &&other) noexcept {
+    if (this != &other) {
+      sock = other.sock;
+#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
+      ssl = other.ssl;
+#endif
+      other.sock = INVALID_SOCKET;
+#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
+      other.ssl = nullptr;
+#endif
+    }
+    return *this;
+  }
+};
+
+namespace detail {
+
+// BodyReader: Manages incremental reading of HTTP response body
+// Supports both Content-Length and chunked transfer encoding
+struct BodyReader {
+  Stream *stream = nullptr;
+  size_t content_length = 0;
+  size_t bytes_read = 0;
+  bool chunked = false;
+  bool eof = false;
+
+  // For chunked encoding
+  size_t current_chunk_remaining = 0;
+
+  // Read up to len bytes into buf
+  // Returns bytes read, 0 on EOF, -1 on error
+  ssize_t read(char *buf, size_t len);
+};
+
+} // namespace detail
+
 class ClientImpl {
 public:
   explicit ClientImpl(const std::string &host);
@@ -1406,41 +1472,67 @@ class ClientImpl {
 
   // Streaming handle for reading response body incrementally
   struct StreamHandle {
+    // Common fields
     std::unique_ptr<Response> response;
     Error error = Error::Success;
+
+    // Mode 1: Memory buffer (existing behavior)
     size_t read_offset_ = 0;
 
+    // Mode 2: Socket direct (true streaming)
+    std::unique_ptr<ClientConnection> connection_; // Socket ownership
+    Stream *stream_ = nullptr;                     // Stream for reading
+    detail::BodyReader body_reader_;               // Body reading state
+
     bool is_valid() const {
       return response != nullptr && error == Error::Success;
     }
 
+    // Check if using socket direct mode (true streaming)
+    bool is_socket_direct_mode() const { return stream_ != nullptr; }
+
     // Read up to len bytes into buf, returns number of bytes read (0 at EOF)
-    // NOTE: Current implementation reads from pre-loaded response body.
-    // TODO: Implement true streaming by reading directly from socket stream
-    //       to support large responses without loading entire body into memory.
     ssize_t read(char *buf, size_t len) {
       if (!is_valid() || !response) { return -1; }
 
-      const auto &body = response->body;
-      if (read_offset_ >= body.size()) { return 0; }
-
-      auto remaining = body.size() - read_offset_;
-      auto to_read = (std::min)(len, remaining);
-      std::memcpy(buf, body.data() + read_offset_, to_read);
-      read_offset_ += to_read;
-      return static_cast<ssize_t>(to_read);
+      if (is_socket_direct_mode()) {
+        // Socket direct mode: read from stream via BodyReader
+        return body_reader_.read(buf, len);
+      } else {
+        // Memory buffer mode: read from pre-loaded response body
+        const auto &body = response->body;
+        if (read_offset_ >= body.size()) { return 0; }
+
+        auto remaining = body.size() - read_offset_;
+        auto to_read = (std::min)(len, remaining);
+        std::memcpy(buf, body.data() + read_offset_, to_read);
+        read_offset_ += to_read;
+        return static_cast<ssize_t>(to_read);
+      }
     }
 
     // Read all remaining content into a string
     std::string read_all() {
       if (!is_valid() || !response) { return {}; }
 
-      const auto &body = response->body;
-      if (read_offset_ >= body.size()) { return {}; }
+      if (is_socket_direct_mode()) {
+        // Socket direct mode: read all from stream
+        std::string result;
+        char buf[8192];
+        ssize_t n;
+        while ((n = body_reader_.read(buf, sizeof(buf))) > 0) {
+          result.append(buf, static_cast<size_t>(n));
+        }
+        return result;
+      } else {
+        // Memory buffer mode
+        const auto &body = response->body;
+        if (read_offset_ >= body.size()) { return {}; }
 
-      auto result = body.substr(read_offset_);
-      read_offset_ = body.size();
-      return result;
+        auto result = body.substr(read_offset_);
+        read_offset_ = body.size();
+        return result;
+      }
     }
   };
 
@@ -3427,68 +3519,6 @@ inline bool is_socket_alive(socket_t sock) {
   return detail::read_socket(sock, &buf[0], sizeof(buf), MSG_PEEK) > 0;
 }
 
-// ClientConnection: Represents ownership of a socket connection
-// Used for true streaming where StreamHandle owns the connection
-struct ClientConnection {
-  socket_t sock = INVALID_SOCKET;
-#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
-  SSL *ssl = nullptr;
-#endif
-
-  bool is_open() const { return sock != INVALID_SOCKET; }
-
-  // Move-only semantics
-  ClientConnection() = default;
-  ~ClientConnection() = default;
-
-  ClientConnection(const ClientConnection &) = delete;
-  ClientConnection &operator=(const ClientConnection &) = delete;
-
-  ClientConnection(ClientConnection &&other) noexcept
-      : sock(other.sock)
-#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
-        ,
-        ssl(other.ssl)
-#endif
-  {
-    other.sock = INVALID_SOCKET;
-#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
-    other.ssl = nullptr;
-#endif
-  }
-
-  ClientConnection &operator=(ClientConnection &&other) noexcept {
-    if (this != &other) {
-      sock = other.sock;
-#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
-      ssl = other.ssl;
-#endif
-      other.sock = INVALID_SOCKET;
-#ifdef CPPHTTPLIB_OPENSSL_SUPPORT
-      other.ssl = nullptr;
-#endif
-    }
-    return *this;
-  }
-};
-
-// BodyReader: Manages incremental reading of HTTP response body
-// Supports both Content-Length and chunked transfer encoding
-struct BodyReader {
-  Stream *stream = nullptr;
-  size_t content_length = 0;
-  size_t bytes_read = 0;
-  bool chunked = false;
-  bool eof = false;
-
-  // For chunked encoding
-  size_t current_chunk_remaining = 0;
-
-  // Read up to len bytes into buf
-  // Returns bytes read, 0 on EOF, -1 on error
-  ssize_t read(char *buf, size_t len);
-};
-
 class SocketStream final : public Stream {
 public:
   SocketStream(socket_t sock, time_t read_timeout_sec, time_t read_timeout_usec,

test/test20.cc

@@ -518,35 +518,35 @@ TEST_F(ChunkedStreamingTest, SSELikeWithGenerator) {
 
 TEST(ClientConnectionTest, StructExists) {
   // Verify ClientConnection struct is defined
-  httplib::detail::ClientConnection conn;
+  httplib::ClientConnection conn;
 
   // Check default state
   EXPECT_EQ(INVALID_SOCKET, conn.sock);
   EXPECT_FALSE(conn.is_open());
 }
 
 TEST(ClientConnectionTest, IsOpenReturnsTrueWhenSocketValid) {
-  httplib::detail::ClientConnection conn;
+  httplib::ClientConnection conn;
   conn.sock = 1; // Fake valid socket
 
   EXPECT_TRUE(conn.is_open());
 }
 
 TEST(ClientConnectionTest, MoveConstructor) {
-  httplib::detail::ClientConnection conn1;
+  httplib::ClientConnection conn1;
   conn1.sock = 42;
 
-  httplib::detail::ClientConnection conn2(std::move(conn1));
+  httplib::ClientConnection conn2(std::move(conn1));
 
   EXPECT_EQ(42, conn2.sock);
   EXPECT_EQ(INVALID_SOCKET, conn1.sock); // Moved-from state
 }
 
 TEST(ClientConnectionTest, MoveAssignment) {
-  httplib::detail::ClientConnection conn1;
+  httplib::ClientConnection conn1;
   conn1.sock = 42;
 
-  httplib::detail::ClientConnection conn2;
+  httplib::ClientConnection conn2;
   conn2 = std::move(conn1);
 
   EXPECT_EQ(42, conn2.sock);
@@ -693,3 +693,101 @@ TEST(BodyReaderTest, ReadWithoutStream) {
 
   EXPECT_EQ(-1, n);
 }
+
+// =============================================================================
+// StreamHandle v2 Tests (Socket Direct Mode)
+// =============================================================================
+
+class StreamHandleV2Test : public ::testing::Test {
+protected:
+  void SetUp() override {
+    mock_stream_ = std::make_unique<MockStream>("Hello from socket!");
+  }
+
+  std::unique_ptr<MockStream> mock_stream_;
+};
+
+TEST_F(StreamHandleV2Test, SocketDirectModeBasic) {
+  // Create StreamHandle with socket direct mode
+  httplib::ClientImpl::StreamHandle handle;
+
+  // Set up response (headers only, body will be read from stream)
+  handle.response = std::make_unique<httplib::Response>();
+  handle.response->status = 200;
+  handle.response->set_header("Content-Length", "18");
+
+  // Set up socket direct mode
+  handle.stream_ = mock_stream_.get();
+  handle.body_reader_.stream = mock_stream_.get();
+  handle.body_reader_.content_length = 18;
+
+  EXPECT_TRUE(handle.is_valid());
+  EXPECT_TRUE(handle.is_socket_direct_mode());
+
+  // Read from socket
+  char buf[32];
+  auto n = handle.read(buf, sizeof(buf));
+  EXPECT_EQ(18, n);
+  EXPECT_EQ(std::string("Hello from socket!"),
+            std::string(buf, static_cast<size_t>(n)));
+
+  // EOF
+  n = handle.read(buf, sizeof(buf));
+  EXPECT_EQ(0, n);
+}
+
+TEST_F(StreamHandleV2Test, SocketDirectModeChunkedRead) {
+  httplib::ClientImpl::StreamHandle handle;
+
+  handle.response = std::make_unique<httplib::Response>();
+  handle.response->status = 200;
+
+  handle.stream_ = mock_stream_.get();
+  handle.body_reader_.stream = mock_stream_.get();
+  handle.body_reader_.content_length = 18;
+
+  // Read in small chunks
+  char buf[5];
+  std::string result;
+
+  ssize_t n;
+  while ((n = handle.read(buf, sizeof(buf))) > 0) {
+    result.append(buf, static_cast<size_t>(n));
+  }
+
+  EXPECT_EQ("Hello from socket!", result);
+  EXPECT_EQ(0, n); // EOF
+}
+
+TEST_F(StreamHandleV2Test, MemoryBufferModeStillWorks) {
+  // Existing behavior: read from response->body
+  httplib::ClientImpl::StreamHandle handle;
+
+  handle.response = std::make_unique<httplib::Response>();
+  handle.response->status = 200;
+  handle.response->body = "Memory buffer content";
+
+  // No stream set = memory buffer mode
+  EXPECT_TRUE(handle.is_valid());
+  EXPECT_FALSE(handle.is_socket_direct_mode());
+
+  char buf[32];
+  auto n = handle.read(buf, sizeof(buf));
+  EXPECT_EQ(21, n);
+  EXPECT_EQ(std::string("Memory buffer content"),
+            std::string(buf, static_cast<size_t>(n)));
+}
+
+TEST_F(StreamHandleV2Test, ReadAllSocketDirect) {
+  httplib::ClientImpl::StreamHandle handle;
+
+  handle.response = std::make_unique<httplib::Response>();
+  handle.response->status = 200;
+
+  handle.stream_ = mock_stream_.get();
+  handle.body_reader_.stream = mock_stream_.get();
+  handle.body_reader_.content_length = 18;
+
+  auto result = handle.read_all();
+  EXPECT_EQ("Hello from socket!", result);
+}