API-Reference.md

# API Reference

This page provides a reference for Elio's public API.

For responsibility boundaries, thread-safety defaults, lifetime preconditions,
and audit triage rules, see [[API Contracts]]. The reference below describes
surface area and usage; the contract page defines what Elio guarantees and
what callers must provide for each public interface.

## Namespaces

| Namespace | Description |
|-----------|-------------|
| `elio` | Root namespace |
| `elio::coro` | Coroutine types |
| `elio::runtime` | Scheduler and workers |
| `elio::io` | I/O context and backends |
| `elio::signal` | Signal handling with signalfd |
| `elio::net` | TCP networking |
| `elio::http` | HTTP client/server |
| `elio::websocket` | Convenience re-export of WebSocket support |
| `elio::sse` | Convenience re-export of Server-Sent Events support |
| `elio::tls` | TLS/SSL support |
| `elio::sync` | Synchronization primitives |
| `elio::time` | Timers |
| `elio::log` | Logging |
| `elio::hash` | Hash and checksum functions |
| `elio::rpc` | RPC framework |
| `elio::rdma` | RDMA verbs abstraction (core, header-only, `ELIO_ENABLE_RDMA`) |
| `elio::rdma_cm` | RDMA Connection Manager helpers (`ELIO_ENABLE_RDMA_CM`) |
| `elio::rdma_ibverbs` | Reference libibverbs backend + endpoint (`ELIO_ENABLE_RDMA_IBVERBS`) |
| `elio::rdma_cuda` | CUDA GPUDirect RDMA helpers (`ELIO_ENABLE_RDMA_CUDA`) |

---

## Coroutines (`elio::coro`)

### `task<T>`

The primary coroutine type.

```cpp
template<typename T = void>
class task {
public:
    using promise_type = /* implementation */;
    
    // Non-copyable, move-only
    task(const task&) = delete;
    task& operator=(const task&) = delete;
    task(task&&) noexcept;
    task& operator=(task&&) noexcept;
    
    ~task();  // Destroys the coroutine frame

    bool valid() const noexcept;
    explicit operator bool() const noexcept;
    
    // Awaitable interface (use with co_await)
    bool await_ready() const noexcept;
    template<typename AwaiterPromise>
    std::coroutine_handle<> await_suspend(
        std::coroutine_handle<AwaiterPromise> awaiter);
    T await_resume();  // Returns result or rethrows exception
};
```

`task<T>` is a single-shot lazy owner. Moving it transfers only ownership of
the unstarted coroutine frame and leaves the source empty; it does not migrate
running work or pending I/O. An unstarted task does not remain in creator-thread
virtual-stack state; ancestry is bound to the actual awaiter when execution
starts. Destroying a non-empty task destroys the frame if ownership has not
been transferred to the runtime. Do not await an empty task or await the same
task more than once.

In 0.6, `await_suspend` is a potentially throwing template. A normal
Elio-to-Elio direct await binds the child to the logical vthread's existing
context without allocating. Context materialization may still allocate for a
raw-resumed deferred parent, a foreign-promise boundary, or the isolated
`task_scope()` boundary. Allocation failure propagates from the `co_await`
expression before the child starts. Normal `co_await task` source remains
unchanged, but code that names the exact `await_suspend` member type or requires
it to be `noexcept` must be updated. A foreign coroutine promise does not
implicitly inherit an Elio runtime token; adapter code must bridge cancellation
explicitly when that behavior is required.

**Basic Usage:**
```cpp
coro::task<int> compute() {
    co_return 42;
}

coro::task<void> example() {
    int result = co_await compute();  // Direct await
    std::cout << result << std::endl;
}
```

### Spawn Functions

Elio provides free functions for spawning concurrent tasks. Callable overloads
provide automatic callable lifetime safety; rvalue-task overloads transfer an
already-constructed lazy task without a wrapper.

These free functions consult only `scheduler::current()` for the calling
thread and require that scheduler to be running. The lookup is thread-local; a
scheduler running on another thread is not an implicit target. Call an explicit
scheduler member function when the caller does not have the intended scheduler
installed as its current scheduler.

#### `elio::go()` - Fire-and-Forget

Spawn a coroutine without awaiting its result. The coroutine runs independently and self-destructs on completion.

```cpp
template<typename F, typename... Args>
void go(F&& f, Args&&... args);

template<typename T>
void go(coro::task<T>&& task);
```

If the calling thread has no current running scheduler, both overloads log an
error and call `std::abort()`; they do not silently discard the work.

**Example:**
```cpp
coro::task<void> background_work(int x) {
    // Do some work...
    co_return;
}

coro::task<void> main_task() {
    // Spawn and continue immediately (fire-and-forget)
    elio::go(background_work, 42);

    // Transfer an already-constructed task without a wrapper frame
    elio::go(background_work(42));
    
    // Lambda with captures is also safe
    int value = 100;
    elio::go([value]() -> coro::task<void> {
        // 'value' is safely copied into the coroutine frame
        co_return;
    });
    
    co_return;
}
```

#### `elio::go_to()` - Affinity Fire-and-Forget

Spawn a coroutine with affinity to a specific worker thread. The affinity is set before the task first resumes, so the task is not executed on another worker; if a steal attempt observes the task on another queue, the scheduler bounces it back to the target worker.

```cpp
template<typename F, typename... Args>
void go_to(size_t worker_id, F&& f, Args&&... args);

template<typename T>
void go_to(size_t worker_id, coro::task<T>&& task);
```

If the calling thread has no current running scheduler, both overloads log an
error and call `std::abort()`.

`worker_id` should be less than the scheduler's current `num_threads()` for
deterministic placement. Out-of-range values are not rejected, but exact pinning
to that numeric worker is not guaranteed; the scheduler may enqueue through a
fallback path if the selected slot is unavailable during resizing.

**Example:**
```cpp
coro::task<void> io_handler(int fd) {
    // Handle I/O on this specific worker
    co_return;
}

coro::task<void> main_task() {
    // Pin the handler to worker 0 for cache locality
    elio::go_to(0, io_handler, fd);
    co_return;
}
```

> **Note:** `go_to()` differs from spawning with `go()` + `co_await set_affinity()`. With `go_to()`, worker affinity is set before the task is scheduled and before it ever runs. A later steal attempt may briefly remove the task from a queue, but the scheduler checks affinity and requeues it instead of running it on the wrong worker. With `go()` + `set_affinity()`, the task may briefly run on any worker before migrating.

#### Worker Lifetime Lease

Include `<elio/runtime/worker_lease.hpp>` (also in `<elio/elio.hpp>`).

```cpp
auto lease = co_await elio::runtime::lease_current_worker();
size_t owner = lease.worker_id();
uint64_t generation = lease.context_generation();
bool active = lease.active();
// Settle external work and destroy owner-thread resources before release.
lease.release();
```

`external_worker_lease` is move-only with RAII release. It retains the acquiring
logical task's exact worker through normal shrink/drain, independently of
caller affinity. Foreign-thread release is supported with serialized access to
the token. Acquisition rejects retiring workers and shutdown. It does not
drive an external ring or prevent force shutdown. See [[Worker Leases]] for
ownership, progress, and teardown rules.

#### `elio::spawn()` - Joinable

Spawn a coroutine and return a `join_handle` to await the result later.

```cpp
template<typename F, typename... Args>
auto spawn(F&& f, Args&&... args) -> coro::join_handle<T>;

template<typename T>
auto spawn(coro::task<T>&& task) -> coro::join_handle<T>;
```

If the calling thread has no current running scheduler, the callable overload
does not invoke the callable and returns an already-ready, already-destroyed
join handle. Observing its result rethrows `std::logic_error`. For an otherwise
valid direct rvalue task, the direct overload consumes and destroys the task
frame before returning the same terminal exception-bearing handle.

**Example:**
```cpp
coro::task<int> compute(int x) {
    co_return x * 2;
}

coro::task<void> parallel_example() {
    // Spawn multiple tasks concurrently
    auto h1 = elio::spawn(compute, 10);
    auto h2 = elio::spawn(compute, 20);
    auto h3 = elio::spawn(compute, 30);

    // Direct transfer keeps the constructed task's execution context and
    // avoids a callable-wrapper frame.
    auto direct = elio::spawn(compute(40));
    
    // All four run in parallel
    // Now wait for results
    int a = co_await h1;  // 20
    int b = co_await h2;  // 40
    int c = co_await h3;  // 60
    int d = co_await direct;  // 80
    
    ELIO_LOG_INFO("Sum: {}", a + b + c + d);  // 200
}
```

The direct overload consumes a non-empty rvalue task that has not already
completed. Keep using the callable form for an arbitrary temporary coroutine
lambda or member callable: the wrapper owns that callable while its returned
coroutine executes, including implementations whose frame retains the callable
through `this`.

An accepted joinable task from `spawn()`, `scheduler::go_joinable()`, or
`scheduler::go_joinable_to()` retains a failure for
`join_handle::await_resume()`; it does not also route that failure to the
scheduler unhandled-exception handler. Destroying the handle without observing
it intentionally discards the result or exception and does not convert the
task to fire-and-forget reporting. By contrast, an exception escaping a `go()`
or `go_to()` task is reported through the handler because those APIs provide no
observation handle.

#### Spawn Macros

For inline coroutine expressions:

```cpp
// Fire-and-forget macro
ELIO_GO(some_async_operation());

// Spawn macro returning join_handle
auto h = ELIO_SPAWN(compute_async());
auto result = co_await h;
```

These macros expand to lambdas with `[&]` captures. Use them only when every
referenced object outlives the spawned task. For detached work that touches local
state, prefer `elio::go()` / `elio::spawn()` with an explicit capture list:

```cpp
elio::go([value = std::move(value)]() mutable -> coro::task<void> {
    co_await use_value(value);
});
```

### `join_handle<T>`

Handle for awaiting spawned tasks. Returned by `elio::spawn(...)`.

```cpp
template<typename T = void>
class join_handle {
public:
    join_handle(join_handle&& other) noexcept;
    join_handle& operator=(join_handle&& other) noexcept;
    
    // Awaitable interface (use with co_await)
    bool await_ready() const noexcept;
    bool await_suspend(std::coroutine_handle<> awaiter);
    T await_resume();  // Returns result or rethrows exception
    
    // Check if the spawned task has completed (non-blocking)
    bool is_ready() const noexcept;

    // Non-consuming observation (include elio/coro/join_wait.hpp)
    task<join_wait_outcome> wait(cancel_token token = {}) const;
    task<join_wait_outcome> wait_until(
        std::chrono::steady_clock::time_point deadline,
        cancel_token token = {}) const;

    // Observe or wait for coroutine-frame destruction
    bool is_destroyed() const noexcept;
    void wait_destroyed() const;
    auto wait_destroyed_async() const noexcept; // Single-use awaitable, void result

    // Cooperative, best-effort cancellation request
    void request_cancel() const;
    bool is_cancellation_requested() const noexcept;
};
```

`is_ready()` reports result publication and may become true before the spawned
wrapper frame is destroyed. `wait_destroyed()` is for non-coroutine callers that
must wait until a normally completed wrapper has released its frame parameters,
callable, arguments, and captures. Multiple external threads may wait at once;
one release publication from final frame destruction wakes all of them.
Scheduler workers must not call this blocking API.

Use `co_await handle.wait_destroyed_async()` for the same destruction publication
without blocking a worker or occupying the blocking pool. It does not consume the
result, rethrow the task's exception, or request cancellation. Each call creates
an independent, move-only, single-use awaitable that pins the shared join state;
the original handle may subsequently move or be discarded. Multiple destruction
observers may wait concurrently, independently of the existing result waiter.
Teardown writes are visible after a successful await.

An already-destroyed handle completes immediately, even outside a scheduler.
A pending wait requires a current calling-thread Elio scheduler; if none is set,
registration throws `std::logic_error`. Registration may allocate and propagate
allocation failure.
The continuation resumes in the scheduler domain where it registered, not the
observed task's domain. Keeping that scheduler alive and running, and the
coroutine's owner alive, until observation completes is a caller precondition;
registration does not check the scheduler's running state. Do not move an
awaitable while its suspension is active or destroy its coroutine after
scheduling ownership has been claimed.
Destroying a still-registered observer removes its registration, including a
selected wake that has not yet been claimed.

This is not a cancellation/deadline API. A task that never terminates can keep an
observer waiting. Forced shutdown retains its existing restrictions: neither
destruction observer makes asynchronous frame destruction safe, joins abandoned
kernel I/O, or promises normal parameter-teardown ordering on a forced-destruction
path. Use cooperative stop plus normal task drain before releasing borrowed
resources.

**Example:**
```cpp
coro::task<int> compute() {
    co_return 42;
}

coro::task<void> main_task() {
    // Spawn a joinable task
    auto handle = elio::spawn(compute);
    
    // Check completion without blocking
    if (!handle.is_ready()) {
        // Do other work while waiting...
    }
    
    // Await the result
    int result = co_await handle;
    co_await handle.wait_destroyed_async();
    std::cout << "Result: " << result << std::endl;
}
```

See the runnable [capture-teardown example](https://github.com/Coldwings/Elio/blob/main/examples/join_destroyed_async.cpp).
If result observation throws, retain the exception, perform the destruction await
outside the catch handler, then release borrowed resources and propagate/report
the exception. A destruction await does not replace result/error observation.

`request_cancel()` publishes through state shared with the spawned task; it does
not access the coroutine frame and remains valid after frame destruction. The
request propagates through direct lazy-task awaits between Elio tasks. It does
not forcibly destroy the task, roll back side effects, or guarantee prompt
completion. Foreign coroutine promises, separately spawned tasks, and explicit
token arguments remain independent unless deliberately bridged. Registered
cancellation callback exceptions are rethrown after callback dispatch.

#### Bounded result observation

`co_await handle.wait(token)` and `co_await handle.wait_until(deadline, token)`
return `coro::join_wait_outcome::{completed, timed_out, cancelled}`. Include
`elio/coro/join_wait.hpp` (also included by `elio/elio.hpp`). `completed` means
the result is ready, including an exceptional result; it neither consumes `T`
nor rethrows the child failure. Consume the result separately with `co_await
handle` or `await_resume()`, and use a destruction barrier separately when needed.

Initial precedence is result-ready, explicit-token-cancelled, then expired
steady-clock deadline. Those fast paths work outside a scheduler. A pending
observation requires a running scheduler worker; otherwise it throws
`std::logic_error`. Its continuation stays in the observing scheduler domain,
even when the child completes elsewhere. Keep that scheduler and the observer's
coroutine owner alive until the observation returns.

Only one pending result observation, whether direct `co_await handle` or a new
wait, may register at a time. A second pending registration throws
`std::logic_error`; independent destruction observers are unaffected.

Result consumption remains single-owner, including an already-ready handle:
do not consume its result while another consuming await is still active. The
pending-registration rejection is not a concurrent multi-consumer guarantee.

Once registered, completion, cancellation, deadline dispatch, and setup failure
arbitrate through one terminal transition. A later event cannot replace the
winner. Deadline dispatch is cooperative, not a physical-time return guarantee.
Allocation during setup, timer setup, and timer failures can propagate if they
win the terminal transition. Cleanup exceptions are separate: allocating the
private timer's frame-destruction observer can fail after an outcome was
selected. That failure may propagate rather than return the selected outcome;
it does not change the child's result. Internal timer state remains runtime-owned,
so keep the scheduler alive through its eventual cleanup. Successful returns
complete the private timer's result and frame-destruction barriers. The
implementation observes result publication through registration rather than
periodic `is_ready()` checks; timer backend fallback behavior is unchanged.

Timeout or cancellation removes only the result observer. It does not request
child cancellation, destroy a child frame, modify its result, or transfer task
ownership. Private timer work is cancelled and normally drained before return.
Internal cancellation cleanup does not wait for unrelated user callbacks to
finish dispatching. Retry observation after departure, then consume the eventual
result. The default token does not implicitly cancel this wait when the caller's
task is cancelled; pass `this_coro::cancel_token()` explicitly for that policy.

These factories copy shared join state before returning their lazy, single-use
task. The original handle can then move or be discarded without invalidating the
observation. Do not use a moved-from handle or concurrently mutate it while
creating an observation. Normal observer removal does not make destruction of
an actively resumed or scheduling-owned coroutine safe; forced shutdown retains
the existing task/I/O lifetime restrictions.

Applications that leave work running after a bounded wait must own its inputs,
bound outstanding work, and retain an eventual result/failure and drain policy.
Requesting cooperative cancellation is a separate application decision, not a
side effect of waiting. The runnable [owned-background example](https://github.com/Coldwings/Elio/blob/main/examples/join_wait.cpp)
keeps the handle and owned inputs after timeout, observes the eventual result,
and awaits final frame destruction. Returning immediately instead requires an
application-owned background owner; discarding a handle alone is not a drain or
failure-reporting policy. Existing `with_timeout` still drains its losing child.

### `task_group` and `task_scope()`

Structured ownership for child tasks submitted to one scheduler domain.

```cpp
enum class task_group_failure_policy {
    fail_fast,
    collect_all,
};

struct task_group_options {
    task_group_failure_policy failure_policy =
        task_group_failure_policy::fail_fast;
    size_t max_concurrency = 0;  // Zero means unlimited
};

class task_group_error : public std::exception {
public:
    const char* what() const noexcept override;
    const std::vector<std::exception_ptr>& failures() const noexcept;
};

class task_group {
public:
    class join_awaitable;

    explicit task_group(task_group_options options = {});
    explicit task_group(runtime::scheduler& scheduler,
                        task_group_options options = {});

    template<typename F, typename... Args>
    void spawn(F&& function, Args&&... args);

    join_awaitable join() noexcept;
    void request_cancel();
    bool is_cancellation_requested() const noexcept;
    size_t outstanding_children() const noexcept;
    std::vector<std::exception_ptr> failures() const;
    task_group_options options() const noexcept;
    runtime::scheduler& scheduler_domain() const noexcept;
};

template<typename F>
task<void> task_scope(F&& body, task_group_options options = {});

template<typename F>
task<void> task_scope(runtime::scheduler& scheduler, F&& body,
                      task_group_options options = {});
```

The explicit-scheduler `task_scope()` overload must initially be awaited on a
worker of that scheduler. It does not dispatch initial entry from another
scheduler or from an external thread, including the thread that called
`scheduler::start()`; violating this precondition throws `std::logic_error`.

The default constructor binds the group to the current scheduler worker and
throws `std::logic_error` when there is none. Merely calling
`scheduler::start()` does not make its calling thread a scheduler worker. The
explicit constructor submits every
child to the selected scheduler. When construction occurs while executing on
that same scheduler, the group links to the current task's cancellation token;
otherwise the group starts with independent cancellation authority.

`spawn()` accepts a callable returning `task<T>`, stores decayed callable and
argument values in scheduler-owned frames, and discards the result value. It
throws after joining has started. Scheduler rejection is recorded as a child
failure and reported by `join()`. A nonzero `max_concurrency` limits child body
execution, not the number of registered or scheduler-queued child frames.
`outstanding_children()` reports those accepted child submissions and does not
include the callback body of an active `task_scope()`.

`join()` is `[[nodiscard]]`, returns a direct single-use awaitable, and must be
awaited while executing on a worker of the group's scheduler. It does not create
or link a nested task, so beginning the join does not allocate a parent
cancellation registration. It stops further spawning, waits until every
registered child frame has left the group, and then reports failures according
to the selected policy. Its
continuation resumes in that scheduler domain; normal completion is queued, and
a same-domain enqueue rejection falls back to direct resumption with the saved
frame context. `join()` must
be awaited exactly once. Under `fail_fast`, the first child failure requests
cooperative sibling cancellation and is rethrown directly. Under `collect_all`,
siblings continue and `join()` throws `task_group_error`; its `failures()` view
contains every recorded exception. A bare group's `failures()` accessor exposes
the same records before or after join. Child code must pass
`this_coro::cancel_token()` to token-aware waits when prompt cancellation is
required.

Children that have not entered their body when group cancellation is already
visible finish without invoking the user callable. Cancellation that races with
body entry remains cooperative; once the callable starts, it must observe or
forward its runtime token.

The `task_group` destructor requests cancellation for unfinished children but
cannot synchronously join from a scheduler worker. Always await `join()` before
destroying a bare group. Prefer `task_scope()` for lexical ownership: it joins
on normal body completion, and on body failure it first requests cancellation,
joins all children, and then rethrows the body failure under `fail_fast`. Under
`collect_all`, concurrent body and child failures are combined into one
`task_group_error`, with the body exception first. If the body succeeds but a
child fails, the child failure is reported after all children finish. The
scope body itself inherits group cancellation, so fail-fast can wake a body that
passes `this_coro::cancel_token()` to its current wait. The body must not call
`join()` on the supplied group; returning from the body initiates the scope's
single join. If a body awaitable resumes on another executor, the scope wrapper
hands execution back to the selected scheduler before joining and resuming its
caller. Both `task_scope()` overloads are `[[nodiscard]]` lazy tasks.
The scope retains the body callable and its captures through child joining.
Automatic local objects in the returned body coroutine are still destroyed
when that coroutine returns; a child that can continue after body return must
not retain references to those locals.

Unlike an ordinary transparent Elio task await, `task_scope()` establishes a
distinct structured-cancellation context. Cancellation of the caller still
flows into the scope, but cancellation selected by the group does not remain
set on the caller after join. The scope inherits caller user affinity and
publishes its final user-affinity value back at return; operation-owned active
I/O pins remain local to the scope context.

`request_cancel()` runs group cancellation callbacks on the selected scheduler.
An ordinary external thread, including the thread that called
`scheduler::start()`, waits for that dispatch and can rethrow a callback
exception. A worker belonging to another scheduler posts the request and returns
without waiting, preventing reciprocal single-worker scheduler deadlocks;
callback failures from that asynchronous path are recorded as group failures.
Keep the selected scheduler running while cancellation or join is pending.

```cpp
coro::task<void> process_batch(std::span<const item> items) {
    co_await coro::task_scope(
        [&](coro::task_group& group) -> coro::task<void> {
            for (const auto& item : items) {
                group.spawn([&item]() -> coro::task<void> {
                    co_await process(item,
                        coro::this_coro::cancel_token());
                });
            }
            co_return;
        },
        {.max_concurrency = 8});
}
```

### `generator<T>`

Async generator for producing a stream of values via symmetric transfer. A single type serves as both the coroutine return type and the consumer interface — the producer coroutine uses `co_yield` to produce values, and the consumer retrieves them via `co_await gen.next()`.

```cpp
template<typename T>
class generator {
public:
    using promise_type = /* implementation */;

    generator();
    generator(generator&& other) noexcept;
    generator& operator=(generator&& other) noexcept;

    // Non-copyable
    generator(const generator&) = delete;
    generator& operator=(const generator&) = delete;

    /// Get the next value. Returns std::nullopt when finished.
    auto next();  // Returns awaitable<std::optional<T>>

    /// Iterate with a callback. If func returns bool, false = early break.
    template<typename F>
    auto for_each(F&& func);  // Returns awaitable<void>

    /// Check if generator is finished.
    [[nodiscard]] bool finished() const noexcept;
};

/// Range-for-like macro (zero overhead, supports break/continue)
#define ELIO_CO_FOR(var, gen)  /* ... */
```

**Basic Usage:**
```cpp
// Producer: generates values using co_yield
generator<int> produce_values(int n) {
    for (int i = 0; i < n; ++i) {
        co_yield i;
    }
}

// Consumer: three iteration styles
coro::task<void> consume() {
    // Style 1: while loop
    auto gen = produce_values(5);
    while (auto val = co_await gen.next()) {
        std::cout << *val << "\n";  // 0, 1, 2, 3, 4
    }

    // Style 2: ELIO_CO_FOR macro (range-for-like, supports break/continue)
    auto gen2 = produce_values(10);
    ELIO_CO_FOR(v, gen2) {
        std::cout << v << "\n";
        if (v >= 4) break;
    }

    // Style 3: for_each method (functional style)
    auto gen3 = produce_values(5);
    co_await gen3.for_each([](int v) {
        std::cout << v << "\n";
    });

    // for_each with early termination (return false to break)
    auto gen4 = produce_values(100);
    co_await gen4.for_each([](int v) -> bool {
        std::cout << v << "\n";
        return v < 5;  // stop when v >= 5
    });
}
```

**With Async Operations:**
```cpp
// Producer can use co_await for async I/O
generator<std::string> read_chunks(net::tcp_stream& stream) {
    char buffer[4096];

    while (stream.is_valid()) {
        auto result = co_await stream.read(buffer, sizeof(buffer));
        if (result.result <= 0) {
            break;
        }

        co_yield std::string(buffer, static_cast<std::size_t>(result.result));
    }
}

coro::task<void> process(net::tcp_stream& stream) {
    auto chunks = read_chunks(stream);
    ELIO_CO_FOR(chunk, chunks) {
        handle_chunk(chunk);
    }
}
```

**Nested Generators:**
```cpp
generator<int> inner(int n) {
    for (int i = 0; i < n; ++i) co_yield i;
}

generator<int> outer() {
    auto g1 = inner(3);
    ELIO_CO_FOR(v, g1) {
        co_yield v + 100;  // 100, 101, 102
    }
}
```

### `cancel_token` and `cancel_source`

Cooperative cancellation mechanism for async operations.

```cpp
namespace elio::coro {

/// Result of a cancellable operation
enum class cancel_result {
    completed,   ///< Operation completed normally
    cancelled    ///< Operation was cancelled
};

/// A token that can be checked for cancellation
class cancel_token {
public:
    using registration = cancel_registration;
    
    cancel_token() = default;  // Empty token (never cancelled)
    
    // Check if cancellation has been requested
    bool is_cancelled() const noexcept;
    
    // Implicit bool conversion (true if NOT cancelled)
    explicit operator bool() const noexcept;
    
    // Register a callback for cancellation
    template<typename F>
    [[nodiscard]] registration on_cancel(F&& callback) const;
    
    // Register a coroutine to resume on cancellation
    // Deprecated: Unsafe with handles suspended on io_awaitables.
    // Pass a cancel_token to the awaitable instead.
    [[deprecated]] [[nodiscard]] registration on_cancel_resume(std::coroutine_handle<> h) const;
};

/// Source for creating cancel tokens and triggering cancellation
class cancel_source {
public:
    cancel_source();  // Create new cancellation state
    
    // Get a token to pass to cancellable operations
    cancel_token get_token() const noexcept;
    
    // Request cancellation (invokes callbacks not reentrantly suppressed)
    void cancel();
    
    // Check if cancelled
    bool is_cancelled() const noexcept;
};

} // namespace elio::coro

namespace elio::coro::this_coro {

// Current runtime task token, or a never-cancelled token outside Elio execution
cancel_token cancel_token() noexcept;

} // namespace elio::coro::this_coro
```

`cancel()` synchronously selects and invokes callbacks on the requesting thread,
then rethrows the first callback exception after dispatching the rest.
Registration teardown suppresses a callback not yet selected by cancellation;
outside callback dispatch, teardown waits once another thread has selected or
started it. During callback reentry, cross-dispatch teardown is deferred instead
of waiting so mutually unregistering callbacks cannot deadlock; the target
payload remains alive through dispatch, but external captured state still needs
synchronization. Self-unregistration and reentrant removal of a later callback
selected by the same synchronous dispatcher are supported. Callbacks can also
overlap when registration races with an already cancelled source.

**Basic Example:**
```cpp
coro::task<void> cancellable_work(coro::cancel_token token) {
    while (!token.is_cancelled()) {
        // Do some work...
        
        // Cancellable sleep
        auto result = co_await time::sleep_for(100ms, token);
        if (result == coro::cancel_result::cancelled) {
            break;  // Exit early
        }
    }
}

coro::task<void> controller() {
    coro::cancel_source source;
    
    // Start work with token
    elio::go(cancellable_work, source.get_token());
    
    // Later, cancel
    co_await time::sleep_for(5s);
    source.cancel();
}
```

**Supported Cancellable Operations:**

| Operation | Usage |
|-----------|-------|
| `time::sleep_for()` | `co_await sleep_for(duration, token)` |
| `rpc_client::call()` | `co_await client->call<Method>(req, timeout, token)` |
| `http::client::get()` | `co_await client.get(url, token)` |
| `websocket::ws_client::connect()` | `co_await client.connect(url, token)` |
| `websocket::ws_client::receive()` | `co_await client.receive(token)` |
| `sse::sse_client::connect()` | `co_await client.connect(url, token)` |
| `sse::sse_client::receive()` | `co_await client.receive(token)` |

RPC client cancellation returns `rpc_error::cancelled` and, after a request has
been written, sends a best-effort cancel frame so context-aware server handlers
can observe `rpc_context::cancel_token`. HTTP, WebSocket, and SSE client
cancellation is propagated into pending socket operations. A token passed to
`connect()` or an HTTP request can abort TCP connect, TLS handshake, request
write, and response-header/body reads. A token passed to WebSocket or SSE
`receive()` can abort a pending frame/event read. Cancelled client operations
return the normal failure shape (`std::nullopt` or `false`) and set `errno` to
`ECANCELED`.

Cancellation is best-effort: actual completion may win a race, I/O side effects
are not rolled back, and a backend that cannot actively abort accepted work may
wait for natural completion. A task-level token only affects operations that
receive or inspect it.

Built-in I/O/timer callbacks for registered waits on a live owner worker reserve
their abort handoff before I/O submission. Requesting cancellation does not
require a fresh abort-executor allocation or an ordinary task-overflow enqueue.
Temporary backend admission rejection retains the request for owner-thread
retry until admission or original-operation retirement. This does not change
the exception contract of user callbacks, guarantee progress under arbitrary
allocation failure, or make cancellation a hard completion deadline. See the
`io_context` ownership and retirement rules below.

### Structured Combinators

```cpp
class combinator_cancelled : public std::runtime_error;

template<typename... Fs>
coro::task<std::tuple</* branch results */...>> when_all(Fs... callables);

template<typename... Fs>
coro::task<std::pair<size_t, /* winner result */>>
when_any(Fs... callables);

template<typename Rep, typename Period, typename F>
coro::task<timeout_result</* callable result */>>
with_timeout(std::chrono::duration<Rep, Period> timeout, F callable);
```

All three helpers return concrete move-only lazy `coro::task` objects, replacing
the dedicated combinator awaitable types from 0.5. They own their callable
objects by value and require execution in a scheduler domain when awaited. Their
branches are registered in one internal `task_group`; no accepted branch is
implicitly detached. Move-only callables must be passed as rvalues.

`when_all()` registers every callable as a group child. A child whose body has
not started when cancellation is already visible may finish without invoking
its callable. After the first failure, `when_all()` requests cancellation of
unfinished siblings, waits for all accepted child frames to leave the group,
and then rethrows the first child failure. Later child failures are
reported through the scheduler's unhandled-exception handler before return. A
failure while transferring a callable into a launched child takes precedence
over child failures because the complete branch set was never accepted. A parent
cancellation request is propagated to the group. If cancellation prevents a
branch from producing the value required by the result tuple, `when_all()` throws
`combinator_cancelled` after drain.

`when_any()` atomically selects the first successful or exceptional branch
completion. It then requests cancellation of every loser and waits for all of
them to terminate before returning the winner. A token-accepting callable
receives its structured child token; a no-argument callable can use
`this_coro::cancel_token()`. A launch-time callable-transfer failure takes
precedence over an already selected winner because the complete branch set was
never accepted. Otherwise, the winner's exception is rethrown. A loser that
throws after winner selection is reported through the current scheduler's
unhandled-exception handler before the combinator returns. If parent cancellation
drains every branch before a winner exists, the operation throws
`combinator_cancelled`.

`with_timeout()` is a structured `when_any()` between the callable and a
cancellable timer. When the timer reports expiry, it selects a timed-out result
and requests cancellation of the callable, but the returned task remains
suspended until the callable reaches a terminal state. Consequently, the
requested duration is not a hard upper bound on return latency. Parent
cancellation is not reported as
timer expiry; if it prevents a result, `combinator_cancelled` is thrown.
If deadline expiry and parent cancellation race before the timer branch publishes
its result, the timer's best-effort cancellation contract applies and either a
timed-out result or `combinator_cancelled` may be observed.

---

## Runtime (`elio::runtime`)

### `scheduler`

Manages coroutine execution across worker threads.

```cpp
class scheduler {
public:
    // Create scheduler with worker threads, wait strategy, and blocking pool size
    explicit scheduler(size_t num_threads = std::thread::hardware_concurrency(),
                       wait_strategy strategy = wait_strategy::blocking(),
                       size_t blocking_threads = 4);
    ~scheduler();
    
    // Start worker threads
    void start();
    
    // Gracefully wait for tracked tasks, then stop workers.
    // Returns true if all tracked work drained before the timeout.
    bool shutdown(std::chrono::milliseconds timeout = std::chrono::milliseconds::max());

    // Stop scheduler workers without graceful coroutine/I/O drain.
    // Accepted scheduler-owned blocking work is drained first.
    void shutdown_force();

    // Inspect or wait for tracked work
    size_t active_tasks() const noexcept;
    bool wait_for_idle(std::chrono::milliseconds timeout = std::chrono::milliseconds::max());
    
    // Hand independent work to the scheduler for its first execution.
    // Construction-time virtual-stack ancestry is detached.
    void spawn(std::coroutine_handle<> handle);
    bool try_spawn(std::coroutine_handle<> handle);

    // Re-enqueue an already-suspended coroutine. Logical await ancestry is
    // preserved so continuation transfer restores the correct parent frame.
    // Rejection leaves the borrowed handle live.
    bool try_schedule(std::coroutine_handle<> handle);
    
    // Spawn a task directly (convenience overload)
    template<typename Task>
    void spawn(Task&& t);  // Accepts any type with release() method

    // High-level scheduler-owned spawning APIs
    template<typename F, typename... Args>
    void go(F&& f, Args&&... args);
    template<typename T>
    void go(coro::task<T>&& task);
    template<typename F, typename... Args>
    void go_to(size_t worker_id, F&& f, Args&&... args);
    template<typename T>
    void go_to(size_t worker_id, coro::task<T>&& task);
    template<typename F, typename... Args>
    coro::join_handle</* task value */> go_joinable(F&& f, Args&&... args);
    template<typename T>
    coro::join_handle<T> go_joinable(coro::task<T>&& task);
    template<typename F, typename... Args>
    coro::join_handle</* task value */> go_joinable_to(size_t worker_id, F&& f, Args&&... args);
    template<typename T>
    coro::join_handle<T> go_joinable_to(size_t worker_id, coro::task<T>&& task);

    // Initial ownership handoff toward a worker; detaches construction ancestry.
    void spawn_to(size_t worker_id, std::coroutine_handle<> handle);

    // Re-enqueue suspended work toward a worker; preserves await ancestry.
    bool try_schedule_to(size_t worker_id, std::coroutine_handle<> handle);

    // For targeted spawn and schedule APIs, exact placement requires
    // worker_id in [0, num_threads()) and an available target worker. Larger
    // values or unavailable targets use fallback scheduling.

    // Get the logical number of workers currently visible for scheduling.
    // Retiring worker threads may still be draining outside this range.
    size_t num_threads(std::memory_order order = std::memory_order_relaxed) const noexcept;

    // Get pending queue and I/O load across visible and draining workers.
    size_t pending_tasks() const noexcept;

    // Get total tasks executed across all workers
    size_t total_tasks_executed() const noexcept;

    // Get tasks executed by a specific worker
    size_t worker_tasks_executed(size_t worker_id) const noexcept;

    // Get steal counters
    size_t total_steals_executed() const noexcept;
    size_t worker_steals_executed(size_t worker_id) const noexcept;

    // Check scheduler state
    bool is_running() const noexcept;
    bool is_paused() const noexcept;

    // Pause/resume task execution
    void pause();
    void resume();

    // Dynamically resize the logical scheduling pool.
    // Must be called from outside scheduler worker threads.
    void set_thread_count(size_t count);

    // Get the current scheduler (thread-local)
    static scheduler* current() noexcept;

    // Advanced accessors
    worker_thread* get_worker(size_t index);
    const wait_strategy& get_wait_strategy() const noexcept;
    blocking_pool* get_blocking_pool() noexcept;

    // Unhandled exception reporting for detached tasks and discarded
    // structured-combinator branches
    using unhandled_exception_handler = std::function<void(std::exception_ptr)>;
    void set_unhandled_exception_handler(unhandled_exception_handler handler);
    const unhandled_exception_handler* get_unhandled_exception_handler() const noexcept;
    void report_unhandled_exception(std::exception_ptr ex) noexcept;
};
```

The unhandled-exception handler APIs are thread-safe with each other. A report
keeps its selected handler alive and invokes it without holding the publication
lock, so replacing the handler concurrently affects later snapshots and a
handler may replace itself. Applications remain responsible for synchronizing
mutable state captured by the handler. A pointer returned by
`get_unhandled_exception_handler()` is backed by a shared snapshot owned by the
calling thread. It remains valid until that same thread calls the getter again
or exits, even if another thread replaces or clears the scheduler handler.

The raw-handle APIs have distinct ownership and virtual-stack contracts.
`spawn()`/`try_spawn()` and `spawn_to()` are for an independent handle before
its first execution; they detach construction-time ancestry.
`try_schedule()` and `try_schedule_to()` are for a coroutine that has already
suspended and must preserve the logical parent established by its await chain.
When `try_schedule()` is called from one of the scheduler's active workers, an
eligible continuation is published directly to that worker's local deque.
Valid affinity to another worker still routes there, and an active I/O pin
always follows its backend owner. Initial admission through `spawn()`, `go()`,
and their variants retains normal distribution semantics.
While a worker remains continuously runnable, it
periodically services external submissions and pending I/O. The bounds are
measured in completed task dispatches from the main worker loop: the external
inbox is checked at most every 256 dispatches, and pending I/O receives a
non-blocking poll at most every 16,384 dispatches. These are cooperative
scheduling bounds, not wall-clock deadlines; a coroutine that does not suspend
can still occupy its worker indefinitely. Coroutines resumed inline while a
backend delivers a completion batch are part of that poll and do not consume
the worker-loop dispatch budget.
The `try_` APIs borrow the handle: rejection leaves it live, and the caller must
resume, retain, destroy, or otherwise resolve it. `spawn()` and `spawn_to()`
consume ownership and destroy a handle rejected before execution. Internal wake
and affinity-migration paths handle rejection explicitly; callers must not
substitute one family for the other.
Materializing an independent execution context before initial publication can
throw. On that exception, `try_spawn()` leaves the borrowed handle live;
`spawn()` and `spawn_to()` destroy their consumed handle and then rethrow.

`shutdown()` is the graceful path. Before waiting, it atomically closes
independent initial task admission against `go()`, `go_to()`, `go_joinable()`,
`go_joinable_to()`, `spawn()`, `try_spawn()`, and `spawn_to()`. Work accepted
before that boundary may still enqueue continuations through `try_schedule()` or
`try_schedule_to()` and register structured task-group children while the
scheduler drains. Task-group submission from outside the scheduler remains
independent admission and is rejected after closure. Before teardown, shutdown
seals linked child registration and rechecks the tracked accepted set under the
lifecycle lock. A running raw task that is not itself tracked therefore cannot
register a new child after shutdown has observed the accepted set empty. The call
waits for tracked work, including work suspended on scheduler-owned I/O, and
returns whether the drain completed before the timeout. A rejected `go()` body
does not run; a rejected `go_joinable()` handle reports `std::logic_error`;
rejected raw-handle calls keep or destroy ownership according to the
`try_`/consuming distinction above. Use `shutdown_force()` only when
non-graceful teardown is required: it does not wait for tracked coroutine or
pending-I/O drain, but it may still wait for already-accepted scheduler-owned
blocking work before stopping workers.

Graceful shutdown does not itself request application-level service loops to
stop. Before calling unbounded `shutdown()`, signal or cancel accept loops,
periodic timers, and other long-running tasks, wake any non-cancellable wait,
and wait for those tasks to finish. If the application cannot guarantee that
drain, pass a finite timeout and handle a `false` result; once the budget
expires, shutdown force-stops the remaining work and may orphan in-flight I/O.

A scheduler has a one-shot lifecycle. Once either shutdown path begins, later
`start()` calls are no-ops; create a new scheduler for another run. Concurrent
shutdown callers share one teardown, and external callers wait for a teardown
initiated by a scheduler worker before returning. Destroying a scheduler from
one of its own worker threads is unsupported and terminates the process because
the scheduler cannot safely join and release the currently executing worker.
Once shutdown begins, `set_thread_count()` also leaves the configured worker
count unchanged. If a draining worker requests force shutdown while an external
grow is waiting to join that same worker, the worker records the request and
returns; the grow controller performs teardown after the worker unwinds. Use an
external lifecycle owner when the caller must observe complete teardown.

`set_thread_count()` must be called from outside scheduler worker threads. If a
worker thread calls it, Elio logs a warning and leaves the worker count
unchanged to avoid deadlocking a resize path that may wait for and join a
draining worker.

Shrinking publishes the lower logical `num_threads()` value and returns after
starting worker retirement; it does not wait for the removed physical threads
to exit. Each retiring worker continues polling its own I/O context until both
pending backend work and active operation pins reach zero. `active_tasks()` and
`pending_tasks()` include that draining work even though its owner is outside
the logical worker range. A later grow that reuses the slot waits for the old
worker to finish draining and can therefore wait as long as the outstanding
I/O. Operations that must not delay reclamation need their own deadline or
cancellation path. A finite `shutdown()` budget and `shutdown_force()` can
interrupt the drain only by entering non-graceful teardown, which may orphan
in-flight I/O.

**Example:**
```cpp
runtime::scheduler sched(4);
sched.start();

// Spawn tasks directly (pass callable, not invoked task)
sched.go(my_coroutine);

sched.shutdown();
```

### `worker_thread`

Individual worker that executes tasks. Workers use a unified idle mechanism where both I/O completions and task submissions wake the same poll wait.

```cpp
class worker_thread {
public:
    // Schedule a task to this worker (thread-safe, wakes worker as needed).
    // A full bounded inbox spills to a locked overflow queue; false means the
    // worker has stopped and the caller retains the handle.
    bool schedule(std::coroutine_handle<> handle);

    // Schedule from owner thread (faster, no wake needed)
    void schedule_local(std::coroutine_handle<> handle);

    // Wake this worker if sleeping (called automatically by schedule())
    void wake() noexcept;

    // Get/set the wait strategy for this worker
    const wait_strategy& get_wait_strategy() const noexcept;
    void set_wait_strategy(wait_strategy strategy) noexcept;

    // Get worker ID
    size_t worker_id() const noexcept;

    // Check if running
    bool is_running() const noexcept;

    // Explicitly opt in to exact per-resume timestamp diagnostics.
    void enable_task_time_tracking() noexcept;

    // Return the latest recorded time. For backward compatibility this also
    // enables tracking when the explicit mutator was not called first. Prefer
    // scheduler counters for periodic monitoring because they do not enable
    // clock reads on every resume.
    std::chrono::steady_clock::time_point last_task_time() const noexcept;

    // Get current worker (thread-local)
    static worker_thread* current() noexcept;
};
```

**Idle Behavior:**
- Workers block efficiently on I/O poll (with eventfd wake support) when no tasks are available
- Optional spin phase before blocking (configurable via `wait_strategy`)
- Cross-thread submissions automatically wake a blocked worker. A burst shares
  one outstanding eventfd notification; before blocking again, the worker
  clears the wake claim and rechecks its external queues so no wake is lost
- The bounded MPSC inbox remains the fast path; a locked overflow queue absorbs rare bursts without resuming worker-bound coroutines on submitter threads
- A continuously runnable worker receives periodic service points:
  external submissions are transferred every 256 completed worker-loop task
  dispatches and pending I/O is polled non-blockingly every 16,384 dispatches.
  User code must suspend for either cooperative bound to advance; inline
  resumes delivered by one backend poll are not separate worker-loop dispatches
- Results in near-zero CPU usage (< 1%) when idle with default blocking strategy

### `wait_strategy`

Configuration for how workers wait when idle.

```cpp
struct wait_strategy {
    size_t spin_iterations = 0;  // Spin count before blocking (0 = pure blocking)
    bool spin_yield = false;     // Yield during spin (true = friendlier to other threads)

    // Preset strategies
    static constexpr wait_strategy blocking() noexcept;      // Default: pure blocking
    static constexpr wait_strategy spinning(size_t n) noexcept;  // Spin with pause
    static constexpr wait_strategy hybrid(size_t n) noexcept;    // Spin with yield, then block
    static constexpr wait_strategy aggressive(size_t n = 1000) noexcept;  // More spinning
};
```

**Example:**
```cpp
// Low-latency scheduler with hybrid waiting
scheduler sched(4, wait_strategy::hybrid(1000));

// Ultra-low latency with dedicated CPUs
scheduler sched(4, wait_strategy::spinning(2000));
```

### `run_config`

Configuration for running async tasks.

```cpp
struct run_config {
    size_t num_threads = 0;           // 0 = hardware concurrency
    size_t blocking_threads = 4;      // Blocking thread pool size
    std::chrono::milliseconds shutdown_timeout = std::chrono::milliseconds::max();
};
```

### `run()`

Run a coroutine to completion.

```cpp
// Run callable returning task with configuration
template<typename F>
auto run(F&& f, const run_config& config = {}) -> task_value_t<invoke_result_t<F>>;

// Run callable with arguments and config first
template<typename F, typename... Args>
auto run(const run_config& config, F&& f, Args&&... args) -> task_value_t<invoke_result_t<F, Args...>>;

// Run callable with arguments (no config)
template<typename F, typename Arg0, typename... Args>
auto run(F&& f, Arg0&& arg0, Args&&... args) -> task_value_t<invoke_result_t<F, Arg0, Args...>>;
```

On the first invocation through the `run()` entry path, Elio installs
`SIG_IGN` for `SIGPIPE` with `sigaction`. This changes the process-wide signal
disposition; it does not change a per-thread signal mask. Elio does not save or
restore the prior disposition, and later `run()` calls do not reapply the
ignore disposition if application code changes it after that first install.

**Example:**
```cpp
coro::task<int> async_main(int argc, char* argv[]) {
    co_return 42;
}

int main(int argc, char* argv[]) {
    return elio::run(async_main, argc, argv);
}

// With configuration
int main(int argc, char* argv[]) {
    elio::run_config config;
    config.num_threads = 4;
    return elio::run(config, async_main, argc, argv);
}
```

### `ELIO_ASYNC_MAIN` Macro

A single `ELIO_ASYNC_MAIN(func)` macro handles all four signature combinations via compile-time dispatch:

| Supported signature | Description |
|---------------------|-------------|
| `task<int>(int, char**)` | With args, returns exit code |
| `task<void>(int, char**)` | With args, always exits 0 |
| `task<int>()` | No args, returns exit code |
| `task<void>()` | No args, always exits 0 |

**Example:**
```cpp
coro::task<int> async_main(int argc, char* argv[]) {
    if (argc < 2) {
        std::cerr << "Usage: " << argv[0] << " <arg>\n";
        co_return 1;
    }
    co_await do_work(argv[1]);
    co_return 0;
}

ELIO_ASYNC_MAIN(async_main)
```

The macro dispatches through `elio::run()` and therefore has the same
process-wide `SIGPIPE` disposition side effect.

---

## Server Lifecycle (`elio`)

### `serve()`

Run a server until a shutdown signal is received.

```cpp
// Serve a single server with graceful shutdown
template<typename Server, typename ListenFunc>
    requires std::invocable<ListenFunc>
coro::task<void> serve(Server& server, ListenFunc listen_func,
                       std::initializer_list<int> signals = {SIGINT, SIGTERM});
```

The first invocation through the server entry path installs process-wide
`SIG_IGN` for `SIGPIPE`. This also applies when `serve()` is used with a custom
scheduler and without `run()` or `ELIO_ASYNC_MAIN`; the server path has its own
one-time installation guard.

The function:
1. Spawns the listen function in the background
2. Waits for a shutdown signal (SIGINT or SIGTERM by default)
3. Calls `server.stop()` when signal is received
4. Waits for the listen task to complete

For process-directed signals to be consumed by `signalfd`, block the same
shutdown signals before scheduler threads are created. Use an explicit
`main()` that calls `signal_set::block_all_threads()` before `elio::run()`;
`ELIO_ASYNC_MAIN` does not mask the calling thread.

**Example:**
```cpp
coro::task<int> async_main(int argc, char* argv[]) {
    http::router r;
    r.get("/", handler);

    http::server srv(r);

    // serve() listens, waits for masked shutdown signals, and stops cleanly
    co_await elio::serve(srv, [&]() { return srv.listen(addr); });

    co_return 0;
}

int main(int argc, char* argv[]) {
    elio::signal::signal_set shutdown_signals(elio::default_shutdown_signals);
    shutdown_signals.block_all_threads();
    return elio::run(async_main, argc, argv);
}
```

### `serve_all()`

Run multiple servers until shutdown.

```cpp
template<typename... Servers, typename... ListenFuncs>
coro::task<void> serve_all(std::tuple<Servers&...> servers,
                           std::tuple<ListenFuncs...> listen_funcs,
                           std::initializer_list<int> signals = {SIGINT, SIGTERM});
```

`serve_all()` has the same server-entry `SIGPIPE` disposition behavior as
`serve()`.

**Example:**
```cpp
coro::task<void> run_servers() {
    http::server http_srv(http_router);
    websocket::ws_server ws_srv(ws_router);

    co_await elio::serve_all(
        std::tie(http_srv, ws_srv),
        std::make_tuple(
            [&]() { return http_srv.listen(http_addr); },
            [&]() { return ws_srv.listen(ws_addr); }
        )
    );
}

int main() {
    elio::signal::signal_set shutdown_signals(elio::default_shutdown_signals);
    shutdown_signals.block_all_threads();
    return elio::run(run_servers);
}
```

### `wait_shutdown_signal()`

Wait for shutdown signals without managing a server.

```cpp
coro::task<signal::signal_info> wait_shutdown_signal(
    std::initializer_list<int> signals = {SIGINT, SIGTERM});
```

**Example:**
```cpp
coro::task<void> custom_server_loop() {
    // Start server tasks...

    auto sig = co_await elio::wait_shutdown_signal();
    ELIO_LOG_INFO("Received {}, shutting down...", sig.full_name());

    // Custom shutdown logic...
}
```

---

## Thread Affinity (`elio::runtime`)

Thread affinity allows you to bind vthreads (coroutines) to specific worker threads so they run on a designated worker. Steal attempts that encounter an affinity-bound task are redirected to the bound worker instead of executing the task on the wrong worker.

### Constants

```cpp
// Constant indicating no caller affinity (internal ownership may still pin)
inline constexpr size_t NO_AFFINITY = std::numeric_limits<size_t>::max();
```

### `current_worker_id()`

Get the current worker thread ID.

```cpp
size_t current_worker_id() noexcept;
```

Returns the worker ID if called from a worker thread, or `NO_AFFINITY` if called from outside the scheduler.

### `set_affinity()`

Bind the current vthread to a specific worker thread.

```cpp
auto set_affinity(size_t worker_id, bool migrate = true);
```

- `worker_id`: The worker thread to bind to
- `migrate`: If true (default), migrate to the target worker immediately

**Example:**
```cpp
coro::task<void> pinned_task() {
    // Bind to worker 0 and migrate there
    co_await set_affinity(0);
    
    // Now subsequent code runs on worker 0 while affinity remains valid
    // Steal attempts are bounced back to the affinity worker
    co_return;
}
```

### `clear_affinity()`

Remove caller-requested affinity, allowing the vthread to migrate freely when
no internal ownership constraint is active. This does not clear or migrate an
active worker-local I/O operation.

```cpp
auto clear_affinity();
```

**Example:**
```cpp
coro::task<void> temporary_pin() {
    co_await set_affinity(2);
    // Critical section on worker 2...
    
    co_await clear_affinity();
    // Can now migrate to any worker
    co_return;
}
```

### `bind_to_current_worker()`

Bind the vthread to whatever worker it's currently running on.

```cpp
auto bind_to_current_worker();
```

**Example:**
```cpp
coro::task<void> stay_here() {
    // Pin to current worker, wherever we are
    co_await bind_to_current_worker();
    
    // Will not migrate for rest of execution
    co_return;
}
```

### Task Execution Context And Promise Affinity

`promise_base` is the frame-resident anchor for a shared
`task_execution_context`. The task object itself does not carry scheduler
policy. Directly awaited Elio frames share the logical-vthread root's context;
external runtime owners may share it without keeping any frame alive.

```cpp
namespace elio::coro {

class task_execution_context {
public:
    // Allocates cancellation state and may throw std::bad_alloc in 0.6
    task_execution_context();

    size_t user_affinity() const noexcept;
    size_t effective_affinity() const noexcept;
    void set_user_affinity(size_t worker_id) noexcept;
    bool has_user_affinity() const noexcept;
    void clear_user_affinity() noexcept;

    // Read-only operation-local I/O ownership diagnostics
    bool has_active_io_pin() const noexcept;
    size_t io_owner_worker() const noexcept;
    uint64_t io_context_generation() const noexcept;
    size_t active_io_pin_count() const noexcept;

    // Internal scheduler-maintenance policy
    void set_worker_local(bool worker_local = true) noexcept;
    bool is_worker_local() const noexcept;

    // Task-chain cancellation control
    cancel_token get_cancel_token() const noexcept;
    void request_cancel();
    bool is_cancellation_requested() const noexcept;
};

} // namespace elio::coro
```

`io_owner_worker()` and `io_context_generation()` expose the last recorded
identity. Treat them as an active placement constraint only when
`has_active_io_pin()` is true; `active_io_pin_count()` is authoritative.

The context's cancellation state survives independently of frames through
shared ownership. Runtime-created contexts co-allocate this state in one shared
control block; a token uses aliasing ownership and can outlive the frame that
produced it. Elio-to-Elio direct `co_await` binds an unstarted child to the
actual awaiter's context. This requires no parent callback registration and
makes cancellation, affinity changes, and active I/O ownership continuous
through transparent helper frames. A retained child token names and may retain
the surrounding logical-vthread context after the child completes.

Independent scheduler and task-group roots materialize distinct contexts before
first resume. Structured roots that inherit cancellation use a weak,
completion-scoped parent registration; final suspend deactivates that link with
a non-waiting atomic transition. `task_scope()` deliberately uses this isolated
model even when directly awaited, so group cancellation cannot poison its
caller. A foreign coroutine promise is also a context and cancellation boundary
unless it deliberately bridges a token. A
`join_handle` shares its spawned root's context, so cancellation remains
race-safe without a raw promise pointer. Completion and cancellation of
individual operations remain in their awaitable/backend state machines.

An unstarted task created inside an active Elio frame may not have a materialized
context yet. Runtime integrations that bypass task `co_await`, `spawn()`, or a
scheduler handoff must establish an independent context before inspecting its
policy or resuming its raw coroutine handle.

In 0.6, standalone construction is no longer `noexcept` because it allocates an
independent cancellation state. Runtime construction can likewise fail while
allocating the combined shared control block. Allocation failure propagates to
the code creating the context; downstream code that explicitly relied on the
old `noexcept` constructor contract must be updated.

The promise affinity methods delegate caller-requested affinity to that shared
context. `effective_affinity()` is the scheduler placement boundary and is kept
distinct from caller affinity. An active I/O owner takes precedence over user
affinity; clearing or changing user affinity does not clear the operation pin:

```cpp
class promise_base {
public:
    std::shared_ptr<task_execution_context> execution_context() const noexcept;

    // Get current affinity (NO_AFFINITY if not set)
    size_t affinity() const noexcept;

    // Get the scheduler placement constraint
    size_t effective_affinity() const noexcept;
    
    // Set affinity to a specific worker
    void set_affinity(size_t worker_id) noexcept;
    
    // Check if affinity is set
    bool has_affinity() const noexcept;
    
    // Clear affinity (allow migration)
    void clear_affinity() noexcept;
};
```

---

## I/O (`elio::io`)

### `io_context`

Manages async I/O operations.

```cpp
class io_context {
public:
    io_context();
    ~io_context();

    // Scheduler ownership diagnostics. Standalone contexts report no owner.
    bool is_worker_owned() const noexcept;
    size_t owner_worker_id() const noexcept;
    uint64_t generation() const noexcept;
    size_t active_pin_count() const noexcept;

    // Low-level mutation. Scheduler contexts require their exact owner thread.
    bool prepare(const io_request& request);
    int submit();
    bool cancel(void* user_data);
    
    // Poll for I/O completions (with optional timeout)
    int poll(std::chrono::milliseconds timeout = std::chrono::milliseconds::zero());

    // Cross-thread-safe wakeup entry
    void notify() noexcept;
    
    // Read-only diagnostics
    bool has_pending() const noexcept;
    size_t pending_count() const noexcept;

    // Most recent built-in-backend completion on the calling thread.
    static io_result get_last_result() noexcept;
};

// Get the current scheduler worker's I/O context, or the global fallback
// outside a scheduler worker.
io_context& current_io_context() noexcept;

// Get the default global I/O context.
io_context& default_io_context();
```

Scheduler workers own their contexts. I/O awaitables validate that a
scheduler-owned context is used only on its owner worker and pin the awaiting
coroutine to that context generation until backend completion or orphan
cleanup. Work stealing and affinity migration cannot move the continuation
while the pin is active. A retiring worker continues polling until both its
backend pending count and active pin count are zero.

Both built-in backends make `poll()` self-driving for staged work: the
io_uring backend auto-submits staged SQEs from `poll()`, and the epoll
backend drains queued synchronous operations (close) at the top of `poll()`.
Poll-only drivers — scheduler worker loops and the standalone
`run()`/`run_for()`/`run_until_complete()` helpers — therefore complete
`async_close` without an explicit `submit()` call. `submit()` remains public
and idempotent for raw-backend users that drive it manually.

A directly constructed `io_context` is standalone. The caller must serialize
access, poll it, and keep it alive for all pending operations. Scheduler
coroutines must use their current worker context; they cannot submit through a
standalone context or another worker's context. Mutating context operations
enforce the exact owner thread and throw `std::logic_error` on violation, while
`notify()` is a non-throwing cross-thread wakeup. Mutable raw-backend access is
not exposed.

Standard awaitables used from a non-Elio coroutine promise retain context-level
drain accounting and complete on the backend owner, but cannot install an Elio
task execution-context pin. A custom coroutine runtime that independently
re-enqueues such a suspended handle must preserve that owner itself.

Built-in token-aware I/O, timer, TCP, and UDS awaiters reserve an intrusive
owner-worker maintenance request and its lifetime ownership before registration
and submission. Their cancellation callbacks publish that request without a new
executor allocation or the ordinary task queue's allocating overflow path.
Temporary backend cancellation-admission failure leaves the request pending;
the owner retries after driving backend progress. Admission stops retries, while
the original operation's completion remains responsible for resumption.

Each attempt checks backend ownership/context generation and arbitrates use of
the cancellation key against permanent retirement. Awaiters retire that key
before their base-class orphan transfer can release the associated `op_state`.
Retirement makes queued retries no-ops; an already executing attempt finishes
its key use on the owner without blocking awaiter teardown. Releasing an attempt
does not reopen a retired key. This prevents address reuse from redirecting an
old cancellation to a new operation. Graceful drain and retiring workers service
pending maintenance. Epoll removes a cancelled timer from its heap in place,
without allocating a replacement queue or discarding unrelated timers.

These guarantees apply to registered operations on a live scheduler owner, not
standalone cross-thread cancellation or forced worker/frame destruction. Setup
can fail before submission; unrelated allocation failures and throwing user
callbacks retain their existing contracts. Neither cancellation admission nor
a timeout rolls back I/O side effects or permits releasing borrowed resources
before operation cleanup completes.

I/O pinning protects backend ownership only. It does not serialize concurrent
operations on the same stream or fd. Follow the concrete stream contract and
externally serialize conflicting reads, writes, close, or destruction.

`get_last_result()` is the legacy result channel used by raw-handle awaitables.
It reports the latest completion published by either built-in backend on the
calling thread, including an epoll runtime fallback in a build that also
supports io_uring. Read it from the resumed completion path before another
context on the same thread can publish a newer result. Standard `op_state`-based
awaitables return their operation-owned `io_result` directly.

### Custom I/O Awaitables

`io_awaitable_base` is a protected integration surface for awaitables that use
Elio's owner-controlled `op_state`. In 0.6, derived awaitables must select and
validate an `io_context` while installing that state. The old
`bind_to_worker()` / `restore_affinity()` pair is removed; the operation guard
now releases the internal pin when backend ownership reaches a terminal state,
allowing the unchanged caller affinity to become effective again.

Use this submission pattern:

```cpp
template<typename Promise>
void await_suspend(std::coroutine_handle<Promise> awaiter) {
    auto& ctx = current_io_context();

    io_request req{};
    req.op = io_op::read;
    req.fd = fd_;
    req.buffer = buffer_;
    req.length = length_;
    req.awaiter = awaiter;
    req.state = setup_op_state(awaiter, ctx);

    if (!prepare_op_state(ctx, req)) {
        clear_op_state();
        // Surfaces the errno the backend published for the rejection
        // (e.g. -EPERM from epoll_ctl), falling back to -EAGAIN.
        result_ = prepare_failure_result();
        awaiter.resume();
        return;
    }
    ctx.submit();
}
```

If custom cancellation state stores `req.state`, use the rollback-callback
overload of `prepare_op_state()` to clear that pointer and unregister callbacks
before an exception escapes. A `false` prepare result means no backend
ownership was transferred and still requires `clear_op_state()`. Once prepare
returns `true`, leave the state attached to the awaitable; normal completion or
the orphan protocol releases the operation guard.

A custom cancellation dispatcher that can outlive its awaitable must not keep
using a raw `req.state` key after frame teardown can enter the orphan protocol.
It must atomically arbitrate its final key use against derived-awaitable
destruction before the `io_awaitable_base` destructor runs. Do not wait from
that destruction path: epoll cancellation may synchronously resume and destroy
the same awaitable inside `io_context::cancel()`.

### `io_result`

Result of an I/O operation.

```cpp
struct io_result {
    int result;  // Bytes transferred or negative errno
    int flags;   // Backend-specific flags
};
```

### Async I/O Awaits

```cpp
// Read from fd
auto result = co_await async_read(fd, buffer, length, offset);

// Write to fd
auto result = co_await async_write(fd, data, length, offset);

// Scatter-gather read
auto result = co_await async_readv(fd, iovecs, count);

// Scatter-gather write
auto result = co_await async_writev(fd, iovecs, count);

// Recv/Send (sockets)
auto result = co_await async_recv(fd, buffer, length, flags);
auto result = co_await async_send(fd, buffer, length, flags);
auto result = co_await async_sendmsg(fd, iovecs, count, flags);

// Accept. The accepted fd is returned in io_result::result; peer storage is
// populated through the addr/addrlen pointers when provided.
struct sockaddr_storage peer_addr{};
socklen_t peer_len = sizeof(peer_addr);
auto accept_result = co_await async_accept(
    listen_fd,
    reinterpret_cast<struct sockaddr*>(&peer_addr),
    &peer_len);
if (accept_result.result >= 0) {
    int client_fd = accept_result.result;
    // peer_addr contains the peer address.
}

// Connect
// Direct callers must keep fd non-blocking when the epoll backend may be used.
// A blocking socket is rejected with result.result == -EINVAL.
auto result = co_await async_connect(fd, addr, addrlen);

// Close
auto result = co_await async_close(fd);

// Poll
auto result = co_await async_poll_read(fd);
auto result = co_await async_poll_write(fd);
```

`async_send()` and `async_sendmsg()` are socket operations. `async_sendmsg()`
is a scatter-gather send over an `iovec` array, not a general `sendmsg(2)`
wrapper for destination addresses or ancillary/control data. On platforms with
per-call `SIGPIPE` suppression, they apply it so peer-close failures are
reported through `io_result` rather than process-level signal delivery.

### Batch I/O

Submit multiple file operations. Segments with non-negative offsets are
positioned operations that can be submitted together with io_uring. Segments
with negative offsets use the file descriptor's current position and are
executed in segment order to preserve file-position semantics.

```cpp
// Batch read: read multiple file regions at once
struct batch_read_segment {
    int64_t offset;   // File offset (negative for current position)
    void* buffer;     // Destination buffer
    size_t length;    // Bytes to read
};

std::vector<batch_read_segment> segments = { ... };
auto results = co_await batch_read(fd, segments);
// results[i] > 0: bytes read; results[i] < 0: -errno

// Batch write: write multiple file regions at once
struct batch_write_segment {
    int64_t offset;      // File offset (negative for current position)
    const void* buffer;  // Source data
    size_t length;       // Bytes to write
};

std::vector<batch_write_segment> segments = { ... };
auto results = co_await batch_write(fd, segments);
```

**How it works:**
1. Positioned segments are prepared in the io_uring submission queue
2. Single `io_uring_submit()` syscall dispatches positioned operations
3. Current-position segments fall back to ordered `read()` / `write()` calls
4. Each io_uring completion is tracked via tagged `user_data` encoding
5. Results are returned in a `std::vector<int>` matching segment order

**Fallback:** When io_uring is unavailable (epoll backend), positioned
segments fall back to sequential synchronous `pread`/`pwrite`.
Current-position segments use ordered `read()` / `write()` calls.

**Regular files under epoll:** `epoll_ctl` rejects regular files with
`EPERM` because they are always ready, so under the epoll backend the
single-shot operations `async_read`, `async_write`, `async_readv`, and
`async_writev` on a regular file never register with epoll. Instead they
execute `pread`/`pwrite`/`preadv`/`pwritev` (or the current-position
variants) inline at submission and complete immediately;
`async_poll_read`/`async_poll_write` on a regular file complete immediately
as ready. The file type is probed once per fd with `fstat` and cached; the
cache is invalidated whenever the fd's backend state becomes inert (last
operation completed, cancellation, or close), so a recycled fd number is
always re-probed. An `O_PATH` regular file passes the probe but cannot be
read or written; operations on it fail inline with `-EBADF` from the
syscall itself.
Because these operations complete without a real suspension, cancellation
tokens are no-ops for them under epoll, whereas the io_uring backend keeps
the equivalent submission truly cancellable until its completion arrives.
Once the inline syscall has executed, the completion is terminal: it wins
over a cancellation request that arrives before the result is collected,
mirroring io_uring's already-completed behavior where `ASYNC_CANCEL`
reports `-ENOENT` and the real result is delivered.
Timeout wrappers remain harmless because completion is immediate. The
inline syscall may briefly block the worker on disk I/O, matching the batch
I/O fallback above.

Inline execution is the deliberate default, not an oversight: a page-cache
hit completes in microseconds, while a thread-pool round trip costs an order
of magnitude more on every operation, and the genuinely asynchronous
alternative for buffered file I/O is io_uring itself (the primary backend).
The cases where an inline syscall can block for longer are specific: cold
page-in from slow media, network or FUSE filesystems, `O_DIRECT` files,
buffered writes under writeback throttling, and memory-reclaim stalls. The
`fstat` probe cannot distinguish these from local-disk files. Workloads that
expect them should move the affected file I/O into `elio::spawn_blocking`
(or an equivalent blocking-pool facility) at the application layer rather
than issuing it directly on a scheduler worker under the epoll backend.

### Positional File Transfers

Include `<elio/io/file_transfer.hpp>` or `<elio/elio.hpp>`. These additive helpers
borrow a regular-file descriptor and caller-owned byte spans; they do not open a
path, allocate a payload-sized buffer, or change the descriptor's current offset.

```cpp
enum class transfer_end { complete, eof, error, cancelled };
struct file_transfer_result {
    size_t transferred;
    transfer_end end;
    std::error_code error;
};

coro::task<file_transfer_result> pread_some(
    int fd, std::span<std::byte> out, uint64_t offset,
    coro::cancel_token token = {});
coro::task<file_transfer_result> pread_exactly(
    int fd, std::span<std::byte> out, uint64_t offset,
    coro::cancel_token token = {});
coro::task<file_transfer_result> pwrite_some(
    int fd, std::span<const std::byte> in, uint64_t offset,
    coro::cancel_token token = {});
coro::task<file_transfer_result> pwrite_exactly(
    int fd, std::span<const std::byte> in, uint64_t offset,
    coro::cancel_token token = {});
```

- Some helpers stop after the first positive completion, which may be short.
  Exact success means `transferred == span.size()`. Both retain progress when a
  later operation fails or cancellation stops the next iteration.
- Read EOF returns `eof` with no error, including zero bytes when already at EOF.
  A zero-progress nonempty write returns `error`/`EIO`. Errors use
  `std::generic_category()`; cancellation returns `cancelled`/`ECANCELED`.
- The whole requested `[offset, offset + size)` range must fit both `int64_t`
  and native `off_t`; otherwise `EOVERFLOW` is returned before any submission.
  At a valid offset, an empty span succeeds without I/O even with a cancelled
  token. Requests are split to fit the signed backend completion width.
- `EINTR` retries the uncompleted range. `EAGAIN` is terminal, not a readiness
  loop. These are regular-file APIs, not socket/pipe exact-transfer helpers.
- A supplied token is observed only before each raw operation. It does not
  cancel an admitted operation: final success or a kernel error remains visible
  if cancellation arrives during that operation. There is no deadline overload
  or prompt-cancellation guarantee, and enclosing-task cancellation is not
  implicitly inherited. Normal awaited return ends submitted buffer access;
  forced frame destruction or forced shutdown does not provide that guarantee.
- Keep the FD open/unrecycled, output storage alive, and input storage alive and
  unchanged until return. Writes require no `O_APPEND`; applications own buffer
  synchronization, alignment, concurrent truncation/resize exclusion, format
  validation, flush/durability policy, and crash consistency. No rollback,
  transaction atomicity, stable-file snapshot, or durability is promised.

These helpers use the existing active I/O context and standalone driving rules.
The io_uring and epoll policies above remain unchanged; exact bookkeeping does
not turn epoll's inline regular-file syscalls into native asynchronous I/O.
Whole-path `read_file()` and its partial-content behavior are unchanged.

See the runnable [positional transfer example](https://github.com/Coldwings/Elio/blob/main/examples/positional_file_io.cpp).

### File Synchronization, Allocation, and Truncation

Include `<elio/io/file_operations.hpp>` or the umbrella header. These FD-based
coroutines require a running scheduler worker; they never create standalone threads or
silently run the potentially slow syscall on a scheduler worker.

```cpp
enum class file_sync_mode { data_only, data_and_metadata };
enum class file_operation_end { complete, error, cancelled };
struct file_status {
    file_operation_end end;
    std::error_code error;
    explicit operator bool() const noexcept; // end == complete
    int error_value() const noexcept;
};
struct file_operation_options {
    size_t max_queued = 256; // Finite positive shared-pool admission limit
};

coro::task<file_status> sync_file(
    int fd, file_sync_mode mode = file_sync_mode::data_and_metadata,
    coro::cancel_token token = {}, file_operation_options options = {});
coro::task<file_status> allocate_file_range(
    int fd, int flags, uint64_t offset, uint64_t length,
    coro::cancel_token token = {}, file_operation_options options = {});
coro::task<file_status> truncate_file(
    int fd, uint64_t length, coro::cancel_token token = {},
    file_operation_options options = {});
```

`data_only` selects `fdatasync`; `data_and_metadata` selects `fsync`. Allocation
passes Linux `fallocate` flags through to the kernel, including hole punching
with `FALLOC_FL_PUNCH_HOLE | FALLOC_FL_KEEP_SIZE`. Truncation selects `ftruncate`.
Each call provides only that syscall's guarantee, not directory durability,
multi-file atomicity, resize serialization, or crash recovery.

The active io_uring ring is probed for supported opcodes. Truncation also needs
the helper in the consumer's liburing headers; older headers safely select the
blocking path without an exported producer-version assumption. Native SQEs
force asynchronous kernel execution. A missing/failed probe or unsupported
opcode selects the scheduler's fixed blocking pool. Once native I/O is admitted,
its terminal error (including `EINVAL` or filesystem unsupported flags) is
returned without replaying the operation through another mechanism.

Fallback admission bounds the existing shared pool queue to `max_queued` at the
point of submission; running work is bounded by the fixed pool threads. It is
not a separate queue, a global application memory limit, or a bound on native
I/O. Saturation or unavailable admission returns `error`/`EAGAIN`. A zero or
`SIZE_MAX` limit is invalid (`EINVAL`). After validation and the pre-cancellation
check, a call outside a running scheduler worker, including the external thread
that called `scheduler::start()`, returns `ENOTSUP` without selecting the
standalone I/O context. An otherwise valid, already-cancelled call instead returns
`cancelled`/`ECANCELED`, even without a scheduler. There is
no detached-thread fallback. Ordinary `spawn_blocking()` behavior is unchanged.
The underlying `blocking_pool::submit_bounded(work, limit)` rejects non-pooled
mode or unavailable/full queues, leaves rejected work untouched, and never
creates per-call threads; ordinary `submit()` keeps its existing behavior.
If pool teardown drains queued work on a scheduler worker, that file operation
returns `error`/`EAGAIN` without invoking the syscall. Generic pool shutdown
behavior is unchanged.

Offsets/range ends and truncation lengths must fit both `int64_t` and native
`off_t` (`EOVERFLOW` otherwise). Zero-length allocation and invalid sync modes
return `EINVAL`. Validation precedes cancellation and dispatch. Syscall errors
are captured on the execution thread and returned with `std::generic_category()`;
callers never need to read another thread's `errno`.

Cancellation is explicit, not implicitly inherited from the enclosing task. An
already-cancelled token, or a queued fallback cancelled before its dispatch
check, yields `cancelled`/`ECANCELED` without invoking that syscall. Queued
cancellation may wait until dequeue before returning. After native admission or
the fallback dispatch check, cancellation does not interrupt the operation or
rewrite success/kernel error. No deadline is provided. Running blocking calls
may delay normal return and graceful scheduler shutdown.

Keep the borrowed FD open and unrecycled until normal awaited return. Forced
frame destruction or forced shutdown is not a substitute for that barrier.
Cancellation is not rollback, and an error after dispatch does not prove that
no side effects occurred. Allocation/format policy, writable descriptors,
concurrent resize exclusion, and persistence ordering remain application work.
The deliberate epoll regular-file read/write inline policy is unchanged.

See the runnable [file persistence example](https://github.com/Coldwings/Elio/blob/main/examples/file_persistence.cpp).

### File Helpers

High-level coroutine functions for common file operations:

```cpp
// Read a file into a string. An engaged result holds the bytes actually
// read (not a completeness guarantee: a read failure after bytes were
// accumulated still returns partial content). nullopt only when open
// fails or the first read fails before any bytes are produced.
std::optional<std::string> content = co_await read_file("/path/to/file.txt");

// Write string to file (creates/truncates)
bool ok = co_await write_file("/path/to/file.txt", "Hello, World!");

// Append to file (creates if not exists)
bool ok = co_await append_file("/path/to/log.txt", "New entry\n");

// File metadata (synchronous, no coroutine needed)
bool exists = file_exists("/path/to/file.txt");
std::optional<int64_t> size = file_size("/path/to/file.txt");

// Read directory
std::optional<std::vector<dir_entry>> entries = read_dir("/path/to/dir");

struct dir_entry {
    std::string name;   // Filename
    bool is_dir;        // Is directory
    bool is_file;       // Is regular file
    bool is_symlink;    // Is symbolic link
};
```

**Chunking strategy:** Large files are read/written in 1MB chunks to avoid excessive single-request memory allocation.

---

## Signal Handling (`elio::signal`)

Coroutine-friendly signal handling using Linux signalfd.

### Process-wide `SIGPIPE` disposition

`elio::run()` and therefore `ELIO_ASYNC_MAIN` install `SIG_IGN` for `SIGPIPE`
on first use of the runtime entry path. `elio::serve()` and `elio::serve_all()`
perform an independent one-time installation so custom-scheduler server users
receive the same protection. This is a fallback for socket/TLS paths where
per-call suppression is unavailable: a peer close is reported as `EPIPE`
instead of terminating the process.

Both paths change the process-wide signal disposition with `sigaction`; neither
saves or restores the previous value. An embedding application that needs a
different disposition later must snapshot it before the first Elio
runtime/server entry and restore it only after all Elio runtime and server use
has ended. Each path has an independent `once_flag`: a path that has never
been used will still install `SIG_IGN` on first call regardless of any
disposition change made in between, so restoration is only safe after all
entry-point paths have been exhausted or will no longer be called.

This policy is separate from signal masking. `signal_set` and `signal_fd` use
per-thread masks (inherited by threads created later) to route shutdown signals
through `signalfd`; they do not save or restore the process-wide `SIGPIPE`
disposition.

### `signal_set`

Manages a set of signals.

```cpp
class signal_set {
public:
    signal_set();                                    // Empty set
    signal_set(std::initializer_list<int> signals); // From list
    
    signal_set& add(int signo);     // Add signal (chainable)
    signal_set& remove(int signo);  // Remove signal
    signal_set& clear();            // Clear all signals
    signal_set& fill();             // Add all signals
    
    bool contains(int signo) const; // Check membership
    
    const sigset_t& mask() const;   // Get underlying mask
    
    // Signal mask operations
    int block_error(sigset_t* old_mask = nullptr) const; // Direct pthread error
    bool block(sigset_t* old_mask = nullptr) const;      // Block for thread
    int unblock_error() const;                           // Direct pthread error
    bool unblock() const;                                // Unblock for thread
    int set_mask_error(sigset_t* old_mask = nullptr) const;
    bool set_mask(sigset_t* old_mask = nullptr) const;
    int block_all_threads_error() const;
    // Blocks the current thread. Call before creating workers so they inherit it.
    bool block_all_threads() const;
};
```

The `*_error()` variants return the direct `pthread_sigmask()` error number, or
`0` on success. The boolean wrappers preserve the source-compatible success/fail
API.

### `signal_fd`

Async-friendly signalfd wrapper.

`signal_fd` retains the `io_context` selected at construction, but `wait()`
resolves its submission context per call: on a scheduler worker the read is
submitted to the CURRENT worker's `io_context` (the awaiting coroutine's
worker), so a descriptor constructed on one worker may be awaited on another;
off-worker the construction-time context is used. A directly constructed
standalone context may be used only when the caller also serializes and polls
that context. At most one `wait()` may be pending on a `signal_fd` at a time
(single-waiter rule); concurrent waits from two workers are not supported and
can silently lose one of the waiters.

```cpp
class signal_fd {
public:
    // Create signalfd (auto_block=true blocks signals on the calling thread)
    explicit signal_fd(
        const signal_set& signals,
        io::io_context& ctx = io::current_io_context(),
        bool auto_block = true);
    
    signal_fd(signal_fd&& other) noexcept;
    signal_fd& operator=(signal_fd&& other) noexcept;
    
    int fd() const noexcept;             // Get file descriptor
    bool valid() const noexcept;         // Check if valid
    explicit operator bool() const;       // Bool conversion
    
    const signal_set& signals() const;   // Get signal set
    
    // Wait for signal (awaitable)
    /* awaitable */ wait();              // Returns std::optional<signal_info>
    
    // Non-blocking read
    std::optional<signal_info> try_read();
    
    // Update the signal set
    bool update(const signal_set& new_signals, bool block = true);
    
    // Deprecated no-op; returns false
    [[deprecated("use signal_set::unblock() explicitly")]]
    bool restore_mask() noexcept;
    
    void close();  // Close explicitly
};
```

Automatic blocking by `signal_fd` is acquire-only. `close()`, moves, and
destruction do not restore or unblock the calling thread's mask. Whole-mask
snapshots are not composable with overlapping descriptors or later caller mask
changes, so `restore_mask()` is deprecated, performs no operation, and returns
`false`. Once no descriptor or worker depends on a blocked signal, release it
explicitly with `signal_set::unblock()` on the thread that owns the mask.

### `signal_info`

Information about a received signal.

```cpp
struct signal_info {
    int signo;              // Signal number
    int32_t errno_value;    // Error number (if applicable)
    int32_t code;           // Signal code (SI_USER, SI_KERNEL, etc.)
    uint32_t pid;           // PID of sending process
    uint32_t uid;           // UID of sending process
    int32_t status;         // Exit status (for SIGCHLD)
    
    const char* name() const;      // "INT", "TERM", etc.
    std::string full_name() const; // "SIGINT", "SIGTERM", etc.
};
```

### `signal_block_guard`

RAII guard for temporary signal blocking.

```cpp
class signal_block_guard {
public:
    explicit signal_block_guard(const signal_set& signals);
    ~signal_block_guard();  // Restores original mask
};
```

### Utility Functions

```cpp
// Wait for signals (convenience, creates temporary signal_fd)
coro::task<signal_info> wait_signal(
    const signal_set& signals,
    io::io_context& ctx = io::current_io_context(),
    bool auto_block = true);

coro::task<signal_info> wait_signal(
    int signo,
    io::io_context& ctx = io::current_io_context());

// Signal name/number conversion
const char* signal_name(int signo);        // SIGINT -> "INT"
int signal_number(const char* name);       // "SIGINT" or "INT" -> 2
```

**Example:**
```cpp
#include <elio/elio.hpp>

using namespace elio::signal;

std::atomic<bool> g_running{true};

coro::task<void> signal_handler_task() {
    signal_set sigs{SIGINT, SIGTERM};
    signal_fd sigfd(sigs);
    
    auto info = co_await sigfd.wait();
    if (info) {
        ELIO_LOG_INFO("Received: {}", info->full_name());
    }
    g_running = false;
    co_return;
}

int main() {
    // Block signals BEFORE creating threads
    signal_set sigs{SIGINT, SIGTERM};
    sigs.block_all_threads();
    
    runtime::scheduler sched(4);
    sched.start();
    
    sched.go(signal_handler_task);
    
    // ... spawn other tasks ...
    
    while (g_running) {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }
    
    sched.shutdown();
}
```

---

## Networking (`elio::net`)

### Bounded Resolver Waiting

Include `<elio/net/resolve_wait.hpp>` or `<elio/elio.hpp>`:

```cpp
enum class resolve_status { resolved, failed, cancelled, timed_out };
struct resolve_result {
    std::vector<socket_address> addresses;
    resolve_status status = resolve_status::failed;
    int error = EHOSTUNREACH;  // positive errno, zero on success
    explicit operator bool() const noexcept;
};
class resolve_domain {
public:
    explicit resolve_domain(size_t capacity = 64);
    size_t capacity() const noexcept;
    size_t outstanding() const noexcept;
};
std::shared_ptr<resolve_domain> default_resolve_domain();
struct resolve_wait_options {
    resolve_options lookup;
    std::optional<std::chrono::steady_clock::time_point> deadline;
    std::shared_ptr<resolve_domain> domain; // null selects shared default
};
coro::task<resolve_result> resolve_all(std::string_view host, uint16_t port,
    resolve_wait_options options, coro::cancel_token token);
```

The explicit fourth token preserves legacy three-argument resolver calls.
Input is copied at factory invocation. Entry cancellation/expiry precedes fast
paths; misses need a running scheduler worker. Cancellation/deadline leaves
observation, not running libc: its owned late work remains admitted until
reclamation, and normal shutdown still drains it. Capacity/pool rejection is
`EAGAIN`; literal/cache fast paths consume no permit. Only live completion
accesses/publishes a borrowed cache, retained through normal awaited return.
No late cache publication, coalescing, detached threads, forced interruption,
or exact wall-clock bound is promised. Exceptions may propagate. See
[Networking](Networking.md#bounded-cancellable-dns-waiting) for arbitration,
cache, admission, and client-budget details.

### `ipv4_address`

IPv4 address with port.

```cpp
struct ipv4_address {
    uint32_t addr = INADDR_ANY;
    uint16_t port = 0;
    
    ipv4_address() = default;
    explicit ipv4_address(uint16_t p);
    ipv4_address(std::string_view ip, uint16_t p);
    
    // String representation
    std::string to_string() const;
};
```

`ipv4_address(std::string_view, uint16_t)` accepts numeric IPv4 literals.
Invalid text logs an error and falls back to `INADDR_ANY`; callers that need
strict address validation should resolve or validate host strings before
construction.

### `ipv6_address`

IPv6 address with port and optional scope ID.

```cpp
struct ipv6_address {
    struct in6_addr addr = IN6ADDR_ANY_INIT;
    uint16_t port = 0;
    uint32_t scope_id = 0;

    ipv6_address() = default;
    explicit ipv6_address(uint16_t p);
    ipv6_address(std::string_view ip, uint16_t p);

    int family() const noexcept;
    std::string to_string() const;
    bool is_v4_mapped() const;
};
```

`ipv6_address(std::string_view, uint16_t)` accepts numeric IPv6 literals. A
link-local scope suffix such as `%eth0` is converted with `if_nametoindex()`.
Invalid text logs an error and falls back to the IPv6 any address.

### `socket_address`

Generic TCP socket address wrapper for IPv4 or IPv6 endpoints.

```cpp
class socket_address {
public:
    socket_address();
    socket_address(const ipv4_address& addr);
    socket_address(const ipv6_address& addr);
    explicit socket_address(uint16_t port);
    socket_address(std::string_view host, uint16_t port);

    int family() const;
    uint16_t port() const;
    bool is_v4() const;
    bool is_v6() const;
    const ipv4_address& as_v4() const;
    const ipv6_address& as_v6() const;
    std::string to_string() const;
};
```

`socket_address(std::string_view, uint16_t)` auto-selects IPv6 when the host
contains `:` and IPv4 otherwise. Empty, `"::"`, and `"0.0.0.0"` select the
IPv6-any dual-stack address, which listeners use for all-interface binds.

### `tcp_listener`

TCP server socket.

```cpp
class tcp_listener {
public:
    // Bind to address (returns std::nullopt on error, check errno)
    static std::optional<tcp_listener> bind(
        const ipv4_address& addr,
        const tcp_options& opts = {}
    );
    static std::optional<tcp_listener> bind(
        const ipv6_address& addr,
        const tcp_options& opts = {}
    );
    static std::optional<tcp_listener> bind(
        const socket_address& addr,
        const tcp_options& opts = {}
    );
    
    // Accept a connection (awaitable, returns std::optional<tcp_stream>)
    /* awaitable */ accept();
    /* awaitable */ accept(coro::cancel_token token);
    
    // Get file descriptor
    int fd() const noexcept;
    
    // Get local address
    const socket_address& local_address() const noexcept;

    // Close after all pending accepts have completed or been cancelled.
    void close();
};
```

`close()` invalidates the listener and prevents later accepts from succeeding.
It does not cancel an `accept()` that has already been submitted to the active
I/O backend. A stoppable service loop should use the cancellable overload,
request cancellation, await the loop task, and only then close or destroy the
listener. The listener must remain alive until the pending accept resumes.

### `tcp_stream`

Output completion is shared with `tls_stream` and `net::stream`:

```cpp
namespace elio::net {
enum class close_scope { write_direction, whole_session };
struct write_finish_result {
    close_scope scope = close_scope::write_direction;
    int error = 0;
    bool local_end_flushed = false;
    bool peer_end_observed = false;
};
}
// Member on tcp_stream, tls_stream and net::stream:
coro::task<net::write_finish_result> finish_write(
    coro::cancel_token token = {},
    std::chrono::milliseconds timeout = std::chrono::milliseconds(5000));
// Interpret a nonempty read operation that returned zero (not a failed read):
net::close_scope read_end_scope() const;
```

One reader may overlap; serialize other writers and lifetime changes. TCP
performs `SHUT_WR`, internally retries EINTR, and ignores the timeout. TLS 1.3
preserves reading; TLS 1.2 automatically closes the session under the timeout.
The result reports closure scope and observations, not proof of peer delivery.
`read_end_scope()` reports directional EOF for TCP/TLS 1.3, or the selected
whole-session closure for TLS 1.2. It does not itself close output, probe
transport capabilities, or turn an error/zero-length read into authenticated EOF.
See [Finishing Stream Output](API-Contracts.md#finishing-stream-output) for
automatic TLS 1.2 closure, ordered ciphertext draining and failure semantics.

TCP connection.

```cpp
class tcp_stream {
public:
    // Compatibility constructor; does not report O_NONBLOCK setup failure.
    explicit tcp_stream(int fd);
    static std::optional<tcp_stream> adopt(int fd) noexcept;
    tcp_stream(tcp_stream&& other) noexcept;
    bool is_valid() const noexcept;
    
    // Read data (awaitable)
    /* awaitable */ read(void* buffer, size_t size);
    /* awaitable */ read(void* buffer, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ read(std::span<T> buffer);
    template<typename T>
    /* awaitable */ read(std::span<T> buffer, coro::cancel_token token);
    
    // Write data (awaitable)
    /* awaitable */ write(const void* data, size_t size);
    /* awaitable */ write(const void* data, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ write(std::span<const T> buffer);
    template<typename T>
    /* awaitable */ write(std::span<const T> buffer, coro::cancel_token token);
    /* awaitable */ write(std::string_view data);
    /* awaitable */ write(std::string_view data, coro::cancel_token token);

    // Exact-length helpers (awaitable)
    /* awaitable */ read_exactly(void* buffer, size_t size);
    /* awaitable */ read_exactly(void* buffer, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ read_exactly(std::span<T> buffer);
    template<typename T>
    /* awaitable */ read_exactly(std::span<T> buffer, coro::cancel_token token);
    /* awaitable */ write_exactly(const void* data, size_t size);
    /* awaitable */ write_exactly(const void* data, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ write_exactly(std::span<const T> buffer);
    template<typename T>
    /* awaitable */ write_exactly(std::span<const T> buffer, coro::cancel_token token);
    /* awaitable */ write_exactly(std::string_view data);
    /* awaitable */ write_exactly(std::string_view data, coro::cancel_token token);
    
    // Readiness-aware borrowed scatter/gather - may return a short write
    coro::task<io::io_result> writev(struct iovec* iovecs, size_t count);
    coro::task<io::io_result> writev(struct iovec* iovecs, size_t count,
                                   coro::cancel_token token);
    
    // Poll for readability (awaitable)
    /* awaitable */ poll_read();
    /* awaitable */ poll_read(coro::cancel_token token);
    
    // Poll for writability (awaitable)
    /* awaitable */ poll_write();
    /* awaitable */ poll_write(coro::cancel_token token);
    
    // Get file descriptor
    int fd() const noexcept;
    
    // Get peer address
    std::optional<socket_address> peer_address() const;

    // Lifecycle and socket options
    /* awaitable */ close();
    void shutdown_socket() noexcept;
    bool shutdown(int how) noexcept;
    bool set_no_delay(bool enable);
    bool set_keep_alive(bool enable);
};

// peer_address() returns the generic socket_address wrapper so callers can
// inspect IPv4 or IPv6 peers.
// adopt() sets O_NONBLOCK before ownership transfer. On failure it returns
// std::nullopt, leaves fd open and caller-owned, and preserves fcntl() errno.
// From call entry until return, the caller must exclusively control fd and its
// duplicate aliases. After success, O_NONBLOCK must remain set on their shared
// open-file description for as long as the adopted stream owns the descriptor.
// Retained aliases must not clear it or otherwise defeat non-blocking I/O
// through status-flag changes.
// close() transfers the descriptor to the async close operation and invalidates
// the stream object. Under the epoll backend, close() and destruction on the
// stream's owning worker fail any I/O still parked on the stream's fd with
// -ECANCELED, resuming each parked awaiter exactly once; destruction off the
// owning worker raw-closes the fd and leaves a parked op suspended until the
// recycled fd number is next prepared or the backend is destroyed. Under
// io_uring, in-flight operations hold a kernel file reference and complete
// normally later against the old file description. A stoppable reader/writer
// should still prefer the cancellable
// overload plus token cancellation and await the operation before closing,
// and the stream must remain alive until parked operations have resumed.
// shutdown_socket() interrupts both socket directions without
// releasing the descriptor; shutdown(int) is the direct half-close wrapper.
// Multiple reads, multiple writes, and close/shutdown racing with I/O require
// external serialization.

// Connect to address (awaitable, returns std::optional<tcp_stream>)
/* awaitable */ tcp_connect(const ipv4_address& addr, const tcp_options& opts = {});
/* awaitable */ tcp_connect(const ipv4_address& addr,
                            coro::cancel_token token,
                            const tcp_options& opts = {});
/* awaitable */ tcp_connect(const ipv6_address& addr, const tcp_options& opts = {});
/* awaitable */ tcp_connect(const ipv6_address& addr,
                            coro::cancel_token token,
                            const tcp_options& opts = {});
/* awaitable */ tcp_connect(const socket_address& addr, const tcp_options& opts = {});
/* awaitable */ tcp_connect(const socket_address& addr,
                            coro::cancel_token token,
                            const tcp_options& opts = {});
```

`read_exactly()` reports success only after storing the full requested byte
count. If the peer closes first, it returns `io_result::result == -ENODATA`;
the destination then contains an incomplete message and should not be treated
as a successful exact-length read.

### Unix Domain Sockets

Local Unix Domain Socket networking.

```cpp
struct uds_options {
    bool reuse_addr = false;
    int recv_buffer = 0;
    int send_buffer = 0;
    int backlog = 128;
    bool unlink_on_bind = true;
};

struct unix_address {
    explicit unix_address(std::string_view path);

    // Linux abstract socket address (does not create a filesystem entry)
    static unix_address abstract(std::string_view name);

    // Convert to sockaddr_un for bind/connect.
    // Throws std::invalid_argument if path is too long for sun_path.
    struct sockaddr_un to_sockaddr() const;
    socklen_t sockaddr_len() const;

    bool is_abstract() const;
    std::string to_string() const;
};

class uds_listener {
public:
    // Bind to filesystem or abstract UDS address
    static std::optional<uds_listener> bind(
        const unix_address& addr,
        const uds_options& opts = {}
    );

    // Accept a connection (awaitable, returns std::optional<uds_stream>)
    /* awaitable */ accept();
    /* awaitable */ accept(coro::cancel_token token);

    int fd() const noexcept;
    const unix_address& local_address() const noexcept;

    // Close after all pending accepts have completed or been cancelled.
    void close();
};
```

`close()` invalidates the listener and prevents later accepts from succeeding.
It does not cancel an `accept()` that has already been submitted to the active
I/O backend: a parked plain `accept()` never wakes on `close()` under either
the io_uring or the epoll backend. A stoppable service loop should use the
cancellable overload, request cancellation, await the loop task, and only then
close or destroy the listener. The listener must remain alive until the
pending accept resumes.

```cpp
class uds_stream {
public:
    // Compatibility constructor; does not report O_NONBLOCK setup failure.
    explicit uds_stream(int fd);
    static std::optional<uds_stream> adopt(int fd) noexcept;
    uds_stream(uds_stream&& other) noexcept;
    bool is_valid() const noexcept;

    // Read data (awaitable)
    /* awaitable */ read(void* buffer, size_t size);
    /* awaitable */ read(void* buffer, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ read(std::span<T> buffer);
    template<typename T>
    /* awaitable */ read(std::span<T> buffer, coro::cancel_token token);

    // Write data (awaitable)
    /* awaitable */ write(const void* data, size_t size);
    /* awaitable */ write(const void* data, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ write(std::span<const T> buffer);
    template<typename T>
    /* awaitable */ write(std::span<const T> buffer, coro::cancel_token token);
    /* awaitable */ write(std::string_view data);
    /* awaitable */ write(std::string_view data, coro::cancel_token token);

    // Exact-length helpers (awaitable)
    /* awaitable */ read_exactly(void* buffer, size_t size);
    /* awaitable */ read_exactly(void* buffer, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ read_exactly(std::span<T> buffer);
    template<typename T>
    /* awaitable */ read_exactly(std::span<T> buffer, coro::cancel_token token);
    /* awaitable */ write_exactly(const void* data, size_t size);
    /* awaitable */ write_exactly(const void* data, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ write_exactly(std::span<const T> buffer);
    template<typename T>
    /* awaitable */ write_exactly(std::span<const T> buffer, coro::cancel_token token);
    /* awaitable */ write_exactly(std::string_view data);
    /* awaitable */ write_exactly(std::string_view data, coro::cancel_token token);

    // Scatter-gather socket write attempt and readiness polling
    /* awaitable */ writev(struct iovec* iovecs, size_t count);
    /* awaitable */ poll_read();
    /* awaitable */ poll_read(coro::cancel_token token);
    /* awaitable */ poll_write();
    /* awaitable */ poll_write(coro::cancel_token token);

    // Socket metadata and Linux credential passing
    int fd() const noexcept;
    std::optional<unix_address> peer_address() const;
    /* awaitable */ close();
    void shutdown_socket() noexcept;
    bool shutdown(int how) noexcept;
    bool set_recv_buffer(int size);
    bool set_send_buffer(int size);
    bool set_pass_credentials(bool enable);
};

// Connect to UDS address/path (awaitable, returns std::optional<uds_stream>)
/* awaitable */ uds_connect(const unix_address& addr,
                            const uds_options& opts = {});
/* awaitable */ uds_connect(const unix_address& addr,
                            coro::cancel_token token,
                            const uds_options& opts = {});
/* awaitable */ uds_connect(std::string_view path,
                            const uds_options& opts = {});
/* awaitable */ uds_connect(std::string_view path,
                            coro::cancel_token token,
                            const uds_options& opts = {});
```

`unix_address` stores the supplied path or Linux abstract name without doing a
syscall. Conversion for `bind()` or `uds_connect()` requires the address to fit
in `sockaddr_un::sun_path`: filesystem paths need room for a trailing NUL, while
abstract addresses include the leading NUL byte in their stored length. If the
address is too long, `unix_address::to_sockaddr()` throws
`std::invalid_argument` before the bind or connect syscall is attempted.
`uds_listener::bind()` reports socket creation failures, and bind/listen
failures after address conversion succeeds, as `std::nullopt` with `errno` set;
`uds_connect()` reports socket creation/connect failures as `std::nullopt` with
`errno` set from the awaited operation. Cancellable overloads return
`std::nullopt` with `errno == ECANCELED` when the token wins the connect wait.

`uds_stream::adopt()` has the same checked descriptor contract as
`tcp_stream::adopt()`: success sets `O_NONBLOCK` and transfers ownership;
failure leaves the descriptor open and caller-owned with the `fcntl()` error in
`errno`. Both factories require the caller to supply a valid connected stream
socket for the matching class; they do not validate socket type, address
family, or connected state. The raw-fd constructors remain unchecked for
compatibility. From call entry until return, the caller must exclusively control
the fd and every duplicate alias, with no concurrent close, use, or status-flag
mutation. After success, `O_NONBLOCK` must remain set on the shared open-file
description for as long as the adopted stream owns the descriptor; retained
aliases must not clear it or otherwise defeat non-blocking I/O through
status-flag changes.

Like the TCP helper, `uds_stream::read_exactly()` returns
`io_result::result == -ENODATA` when EOF arrives before the requested byte
count. Only a result equal to the requested count is a successful exact-length
read.

UDS streams share the same concurrency contract as TCP streams: one reader and
one writer may operate concurrently, but multiple concurrent reads, multiple
concurrent writes, or a read racing with `close()` require external
serialization. Under the epoll backend, `close()` and destruction on the
stream's owning worker fail any I/O still parked on the stream's fd with
`-ECANCELED`, resuming each parked awaiter exactly once; destruction off the
owning worker raw-closes the fd and leaves a parked op suspended until the
recycled fd number is next prepared or the backend is destroyed. Under
io_uring, in-flight operations hold a kernel file
reference and complete normally later against the old file description. A
stoppable reader/writer should still prefer the cancellable overload plus
token cancellation and await the operation before closing, and the stream
must remain alive until parked operations have resumed.
`shutdown_socket()` interrupts both directions without releasing
the descriptor; `shutdown(int)` is the direct half-close wrapper. Buffer setters
wrap `SO_RCVBUF` and `SO_SNDBUF`, while `set_pass_credentials()` wraps
`SO_PASSCRED`.

### `net::publishing_byte_stream`

Include `<elio/net/byte_stream.hpp>` (also available through `<elio/elio.hpp>`).
The C++20 concept checks an unqualified object type, move construction,
absence of copying, the exact
`publishing_byte_stream_contract` opt-in, and these operations:

```cpp
// Representative compatible members, not declarations on net::stream.
// The concept checks call expressions/results, not exact parameter signatures.
using byte_stream_contract = net::publishing_byte_stream_contract;
coro::task<io::io_result> read(void*, size_t, coro::cancel_token);
coro::task<io::io_result> write(const void*, size_t, coro::cancel_token);
coro::task<net::write_finish_result> finish_write(
    coro::cancel_token, std::chrono::milliseconds);
net::close_scope read_end_scope() const noexcept;
coro::task<void> abort_and_settle();
```

No descriptor, readiness probe, or TLS header is required. The opt-in promises
recursive positive-write publication and the full ownership/EOF/finish/abort
contract in [[Byte Streams]]; syntax cannot verify those runtime semantics.
One abort may overlap one reader and one writer, but internal settlement is not
public-frame destruction. Existing TCP/TLS/common-stream types are not marked
as conforming by this foundation; adapters are separate implementations.

### `net::stream`

Type-erased wrapper over `tcp_stream` and, when TLS support is enabled,
`tls_stream`. It delegates I/O to the active underlying stream.

`net::stream` follows the concurrency contract of its active transport.
TCP-backed streams allow one reader and one writer concurrently, matching
`tcp_stream`. After the handshake completes, TLS-backed streams also allow one
read-side operation and one write-side operation to overlap while waiting for
socket readiness; `tls_stream` serializes OpenSSL dispatch and retry ownership
internally. TLS-backed writes inherit the 16 KiB short-progress ceiling and
bounded ciphertext storage described below; use `write_exactly()` for a complete
logical write. Multiple concurrent reads, multiple concurrent writes,
handshake-starting operations, or `close()` racing with any read/write operation
require external serialization for all variants.

```cpp
class stream {
public:
    stream();
    explicit stream(tcp_stream tcp);
    explicit stream(tls::tls_stream tls);  // When ELIO_HAS_TLS is enabled

    bool is_connected() const noexcept;
    bool is_secure() const noexcept;

    // Read/write data (awaitable)
    /* awaitable */ read(void* buffer, size_t size);
    /* awaitable */ read(void* buffer, size_t size, coro::cancel_token token);
    /* awaitable */ write(const void* data, size_t size);
    /* awaitable */ write(const void* data, size_t size, coro::cancel_token token);
    /* awaitable */ write(std::string_view data);
    /* awaitable */ write(std::string_view data, coro::cancel_token token);

    // Exact-length helpers (awaitable)
    /* awaitable */ read_exactly(void* buffer, size_t size);
    /* awaitable */ read_exactly(void* buffer, size_t size, coro::cancel_token token);
    /* awaitable */ write_exactly(const void* data, size_t size);
    /* awaitable */ write_exactly(const void* data, size_t size, coro::cancel_token token);
    /* awaitable */ write_exactly(std::string_view data);
    /* awaitable */ write_exactly(std::string_view data, coro::cancel_token token);

    // Compatibility aliases for write_exactly(); prefer write_exactly() in new code
    /* awaitable */ write_all(const void* data, size_t size);
    /* awaitable */ write_all(const void* data, size_t size, coro::cancel_token token);
    /* awaitable */ write_all(std::string_view data);
    /* awaitable */ write_all(std::string_view data, coro::cancel_token token);

    // Close/shutdown the active stream (awaitable)
    /* awaitable */ close();
};
```

`net::stream::read_exactly()` preserves the active TCP or TLS transport's
exact-length result: EOF before the requested byte count is reported as
`io_result::result == -ENODATA`.

TCP, TLS and `net::stream` also expose:

```cpp
coro::task<io::io_result> writev(struct iovec* parts, size_t count);
coro::task<io::io_result> writev(struct iovec* parts, size_t count,
                               coro::cancel_token token);
```

These borrow descriptors and payload until completion and may return positive
short progress. TCP waits for readiness and retries EINTR internally. TLS
submits the first nonempty borrowed slice, without joining payload into an
intermediate buffer. No single syscall or TLS record is promised. Each call
accepts at most 1024 vectors and INT32_MAX aggregate bytes; invalid count,
nonempty null array/segment, and overflow fail before submission with EINVAL,
EFAULT, and EOVERFLOW respectively (negative in `io_result::result`). Empty
input succeeds with zero on a connected stream. With a transport present, an
already-cancelled token takes precedence over input validation. An empty
`net::stream` with no transport variant returns ENOTCONN even if the token is
cancelled, matching scalar read/write dispatch. Caller code
owns vector advancement and keeps the stream alive through completion.

---

## HTTP (`elio::http`)

### `url`

Parsed HTTP URL components used by HTTP, WebSocket, SSE, and HTTP/2 clients.

```cpp
struct url {
    std::string scheme;
    std::string host;
    uint16_t port = 0;
    std::string path;
    std::string query;
    std::string fragment;
    std::string userinfo;

    std::string path_with_query() const;
    std::string host_authority() const;
    std::string authority() const;
    std::string to_string() const;
    uint16_t effective_port() const;
    uint16_t default_port() const;
    bool is_secure() const;

    static std::optional<url> parse(std::string_view str);
    static std::optional<url> resolve_reference(
        const url& base,
        std::string_view reference);
};
```

`path_with_query()` intentionally excludes `fragment`, because fragments are
client-side URL components and are not sent in HTTP request targets.
`resolve_reference()` resolves redirect-style `Location` references against a
base URL, including relative paths, query-only references, fragment-only
references, scheme-relative references, and dot-segment removal.

### `client`

HTTP client with private or explicitly shared connection transport ownership.

```cpp
class client {
public:
    client();
    explicit client(client_config config);
    explicit client(std::shared_ptr<transport> shared_transport,
                    client_config config = {});

    // GET request (awaitable)
    /* awaitable */ get(std::string_view url);
    /* awaitable */ get(std::string_view url, coro::cancel_token token);

    // POST request (awaitable)
    /* awaitable */ post(std::string_view url,
                         std::string_view body,
                         std::string_view content_type = mime::application_form_urlencoded);
    /* awaitable */ post(std::string_view url,
                         std::string_view body,
                         coro::cancel_token token,
                         std::string_view content_type = mime::application_form_urlencoded);

    // PUT request (awaitable)
    /* awaitable */ put(std::string_view url,
                        std::string_view body,
                        std::string_view content_type = mime::application_json);
    /* awaitable */ put(std::string_view url,
                        std::string_view body,
                        coro::cancel_token token,
                        std::string_view content_type = mime::application_json);

    // DELETE request (awaitable)
    /* awaitable */ del(std::string_view url);
    /* awaitable */ del(std::string_view url, coro::cancel_token token);

    // PATCH request (awaitable)
    /* awaitable */ patch(std::string_view url,
                          std::string_view body,
                          std::string_view content_type = mime::application_json);
    /* awaitable */ patch(std::string_view url,
                          std::string_view body,
                          coro::cancel_token token,
                          std::string_view content_type = mime::application_json);

    // HEAD request (awaitable)
    /* awaitable */ head(std::string_view url);
    /* awaitable */ head(std::string_view url, coro::cancel_token token);

    // Send custom request (awaitable)
    /* awaitable */ send(request& req, const url& target);
    /* awaitable */ send(request& req, const url& target, coro::cancel_token token);

    coro::task<client_result<response>> get_result(
        std::string_view url, coro::cancel_token token = {});
    coro::task<client_result<response>> request_result(
        method m, std::string_view url, std::string_view body = {},
        std::string_view content_type = {}, coro::cancel_token token = {});
    coro::task<client_result<response>> send_result(
        request& req, const url& target, coro::cancel_token token = {});

    // Handler: task<void>(const response&, response_body_reader&, cancel_token).
    template<typename Handler>
    coro::task<client_result<std::monostate>> with_response(
        request req, url target, coro::cancel_token token, Handler handler,
        streaming_response_options options = {});

    // Inspect sealed transport TLS diagnostics and mutate request policy.
    transport_tls_diagnostics tls_diagnostics() const noexcept;
    client_config& config() noexcept;
    const client_config& config() const noexcept;
};

// Convenience functions for one-off requests
/* awaitable */ get(std::string_view url);
/* awaitable */ get(std::string_view url, coro::cancel_token token);
/* awaitable */ post(std::string_view url,
                     std::string_view body,
                     std::string_view content_type = mime::application_form_urlencoded);
/* awaitable */ post(std::string_view url,
                     std::string_view body,
                     coro::cancel_token token,
                     std::string_view content_type = mime::application_form_urlencoded);
```

`client()` and `client(client_config)` create a private `http::transport`.
`client(shared_ptr<transport>, client_config)` shares that transport's resolver,
DNS admission, sealed TLS security context, and idle connection pool while retaining an
independent request policy on each client. Request policy includes redirects,
User-Agent, read/Expect timeouts, response limits, and the TCP/TLS
`connect_timeout` budget passed to each acquisition. `client` is move-only; copy
construction/assignment is deleted so sharing remains explicit through
`shared_ptr<transport>`.

### `transport_config` and `transport`

```cpp
class transport_tls_config {
public:
    bool load_certificate(std::string_view cert_file);
    bool load_private_key(std::string_view key_file, std::string_view password = {});
    bool load_verify_locations(std::string_view ca_file = {},
                               std::string_view ca_path = {});
    bool use_default_verify_paths();
    void set_verify_mode(tls::verify_mode mode);
    bool set_alpn_protocols(std::string_view protocols);
    bool set_ciphers(std::string_view ciphers);
    bool set_ciphersuites(std::string_view ciphersuites);
    tls::tls_mode mode() const noexcept;
    long verify_mode() const noexcept;
};

struct transport_tls_diagnostics {
    tls::tls_mode mode;
    long verify_mode;
};

struct pool_limits {
    size_t max_idle_per_route = 6;
    size_t max_idle_total = 64;
    size_t max_live_per_route = 12;
    size_t max_live_total = 128;
    size_t max_dials_total = 16;
    size_t max_waiters_total = 256;
    size_t max_route_buckets = 128;
};

struct transport_config {
    bool verify_certificate = true;
    net::resolve_options resolve_options = net::default_cached_resolve_options();
    bool rotate_resolved_addresses = true;
    std::chrono::nanoseconds dns_timeout{0};
    std::shared_ptr<net::resolve_domain> dns_domain;
    size_t max_connections_per_host = 6;
    std::chrono::seconds pool_idle_timeout{60};
    std::optional<pool_limits> limits;
    std::chrono::nanoseconds acquisition_timeout{0};
    std::optional<http_proxy_config> proxy;
    std::function<void(transport_tls_config&)> configure_tls;

    transport_config();
    explicit transport_config(const client_config& config);
};

class transport {
public:
    explicit transport(transport_config config = {});
    explicit transport(const client_config& config);

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

    void clear();
    coro::task<coro::cancel_result> shutdown(coro::cancel_token token = {});

    transport_tls_diagnostics tls_diagnostics() const noexcept;
    const transport_config& config() const noexcept;
    bool is_shutdown() const noexcept;
};
```

`transport_config(client_config)` copies only connection-affecting fields:
certificate verification, resolver/cache/address-rotation policy, DNS
observation/admission, the explicit proxy profile, idle-pool limits, opt-in finite pool admission, and the
absolute acquisition budget. It intentionally does not copy
request/response policy such as redirect limits, User-Agent, body limits,
header limits, read timeout, or Expect fallback timeout.

For HTTP clients, connection-affecting fields are frozen when the private or
shared transport is constructed. Mutating `client.config()` later changes only
the client request policy plus the per-acquisition `connect_timeout`; it does
not mutate resolver, DNS, TLS verification, proxy configuration, or pool identity. Publish a new
transport to change those connection-policy domains.
`transport_config::configure_tls` runs once during transport construction after
default client TLS initialization; use the supplied `transport_tls_config`
builder for custom trust roots or ciphers before the transport is published.
The builder forwards common TLS policy mutators but exposes only copied
diagnostic values such as mode and OpenSSL verification flags. It does not
expose an `SSL_CTX*`, `X509_STORE*`, or the published `tls_context`, so callbacks
cannot retain mutable access to the active security identity.
`client::tls_diagnostics()` and `transport::tls_diagnostics()` return the same
kind of copied value snapshot after publication. This is a breaking HTTP/1
client migration from the previous mutable accessor; WebSocket, SSE, and HTTP/2
keep their mutable per-client TLS context APIs.

`transport::clear()` drops idle pooled connections and invalidates returns from
pre-clear leases. Active or dialing operations continue normally, then retire
instead of returning to that pool generation. New acquisitions remain allowed.
`transport::shutdown()` marks the transport closed, drops idle
connections, rejects new acquisitions with `ESHUTDOWN`, and asynchronously waits
for client-managed dialing/acquired exchanges to settle. It does not destroy
caller coroutine frames or abort already active exchanges; callers still keep
the client, transport, request/URL objects, caches, and borrowed strings alive
until awaited return.
Transport acquisition/release is intentionally client-managed in this release;
raw external leases and cross-transport connection injection are not public API.
Internally a move-only lease retains the original route and strong state owner,
returns at most once only after the exchange proves safe completion, and otherwise
aborts/disconnects. Destruction does not asynchronously drain or mark a partial
response reusable. Both buffered and scoped streaming exchanges use this owner.

HTTP/1 connection establishment and idle pooling now consume one internal
immutable route plan per exchange. Its structured key compares normalized
origin authority, route mode, ordered proxy-hop identities, security/authentication
domains, protocol requirements, and connector/resolution domains by full value
equality. Direct routes and one explicit HTTP/HTTPS proxy are implemented.
Proxy and origin TLS security domains remain independent. Redirects create fresh plans, and returns retain the
acquisition plan. See [[HTTP Routing]] (`HTTP-Routing.md`) for the compatibility
matrix, normalization, and standalone-pool responsibility boundary.

#### Explicit HTTP Proxy Configuration

```cpp
struct proxy_basic_credentials {
    std::string username;
    std::string password;
};
struct proxy_connect_limits {
    size_t max_headers = 100;
    size_t max_header_size = 8192;
    size_t max_response_bytes = 65536;
    size_t max_informational_responses = 8;
    size_t max_read_ahead = 8192;
};
struct http_proxy_config {
    std::string endpoint; // explicit http[s]://host[:port] authority
    std::optional<proxy_basic_credentials> basic_auth;
    proxy_connect_limits connect_limits;
    bool verify_certificate = true; // proxy TLS only
    std::function<void(transport_tls_config&)> configure_tls; // proxy TLS only
};
```

Set `transport_config::proxy` (or `client_config::proxy` before constructing a
private Transport). The Transport freezes endpoint, authentication domain and
CONNECT limits. HTTP origins use absolute-form forwarding, HTTPS origins use
target-bound CONNECT then independently verified origin TLS. Only the proxy
endpoint is resolved locally. Credentials are explicitly selected preemptive
Basic octets; there is no automatic 407 challenge replay or environment discovery.
Plain HTTP does not encrypt proxy credentials. Generic `Proxy-Authorization`
request headers are stripped from direct/tunneled requests, and only the frozen
profile supplies forwarding/CONNECT hop credentials. Caller-supplied CONNECT
requests are unsupported through an explicitly proxied high-level client:
value APIs return `ENOTSUP` at `client_stage::request` before acquisition;
optional adapters return empty. Only the route connector owns CONNECT and its
handoff into origin TLS; there is no caller-facing raw tunnel API here.
Direct-route caller CONNECT handling and public request serialization are unchanged;
the credential-header migration below still applies to direct requests.
To migrate custom proxy
headers, configure `proxy.basic_auth`; public request serialization remains
unchanged. HTTPS proxy uses a separate construction-only TLS policy; existing
Transport TLS options remain origin-only. The proxy builder accepts `http/1.1`
or no ALPN, and rejects other lists unchanged. SOCKS, chained proxy and HTTP/2
routes are not supported.
Standalone `connection_pool` remains direct-only and rejects construction with
an explicit proxy option (`std::invalid_argument`) rather than ignoring it.
Full encoding, zero-bound, error and ownership rules are in [[HTTP Routing]].

#### Owned HTTP Client Errors

Opt in by replacing `get()` with `get_result()`, `send()` with `send_result()`,
or using `request_result()` for any supported method. The content type is not
automatically chosen by `request_result()`; pass it when required. An explicit
nonempty type is emitted even for an empty body, together with `Content-Length: 0`.
An empty body without a type remains bodyless. Existing
optional-returning methods retain their signatures and map a failed value to
an empty optional plus `errno`. Capture that legacy errno immediately.

```cpp
enum class client_stage {
    target, resolve, acquire, connect, tls, request, headers, body, framing,
    proxy_connect, proxy_tls
};
struct client_error {
    std::error_code code;
    client_stage stage;
};
template<class T> using client_result = std::variant<T, client_error>;

auto result = co_await c.get_result(endpoint, token);
if (auto* failure = std::get_if<client_error>(&result)) {
    report_failure(failure->stage, failure->code);
} else {
    handle_response(std::get<response>(result)); // 401/404/503 are responses.
}
```

All operational codes are positive errno values in `std::generic_category()`;
an unavailable/nonpositive cause is represented as `EIO`. Metadata is fixed-size
and owned: it contains no borrowed views, URLs, authorization data, or diagnostic
strings. It remains valid after the request/client is destroyed or `errno`
changes. This is not a promise that existing debug logging redacts requests.

| Stage | Boundary |
|-------|----------|
| `target` | URL/scheme/target validation, or cancellation before URL setup |
| `resolve` | Address resolution failure or cancellation at that boundary |
| `acquire` | Cancellation before connection acquisition |
| `connect` | TCP connection failure, cancellation, or connect deadline |
| `tls` | TLS context validation, handshake failure/cancellation/deadline |
| `proxy_connect` | CONNECT negotiation, status rejection, framing/size bound, cancellation or setup deadline |
| `proxy_tls` | Independent outer proxy TLS authentication, ALPN, cancellation or setup deadline |
| `request` | Request/header validation, serialization, or request write failure/cancellation/deadline |
| `headers` | Transport failure, cancellation, or deadline before final headers complete |
| `body` | Transport failure, cancellation, or deadline after headers; aggregate body limit (`EMSGSIZE`) |
| `framing` | Decoder errors (including malformed/truncated input), unsupported protocol handoff, or aggregate informational-response framing limit |

`ECANCELED` reports explicit cancellation, `ETIMEDOUT` a configured deadline,
and malformed/truncated framing uses `EBADMSG`. Decoder size limits can use
`EMSGSIZE`. TLS errors preserve the TLS stream's positive errno mapping rather
than embedding OpenSSL diagnostics. A race can still be won by actual I/O
completion, and stages do not prescribe retry/replay policy. Redirect processing,
pool reuse rules, and caller retry policy are unchanged. New connection DNS
observation is cancellable and uses `dns_timeout`/`dns_domain`; the independent
TCP/TLS connect budget still begins after resolution; proxy routes include CONNECT
without restarting that budget.

HTTP acquisition takes an operation-owned snapshot of the owning transport's
`transport_config::dns_timeout` and `dns_domain`. Configure these before
publishing the transport. `connection_pool::{acquire_result,acquire}` accept a
trailing optional `connection_pool::dns_options{timeout, domain}` after the
token. An omitted override uses the pool configuration; an engaged null domain
selects the shared resolver default, including after clearing a constructor-time
custom domain.

The same vocabulary is available in `client_connect_result()` and
`connection_pool::acquire_result()`; their optional counterparts remain adapters.
Pool acquisition preserves the legacy immediate-completion rule: a fresh cached
connection is returned before checking an already-cancelled token. Without a
usable cached connection, pre-cancellation returns `ECANCELED` at `acquire`.
These are not universally nonthrowing APIs: allocation, TLS setup, scheduler
admission, and programming exceptions may propagate. Keep clients, request/URL
objects, caches/TLS contexts, and borrowed string inputs alive through awaited
return, and serialize mutable client use.

#### Scoped Streaming Client Results

```cpp
struct streaming_response_options {
    size_t max_body_size = std::numeric_limits<size_t>::max();
    size_t max_informational_bytes = 16 * 1024 * 1024;
};
struct body_read_progress {
    size_t transferred = 0;
    bool complete = false;
};
using body_read_result = client_result<body_read_progress>;
class response_body_reader { // Noncopyable/nonmovable; only within the handler.
public:
    coro::task<body_read_result> read_into(std::span<char>, coro::cancel_token = {});
    coro::task<body_read_result> read_into(std::span<std::byte>, coro::cancel_token = {});
    bool complete() const noexcept;
    const std::optional<client_error>& error() const noexcept;
};
```

`with_response` owns its request, target, and possibly move-only handler before
lazy execution. Keep the client alive/unmoved and its configuration stable through
awaited return. The handler receives final initial headers with an empty body,
then explicitly pulls payload through a scoped reader. Neither reader nor read
task may escape; serialize and await all started reads before handler return.
`complete()` and `error()` are inspected only between reads. Empty destinations
do not advance framing; zero bytes without `complete=true` are not EOF. Positive
short reads are normal, and terminal errors remain sticky. Concurrent entry is
rejected with nonterminal `EALREADY` without changing the admitted read; scope
serialization/join requirements still apply. The handler's token argument is a
const lvalue: by-value and const-reference token parameters are supported.
Borrowed destination access
ends before each awaited return, including cancellation/error return.

A root token and each read's token both participate while incomplete. Explicit
completion takes precedence over later read cancellation; root cancellation
still fails the outer exchange and prevents reuse. The absolute per-hop
response I/O deadline is retained across pulls, not extended per read; it is not
a total DNS/setup/handler budget. Early exit, exceptions, incomplete consumption,
framing failure and cancellation close rather than pool the connection. Observe
explicit complete=true before successful reuse is possible. The outer result is
an empty success value or owned operational error; ignored read errors still
fail it, while handler exceptions propagate. Success does not validate a range
or turn a non-2xx status into an error. Streaming follows accepted redirects at
headers without aggregating/draining their bodies. See
[HTTP Streaming](HTTP-Streaming.md#scoped-client-response-consumption) for precise
buffer, limit, timeout, cancellation, and disposition boundaries.

### `base_client_config`

Shared by `http::client_config`, `websocket::client_config`, and
`sse::client_config`.

```cpp
struct base_client_config {
    std::chrono::seconds connect_timeout{10};
    std::chrono::seconds read_timeout{30};
    size_t read_buffer_size = 8192;
    std::string user_agent;
    bool verify_certificate = true;
    net::resolve_options resolve_options = net::default_cached_resolve_options();
    bool rotate_resolved_addresses = true;
    size_t max_headers = 100;
    size_t max_header_size = 8192;
    std::chrono::nanoseconds dns_timeout{0};
    std::shared_ptr<net::resolve_domain> dns_domain;
};
```

- `connect_timeout`: TCP connect and TLS handshake deadline. `<=0` disables it.
- `dns_timeout`: Independent per-new-connection DNS observer budget; `<=0`
  disables it (the default). It does not change `connect_timeout` scope.
- `dns_domain`: Shared DNS admission; null selects the capacity-64 default.
- `read_timeout`: Request/response, WebSocket upgrade, or SSE response header
  read deadline depending on the client. `<=0` disables it.
- `read_buffer_size`: Per-client read buffer size.
- `user_agent`: User-Agent header; empty disables the header.
- `verify_certificate`: TLS certificate verification policy.
- `resolve_options`: DNS resolution and cache behavior.
- `rotate_resolved_addresses`: Rotate the starting address across DNS results.
- `max_headers`: Maximum response headers accepted by parsers.
- `max_header_size`: Maximum size of one response header line in bytes.

For `http::client`, `verify_certificate`, `resolve_options`,
`rotate_resolved_addresses`, `dns_timeout`, and `dns_domain` are copied into the
owning `http::transport` at construction. WebSocket, SSE, and HTTP/2 clients
still own their connection policy directly in their client configuration.

### `client_config`

```cpp
struct client_config : base_client_config {
    size_t max_redirects = 5;
    bool follow_redirects = true;
    size_t max_connections_per_host = 6;
    std::chrono::seconds pool_idle_timeout{60};
    std::optional<pool_limits> limits;
    std::chrono::nanoseconds acquisition_timeout{0};
    std::optional<http_proxy_config> proxy;
    size_t max_response_size = 16 * 1024 * 1024;
    std::chrono::milliseconds expect_continue_timeout{1000};
    // Inherits all base_client_config fields.
};
```

For `http::client`, `max_connections_per_host`, `pool_idle_timeout`, `limits`,
`acquisition_timeout`, and `proxy` are
transport-policy fields. They are copied into a private transport by
`client(client_config)` or into an explicit `transport_config` by
`transport_config(client_config)`. Mutating them through `client.config()` after
construction does not resize an existing pool. `connect_timeout` remains
per-client/per-acquisition for compatibility.

An absent `limits` keeps legacy unbounded live admission and idle-only
`max_connections_per_host`. When enabled, finite idle limits replace that legacy
retention option. Every zero limit denies the named resource, not infinity.
`acquisition_timeout` defaults to disabled (`<= 0`); when positive, one absolute
budget covers queueing, DNS, TCP, CONNECT and TLS, independently of finite admission.
Independent DNS/connect caps can shorten it. Global FIFO and overload semantics,
streaming capacity ownership and migration hazards are described in
[HTTP Connection Routing And Reuse](HTTP-Routing.md#opt-in-finite-admission).

When `follow_redirects` is enabled, the client resolves `Location` values with
`url::resolve_reference()`, rejects unsupported schemes, and rejects HTTPS to
HTTP downgrades.

Method-preserving redirects retain the payload, content type, and explicitly
supplied zero-length representation metadata. For an empty body, only a strictly
parsed zero Content-Length is copied; nonzero or invalid raw assertions are not
forwarded. This does not add first-hop request-framing validation. Redirects do
not invent a length for an originally bodyless request. Redirects that change
POST to GET (301/302), and 303 content-dropping redirects, omit representation
metadata; 303 retains
HEAD as HEAD. The setter-managed `Expect: 100-continue` handshake is omitted
for an empty body; this does not validate a manually supplied raw Expect header.

`expect_continue_timeout` bounds the wait for an interim `100 Continue` when a
request uses `request::set_expect_continue()` and has a body. If the server
answers with `100 Continue`, the client sends the body and then processes the
response normally (any further interim 1xx responses are skipped). If the
server answers with a final response first (for example `417 Expectation
Failed`), the body is not sent and the response is consumed as usual. If the
deadline expires first, the body is sent anyway (RFC 9110 §10.1.1 fallback).
The wait is additionally bounded by the absolute response deadline
(`read_timeout`), whichever expires first; response-deadline expiry fails the
request with `ETIMEDOUT` instead of triggering the fallback. A value less
than or equal to zero skips the wait entirely: the body is sent
immediately after the headers. For redirects that preserve the request body
(307/308 and method-preserving redirects), the Expect handshake re-runs per
hop.

`websocket::client_config` and `sse::client_config` also inherit
`base_client_config`, including timeout, read-buffer, TLS verification, DNS
resolution/cache, address rotation, and response-header limit settings.

`websocket::client_config` does not define automatic reconnect settings.
`websocket::ws_client::connect()` is a single connection attempt. On connect
failure, close, or read error, Elio reports the result through the operation
return value, `errno` where applicable, and connection state. Cancelling an
operation reports cancellation for that operation, but it is not an automatic
reconnect trigger. The caller owns retry/backoff policy, idempotency, message
replay, and any application session restoration. Callers may explicitly call
`connect()` again after the client is closed.

Cancellation tokens are independent from configured deadlines. Passing a token
to HTTP, WebSocket, or SSE client operations cancels the underlying pending I/O
instead of only checking the token between I/O calls.

### `server_config`

```cpp
struct server_config {
    size_t max_request_size = 10 * 1024 * 1024;
    size_t read_buffer_size = 8192;
    std::chrono::seconds keep_alive_timeout{30};
    size_t max_keep_alive_requests = 100;
    bool enable_logging = true;
    std::chrono::milliseconds write_timeout{0};
    size_t max_headers = 100;
    size_t max_header_size = 8192;
};
```

`max_request_size` is an aggregate HTTP request-byte cap. It includes the
request line, headers, and body for the request currently being parsed. The
server rejects a request with `413 Payload Too Large` when parsed request bytes,
buffered request bytes, or the accumulated body exceed the configured cap.
`http::server` can also reject an oversized declared `Content-Length` before
allocating the body. For WebSocket upgrades, only the HTTP upgrade request is
counted; bytes buffered after the completed upgrade belong to the WebSocket
stream and are governed by WebSocket frame/message limits instead. Callers must
choose a value that covers the largest accepted combination of request line,
headers, and body, rather than treating the setting as a body-only limit.

`keep_alive_timeout` bounds each incoming request handled by `http::server`
and the HTTP upgrade request read handled by `websocket::ws_server`. For
`server::listen_tls()` and `websocket::ws_server::listen_tls()`, it also bounds
the inbound TLS handshake. A value less than or equal to zero disables these
server-side deadlines.

`write_timeout` defaults to zero (disabled) to avoid silently introducing a
new outbound deadline. Positive values bound each logical final-header, body
write or final-marker operation, including all its partial-write retries.
It is not a producer, whole-response or SSE-session deadline.

### `context`

HTTP request context passed to `http::server` route handlers.

```cpp
class context {
public:
    using interim_writer = std::function<coro::task<bool>(std::string_view)>;
    context(request, std::string_view client_addr,
            interim_writer = {}, coro::cancel_token = {});
    coro::cancel_token cancel_token() const noexcept;
    const request& req() const noexcept;
    request& req() noexcept;
    std::string_view client_addr() const noexcept;
    std::string_view param(std::string_view name) const;
    void set_param(std::string_view name, std::string_view value);
    std::string query_param(std::string_view name) const;
    const std::unordered_map<std::string, std::string>& params() const noexcept;

    // Send an interim (1xx) response before the final response (awaitable)
    coro::task<bool> send_interim(const response& resp);
};
```

`send_interim()` writes an interim response on the connection before the
handler returns the final response. The response status must be 1xx other
than 101 Switching Protocols (an upgrade is never an interim response);
anything else sets `errno = EINVAL` and returns `false`. Multiple interim
responses may be sent, as RFC 9110 §15.2 permits. Body and framing headers
are never serialized for 1xx statuses, so `response(status::continue_)`
writes exactly `HTTP/1.1 100 Continue\r\n\r\n`.

The context remains alive through handler selection, the selected producer,
and send cleanup. It must not escape that scope (for example into a detached
task). Final selection seals interims: subsequent `send_interim()` calls fail
with `EALREADY`, including calls from the producer. Contexts dispatched
without a connection writer — for example the plain-HTTP fallback routes of
`websocket::ws_server` — cannot send interims: `send_interim()` then sets
`errno = ENOTSUP` and returns `false`, and the final response is unaffected.

> **Note**: `http::server` reads the full request, including the body, before
> dispatching to the handler. An explicit `100 Continue` sent with
> `send_interim()` therefore cannot accelerate an `Expect: 100-continue`
> client's first body send; it serves clients that pipeline or that wait for
> an interim the application emits deliberately.

### Router Return Types and Server Shutdown

```cpp
using handler_func = std::function<coro::task<reply>(context&)>;
using sync_handler_func = std::function<response(context&)>;
// Constrained Handler returns exactly one of:
// response, streaming_response, reply, task<response>,
// task<streaming_response>, task<reply>.
template<typename Handler>
void router::add_route(method, std::string_view pattern, Handler);
// get/post/put/del/patch/options use the same supported handler shapes.
template<typename Handler>
void server::set_not_found_handler(Handler);
void server::stop();
size_t server::active_connections() const noexcept;
```

Stored handler callables must be copyable; a streaming response's owned
producer may be move-only. The server and WebSocket ordinary HTTP fallback
use the same reply sender; successful WebSocket upgrades remain a separate
protocol handoff. Pass `ctx.cancel_token()` or the supplied producer token
into cancellation-aware waits.

`stop()` requests cooperative listener/session cancellation, not a join or
forced frame destruction. Retained cancellation sources cover accepted
connections even after their accept loop exits. Before destroying the server
or referenced TLS/handler resources: stop, await every listener task, then
wait for `active_connections() == 0`. A zero count before listener completion
does not rule out an accept/spawn race. Token-ignoring work can delay cleanup.
TLS close-notify uses the whole-session close budget (default 5 seconds), with
cleanup allowed to outlast it; it has no session-token overload.

### `request`

HTTP request message.

```cpp
class request {
public:
    request(method m, std::string_view path);
    
    void set_method(method m) noexcept;
    void set_path(std::string_view path);
    void set_query(std::string_view query);
    void set_version(std::string_view version);
    void set_header(std::string_view name, std::string_view value);
    void set_body(std::string_view body);
    void set_body(std::string&& body);
    void set_host(std::string_view host);
    void set_content_type(std::string_view type);
    void set_expect_continue(bool on = true);
    headers& get_headers() noexcept;
    const headers& get_headers() const noexcept;
    
    method get_method() const noexcept;
    std::string_view path() const noexcept;
    std::string_view query() const noexcept;
    std::string_view version() const noexcept;
    std::string_view header(std::string_view name) const;
    std::string_view body() const noexcept;
    std::string_view host() const;
    std::string_view content_type() const;
    bool expect_continue() const noexcept;

    std::string serialize_headers() const;
    std::string serialize() const;
};
```

`set_path()` and `set_query()` validate request-target components and throw
`std::invalid_argument` for invalid control characters or spaces.
`set_version()` accepts an empty value for the default `HTTP/1.1` serialization
or a version token of the form `HTTP/<digits>.<digits>`; invalid values throw
`std::invalid_argument`.

`set_expect_continue()` sets or clears the `Expect: 100-continue` header
together with the client-side sending flag. The setter owns the `Expect`
header: enabling overwrites any existing value and disabling removes the
header outright. When the flag is enabled and the request has a body,
`http::client::send()` transmits the headers first and waits (bounded by
`client_config::expect_continue_timeout`) for an interim `100 Continue`
before sending the body; see `client_config` for the fallback semantics. A
bodyless request never serializes the `Expect` header (RFC 9110 §10.1.1
forbids `Expect` without content). `serialize_headers()` returns the request
line and headers without the body; `serialize()` shares it and appends the
body.

### CONNECT Request Parsing

`request_parser` accepts CONNECT authority-form (`host:port`, or `[IP-literal]:port`),
with a nonempty URI host and explicit decimal port in 1..65535. IPv6 and RFC 3986
IPvFuture bracket syntax are validated; unbracketed names use URI reg-name
grammar, not a DNS-only policy. Raw case, trailing dots, percent triplets,
brackets and leading port zeros are preserved in `path()`; `query()` and `body()`
are empty. Userinfo, path/query/fragment, invalid escapes/literals and invalid
ports are rejected. Scoped IPv6 zone identifiers are outside this URI grammar.

Transfer-Encoding or nonzero Content-Length is rejected when headers complete,
without waiting for request content; CL:0 is allowed. `take_remaining()` moves
out post-header bytes exactly once for the next protocol. Host cardinality
checks remain unchanged, and Host is not a replacement tunnel destination.
Resolution and access policy belong to the application. Parsing alone does not
accept a tunnel; use the separate HTTP/1 server API below. HTTP/2 CONNECT is not
included.

### CONNECT Routing And Sessions

Declared in `http_tunnel.hpp`, `http_tunnel_response.hpp` and
`http_tunnel_relay.hpp`, and available through the HTTP umbrella header:

```cpp
struct connect_authority_view {
    std::string_view raw, host;
    uint16_t port;
};
// router.connect(handler): handler(context&, connect_authority_view)
// accepts response, streaming_response, tunnel_response, reply, or task of each.

enum class tunnel_end {
    completed, session_closed, cancelled, timed_out, transport_error,
    invalid_response, invalid_state, callback_error
};
struct tunnel_direction_result {
    uint64_t source_bytes = 0, accepted_bytes = 0;
    bool uncertain_write = false;
};
struct tunnel_result {
    tunnel_end end = tunnel_end::completed;
    int error = 0;
    tunnel_direction_result client_to_upstream, upstream_to_client;
    bool success() const noexcept;
};
struct tunnel_write_result {
    uint64_t accepted_bytes = 0;
    int error = 0;
    bool uncertain_attempt = false;
    bool success() const noexcept;
};
class tunnel_stream { // Noncopyable/nonmovable; provided only to the session.
public:
    coro::task<io::io_result> read(void*, size_t, coro::cancel_token = {});
    coro::task<tunnel_write_result> write(const void*, size_t, coro::cancel_token = {});
    coro::task<tunnel_write_result> write(std::string_view, coro::cancel_token = {});
    coro::task<tunnel_write_result> writev(std::span<const iovec>, coro::cancel_token = {});
    coro::task<net::write_finish_result> finish_output(coro::cancel_token = {});
    net::close_scope read_end_scope() const;
    int error() const noexcept;
};
class tunnel_response : public response_head {
public:
    template<class Session> tunnel_response(response_head, Session&&);
    template<class Session> tunnel_response(status, Session&&);
    template<class Session> explicit tunnel_response(Session&&); // Default 200.
    // Move-only; Session returns task<tunnel_result>(tunnel_stream&, cancel_token).
};
struct relay_options { size_t buffer_size = 64 * 1024; };
coro::task<tunnel_result> relay(tunnel_stream&, net::stream&,
    relay_options = {}, coro::cancel_token = {});
```

`raw` preserves the authority spelling; `host` removes IP-literal brackets but
does not decode percent escapes or resolve names. Views borrow request storage.
The dedicated CONNECT handler bypasses path matching. Authorize and establish
the upstream before accepting; a non-2xx ordinary response rejects the request.

Server dispatch requires a 2xx tunnel response without CL/TE for an HTTP/1
CONNECT request. It writes the head before invoking the owned callable at most
once, moves parser read-ahead into the view, and never resumes HTTP parsing or
reuse. Ordinary `send_response()` rejects this alternative and ordinary 2xx
CONNECT replies. A moved-from or already invoked session cannot run again.

One read may overlap one write-side operation; the callback must join its own
tasks before returning. Writes complete all supplied slices or return confirmed
progress plus an uncertain failed attempt. Payloads and descriptors stay
borrowed through cleanup; there is no aggregate plaintext output buffer or
automatic replay. `success()` on `tunnel_result` recognizes `completed` and
`session_closed`; neither means peer receipt or complete reverse forwarding.

`read`, `write`, `writev` and `finish_output` can throw before returning a task
if coroutine-frame construction fails. Their entry wrappers first make the view
terminal (`ENOMEM` for allocation failure, otherwise `EIO`) and request sibling
cancellation, then rethrow. Catching that exception does not make the view reusable:
still join every overlapping task before releasing its buffers or returning from
the session. A scalar write whose nested vector-operation frame fails after its
task has started instead returns a structured failure with no accepted bytes or
uncertain transport attempt. These guarantees do not promise progress under
arbitrary memory exhaustion or permit forced coroutine-frame destruction.

The optional relay owns two fixed buffers and joins both directional tasks on
every exit, including launch failure. Normal directional EOF preserves reverse
traffic. Whole-session EOF/finish coordinates normal closure before internal
sibling stop; external cancellation and transport failures remain distinct
result causes. `read_end_scope()` describes an observed EOF, not a transport
capability and not evidence of authenticated EOF after an error. For TLS 1.2
it may also identify the already selected whole-close state when coordinating
normal `ESHUTDOWN` from the other direction.

See [HTTP Streaming](HTTP-Streaming.md#connect-tunnel-handoff) for the TLS 1.2
commitment boundary, five-second whole-close budget and caller-owned security
policy. High-level HTTP client CONNECT support is not added by this server API.

### `headers`

Case-insensitive HTTP header collection used by `request` and `response`.

```cpp
class headers {
public:
    void set(std::string_view name, std::string_view value);
    void add(std::string_view name, std::string_view value);
    std::string_view get(std::string_view name) const;
    std::vector<std::string_view> get_all(std::string_view name) const;
    bool contains(std::string_view name) const;
    void remove(std::string_view name);
    void clear();
};
```

`set()` overwrites the named field. `add()` records an additional field line:
list-valued headers keep the existing `get()` behavior by returning a
comma-joined value, while `get_all()` returns each field-line value
individually.
`Set-Cookie` is not comma-joined; `get()` returns the first cookie value and
`get_all()` returns every cookie field line. Conflicting duplicate
`Content-Length` values throw `std::invalid_argument`.

### Response Metadata, Complete Bodies and Streaming

Headers: `<elio/http/http_response_head.hpp>`, `http_message.hpp`,
`http_streaming_response.hpp`, `http_reply.hpp`, `http_body_writer.hpp`, and
`http_response_sender.hpp` (under `elio/http/`).

```cpp
class response_head {
public:
    response_head();
    explicit response_head(status);
    status get_status() const noexcept;
    uint16_t status_code() const noexcept;
    void set_status(status) noexcept;
    std::string_view version() const noexcept;
    void set_version(std::string_view);
    headers& get_headers() noexcept;
    const headers& get_headers() const noexcept;
    std::string_view header(std::string_view) const;
    void set_header(std::string_view name, std::string_view value);
    std::string_view content_type() const;
    void set_content_type(std::string_view);
    std::optional<uint64_t> representation_length() const noexcept;
    void set_representation_length(std::optional<uint64_t>) noexcept;
    bool is_success() const noexcept;
    bool is_redirect() const noexcept;
    bool is_client_error() const noexcept;
    bool is_server_error() const noexcept;
};
class response : public response_head {
public:
    response();
    explicit response(status);
    response(status, std::string_view body, std::string_view content_type = mime::text_plain);
    std::string_view body() const noexcept;
    void set_body(std::string_view);
    void set_body(std::string&&);
    std::string serialize() const;
    std::string serialize(method request_method) const;
    static response from_parser(response_parser&);
    static response from_decoder(const response_decoder&, std::string body);
    // Existing ok/json/html/not_found/bad_request/internal_error/redirect factories.
};
enum class response_transfer { automatic, close_delimited };
class streaming_response : public response_head {
public:
    template<typename Producer>
    streaming_response(response_head, Producer&&,
        std::optional<uint64_t> length = std::nullopt,
        response_transfer transfer = response_transfer::automatic);
    template<typename Producer>
    streaming_response(status, Producer&&,
        std::optional<uint64_t> length = std::nullopt,
        response_transfer transfer = response_transfer::automatic);
    std::optional<uint64_t> body_length() const noexcept;
    response_transfer transfer() const noexcept;
    // Move-only; owns the producer, not externally referenced payload.
};
using reply = std::variant<response, streaming_response, tunnel_response>;
```

Metadata defaults to 200 / HTTP/1.1 and no representation length. Version setters
validate syntax; final preflight supports HTTP/1.0 and HTTP/1.1 only.
`response` body setters do not create or update Content-Length. Manual CL is
an assertion checked against selected framing. Ordinary `serialize()` uses
the shared preflight and throws `std::invalid_argument` for invalid CL/TE;
it explicitly materializes a string, unlike the borrowed server send path.
Informational 1xx/101 and successful CONNECT use a distinct headers-only
serialization branch, stripping prohibited framing fields.

`from_parser()`/`from_decoder()` preserve received headers and decoded body.
Before reserializing a received chunked body, explicitly remove
`Transfer-Encoding`; remove or update any stale CL if changing payload.
No implicit normalization hides this responsibility. Complete-response
`set_close_delimited()`/`close_delimited()` are removed.

The producer is callable as
`coro::task<send_result>(body_writer&, coro::cancel_token)` and may be move-only.
It executes at most once and returns success or failure; it has no public
finish step. HEAD/bodyless replies skip it. Captures, selected reply and
borrowed data must remain valid through execution and cleanup; do not move
the reply or escape its writer during sending.

### Framing Preflight and Send Results

```cpp
enum class response_body_kind { complete, streaming };
enum class response_framing { none, content_length, chunked, close_delimited };
struct body_description {
    response_body_kind kind = response_body_kind::complete;
    std::optional<uint64_t> length = std::nullopt;
    response_transfer transfer = response_transfer::automatic;
};
struct response_plan {
    std::string header_block;
    response_framing framing = response_framing::none;
    std::optional<uint64_t> expected_body_bytes;
    bool invoke_producer = false;
    bool reusable = false;
    int error = 0; // positive errno
    bool success() const noexcept;
};
response_plan prepare_response(const response_head&, body_description,
    method request_method, std::string_view request_version, bool allow_reuse);

enum class send_errc { none, invalid_response, length_mismatch, invalid_state,
    cancelled, timed_out, transport_error, producer_error };
struct send_result {
    send_errc error = send_errc::none;
    int transport_error = 0;
    uint64_t confirmed_body_bytes = 0;
    bool success() const noexcept;
};
struct body_buffer { const void* data = nullptr; size_t size = 0; };
class body_writer { // noncopyable, nonmovable; supplied by sender only
public:
    coro::task<send_result> write(std::string_view, coro::cancel_token = {});
    coro::task<send_result> writev(std::span<const body_buffer>, coro::cancel_token = {});
};
struct response_send_result {
    send_result result;
    bool reusable = false;
    bool success() const noexcept;
};
template<typename Stream>
coro::task<response_send_result> send_response(Stream&, reply&, method,
    std::string_view request_version, bool allow_reuse,
    coro::cancel_token = {}, std::chrono::nanoseconds write_timeout = {});
```

Preflight emits no final header bytes on error (allocation may throw). Complete
bodies require an explicitly supplied length, including zero for an empty body.
`body_description::length` defaults to `std::nullopt`: an omitted streaming
length is unknown, while a default complete description is invalid. Known
streaming length uses CL; unknown length
uses chunked for HTTP/1.1 or close delimiting for HTTP/1.0. Explicit close requires
unknown length and no manual CL. Response HTTP/1.1 is clamped for a request HTTP/1.0.
Explicit TE and malformed/conflicting CL fail; identical duplicate CL lines
already canonicalized by `headers` have no recoverable duplicate history.

HEAD chooses representation length then known body length, suppressing actual
bytes. 304 uses representation length or validated manual metadata CL, never
the stored body length. 204 suppresses framing; 205 emits CL 0 and rejects a
nonzero manual assertion. Ordinary final sending rejects 1xx/101 and successful
CONNECT; they require separate interim/handoff handling. These special bodyless
rules precede producer configuration. Reuse combines caller permission,
response Connection policy and framing; nonreuse emits Connection: close.

These length selections follow status precedence, including for HEAD requests.
For ordinary HEAD, manual CL alone cannot supply a missing representation/body
length: it must agree with the selected length. For 304, manual CL can supply
metadata when no explicit representation length is set. In either case, the
caller is responsible for the truth of the advertised representation size.
Preflight validates supplied values and their consistency, not the size that a
corresponding GET would actually produce. No producer is run for verification.

`write`/`writev` are sequential borrowed operations: descriptors and payload
stay immutable/alive until await returns after transport/watchdog cleanup.
Empty writes are no-ops only on an open, noncancelled writer. Positive short
writes and EINTR are retried internally; readiness-aware transports handle
EAGAIN without an application retry loop. Bounded descriptor scratch and
chunks of at most 1 GiB do not imply zero allocations, zero-copy TLS, or stable
chunk/syscall boundaries. No payload-sized staging buffer or output queue is
introduced by body_writer.

Known-length overrun fails before that write sends bytes; underproduction
fails internal finalization. First failure terminates the writer, including
ignored failures. Each logical write has one success/timeout/cancel/error
winner and one deadline across retries. Late positive completion may increase
cumulative diagnostic body-byte counts but does not rewrite its winner.
Failure may follow visible wire effects: no rollback or whole-response replay.
State/setup allocation errors report sticky ENOMEM; task-frame allocation
can instead throw after marking failure because returning an error task also
requires allocation. Catching that exception does not reopen the writer.

For direct `send_response`, retain stream/reply through await and close on
failure or `reusable == false`; the function does not own pooling or closing.
The supplied stream must provide readiness-aware
`writev(iovec*, size_t, coro::cancel_token)` returning `coro::task<io::io_result>`.
Positive write timeouts require a current scheduler (otherwise ENOTSUP).
See [HTTP Streaming](HTTP-Streaming.md) for lifecycle and migration details.

### HTTP Enums

For response decoder events and pull-reader signatures, see the following
incremental receive section.

```cpp
enum class method {
    GET, HEAD, POST, PUT, DELETE_, CONNECT, OPTIONS, TRACE, PATCH
};

enum class status {
    ok = 200,
    created = 201,
    no_content = 204,
    moved_permanently = 301,
    found = 302,
    bad_request = 400,
    unauthorized = 401,
    forbidden = 403,
    not_found = 404,
    internal_server_error = 500,
    // ... more
};

// Get reason phrase for status
constexpr std::string_view status_reason(status s) noexcept;
```

---

## Incremental HTTP Response Receive (`elio::http`)

Include `<elio/http/http_parser.hpp>` for `response_decoder` and the
accumulating `response_parser`; include `<elio/http/http_response_reader.hpp>`
for the pull reader. See [[HTTP Streaming]] for lifetime rules and examples.

```cpp
enum class response_event {
    need_more, headers_complete, body, message_complete, protocol_handoff, error
};

struct response_decode_result {
    response_event event = response_event::need_more;
    size_t consumed = 0;
    std::string_view body;
};

class response_decoder {
public:
    void set_max_headers(size_t max) noexcept;
    void set_max_header_size(size_t max) noexcept;
    void set_request_method(method value) noexcept;
    void reset();
    response_decode_result decode(std::string_view input);
    response_decode_result finish_eof();
    status get_status() const noexcept;
    uint16_t status_code() const noexcept;
    std::string_view version() const noexcept;
    std::string_view reason() const noexcept;
    const headers& get_headers() const noexcept;
    headers& get_headers() noexcept;
    std::string_view error_message() const noexcept;
    bool headers_complete() const noexcept;
    bool is_complete() const noexcept;
    bool has_error() const noexcept;
    bool limit_exceeded() const noexcept;
    bool is_close_delimited() const noexcept;
    size_t bytes_buffered() const noexcept;
};

struct response_read_result {
    response_event event = response_event::need_more;
    std::string_view body;
    int error = 0;
    bool success() const noexcept; // error == 0, not message completeness
};

class response_reader {
public:
    explicit response_reader(size_t buffer_size = 8192);
    response_reader(response_reader&&);
    response_reader& operator=(response_reader&&);
    const response_decoder& decoder() const noexcept;
    void set_max_headers(size_t max) noexcept;
    void set_max_header_size(size_t max) noexcept;
    void set_request_method(method value) noexcept;
    void reset();
    template<typename Stream>
    coro::task<response_read_result> read(
        Stream& stream, coro::cancel_token token = {});
    template<typename Receive>
    coro::task<response_read_result> read_with(
        Receive& receive, coro::cancel_token token = {});
    bool next_response();
    size_t bytes_remaining() const noexcept;
    size_t message_bytes() const noexcept;
    std::string_view remaining() const noexcept;
    bool reached_eof() const noexcept;
};
```

The decoder emits headers before body, even when both arrive in one input.
`consumed` is relative only to that input. Drain events, including with empty
input, until `need_more` or a terminal event; terminal events repeat without
consuming more input. A decoder body view borrows the input. A reader body
view borrows its receive buffer and is valid only until the next reader
operation, move, or destruction. Neither stores an accumulating body buffer.
Do not move a reader during an active operation. A moved-from reader is usable
only for destruction or assignment. A zero receive-buffer size is normalized
to one byte; the default is 8192 bytes.

Configure limits and request method before decoding. Defaults are 100 header
field lines and 8192 bytes per metadata line, excluding CRLF; the line bound
also applies to status, chunk-size, and trailer lines. Duplicate field lines
count, and trailers share the header count. The existing `kMaxChunkSize`
limit is 1 GiB per declared chunk. `bytes_buffered()` counts only pending
framing-line bytes, not owned parsed headers or delivered body. Neither low-level
receiver imposes an aggregate body-byte limit. Ordinary `http::client` separately
caps accumulated final body and cumulative interim wire bytes using
`max_response_size`; these are separate budgets, not a combined total.
`client::with_response` instead uses separate streaming payload/interim options
and retains only bounded scratch/framing storage; it does not impose the buffered
body limit or claim transport-to-destination zero-copy.

`Stream::read(data, size, token)` must be readiness-aware and return an
`io::io_result`. `read_with()` accepts a callback invoked as
`receive(void*, size_t)`, returning an awaitable `io::io_result`; it must obey
the supplied buffer bounds and end its buffer access before completion. The
callback owns its deadline and in-flight cancellation policy; the reader's
token is not passed as an extra callback argument. Short reads and `EINTR`
are handled internally. Other transport errors are returned as positive
`error` values without resetting framing state. Framing errors are terminal
until reset. The reader does not close, pool, reconnect, or replay a connection.

`next_response()` succeeds only after a `message_complete` event and retains
unread transport bytes. It refuses pending, erroneous, and handed-off messages.
`reset()` instead discards all receive state for a new connection. Both retain
configured limits and clear the request method; reapply it for the next response.
`message_bytes()` counts accepted wire bytes for the current message, including
framing, saturates at `SIZE_MAX`, and resets on either operation. `remaining()`
exposes unread wire bytes, not decoded body; protocol handoff requires the
caller's own upgrade/tunnel validation.

`response_parser` remains the accumulating adapter, not a second response
framing implementation. Its legacy consumed count includes retired bytes from
earlier feeds, and its `reset()` retains unread input. Chunk body progress is
now visible before trailing CRLF validation. Check completion, not just a
nonempty body. `response::from_decoder(const response_decoder&, std::string)`
constructs an owning response from metadata and an explicitly accumulated body;
the caller must establish successful final completion before using it.

---

## WebSocket (`elio::websocket`)

WebSocket support is declared in `elio::http::websocket` and re-exported as
`elio::websocket` by `<elio/http/websocket.hpp>`.

### `websocket::client_config`

```cpp
struct client_config : http::base_client_config {
    size_t max_message_size = 16 * 1024 * 1024;
    std::vector<std::string> subprotocols;
    std::string origin;
};
```

`websocket::client_config` inherits the shared HTTP client timeout, buffer, TLS
verification, DNS, and response-header limit settings. It does not define an
automatic reconnect loop.

### `websocket::server_config`

```cpp
struct server_config {
    size_t max_message_size = 16 * 1024 * 1024;
    size_t read_buffer_size = 8192;
    std::chrono::seconds ping_interval{30};
    std::chrono::seconds ping_timeout{10};
    std::vector<std::string> subprotocols;
    bool enable_logging = true;
};
```

`ping_interval <= 0` disables the automatic server heartbeat. When enabled,
`ws_server` starts a heartbeat task after a successful upgrade. The task has up
to `ping_timeout` to send a server ping and observe a pong from the route
handler's receive loop; if either step misses that window, the connection fails
closed.
`ping_timeout <= 0` keeps periodic pings but disables timeout closure. A
heartbeat timeout may close the transport without delivering a WebSocket close
frame. The heartbeat does not read from the stream; route handlers remain
responsible for running the single `receive()` loop that processes peer frames
and records pongs.

### `websocket::ws_client`

```cpp
class ws_client {
public:
    ws_client();
    explicit ws_client(client_config config);

    /* awaitable */ connect(std::string_view url);
    /* awaitable */ connect(std::string_view url, coro::cancel_token token);

    connection_state state() const noexcept;
    bool is_open() const noexcept;
    std::string_view subprotocol() const noexcept;

    /* awaitable */ send_text(std::string_view message);
    /* awaitable */ send_binary(std::string_view data);
    /* awaitable */ send_ping(std::string_view payload = "");
    /* awaitable */ send_pong(std::string_view payload = "");
    /* awaitable */ close(close_code code = close_code::normal,
                          std::string_view reason = "");
    /* awaitable */ receive();
    /* awaitable */ receive(coro::cancel_token token);

    tls::tls_context& tls_context() noexcept;
    client_config& config() noexcept;
    const client_config& config() const noexcept;
};
```

`connect()` is one connection attempt. If it fails or a later operation observes
a closed/failed connection, callers choose retry, backoff, replay, and
application session restoration policy.

During the upgrade handshake, interim 1xx responses (for example
`100 Continue`) that precede the `101 Switching Protocols` are skipped under a
cumulative byte cap; the handshake completes on the 101 and fails with
`EBADMSG` for any other final status.

### `websocket::ws_connection`

Server-side WebSocket connection passed to route handlers.

```cpp
class ws_connection {
public:
    connection_state state() const noexcept;
    bool is_open() const noexcept;
    std::string_view subprotocol() const noexcept;

    std::string_view param(std::string_view name) const;
    const std::unordered_map<std::string, std::string>& params() const noexcept;

    /* awaitable */ send_text(std::string_view message);
    /* awaitable */ send_binary(std::string_view data);
    /* awaitable */ send_ping(std::string_view payload = "");
    /* awaitable */ send_pong(std::string_view payload = "");
    /* awaitable */ close(close_code code = close_code::normal,
                          std::string_view reason = "");
    /* awaitable */ receive();
    /* awaitable */ run_heartbeat(std::chrono::milliseconds ping_interval,
                                  std::chrono::milliseconds ping_timeout,
                                  coro::cancel_token token = {});
};
```

Only one coroutine should receive from a connection at a time. Send helpers,
including heartbeat pings and automatic pong/close responses, are serialized so
concurrent senders do not interleave WebSocket frames.

### `websocket::ws_router` and `ws_server`

```cpp
using ws_handler_func = std::function<coro::task<void>(ws_connection&)>;

class ws_router : public http::router {
public:
    void websocket(std::string_view pattern,
                   ws_handler_func handler,
                   server_config config = {});
};

class ws_server {
public:
    explicit ws_server(ws_router router,
                       http::server_config http_config = {});

    /* awaitable */ listen(const net::socket_address& addr,
                           const net::tcp_options& opts = {});
    /* awaitable */ listen_tls(const net::socket_address& addr,
                               tls::tls_context& tls_ctx,
                               const net::tcp_options& opts = {});
    void stop();
    bool is_running() const noexcept;
    size_t active_connections() const noexcept;
};
```

Route pattern syntax matches the HTTP router: literal components, `:name`
parameters, and trailing `*` wildcards.

### Frame Types and Helpers

```cpp
enum class opcode : uint8_t;
enum class close_code : uint16_t;
enum class connection_state {
    connecting, open, closing, closed
};

enum class endpoint_role {
    unspecified, server, client
};

std::vector<uint8_t> encode_text_frame(std::string_view text, bool mask = false);
std::vector<uint8_t> encode_binary_frame(std::string_view data, bool mask = false);
std::pair<close_code, std::string> parse_close_payload(std::string_view payload);

inline constexpr size_t default_max_message_size = 16 * 1024 * 1024;

class frame_parser {
public:
    // Defaults to default_max_message_size (16 MiB); 0 explicitly disables it.
    void set_max_message_size(size_t max_size);
    void set_role(endpoint_role role);
    close_code error_close_code() const noexcept;
};
```

The raw frame parser is a protocol helper. It rejects aggregate messages above
the 16 MiB `default_max_message_size` unless callers choose another limit with
`set_max_message_size()`; passing `0` explicitly enables unlimited messages. It
enforces masking direction only after callers configure an endpoint role
(`server` or `client`). Applications still validate message payload schemas
after a frame has been accepted.

### `websocket::ws_connect`

```cpp
/* awaitable */ ws_connect(std::string_view url,
                           client_config config = {});
```

Returns an optional connected `ws_client`. It performs one connection attempt;
callers own retry and backoff policy.

---

## Server-Sent Events (`elio::sse`)

SSE support is declared in `elio::http::sse` and re-exported as `elio::sse` by
`<elio/http/sse.hpp>`.

### `sse::event`

```cpp
struct event {
    std::string id;
    std::string type;
    std::string data;
    int retry = -1;

    static event message(std::string_view data);
    static event typed(std::string_view type, std::string_view data);
    static event with_id(std::string_view id, std::string_view data);
    static event full(std::string_view id, std::string_view type,
                      std::string_view data, int retry = -1);
};
```

### `sse::sse_connection`

Server-side SSE connection passed to handlers.

```cpp
enum class connection_state {
    active, closed
};

class sse_connection {
public:
    connection_state state() const noexcept;
    bool is_active() const noexcept;
    std::string_view last_event_id() const noexcept;

    /* awaitable */ send(const event& evt);
    /* awaitable */ send_data(std::string_view data);
    /* awaitable */ send_event(std::string_view type, std::string_view data);
    /* awaitable */ send_comment(std::string_view comment = "");
    /* awaitable */ send_retry(int retry_ms);
    void close();
    void set_active();
    /* awaitable */ run_heartbeat(
        std::chrono::milliseconds interval = std::chrono::seconds(30),
        coro::cancel_token token = {},
        std::string_view comment = "ping");
};
```

SSE sends are serialized by the connection object. Application code owns event
schema, authorization, replay, and duplicate-handling policy.

### Managed SSE Event Production

Declared in `<elio/http/sse_writer.hpp>` and exported by `<elio/http/sse.hpp>`.

```cpp
struct event_view {
    std::optional<std::string_view> id;
    std::string_view type;
    std::string_view data;
    int retry = -1;
};
class event_writer { // factory-provided sink; no public constructor/copy
public:
    send_result result() const noexcept;
    coro::task<send_result> send_event(event_view, coro::cancel_token = {});
    coro::task<send_result> send_data(std::string_view, coro::cancel_token = {});
    coro::task<send_result> send_comment(std::string_view, coro::cancel_token = {});
};
template<typename Producer>
http::streaming_response make_streaming_response(Producer&&);
// Producer: task<send_result>(event_writer&, cancel_token), possibly move-only.
```

The factory provides a sequential producer-scoped event_writer. It sets
Content-Type: text/event-stream and Cache-Control: no-cache, not CORS policy.
Default HTTP/1.1 framing is chunked; HTTP/1.0 uses close delimiting.
The server owns response completion. Do not construct or escape the sink,
overlap sends, or add independent raw socket writes/heartbeat writers.

Event fields remain borrowed and immutable through send completion. An absent
id (`std::nullopt` or `{}`) is omitted, preserving the receiver's Last-Event-ID.
A present empty id (`std::string_view{}` or `""`) emits `id:\n`, clearing it.
The optional stores presence and a borrowed view, not an owned string.
Empty type and negative retry are omitted; data is always emitted.
CR, LF and CRLF delimit data/comment lines. Invalid CR/LF/NUL in a present id
or type fails before event output. Bounded descriptor batches avoid an
event-sized encoded string; a logical event can span multiple body writes.
The first failure is sticky even if the producer ignores its result. Frame
allocation may throw after recording a terminal error.

### Legacy Raw SSE Endpoint

`sse_connection` above serializes raw SSE bytes, not managed HTTP chunks.
Use it only when independently owning compatible HTTP framing and connection
lifetime; never attach it to a managed body_writer response.

```cpp
using sse_handler_func = std::function<coro::task<void>(sse_connection&)>;
class sse_endpoint {
public:
    explicit sse_endpoint(sse_handler_func);
    const sse_handler_func& handler() const;
};
```

The endpoint only stores a raw-stream handler, not an HTTP router reply.
`build_sse_response()` has been removed; migrate managed routes to
`make_streaming_response()` instead of sending headers separately.

### `sse::client_config`

```cpp
struct client_config : http::base_client_config {
    int default_retry_ms = 3000;
    bool auto_reconnect = true;
    size_t max_reconnect_attempts = 0;
    size_t max_event_buffer_size = 1024 * 1024;
    size_t max_informational_responses = 16;
    std::string last_event_id;
};
```

### `sse::sse_client`

```cpp
enum class client_state {
    disconnected, connecting, connected, reconnecting, closed
};

class sse_client {
public:
    sse_client();
    explicit sse_client(client_config config);

    /* awaitable */ connect(std::string_view url);
    /* awaitable */ connect(std::string_view url, coro::cancel_token token);

    client_state state() const noexcept;
    bool is_connected() const noexcept;
    std::string_view last_event_id() const noexcept;

    /* awaitable */ receive();
    /* awaitable */ receive(coro::cancel_token token);
    /* awaitable */ close();

    tls::tls_context& tls_context() noexcept;
    client_config& config() noexcept;
    const client_config& config() const noexcept;
};
```

The client tracks `Last-Event-ID`, applies configured event-buffer limits, and
uses `client_config::auto_reconnect` / `max_reconnect_attempts` for
receive-driven reconnect behavior after an established stream fails while not
closed. Initial `connect()` failures are single attempts; callers own retry and
background reconnect policy for initial connection establishment.

`connect()` succeeds on valid final `200` / `text/event-stream` headers; it
does not wait for the complete body. `receive()` incrementally consumes HTTP
body slices, removing chunk framing and honoring Content-Length. It never
interprets bytes beyond the declared body as events. `max_informational_responses`
caps preceding non-101 interim responses at 16 by default; zero disallows them,
and exceeding the cap fails connection setup with `EMSGSIZE`. Each message
still has the configured metadata limits, and the absolute header deadline
covers the entire interim sequence. With automatic reconnect disabled, normal
HTTP body completion returns `std::nullopt` with `errno = 0`; malformed or
truncated framing returns `EBADMSG`. Events already delivered are not retracted.
The per-`receive()` token remains effective through receive-driven reconnect
backoff and connection/header setup, alongside the original connection token.
It does not replace or permanently cancel that original token.

### `sse::sse_connect`

```cpp
/* awaitable */ sse_connect(std::string_view url,
                            client_config config = {});
/* awaitable */ sse_connect(std::string_view url,
                            coro::cancel_token token,
                            client_config config = {});
```

Returns an optional connected `sse_client`.

---

## HTTP/2 (`elio::http`)

HTTP/2 support requires linking with `elio_http2`.

### `h2_client`

HTTP/2 client with sequential pooled connection reuse. The underlying session
layer supports HTTP/2 streams, but the current high-level client does not
coordinate multiple in-flight requests over one shared connection.

```cpp
class h2_client {
public:
    h2_client();
    explicit h2_client(h2_client_config config);

    // GET request (awaitable)
    coro::task<std::optional<response>> get(std::string_view url);

    // POST request (awaitable)
    coro::task<std::optional<response>> post(
        std::string_view url,
        std::string_view body,
        std::string_view content_type = mime::application_form_urlencoded
    );

    // PUT request (awaitable)
    coro::task<std::optional<response>> put(
        std::string_view url,
        std::string_view body,
        std::string_view content_type = mime::application_json
    );

    // DELETE request (awaitable)
    coro::task<std::optional<response>> del(std::string_view url);

    // PATCH request (awaitable)
    coro::task<std::optional<response>> patch(
        std::string_view url,
        std::string_view body,
        std::string_view content_type = mime::application_json
    );

    // Send custom request (awaitable)
    coro::task<std::optional<response>> send(
        method m,
        const url& target,
        std::string_view body = {},
        std::string_view content_type = {}
    );

    // Access TLS context and client configuration
    tls::tls_context& tls_context() noexcept;
    h2_client_config& config() noexcept;
    const h2_client_config& config() const noexcept;
};

// Convenience function for one-off HTTP/2 GET
coro::task<std::optional<response>> h2_get(std::string_view url);

// Convenience function for one-off HTTP/2 POST
coro::task<std::optional<response>> h2_post(
    std::string_view url,
    std::string_view body,
    std::string_view content_type = mime::application_form_urlencoded
);
```

`h2_client::send()` accepts ordinary request methods for HTTPS targets. HTTP/2
`CONNECT` is not implemented by the high-level client; passing
`method::CONNECT` fails before opening a connection, sets `errno` to
`EOPNOTSUPP`, and returns `std::nullopt`.

### `h2_client_config`

```cpp
struct h2_client_config {
    std::chrono::seconds connect_timeout{10};  // TCP connect + TLS handshake timeout
    std::chrono::seconds read_timeout{30};     // Session I/O timeout; <=0 disables
    size_t max_concurrent_streams = 100;
    uint32_t initial_window_size = 65535;
    size_t max_response_size = 16 * 1024 * 1024;  // Max buffered body bytes
    std::string user_agent = "elio-http2/1.0";
    bool enable_push = false;  // Advertise SETTINGS_ENABLE_PUSH only;
                               // pushed responses are not exposed
    net::resolve_options resolve_options = net::default_cached_resolve_options();
    bool rotate_resolved_addresses = true;
    size_t max_response_headers = 100;             // Max accepted field lines
    size_t max_response_header_bytes = 64 * 1024; // Max accepted name/value bytes
    std::chrono::nanoseconds dns_timeout{0};     // Independent DNS observer budget
    std::shared_ptr<net::resolve_domain> dns_domain;
};
```

The two response-header limits apply per stream to regular field lines. The
byte limit is the sum of accepted field-name and field-value lengths. Final
headers and trailers share the budget; discarded informational blocks do not.
A limit breach resets only the offending stream with
`NGHTTP2_ENHANCE_YOUR_CALM` and the request fails with `errno == EMSGSIZE`.

### `h2_session`

Low-level HTTP/2 session (for advanced use).

`h2_session_config` exposes the same `max_response_headers` and
`max_response_header_bytes` defaults for direct session users.

```cpp
class h2_session {
public:
    explicit h2_session(tls::tls_stream& stream,
                        h2_session_config config = {});
    
    // Submit a request, returns stream ID
    int32_t submit_request(method m, const url& target,
                           std::string_view body = {},
                           std::string_view content_type = {});
    
    // Process session I/O (awaitable)
    /* awaitable */ process();
    
    // Wait for stream to complete (awaitable)
    /* awaitable */ wait_for_stream(int32_t stream_id);
    
    // Check if session is alive
    bool is_alive() const;
    
    // Graceful shutdown (awaitable)
    /* awaitable */ shutdown();
};
```

`submit_request()` validates HTTPS targets, request-target bytes, authority
bytes, generated header values, and rejects `method::CONNECT` before submitting
to nghttp2. Validation failures return a negative errno-style value and set
`errno`; unsupported `CONNECT` requests return `-EOPNOTSUPP`.

---

## TLS (`elio::tls`)

### `tls_context`

TLS configuration context.

```cpp
enum class tls_version {
    tls_1_2,
    tls_1_3,
    tls_1_2_or_higher,
    tls_1_3_only
};

enum class tls_mode {
    client,
    server
};

enum class verify_mode {
    none,
    peer,
    fail_if_no_cert
};

class tls_context {
public:
    explicit tls_context(tls_mode mode, tls_version version = tls_version::tls_1_2_or_higher);
    
    // Load certificate, key, and trust material
    bool load_certificate(std::string_view cert_file);
    bool load_private_key(std::string_view key_file,
                          std::string_view password = "");
    bool load_verify_locations(std::string_view ca_file = "",
                               std::string_view ca_path = "");
    bool use_default_verify_paths();
    
    // Certificate verification
    void set_verify_mode(verify_mode mode);
    
    // ALPN and cipher configuration
    bool set_alpn_protocols(std::string_view protocols);
    bool set_ciphers(std::string_view ciphers);
    bool set_ciphersuites(std::string_view ciphersuites);

    SSL_CTX* native_handle() noexcept;
    const SSL_CTX* native_handle() const noexcept;
    tls_mode mode() const noexcept;

    static tls_context make_client();
    static tls_context make_server(std::string_view cert_file,
                                   std::string_view key_file);
};
```

### `basic_tls_stream` and `tls_stream`

TLS wrapper over a move-owned asynchronous byte stream. The existing
`tls_stream` name remains the concrete TCP facade:

```cpp
template<typename Lower>
class basic_tls_stream;

class tls_stream : public basic_tls_stream<net::tcp_stream> {
public:
    using basic_tls_stream<net::tcp_stream>::basic_tls_stream;
};
```

After the TLS handshake completes, TLS streams serialize OpenSSL dispatch and
retry ownership internally. One read-side operation and one write-side operation
may overlap while either side is suspended on lower-layer progress.
Callers must still serialize handshake-starting operations, multiple concurrent
reads, multiple concurrent writes, and shutdown/destruction against active I/O
at the protocol layer.

```cpp
struct tls_stream_options {
    size_t ciphertext_budget = 1024 * 1024;
    std::chrono::milliseconds session_close_timeout{5000};
};

template<typename Lower = net::tcp_stream>
class basic_tls_stream {
public:
    basic_tls_stream(Lower lower, tls_context& ctx, tls_stream_options options = {});
    
    // Select DNS/SNI or an unbracketed numeric IP SAN reference
    void set_hostname(std::string_view hostname);
    
    // Perform TLS handshake (awaitable)
    /* awaitable */ handshake();
    /* awaitable */ handshake(coro::cancel_token token);

    // Whole-session close budget; return may take longer for I/O cleanup.
    coro::task<void> shutdown(std::chrono::milliseconds timeout =
                                 std::chrono::milliseconds(5000));

    // Write-side operation; may overlap one reader after handshake.
    coro::task<net::write_finish_result> finish_write(
        coro::cancel_token token = {},
        std::chrono::milliseconds timeout = std::chrono::milliseconds(5000));
    
    // Read decrypted data (awaitable)
    /* awaitable */ read(void* buffer, size_t size);
    /* awaitable */ read(void* buffer, size_t size, coro::cancel_token token);
    
    // Write data to encrypt (awaitable)
    /* awaitable */ write(const void* data, size_t size);
    /* awaitable */ write(const void* data, size_t size, coro::cancel_token token);
    /* awaitable */ write(std::string_view data);
    /* awaitable */ write(std::string_view data, coro::cancel_token token);

    // Exact-length helpers (awaitable)
    /* awaitable */ read_exactly(void* buffer, size_t size);
    /* awaitable */ read_exactly(void* buffer, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ read_exactly(std::span<T> buffer);
    template<typename T>
    /* awaitable */ read_exactly(std::span<T> buffer, coro::cancel_token token);
    /* awaitable */ write_exactly(const void* data, size_t size);
    /* awaitable */ write_exactly(const void* data, size_t size, coro::cancel_token token);
    template<typename T>
    /* awaitable */ write_exactly(std::span<const T> buffer);
    template<typename T>
    /* awaitable */ write_exactly(std::span<const T> buffer, coro::cancel_token token);
    /* awaitable */ write_exactly(std::string_view data);
    /* awaitable */ write_exactly(std::string_view data, coro::cancel_token token);
    
    // Get negotiated ALPN protocol
    std::string_view alpn_protocol() const;
    const char* version() const;
    const char* cipher() const;

    int fd() const noexcept;
    const net::tcp_stream& tcp() const noexcept; // TCP facade only
    bool is_handshake_complete() const noexcept;

    // Watchdog helpers for externally interrupted sockets
    void mark_externally_shut_down() noexcept;
    void shutdown_socket() noexcept;

    X509* peer_certificate() const;
    long verify_result() const;
};
```

`Lower` is move-owned by the TLS stream. Apart from the TCP facade,
`basic_tls_stream<Lower>` requires `Lower` to satisfy
`net::publishing_byte_stream`: it must explicitly opt in with
`publishing_byte_stream_contract`, provide cancellable asynchronous `read()` and
`write()`, report EOF scope, support protocol finish, and provide
`abort_and_settle()` for whole-chain abort. The borrowed buffer lifetime rule is
the same as other Elio byte streams: the buffer remains live until the awaited
operation returns. A lower stream may optionally expose `shutdown_socket()` for
synchronous abort propagation and `fd()` for diagnostics. Exposing `fd()` does
not authorize TLS to bypass that lower protocol. The raw descriptor output fast
path is used only by the TCP facade; generic and nested streams publish
ciphertext by awaiting the lower stream's `write()`.

A lower stream may also expose
`static constexpr bool tls_progress_interrupts_read = true` when canceling an
in-flight lower `read()` is nonterminal. TLS uses that opt-in to interrupt a
parked lower read after sibling TLS progress so the logical reader can retry
OpenSSL state. Omit the hook, or leave it `false`, when read cancellation closes,
poisons, or otherwise aborts the lower protocol. TLS treats its own
progress-cancelled `-ECANCELED` result as a retry signal; genuine lower errors
such as `-ECONNRESET` remain terminal.

Generic TLS layers keep independent `tls_context`, SNI, certificate
verification, ALPN, session state and close semantics. A TLS-over-TLS stack is
therefore just `basic_tls_stream<tls_stream>` (or another conforming lower
stream), not a special double-TLS type. Finish and shutdown apply to the current
TLS layer; callers decide when lower layers are finished or aborted.

`set_hostname()` selects DNS certificate matching and SNI for names, or
IP-address SAN matching without SNI for numeric IPv4/IPv6 references. It replaces
the previous reference, including the opposite identity type. Numeric DNS SANs
do not substitute for IP SANs.
IPv6 `%zone` suffixes select local socket scope and are excluded from the
certificate identity and SNI. The resolver/caller owns interface selection and
zone validity; an empty zone is rejected. This is not URI decoding.
Empty input retains explicit reference clearing;
that leaves trust-chain verification, not endpoint-name authentication. Embedded
NUL or failed native identity setup throws and makes the session terminal.
Configure a reference before the handshake and serialize it with public stream
operations. Callers supply IDNA ASCII names and their chosen verification/trust
policy; this setter does not decode URI escapes.

`tls_stream::read_exactly()` reports EOF before the requested byte count as
`io_result::result == -ENODATA`, matching the TCP and UDS exact-length helpers.
Success reports the full requested count.

Low-level `write()` can return positive short progress, at most 16 KiB per
call. `writev()` applies this to its first nonempty slice. Use `write_exactly()`
or explicitly advance after short progress; HTTP `body_writer` already manages
this internally. Keep plaintext buffers valid through the awaited operation.

For the TCP facade, ciphertext may go directly to the nonblocking socket when
there is no queued prefix. Generic lower streams always route ciphertext through
their `write()` operation, so an inner TLS layer, tunnel or buffered channel is
not bypassed even if it exposes a descriptor. Backpressure retains only the
unsent ciphertext in an owned output BIO; an internal pump drains it without
accessing SSL or caller plaintext. There is no application-body aggregation or
background plaintext queue. A successful read does not wait for unrelated
outgoing ciphertext. Handshake success means local TLS establishment, not peer
receipt: final handshake/control records may still be owned by that output pump.

`ciphertext_budget` limits retained output-BIO payload allocations, defaults to
1 MiB, and is allocated on demand. A partially consumed block and an in-flight
drain lease retain their full payload allocation charge until the block is
freed. Queue metadata, OpenSSL storage, kernel buffers and caller buffers are
outside this limit. It is neither a total-memory bound nor a system-wide
zero-copy claim. Capacity exhaustion is terminal `ENOBUFS`, allocation failure
is terminal `ENOMEM`, and the first transport error stays sticky. An operation
ending in transport failure cancels owned output work and awaits its I/O-lease
cleanup before returning; bytes already sent cannot be rolled back.

`shutdown()` sends `close_notify` and waits for the peer's `close_notify` under
one whole-session budget, default 5 seconds, separate from application I/O
budgets. Failure or expiry starts abort processing and drains owned I/O before
returning, so cleanup can extend beyond that budget. The legacy `task<void>`
result does not establish lossless peer delivery. This is not a directional
half-close API; use `finish_write()` for protocol-aware output completion.
The HTTP CONNECT handoff is a separate feature, not supplied by TLS closure.
Whole-session shutdown retires the transport; this object has no TLS-session
reset or re-handshake API. Terminal output settlement uses three pre-reserved
notification slots for the permitted reader, writer and concurrent abort, without allocating
new cleanup waiters.

`finish_write()` requires a completed handshake. It leaves
`is_handshake_complete()` as handshake history, not a test for a usable write
direction. Nonempty writes after normal output closure return `ESHUTDOWN`
without changing a successful close into a transport failure. TLS 1.2 closure
also ends application reads: remaining reverse plaintext is discarded while
processing the peer's alert under the same absolute deadline. The small discard
scratch is not an application queue or a lossless forwarding guarantee.
An unfinished SSL write retry prevents graceful TLS 1.2 closure and produces
terminal `ECANCELED`, never an SSL call with substituted retry arguments.
Repeated finish calls report current sticky failure and closure observations;
they neither reopen output nor restart an existing session deadline.

TLS 1.2 automatic closure uses `session_close_timeout` when a read first
observes the authenticated peer alert. Explicit finish uses its timeout if it
selects session closure first. TLS 1.3 ignores both session-close timers during
independent write closure and keeps reverse reads available.

Cancellation detected by the operation's initial cancellation check is local
to that call. After it passes that check, subsequently observed cancellation
terminates the whole connection with sticky `ECANCELED`, including an overlapping
sibling with a different token. Await both operations; do not retry on that
connection. A completion that wins the race may still succeed, and cancellation
cannot roll back transmitted bytes. The exact helpers also check cancellation
between completed slices; cancellation at that boundary has no unfinished SSL
operation and does not itself abort the stream.

Moved-from TCP-facade streams support destruction, reassignment, `fd()`/`tcp()`
queries (descriptor -1), `is_handshake_complete()` (false), and inert
`shutdown()` / `shutdown_socket()`. Generic specializations support the same
inert lifetime operations except for `tcp()`, which is available only on the
TCP facade. Other operations require a live, unmoved stream.

Callers must serialize shutdown/destruction against public reads/writes, request
cancellation where needed, and await those operations before releasing stream
or plaintext storage. Destruction aborts the owned ciphertext pump; it does not
asynchronously finish normal shutdown or authorize forced coroutine-frame
destruction. Internal transport ownership retains the physical descriptor
through outstanding I/O cleanup on both backends.
`shutdown_socket()` and `mark_externally_shut_down()` are
watchdog-oriented
helpers for code that has already interrupted the underlying TCP socket and
needs the stream to skip a later `SSL_shutdown()` write.

`peer_certificate()` returns a caller-owned `X509*` when a peer certificate is
available; callers must release each non-null result with `X509_free()` when
done.

### `tls_connect()`

```cpp
coro::task<std::optional<tls_stream>>
tls_connect(tls_context& ctx,
            std::string_view host,
            uint16_t port,
            net::resolve_options resolve_opts =
                net::default_cached_resolve_options());
```

`tls_connect()` resolves the host, connects TCP, selects the DNS/IP reference
from `host` (SNI for DNS names only), and
performs the TLS handshake. It returns `std::optional<tls_stream>`; an empty
optional means resolution, TCP connect, or TLS handshake failed.

### `tls_listener`

```cpp
class tls_listener {
public:
    tls_listener(net::tcp_listener tcp, tls_context& ctx);

    // Accept TCP and complete the server-side TLS handshake
    coro::task<std::optional<tls_stream>> accept();

    int fd() const noexcept;

    static std::optional<tls_listener>
    bind(const net::ipv4_address& addr, tls_context& ctx);
    static std::optional<tls_listener>
    bind(const net::ipv6_address& addr, tls_context& ctx);
    static std::optional<tls_listener>
    bind(const net::socket_address& addr, tls_context& ctx);
};
```

`tls_listener` keeps a pointer to the supplied `tls_context`; callers must keep
that context alive while accepts are pending and while accepted streams use it.

---

## Synchronization (`elio::sync`)

### Cancellation Safety

Coroutine-aware synchronization primitives (`mutex`, `shared_mutex`, `event`, `semaphore`, `condition_variable`, `channel`) track suspended waiters through intrusive nodes embedded in coroutine frames. If a frame is destroyed while its waiter is still linked, the awaiter's destructor unlinks the node from the primitive.

This cleanup does not make every operation cancellable. `with_timeout()`
requests cooperative cancellation but does not forcibly destroy its losing
child. It joins the child before returning, so the child must pass the supplied
`cancel_token` or `this_coro::cancel_token()` to a token-aware operation to stop
promptly. Every suspending core synchronization primitive provides an explicit
token-aware wait. Their no-token overloads remain non-cancellable and preserve
their existing await results.

Cancellation and normal notification atomically select one terminal result. A cancellation winner does not acquire a lock or permit, transfer a pending send value into a channel, or consume a channel receive value. Once normal notification wins, the operation returns `completed` and any acquired resource or completed transfer remains caller-owned. A condition wait that released an associated lock re-acquires it before returning either result. Channel result objects carry both `cancel_result` and the existing sent/value result so cancellation remains distinct from closure.

Callers must inspect the `cancel_result` from every token-aware wait before assuming that notification occurred, a lock or permit was acquired, or a channel operation observed closure rather than cancellation.

### `mutex`

Coroutine-aware mutex.

```cpp
class mutex {
public:
    mutex();
    
    // Acquire lock (awaitable)
    /* awaitable */ lock();

    // Acquire or return cancel_result::cancelled
    /* awaitable<cancel_result> */ lock(coro::cancel_token token);
    
    // Try to acquire without waiting
    bool try_lock();
    
    // Release lock
    void unlock();
};
```

The no-token `lock()` completes without allocation when the mutex is
uncontended, including when an unlock wins the race between `await_ready()` and
`await_suspend()`. A wait that remains contended creates independently owned
wake state before entering the waiter-queue critical section, so
`await_suspend()` may propagate `std::bad_alloc` without changing lock or queue
state. Token-aware waits create their arbitration state eagerly so cancellation
can race ownership transfer with exactly one terminal result.

### `shared_mutex`

Coroutine-aware read-write lock. Allows multiple concurrent readers or a single exclusive writer.

```cpp
class shared_mutex {
public:
    shared_mutex();
    
    // Acquire shared (read) lock (awaitable)
    /* awaitable */ lock_shared();

    // Acquire shared lock or return cancel_result::cancelled
    /* awaitable<cancel_result> */ lock_shared(coro::cancel_token token);
    
    // Acquire exclusive (write) lock (awaitable)
    /* awaitable */ lock();

    // Acquire exclusive lock or return cancel_result::cancelled
    /* awaitable<cancel_result> */ lock(coro::cancel_token token);
    
    // Try to acquire shared lock without waiting
    bool try_lock_shared();
    
    // Try to acquire exclusive lock without waiting
    bool try_lock();
    
    // Release shared lock
    void unlock_shared();
    
    // Release exclusive lock
    void unlock();
    
    // Get current reader count
    size_t reader_count() const;
    
    // Check if a writer holds the lock
    bool is_writer_active() const;
};
```

The packed mutex state reserves 62 bits for the number of outstanding shared
acquisitions. Callers must keep that number below `(1ULL << 62) - 1` before a
non-try shared acquisition attempt and must balance every successful shared
acquisition with exactly one `unlock_shared()`. Exceeding the representation
limit is outside the supported contract. `try_lock_shared()` instead returns
`false` when another shared acquisition cannot be represented. The limit counts
outstanding acquisitions, not coroutine frames or distinct reader coroutines.

When the current reader count is below `READER_MASK`, a reader that reaches the
locked admission recheck retries concurrent packed-state changes before
deciding to park. If a writer becomes active or waiting during that retry, the
reader parks behind the writer instead of bypassing writer preference.

The no-token `lock_shared()` path creates no wake state when either its initial
ready check or its suspension-entry lock-free retry admits the reader. Once it
still observes writer preference, it creates independently owned wake state
before taking the waiter-queue mutex; allocation failure can therefore
propagate from `await_suspend()` without publishing or granting the reader. The
representation-limit fallback follows the same internal allocation boundary;
the shared-acquisition precondition above is unchanged. Token-aware readers
retain eager cancellation arbitration state.

The no-token `lock()` path likewise creates no wake state for a ready writer.
After a failed ready check, suspension entry creates independently owned wake
state before taking the waiter-queue mutex and before publishing
`WRITER_WAITING`, changing pending-writer accounting, or publishing a queue
node. Its `await_suspend()` may therefore propagate `std::bad_alloc` with no
exclusive-lock state change. The existing locked writer admission and
preference protocol is unchanged after allocation. Token-aware writers retain
eager cancellation arbitration state.

### `shared_lock_guard`

RAII unlock guard for an already-held shared (reader) lock. Callers must
`co_await lock_shared()` before constructing the guard.

```cpp
class shared_lock_guard {
public:
    explicit shared_lock_guard(shared_mutex& m);
    ~shared_lock_guard();  // Calls unlock_shared()
    
    void unlock();  // Manual early unlock
};
```

### `unique_lock_guard`

RAII unlock guard for an already-held exclusive (writer) lock. Callers must
`co_await lock()` before constructing the guard.

```cpp
class unique_lock_guard {
public:
    explicit unique_lock_guard(shared_mutex& m);
    ~unique_lock_guard();  // Calls unlock()
    
    void unlock();  // Manual early unlock
};
```

### `spinlock`

Lightweight spinlock using TTAS (Test-and-Test-and-Set) algorithm. Suitable for short critical sections with low contention where the overhead of coroutine suspension would exceed the spin time.

```cpp
class spinlock {
public:
    spinlock();

    // Acquire the lock (spins until acquired)
    void lock() noexcept;

    // Try to acquire without spinning
    bool try_lock() noexcept;

    // Release the lock
    void unlock() noexcept;

    // Check if locked (debugging only)
    bool is_locked() const noexcept;
};
```

### `spinlock_guard`

RAII guard for spinlock. Movable, non-copyable.

```cpp
class spinlock_guard {
public:
    explicit spinlock_guard(spinlock& s);  // Locks on construction
    ~spinlock_guard();                      // Unlocks on destruction

    spinlock_guard(spinlock_guard&& other) noexcept;
    spinlock_guard& operator=(spinlock_guard&& other) noexcept;

    void unlock();  // Manual early unlock (safe to call multiple times)
};
```

### `condition_variable`

Coroutine-aware condition variable whose wait phase suspends the coroutine
instead of blocking the thread. Generic-lock re-acquisition is synchronous as
described below.

Supports three modes of use:
- With `elio::sync::mutex` (coroutine-aware async re-lock)
- With a short-duration synchronous lockable such as `elio::sync::spinlock`
  (direct re-lock on the resuming thread)
- Without any lock (`wait_unlocked()`) for single-worker scenarios

```cpp
class condition_variable {
public:
    condition_variable();

    /// Wait with elio::sync::mutex (single co_await)
    coro::task<void> wait(mutex& m);

    // Cancellation-aware wait; re-acquires m if the wait released it
    coro::task<coro::cancel_result> wait(mutex& m, coro::cancel_token token);

    // Wait with a short-duration synchronous lockable (e.g., spinlock)
    // Calls Lock::lock() synchronously in await_resume()
    template<lockable Lock>
    /* awaitable */ wait(Lock& lock);

    // The token overload uses the same synchronous re-lock path
    template<lockable Lock>
    /* awaitable<cancel_result> */ wait(Lock& lock, coro::cancel_token token);

    // Wait without external lock (single-worker-thread only)
    /* awaitable */ wait_unlocked();

    /* awaitable<cancel_result> */ wait_unlocked(coro::cancel_token token);

    // Wake one waiting coroutine
    void notify_one();

    // Wake all waiting coroutines
    void notify_all();

    // Check if there are waiting coroutines
    bool has_waiters() const noexcept;
};
```

The generic `wait(Lock&)` overloads are selected by a syntactic concept that
requires `lock()` and `unlock()`; satisfying that concept does not make the lock
coroutine-aware. After notification, or after cancellation if the wait released
the lock, `await_resume()` calls `Lock::lock()` directly on the resuming thread.
The token overload returns `cancel_result` and atomically selects notification
or cancellation. A pre-cancelled wait keeps the already-held lock; once a wait
has released the lock, it synchronously re-acquires it before returning either
`completed` or `cancelled`.
`Lock::unlock()` must release immediately, and `Lock::lock()` must have acquired
ownership when it returns; an awaitable-returning `lock()` is not supported by
the generic overload. The caller must also guarantee that `lock()` returns
promptly without causing a scheduler-significant or unbounded synchronous wait.
A contended `std::mutex` satisfies the concept but can park and stall the worker
and is not suitable for this overload. A `sync::spinlock` is suitable only when
the critical section is very short and contention is rare. Use the dedicated
`wait(sync::mutex&)` overload when re-locking may need to wait; it suspends the
coroutine while asynchronously re-acquiring the mutex.

**Usage with mutex (single co_await):**
```cpp
sync::mutex mtx;
sync::condition_variable cv;
bool ready = false;

coro::task<void> waiter() {
    co_await mtx.lock();
    while (!ready) {
        co_await cv.wait(mtx);  // single co_await
    }
    mtx.unlock();
}

coro::task<void> notifier() {
    co_await mtx.lock();
    ready = true;
    mtx.unlock();
    cv.notify_one();
}
```

**Usage with spinlock (single co_await):**
```cpp
sync::spinlock sl;
sync::condition_variable cv;
bool ready = false;

coro::task<void> waiter() {
    sl.lock();
    while (!ready) {
        // Generic wait re-locks synchronously on this worker. Keep the
        // critical section very short and contention rare.
        co_await cv.wait(sl);
    }
    sl.unlock();
}
```

### `event`

Manual-reset signaling primitive. One or more coroutines wait for the event to
be set; subsequent waits complete until `reset()` clears it.

```cpp
class event {
public:
    event();

    // Wait for the event to be set (awaitable)
    /* awaitable */ wait();

    // Wait or return cancel_result::cancelled
    /* awaitable<cancel_result> */ wait(coro::cancel_token token);

    // Set the event (wakes all waiters)
    void set();

    // Check if the event is set
    bool is_set() const noexcept;

    // Reset the event
    void reset();
};
```

The no-token `wait()` completes without allocation when the event is already
set. If it reaches the unset slow path, `await_suspend()` creates independently
owned wake state and may propagate `std::bad_alloc`; that state keeps a dequeued
wake safe if the coroutine frame is destroyed before scheduling. Token-aware
waits create their arbitration state eagerly so cancellation can race `set()`
with exactly one terminal result.

`set()` prepares dispatch storage before changing the signal or selecting
pending waiters. Storage preparation can throw, for example `std::bad_alloc`;
the prior signal state and pending waits remain unchanged, so callers can retry
or cancel token-aware waits. Successful signaling dispatches outside the event
mutex. Keep the event, scheduler, and waiter frames alive until pending
operations normally complete; signaling failure does not authorize frame
destruction.

### `channel<T>`

Multi-producer multi-consumer channel for passing values between coroutines. Supports rendezvous (synchronous), bounded, and unbounded modes.

```cpp
template<typename T>
class channel {
public:
    struct cancellable_send_result {
        bool sent;
        coro::cancel_result cancel;

        bool success() const noexcept;
        bool was_cancelled() const noexcept;
        bool was_closed() const noexcept;
    };

    struct cancellable_recv_result {
        std::optional<T> value;
        coro::cancel_result cancel;

        bool success() const noexcept;
        bool was_cancelled() const noexcept;
        bool was_closed() const noexcept;
    };

    // Create a rendezvous channel (default, capacity 0)
    channel();

    // Create a bounded channel with specified capacity
    explicit channel(size_t capacity);

    // Create an unbounded channel
    static channel unbounded();

    // Send a value (awaitable, blocks if full for bounded channels)
    /* awaitable */ send(T value);

    // Send, report cancellation separately from channel closure
    /* awaitable<cancellable_send_result> */
    send(T value, coro::cancel_token token);

    // Try to send without waiting
    bool try_send(T value);

    // Receive a value (awaitable, blocks if empty)
    /* awaitable<std::optional<T>> */ recv();

    // Receive, report cancellation separately from channel closure
    /* awaitable<cancellable_recv_result> */
    recv(coro::cancel_token token);

    // Try to receive without waiting
    std::optional<T> try_recv();

    // Close the channel; repeated calls are no-ops
    void close();

    // Check if closed
    bool is_closed() const noexcept;

    // Observe the number of buffered values
    size_t size() const noexcept;

    // Observe whether no values are buffered
    bool empty() const noexcept;
};
```

`close()` is idempotent. Closing rejects later sends, wakes pending operations,
and preserves values already committed to the channel so receivers can drain
them before observing closure.

When no send, receive, or close operation is running concurrently, `size()` and
`empty()` report the channel's buffered receivable values, including values
preserved for draining after close. During concurrent operations, bounded
channels can update their lock-free ring independently of the channel mutex, so
these observers are approximate and may already be stale when they return. Use
them for diagnostics only, not as a synchronization predicate. Blocked sender
values that have not been committed to the channel are not buffered values.

Both `send` overloads take their payload by value, so the returned task owns it
in the coroutine frame until delivery, cancellation, closure, or task
destruction resolves the operation. The internal queued waiter borrows that
frame-owned object and transfers it only after normal completion wins. It does
not add a second `T` to the frame. This is an implementation detail of the task
wrappers: directly constructed `send_awaitable` and
`cancellable_send_awaitable` objects continue to own their payload and may
outlive the expression that supplied it.

### `semaphore`

Counting semaphore.

```cpp
class semaphore {
public:
    explicit semaphore(int initial_count = 0);

    // Acquire (awaitable)
    /* awaitable */ acquire();

    // Acquire or return cancel_result::cancelled
    /* awaitable<cancel_result> */ acquire(coro::cancel_token token);

    // Try acquire without waiting
    bool try_acquire() noexcept;

    // Release one or more permits
    void release(int count = 1);

    // Snapshot the currently available permit count
    int count() const noexcept;
};
```

`initial_count` must be non-negative, and `release(count)` requires `count` to
be positive. Callers must keep the sum of available permits and permits
reserved for not-yet-resumed waiter handoffs at or below `INT_MAX`. This
includes permits absent from `count()` while a selected waiter has not yet
resumed, because waiter destruction before resume can return that handoff to
the available count. These are caller preconditions, not runtime error-reporting
guarantees.
`count()` takes the semaphore's internal lock and returns an exact instantaneous
snapshot of the available permits; it excludes pending handoffs. Concurrent
acquisitions, releases, or handoff recovery can make that snapshot stale
immediately after it returns.

The no-token `acquire()` completes without wake-state allocation when a permit
is immediately available. If the ready check observes no permit, suspension
creates independently owned wake state before entering the semaphore queue
critical section. `await_suspend()` may therefore propagate `std::bad_alloc`,
but allocation failure does not consume a permit or publish a waiter. If a
permit released between `await_ready()` and `await_suspend()` remains
available, the locked recheck consumes it; that race can perform one unused
allocation without losing the permit. Token-aware acquires create arbitration
state eagerly so cancellation can race permit handoff with exactly one terminal
result.

---

## Timers (`elio::time`)

```cpp
// Sleep for duration
template<typename Rep, typename Period>
/* awaitable */ sleep_for(std::chrono::duration<Rep, Period> duration);

// Sleep for duration with cancellation support
// Returns coro::cancel_result::completed or coro::cancel_result::cancelled
template<typename Rep, typename Period>
/* awaitable<coro::cancel_result> */ sleep_for(std::chrono::duration<Rep, Period> duration,
                                               coro::cancel_token token);

// Sleep until time point
template<typename Clock, typename Duration>
/* awaitable */ sleep_until(std::chrono::time_point<Clock, Duration> tp);

// Yield execution to other coroutines
/* awaitable */ yield();
```

`sleep_for()` and `sleep_until()` normally use the current worker's I/O
backend. If timer preparation fails, they route the wait through the scheduler
blocking pool while preserving worker affinity. If that pool is unavailable,
the await continues on its current worker and throws `std::runtime_error`;
this rejection is not reported as token cancellation.

**Example:**
```cpp
coro::task<void> example(coro::cancel_token token) {
    // Simple sleep
    co_await time::sleep_for(100ms);
    
    // Cancellable sleep
    auto result = co_await time::sleep_for(5s, token);
    if (result == coro::cancel_result::cancelled) {
        // Cancelled early
    }
    
    // Yield to other coroutines
    co_await time::yield();
}
```

---

## Logging (`elio::log`)

### Macros

```cpp
ELIO_LOG_DEBUG(fmt, args...)
ELIO_LOG_INFO(fmt, args...)
ELIO_LOG_WARNING(fmt, args...)
ELIO_LOG_ERROR(fmt, args...)
```

### `logger`

```cpp
class logger {
public:
    static logger& instance();
    
    void set_level(level lvl);
    level get_level() const;
    
    template<typename... Args>
    void log(level lvl, const char* file, int line,
             fmt::format_string<Args...> fmt_str, Args&&... args);
};

enum class level {
    debug,
    info,
    warning,
    error
};
```

Ordinary callers should use the `ELIO_LOG_INFO` / `ELIO_LOG_WARNING` /
`ELIO_LOG_ERROR` macros (and `ELIO_LOG_DEBUG` when `ELIO_DEBUG` is defined)
from `elio/log/macros.hpp`; they supply `__FILE__` and `__LINE__`
automatically.

---

## Hash (`elio::hash`)

### CRC32

```cpp
// Compute CRC32 checksum
uint32_t crc32(const void* data, size_t length, uint32_t crc = 0xFFFFFFFF);
uint32_t crc32(std::span<const uint8_t> data, uint32_t crc = 0xFFFFFFFF);

// CRC32 over scatter-gather buffers
uint32_t crc32_iovec(const struct iovec* iov, size_t count);

// Incremental CRC32
uint32_t crc32_update(const void* data, size_t length, uint32_t crc);
uint32_t crc32_finalize(uint32_t crc);
```

### CRC32C

The header-only CRC32C entry points use translation-unit-local linkage so
sources compiled with different ISA flags keep independent dispatch paths.

```cpp
// Compute CRC32C (Castagnoli polynomial)
uint32_t crc32c(const void* data, size_t length, uint32_t crc = 0xFFFFFFFF);
uint32_t crc32c(std::span<const uint8_t> data, uint32_t crc = 0xFFFFFFFF);

// Check whether this translation unit has a compiled hardware CRC32C path
// supported by the current CPU
bool crc32c_hw_available() noexcept;
```

### SHA-1

```cpp
// Constants
constexpr size_t sha1_digest_size = 20;
constexpr size_t sha1_block_size = 64;

// Digest type
using sha1_digest = std::array<uint8_t, sha1_digest_size>;

// Compute SHA-1 hash
sha1_digest sha1(const void* data, size_t length);
sha1_digest sha1(std::span<const uint8_t> data);
sha1_digest sha1(std::string_view str);

// Get hex string
std::string sha1_hex(const sha1_digest& digest);
std::string sha1_hex(const void* data, size_t length);
std::string sha1_hex(std::string_view str);

// Incremental hashing
class sha1_context {
public:
    sha1_context() noexcept;
    void reset() noexcept;
    void update(const void* data, size_t length) noexcept;
    void update(std::span<const uint8_t> data) noexcept;
    void update(std::string_view str) noexcept;
    sha1_digest finalize() noexcept;
};
```

### SHA-256

```cpp
// Constants
constexpr size_t sha256_digest_size = 32;
constexpr size_t sha256_block_size = 64;

// Digest type
using sha256_digest = std::array<uint8_t, sha256_digest_size>;

// Compute SHA-256 hash
sha256_digest sha256(const void* data, size_t length);
sha256_digest sha256(std::span<const uint8_t> data);
sha256_digest sha256(std::string_view str);

// Get hex string
std::string sha256_hex(const sha256_digest& digest);
std::string sha256_hex(const void* data, size_t length);
std::string sha256_hex(std::string_view str);

// Incremental hashing
class sha256_context {
public:
    sha256_context() noexcept;
    void reset() noexcept;
    void update(const void* data, size_t length) noexcept;
    void update(std::span<const uint8_t> data) noexcept;
    void update(std::string_view str) noexcept;
    sha256_digest finalize() noexcept;
};
```

### Utilities

```cpp
// Convert digest to hex string
template<size_t N>
std::string to_hex(const std::array<uint8_t, N>& digest);

// Convert raw bytes to hex
std::string to_hex(const void* data, size_t length);
```

---

## RPC (`elio::rpc`)

### Buffer Types

#### `buffer_view`

Read-only view into serialized data.

```cpp
class buffer_view {
public:
    buffer_view(const void* data, size_t size);
    buffer_view(std::span<const uint8_t> span);
    
    const uint8_t* data() const noexcept;
    size_t size() const noexcept;
    size_t remaining() const noexcept;
    size_t position() const noexcept;
    
    void seek(size_t pos);
    void skip(size_t n);
    
    template<typename T> T read();           // Read primitive
    template<typename T> void read_into(T& value);
    template<typename T> T peek() const;     // Peek without advancing
    
    std::string_view read_string();          // Zero-copy string read
    std::span<const uint8_t> read_blob();    // Zero-copy blob read
    uint32_t read_array_size();
    
    std::span<const uint8_t> remaining_span() const noexcept;
};
```

#### `buffer_writer`

Growable buffer for serialization.

```cpp
class buffer_writer {
public:
    explicit buffer_writer(size_t initial_capacity = 256);
    
    void clear() noexcept;
    size_t size() const noexcept;
    const uint8_t* data() const noexcept;
    std::span<const uint8_t> span() const noexcept;
    struct iovec to_iovec() const noexcept;
    
    template<typename T> void write(T value);  // Write primitive
    void write_bytes(const void* src, size_t n);
    void write_string(std::string_view str);
    void write_blob(std::span<const uint8_t> blob);
    void write_array_size(uint32_t count);
    
    size_t reserve_space(size_t n);            // For back-patching
    template<typename T> void write_at(size_t offset, T value);
    
    buffer_view view() const noexcept;
    std::vector<uint8_t> release() noexcept;
};
```

#### `buffer_ref`

Non-owning reference to external buffer data. Deserialization can return a
`buffer_ref` view into the received payload without copying. Serialization of a
`buffer_ref` currently copies the referenced bytes into the outgoing
`buffer_writer`; true send-side zero-copy/iovec-tail support is not implemented.

```cpp
class buffer_ref {
public:
    buffer_ref() noexcept;
    buffer_ref(const void* data, size_t size) noexcept;
    buffer_ref(std::span<const uint8_t> span) noexcept;
    buffer_ref(const struct iovec& iov) noexcept;
    
    const uint8_t* data() const noexcept;
    size_t size() const noexcept;
    bool empty() const noexcept;
    
    std::span<const uint8_t> span() const noexcept;
    struct iovec to_iovec() const noexcept;
    std::string_view as_string_view() const noexcept;
};
```

#### `iovec_buffer`

Discontinuous buffer for scatter-gather I/O.

```cpp
class iovec_buffer {
public:
    void add(const void* data, size_t size);
    void add(std::span<const uint8_t> span);
    void add(const buffer_writer& writer);
    void clear() noexcept;
    
    struct iovec* iovecs() noexcept;
    size_t count() const noexcept;
    size_t total_size() const noexcept;
    
    std::vector<uint8_t> flatten() const;  // Copies all data
};
```

### CRC32 Checksum

RPC CRC32 checksums are non-cryptographic corruption checks. They are not
authentication, authorization, or tamper protection against adversarial peers.
Use TLS/mTLS or an application MAC/signature layer when the protocol needs a
security boundary.

```cpp
// Compute CRC32 checksum
uint32_t crc32(const void* data, size_t length, uint32_t crc = 0xFFFFFFFF);
uint32_t crc32(std::span<const uint8_t> data, uint32_t crc = 0xFFFFFFFF);
uint32_t crc32_iovec(const struct iovec* iov, size_t count);
```

### Serialization

```cpp
// Serialize value to buffer
template<typename T>
void serialize(buffer_writer& writer, const T& value);

// Deserialize value from buffer
template<typename T>
void deserialize(buffer_view& reader, T& value);

// Convenience functions
template<typename T>
buffer_writer serialize(const T& value);

template<typename T>
T deserialize(buffer_view& reader);
```

### Schema Definition Macros

```cpp
// Define serializable fields for a struct
ELIO_RPC_FIELDS(ClassName, field1, field2, ...)

// Define empty struct (no fields)
ELIO_RPC_EMPTY_FIELDS(ClassName)

// Define RPC method
ELIO_RPC_METHOD(method_id, RequestType, ResponseType)
```

### Protocol Types

#### `frame_header`

```cpp
constexpr uint8_t protocol_version = 1;
constexpr size_t frame_header_size = 19;

struct frame_header {
    uint32_t magic;           // 0x454C494F ("ELIO")
    uint32_t request_id;
    message_type type;
    message_flags flags;
    method_id_t method_id;
    uint32_t payload_length;
    uint8_t version;          // protocol_version
    
    bool is_valid() const noexcept;
    std::array<uint8_t, frame_header_size> to_bytes() const;
    static frame_header from_bytes(const uint8_t* data);
};
```

The fixed 19-byte wire header includes the final 1-byte `version` field.
Frames are valid only when `version == protocol_version`.

#### `message_type`

```cpp
enum class message_type : uint8_t {
    request = 0,
    response = 1,
    error = 2,
    ping = 3,
    pong = 4,
    cancel = 5,
};
```

#### `message_flags`

```cpp
enum class message_flags : uint8_t {
    none = 0,
    has_timeout = 1 << 0,
    has_checksum = 1 << 1,
    compressed = 1 << 2,    // reserved
    streaming = 1 << 3,     // reserved
    no_response = 1 << 4,   // one-way request: suppress response/error
};

bool has_flag(message_flags flags, message_flags flag);
```

#### `rpc_error`

```cpp
enum class rpc_error : uint32_t {
    success = 0,
    timeout = 1,
    connection_closed = 2,
    invalid_message = 3,
    method_not_found = 4,
    serialization_error = 5,
    internal_error = 6,
    cancelled = 7,
    resource_exhausted = 8,
};

const char* rpc_error_str(rpc_error err);
```

### Message Builders

```cpp
// Build request frame
template<typename Request>
std::pair<frame_header, buffer_writer> build_request(
    uint32_t request_id,
    method_id_t method_id,
    const Request& request,
    std::optional<uint32_t> timeout_ms = std::nullopt,
    bool enable_checksum = false);

// Build one-way request frame
template<typename Request>
std::pair<frame_header, buffer_writer> build_oneway_request(
    uint32_t request_id,
    method_id_t method_id,
    const Request& request,
    bool enable_checksum = false);

// Build response frame
template<typename Response>
std::pair<frame_header, buffer_writer> build_response(
    uint32_t request_id,
    const Response& response,
    bool enable_checksum = false);

// Build error response
std::pair<frame_header, buffer_writer> build_error_response(
    uint32_t request_id,
    rpc_error error_code,
    std::string_view error_message = "",
    bool enable_checksum = false);

// Build ping/pong/cancel
frame_header build_ping(uint32_t ping_id);
frame_header build_pong(uint32_t ping_id);
frame_header build_cancel(uint32_t request_id);
```

### Server Types

#### `rpc_context`

```cpp
struct rpc_context {
    uint32_t request_id;
    method_id_t method_id;
    std::optional<uint32_t> timeout_ms;
    coro::cancel_token cancel_token;
    
    bool has_timeout() const noexcept;
};
```

`cancel_token` is cancelled when the client sends an RPC cancel frame for this
request or when the session is closed. Cancellation is cooperative; handlers
that need to stop early should poll the token or pass it to cancellable Elio
operations.

#### `cleanup_callback_t`

```cpp
using cleanup_callback_t = std::function<void()>;
```

Cleanup callbacks returned by `register_method_with_cleanup()` and
`register_method_with_context_and_cleanup()` run only after the response has
been successfully sent. For `no_response` one-way requests, no response is sent;
the callback runs after the handler result has been serialized and the unsent
payload can be discarded. They are not failure-path finalizers: handler errors,
serialization errors, disconnects, write failures, and `send_response`
exceptions skip cleanup, so handlers must not rely on the callback for mandatory
local failure cleanup.

#### `rpc_server_config`

```cpp
enum class rpc_request_overload_policy {
    reject_request,
    close_session,
};
```

```cpp
struct rpc_server_config {
    size_t max_sessions = 1024;
    std::chrono::seconds frame_read_timeout{30};
    uint32_t max_message_size = elio::rpc::max_message_size;
    size_t max_in_flight_requests_per_session = 0;
    rpc_request_overload_policy request_overload_policy =
        rpc_request_overload_policy::reject_request;
};
```

- `max_sessions`: Maximum concurrent sessions accepted by `serve()`.
  `0` disables the cap.
- `frame_read_timeout`: Per-frame deadline for receiving the header,
  payload, and optional checksum. `0s` disables the deadline.
- `max_message_size`: Maximum payload bytes accepted per frame. The
  default is the protocol-wide 16 MiB limit.
- `max_in_flight_requests_per_session`: Maximum active request slots for one
  client session. A response-capable request holds its slot until its handler
  has produced a result and the response/error send path has completed or
  failed; a `no_response` request holds its slot until its handler finishes.
  `0` preserves legacy unlimited concurrency.
- `request_overload_policy`: Strategy after the per-session in-flight cap is
  reached. `reject_request` sends `rpc_error::resource_exhausted` for a
  response-capable excess request when no previous overload rejection is still
  being written, and drops over-limit `no_response` requests. If the peer is not
  draining responses and an overload rejection is already in flight, additional
  excess requests may also be dropped; a waiting client call for such a dropped
  request completes only through its own timeout or connection close.
  `close_session` closes the session.
  Accepted `no_response` requests still count against the cap until their
  handlers finish. Duplicate active request IDs close the session and do not
  consume capacity.

Server pong writes are bounded to one in-flight pong per session. If a peer
sends more pings while a previous pong is still being written, later pings may
not receive a pong; clients should rely on their own ping timeout and connection
policy.

Every session owns accepted request handlers, pong writes, and overload
responses through one scheduler-bound task scope. When the session closes or
the task awaiting `handle_client()` is cancelled, the server wakes pending
frame reads, requests the explicit `rpc_context::cancel_token` and the handler's
runtime `coro::this_coro::cancel_token()`, cancels pending frame writes and
response-lock waits, and joins all accepted children before `handle_client()`
returns or the session slot is released. Cancellation is cooperative: handlers
must pass one of these tokens to waits that should stop, and code that ignores
both tokens can delay session teardown. This structured ownership does not
change request admission or overload policy. Session tracking and slot state are
shared with draining sessions. Keep the server facade alive until active
`serve()` and `handle_client()` calls return; after a stopped `serve()` call has
returned, the facade may be released before cooperative handler drain completes.

#### `rpc_server<Stream>`

```cpp
template<typename Stream>
class rpc_server {
public:
    rpc_server() = default;
    explicit rpc_server(rpc_server_config config);

    const rpc_server_config& config() const noexcept;

    // Register async handler
    template<typename Method, typename Handler>
    void register_method(Handler handler);
    
    // Register async handler with context
    template<typename Method, typename Handler>
    void register_method_with_context(Handler handler);
    
    // Register sync handler
    template<typename Method, typename Handler>
    void register_sync_method(Handler handler);
    
    // Register handler with cleanup callback
    template<typename Method, typename Handler>
    void register_method_with_cleanup(Handler handler);
    
    // Register handler with context and cleanup
    template<typename Method, typename Handler>
    void register_method_with_context_and_cleanup(Handler handler);
    
    // Serve connections (awaitable)
    /* awaitable */ serve(net::tcp_listener& listener);
    /* awaitable */ serve(net::uds_listener& listener);
    
    // Handle single client
    /* awaitable */ handle_client(Stream stream);
    
    void stop();
    bool is_running() const noexcept;
    size_t session_count() const;
};

// Type aliases
using tcp_rpc_server = rpc_server<net::tcp_stream>;
using uds_rpc_server = rpc_server<net::uds_stream>;
```

### Client Types

#### `rpc_client_config`

```cpp
struct rpc_client_config {
    std::chrono::seconds frame_read_timeout{30};
    uint32_t max_message_size = elio::rpc::max_message_size;
};
```

- `frame_read_timeout`: Inactivity deadline for each client receive-loop frame
  read. The timer starts while waiting for the next frame header and continues
  until the complete response/control frame, including payload and optional
  checksum, is read. Expiry closes the client connection and completes pending
  calls as `rpc_error::connection_closed`. `0s` disables the deadline; use a
  larger value or `0s` for long-lived idle clients or calls whose server may be
  silent longer than the default.
- `max_message_size`: Maximum payload bytes accepted per frame. The default is
  the protocol-wide 16 MiB limit.

#### `rpc_client<Stream>`

```cpp
template<typename Stream>
class rpc_client {
public:
    using ptr = std::shared_ptr<rpc_client>;

    static std::shared_ptr<rpc_client> create(
        Stream stream,
        rpc_client_config config = {});

    template<typename... Args>
    static coro::task<std::optional<std::shared_ptr<rpc_client>>>
        connect(Args&&... args);

    template<typename... Args>
    static coro::task<std::optional<std::shared_ptr<rpc_client>>>
        connect_with_config(rpc_client_config config, Args&&... args);

    bool is_connected() const noexcept;
    bool start();
    void close();

    template<typename Method>
    coro::task<rpc_result<typename Method::response_type>>
        call(const typename Method::request_type& request);

    template<typename Method, typename Rep, typename Period>
    coro::task<rpc_result<typename Method::response_type>>
        call(const typename Method::request_type& request,
             std::chrono::duration<Rep, Period> timeout);

    template<typename Method>
    coro::task<rpc_result<typename Method::response_type>>
        call(const typename Method::request_type& request,
             coro::cancel_token token);

    template<typename Method, typename Rep, typename Period>
    coro::task<rpc_result<typename Method::response_type>>
        call(const typename Method::request_type& request,
             std::chrono::duration<Rep, Period> timeout,
             coro::cancel_token token);

    template<typename Method>
    coro::task<bool> send_oneway(
        const typename Method::request_type& request);

    coro::task<bool> ping(
        std::chrono::milliseconds timeout = std::chrono::milliseconds(5000));

    Stream& stream() noexcept;
    const Stream& stream() const noexcept;
    const rpc_client_config& config() const noexcept;
};

using tcp_rpc_client = rpc_client<net::tcp_stream>;
using uds_rpc_client = rpc_client<net::uds_stream>;
```

`create()` constructs a client from an existing stream and attempts to start the
background receive loop immediately. If it is called outside a scheduler,
`start()` returns `false`; call `start()` from a scheduler before issuing
response-bearing operations such as `call()` or `ping()`.

`connect()` and `connect_with_config()` perform the transport connection from a
scheduler context and return a client with its receive loop started on success.

Call `close()` explicitly when the client is no longer needed. The receive loop
can hold a strong reference while blocked in a read, so dropping the last
external `shared_ptr` is not a substitute for closing the underlying stream and
waking pending calls.

#### `rpc_result<T>`

```cpp
template<typename T>
class rpc_result {
public:
    explicit rpc_result(T value);         // Success
    explicit rpc_result(rpc_error err);   // Error
    
    bool ok() const noexcept;
    explicit operator bool() const noexcept;
    
    rpc_error error() const noexcept;
    const char* error_message() const noexcept;
    
    T& value() &;
    const T& value() const&;
    T&& value() &&;
    
    template<typename U> T value_or(U&& default_value) const&;
    
    T* operator->();
    T& operator*();
};

// Specialization for void
template<>
class rpc_result<void> {
    static rpc_result success();
    bool ok() const noexcept;
    rpc_error error() const noexcept;
};
```

### Type Traits

```cpp
template<typename T> inline constexpr bool is_primitive_v;
template<typename T> inline constexpr bool is_string_type_v;
template<typename T> inline constexpr bool is_vector_v;
template<typename T> inline constexpr bool is_std_array_v;
template<typename T> inline constexpr bool is_map_type_v;
template<typename T> inline constexpr bool is_optional_v;
template<typename T> inline constexpr bool is_buffer_ref_v;
template<typename T> inline constexpr bool has_rpc_fields_v;
```