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

Create a new module with a given shared Context.

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

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

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.

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 subscriptionID 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.
    • 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, SubscriptionSink};
use jsonrpsee_core::Error;

let mut ctx = RpcModule::new(99_usize);
ctx.register_subscription("sub", "notif_name", "unsub", |params, mut sink, ctx| {
    let x = match params.one::<usize>() {
        Ok(x) => x,
        Err(e) => {
            let err: Error = e.into();
            sink.reject(err);
            return Ok(());
        }
    };
    // Sink is accepted on the first `send` call.
    std::thread::spawn(move || {
        let sum = x + (*ctx);
        let _ = sink.send(&sum);
    });

    Ok(())
});

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

Methods from Deref<Target = Methods>

Merge two Methods’s by adding all MethodCallbacks 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.

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

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

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

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

Mutably dereferences the value.

Converts to this type from the input type.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

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

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

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

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

Calls U::from(self).

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

The resulting type after obtaining ownership.

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

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

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

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

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