- replace next action, by a proper chain pattern

Author: jknack

modules/jooby-jsonrpc/src/main/java/io/jooby/internal/jsonrpc/JsonRpcExecutor.java

@@ -8,6 +8,7 @@
 import java.util.Map;
 import java.util.Optional;
 
+import org.jspecify.annotations.NonNull;
 import org.slf4j.Logger;
 
 import io.jooby.Context;
@@ -17,7 +18,8 @@
 /**
  * The internal execution engine and "final invoker" for JSON-RPC requests.
  *
- * <p>This class is responsible for the final stages of the JSON-RPC lifecycle:
+ * <p>This class acts as the terminal end of the {@link JsonRpcChain}. It is responsible for the
+ * final stages of the JSON-RPC lifecycle:
  *
  * <ul>
  *   <li>Validating the parsed request envelope.
@@ -27,10 +29,8 @@
  *       compliant {@link JsonRpcResponse} objects.
  * </ul>
  */
-public class JsonRpcExecutor implements SneakyThrows.Supplier<Optional<JsonRpcResponse>> {
+public class JsonRpcExecutor implements JsonRpcChain {
   private final Map<String, JsonRpcService> services;
-  private final Context ctx;
-  private final JsonRpcRequest request;
   private final Map<Class<?>, Logger> loggers;
   private final JsonRpcExceptionTranslator exceptionTranslator;
   private final Exception parseError;
@@ -40,25 +40,19 @@ public class JsonRpcExecutor implements SneakyThrows.Supplier<Optional<JsonRpcRe
    *
    * @param loggers A map of loggers keyed by service class.
    * @param services A map of registered JSON-RPC services keyed by method name.
-   * @param ctx The current HTTP context.
    * @param exceptionTranslator The translator used to map standard Throwables to JSON-RPC error
    *     codes.
-   * @param request The incoming JSON-RPC request.
    * @param parseError Any exception that occurred during the initial JSON parsing phase.
    */
   public JsonRpcExecutor(
       Map<Class<?>, Logger> loggers,
       Map<String, JsonRpcService> services,
-      Context ctx,
       JsonRpcExceptionTranslator exceptionTranslator,
-      JsonRpcRequest request,
       Exception parseError) {
     this.services = services;
-    this.ctx = ctx;
+    this.loggers = loggers;
     this.exceptionTranslator = exceptionTranslator;
-    this.request = request;
     this.parseError = parseError;
-    this.loggers = loggers;
   }
 
   /**
@@ -68,13 +62,14 @@ public JsonRpcExecutor(
    * response generation. It will return {@link Optional#empty()} for Notifications, unless a
    * fundamental Parse Error or Invalid Request error occurs, which always require a response.
    *
+   * @param ctx The current HTTP context passed down the chain.
+   * @param request The incoming JSON-RPC request passed down the chain.
    * @return An Optional containing the JSON-RPC response, or empty if the request was a valid
    *     Notification.
-   * @throws Exception Only thrown if a fatal JVM error occurs (e.g., OutOfMemoryError) that cannot
-   *     be recovered.
    */
   @Override
-  public Optional<JsonRpcResponse> tryGet() throws Exception {
+  public @NonNull Optional<JsonRpcResponse> proceed(
+      @NonNull Context ctx, @NonNull JsonRpcRequest request) {
     var log = loggers.get(JsonRpcService.class);
     try {
       if (parseError != null) {

modules/jooby-jsonrpc/src/main/java/io/jooby/internal/jsonrpc/JsonRpcHandler.java

@@ -70,12 +70,12 @@ public JsonRpcHandler(
     }
 
     var responses = new ArrayList<JsonRpcResponse>();
+    var executor = new JsonRpcExecutor(loggers, services, exceptionTranslator, parseError);
 
     // Look up all generated *Rpc classes registered in the service registry
     for (var request : input) {
-      var target =
-          new JsonRpcExecutor(loggers, services, ctx, exceptionTranslator, request, parseError);
-      var response = invoker == null ? target.get() : invoker.invoke(ctx, request, target);
+      var response =
+          invoker == null ? executor.proceed(ctx, request) : invoker.invoke(ctx, request, executor);
       response.ifPresent(responses::add);
     }
 

modules/jooby-jsonrpc/src/main/java/io/jooby/jsonrpc/JsonRpcChain.java

@@ -0,0 +1,50 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.jsonrpc;
+
+import java.util.Optional;
+
+import io.jooby.Context;
+
+/**
+ * Represents the remaining execution pipeline for a JSON-RPC request.
+ *
+ * <p>This interface is a core component of the JSON-RPC middleware architecture (Chain of
+ * Responsibility). When a {@link JsonRpcInvoker} executes, it is provided an instance of this
+ * chain, which represents all subsequent middleware components and the final execution target.
+ *
+ * <p>A typical middleware implementation will:
+ *
+ * <ol>
+ *   <li>Perform pre-processing (e.g., start a timer, evaluate security constraints).
+ *   <li>Call {@link #proceed(Context, JsonRpcRequest)} to delegate execution to the next link in
+ *       the chain.
+ *   <li>Inspect or log the returned {@link JsonRpcResponse}.
+ *   <li>Return the response back up the chain.
+ * </ol>
+ *
+ * <p>The terminal implementation of this chain is the internal execution engine, which guarantees
+ * that exceptions are caught and safely translated into standard JSON-RPC error responses.
+ * Therefore, callers of {@code proceed} generally do not need to wrap the call in a try-catch block
+ * for application logic.
+ */
+public interface JsonRpcChain {
+
+  /**
+   * Passes control to the next element in the pipeline, or executes the target JSON-RPC method if
+   * this is the end of the chain.
+   *
+   * <p>Because the request and context are passed explicitly, a middleware component is free to
+   * modify, wrap, or sanitize them before passing them down the line.
+   *
+   * @param ctx The current HTTP context.
+   * @param request The parsed JSON-RPC request envelope.
+   * @return An {@link Optional} containing the final JSON-RPC response. This will be {@link
+   *     Optional#empty()} if the request was a valid Notification (which explicitly forbids a
+   *     response).
+   */
+  Optional<JsonRpcResponse> proceed(Context ctx, JsonRpcRequest request);
+}

modules/jooby-jsonrpc/src/main/java/io/jooby/jsonrpc/JsonRpcInvoker.java

@@ -9,7 +9,6 @@
 import java.util.Optional;
 
 import io.jooby.Context;
-import io.jooby.SneakyThrows;
 
 /**
  * Interceptor or middleware for processing JSON-RPC requests.
@@ -47,22 +46,22 @@
 public interface JsonRpcInvoker {
 
   /**
-   * Invokes the JSON-RPC request, passing control to the next invoker in the chain or to the final
+   * Invokes the JSON-RPC request, passing control to the next element in the chain or to the final
    * target method.
    *
    * <p>Because the final invoker automatically catches exceptions and converts them into error
-   * responses, you do not need to wrap the {@code action} in a try-catch block. Instead, if your
-   * middleware needs to react to a failure (e.g., to record an error metric), you can execute the
-   * action and check for an error by evaluating {@code response.get().getError() != null}.
+   * responses, you do not need to wrap the call to {@code next.proceed()} in a try-catch block.
+   * Instead, if your middleware needs to react to a failure (e.g., to record an error metric), you
+   * can proceed with the chain and check for an error by evaluating {@code
+   * response.get().getError() != null}.
    *
    * @param ctx The current HTTP context.
    * @param request The incoming JSON-RPC request.
-   * @param action The next step in the invocation chain (or the final method execution).
+   * @param next The remaining execution pipeline, ending in the final method execution.
    * @return An {@link Optional} containing the response for a standard method call, or {@link
    *     Optional#empty()} if the incoming request was a notification.
    */
-  Optional<JsonRpcResponse> invoke(
-      Context ctx, JsonRpcRequest request, SneakyThrows.Supplier<Optional<JsonRpcResponse>> action);
+  Optional<JsonRpcResponse> invoke(Context ctx, JsonRpcRequest request, JsonRpcChain next);
 
   /**
    * Chains this invoker with another one to form a middleware pipeline.
@@ -74,7 +73,7 @@ Optional<JsonRpcResponse> invoke(
    */
   default JsonRpcInvoker then(JsonRpcInvoker next) {
     Objects.requireNonNull(next, "next invoker is required");
-    return (ctx, request, action) ->
-        JsonRpcInvoker.this.invoke(ctx, request, () -> next.invoke(ctx, request, action));
+    return (ctx, request, chain) ->
+        JsonRpcInvoker.this.invoke(ctx, request, (c, r) -> next.invoke(c, r, chain));
   }
 }

modules/jooby-jsonrpc/src/main/java/io/jooby/jsonrpc/JsonRpcModule.java

@@ -8,8 +8,6 @@
 import java.util.*;
 
 import org.jspecify.annotations.Nullable;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 import io.jooby.*;
 import io.jooby.exception.MissingValueException;
@@ -19,54 +17,83 @@
 import io.jooby.jsonrpc.instrumentation.OtelJsonRcpTracing;
 
 /**
- * Global Tier 1 Dispatcher for JSON-RPC 2.0 requests.
+ * Jooby Extension module for integrating JSON-RPC 2.0 capabilities.
  *
- * <p>This dispatcher acts as the central entry point for all JSON-RPC traffic. It manages the
- * lifecycle of a request by:
+ * <p>This module acts as the central configuration point for setting up a JSON-RPC endpoint. It
+ * registers the target {@link JsonRpcService} instances, configures the route path, maps standard
+ * framework exceptions to JSON-RPC error codes, and installs the underlying request handler into
+ * the Jooby application.
+ *
+ * <h3>Middleware Pipeline (Invoker / Chain API)</h3>
+ *
+ * <p>This module allows you to configure a pipeline of interceptors using the {@link
+ * JsonRpcInvoker} API. By adding invokers, you create a {@link JsonRpcChain} that wraps the final
+ * method execution. This is the standard way to apply cross-cutting concerns to your RPC endpoints,
+ * such as:
  *
  * <ul>
- *   <li>Parsing the incoming body into a {@link JsonRpcRequest} (supporting both single and batch
- *       shapes).
- *   <li>Iterating through registered {@link JsonRpcService} instances to find a matching namespace.
- *   <li>Handling <strong>Notifications</strong> (requests without an {@code id}) by suppressing
- *       responses.
- *   <li>Unifying batch results into a single JSON array or a single object response as per the
- *       spec.
+ *   <li>Logging request payloads and execution times.
+ *   <li>Enforcing security and authorization rules.
+ *   <li>Gathering metrics and OpenTelemetry tracing.
  * </ul>
  *
- * <p>*
- *
- * <p>Usage:
+ * <h3>Usage:</h3>
  *
  * <pre>{@code
+ * {
  * install(new Jackson3Module());
- *
  * install(new JsonRpcJackson3Module());
- *
- * install(new JsonRpcModule(new MyServiceRpc_()));
- *
+ * * install(new JsonRpcModule(new MyServiceRpc_())
+ * .invoker(new MyJsonRpcMiddleware()));
+ * }
  * }</pre>
  *
  * @author Edgar Espina
  * @since 4.0.17
  */
 public class JsonRpcModule implements Extension {
-  private final Logger log = LoggerFactory.getLogger(JsonRpcService.class);
   private final Map<String, JsonRpcService> services = new HashMap<>();
   private final String path;
   private @Nullable JsonRpcInvoker invoker;
   private @Nullable OtelJsonRcpTracing head;
 
+  /**
+   * Creates a new JSON-RPC module at a custom HTTP path.
+   *
+   * @param path The HTTP path where the JSON-RPC endpoint will be mounted (e.g., {@code
+   *     "/api/rpc"}).
+   * @param service The primary {@link JsonRpcService} containing the RPC methods to expose.
+   * @param services Additional {@link JsonRpcService} instances to expose on the same endpoint.
+   */
   public JsonRpcModule(String path, JsonRpcService service, JsonRpcService... services) {
     this.path = path;
     registry(service);
     Arrays.stream(services).forEach(this::registry);
   }
 
+  /**
+   * Creates a new JSON-RPC module mounted at the default {@code "/rpc"} HTTP path.
+   *
+   * @param service The primary {@link JsonRpcService} containing the RPC methods to expose.
+   * @param services Additional {@link JsonRpcService} instances to expose on the same endpoint.
+   */
   public JsonRpcModule(JsonRpcService service, JsonRpcService... services) {
     this("/rpc", service, services);
   }
 
+  /**
+   * Adds a {@link JsonRpcInvoker} middleware to the execution pipeline.
+   *
+   * <p>Middlewares are composed together to form a {@link JsonRpcChain}. When multiple invokers are
+   * registered, they wrap around each other, meaning the first added invoker will execute first.
+   *
+   * <p><strong>Tracing Priority:</strong> If the provided invoker is an instance of {@link
+   * OtelJsonRcpTracing}, it is automatically promoted to the absolute head of the pipeline. This
+   * guarantees that OpenTelemetry spans encompass all other middlewares and the final execution.
+   *
+   * @param invoker The middleware interceptor to add to the pipeline.
+   * @return This module instance for fluent configuration chaining.
+   */
   public JsonRpcModule invoker(JsonRpcInvoker invoker) {
     if (invoker instanceof OtelJsonRcpTracing otel) {
       // otel goes first:
@@ -88,10 +115,15 @@ private void registry(JsonRpcService service) {
   }
 
   /**
-   * Installs the JSON-RPC handler at the default {@code /rpc} endpoint.
+   * Installs the JSON-RPC handler into the Jooby application.
+   *
+   * <p>This method is invoked automatically by Jooby during application startup. It resolves the
+   * final middleware chain, registers the HTTP POST route at the configured path, and sets up
+   * default exception mappings for standard Jooby routing errors (like missing or mismatched
+   * parameters).
    *
    * @param app The Jooby application instance.
-   * @throws Exception If registration fails.
+   * @throws Exception If route registration or configuration fails.
    */
   @Override
   public void install(Jooby app) throws Exception {