- Unify body and head interceptor in a single builder

- Add max buffered size during body interception
- Handle body and head interception failures

Motivation:

The body and head interception API can be unified further more by providing a single interceptor instead of two interceptors.

The current body transformation API assumes buffering and therefore uses buffer cumulation, therefore it should have an upper bound regarding this cumulation.

The interceptor implementation does not handle failures such as a transformation failure or a buffer overflow.

Author: vietj

src/main/asciidoc/index.adoc

@@ -134,26 +134,24 @@ You can filter body by simply replacing the original {@link io.vertx.httpproxy.B
 {@link io.vertx.httpproxy.ProxyContext#sendRequest} and {@link io.vertx.httpproxy.ProxyContext#sendResponse} continue the
 current interception chain and then send the result to the origin server or the user-agent.
 
-You can change the control, e.g you can send a response immediately to the user-agent without even requesting the origin server
+You can change the control, e.g. you can send a response immediately to the user-agent without even requesting the origin server
 
 [source,java]
 ----
 {@link examples.HttpProxyExamples#immediateResponse}
 ----
 
-==== Head interceptor
+==== Customizable interceptor
 
-You can use the {@link io.vertx.httpproxy.interceptors.HeadInterceptor} to change HTTP request/response heads:
+You can use {@link io.vertx.httpproxy.ProxyInterceptor#builder()} that facilitates the implementation of an interceptor
+that modifies the request/response heads and bodies:
 
 - request path
 - query params
 - request and response headers
+- body transformation
 
-A {@link io.vertx.httpproxy.interceptors.HeadInterceptor} is created and configured with a {@link io.vertx.httpproxy.interceptors.HeadInterceptorBuilder}.
-
-The builder methods can be invoked several times.
-Operations on the path will be invoked in the order of configuration.
-That goes for operations on query parameters, request headers and response headers.
+Such interceptor is created and configured with a {@link io.vertx.httpproxy.ProxyInterceptorBuilder}.
 
 ===== Headers interception
 
@@ -164,7 +162,9 @@ You can apply the interceptor to change headers from the request and response wi
 {@link examples.HttpProxyExamples#headerInterceptorFilter}
 ----
 
-Check out {@link io.vertx.httpproxy.interceptors.HeadInterceptorBuilder} for details about the available methods.
+Headers modifying methods can be invoked several times, operations are applied in the order of configuration.
+
+Check out {@link io.vertx.httpproxy.ProxyInterceptorBuilder} for details about the available methods.
 
 ===== Query params interception
 
@@ -175,18 +175,27 @@ You can apply the interceptor to update or remove query parameters:
 {@link examples.HttpProxyExamples#queryInterceptorAdd}
 ----
 
-You can also refer to {@link io.vertx.httpproxy.interceptors.HeadInterceptorBuilder} for more information.
+Query params modifying methods can be invoked several times, operations are applied in the order of configuration.
+
+You can also refer to {@link io.vertx.httpproxy.ProxyInterceptorBuilder} for more information.
 
 ==== Body interceptor
 
-You can use body interceptor to create body transformations for common data types, like {@link io.vertx.core.json.JsonObject}:
+You can use body interceptor to create body transformations.
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#bodyInterceptorJson}
+----
+
+{@link io.vertx.httpproxy.BodyTransformer} provides transformation for common data types, like {@link io.vertx.core.json.JsonObject}:
 
 [source,java]
 ----
 {@link examples.HttpProxyExamples#bodyInterceptorJson}
 ----
 
-Please check the {@link io.vertx.httpproxy.interceptors.BodyTransformer} for other supported transformations.
+Please check the {@link io.vertx.httpproxy.BodyTransformer} for other supported transformations.
 
 ==== Interception and WebSocket upgrades
 

src/main/java/examples/HttpProxyExamples.java

@@ -13,9 +13,7 @@
 import io.vertx.core.net.SocketAddress;
 import io.vertx.httpproxy.*;
 import io.vertx.httpproxy.cache.CacheOptions;
-import io.vertx.httpproxy.interceptors.BodyInterceptor;
-import io.vertx.httpproxy.interceptors.BodyTransformer;
-import io.vertx.httpproxy.interceptors.HeadInterceptor;
+import io.vertx.httpproxy.BodyTransformer;
 
 import java.util.Set;
 
@@ -111,25 +109,39 @@ public Future<Void> handleProxyResponse(ProxyContext context) {
   public void headerInterceptorFilter(HttpProxy proxy, Set<CharSequence> shouldRemove) {
     // remove a set of headers
     proxy.addInterceptor(
-      HeadInterceptor.builder().filteringResponseHeaders(shouldRemove).build());
+      ProxyInterceptor.builder().filteringResponseHeaders(shouldRemove).build());
   }
 
   public void queryInterceptorAdd(HttpProxy proxy, String key, String value) {
     proxy.addInterceptor(
-      HeadInterceptor.builder().settingQueryParam(key, value).build());
+      ProxyInterceptor.builder().settingQueryParam(key, value).build());
+  }
+
+  public void bodyInterceptorTransformer(HttpProxy proxy) {
+    proxy.addInterceptor(
+      ProxyInterceptor
+        .builder()
+        .transformingResponseBody(
+          buffer -> {
+            // Apply some transformation
+            return buffer;
+          }
+        ).build());
   }
 
   public void bodyInterceptorJson(HttpProxy proxy) {
     proxy.addInterceptor(
-      BodyInterceptor.modifyResponseBody(
-        BodyTransformer.transformJsonObject(
-          jsonObject -> removeSomeFields(jsonObject)
-        )
-      ));
+      ProxyInterceptor
+        .builder()
+        .transformingResponseBody(
+          BodyTransformer.transformJsonObject(
+            jsonObject -> removeSomeFields(jsonObject)
+          )
+        ).build());
   }
 
   public void webSocketInterceptorPath(HttpProxy proxy) {
-    HeadInterceptor interceptor = HeadInterceptor.builder()
+    ProxyInterceptor interceptor = ProxyInterceptor.builder()
       .addingPathPrefix("/api")
       .build();
     proxy.addInterceptor(interceptor, true);

src/main/java/io/vertx/httpproxy/interceptors/BodyTransformer.java renamed to src/main/java/io/vertx/httpproxy/BodyTransformer.java

@@ -1,16 +1,16 @@
-package io.vertx.httpproxy.interceptors;
+package io.vertx.httpproxy;
 
 import io.vertx.codegen.annotations.Unstable;
 import io.vertx.codegen.annotations.VertxGen;
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.json.JsonArray;
 import io.vertx.core.json.JsonObject;
-import io.vertx.httpproxy.interceptors.impl.BodyTransformerImpl;
+import io.vertx.httpproxy.impl.BodyTransformerImpl;
 
 import java.util.function.Function;
 
 /**
- * The callback to transform the request or response body.
+ * A synchronous function that transforms an HTTP body entity.
  */
 @VertxGen
 @Unstable

src/main/java/io/vertx/httpproxy/ProxyInterceptor.java

@@ -2,13 +2,24 @@
 
 import io.vertx.codegen.annotations.VertxGen;
 import io.vertx.core.Future;
+import io.vertx.httpproxy.impl.interceptor.ProxyInterceptorBuilderImpl;
 
 /**
  * A {@link HttpProxy} interceptor.
  */
-@VertxGen(concrete = false)
+@VertxGen
 public interface ProxyInterceptor {
 
+  /**
+   * Create a builder for implementing common HTTP interception hooks such as modifying headers or transforming
+   * the HTTP entity stream.
+   *
+   * @return a builder for common interception
+   */
+  static ProxyInterceptorBuilder builder() {
+    return new ProxyInterceptorBuilderImpl();
+  }
+
   /**
    * Handle the proxy request at the stage of this interceptor.
    *

src/main/java/io/vertx/httpproxy/interceptors/HeadInterceptorBuilder.java renamed to src/main/java/io/vertx/httpproxy/ProxyInterceptorBuilder.java

@@ -9,7 +9,7 @@
  * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
  */
 
-package io.vertx.httpproxy.interceptors;
+package io.vertx.httpproxy;
 
 import io.vertx.codegen.annotations.Fluent;
 import io.vertx.codegen.annotations.GenIgnore;
@@ -24,20 +24,26 @@
 import static io.vertx.codegen.annotations.GenIgnore.PERMITTED_TYPE;
 
 /**
- * Configuration for an interceptor updating HTTP request/response head attributes (headers, path, query params).
- * <p>
- * All configuration methods can be invoked several times.
- * Operations on the path will be invoked in the order of configuration.
- * That goes for operations on request headers, response headers and query parameters.
+ * <p>>Builder class for a customizable interceptor capable of transforming HTTP request/response head attributes
+ * (headers, path, query params) as well as transforming the HTTP body.</p
+ *
+ * <p>Head transformation methods can be invoked multiple times. Operations on the path will be invoked in the order
+ * of configuration, that goes for operations on request headers, response headers and query parameters.</p>
+ *
+ * <p>Body transformation can be achieved with {@link #transformingResponseBody(BodyTransformer)} and
+ * {@link #transformingRequestBody(BodyTransformer)}. Body transformation buffer the body content and then apply
+ * a transforming function before sending the response.</p>
  */
 @VertxGen
 @Unstable
-public interface HeadInterceptorBuilder {
+public interface ProxyInterceptorBuilder {
+
+  long DEFAULT_MAX_BUFFERED_SIZE = 256 * 1024;
 
   /**
-   * @return an interceptor build according to builder requirements
+   * @return the proxy interceptor build according to builder requirements
    */
-  HeadInterceptor build();
+  ProxyInterceptor build();
 
   /**
    * Apply modifications to the query parameters.
@@ -46,7 +52,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder updatingQueryParams(Handler<MultiMap> updater);
+  ProxyInterceptorBuilder transformingQueryParams(Handler<MultiMap> updater);
 
   /**
    * Add a query parameter to the request.
@@ -56,7 +62,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder settingQueryParam(String name, String value);
+  ProxyInterceptorBuilder settingQueryParam(String name, String value);
 
   /**
    * Remove a query parameter from the request.
@@ -65,7 +71,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder removingQueryParam(String name);
+  ProxyInterceptorBuilder removingQueryParam(String name);
 
   /**
    * Apply a callback to change the request URI when the proxy receives it.
@@ -74,7 +80,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder updatingPath(Function<String, String> mutator);
+  ProxyInterceptorBuilder transformingPath(Function<String, String> mutator);
 
   /**
    * Add a prefix to the URI.
@@ -83,7 +89,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder addingPathPrefix(String prefix);
+  ProxyInterceptorBuilder addingPathPrefix(String prefix);
 
   /**
    * Remove a prefix to the URI. Do nothing if it doesn't exist.
@@ -92,7 +98,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder removingPathPrefix(String prefix);
+  ProxyInterceptorBuilder removingPathPrefix(String prefix);
 
   /**
    * Apply callbacks to change the request headers when the proxy receives them.
@@ -101,7 +107,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder updatingRequestHeaders(Handler<MultiMap> requestHeadersUpdater);
+  ProxyInterceptorBuilder transformingRequestHeaders(Handler<MultiMap> requestHeadersUpdater);
 
   /**
    * Apply callbacks to change the response headers when the proxy receives them.
@@ -110,7 +116,7 @@ public interface HeadInterceptorBuilder {
    * @return a reference to this, so the API can be used fluently
    */
   @Fluent
-  HeadInterceptorBuilder updatingResponseHeaders(Handler<MultiMap> responseHeadersUpdater);
+  ProxyInterceptorBuilder transformingResponseHeaders(Handler<MultiMap> responseHeadersUpdater);
 
   /**
    * Filter the request headers in the given set.
@@ -120,7 +126,7 @@ public interface HeadInterceptorBuilder {
    */
   @GenIgnore(PERMITTED_TYPE)
   @Fluent
-  HeadInterceptorBuilder filteringRequestHeaders(Set<CharSequence> forbiddenRequestHeaders);
+  ProxyInterceptorBuilder filteringRequestHeaders(Set<CharSequence> forbiddenRequestHeaders);
 
   /**
    * Filter the response headers in the given set.
@@ -130,5 +136,46 @@ public interface HeadInterceptorBuilder {
    */
   @GenIgnore(PERMITTED_TYPE)
   @Fluent
-  HeadInterceptorBuilder filteringResponseHeaders(Set<CharSequence> forbiddenResponseHeaders);
+  ProxyInterceptorBuilder filteringResponseHeaders(Set<CharSequence> forbiddenResponseHeaders);
+
+  /**
+   * Like {@link #transformingRequestBody(BodyTransformer, long)} with {@code maxBufferedSize} = {@link #DEFAULT_MAX_BUFFERED_SIZE}
+   */
+  @Fluent
+  default ProxyInterceptorBuilder transformingRequestBody(BodyTransformer requestTransformer) {
+    return transformingRequestBody(requestTransformer, DEFAULT_MAX_BUFFERED_SIZE);
+  }
+
+  /**
+   * <p>Apply a transformation to change the request body when the proxy receives it.</p>
+   *
+   * <p>The interceptor fully buffers the request body and then apply the transformation.</p>
+   *
+   * @param requestTransformer the operation to apply to the request body
+   * @param maxBufferedSize the maximum number of buffered bytes, when the buffered amount exceeds an HTTP error is sent
+   * @return the created interceptor
+   */
+  @Fluent
+  ProxyInterceptorBuilder transformingRequestBody(BodyTransformer requestTransformer, long maxBufferedSize);
+
+  /**
+   * Like {@link #transformingResponseBody(BodyTransformer, long)} with {@code maxBufferedSize} = {@link #DEFAULT_MAX_BUFFERED_SIZE}
+   */
+  @Fluent
+  default ProxyInterceptorBuilder transformingResponseBody(BodyTransformer responseTransformer) {
+    return transformingResponseBody(responseTransformer, DEFAULT_MAX_BUFFERED_SIZE);
+  }
+
+  /**
+   * <p>Apply a transformation to change the response body when the proxy receives it.</p>
+   *
+   * <p>The interceptor fully buffers the response body and then apply the transformation.</p>
+   *
+   * @param responseTransformer the operation to apply to the response body
+   * @param maxBufferedSize the maximum number of buffered bytes, when the buffered amount exceeds an HTTP error is sent
+   * @return the created interceptor
+   */
+  @Fluent
+  ProxyInterceptorBuilder transformingResponseBody(BodyTransformer responseTransformer, long maxBufferedSize);
+
 }

src/main/java/io/vertx/httpproxy/interceptors/impl/BodyTransformerImpl.java renamed to src/main/java/io/vertx/httpproxy/impl/BodyTransformerImpl.java

@@ -1,10 +1,10 @@
-package io.vertx.httpproxy.interceptors.impl;
+package io.vertx.httpproxy.impl;
 
 import io.vertx.core.buffer.Buffer;
 import io.vertx.core.json.Json;
 import io.vertx.core.json.JsonArray;
 import io.vertx.core.json.JsonObject;
-import io.vertx.httpproxy.interceptors.BodyTransformer;
+import io.vertx.httpproxy.BodyTransformer;
 
 import java.util.Objects;
 import java.util.function.Function;