Module jsonrpsee_core::server::resource_limiting

Available on crate feature server only.

Resource limiting. Create generic “resources” and configure their limits to ensure servers are not overloaded.

Resource Limiting

This module handles limiting the capacity of the server to respond to requests.

jsonrpsee is agnostic about the types of resources available on the server, and the units used are arbitrary. The units are used to model the availability of a resource, be it something mundane like CPU or Memory, or more exotic things like remote API access to a 3rd party service, or use of some external hardware that’s under the control of the server.

To get the most out of this feature, we suggest benchmarking individual methods to see how many resources they consume, in particular anything critical that is expected to result in a lot of stress on the server, and then defining your units such that the limits (capacity) can be adjusted for different hardware configurations.

Up to 8 resources can be defined using the ServerBuilder::register_resource

Each method will claim the specified number of units (or the default) for the duration of its execution. Any method execution that would cause the total sum of claimed resource units to exceed the capacity of that resource will be denied execution, immediately returning JSON-RPC error object with code -32604.

Setting the execution cost to 0 equates to the method effectively not being limited by a given resource. Likewise setting the capacity to 0 disables any limiting for a given resource.

To specify a different than default number of units a method should use, use the resources argument in the #[method] attribute:

#[rpc(server)]
pub trait Rpc {
    #[method(name = "my_expensive_method", resources("cpu" = 5, "mem" = 2))]
    async fn my_expensive_method(&self) -> RpcResult<&'static str> {
        // Do work
        Ok("hello")
    }
}

Alternatively, you can use the resource method when creating a module manually without the help of the macro:

let mut module = RpcModule::new(());

module
    .register_async_method("my_expensive_method", |_, _| async move {
        // Do work
        Ok("hello")
    })?
    .resource("cpu", 5)?
    .resource("mem", 2)?;

Each resource needs to have a unique name, such as "cpu" or "memory", which can then be used across all RpcModules. In case a module definition uses a resource label not defined on the server, starting the server with such a module will result in a runtime error containing the information about the offending method.

Structs

• ResourceGuard
  RAII style “lock” for claimed resources, will automatically release them once dropped.
• Resources
  User defined resources available to be used by calls on the JSON-RPC server. Each of the 8 possible resource kinds, for instance “cpu”, “io”, “nanobots”, store a maximum capacity and a default. A value of 0 means no limits for the given resource.

Type Definitions

• ResourceTable
  Fixed size table, mapping a resource to a (unitless) value indicating the amount of the resource that is available to RPC calls.
• ResourceVec
  Variable size table, mapping a resource to a (unitless) value indicating the amount of the resource that is available to RPC calls.