HTTPS proxy hangs on HTTP/2 client requests; works over HTTP/1.1

[Maxwell2022]

Describe the issue

MockServer hangs for ~30 seconds and then sends a graceful HTTP/2 GOAWAY (NO_ERROR, last_stream=1) without sending any response, when an HTTPS request is made through the proxy port (1080) over HTTP/2. The same request works correctly when forced to HTTP/1.1.

This affects both:

• requests matching a configured expectation (mocked response), and
• requests with no matching expectation (forward / catch-all behaviour).

The hang happens after MockServer accepts the CONNECT, completes TLS, negotiates h2 via ALPN, and receives the HTTP/2 GET frame. It then never writes a response. After the timeout it sends GOAWAY error=0 and closes the stream, causing curl to error with (16) Error in the HTTP2 framing layer.

What you are trying to do

Use MockServer as the HTTPS forward proxy for a Playwright-based e2e test suite. The browser (headless Chromium) connects to MockServer via proxy: { server: 'http://mockserver:1080' } and Chromium negotiates h2 with the proxy. Some requests should be served by MockServer expectations (e.g. payment-gateway stubs), others should be forwarded upstream. Both paths fail over HTTP/2.

MockServer version

mockserver/mockserver:5.15.0 upgraded to v6 (same image repo, latest v6 tag). Same behaviour on both — v5 fails on upstream HTTP/2, v6 fails on the proxy-facing HTTP/2 response path.

To Reproduce

1. Run MockServer via Docker (minimal repro, no docker-compose needed):

# CA + key for TLS MITM (any CA works; using mkcert here for simplicity)
mkdir -p ./ca
mkcert -install
cp "$(mkcert -CAROOT)/rootCA.pem" ./ca/cert.pem
cp "$(mkcert -CAROOT)/rootCA-key.pem" ./ca/key.pem

# Expectations: one mock for a known host
mkdir -p ./expectations
cat > ./expectations/typekit.json <<'EOF'
  [
    {
      "id": "typekit-stub-css",
      "priority": 10,
      "httpRequest": {
        "method": "GET",
        "path": "/mzn8ecb.css",
        "headers": { "Host": ["use\\.typekit\\.net"] }
      },
      "httpResponse": {
        "statusCode": 200,
        "headers": { "Content-Type": ["text/css;charset=utf-8"] },
        "body": "/* mocked */"
      }
    }
  ]
  EOF


docker run --rm --name mockserver \
    -p 1080:1080 \
    -v "$PWD/ca:/config/ca:ro" \
    -v "$PWD/expectations:/config/expectations:ro" \
    -e MOCKSERVER_SERVER_PORT="1080,443" \
    -e MOCKSERVER_LOG_LEVEL="INFO" \
    -e MOCKSERVER_CERTIFICATE_AUTHORITY_X509_CERTIFICATE="/config/ca/cert.pem" \
    -e MOCKSERVER_CERTIFICATE_AUTHORITY_PRIVATE_KEY="/config/ca/key.pem" \
    -e MOCKSERVER_INITIALIZATION_JSON_PATH="/config/expectations/*.json" \
    mockserver/mockserver:6.0.0 # or 5.15.0

2. Reproduce — HTTPS over HTTP/2 (hangs):

curl -kx http://localhost:1080 -v 'https://use.typekit.net/mzn8ecb.css' \
  -o /dev/null --max-time 35 2>&1 | tail -20

  Output (abridged):
  * using HTTP/2
  * [HTTP/2] [1] OPENED stream for https://use.typekit.net/mzn8ecb.css
  * [HTTP/2] [1] [:method: GET]
  * [HTTP/2] [1] [:authority: use.typekit.net]
  * [HTTP/2] [1] [:path: /mzn8ecb.css]
  > GET /mzn8ecb.css HTTP/2
  * Request completely sent off
  * received GOAWAY, error=0, last_stream=1   <-- ~29s later
  * TLSv1.2 (IN), TLS alert, close notify (256):
  curl: (16) Error in the HTTP2 framing layer

3. Compare — same request forced to HTTP/1.1 (works):

  curl -kx http://localhost:1080 --http1.1 -v 'https://use.typekit.net/mzn8ecb.css' \
    -o /dev/null --max-time 35 2>&1 | tail -20

  3. Output:
  < HTTP/1.1 200 OK
  < Content-Type: text/css;charset=utf-8
  < content-length: 12
  { [12 bytes data]
  /* mocked */

The only variable between the two runs is ALPN negotiating h2 vs http/1.1. The mocked expectation matches in both cases, only HTTP/2 hangs.

Expected behaviour

When the client negotiates h2 via ALPN on the proxy port, MockServer should:

• send the mocked httpResponse back as a valid HTTP/2 response on the same stream, or
• if no expectation matches and forwarding is desired, complete the forward and relay the upstream response as HTTP/2.

Either outcome is acceptable; silently hanging and emitting GOAWAY after ~30s is not.

MockServer Log

At MOCKSERVER_LOG_LEVEL=INFO (and at lower levels), no log line is emitted for the HTTP/2 request — neither a "received request" entry nor an "expectation matched" entry.

The mockserver/retrieve?type=LOGS&format=JSON endpoint also returns no record of the request. From the operator's perspective the request silently disappears inside MockServer. The HTTP/1.1 variant of the same request does produce normal INFO-level log entries showing the expectation matching.

  (Container startup logs only contain SLF4J init noise:)
  SLF4J(W): No SLF4J providers were found.
  SLF4J(W): Defaulting to no-operation (NOP) logger implementation
  SLF4J(W): See https://www.slf4j.org/codes.html#noProviders for further details.
  Loading JavaScript to validate ECMA262 regular expression in JsonSchema ...

The absence of an SLF4J binding in the official image (v6.0.0) is likely a separate packaging issue but is worth flagging here as it makes the HTTP/2 hang impossible to diagnose from container logs alone.

[jamesdbloom]

investigating

[jamesdbloom]

Fixed on master in 8a5c2d1 — this issue was auto-closed by that commit.

Root cause

Your diagnosis was on the mark. MockServer's HTTPS forward proxy serves a CONNECT tunnel through an internal self-loopback relay: it opens a connection back to its own port and ferries the tunnelled request across it. That loopback connection hard-wired an HTTP/1.1 codec, but its TLS layer still ran ALPN. So when the tunnelled client negotiated h2, the loopback's TLS negotiated h2 too — while the codec sitting behind it only understood HTTP/1.1. The HTTP/2 frames were therefore never decoded, the request never reached the matching/forwarding engine (hence no log entry and nothing in retrieve), and the connection stalled until it was torn down with a GOAWAY. HTTP/1.1 worked only because there the codec and the negotiated protocol happened to agree.

Both behaviours you described — mocked expectations and forwarding/catch-all — go through this same relay, which is why both failed over HTTP/2.

Fix

RelayConnectHandler now builds the loopback pipeline to match the protocol negotiated with the proxy client: a client-mode HTTP/2 codec when the client negotiated h2, the HTTP/1.1 codec otherwise. The loopback's TLS layer and its codec always agree, so the relay is a transparent passthrough — HTTP/2 through the CONNECT proxy now works for both mocked and forwarded requests.

New http2Enabled configuration property

Also added an http2Enabled property (default true; system property mockserver.http2Enabled, environment variable MOCKSERVER_HTTP2_ENABLED). Setting it to false makes MockServer advertise only http/1.1 via ALPN and ignore the h2c cleartext upgrade, forcing HTTP/2-capable clients (e.g. headless Chromium) down to HTTP/1.1 without changing the client.

Tests

Added integration coverage for HTTP/2 through the CONNECT proxy (mocked response, forwarding to a secure target, large request/response bodies) and for the http2Enabled=false opt-out, plus unit coverage for the ALPN gating.

On the SLF4J note

Thanks for flagging the missing SLF4J binding in the official 6.0.0 image — you're right that it made this hard to diagnose from container logs alone. That is a separate packaging issue and will be tracked independently.

This fix ships in the next release (master is currently 6.0.1-SNAPSHOT).

[Maxwell2022]

Thanks @jamesdbloom ! Do you have an ETA for publishing this version in dockerhub so I can test it?

---

Edit:

I've pulled docker pull mockserver/mockserver:mockserver-snapshot-graaljs and it seems to be working as expected 🚀

I'll wait for the 6.0.1 version to land to pin it

[jamesdbloom]

The snapshot tag should now have this fix. I'm planning to do a release very soon but just finishing LLM proxy / debugging functionality.

[jamesdbloom]

Sorry using my mobile and just saw the second half of your message, thanks for testing it @Maxwell2022 very helpful to know it passes. I expect to release a new version on Tuesday / Wednesday next week.