Package org.mockserver.mock.action.http

Class WebSocketProxyRelayHandler

java.lang.Object

org.mockserver.mock.action.http.WebSocketProxyRelayHandler

public class WebSocketProxyRelayHandler
extends Object

Proxy passthrough relay for WebSocket connections.

When a WebSocket upgrade request (HTTP GET with Upgrade: websocket) arrives in proxy mode and no WebSocket mock expectation matches (or a FORWARD expectation matches), MockServer opens the upstream WebSocket connection (honouring scheme/TLS), relays the 101 Switching Protocols handshake, and then relays frames bidirectionally (text, binary, ping, pong, close) until either side closes.

The relay reuses the inbound channel's event loop for the upstream connection, so both the client-facing and upstream-facing halves run on the same single thread — there are no cross-thread races between the two frame relays.

The upgrade exchange is recorded as a FORWARDED_REQUEST in the event log (request = the upgrade GET, response = 101 carrying the transcript of relayed frames), so retrieveRecordedRequests and the dashboard show the WebSocket traffic. The transcript is bounded by Configuration.webSocketProxyMaxRecordedFrames() frames per connection and each frame payload is capped at MAX_RECORDED_FRAME_BYTES bytes, mirroring the maxLogEntries memory-management philosophy.

Scope (v1): HTTP/1.1 upgrade relay only (plain and TLS upstream). HTTP/2 extended-CONNECT WebSocket is a documented boundary — see docs/code/netty-pipeline.md.

Constructor Summary

Constructors

Constructor	Description
WebSocketProxyRelayHandler(Configuration configuration, MockServerLogger mockServerLogger, NettySslContextFactory nettySslContextFactory)

Method Summary

Modifier and Type	Method	Description
static boolean	isWebSocketUpgrade(HttpRequest request)	Whether the request is an HTTP/1.1 WebSocket upgrade handshake (GET + Upgrade: websocket + Connection: upgrade + a Sec-WebSocket-Key).
void	relay(HttpRequest request, io.netty.channel.ChannelHandlerContext clientCtx, String upstreamHost, int upstreamPort, boolean tlsUpstream)	Establish the upstream WebSocket connection and, on a successful upstream handshake, relay the 101 downstream and begin bidirectional frame relay.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

WebSocketProxyRelayHandler

public WebSocketProxyRelayHandler(Configuration configuration,
 MockServerLogger mockServerLogger,
 NettySslContextFactory nettySslContextFactory)

Method Details

isWebSocketUpgrade

public static boolean isWebSocketUpgrade(HttpRequest request)

Whether the request is an HTTP/1.1 WebSocket upgrade handshake (GET + Upgrade: websocket + Connection: upgrade + a Sec-WebSocket-Key).

relay

public void relay(HttpRequest request,
 io.netty.channel.ChannelHandlerContext clientCtx,
 String upstreamHost,
 int upstreamPort,
 boolean tlsUpstream)

Establish the upstream WebSocket connection and, on a successful upstream handshake, relay the 101 downstream and begin bidirectional frame relay. On any failure a 502 is written to the client and both channels are closed.