org.littleshoot.proxy.impl

Class ProxyConnection<I extends HttpObject>

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

io.netty.channel.SimpleChannelInboundHandler<Object>

org.littleshoot.proxy.impl.ProxyConnection<I>

Type Parameters:

I - the type of "initial" message. This will be either HttpResponse or HttpRequest.

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler

Direct Known Subclasses:

ClientToProxyConnection, ProxyToServerConnection

abstract class ProxyConnection<I extends HttpObject>
extends SimpleChannelInboundHandler<Object>

Base class for objects that represent a connection to/from our proxy.

A ProxyConnection models a bidirectional message flow on top of a Netty Channel.

The read(Object) method is called whenever a new message arrives on the underlying socket.

The write(Object) method can be called by anyone wanting to write data out of the connection.

ProxyConnection has a lifecycle and its current state within that lifecycle is recorded as a ConnectionState. The allowed states and transitions vary a little depending on the concrete implementation of ProxyConnection. However, all ProxyConnections share the following lifecycle events:

• connected() - Once the underlying channel is active, the ProxyConnection is considered connected and moves into ConnectionState.AWAITING_INITIAL. The Channel is recorded at this time for later referencing.
• disconnected() - When the underlying channel goes inactive, the ProxyConnection moves into ConnectionState.DISCONNECTED
• becameWritable() - When the underlying channel becomes writeable, this callback is invoked.

By default, incoming data on the underlying channel is automatically read and passed to the read(Object) method. Reading can be stopped and resumed using stopReading() and resumeReading().

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected class	ProxyConnection.BytesReadMonitor Utility handler for monitoring bytes read on this connection.
protected class	ProxyConnection.BytesWrittenMonitor Utility handler for monitoring bytes written on this connection.
protected class	ProxyConnection.RequestReadMonitor Utility handler for monitoring requests read on this connection.
protected class	ProxyConnection.RequestWrittenMonitor Utility handler for monitoring requests written on this connection.
protected class	ProxyConnection.ResponseReadMonitor Utility handler for monitoring responses read on this connection.
protected class	ProxyConnection.ResponseWrittenMonitor Utility handler for monitoring responses written on this connection.

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

ChannelHandler.Sharable

Field Summary

Fields

Modifier and Type	Field and Description
protected Channel	channel
protected ChannelHandlerContext	ctx
private ConnectionState	currentState
protected long	lastReadTime
protected ProxyConnectionLogger	LOG
protected DefaultHttpProxyServer	proxyServer
protected boolean	runsAsSslClient
protected SSLEngine	sslEngine If using encryption, this holds our SSLEngine.
protected ConnectionFlowStep	StartTunneling Enables tunneling on this connection by dropping the HTTP related encoders and decoders, as well as idle timers.
private boolean	tunneling

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ProxyConnection(ConnectionState initialState, DefaultHttpProxyServer proxyServer, boolean runsAsSslClient) Construct a new ProxyConnection.

Method Summary

Modifier and Type	Method and Description
protected void	aggregateContentForFiltering(ChannelPipeline pipeline, int numberOfBytesToBuffer) Enables decompression and aggregation of content, which is useful for certain types of filtering activity.
protected void	becameSaturated() Callback that's invoked if this connection becomes saturated.
protected void	becameWritable() Callback that's invoked when this connection becomes writeable again.
protected void	become(ConnectionState state) Udpates the current state to the given value.
void	channelActive(ChannelHandlerContext ctx) Only once the Netty Channel is active to we recognize the ProxyConnection as connected.
void	channelInactive(ChannelHandlerContext ctx) As soon as the Netty Channel is inactive, we recognize the ProxyConnection as disconnected.
protected void	channelRead0(ChannelHandlerContext ctx, Object msg) Adapting the Netty API
void	channelRegistered(ChannelHandlerContext ctx)
void	channelWritabilityChanged(ChannelHandlerContext ctx)
private void	closeChannel(Promise<Void> promise)
protected void	connected() This method is called as soon as the underlying Channel is connected.
(package private) Future<Void>	disconnect() Disconnects.
protected void	disconnected() This method is called as soon as the underlying Channel becomes disconnected.
(package private) void	doWrite(Object msg)
protected Future<Channel>	encrypt(ChannelPipeline pipeline, SSLEngine sslEngine, boolean authenticateClients) Encrypts traffic on this connection with SSL/TLS.
protected Future<Channel>	encrypt(SSLEngine sslEngine, boolean authenticateClients) Encrypts traffic on this connection with SSL/TLS.
protected ConnectionFlowStep	EncryptChannel(SSLEngine sslEngine) Encrypts the channel using the provided SSLEngine.
void	exceptionCaught(ChannelHandlerContext ctx, Throwable cause)
protected void	exceptionCaught(Throwable cause) Override this to handle exceptions that occurred during asynchronous processing on the Channel.
protected ConnectionState	getCurrentState()
protected HttpFilters	getHttpFiltersFromProxyServer(HttpRequest httpRequest) Request the ProxyServer for Filters.
(package private) ProxyConnectionLogger	getLOG()
SSLEngine	getSslEngine()
protected boolean	is(ConnectionState state) Utility for checking current state.
protected boolean	isConnecting() If this connection is currently in the process of going through a ConnectionFlow, this will return true.
protected boolean	isSaturated() Indicates whether or not this connection is saturated (i.e.
boolean	isTunneling()
protected void	read(Object msg) Read is invoked automatically by Netty as messages arrive on the socket.
private void	readHTTP(HttpObject httpObject) Handles reading HttpObjects.
protected abstract void	readHTTPChunk(HttpContent chunk) Implement this to handle reading a chunk in a chunked transfer.
protected abstract ConnectionState	readHTTPInitial(I httpObject) Implement this to handle reading the initial object (e.g.
protected abstract void	readRaw(ByteBuf buf) Implement this to handle reading a raw buffer as they are used in HTTP tunneling.
protected void	resumeReading() Call this to resume reading.
protected void	stopReading() Call this to stop reading.
protected void	timedOut() This method is called when the underlying Channel times out due to an idle timeout.
void	userEventTriggered(ChannelHandlerContext ctx, Object evt) We're looking for IdleStateEvents to see if we need to disconnect.
(package private) void	write(Object msg) This method is called by users of the ProxyConnection to send stuff out over the socket.
protected void	writeHttp(HttpObject httpObject) Writes HttpObjects to the connection asynchronously.
protected void	writeRaw(ByteBuf buf) Writes raw buffers to the connection.
protected ChannelFuture	writeToChannel(Object msg)

Methods inherited from class io.netty.channel.SimpleChannelInboundHandler

acceptInboundMessage, channelRead

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelReadComplete, channelUnregistered

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

ensureNotSharable, handlerAdded, handlerRemoved, isSharable

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.netty.channel.ChannelHandler

handlerAdded, handlerRemoved

Field Detail

LOG

protected final ProxyConnectionLogger LOG

proxyServer

protected final DefaultHttpProxyServer proxyServer

runsAsSslClient

protected final boolean runsAsSslClient

ctx

protected volatile ChannelHandlerContext ctx

channel

protected volatile Channel channel

currentState

private volatile ConnectionState currentState

tunneling

private volatile boolean tunneling

lastReadTime

protected volatile long lastReadTime

sslEngine

protected volatile SSLEngine sslEngine

If using encryption, this holds our SSLEngine.

StartTunneling

protected ConnectionFlowStep StartTunneling

Enables tunneling on this connection by dropping the HTTP related encoders and decoders, as well as idle timers.

Note - the work is done on the ChannelHandlerContext's executor because ChannelPipeline.remove(String) can deadlock if called directly.

Constructor Detail

ProxyConnection

protected ProxyConnection(ConnectionState initialState,
                          DefaultHttpProxyServer proxyServer,
                          boolean runsAsSslClient)

Construct a new ProxyConnection.

Parameters:

initialState - the state in which this connection starts out

proxyServer - the DefaultHttpProxyServer in which we're running

runsAsSslClient - determines whether this connection acts as an SSL client or server (determines who does the handshake)

Method Detail

read

protected void read(Object msg)

Read is invoked automatically by Netty as messages arrive on the socket.

Parameters:

msg -

readHTTP

private void readHTTP(HttpObject httpObject)

Handles reading HttpObjects.

Parameters:

httpObject -

readHTTPInitial

protected abstract ConnectionState readHTTPInitial(I httpObject)

Implement this to handle reading the initial object (e.g. HttpRequest or HttpResponse).

Parameters:

httpObject -

Returns:

readHTTPChunk

protected abstract void readHTTPChunk(HttpContent chunk)

Implement this to handle reading a chunk in a chunked transfer.

Parameters:

chunk -

readRaw

protected abstract void readRaw(ByteBuf buf)

Implement this to handle reading a raw buffer as they are used in HTTP tunneling.

Parameters:

buf -

write

void write(Object msg)

This method is called by users of the ProxyConnection to send stuff out over the socket.

Parameters:

msg -

doWrite

void doWrite(Object msg)

writeHttp

protected void writeHttp(HttpObject httpObject)

Writes HttpObjects to the connection asynchronously.

Parameters:

httpObject -

writeRaw

protected void writeRaw(ByteBuf buf)

Writes raw buffers to the connection.

Parameters:

buf -

writeToChannel

protected ChannelFuture writeToChannel(Object msg)

connected

protected void connected()

This method is called as soon as the underlying Channel is connected. Note that for proxies with complex ConnectionFlows that include SSL handshaking and other such things, just because the Channel is connected doesn't mean that our connection is fully established.

disconnected

protected void disconnected()

This method is called as soon as the underlying Channel becomes disconnected.

timedOut

protected void timedOut()

This method is called when the underlying Channel times out due to an idle timeout.

encrypt

protected Future<Channel> encrypt(SSLEngine sslEngine,
                                  boolean authenticateClients)

Encrypts traffic on this connection with SSL/TLS.

Parameters:

sslEngine - the SSLEngine for doing the encryption

authenticateClients - determines whether to authenticate clients or not

Returns:

a Future for when the SSL handshake has completed

encrypt

protected Future<Channel> encrypt(ChannelPipeline pipeline,
                                  SSLEngine sslEngine,
                                  boolean authenticateClients)

Encrypts traffic on this connection with SSL/TLS.

Parameters:

pipeline - the ChannelPipeline on which to enable encryption

sslEngine - the SSLEngine for doing the encryption

authenticateClients - determines whether to authenticate clients or not

Returns:

a Future for when the SSL handshake has completed

EncryptChannel

protected ConnectionFlowStep EncryptChannel(SSLEngine sslEngine)

Encrypts the channel using the provided SSLEngine.

Parameters:

sslEngine - the SSLEngine for doing the encryption

aggregateContentForFiltering

protected void aggregateContentForFiltering(ChannelPipeline pipeline,
                                            int numberOfBytesToBuffer)

Enables decompression and aggregation of content, which is useful for certain types of filtering activity.

Parameters:

pipeline -

numberOfBytesToBuffer -

becameSaturated

protected void becameSaturated()

Callback that's invoked if this connection becomes saturated.

becameWritable

protected void becameWritable()

Callback that's invoked when this connection becomes writeable again.

exceptionCaught

protected void exceptionCaught(Throwable cause)

Override this to handle exceptions that occurred during asynchronous processing on the Channel.

Parameters:

cause -

disconnect

Future<Void> disconnect()

Disconnects. This will wait for pending writes to be flushed before disconnecting.

Returns:

Future for when we're done disconnecting. If we weren't connected, this returns null.

closeChannel

private void closeChannel(Promise<Void> promise)

isSaturated

protected boolean isSaturated()

Indicates whether or not this connection is saturated (i.e. not writeable).

Returns:

is

protected boolean is(ConnectionState state)

Utility for checking current state.

Parameters:

state -

Returns:

isConnecting

protected boolean isConnecting()

If this connection is currently in the process of going through a ConnectionFlow, this will return true.

Returns:

become

protected void become(ConnectionState state)

Udpates the current state to the given value.

Parameters:

state -

getCurrentState

protected ConnectionState getCurrentState()

isTunneling

public boolean isTunneling()

getSslEngine

public SSLEngine getSslEngine()

stopReading

protected void stopReading()

Call this to stop reading.

resumeReading

protected void resumeReading()

Call this to resume reading.

getHttpFiltersFromProxyServer

protected HttpFilters getHttpFiltersFromProxyServer(HttpRequest httpRequest)

Request the ProxyServer for Filters. By default, no-op filters are returned by DefaultHttpProxyServer. Subclasses of ProxyConnection can change this behaviour.

Parameters:

httpRequest - Filter attached to the give HttpRequest (if any)

Returns:

getLOG

ProxyConnectionLogger getLOG()

channelRead0

protected final void channelRead0(ChannelHandlerContext ctx,
                                  Object msg)
                           throws Exception

Adapting the Netty API

Specified by:

channelRead0 in class SimpleChannelInboundHandler<Object>

Throws:

Exception

channelRegistered

public void channelRegistered(ChannelHandlerContext ctx)
                       throws Exception

Specified by:

channelRegistered in interface ChannelInboundHandler

Overrides:

channelRegistered in class ChannelInboundHandlerAdapter

Throws:

Exception

channelActive

public final void channelActive(ChannelHandlerContext ctx)
                         throws Exception

Only once the Netty Channel is active to we recognize the ProxyConnection as connected.

Specified by:

channelActive in interface ChannelInboundHandler

Overrides:

channelActive in class ChannelInboundHandlerAdapter

Throws:

Exception

channelInactive

public void channelInactive(ChannelHandlerContext ctx)
                     throws Exception

As soon as the Netty Channel is inactive, we recognize the ProxyConnection as disconnected.

Specified by:

channelInactive in interface ChannelInboundHandler

Overrides:

channelInactive in class ChannelInboundHandlerAdapter

Throws:

Exception

channelWritabilityChanged

public final void channelWritabilityChanged(ChannelHandlerContext ctx)
                                     throws Exception

Specified by:

channelWritabilityChanged in interface ChannelInboundHandler

Overrides:

channelWritabilityChanged in class ChannelInboundHandlerAdapter

Throws:

Exception

exceptionCaught

public final void exceptionCaught(ChannelHandlerContext ctx,
                                  Throwable cause)
                           throws Exception

Specified by:

exceptionCaught in interface ChannelHandler

Specified by:

exceptionCaught in interface ChannelInboundHandler

Overrides:

exceptionCaught in class ChannelInboundHandlerAdapter

Throws:

Exception

userEventTriggered

public final void userEventTriggered(ChannelHandlerContext ctx,
                                     Object evt)
                              throws Exception

We're looking for IdleStateEvents to see if we need to disconnect.

Note - we don't care what kind of IdleState we got. Thanks to qbast for pointing this out.

Specified by:

userEventTriggered in interface ChannelInboundHandler

Overrides:

userEventTriggered in class ChannelInboundHandlerAdapter

Throws:

Exception