Allow generalising over RPC implementation (#634)

* WIP generalising RPC client * WIP: non-object-safe RpcClientT.. aah generics everywhere * WIP object-safe RpcClientT trait and no more extra generics * Get core things compiling again with object-safe RpcClientT trait * Make jsonrpsee optional and get test-runtime working again * cargo fmt * add RpcParams object to enforce correct formatting of rps params * Wee tweaks * clippy fixes * cargo fmt * TWeak a few types * make sure we get jsonrpsee-types, too * Add examples for rpc_params/RpcParams * more doc tweaks * remove a now unneeded dev note * Option<Box<RawValue>> instead to avoid allocations in some cases * update docs * tweak RpcClientT trait docs * Tweak docs around RpcClient and RpcClientT. Don't expose RpcClientT directly * more doc tweaking about RpcParams and undo decision not to expose RpcParamsT * Doc tweak Co-authored-by: Alexandru Vasile <60601340+lexnv@users.noreply.github.com> * more doc tweaks * Fix doc thing * Add an example of injecting a custom RPC client * Fix a typo * Address clippy things in example * Fix a silly typo * another clippy fix * rpc_params to panic instead of returning a result, like serde_json::json, and deref on Rpc<T> * fix docs Co-authored-by: Alexandru Vasile <60601340+lexnv@users.noreply.github.com>
2026-06-14 04:01:10 +00:00 · 2022-08-31 10:00:49 +01:00
parent 5ff849318b
commit 599107b432
17 changed files with 737 additions and 143 deletions
@@ -0,0 +1,59 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+use crate::error::RpcError;
+use futures::Stream;
+use std::{
+    future::Future,
+    pin::Pin,
+};
+
+// Re-exporting for simplicity since it's used a bunch in the trait definition.
+pub use serde_json::value::RawValue;
+
+/// Any RPC client which implements this can be used in our [`super::Rpc`] type
+/// to talk to a node.
+///
+/// This is a low level interface whose methods expect an already-serialized set of params,
+/// and return an owned but still-serialized [`RawValue`], deferring deserialization to
+/// the caller. This is the case because we want the methods to be object-safe (which prohibits
+/// generics), and want to avoid any unnecessary allocations in serializing/deserializing
+/// parameters.
+pub trait RpcClientT: Send + Sync + 'static {
+    /// Make a raw request for which we expect a single response back from. Implementations
+    /// should expect that the params will either be `None`, or be an already-serialized
+    /// JSON array of parameters.
+    ///
+    /// See [`super::RpcParams`] and the [`super::rpc_params!`] macro for an example of how to
+    /// construct the parameters.
+    ///
+    /// Prefer to use the interface provided on [`super::RpcClient`] where possible.
+    fn request_raw<'a>(
+        &'a self,
+        method: &'a str,
+        params: Option<Box<RawValue>>,
+    ) -> RpcFuture<'a, Box<RawValue>>;
+
+    /// Subscribe to some method. Implementations should expect that the params will
+    /// either be `None`, or be an already-serialized JSON array of parameters.
+    ///
+    /// See [`super::RpcParams`] and the [`super::rpc_params!`] macro for an example of how to
+    /// construct the parameters.
+    ///
+    /// Prefer to use the interface provided on [`super::RpcClient`] where possible.
+    fn subscribe_raw<'a>(
+        &'a self,
+        sub: &'a str,
+        params: Option<Box<RawValue>>,
+        unsub: &'a str,
+    ) -> RpcFuture<'a, RpcSubscription>;
+}
+
+/// A boxed future that is returned from the [`RpcClientT`] methods.
+pub type RpcFuture<'a, T> =
+    Pin<Box<dyn Future<Output = Result<T, RpcError>> + Send + 'a>>;
+
+/// The inner subscription stream returned from our [`RpcClientT`]'s `subscription` method.
+pub type RpcSubscription =
+    Pin<Box<dyn Stream<Item = Result<Box<RawValue>, RpcError>> + Send + 'static>>;