feat(api): add custom validation framework (#1756)

* feat(api): add custom validation framework

* added documentation

* updated docs

* Apply suggestions from code review

Co-authored-by: Florian Rusch (ZF Friedrichshafen AG) <[email protected]>

* renamed to InterceptorFunctionRegistry

Co-authored-by: Florian Rusch (ZF Friedrichshafen AG) <[email protected]>

Author: paullatzelsperger

docs/developer/README.md

@@ -34,6 +34,7 @@ As a developer, I do not want to ...
 - [Serialization Context](./decision-records/2022-07-04-type-manager/README.md)
 - [State machine](state-machine.md)
 - [Style guide](_helper/styleguide.md)
+- [Custom request validation](custom_validation.md)
 - [Testing](testing.md)
 
 > All implementations have to follow existing design principles and architectural patterns that are provided as

docs/developer/custom_validation.md

@@ -0,0 +1,74 @@
+# Custom validation framework
+
+The validation framework hooks into the normal Jetty/Jersey request dispatch mechanism and is designed to allow users to
+intercept the request chain to perform additional validation tasks. In its current form it is intended for intercepting
+REST requests. Users can elect any validation framework they desire, such as `jakarta.validation` or
+the [Apache Commons Validator](https://commons.apache.org/proper/commons-validator/), or they can implement one
+themselves.
+
+## When to use it
+
+This feature is intended for use cases where the standard DTO validation, that ships with EDC's APIs is not sufficient.
+Please check out the [OpenAPI spec](../../resources/openapi/openapi.yaml) to find out more about the object schema.
+
+EDC features various data types that do not have a strict schema but are *extensible*, for example `Asset`/`AssetDto`,
+or a `DataRequest`/`DataRequestDto`. This was done by design, to allow for maximum flexibility and openness. However,
+users may still want to put a more rigid schema on top of those data types, for example a use case may require an
+`Asset` to always have a `owner` property or may require a `contentType` to be present. The standard EDC validation
+scheme has no way of enforcing that, so this is where _custom validation_ enters the playing field.
+
+## Building blocks
+
+There are two important components necessary for custom validation:
+
+- the `InterceptorFunction`: a function that accepts the intercepted method's parameters as argument (as `Object[]`),
+  and returns a `Result<Void>` to indicate the validation success. It **must not** throw an exception, or dispatch to
+  the target resource is not guaranteed.
+- the `ValidationFunctionRegistry`: all `InterceptorFunctions` must be registered there, using one of three registration
+  methods (see below).
+
+Custom validation works by supplying an `InterceptorFunction` to the `ValidationFunctionRegistry` in one of the
+following ways:
+
+1. bound to a resource-method: here, we register the `InterceptorFunction` to any of a controller's methods. That means,
+   we need compile-time access to the controller class, because we use reflection to obtain the `Method`:
+   ```java
+   var method = YourController.class.getDeclaredMethods("theMethod", /*parameter types*/)
+   var yourFunction = objects -> Result.success(); // you validation logic goes here
+   registry.addFunction(method, yourFunction);
+   ```
+   Consequently `yourFunction` will get invoked before `YourController#theMethod` is invoked by the request dispatcher.
+   Note that there is currently no way to bind an `InterceptorFunction` directly to an HTTP endpoint.
+
+2. bound to an argument type: the interceptor function gets bound to all resource methods that have a particular type in
+   their signature:
+   ```java
+   var yourFunction = objects -> Result.success(); // your validation logic goes here
+   registry.addFunction(YourObjectDto.class, yourFunction);
+   ```
+   The above function would therefore get invoked in all controllers on the classpath, that have a `YourObjectDto`
+   in their signature, e.g. `public void createObject(YourObjectDto dto)` and `public boolean deleteObject
+   (YourObjectDto dto)` would both get intercepted, even if they are defined in different controller classes.
+   *This is the recommended way in the situation described above - adding additional schema restrictions on extensible
+   types*
+
+3. globally, for all resource methods: this is intended for interceptor functions that should get invoked on *all*
+   resource methods. *This is generally not recommended and should only be used in very specific situations such as
+   logging*
+
+Please check
+out [this test](../../extensions/http/jersey/src/test/java/org/eclipse/dataspaceconnector/extension/jersey/validation/integrationtest/ValidationIntegrationTest.java)
+for a comprehensive example how validation can be enabled. All functions are registered during the extension's
+initialization phase.
+
+## Limitations and caveats
+
+- `InterceptorFunction` objects **must not** throw exceptions
+- all function registration must happen during the `initialize` phase of the extension lifecycle.
+- interceptor functions **should not** perform time-consuming tasks, such as invoking other backend systems, so as not
+  to cause timeouts in the request chain
+- for method-based interception compile-time access to the resource is required. This might not be suitable for a lot of
+  situations.
+- returning a `Result.failure(...)` will result in an `HTTP 400 BAD REQUEST` status code. This is the only supported
+  status code at this time. Note that the failure message will be part of the HTTP response body.
+- binding methods directly to paths ("endpoints") is not supported.

docs/developer/decision-records/2022-07-27-custom-dto-validation/README.md

@@ -53,28 +53,28 @@ public interface CustomValidationRegistry {
      * Registers a validation function for a particular type (e.g. a DTO). The validation function gets applied to 
      * all resource methods that have a T object in their signature 
      * @param type The class of the object for which to register the function
-     * @param validationFunction A function that evaluates the object and returns a Result
+     * @param interceptorFunction A function that evaluates the object and returns a Result
      */
-    <T> void registerForType(Class<T> type, Function<T, Result> validationFunction);
+    <T> void registerForType(Class<T> type, Function<T, Result> interceptorFunction);
 
     /**
      * Registers a validation function for all resource methods. Conditional evaluation must be done in the 
      * evaluation function itself
-     * @param validationFunction Receives the list of arguments of the resource method, returns a Result
+     * @param interceptorFunction Receives the list of arguments of the resource method, returns a Result
      */
-    void register(Function<Object[], Result> validationFunction);
+    void register(Function<Object[], Result> interceptorFunction);
 
     /**
      * Registers a validation function for a particular resource method (= Controller method). The validation 
      * function only gets applied to that particular method.
      * @param method The {@link java.lang.reflect.Method} (of a controller) for which to register the function
-     * @param validationFunction Receives the list of arguments of the resource method, returns a Result
+     * @param interceptorFunction Receives the list of arguments of the resource method, returns a Result
      */
-    void registerForMethod(Method method, Function<Object[], Result> validationFunction);
+    void registerForMethod(Method method, Function<Object[], Result> interceptorFunction);
 }
 ```
 
-If the `validationFunction` returns a failed `Result`, the `InvocationHandler` will throw an
+If the `interceptorFunction` returns a failed `Result`, the `InvocationHandler` will throw an
 `InvalidRequestException`, resulting in an HTTP 400 error code. As a side note is important to wrap that exception in
 an `InvocationTargetException`, so that it gets picked up by the method dispatcher.
 

extensions/http/jersey/src/main/java/org/eclipse/dataspaceconnector/extension/jersey/JerseyExtension.java

@@ -14,19 +14,24 @@
 
 package org.eclipse.dataspaceconnector.extension.jersey;
 
+import org.eclipse.dataspaceconnector.extension.jersey.validation.ResourceInterceptorBinder;
+import org.eclipse.dataspaceconnector.extension.jersey.validation.ResourceInterceptorProvider;
 import org.eclipse.dataspaceconnector.extension.jetty.JettyService;
 import org.eclipse.dataspaceconnector.spi.WebService;
 import org.eclipse.dataspaceconnector.spi.system.Inject;
+import org.eclipse.dataspaceconnector.spi.system.Provider;
 import org.eclipse.dataspaceconnector.spi.system.Provides;
 import org.eclipse.dataspaceconnector.spi.system.ServiceExtension;
 import org.eclipse.dataspaceconnector.spi.system.ServiceExtensionContext;
+import org.eclipse.dataspaceconnector.spi.validation.InterceptorFunctionRegistry;
 
 @Provides(WebService.class)
 public class JerseyExtension implements ServiceExtension {
     private JerseyRestService jerseyRestService;
 
     @Inject
     private JettyService jettyService;
+    private ResourceInterceptorProvider provider;
 
     @Override
     public String name() {
@@ -42,11 +47,19 @@ public void initialize(ServiceExtensionContext context) {
 
         jerseyRestService = new JerseyRestService(jettyService, typeManager, configuration, monitor);
 
+        provider = new ResourceInterceptorProvider();
+        jerseyRestService.registerInstance(() -> new ResourceInterceptorBinder(provider));
+
         context.registerService(WebService.class, jerseyRestService);
     }
 
     @Override
     public void start() {
         jerseyRestService.start();
     }
+
+    @Provider
+    public InterceptorFunctionRegistry createInterceptorFunctionRegistry() {
+        return provider;
+    }
 }

extensions/http/jersey/src/main/java/org/eclipse/dataspaceconnector/extension/jersey/JerseyRestService.java

@@ -32,6 +32,7 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Supplier;
 
 import static java.util.stream.Collectors.toSet;
 import static org.glassfish.jersey.server.ServerProperties.WADL_FEATURE_DISABLE;
@@ -45,6 +46,7 @@ public class JerseyRestService implements WebService {
 
     private final Map<String, List<Object>> controllers = new HashMap<>();
     private final JerseyConfiguration configuration;
+    private final List<Supplier<Object>> additionalInstances = new ArrayList<>();
 
     public JerseyRestService(JettyService jettyService, TypeManager typeManager, JerseyConfiguration configuration, Monitor monitor) {
         this.jettyService = jettyService;
@@ -65,6 +67,10 @@ public void registerResource(String contextAlias, Object resource) {
                 .add(resource);
     }
 
+    void registerInstance(Supplier<Object> instance) {
+        additionalInstances.add(instance);
+    }
+
     public void start() {
         try {
             controllers.forEach(this::registerContext);
@@ -89,6 +95,9 @@ private void registerContext(String contextAlias, List<Object> controllers) {
         resourceConfig.registerInstances(new ValidationExceptionMapper());
         resourceConfig.registerInstances(new UnexpectedExceptionMapper(monitor));
 
+        additionalInstances.forEach(supplier -> resourceConfig.registerInstances(supplier.get()));
+
+
         if (configuration.isCorsEnabled()) {
             resourceConfig.register(new CorsFilter(configuration));
         }

extensions/http/jersey/src/main/java/org/eclipse/dataspaceconnector/extension/jersey/validation/ResourceInterceptor.java

@@ -0,0 +1,62 @@
+/*
+ *  Copyright (c) 2022 Microsoft Corporation
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Microsoft Corporation - initial API and implementation
+ *
+ */
+
+package org.eclipse.dataspaceconnector.extension.jersey.validation;
+
+import org.eclipse.dataspaceconnector.spi.exception.InvalidRequestException;
+import org.eclipse.dataspaceconnector.spi.result.Result;
+import org.eclipse.dataspaceconnector.spi.validation.InterceptorFunction;
+
+import java.lang.reflect.InvocationHandler;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.util.List;
+
+/**
+ * This {@link InvocationHandler} acts as interceptor whenever methods get called on a proxy object, and invokes
+ * a list of {@link InterceptorFunction} objects before calling the actual proxy.
+ * <p>
+ * Note that any exception thrown by a {@link InterceptorFunction} may get swallowed or cause the proxy not to be invoked at all.
+ */
+class ResourceInterceptor implements InvocationHandler {
+
+    private final List<InterceptorFunction> interceptorFunctions;
+
+    ResourceInterceptor(List<InterceptorFunction> functions) {
+        interceptorFunctions = List.copyOf(functions);
+    }
+
+    @Override
+    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
+        var results = interceptorFunctions.stream()
+                .map(f -> f.apply(args))
+                .reduce(Result::merge);
+
+        if (results.isPresent()) {
+            if (results.get().failed()) {
+                throwException(results.get());
+            }
+        }
+
+        return method.invoke(proxy, args);
+    }
+
+    private void throwException(Result<Void> result) throws InvocationTargetException {
+        var cause = new InvalidRequestException(result.getFailureMessages());
+
+        // must be wrapped in an InvocationTargetException, so that the message dispatcher picks it up and forwards
+        // it to the exception mapper(s)
+        throw new InvocationTargetException(cause);
+    }
+}

extensions/http/jersey/src/main/java/org/eclipse/dataspaceconnector/extension/jersey/validation/ResourceInterceptorBinder.java

@@ -0,0 +1,36 @@
+/*
+ *  Copyright (c) 2022 Microsoft Corporation
+ *
+ *  This program and the accompanying materials are made available under the
+ *  terms of the Apache License, Version 2.0 which is available at
+ *  https://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  SPDX-License-Identifier: Apache-2.0
+ *
+ *  Contributors:
+ *       Microsoft Corporation - initial API and implementation
+ *
+ */
+
+package org.eclipse.dataspaceconnector.extension.jersey.validation;
+
+import org.glassfish.jersey.internal.inject.AbstractBinder;
+import org.glassfish.jersey.server.spi.internal.ResourceMethodInvocationHandlerProvider;
+
+/**
+ * Binds a concrete instance of a {@link ResourceInterceptorProvider} to a {@link ResourceMethodInvocationHandlerProvider}, thus enabling
+ * the method interceptor mechanism.
+ */
+public class ResourceInterceptorBinder extends AbstractBinder {
+
+    private final ResourceInterceptorProvider provider;
+
+    public ResourceInterceptorBinder(ResourceInterceptorProvider provider) {
+        this.provider = provider;
+    }
+
+    @Override
+    protected void configure() {
+        bindFactory(() -> provider).to(ResourceMethodInvocationHandlerProvider.class);
+    }
+}