Skip to content

Conversation

@jaw-sh
Copy link

@jaw-sh jaw-sh commented Jan 22, 2026

This adds a PreTlsProcess trait and callback mechanism that allows applications to read and process bytes from the raw TCP stream before the TLS handshake begins. Provides a way to self-implement #132 .

This also exposes HTTP2 session terminators. Closes #775.

The HAProxy PROXY protocol spec requires that the header be parsed from the raw TCP stream before any application protocol processing, including TLS. Currently there's no way to do this in Pingora - by the time ServerApp::process_new runs, TLS has already completed.
https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

This is how nginx and haproxy handle it: TCP accept → parse PROXY header → TLS handshake → HTTP.
https://github.com/nginx/nginx/blob/master/src/http/ngx_http_request.c#L307-L362

Changes

  • Add PreTlsProcess trait in pingora-core/src/listeners/mod.rs
  • Thread callback through TransportStackBuilder → TransportStack → UninitializedStream
  • Call callback in UninitializedStream::handshake() before TLS
  • Make Stream::rewind() public so implementations can put back bytes that aren't PROXY protocol

Usage

struct ProxyProtocolHandler;

#[async_trait]
impl PreTlsProcess for ProxyProtocolHandler {
    async fn process(&self, stream: &mut L4Stream) -> Result<()> {
        // Read PROXY header, update socket digest with real client IP
        Ok(())
    }
}

// In setup:
listeners.set_pre_tls_callback(Arc::new(ProxyProtocolHandler));

This code is being used in a beta server deployment with PROXY Protocol v1 and v2 support to handle incoming traffic from other web servers and Tor with success.

Allow sending RST_STREAM with a custom reason code instead of hardcoded
INTERNAL_ERROR. This enables RFC 7540 §9.1.2 compliant 421 responses where
HTTP_1_1_REQUIRED can signal clients to retry over HTTP/1.1.

Fixes cloudflare#787
Add shutdown_with_reason for H2 streams
Add a PreTlsProcess trait and set_pre_tls_callback() method that allows
applications to process raw bytes before the TLS handshake occurs.

This is useful for protocols like HAProxy's PROXY protocol (used by Tor
and load balancers), which sends client address information before TLS.
The callback can read and consume protocol headers, then update the
socket digest with the real client address.

The callback is invoked after TCP accept and set_buffer() but before
tls_handshake(), allowing the application to handle pre-TLS data without
requiring changes to Pingora's TLS implementation.
Make the rewind() method public so that PreTlsProcess implementations
can put data back onto the stream when the data doesn't match the
expected protocol signature.

This is needed for PROXY protocol detection where the pre-TLS handler
reads initial bytes to check for the PROXY signature, and must rewind
if the data is not PROXY protocol so TLS can proceed normally.
@duke8253 duke8253 added the enhancement New feature or request label Jan 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Provide TlsRef details to HTTP/2 requests

3 participants