Skip to main content

tor_proto/circuit/reactor/
hop_mgr.rs

1//! Channel for sending messages to [`StreamReactor`].
2
3use crate::circuit::UniqId;
4use crate::circuit::circhop::{CircHopOutbound, HopSettings};
5use crate::circuit::reactor::circhop::CircHopList;
6use crate::circuit::reactor::stream::{CtrlMsg, ReadyStreamMsg, StreamHandler, StreamReactor};
7use crate::congestion::CongestionControl;
8use crate::memquota::CircuitAccount;
9use crate::util::err::ReactorError;
10use crate::{Error, HopNum, Result};
11
12#[cfg(any(feature = "hs-service", feature = "relay"))]
13use {
14    crate::stream::CloseStreamBehavior, crate::stream::incoming::IncomingStreamRequestHandler,
15    tor_cell::relaycell::StreamId,
16};
17
18use tor_cell::chancell::CircId;
19use tor_error::internal;
20use tor_rtcompat::Runtime;
21
22use futures::SinkExt;
23use futures::channel::mpsc;
24
25use std::result::Result as StdResult;
26use std::sync::{Arc, Mutex, RwLock};
27
28/// The hop manager of a reactor.
29///
30/// This contains the per-hop state (e.g. congestion control information),
31/// and a handle to the stream reactor of the hop.
32///
33/// The stream reactor of the hop is launched lazily,
34/// when the first [`CtrlMsg`] is sent via [`HopMgr::send`].
35pub(crate) struct HopMgr<R: Runtime> {
36    /// A handle to the runtime.
37    runtime: R,
38    /// Context used when spawning a stream reactor.
39    ctx: StreamReactorContext,
40    /// Sender for sending messages to BWD.
41    ///
42    /// The receiver is in BWD.
43    ///
44    /// A clone of this is passed to each spawned StreamReactor
45    bwd_tx: mpsc::Sender<ReadyStreamMsg>,
46    /// The underlying senders, indexed by [`HopNum`].
47    ///
48    /// Relays have at most one stream reactor per circuit.
49    /// Clients have at most one stream reactor per circuit hop.
50    ///
51    /// This is shared with the backward reactor.
52    /// The backward reactor only ever *reads* from this
53    /// (it never mutates the list).
54    ///
55    // TODO: the backward reactor only ever reads from this.
56    // Conceptually, it is the HopMgr that owns this list,
57    // because only HopMgr can add hops to the list.
58    //
59    // Perhaps we need a specialized abstraction that only allows reading here.
60    // This could be a wrapper over RwLock, providing a read-only API for the BWD.
61    hops: Arc<RwLock<CircHopList>>,
62    /// Memory quota account
63    memquota: CircuitAccount,
64}
65
66/// State needed to build a stream reactor.
67///
68/// Used when spawning the stream reactor of a hop.
69struct StreamReactorContext {
70    /// An identifier for logging about this reactor's circuit.
71    unique_id: UniqId,
72    /// The circuit identifier on the inbound Tor channel.
73    circ_id: CircId,
74    /// The incoming stream handler.
75    ///
76    /// This is shared with every StreamReactor.
77    #[cfg(any(feature = "hs-service", feature = "relay"))]
78    incoming: Arc<Mutex<Option<IncomingStreamRequestHandler>>>,
79    /// A handler for customizing the stream reactor behavior.
80    handler: Arc<dyn StreamHandler>,
81}
82
83impl<R: Runtime> HopMgr<R> {
84    /// Create a new [`HopMgr`] consisting of a single CircHop
85    /// (built using the specified `settings),
86    /// setting the incoming stream request handler to `incoming_handler`.
87    #[cfg(feature = "relay")]
88    #[allow(clippy::too_many_arguments)] // this is an internal function with 1 call site
89    pub(crate) fn new_relay<S: StreamHandler>(
90        runtime: R,
91        settings: HopSettings,
92        unique_id: UniqId,
93        circ_id: CircId,
94        handler: S,
95        bwd_tx: mpsc::Sender<ReadyStreamMsg>,
96        incoming_handler: IncomingStreamRequestHandler,
97        memquota: CircuitAccount,
98    ) -> Self {
99        let hops = CircHopList::new_relay(settings);
100
101        Self::new_inner(
102            runtime,
103            hops,
104            unique_id,
105            circ_id,
106            handler,
107            bwd_tx,
108            Some(incoming_handler),
109            memquota,
110        )
111    }
112
113    /// Create a new [`HopMgr`] with an empty hop list.
114    ///
115    /// Hops are added with [`HopMgr::add_hop`].
116    #[expect(unused)] // TODO(dedup): clients will use this
117    pub(crate) fn new_client<S: StreamHandler>(
118        runtime: R,
119        unique_id: UniqId,
120        circ_id: CircId,
121        handler: S,
122        bwd_tx: mpsc::Sender<ReadyStreamMsg>,
123        memquota: CircuitAccount,
124    ) -> Self {
125        let hops = CircHopList::new_client();
126        Self::new_inner(
127            runtime,
128            hops,
129            unique_id,
130            circ_id,
131            handler,
132            bwd_tx,
133            #[cfg(any(feature = "hs-service", feature = "relay"))]
134            None,
135            memquota,
136        )
137    }
138
139    /// Helper for the new*() functions.
140    #[allow(clippy::too_many_arguments)] // this is an internal function with 2 call sites
141    fn new_inner<S: StreamHandler>(
142        runtime: R,
143        hops: CircHopList,
144        unique_id: UniqId,
145        circ_id: CircId,
146        handler: S,
147        bwd_tx: mpsc::Sender<ReadyStreamMsg>,
148        #[cfg(any(feature = "hs-service", feature = "relay"))] incoming_handler: Option<
149            IncomingStreamRequestHandler,
150        >,
151        memquota: CircuitAccount,
152    ) -> Self {
153        let hops = Arc::new(RwLock::new(hops));
154        let ctx = StreamReactorContext {
155            unique_id,
156            circ_id,
157            #[cfg(any(feature = "hs-service", feature = "relay"))]
158            incoming: Arc::new(Mutex::new(incoming_handler)),
159            handler: Arc::new(handler),
160        };
161
162        Self {
163            runtime,
164            hops,
165            ctx,
166            bwd_tx,
167            memquota,
168        }
169    }
170
171    /// Return a reference to our hop list.
172    pub(crate) fn hops(&self) -> &Arc<RwLock<CircHopList>> {
173        &self.hops
174    }
175
176    /// Set the incoming stream handler for this reactor.
177    ///
178    /// There can only be one incoming stream handler per reactor,
179    /// and each stream handler only pertains to a single hop (see expected_hop())
180    //
181    // TODO: eventually, we might want a different design here,
182    // for example we might want to allow multiple stream handlers per reactor (one per hop).
183    // However, for now, the implementation is intentionally kept similar to that
184    // in the client reactor (to make it easier to migrate it to the new reactor design).
185    //
186    /// Returns an error if the hop manager already has a stream handler.
187    ///
188    /// Since the handler is shared with every hop's stream reactor,
189    /// this function will update the handler for all of them.
190    ///
191    // TODO(DEDUP): almost identical to the client-side
192    // CellHandlers::set_incoming_stream_req_handler()
193    #[cfg(any(feature = "hs-service", feature = "relay"))]
194    pub(crate) fn set_incoming_handler(&self, handler: IncomingStreamRequestHandler) -> Result<()> {
195        let mut lock = self.ctx.incoming.lock().expect("poisoned lock");
196
197        if lock.is_none() {
198            *lock = Some(handler);
199            Ok(())
200        } else {
201            Err(Error::from(internal!(
202                "Tried to install a BEGIN cell handler before the old one was gone."
203            )))
204        }
205    }
206
207    /// Push a new hop to our hop list.
208    ///
209    /// Prepares a cc object for the hop, but does not spawn a stream reactor.
210    ///
211    /// Will return an error if the circuit already has [`u8::MAX`] hops.
212    #[expect(unused)] // TODO(dedup): clients will use this
213    pub(crate) fn add_hop(&mut self, settings: HopSettings) -> Result<()> {
214        let mut hops = self.hops.write().expect("poisoned lock");
215        hops.add_hop(settings)
216    }
217
218    /// Send a message to the stream reactor of the specified `hop`,
219    /// spawning it if necessary.
220    pub(crate) async fn send(
221        &mut self,
222        hopnum: Option<HopNum>,
223        msg: CtrlMsg,
224    ) -> StdResult<(), ReactorError> {
225        let mut tx = self.get_or_spawn_stream_reactor(hopnum)?;
226
227        tx.send(msg).await.map_err(|_| {
228            // The stream reactor has shut down
229            ReactorError::Shutdown
230        })
231    }
232
233    /// Tell the stream reactor of the specified `hop`
234    /// to close the stream with the specified `stream_id`.
235    #[cfg(any(feature = "hs-service", feature = "relay"))]
236    pub(crate) async fn close_pending(
237        &mut self,
238        hopnum: Option<HopNum>,
239        stream_id: StreamId,
240        behav: CloseStreamBehavior,
241    ) -> StdResult<(), Error> {
242        let mut tx = self.get_or_spawn_stream_reactor(hopnum)?;
243
244        let msg = CtrlMsg::ClosePendingStream { stream_id, behav };
245
246        tx.send(msg).await.map_err(|_| {
247            // The stream reactor has shut down
248            Error::NotConnected
249        })
250    }
251
252    /// Get a handle to the stream reactor, spawning it if necessary
253    fn get_or_spawn_stream_reactor(
254        &self,
255        hopnum: Option<HopNum>,
256    ) -> StdResult<mpsc::Sender<CtrlMsg>, Error> {
257        let mut hops = self.hops.write().expect("poisoned lock");
258        let hop = hops.get_mut(hopnum)?;
259
260        let tx = match &hop.tx {
261            Some(tx) => tx.clone(),
262            None => {
263                // If we don't have a handle to the stream reactor,
264                // it means it hasn't been spawned yet, so we have to spawn it now.
265                let tx =
266                    self.spawn_stream_reactor(hopnum, &hop.settings, Arc::clone(&hop.ccontrol))?;
267
268                hop.tx = Some(tx.clone());
269
270                // Return a copy of this sender (can't borrow because the hop
271                // is behind a Mutex, and we can't keep it locked across the send()
272                // await point)
273                tx
274            }
275        };
276
277        Ok(tx)
278    }
279
280    /// Spawn a [`StreamReactor`] for the specified hop.
281    fn spawn_stream_reactor(
282        &self,
283        hopnum: Option<HopNum>,
284        settings: &HopSettings,
285        ccontrol: Arc<Mutex<CongestionControl>>,
286    ) -> StdResult<mpsc::Sender<CtrlMsg>, Error> {
287        use tor_rtcompat::SpawnExt as _;
288
289        // NOTE: not registering this channel with the memquota subsystem is okay,
290        // because it has no buffering (if ever decide to make the size of this buffer
291        // non-zero for whatever reason, we must remember to register it with memquota
292        // so that it counts towards the total memory usage for the circuit.
293        //
294        // NOTE: We should be careful about the effect of buffering on flow control.
295        // See comments on `StreamReactor::cell_rx` about XON/XOFF flow control.
296        //
297        // TODO(tuning): having zero buffering here is very likely suboptimal.
298        // We should do *some* buffering here, and then figure out if we should it
299        // up to memquota or not.
300        #[allow(clippy::disallowed_methods)]
301        let (fwd_stream_tx, fwd_stream_rx) = mpsc::channel(0);
302
303        let flow_ctrl_params = Arc::new(settings.flow_ctrl_params.clone());
304        let relay_format = settings.relay_crypt_protocol().relay_cell_format();
305        let outbound = CircHopOutbound::new(ccontrol, relay_format, flow_ctrl_params, settings);
306
307        let stream_reactor = StreamReactor::new(
308            self.runtime.clone(),
309            hopnum,
310            outbound,
311            self.ctx.unique_id,
312            self.ctx.circ_id,
313            fwd_stream_rx,
314            self.bwd_tx.clone(),
315            Arc::clone(&self.ctx.handler),
316            #[cfg(any(feature = "hs-service", feature = "relay"))]
317            Arc::clone(&self.ctx.incoming),
318            self.memquota.clone(),
319        );
320
321        self.runtime
322            .spawn(async {
323                let _ = stream_reactor.run().await;
324            })
325            .map_err(|e| Error::Spawn {
326                spawning: "stream reactor",
327                cause: e.into(),
328            })?;
329
330        Ok(fwd_stream_tx)
331    }
332}