# turnloop-http
Own HTTP/1.1 and HTTP/2 wire engines, with no runtime or transport dependency.
- `http1::Decoder::receive` consumes a prefix and returns one event. Retain the unconsumed bytes, including bytes after a CONNECT/WebSocket upgrade. A zero-consumption event is progress; call again until both consumption and event are empty. `eof` distinguishes close-delimited completion from truncated framing.
- `client::Http1Connection` adds non-pipelined requests, streamed uploads, `100-continue`, output acknowledgements, deadline/abort state, and one terminal completion per accepted request. Take the completion before reusing the connection.
- `http2::Connection` handles both roles. Flush and acknowledge `output`, retain incomplete input, consume one frame/event at a time. `send_data` can accept only a prefix or zero when flow-controlled; retain the remainder. Return DATA capacity with `release_capacity` after the application consumes it. Queue application responses in the host during stalls. On transport loss call `eof`, then drain `poll_failed_stream`.
- `hpack` provides the independent bounded RFC 7541 codec. The encoder never indexes credentials/cookies. Decode failures poison a context.
- `client::Pool` reserves connections before DNS/connect so parallel commands respect per-origin/proxy limits. `Route` emits resolution/TLS requests and builds proxy CONNECT or absolute-form heads. `Resolver` belongs to the host. `Request::redirect` applies Fetch redirects; use `DEFAULT_MAX_REDIRECTS` (20). JS conversions and promise delivery remain with Perry.
- `compression::StreamingDecoder` accepts input and caller-owned output. Reuse it with `reset` to retain scratch buffers across bodies. Hosts may cache one per content encoding. `decode` is the convenience whole-body path and constructs algorithm state each time.
No engine samples a clock. The host passes `Instant` deadlines and invokes timeout handlers. Hold output storage stable until a completion-shaped write finishes: do not mutate the engine while an I/O operation borrows its output. Error codes are transport causes; Perry creates the JS error objects and detailed OS diagnostics.
WASM uses the published `turnloop-zstd-decoder` fork of ruzstd 0.8.3 with retained sequence tables. Consumers need no workspace patch. Native builds use the reference zstd decoder by default; `pure-rust-zstd` selects the same decoder as WASM, including its allocation gates. See the decoder crate’s `UPSTREAM.md`.
Tests use private ephemeral loopback servers, Node 26, curl, generated TLS certificates, RFC vectors and a vendored HPACK corpus. `examples/h2spec_server.rs` drives the async server on turnloop; the required h2spec gate checks all 147 strict cases. Exact commands and limitations are in the root `LANE_REPORT.md`.
## Getting started on turnloop
Enable the `turnloop` feature. Create `LocalExecutor<Platform>`, clone its handle,
and spawn a task using `asynchronous::client::Client`. `request(&mut Request,
events, writes and HTTP upgrade handoff. HTTP/2 callbacks release receive capacity
after consuming DATA and retain unsent application data while send windows stall.
The pooled facade serializes each client's requests; multiplexing is available
through the lower-level HTTP/2 driver. `Expect: 100-continue` waits for an informational reply or the configured
continue deadline; an early final response suppresses the upload and closes the lease.
`asynchronous::server::Server` owns the TCP accept loop and local service tasks.
Use `server::http1` or `server::http2` inside a service (optionally after TLS/ALPN).
The HTTP/1 callback streams request events into a reusable Response encoder.
`server.shutdown().stop()` stops accepts, closes idle HTTP/1 connections and sends
HTTP/2 GOAWAY while existing streams drain. Wrap drain in an application deadline;
dropping Server cancels its remaining service tasks.
```sh
cargo run -p turnloop-http --features turnloop --example https_get -- https://example.com/
cargo run -p turnloop-http --features turnloop --example tls_echo -- cert.pem key.pem 127.0.0.1:8443
cargo run -p turnloop-http --features turnloop --example https_get -- https://localhost:8443/ cert.pem
```
The TLS echo example negotiates HTTP/1.1 or HTTP/2 through ALPN. Certificates and
private keys are supplied by the host; certificate verification stays enabled.
WASI 0.2/0.3 use wasi:sockets and this same TLS/HTTP path (p3 remains experimental).
The current core resolver uses a native blocking pool: WASI clients need literal
IP URLs, or a host-resolved stream with the low-level HTTP/TLS drivers. The latter
lets the host retain the original hostname for SNI and certificate validation.
On browsers, `asynchronous::web::get` maps to the existing host fetch operation:
bounded GET response bodies, abort and deadlines. The current host interface does
not expose status/headers, custom methods, body streaming, proxy CONNECT or ALPN;
redirects, decompression and TLS are controlled by the browser. Servers/raw sockets
are Unsupported there. See `turnloop-io` for the shared ownership pattern.