Skip to main content

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}