Contact Us 1-800-596-4880

HTTP/2 Support

Get faster, more efficient, and secure communication in Mule apps with HTTP/2 support in the 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 currently 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" />

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

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.

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)

Use this configuration to enable HTTP/2 support with cleartext on the listener connection 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>

When you enable both HTTP/1 and HTTP/2 on the server, your client can send old-known HTTP/1 requests, HTTP/2 requests with prior knowledge, or HTTP/1 requests with an “Upgrade” header to switch to HTTP/2.

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>
View on GitHub