turnloop-io 0.1.0-beta.2

Shared async stream and sans-I/O driver glue for turnloop
Documentation
# turnloop-io

Shared, runtime-free async glue for turnloop protocol adapters. TCP and pipe
`AsyncIo` handles and `TlsStream` implement the same `Stream` trait. The host owns
`LocalExecutor` and calls `turn`; adapters never drive the loop or start threads.

## Getting started on turnloop

Enable a protocol crate's `turnloop` feature. Create an executor, clone its handle,
and spawn a local task. Connect with `handle.connect(address, options).await` or
accept with `Listener::bind(&handle, address)?.accept().await`. Use `deadline` with
one absolute backend-clock deadline for a whole exchange.

## Adapter pattern

1. Keep the sans-I/O core and its retained buffers in the connection.
2. Feed only bytes actually received. Preserve unconsumed bytes across events and
   upgrades. On no progress, await a transport read; never wake/poll an idle core.
3. Use `drain` to write core output, flush, then acknowledge it. Do not clear output
   while delivery is pending. Partial writes and errors retain ownership.
4. A request owns its connection lease until its response body is fully consumed.
   Dropping an incomplete exchange closes the stream rather than returning a
   partially consumed protocol to the pool. AsyncIo cancellation retains submitted
   staging until the backend's exactly-once terminal completion.
5. Allocate retained buffers at connection creation/warm-up, never per I/O call.
   Application-owned headers/messages and crypto state have separate accounting.

## Half-close and lingering close

`close` releases the whole transport. `shutdown` (the `HalfClose` trait, implemented
by `AsyncIo`, `TlsStream` and `Transport`) flushes accepted writes and ends only the
write direction: TLS sends close_notify, then TCP `shutdown(SHUT_WR)` (IOCP
`SD_SEND`, WASI `shutdown(send)`). Reads continue until the peer's EOF and the handle
stays open until `close` or drop. UDP, Windows named pipes and non-socket Unix
descriptors return `Unsupported`.

A server should not close a socket while peer bytes are unread: that sends RST, and
on macOS and Windows a received RST discards data the peer has not read yet (the
tail of the final response). `linger_close(stream, scratch, deadline)` flushes and
half-closes, reads and discards into caller-retained scratch until the peer's EOF
or the deadline, then closes. It waits only on one read and one executor timer (no
spin) and allocates nothing per read; `Lingered` reports how it ended and how many
bytes were discarded.

Native TCP/pipes and WASI sockets use the identical generic stream code. Browser
raw sockets/listeners return Unsupported; browser HTTP uses host fetch. Windows
uses the production Backend implementation when integrated.

## Pools and DNS

`pool::Pool` schedules the existing protocol pool policies with one manager task,
retained waiters and real executor deadlines. A lease owns the connection across
awaits. Cancelling a waiter removes its request; returning an incomplete exchange
retires the transport. Pool replacement/end observes the backend's physical close
acknowledgement through `ExecutorHandle::close`.

`resolve` uses native blocking DNS or WASI 0.2 `ip-name-lookup`. `dns::query` returns
native SRV/TXT records through `ExecutorHandle::blocking`, keeping system resolver
calls off the loop thread. Native worker count/queue bounds remain those of the
host's turnloop configuration. WASI exposes no SRV/TXT capability; use resolved
seeds when the protocol needs those records.