Out-of-the-box transformations for proxied requests (#78)

* Initial API proposal for interceptors

See #65

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Add basic header and path interceptors (#80)

* Add basic header and path interceptors

* fix batch 1

* fix batch 2

* fix batch 3

* add query interceptor

* fix batch 4

* Add body interceptor (#81)

* temp: test stucked

* fix batch 1

* fix batch 2

* fix batch 3

* fix connection closed (#88)

---------

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>
Co-authored-by: Zengyi Wang <wangzengyi1935@163.com>

Author: tsegismont

src/main/asciidoc/index.adoc

@@ -140,3 +140,37 @@ You can change the control, e.g you can send a response immediately to the user-
 ----
 {@link examples.HttpProxyExamples#immediateResponse}
 ----
+
+==== Header interceptor
+
+You can apply header interceptors to change headers from the request and response with common operations:
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#headerInterceptorFilter}
+----
+
+Check out the {@link io.vertx.httpproxy.interceptors.HeadersInterceptor} class for details about the available methods.
+
+==== Query interceptor
+
+You can use query interceptors to update or remove the query parameters:
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#queryInterceptorAdd}
+----
+
+You can also refer to {@link io.vertx.httpproxy.interceptors.QueryInterceptor} 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}:
+
+[source,java]
+----
+{@link examples.HttpProxyExamples#bodyInterceptorJson}
+----
+
+Please check the {@link io.vertx.httpproxy.interceptors.BodyTransformer} for other supported transformations.
+

src/main/java/examples/HttpProxyExamples.java

@@ -8,16 +8,17 @@
 import io.vertx.core.http.HttpServer;
 import io.vertx.core.http.HttpServerRequest;
 import io.vertx.core.http.RequestOptions;
+import io.vertx.core.json.JsonObject;
 import io.vertx.core.net.HostAndPort;
 import io.vertx.core.net.SocketAddress;
-import io.vertx.httpproxy.Body;
-import io.vertx.httpproxy.HttpProxy;
-import io.vertx.httpproxy.ProxyContext;
-import io.vertx.httpproxy.ProxyInterceptor;
-import io.vertx.httpproxy.ProxyOptions;
-import io.vertx.httpproxy.ProxyRequest;
-import io.vertx.httpproxy.ProxyResponse;
+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.HeadersInterceptor;
+import io.vertx.httpproxy.interceptors.QueryInterceptor;
+
+import java.util.Set;
 
 /**
  * @author <a href="mailto:emad.albloushi@gmail.com">Emad Alblueshi</a>
@@ -108,6 +109,26 @@ public Future<Void> handleProxyResponse(ProxyContext context) {
     });
   }
 
+  public void headerInterceptorFilter(HttpProxy proxy, Set<CharSequence> shouldRemove) {
+    // remove a set of headers
+    proxy.addInterceptor(
+      HeadersInterceptor.filterResponseHeaders(shouldRemove));
+  }
+
+  public void queryInterceptorAdd(HttpProxy proxy, String key, String value) {
+    proxy.addInterceptor(
+      QueryInterceptor.setQueryParam(key, value));
+  }
+
+  public void bodyInterceptorJson(HttpProxy proxy) {
+    proxy.addInterceptor(
+      BodyInterceptor.modifyResponseBody(
+        BodyTransformer.transformJsonObject(
+          jsonObject -> removeSomeFields(jsonObject)
+        )
+      ));
+  }
+
   public void immediateResponse(HttpProxy proxy) {
     proxy.addInterceptor(new ProxyInterceptor() {
       @Override
@@ -137,6 +158,12 @@ private Body filter(Body body) {
     return body;
   }
 
+  private JsonObject removeSomeFields(JsonObject o) {
+    return o;
+  }
+
+  ;
+
   public void more(Vertx vertx, HttpClient proxyClient) {
     HttpProxy proxy = HttpProxy.reverseProxy(proxyClient).originSelector(
       address -> Future.succeededFuture(SocketAddress.inetSocketAddress(7070, "origin"))

src/main/java/io/vertx/httpproxy/impl/BufferingWriteStream.java

@@ -11,14 +11,12 @@
 package io.vertx.httpproxy.impl;
 
 import io.vertx.codegen.annotations.Nullable;
-import io.vertx.core.AsyncResult;
 import io.vertx.core.Future;
 import io.vertx.core.Handler;
 import io.vertx.core.buffer.Buffer;
-import io.vertx.core.streams.ReadStream;
 import io.vertx.core.streams.WriteStream;
 
-class BufferingWriteStream implements WriteStream<Buffer> {
+public class BufferingWriteStream implements WriteStream<Buffer> {
 
   private final Buffer content;
 

src/main/java/io/vertx/httpproxy/interceptors/BodyInterceptor.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2011-2024 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+
+package io.vertx.httpproxy.interceptors;
+
+import io.vertx.codegen.annotations.Unstable;
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.httpproxy.ProxyInterceptor;
+import io.vertx.httpproxy.interceptors.impl.BodyInterceptorImpl;
+
+/**
+ * Used to create interceptors to modify request and response bodies.
+ */
+@VertxGen
+@Unstable
+public interface BodyInterceptor {
+
+  /**
+   * Apply callbacks to change the request and response bodies when the proxy receives them.
+   *
+   * @param requestTransformer the operation to apply to the request body
+   * @param responseTransformer the operation to apply to the response body
+   * @return the created interceptor
+   */
+  static ProxyInterceptor modifyBody(BodyTransformer requestTransformer, BodyTransformer responseTransformer) {
+    return new BodyInterceptorImpl(requestTransformer, responseTransformer);
+  }
+
+  /**
+   * Apply callbacks to change the request body when the proxy receives it.
+   *
+   * @param requestTransformer the operation to apply to the request body
+   * @return the created interceptor
+   */
+  static ProxyInterceptor modifyRequestBody(BodyTransformer requestTransformer) {
+    return new BodyInterceptorImpl(requestTransformer, null);
+  }
+
+  /**
+   * Apply callbacks to change the response body when the proxy receives it.
+   *
+   * @param responseTransformer the operation to apply to the response body
+   * @return the created interceptor
+   */
+  static ProxyInterceptor modifyResponseBody(BodyTransformer responseTransformer) {
+    return new BodyInterceptorImpl(null, responseTransformer);
+  }
+}

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

@@ -0,0 +1,67 @@
+package io.vertx.httpproxy.interceptors;
+
+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 java.util.function.Function;
+
+/**
+ * The callback to transform the request or response body.
+ */
+@VertxGen
+@Unstable
+public interface BodyTransformer extends Function<Buffer, Buffer> {
+
+  /**
+   * Create a callback for transform JsonObject.
+   *
+   * @param transformer the operation to transform data
+   * @return the built callback
+   */
+  static BodyTransformer transformJsonObject(Function<JsonObject, JsonObject> transformer) {
+    return BodyTransformerImpl.transformJsonObject(transformer);
+  }
+
+  /**
+   * Create a callback for transform JsonArray.
+   *
+   * @param transformer the operation to transform data
+   * @return the built callback
+   */
+  static BodyTransformer transformJsonArray(Function<JsonArray, JsonArray> transformer) {
+    return BodyTransformerImpl.transformJsonArray(transformer);
+  }
+
+  /**
+   * Create a callback for transform json with unknown shape.
+   *
+   * @param transformer the operation to transform data
+   * @return the built callback
+   */
+  static BodyTransformer transformJson(Function<Object, Object> transformer) {
+    return BodyTransformerImpl.transformJson(transformer);
+  }
+
+  /**
+   * Create a callback for transform texts.
+   *
+   * @param transformer the operation to transform data
+   * @return the built callback
+   */
+  static BodyTransformer transformText(Function<String, String> transformer, String encoding) {
+    return BodyTransformerImpl.transformText(transformer, encoding);
+  }
+
+  /**
+   * Create a callback to discard the body.
+   *
+   * @return the built callback
+   */
+  static BodyTransformer discard() {
+    return BodyTransformerImpl.discard();
+  }
+}

src/main/java/io/vertx/httpproxy/interceptors/HeadersInterceptor.java

@@ -0,0 +1,77 @@
+/*
+ * Copyright (c) 2011-2024 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+
+package io.vertx.httpproxy.interceptors;
+
+import io.vertx.codegen.annotations.GenIgnore;
+import io.vertx.codegen.annotations.Unstable;
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.core.Handler;
+import io.vertx.core.MultiMap;
+import io.vertx.httpproxy.ProxyInterceptor;
+import io.vertx.httpproxy.interceptors.impl.HeadersInterceptorImpl;
+
+import java.util.Set;
+
+import static io.vertx.codegen.annotations.GenIgnore.PERMITTED_TYPE;
+
+/**
+ * Used to create interceptors to modify request and response headers.
+ */
+@VertxGen
+@Unstable
+public interface HeadersInterceptor {
+
+  /**
+   * Apply callbacks to change the request and response headers when the proxy receives them.
+   *
+   * @param changeRequestHeaders the operation to apply to the request headers
+   * @param changeResponseHeaders the operation to apply to the response headers
+   * @return the created interceptor
+   */
+  static ProxyInterceptor changeHeaders(Handler<MultiMap> changeRequestHeaders, Handler<MultiMap> changeResponseHeaders) {
+    return new HeadersInterceptorImpl(changeRequestHeaders, changeResponseHeaders);
+  }
+
+  /**
+   * Filter the request headers in the given set.
+   *
+   * @param requestHeaders a set of the headers that need to be filtered
+   * @return the created interceptor
+   */
+  @GenIgnore(PERMITTED_TYPE)
+  static ProxyInterceptor filterRequestHeaders(Set<CharSequence> requestHeaders) {
+    return HeadersInterceptorImpl.filter(requestHeaders, null);
+  }
+
+  /**
+   * Filter the response headers in the given set.
+   *
+   * @param responseHeaders a set of the headers that need to be filtered
+   * @return the created interceptor
+   */
+  @GenIgnore(PERMITTED_TYPE)
+  static ProxyInterceptor filterResponseHeaders(Set<CharSequence> responseHeaders) {
+    return HeadersInterceptorImpl.filter(null, responseHeaders);
+  }
+
+  /**
+   * Filter the request and response headers in the given sets.
+   *
+   * @param requestHeaders a set of the request headers that need to be filtered
+   * @param responseHeaders a set of the response headers that need to be filtered
+   * @return the created interceptor
+   */
+  @GenIgnore(PERMITTED_TYPE)
+  static ProxyInterceptor filterHeaders(Set<CharSequence> requestHeaders, Set<CharSequence> responseHeaders) {
+    return HeadersInterceptorImpl.filter(requestHeaders, responseHeaders);
+  }
+}

src/main/java/io/vertx/httpproxy/interceptors/PathInterceptor.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2011-2024 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+
+package io.vertx.httpproxy.interceptors;
+
+import io.vertx.codegen.annotations.Unstable;
+import io.vertx.codegen.annotations.VertxGen;
+import io.vertx.httpproxy.ProxyInterceptor;
+import io.vertx.httpproxy.interceptors.impl.PathInterceptorImpl;
+
+import java.util.function.Function;
+
+/**
+ * Used to create interceptors to modify the request path.
+ */
+@VertxGen
+@Unstable
+public interface PathInterceptor {
+
+  /**
+   * Apply a callback to change the request URI when the proxy receives it.
+   *
+   * @param pattern the operation that applied to the path
+   * @return the created interceptor
+   */
+  static ProxyInterceptor changePath(Function<String, String> pattern) {
+    return new PathInterceptorImpl(pattern);
+  }
+
+  /**
+   * Add a prefix to the URI.
+   *
+   * @param prefix the prefix that need to be added
+   * @return the created interceptor
+   */
+  static ProxyInterceptor removePrefix(String prefix) {
+    return PathInterceptorImpl.removePrefix(prefix);
+  }
+
+  /**
+   * Remove a prefix to the URI. Do nothing if it doesn't exist.
+   *
+   * @param prefix the prefix that need to be removed
+   * @return the created interceptor
+   */
+  static ProxyInterceptor addPrefix(String prefix) {
+    return PathInterceptorImpl.addPrefix(prefix);
+  }
+}