Struct jsonrpsee_http_server::RpcModule
source · [−]pub struct RpcModule<Context> { /* private fields */ }
Expand description
Sets of JSON-RPC methods can be organized into a “module“s that are in turn registered on the server or,
alternatively, merged with other modules to construct a cohesive API. RpcModule
wraps an additional context
argument that can be used to access data during call execution.
Implementations
Register a new synchronous RPC method, which computes the response with the given callback.
pub fn register_async_method<R, Fun, Fut>(
&mut self,
method_name: &'static str,
callback: Fun
) -> Result<MethodResourcesBuilder<'_>, Error> where
R: 'static + Serialize + Send + Sync,
Fut: Future<Output = Result<R, Error>> + Send,
Fun: 'static + Fn(Params<'static>, Arc<Context>) -> Fut + Copy + Send + Sync,
pub fn register_async_method<R, Fun, Fut>(
&mut self,
method_name: &'static str,
callback: Fun
) -> Result<MethodResourcesBuilder<'_>, Error> where
R: 'static + Serialize + Send + Sync,
Fut: Future<Output = Result<R, Error>> + Send,
Fun: 'static + Fn(Params<'static>, Arc<Context>) -> Fut + Copy + Send + Sync,
Register a new asynchronous RPC method, which computes the response with the given callback.
Register a new blocking synchronous RPC method, which computes the response with the given callback.
Unlike the regular register_method
, this method can block its thread and perform expensive computations.
pub fn register_subscription<F>(
&mut self,
subscribe_method_name: &'static str,
notif_method_name: &'static str,
unsubscribe_method_name: &'static str,
callback: F
) -> Result<(), Error> where
Context: 'static + Send + Sync,
F: 'static + Fn(Params<'_>, SubscriptionSink, Arc<Context>) -> Result<(), Error> + Send + Sync,
pub fn register_subscription<F>(
&mut self,
subscribe_method_name: &'static str,
notif_method_name: &'static str,
unsubscribe_method_name: &'static str,
callback: F
) -> Result<(), Error> where
Context: 'static + Send + Sync,
F: 'static + Fn(Params<'_>, SubscriptionSink, Arc<Context>) -> Result<(), Error> + Send + Sync,
Register a new RPC subscription that invokes s callback on every subscription call.
This method ensures that the subscription_method_name
and unsubscription_method_name
are unique.
The notif_method_name
argument sets the content of the method
field in the JSON document that
the server sends back to the client. The uniqueness of this value is not machine checked and it’s up to
the user to ensure it is not used in any other RpcModule
used in the server.
Arguments
subscription_method_name
- name of the method to call to initiate a subscriptionnotif_method_name
- name of method to be used in the subscription payload (technically a JSON-RPC notification)unsubscription_method
- name of the method to call to terminate a subscriptioncallback
- A callback to invoke on each subscription; it takes three parameters:Params
: JSON-RPC parameters in the subscription call.SubscriptionSink
: A sink to send messages to the subscriber.- Context: Any type that can be embedded into the
RpcModule
.
Examples
use jsonrpsee_core::server::rpc_module::RpcModule;
let mut ctx = RpcModule::new(99_usize);
ctx.register_subscription("sub", "notif_name", "unsub", |params, mut sink, ctx| {
let x: usize = params.one()?;
std::thread::spawn(move || {
let sum = x + (*ctx);
sink.send(&sum)
});
Ok(())
});
Methods from Deref<Target = Methods>
Merge two Methods
’s by adding all MethodCallback
s from other
into self
.
Fails if any of the methods in other
is present already.
Returns the method callback.
Returns the method callback along with its name. The returned name is same as the
method_name
, but its lifetime bound is 'static
.
pub async fn call<Params, T>(
&'_ self,
method: &'_ str,
params: Params
) -> Result<T, Error> where
Params: ToRpcParams,
T: DeserializeOwned,
pub async fn call<Params, T>(
&'_ self,
method: &'_ str,
params: Params
) -> Result<T, Error> where
Params: ToRpcParams,
T: DeserializeOwned,
Helper to call a method on the RPC module
without having to spin up a server.
The params must be serializable as JSON array, see ToRpcParams
for further documentation.
Returns the decoded value of the result field
in JSON-RPC response if succesful.
Examples
#[tokio::main]
async fn main() {
use jsonrpsee::RpcModule;
let mut module = RpcModule::new(());
module.register_method("echo_call", |params, _| {
params.one::<u64>().map_err(Into::into)
}).unwrap();
let echo: u64 = module.call("echo_call", [1_u64]).await.unwrap();
assert_eq!(echo, 1);
}
pub async fn raw_json_request(
&'_ self,
call: &'_ str
) -> Result<(String, UnboundedReceiver<String>), Error>
pub async fn raw_json_request(
&'_ self,
call: &'_ str
) -> Result<(String, UnboundedReceiver<String>), Error>
Make a request (JSON-RPC method call or subscription) by using raw JSON.
Returns the raw JSON response to the call and a stream to receive notifications if the call was a subscription.
Examples
#[tokio::main]
async fn main() {
use jsonrpsee::RpcModule;
use jsonrpsee::types::Response;
use futures_util::StreamExt;
let mut module = RpcModule::new(());
module.register_subscription("hi", "hi", "goodbye", |_, mut sink, _| {
sink.send(&"one answer").unwrap();
Ok(())
}).unwrap();
let (resp, mut stream) = module.raw_json_request(r#"{"jsonrpc":"2.0","method":"hi","id":0}"#).await.unwrap();
let resp = serde_json::from_str::<Response<u64>>(&resp).unwrap();
let sub_resp = stream.next().await.unwrap();
assert_eq!(
format!(r#"{{"jsonrpc":"2.0","method":"hi","params":{{"subscription":{},"result":"one answer"}}}}"#, resp.result),
sub_resp
);
}
pub async fn subscribe(
&'_ self,
sub_method: &'_ str,
params: impl ToRpcParams
) -> Result<Subscription, Error>
pub async fn subscribe(
&'_ self,
sub_method: &'_ str,
params: impl ToRpcParams
) -> Result<Subscription, Error>
Helper to create a subscription on the RPC module
without having to spin up a server.
The params must be serializable as JSON array, see ToRpcParams
for further documentation.
Returns Subscription
on succes which can used to get results from the subscriptions.
Examples
#[tokio::main]
async fn main() {
use jsonrpsee::{RpcModule, types::EmptyParams};
let mut module = RpcModule::new(());
module.register_subscription("hi", "hi", "goodbye", |_, mut sink, _| {
sink.send(&"one answer").unwrap();
Ok(())
}).unwrap();
let mut sub = module.subscribe("hi", EmptyParams::new()).await.unwrap();
// In this case we ignore the subscription ID,
let (sub_resp, _sub_id) = sub.next::<String>().await.unwrap().unwrap();
assert_eq!(&sub_resp, "one answer");
}
Returns an Iterator
with all the method names registered on this server.
Trait Implementations
Auto Trait Implementations
impl<Context> !RefUnwindSafe for RpcModule<Context>
impl<Context> !UnwindSafe for RpcModule<Context>
Blanket Implementations
Mutably borrows from an owned value. Read more
pub fn vzip(self) -> V
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more