Home /Modules/http-3.0/FLOW.md

FLOW.md

http-3.0/FLOW.md · 175 line(s) · markdown

HTTP 3.0 Data Flow — Spec → Code Map

This maps the data that drives the HTTP 3.0 spec (../http/spec/HTTP-3.0-SPEC.md) to the source in this directory, and traces one request end to end. Companion: STATUS.md.

The data, and where it lives

Spec conceptSectionType / symbolFile
Compact envelope§5http3_envelope_thttp3_envelope.h
├ VERSION / FLAGS§5version, flags (http3_envelope_flag_t)http3_envelope.h
├ SERVICE-ID / OP-ID§4/§5service_id, op_idhttp3_envelope.h
├ REQUEST-ID§6request_idhttp3_envelope.h
├ NONCE (replay guard)§5nonce (MAC-covered; pipeline high-water mark)http3_envelope.h / http3_pipeline.c
├ DIGEST (per-packet keyed MAC)§5digest + http3_envelope_compute_digest (SipHash-2-4, http3_mac.{h,c})http3_envelope.{h,c}
├ INTACTX (host-integrity id)§5intactx (http3_intactx_t)http3_intactx.{h,c}
├ BASKET (goods & services)§5basket (fixed 14-item block, ISO USD/g)http3_basket.{h,c}
└ PAYLOAD§5payload, payload_lenhttp3_envelope.h
Textual pack/unpack§5http3_envelope_pack_text / _unpack_texthttp3_envelope.c
Binary pack/unpack§5http3_envelope_pack_binary / _unpack_binaryhttp3_envelope.c
Fast-naming dictionary§4http3_naming_thttp3_naming.h
Name → compact id (cached)§4http3_naming_intern_service / _intern_ophttp3_naming.c
Id → name (dispatch/diag)§4http3_naming_service_name / _op_namehttp3_naming.c
Integrity gate (digest + tamper + replay)§19http3_pipeline_handle_wire (verify + reset + replay)http3_pipeline.c
INTACTX variance / tamper check§5http3_intactx_variance / _is_tamperedhttp3_intactx.c
Replay window (NONCE high-water)§19nonce_high_water + http3_pipeline_reset_replay_windowhttp3_pipeline.c
Timing: max speed / on time / balance / carrier certainty§19http3_timing_t + http3_pipeline_observe_timinghttp3_timing.{h,c} / http3_pipeline.c
Response model§7http3_response_t (status, request_id, result)http3_envelope.h
Application status§7http3_status_t (incl. BAD_DIGEST, TAMPERED, REPLAYED)http3_envelope.h
Retry classes§9http3_retry_class_thttp3_pipeline.h
Dispatch table§19http3_service_binding_t / http3_op_binding_thttp3_pipeline.h
Processing pipeline§19http3_pipeline_dispatch / http3_pipeline_handle_wirehttp3_pipeline.c
Governing principle (any client)§20http3_flow.py (Python parity)http3_flow.py

End-to-end trace (§19 hot path)

                         REQUEST
   name: service="orders", operation="calculate", payload="20,22"
        │
        ▼  §4 fast naming — resolve + cache compact ids
   http3_naming_intern_service("orders") -> 1
   http3_naming_intern_op("orders","calculate") -> 1
        │
        ▼  §5 build the compact envelope (NONCE + INTACTX, seals keyed DIGEST)
   intactx = http3_intactx_compute(&ix)
   http3_envelope_init(env, service_id=1, op_id=1, request_id=1001,
                       flags=0, nonce=1, intactx, mac_key, payload="20,22")
        │
        ▼  §5 pack to wire (textual OR binary). NONCE + DIGEST + INTACTX +
           BASKET (fixed 14-item block) all travel too.
   textual:  H3 3 0 1 1 1001 <nonce> <digest> <intactx> <basket-hex> 5:20,22
   binary :  03 01 00000001 00000001 00000000000003e9
             <nonce:8> <digest:8> <intactx:8> <basket:172> 00000005 32302c3232
        │
        ▼  §19 receive + minimal parse (auto-detect wire form)
   http3_pipeline_handle_wire(pipe, wire, len, out, ...)
        │      └─ http3_envelope_unpack_text/_binary -> env
        ▼  §19 integrity gate (BEFORE dispatch)
   verify keyed MAC   -> mismatch => BAD_DIGEST (corrupted OR forged; dropped)
   INTACTX variance   -> over threshold => TAMPERED + RESET (not dispatched)
   NONCE <= high-water => REPLAYED (replay of a valid packet; dropped)
        │
        ▼  §19 service-id lookup -> op-id lookup (dispatch table)
   http3_pipeline_dispatch(pipe, env, resp)
        │      └─ find_binding(service_id=1) -> find_op(op_id=1)
        ▼  §19 SLeeLa dispatch -> business logic
   handler(payload="20,22") -> status=OK, result="sum=42"
        │
        ▼  §7 pack response — STATUS | REQUEST-ID | RESULT
   H3R 0 1001 6:sum=42
                         RESPONSE

Key invariants surfaced by the flow:

Run it

cd http-3.0
make demo     # builds + runs the C flow demo (http3_pipeline_demo)
make test     # C demo + Python flow tests (test_http3_flow.py)
python3 test_http3_flow.py   # Python-only; verifies byte-identical wire

Relationship to the crypto substrate

The protocol core (http3_protocol.h: envelope + naming + pipeline) is independent of the cryptographic layer (http3_crypto.h: capsules, KDS, route sessions). They compose at deployment: the envelope/PAYLOAD is what a capsule/session would protect, and SERVICE/OP naming is what a route decision would carry — but neither layer depends on the other's build. This keeps the data-flow model and the security model separable, per the spec's boundary between application protocol (§1–§19) and transport/security infrastructure (§2, §12).

The one place the two layers touch by value (not by build) is the per-packet DIGEST key: the keyed MAC (http3_mac.{h,c}, SipHash-2-4) is a dependency-free part of the protocol core, but its 16-byte key is a per-connection secret that a deployment supplies from the crypto substrate's key agreement (crypto_key_agreement.*). The protocol core never links OpenSSL; it just accepts the key bytes, so the separation of builds is preserved while packets gain authenticity end to end.

Port and Stream Multiplexing

HTTP 3.0 extends the same architecture used by HTTP 2.1. QUIC/HTTP/3 supplies the transport-level stream multiplexing, while the SLeeLa envelope supplies the application-level logical port.

QUIC connection
      |
      +-- HTTP/3 stream 1 -- PORT -- SERVICE/OP -- payload
      +-- HTTP/3 stream 2 -- PORT -- SERVICE/OP -- payload
      +-- HTTP/3 stream N -- PORT -- SERVICE/OP -- payload

The namespaces remain separate:

transport endpoint → HTTP/3 stream → SLeeLa logical PORT → SERVICE-ID / OP-ID

The 20-byte PORT field documented in PORTS.md is therefore not a native TCP/UDP port field. It is a logical application identifier carried inside the SLeeLa envelope.

Download Mode for Files > 50 MB

HTTP 3.0 uses QUIC/HTTP/3 streams for transport multiplexing and the same SLeeLa DOWNLOAD contract for large files. A transfer is divided into indexed segments so an interrupted download can resume without restarting the complete file.

SESSION-ID | DATETIME | FILE-ID | FILE-NAME | INDEX | OFFSET | TOTAL-SIZE

FILE-ID is the stable transfer identity; INDEX identifies the segment and OFFSET provides the exact byte continuation point. A new HTTP/3 stream may continue an existing download.