accepted, // bytes copied into the engine's bounded output queue

full, // queue at capacity; the writer must park

failed, // transport/protocol failure; see body_sink::failure()

freed, // output queue room freed; re-push

failed,

cancelled, // the exchange's stop fired before completion

public:

virtual ~body_sink() = default;

// Copies at most from.size() bytes into the output queue and

// returns the verdict plus the count copied. Room appears only

// while the engine drains its queue (never as peer

// acknowledgement). Zero-byte accepted pushes are forbidden; the

// writer re-pushes them.

virtual body_push_result push(std::span<const std::byte> from) = 0;

// Ends the body; `trailers` ride the final framing. The end marker

// occupies one queue slot, so a full queue reports full. Exactly

// once per sink; the writer guarantees the single call.

virtual body_push_result push_end(const http::fields& trailers) = 0;

// Failure diagnostic; meaningful once a push returned failed.

virtual const http::outcome& failure() const noexcept = 0;

// Parks `wait` until the FIRST of: queue room freed, failure

// raised, or the exchange's stop requested (cancelled). Completes

// at most once, posted to the waiter's executor (never inline on

// the completing thread). Precondition: at most one waiter parked

// per sink.

virtual void park(body_write_wait& wait) = 0;

// Detaches a still-parked waiter (the waiter was destroyed without

// waking). After unpark, the sink must forget the waiter.

virtual void unpark(body_write_wait& wait) = 0;

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

body_room result = body_room::cancelled;

std::coroutine_handle<> awaiting;

std::shared_ptr<frame_witness> witness; // null for foreign coroutines

executor* target = nullptr; // null resumes witness-guarded

bool claim() noexcept;

// Posts the resumption to the waiter's executor. Only when no

// executor is known does the resumption run inline, still guarded

// by the frame witness.

void resume_posted() noexcept;

public:

body_write_wait(body_sink* sink, stop_token cancel);

body_write_wait(const body_write_wait&) = delete;

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

body_write_wait(body_write_wait&&) = delete;

body_write_wait& operator=(body_write_wait&&) = delete;

body_write_wait& bind_frame(task_frame_base* frame) noexcept;

bool await_ready() const noexcept { return false; }

std::coroutine_handle<> await_suspend(std::coroutine_handle<> awaiting);

body_room await_resume() const noexcept { return node_->result; }

// Completion entry for body_sink implementations (any thread).

// Exactly-once via the claim; a losing later completion is a

// no-op. The posted job owns the node, so it stays safe across

// waiter destruction.

void complete(body_room room) noexcept;

// The exchange's disconnect token: the seam completes a parked

// wait as cancelled when it fires.

const stop_token& cancel_token() const noexcept { return cancel_; }

~body_write_wait();

private:

friend class http2_body_stream;

body_sink* sink_;

std::shared_ptr<write_wait_node> node_;

task_frame_base* frame_ = nullptr;

stop_token cancel_;

public:

// Streams one chunk into the engine's bounded output queue,

// suspending while the queue is full and resuming when room frees.

// Resolves ok only once the whole chunk was accepted; a partial

// acceptance surfaces as further internal pushes. An empty chunk

// fails invalid_argument without touching the engine.

task<body_write> write(std::span<const std::byte> data);

// Ends the response body. `trailers` ride the final framing (empty

// when none). On ok the writer is closed; further write/finish fail

// invalid_state. Exactly-once: the sink sees push_end at most once

// (the one-outstanding gate serializes entry; a cancelled finish

// never half-ends the body).

task<body_finish> finish(http::fields trailers = http::fields());

response_writer(response_writer&&) noexcept = default;

response_writer& operator=(response_writer&&) noexcept = default;

response_writer(const response_writer&) = delete;

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

private:

friend class exchange;

explicit response_writer(stop_token cancel) noexcept

: cancel_token_(std::move(cancel)) { }

// exchange::start_response, after the engine accepted the head. A

// null sink keeps every write at invalid_state.

void activate(detail::body_sink* sink) noexcept;

// exchange::abort, and finish itself on success: the writer shuts

// down and every later operation fails typed. Idempotent bool, so

// the body ends exactly once no matter the finish/abort ordering.

void close() noexcept { closed_ = true; }

// exchange::disconnect, before the stop fan-out: stores the detail

// that writes issued after the disconnect report with their typed

// connection_closed failure.

void note_disconnect(const http::outcome& reason) noexcept {

disconnect_reason_ = reason;

}

// Shared entry gate of the write operations: fails typed and

// touches nothing when a push may not start.

http::outcome enter(bool empty_chunk) const;

// Sticky failure: the body is unusable after this point; later

// writes return the same outcome without touching the engine.

void fail_sticky(const http::outcome& reason) noexcept;

detail::body_sink* sink_ = nullptr;

stop_token cancel_token_;

http::outcome failure_;

http::outcome disconnect_reason_;

bool started_ = false;

bool pending_ = false;

bool finished_ = false;

bool failed_ = false;

bool closed_ = false;