JSON-RPC library designed for async/await in Rust

Designed to be the successor to tracking issue for next stable release (0

jsonrpsee

JSON-RPC library designed for async/await in Rust.

Designed to be the successor to ParityTech's JSONRPC crate.

Support WebSocket and HTTP transports for both client and server.

Under development

The library is still under development; do not use in production.

Sub-projects

  • jsonrpsee-http-client
  • jsonrpsee-http-server
  • jsonrpsee-proc-macros
  • jsonrpsee-ws-client
  • jsonrpsee-ws-server

Examples

  • HTTP
  • WebSocket
  • WebSocket pubsub
  • API generation with proc macro

Roadmap

See tracking issue for next stable release (0.7)

Users

If your project uses jsonrpsee we would like to know. Please open a pull request and add your project to the list below:

  • substrate-subxt
  • parity bridges common
  • remote externalities
Issues

Collection of the latest Issues

jsdw

jsdw

0

At the moment, subscriptions can push messages onto an unbounded Sink to be sent to connected clients. However, if the client is too slow to accept messages, they will build up in that unbounded channel, and the subscription handler won't be made aware of any slowness.

One option to address this is to make the Sinks bounded. This adds backpressure, and makes the subscription aware of any slowness (via poll_ready on the sink returning Pending). The subscription can then take advantage of this backpressure to implement strategies like aggregating or dropping messages, dropping the connection entirely, or just using its own unbounded channel to buffer messages internally to recreate the existing behaviour.

There are some doubts about using bounded sinks in thie way owing to previous bugs that have cropped up from doing so, so let's tread carefully and prototype this (or some other approach that provides the same information to subscriptions) before committing to it.

See https://github.com/paritytech/substrate/issues/11689 for a discussion on this.

tgmichel

tgmichel

2

Some http providers by default include non-standard fields (i.e. skipCache) in the request. This results in Invalid Request as the Request explicitly denies deserialization of unknown fields.

To support this type of requests on jsonrpsee, some options:

  • Adding a generic parameter to Request to allow accepting specific non-standard fields. This generic must implement Deserialize, represented as a flatten field in Request, and default to an empty type, something like:

  • Other option can be putting deny_unknown_fields behind a feature flag, which will optionally accept any non-standard field.

niklasad1

niklasad1

0

I'm struggling to understand ALWAYS_ALLOWED_HEADERS; I think that we allow any headers specified in AllowHeaders plus any in ALWAYS_ALLOWED_HEADERS.

I guess we have this list so that if the user doesn't allow any headers themselves via the access control stuff, standard requests will still work?

Some headers are also not completely black and white as to whether they are accepted or not. Eg with CORS, we'll always need to return "Content-Type" in the "Access-Control-Allowed-Headers" response, because otherwise I think the user couldn't set that to "application/json" without CORS disallowing it (see https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_request_header#additional_restrictions).

Also there is an Access-Control-Allow-Origin header in the list, which is what the server would respond with, so perhaps this doesn't need to be there? Also a client can send an Access-Control-Request-Method header in a preflight request, and so perhaps that should be there?

Originally posted by @jsdw in https://github.com/paritytech/jsonrpsee/pull/781#discussion_r895569757

koivunej

koivunej

2

I noticed that jsonrpsee-0.11 and 0.13.x don't handle gracefully RpcModule::register_blocking_method methods which panic. Reproducer can be found at https://gist.github.com/koivunej/8eeb6cf7cd5cfcae3696eb458a10297e

I was initially thinking that this is because the response object is built within the spawn_blocking the actual callback is executed: https://docs.rs/jsonrpsee-core/0.13.1/src/jsonrpsee_core/server/rpc_module.rs.html#595-612 However running the reproducer with stable 1.61.0 gives an additional expect failing:

Which is here: https://github.com/paritytech/jsonrpsee/blob/4706aadbb08b86f33efbf35442a080cdd478d735/http-server/src/server.rs#L712

I think an expected graceful handling would be similar what we are doing right now in pathfinder, which is almost (in methods registered as async methods):

We would like to use register_blocking_method in cases where we only have blocking code to execute. We could add a layer of catch_unwind to use register_blocking_method but that would take up as many (or more) lines as the current spawn_blocking usage from async context.

I haven't checked if the register_async_method guard against panicking, but that is less of a concern for us.

lexnv

lexnv

enhancement
0

PR #772 introduced the ability to Ping periodically the WS server, as a keep-alive alternative.

As an improvement, this can be extended to process Pong frames. If a Pong frame was not received in a set interval (ie: time between two Pings, or user-driven interval), then the connection should be dropped.

This adds extra complexity and should be taken into consideration if or when customers need such behavior.

niklasad1

niklasad1

0

Recently the subscription code got refactor where one must reject or accept a subscription manually and because SubscriptionClosed is not treated as an error the closures must not return Result.

However, it's quite awkward to so:

Example:

So it would be more ergonomic / less awkward if it would be possible to do:

The tricky part is that if one wants to reject a call explicitly then the error type has to be cloned or borrowed. So that's rationale why the API is like is at the moment.

ljedrz

ljedrz

5

snarkOS could use the ability to log the source and possibly some of the header of the RPC requests it receives: https://github.com/AleoHQ/snarkOS/issues/1628; I think this could be achieved by extending the parameters of Middleware::on_call, but I'm open to other options.

If I didn't miss anything in my partial implementation of a PR addressing the linked issue, this is currently not supported.

I know that there is a DEBUG log turned on by default, but it was too verbose and I think it only contained information on the response (which was also truncated if it was deemed too long), so we silenced that one.

Possibly related existing issues: https://github.com/paritytech/jsonrpsee/issues/450, https://github.com/paritytech/jsonrpsee/issues/487.

jsdw

jsdw

5

First off, apologies if this is wrong; I haven't spent long digging into the macro code here!

So, currently we can generate a client impl using the proc macro like so:

I believe this generates something like an trait MyRpcClient<T>: ClientT where T: Send + Sync + 'static trait, and an impl for it that means the RPC Client impls these methods (very cool btw!).

However, in some cases this general rule of applying Send + Sync + 'static to all type params is unnecessarily restrictive. Take the following example:

This generates something like trait MyRpcClient<T>: ClientT where T: Send + Sync + 'static + Config, but here T does not need to be Send + Sync + 'static since it's not actually returned or passed in anywhere (we only care about T::Hash).

This is quite a common issue in derives too, for instance if we take this struct:

The generated Clone impl is something like impl <T> Clone for Foo<T> where T: Clone {..}, which is unnecessary since T really doesn't need to be cloneable (it's not instantiated anywhere).

A common solution is to allow people an escape hatch to override the automatically applied trait bounds. The derivative library provides this for common traits, so we could impl Clone for all Foo<T>'s like so:

This generates an impl more like impl <T> Clone for Foo<T> {..} (we override the Clone bounds to be nothing).

Serde has a similar feature:

Again, we can manually set the bound to something like "T: MyTrait", or in our case, nothing ("").

Perhaps it would be useful to provide a similar "escape hatch" in jsonrpsee? With such a feature, the earlier example could be made to work with something like:

It would need a little thought;

  • does client_bounds override all bounds that would be applied, so that they all need to be manual? In this case we might need eg client_bound = "T::Hash: Serialize + Deserialize" or something?
  • would we need client_bound and server_bound to allow overriding each?
niklasad1

niklasad1

0

It would be nice to provide a way to perform batch request using the macro API trait Similar to:

However, :point_up: would make a separate RPC call for each request. So instead we would need to have a separate trait or method that internally just extracts the method name and params and converts it to a batch request such as:

lexnv

lexnv

bug
12

Details

  • cargo bench -p jsonrpsee-benchmarks -- --output-format bencher results in a repeating panic
  • commit: 2864756 - dependabot[bot] - chore(deps): update parking_lot requirement from 0.11 to 0.12 (#682)
  • os | hardware: macOS Monterey v12.2 | apple M1 pro

Panic Details

maciejhirsz

maciejhirsz

0

We need to make sure that the FutureDriver completes before connection is dropped. It's not strictly necessary but it might help with weird cancellation issues for users downstream.

The test should include a method that takes a while to execute (either async sleep, or some mutex lock that we can lock to ensure the order of operation here), with a mock client that will send a request to the server and then drop the connection before reading from the socket, thus forcing the method to be executed while the background task for the connection is winding down.

crystalin

crystalin

2

Ideally, the library should allow the user to control how the logs are produced. Here is the requirements we believe are needed for our parachain node:

  • Support to log the request, including its payload*
  • Support to log the response, including its payload* and the timing
  • *Payload could be filtered (to include some fields, or based on the method used). The possibility to reduce the the content of the fields in the payout automatically (like an array of 1000 items displaying only the first and last item).
gilescope

gilescope

4

It would be pretty cool if when you hit a "Method not found" it would (maybe only when built in debug) suggest other method(s) that sounded similar to that method.

Touches like this make developing with such libraries a pleasure and reduce head scratching leading to better cycle times.

Example of prior art:

Versions

Find the latest versions by id

v0.14.0 - Jun 14, 2022

[v0.14.0] - 2022-06-14

v0.14.0 is breaking release which changes the health and access control APIs and a bunch of bug fixes.

[Fixed]

  • fix(servers): more descriptive errors when calls fail #790
  • fix(ws server): support * in host and origin filtering #781
  • fix(rpc module): register failed unsubscribe calls in middleware #792
  • fix(http server): omit jsonrpc details in health API #785
  • fix(servers): skip leading whitespace in JSON deserialization #783
  • fix(ws-server): Submit ping regardless of WS messages #788
  • fix(rpc_module): remove expect in fn call #774

[Added]

  • feat(ws-client): ping-pong for WebSocket clients #772
  • feat(ws-server): Implement ping-pong for WebSocket server #782

[Changed]

  • chore(deps): bump Swatinem/rust-cache from 1.3.0 to 1.4.0 #778
  • chore(deps): bump actions/checkout from 2.4.0 to 3.0.2 #779
  • chore(ci): bring back daily benchmarks #777
  • chore(examples): Move examples under dedicated folder to simplify Cargo.toml #769

v0.13.1 - May 13, 2022

[v0.13.1] - 2022-05-13

v0.13.1 is a release that fixes the documentation for feature-gated items on docs.rs.

v0.13.0 - May 11, 2022

[v0.13.0] - 2022-05-11

v0.13.0 is release that adds health API support for the HTTP server and a few bug fixes.

[Added]

feat: add http health API #763

[Fixed]

  • hide internal macros from public interface #755
  • fix: add core behind http-server feature #760

v0.12.0 - May 06, 2022

[v0.12.0] - 2022-05-06

v0.12.0 is mainly a patch release with some minor features added.

[Added]

  • Make it possible to disable batch requests support #744
  • feat: add a way to limit the number of subscriptions per connection #739

[Fixed]

  • fix(http client): use https connector for https #750
  • fix(rpc module): close subscription task when a subscription is unsubscribed via the unsubscribe call #743
  • fix(jsonrpsee): generate docs behind features #741

[Changed]

  • remove vault from ci #745
  • chore(deps): update pprof requirement from 0.7 to 0.8 #732
  • chore(deps): update gloo-net requirement from 0.1.0 to 0.2.0 #733

v0.11.0 - Apr 21, 2022

[v0.11.0] - 2022-04-21

v0.11.0 is a breaking release that reworks how subscriptions are handled by the servers where the users have to explicitly reject or accept each subscription. The reason for this is that the actual params in the subscription is passed to the callback and if the application decides the params are invalid and the server can't know if the call is going to fail or pass when dispatching the call. Thus, the actual subscription method call is only answered when the subscription is accepted or rejected.

Additionally, the servers before sent a SubscriptionClosed message which is now disabled by default because it might break other implementations. It is still possible to respond with a SubscriptionClosed message but one has to match on the result from SubscriptionSink::pipe_from_stream.

This release also adds support for JSON-RPC WASM client using web-sys bindings.

[Added]

  • feat: WASM client via web-sys transport #648

[Changed]

  • CI: bump Swatinem/rust-cache from 1.3.0 to 1.4.0 #730

[Fixed]

  • fix(rpc module): fail subscription calls with bad params #728

v0.10.1 - Apr 05, 2022

[v0.10.1] - 2022-04-05

v0.10.1 is a release that fixes a regression in the HTTP server where the backlog was hardcoded to 128 (this is now set to 1024 by default but also configurable), introduces a couple of new APIs and a few minor bug fixes.

If your usage expects a high rate of new HTTP connections you are encouraged to update or manually configure the socket based on the traffic characteristics.

[Changed]

  • [proc macros]: only generate unsub method if not provided (#702)
  • [examples]: update pubsub examples #705
  • core: remove Error::Request variant #717
  • Replace async-channel #708
  • chore(deps): bump actions/checkout from 2.4.0 to 3 #710
  • CI: cache cargo hack installation #706
  • CI: try nextest #701
  • chore(deps): update tokio-util requirement from 0.6 to 0.7 #695
  • CI: Move CI script to new location #694
  • refactor(log): downgrade send errors to warn #726

[Fixed]

  • fix(client): close subscription when server sent SubscriptionClosed notification #721
  • fix(http client): set reuseaddr and nodelay. #687
  • fix(rpc module): unsubscribe according ethereum pubsub spec #693
  • http server: fix regression set backlog to 1024 #718
  • README.MD: fix link to ws server #703
  • fix(ws server): close all subscription when the connection is closed #725
  • perf: don't send messages when client is gone #724

[Added]

  • feat(http server): add new builder APIs build_from_tcp and build_from_hyper #719
  • feat(servers): add SubscriptionSink::pipe_from_try_stream to support streams that returns Result #720
  • feat(servers): add max_response_size #711

v0.10.0 - Apr 04, 2022

[v0.10.0] - 2022-04-04 [YANKED]

v0.9.0 - Feb 14, 2022

[v0.9.0] - 2022-02-03

v0.9.0 is technically a breaking release because of the Debug bound of the IdProvider trait changed which is used by WebSocket server. In practise it should be a non-breaking upgrade for most users.

[Changed]

refactor(ws server): impl IdProvider for Box #684 chore(deps): update parking_lot requirement from 0.11 to 0.12 #682

v0.8.0 - Jan 26, 2022

[v0.8.0] - 2022-01-21

v0.8.0 is a breaking release for the way subscription closing is handled, along with a few other minor tweaks and fixes.

[Added]

  • feat(client): support request id as Strings. #659
  • feat(rpc module) Add a method to RpcModule that transforms the module into a RpcModule<()>, i.e. removes the context. #660
  • feat(rpc module): stream API for SubscriptionSink #639

[Fixed]

  • fix: nit in WsError #662
  • fix(jsonrpsee): feature macros include client types #656
  • fix(ws client): export WsClient #646
  • fix(ws client): improve error message bad URL #642
  • fix(ws client): expose tls feature. #640
  • fix(http server): handle post and option HTTP requests properly. #637

v0.7.0 - Dec 22, 2021

[v0.7.0] - 2022-12-22

v0.7.0 is a breaking release that contains a big refactoring of the crate structure. The types and utils crates are split up as types and core to clarify the difference between the two.

core: common types used in various places. types: includes JSON-RPC specification related types.

[Added]

  • servers: configurable subscriptionID #604
  • client: impl Stream on Subscription and tweak built-in next() method #601
  • ci: Create gitlab pipeline #534

[Changed]

  • chore: migrate to rust 2021 #618
  • extract async client abstraction. #580
  • Crate restructuring #590
  • servers: refactor SubscriptionClosed #612
  • ci: Add job to publish benchmark results to github pages #603
  • rpc module: refactor calls/subs without a server #591
  • types: make subscription ID a CoW String. #594
  • ci: remove GHA daily benchmark #598
  • examples: Remove usage of the palaver crate in an example #597
  • clients: use FxHashMap instead FnvHashMap #592
  • clients: feature gate tls #545

[Fixed]

  • benches: fix image in check-bench job #621
  • benches: update publish script #619
  • chore(http client): remove needless clone #620
  • jsonrpsee wrapper: make ws tls configurable #616
  • deps: Upgrade tracing-subscriber #615
  • proc macros: Fix span for underscore_token for tests to be equivalent on stable and nightly #614
  • proc macros: Better error messages for method arguments ignored with a _ #611
  • http client: re-export transport types. #607
  • benches: Fix job to publish benchmark results to gh-pages #608
  • benches: make jsonrpc crates optional #596
  • deps: duplicate env logger deps #595

v0.6.1 - Dec 07, 2021

[v0.6.1] – 2021-12-07

[Added]

  • rpc module: add call_and_subscribe #588

v0.6.0 - Dec 01, 2021

[v0.6.0] – 2021-12-01

v0.6 is a breaking release

[Added]

  • Servers: Middleware for metrics #576
  • http client: impl Clone #583

[Fixed]

  • types: use Cow for deserializing str #584
  • deps: require tokio ^1.8 #586

v0.5.1 - Nov 26, 2021

[v0.5.1] – 2021-11-26

The v0.5.1 release is a bug fix.

[Fixed]

  • rpc error: support escaped strings #578

v0.5.0 - Nov 24, 2021

[v0.5.0] – 2021-11-23

v0.5 is a breaking release

[Added]

  • Add register_blocking_method #523
  • Re-introduce object param parsing #526
  • clients: add support for webpki and native certificate stores #533
  • feat(ws client): support custom headers. #535
  • Proc macro support for map param #544
  • feat: make it possible to try several sockaddrs when starting server #567
  • feat: make it possible to override method name in subscriptions #568
  • proc-macros: Support deprecated methods for rpc client #570

[Change]

  • DRY error handling for methods #515
  • deps: replace log with tracing #525
  • benches: add option to run benchmarks against jsonrpc crate servers #527
  • clients: request ID as RAII guard #543
  • Allow awaiting on server handles #550
  • ws server: reject too big response #553
  • Array syntax aliases #557
  • rpc module: report error on invalid subscription #561
  • [rpc module]: improve TestSubscription to return None when closed #566

[Fixed]

  • ws server: respect max limit for received messages #537
  • fix(ws server): batch wait until all methods has been executed. #542
  • Re-export tracing for macros #555
  • Periodically wake DriverSelect so we can poll whether or not stop had been called. #556
  • Implement SubscriptionClient for HttpClient #563
  • fix: better log for failed unsubscription call #575

v0.4.1 - Oct 12, 2021

The v0.4.1 release is a bug fix.

[Fixed]

  • fix: nit in ServerBuilder::custom_tokio_runtime #512

v0.4.0 - Oct 12, 2021

The v0.4 release is a breaking change.

[Added]

  • Document resource limiting (#510)
  • Resource limiting #500
  • Support http redirects when doing the ws handshake #397
  • Add convenience rpc_params macro to build params in http and ws clients #498
  • Method alias attribute for proc macros #442
  • Add benchmarks for concurrent connections #430
  • Support generic type params in the proc macro #436

[Changed]

  • use tokio::spawn internally in HttpServer::start and return StopHandle #402
  • remove ParamsSer::NoParams #501
  • http server uses similar API for host and origin filtering as WS #473
  • SubscriptionClosed errors carry more information #504
  • Improve feature configuration for faster builds and leaner build artifacts #494
  • Unbox async futures #495
  • WS clients default subscription buffer set to 1024 items #475
  • Re-export v2 submodules #469
  • Replace internal array_impl macro with const generics #470
  • Rename and reorganize many public types #462
  • Export acl types #466
  • Propagate cause of InvalidParams #463
  • Reject overflowing connection with status code 429 #456
  • Test helper for calling and converting types to JSON-RPC params #458
  • Make it possible to treat empty JSON response as no params #446
  • Methods generated by the proc macro return Result #435
  • Concurrent polling on async methods #424
  • Sniff the first byte to glean if the incoming request is a single or batch request #419
  • Upgrade hyper to ^0.14.10 #427
  • Proc macro params optimizations and tests. #421

[Fixed]

  • Proc macro Argument parsing should permit commas inside angle brackets #509
  • Fix http client bench with request limit #506
  • Fixed flaky test on windows #491
  • Share the request id code between the http and websocket clients #490
  • WS server terminates subscriptions when connection is closed by the client. #483
  • Subscription code generated by the proc macro generated returns Result #455
  • Proc macro generates documentation for trait methods. #453
  • Fix errors with generics when using the proc macro #433
  • WS client uses query part of the URL #429

[Removed]

  • Remove rustls #502
  • Remove cors_max_age #466
  • Remove support for tokio 0.2 runtimes #432

v0.3.1 - Sep 17, 2021

Patch release that fixes:

  • [ws-client]: Increase default buffer size for subscriptions to 1024 #475
  • [ws-client]: Use query part of the URL #429

v0.2.0 - Jun 04, 2021

⚠️ Breaking change ⚠️

Version 0.2.0 is a major refactoring of all jsonrpsee internals. It is yet feature incomplete. See the CHANGELOG for some more details.

v0.2.0-alpha.7 - May 27, 2021

  • unify error types in the servers. (#294)
  • Fix clippy warning and enforce no warning in the CI (#273)
  • Fix examples links (#297)
  • [servers] return error if context or params fails (#295)
  • [ws-server] Batch support (#300)
  • [utils]: add futures util feature to server (#305)
  • [ci]: fix workflow to run (#310)
  • Add a test for calling methods with multiple params of multiple types (#308)
  • [ws client] RegisterNotification support (#303)
  • Change order of type params to register_method (#312)
  • CI: optimize caching (#317)
  • Bump actions/checkout from 2 to 2.3.4 (#315)
  • Bump actions-rs/cargo from 1 to 1.0.3 (#314)
  • Bump actions-rs/toolchain from 1 to 1.0.7 (#313)
  • [ws server]: add logs (#319)
  • Add certificate_store() to WsClientBuilder and enable native certificate store by default (#321)
  • [servers] extract rpc modules to utils (#322)
  • [types]: ID type instead of serde_json::RawValue (#325)
  • Add unit-tests for the request/call (de)serialization (#326)
  • [ws client]: fix faulty poll in test. (#330)
  • Impl Deref/DerefMut for RpcContextModule (#331)
  • Add timeouts to the futures in tests (#332)
  • Switch from anyhow::Result to std Result (#333)
  • [ws client]: parse path from the URL (#335)
  • chore(deps): bump soketto to fix #337 (#341)
  • [ws client]: return last seen error in connect (#338)
  • chore(deps): update futures 0.3.14 (#342)
  • chore(deps): relax async-std to 1 (#343)
  • chore(release): 0.2.0-alpha.7 (#344)

v0.2.0-alpha.6 - Apr 27, 2021

Patch release that fixes:

  • Race condition in RequestIdGuard
  • Make all AtomicIntegers SeqCst to be on the safe-side
  • Fix bad deserialization implementation of JSONRPC Error Object.

Information - Updated Jun 23, 2022

Stars: 212
Forks: 65
Issues: 40

Rust library for Self Organising Maps (SOM)

Add rusticsom as a dependency in Cargo

Rust library for Self Organising Maps (SOM)

Rust library for parsing configuration files

The 'option' can be any string with no whitespace

Rust library for parsing configuration files

Rust library for the Pimoroni Four Letter pHAT

This library aims to port ht16k33 (or rather a fork, as of right now) so credit goes to ht16k33-diet

Rust library for the Pimoroni Four Letter pHAT

Rust library for emulating 32-bit RISC-V

This library can execute instructions against any memory and register file that implements

Rust library for emulating 32-bit RISC-V

Rust library for connecting to the IPFS HTTP API using Hyper/Actix

You can use actix-web as a backend instead of hyper

Rust library for connecting to the IPFS HTTP API using Hyper/Actix

Rust library to manipulate file system access control lists (ACL) on macOS, Linux, and FreeBSD

This module provides two high level functions, getfacl and setfacl

Rust library to manipulate file system access control lists (ACL) on macOS, Linux, and FreeBSD

Rust library translation (rust-src/rust-std/stdlib/rustlib translation)

This is the place to translate Having a documentation in your native language is essential if you don't speak English, and still enjoyable even if...

Rust library translation (rust-src/rust-std/stdlib/rustlib translation)

Rust library for using Infrared hardware decoders (For example a Vishay TSOP* decoder),

enabling remote control support for embedded project

Rust library for using Infrared hardware decoders (For example a Vishay TSOP* decoder),

Rust library for interaction with the OriginTrail Decentralized Knowledge Graph

open up an issue on this repository and let us know

Rust library for interaction with the OriginTrail Decentralized Knowledge Graph

Rust library for parsing COLLADA files

Notice: This library is built around files exported from Blender 2

Rust library for parsing COLLADA files

Rust library for low-level abstraction of MIPS32 processors

This project is licensed under the terms of the MIT license

Rust library for low-level abstraction of MIPS32 processors
Facebook Instagram Twitter GitHub Dribbble
Privacy