Merge pull request #122 from eclipse-vertx/simplify-creation-of-interceptors

Interceptor improvements

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,46 @@ 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 a {@link io.vertx.httpproxy.BodyTransformer} to create body transformations.
+
+A set of predefined transformations facilitates the creation of a transformer.
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#bodyTransformer}
+----
+
+A body transformer is then turned into a proxy interceptor with the builder:
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#bodyInterceptorTransformer}
+----
+
+{@link io.vertx.httpproxy.BodyTransformers} 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.
+Most transformations provided in {@link io.vertx.httpproxy.BodyTransformers} are synchronous and buffer bytes. The default
+maximum amount of bytes is 256K bytes, you can provide a different amount:
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#bodyInterceptorJsonMaxBufferedSize}
+----
+
+Please check the {@link io.vertx.httpproxy.BodyTransformers} for other supported transformations.
+
+NOTE: you can also implement {@link io.vertx.httpproxy.BodyTransformer} contract to best adapt it to your needs.
 
 ==== Interception and WebSocket upgrades
 

src/main/java/examples/HttpProxyExamples.java

@@ -12,9 +12,6 @@
 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 java.util.Set;
 
@@ -111,25 +108,60 @@ 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 bodyTransformer() {
+    BodyTransformer transformer = BodyTransformers.transform(
+      MediaType.APPLICATION_JSON,
+      MediaType.APPLICATION_OCTET_STREAM,
+      buffer -> {
+        // Apply some transformation
+        return buffer;
+      }
+    );
+  }
+
+  public void bodyInterceptorTransformer(HttpProxy proxy, BodyTransformer transformer) {
+    proxy.addInterceptor(
+      ProxyInterceptor
+        .builder()
+        .transformingResponseBody(transformer)
+        .build()
+    );
   }
 
   public void bodyInterceptorJson(HttpProxy proxy) {
     proxy.addInterceptor(
-      BodyInterceptor.modifyResponseBody(
-        BodyTransformer.transformJsonObject(
-          jsonObject -> removeSomeFields(jsonObject)
-        )
-      ));
+      ProxyInterceptor
+        .builder()
+        .transformingResponseBody(
+          BodyTransformers.jsonObject(
+            jsonObject -> removeSomeFields(jsonObject)
+          )
+        ).build());
+  }
+
+  public void bodyInterceptorJsonMaxBufferedSize(HttpProxy proxy) {
+    proxy.addInterceptor(
+      ProxyInterceptor
+        .builder()
+        .transformingResponseBody(
+          BodyTransformers.jsonObject(
+            // Maximum amount of buffered bytes
+            128 * 1024,
+            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/Body.java

@@ -31,7 +31,32 @@ public interface Body {
    * @return a reference to this, so the API can be used fluently
    */
   static Body body(ReadStream<Buffer> stream, long len) {
+    return body(stream, len, MediaType.APPLICATION_OCTET_STREAM);
+  }
+
+  static Body body(ReadStream<Buffer> stream, long len, MediaType mediatype) {
+    return new Body() {
+      @Override
+      public String mediaType() {
+        return mediatype != null ? mediatype.toString() : null;
+      }
+      @Override
+      public long length() {
+        return len;
+      }
+      @Override
+      public ReadStream<Buffer> stream() {
+        return stream;
+      }
+    };
+  }
+
+  static Body body(ReadStream<Buffer> stream, long len, String mediatype) {
     return new Body() {
+      @Override
+      public String mediaType() {
+        return mediatype;
+      }
       @Override
       public long length() {
         return len;
@@ -52,15 +77,24 @@ public ReadStream<Buffer> stream() {
   static Body body(ReadStream<Buffer> stream) {
     return body(stream, -1L);
   }
-  
+
+  static Body body(Buffer buffer) {
+    return body(buffer, MediaType.APPLICATION_OCTET_STREAM);
+  }
+
   /**
    * Create a new {@code Body} instance.
    *
    * @param buffer the {@link Buffer} of the body
+   * @param mediaType the body media type
    * @return a reference to this, so the API can be used fluently
    */
-  static Body body(Buffer buffer) {
+  static Body body(Buffer buffer, MediaType mediaType) {
     return new Body() {
+      @Override
+      public String mediaType() {
+        return mediaType == null ? null : mediaType.toString();
+      }
       @Override
       public long length() {
         return buffer.length();
@@ -72,6 +106,11 @@ public ReadStream<Buffer> stream() {
     };
   }
 
+  /**
+   * @return the media type of this body
+   */
+  String mediaType();
+
   /**
    *
    * Get length of the {@code Body}.

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

@@ -0,0 +1,42 @@
+package io.vertx.httpproxy;
+
+import io.vertx.codegen.annotations.GenIgnore;
+import io.vertx.codegen.annotations.Unstable;
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.core.Future;
+
+/**
+ * A synchronous function that transforms an HTTP body entity.
+ */
+@VertxGen
+@Unstable
+public interface BodyTransformer {
+
+  /**
+   * @return whether this transformer consumes the {@code mediaType}, {@code mediaType} can be {@code null}
+   *         when the HTTP head does not present a body, the default implementation returns {@code true}
+   */
+  default boolean consumes(MediaType mediaType) {
+    return true;
+  }
+
+  /**
+   * @return the media type produced by this transformer, the default implementation returns the same media type
+   */
+  default MediaType produces(MediaType mediaType) {
+    return mediaType;
+  }
+
+  /**
+   * Return the future body, transformed.
+   *
+   * The default implementation returns the same body.
+   *
+   * @param body the body to rewrite
+   * @return a future of the transformed body
+   */
+  @GenIgnore
+  default Future<Body> transform(Body body) {
+    return Future.succeededFuture(body);
+  }
+}