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 {

bool expected = false;

return delivered.compare_exchange_strong(expected, true,

std::memory_order_acq_rel,

std::memory_order_acquire);

}

// 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 {

if (target != nullptr) {

try {

target->post([witness = witness, frame = awaiting] {

if (witness) {

guarded_resume(witness, frame);

} else {

frame.resume();

}

});

} catch (...) {

}

return;

}

if (witness) {

guarded_resume(witness, awaiting);

} else {

awaiting.resume();

}

}

public:

body_write_wait(body_sink* sink, stop_token cancel)

: sink_(sink), node_(std::make_shared<write_wait_node>()),

cancel_(std::move(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 {

frame_ = frame;

return *this;

}

bool await_ready() const noexcept { return false; }

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

node_->awaiting = awaiting;

node_->witness = frame_ ? frame_->frame_witness_ptr() : nullptr;

node_->target = frame_ ? frame_->frame_executor() : current_executor();

sink_->park(*this);

// Seam contract: completion is posted to this executor, never

// resumed inline on the parking (or completing) thread.

return std::noop_coroutine();

}

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 {

if (!node_->claim()) return;

node_->result = room;

node_->resume_posted();

}

// 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() {

if (!node_->delivered.load(std::memory_order_acquire)) {

sink_->unpark(*this);

}

}

private:

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) {

const http::outcome gate = enter(data.empty());

if (!gate.ok()) {

co_return body_write{gate, 0};

}

pending_ = true;

std::size_t total = 0;

while (total < data.size()) {

const detail::body_push_result pushed =

sink_->push(data.subspan(total));

if (pushed.kind == detail::body_push::accepted) {

// A zero-byte accepted push is engine misuse: count

// nothing and re-push (never surface progress).

total += pushed.copied;

continue;

}

if (pushed.kind == detail::body_push::failed) {

fail_sticky(sink_->failure());

pending_ = false;

co_return body_write{failure_, total};

}

// Queue at capacity: park until the first of queue room,

// engine failure, or exchange disconnect. This suspension

// IS the backpressure (PRD-V3N-REQ-027).

detail::body_write_wait wait(sink_, cancel_token_);

if (co_await wait == detail::body_room::cancelled) {

pending_ = false;

co_return body_write{

http::outcome(http::outcome_code::cancelled,

"response_writer: write cancelled by "

"disconnect"),

total};

}

}

pending_ = false;

co_return body_write{http::outcome::okay(), total};

}

// 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()) {

const http::outcome gate = enter(false);

if (!gate.ok()) {

co_return body_finish{gate};

}

pending_ = true;

for (;;) {

const detail::body_push_result pushed =

sink_->push_end(trailers);

if (pushed.kind == detail::body_push::accepted) {

finished_ = true;

pending_ = false;

close();

co_return body_finish{http::outcome::okay()};

}

if (pushed.kind == detail::body_push::failed) {

fail_sticky(sink_->failure());

pending_ = false;

co_return body_finish{failure_};

}

detail::body_write_wait wait(sink_, cancel_token_);

if (co_await wait == detail::body_room::cancelled) {

pending_ = false;

co_return body_finish{

http::outcome(http::outcome_code::cancelled,

"response_writer: finish cancelled by "

"disconnect")};

}

}

}

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 {

sink_ = sink;

started_ = true;

}

// 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 {

if (pending_) {

return http::outcome(http::outcome_code::invalid_state,

"response_writer: a write is already "

"outstanding");

}

if (cancel_token_.stop_requested()) {

return http::outcome(http::outcome_code::connection_closed,

disconnect_reason_.message());

}

if (closed_) {

return http::outcome(http::outcome_code::invalid_state,

"response_writer: writer is closed");

}

if (!started_ || sink_ == nullptr) {

return http::outcome(http::outcome_code::invalid_state,

"response_writer: response not started");

}

if (empty_chunk) {

return http::outcome(http::outcome_code::invalid_argument,

"response_writer: chunk is empty");

}

if (finished_) {

return http::outcome(http::outcome_code::invalid_state,

"response_writer: body already finished");

}

if (failed_) {

return failure_;

}

return http::outcome::okay();

}

// 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 {

failed_ = true;

failure_ = reason;

}

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;