Module jsonrpsee_core::server::resource_limiting
source · Expand description
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
RpcModule
s. 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
- RAII style “lock” for claimed resources, will automatically release them once dropped.
- 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 of0
means no limits for the given resource.
Type Definitions
- Fixed size table, mapping a resource to a (unitless) value indicating the amount of the resource that is available to RPC calls.
- Variable size table, mapping a resource to a (unitless) value indicating the amount of the resource that is available to RPC calls.