feat(jsonrpc): implement middleware pipeline and OpenTelemetry tracing

Introduce a robust, JSON-RPC 2.0 compliant middleware pipeline and
execution engine, alongside OpenTelemetry instrumentation.

The new pipeline relies on a chain of `JsonRpcInvoker` instances. To
strictly adhere to the JSON-RPC 2.0 spec, the pipeline suppresses raw
exceptions, wrapping all application and protocol errors (e.g., Parse
Error, Invalid Request) inside a `JsonRpcResponse`. It also leverages
`Optional<JsonRpcResponse>` to properly handle fire-and-forget
Notifications (which require no response) versus standard Method Calls.

Key additions:
- `JsonRpcInvoker`: Middleware interface using `Optional<JsonRpcResponse>`
  to support both standard calls and notifications. Enforces an exception-
  safe architecture by requiring errors to be returned in the response.
- `JsonRpcExecutor`: The terminal invoker that routes requests to target
  services. Acts as the ultimate safety net, safely translating uncaught
  exceptions and protocol faults into valid JSON-RPC error objects.
- `OtelJsonRcpTracing`: OpenTelemetry middleware that traces RPC spans.
  It integrates perfectly with the exception-less pipeline by inspecting
  the response envelope for `ErrorDetail` to accurately report span
  success or failure, logging semantic attributes like `rpc.method` and
  `rpc.jsonrpc.request_id`.

Author: jknack

modules/jooby-jsonrpc-avaje-jsonb/src/main/java/io/jooby/internal/jsonrpc/avaje/jsonb/AvajeJsonRpcRequestAdapter.java

@@ -34,6 +34,7 @@ public JsonRpcRequest fromJson(JsonReader reader) {
         JsonRpcRequest invalid = new JsonRpcRequest();
         invalid.setMethod(null);
         invalid.setBatch(false);
+        invalid.setJsonrpc(null);
         return invalid;
       }
 
@@ -67,10 +68,11 @@ private JsonRpcRequest parseSingle(Object node) {
 
     // 2. Validate JSON-RPC version
     Object versionVal = map.get("jsonrpc");
-    if (!"2.0".equals(versionVal)) {
+    if (!JsonRpcRequest.JSONRPC.equals(versionVal)) {
       req.setMethod(null);
       return req;
     }
+    req.setJsonrpc(JsonRpcRequest.JSONRPC);
 
     // 3. Extract Method
     Object methodVal = map.get("method");

modules/jooby-jsonrpc-jackson2/src/main/java/io/jooby/internal/jsonrpc/jackson2/JacksonJsonRpcRequestDeserializer.java

@@ -66,10 +66,13 @@ private JsonRpcRequest parseSingle(JsonNode node) {
 
     // 2. Validate JSON-RPC version
     JsonNode versionNode = node.get("jsonrpc");
-    if (versionNode == null || !versionNode.isTextual() || !"2.0".equals(versionNode.asText())) {
+    if (versionNode == null
+        || !versionNode.isTextual()
+        || !JsonRpcRequest.JSONRPC.equals(versionNode.asText())) {
       req.setMethod(null); // Triggers -32600 Invalid Request
       return req;
     }
+    req.setJsonrpc(JsonRpcRequest.JSONRPC);
 
     // 3. Extract Method
     JsonNode methodNode = node.get("method");

modules/jooby-jsonrpc-jackson3/src/main/java/io/jooby/internal/jsonrpc/jackson3/JacksonJsonRpcRequestDeserializer.java

@@ -30,6 +30,7 @@ public JsonRpcRequest deserialize(JsonParser p, DeserializationContext ctxt) {
         JsonRpcRequest invalid = new JsonRpcRequest();
         invalid.setMethod(null); // Acts as a flag for Invalid Request
         invalid.setBatch(false); // Force single return shape
+        invalid.setJsonrpc(null);
         return invalid;
       }
 
@@ -63,10 +64,13 @@ private JsonRpcRequest parseSingle(JsonNode node) {
 
     // 2. Validate JSON-RPC version
     JsonNode versionNode = node.get("jsonrpc");
-    if (versionNode == null || !versionNode.isString() || !"2.0".equals(versionNode.asString())) {
+    if (versionNode == null
+        || !versionNode.isString()
+        || !JsonRpcRequest.JSONRPC.equals(versionNode.asString())) {
       req.setMethod(null); // Triggers -32600 Invalid Request
       return req;
     }
+    req.setJsonrpc(JsonRpcRequest.JSONRPC);
 
     // 3. Extract Method
     JsonNode methodNode = node.get("method");

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

@@ -11,7 +11,7 @@
 import io.jooby.Reified;
 import io.jooby.Router;
 import io.jooby.jsonrpc.JsonRpcErrorCode;
-import io.jooby.jsonrpc.JsonRpcResponse;
+import io.jooby.jsonrpc.JsonRpcException;
 
 public class JsonRpcExceptionTranslator {
   private final Router router;
@@ -21,17 +21,16 @@ public JsonRpcExceptionTranslator(Router router) {
   }
 
   public JsonRpcErrorCode toErrorCode(Throwable cause) {
+    if (cause instanceof JsonRpcException rpcException) {
+      return rpcException.getCode();
+    }
     // Attempt to look up any user-defined exception mappings from the registry
     Map<Class<?>, JsonRpcErrorCode> customMapping =
         router.require(Reified.map(Class.class, JsonRpcErrorCode.class));
     return errorCode(customMapping, cause)
         .orElseGet(() -> JsonRpcErrorCode.of(router.errorCode(cause)));
   }
 
-  public JsonRpcResponse.ErrorDetail toErrorDetail(Throwable cause) {
-    return new JsonRpcResponse.ErrorDetail(toErrorCode(cause), cause);
-  }
-
   /**
    * Evaluates the given exception against the registered custom exception mappings.
    *

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

@@ -8,41 +8,173 @@
 import java.util.Map;
 import java.util.Optional;
 
+import org.slf4j.Logger;
+
 import io.jooby.Context;
 import io.jooby.SneakyThrows;
-import io.jooby.jsonrpc.JsonRpcErrorCode;
-import io.jooby.jsonrpc.JsonRpcRequest;
-import io.jooby.jsonrpc.JsonRpcResponse;
-import io.jooby.jsonrpc.JsonRpcService;
+import io.jooby.jsonrpc.*;
 
+/**
+ * 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:
+ *
+ * <ul>
+ *   <li>Validating the parsed request envelope.
+ *   <li>Routing the request to the appropriate {@link JsonRpcService}.
+ *   <li>Executing the target method.
+ *   <li>Acting as the ultimate safety net by catching all exceptions and translating them into
+ *       compliant {@link JsonRpcResponse} objects.
+ * </ul>
+ */
 public class JsonRpcExecutor implements SneakyThrows.Supplier<Optional<JsonRpcResponse>> {
   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;
 
+  /**
+   * Constructs a new executor for a single JSON-RPC request.
+   *
+   * @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<String, JsonRpcService> services, Context ctx, JsonRpcRequest request) {
+      Map<Class<?>, Logger> loggers,
+      Map<String, JsonRpcService> services,
+      Context ctx,
+      JsonRpcExceptionTranslator exceptionTranslator,
+      JsonRpcRequest request,
+      Exception parseError) {
     this.services = services;
     this.ctx = ctx;
+    this.exceptionTranslator = exceptionTranslator;
     this.request = request;
+    this.parseError = parseError;
+    this.loggers = loggers;
   }
 
+  /**
+   * Executes the JSON-RPC request and returns an optional response.
+   *
+   * <p>This method adheres strictly to the JSON-RPC 2.0 specification regarding error handling and
+   * 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.
+   *
+   * @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 {
-    var fullMethod = request.getMethod();
-    if (fullMethod == null) {
-      return Optional.of(
-          JsonRpcResponse.error(request.getId(), JsonRpcErrorCode.INVALID_REQUEST, null));
+    var log = loggers.get(JsonRpcService.class);
+    try {
+      if (parseError != null) {
+        throw new JsonRpcException(JsonRpcErrorCode.PARSE_ERROR, parseError);
+      }
+      if (!request.isValid()) {
+        throw new JsonRpcException(JsonRpcErrorCode.INVALID_REQUEST, "Invalid JSON-RPC request");
+      }
+      var fullMethod = request.getMethod();
+      var targetService = services.get(fullMethod);
+      if (targetService != null) {
+        log = loggers.get(targetService.getClass());
+        var result = targetService.execute(ctx, request);
+        return request.getId() != null
+            ? Optional.of(JsonRpcResponse.success(request.getId(), result))
+            : Optional.empty();
+      }
+      if (request.getId() == null) {
+        return Optional.empty();
+      }
+      throw new JsonRpcException(
+          JsonRpcErrorCode.METHOD_NOT_FOUND, "Method not found: " + fullMethod);
+    } catch (Throwable cause) {
+      return toRpcResponse(log, request, cause);
+    }
+  }
+
+  private Optional<JsonRpcResponse> toRpcResponse(
+      Logger log, JsonRpcRequest request, Throwable ex) {
+    var code = exceptionTranslator.toErrorCode(ex);
+    log(log, request, code, ex);
+
+    if (SneakyThrows.isFatal(ex)) {
+      throw SneakyThrows.propagate(ex);
+    } else if (ex.getCause() != null && SneakyThrows.isFatal(ex.getCause())) {
+      throw SneakyThrows.propagate(ex.getCause());
+    }
+
+    if (request.getId() != null) {
+      return Optional.of(JsonRpcResponse.error(request.getId(), code, ex));
+    } else if (code == JsonRpcErrorCode.PARSE_ERROR || code == JsonRpcErrorCode.INVALID_REQUEST) {
+      // must return a valid response even if the request is invalid
+      return Optional.of(JsonRpcResponse.error(null, code, ex));
     }
-    var targetService = services.get(fullMethod);
-    if (targetService != null) {
-      var result = targetService.execute(ctx, request);
-      return request.getId() != null
-          ? Optional.of(JsonRpcResponse.success(request.getId(), result))
-          : Optional.empty();
+    return Optional.empty();
+  }
+
+  /**
+   * Logs JSON-RPC errors adaptively based on the error code.
+   *
+   * <p>Internal server errors are logged as standard errors. Authorization and routing errors are
+   * logged at debug level to prevent log flooding. Other application errors are logged as warnings.
+   *
+   * @param log The logger instance to use.
+   * @param request The request that triggered the error.
+   * @param code The error code.
+   * @param cause The underlying exception.
+   */
+  private void log(Logger log, JsonRpcRequest request, JsonRpcErrorCode code, Throwable cause) {
+    var type = code == JsonRpcErrorCode.INTERNAL_ERROR ? "server" : "client";
+    var message = "JSON-RPC {} error [{} {}] on method '{}' (id: {})";
+    switch (code) {
+      case INTERNAL_ERROR ->
+          log.error(
+              message,
+              type,
+              code.getCode(),
+              code.getMessage(),
+              request.getMethod(),
+              request.getId(),
+              cause);
+      case UNAUTHORIZED, FORBIDDEN, NOT_FOUND_ERROR ->
+          log.debug(
+              message,
+              type,
+              code.getCode(),
+              code.getMessage(),
+              request.getMethod(),
+              request.getId(),
+              cause);
+      default -> {
+        if (cause instanceof JsonRpcException) {
+          log.warn(
+              message,
+              type,
+              code.getCode(),
+              code.getMessage(),
+              request.getMethod(),
+              request.getId());
+        } else {
+          log.warn(
+              message,
+              type,
+              code.getCode(),
+              code.getMessage(),
+              request.getMethod(),
+              request.getId(),
+              cause);
+        }
+      }
     }
-    return Optional.of(
-        JsonRpcResponse.error(
-            request.getId(), JsonRpcErrorCode.METHOD_NOT_FOUND, "Method not found: " + fullMethod));
   }
 }

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

@@ -0,0 +1,95 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.internal.jsonrpc;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.Map;
+
+import org.jspecify.annotations.NonNull;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import io.jooby.Context;
+import io.jooby.Route;
+import io.jooby.StatusCode;
+import io.jooby.annotation.Generated;
+import io.jooby.jsonrpc.JsonRpcInvoker;
+import io.jooby.jsonrpc.JsonRpcRequest;
+import io.jooby.jsonrpc.JsonRpcResponse;
+import io.jooby.jsonrpc.JsonRpcService;
+
+public class JsonRpcHandler implements Route.Handler {
+  private final Map<String, JsonRpcService> services;
+  private final JsonRpcExceptionTranslator exceptionTranslator;
+  private final HashMap<Class<?>, Logger> loggers;
+  private final JsonRpcInvoker invoker;
+
+  public JsonRpcHandler(
+      Map<String, JsonRpcService> services,
+      JsonRpcExceptionTranslator exceptionTranslator,
+      JsonRpcInvoker invoker) {
+    this.services = services;
+    this.exceptionTranslator = exceptionTranslator;
+    this.invoker = invoker;
+    this.loggers = new HashMap<>();
+    loggers.put(JsonRpcService.class, LoggerFactory.getLogger(JsonRpcService.class));
+    services
+        .values()
+        .forEach(
+            service -> {
+              var generated = service.getClass().getAnnotation(Generated.class);
+              loggers.put(service.getClass(), LoggerFactory.getLogger(generated.value()));
+            });
+  }
+
+  /**
+   * Main handler for the JSON-RPC protocol. *
+   *
+   * <p>This method implements the flattened iteration logic. Because {@link JsonRpcRequest}
+   * implements {@code Iterable}, this handler treats single requests and batch requests identically
+   * during processing.
+   *
+   * @param ctx The current Jooby context.
+   * @return A single {@link JsonRpcResponse}, a {@code List} of responses for batches, or an empty
+   *     string for notifications.
+   */
+  @Override
+  public @NonNull Object apply(@NonNull Context ctx) throws Exception {
+    JsonRpcRequest input;
+    Exception parseError = null;
+    try {
+      input = ctx.body(JsonRpcRequest.class);
+    } catch (Exception cause) {
+      // still execute the handler/pipeline so we can log the error properly
+      input = JsonRpcRequest.BAD_REQUEST;
+      parseError = cause;
+    }
+
+    var responses = new ArrayList<JsonRpcResponse>();
+
+    // 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);
+      response.ifPresent(responses::add);
+    }
+
+    // Handle the case where all requests in a batch were notifications
+    if (responses.isEmpty()) {
+      return ctx.send(StatusCode.NO_CONTENT);
+    }
+
+    // Spec: Return an array only if the original request was a batch
+    return input.isBatch() ? responses : responses.getFirst();
+  }
+
+  @Override
+  public void setRoute(Route route) {
+    route.setAttribute("jsonrpc", true);
+  }
+}

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

@@ -32,6 +32,18 @@ public JsonRpcException(JsonRpcErrorCode code, String message) {
     this.data = null;
   }
 
+  /**
+   * Constructs a new JSON-RPC exception.
+   *
+   * @param code The integer error code (preferably one of the standard constants).
+   * @param cause The underlying cause of the error.
+   */
+  public JsonRpcException(JsonRpcErrorCode code, Throwable cause) {
+    super(code.getMessage(), cause);
+    this.code = code;
+    this.data = null;
+  }
+
   /**
    * Constructs a new JSON-RPC exception.
    *