http::outcome status;

std::span<const std::byte> data;

bool end = false;

public:

body_lease() noexcept = default;

// Pins `keeper` (typically the buffer's owner) for the

// definition's lifetime.

template <typename T>

explicit body_lease(std::shared_ptr<T> keeper) noexcept

: keeper_(std::move(keeper)) {

}

// True iff the lease pins something. borrowed() rejects an empty

// lease before a definition exists.

bool valid() const noexcept { return keeper_ != nullptr; }

private:

std::shared_ptr<const void> keeper_;

owned_bytes,

reopen_file,

factory,

borrowed,

owned_file,

owned_pipe,

public:

transferred_handle(std::FILE* handle, owned_close_fn close) noexcept

: handle_(handle),

close_(std::move(close)) {

}

transferred_handle(const transferred_handle&) = delete;

transferred_handle& operator=(const transferred_handle&) = delete;

// The backstop closer: an unsent definition's destruction ends

// here. Idempotent with close(), so a send that already released

// the handle never double-closes.

~transferred_handle() { close(); }

// The one-shot gate: true for exactly one caller ever.

bool claim() noexcept;

// Fires the close operation exactly once.

void close() noexcept;

std::FILE* get() const noexcept { return handle_; }

private:

std::atomic<bool> claimed_{false};

std::atomic<bool> closed_{false};

std::FILE* handle_;

owned_close_fn close_;

response_source_kind kind = response_source_kind::owned_bytes;

std::vector<std::byte> bytes; // owned_bytes

std::string path; // reopen_file

body_factory make; // factory

std::span<const std::byte> view; // borrowed: the application body

body_lease lease; // borrowed: pins view alive

// owned_file/owned_pipe: the transferred handle. Deliberately a

// pointer to a mutable transferred_handle inside an otherwise

// const frozen block: the one-shot claim and the exactly-once

// close are per-handle state (the only mutability inside a frozen

// definition), and no releasable token exists to misuse.

std::shared_ptr<transferred_handle> handle;

public:

// A cursor releases ONLY the handle it claimed: a losing one-shot

// send closes nothing (its claim never happened), so a racing

// loser's destruction can never close the handle under the

// winner's read. A claimed transfer's handle is released here on

// every send fate: completed, failed, cancelled (the coroutine

// frame's destruction runs this). close() is idempotent, so the

// holder's backstop destructor never double-closes.

~send_cursor();

// Binds to `source` (one definition's frozen body block) and takes

// this send's snapshot of it against the merged framing

// `framing`: the bytes or leased span aliased (the source pins

// them alive), the file freshly opened with its read bound taken

// from an explicit Content-Length when the merged fields carry one

// (the observed size otherwise), one fresh producer invoked, or

// the transferred handle claimed (one-shot) and probed.

http::outcome prepare(std::shared_ptr<const response_body_source> source,

const http::fields& framing);

// The next chunk of this send's body (prepare() must have

// succeeded): exactly one meaning per body_chunk, spans valid

// until the next pull on this cursor.

body_chunk pull();

// File-backed sources only: the size observed at this send's

// prepare (the pinned Content-Length); 0 for every other kind.

std::uint64_t file_size() const noexcept { return file_size_; }

private:

// owned_bytes and borrowed share one streaming shape: a frozen

// span this send walks once — the source's own bytes, or the

// leased application span.

void bind_span(std::span<const std::byte> body) noexcept;

// One fresh private handle per send: concurrent sends of one

// reopen_file definition never share seek state. The size observed

// here is this send's pinned Content-Length; an explicit

// Content-Length in the merged framing becomes the read bound

// instead, so a file short of its declared length fails that send

// typed (the ownership matrix's shrink guarantee).

http::outcome prepare_file(const http::fields& framing);

// One fresh producer per send; an empty one is a contract

// violation failed before the head commits.

http::outcome prepare_factory();

// owned_file: the one-shot claim FIRST (two racing sends' probes

// must never interleave), then the size probe — the handle's

// position at transfer is honored: body = position→EOF. The claim

// is not refundable: a failed probe (an unseekable handle) leaves

// the definition spent — a one-shot definition admits exactly one

// send attempt past validation.

http::outcome prepare_owned_file(const http::fields& framing);

// owned_pipe: the one-shot claim, NO probe — a pipe endpoint has

// no seek position, and transferring it means the bytes feed

// exactly one send. Without a declared Content-Length the length is

// unknown: the read runs to the stream's own EOF and nothing is

// pinned (the framing stays the transport's). A declared length

// becomes the read bound instead. Like owned_file, the claim is

// not refundable.

http::outcome prepare_owned_pipe(const http::fields& framing);

// owned_bytes / borrowed: the whole remaining span in one chunk

// carrying end (the writer's internal loop paces it against queue

// capacity, so backpressure stays the writer's).

body_chunk pull_span();

// reopen_file: at most one buffer's worth of the pinned size. A

// clean EOF with bytes still owed to the pinned Content-Length is

// a short body (the file shrank between sends): typed

// protocol_error, mirroring the engine's short-body diagnosis.

body_chunk pull_file();

// factory: forwards to this send's producer; an empty non-end

// chunk is a producer contract violation failed typed (never

// silently skipped); end and failure pass through verbatim.

body_chunk pull_factory();

// owned_file / owned_pipe: at most one buffer's worth of the

// bounded read. A short read is the stream's own verdict: an I/O

// failure is invalid_state; EOF on an unbounded pipe (no declared

// Content-Length) ends the body there; EOF with bytes still owed

// to the pinned or declared length is a short body

// (protocol_error, like reopen_file).

body_chunk pull_handle();

private:

// The unseekable-handle diagnosis of owned_file's probe.

static http::outcome unseekable();

std::shared_ptr<const response_body_source> owner_;

bool owns_handle_ = false; // this send claimed owner_'s handle

std::span<const std::byte> view_; // owned_bytes/borrowed: the span

std::uint64_t offset_ = 0; // owned_bytes/borrowed span cursor

std::uint64_t total_ = 0; // owned_bytes/borrowed span total

std::uint64_t file_size_ = 0; // file-backed pinned size at prepare

std::uint64_t remaining_ = 0; // file-backed bytes left to the bound

bool eof_ends_ = false; // owned_pipe: EOF terminates the body

std::ifstream file_; // reopen_file: this send's private handle

std::vector<std::byte> buffer_; // file-backed read buffer

body_producer producer_; // factory: this send's producer