- document new features

Author: jknack

docs/asciidoc/modules/json-rpc.adoc

@@ -105,6 +105,90 @@ Supported engines include:
 
 No additional configuration is required. The generated dispatcher automatically hooks into the installed engine using the `JsonRpcParser` and `JsonRpcDecoder` interfaces, ensuring primitive types are strictly validated and parsed.
 
+=== Middleware Pipeline
+
+Jooby provides a dedicated middleware architecture for JSON-RPC using the `JsonRpcInvoker` and `JsonRpcChain` APIs. This allows you to intercept RPC calls to apply cross-cutting concerns like logging, security, metrics, or tracing.
+
+To create an interceptor, implement the `JsonRpcInvoker` interface.
+
+.JSON-RPC
+[source,java,role="primary"]
+----
+import io.jooby.jsonrpc.*;
+import java.util.Optional;
+
+public class LoggingInvoker implements JsonRpcInvoker {
+  
+  @Override
+  public Optional<JsonRpcResponse> invoke(Context ctx, JsonRpcRequest request, JsonRpcChain next) {
+    long start = System.currentTimeMillis();
+    
+    // Proceed down the chain
+    Optional<JsonRpcResponse> response = next.proceed(ctx, request);
+    
+    long took = System.currentTimeMillis() - start;
+    
+    // Inspect the response
+    response.ifPresent(res -> {
+      if (res.getError() != null) {
+        ctx.getLog().warn("RPC {} failed in {}ms", request.getMethod(), took);
+      } else {
+        ctx.getLog().info("RPC {} succeeded in {}ms", request.getMethod(), took);
+      }
+    });
+    
+    return response;
+  }
+}
+----
+
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+import io.jooby.jsonrpc.*
+import java.util.Optional
+
+class LoggingInvoker : JsonRpcInvoker {
+  
+  override fun invoke(ctx: Context, request: JsonRpcRequest, next: JsonRpcChain): Optional<JsonRpcResponse> {
+    val start = System.currentTimeMillis()
+    
+    // Proceed down the chain
+    val response = next.proceed(ctx, request)
+    
+    val took = System.currentTimeMillis() - start
+    
+    // Inspect the response
+    response.ifPresent { res ->
+      if (res.error != null) {
+        ctx.log.warn("RPC {} failed in {}ms", request.method, took)
+      } else {
+        ctx.log.info("RPC {} succeeded in {}ms", request.method, took)
+      }
+    }
+    
+    return response
+  }
+}
+----
+
+You register invokers fluently when installing the `JsonRpcModule`. You can chain multiple invokers together, and they will execute in the order they are added.
+
+[source,java]
+----
+install(new JsonRpcModule(new MovieServiceRpc_())
+    .invoker(new SecurityInvoker())
+    .invoker(new LoggingInvoker()));
+----
+
+==== Safe Exception Handling
+Notice that you **do not** need to wrap `next.proceed()` in a `try-catch` block. The final executor in the JSON-RPC pipeline acts as an ultimate safety net. It catches all unhandled exceptions, protocol failures (like Parse Errors), and routing failures, safely transforming them into a standard `JsonRpcResponse` containing an `ErrorDetail`.
+
+To react to failures in your middleware, simply inspect `response.get().getError() != null`.
+
+==== Notifications and Optional Responses
+The invocation pipeline returns an `Optional<JsonRpcResponse>`. This is because the JSON-RPC 2.0 specification explicitly dictates that **Notifications** (requests sent without an `id` member) must not receive a response. For these requests, the chain will safely execute the target method but return `Optional.empty()`.
+
 === Error Mapping
 
 Jooby seamlessly bridges standard Java application exceptions and HTTP status codes into the JSON-RPC 2.0 format using the `JsonRpcErrorCode` mapping. You do not need to throw custom protocol exceptions for standard failures.

docs/asciidoc/modules/opentelemetry.adoc

@@ -284,6 +284,46 @@ import io.jooby.opentelemetry.instrumentation.OtelHikari
 }
 ----
 
+==== JSON-RPC
+
+Provides automatic tracing for your JSON-RPC 2.0 endpoints. By adding the `OtelJsonRcpTracing` middleware to your JSON-RPC pipeline, it generates a dedicated OpenTelemetry span for every RPC invocation.
+
+It automatically records standard semantic attributes (such as `rpc.system`, `rpc.method`, and `rpc.jsonrpc.request_id`). Furthermore, because it hooks directly into the `JsonRpcChain`, it accurately records protocol errors and application failures by inspecting the `JsonRpcResponse` envelope, without relying on thrown exceptions.
+
+.JSON-RPC Integration
+[source, java, role = "primary"]
+----
+import io.jooby.jsonrpc.JsonRpcModule;
+import io.jooby.jsonrpc.instrumentation.OtelJsonRcpTracing;
+import io.opentelemetry.api.OpenTelemetry;
+
+{
+  install(new OtelModule());
+
+  // Register the JSON-RPC module and attach the tracing middleware
+  install(new JsonRpcModule(new MovieServiceRpc_())
+    .invoker(new OtelJsonRcpTracing(require(OpenTelemetry.class)))
+  );
+}
+----
+
+.Kotlin
+[source, kt, role="secondary"]
+----
+import io.jooby.jsonrpc.JsonRpcModule
+import io.jooby.jsonrpc.instrumentation.OtelJsonRcpTracing
+import io.opentelemetry.api.OpenTelemetry
+
+{
+  install(OtelModule())
+
+  // Register the JSON-RPC module and attach the tracing middleware
+  install(JsonRpcModule(MovieServiceRpc_())
+    .invoker(OtelJsonRcpTracing(require(OpenTelemetry::class.java)))
+  )
+}
+----
+
 ==== Log4j2
 
 Seamlessly exports all application logs to your OpenTelemetry backend, automatically correlated with active trace and span IDs using a dynamic appender.