# flare.http.proto

> A module of flare_mlake's API.

``flare.http.proto`` -- pure-function HTTP wire codecs and parsers.

This package is the **sans-I/O** face of flare's HTTP stack. Every
module re-exported here is a pure-function library over byte spans
and Mojo values: no sockets, no reactor, no TLS context, no
filesystem access, no syscalls beyond what the Mojo stdlib pulls in
for ``String`` / ``List[UInt8]`` allocation. The strict contract:

- No imports from ``flare.runtime`` (reactor, scheduler, cancel,
  timers, handoff, pools, blocking helpers).
- No imports from ``flare.io`` (``BufReader``).
- No imports from ``flare.tcp`` / ``flare.udp`` / ``flare.uds``.
- No imports from ``flare.tls`` (OpenSSL FFI).
- No imports from ``flare.net`` (socket address resolution).

The contract is enforced statically by ``pixi run check-sans-io``
which scans every file registered in ``tests/tools/check_sans_io.sh``
for the forbidden import prefixes. Adding a file to the sans-I/O
list is a one-line change in that script.

## Why a separate namespace

The same parser modules feed multiple users: the reactor server,
the in-process ``TestClient``, fuzz harnesses, conformance test
runners, and downstream applications that want to embed flare's
parsers without pulling in the reactor. Today they live under
``flare.http.*`` next to reactor-coupled code; the layout buries
the boundary. ``flare.http.proto`` is the explicit, lint-enforced
public face for the parser-only surface.

## What lives here

This package re-exports the canonical sans-I/O modules from their
existing locations under ``flare.http.*`` and ``flare.http2.*``;
imports continue to work via either path. New pure-function
parsers added in future work land here directly.

```mojo
from flare.http.proto import (
    Cookie, CookieJar, parse_cookie_header,
    FormData, parse_form_urlencoded, urldecode, urlencode,
    MultipartForm, parse_multipart_form_data,
    Url, UrlParseError,
    HeaderMap, HeaderMapView,
    H2Frame, parse_h2_frame, encode_h2_frame,
    HpackEncoder, HpackDecoder,
    Http2Connection, H2Stream, H2StreamState,
)
```

The H1 message parser, multipart boundary scanner, URL
percent-decoder, cookie / Set-Cookie parser, HPACK encoder /
decoder, and HTTP/2 frame codec / connection state machine are
all sans-I/O. The reactor-bound dispatcher in
``flare.http.server`` calls into this layer; downstream users
embedding flare-as-parser can do the same.

## H1 leniency

The H1 parser accepts a handful of widely-deployed RFC 9110 /
RFC 9112 relaxations as opt-in flags. The ``H1LeniencyConfig``
carrier surfaces them; strict mode (the no-argument constructor)
is the default. Each flag wires to a specific parser branch in
:func:`flare.http.server._parse_http_request_bytes`. The legacy
``_ExperimentalH1LeniencyConfig`` alias remains importable for
back-compat.