HTTP/2 Support

Get faster, more efficient, and secure communication in Mule apps with HTTP/2 support in HTTP Connector.

HTTP/2 is the second major version of the Hypertext Transfer Protocol, the foundation of communication for the World Wide Web. Published as RFC 7540, HTTP/2 addresses the performance limitations of HTTP/1.1 by improving speed, efficiency, and security.

experimental: HTTP/2 features are experimental in Mule runtime 4.10.0 and subject to change or removal from future versions.

Before You Begin

To use this feature, you must have:

Mule runtime 4.10.0 or later
HTTP Connector version 1.11.0 or later
The mule.http.service.implementation=NETTY system property set
Runtime Fabric or a Hybrid Standalone environment

HTTP/2 support is available only on Anypoint Runtime Fabric and Hybrid Standalone environments.

Key Features

HTTP/2 support improves performance with these capabilities:

Multiplexing

Sends multiple requests and responses over a single TCP connection at the same time, avoiding HTTP/1.1 head-of-line blocking and reducing latency.
Header Compression (HPACK)

Compresses request and response headers to reduce data transfer size and speed up load times.
Binary Protocol

Uses binary framing instead of text representation for more efficient communication.

Backward Compatibility

Apps that work with HTTP/1 continue to work without changes. If you don’t modify the connector configuration, HTTP/1.1 remains the default protocol.
Autogenerated API proxies continue to use HTTP/1.1 unless you customize the proxy configuration to enable HTTP/2.

Wire Logging

Wire logging uses the same configuration as HTTP/1.1. Because HTTP/2 is a binary protocol, log output looks different:

<AsyncLogger name="org.mule.service.http.impl.service.HttpMessageLogger" level="DEBUG" />

Example: HTTP/2 Wire Logging Output

When HTTP/2 wire logging is enabled, Mule logs both the binary frames exchanged between the client and server and the decoded data for readability. Because HTTP/2 is a binary protocol, the output includes hexadecimal representations of each frame.

DEBUG [http.listener.08] org.mule.service.http.impl.service.HttpMessageLogger.h2ListenerConfig: [6b24f7f9, L:/127.0.0.1:8081 - R:/127.0.0.1:57672] READ: 117B
         +-------------------------------------------------+
|00000000| 50 52 49 20 2a 20 48 54 54 50 2f 32 2e 30 0d 0a |PRI * HTTP/2.0..|
|00000010| 0d 0a 53 4d 0d 0a 0d 0a ...                     |..SM...          |
DEBUG [http.listener.08] org.mule.service.http.impl.service.HttpMessageLogger.h2ListenerConfig: WRITE: 36B
|00000000| 52 65 71 75 65 73 74 20 70 72 6f 74 6f 63 6f 6c |Request protocol|
|00000010| 20 76 65 72 73 69 6f 6e 20 77 61 73 3a 20 48 54 | version was: HT|
|00000020| 54 50 2f 32                                     |TP/2            |

The log shows these details:

The PRI * HTTP/2.0 connection preface sent by the client.
Binary frame content in hexadecimal form.
Mule’s decoded payload returned to the client (Request protocol version was: HTTP/2).
READ entries correspond to inbound frames, and WRITE entries are outbound frames.

Configuration Structure

Enable HTTP/2 support by adding the <http:protocol-support> element to your connection configuration. You can enable or disable HTTP/1.1 and HTTP/2 independently with this element.

Basic Configuration Example

Use this configuration to enable both HTTP/1.1 and HTTP/2 support on the same listener connection.

<http:listener-config name="http2Config">
    <http:listener-connection host="0.0.0.0" port="8081" protocol="HTTPS">
        <tls:context>
            <!-- TLS configuration -->
        </tls:context>
        <http:protocol-support>
            <http:http1-support enable="true" />
            <http:http2-support enable="true" />
        </http:protocol-support>
    </http:listener-connection>
</http:listener-config>

HTTP/2 Configuration Parameters

The <http:http2-support> element supports these parameters:

Parameter Type Default Range Description

Parameter	Type	Default	Range	Description
`enable`	Boolean	`true`	-	Enables or disables HTTP/2 support.
`headerTableSize`	Long	4096	0 - 4,294,967,295	Maximum size of header compression table in octets.
`maxConcurrentStreams`	Long	No limit	100 - 4,294,967,295	Maximum number of concurrent streams.
`initialWindowSize`	Integer	65535	0 - 2,147,483,647	Initial flow-control window size in octets.
`maxFrameSize`	Integer	16384	16,384 - 16,777,215	Maximum frame payload size in octets.
`maxHeaderListSize`	Long	8192	0 - 4,294,967,295	Maximum header list size in octets.

enable

Boolean

true

Enables or disables HTTP/2 support.

headerTableSize

Long

4096

0 - 4,294,967,295

Maximum size of header compression table in octets.

maxConcurrentStreams

Long

No limit

100 - 4,294,967,295

Maximum number of concurrent streams.

initialWindowSize

Integer

65535

0 - 2,147,483,647

Initial flow-control window size in octets.

maxFrameSize

Integer

16384

16,384 - 16,777,215

Maximum frame payload size in octets.

maxHeaderListSize

Long

8192

0 - 4,294,967,295

Maximum header list size in octets.

Configuration Examples

These examples show how to enable and configure HTTP/2 support in different scenarios.

Basic HTTP/2 with SSL (Recommended)

Use this configuration to enable HTTP/2 over HTTPS with TLS for secure communication.

<http:listener-config name="h2ListenerConfig">
    <http:listener-connection host="0.0.0.0" port="8443" protocol="HTTPS">
        <tls:context>
            <tls:trust-store path="cacerts.jks" password="changeit" type="JKS"/>
            <tls:key-store path="keystore.jks" keyPassword="changeit" password="changeit" type="JKS"/>
        </tls:context>
        <http:protocol-support>
            <http:http1-support />
            <http:http2-support />
        </http:protocol-support>
    </http:listener-connection>
</http:listener-config>

<http:request-config name="h2RequestConfig">
    <http:request-connection host="localhost" port="8443" protocol="HTTPS">
        <tls:context>
            <tls:trust-store path="cacerts.jks" password="changeit" type="JKS"/>
            <tls:key-store path="keystore.jks" keyPassword="changeit" password="changeit" type="JKS"/>
        </tls:context>
        <http:protocol-support>
            <http:http2-support />
        </http:protocol-support>
    </http:request-connection>
</http:request-config>

When using SSL, TLS negotiates which HTTP version to use through the ALPN extension.

HTTP/2 Cleartext (H2C) with Upgrade

Use this configuration to enable HTTP/2 support with cleartext on the listener connection.

<http:listener-config name="h2cListenerConfig">
    <http:listener-connection host="0.0.0.0" port="8080" protocol="HTTP">
        <http:protocol-support>
            <http:http1-support />
            <http:http2-support />
        </http:protocol-support>
    </http:listener-connection>
</http:listener-config>

<http:request-config name="h2cRequestConfig">
    <http:request-connection host="localhost" port="8080">
        <http:protocol-support>
            <http:http1-support />
            <http:http2-support />
        </http:protocol-support>
    </http:request-connection>
</http:request-config>

HTTP/2 Cleartext with Prior Knowledge (H2C Prior Knowledge)

This configuration shows how to enable HTTP/2 on a server without HTTP/1 support, allowing HTTP clients to use HTTP/2 with prior knowledge.

<http:listener-config name="h2cPKListenerConfig">
    <http:listener-connection host="0.0.0.0" port="8080" protocol="HTTP">
        <http:protocol-support>
            <http:http1-support enable="false" />
            <http:http2-support />
        </http:protocol-support>
    </http:listener-connection>
</http:listener-config>

<http:request-config name="h2cPKRequestConfig">
    <http:request-connection host="localhost" port="8080">
        <http:protocol-support>
            <http:http1-support enable="false" />
            <http:http2-support />
        </http:protocol-support>
    </http:request-connection>
</http:request-config>

When you enable only HTTP/2 on the server, HTTP clients can send only HTTP/2 requests with prior knowledge. An HTTP/1 request with “Upgrade: h2c” header is rejected by that server.

Fully Parameterized HTTP/2 Configuration

This example shows all configurable HTTP/2 parameters, including recommended values from the HTTP/2 specification.

<http:listener-config name="h2AllParamsListenerConfig">
    <http:listener-connection host="0.0.0.0" port="8443" protocol="HTTPS">
        <tls:context>
            <tls:trust-store path="cacerts.jks" password="changeit" type="JKS"/>
            <tls:key-store path="keystore.jks" keyPassword="changeit"
                           password="changeit" type="JKS"/>
        </tls:context>
        <http:protocol-support>
            <http:http1-support enable="true" />
            <http:http2-support enable="true"
                                headerTableSize="8192"
                                maxConcurrentStreams="100"
                                initialWindowSize="65535"
                                maxFrameSize="17000"
                                maxHeaderListSize="8192" />
        </http:protocol-support>
    </http:listener-connection>
</http:listener-config>

These parameters configure HTTP/2 support and use recommended values from the HTTP/2 Settings.

Protocol Detection in Flows

You can detect which HTTP version a request used by checking attributes.version:

<flow name="protocolDetectionFlow">
    <http:listener path="/*" config-ref="h2ListenerConfig"/>
    <set-payload value="#['Request protocol version was: ' ++ attributes.version]" />
</flow>

This flow can return:

Request protocol version was: HTTP/2
Request protocol version was: HTTP/1.1

Configuration Guidelines

These guidelines help you configure HTTP/2 settings for compatibility, security, and performance.

Protocol Compatibility

Use HTTP/2 with SSL whenever possible. The server negotiates the protocol using ALPN (H2 or HTTP/1.1).

Parameter Tuning

HTTP/2 settings are recommendations to the implementation and aren’t guaranteed to be honored.

Security

Use SSL to secure communications.

Validation Rules

The connector validates HTTP/2 parameters according to RFC 7540:

headerTableSize: 0 - 4,294,967,295
maxConcurrentStreams: 100 - 4,294,967,295 (minimum recommended: 100)
initialWindowSize: 0 - 2,147,483,647
maxFrameSize: 16,384 - 16,777,215
maxHeaderListSize: 0 - 4,294,967,295

Troubleshooting

Common issues and solutions:

HTTP/2 not working

Confirm Mule runtime 4.10.0+ and HTTP Connector 1.11.0+ are installed.
Connection failures

Verify TLS configuration for HTTPS connections.
Parameter validation errors

Ensure parameter values are within the supported ranges.
Protocol negotiation failures

Make sure the client and server both support the same protocols.

Testing HTTP/2 Configuration

Use this MUnit test to confirm HTTP/2 is working:

<munit:test name="http2VerificationTest">
    <munit:execution>
        <http:request config-ref="h2RequestConfig" path="/test" />
    </munit:execution>
    <munit:validation>
        <munit-tools:assert-that expression="#[payload]"
            is="#[MunitTools::containsString('HTTP/2')]" />
    </munit:validation>
</munit:test>

HTTP/2 Support

Before You Begin

Key Features

Backward Compatibility

Wire Logging

Example: HTTP/2 Wire Logging Output

Configuration Structure

Basic Configuration Example

HTTP/2 Configuration Parameters

Configuration Examples

Basic HTTP/2 with SSL (Recommended)

HTTP/2 Cleartext (H2C) with Upgrade

HTTP/2 Cleartext with Prior Knowledge (H2C Prior Knowledge)

Fully Parameterized HTTP/2 Configuration

Protocol Detection in Flows

Configuration Guidelines

Protocol Compatibility

Parameter Tuning

Security

Validation Rules

Troubleshooting

Testing HTTP/2 Configuration

See Also