feat(jsonrpc): implement 1:1 service generation and O(1) global dispatcher

- Transition from artificial namespace routing to strict JSON-RPC 2.0 method mapping.
- Update APT `JoobyProcessor` to generate isolated `*Rpc_` classes for each `@JsonRpc` annotated controller.
- Preserve standard MVC factory constructor patterns (`Function<Context, T>`) in generated RPC services to maintain full Dependency Injection support.
- Introduce `JsonRpcService.getMethods()` to explicitly declare supported protocol methods.
- Implement $O(1)$ `HashMap` method resolution in the Tier 1 `JsonRpcDispatcher`.
- Remove implicit `Extension` self-registration from generated classes in favor of explicit manual registration via the dispatcher constructor.
- Fix `@Generated` annotation metadata output for Java (`.class`) and Kotlin (`::class`).
- ref #3868

Author: jknack

jooby/src/main/java/io/jooby/annotation/JsonRpc.java

@@ -0,0 +1,48 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a class and its methods as a JSON-RPC 2.0 endpoint. *
+ *
+ * <p>To expose a method via JSON-RPC, the method <b>must</b> be annotated with {@code @JsonRpc}. If
+ * a class contains methods annotated with {@code @JsonRpc}, the class itself can optionally be
+ * annotated to define a common namespace. *
+ *
+ * <h3>Routing Rules:</h3>
+ *
+ * <ul>
+ *   <li><b>Class Level (Namespace):</b> When applied to a class, the {@link #value()} defines the
+ *       namespace for all JSON-RPC methods within that class. If the annotation is present but the
+ *       value is empty, the simple class name (e.g., {@code MovieService}) is used as the
+ *       namespace. If the class is not annotated at all, the methods are registered without a
+ *       namespace. *
+ *   <li><b>Method Level (Method Name):</b> When applied to a method, the method is exposed over
+ *       JSON-RPC. The {@link #value()} defines the exact RPC method name. If the value is empty,
+ *       the actual Java/Kotlin method name is used.
+ * </ul>
+ *
+ * *
+ *
+ * <p>The final JSON-RPC method string expected by the dispatcher is formatted as {@code
+ * "namespace.methodName"} (or just {@code "methodName"} if no namespace exists).
+ */
+@Target({ElementType.TYPE, ElementType.METHOD})
+@Retention(RetentionPolicy.RUNTIME)
+public @interface JsonRpc {
+
+  /**
+   * The explicit namespace (when used on a class) or the explicit method name (when used on a
+   * method). * @return The overridden name, or an empty string to use the defaults (Simple Class
+   * Name or Method Name).
+   */
+  String value() default "";
+}

jooby/src/main/java/io/jooby/jsonrpc/JsonRpcDecoder.java

@@ -0,0 +1,35 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.jsonrpc;
+
+/**
+ * A pre-resolved decoder used at runtime to deserialize JSON-RPC parameter nodes into complex Java
+ * objects.
+ *
+ * <p>This interface is heavily utilized by the Jooby Annotation Processor (APT). When compiling
+ * {@code @JsonRpc}-annotated controllers, the APT generates highly optimized routing code that
+ * resolves the appropriate {@code JsonRpcDecoder} for each method argument. By pre-resolving these
+ * decoders, Jooby efficiently parses incoming JSON arguments without incurring reflection overhead
+ * on every request.
+ *
+ * <p>Note: Primitive types and standard wrappers (like {@code int}, {@code String}, {@code
+ * boolean}) are typically handled directly by the {@link JsonRpcReader} rather than requiring a
+ * dedicated decoder.
+ *
+ * @param <T> The target Java type this decoder produces.
+ */
+public interface JsonRpcDecoder<T> {
+
+  /**
+   * Decodes a generic JSON node object into the target Java object.
+   *
+   * @param name The name of the parameter being decoded (useful for error reporting or wrapping).
+   * @param node The generic JSON node (e.g., a Map, List, or library-specific AST node)
+   *     representing this specific argument.
+   * @return The fully deserialized Java object.
+   */
+  T decode(String name, Object node);
+}

jooby/src/main/java/io/jooby/jsonrpc/JsonRpcDispatcher.java

@@ -0,0 +1,139 @@
+/*
+ * 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.ArrayList;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import io.jooby.*;
+
+/**
+ * Global Tier 1 Dispatcher for JSON-RPC 2.0 requests. *
+ *
+ * <p>This dispatcher acts as the central entry point for all JSON-RPC traffic. It manages the
+ * lifecycle of a request by:
+ *
+ * <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.
+ * </ul>
+ *
+ * *
+ *
+ * <p>Usage:
+ *
+ * <pre>{@code
+ * install(new JsonRpcDispatcher());
+ * services().put(JsonRpcService.class, new MyServiceRpc(new MyService()));
+ * }</pre>
+ *
+ * @author Edgar Espina
+ * @since 4.0.17
+ */
+public class JsonRpcDispatcher implements Extension {
+
+  private final Map<String, JsonRpcService> services = new HashMap<>();
+
+  public JsonRpcDispatcher(JsonRpcService... services) {
+    for (JsonRpcService service : services) {
+      for (String method : service.getMethods()) {
+        this.services.put(method, service);
+      }
+    }
+  }
+
+  /**
+   * Installs the JSON-RPC handler at the default {@code /rpc} endpoint.
+   *
+   * @param app The Jooby application instance.
+   * @throws Exception If registration fails.
+   */
+  @Override
+  public void install(Jooby app) throws Exception {
+    app.post("/rpc", this::handle);
+  }
+
+  /**
+   * 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.
+   */
+  public Object handle(Context ctx) {
+    JsonRpcRequest input;
+    try {
+      input = ctx.body(JsonRpcRequest.class);
+    } catch (Exception e) {
+      // Spec: -32700 Parse error if the JSON is physically malformed.
+      return JsonRpcResponse.error(null, -32700, "Parse error");
+    }
+
+    List<JsonRpcResponse> responses = new ArrayList<>();
+
+    // Look up all generated *Rpc classes registered in the service registry
+
+    for (var request : input) {
+      String fullMethod = request.getMethod();
+
+      // Spec: -32600 Invalid Request if the method member is missing or null
+      if (fullMethod == null) {
+        if (request.getId() != null) {
+          responses.add(JsonRpcResponse.error(request.getId(), -32600, "Invalid Request"));
+        }
+        continue;
+      }
+
+      try {
+        JsonRpcService targetService = services.get(fullMethod);
+        if (targetService != null) {
+          Object result = targetService.execute(ctx, request);
+          // Spec: If the "id" is missing, it is a notification and no response is returned.
+          if (request.getId() != null) {
+            responses.add(JsonRpcResponse.success(request.getId(), result));
+          }
+        } else {
+          // Spec: -32601 Method not found
+          if (request.getId() != null) {
+            responses.add(
+                JsonRpcResponse.error(request.getId(), -32601, "Method not found: " + fullMethod));
+          }
+        }
+      } catch (JsonRpcException e) {
+        // Domain-specific or protocol-level exceptions (e.g., -32602 Invalid Params)
+        if (request.getId() != null) {
+          responses.add(JsonRpcResponse.error(request.getId(), e.getCode(), e.getMessage()));
+        }
+      } catch (Exception e) {
+        // Spec: -32603 Internal error for unhandled application exceptions
+        if (request.getId() != null) {
+          responses.add(
+              JsonRpcResponse.error(request.getId(), -32603, "Internal error: " + e.getMessage()));
+        }
+      }
+    }
+
+    // Handle the case where all requests in a batch were notifications
+    if (responses.isEmpty()) {
+      ctx.setResponseCode(StatusCode.NO_CONTENT);
+      return "";
+    }
+
+    // Spec: Return an array only if the original request was a batch
+    return input.isBatch() ? responses : responses.getFirst();
+  }
+}

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

@@ -0,0 +1,79 @@
+/*
+ * Jooby https://jooby.io
+ * Apache License Version 2.0 https://jooby.io/LICENSE.txt
+ * Copyright 2014 Edgar Espina
+ */
+package io.jooby.jsonrpc;
+
+/**
+ * Exception thrown when a JSON-RPC error occurs during routing, parsing, or execution.
+ *
+ * <p>Contains standard JSON-RPC 2.0 error codes. When caught by the dispatcher, this exception
+ * should be transformed into a {@link JsonRpcResponse} containing the error details.
+ */
+public class JsonRpcException extends RuntimeException {
+
+  /**
+   * Invalid JSON was received by the server. An error occurred on the server while parsing the JSON
+   * text.
+   */
+  public static final int PARSE_ERROR = -32700;
+
+  /** The JSON sent is not a valid Request object. */
+  public static final int INVALID_REQUEST = -32600;
+
+  /** The method does not exist / is not available. */
+  public static final int METHOD_NOT_FOUND = -32601;
+
+  /** Invalid method parameter(s). */
+  public static final int INVALID_PARAMS = -32602;
+
+  /** Internal JSON-RPC error. */
+  public static final int INTERNAL_ERROR = -32603;
+
+  private final int code;
+  private final Object data;
+
+  /**
+   * Constructs a new JSON-RPC exception.
+   *
+   * @param code The integer error code (preferably one of the standard constants).
+   * @param message A short description of the error.
+   */
+  public JsonRpcException(int code, String message) {
+    super(message);
+    this.code = code;
+    this.data = null;
+  }
+
+  /**
+   * Constructs a new JSON-RPC exception with additional error data.
+   *
+   * @param code The integer error code.
+   * @param message A short description of the error.
+   * @param data Additional data about the error (e.g., stack trace or validation messages).
+   */
+  public JsonRpcException(int code, String message, Object data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+
+  /**
+   * Returns the JSON-RPC error code.
+   *
+   * @return The JSON-RPC error code.
+   */
+  public int getCode() {
+    return code;
+  }
+
+  /**
+   * Returns additional data regarding the error.
+   *
+   * @return Additional data regarding the error, or null if none was provided.
+   */
+  public Object getData() {
+    return data;
+  }
+}

jooby/src/main/java/io/jooby/jsonrpc/JsonRpcParser.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.lang.reflect.Type;
+
+/**
+ * The core JSON parsing SPI (Service Provider Interface) for JSON-RPC.
+ *
+ * <p>This factory is implemented by Jooby's JSON modules (such as Jackson or Avaje) and serves as
+ * the bridge between the parsed JSON-RPC request and the application's Java objects.
+ *
+ * <p><b>Startup Optimization:</b>
+ *
+ * <p>The Jooby Annotation Processor (APT) generates highly optimized routing code that relies on
+ * this interface. At application startup, the generated routes use this parser to eagerly resolve
+ * and cache type-specific {@link JsonRpcDecoder}s. This ensures that during actual HTTP requests,
+ * arguments are deserialized with near-zero reflection overhead.
+ */
+public interface JsonRpcParser {
+
+  /**
+   * Resolves and caches a type-specific deserializer during route initialization.
+   *
+   * <p>This method is invoked by the APT-generated code when the application starts. By eagerly
+   * requesting a decoder for complex generic types, the framework avoids expensive reflection
+   * lookups during runtime request processing.
+   *
+   * @param type The target Java type (e.g., {@code List<Movie>}, {@code User}) to decode.
+   * @param <T> The expected Java type.
+   * @return A highly optimized decoder capable of parsing generic JSON nodes into the target type.
+   */
+  <T> JsonRpcDecoder<T> decoder(Type type);
+
+  /**
+   * Creates a stateful reader for extracting JSON-RPC arguments from the request parameters.
+   *
+   * <p>Because JSON-RPC 2.0 parameters can be either positional (a JSON Array) or named (a JSON
+   * Object), this reader manages the extraction context to hand off the correct JSON segment to the
+   * pre-resolved {@link JsonRpcDecoder}s or extract primitives.
+   *
+   * @param params The parsed parameter object (typically a List or Map depending on the underlying
+   *     JSON library) from the {@link JsonRpcRequest}.
+   * @return A reader for argument extraction.
+   */
+  JsonRpcReader reader(Object params);
+}