这是indexloc提供的服务,不要输入任何密码
Skip to content

Conversation

@ppipada
Copy link

@ppipada ppipada commented Jan 15, 2025

Hi,

I have been working on supporting jsonrpc 2.0 for one of my use case using huma.

The main features include:

  • Support full jsonrpc message specification including request, response, notification and error
  • Support batch requests
  • Modular code with consumers having ability to stitch code as required. Conventional stitching helpers already present.
  • Easy consumption by just importing the package and adding request/notification handlers
  • Create a full openapi 3.1 schema for the supported requests/notifications with proper types

Things I have not added:

  • Concurrent processing of requests inside a batch. This can be built incrementally on top of this without any impact on consumers.
  • Errors that are supposed to be "Invalid Method Params" are not detected. Some details below.

Implementation notes:

  • Given that jsonrpc supports batch or single requests and each request/response/notification is in itself is a multiplexed format, we need to start by adding a meta request that puts single/multiple requests inside a array and then processes them. This means that the schema generation for this meta handler and individual handlers cannot be directly done using the input struct. A custom schema needs to be created using a two level OneOf.
  • Similar is true at one more level for responses as they must contain a error or a result.
  • jsonrpc is to be served on a single post endpoint. Therefore the individual methods are available at registration time. Added a utility to create and append their schema as well.
  • The whole schema generation took some time to get right because of the multi level multiplexing of jsonrpc and the use of "sum types" in the specification. I have mostly tried to do this by looking at huma's actual handling code. As I am very new to this, it is quite possible that there is a much simple/better way for doing this.
  • An error handler to convert all errors to jsonrpc format errors is present. The error handler looks a bit all over the place. This is because I needed to deduce various scenarios in the handler from the error message (especially if it is a huma generated error). One scenario I was not able to handle was that of deducing whether the error was a request error or a method params error as all things are raised as a "validation failed" error. There may be better ways to do this but I was not able to figure this out.
  • Unit tests are present. Some scenarios are tested using an example server/client test.

I understand that this is a direct pull request without sufficient discussion first and I am sorry if this is way out of line. The main rationale of doing a pull request directly was that the implementation looked involved enough that discussion using code seemed like a better idea.

If jsonrpc support doesn't really align with huma's goals, feel free to close this.

Thank you for your great work, I do love huma !!!

@danielgtaylor
Copy link
Owner

@ppipada this is really neat, thank you for building it! I'm not very familiar with jsonrpc so I will read up on it some more, and before I do a deeper review I did want to ask a question. It seems like this doesn't change any Huma internals, so is there a reason you want this as part of Huma's core rather than as an extra lib you can install to work alongside/with Huma?

@ppipada
Copy link
Author

ppipada commented Jan 17, 2025

@danielgtaylor Thank you for your response.

On why jsonrpc with huma:

  • My impression of huma is that it takes care of the contractual part of a service (transport helpers/adapters + encode decode + api docs) with consumers left to focus on their business logic i.e write their handlers. Its focus for doing this is http based systems.
  • Because of above huma has a sse adapter on top of core huma so that sse writers can focus on sending events rather than the encode/decode/docs part of it.
  • jsonrpc is a message format and interaction specification that is agnostic of transport. It is helpful and used in simpler polyglot services. In my usecase and in services migrating to go from other programming languages, it is not uncommon for jsonrpc endpoint to be present with other normal rest endpoints.
  • I have tried to write jsonrpc in similar to sse fashion. i.e dont touch the core give it as a additional adapter. The adapter takes care of encode/decode/api docs and has some small helpers on top of huma core for ease of consumption related to registration/error handling. (go-kit has it as a additional subtransport of http)
  • This enables consumers who care about supporting jsonrpc to do so in a similar fashion to rest of huma i.e write handlers, leave encode/decode/docs to huma. Also, as it doesnt touch huma core, no current consumers or people who dont care about jsonrpc are not affected.

@danielgtaylor
Copy link
Owner

@ppipada thanks! I think this work is great and I understand why you'd want to use jsonrpc with Huma. It makes sense that you built it similar to the SSE package.

My main question is, why not make a new repo ppipada/huma-jsonrpc? I am happy to link to it in the README and docs site so that anyone looking for jsonrpc support goes to your module, I'm just concerned I won't be able to maintain your jsonrpc code and fix any bugs or add features in it as part of working on Huma itself.

@ppipada
Copy link
Author

ppipada commented Jan 19, 2025

@danielgtaylor Maintaining this is as a
separate repo is also fine I suppose. I will ping when I create a repo.

Thanks for your time !

@ppipada ppipada closed this Jan 19, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants