4.x: Initial support for proxy protocol V1 and V2

[spericas]

Description

This PR includes an implementation of the proxy protocol V1 and V2 as described here https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt. This feature can be enabled on a listener configuration:

    /**
     * Enable support for proxy protocol for this socket.
     * Default is {@code false}.
     *
     * @return proxy support status
     */
    @Option.Default("false")
    boolean enableProxyProtocol();

Once enabled, it is disabled by default, the proxy protocol header MUST be present in the connection (only for the first request if multiple ones are sent over a long-lived connection). The feature is supported for HTTP/1.1 and HTTP2 and can also be used in combination with TLS (proxy protocol header is processed before the SSL handshake).

The proxy protocol version, either V1 or V2, is automatically discovered by inspecting the first few bytes of a connection. The data collected from the protocol header can be obtained from a ServerRequest as shown below:

ServerRequest request = ...
ProxyProtocolData data = request.proxyProtocolData().ifPresent(ppd -> ...);

It addition, a subset of the proxy protocol data is made available as the HTTP headers X-Forwarded-For and X-Forwarded-Port. These headers can also be used in combination with RequestedUriDiscoveryContext when configured to inspect the aforementioned headers.

Other than unit and integration tests, both the V1 and V2 protocol headers have been manually tested to be compatible with Wireshark's decoder.

Documentation

I shall create a new follow-up issue to document this new features, if and when it is merged.

[tjquinno]

The revised Http1Connection and Http2Connection classes set the non-standard (but oft-used) X-Forwarded-For and X-Forwarded-Port headers but not the standard Forwarded header.

Should the code allow users to configure which family of header to use (maybe both??) and then set the corresponding header(s)?

I see that the proxy spec (thanks for the link) uses the X-Forwarded-* headers in the text but also mentions in passing Forwarded. It's not clear from my quick read whether the proxy spec requires X-Forwarded-* or happened to use that as an example.

Given that our requested URI support allows users to configure one or the other or both families of headers for that feature, should the proxy support do the same?

Or, perhaps, just always set both Forwarded and the X-Forwarded-* family?

[spericas]

The revised Http1Connection and Http2Connection classes set the non-standard (but oft-used) X-Forwarded-For and X-Forwarded-Port headers but not the standard Forwarded header.

Should the code allow users to configure which family of header to use (maybe both??) and then set the corresponding header(s)?

I see that the proxy spec (thanks for the link) uses the X-Forwarded-* headers in the text but also mentions in passing Forwarded. It's not clear from my quick read whether the proxy spec requires X-Forwarded-* or happened to use that as an example.

Given that our requested URI support allows users to configure one or the other or both families of headers for that feature, should the proxy support do the same?

Or, perhaps, just always set both Forwarded and the X-Forwarded-* family?

It's obviously possible to support both. I wanted to do the minimum without consulting config and without creating formatted strings, to avoid adding more code to the request processing loop. Using the X headers seems more efficient and it is one of the options supported by the existing URI mechanism. Perhaps we can start with something simple and provide other options if/when customer feedback is received.