# flare_mlake API reference

> The `flare` package, from flare_mlake 0.13.2, as published on mojoshelf (commit b1371866a784), by `mojo doc` from Mojo 1.2.0.

## Modules

- [flare.crypto](https://magmalake.dev/s/flare_mlake/api/crypto.md): ``flare.crypto`` — minimal cryptographic primitives over the OpenSSL FFI.
- [flare.crypto.base64](https://magmalake.dev/s/flare_mlake/api/crypto/base64.md): ``flare.crypto.base64`` -- RFC 4648 §4 standard base64 encode/decode.
- [flare.crypto.hmac](https://magmalake.dev/s/flare_mlake/api/crypto/hmac.md): HMAC-SHA256 + URL-safe base64 over the OpenSSL FFI.
- [flare.crypto.random](https://magmalake.dev/s/flare_mlake/api/crypto/random.md): ``flare.crypto.random`` -- bytes from the operating system's CSPRNG.
- [flare.dns](https://magmalake.dev/s/flare_mlake/api/dns.md): DNS resolution via `getaddrinfo(3)`.
- [flare.dns.async_resolve](https://magmalake.dev/s/flare_mlake/api/dns/async_resolve.md): DNS resolution on a separate thread + happy-eyeballs ordering.
- [flare.dns.cache](https://magmalake.dev/s/flare_mlake/api/dns/cache.md): TTL-bounded DNS resolution cache.
- [flare.dns.resolver](https://magmalake.dev/s/flare_mlake/api/dns/resolver.md): DNS hostname resolution via libc ``getaddrinfo(3)``.
- [flare.errors](https://magmalake.dev/s/flare_mlake/api/errors.md): Cross-module typed-error vocabulary for flare.
- [flare.grpc](https://magmalake.dev/s/flare_mlake/api/grpc.md): ``flare.grpc`` — gRPC primitives on top of the HTTP/2 reactor.
- [flare.grpc.client](https://magmalake.dev/s/flare_mlake/api/grpc/client.md): The gRPC unary client over the HTTP/2 ``HttpClient`` path.
- [flare.grpc.client_stream](https://magmalake.dev/s/flare_mlake/api/grpc/client_stream.md): ``flare.grpc.client_stream`` -- server-side client-streaming + bidi.
- [flare.grpc.framing](https://magmalake.dev/s/flare_mlake/api/grpc/framing.md): ``gRPC`` length-prefix-message (LPM) framing codec.
- [flare.grpc.health](https://magmalake.dev/s/flare_mlake/api/grpc/health.md): ``flare.grpc.health`` -- the standard ``grpc.health.v1.Health`` service (Check), implemented as a :trait:`GrpcUnary` handler.
- [flare.grpc.interceptor](https://magmalake.dev/s/flare_mlake/api/grpc/interceptor.md): ``flare.grpc.interceptor`` -- chainable unary server interceptors.
- [flare.grpc.metadata](https://magmalake.dev/s/flare_mlake/api/grpc/metadata.md): ``gRPC`` metadata carrier (initial + trailing).
- [flare.grpc.proto](https://magmalake.dev/s/flare_mlake/api/grpc/proto.md): ``flare.grpc.proto`` -- proto3 wire-format codec.
- [flare.grpc.reflection](https://magmalake.dev/s/flare_mlake/api/grpc/reflection.md): ``flare.grpc.reflection`` -- gRPC server reflection (v1alpha).
- [flare.grpc.server](https://magmalake.dev/s/flare_mlake/api/grpc/server.md): ``flare.grpc.server`` -- gRPC server adapter on the HTTP/2 reactor.
- [flare.grpc.server_stream](https://magmalake.dev/s/flare_mlake/api/grpc/server_stream.md): ``flare.grpc.server_stream`` -- server-streaming gRPC adapter.
- [flare.grpc.status](https://magmalake.dev/s/flare_mlake/api/grpc/status.md): ``gRPC`` status codes and trailer carrier.
- [flare.grpc.streaming](https://magmalake.dev/s/flare_mlake/api/grpc/streaming.md): The gRPC streaming calls over a long-lived HTTP/2 stream.
- [flare.http](https://magmalake.dev/s/flare_mlake/api/http.md): HTTP/1.1 client and server.
- [flare.http.alpn_dispatch](https://magmalake.dev/s/flare_mlake/api/http/alpn_dispatch.md): ``flare.http.alpn_dispatch`` -- ALPN-driven wire dispatcher.
- [flare.http.async_body](https://magmalake.dev/s/flare_mlake/api/http/async_body.md): Reactor-integrated external streaming source.
- [flare.http.auth](https://magmalake.dev/s/flare_mlake/api/http/auth.md): HTTP authentication helpers.
- [flare.http.auth_extract](https://magmalake.dev/s/flare_mlake/api/http/auth_extract.md): Server-side authentication extractors + CSRF helper.
- [flare.http.body](https://magmalake.dev/s/flare_mlake/api/http/body.md): Streaming response body primitives.
- [flare.http.cache](https://magmalake.dev/s/flare_mlake/api/http/cache.md): ``flare.http.cache`` — RFC 9111 HTTP cache primitives.
- [flare.http.cache.control](https://magmalake.dev/s/flare_mlake/api/http/cache/control.md): ``Cache-Control`` header parser (RFC 9111 §5.2).
- [flare.http.cache.key](https://magmalake.dev/s/flare_mlake/api/http/cache/key.md): Cache key derivation (RFC 9111 §4 "Constructing Responses from Caches").
- [flare.http.cache.middleware](https://magmalake.dev/s/flare_mlake/api/http/cache/middleware.md): HTTP cache middleware (RFC 9111).
- [flare.http.cache.store](https://magmalake.dev/s/flare_mlake/api/http/cache/store.md): Cache store trait + in-memory implementation.
- [flare.http.cancel](https://magmalake.dev/s/flare_mlake/api/http/cancel.md): Cancel token plumbed from the reactor into request handlers.
- [flare.http.client](https://magmalake.dev/s/flare_mlake/api/http/client.md): HTTP/1.1 client with optional TLS support.
- [flare.http.client_pool](https://magmalake.dev/s/flare_mlake/api/http/client_pool.md): HTTP/1.1 client connection pool.
- [flare.http.conditional](https://magmalake.dev/s/flare_mlake/api/http/conditional.md): Conditional GET / PUT middleware (RFC 9110 §13).
- [flare.http.cookie](https://magmalake.dev/s/flare_mlake/api/http/cookie.md): HTTP cookie support (RFC 6265).
- [flare.http.cors](https://magmalake.dev/s/flare_mlake/api/http/cors.md): ``Cors[Inner]`` middleware (Cross-Origin Resource Sharing).
- [flare.http.encoding](https://magmalake.dev/s/flare_mlake/api/http/encoding.md): HTTP content-encoding helpers: gzip and deflate via zlib FFI.
- [flare.http.error](https://magmalake.dev/s/flare_mlake/api/http/error.md): HTTP-level error types.
- [flare.http.extract](https://magmalake.dev/s/flare_mlake/api/http/extract.md): Typed request extractors with reflective auto-injection.
- [flare.http.form](https://magmalake.dev/s/flare_mlake/api/http/form.md): ``application/x-www-form-urlencoded`` parsing (WHATWG URL Living Standard, §5.1).
- [flare.http.frontend](https://magmalake.dev/s/flare_mlake/api/http/frontend.md): HTTP frontends for the multicore :class:`flare.runtime.Scheduler`.
- [flare.http.fs](https://magmalake.dev/s/flare_mlake/api/http/fs.md): ``FileServer`` — serve files from a directory with HEAD + Range support.
- [flare.http.handler](https://magmalake.dev/s/flare_mlake/api/http/handler.md): The ``Handler`` trait: flare's request-to-response contract.
- [flare.http.header_phf](https://magmalake.dev/s/flare_mlake/api/http/header_phf.md): Comptime perfect-hash dispatch for ~70 standard HTTP header names.
- [flare.http.header_view](https://magmalake.dev/s/flare_mlake/api/http/header_view.md): Borrowed header storage.
- [flare.http.headers](https://magmalake.dev/s/flare_mlake/api/http/headers.md): HTTP header collection with case-insensitive key lookup.
- [flare.http.hpack_huffman](https://magmalake.dev/s/flare_mlake/api/http/hpack_huffman.md): HPACK Huffman codec — RFC 7541 Appendix B.
- [flare.http.hpack_huffman_simd](https://magmalake.dev/s/flare_mlake/api/http/hpack_huffman_simd.md): HPACK Huffman fast decoder.
- [flare.http.intern](https://magmalake.dev/s/flare_mlake/api/http/intern.md): Interned ``StaticString`` table for HTTP method names + common header values.
- [flare.http.metrics](https://magmalake.dev/s/flare_mlake/api/http/metrics.md): Prometheus-text-exposition metrics middleware.
- [flare.http.middleware](https://magmalake.dev/s/flare_mlake/api/http/middleware.md): Generic middleware library for .
- [flare.http.multipart](https://magmalake.dev/s/flare_mlake/api/http/multipart.md): ``multipart/form-data`` parsing (RFC 7578).
- [flare.http.multipart_builder](https://magmalake.dev/s/flare_mlake/api/http/multipart_builder.md): Client-side ``multipart/form-data`` request-body builder (RFC 7578).
- [flare.http.proto](https://magmalake.dev/s/flare_mlake/api/http/proto.md): ``flare.http.proto`` -- pure-function HTTP wire codecs and parsers.
- [flare.http.proto.ascii](https://magmalake.dev/s/flare_mlake/api/http/proto/ascii.md): ``flare.http.proto.ascii`` -- zero-validation ASCII helpers.
- [flare.http.proto.chunked](https://magmalake.dev/s/flare_mlake/api/http/proto/chunked.md): Sans-I/O framing for ``Transfer-Encoding: chunked`` request bodies.
- [flare.http.proto.h1_leniency](https://magmalake.dev/s/flare_mlake/api/http/proto/h1_leniency.md): Named opt-in flags for HTTP/1.1 parser leniency.
- [flare.http.proto.h2_config](https://magmalake.dev/s/flare_mlake/api/http/proto/h2_config.md): HTTP/2 SETTINGS and per-connection limits.
- [flare.http.proto.h2c_upgrade](https://magmalake.dev/s/flare_mlake/api/http/proto/h2c_upgrade.md): HTTP/1.1 -> HTTP/2 cleartext (h2c) upgrade detection (RFC 7540 §3.2).
- [flare.http.proto.huffman](https://magmalake.dev/s/flare_mlake/api/http/proto/huffman.md): Canonical sans-I/O HPACK / QPACK Huffman codec surface (``flare.http.proto.huffman``) -- RFC 7541 §5.2 + Appendix B.
- [flare.http.proto.utf8](https://magmalake.dev/s/flare_mlake/api/http/proto/utf8.md): Lossy UTF-8 decoding for caller-supplied byte bodies.
- [flare.http.proxy_protocol](https://magmalake.dev/s/flare_mlake/api/http/proxy_protocol.md): PROXY protocol v1 + v2 parser (HAProxy spec).
- [flare.http.redirect_policy](https://magmalake.dev/s/flare_mlake/api/http/redirect_policy.md): HTTP redirect policy: configurable cross-origin + auth gating.
- [flare.http.reliability](https://magmalake.dev/s/flare_mlake/api/http/reliability.md): Reliability middleware: ``Retry`` / ``PostHocDeadline`` / ``RateLimit`` / ``CircuitBreaker`` policies.
- [flare.http.request](https://magmalake.dev/s/flare_mlake/api/http/request.md): HTTP request type.
- [flare.http.request_body](https://magmalake.dev/s/flare_mlake/api/http/request_body.md): A request body that keeps arriving after the handler has started.
- [flare.http.request_builder](https://magmalake.dev/s/flare_mlake/api/http/request_builder.md): Fluent-ish per-request builder for the HTTP client.
- [flare.http.request_chunks](https://magmalake.dev/s/flare_mlake/api/http/request_chunks.md): Streaming-shape adapter for inbound request bodies.
- [flare.http.request_view](https://magmalake.dev/s/flare_mlake/api/http/request_view.md): Zero-copy HTTP request view.
- [flare.http.response](https://magmalake.dev/s/flare_mlake/api/http/response.md): HTTP response type.
- [flare.http.response_pool](https://magmalake.dev/s/flare_mlake/api/http/response_pool.md): Per-worker ``Response`` pool.
- [flare.http.response_stream](https://magmalake.dev/s/flare_mlake/api/http/response_stream.md): Streaming-response plumbing for the normal Handler path (K1).
- [flare.http.router](https://magmalake.dev/s/flare_mlake/api/http/router.md): HTTP request router with method dispatch + path parameters.
- [flare.http.routes](https://magmalake.dev/s/flare_mlake/api/http/routes.md): Comptime-compiled route table and ``ComptimeRouter``.
- [flare.http.server](https://magmalake.dev/s/flare_mlake/api/http/server.md): HTTP/1.1 server with buffered reads, keep-alive, and per-connection handler callbacks.
- [flare.http.session](https://magmalake.dev/s/flare_mlake/api/http/session.md): Signed cookies + typed sessions.
- [flare.http.simd_parsers](https://magmalake.dev/s/flare_mlake/api/http/simd_parsers.md): SIMD-friendly byte-scan primitives for the HTTP/1.1 parser hot path.
- [flare.http.sse](https://magmalake.dev/s/flare_mlake/api/http/sse.md): Server-Sent Events (W3C SSE / RFC 9110 ``text/event-stream``).
- [flare.http.static_response](https://magmalake.dev/s/flare_mlake/api/http/static_response.md): Pre-encoded literal HTTP responses for the fastest possible fast path.
- [flare.http.streaming_response](https://magmalake.dev/s/flare_mlake/api/http/streaming_response.md): Streaming response with a parametric body type.
- [flare.http.streaming_serialize](https://magmalake.dev/s/flare_mlake/api/http/streaming_serialize.md): Streaming response serializer.
- [flare.http.streaming_server](https://magmalake.dev/s/flare_mlake/api/http/streaming_server.md): Typed streaming-handler surface.
- [flare.http.structured_logger](https://magmalake.dev/s/flare_mlake/api/http/structured_logger.md): Structured (JSON-shaped) request logger middleware.
- [flare.http.template](https://magmalake.dev/s/flare_mlake/api/http/template.md): Tiny tag-based template engine.
- [flare.http.url](https://magmalake.dev/s/flare_mlake/api/http/url.md): URL parser for HTTP/HTTPS URLs.
- [flare.http.wire](https://magmalake.dev/s/flare_mlake/api/http/wire.md): ``flare.http.wire`` -- neutral wire-shape types shared by every HTTP wire.
- [flare.http2](https://magmalake.dev/s/flare_mlake/api/http2.md): ``flare.http2`` -- low-level HTTP/2 driver primitives (RFC 9113 + RFC 7541).
- [flare.http2.client](https://magmalake.dev/s/flare_mlake/api/http2/client.md): HTTP/2 client byte driver (RFC 9113).
- [flare.http2.frame](https://magmalake.dev/s/flare_mlake/api/http2/frame.md): HTTP/2 frame codec (RFC 9113 §4).
- [flare.http2.hpack](https://magmalake.dev/s/flare_mlake/api/http2/hpack.md): HPACK header compression (RFC 7541).
- [flare.http2.server](https://magmalake.dev/s/flare_mlake/api/http2/server.md): HTTP/2 server glue (RFC 9113).
- [flare.http2.state](https://magmalake.dev/s/flare_mlake/api/http2/state.md): HTTP/2 state machines (RFC 9113 §5).
- [flare.http2.stream_slab](https://magmalake.dev/s/flare_mlake/api/http2/stream_slab.md): HTTP/2 per-connection stream slab.
- [flare.http3](https://magmalake.dev/s/flare_mlake/api/http3.md): ``flare.http3`` — sans-I/O HTTP/3 codec primitives (RFC 9114).
- [flare.http3.capsule](https://magmalake.dev/s/flare_mlake/api/http3/capsule.md): The Capsule Protocol (RFC 9297 sec 3).
- [flare.http3.client](https://magmalake.dev/s/flare_mlake/api/http3/client.md): HTTP/3 client connection driver -- QUIC + H3 composition.
- [flare.http3.frame](https://magmalake.dev/s/flare_mlake/api/http3/frame.md): HTTP/3 frame codec (RFC 9114 §7).
- [flare.http3.request_reader](https://magmalake.dev/s/flare_mlake/api/http3/request_reader.md): HTTP/3 request-stream reader -- sans-I/O state machine.
- [flare.http3.request_writer](https://magmalake.dev/s/flare_mlake/api/http3/request_writer.md): HTTP/3 request-stream writer -- sans-I/O byte emitter.
- [flare.http3.response_reader](https://magmalake.dev/s/flare_mlake/api/http3/response_reader.md): HTTP/3 response-stream reader -- sans-I/O stateful decoder.
- [flare.http3.response_writer](https://magmalake.dev/s/flare_mlake/api/http3/response_writer.md): HTTP/3 response-stream writer -- sans-I/O byte emitter.
- [flare.http3.server](https://magmalake.dev/s/flare_mlake/api/http3/server.md): ``flare.http3.server`` -- HTTP/3 server connection driver.
- [flare.io](https://magmalake.dev/s/flare_mlake/api/io.md): Buffered I/O utilities for flare streams.
- [flare.io.buf_reader](https://magmalake.dev/s/flare_mlake/api/io/buf_reader.md): Buffered reader for stream I/O.
- [flare.io.byte_cursor](https://magmalake.dev/s/flare_mlake/api/io/byte_cursor.md): Safe, bounds-checked byte cursors.
- [flare.net](https://magmalake.dev/s/flare_mlake/api/net.md): Raw POSIX socket primitives — the foundation of the flare networking stack.
- [flare.net.address](https://magmalake.dev/s/flare_mlake/api/net/address.md): IP address and socket address types.
- [flare.net.error](https://magmalake.dev/s/flare_mlake/api/net/error.md): Typed network errors for flare.
- [flare.net.socket](https://magmalake.dev/s/flare_mlake/api/net/socket.md): Raw POSIX socket wrapper — the single point where flare touches the OS.
- [flare.openapi](https://magmalake.dev/s/flare_mlake/api/openapi.md): ``flare.openapi`` — OpenAPI 3.1 spec data model + JSON emitter.
- [flare.openapi.from_router](https://magmalake.dev/s/flare_mlake/api/openapi/from_router.md): Derive an :class:`OpenApiSpec` from a runtime :class:`Router`.
- [flare.openapi.spec](https://magmalake.dev/s/flare_mlake/api/openapi/spec.md): OpenAPI 3.1 spec data model + JSON serializer.
- [flare.prelude](https://magmalake.dev/s/flare_mlake/api/prelude.md): ``flare.prelude`` -- the everyday surface, in one import.
- [flare.qpack](https://magmalake.dev/s/flare_mlake/api/qpack.md): ``flare.qpack`` -- QPACK encoder/decoder (RFC 9204).
- [flare.qpack.codec](https://magmalake.dev/s/flare_mlake/api/qpack/codec.md): QPACK encoder + decoder (RFC 9204) -- static-only.
- [flare.qpack.dynamic](https://magmalake.dev/s/flare_mlake/api/qpack/dynamic.md): QPACK dynamic table + encoder/decoder stream instructions (RFC 9204).
- [flare.qpack.static_table](https://magmalake.dev/s/flare_mlake/api/qpack/static_table.md): QPACK static table (RFC 9204 Appendix A).
- [flare.quic](https://magmalake.dev/s/flare_mlake/api/quic.md): ``flare.quic`` — sans-I/O QUIC v1 codec primitives (RFC 9000).
- [flare.quic.cc](https://magmalake.dev/s/flare_mlake/api/quic/cc.md): QUIC congestion control (RFC 9002 section 7): Reno + CUBIC (HyStart++).
- [flare.quic.client](https://magmalake.dev/s/flare_mlake/api/quic/client.md): ``flare.quic.client`` -- QUIC v1 client connection driver.
- [flare.quic.crypto](https://magmalake.dev/s/flare_mlake/api/quic/crypto.md): QUIC v1 crypto primitives (RFC 9001).
- [flare.quic.frame](https://magmalake.dev/s/flare_mlake/api/quic/frame.md): QUIC v1 transport-frame codec (RFC 9000 §19).
- [flare.quic.packet](https://magmalake.dev/s/flare_mlake/api/quic/packet.md): QUIC v1 packet header codec (RFC 9000 §17).
- [flare.quic.protection](https://magmalake.dev/s/flare_mlake/api/quic/protection.md): ``flare.quic.protection`` -- QUIC v1 per-packet header + AEAD protection (RFC 9001 §5.3-5.4).
- [flare.quic.retry](https://magmalake.dev/s/flare_mlake/api/quic/retry.md): QUIC server Retry + Version Negotiation packet codecs (RFC 9000 §8.1 / §17.2.1 / §17.2.5, RFC 9001 §5.8).
- [flare.quic.server](https://magmalake.dev/s/flare_mlake/api/quic/server.md): ``flare.quic.server`` -- QUIC server reactor.
- [flare.quic.state](https://magmalake.dev/s/flare_mlake/api/quic/state.md): QUIC connection + stream state machines (RFC 9000 §3 + §13).
- [flare.quic.timers](https://magmalake.dev/s/flare_mlake/api/quic/timers.md): ``flare.quic.timers`` -- per-connection timer kinds + token encoding for the QUIC reactor.
- [flare.quic.transport_params](https://magmalake.dev/s/flare_mlake/api/quic/transport_params.md): QUIC transport-parameter codec (RFC 9000 §18 + §19.1.1).
- [flare.quic.varint](https://magmalake.dev/s/flare_mlake/api/quic/varint.md): Variable-length integer codec for QUIC (RFC 9000 §16).
- [flare.runtime](https://magmalake.dev/s/flare_mlake/api/runtime.md): ``flare.runtime`` — event-loop primitives for the Stage 1 reactor.
- [flare.runtime.blocking](https://magmalake.dev/s/flare_mlake/api/runtime/blocking.md): Blocking-escape hatch: ``block_in_pool``.
- [flare.runtime.buffer_pool](https://magmalake.dev/s/flare_mlake/api/runtime/buffer_pool.md): Per-worker, size-class-bucketed buffer pool.
- [flare.runtime.date_cache](https://magmalake.dev/s/flare_mlake/api/runtime/date_cache.md): Per-worker monotonic Date-header cache.
- [flare.runtime.event](https://magmalake.dev/s/flare_mlake/api/runtime/event.md): Event primitives for the flare reactor.
- [flare.runtime.frontend](https://magmalake.dev/s/flare_mlake/api/runtime/frontend.md): Worker-target trait for the multicore :class:`Scheduler`.
- [flare.runtime.handoff](https://magmalake.dev/s/flare_mlake/api/runtime/handoff.md): Cross-worker connection handoff.
- [flare.runtime.io_uring](https://magmalake.dev/s/flare_mlake/api/runtime/io_uring.md): ``io_uring`` backend substrate.
- [flare.runtime.io_uring_abi](https://magmalake.dev/s/flare_mlake/api/runtime/io_uring_abi.md): ``flare.runtime.io_uring_abi`` -- io_uring ABI constants + byte codec.
- [flare.runtime.io_uring_driver](https://magmalake.dev/s/flare_mlake/api/runtime/io_uring_driver.md): ``io_uring`` SQ/CQ ring driver.
- [flare.runtime.io_uring_sqe](https://magmalake.dev/s/flare_mlake/api/runtime/io_uring_sqe.md): ``io_uring`` SQE encoder + CQE decoder primitives.
- [flare.runtime.iovec](https://magmalake.dev/s/flare_mlake/api/runtime/iovec.md): ``writev(2)`` vectored-I/O primitive.
- [flare.runtime.pool](https://magmalake.dev/s/flare_mlake/api/runtime/pool.md): Typed heap-allocator wrapper.
- [flare.runtime.reactor](https://magmalake.dev/s/flare_mlake/api/runtime/reactor.md): Reactor: the event-loop core powering flare's single-threaded HTTP server.
- [flare.runtime.reuseport](https://magmalake.dev/s/flare_mlake/api/runtime/reuseport.md): ``SO_REUSEPORT`` helpers for thread-per-core listeners.
- [flare.runtime.scheduler](https://magmalake.dev/s/flare_mlake/api/runtime/scheduler.md): Multicore scheduler: 1 shared listener, N reactors, N workers.
- [flare.runtime.scheduler_stats](https://magmalake.dev/s/flare_mlake/api/runtime/scheduler_stats.md): Cross-thread stop flag and per-worker stats cell.
- [flare.runtime.timer_wheel](https://magmalake.dev/s/flare_mlake/api/runtime/timer_wheel.md): Hashed timing wheel for the flare reactor.
- [flare.runtime.uring_reactor](https://magmalake.dev/s/flare_mlake/api/runtime/uring_reactor.md): ``UringReactor``: io_uring-native event-loop wrapper.
- [flare.runtime.watchdog](https://magmalake.dev/s/flare_mlake/api/runtime/watchdog.md): Deadline watchdog: a background thread that flips Cancel cells on expiry.
- [flare.tcp](https://magmalake.dev/s/flare_mlake/api/tcp.md): Blocking TCP streams and listeners.
- [flare.tcp.listener](https://magmalake.dev/s/flare_mlake/api/tcp/listener.md): TCP listener: a socket bound and listening for incoming connections.
- [flare.tcp.stream](https://magmalake.dev/s/flare_mlake/api/tcp/stream.md): TCP stream: a connected, bidirectional byte stream.
- [flare.testing](https://magmalake.dev/s/flare_mlake/api/testing.md): ``flare.testing`` — handler + middleware testing helpers.
- [flare.testing.client](https://magmalake.dev/s/flare_mlake/api/testing/client.md): In-process test client for ``Handler`` implementations.
- [flare.testing.fork_server](https://magmalake.dev/s/flare_mlake/api/testing/fork_server.md): Fork-and-serve helpers for cookbook examples and integration tests.
- [flare.tls](https://magmalake.dev/s/flare_mlake/api/tls.md): TLS/SSL layer — wraps `TcpStream` with OpenSSL encryption.
- [flare.tls.acceptor](https://magmalake.dev/s/flare_mlake/api/tls/acceptor.md): Server-side TLS acceptor.
- [flare.tls.config](https://magmalake.dev/s/flare_mlake/api/tls/config.md): TLS configuration: certificates, keys, and verification policy.
- [flare.tls.error](https://magmalake.dev/s/flare_mlake/api/tls/error.md): TLS-specific error types for ``flare.tls``.
- [flare.tls.rustls_quic](https://magmalake.dev/s/flare_mlake/api/tls/rustls_quic.md): `flare.tls.rustls_quic` -- rustls QUIC binding surface.
- [flare.tls.stream](https://magmalake.dev/s/flare_mlake/api/tls/stream.md): TLS stream: encrypts a TcpStream via OpenSSL FFI.
- [flare.udp](https://magmalake.dev/s/flare_mlake/api/udp.md): UDP datagram sockets.
- [flare.udp.batch](https://magmalake.dev/s/flare_mlake/api/udp/batch.md): Batched UDP I/O: ``recvmmsg`` / ``sendmmsg`` + GSO segmentation.
- [flare.udp.socket](https://magmalake.dev/s/flare_mlake/api/udp/socket.md): UDP socket: connectionless datagrams.
- [flare.uds](https://magmalake.dev/s/flare_mlake/api/uds.md): ``flare.uds`` — Unix domain socket primitives.
- [flare.uds.frame_mux](https://magmalake.dev/s/flare_mlake/api/uds/frame_mux.md): Multiplexed duplex framed transport over one connection.
- [flare.uds.listener](https://magmalake.dev/s/flare_mlake/api/uds/listener.md): AF_UNIX listener — bound + listening Unix domain socket.
- [flare.uds.stream](https://magmalake.dev/s/flare_mlake/api/uds/stream.md): Connected AF_UNIX byte stream.
- [flare.utils](https://magmalake.dev/s/flare_mlake/api/utils.md): Cross-cutting utility helpers that don't fit any other layer.
- [flare.utils.dylib](https://magmalake.dev/s/flare_mlake/api/utils/dylib.md): Canonical FFI dylib path resolver shared across :mod:`flare`.
- [flare.utils.posix_proc](https://magmalake.dev/s/flare_mlake/api/utils/posix_proc.md): POSIX process-control helpers thin-wrapped over ``external_call``.
- [flare.ws](https://magmalake.dev/s/flare_mlake/api/ws.md): WebSocket client and server (RFC 6455).
- [flare.ws.auto_client](https://magmalake.dev/s/flare_mlake/api/ws/auto_client.md): `flare.ws.auto_client` -- ALPN-driven WebSocket client dispatcher.
- [flare.ws.client](https://magmalake.dev/s/flare_mlake/api/ws/client.md): WebSocket client (RFC 6455).
- [flare.ws.client_h2](https://magmalake.dev/s/flare_mlake/api/ws/client_h2.md): WebSocket-over-HTTP/2 stream <-> frame adapter (RFC 8441).
- [flare.ws.client_h3](https://magmalake.dev/s/flare_mlake/api/ws/client_h3.md): Client side of WebSocket over HTTP/3 (RFC 9220).
- [flare.ws.extensions](https://magmalake.dev/s/flare_mlake/api/ws/extensions.md): ``Sec-WebSocket-Extensions`` header parser + emitter (RFC 6455 §9 + RFC 7692 §7).
- [flare.ws.frame](https://magmalake.dev/s/flare_mlake/api/ws/frame.md): WebSocket frame codec (RFC 6455 §5).
- [flare.ws.permessage_deflate](https://magmalake.dev/s/flare_mlake/api/ws/permessage_deflate.md): WebSocket permessage-deflate extension (RFC 7692).
- [flare.ws.protocol](https://magmalake.dev/s/flare_mlake/api/ws/protocol.md): Sans-I/O WebSocket server protocol core (RFC 6455).
- [flare.ws.server](https://magmalake.dev/s/flare_mlake/api/ws/server.md): WebSocket server: upgrades HTTP connections to WebSocket (RFC 6455).
- [flare.ws.server_h2](https://magmalake.dev/s/flare_mlake/api/ws/server_h2.md): Server-side WebSocket-over-HTTP/2 carrier (RFC 8441).
- [flare.ws.server_h3](https://magmalake.dev/s/flare_mlake/api/ws/server_h3.md): Server-side WebSocket over HTTP/3 (RFC 9220).
- [flare.ws.server_reactor](https://magmalake.dev/s/flare_mlake/api/ws/server_reactor.md): Event-driven WebSocket handlers for HTTP/1.1 upgrades on the reactor.

``flare`` -- a Mojo full networking stack in one library.

HTTP/1.1 + HTTP/2 server and client, WebSocket server and
client (RFC 6455), TLS 1.2/1.3 (OpenSSL with ALPN), TCP, UDP,
DNS. The HTTP server and client are version-aware:
``HttpServer.serve(handler)`` peeks the first 24 bytes of every
accepted connection and dispatches HTTP/1.1 or HTTP/2 to the
same handler. ``HttpClient.get("https://...")`` advertises ALPN
``["h2", "http/1.1"]`` and switches wires from what the server
picks. The application surface (``Router``,
middleware, typed extractors, ``Auth``, ``Session``) doesn't
know which wire is talking to it.

Small FFI footprint: libc syscalls, OpenSSL for TLS, zlib +
brotli for content encoding. No HTTP framework dependency.

```mojo
from flare import HttpServer, Router, Request, Response, ok, SocketAddr

def hello(req: Request) raises -> Response:
    return ok("hello")

def main() raises:
    var r = Router()
    r.get("/", hello)
    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve(r^, num_workers=4)
```

## What flare is

One reactor per worker (``kqueue`` on macOS, ``epoll`` on
Linux, opt-in ``io_uring`` on Linux >= 6.0 via
``FLARE_BUFRING_HANDLER=1``), a ``Handler`` trait that takes plain ``def`` functions
or compiled-down structs, an RFC 7230 parser under continuous fuzzing (62
fuzz harnesses across the tree, 9M+ runs combined, zero known crashes), and a ``Cancel`` token plumbed to handlers via
``CancelHandler``. ``num_workers=1`` is a single-threaded
reactor; ``num_workers=N`` with ``N >= 2`` runs N
workers (on Mojo's AsyncRT pool) behind per-worker ``SO_REUSEPORT`` listeners by default
(matches actix_web's listener strategy and gives the highest
steady-state throughput). Set ``FLARE_REUSEPORT_WORKERS=0`` to
opt into the single shared listener with ``EPOLLEXCLUSIVE`` --
trades 7-22 % req/s (handler vs static fast path) for a
uniformly tighter p99.99 tail under sustained load. See
``docs/benchmark.md`` for the head-to-head numbers. Static
endpoints can skip the parser entirely with
``serve_static(resp, num_workers=N)``.

The operational core: per-request / handler / body-read deadlines,
``HttpServer.drain(timeout_ms)`` for graceful shutdown, sanitised
error responses, ``Request.peer`` threaded from the accept path,
zero-copy reads (``RequestView[origin]`` + ``ViewHandler``),
streaming response primitives (``Body`` / ``ChunkSource`` /
``StreamingResponse[B]``; ``stream_response(source)`` streams the same
handler byte-identically over h1 / h2 / h3 / https), and server-side
TLS (``TlsAcceptor`` over OpenSSL, plus in-process HTTPS termination
via ``HttpServer.bind_tls`` + ``serve``).

The application layer: ``Router`` with path params, typed
extractors (``PathInt`` / ``QueryInt`` /
``HeaderStr`` / ``Form`` / ``Multipart`` / ``Cookies`` / ...),
generic middleware (``Logger`` / ``RequestId`` / ``Compress`` /
``CatchPanic``), ``Cors``, ``FileServer`` with HEAD + Range,
gzip + brotli content negotiation, RFC 6265 cookie jars,
HMAC-SHA256 signed cookies, and signed ``Session`` stores.

## Architecture

```
flare.io       - BufReader
flare.ws       - WebSocket client + server (RFC 6455, permessage-deflate
                 with context-takeover, WS-over-h2 via RFC 8441 and
                 WS-over-h3 via RFC 9220 Extended CONNECT)
flare.http2    - HTTP/2 frame codec + HPACK (with table-driven Huffman
                 fast decoder) + h2c upgrade (RFC 9113 / 7541)
flare.http     - HTTP/1.1 client + reactor server + Router /
                 extractors + middleware (Logger / RequestId / Compress /
                 Cors / Retry / PostHocDeadline / Conditional) + FileServer +
                 forms + cookies + sessions + content-encoding + SSE
                 + template engine with {% block %} / {% extends %}
                 inheritance + serve_streaming streaming-proxy surface
                 (StreamHandler / StreamConn, UpstreamChunkSource,
                 watermark backpressure, admission control) + sans-I/O
                 parser sublayer under flare.http.proto.*
flare.http.cache - RFC 9111 cache primitives (CacheControl directive
                 parser, CacheKey, InMemoryCacheStore)
flare.grpc     - gRPC primitives on flare.http2: LPM message framing,
                 canonical Status codes (with optional
                 ``grpc-status-details-bin`` payload), Metadata
                 carrier, the unary server adapter
                 (``GrpcRequestHeaders`` typed request-headers
                 carrier -> ``GrpcUnaryReply`` typed handler return
                 (``ok`` / ``err`` factories) -> ``run_unary_call``
                 never-raises orchestrator that maps header / LPM /
                 handler failures to typed ``INVALID_ARGUMENT`` /
                 ``INTERNAL`` outcomes), and a ``GrpcClient`` that
                 drives unary RPCs over the ``HttpClient`` HTTP/2 path
                 plus server- / client- / bidi-streaming RPCs
                 (``GrpcServerStream`` / ``GrpcBidiStream``) that
                 surface LPM messages incrementally on a long-lived
                 HTTP/2 stream
flare.openapi  - OpenAPI 3.1 spec model + deterministic JSON emitter
flare.quic     - Sans-I/O QUIC v1 codec primitives (varint, long /
                 short packet headers, all 22 RFC 9000 §19 transport
                 frames dispatched via the ``FrameHandler`` trait +
                 ``parse_frame_into[H]`` (per-type callbacks; no
                 intermediate union carrier), with per-type
                 ``encode_*(payload, mut out: List[UInt8])`` writers,
                 RFC 9000 §18 transport parameters, and RFC 9000 §3 /
                 §13 connection + stream state machines, plus the live
                 ``QuicListener`` UDP reactor, the ``QuicClientConnection``
                 client driver (incl. resumption + 0-RTT EarlyData
                 send flight, NEW_TOKEN, ECN, ACK_FREQUENCY and path-MTU
                 discovery), and the rustls QUIC TLS drive that
                 carry HTTP/3 end-to-end
flare.http3       - Sans-I/O HTTP/3 frame codec, SETTINGS payload,
                 request-stream reader (``Http3RequestReader`` +
                 ``Http3RequestEventHandler`` + ``feed_into[H]`` --
                 typed ``on_headers`` / ``on_data`` / ``on_trailers``
                 callbacks), response-stream writer with QPACK-
                 encoded field sections and the ``mut out:
                 List[UInt8]`` buffer-reuse contract (RFC 9114 §4 +
                 §7), plus the client side: ``Http3ClientConnection``
                 (request writer + response reader over the QUIC
                 client driver) for end-to-end HTTP/3 requests,
                 including ``fetch_0rtt`` -- idempotent-method-only
                 0-RTT: emits the request in the first EarlyData flight
                 on a resumed connection and transparently replays it
                 at 1-RTT if the server rejects early data
flare.qpack    - Sans-I/O static-only QPACK encoder / decoder for
                 HTTP/3 field sections (RFC 9204 Appendix A static
                 table + literal + Huffman, shared with HPACK)
flare.crypto   - HMAC-SHA256, base64url
flare.tls      - TLS 1.2/1.3 (OpenSSL, client + server, ALPN, session resumption,
                 SNI certificates, certificate hot reload)
flare.tcp      - TcpStream + TcpListener (IPv4 + IPv6)
flare.udp      - UdpSocket (IPv4 + IPv6)
flare.uds      - UnixListener + UnixStream (AF_UNIX sidecar IPC);
                 FrameMux / FrameDemux multiplex logical streams over
                 one UnixStream (encode_frame / decode_frame)
flare.dns      - getaddrinfo (dual-stack) + an additive TTL
                 ``DnsCache`` over the sync resolver, plus an
                 off-reactor ``resolve_async`` (getaddrinfo on a pool
                 thread) and ``order_happy_eyeballs`` address ordering
flare.net      - IpAddr, SocketAddr, RawSocket
flare.runtime  - Reactor (kqueue / epoll, opt-in io_uring on Linux),
                 TimerWheel, Scheduler, HandoffQueue +
                 WorkerHandoffPool, BufferPool, vectored I/O
flare.testing  - TestClient[H] (in-process handler exerciser) +
                 fork_server / kill_forked_server for integration tests
flare.utils    - POSIX FFI thunks (fork / waitpid / kill / usleep /
                 exit / getpid) the Mojo stdlib doesn't expose yet
```

Each layer mostly imports from layers below it. The runtime
scheduler is generic over a ``Frontend`` trait so that
``flare.runtime`` no longer imports from ``flare.http``; the HTTP
worker bring-up lives in ``flare.http.multicore`` and plugs into
the scheduler via that trait. ``flare.http`` still re-imports
``flare.http2`` for the unified reactor dispatch (the only
remaining intra-http cycle, tracked as cleanup in the source).

## HTTP requests

```mojo
from flare.http import get, post

def main() raises:
    var resp = get("https://httpbin.org/get")
    print(resp.status, resp.ok()) # 200 True

    var r = post("https://httpbin.org/post", '{"hello": "flare"}')
    r.raise_for_status()
    var data = r.json()
    print(data["json"]["hello"].string_value())
```

``post`` with a String body sets ``Content-Type: application/json``
automatically.

The server-side sections below build gradually: each one adds one new
concept on top of the previous example.

## Routing: ``Router``

One event loop (kqueue on macOS, epoll on Linux), non-blocking sockets,
a per-connection state machine, a hashed timing wheel for idle
timeouts. Routes carry path parameters (``:name``) and methods;
unknown paths return 404, known paths with the wrong method return 405
with an auto-generated ``Allow:`` header.

```mojo
from flare.http import Router, Request, Response, ok, HttpServer
from flare.net import SocketAddr

def home(req: Request) raises -> Response:
    return ok("home")

def get_user(req: Request) raises -> Response:
    return ok("user " + req.param("id"))

def create_user(req: Request) raises -> Response:
    return ok("created")

def main() raises:
    var r = Router()
    r.get("/", home)
    r.get("/users/:id", get_user)
    r.post("/users", create_user)

    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve(r^)
```

## Typed inputs: ``Extracted[H]``

Declare the handler's extractors as the fields of a ``Handler`` struct
and wrap it in ``Extracted[H]``. The adapter reflects on the struct's
field types at compile time to pull each one from the request before
calling the inner ``serve``. Parse failures become automatic 400
responses; ``serve`` is only reached when every field has a value of
the right type.

```mojo
from flare.http import (
    Router, Handler, Request, Response, ok, HttpServer,
    Extracted, PathInt, OptionalQueryInt, HeaderStr,
)
from flare.net import SocketAddr

@fieldwise_init
struct GetUser(Copyable, Defaultable, Handler):
    var id: PathInt["id"]
    var page: OptionalQueryInt["page"]
    var auth: HeaderStr["Authorization"]

    def __init__(out self):
        self.id = PathInt["id"]()
        self.page = OptionalQueryInt["page"]()
        self.auth = HeaderStr["Authorization"]()

    def serve(self, req: Request) raises -> Response:
        return ok("user=" + String(self.id.value))

def main() raises:
    var r = Router()
    r.get("/users/:id", Extracted[GetUser]())
    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve(r^)
```

The concrete ``PathInt`` / ``PathStr`` / ``QueryInt`` / ``HeaderStr``
/ etc. extractors expose ``.value`` directly as the parsed primitive.
Custom types are handled by writing your own ``Extractor`` struct.
Value-constructor extractors (``PathInt["id"].extract(req)``) are
also available for use inside plain ``def`` handlers when the
struct shape is overkill.

## Static route tables: ``ComptimeRouter``

Same routing surface as ``Router``, but the route list is a
compile-time value. Segment parsing happens at build time and the
dispatch loop unrolls per route, so the runtime does zero
string-compares on unknown paths.

```mojo
from flare.http import (
    ComptimeRoute, ComptimeRouter, Request, Response, Method, ok, HttpServer,
)
from flare.net import SocketAddr

def home(req: Request) raises -> Response:
    return ok("home")

def get_user(req: Request) raises -> Response:
    return ok("user=" + req.param("id"))

def create_user(req: Request) raises -> Response:
    return ok("created")

comptime ROUTES: List[ComptimeRoute] = [
    ComptimeRoute(Method.GET, "/", home),
    ComptimeRoute(Method.GET, "/users/:id", get_user),
    ComptimeRoute(Method.POST, "/users", create_user),
]

def main() raises:
    var r = ComptimeRouter[ROUTES]()
    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve(r^)
```

## Shared state via captured handlers

When a handler needs application-scoped state, build a wrapping
``Handler`` struct that captures the state by value. Middleware
itself is a ``Handler`` that holds another ``Handler``, so you
stack layers by nesting constructors, no callback chain to
thread through.

```mojo
from flare.http import Router, Request, Response, Handler, ok, HttpServer
from flare.net import SocketAddr

@fieldwise_init
struct Counters(Copyable):
    var hits: Int

def home(req: Request) raises -> Response:
    return ok("home")

@fieldwise_init
struct WithHits[Inner: Handler](Handler):
    var inner: Self.Inner
    var counters: Counters

    def serve(self, req: Request) raises -> Response:
        var resp = self.inner.serve(req).lower()
        resp.headers.set("X-Hits", String(self.counters.hits))
        return resp^

def main() raises:
    var router = Router()
    router.get("/", home)

    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve(WithHits(inner=router^, counters=Counters(hits=37)))
```

## Scale knob: ``num_workers``

Every server example above takes an optional ``num_workers``. At
``1`` (the default) it's the single-threaded reactor. Set it to
``default_worker_count()`` and flare runs N workers,
each with its own reactor + timer wheel, with per-core pinning
on Linux. The handler type is unchanged.

By default each worker binds its own ``SO_REUSEPORT``
listener (the kernel hashes new 4-tuples to one of N
listeners; matches actix_web's listener strategy and gives
the highest steady-state throughput on dev-box workloads).
Export ``FLARE_REUSEPORT_WORKERS=0`` before launch to
opt back into the single shared listener with
``EPOLLEXCLUSIVE`` -- 7-22 % less req/s (handler vs static
fast path) for a uniformly tighter p99.99 σ under sustained
load (the kernel offers each accept event to whichever
worker is currently parked in ``epoll_wait``, so idle
workers absorb spikes). See [``docs/benchmark.md``](../docs/benchmark.md)
for the head-to-head numbers and the rationale.

```mojo
from flare.http import HttpServer, Router, Request, Response, ok
from flare.net import SocketAddr
from flare.runtime import default_worker_count

def hello(req: Request) raises -> Response:
    return ok("hello")

def main() raises:
    var r = Router()
    r.get("/", hello)
    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve(r^, num_workers=default_worker_count())
```

``pin_cores=True`` (default) pins worker N to core ``N % num_cpus()``
on Linux and is a no-op on macOS. Upper bound on ``num_workers`` is
256.

## Fixed-body endpoints: ``serve_static``

For endpoints that always return the same bytes (health checks, TFB
plaintext, single-URL microservices), ``precompute_response`` builds
the full HTTP wire form at startup and ``HttpServer.serve_static``
runs a specialised reactor that skips the parser's Request-construction
and handler-dispatch step entirely.

```mojo
from flare.http import HttpServer, precompute_response
from flare.net import SocketAddr

def main() raises:
    var resp = precompute_response(
        status=200,
        content_type="text/plain; charset=utf-8",
        body="Hello, World!",
    )
    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    srv.serve_static(resp)
```

Keep-alive and ``Connection: close`` wire forms are both pre-encoded;
the reactor picks the right one per request from the parsed Connection
header. ``serve_static(resp, num_workers=N)`` fans the same fast path
out across ``N`` worker threads, each with its own listener.

## Comptime config checks

``ServerConfig.check[config]()`` validates a comptime ``ServerConfig``
through Mojo ``comptime assert`` so misconfigured servers fail the
build rather than the first request:

```mojo
from flare.http import HttpServer, Request, Response, ok
from flare.http.handler import FnHandler
from flare.http.server import ServerConfig
from flare.net import SocketAddr

def hello(req: Request) raises -> Response:
    return ok("hello")

comptime CONFIG: ServerConfig = ServerConfig(
    max_header_size=4096,
    max_body_size=64 * 1024, # must be >= max_header_size (compile time)
    max_keepalive_requests=1000,
    idle_timeout_ms=30_000,
)

def main() raises:
    ServerConfig.check[CONFIG]()
    var srv = HttpServer.bind(SocketAddr.localhost(8080), materialize[CONFIG]())
    srv.serve(FnHandler(hello))
```

Break any invariant (e.g. ``max_body_size < max_header_size``) and Mojo
rejects the build with a pointed error. The impossible state doesn't
compile, so no runtime guard is needed.

## HTTP client with auth

```mojo
from flare.http import HttpClient, BasicAuth, BearerAuth

def main() raises:
    var client = HttpClient("https://api.example.com", BearerAuth("tok_abc"))
    var items = client.get("/items").json()
    client.post("/items", '{"name": "new"}').raise_for_status()
```

## HTTP/2: same client, same server, version-aware

There is no separate ``Http2Client`` / ``Http2Server`` to learn:
the same :class:`flare.http.HttpClient` and
:class:`flare.http.HttpServer` are HTTP-version-aware internally.

```mojo
from flare.http import HttpClient

def main() raises:
    # https:// auto-negotiates via TLS+ALPN. If the server picks
    # h2 the request is driven through HTTP/2 internally; if it
    # picks http/1.1 (or doesn't speak ALPN at all) the
    # existing HTTP/1.1 wire is used. Either way you get a
    # flare.http.Response back.
    with HttpClient() as c:
        var r = c.get("https://nghttp2.org/")
        print(r.status, r.text())

    # http:// is HTTP/1.1 by default; opt into HTTP/2 cleartext
    # via prior knowledge with prefer_h2c=True:
    with HttpClient(prefer_h2c=True, base_url="http://localhost:8080") as c:
        var r = c.get("/api/users")
        r.raise_for_status()

    # https:// can prefer HTTP/3 over QUIC with prefer_http3=True. The
    # same call site applies; an idempotent GET races h3 against h2/h1
    # (happy-eyeballs) and any QUIC failure falls back transparently:
    with HttpClient(prefer_http3=True, base_url="https://cloudflare.com") as c:
        var r = c.get("/")
        print(r.status, r.text())
```

The client surface is additive and composable: ``with_redirect_policy``,
``with_retry``, ``with_cookies``, and ``with_pool`` chain off the
constructor, and ``auto_decompress`` (default on) transparently decodes
``gzip`` / ``deflate`` / ``br`` responses. The H3 / QUIC client drivers
stay internal -- you reach HTTP/3 through ``HttpClient``, never a
separate type.

The server side is symmetric -- one accept loop dispatches both
wires per connection (preface peek for cleartext, ALPN ``h2``
for TLS):

```mojo
from flare.http import HttpServer, Request, Response, ok
from flare.net import SocketAddr

def hello(req: Request) raises -> Response:
    return ok("hi")

def main() raises:
    var srv = HttpServer.bind(SocketAddr.localhost(8080))
    # The same handler is dispatched whether the client speaks
    # HTTP/1.1 or HTTP/2 over the same port.
    srv.serve(hello, num_workers=4)
```

## WebSocket

```mojo
from flare.ws import WsClient

def main() raises:
    with WsClient.connect("ws://echo.websocket.events") as ws:
        ws.send_text("hello")
        var msg = ws.recv_message()
        if msg.is_text:
            print(msg.as_text())
```

## Cookies

```mojo
from flare.http import Cookie, CookieJar, parse_set_cookie_header

def main() raises:
    var jar = CookieJar()
    jar.set(Cookie("session", "abc123", secure=True, http_only=True))
    print(jar.to_request_header()) # session=abc123

    var c = parse_set_cookie_header("id=42; Path=/; Max-Age=3600")
    print(c.name, c.value, c.max_age) # id 42 3600
```

## Low-level API

### IP addresses and DNS

```mojo
from flare.net import IpAddr, SocketAddr
from flare.dns import resolve

def main() raises:
    var ip = IpAddr.parse("192.168.1.100")
    print(ip.is_private()) # True

    var addr = SocketAddr.parse("[::1]:8080")
    print(addr.ip.is_v6(), addr.port) # True 8080

    var addrs = resolve("example.com") # returns both IPv4 and IPv6
    print(addrs[0])
```

### TCP

```mojo
from flare.tcp import TcpStream

def main() raises:
    var conn = TcpStream.connect("localhost", 8080)
    _ = conn.write("Hello\n".as_bytes())

    var buf = List[UInt8](capacity=4096)
    buf.resize(4096, 0)
    var n = conn.read(buf.unsafe_ptr(), len(buf))
    conn.close()
```

### TLS

```mojo
from flare.tls import TlsStream, TlsConfig

def main() raises:
    var tls = TlsStream.connect("example.com", 443, TlsConfig())
    _ = tls.write("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n".as_bytes())
    tls.close()
```

### WebSocket frames

```mojo
from flare.ws import WsClient, WsFrame

def main() raises:
    var ws = WsClient.connect("ws://echo.websocket.events")
    ws.send_text("ping")
    var frame = ws.recv()
    print(frame.text_payload())
    ws.close()
```

### Reactor (advanced)

```mojo
from flare.runtime import Reactor, Event, INTEREST_READ

def main() raises:
    var r = Reactor()
    # Register a non-blocking fd; see ``Reactor`` docs for a full example.
```