HTTP/2 103 Early Hints Support

[apu031]

Implement HTTP/2 103 Early Hints Support

Add complete HTTP/2 103 Early Hints implementation with full client and server support, building upon the initial 1xx informational responses prototype to deliver a solution for web performance optimization.

Key Features Added

Client-side Support

• Add InformationalConfig with callback system for processing 1xx informational responses
• Extend HTTP/2 client builder with informational_responses() configuration method
• Implement informational response polling in h2 client task with callback invocation
• Support real-time processing of 103 Early Hints and other informational responses
• Handle multiple informational responses before final response arrives

Server-side Support

• Builder opt-in pattern: Add .enable_informational() method for explicit feature activation
• Zero-cost abstraction: When disabled (default), zero overhead - no allocations, no extensions
• early_hints_pusher() API: Ergonomic interface for sending 103 Early Hints
  • Returns EarlyHintsPusher handle when feature enabled
  • Returns EarlyHintsError::NotSupported when feature not enabled
  • Validates 103 status code requirement
• Add InformationalSender extension for hint transmission via mpsc channel
• Implement server-side informational response forwarding using h2's send_informational API
• Support multiple 103 Early Hints responses per request for progressive resource discovery
• Validate informational responses and handle errors gracefully

Complete Implementation

• Build upon Joel Dice's initial HTTP/1 prototype (commit 4e2483a) to add full HTTP/2 support
• Integrate with h2 crate's informational response capabilities
• Add robust error handling and validation
• Include production-ready example with TLS, resource preloading, and performance monitoring
• Provide extensive test coverage with 11 integration tests covering different scenarios

Changed Files

• Cargo.toml: Example build configuration
• examples/README.md: Document new HTTP/2 Early Hints example
• examples/http2_early_hints.rs: Working example with TLS, and resource preloading
• src/client/conn/http2.rs: Extend HTTP/2 client builder with informational response configuration
• src/client/conn/informational.rs: New module implementing client-side informational callback system
• src/client/conn/mod.rs: Export new informational module
• src/ext/informational_sender.rs: New early_hints_pusher() API
• src/ext/mod.rs: Export new Early Hints API types
• src/proto/h1/dispatch.rs: Update HTTP/1 dispatch for informational compatibility
• src/proto/h1/role.rs: Extend HTTP/1 role handling for informational responses
• src/proto/h2/client.rs: HTTP/2 client informational response polling
• src/proto/h2/server.rs: Add enable_informational config field (defaults to false), conditional channel creation, helper method for polling logic
• src/server/conn/http2.rs: Add .enable_informational() builder method
• tests/integration-early-hints.rs: 11 integration tests

Test Coverage

Integration Tests (11 tests, ~0.27s)

All tests pass consistently, covering:

• Basic preconnect hints functionality
• Resource preloading (CSS, JS, fonts, images)
• Content Security Policy enforcement via Early Hints
• Multiple sequential 103 responses
• Mixed Link header types with HTTP/2 compression handling
• Cross-origin redirect security behavior
• Real-world web page optimization scenarios
• Empty 103 response validation
• Timing validation for performance benefits
• Error response handling after hints sent

Unit Tests (18 tests, ~0.24s)

• API layer (7 tests): Error handling, channel communication, status validation
• Builder layer (6 tests): Configuration, method chaining, flag propagation
• Config layer (5 tests): Defaults, mutation, cloning, debug output

Documentation Tests (2 tests)

• Examples for early_hints_pusher() usage
• Example for .enable_informational() builder method

Total: 152 tests passing (31 new from this PR)

API Usage Example

Server-side (Requires Opt-in)

use hyper::server::conn::http2;
use hyper::ext::early_hints_pusher;
use hyper::{Request, Response, StatusCode};

// 1. Enable feature via builder
let builder = http2::Builder::new(executor)
    .enable_informational();

// 2. Use in service handler
async fn handle(mut req: Request<Incoming>) -> Result<Response<String>, Error> {
    if let Ok(mut pusher) = early_hints_pusher(&mut req) {
        let hints = Response::builder()
            .status(StatusCode::EARLY_HINTS)
            .header("link", "</style.css>; rel=preload; as=style")
            .header("link", "</app.js>; rel=preload; as=script")
            .body(())
            .unwrap();
        
        let _ = pusher.send_hints(hints).await;
    }
    
    Ok(Response::new("<!DOCTYPE html>...".to_string()))
}

Use Cases Supported

• 103 Early Hints: Enable early resource discovery and preloading for web performance optimization
• 100 Continue: Support request/response optimization for large payloads
• Resource Preloading: CSS, JavaScript, fonts, images, and fetch resources
• CDN Preconnection: Early connection establishment to external domains
• Progressive Enhancement: Multiple hint responses as server processing progresses

Technical Implementation

• Builder opt-in pattern ensures zero overhead when feature not used (default state)
• Informational responses sent without END_STREAM flag to maintain connection
• Stream state management preserves HTTP/2 flow control during informational responses
• Client callback system separates informational processing from main response flow
• Server extension system allows middleware and applications to send hints seamlessly
• Cross-origin security validated for redirect scenarios
• Backward compatibility maintained - existing code continues to work unchanged

Standards Compliance

• RFC 8297: Complete HTTP Status Code 103 Early Hints implementation
• RFC 7540: HTTP/2 specification compliance for informational responses
• HTTP/2 HPACK: Proper header compression handling for multiple Link headers
• Browser Security: Cross-origin redirect protection and validation

Migration Path

This implementation is fully backward compatible with opt-in behavior:

No Changes Required

Existing applications continue to work unchanged with zero performance impact.

To Enable Feature

Add single builder method call:

// Before: Feature automatically disabled
let builder = http2::Builder::new(executor);

// After: Single line to enable
let builder = http2::Builder::new(executor)
    .enable_informational();

Then use early_hints_pusher() in handlers:

if let Ok(mut pusher) = early_hints_pusher(&mut req) {
    pusher.send_hints(hints).await?;
}

No breaking changes. Pay only for what you use.

---

Browser Tests

• Chrome:

• Firefox:

---

The implementation provides a robust foundation for web performance optimization while maintaining the reliability and safety expected from the hyper HTTP library.

Resolves #3980 and #2426 for HTTP/2 103 Early Hints support and extends the informational responses capability for HTTP/2 protocols.

---

---

Revision 2

Addresses @JakubKoralewski 's feedback

This implementation addresses all concerns raised during code review:

1. Unconditional allocation → Builder opt-in with zero-cost default
2. API design consistency → Follows informational_pusher pattern
3. Performance impact → Zero overhead when disabled
4. Redundant feature gates → Removed unnecessary annotations
5. Dependency version → h2 = 0.4.13
6. Example quality → Only critical resources hinted
7. Polling optimization → Restricted to Service state only

[apu031]

Accidentally forced pushed the branch so recreating the PR (Previous PR #3991)

[apu031]

Hi @seanmonstar,

It is no doubt that maintaining hyper is super demanding of your time. The HTTP 103 support from hyper is blocking some internal work for us. So requesting your precious time to get the PR #3991 (now PR #4114) to the finish line since it has been open for the last 8 months.

I promise I will promptly address any concerns you have to save your time following your review.

Truly appreciate the help, @seanmonstar !