HTTP overview

Standards

Chunked transfer encoding and trailers are implemented on the Stream SPI; see Limitations for the HTTP/1.1 trailer gap.

Architecture

TcpListenerConfig / TcpConnectorConfig / Quic hooks
        │
        ▼
  ProtocolHandler adapters
  (H1Endpoint | H2Endpoint | CleartextHttpEndpoint |
   AlpnHttpEndpoint | H3*Connection via listen_h3/connect_h3)
        │
        ▼
     HttpStream  (one request/response)
        │
        ├── ServerHandler  ↔  ServerWriter
        └── ClientHandler  ↔  ClientWriter

Push event order on the server (with a body):

headers → start_request_body → request_body_content* → end_request_body → request_complete

Without a body: headers → request_complete.

Client handlers write in start, then receive response_headers → body* → optional response_trailers → response_complete.

Body chunks are zero-copy for the duration of each callback. Response bodies auto-chunk when applicable. Informational 1xx responses use ServerWriter::send_informational.

Version matrix

Cargo features: default = [], h3 = ["dep:hopf-quic"], integration = ["h3"].

HttpLimits

Shared parser / connection limits (Gumdrop defaults):

use hopf_http::HttpLimits;

let limits = HttpLimits {
    max_request_body: 64 * 1024 * 1024, // raise for large uploads
    ..HttpLimits::default()
};

Additional framing knobs live on the parsers (not HttpLimits):

Endpoint constructor flags:

Cleartext, ALPN, and H3 wiring

Cleartext (H1 + h2c)

CleartextHttpEndpoint sniffs the HTTP/2 connection preface for prior-knowledge h2c, supports the h2c Upgrade path (101), and otherwise falls back to HTTP/1.1.

use std::sync::Arc;
use hopf_core::{ProtocolHandler, Runtime, RuntimeConfig, TcpListenerConfig};
use hopf_http::{CleartextHttpEndpoint, HttpLimits, ServerHandlerFactory};

fn listen_cleartext(rt: &Runtime, factory: Arc<dyn ServerHandlerFactory>) -> std::io::Result<()> {
    let limits = HttpLimits::default();
    let f = Arc::clone(&factory);
    rt.add_tcp_listener(TcpListenerConfig::new("127.0.0.1:8080".parse()?, move || {
        Box::new(CleartextHttpEndpoint::new(Arc::clone(&f), limits)) as Box<dyn ProtocolHandler>
    }))?;
    Ok(())
}

TLS + ALPN (H1 / H2)

Wire TLS on TcpListenerConfig / TcpConnectorConfig via hopf-core's in-tree TLS (acceptor_from_pem et al.), and use AlpnHttpEndpoint as the ProtocolHandler. Negotiated ALPN selects H2 or H1. Typical ALPN list: &[b"h2", b"http/1.1"].

use hopf_core::{ProtocolHandler, TcpListenerConfig};
use hopf_http::{AlpnHttpEndpoint, HttpLimits};
use hopf_core::acceptor_from_pem;
use std::path::Path;
use std::sync::Arc;

let acceptor = acceptor_from_pem(
    Path::new("cert.pem"),
    Path::new("key.pem"),
    &[b"h2", b"http/1.1"],
)?;
let factory: Arc<dyn hopf_http::ServerHandlerFactory> = /* ... */;
let limits = HttpLimits::default();
let f = Arc::clone(&factory);
let cfg = TcpListenerConfig::new(addr, move || {
    Box::new(AlpnHttpEndpoint::new(Arc::clone(&f), limits)) as Box<dyn ProtocolHandler>
})
.with_tls(acceptor);

HTTP/3

Enable feature h3. Build a QUIC server/client config with ALPN h3 (hopf_quic::ALPN_H3), then call listen_h3 / connect_h3. See quic-h3.md.

use hopf_http::{listen_h3, HttpLimits};
use hopf_quic::{server_config_self_signed, ALPN_H3};
use std::sync::Arc;

let (server_cfg, _leaf_pem) = server_config_self_signed(&["localhost"], &[ALPN_H3])?;
let handle = listen_h3(
    "127.0.0.1:4433".parse()?,
    server_cfg,
    factory,
    HttpLimits::default(),
)?;
// QuicDriverHandle owns the UDP driver thread — shut down or drop explicitly.

Upgrade seams

ServerWriter::upgrade(headers, handler) hands the connection (H1) or stream (H2/H3) to a ProtocolUpgradeHandler after a successful switch:

Outbound bytes are drained via ProtocolUpgradeHandler::take_outbound. Used by hopf-websocket (RFC 6455 / 8441 / 9220) and similar upgrades. Returns false if the transport cannot upgrade (already responded, wrong version, etc.).

Shared types

Examples

Smoke: cargo test -p hopf-http --features h3 h3_get_hello.

Limitations

• No HTTP/2 server push — PUSH_PROMISE is rejected (client: RST_STREAM; server: GOAWAY).
• H2 PRIORITY frames (RFC 7540) are ignored; hopf uses RFC 9218 Extensible Prioritization (Priority header + PRIORITY_UPDATE) with urgency/incremental scheduling.
• HTTP/1.1 trailers are ignored on the wire (parity gap with Gumdrop). H2/H3 trailers work as a second HEADERS frame (ServerWriter::trailers / ClientHandler::response_trailers).
• UDP / QUIC for H3 lives in hopf-quic and is feature-gated (h3).
• Several declared deps (tractrix, rjsonparser, rmimeparser) support later protocol crates, not the Stream SPI itself.

See also

• HTTP server — ServerHandler, writers, auth, deferred responses
• HTTP client — ClientHandler, dial patterns, http-get
• QUIC / H3 — transport configs and PEM builders
• WebSocket — upgrade consumer
• gRPC — unary over Streams (needs trailers on H2/H3)

GitHub