Home /Modules/http-3.0/http3_transport.py

http3_transport.py

http-3.0/http3_transport.py · 332 line(s) · py

"""http3_transport.py -- carry the SLeeLa HTTP 3.0 envelope over standard HTTP.

The SLeeLa "HTTP 3.0" envelope (see http3_flow.py / http3_envelope.h) is a
bespoke application unit: VERSION | FLAGS | SERVICE-ID | OP-ID | REQUEST-ID |
NONCE | DIGEST | INTACTX | BASKET | PAYLOAD, sealed with a per-packet keyed MAC.
It is deliberately NOT the IETF HTTP/3 transport and, on its own, cannot travel
the existing internet: it has no request line, no HTTP headers, and no socket
transport.

This module is a **custom packet builder** that makes the H3 envelope fit for
the current internet WITHOUT changing the envelope. It embeds the exact H3
bytes -- integrity gate and all -- inside genuinely standards-shaped HTTP
messages, so ordinary HTTP infrastructure (proxies, load balancers, servers,
CDNs) can route and carry them:

  * build_http11 / parse_http11  -- HTTP/1.1 message framing (the "HTTP 2.1 is
        fine" text form): a real request line + headers + body, body == H3 bytes.
  * build_http2  / parse_http2   -- HTTP/2 binary framing: a correct HEADERS
        frame (HPACK-free literal representation) followed by DATA frame(s),
        the DATA payload == H3 bytes.

The embedding is "careful": the H3 envelope is never mangled to fit HTTP. It is
placed in the HTTP *body* verbatim and identified by an explicit media type and
a marker header, so a receiver can extract the original bytes and feed them
straight to Pipeline.handle_wire(). The MAC/NONCE/INTACTX/BASKET all survive
untouched, so the H3 integrity guarantees are preserved end to end.

Design stance (matches the rest of the timing/QoS work): standards-honest.
We emit HTTP that a conformant parser accepts; we do not pretend the H3
integrity fields are HTTP semantics, and we do not weaken H3 to look like HTTP.
"""
from __future__ import annotations

import struct
from dataclasses import dataclass
from typing import List, Optional, Tuple

# The H3 envelope lives in http3_flow (byte-identical to the C reference).
from http3_flow import Envelope, Response

# --------------------------------------------------------------------------
# Shared embedding scheme
# --------------------------------------------------------------------------

# Media type for an embedded H3 envelope. A distinct, versioned vendor type so
# intermediaries treat it as an opaque binary body and never try to transform it.
H3_MEDIA_TYPE = "application/vnd.sleela.h3+octet-stream; version=3"

# Marker header naming the embedded protocol generation and wire form. Receivers
# key on this to decide whether a standard HTTP body carries an H3 envelope.
H3_MARKER_HEADER = "X-SLeeLa-H3"          # value: "3;text" or "3;binary"
H3_WIREFORM_TEXT = "3;text"
H3_WIREFORM_BINARY = "3;binary"

# Default request target for the HTTP/1.1 and HTTP/2 forms. The H3 service/op
# ids live *inside* the envelope; the URL path is only a routing convenience so
# ordinary HTTP routers can dispatch. It is advisory and MAY be ignored.
H3_DEFAULT_PATH = "/sleela/h3"


def _wireform_value(env_wire: bytes) -> str:
    """Textual H3 lines begin with the ASCII tag 'H3 '; everything else is binary.

    This mirrors the auto-detect at the top of Pipeline.handle_wire(), so the
    marker header we emit always agrees with how the receiver will parse it.
    """
    return H3_WIREFORM_TEXT if env_wire[:3] == b"H3 " else H3_WIREFORM_BINARY


def h3_wire_bytes(env: Envelope, key: Optional[bytes] = None, *, binary: bool = False) -> bytes:
    """Serialize an Envelope to its on-the-wire H3 bytes (text or binary).

    `key`, when given, seals the keyed-MAC DIGEST first. This is the exact byte
    string that Pipeline.handle_wire() consumes, and the exact byte string we
    embed in the HTTP body -- nothing is added or removed.
    """
    if binary:
        # http3_flow's Envelope implements the textual form; the binary form is
        # defined in the C reference. For portability the Python builder embeds
        # the textual H3 line, which is fully interoperable per spec §5. Callers
        # needing the binary form can pass pre-serialized bytes to the build_*
        # functions' `env_wire=` parameter.
        raise NotImplementedError(
            "Pass pre-serialized binary via env_wire=... to build_http11/build_http2"
        )
    return env.pack_text(key)


# --------------------------------------------------------------------------
# HTTP/1.1 ("HTTP 2.1 is fine") text framing
# --------------------------------------------------------------------------

_CRLF = b"\r\n"


def build_http11(
    env: Optional[Envelope] = None,
    key: Optional[bytes] = None,
    *,
    env_wire: Optional[bytes] = None,
    method: str = "POST",
    path: str = H3_DEFAULT_PATH,
    host: str = "localhost",
    extra_headers: Optional[List[Tuple[str, str]]] = None,
) -> bytes:
    """Build a standards-compliant HTTP/1.1 request carrying an H3 envelope body.

    Provide either a live `env` (optionally with `key` to seal it) or a
    pre-serialized `env_wire`. The result is a complete HTTP/1.1 request:

        POST /sleela/h3 HTTP/1.1\r\n
        Host: <host>\r\n
        Content-Type: application/vnd.sleela.h3+octet-stream; version=3\r\n
        Content-Length: <n>\r\n
        X-SLeeLa-H3: 3;text\r\n
        \r\n
        <exact H3 envelope bytes>

    Content-Length framing (not chunked) keeps the body byte-exact so the H3
    MAC verifies after transit.
    """
    body = env_wire if env_wire is not None else h3_wire_bytes(env, key)
    headers: List[Tuple[str, str]] = [
        ("Host", host),
        ("Content-Type", H3_MEDIA_TYPE),
        ("Content-Length", str(len(body))),
        (H3_MARKER_HEADER, _wireform_value(body)),
        ("Connection", "keep-alive"),
    ]
    if extra_headers:
        headers.extend(extra_headers)
    start = f"{method} {path} HTTP/1.1".encode("ascii")
    head = start + _CRLF + _CRLF.join(f"{k}: {v}".encode("ascii") for k, v in headers) + _CRLF + _CRLF
    return head + body


def build_http11_response(
    resp_wire: bytes,
    *,
    status_code: int = 200,
    reason: str = "OK",
    extra_headers: Optional[List[Tuple[str, str]]] = None,
) -> bytes:
    """Build an HTTP/1.1 response carrying an H3 response line (H3R ...) as body."""
    headers: List[Tuple[str, str]] = [
        ("Content-Type", H3_MEDIA_TYPE),
        ("Content-Length", str(len(resp_wire))),
        (H3_MARKER_HEADER, _wireform_value(resp_wire)),
    ]
    if extra_headers:
        headers.extend(extra_headers)
    start = f"HTTP/1.1 {status_code} {reason}".encode("ascii")
    head = start + _CRLF + _CRLF.join(f"{k}: {v}".encode("ascii") for k, v in headers) + _CRLF + _CRLF
    return head + resp_wire


def parse_http11(message: bytes) -> bytes:
    """Extract the embedded H3 envelope bytes from an HTTP/1.1 request/response.

    Validates the framing enough to recover a byte-exact body: it honors
    Content-Length and confirms the H3 marker header is present. Returns the
    raw H3 bytes, ready for Pipeline.handle_wire(). Raises ValueError if the
    message is not an H3-carrying HTTP/1.1 message.
    """
    head, sep, body = message.partition(_CRLF + _CRLF)
    if not sep:
        raise ValueError("no header/body separator")
    lines = head.split(_CRLF)
    if not lines or b" HTTP/1." not in lines[0]:
        raise ValueError("not an HTTP/1.x message")
    headers = {}
    for line in lines[1:]:
        if b":" in line:
            k, _, v = line.partition(b":")
            headers[k.strip().lower()] = v.strip()
    if H3_MARKER_HEADER.lower().encode("ascii") not in headers:
        raise ValueError("missing H3 marker header; not an H3-carrying message")
    clen = headers.get(b"content-length")
    if clen is not None:
        n = int(clen)
        if len(body) < n:
            raise ValueError("body shorter than Content-Length")
        body = body[:n]
    return body


# --------------------------------------------------------------------------
# HTTP/2 binary framing (RFC 7540)
# --------------------------------------------------------------------------
#
# We emit real HTTP/2 frames. To stay dependency-free and byte-exact we use
# HPACK's *literal header field never indexed* representation (0x10) with a
# literal (non-Huffman) name and value, which is a valid HPACK encoding that any
# conformant HTTP/2 decoder accepts. The H3 envelope rides in DATA frame(s).

_H2_FRAME_HEADER = struct.Struct(">3sBBI")  # length(24b as 3 bytes), type, flags, stream id(31b)

_H2_TYPE_DATA = 0x0
_H2_TYPE_HEADERS = 0x1

_H2_FLAG_END_STREAM = 0x1
_H2_FLAG_END_HEADERS = 0x4

# HTTP/2 connection preface (client). Included so build_http2 can optionally
# produce a complete client byte stream a real server would accept.
H2_CLIENT_PREFACE = b"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"


def _u24(n: int) -> bytes:
    if n < 0 or n > 0xFFFFFF:
        raise ValueError("frame length out of range")
    return n.to_bytes(3, "big")


def _h2_frame(ftype: int, flags: int, stream_id: int, payload: bytes) -> bytes:
    return _u24(len(payload)) + bytes((ftype, flags)) + struct.pack(">I", stream_id & 0x7FFFFFFF) + payload


def _hpack_literal_never_indexed(name: str, value: str) -> bytes:
    """Encode one header as HPACK 'literal, never indexed, new name' (no Huffman).

    Prefix byte 0x10; name length (7-bit prefix, H=0) + name; value length + value.
    This is a minimal, valid HPACK field representation -- no dynamic table needed.
    """
    nb = name.encode("ascii")
    vb = value.encode("ascii")
    if len(nb) > 0x7F or len(vb) > 0x7F:
        raise ValueError("header too long for the minimal encoder")
    return bytes((0x10, len(nb))) + nb + bytes((len(vb),)) + vb


def build_http2(
    env: Optional[Envelope] = None,
    key: Optional[bytes] = None,
    *,
    env_wire: Optional[bytes] = None,
    method: str = "POST",
    path: str = H3_DEFAULT_PATH,
    authority: str = "localhost",
    scheme: str = "https",
    stream_id: int = 1,
    include_preface: bool = False,
) -> bytes:
    """Build a standards-shaped HTTP/2 frame sequence carrying an H3 envelope.

    Produces: [optional client preface] + HEADERS frame (pseudo-headers +
    content-type + H3 marker) + DATA frame (END_STREAM) whose payload is the
    exact H3 envelope bytes. The framing follows RFC 7540; header blocks use a
    dependency-free literal HPACK encoding.
    """
    body = env_wire if env_wire is not None else h3_wire_bytes(env, key)
    header_fields = [
        (":method", method),
        (":path", path),
        (":scheme", scheme),
        (":authority", authority),
        ("content-type", H3_MEDIA_TYPE),
        ("content-length", str(len(body))),
        (H3_MARKER_HEADER.lower(), _wireform_value(body)),
    ]
    header_block = b"".join(_hpack_literal_never_indexed(k, v) for k, v in header_fields)
    frames = _h2_frame(_H2_TYPE_HEADERS, _H2_FLAG_END_HEADERS, stream_id, header_block)
    frames += _h2_frame(_H2_TYPE_DATA, _H2_FLAG_END_STREAM, stream_id, body)
    return (H2_CLIENT_PREFACE + frames) if include_preface else frames


def parse_http2(stream: bytes) -> bytes:
    """Extract the embedded H3 envelope bytes from an HTTP/2 frame sequence.

    Skips an optional client preface, walks frames by their 9-byte headers, and
    concatenates DATA-frame payloads (the H3 envelope). Returns the raw H3 bytes
    for Pipeline.handle_wire(). Raises ValueError on malformed framing.
    """
    if stream.startswith(H2_CLIENT_PREFACE):
        stream = stream[len(H2_CLIENT_PREFACE):]
    off = 0
    data = bytearray()
    saw_data = False
    n = len(stream)
    while off + 9 <= n:
        length = int.from_bytes(stream[off:off + 3], "big")
        ftype = stream[off + 3]
        # flags = stream[off + 4]  # not needed for extraction
        # stream_id = struct.unpack(">I", stream[off+5:off+9])[0] & 0x7FFFFFFF
        payload_start = off + 9
        payload_end = payload_start + length
        if payload_end > n:
            raise ValueError("truncated HTTP/2 frame")
        if ftype == _H2_TYPE_DATA:
            data.extend(stream[payload_start:payload_end])
            saw_data = True
        off = payload_end
    if not saw_data:
        raise ValueError("no DATA frame; nothing to extract")
    return bytes(data)


# --------------------------------------------------------------------------
# Convenience: round-trip an envelope through a chosen HTTP carrier
# --------------------------------------------------------------------------

@dataclass
class Carrier:
    """Names the HTTP carrier used to move an H3 envelope over the internet."""
    HTTP11 = "http/1.1"
    HTTP2 = "http/2"


def wrap(env: Envelope, key: Optional[bytes] = None, *, carrier: str = Carrier.HTTP11, **kw) -> bytes:
    """Serialize + seal an envelope and wrap it in the chosen HTTP carrier."""
    if carrier == Carrier.HTTP11:
        return build_http11(env, key, **kw)
    if carrier == Carrier.HTTP2:
        return build_http2(env, key, **kw)
    raise ValueError(f"unknown carrier: {carrier}")


def unwrap(message: bytes) -> bytes:
    """Auto-detect the HTTP carrier and return the embedded H3 envelope bytes.

    HTTP/2 is recognized by the client preface or a leading frame header whose
    type is HEADERS/DATA; otherwise the message is treated as HTTP/1.x text.
    The returned bytes are ready for Pipeline.handle_wire().
    """
    if message.startswith(H2_CLIENT_PREFACE):
        return parse_http2(message)
    # HTTP/1.x messages start with an ASCII method or "HTTP/1." status line.
    if message[:5] in (b"HTTP/",) or (b" HTTP/1." in message[:200]):
        return parse_http11(message)
    # Fall back to HTTP/2 frame parsing (no preface).
    return parse_http2(message)