Implement JsonRpcService

[ikhoon]

The following code is designed as an API to support the JSON-RPC protocol. The design may be subject to change during implementation.
Related: #6179 #6222

• JsonRpcService is an HttpService to decode JSON RPC requests and handle responses
  • Responses to batched requests may be sent via Server-sent events when:
    • the client accepts text/event-stream and;
    • JsonRpcServiceBuilder.useSse(true) is enabled.

  public final class JsonRpcService implements HttpService {
  
      public static JsonRpcServiceBuilder builder() {
          return new JsonRpcServiceBuilder();
      }
  
      @Override
      public HttpResponse serve(ServiceRequestContext ctx, HttpRequest req) throws Exception {
          // Parse the incoming request as JSON.
          JsonNode rawRequest = null;
          if (rawRequest.isObject()) {
              return handleUnaryRequest(ctx, rawRequest);
          } else if (rawRequest.isArray()) {
              return handleBatchRequests(ctx, rawRequest);
          } else {
              // If the request is neither an object nor an array, return an error response.
              return HttpResponse.ofJson(HttpStatus.BAD_REQUEST, "Invalid JSON-RPC request format.");
          }
      }
  
      private HttpResponse handleUnaryRequest(ServiceRequestContext ctx, JsonNode rawRequest) {
          // Handle the unary JSON-RPC request.
          // Find a suitable handler for the method and invoke it.
          return null;
      }
  
      private HttpResponse handleBatchRequests(ServiceRequestContext ctx, JsonNode rawRequest) {
          if (shouldUseSse) {
              // Handle the batch JSON-RPC requests using Server-Sent Events (SSE).
              // This is useful for long-running operations or streaming responses.
          } else {
              // Handle the batch JSON-RPC requests normally.
              // Process each request in the batch and return a combined response in array format.
          }
          return null;
      }
  }

• JsonServiceBuilder to add handlers and set options

  public final class JsonRpcServiceBuilder {
  
      JsonRpcServiceBuilder() {}
  
      public JsonRpcServiceBuilder addHandler(String methodName, JsonRpcHandler handler) {
          return this;
      }
  
      /**
       * Use Sever-Sent Event (SSE) to send batched responses.
       */
      public JsonRpcServiceBuilder useSse(boolean useSse) {
          return this;
      }
  
      /**
       * Builds a new {@link JsonRpcService} instance.
       */
      public JsonRpcService build() {
          return new JsonRpcService();
      }
  }

• JsonRpcHandler to handle each request, such as { "jsonrpc": "2.0", "method": "foo", "id": 1 ... }

  @FunctionalInterface
  public interface JsonRpcHandler {
  
      CompletableFuture<JsonRpcResponse> handle(ServiceRequestContext ctx, JsonRpcRequest request);
  }

• JsonRpcRequest to represent the incoming request

  public interface JsonRpcRequest {
  
      /**
       * Returns the ID of the JSON-RPC request.
       */
      @Nullable
      Object id();
    
      /**
       * Returns the JSON-RPC method name.
       */
      String method();
  
      /**
       * Returns the parameters for the JSON-RPC method.
       */
      Object[] params();
    
      /**
       * Returns the JSON-RPC version.
       */
      String version();
  }

• JsonRpcResponse to represent the response to be sent to the client

  public interface JsonRpcResponse {
      // "id" and "jsonrpc" will be automatically filled by JsonRpcService
    	
      @Nullable
      Object result();
    
      @Nullable
      JsonRpcError error();	
  }

[patcher454]

Would you mind if I took another attempt at implementing that feature?

[Dogacel]

@ikhoon What's your opinion on how the service would like from the developer's perspective?

I.e.

public class EchoService implements JsonRpcHandler {

    @Override
    public CompletableFuture<JsonRpcResponse> handle(ServiceRequestContext ctx,
                                                     JsonRpcRequest request) {
        return switch (request.getMethod()) {
            case "echo"    -> handleEcho(request);
            case "reverse" -> handleReverse(request);
            default        -> handleUnknown(request);
        };
    }

    private CompletableFuture<JsonRpcResponse> handleEcho(JsonRpcRequest request) {
        return CompletableFuture.supplyAsync(() -> {
            Object params = request.getParams();
            return JsonRpcResponse.success(request.getId(), params);
        });
    }

    ...
}

This will require manually handling each method and their parameters serialization. Do you think we can provide a similar interface to annotated service?

@AnnotatedJsonRpcService
public class EchoService {

    // Option 1: Pass the request directly
    @JsonRpcMethod("echo")
    CompletableFuture<JsonRpcResponse> handleEcho(JsonRpcRequest request) {
        return CompletableFuture.supplyAsync(() -> {
            Object params = request.getParams();
            return JsonRpcResponse.success(request.getId(), params);
        });
    }

    // Option 2: Pass the request parameters directly, deserialized from Jackson
    // class SumRequestBody { int x, int y }
    @JsonRpcMethod("sum")
    CompletableFuture<JsonRpcResponse> handleSum(SumRequestBody sumRequestBody) { ... }

    // Option 3: Deconstruct the method body
    // body -> { "nominator": 5, "denominator": 12 }
    @JsonRpcMethod("divide")
    JsonRpcResponse handleDivide(@JsonRpcParam("nominator") x, @JsonRpcParam("denominator") y) { ... }
    
}

We can apply the principle to the response type too. Return the serializable result directly or throw an exception that extends JsonRpcError.

[ikhoon]

Would you mind if I took another attempt at implementing that feature?

Yes, please. 🙏

[ikhoon]

What's your opinion on how the service would like from the developer's perspective?

I imagined each method has its handler, and JsonRpcService dispatches requests to the appropriate handler.

public class EchoService implements JsonRpcHandler {
    ...
}

public class ReverseService implements JsonRpcHandler {
    ...
}

JsonRpcService
  .builder()
  .handler("echo", new EchoService())
  .handler("reverse", new ReverseService())
  ...
  .build();

Do you think we can provide a similar interface to annotated service?

Certainly. The goal of the API is to implement JSON-RPC specification on top of HttpService. We plan to integrate JsonRpcService with annotated services in the next phase.

[Dogacel]

Would you mind if I took another attempt at implementing that feature?

Yes, please. 🙏

Another idea, do you think working on a "stacked-pr" (merging your 'reviewed' changes into a development branch) would make it easier to collaborate? As this feature spec is pretty large, I thought it might help.

I.e. first merge the interface definitions, then implement service builder and finally the service.

[patcher454]

Would you mind if I took another attempt at implementing that feature?

Yes, please. 🙏

Another idea, do you think working on a "stacked-pr" (merging your 'reviewed' changes into a development branch) would make it easier to collaborate? As this feature spec is pretty large, I thought it might help.

I.e. first merge the interface definitions, then implement service builder and finally the service.

It's always welcome, so please feel free to proceed!

[ikhoon]

do you think working on a "stacked-pr" (merging your 'reviewed' changes into a development branch) would make it easier to collaborate?

Sounds good. I've created https://github.com/line/armeria/tree/json-rpc and changed the base branch of #6289 to it.