alloy_rpc_client/
builder.rs

1use crate::{BuiltInConnectionString, RpcClient};
2use alloy_transport::{BoxTransport, IntoBoxTransport, TransportConnect, TransportResult};
3use tower::{
4    layer::util::{Identity, Stack},
5    Layer, ServiceBuilder,
6};
7
8/// A builder for the transport  [`RpcClient`].
9///
10/// This is a wrapper around [`tower::ServiceBuilder`]. It allows you to
11/// configure middleware layers that will be applied to the transport, and has
12/// some shortcuts for common layers and transports.
13///
14/// A builder accumulates Layers, and then is finished via the
15/// [`ClientBuilder::connect`] method, which produces an RPC client.
16#[derive(Debug)]
17pub struct ClientBuilder<L> {
18    pub(crate) builder: ServiceBuilder<L>,
19}
20
21impl Default for ClientBuilder<Identity> {
22    fn default() -> Self {
23        Self { builder: ServiceBuilder::new() }
24    }
25}
26
27impl<L> ClientBuilder<L> {
28    /// Add a middleware layer to the stack.
29    ///
30    /// This is a wrapper around [`tower::ServiceBuilder::layer`]. Layers that
31    /// are added first will be called with the request first.
32    pub fn layer<M>(self, layer: M) -> ClientBuilder<Stack<M, L>> {
33        ClientBuilder { builder: self.builder.layer(layer) }
34    }
35
36    /// Create a new [`RpcClient`] with the given transport and the configured
37    /// layers.
38    ///
39    /// This collapses the [`tower::ServiceBuilder`] with the given transport via
40    /// [`tower::ServiceBuilder::service`].
41    pub fn transport<T>(self, transport: T, is_local: bool) -> RpcClient
42    where
43        L: Layer<T>,
44        T: IntoBoxTransport,
45        L::Service: IntoBoxTransport,
46    {
47        RpcClient::new_layered(is_local, transport, move |t| self.builder.service(t))
48    }
49
50    /// Convenience function to create a new [`RpcClient`] with a [`reqwest`]
51    /// HTTP transport.
52    #[cfg(feature = "reqwest")]
53    pub fn http(self, url: url::Url) -> RpcClient
54    where
55        L: Layer<alloy_transport_http::Http<reqwest::Client>>,
56        L::Service: IntoBoxTransport,
57    {
58        let transport = alloy_transport_http::Http::new(url);
59        let is_local = transport.guess_local();
60
61        self.transport(transport, is_local)
62    }
63
64    /// Convenience function to create a new [`RpcClient`] with a `hyper` HTTP transport.
65    #[cfg(all(not(target_family = "wasm"), feature = "hyper"))]
66    pub fn hyper_http(self, url: url::Url) -> RpcClient
67    where
68        L: Layer<alloy_transport_http::HyperTransport>,
69        L::Service: IntoBoxTransport,
70    {
71        let transport = alloy_transport_http::HyperTransport::new_hyper(url);
72        let is_local = transport.guess_local();
73
74        self.transport(transport, is_local)
75    }
76
77    /// Connect a pubsub transport, producing an [`RpcClient`] with the provided
78    /// connection.
79    #[cfg(feature = "pubsub")]
80    pub async fn pubsub<C>(self, pubsub_connect: C) -> TransportResult<RpcClient>
81    where
82        C: alloy_pubsub::PubSubConnect,
83        L: Layer<alloy_pubsub::PubSubFrontend>,
84        L::Service: IntoBoxTransport,
85    {
86        let is_local = pubsub_connect.is_local();
87        let transport = pubsub_connect.into_service().await?;
88        Ok(self.transport(transport, is_local))
89    }
90
91    /// Connect a WS transport, producing an [`RpcClient`] with the provided
92    /// connection.
93    #[cfg(feature = "ws")]
94    pub async fn ws(self, ws_connect: alloy_transport_ws::WsConnect) -> TransportResult<RpcClient>
95    where
96        L: Layer<alloy_pubsub::PubSubFrontend>,
97        L::Service: IntoBoxTransport,
98    {
99        self.pubsub(ws_connect).await
100    }
101
102    /// Connect an IPC transport, producing an [`RpcClient`] with the provided
103    /// connection.
104    #[cfg(feature = "ipc")]
105    pub async fn ipc<T>(
106        self,
107        ipc_connect: alloy_transport_ipc::IpcConnect<T>,
108    ) -> TransportResult<RpcClient>
109    where
110        alloy_transport_ipc::IpcConnect<T>: alloy_pubsub::PubSubConnect,
111        L: Layer<alloy_pubsub::PubSubFrontend>,
112        L::Service: IntoBoxTransport,
113    {
114        self.pubsub(ipc_connect).await
115    }
116
117    /// Connect a transport specified by the given string, producing an [`RpcClient`].
118    ///
119    /// See [`BuiltInConnectionString`] for more information.
120    pub async fn connect(self, s: &str) -> TransportResult<RpcClient>
121    where
122        L: Layer<BoxTransport>,
123        L::Service: IntoBoxTransport,
124    {
125        self.connect_with(s.parse::<BuiltInConnectionString>()?).await
126    }
127
128    /// Connect a transport, producing an [`RpcClient`].
129    pub async fn connect_with<C>(self, connect: C) -> TransportResult<RpcClient>
130    where
131        C: TransportConnect,
132        L: Layer<BoxTransport>,
133        L::Service: IntoBoxTransport,
134    {
135        let transport = connect.get_transport().await?;
136        Ok(self.transport(transport, connect.is_local()))
137    }
138
139    /// Connect a transport, producing an [`RpcClient`] with a [`BoxTransport`]
140    /// connection.
141    #[deprecated(
142        since = "0.9.0",
143        note = "RpcClient is now always boxed, use `connect_with` instead"
144    )]
145    pub async fn connect_boxed<C>(self, connect: C) -> TransportResult<RpcClient>
146    where
147        C: TransportConnect,
148        L: Layer<BoxTransport>,
149        L::Service: IntoBoxTransport,
150    {
151        self.connect_with(connect).await
152    }
153}
alloy_rpc_client/builder.rs

alloy_rpc_client/
builder.rs
