Struct jsonrpsee_http_server::RpcModule

pub struct RpcModule<Context> { /* fields omitted */ }

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

impl<Context> RpcModule<Context>

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

Create a new module with a given shared Context.

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

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

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, 

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

pub fn register_blocking_method<R, F>(
    &mut self,
    method_name: &'static str,
    callback: F
) -> Result<MethodResourcesBuilder<'_>, Error> where
    Context: 'static + Send + Sync,
    R: Serialize,
    F: 'static + Fn(Params<'_>, Arc<Context>) -> Result<R, Error> + Copy + Send + Sync, 

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, 

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 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_utils::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(())
});

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

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

Methods from Deref<Target = Methods>

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

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

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

Returns the method callback.

pub fn execute(
    &self,
    tx: &UnboundedSender<String>,
    req: Request<'_>,
    conn_id: usize,
    max_response_size: u32
) -> Option<Pin<Box<dyn Future<Output = ()> + Send + 'static, Global>>>

Attempt to execute a callback, sending the resulting JSON (success or error) to the specified sink.

pub fn execute_with_resources(
    &self,
    tx: &UnboundedSender<String>,
    req: Request<'_>,
    conn_id: usize,
    resources: &Resources,
    max_response_size: u32
) -> Option<Pin<Box<dyn Future<Output = ()> + Send + 'static, Global>>>

Attempt to execute a callback while checking that the call does not exhaust the available resources, sending the resulting JSON (success or error) to the specified sink.

pub async fn call_with<Params>(
    &'_ self,
    method: &'_ str,
    params: Params
) -> Option<String> where
    Params: ToRpcParams, 

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.

pub async fn call(
    &'_ self,
    method: &'_ str,
    params: Option<Box<RawValue, Global>>
) -> Option<String>

Helper alternative to execute, useful for writing unit tests without having to spin a server up.

pub async fn test_subscription(
    &'_ self,
    method: &'_ str,
    params: impl ToRpcParams
) -> TestSubscription

Test helper that sets up a subscription using the given method. Returns a tuple of the SubscriptionId and a channel on which subscription JSON payloads can be received.

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

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

Trait Implementations

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

impl<Context> Deref for RpcModule<Context>

type Target = Methods

The resulting type after dereferencing.

pub fn deref(&self) -> &Methods

Dereferences the value.

impl<Context> DerefMut for RpcModule<Context>

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

Mutably dereferences the value.

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

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

Performs the conversion.