head, // complete head routed; decision pending

admitted, // body admission accepted; response still available

responded, // terminal: response committed to the engine

upgraded, // terminal: connection ownership transferred

cancelled, // disconnected before a terminal decision

std::vector<std::string> subprotocols;

// Empty allowlist accepts any syntactically valid origin. Matching

// uses exact serialized origins, without case/default-port rewriting.

std::vector<std::string> allowed_origins;

bool allow_absent_origin = true;

bool require_subprotocol = false;

websocket::options limits;

http::outcome status;

std::optional<websocket::session> session;

std::string selected_subprotocol;

http::status rejection_status = http::status::from_code(400);

http::fields rejection_fields;

public:

virtual ~exchange_sink() = default;

// Body admission accepted: may emit the interim 100 response and

// starts bounded body delivery.

virtual void on_admit(const body_policy& policy) = 0;

// Response head committed; serialized per protocol version rules.

virtual void on_respond(const http::status& s,

const http::fields& f) = 0;

// Connection ownership transferred to the upgrade session.

virtual websocket_upgrade_result on_upgrade(const ws_upgrade_options& options) = 0;

// Post-commit failure (e.g. a handler threw after responding):

// reset/close per protocol rules.

virtual void on_abort() = 0;

public:

// Engine construction only. `sink` receives every committed

// decision; `connection_id` identifies the underlying connection

// for engine bookkeeping; `body_source` is the engine's delivery

// seam for the admitted body (null until an engine provides one);

// `response_sink` is the engine's delivery seam for the streaming

// response body (null until an engine provides one); `peer` is

// the transport peer snapshot stamped at accept (TASK-119) --

// immutable for the exchange's lifetime, unspec for a rigged

// exchange.

exchange(const http::request_head& head, detail::exchange_sink* sink,

std::uint64_t connection_id = 0,

detail::body_source* body_source = nullptr,

detail::body_sink* response_sink = nullptr,

net::peer_address peer = net::peer_address{}) noexcept

: head_(head), sink_(sink), connection_id_(connection_id),

body_source_(body_source), body_(stop_.get_token()),

response_sink_(response_sink), writer_(stop_.get_token()),

peer_(peer) { }

exchange(exchange&& other) noexcept = default;

exchange& operator=(exchange&& other) noexcept = default;

exchange(const exchange&) = delete;

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

// The routed head, exactly as received (raw_target preserved;

// route_path is the matching input).

const http::request_head& head() const noexcept { return head_; }

exchange_state state() const noexcept { return state_; }

// True in the two terminal states (responded, upgraded).

bool terminal() const noexcept {

return state_ == exchange_state::responded

|| state_ == exchange_state::upgraded;

}

bool suspended() const noexcept { return suspended_; }

bool disconnected() const noexcept { return disconnected_; }

// Reason and detail of the disconnect; meaningful only once

// disconnected().

const http::outcome& disconnect_reason() const noexcept {

return disconnect_reason_;

}

std::uint64_t connection_id() const noexcept { return connection_id_; }

// TASK-119 (plan D3): the transport peer snapshot taken at accept

// and carried immutably -- the address and port the peer policy

// consulted and the value a handler observes. There is no setter:

// a reconnect is a new connection with a new snapshot. Unspec for

// a rigged exchange.

const net::peer_address& peer() const noexcept { return peer_; }

// The admitted request body. Operations are legal only after a

// successful admit_body() and fail typed otherwise.

body_reader& body() noexcept { return body_; }

// The streaming response writer. Operations are legal only after a

// successful start_response() and fail typed otherwise.

response_writer& writer() noexcept { return writer_; }

// Fan-out handle observing this exchange's disconnect.

stop_token cancellation() const noexcept { return stop_.get_token(); }

// TASK-118 (plan D2): the named path captures of the resolved

// route, stamped by the engine's dispatcher before the handler

// runs; empty when no parameterized route matched. Names view the

// registry's stored pattern text (valid while the registry is not

// mutated -- registration is closed once listen() runs); values

// are owned by the exchange for its whole lifetime.

void set_path_args(std::vector<server::route_captures> args) {

path_args_ = std::move(args);

}

std::span<const server::route_captures> path_args() const noexcept {

return path_args_;

}

// Terminal response decision; doubles as the reject decision when

// called with an error status straight from the head. Commits via

// the engine sink and clears any suspension.

http::outcome respond(const http::status& s, const http::fields& f) {

if (disconnected_) return closed_failure();

if (state_ != exchange_state::head

&& state_ != exchange_state::admitted) {

return http::outcome(

http::outcome_code::invalid_state,

"exchange: respond() after a terminal decision");

}

state_ = exchange_state::responded;

suspended_ = false;

body_.close();

if (sink_ != nullptr) sink_->on_respond(s, f);

return http::outcome::okay();

}

// Streaming response decision (head-time or after admission):

// commits the response head exactly like respond(), then activates

// the writer, so the handler streams the body through writer()

// with backpressure (architecture §3.1). The engine's on_respond

// still fires exactly once: afterwards the state is responded, so

// any second terminal decision fails invalid_state.

http::outcome start_response(const http::status& s, const http::fields& f) {

if (disconnected_) return closed_failure();

if (state_ != exchange_state::head

&& state_ != exchange_state::admitted) {

return http::outcome(

http::outcome_code::invalid_state,

"exchange: start_response() after a terminal decision");

}

state_ = exchange_state::responded;

suspended_ = false;

body_.close();

if (sink_ != nullptr) sink_->on_respond(s, f);

writer_.activate(response_sink_);

return http::outcome::okay();

}

// Body admission decision (head-time). Hands the policy to the

// engine, which owns bounded delivery of the body.

http::outcome admit_body(const body_policy& policy) {

if (disconnected_) return closed_failure();

if (state_ != exchange_state::head) {

return http::outcome(

http::outcome_code::invalid_state,

"exchange: admit_body() is a head-time decision");

}

state_ = exchange_state::admitted;

if (sink_ != nullptr) sink_->on_admit(policy);

body_.activate(body_source_);

return http::outcome::okay();

}

// Suspension decision: stores a fresh resume signal, hands a copy

// to the caller, and marks the exchange suspended. The engine

// applies its configured suspension timeout while suspended().

// The state does not change; the handler still owns the decision.

http::outcome suspend(resume_signal& out) {

if (disconnected_) return closed_failure();

if (state_ != exchange_state::head

&& state_ != exchange_state::admitted) {

return http::outcome(

http::outcome_code::invalid_state,

"exchange: suspend() requires an open exchange");

}

resume_signal fresh;

out = fresh;

resume_signals_.push_back(std::move(fresh));

suspended_ = true;

return http::outcome::okay();

}

// Upgrade decision: transfers connection ownership to the upgrade

// session. The upgrade handshake exists on HTTP/1.1 only; other

// versions negotiate differently and report not_supported.

// Lazy like other tasks: options are owned before first suspension.

// Await immediately while the engine-owned exchange is alive.

task<websocket_upgrade_result> upgrade(ws_upgrade_options options) {

websocket_upgrade_result result;

if (disconnected_) {

result.status = closed_failure(); co_return result;

}

if (state_ != exchange_state::head) {

result.status = {http::outcome_code::invalid_state,

"exchange: upgrade() is a head-time decision"};

co_return result;

}

if (head_.request_protocol != http::protocol::http_1_1 || sink_ == nullptr) {

result.status = {http::outcome_code::not_supported,

"exchange: upgrade requires native HTTP/1.1"};

co_return result;

}

result = sink_->on_upgrade(options);

if (result.status.ok()) {

state_ = exchange_state::upgraded;

suspended_ = false;

body_.close();

}

co_return result;

}

// Engine-facing disconnect notification (PRD-V3N-REQ-025). Reasons

// mirror http::outcome_code; `ok` is not one. Idempotent: later

// calls are no-ops. Fans out to the stop token (handler-safe per

// DR-V3-008: request_stop returns before any waiter runs) and to

// every recorded resume signal, then moves a non-terminal state to

// cancelled. Terminal states stay terminal.

http::outcome disconnect(http::outcome_code reason, std::string detail) {

if (reason == http::outcome_code::ok) {

return http::outcome(

http::outcome_code::invalid_argument,

"exchange: disconnect() requires a failure reason");

}

if (disconnected_) return http::outcome::okay();

disconnected_ = true;

disconnect_reason_ = http::outcome(reason, std::move(detail));

body_.note_disconnect(disconnect_reason_);

writer_.note_disconnect(disconnect_reason_);

stop_.request_stop();

for (resume_signal& sig : resume_signals_) {

sig.cancel();

}

if (!terminal()) state_ = exchange_state::cancelled;

return http::outcome::okay();

}

// Engine-facing post-commit failure notification (architecture

// §3.1): the response was already committed but the exchange failed

// afterwards (e.g. a handler threw), so the engine resets or closes

// the connection per protocol rules instead of committing another

// response. No state change: a terminal exchange stays terminal.

http::outcome abort() {

// A streaming handler may have thrown mid-body; shut the

// writer down (idempotent) so no further write passes its

// gate, then let the engine reset per protocol rules.

writer_.close();

if (sink_ != nullptr) sink_->on_abort();

return http::outcome::okay();

}

private:

// Decisions after a disconnect fail closed, carrying the stored

// detail so the diagnostic names the original reason.

http::outcome closed_failure() const {

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

disconnect_reason_.message());

}

http::request_head head_;

detail::exchange_sink* sink_;

std::uint64_t connection_id_ = 0;

exchange_state state_ = exchange_state::head;

bool suspended_ = false;

bool disconnected_ = false;

http::outcome disconnect_reason_;

stop_source stop_;

detail::body_source* body_source_ = nullptr;

// Declared after stop_: the reader's constructor copies the stop

// token, so disconnects fan out to parked body reads.

body_reader body_;

detail::body_sink* response_sink_ = nullptr;

// Declared after stop_: the writer's constructor copies the stop

// token, so disconnects fan out to parked response writes.

response_writer writer_;

std::vector<server::route_captures> path_args_;

std::vector<resume_signal> resume_signals_;

net::peer_address peer_;