Struct jsonrpsee_server::Methods

source ·

pub struct Methods { /* private fields */ }

Expand description

Reference-counted, clone-on-write collection of synchronous and asynchronous methods.

Implementations§

source §

impl Methods

source

pub fn new() -> Methods

Creates a new empty Methods.

source

pub fn verify_method_name( &mut self, name: &'static str, ) -> Result<(), RegisterMethodError>

Verifies that the method name is not already taken, and returns an error if it is.

source

pub fn verify_and_insert( &mut self, name: &'static str, callback: MethodCallback, ) -> Result<&mut MethodCallback, RegisterMethodError>

Inserts the method callback for a given name, or returns an error if the name was already taken. On success it returns a mut reference to the MethodCallback just inserted.

source

pub fn merge( &mut self, other: impl Into<Methods>, ) -> Result<(), RegisterMethodError>

Merge two Methods’s by adding all MethodCallbacks from other into self. Fails if any of the methods in other is present already.

source

pub fn method(&self, method_name: &str) -> Option<&MethodCallback>

Returns the method callback.

source

pub fn method_with_name( &self, method_name: &str, ) -> Option<(&'static str, &MethodCallback)>

Returns the method callback along with its name. The returned name is same as the method_name, but its lifetime bound is 'static.

source

pub async fn call<Params, T>( &self, method: &str, params: Params, ) -> Result<T, MethodsError>
where Params: ToRpcParams, T: DeserializeOwned + Clone,

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 successful.

§Examples

#[tokio::main]
async fn main() {
    use jsonrpsee::{RpcModule, IntoResponse};
    use jsonrpsee::core::RpcResult;

    let mut module = RpcModule::new(());
    module.register_method::<RpcResult<u64>, _>("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);
}

source

pub async fn raw_json_request( &self, request: &str, buf_size: usize, ) -> Result<(String, Receiver<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, SubscriptionMessage};
    use jsonrpsee::types::{response::Success, Response};
    use futures_util::StreamExt;

    let mut module = RpcModule::new(());
    module.register_subscription("hi", "hi", "goodbye", |_, pending, _, _| async {
        let sink = pending.accept().await?;

        // see comment above.
        sink.send("one answer".into()).await?;

        Ok(())
    }).unwrap();
    let (resp, mut stream) = module.raw_json_request(r#"{"jsonrpc":"2.0","method":"hi","id":0}"#, 1).await.unwrap();
    // If the response is an error converting it to `Success` will fail.
    let resp: Success<u64> = serde_json::from_str::<Response<u64>>(&resp).unwrap().try_into().unwrap();
    let sub_resp = stream.recv().await.unwrap();
    assert_eq!(
        format!(r#"{{"jsonrpc":"2.0","method":"hi","params":{{"subscription":{},"result":"one answer"}}}}"#, resp.result),
        sub_resp
    );
}

source

pub async fn subscribe_unbounded( &self, sub_method: &str, params: impl ToRpcParams, ) -> Result<Subscription, MethodsError>

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 success which can used to get results from the subscription.

§Examples

#[tokio::main]
async fn main() {
    use jsonrpsee::{RpcModule, SubscriptionMessage};
    use jsonrpsee::core::{EmptyServerParams, RpcResult};

    let mut module = RpcModule::new(());
    module.register_subscription("hi", "hi", "goodbye", |_, pending, _, _| async move {
        let sink = pending.accept().await?;
        sink.send("one answer".into()).await?;
        Ok(())
    }).unwrap();

    let mut sub = module.subscribe_unbounded("hi", EmptyServerParams::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");
}

Similar to Methods::subscribe_unbounded but it’s using a bounded channel and the buffer capacity must be provided.

source

pub fn method_names(&self) -> impl Iterator<Item = &'static str>

Returns an Iterator with all the method names registered on this server.

source

pub fn extensions(&mut self) -> &Extensions

Similar to Methods::extensions_mut but it’s immutable.

source

pub fn extensions_mut(&mut self) -> &mut Extensions

Get a mutable reference to the extensions to add or remove data from the extensions.

This only affects direct calls to the methods and subscriptions and can be used for example to unit test the API without a server.

§Examples

#[tokio::main]
async fn main() {
    use jsonrpsee::{RpcModule, IntoResponse, Extensions};
    use jsonrpsee::core::RpcResult;

    let mut module = RpcModule::new(());
    module.register_method::<RpcResult<u64>, _>("magic_multiply", |params, _, ext| {
        let magic = ext.get::<u64>().copied().unwrap();
        let val = params.one::<u64>()?;
        Ok(val * magic)
    }).unwrap();

    // inject arbitrary data into the extensions.
    module.extensions_mut().insert(33_u64);

    let magic: u64 = module.call("magic_multiply", [1_u64]).await.unwrap();
    assert_eq!(magic, 33);
}