Keep the library boundary explicit.
The HTTP crate depends on Flyology. Flyology does not depend on HTTP. Public HTTP calls remain synchronous Ada calls in either task lane.
A lightweight caller may suspend while Flyology waits for socket or TLS readiness. A native caller uses the ordinary blocking-thread path.
Each provider package owns its complete operation vocabulary: the synchronous call, limited root constructor, established in-out initiator, operation type, and typed Finish. “Scoped” describes the limited operation's lifetime, completion-set ownership, retained borrows, and cancellation drain; it is not a second provider namespace. Colocating both forms makes their shared state machine discoverable and prevents parallel API trees from drifting.
- Flyology HTTP
- Request and response framing, headers, client pools, routing, middleware, SSE, WebSockets, and application-server policy.
- Flyology
- Task-aware sockets, TLS, connections, files, buffers, cancellation, structured scopes, execution groups, and runtime integration.
Keep one owner for each client transport.
An origin-bound HTTP client bounds open and connecting transports. One monotonic deadline covers admission, DNS, connection attempts, TLS, transmission, response-head parsing, and later body reads.
The returned response retains an exchange lease until its body is consumed or abandoned. A clean HTTP/1.1 connection returns to the pool. An HTTP/2 stream completes or resets without disturbing unrelated streams on the same transport.
The separate WebSocket client owns one connection through upgrade, bounded message exchange, WebSocket close, and TLS close notification for wss.
Read the client guide for request bodies, redirects, authentication, pooling, HTTPS, and WebSockets. The HTTP/2 guide covers protocol selection and multiplexing.
Keep exchange ownership with the handler.
A connection or stream handler parses one request, applies body policy, and owns response framing for that exchange. Routing and deterministic middleware compose above the transport without transferring its live owner.
One unified lifecycle can run cleartext HTTP/1.x, TLS HTTP/1.1 and HTTP/2, and QUIC HTTP/3 through the same router. The exchange records the scheme separately from the protocol. Cleartext requests can be routed or redirected to a configured HTTPS origin.
SSE and WebSocket upgrades retain an explicit connection lifecycle. They do not create another hidden transport owner.
Read the server guide for unified listeners, routing, middleware, request tasks, streaming, and upgrades.
Pass only detached values to native workers.
A routed handler may prepare bounded, detached CPU input and submit it to Flyology's native executors. The live exchange, request body, connection, and response writer stay with the request owner.
The worker returns a detached result. The original owner renders it and retains framing and cancellation ownership.
Keep protocol selection and limits explicit.
HTTP/2 is opt-in through TLS ALPN or cleartext prior knowledge. The active exchange owner drives bounded multiplexed framing and flow control without a background pump task.
HTTP/3 is direct or learned from same-origin Alt-Svc. It uses bounded QUIC connection and stream state, static-table QPACK, and shared multiplexed pooled sessions driven by the active exchange owner.
The raw Server.Connection type is specific to HTTP/1.x. Protocol-neutral applications use Applications.Exchange.
The library does not provide h2c Upgrade, HTTP/2 server push or WebSockets, proxying, content decoding, challenge-driven client authentication, or production qualification.
See the HTTP/2 guide and HTTP/3 server guide for selection modes and limits. The generated API reference defines exact parameters, exceptions, ownership rules, and limits.