docs & refactoring

Author: kliushnichenko

docs/asciidoc/modules/avaje-validator.adoc

@@ -167,13 +167,6 @@ import io.jooby.validation.BeanValidator
 }
 ----
 
-[IMPORTANT]
-====
-Please note, if you are mixing both approaches (MVC/scripts), it's better to avoid using a filter,
-as it may lead to double validation on MVC routes. In this case,
-it's recommended to use the handler version (see below).
-====
-
 `BeanValidator.validate()` behaves identically to validation in MVC routes.
 It also supports validating list, array, and map of beans.
 
@@ -223,6 +216,12 @@ catches `ConstraintViolationException` and transforms it into the following resp
 }
 ----
 
+[NOTE]
+====
+`AvajeValidatorModule` is compliant with `ProblemDetails`. Therefore, if you enable 
+the Problem Details feature, the response above will be transformed into an `RFC 7807` compliant format
+====
+
 It is possible to override the `title` and `status` code of the response above:
 
 [source, java]
@@ -330,4 +329,4 @@ import io.jooby.avaje.validator.AvajeValidatorModule;
     cfg.failFast(true);
   }));
 }
-----
+----

docs/asciidoc/modules/hibernate-validator.adoc

@@ -130,13 +130,6 @@ import io.jooby.validation.BeanValidator
 }
 ----
 
-[IMPORTANT]
-====
-Please note, if you are mixing both approaches (MVC/scripts), it's better to avoid using a filter,
-as it may lead to double validation on MVC routes. In this case,
-it's recommended to use the handler version (see below).
-====
-
 `BeanValidator.validate()` behaves identically to validation in MVC routes.
 It also supports validating list, array, and map of beans
 
@@ -186,6 +179,12 @@ catches `ConstraintViolationException` and transforms it into the following resp
 }
 ----
 
+[NOTE]
+====
+`HibernateValidatorModule` is compliant with `ProblemDetails`. Therefore, if you enable the Problem Details feature, 
+the response above will be transformed into an `RFC 7807` compliant format
+====
+
 It is possible to override the `title` and `status` code of the response above:
 
 [source, java]
@@ -386,4 +385,4 @@ import io.jooby.hibernate.validator.HibernateValidatorModule;
     cfg.failFast(true);
   }));
 }
-----
+----

docs/asciidoc/problem-details.adoc

@@ -10,52 +10,44 @@ Thankfully, there’s a standard called https://www.rfc-editor.org/rfc/rfc7807[I
 By adopting `RFC 7807`, API designers don’t have to spend time creating a custom solution, and users benefit by recognizing a familiar format across different APIs.
 If it suits the API’s needs, using this standard benefits both designers and users alike.
 
-`Jooby` provides built-in support for `Problem Details`. There are two main entities to work with:
+`Jooby` provides built-in support for `Problem Details`.
 
-1. `HttpProblem` - representation of the `RFC 7807` model and the way to instantiate the problem.
+=== Set up ProblemDetails
 
-2. `ProblemDetailsHandler` - global error handler that catches all exceptions, transforms them into `Problem Details` compliant format and renders the response based on the `Accept` header value.
-It also sets the appropriate content-type in response (e.g. application/problem+json, application/problem+xml)
+To enable the `ProblemDetails`, simply add the following line to your configuration:
 
-=== Set up handler
+.application.conf
+[source, properties]
+----
+problem.details.enabled = true
+----
 
-The bare minimal requirement is to set up an error handler:
+This is the bare minimal configuration you need.
+It enables a global error handler that catches all exceptions, transforms them into Problem Details compliant format and renders the response based on the Accept header value. It also sets the appropriate content-type in response (e.g. application/problem+json, application/problem+xml)
 
-.Java
-[source,java,role="primary"]
-----
-import io.jooby.problem.ProblemDetailsHandler;
+All supported settings include:
 
-{
-  ...  
-  error(new ProblemDetailsHandler()          // <1>
-    .log4xxErrors()                          // <2>
-    .mute(StatusCode.UNAUTHORIZED)           // <3>
-  );
+.application.conf
+[source, properties]
+----
+problem.details {
+  enabled = true
+  log4xxErrors = true                                // <1>
+  muteCodes = [401, 403]                             // <2>
+  muteTypes = ["com.example.MyMutedException"]       // <3>
 }
 ----
 
-.Kotlin
-[source,kt,role="secondary"]
-----
-import io.jooby.problem.ProblemDetailsHandler
 
-{
-  ...  
-  error(new ProblemDetailsHandler()          // <1>
-    .log4xxErrors()                          // <2>
-    .mute(StatusCode.UNAUTHORIZED)           // <3>
-  )
-}
-----
+<1> By default, only server errors (5xx) will be logged. You can optionally enable the logging of client errors (4xx). If `DEBUG` logging level is enabled, the log will contain a stacktrace as well.
+<2> You can optionally mute some status codes completely.
+<3> You can optionally mute some exceptions logging completely.
 
-<1> Enable `Problem Details` handler.
-Keep in mind, order matters (WYSIWYG), so if you have some specific exception handlers, they should be placed above this line.
-<2> By default, only server errors (5xx) will be logged. You can optionally enable the logging of client errors (4xx). If `DEBUG` logging level is enabled, the log will contain a stacktrace as well.
-<3> You can optionally mute some status codes or exceptions logging completely.
 
 === Creating problems
 
+`HttpProblem` class represents the `RFC 7807` model. It is the main entity you need to work with to produce the problem.
+
 ==== Static helpers
 
 There are several handy static methods to produce a simple `HttpProblem`:
@@ -70,6 +62,8 @@ Don't overuse it, the problem should have meaningful `title` and `detail` when p
 .Java
 [source,java,role="primary"]
 ----
+import io.jooby.problem.HttpProblem;
+
 get("/users/{userId}", ctx -> {
   var userId = ctx.path("userId").value();
   User user = userRepository.findUser(userId);
@@ -87,6 +81,8 @@ get("/users/{userId}", ctx -> {
 .Kotlin
 [source,kt,role="secondary"]
 ----
+import io.jooby.problem.HttpProblem
+
 get("/users/{userId}") { ctx ->
   val userId = ctx.path("userId").value()
   val user = userRepository.findUser(userId)
@@ -117,7 +113,7 @@ Resulting response:
 
 ==== Builder
 
-Use builder to create rich problem instance with all properties:
+Use builder to create a rich problem instance with all properties:
 
 [source,java]
 ----
@@ -190,8 +186,8 @@ It is basically another extension `errors` on a root level. Adding errors is str
 ----
 throw HttpProblem.builder()
   ...
-  .error(new HttpProblem.Error("First name cannot be blank", "#/firstName"))
-  .error(new HttpProblem.Error("Last name is required", "#/lastName"))
+  .error(new HttpProblem.Error("First name cannot be blank", "/firstName"))
+  .error(new HttpProblem.Error("Last name is required", "/lastName"))
   .build();
 ----
 
@@ -203,11 +199,11 @@ In response:
   "errors": [
     {
       "detail": "First name cannot be blank",
-      "pointer": "#/firstName"
+      "pointer": "/firstName"
     },
     {
       "detail": "Last name is required",
-      "pointer": "#/lastName"
+      "pointer": "/lastName"
     }
   ]
 }
@@ -261,8 +257,7 @@ public class OutOfStockProblem extends HttpProblem {
 
 === Custom Exception Handlers
 
-All the features described above should give you ability to rely solely on `ProblemDetailsHandler`.
-But, in case you still need custom exception handler for some reason, you still can do it:
+All the features described above should give you ability to rely solely on built-in global error handler. But, in case you still need custom exception handler for some reason, you still can do it:
 
 [source,java]
 ----
@@ -275,20 +270,16 @@ But, in case you still need custom exception handler for some reason, you still
       
       ctx.getRouter().getErrorHandler().apply(ctx, problem, code);     // <2>
     });
-
-    // should always go below (WYSIWYG)
-    error(new ProblemDetailsHandler());                                // <3>
 }
 ----
 
 <1> Transform exception to `HttpProblem`
 <2> Propagate the problem to `ProblemDetailsHandler`. It will handle the rest.
-<3> `ProblemDetailsHandler` should always go below your custom exception handlers
 
 [IMPORTANT]
 ====
 Do not attempt to render `HttpProblem` manually, it is strongly discouraged.
 `HttpProblem` is derived from the `RuntimeException` to enable ease of `HttpProblem` throwing.
 Thus, thrown `HttpProblem` will also contain a stacktrace, if you render `HttpProblem` as is -
-it will be rendered together with stacktrace. It is  strongly advised not to expose the stacktrace to the client. Propagate the problem to `ProblemDetailsHandler` and let him take care of the rest. 
+it will be rendered together with stacktrace. It is  strongly advised not to expose the stacktrace to the client system. Propagate the problem to global error handler and let him take care of the rest. 
 ====

jooby/src/main/java/io/jooby/Jooby.java

@@ -1325,10 +1325,15 @@ public static Jooby createApp(
     return app;
   }
 
-  public boolean problemDetailsEnabled() {
+  /**
+   * Check if {@link ProblemDetailsHandler} is enabled as a global error handler
+   *
+   * @return boolean flag
+   */
+  public boolean problemDetailsIsEnabled() {
     var config = getConfig();
-    return config.hasPath(ProblemDetailsHandler.ENABLE_KEY)
-           && config.getBoolean(ProblemDetailsHandler.ENABLE_KEY);
+    return config.hasPath(ProblemDetailsHandler.ENABLED_KEY)
+           && config.getBoolean(ProblemDetailsHandler.ENABLED_KEY);
   }
 
   private static void configurePackage(Package pkg) {

jooby/src/main/java/io/jooby/internal/RouterImpl.java

@@ -667,8 +667,17 @@ private void pureAscii(String pattern, Consumer<String> consumer) {
     return this;
   }
 
+  /**
+   * Define the global error handler.
+   * If ProblemDetails is enabled the {@link ProblemDetailsHandler} instantiated
+   * from configuration settings and returned. Otherwise, {@link DefaultErrorHandler} instance
+   * returned.
+   *
+   * @param app - Jooby application instance
+   * @return global error handler
+   */
   private ErrorHandler defineGlobalErrorHandler(Jooby app) {
-    if (app.problemDetailsEnabled()) {
+    if (app.problemDetailsIsEnabled()) {
       var problemDetailsConfig = app.getConfig().getConfig(ProblemDetailsHandler.ROOT_CONFIG_PATH);
       return ProblemDetailsHandler.fromConfig(problemDetailsConfig);
     } else {

jooby/src/main/java/io/jooby/problem/ProblemDetailsHandler.java

@@ -31,8 +31,12 @@
  */
 public class ProblemDetailsHandler extends DefaultErrorHandler {
 
+  private static final String MUTE_CODES_KEY = "muteCodes";
+  private static final String MUTE_TYPES_KEY = "muteTypes";
+  private static final String LOG_4XX_ERRORS_KEY = "log4xxErrors";
+
   public static final String ROOT_CONFIG_PATH = "problem.details";
-  public static final String ENABLE_KEY = ROOT_CONFIG_PATH + ".enable";
+  public static final String ENABLED_KEY = ROOT_CONFIG_PATH + ".enabled";
 
   private boolean log4xxErrors;
 
@@ -54,7 +58,7 @@ public void apply(@NonNull Context ctx, @NonNull Throwable cause, @NonNull Statu
     }
 
     try {
-      HttpProblem problem = evaluateTheProblem(ctx, cause, code);
+      HttpProblem problem = evaluateTheProblem(cause, code);
 
       logProblem(ctx, problem, cause);
 
@@ -87,7 +91,7 @@ private void setResponseType(Context ctx, MediaType type) {
     }
   }
 
-  private HttpProblem evaluateTheProblem(Context ctx, Throwable cause, StatusCode statusCode) {
+  private HttpProblem evaluateTheProblem(Throwable cause, StatusCode statusCode) {
     HttpProblem problem;
     if (cause instanceof HttpProblem httpProblem) {
       problem = httpProblem;
@@ -201,19 +205,17 @@ private String buildLogMsg(Context ctx, HttpProblem problem, StatusCode statusCo
   public static ProblemDetailsHandler fromConfig(Config config) {
     var handler = new ProblemDetailsHandler();
 
-    if(config.hasPath("log4xxErrors")) {
-      if(config.getBoolean("log4xxErrors")) {
-        handler.log4xxErrors();
-      }
+    if (config.hasPath(LOG_4XX_ERRORS_KEY) && config.getBoolean(LOG_4XX_ERRORS_KEY)) {
+      handler.log4xxErrors();
     }
 
-    if(config.hasPath("muteCodes")) {
-      config.getIntList("muteCodes")
+    if (config.hasPath(MUTE_CODES_KEY)) {
+      config.getIntList(MUTE_CODES_KEY)
           .forEach(code -> handler.mute(StatusCode.valueOf(code)));
     }
 
-    if(config.hasPath("muteTypes")) {
-      config.getStringList("muteTypes")
+    if (config.hasPath(MUTE_TYPES_KEY)) {
+      config.getStringList(MUTE_TYPES_KEY)
           .forEach(throwingConsumer(
               className -> handler.mute((Class<? extends Exception>) Class.forName(className))));
     }

jooby/src/main/java/io/jooby/validation/JsonPointer.java

@@ -5,6 +5,16 @@
 import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
+/**
+ * Transforms hibernate-validator (or avaje-validator) `propertyPath` into
+ * <a href="https://www.rfc-editor.org/rfc/rfc6901.html">JSON POINTER</a> format.
+ * For example:
+ * <p>"person.firstName" -> "/person/firstName"</p>
+ * <p>"persons[0].firstName" -> "/persons/0/firstName"</p>
+ *
+ * @author kliushnichenko
+ * @since 3.4.2
+ */
 public class JsonPointer {
   private static final Pattern ARRAY_PATTERN = Pattern.compile("(\\w+)\\[(\\d+)]");
 
@@ -14,7 +24,7 @@ public static String of(String propertyPath) {
 
   private static String toJsonPointer(String path) {
     if (path == null || path.isEmpty()) {
-      return "/";
+      return ""; // means the whole document
     }
 
     List<String> parts = List.of(path.split("\\."));

jooby/src/main/java/io/jooby/validation/ValidationResult.java

@@ -38,11 +38,11 @@ public HttpProblem toHttpProblem() {
         .build();
   }
 
-  private List<ProblemError> convertErrors() {
-    List<ProblemError> problemErrors = new LinkedList<>();
+  private List<HttpProblem.Error> convertErrors() {
+    List<HttpProblem.Error> problemErrors = new LinkedList<>();
     for (Error err : errors) {
       for (var msg : err.messages()) {
-        problemErrors.add(new ProblemError(msg, JsonPointer.of(err.field), err.type));
+        problemErrors.add(new HttpProblem.Error(msg, JsonPointer.of(err.field)));
       }
     }
     return problemErrors;
@@ -51,19 +51,6 @@ private List<ProblemError> convertErrors() {
   public record Error(String field, List<String> messages, ErrorType type) {
   }
 
-  public static class ProblemError extends HttpProblem.Error {
-    private final ErrorType type;
-
-    public ProblemError(String detail, String pointer, ErrorType type) {
-      super(detail, pointer);
-      this.type = type;
-    }
-
-    public ErrorType getType() {
-      return type;
-    }
-  }
-
   public enum ErrorType {
     FIELD,
     GLOBAL