WebSocket Routing and Intercepting

Membrane Service Proxy can route WebSocket traffic to endpoints.

In addition to routing Membrane can intercept WebSocket traffic. This means that Membrane reads the WebSocket traffic, manipulates it and writes it back to the designated target.

Following this you will find reasons on why routing/intercepting with Membrane is a good idea if you want to monitor/manipulate WebSocket traffic in any way.

Service Proxy Routing with Support for WebSockets

WebSocket routing starts by adding the webSocket interceptor to a service proxy. There are 2 ways on how to define the target of the WebSocket traffic: either implicitly through the target element or explicitly by specifying an URL in the webSocket interceptor.

Implicit Routing

Take a look at the following listing that shows an example WebSocket routing rule with implicit routing.

					<serviceProxy port="8080">
						<webSocket/>
						<target host="localhost" port="2001" />
					</serviceProxy>

Listing 1: WebSocket implicit routing

In the service proxy you will find a webSocket interceptor without any additional attributes or child elements. By doing it like this you tell Membrane to look for HTTP upgrade requests on port 2000. When an upgrade handshake was successful Membrane takes the current HTTP connection, reuses it as a WebSocket connection and starts routing it to the target (as a WebSocket connection).

The target element is used for HTTP and WebSocket traffic.

Explicit Routing

Take a look at the following listing that shows an example WebSocket routing rule with implicit routing.

					<serviceProxy port="8080">
						<webSocket url=“http://localhost:2001“/>
						<target host="localhost" port="8081" />
					</serviceProxy>

Listing 2: WebSocket explicit routing

Explicit routing works similiar to implicit routing except that the target is not used for WebSocket routing but the destination is explicitly specified in the url attribute of the webSocket interceptor.

The target element is only used for HTTP traffic.

Intercepting

Intercepting can be done in addition to routing WebSocket traffic. For this to work one has to specify WebSocket interceptors that process individual WebSocket Frames.

WebSocket intercepting is different to HTTP intercepting because WebSocket communication has no pair of Request -> Response but it has a bi-directional TCP connection where client and server can send messages freely. That is why WebSocket frames are processed independently and also have no counterpart.

Processing of the intercepted WebSocket traffic is done on a per WebSocket frame basis. For this the WebSocket stream is read until a frame can be constructed. Constructed frames are then passed to the WebSocket interceptor chain specified as child elements in the webSocket interceptor. The following listing shows an example where WebSocket frames are printed to the console through the wsLog interceptor.

					<serviceProxy port="8080">
						<webSocket>
							<wsLog/>
						</ webSocket>
						<target host="localhost" port="2001" />
					</serviceProxy>

Listing 3: WebSocket intercepting with wsLog

The listing demonstrates how to add WebSocket interceptors. The interceptors are added as child elements of the webSocket interceptor. Currently 2 predefined interceptors are available: wsLog and wsStompReassembler

The wsLog interceptors only purpose is to print received WebSocket frames to the console.

The wsStompReassembler interceptors purpose is to easily manipulate STOMP over WebSocket messages through Membranes other interceptors. For this the wsStompReassembler interceptor converts a STOMP over WebSocket message to an exchange. For further reading on this please visit the STOMP over WebSockets page.

Getting Started

See $MEMBRANE_HOME/examples/websocket-intercepting in the Membrane Service Proxy distribution for a working example.