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}