tor_proto/circuit/reactor/forward.rs
1//! A circuit's view of the forward state of the circuit.
2
3use crate::circuit::UniqId;
4use crate::circuit::reactor::backward::BackwardReactorCmd;
5use crate::circuit::reactor::hop_mgr::HopMgr;
6use crate::circuit::reactor::macros::derive_deftly_template_CircuitReactor;
7use crate::circuit::reactor::stream;
8use crate::circuit::reactor::{ControlHandler, ReactorResultChannel};
9use crate::congestion::sendme;
10use crate::stream::cmdcheck::AnyCmdChecker;
11use crate::stream::msg_streamid;
12use crate::util::err::ReactorError;
13use crate::{Error, HopNum, Result};
14
15#[cfg(any(feature = "hs-service", feature = "relay"))]
16use {
17 crate::stream::CloseStreamBehavior,
18 crate::stream::incoming::{
19 IncomingStreamRequestFilter, IncomingStreamRequestHandler, StreamReqSender,
20 },
21};
22
23// TODO(circpad): once padding is stabilized, the padding module will be moved out of client.
24use crate::client::circuit::padding::PaddingController;
25
26use tor_cell::chancell::{CircId, msg::AnyChanMsg};
27use tor_cell::relaycell::flow_ctrl::XonKBpsEwma;
28use tor_cell::relaycell::msg::{Sendme, SendmeTag};
29use tor_cell::relaycell::{
30 AnyRelayMsgOuter, RelayCellDecoderResult, RelayCellFormat, RelayCmd, StreamId, UnparsedRelayMsg,
31};
32use tor_linkspec::HasRelayIds;
33use tor_rtcompat::Runtime;
34
35use derive_deftly::Deftly;
36use futures::SinkExt;
37use futures::channel::mpsc;
38use futures::{FutureExt as _, StreamExt, select_biased};
39use std::result::Result as StdResult;
40use tracing::debug;
41
42use crate::circuit::CircuitRxReceiver;
43
44/// The forward circuit reactor.
45///
46/// See the [`reactor`](crate::circuit::reactor) module-level docs.
47///
48/// Shuts downs down if an error occurs, or if either the [`Reactor`](super::Reactor)
49/// or the [`BackwardReactor`](super::BackwardReactor) shuts down:
50///
51/// * if the `Reactor` shuts down, we are alerted via the ctrl/command mpsc channels
52/// (their sending ends will close, which causes run_once() to return ReactorError::Shutdown)
53/// * if `BackwardReactor` shuts down, the `Reactor` will notice and will itself shut down,
54/// which, in turn, causes the `ForwardReactor` to shut down as described above
55#[derive(Deftly)]
56#[derive_deftly(CircuitReactor)]
57#[deftly(reactor_name = "forward reactor")]
58#[deftly(run_inner_fn = "Self::run_once")]
59#[must_use = "If you don't call run() on a reactor, the circuit won't work."]
60pub(super) struct ForwardReactor<R: Runtime, F: ForwardHandler> {
61 /// A handle to the runtime.
62 runtime: R,
63 /// An identifier for logging about this reactor's circuit.
64 unique_id: UniqId,
65 /// The circuit identifier on the inbound Tor channel.
66 circ_id: CircId,
67 /// Implementation-dependent part of the reactor.
68 ///
69 /// This enables us to customize the behavior of the reactor,
70 /// depending on whether we are a client or a relay.
71 inner: F,
72 /// Channel for receiving control commands.
73 command_rx: mpsc::UnboundedReceiver<CtrlCmd<F::CtrlCmd>>,
74 /// Channel for receiving control messages.
75 control_rx: mpsc::UnboundedReceiver<CtrlMsg<F::CtrlMsg>>,
76 /// The reading end of the inbound Tor channel.
77 ///
78 /// Yields cells moving from the client towards the exit, if we are a relay,
79 /// or cells moving towards *us*, if we are a client.
80 inbound_chan_rx: CircuitRxReceiver,
81 /// Sender for sending commands to the BackwardReactor.
82 ///
83 /// Used for sending:
84 ///
85 /// * circuit-level SENDMEs received from the other endpoint
86 /// (`[BackwardReactorCmd::HandleSendme]`)
87 /// * circuit-level SENDMEs that need to be delivered to the other endpoint
88 /// (using `[BackwardReactorCmd::SendRelayMsg]`)
89 ///
90 /// The receiver is in [`BackwardReactor`](super::BackwardReactor), which is responsible for
91 /// sending cell over the inbound channel.
92 backward_reactor_tx: mpsc::Sender<BackwardReactorCmd>,
93 /// Hop manager, storing per-hop state, and handles to the stream reactors.
94 ///
95 /// Contains the `CircHopList`.
96 hop_mgr: HopMgr<R>,
97 /// An implementation-specific event stream.
98 ///
99 /// Polled from the main loop of the reactor.
100 /// Each event is passed to [`ForwardHandler::handle_event`].
101 circ_events: mpsc::Receiver<F::CircEvent>,
102 /// A padding controller to which padding-related events should be reported.
103 padding_ctrl: PaddingController,
104}
105
106/// A control command aimed at the generic forward reactor.
107pub(crate) enum CtrlCmd<C> {
108 /// Begin accepting streams on this circuit.
109 //
110 // TODO(DEDUP): this is very similar to its client-side counterpart,
111 // except the hop is a Option<HopNum> instead of a TargetHop.
112 #[cfg(any(feature = "hs-service", feature = "relay"))]
113 #[allow(unused)] // TODO(dedup): this will be used by hs services
114 AwaitStreamRequests {
115 /// A channel for sending information about an incoming stream request.
116 incoming_sender: StreamReqSender,
117 /// A `CmdChecker` to keep track of which message types are acceptable.
118 cmd_checker: AnyCmdChecker,
119 /// Oneshot channel to notify on completion.
120 done: ReactorResultChannel<()>,
121 /// The hop that is allowed to create streams.
122 ///
123 /// Set to None if we are a relay wanting to accept stream requests.
124 hop: Option<HopNum>,
125 /// A filter used to check requests before passing them on.
126 filter: Box<dyn IncomingStreamRequestFilter>,
127 },
128
129 /// Close the specified pending incoming stream, sending the provided END message.
130 ///
131 /// A stream is said to be pending if the message for initiating the stream was received but
132 /// not has not been responded to yet.
133 ///
134 /// This should be used by responders for closing pending incoming streams initiated by the
135 /// other party on the circuit.
136 ///
137 /// TODO(dedup): this is almost identical to the ClosePendingStream control message
138 /// from the client-side. We can get rid of the duplication by rewriting
139 /// the client circuit reactor to use the new multi-reactor architecture
140 #[cfg(any(feature = "hs-service", feature = "relay"))]
141 ClosePendingStream {
142 /// The hop number the stream is on.
143 ///
144 /// Set to None if we are a relay.
145 hop: Option<HopNum>,
146 /// The stream ID to send the END for.
147 stream_id: StreamId,
148 /// The END message to send, if any.
149 message: CloseStreamBehavior,
150 /// Oneshot channel to notify on completion.
151 done: ReactorResultChannel<()>,
152 },
153 /// Inform the stream reactor that the drain rate of a stream has changed so that it
154 /// can send an XON if needed.
155 ///
156 /// This is routed to the stream reactor because the it owns the stream map and the
157 /// XON/XOFF state. It is also the reactor that decides to send an XOFF or not. It is
158 /// in charge of sending the XON to the backward reactor if need be.
159 StreamDrainRateUpdate {
160 /// The hop number the stream is on.
161 ///
162 /// Set to None if we are a relay.
163 hop: Option<HopNum>,
164 /// The stream ID to send the XON on.
165 stream_id: StreamId,
166 /// The drain rate to advertise in the XON.
167 rate: XonKBpsEwma,
168 },
169 /// An implementation-dependent control command.
170 #[allow(unused)] // TODO(relay)
171 Custom(C),
172}
173
174/// A control message aimed at the generic forward reactor.
175pub(crate) enum CtrlMsg<M> {
176 /// An implementation-dependent control message.
177 #[allow(unused)] // TODO(relay)
178 Custom(M),
179}
180
181/// Trait for customizing the behavior of the forward reactor.
182///
183/// Used for plugging in the implementation-dependent (client vs relay)
184/// parts of the implementation into the generic one.
185pub(crate) trait ForwardHandler: ControlHandler {
186 /// Type that explains how to build an outgoing channel.
187 type BuildSpec: HasRelayIds;
188
189 /// The subclass of ChanMsg that can arrive on this type of circuit.
190 type CircChanMsg: TryFrom<AnyChanMsg, Error = crate::Error>;
191
192 /// An opaque event type.
193 ///
194 /// The [`ForwardReactor`] polls an MPSC stream yielding `CircEvent`s from the main loop.
195 /// Each event is passed to [`Self::handle_event`] for handling.
196 type CircEvent;
197
198 /// Handle a non-SENDME RELAY message on this circuit with stream ID 0.
199 async fn handle_meta_msg<R: Runtime>(
200 &mut self,
201 runtime: &R,
202 early: bool,
203 hopnum: Option<HopNum>,
204 msg: UnparsedRelayMsg,
205 relay_cell_format: RelayCellFormat,
206 ) -> StdResult<(), ReactorError>;
207
208 /// Handle a forward (TODO terminology) cell.
209 ///
210 /// The cell is
211 /// - moving from the client towards the exit, if we're a relay
212 /// - moving from the guard towards us, if we're a client
213 ///
214 /// Returns an error if the cell should cause the reactor to shut down,
215 /// or a [`ForwardCellDisposition`] specifying how it should be handled.
216 ///
217 /// Returns `None` if the cell was handled internally by this handler.
218 async fn handle_forward_cell<R: Runtime>(
219 &mut self,
220 hop_mgr: &HopMgr<R>,
221 cell: Self::CircChanMsg,
222 ) -> StdResult<Option<ForwardCellDisposition>, ReactorError>;
223
224 /// Handle an implementation-specific circuit event.
225 ///
226 /// Returns a command for the backward reactor.
227 fn handle_event(
228 &mut self,
229 event: Self::CircEvent,
230 ) -> StdResult<Option<BackwardReactorCmd>, ReactorError>;
231
232 /// Wait until the outbound channel, if there is one, is ready to accept more cells.
233 ///
234 /// Resolves immediately if there is no outbound channel.
235 /// Blocks if there is a pending outbound channel.
236 async fn outbound_chan_ready(&mut self) -> Result<()>;
237}
238
239/// What action to take in response to a cell arriving on our inbound Tor channel.
240pub(crate) enum ForwardCellDisposition {
241 /// Handle a decoded RELAY or RELAY_EARLY cell in the [`ForwardReactor`].
242 HandleRecognizedRelay {
243 /// The decoded cell.
244 cell: RelayCellDecoderResult,
245 /// Whether this was a RELAY_EARLY.
246 early: bool,
247 /// The hop this cell was for.
248 hopnum: Option<HopNum>,
249 /// The SENDME tag.
250 tag: SendmeTag,
251 },
252}
253
254impl<R: Runtime, F: ForwardHandler> ForwardReactor<R, F> {
255 /// Create a new [`ForwardReactor`].
256 #[allow(clippy::too_many_arguments)] // TODO
257 pub(super) fn new(
258 runtime: R,
259 unique_id: UniqId,
260 circ_id: CircId,
261 inner: F,
262 hop_mgr: HopMgr<R>,
263 inbound_chan_rx: CircuitRxReceiver,
264 control_rx: mpsc::UnboundedReceiver<CtrlMsg<F::CtrlMsg>>,
265 command_rx: mpsc::UnboundedReceiver<CtrlCmd<F::CtrlCmd>>,
266 backward_reactor_tx: mpsc::Sender<BackwardReactorCmd>,
267 circ_events: mpsc::Receiver<F::CircEvent>,
268 padding_ctrl: PaddingController,
269 ) -> Self {
270 Self {
271 runtime,
272 unique_id,
273 circ_id,
274 inbound_chan_rx,
275 control_rx,
276 command_rx,
277 inner,
278 backward_reactor_tx,
279 hop_mgr,
280 circ_events,
281 padding_ctrl,
282 }
283 }
284
285 /// Helper for [`run`](Self::run).
286 async fn run_once(&mut self) -> StdResult<(), ReactorError> {
287 let outbound_chan_ready = self.inner.outbound_chan_ready();
288
289 let inbound_chan_rx_fut = async {
290 // Avoid reading from the inbound_chan_rx Tor Channel if the outgoing sink is blocked
291 outbound_chan_ready.await?;
292 Ok(self.inbound_chan_rx.next().await)
293 };
294
295 select_biased! {
296 res = self.command_rx.next().fuse() => {
297 let cmd = res.ok_or_else(|| ReactorError::Shutdown)?;
298 self.handle_cmd(cmd).await
299 }
300 res = self.control_rx.next().fuse() => {
301 let msg = res.ok_or_else(|| ReactorError::Shutdown)?;
302 self.handle_msg(msg)
303 }
304 res = self.circ_events.next().fuse() => {
305 let ev = res.ok_or_else(|| ReactorError::Shutdown)?;
306 if let Some(cmd) = self.inner.handle_event(ev)? {
307 self.send_reactor_cmd(cmd).await?;
308 }
309
310 Ok(())
311 }
312 res = inbound_chan_rx_fut.fuse() => {
313 let cell = res.map_err(ReactorError::Err)?;
314 let Some(cell) = cell else {
315 debug!(
316 circ_uniq_id = %self.unique_id,
317 backward_circ_id = %self.circ_id,
318 "Backward channel has closed, shutting down forward relay reactor",
319 );
320
321 return Err(ReactorError::Shutdown);
322 };
323
324 let cell: F::CircChanMsg = cell.try_into()?;
325 let Some(disp) = self.inner.handle_forward_cell(&self.hop_mgr, cell).await? else {
326 return Ok(());
327 };
328
329 match disp {
330 ForwardCellDisposition::HandleRecognizedRelay { cell, early, hopnum, tag } => {
331 self.handle_relay_cell(cell, early, hopnum, tag).await
332 }
333 }
334 },
335 }
336 }
337
338 /// Handle a control command.
339 #[allow(clippy::unused_async)] // used if any(feature = "hs-service", feature = "relay")
340 async fn handle_cmd(&mut self, cmd: CtrlCmd<F::CtrlCmd>) -> StdResult<(), ReactorError> {
341 match cmd {
342 #[cfg(any(feature = "hs-service", feature = "relay"))]
343 CtrlCmd::AwaitStreamRequests {
344 incoming_sender,
345 cmd_checker,
346 done,
347 hop,
348 filter,
349 } => {
350 let handler = IncomingStreamRequestHandler {
351 incoming_sender,
352 cmd_checker,
353 hop_num: hop,
354 filter,
355 };
356
357 // Update the HopMgr with the
358 let ret = self.hop_mgr.set_incoming_handler(handler);
359 let _ = done.send(ret); // don't care if the corresponding receiver goes away.
360 Ok(())
361 }
362 #[cfg(any(feature = "hs-service", feature = "relay"))]
363 CtrlCmd::ClosePendingStream {
364 hop,
365 stream_id,
366 message,
367 done,
368 } => {
369 let ret = self.hop_mgr.close_pending(hop, stream_id, message).await;
370 let _ = done.send(ret); // don't care if the corresponding receiver goes away.
371
372 Ok(())
373 }
374 CtrlCmd::StreamDrainRateUpdate {
375 hop,
376 stream_id,
377 rate,
378 } => {
379 let msg = stream::CtrlMsg::DrainRateUpdate { stream_id, rate };
380 self.hop_mgr.send(hop, msg).await
381 }
382 CtrlCmd::Custom(c) => self.inner.handle_cmd(c),
383 }
384 }
385
386 /// Handle a control message.
387 fn handle_msg(&mut self, msg: CtrlMsg<F::CtrlMsg>) -> StdResult<(), ReactorError> {
388 match msg {
389 CtrlMsg::Custom(c) => self.inner.handle_msg(c),
390 }
391 }
392
393 /// Note that we have received a RELAY cell.
394 ///
395 /// Updates the padding and CC state.
396 fn note_relay_cell_received(
397 &self,
398 hopnum: Option<HopNum>,
399 c_t_w: bool,
400 ) -> Result<(RelayCellFormat, bool)> {
401 let mut hops = self.hop_mgr.hops().write().expect("poisoned lock");
402 let hop = hops.get_mut(hopnum)?;
403
404 // Check whether we are allowed to receive more data for this circuit hop.
405 hop.inbound.decrement_cell_limit()?;
406
407 // Decrement the circuit sendme windows, and see if we need to
408 // send a sendme cell.
409 let send_circ_sendme = if c_t_w {
410 hop.ccontrol
411 .lock()
412 .expect("poisoned lock")
413 .note_data_received()?
414 } else {
415 false
416 };
417
418 let relay_cell_format = hop.settings.relay_crypt_protocol().relay_cell_format();
419
420 Ok((relay_cell_format, send_circ_sendme))
421 }
422
423 /// Handle a RELAY cell.
424 ///
425 // TODO(DEDUP): very similar to Client::handle_relay_cell()
426 async fn handle_relay_cell(
427 &mut self,
428 decode_res: RelayCellDecoderResult,
429 early: bool,
430 hopnum: Option<HopNum>,
431 tag: SendmeTag,
432 ) -> StdResult<(), ReactorError> {
433 // For padding purposes, if we are a relay, we set the hopnum to 0
434 // TODO(relay): is this right?
435 let hopnum_padding = hopnum.unwrap_or_else(|| HopNum::from(0));
436 if decode_res.is_padding() {
437 self.padding_ctrl.decrypted_padding(hopnum_padding)?;
438 } else {
439 self.padding_ctrl.decrypted_data(hopnum_padding);
440 }
441
442 let c_t_w = decode_res.cmds().any(sendme::cmd_counts_towards_windows);
443 let (relay_cell_format, send_circ_sendme) = self.note_relay_cell_received(hopnum, c_t_w)?;
444
445 // If we do need to send a circuit-level SENDME cell, do so.
446 if send_circ_sendme {
447 // This always sends a V1 (tagged) sendme cell, and thereby assumes
448 // that SendmeEmitMinVersion is no more than 1. If the authorities
449 // every increase that parameter to a higher number, this will
450 // become incorrect. (Higher numbers are not currently defined.)
451 let sendme = Sendme::from(tag);
452 let msg = AnyRelayMsgOuter::new(None, sendme.into());
453 let forward = BackwardReactorCmd::SendRelayMsg { hop: hopnum, msg };
454
455 // NOTE: sending the SENDME to the backward reactor for handling
456 // might seem counterintuitive, given that we have access to
457 // the congestion control object right here (via hop_mgr).
458 //
459 // However, the forward reactor does not have access to the
460 // outbound_chan_tx part of the inbound (towards the client) Tor channel,
461 // and so it cannot handle the SENDME on its own
462 // (because it cannot obtain the congestion signals),
463 // so the SENDME needs to be handled in the backward reactor.
464 //
465 // NOTE: this will block if the backward reactor is not ready
466 // to send any more cells.
467 self.send_reactor_cmd(forward).await?;
468 }
469
470 let (mut msgs, incomplete) = decode_res.into_parts();
471 while let Some(msg) = msgs.next() {
472 match self
473 .handle_relay_msg(early, hopnum, msg, relay_cell_format, c_t_w)
474 .await
475 {
476 Ok(()) => continue,
477 Err(e) => {
478 for m in msgs {
479 debug!(
480 circ_uniq_id = %self.unique_id,
481 backward_circ_id = %self.circ_id,
482 "Ignoring relay msg received after triggering shutdown: {m:?}",
483 );
484 }
485 if let Some(incomplete) = incomplete {
486 debug!(
487 circ_uniq_id = %self.unique_id,
488 backward_circ_id = %self.circ_id,
489 "Ignoring partial relay msg received after triggering shutdown: {:?}",
490 incomplete,
491 );
492 }
493
494 return Err(e);
495 }
496 }
497 }
498
499 Ok(())
500 }
501
502 /// Handle a single incoming RELAY message.
503 async fn handle_relay_msg(
504 &mut self,
505 early: bool,
506 hop: Option<HopNum>,
507 msg: UnparsedRelayMsg,
508 relay_cell_format: RelayCellFormat,
509 cell_counts_toward_windows: bool,
510 ) -> StdResult<(), ReactorError> {
511 // If this msg wants/refuses to have a Stream ID, does it
512 // have/not have one?
513 let streamid = msg_streamid(&msg)?;
514
515 // If this doesn't have a StreamId, it's a meta cell,
516 // not meant for a particular stream.
517 let Some(sid) = streamid else {
518 return self
519 .handle_meta_msg(early, hop, msg, relay_cell_format)
520 .await;
521 };
522
523 let msg = stream::CtrlMsg::DeliverStreamMsg {
524 sid,
525 msg,
526 cell_counts_toward_windows,
527 };
528
529 // All messages on streams are handled in the stream reactor
530 // (because that's where the stream map is)
531 //
532 // Internally, this will spawn a StreamReactor for the target hop,
533 // if not already spawned.
534 self.hop_mgr.send(hop, msg).await
535 }
536
537 /// Handle a RELAY or RELAY_EARLY message on this circuit with stream ID 0.
538 async fn handle_meta_msg(
539 &mut self,
540 early: bool,
541 hopnum: Option<HopNum>,
542 msg: UnparsedRelayMsg,
543 relay_cell_format: RelayCellFormat,
544 ) -> StdResult<(), ReactorError> {
545 match msg.cmd() {
546 RelayCmd::SENDME => {
547 let sendme = msg
548 .decode::<Sendme>()
549 .map_err(|e| Error::from_bytes_err(e, "sendme message"))?
550 .into_msg();
551
552 let cmd = BackwardReactorCmd::HandleSendme {
553 hop: hopnum,
554 sendme,
555 };
556
557 self.send_reactor_cmd(cmd).await
558 }
559 _ => {
560 self.inner
561 .handle_meta_msg(&self.runtime, early, hopnum, msg, relay_cell_format)
562 .await
563 }
564 }
565 }
566
567 /// Send a command to the backward reactor.
568 ///
569 /// Blocks if the `backward_reactor_tx` channel is full, i.e. if the backward reactor
570 /// is not ready to send any more cells.
571 ///
572 /// Returns an error if the backward reactor has shut down.
573 async fn send_reactor_cmd(
574 &mut self,
575 forward: BackwardReactorCmd,
576 ) -> StdResult<(), ReactorError> {
577 self.backward_reactor_tx.send(forward).await.map_err(|_| {
578 // The other reactor has shut down
579 ReactorError::Shutdown
580 })
581 }
582}