Make persistent connections actually reuse the socket

Re-running the benchmark after the timeout change showed persistent and
non-persistent within noise of each other, and the connection pool
always empty. Root cause is in std.http.Client.fetch (0.16): when a body
is both compressed and chunked, which is serpapi.com's default framing,
the decompressor stops at the end of the gzip stream and the terminating
"0\r\n\r\n" chunk is never read. Request.deinit then sees the body as
unfinished and closes the connection, so keep_alive was silently a no-op
and every request paid for a fresh TCP + TLS handshake.

fetchStatus now drives the request itself (mirroring fetch) and, after
the decompressed body has been streamed, drains the remaining framing
through req.reader.interface so the body is marked complete and the
connection returns to the pool.

zig build bench, 10 sequential searches, three rounds:
  before: non-persistent 2.1-2.5s, persistent 2.4-2.7s
  after:  non-persistent 2.1-2.4s, persistent 0.5-1.0s (3-4x)

A unit test serves two chunked gzip responses on one loopback connection
and asserts the pool holds the connection between them; it fails without
the drain. Docs updated from the old "2x" claim, which the code had never
actually delivered.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jvmvik

CHANGELOG.md

@@ -10,6 +10,13 @@
 - `serpapi.version` is derived from `build.zig.zon` at build time instead
   of being duplicated in `src/client.zig`, so the tag cut by `rake release`
   and the version reported to serpapi.com cannot drift apart
+- Fix: persistent connections are actually reused. `std.http.Client.fetch`
+  leaves the terminating chunk of a compressed, chunked response unread,
+  so it judged every serpapi.com body unfinished and closed the socket:
+  `persistent = true` was silently a no-op and each request paid for a new
+  TLS handshake. The client now drives the request itself and drains the
+  framing; `zig build bench` goes from ~2.4s to ~0.5-1.0s for 10 searches
+  (3-4x), where before persistent and non-persistent were within noise
 - Fix: the `timeout` option is enforced. It was accepted and documented
   but never applied, so a stalled connection blocked forever. Each request
   now races a timer on the client's `std.Io.Threaded` pool and is canceled

README.md

@@ -13,7 +13,7 @@ SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBa
 Query a vast range of data at scale, including web search results, flight schedules, stock market data, news headlines, and [more](https://serpapi.com).
 
 ## Features
-  * `persistent` → Keep socket connection open to save on SSL handshake / reconnection (2x faster).
+  * `persistent` → Keep socket connection open to save on SSL handshake / reconnection (3-4x faster on repeated searches).
   * `md` → Markdown output, token-efficient and ready to feed to LLMs and AI agents. [Search API — Markdown](#search-api--markdown)
   * zero dependency → only the Zig standard library (`std.http`, `std.json`), nothing else to fetch.
   * cross platform → Linux, macOS, and Windows.
@@ -317,8 +317,10 @@ var results = try client.searchArchive(search_id);
 ## Search at scale
 
 With `persistent = true` (the default), the client keeps the TLS connection
-to serpapi.com open between requests, which roughly doubles throughput on
-repeated searches (measure it yourself with `zig build bench`):
+to serpapi.com open between requests, skipping the TCP + TLS handshake on
+every search after the first. On repeated searches this is 3-4x faster than
+reconnecting (10 sequential searches: ~0.5-1.0s persistent vs ~2.2s not;
+measure it yourself with `zig build bench`):
 
 ```zig
 for (queries) |query| {

bench/benchmark.zig

@@ -1,6 +1,6 @@
 //! Benchmark: SerpApi client with and without persistent connection.
 //!
-//! Demonstrates that persistent (keep-alive) connections are ~2x quicker
+//! Demonstrates that persistent (keep-alive) connections are ~3-4x quicker
 //! than reconnecting for every request, by timing sequential searches.
 //! Results are printed and appended to a CSV file:
 //!   serpapi_zig_<zig_version>_<timestamp>.csv

src/client.zig

@@ -74,7 +74,7 @@ pub const Client = struct {
     params: std.array_list.Managed(Param),
     /// HTTP request timeout in seconds, 0 to wait forever [default: 120].
     timeout: u32,
-    /// Keep the connection open between requests (2x faster). [default: true]
+    /// Keep the connection open between requests (3-4x faster). [default: true]
     persistent: bool,
     /// Last error payload returned by serpapi.com (owned), see `errorMessage`.
     last_error: ?[]u8 = null,
@@ -91,7 +91,7 @@ pub const Client = struct {
     ///    Covers the whole request, from connecting to the last body byte;
     ///    an overrun returns `error.Timeout`. 0 disables the limit.
     ///  * `persistent`: keep the socket open to save on SSL handshake /
-    ///    reconnection (2x faster) [default: true]
+    ///    reconnection (3-4x faster) [default: true]
     ///
     /// Every other field (`api_key`, `engine`, `gl`, ...) becomes a default
     /// query parameter applied to every request:
@@ -459,7 +459,7 @@ pub const Client = struct {
 
     /// Outcome of racing the request against the timeout timer.
     const Race = union(enum) {
-        request: std.http.Client.FetchError!std.http.Status,
+        request: FetchError!std.http.Status,
         timer: std.Io.Cancelable!void,
     };
 
@@ -502,13 +502,62 @@ pub const Client = struct {
         }
     }
 
-    fn fetchStatus(http: *std.http.Client, url: []const u8, w: *std.Io.Writer, keep_alive: bool) std.http.Client.FetchError!std.http.Status {
-        const result = try http.fetch(.{
-            .location = .{ .url = url },
-            .response_writer = w,
+    /// Errors from `fetchStatus`: everything `std.http.Client.fetch` reports,
+    /// plus body decoding failures surfaced while draining the framing.
+    const FetchError = std.http.Client.FetchError || std.http.Reader.BodyError || Allocator.Error;
+
+    /// GET `url` and stream the decoded body to `w`, returning the status.
+    ///
+    /// This mirrors `std.http.Client.fetch`, with one addition. When the
+    /// body is compressed *and* chunked (serpapi.com's default), the
+    /// decompressor stops at the end of the gzip stream, leaving the
+    /// terminating `0\r\n\r\n` chunk unread. std's `fetch` then sees the
+    /// body as unfinished and closes the connection, so `keep_alive` was
+    /// silently a no-op and every request paid for a new TLS handshake.
+    /// Draining the framing marks the body complete and lets the connection
+    /// return to the pool. Measured: ~4x faster on repeated searches.
+    fn fetchStatus(http: *std.http.Client, url: []const u8, w: *std.Io.Writer, keep_alive: bool) FetchError!std.http.Status {
+        const uri = try std.Uri.parse(url);
+
+        var req = try http.request(.GET, uri, .{
+            // follow up to 3 redirects, as std.http.Client.fetch does
+            .redirect_behavior = @enumFromInt(3),
             .keep_alive = keep_alive,
         });
-        return result.status;
+        defer req.deinit();
+        try req.sendBodiless();
+
+        var redirect_buffer: [8 * 1024]u8 = undefined;
+        var response = try req.receiveHead(&redirect_buffer);
+
+        const decompress_buffer: []u8 = switch (response.head.content_encoding) {
+            .identity => &.{},
+            .zstd => try http.allocator.alloc(u8, std.compress.zstd.default_window_len),
+            .deflate, .gzip => try http.allocator.alloc(u8, std.compress.flate.max_window_len),
+            .compress => return error.UnsupportedCompressionMethod,
+        };
+        defer http.allocator.free(decompress_buffer);
+
+        var transfer_buffer: [64]u8 = undefined;
+        var decompress: std.http.Decompress = undefined;
+        const reader = response.readerDecompressing(&transfer_buffer, &decompress, decompress_buffer);
+        _ = reader.streamRemaining(w) catch |err| switch (err) {
+            error.ReadFailed => return response.bodyErr() orelse error.ReadFailed,
+            else => |e| return e,
+        };
+
+        // Consume whatever transfer framing the decompressor left behind so
+        // `req.deinit` sees a finished body and keeps the connection.
+        switch (req.reader.state) {
+            .body_remaining_chunk_len, .body_remaining_content_length => {
+                _ = req.reader.interface.discardRemaining() catch |err| switch (err) {
+                    error.ReadFailed => return response.bodyErr() orelse error.ReadFailed,
+                };
+            },
+            else => {},
+        }
+
+        return response.head.status;
     }
 
     fn getJson(self: *Client, comptime T: type, endpoint: []const u8, params: anytype, extra: []const Param) !std.json.Parsed(T) {
@@ -916,3 +965,64 @@ test "fetch returns before the timeout when the server answers" {
     try testing.expectEqualStrings("{\"ok\":true}\n", body.written());
     try answer.await(io);
 }
+
+test "persistent connection is reused after a chunked gzip response" {
+    var client = try Client.init(testing.allocator, .{ .timeout = 30 });
+    defer client.deinit();
+    const io = client.threaded.io();
+
+    const loopback: std.Io.net.IpAddress = try .parseIp4("127.0.0.1", 0);
+    var server = try loopback.listen(io, .{});
+    defer server.deinit(io);
+
+    // serpapi.com's default framing: Transfer-Encoding: chunked + gzip.
+    // Two requests are answered on the same accepted connection; the second
+    // can only succeed if the client kept the first connection alive.
+    const Server = struct {
+        fn serve(server_ptr: *std.Io.net.Server, server_io: std.Io, allocator: Allocator) !void {
+            var stream = try server_ptr.accept(server_io);
+            defer stream.close(server_io);
+            var read_buffer: [4096]u8 = undefined;
+            var reader = stream.reader(server_io, &read_buffer);
+            var write_buffer: [1024]u8 = undefined;
+            var writer = stream.writer(server_io, &write_buffer);
+
+            var gz: std.Io.Writer.Allocating = .init(allocator);
+            defer gz.deinit();
+            try gz.ensureUnusedCapacity(64);
+            const window = try allocator.alloc(u8, std.compress.flate.max_window_len);
+            defer allocator.free(window);
+            var compress: std.compress.flate.Compress = try .init(&gz.writer, window, .gzip, .default);
+            try compress.writer.writeAll("{\"ok\":true}");
+            try compress.finish();
+            try gz.writer.flush();
+            const payload = gz.written();
+
+            for (0..2) |_| {
+                while (true) {
+                    const line = try reader.interface.takeDelimiterInclusive('\n');
+                    if (line.len <= 2) break;
+                }
+                try writer.interface.writeAll("HTTP/1.1 200 OK\r\nContent-Encoding: gzip\r\nTransfer-Encoding: chunked\r\nConnection: keep-alive\r\n\r\n");
+                try writer.interface.print("{x}\r\n", .{payload.len});
+                try writer.interface.writeAll(payload);
+                try writer.interface.writeAll("\r\n0\r\n\r\n");
+                try writer.interface.flush();
+            }
+        }
+    };
+    var served = try io.concurrent(Server.serve, .{ &server, io, testing.allocator });
+    defer _ = served.cancel(io) catch {};
+
+    const url = try std.fmt.allocPrint(testing.allocator, "http://127.0.0.1:{d}/search", .{server.socket.address.getPort()});
+    defer testing.allocator.free(url);
+
+    for (0..2) |_| {
+        var body: std.Io.Writer.Allocating = .init(testing.allocator);
+        defer body.deinit();
+        try testing.expectEqual(std.http.Status.ok, try client.fetch(url, &body.writer));
+        try testing.expectEqualStrings("{\"ok\":true}", body.written());
+        try testing.expectEqual(@as(usize, 1), client.http.connection_pool.free_len);
+    }
+    try served.await(io);
+}