Package org.littleshoot.proxy

Interface HttpFilters

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 Details

    • 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.