Body transformer should accept and produce a media type

Motivation:

Currently body transformer are applied on the media type whatsoever.

A body transformer should declare the list of media type it produces as well as indicate which media type it consumes.

These should be taken in account when applying the body transformer or not on the proxied stream.

Changes:

Add a body transformer produces/consumes method.

The generic proxy interceptor uses the produces/consumes to decide whether or not to apply the transformer based on the response accept header.

The Body interface has been added a media type that indicates the media type of the body entity which can be used to match against transformers and also let the transformer set a body with a different media type.

Author: vietj

src/main/java/examples/HttpProxyExamples.java

@@ -122,6 +122,8 @@ public void bodyInterceptorTransformer(HttpProxy proxy) {
       ProxyInterceptor
         .builder()
         .transformingResponseBody(
+          MediaType.APPLICATION_JSON,
+          MediaType.APPLICATION_OCTET_STREAM,
           buffer -> {
             // Apply some transformation
             return buffer;

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

@@ -1,65 +1,91 @@
 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.buffer.Buffer;
 import io.vertx.core.json.JsonArray;
 import io.vertx.core.json.JsonObject;
 import io.vertx.httpproxy.impl.BodyTransformerImpl;
 
+import java.util.Collections;
+import java.util.List;
 import java.util.function.Function;
 
 /**
  * A synchronous function that transforms an HTTP body entity.
  */
 @VertxGen
 @Unstable
-public interface BodyTransformer extends Function<Buffer, Buffer> {
+public interface BodyTransformer {
 
   /**
-   * Create a callback for transform JsonObject.
+   * @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 false}
+   */
+  default boolean consumes(MediaType mediaType) {
+    return false;
+  }
+
+  /**
+   * @return the media type produced by this transformer, the default implementation returns {@code application/octet-stream}
+   */
+  default MediaType produces(MediaType mediaType) {
+    return mediaType;
+  }
+
+  @GenIgnore
+  Function<Buffer, Buffer> transformer(MediaType mediaType);
+
+  @GenIgnore(GenIgnore.PERMITTED_TYPE)
+  static BodyTransformer transformer(MediaType consumedMediaType, MediaType producedMediaType, Function<Buffer, Buffer> transformer) {
+    return new BodyTransformerImpl(transformer, consumedMediaType, producedMediaType);
+  }
+
+  /**
+   * Create a transformer that transforms JSON object to JSON object, the transformer accepts and produces {@code application/json}.
    *
-   * @param transformer the operation to transform data
-   * @return the built callback
+   * @param fn the operation to transform data
+   * @return the transformer instance
    */
-  static BodyTransformer transformJsonObject(Function<JsonObject, JsonObject> transformer) {
-    return BodyTransformerImpl.transformJsonObject(transformer);
+  static BodyTransformer transformJsonObject(Function<JsonObject, JsonObject> fn) {
+    return BodyTransformerImpl.transformJsonObject(fn);
   }
 
   /**
-   * Create a callback for transform JsonArray.
+   * Create a transformer that transforms JSON array to JSON array, the transformer accepts and produces {@code application/json}.
    *
-   * @param transformer the operation to transform data
-   * @return the built callback
+   * @param fn the operation to transform data
+   * @return the transformer instance
    */
-  static BodyTransformer transformJsonArray(Function<JsonArray, JsonArray> transformer) {
-    return BodyTransformerImpl.transformJsonArray(transformer);
+  static BodyTransformer transformJsonArray(Function<JsonArray, JsonArray> fn) {
+    return BodyTransformerImpl.transformJsonArray(fn);
   }
 
   /**
-   * Create a callback for transform json with unknown shape.
+   * Create a transformer that transforms JSON value to JSON value, the transformer accepts and produces {@code application/json}.
    *
-   * @param transformer the operation to transform data
-   * @return the built callback
+   * @param fn the operation to transform data
+   * @return the transformer instance
    */
-  static BodyTransformer transformJson(Function<Object, Object> transformer) {
-    return BodyTransformerImpl.transformJson(transformer);
+  static BodyTransformer transformJson(Function<Object, Object> fn) {
+    return BodyTransformerImpl.transformJson(fn);
   }
 
   /**
-   * Create a callback for transform texts.
+   * Create a transformer that transforms text to text, the transformer accepts and produces {@code text/plain}.
    *
-   * @param transformer the operation to transform data
-   * @return the built callback
+   * @param fn the operation to transform data
+   * @return the transformer instance
    */
-  static BodyTransformer transformText(Function<String, String> transformer, String encoding) {
-    return BodyTransformerImpl.transformText(transformer, encoding);
+  static BodyTransformer transformText(Function<String, String> fn, String encoding) {
+    return BodyTransformerImpl.transformText(fn, encoding);
   }
 
   /**
-   * Create a callback to discard the body.
+   * Create a transformer that discards the body, the transformer accepts any media type.
    *
-   * @return the built callback
+   * @return the transformer instance
    */
   static BodyTransformer discard() {
     return BodyTransformerImpl.discard();

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

@@ -0,0 +1,68 @@
+package io.vertx.httpproxy;
+
+import io.vertx.codegen.annotations.DataObject;
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.httpproxy.impl.MediaTypeImpl;
+
+import java.util.List;
+
+/**
+ * Represent a Media type (rfc6838).
+ *
+ * @author <a href="mailto:julien@julienviet.com">Julien Viet</a>
+ */
+@DataObject
+public interface MediaType {
+
+  MediaType ANY = MediaType.parse("*/*");
+  MediaType APPLICATION = MediaType.parse("application/*");
+  MediaType APPLICATION_OCTET_STREAM = MediaType.parse("application/octet-stream");
+  MediaType APPLICATION_JSON = MediaType.parse("application/json");
+  MediaType TEXT = MediaType.parse("text/*");
+  MediaType TEXT_PLAIN = MediaType.parse("text/plain");
+
+  /**
+   * Parse an accept header which is a list of media types
+   *
+   * @param header the header
+   * @return the list of media types
+   * @throws IllegalArgumentException when the list is not valid
+   */
+  static List<MediaType> parseAcceptHeader(String header) throws IllegalArgumentException {
+    return MediaTypeImpl.parseCommaSeparatedList(header, 0);
+  }
+
+  /**
+   * Parse a media type.
+   *
+   * @param s the string representation
+   * @return the parsed media type or {@code null} when the string to parse is not valid
+   */
+  static MediaType parse(String s) {
+    return MediaTypeImpl.parseMediaType(s, 0);
+  }
+
+  /**
+   * @return the type or {@code null} when everything is matched (*)
+   */
+  String type();
+
+  /**
+   * @return the sub type or {@code null} when everything is matched (*)
+   */
+  String subType();
+
+  /**
+   * @return whether the {@code other} mime type is accepted
+   */
+  boolean accepts(MediaType other);
+
+  /**
+   * Return a media type parameter
+   *
+   * @param name the parameter name
+   * @return the value or {@code null}
+   */
+  String parameter(String name);
+
+}

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

@@ -17,6 +17,8 @@
 import io.vertx.codegen.annotations.VertxGen;
 import io.vertx.core.Handler;
 import io.vertx.core.MultiMap;
+import io.vertx.core.buffer.Buffer;
+import io.vertx.httpproxy.impl.BodyTransformerImpl;
 
 import java.util.Set;
 import java.util.function.Function;
@@ -31,7 +33,7 @@
  * 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
+ * {@link #transformingRequestBody(BodyTransformer)}. Body transformation buffer the body content and then applies
  * a transforming function before sending the response.</p>
  */
 @VertxGen
@@ -149,7 +151,7 @@ default ProxyInterceptorBuilder transformingRequestBody(BodyTransformer requestT
   /**
    * <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>
+   * <p>The interceptor fully buffers the request body and then applies 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
@@ -158,6 +160,30 @@ default ProxyInterceptorBuilder transformingRequestBody(BodyTransformer requestT
   @Fluent
   ProxyInterceptorBuilder transformingRequestBody(BodyTransformer requestTransformer, long maxBufferedSize);
 
+  /**
+   * Like {@link #transformingRequestBody(MediaType, MediaType, Function, long)} with {@code maxBufferedSize} = {@link #DEFAULT_MAX_BUFFERED_SIZE}
+   */
+  @Fluent
+  default ProxyInterceptorBuilder transformingRequestBody(MediaType consumedMediaType, MediaType producedMediaType, Function<Buffer, Buffer> requestTransformer) {
+    return transformingRequestBody(consumedMediaType, producedMediaType, 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 applies the transformation.</p>
+   *
+   * @param consumedMediaType the media type this transformer understand
+   * @param producedMediaType the media type this transformer produces
+   * @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
+  default ProxyInterceptorBuilder transformingRequestBody(MediaType consumedMediaType, MediaType producedMediaType, Function<Buffer, Buffer> requestTransformer, long maxBufferedSize) {
+    return transformingRequestBody(new BodyTransformerImpl(requestTransformer, consumedMediaType, producedMediaType), maxBufferedSize);
+  }
+
   /**
    * Like {@link #transformingResponseBody(BodyTransformer, long)} with {@code maxBufferedSize} = {@link #DEFAULT_MAX_BUFFERED_SIZE}
    */
@@ -169,7 +195,7 @@ default ProxyInterceptorBuilder transformingResponseBody(BodyTransformer respons
   /**
    * <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>
+   * <p>The interceptor fully buffers the response body and then applies 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
@@ -178,4 +204,28 @@ default ProxyInterceptorBuilder transformingResponseBody(BodyTransformer respons
   @Fluent
   ProxyInterceptorBuilder transformingResponseBody(BodyTransformer responseTransformer, long maxBufferedSize);
 
+  /**
+   * Like {@link #transformingResponseBody(MediaType, MediaType, Function, long)} with {@code maxBufferedSize} = {@link #DEFAULT_MAX_BUFFERED_SIZE}
+   */
+  @Fluent
+  default ProxyInterceptorBuilder transformingResponseBody(MediaType consumedMediaType, MediaType producedMediaType, Function<Buffer, Buffer> responseTransformer) {
+    return transformingResponseBody(consumedMediaType, producedMediaType, 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 applies the transformation.</p>
+   *
+   * @param consumedMediaType the media type this transformer understand
+   * @param producedMediaType the media type this transformer produces
+   * @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
+  default ProxyInterceptorBuilder transformingResponseBody(MediaType consumedMediaType, MediaType producedMediaType, Function<Buffer, Buffer> responseTransformer, long maxBufferedSize) {
+    return transformingResponseBody(new BodyTransformerImpl(responseTransformer, consumedMediaType, producedMediaType), maxBufferedSize);
+  }
+
 }

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

@@ -15,14 +15,7 @@
 import io.vertx.codegen.annotations.VertxGen;
 import io.vertx.core.Future;
 import io.vertx.core.MultiMap;
-import io.vertx.core.buffer.Buffer;
-import io.vertx.core.http.HttpClient;
 import io.vertx.core.http.HttpClientResponse;
-import io.vertx.core.http.HttpServerRequest;
-import io.vertx.core.http.HttpServerResponse;
-import io.vertx.core.streams.ReadStream;
-
-import java.util.function.Function;
 
 /**
  *