Unified head interception (#104)

* Unified head interception

Motivation:

The new interceptors for changing request/response head each do a separate change yet they only modify the request/response head.

We should instead have a single interceptor that can implement all of them a batch the modification of the head in a single interceptor.

The builder pattern can be used to build such interceptor with the desired modification of the developer

Changes:

A new HeadInterceptor with a builder that aggregates the existing head individual interceptors.

* Make HeadInterceptor operations additive

The builder configuration methods can be invoked several times.

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

* Add a note in the documentation about builder methods

- Can be invoked several times
- Operations are invoked in the order of configuration

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

---------

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

Author: vietj

src/main/asciidoc/index.adoc

@@ -143,27 +143,41 @@ You can change the control, e.g you can send a response immediately to the user-
 {@link examples.HttpProxyExamples#immediateResponse}
 ----
 
-==== Header interceptor
+==== Head interceptor
 
-You can apply header interceptors to change headers from the request and response with common operations:
+You can use the {@link io.vertx.httpproxy.interceptors.HeadInterceptor} to change HTTP request/response heads:
+
+- request path
+- query params
+- request and response headers
+
+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.
+
+===== Headers interception
+
+You can apply the interceptor 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.
+Check out {@link io.vertx.httpproxy.interceptors.HeadInterceptorBuilder} for details about the available methods.
 
-==== Query interceptor
+===== Query params interception
 
-You can use query interceptors to update or remove the query parameters:
+You can apply the interceptor to update or remove query parameters:
 
 [source,java]
 ----
 {@link examples.HttpProxyExamples#queryInterceptorAdd}
 ----
 
-You can also refer to {@link io.vertx.httpproxy.interceptors.QueryInterceptor} for more information.
+You can also refer to {@link io.vertx.httpproxy.interceptors.HeadInterceptorBuilder} for more information.
 
 ==== Body interceptor
 

src/main/java/examples/HttpProxyExamples.java

@@ -109,12 +109,12 @@ public Future<Void> handleProxyResponse(ProxyContext context) {
   public void headerInterceptorFilter(HttpProxy proxy, Set<CharSequence> shouldRemove) {
     // remove a set of headers
     proxy.addInterceptor(
-      HeadersInterceptor.filterResponseHeaders(shouldRemove));
+      HeadInterceptor.builder().filteringResponseHeaders(shouldRemove).build());
   }
 
   public void queryInterceptorAdd(HttpProxy proxy, String key, String value) {
     proxy.addInterceptor(
-      QueryInterceptor.setQueryParam(key, value));
+      HeadInterceptor.builder().settingQueryParam(key, value).build());
   }
 
   public void bodyInterceptorJson(HttpProxy proxy) {
@@ -128,7 +128,7 @@ public void bodyInterceptorJson(HttpProxy proxy) {
 
   public void webSocketInterceptorPath(HttpProxy proxy) {
     proxy.addInterceptor(
-      WebSocketInterceptor.allow(PathInterceptor.addPrefix("/api"))
+      WebSocketInterceptor.allow(HeadInterceptor.builder().addingPathPrefix("/api").build())
     );
   }
 

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

@@ -0,0 +1,31 @@
+/*
+ * 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.HeadInterceptorBuilderImpl;
+
+/**
+ * An interceptor updating HTTP request/response head attributes (headers, path, query params).
+ */
+@VertxGen
+@Unstable
+public interface HeadInterceptor extends ProxyInterceptor {
+
+  /**
+   * @return a builder for head interception
+   */
+  static HeadInterceptorBuilder builder() {
+    return new HeadInterceptorBuilderImpl();
+  }
+}

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

@@ -0,0 +1,134 @@
+/*
+ * 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.Fluent;
+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 java.util.Set;
+import java.util.function.Function;
+
+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.
+ */
+@VertxGen
+@Unstable
+public interface HeadInterceptorBuilder {
+
+  /**
+   * @return an interceptor build according to builder requirements
+   */
+  HeadInterceptor build();
+
+  /**
+   * Apply modifications to the query parameters.
+   *
+   * @param updater the operation to apply to the request query parameters (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder updatingQueryParams(Handler<MultiMap> updater);
+
+  /**
+   * Add a query parameter to the request.
+   *
+   * @param name the parameter name (can be null, but in this case nothing happens)
+   * @param value the parameter value (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder settingQueryParam(String name, String value);
+
+  /**
+   * Remove a query parameter from the request.
+   *
+   * @param name the parameter name (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder removingQueryParam(String name);
+
+  /**
+   * Apply a callback to change the request URI when the proxy receives it.
+   *
+   * @param mutator the operation that applied to the path (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder updatingPath(Function<String, String> mutator);
+
+  /**
+   * Add a prefix to the URI.
+   *
+   * @param prefix the prefix that need to be added (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder addingPathPrefix(String prefix);
+
+  /**
+   * Remove a prefix to the URI. Do nothing if it doesn't exist.
+   *
+   * @param prefix the prefix that need to be removed (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder removingPathPrefix(String prefix);
+
+  /**
+   * Apply callbacks to change the request headers when the proxy receives them.
+   *
+   * @param requestHeadersUpdater the operation to apply to the request headers (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder updatingRequestHeaders(Handler<MultiMap> requestHeadersUpdater);
+
+  /**
+   * Apply callbacks to change the response headers when the proxy receives them.
+   *
+   * @param responseHeadersUpdater the operation to apply to the response headers (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @Fluent
+  HeadInterceptorBuilder updatingResponseHeaders(Handler<MultiMap> responseHeadersUpdater);
+
+  /**
+   * Filter the request headers in the given set.
+   *
+   * @param forbiddenRequestHeaders a set of the headers that need to be filtered (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @GenIgnore(PERMITTED_TYPE)
+  @Fluent
+  HeadInterceptorBuilder filteringRequestHeaders(Set<CharSequence> forbiddenRequestHeaders);
+
+  /**
+   * Filter the response headers in the given set.
+   *
+   * @param forbiddenResponseHeaders a set of the headers that need to be filtered (can be null, but in this case nothing happens)
+   * @return a reference to this, so the API can be used fluently
+   */
+  @GenIgnore(PERMITTED_TYPE)
+  @Fluent
+  HeadInterceptorBuilder filteringResponseHeaders(Set<CharSequence> forbiddenResponseHeaders);
+}