Struct jsonrpsee::RpcModule

source ·
pub struct RpcModule<Context> { /* private fields */ }
Expand description

Sets of JSON-RPC methods can be organized into “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§

source§

impl<Context> RpcModule<Context>

source

pub fn new(ctx: Context) -> RpcModule<Context>

Create a new module with a given shared Context.

source

pub fn from_arc(ctx: Arc<Context>) -> RpcModule<Context>

Create a new module from an already shared Context.

This is useful if Context needs to be shared outside of an RpcModule.

source

pub fn remove_context(self) -> RpcModule<()>

Transform a module into an RpcModule<()> (unit context).

source§

impl<Context> RpcModule<Context>
where Context: Send + Sync + 'static,

source

pub fn register_method<R, F>( &mut self, method_name: &'static str, callback: F, ) -> Result<&mut MethodCallback, RegisterMethodError>
where Context: Send + Sync + 'static, R: IntoResponse + 'static, F: Fn(Params<'_>, &Context, &Extensions) -> R + Send + Sync + 'static,

Register a new synchronous RPC method, which computes the response with the given callback.

§Examples
use jsonrpsee_core::server::RpcModule;

let mut module = RpcModule::new(());
module.register_method("say_hello", |_params, _ctx, _| "lo").unwrap();
source

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

Removes the method if it exists.

Be aware that a subscription consist of two methods, subscribe and unsubscribe and it’s the caller responsibility to remove both subscribe and unsubscribe methods for subscriptions.

source

pub fn register_async_method<R, Fun, Fut>( &mut self, method_name: &'static str, callback: Fun, ) -> Result<&mut MethodCallback, RegisterMethodError>
where R: IntoResponse + 'static, Fut: Future<Output = R> + Send, Fun: Fn(Params<'static>, Arc<Context>, Extensions) -> Fut + Clone + Send + Sync + 'static,

Register a new asynchronous RPC method, which computes the response with the given callback.

§Examples
use jsonrpsee_core::server::RpcModule;

let mut module = RpcModule::new(());
module.register_async_method("say_hello", |_params, _ctx, _| async { "lo" }).unwrap();
source

pub fn register_blocking_method<R, F>( &mut self, method_name: &'static str, callback: F, ) -> Result<&mut MethodCallback, RegisterMethodError>
where Context: Send + Sync + 'static, R: IntoResponse + 'static, F: Fn(Params<'_>, Arc<Context>, Extensions) -> R + Clone + Send + Sync + 'static,

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.

source

pub fn register_subscription<R, F, Fut>( &mut self, subscribe_method_name: &'static str, notif_method_name: &'static str, unsubscribe_method_name: &'static str, callback: F, ) -> Result<&mut MethodCallback, RegisterMethodError>
where Context: Send + Sync + 'static, F: Fn(Params<'static>, PendingSubscriptionSink, Arc<Context>, Extensions) -> Fut + Send + Sync + Clone + 'static, Fut: Future<Output = R> + Send + 'static, R: IntoSubscriptionCloseResponse + Send,

Register a new publish/subscribe interface using JSON-RPC notifications.

It implements the ethereum pubsub specification with an option to choose custom subscription ID generation.

Furthermore, it generates the unsubscribe implementation where a bool is used as the result to indicate whether the subscription was successfully unsubscribed to or not. For instance an unsubscribe call may fail if a non-existent subscription ID is used in the 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 subscription
  • notif_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 subscription
  • callback - A callback to invoke on each subscription; it takes three parameters:
    • Params: JSON-RPC parameters in the subscription call.
    • PendingSubscriptionSink: A pending subscription waiting to be accepted, in order to send out messages on the subscription
    • Context: Any type that can be embedded into the RpcModule.
§Returns

An async block which returns something that implements crate::server::IntoSubscriptionCloseResponse which decides what action to take when the subscription ends whether such as to sent out another message on the subscription stream before closing down it.

NOTE: The return value is ignored if PendingSubscriptionSink hasn’t been called or is unsuccessful, as the subscription is not allowed to send out subscription notifications before the actual subscription has been established.

This is implemented for Result<T, E> and ().

It’s recommended to use Result if you want to propagate the error as special error notification Another option is to implement crate::server::IntoSubscriptionCloseResponse if you want customized behaviour.

The error notification has the following format:

{
 "jsonrpc": "2.0",
 "method": "<method>",
 "params": {
   "subscription": "<subscriptionID>",
   "error": <your msg>
   }
 }
}
§Examples

use jsonrpsee_core::server::{RpcModule, SubscriptionSink, SubscriptionMessage};
use jsonrpsee_types::ErrorObjectOwned;

let mut ctx = RpcModule::new(99_usize);
ctx.register_subscription("sub", "notif_name", "unsub", |params, pending, ctx, _| async move {

    let x = match params.one::<usize>() {
        Ok(x) => x,
        Err(e) => {
           pending.reject(ErrorObjectOwned::from(e)).await;
           // If the subscription has not been "accepted" then
           // the return value will be "ignored" as it's not
           // allowed to send out any further notifications on
           // on the subscription.
           return Ok(());
        }
    };

    // Mark the subscription is accepted after the params has been parsed successful.
    // This is actually responds the underlying RPC method call and may fail if the
    // connection is closed.
    let sink = pending.accept().await?;
    let sum = x + (*ctx);

    // This will send out an error notification if it fails.
    //
    // If you need some other behavior implement or custom format of the error field
    // you need to manually handle that.
    let msg = SubscriptionMessage::from_json(&sum)?;

    // This fails only if the connection is closed
    sink.send(msg).await?;

    Ok(())
});
source

pub fn register_subscription_raw<R, F>( &mut self, subscribe_method_name: &'static str, notif_method_name: &'static str, unsubscribe_method_name: &'static str, callback: F, ) -> Result<&mut MethodCallback, RegisterMethodError>
where Context: Send + Sync + 'static, F: Fn(Params<'_>, PendingSubscriptionSink, Arc<Context>, &Extensions) -> R + Send + Sync + Clone + 'static, R: IntoSubscriptionCloseResponse,

Similar to RpcModule::register_subscription but a little lower-level API where handling the subscription is managed the user i.e, polling the subscription such as spawning a separate task to do so.

This is more efficient as this doesn’t require cloning the params in the subscription and it won’t send out a close message. Such things are delegated to the user of this API

§Examples

use jsonrpsee_core::server::{RpcModule, SubscriptionSink, SubscriptionMessage};
use jsonrpsee_types::ErrorObjectOwned;

let mut ctx = RpcModule::new(99_usize);
ctx.register_subscription_raw("sub", "notif_name", "unsub", |params, pending, ctx, _| {

    // The params are parsed outside the async block below to avoid cloning the bytes.
    let val = match params.one::<usize>() {
        Ok(val) => val,
        Err(e) => {
            // If the subscription has not been "accepted" then
            // the return value will be "ignored" as it's not
            // allowed to send out any further notifications on
            // on the subscription.
            tokio::spawn(pending.reject(ErrorObjectOwned::from(e)));
            return;
        }
    };

    tokio::spawn(async move {
        // Mark the subscription is accepted after the params has been parsed successful.
        // This is actually responds the underlying RPC method call and may fail if the
        // connection is closed.
        let sink = pending.accept().await.unwrap();
        let sum = val + (*ctx);

        let msg = SubscriptionMessage::from_json(&sum).unwrap();

        // This fails only if the connection is closed
        sink.send(msg).await.unwrap();
    });
});
source

pub fn register_alias( &mut self, alias: &'static str, existing_method: &'static str, ) -> Result<(), RegisterMethodError>

Register an alias for an existing_method. Alias uniqueness is enforced.

Methods from Deref<Target = 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");
}
source

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

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);
}

Trait Implementations§

source§

impl<Context> Clone for RpcModule<Context>
where Context: Clone,

source§

fn clone(&self) -> RpcModule<Context>

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl<Context> Debug for RpcModule<Context>
where Context: Debug,

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
source§

impl<Context> Deref for RpcModule<Context>

§

type Target = Methods

The resulting type after dereferencing.
source§

fn deref(&self) -> &Methods

Dereferences the value.
source§

impl<Context> DerefMut for RpcModule<Context>

source§

fn deref_mut(&mut self) -> &mut Methods

Mutably dereferences the value.
source§

impl<Context> From<RpcModule<Context>> for Methods

source§

fn from(module: RpcModule<Context>) -> Methods

Converts to this type from the input type.

Auto Trait Implementations§

§

impl<Context> Freeze for RpcModule<Context>

§

impl<Context> !RefUnwindSafe for RpcModule<Context>

§

impl<Context> Send for RpcModule<Context>
where Context: Sync + Send,

§

impl<Context> Sync for RpcModule<Context>
where Context: Sync + Send,

§

impl<Context> Unpin for RpcModule<Context>

§

impl<Context> !UnwindSafe for RpcModule<Context>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

default unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> Same for T

§

type Output = T

Should always be Self
source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> MaybeSend for T
where T: Send,