witty_jsonrpc/transports/
mod.rs

1use jsonrpc_ws_server::tokio;
2use std::{
3    fmt,
4    sync::{Arc, Mutex},
5};
6
7use crate::handler::Handler;
8
9/// A JSON-RPC over HTTP transport built around the `jsonrpc_http_server` library.
10#[cfg(feature = "http")]
11pub mod http;
12/// A JSON-RPC over TCP transport built around the `jsonrpc_tcp_server` library.
13#[cfg(feature = "tcp")]
14pub mod tcp;
15/// A JSON-RPC over WebSockets transport built around the `jsonrpc_ws_server` library.
16#[cfg(feature = "ws")]
17pub mod ws;
18
19/// Enumerates all the different errors that a `Transport` can get into.
20#[derive(Debug)]
21pub enum TransportError {
22    /// An IP or address cannot be parsed.
23    Address(std::net::AddrParseError),
24    /// An IO error.
25    IO(std::io::Error),
26    /// Some operation requires an IO handler, but none is configured yet.
27    NoHandler,
28    /// An unknown error.
29    Unknown,
30    /// An error that is specific to WebSockets.
31    #[cfg(feature = "ws")]
32    WebSockets(Box<crate::transports::ws::Error>),
33}
34
35impl std::error::Error for TransportError {}
36
37impl fmt::Display for TransportError {
38    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
39        match self {
40            TransportError::Address(error) => {
41                write!(f, "{}", error)
42            }
43            TransportError::IO(error) => {
44                write!(f, "{}", error)
45            }
46            TransportError::NoHandler => {
47                write!(
48                    f,
49                    "The operation requires an IO handler, but none is configured yet."
50                )
51            }
52            TransportError::Unknown => {
53                write!(f, "Unknown error.")
54            }
55            #[cfg(feature = "ws")]
56            TransportError::WebSockets(error) => {
57                write!(f, "{}", error)
58            }
59        }
60    }
61}
62
63impl From<std::io::Error> for TransportError {
64    fn from(value: std::io::Error) -> Self {
65        Self::IO(value)
66    }
67}
68
69impl From<std::net::AddrParseError> for TransportError {
70    fn from(value: std::net::AddrParseError) -> Self {
71        Self::Address(value)
72    }
73}
74
75#[cfg(feature = "ws")]
76impl From<crate::transports::ws::Error> for TransportError {
77    fn from(value: crate::transports::ws::Error) -> Self {
78        match value {
79            crate::transports::ws::Error::Io(e) => Self::IO(e),
80            e => Self::WebSockets(Box::new(e)),
81        }
82    }
83}
84
85/// Generically defines message transports that can be used with JSON-RPC servers.
86pub trait Transport<H>
87where
88    H: Handler,
89{
90    /// Tell whether this transport requires reconfiguration if the IO handler of the server is
91    /// changed.
92    ///
93    /// That is the case for those transports that use a server builder behind the scenes, because
94    /// they cannot leverage the `Arc` around the IO handler of the parent JSON-RPC server.
95    fn requires_reset(&self) -> bool;
96    /// Tell whether the transport is listening or not.
97    fn running(&self) -> bool;
98    /// Set the IO handler that the transport will use to process the JSON-RPC messages it receives.
99    fn set_handler(
100        &mut self,
101        handler: Arc<Mutex<H>>,
102        runtime: Option<tokio::runtime::Handle>,
103    ) -> Result<(), TransportError>;
104    /// Start the transport.
105    ///
106    /// Most often, this will start message listeners, network sockets, and the like.
107    fn start(&mut self) -> Result<(), TransportError>;
108    /// Stop the transport.
109    ///
110    /// Stopping a transport is assumed to also stop any underlying listeners and sockets, and to
111    /// completely halt the processing of further JSON-RPC messages.
112    fn stop(&mut self) -> Result<(), TransportError>;
113}
witty_jsonrpc/transports/mod.rs

witty_jsonrpc/transports/
mod.rs
