Package org.microproxy

Class HttpFiltersBuilder

java.lang.Object
org.microproxy.HttpFiltersBuilder
public final class HttpFiltersBuilder extends Object
Builds HttpFilters from lambdas, one per hook, instead of a class that overrides the hooks it needs: 

 HttpFilters filters = HttpFilters.builder()
         .onRequest(req -> req.uri().endsWith("/blocked") ? forbidden() : null)
         .onResponse(res -> { res.headers().set("X-Proxy", "micro"); return res; })
         .onWebSocketFrame((frame, fromClient) -> frame.isPing() ? null : frame)
         .onWebSocketMessage((msg, fromClient) -> msg.isText() ? msg.withText(msg.text().trim()) : msg)
         .build();
 MicroProxy.bootstrap().withFiltersSource((request, ctx) -> filters).start();

Registering the same hook twice runs both, in order: the first short-circuit response wins, and transformations feed into each other (null aborts, as in HttpFiltersChain).

Bodies, WebSocket frames and messages are only parsed into pieces when a body, frame or message hook was registered (HttpFiltersBuilder.Built.sees(org.microproxy.HttpFiltersBuilder.Body)); otherwise they are relayed by the proxy's fast path, just as for a filters class that does not override those hooks. The built filters keep no state of their own, so one instance can serve every request if the lambdas allow it.

  • Method Details

    • onRequest

      public HttpFiltersBuilder onRequest(Function<HttpRequest,HttpResponse> hook)
      The request head as the client sent it (clientToProxyRequest); a whole FullHttpRequest when buffered (bufferRequests(int)). Return a response to answer without contacting the server, or null to continue.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • onRequestBody

      public HttpFiltersBuilder onRequestBody(Consumer<HttpContent> hook)
      Each piece of a streamed request body, ending with a LastHttpContent.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • beforeSending

      public HttpFiltersBuilder beforeSending(Function<HttpRequest,HttpResponse> hook)
      The request head just before it goes to the server (proxyToServerRequest), with the proxy's own header changes applied. Return a response to answer instead, or null.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • onResponse

      public HttpFiltersBuilder onResponse(UnaryOperator<HttpResponse> hook)
      The response head from the server (serverToProxyResponse); a whole FullHttpResponse when buffered (bufferResponses(int)). Return it (changed or not), a replacement, or null to abort the exchange.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • onResponseBody

      public HttpFiltersBuilder onResponseBody(UnaryOperator<HttpContent> hook)
      Each piece of a streamed response body: return it, a replacement, or null to abort.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • beforeResponding

      public HttpFiltersBuilder beforeResponding(UnaryOperator<HttpResponse> hook)
      The response head just before it goes to the client (proxyToClientResponse).
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • onFailure

      public HttpFiltersBuilder onFailure(Function<ProxyFailure,HttpResponse> hook)
      The proxy's own answer when the request fails (proxyToServerFailure): return a response to send instead of the default, or null.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • onWebSocketFrame

      public HttpFiltersBuilder onWebSocketFrame(BiFunction<WebSocketFrame,Boolean,WebSocketFrame> hook)
      Each WebSocket frame, with whether it came from the client: return it, a replacement, or null to drop it (see HttpFilters.filterWebSocketFrame(org.microproxy.http.WebSocketFrame, boolean)).
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • onWebSocketMessage

      public HttpFiltersBuilder onWebSocketMessage(BiFunction<WebSocketMessage,Boolean,WebSocketMessage> hook)
      Each whole WebSocket message, joined from its frames (and inflated), with whether it came from the client: return it, a replacement, or null to drop it (see HttpFilters.filterWebSocketMessage(org.microproxy.http.WebSocketMessage, boolean)). With onWebSocketFrame as well, frames go through that hook first.
      Parameters:
      hook - the callback for this filter stage
      Returns:
      this builder

    • resolveWith

      public HttpFiltersBuilder resolveWith(Function<String,InetSocketAddress> resolver)
      Chooses the server address for host:port; null resolves as usual.
      Parameters:
      resolver - the function selecting a destination address
      Returns:
      this builder

    • allowMitm

      public HttpFiltersBuilder allowMitm(BooleanSupplier allow)
      Whether CONNECT requests may be intercepted (default true when MITM is configured).
      Parameters:
      allow - the supplier deciding whether interception is allowed
      Returns:
      this builder

    • allowMitmFor

      public HttpFiltersBuilder allowMitmFor(Predicate<? super ClientHello> allow)
      Whether a TLS connection may be intercepted, decided from the client's ClientHello (its server name and ALPN protocols); see HttpFilters.proxyToServerAllowMitm(ClientHello). Default: yes.
      Parameters:
      allow - the predicate deciding from the ClientHello whether interception is allowed
      Returns:
      this builder

    • tlsIdentity

      public HttpFiltersBuilder tlsIdentity(Function<String,TlsServerIdentity> identity)
      The TLS identity (server name and verification host) of these requests' connections to servers, by the server's host:port; see HttpFilters.proxyToServerTlsIdentity(java.lang.String). Return null for the default.
      Parameters:
      identity - the function choosing the identity for a server's host:port
      Returns:
      this builder

    • connectTimeout

      public HttpFiltersBuilder connectTimeout(Duration timeout)
      The connect timeout for these requests' new connections, instead of the server's (see HttpFilters.proxyToServerConnectTimeout()).
      Parameters:
      timeout - the outbound connection timeout override
      Returns:
      this builder

    • tlsHandshakeTimeout

      public HttpFiltersBuilder tlsHandshakeTimeout(Duration timeout)
      The upstream TLS handshake timeout for these requests' new connections, instead of the server's (see HttpFilters.proxyToServerTlsHandshakeTimeout()).
      Parameters:
      timeout - the TLS handshake timeout override, positive
      Returns:
      this builder

    • retryBackoff

      public HttpFiltersBuilder retryBackoff(RetryBackoff backoff)
      The backoff between these requests' attempts at the routes the ChainedProxyManager offered, instead of the server's (see HttpFilters.chainedProxyRetryBackoff()); RetryBackoff.none() retries at once.
      Parameters:
      backoff - the retry backoff override
      Returns:
      this builder

    • mitmServerHandshake

      public HttpFiltersBuilder mitmServerHandshake(MitmServerHandshake handshake)
      When the proxy runs its TLS handshake with the server for these requests' intercepted CONNECTs, instead of the protocol policy's choice (see HttpFilters.proxyToServerMitmHandshake()).
      Parameters:
      handshake - when the server's handshake runs
      Returns:
      this builder

    • bufferRequests

      public HttpFiltersBuilder bufferRequests(int maxBytes)
      Buffer request bodies up to maxBytes, so onRequest gets the whole request.
      Parameters:
      maxBytes - the maximum number of body bytes
      Returns:
      this builder

    • bufferResponses

      public HttpFiltersBuilder bufferResponses(int maxBytes)
      Buffer response bodies up to maxBytes, so onResponse gets the whole response.
      Parameters:
      maxBytes - the maximum number of body bytes
      Returns:
      this builder

    • log

      public HttpFiltersBuilder log(HttpLogger logger)
      Logs each exchange with logger, around these hooks: requests as the client sent them (before onRequest) and as forwarded (after beforeSending), responses as the server sent them (before onResponse) and as delivered (after beforeResponding). Bodies are only parsed when the logger's level needs them.

      The logger keeps state per exchange. The proxy gives each exchange its own copy of the built filters for that state, whether they are the source (withFiltersSource(built), plusFiltersSource(built), a member of an HttpFiltersChain) or are returned from another source, such as withFiltersSource((request, ctx) -> built). Wrapped in filters of your own that delegate to them, they run their hooks but log nothing (with one warning).

      Parameters:
      logger - the exchange logger
      Returns:
      this builder

    • build

      public HttpFiltersBuilder.Built build()
      Creates a filter source combining the configured hooks.
      Returns:
      the combined per-request filter source