Skip to main content

arti/
rpc.rs

1//! Experimental RPC support.
2
3use anyhow::Result;
4use arti_rpcserver::RpcMgr;
5use derive_deftly::Deftly;
6use fs_mistrust::Mistrust;
7use futures::{AsyncReadExt, stream::StreamExt};
8use session::ArtiRpcSession;
9use std::collections::BTreeMap;
10use std::{io::Result as IoResult, sync::Arc};
11use tor_config::derive::prelude::*;
12use tor_config_path::CfgPathResolver;
13use tracing::{debug, info};
14
15use arti_client::TorClient;
16use tor_rtcompat::{NetStreamListener as _, Runtime, SpawnExt, general};
17
18semipublic_mod! { pub(crate) mod configuration; }
19pub(crate) mod conntarget;
20mod geoip;
21pub(crate) mod listener;
22mod proxyinfo;
23mod session;
24mod superuser;
25
26pub(crate) use configuration::{ConfigSettings, ConfigValue};
27use listener::RpcListenerSetConfig;
28pub(crate) use session::{RpcStateSender, RpcVisibleArtiState};
29
30use crate::reload_cfg::{CfgMgr, LaunchableTorClient};
31use crate::rpc::superuser::RpcSuperuser;
32
33/// Configuration for Arti's RPC subsystem.
34///
35/// You cannot change this section on a running Arti client.
36#[derive(Debug, Clone, Deftly, Eq, PartialEq)]
37#[derive_deftly(TorConfig)]
38#[cfg_attr(feature = "experimental-api", visibility::make(pub))]
39#[cfg_attr(feature = "experimental-api", deftly(tor_config(vis = pub)))]
40pub(crate) struct RpcConfig {
41    /// If true, then the RPC subsystem is enabled and will listen for connections.
42    #[deftly(tor_config(default = false))] // TODO RPC make this true once we are stable.
43    enable: bool,
44
45    /// A set of named locations in which to find connect files.
46    #[deftly(tor_config(map, default = listener::listener_map_defaults()))]
47    listen: BTreeMap<String, RpcListenerSetConfig>,
48
49    /// A list of default connect points to bind
50    /// if no enabled connect points are found under `listen`.
51    #[deftly(tor_config(list(element(clone)), default = listen_defaults_defaults()))]
52    listen_default: Vec<String>,
53}
54
55/// Return default values for `RpcConfig.listen_default`
56fn listen_defaults_defaults() -> Vec<String> {
57    vec![tor_rpc_connect::USER_DEFAULT_CONNECT_POINT.to_string()]
58}
59
60/// Information about an incoming connection.
61///
62/// Yielded in a stream from our RPC listeners.
63type IncomingConn = (
64    general::Stream,
65    general::SocketAddr,
66    Arc<listener::RpcConnInfo>,
67);
68
69/// Bind to all configured RPC listeners in `cfg`.
70///
71/// On success, return a stream of `IncomingConn`.
72async fn launch_all_listeners<R: Runtime>(
73    runtime: &R,
74    cfg: &RpcConfig,
75    resolver: &CfgPathResolver,
76    mistrust: &Mistrust,
77) -> anyhow::Result<(
78    impl futures::Stream<Item = IoResult<IncomingConn>> + Unpin + use<R>,
79    Vec<tor_rpc_connect::server::ListenerGuard>,
80)> {
81    let mut listeners = Vec::new();
82    let mut guards = Vec::new();
83    for (name, listener_cfg) in cfg.listen.iter() {
84        for (lis, info, guard) in listener_cfg
85            .bind(runtime, name.as_str(), resolver, mistrust)
86            .await?
87        {
88            // (Note that `bind` only returns enabled listeners, so we don't need to check here.
89            debug!(
90                "Listening at {} for {}",
91                lis.local_addr()
92                    .expect("general::listener without address?")
93                    .display_lossy(),
94                info.name,
95            );
96            listeners.push((lis, info));
97            guards.push(guard);
98        }
99    }
100    if listeners.is_empty() {
101        for (idx, connpt) in cfg.listen_default.iter().enumerate() {
102            let display_index = idx + 1; // One-indexed values are more human-readable.
103            let (lis, info, guard) =
104                listener::bind_string(connpt, display_index, runtime, resolver, mistrust).await?;
105            debug!(
106                "Listening at {} for {}",
107                lis.local_addr()
108                    .expect("general::listener without address?")
109                    .display_lossy(),
110                info.name,
111            );
112            listeners.push((lis, info));
113            guards.push(guard);
114        }
115    }
116    if listeners.is_empty() {
117        info!("No RPC listeners configured.");
118    }
119
120    let streams = listeners.into_iter().map(|(listener, info)| {
121        listener
122            .incoming()
123            .map(move |accept_result| match accept_result {
124                Ok((netstream, addr)) => Ok((netstream, addr, Arc::clone(&info))),
125                Err(e) => Err(e),
126            })
127    });
128
129    Ok((futures::stream::select_all(streams), guards))
130}
131
132/// Create an RPC manager, bind to connect points, and open a listener task to accept incoming
133/// RPC connections.
134pub(crate) async fn launch_rpc_mgr<R: Runtime>(
135    runtime: &R,
136    cfg: &RpcConfig,
137    resolver: &CfgPathResolver,
138    mistrust: &Mistrust,
139    client: Arc<TorClient<R>>,
140    launchable: Arc<LaunchableTorClient<R>>,
141    cfg_mgr: Arc<CfgMgr<R>>,
142) -> Result<Option<RpcProxySupport>> {
143    if !cfg.enable {
144        return Ok(None);
145    }
146    let (rpc_state, rpc_state_sender) = RpcVisibleArtiState::new();
147
148    let rpc_mgr = RpcMgr::new()?;
149    // Register methods. Needed since TorClient is generic.
150    //
151    // TODO: If we accumulate a large number of generics like this, we should do this elsewhere.
152    rpc_mgr.register_rpc_methods(TorClient::<R>::rpc_methods());
153    rpc_mgr.register_rpc_methods(arti_rpcserver::rpc_methods::<R>());
154    rpc_mgr.register_rpc_methods(RpcSuperuser::<R>::rpc_methods());
155
156    let rt_clone = runtime.clone();
157    let rpc_mgr_clone = rpc_mgr.clone();
158
159    let (incoming, guards) = launch_all_listeners(runtime, cfg, resolver, mistrust).await?;
160
161    // TODO: Using spawn in this way makes it hard to report whether we
162    // succeeded or not. This is something we should fix when we refactor
163    // our service-launching code.
164    runtime.spawn(async move {
165        let result = run_rpc_listener(
166            rt_clone,
167            incoming,
168            rpc_mgr_clone,
169            client,
170            launchable,
171            cfg_mgr,
172            rpc_state,
173        )
174        .await;
175        if let Err(e) = result {
176            tracing::warn!("RPC manager quit with an error: {}", e);
177        }
178        drop(guards);
179    })?;
180    Ok(Some(RpcProxySupport {
181        rpc_mgr,
182        rpc_state_sender,
183    }))
184}
185
186/// Backend function to implement an RPC listener: runs in a loop.
187async fn run_rpc_listener<R: Runtime>(
188    runtime: R,
189    mut incoming: impl futures::Stream<Item = IoResult<IncomingConn>> + Unpin,
190    rpc_mgr: Arc<RpcMgr>,
191    client: Arc<TorClient<R>>,
192    launchable: Arc<LaunchableTorClient<R>>,
193    cfg_mgr: Arc<CfgMgr<R>>,
194    rpc_state: Arc<RpcVisibleArtiState>,
195) -> Result<()> {
196    while let Some((stream, _addr, info)) = incoming.next().await.transpose()? {
197        debug!("Received incoming RPC connection from {}", &info.name);
198
199        let client_clone = client.clone();
200        let rpc_state_clone = rpc_state.clone();
201        let launchable = launchable.clone();
202        let cfg_mgr_clone = cfg_mgr.clone();
203        let connection = rpc_mgr.new_connection(info.auth.clone(), move |auth| {
204            ArtiRpcSession::new(
205                auth,
206                &client_clone,
207                &launchable,
208                &rpc_state_clone,
209                &cfg_mgr_clone,
210                &info,
211            ) as _
212        });
213        let (input, output) = stream.split();
214
215        runtime.spawn(async {
216            let result = connection.run(input, output).await;
217            if let Err(e) = result {
218                tracing::warn!("RPC session ended with an error: {}", e);
219            }
220        })?;
221    }
222    Ok(())
223}
224
225/// Information passed to a proxy or similar stream provider when running with RPC support.
226pub(crate) struct RpcProxySupport {
227    /// An RPC manager to use for looking up objects as possible stream targets.
228    pub(crate) rpc_mgr: Arc<arti_rpcserver::RpcMgr>,
229    /// An RPCStateSender to use for registering the list of known proxy ports.
230    pub(crate) rpc_state_sender: RpcStateSender,
231}
232
233#[cfg(test)]
234mod test {
235    // @@ begin test lint list maintained by maint/add_warning @@
236    #![allow(clippy::bool_assert_comparison)]
237    #![allow(clippy::clone_on_copy)]
238    #![allow(clippy::dbg_macro)]
239    #![allow(clippy::mixed_attributes_style)]
240    #![allow(clippy::print_stderr)]
241    #![allow(clippy::print_stdout)]
242    #![allow(clippy::single_char_pattern)]
243    #![allow(clippy::unwrap_used)]
244    #![allow(clippy::unchecked_time_subtraction)]
245    #![allow(clippy::useless_vec)]
246    #![allow(clippy::needless_pass_by_value)]
247    #![allow(clippy::string_slice)] // See arti#2571
248    //! <!-- @@ end test lint list maintained by maint/add_warning @@ -->
249
250    use listener::{ConnectPointOptionsBuilder, RpcListenerSetConfigBuilder};
251    use tor_config_path::CfgPath;
252    use tor_rpc_connect::ParsedConnectPoint;
253
254    use super::*;
255
256    #[test]
257    fn rpc_method_names() {
258        // We run this from a nice high level module, to ensure that as many method names as
259        // possible will be in-scope.
260        let problems = tor_rpcbase::check_method_names([]);
261
262        for (m, err) in &problems {
263            eprintln!("Bad method name {m:?}: {err}");
264        }
265        assert!(problems.is_empty());
266    }
267
268    #[test]
269    fn parse_listener_defaults() {
270        for string in listen_defaults_defaults() {
271            let _parsed: ParsedConnectPoint = string.parse().unwrap();
272        }
273    }
274
275    #[test]
276    fn parsing_and_building() {
277        fn build(s: &str) -> Result<RpcConfig, anyhow::Error> {
278            let b: RpcConfigBuilder = toml::from_str(s)?;
279            Ok(b.build()?)
280        }
281
282        let mut user_defaults_builder = RpcListenerSetConfigBuilder::default();
283        user_defaults_builder.listener_options().enable(true);
284        user_defaults_builder.dir(CfgPath::new("${ARTI_LOCAL_DATA}/rpc/connect.d".to_string()));
285        let mut system_defaults_builder = RpcListenerSetConfigBuilder::default();
286        system_defaults_builder.listener_options().enable(false);
287        system_defaults_builder.dir(CfgPath::new("/etc/arti-rpc/connect.d".to_string()));
288
289        // Make sure that an empty configuration gets us the defaults.
290        let defaults = build("").unwrap();
291        assert_eq!(
292            defaults,
293            RpcConfig {
294                enable: false,
295                listen: vec![
296                    (
297                        "user-default".to_string(),
298                        user_defaults_builder.build().unwrap()
299                    ),
300                    (
301                        "system-default".to_string(),
302                        system_defaults_builder.build().unwrap()
303                    ),
304                ]
305                .into_iter()
306                .collect(),
307                listen_default: listen_defaults_defaults()
308            }
309        );
310
311        // Make sure that overriding specific options works as expected.
312        let altered = build(
313            r#"
314[listen."user-default"]
315enable = false
316[listen."system-default"]
317dir = "/usr/local/etc/arti-rpc/connect.d"
318file_options = { "tmp.toml" = { "enable" = false } }
319[listen."my-connpt"]
320file = "/home/dante/.paradiso/connpt.toml"
321"#,
322        )
323        .unwrap();
324        let mut altered_user_defaults = user_defaults_builder.clone();
325        altered_user_defaults.listener_options().enable(false);
326        let mut altered_system_defaults = system_defaults_builder.clone();
327        altered_system_defaults.dir(CfgPath::new(
328            "/usr/local/etc/arti-rpc/connect.d".to_string(),
329        ));
330        let mut opt = ConnectPointOptionsBuilder::default();
331        opt.enable(false);
332        altered_system_defaults
333            .file_options()
334            .insert("tmp.toml".to_string(), opt);
335        let mut my_connpt = RpcListenerSetConfigBuilder::default();
336        my_connpt.file(CfgPath::new(
337            "/home/dante/.paradiso/connpt.toml".to_string(),
338        ));
339
340        assert_eq!(
341            altered,
342            RpcConfig {
343                enable: false,
344                listen: vec![
345                    (
346                        "user-default".to_string(),
347                        altered_user_defaults.build().unwrap()
348                    ),
349                    (
350                        "system-default".to_string(),
351                        altered_system_defaults.build().unwrap()
352                    ),
353                    ("my-connpt".to_string(), my_connpt.build().unwrap()),
354                ]
355                .into_iter()
356                .collect(),
357                listen_default: listen_defaults_defaults()
358            }
359        );
360    }
361}