Home /Modules/http-3.0/test_http3_flow.py

test_http3_flow.py

http-3.0/test_http3_flow.py · 269 line(s) · py

"""Tests for the HTTP 3.0 data-flow reference (spec §4/§5/§7/§9).

Runs with either pytest or plain `python3 test_http3_flow.py`. Exercises the
pure-data protocol surface (envelope, naming, response, pipeline, retry
classes) implemented in http3_flow.py. Crypto is intentionally out of scope
here — it lives in the C substrate (crypto_openssl.c et al.).
"""
from __future__ import annotations

from http3_flow import (
    Envelope, Flag, Intactx, Naming, Pipeline, Response, RetryClass, Status,
    INTACTX_VARIANCE_SHIFT, INTACTX_VARIANCE_MASK, INTACTX_TAMPER_THRESHOLD,
    MAC_KEY_BYTES, siphash24,
    BASKET, BASKET_ITEMS, BASKET_BLOCK_SIZE, BASKET_ISO_NUMERIC,
    basket_serialize, basket_parse,
)

# A fixed per-connection key for tests (0x00..0x0f).
KEY = bytes(range(16))


def test_siphash24_reference_vector() -> None:
    # Reference vector from the SipHash paper: key 00..0f, msg 00..0e (15 bytes).
    msg = bytes(range(15))
    assert siphash24(KEY, msg) == 0xA129CA6149BE45E5


def test_envelope_text_round_trip() -> None:
    env = Envelope(service_id=7, op_id=3, request_id=1001, payload=b"20,22", nonce=5)
    wire = env.pack_text(KEY)
    # Wire carries NONCE, keyed DIGEST, INTACTX, and the BASKET (hex) before length.
    basket_hex = env.basket.hex()
    assert wire == f"H3 3 0 7 3 1001 5 {env.digest} 0 {basket_hex} 5:".encode() + b"20,22\n"
    back = Envelope.unpack_text(wire)
    assert (back.service_id, back.op_id, back.request_id, back.payload) == (7, 3, 1001, b"20,22")
    assert back.nonce == 5 and back.digest == env.digest and back.intactx == 0
    assert back.basket == env.basket
    assert back.verify_digest(KEY)


def test_digest_is_keyed_mac_detects_corruption_and_forgery() -> None:
    env = Envelope(service_id=1, op_id=1, request_id=5, payload=b"20,22").seal(KEY)
    assert env.verify_digest(KEY)
    back = Envelope.unpack_text(env.pack_text(KEY))
    assert back.verify_digest(KEY)
    # Corruption: change the payload after sealing -> MAC no longer verifies.
    back.payload = b"90,22"
    assert not back.verify_digest(KEY)
    # Forgery: a packet sealed under a DIFFERENT key fails under the real key,
    # which a plain hash could not detect. This is the keyed-MAC guarantee.
    forged = Envelope(service_id=1, op_id=1, request_id=5, payload=b"20,22").seal(bytes(range(16, 32)))
    assert not forged.verify_digest(KEY)


def test_basket_serialize_round_trip_and_size() -> None:
    block = basket_serialize()
    assert len(block) == BASKET_BLOCK_SIZE == 4 + 14 * 12 == 172
    iso, items = basket_parse(block)
    assert iso == BASKET_ISO_NUMERIC == 840
    assert len(items) == BASKET_ITEMS == 14
    # Parsed (number, value) pairs match the fixed basket table.
    assert items == [(n, v) for (n, v, _name) in BASKET]


def test_basket_travels_and_is_mac_covered() -> None:
    # The basket rides on every packet by default and is inside the MAC:
    # altering it invalidates the DIGEST.
    env = Envelope(service_id=1, op_id=1, request_id=9, payload=b"x", nonce=1).seal(KEY)
    assert env.basket == basket_serialize()
    assert env.verify_digest(KEY)
    back = Envelope.unpack_text(env.pack_text(KEY))
    assert back.basket == env.basket and back.verify_digest(KEY)
    # Tamper one byte of the basket after sealing -> MAC no longer verifies.
    tampered = bytearray(env.basket)
    tampered[10] ^= 0x01
    env.basket = bytes(tampered)
    assert not env.verify_digest(KEY)


def test_intactx_variance_layout_and_tamper() -> None:
    # Variance sits in the high bits; a larger variance is a larger number.
    low = (1 << INTACTX_VARIANCE_SHIFT) | 0xABC
    high = (INTACTX_VARIANCE_MASK << INTACTX_VARIANCE_SHIFT) | 0xABC
    assert high > low
    assert Intactx.variance(high) == INTACTX_VARIANCE_MASK
    assert not Intactx.is_tampered(low, INTACTX_TAMPER_THRESHOLD)
    assert Intactx.is_tampered(high, INTACTX_TAMPER_THRESHOLD)


def test_pipeline_rejects_bad_digest_forgery_and_resets_tampered() -> None:
    pipe = Pipeline(mac_key=KEY)

    def echo(payload: bytes, ctx: object):
        return Status.OK, payload

    sid, oid = pipe.register("svc", "echo", RetryClass.READ, echo)

    # A packet with a tampered digest field is rejected before dispatch.
    env = Envelope(sid, oid, 7001, b"hi").seal(KEY)
    env.digest ^= 0xFF  # tamper the digest field
    assert Response.unpack_text(pipe.handle_wire(env.pack_text())).status == Status.BAD_DIGEST
    assert pipe.digest_rejects == 1

    # A forged packet (sealed with the WRONG key) is rejected by the pipeline.
    forged = Envelope(sid, oid, 7003, b"hi").seal(bytes(range(16, 32)))
    assert Response.unpack_text(pipe.handle_wire(forged.pack_text())).status == Status.BAD_DIGEST
    assert pipe.digest_rejects == 2

    # A packet from a tampered host (max variance) is RESET, not dispatched.
    tampered_intactx = (INTACTX_VARIANCE_MASK << INTACTX_VARIANCE_SHIFT) | 0x1234
    env2 = Envelope(sid, oid, 7002, b"hi", flags=int(Flag.RESET), intactx=tampered_intactx).seal(KEY)
    resp = Response.unpack_text(pipe.handle_wire(env2.pack_text()))
    assert resp.status == Status.TAMPERED and resp.result == b"RESET"
    assert pipe.tamper_resets == 1


def test_timing_advisory_flags_and_certainty() -> None:
    from http3_flow import TIMING_OVER_RATE, TIMING_LATE, TIMING_OK
    pipe = Pipeline(mac_key=KEY)
    pipe.set_timing(1000, 50_000_000, 10_000_000)  # 1us min gap, 50ms grace, 10ms band
    base, step = 1_000_000_000, 10_000_000
    last = base
    # A well-paced, on-time stream raises no flags.
    for k in range(6):
        at = base + k * step
        assert pipe.observe_timing(at, at) == TIMING_OK
        last = at
    assert pipe.late_packets == 0 and pipe.over_rate_packets == 0
    # A burst (100ns after the previous packet) is flagged OVER_RATE (advisory).
    last += 100
    assert pipe.observe_timing(last, 0) & TIMING_OVER_RATE
    assert pipe.over_rate_packets == 1
    # A packet well past its deadline is flagged LATE.
    assert pipe.observe_timing(last + 100 * step, last) & TIMING_LATE
    assert pipe.late_packets == 1
    # Certainty is a running estimate in [0,1], dented by the two bad packets.
    c = pipe.carrier_certainty()
    assert 0.0 <= c <= 1.0 and c < 1.0
    # Timing is advisory: it never rejects, so no packet turned into a response here.


def test_handshake_highest_common_level_and_baseline_fallback() -> None:
    from http3_flow import (
        CapOffer, handshake_resolve, handshake_negotiate,
        CAP_ALL, CAP_NONE, CAP_L1_BASE, CAP_L2_PERLEG, CAP_L3_PACING, CAP_L4_ECHO,
    )
    # A fully-updated peer and an older baseline-only router negotiate down to L1.
    full = CapOffer.make(CAP_ALL, KEY)
    old = CapOffer.make(CAP_L1_BASE, KEY)  # not yet updated
    assert handshake_resolve(full, old, KEY) == CAP_L1_BASE
    # Two current peers reach the top level.
    assert handshake_resolve(full, full, KEY) == CAP_L4_ECHO
    # Highest COMMON level: L3-capable peer vs full -> L3.
    l3 = CapOffer.make(CAP_L1_BASE | CAP_L2_PERLEG | CAP_L3_PACING, KEY)
    assert handshake_resolve(full, l3, KEY) == CAP_L3_PACING
    # make() always folds in the baseline (even if omitted).
    assert CapOffer.make(0, KEY).capabilities & CAP_L1_BASE
    # A tampered offer fails verification.
    forged = CapOffer.make(CAP_ALL, KEY)
    forged.capabilities = CAP_L1_BASE  # change caps after MAC was stamped
    try:
        handshake_resolve(forged, full, KEY)
        assert False, "expected MAC failure"
    except ValueError:
        pass
    # A peer lacking the baseline (non-conforming) negotiates to NONE.
    assert handshake_negotiate(CAP_L2_PERLEG, CAP_L2_PERLEG) == CAP_NONE


def test_pipeline_rejects_replayed_nonce() -> None:
    pipe = Pipeline(mac_key=KEY)

    def echo(payload: bytes, ctx: object):
        return Status.OK, payload

    sid, oid = pipe.register("svc", "echo", RetryClass.READ, echo)

    # A fresh packet (nonce ahead of high-water) is accepted.
    wire = Envelope(sid, oid, 8001, b"hi", nonce=1).pack_text(KEY)
    assert Response.unpack_text(pipe.handle_wire(wire)).status == Status.OK
    # The exact same wire bytes resent (same nonce) is rejected as a replay.
    assert Response.unpack_text(pipe.handle_wire(wire)).status == Status.REPLAYED
    assert pipe.replays_rejected == 1
    # A stale nonce (<= high-water) is also rejected; a higher one is accepted.
    assert Response.unpack_text(
        pipe.handle_wire(Envelope(sid, oid, 8002, b"hi", nonce=1).pack_text(KEY))
    ).status == Status.REPLAYED
    assert Response.unpack_text(
        pipe.handle_wire(Envelope(sid, oid, 8003, b"hi", nonce=2).pack_text(KEY))
    ).status == Status.OK


def test_envelope_payload_is_length_prefixed_and_binary_safe() -> None:
    # A payload containing spaces and a newline must survive the round trip.
    payload = b"a b\nc:d"
    env = Envelope(service_id=1, op_id=1, request_id=5, payload=payload)
    back = Envelope.unpack_text(env.pack_text(KEY))
    assert back.payload == payload
    assert back.verify_digest(KEY)


def test_response_round_trip_echoes_request_id() -> None:
    resp = Response(Status.OK, request_id=1001, result=b"sum=42")
    back = Response.unpack_text(resp.pack_text())
    assert back.status == Status.OK
    assert back.request_id == 1001
    assert back.result == b"sum=42"


def test_fast_naming_caches_ids_on_first_use() -> None:
    naming = Naming()
    assert naming.intern_service("orders") == 1
    assert naming.intern_service("orders") == 1  # cached, same id
    assert naming.intern_service("billing") == 2
    # op ids are local to a service and start at 1
    assert naming.intern_op("orders", "calculate") == 1
    assert naming.intern_op("orders", "place") == 2
    assert naming.intern_op("orders", "calculate") == 1  # cached


def test_pipeline_dispatch_and_retry_classes() -> None:
    pipe = Pipeline(mac_key=KEY)

    def calculate(payload: bytes, ctx: object):
        a, b = (int(x) for x in payload.decode().split(","))
        return Status.OK, f"sum={a + b}".encode()

    def place(payload: bytes, ctx: object):
        ctx["n"] += 1
        return Status.OK, f"order_id={ctx['n']}".encode()

    sid, calc = pipe.register("orders", "calculate", RetryClass.READ, calculate)
    _, place_id = pipe.register("orders", "place", RetryClass.MUTATING, place, ctx={"n": 0})

    # §19 over the wire, textual (packet sealed with the pipeline's shared key;
    # NONCE must be ahead of the pipeline's high-water mark to be accepted).
    out = pipe.handle_wire(Envelope(sid, calc, 1001, b"20,22", nonce=1).pack_text(KEY))
    resp = Response.unpack_text(out)
    assert resp.status == Status.OK and resp.request_id == 1001 and resp.result == b"sum=42"

    # §9 retry classes.
    assert pipe.retry_class(sid, calc) == RetryClass.READ
    assert pipe.retry_class(sid, place_id) == RetryClass.MUTATING

    # §7 posture: unknown service / operation.
    assert pipe.dispatch(Envelope(999, 1, 2002)).status == Status.UNKNOWN_SERVICE
    assert pipe.dispatch(Envelope(sid, 999, 2003)).status == Status.UNKNOWN_OPERATION

    # bad envelope -> typed status, no crash.
    assert Response.unpack_text(pipe.handle_wire(b"not-an-envelope")).status == Status.BAD_ENVELOPE


def _run_all() -> int:
    failures = 0
    for name, fn in sorted(globals().items()):
        if name.startswith("test_") and callable(fn):
            try:
                fn()
                print(f"  [ok]   {name}")
            except AssertionError as exc:  # pragma: no cover - manual runner
                print(f"  [FAIL] {name}: {exc}")
                failures += 1
    print("HTTP 3.0 flow tests:", "PASS" if failures == 0 else f"FAIL ({failures})")
    return failures


if __name__ == "__main__":
    raise SystemExit(_run_all())