tomchv / jsonrpc2

An idiomatic JSON RPC 2.0 Golang implementation

Welcome to my profile 👋

I'm Tom, french developer with an unlimited curiosity, passionate by software, devops, and many other things 📘
Currently working at Dagger, I'm also working on Open Source project in Quartz.

I love learning new things, right now, I'm on:

• CI/CD
• Cryptography
• Writing cool blogpost

Currently contributing on:

• Dagger 🚀
• Buildkit

📫 How to reach me: [email protected].

Stats

jsonrpc2's Issues

Use Gin server

Refactor server to use Gin because it include many useful tools that it will be a waste of time to code in the library.

Add Go releaser package

JSON RPC 2 will be an open source client/server library.

To make release easier, there should be a go releaser action.

Handle positional parameter

According to JSON RPC 2.0 standard, there are 2 ways to pass arguments:

• Positional argument
• Named argument

Example with the following function

type SubtractArg struct {
    Minuend    int
    Subtracter int
}

func Subtract(arg SubtractArg) (int, error)

It must be possible to pass arguments with both ways

• [1, 2]
• {"minuend": 1, "subtracter": 2}

Currently, validator use the absolute type of the function, so positional arguments will be considered as an invalid argument

Add documentation generation from an endpoint `/docs`

Context

That would be awesome to generate a JSON RPC 2.0 Open API Spec from an endpoint /docs.

Questions

• How should we manage comments, further documentation?
• Should we build a webpage? (Later)

Handle batch request

JSON RPC 2.0 standard define a batch request system to improve server performance.

It must obey to the following rules

To send several Request objects at the same time, the Client MAY send an Array filled with Request objects.

The Server should respond with an Array containing the corresponding Response objects, after all of the batch Request objects have been processed. A Response object SHOULD exist for each Request object, except that there SHOULD NOT be any Response objects for notifications. The Server MAY process a batch rpc call as a set of concurrent tasks, processing them in any order and with any width of parallelism.

The Response objects being returned from a batch call MAY be returned in any order within the Array. The Client SHOULD match contexts between the set of Request objects and the resulting set of Response objects based on the id member within each Object.

If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least one value, the response from the Server MUST be a single Response object. If there are no Response objects contained within the Response array as it is to be sent to the client, the server MUST NOT return an empty Array and should return nothing at all.

Return ID on error when it's possible

Currently, if an error happens during request's parsing, no identifier will be set in the error.
It's a problem because sometime the parsing error come from an invalid parameter or anything else but the request's shape is valid.

To simplify tracking of those request, the identifier should be forward to the client.

Wrap Batch management into structure

Currently, Batch is handle with an array of Request.
There should be a defined struct to correctly handle it and simplify the codebase.

type Batch struct {
    reqs []common.Request
    r sync.Mutex
)

// Append
// Get
// Send

Test server with official JSON RPC 2.0 examples

There is a good number of unit test in the codebase but it would be great to add officiel example to ensure the library has the correct behaviour.

Params error handling is too permissive

Currently, params allow request to contains any kind of parameters, from object to array, including single type value.

For instance, those values are correct

• "foo"
• 4
• ["foo", 4]
• {"foo": "bar", "baz": 4}

According to the standard :

If present, parameters for the rpc call MUST be provided as a Structured value. Either by-position through an Array or by-name through an Object.

by-position: params MUST be an Array, containing the values in the Server expected order.
by-name: params MUST be an Object, with member names that match the Server expected parameter names. The absence of expected names MAY result in an error being generated. The names MUST match exactly, including case, to the method's expected parameters.

The library should then enforce that parameters correctly obey to the standard

Add code coverage

As an Open Source package, it's important to share how the package is tested.

Showing coverage is a first step to attest it.

To so so, we must use codecov and take inspiration from zap.

Implement an optional logger

Request

There should be a logger in the server to correctly monitor server.

Capabilities

• Logger should have severity level
• Logger should output into both file or stdout
• Logger should be thread safe and accessible in functions

Tools

• Zap from Uber

Add fuzzing test

For security purpose, it would be good to also test functions with fuzzing.

Specially:

• Validator
• Request parser

Use Dagger as CI tool

Dagger is now live, we should use it to improve CI speed and scalability.

We should have a plan with an action ci that do:

• lint
• test

Handle notification

Currently server returns a response when a request is made without an identifier.

According to the JSON RPC standard

A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. "Invalid params","Internal error").

The server should handle that special case.

Write usage example in documentation

The current README has no example in his section.
When the project will be ready, there should be complete example to help users use the library.