feat(api): add custom validation framework

[paullatzelsperger]

What this PR changes/adds

This PR adds a convenient way for users to register their own validation functions for API methods.

Why it does that

Extensible validation may be desired by users, especially when dealing with extensible types.

Further notes

• Contrary to what is stated in the DR, all registration methods now accept a ValidationFunction, which is a marker for Function<Object[], Result<Void>>. This was done to improve readability.

Example Usage

public class CustomValidationExtension implements ServiceExtension {

    @Inject
    private ValidationFunctionRegistry validationFunctionRegistry;

    @Override
    public void initialize(ServiceExtensionContext context) {

        // lets validate that every Asset must have an "owner" property
        validationFunctionRegistry.registerForType(AssetEntryDto.class, objects -> {
            var assetDto = Stream.of(objects).filter(ob -> AssetEntryDto.class.isAssignableFrom(ob.getClass())).findFirst();

            if (assetDto.isEmpty()) return Result.failure("Method parameters did not contain an AssetEntryDto!");

            var dto = (AssetEntryDto) assetDto.get();

            if (!dto.getAsset().getProperties().containsKey("owner")) {
                return Result.failure("owner property not present");
            }

            return dto.getAsset().getProperties().get("owner") == null ? Result.failure("owner was null") : Result.success();
        });

        // now lets add some other validation logic, specifically for the "createAsset" method
        try {
            var method = AssetApiController.class.getDeclaredMethod("createAsset", AssetEntryDto.class);
            validationFunctionRegistry.registerForMethod(method, methodArguments -> {
                // some elaborate validation logic
                return Result.failure("createAsset: elaborate validation failed");
            });
        } catch (NoSuchMethodException e) {
            throw new RuntimeException(e);
        }
    }
}

Linked Issue(s)

Closes #1736

Checklist

• added appropriate tests?
• performed checkstyle check locally?
• added/updated copyright headers?
• documented public classes/methods?
• added/updated relevant documentation?
• assigned appropriate label? (exclude from changelog with label no-changelog)
• formatted title correctly? (take a look at the CONTRIBUTING and styleguide for details)

[codecov-commenter]

Codecov Report

Merging #1756 (2ba13b4) into main (78c1496) will increase coverage by 0.33%.
The diff coverage is 97.87%.

@@            Coverage Diff             @@
##             main    #1756      +/-   ##
==========================================
+ Coverage   67.38%   67.72%   +0.33%     
==========================================
  Files         781      795      +14     
  Lines       16747    16981     +234     
  Branches     1056     1079      +23     
==========================================
+ Hits        11285    11500     +215     
- Misses       5004     5018      +14     
- Partials      458      463       +5     

Impacted Files	Coverage Δ
...tension/jersey/validation/ResourceInterceptor.java	91.66% <91.66%> (ø)
...aceconnector/extension/jersey/JerseyExtension.java	100.00% <100.00%> (ø)
...econnector/extension/jersey/JerseyRestService.java	95.00% <100.00%> (+0.55%)	⬆️
...n/jersey/validation/ResourceInterceptorBinder.java	100.00% <100.00%> (ø)
...jersey/validation/ResourceInterceptorProvider.java	100.00% <100.00%> (ø)
...dataspaceconnector/ids/core/util/CalendarUtil.java	0.00% <0.00%> (-25.00%)	⬇️
...dataspaceconnector/core/CoreServicesExtension.java	87.50% <0.00%> (-0.97%)	⬇️
...nder/MultipartCatalogDescriptionRequestSender.java	5.88% <0.00%> (-0.12%)	⬇️
...aceconnector/ids/core/IdsCoreServiceExtension.java	0.00% <0.00%> (ø)
...api/multipart/IdsMultipartApiServiceExtension.java	76.00% <0.00%> (ø)
... and 29 more

Help us with your feedback. Take ten seconds to tell us how you rate us.

[ndr-brt]

Looks really promising!
A test showing the a custom validation implemented would help the comprehension, I know that's still a draft, but it would be a nice to have in the final version of the PR

[ndr-brt]

Seems like an avoidable indirection layer, could ResourceInterceptorProvider directly implement ValidationFunctionRegistry?

[paullatzelsperger]

technically we could do that, but the idea was to make the ResourceInterceptorProvider a generic hook point that could be used for other things too, not only validation, so it is a generic layer, that doesn't need to know about validation, whereas the ValidationFunctionRegistry "binds" it specifically to the validation use case.

Also, I liked the idea of having a clean user-facing interface.

[paullatzelsperger]

hmmm, so I gave it a try, and I do actually like it. check the respective commit

[ndr-brt]

@paullatzelsperger maybe the ValidationFunctionRegistry could be called InterceptorFunctionRegistry?
That would make it more generic looking.

[paullatzelsperger]

I thought about it before, wasn't sure, and considering that everything else is called "interceptor"-something and you also now mentioned it, I'm fine with it.

[paullatzelsperger]

Looks really promising!

A test showing the a custom validation implemented would help the comprehension, I know that's still a draft, but it would be a nice to have in the final version of the PR

That's a cool idea - I'll add an integration test for that

[florianrusch-zf]

LGTM so far.

Just one additional point: We should maybe also describe at least in the documentation, that the failure message is "important" to be a good one, as it will be returned to the client in the response body.

[paullatzelsperger]

... the failure message is "important" to be a good one, as it will be returned to the client in the response body.

All failure messages should be treated as "good ones". No point in stating that explicitly.

[ndr-brt]

Great, LGTM 🚀