HttpFilters (LittleProxy 2.0.19 API)

All Known Implementing Classes:

HttpFiltersAdapter
```
public interface HttpFilters
```
Interface for objects that filter HttpObjects, including both requests and responses, and informs of different steps in request/response.

Multiple methods are defined, corresponding to different steps in the request processing lifecycle. Some of these methods is given the current object (request, response or chunk) and is allowed to modify it in place. Others provide a notification of when specific operations happen (i.e. connection in queue, DNS resolution, SSL handshaking and so forth).

Because HTTP transfers can be chunked, for any given request or response, the filter methods that can modify request/response in place may be called multiple times, once for the initial HttpRequest or HttpResponse, and once for each subsequent HttpContent. The last chunk will always be a LastHttpContent and can be checked for being last using ProxyUtils.isLastChunk(HttpObject).

HttpFiltersSource.getMaximumRequestBufferSizeInBytes() and HttpFiltersSource.getMaximumResponseBufferSizeInBytes() can be used to instruct the proxy to buffer the HttpObjects sent to all of its request/response filters, in which case it will buffer up to the specified limit and then send either complete HttpRequests or HttpResponses to the filter methods. When buffering, if the proxy receives more data than fits in the specified maximum bytes to buffer, the proxy will stop processing the request and respond with a 502 Bad Gateway error.

A new instance of HttpFilters is created for each request, so these objects can be stateful.

To monitor (and time measure?) the different steps the request/response goes through, many informative methods are provided. Those steps are reported in the following order:
1. clientToProxyRequest
2. proxyToServerConnectionQueued
3. proxyToServerResolutionStarted
4. proxyToServerResolutionSucceeded
5. proxyToServerRequest (can be multiple if chunked)
6. proxyToServerConnectionStarted
7. proxyToServerConnectionFailed (if connection couldn't be established)
8. proxyToServerConnectionSSLHandshakeStarted (only if HTTPS required)
9. proxyToServerConnectionSucceeded
10. proxyToServerRequestSending
11. proxyToServerRequestSent
12. serverToProxyResponseReceiving
13. serverToProxyResponse (can be multiple if chunked)
14. serverToProxyResponseReceived
15. proxyToClientResponse

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`HttpResponse`	`clientToProxyRequest(HttpObject httpObject)` Filters requests on their way from the client to the proxy.
`HttpObject`	`proxyToClientResponse(HttpObject httpObject)` Filters responses on their way from the proxy to the client.
`boolean`	`proxyToServerAllowMitm()` Allow this proxy to act as an SSL man in the middle.
`void`	`proxyToServerConnectionFailed()` Informs filter that proxy to server connection has failed.
`void`	`proxyToServerConnectionQueued()` Informs filter that proxy to server connection is in queue.
`void`	`proxyToServerConnectionSSLHandshakeStarted()` Informs filter that proxy to server ssl handshake is initiating.
`void`	`proxyToServerConnectionStarted()` Informs filter that proxy to server connection is initiating.
`void`	`proxyToServerConnectionSucceeded(ChannelHandlerContext serverCtx)` Informs filter that proxy to server connection has succeeded.
`HttpResponse`	`proxyToServerRequest(HttpObject httpObject)` Filters requests on their way from the proxy to the server.
`void`	`proxyToServerRequestSending()` Informs filter that proxy to server request is being sent.
`void`	`proxyToServerRequestSent()` Informs filter that the HTTP request, including any content, has been sent.
`void`	`proxyToServerResolutionFailed(String hostAndPort)` Informs filter that proxy to server DNS resolution failed for the specified host and port.
`InetSocketAddress`	`proxyToServerResolutionStarted(String resolvingServerHostAndPort)` Filter DNS resolution from proxy to server.
`void`	`proxyToServerResolutionSucceeded(String serverHostAndPort, InetSocketAddress resolvedRemoteAddress)` Informs filter that proxy to server DNS resolution has happened.
`HttpObject`	`serverToProxyResponse(HttpObject httpObject)` Filters responses on their way from the server to the proxy.
`void`	`serverToProxyResponseReceived()` Informs filter that server to proxy response has been received.
`void`	`serverToProxyResponseReceiving()` Informs filter that server to proxy response is being received.
`void`	`serverToProxyResponseTimedOut()` Informs filter that a timeout occurred before the server response was received by the client.

- Method Detail
  - clientToProxyRequest
```
HttpResponse clientToProxyRequest(HttpObject httpObject)
```
    Filters requests on their way from the client to the proxy. To interrupt processing of this request and return a response to the client immediately, return an HttpResponse here. Otherwise, return null to continue processing as usual.
    Important: When returning a response, you must include a mechanism to allow the client to determine the length of the message (see RFC 7230, section 3.3.3: https://tools.ietf.org/html/rfc7230#section-3.3.3 ). For messages that may contain a body, you may do this by setting the Transfer-Encoding to chunked, setting an appropriate Content-Length, or by adding a "Connection: close" header to the response (which will instruct LittleProxy to close the connection). If the short-circuit response contains body content, it is recommended that you return a FullHttpResponse.
    
    Parameters:
    
    httpObject - Client to Proxy HttpRequest (and HttpContent, if chunked)
    
    Returns:
    
    a short-circuit response, or null to continue processing as usual
  - proxyToServerRequest
```
HttpResponse proxyToServerRequest(HttpObject httpObject)
```
    Filters requests on their way from the proxy to the server. To interrupt processing of this request and return a response to the client immediately, return an HttpResponse here. Otherwise, return null to continue processing as usual.
    Important: When returning a response, you must include a mechanism to allow the client to determine the length of the message (see RFC 7230, section 3.3.3: https://tools.ietf.org/html/rfc7230#section-3.3.3 ). For messages that may contain a body, you may do this by setting the Transfer-Encoding to chunked, setting an appropriate Content-Length, or by adding a "Connection: close" header to the response. (which will instruct LittleProxy to close the connection). If the short-circuit response contains body content, it is recommended that you return a FullHttpResponse.
    
    Parameters:
    
    httpObject - Proxy to Server HttpRequest (and HttpContent, if chunked)
    
    Returns:
    
    a short-circuit response, or null to continue processing as usual
  - proxyToServerRequestSending
```
void proxyToServerRequestSending()
```
    Informs filter that proxy to server request is being sent.
  - proxyToServerRequestSent
```
void proxyToServerRequestSent()
```
    Informs filter that the HTTP request, including any content, has been sent.
  - serverToProxyResponse
```
HttpObject serverToProxyResponse(HttpObject httpObject)
```
    Filters responses on their way from the server to the proxy.
    
    Parameters:
    
    httpObject - Server to Proxy HttpResponse (and HttpContent, if chunked)
    
    Returns:
    
    the modified (or unmodified) HttpObject. Returning null will force a disconnect.
  - serverToProxyResponseTimedOut
```
void serverToProxyResponseTimedOut()
```
    Informs filter that a timeout occurred before the server response was received by the client. The timeout may have occurred while the client was sending the request, waiting for a response, or after the client started receiving a response (i.e. if the response from the server "stalls"). See HttpProxyServerBootstrap.withIdleConnectionTimeout(int) for information on setting the timeout.
  - serverToProxyResponseReceiving
```
void serverToProxyResponseReceiving()
```
    Informs filter that server to proxy response is being received.
  - serverToProxyResponseReceived
```
void serverToProxyResponseReceived()
```
    Informs filter that server to proxy response has been received.
  - proxyToClientResponse
```
HttpObject proxyToClientResponse(HttpObject httpObject)
```
    Filters responses on their way from the proxy to the client.
    
    Parameters:
    
    httpObject - Proxy to Client HttpResponse (and HttpContent, if chunked)
    
    Returns:
    
    the modified (or unmodified) HttpObject. Returning null will force a disconnect.
  - proxyToServerConnectionQueued
```
void proxyToServerConnectionQueued()
```
    Informs filter that proxy to server connection is in queue.
  - proxyToServerResolutionStarted
```
InetSocketAddress proxyToServerResolutionStarted(String resolvingServerHostAndPort)
```
    Filter DNS resolution from proxy to server.
    
    Parameters:
    
    resolvingServerHostAndPort - Server "HOST:PORT"
    
    Returns:
    
    alternative address resolution. Returning null will let normal DNS resolution continue.
  - proxyToServerResolutionFailed
```
void proxyToServerResolutionFailed(String hostAndPort)
```
    Informs filter that proxy to server DNS resolution failed for the specified host and port.
    
    Parameters:
    
    hostAndPort - hostname and port the proxy failed to resolve
  - proxyToServerResolutionSucceeded
```
void proxyToServerResolutionSucceeded(String serverHostAndPort,
                                      InetSocketAddress resolvedRemoteAddress)
```
    Informs filter that proxy to server DNS resolution has happened.
    
    Parameters:
    
    serverHostAndPort - Server "HOST:PORT"
    
    resolvedRemoteAddress - Address it was proxyToServerResolutionSucceeded to
  - proxyToServerConnectionStarted
```
void proxyToServerConnectionStarted()
```
    Informs filter that proxy to server connection is initiating.
  - proxyToServerConnectionSSLHandshakeStarted
```
void proxyToServerConnectionSSLHandshakeStarted()
```
    Informs filter that proxy to server ssl handshake is initiating.
  - proxyToServerConnectionFailed
```
void proxyToServerConnectionFailed()
```
    Informs filter that proxy to server connection has failed.
  - proxyToServerConnectionSucceeded
```
void proxyToServerConnectionSucceeded(ChannelHandlerContext serverCtx)
```
    Informs filter that proxy to server connection has succeeded.
    
    Parameters:
    
    serverCtx - the ChannelHandlerContext used to connect to the server
  - proxyToServerAllowMitm
```
boolean proxyToServerAllowMitm()
```
    Allow this proxy to act as an SSL man in the middle.
    Has no impact if man in the middle is not enabled.
    
    Returns:
    
    true to allow mitm, false to not mitm the proxy to server connection.

Interface HttpFilters

Method Summary

Method Detail

clientToProxyRequest

proxyToServerRequest

proxyToServerRequestSending

proxyToServerRequestSent

serverToProxyResponse

serverToProxyResponseTimedOut

serverToProxyResponseReceiving

serverToProxyResponseReceived

proxyToClientResponse

proxyToServerConnectionQueued

proxyToServerResolutionStarted

proxyToServerResolutionFailed

proxyToServerResolutionSucceeded

proxyToServerConnectionStarted

proxyToServerConnectionSSLHandshakeStarted

proxyToServerConnectionFailed

proxyToServerConnectionSucceeded

proxyToServerAllowMitm