Stream a response body to a sink instead of buffering it (#213 slice 1)

[aaylward]

Slice 1 of #213, the runtime half: a transport can hand a response body to the caller in pieces. No codegen — a @streaming blob still generates a buffered opal::Blob, which is slice 2.

What

std::ofstream out("export.pgn", std::ios::binary);
const opal::http::BodySink to_file{
    .accept = [](int status, const opal::http::Headers&) { return status == 200; },
    .write = [&](std::string_view piece) { return out.write(piece.data(), piece.size()).good(); },
};
auto response = transport->SendStreaming(request, to_file);   // response->body is empty

This is what max_response_bytes (#212) could not be. That cap bounds what the process holds; a download whose size the service does not bound needs the process not to hold it.

accept is asked once per response, after the status and headers and before any body byte. That timing is the whole design: early enough to keep the body out of memory, late enough to know what the body is. Per-response means a sink that takes payloads leaves a 404's error document in response.body, where the generated deserializer already reads it — pinned by a consumer test.

write gets pieces in order, never empty, valid for the call only. False aborts: non-retryable error, connection dropped rather than pooled.

Beast is the transport that actually streams

Its read path moves from string_body to buffer_body: read the header, ask the sink, then pump through a 16 KiB window. Every other transport inherits a default SendStreaming that buffers and hands the body over in one piece — same delivery, same empty response.body, no memory bound. So the API works everywhere and pays off where it matters, and Loopback and SocketHttpClient need no changes.

Two things the rewrite preserves deliberately, since it now carries every Beast send:

• max_response_bytes still bounds the buffered branch, including refusing a declared Content-Length over the cap before reading any of it (now an explicit parser.content_length() check rather than Beast's body_limit).
• A streamed body is not bounded by it. The cap is about what this process holds, and here it holds nothing.

Retries

SendWithRetries gains a sink overload and withholds retryable statuses from the sink while retries are enabled. Streaming a 503's error document and then retrying would leave the sink holding that body followed by the real one, with no way to take the first back.

The rule holds on the last attempt too, deliberately: which attempt produced a 503 is not something a caller should have to reason about, and such a body is small and arrives in response.body like every other error document. With max_attempts = 1 nothing can be discarded, so the caller's accept stands unaltered. A failure after the sink took bytes is non-retryable, so the loop stops there.

I had this one wrong in the first draft — the doc comment promised "while another attempt may follow" and the code withheld on every attempt. The test caught the disagreement. The code's behavior is the better of the two, so the comment and test moved to it rather than the other way around.

Answers to the open questions in #213

1. Beast only. The socket client keeps refusing transfer-encoding; teaching it chunked decoding is a security-sensitive change that wants its own hostile bank and fuzz target, and it is test/reference-only (ADR-0006).
2. Push callback, with bool to cancel.
3. Yes, interceptors see a headers-only response. Documented on Interceptor and tested — a hook that logs bodies sees nothing rather than something truncated.
4. The cap does not apply to a streamed body, and still applies to a declined one.
5. Left to slice 2.

Testing

• runtime/tests/http/body_sink_test.cc (new): the shared contract on Loopback and SocketHttpClient — accepted, declined, aborted, empty body, half a sink is no sink, a transport failure never reaches the sink.
• beast_client_test.cc: more than one piece (the observable difference between streaming and having streamed nothing — 1 MiB through a 16 KiB window), a 64 KiB body streaming past a 16-byte cap while the same response declined trips it, abort leaves the client usable, and three streamed round trips reuse the pooled connection.
• retry_test.cc: the sink never sees a 503's body and accept is not even consulted for one; the same on the final attempt; with retries disabled the caller's decision stands; a non-retryable failure ends the loop; interceptors see an empty body.
• examples/bazel-consumer/response_sink_acceptance_test.cc (new): a consumer module reaching BodySink through @opal_cpp//runtime:http, pulling a 512 KiB blob payload off a generated server and checking a digest, and leaving a modeled error's document intact.
• bazel test //... --config=werror: 130 pass. Consumer module: 17 pass. --config=noexcept build passes. gradle build spotlessCheck passes. Goldens untouched (no emitter change). clang-format, clang-tidy, buildifier clean.

The existing 129 tests all run through the rewritten Beast read path, which is most of the confidence that buffer_body behaves like string_body did.

Checklist

• Tests added/updated for the change
• bazel test //... and (cd codegen && gradle build spotlessCheck) pass locally
• Formatting clean (clang-format, buildifier, spotless)
• Architectural decisions recorded as an ADR (not applicable: an additive method on an existing interface; the design record is @streaming blob bodies: deliver a response in pieces instead of buffering it #213 and the research doc's §6 status note)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Jj5X2fKdgrYurHmbwLzUiQ

---

Generated by Claude Code

[cursor]

Rechecked eb8dccd. All four review findings are addressed correctly, including their regression coverage, and I found no new actionable issues.