for (const char c : v) {

const auto u = static_cast<unsigned char>(c);

if ((u < 0x20 && u != '\t') || u == 0x7F) return true;

}

return false;

for (const http::fields::entry e : f.entries()) {

if (!http::detail::is_token(e.name)) {

return http::outcome(

http::outcome_code::invalid_argument,

"response fields: name '" + std::string(e.name)

+ "' is not a token");

}

if (field_value_has_ctl(e.value)) {

return http::outcome(

http::outcome_code::invalid_argument,

"response fields: value of '" + std::string(e.name)

+ "' carries a control byte");

}

}

return http::outcome::okay();

if (f.count("content-length") > 1) {

return http::outcome(

http::outcome_code::invalid_argument,

"response fields: repeated Content-Length");

}

if (f.count("content-length") > 0

&& f.count("transfer-encoding") > 0) {

return http::outcome(

http::outcome_code::invalid_argument,

"response fields: Transfer-Encoding with Content-Length");

}

std::uint64_t declared = 0;

return parse_content_length(f, declared);

if (f.count("content-length") == 0

&& f.count("transfer-encoding") == 0) {

f.append("Content-Length", std::to_string(size));

}

public:

// The source taxonomy lives in response_sources.hpp; the alias

// keeps the TASK-112 spelling (response_definition::source_kind).

using source_kind = response_source_kind;

// Body held by value; Content-Length pinned to the body size when

// the fields carry neither framing field (including "0").

static http::outcome owned_bytes(const http::status& s, http::fields f,

std::vector<std::byte> body,

response_definition& out) {

build state;

state.status = s;

detail::pin_content_length(f, body.size());

state.fields = std::move(f);

state.body.kind = source_kind::owned_bytes;

state.body.bytes = std::move(body);

return commit(std::move(state), out);

}

// Body re-read from `path` on every send: nothing is opened at

// construction, so a definition outlives any one file's lifetime;

// each send observes the file at its own prepare and pins

// Content-Length per send.

static http::outcome reopen_file(const http::status& s, http::fields f,

std::string path,

response_definition& out) {

build state;

state.status = s;

state.fields = std::move(f);

state.body.kind = source_kind::reopen_file;

state.body.path = std::move(path);

return commit(std::move(state), out);

}

// Body produced per send by a fresh producer from `make`.

static http::outcome factory(const http::status& s, http::fields f,

body_factory make,

response_definition& out) {

build state;

state.status = s;

state.fields = std::move(f);

state.body.kind = source_kind::factory;

state.body.make = std::move(make);

return commit(std::move(state), out);

}

// Body borrowed from application memory under an explicit lease:

// the library stores only the view and the lease, never a copy.

// The keeper keeps [body.data(), body.data() + body.size())

// unchanged and alive while the definition lives (that

// immutability is what makes a borrowed body replayable);

// releasing the last definition releases the keeper. An invalid

// lease is rejected before a definition exists — sharing a

// borrowed body without a valid lease has no safe send (REQ-028).

static http::outcome borrowed(const http::status& s, http::fields f,

std::span<const std::byte> body,

body_lease lease,

response_definition& out) {

build state;

state.status = s;

detail::pin_content_length(f, body.size());

state.fields = std::move(f);

state.body.kind = source_kind::borrowed;

state.body.view = body;

state.body.lease = std::move(lease);

return commit(std::move(state), out);

}

// Body streamed from an open std::FILE* TRANSFERRED to the

// library and closed with std::fclose (see the owned_close_fn

// overload for a custom release).

static http::outcome owned_file(const http::status& s, http::fields f,

std::FILE* handle,

response_definition& out) {

return owned_file(s, std::move(f), handle,

owned_close_fn(&detail::fclose_owned), out);

}

// Body streamed from an open std::FILE* transferred to the

// library (REQ-028): ONE-SHOT — one handle holds one seek

// position, so exactly one send may consume it; a second send

// fails invalid_state before writing anything. The body is the

// handle's remaining bytes at transfer (position→EOF), probed at

// the send's prepare (an unseekable handle fails there, typed,

// and spends the definition). Content-Length pins per send to the

// probed size unless the fields declare one — a declared length

// becomes the read bound, and a body short of it fails that send

// typed. The library owns the handle from here on and closes it

// exactly once: after the send completes, fails, or is cancelled,

// or when an unsent definition is destroyed. An application that

// must keep its handle open wraps the readable side in a factory

// source instead. `long`-based offsets bound the probed size to

// LONG_MAX on LLP64 platforms; larger transfers belong to

// reopen_file (std::streamoff).

static http::outcome owned_file(const http::status& s, http::fields f,

std::FILE* handle,

owned_close_fn close,

response_definition& out) {

if (handle == nullptr || !close) {

return http::outcome(

http::outcome_code::invalid_argument,

"response_definition: owned_file requires a handle and "

"a close operation");

}

build state;

state.status = s;

state.fields = std::move(f);

state.body.kind = source_kind::owned_file;

state.body.handle =

std::make_shared<detail::transferred_handle>(

handle, std::move(close));

return commit(std::move(state), out);

}

// Body streamed from an open pipe endpoint TRANSFERRED to the

// library and closed with std::fclose (see the owned_close_fn

// overload for a custom release).

static http::outcome owned_pipe(const http::status& s, http::fields f,

std::FILE* handle,

response_definition& out) {

return owned_pipe(s, std::move(f), handle,

owned_close_fn(&detail::fclose_owned), out);

}

// Body streamed from an open pipe endpoint (any std::FILE* with no

// usable seek position) transferred to the library (REQ-028):

// ONE-SHOT and NON-REPLAYABLE (architecture §3.2) — the bytes can

// be read exactly once, so exactly one send may consume the

// definition; a second send, however it races the winner, fails

// invalid_state before writing anything. Nothing is probed at the

// send's prepare (a pipe is never seeked). The length is unknown

// unless the fields declare a Content-Length: without one no

// length is pinned and the framing stays the transport's (chunked

// on HTTP/1.1, close-delimited on HTTP/1.0); with one the declared

// length bounds the read, and a body short of it fails that send

// typed. The library owns the endpoint from here on and closes it

// exactly once: after the send completes, fails, or is cancelled,

// or when an unsent definition is destroyed.

static http::outcome owned_pipe(const http::status& s, http::fields f,

std::FILE* handle,

owned_close_fn close,

response_definition& out) {

if (handle == nullptr || !close) {

return http::outcome(

http::outcome_code::invalid_argument,

"response_definition: owned_pipe requires a handle and "

"a close operation");

}

build state;

state.status = s;

state.fields = std::move(f);

state.body.kind = source_kind::owned_pipe;

state.body.handle =

std::make_shared<detail::transferred_handle>(

handle, std::move(close));

return commit(std::move(state), out);

}

// The empty, not-yet-valid definition; valid() reports false.

response_definition() noexcept = default;

response_definition(const response_definition&) noexcept = default;

response_definition& operator=(const response_definition&) noexcept

= default;

response_definition(response_definition&&) noexcept = default;

response_definition& operator=(response_definition&&) noexcept

= default;

// Meaningful only when valid().

source_kind kind() const noexcept {

return impl_ ? impl_->body->kind : source_kind::owned_bytes;

}

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

// The frozen status and base fields. For an invalid definition

// these return shared empty instances. The fields never include

// overlay content: a send merges its overlay into a local copy.

const http::status& status() const noexcept {

static const http::status empty;

return impl_ ? impl_->status : empty;

}

const http::fields& fields() const noexcept {

static const http::fields empty;

return impl_ ? impl_->fields : empty;

}

private:

// The one send-side reach into the frozen state: prepare_send

// hands the cursor the body block. Consumers never see the impl.

friend http::outcome detail::prepare_send(const response_definition&,

const response_overlay&,

http::fields&,

detail::send_cursor&);

// The frozen state. Built locally by a factory as a `build`,

// validated in full, and only then shared immutably

// (`shared_ptr<const impl>` makes the immutability structural: no

// API can reach a mutable reference). The body rides as its own

// shared immutable block so a live send's cursor pins it

// independently of this object.

struct impl {

http::status status;

http::fields fields;

std::shared_ptr<const detail::response_body_source> body;

};

// A factory's pending, still-private assembly: like impl but the

// body is a plain value. validate/commit are its only consumers;

// a failed build is discarded without ever being shared.

struct build {

http::status status;

http::fields fields;

detail::response_body_source body;

};

// Full validation of the assembled state; nothing is mutated on

// failure (the caller never touches `out` before this returns ok).

static http::outcome validate(const build& state) {

if (!state.status.valid()) {

return http::outcome(

http::outcome_code::invalid_argument,

"response_definition: status code is invalid");

}

const http::outcome wire =

detail::check_fields_wire_safe(state.fields);

if (!wire.ok()) return wire;

const http::outcome framing =

detail::check_fields_framing(state.fields);

if (!framing.ok()) return framing;

if (state.body.kind == source_kind::reopen_file

&& state.body.path.empty()) {

return http::outcome(

http::outcome_code::invalid_argument,

"response_definition: reopen_file requires a path");

}

if (state.body.kind == source_kind::factory && !state.body.make) {

return http::outcome(

http::outcome_code::invalid_argument,

"response_definition: factory requires a callable");

}

if (state.body.kind == source_kind::borrowed

&& !state.body.lease.valid()) {

return http::outcome(

http::outcome_code::invalid_argument,

"response_definition: borrowed requires a lease");

}

return http::outcome::okay();

}

// Validates `state` and, only on success, freezes it into `out`:

// the body block becomes its own shared immutable piece, so the

// definition and any in-flight cursor alias one frozen source.

static http::outcome commit(build&& state, response_definition& out) {

const http::outcome checked = validate(state);

if (!checked.ok()) return checked;

impl frozen;

frozen.status = std::move(state.status);

frozen.fields = std::move(state.fields);

frozen.body = std::make_shared<const detail::response_body_source>(

std::move(state.body));

out.impl_ = std::make_shared<const impl>(std::move(frozen));

return http::outcome::okay();

}

std::shared_ptr<const impl> impl_;

const response_overlay& overlay) {

http::fields merged = def.fields();

for (const http::fields::entry e : overlay.headers.entries()) {

merged.append(e.name, e.value);

}

return merged;

for (const std::string_view name :

{"Transfer-Encoding", "Content-Length", "Host"}) {

if (trailers.count(name) > 0) {

return http::outcome(

http::outcome_code::invalid_argument,

"response fields: '" + std::string(name)

+ "' cannot be a trailer");

}

}

return http::outcome::okay();

const http::outcome headers =

check_fields_wire_safe(overlay.headers);

if (!headers.ok()) return headers;

const http::outcome trailers =

check_fields_wire_safe(overlay.trailers);

if (!trailers.ok()) return trailers;

return check_trailer_names(overlay.trailers);

const response_overlay& overlay,

http::fields& merged,

send_cursor& cursor) {

if (!def.valid()) {

return http::outcome(

http::outcome_code::invalid_argument,

"send_definition: definition is empty");

}

const http::outcome overlay_ok = check_overlay(overlay);

if (!overlay_ok.ok()) return overlay_ok;

merged = merge_send_fields(def, overlay);

const http::outcome framing = check_fields_framing(merged);

if (!framing.ok()) return framing;

const std::shared_ptr<const response_body_source>& body =

def.impl_->body;

const http::outcome prepared = cursor.prepare(body, merged);

if (!prepared.ok()) return prepared;

if (body->kind == response_source_kind::reopen_file

|| body->kind == response_source_kind::owned_file) {

// The pinned size is per send: the file is re-observed (or the

// transferred handle probed) every time, never baked into the

// definition.

pin_content_length(merged, cursor.file_size());

}

return http::outcome::okay();

std::size_t& body_bytes) {

for (;;) {

const body_chunk chunk = cursor.pull();

if (!chunk.status.ok()) co_return chunk.status;

if (!chunk.data.empty()) {

const body_write written =

co_await x.writer().write(chunk.data);

if (!written.status.ok()) co_return written.status;

body_bytes += chunk.data.size();

}

if (chunk.end) co_return http::outcome::okay();

}

const response_definition& def,

response_overlay overlay = {}) {

send_report report;

if (x.disconnected()) {

report.status = http::outcome(

http::outcome_code::connection_closed,

"send_definition: exchange is disconnected");

co_return report;

}

http::fields merged;

detail::send_cursor cursor;

report.status = detail::prepare_send(def, overlay, merged, cursor);

if (!report.status.ok()) co_return report;

report.status = x.start_response(def.status(), merged);

if (!report.status.ok()) co_return report;

report.status =

co_await detail::stream_body(x, cursor, report.body_bytes);

if (!report.status.ok()) co_return report;

const body_finish finished =

co_await x.writer().finish(overlay.trailers);

report.status = finished.status;

co_return report;