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