Skip to main content

tor_proto/circuit/reactor/
backward.rs

1//! A circuit's view of the backward state of the circuit.
2
3use crate::channel::Channel;
4use crate::circuit::UniqId;
5use crate::circuit::cell_sender::CircuitCellSender;
6use crate::circuit::reactor::ControlHandler;
7use crate::circuit::reactor::circhop::CircHopList;
8use crate::circuit::reactor::macros::derive_deftly_template_CircuitReactor;
9use crate::circuit::reactor::stream::ReadyStreamMsg;
10use crate::congestion::{CongestionControl, sendme};
11use crate::crypto::cell::RelayCellBody;
12use crate::util::err::ReactorError;
13use crate::util::poll_all::PollAll;
14use crate::{Error, HopNum, Result};
15
16// TODO(circpad): once padding is stabilized, the padding module will be moved out of client.
17use crate::client::circuit::padding::{
18    self, PaddingController, PaddingEvent, PaddingEventStream, QueuedCellPaddingInfo,
19};
20
21use tor_cell::chancell::msg::{AnyChanMsg, Relay};
22use tor_cell::chancell::{AnyChanCell, BoxedCellBody, ChanCmd, CircId};
23use tor_cell::relaycell::msg::{Sendme, SendmeTag};
24use tor_cell::relaycell::{AnyRelayMsgOuter, RelayCellFormat, RelayCmd, StreamId};
25use tor_rtcompat::{DynTimeProvider, Runtime};
26
27use derive_deftly::Deftly;
28use futures::SinkExt;
29use futures::channel::mpsc;
30use futures::{FutureExt as _, StreamExt, future, select_biased};
31use tracing::{debug, trace};
32
33use std::pin::Pin;
34use std::result::Result as StdResult;
35use std::sync::{Arc, Mutex, RwLock};
36
37use crate::circuit::CircuitRxReceiver;
38
39#[cfg(feature = "circ-padding")]
40use crate::circuit::padding::{CircPaddingDisposition, padding_disposition};
41
42#[cfg(feature = "relay")]
43use tor_cell::relaycell::msg::Extended2;
44
45/// The "backward" circuit reactor of a relay.
46///
47/// See the [`reactor`](crate::circuit::reactor) module-level docs.
48///
49/// Shuts downs down if an error occurs, or if the [`Reactor`](super::Reactor),
50/// [`ForwardReactor`](super::ForwardReactor), or if one of the
51/// [`StreamReactor`](super::stream::StreamReactor)s of this circuit shuts down:
52///
53///   * if the `Reactor` shuts down, we are alerted via the ctrl/command mpsc channels
54///     (their sending ends will close, which causes run_once() to return ReactorError::Shutdown)
55///   * if `ForwardReactor` shuts down, the `Reactor` will notice and will itself shut down,
56///     which, in turn, causes the `BackwardReactor` to shut down as described above
57///   * if one of the `StreamReactor`s shuts down, the `ForwardReactor` will
58///     notice when it next tries to deliver a stream message to it, and shut down,
59///     causing the `BackwardReactor` and top-level `Reactor` to follow suit
60#[derive(Deftly)]
61#[derive_deftly(CircuitReactor)]
62#[deftly(reactor_name = "backward reactor")]
63#[deftly(run_inner_fn = "Self::run_once")]
64#[must_use = "If you don't call run() on a reactor, the circuit won't work."]
65pub(super) struct BackwardReactor<B: BackwardHandler> {
66    /// The time provider.
67    time_provider: DynTimeProvider,
68    /// An identifier for logging about this reactor's circuit.
69    unique_id: UniqId,
70    /// The circuit identifier on the backward Tor channel.
71    circ_id: CircId,
72    /// The inbound Tor channel.
73    channel: Arc<Channel>,
74    /// Implementation-dependent part of the reactor.
75    ///
76    /// This enables us to customize the behavior of the reactor,
77    /// depending on whether we are a client or a relay.
78    inner: B,
79    /// The reading end of the outbound Tor channel, if we are not the last hop.
80    ///
81    /// Yields cells moving from the exit towards the client, if we are a middle relay.
82    outbound_chan_rx: Option<CircuitRxReceiver>,
83    /// The per-hop state, shared with the forward reactor.
84    ///
85    /// The backward reactor acquires a read lock to this whenever it needs to
86    ///
87    ///   * send a circuit-level SENDME
88    ///   * handle a circuit-level SENDME
89    ///   * send a padding cell
90    ///
91    // Note: For the sending/handling of SENDMEs, we lock the hop list
92    // to extract the relay cell format and CC state of the hop.
93    // Technically, for the SENDME cases, we could've avoided locking
94    // the hop list from the BWD, by having the FWD share the relay cell format
95    // and CC state in the BackwardReactorCmd::{Send,Handle}Sendme command.
96    // But for the padding case, we *need* the hop list, because we need
97    // to work out what relay cell format to use when sending the padding cell.
98    // But for the sake of simplicity, I made the BWD consult the CircHopList in all cases.
99    //
100    // TODO: the backward reactor only ever reads from this.
101    // Conceptually, it is the forward reactor's HopMgr that owns this list:
102    // only HopMgr can add hops to the list.
103    //
104    // Perhaps we need a specialized abstraction that only allows reading here.
105    // This could be a wrapper over RwLock, providing a read-only API.
106    hops: Arc<RwLock<CircHopList>>,
107    /// The sending end of the backward Tor channel.
108    ///
109    /// Delivers cells towards the other endpoint: towards the client, if we are a relay,
110    /// or towards the exit, if we are a client.
111    inbound_chan_tx: CircuitCellSender,
112    /// Channel for receiving control commands.
113    command_rx: mpsc::UnboundedReceiver<CtrlCmd<B::CtrlCmd>>,
114    /// Channel for receiving control messages.
115    control_rx: mpsc::UnboundedReceiver<CtrlMsg<B::CtrlMsg>>,
116    /// Receiver for [`BackwardReactorCmd`]s coming from the forward reactor.
117    ///
118    /// The sender is in [`ForwardReactor`](super::ForwardReactor), which will forward all cells
119    /// carrying Tor stream data to us.
120    ///
121    /// This serves a dual purpose:
122    ///
123    ///   * it enables the `ForwardReactor` to deliver Tor stream data received
124    ///     from the other endpoint
125    ///   * it lets the `BackwardReactor` know if the `ForwardReactor` has shut down:
126    ///     we select! on this MPSC channel in the main loop, so if the `ForwardReactor`
127    ///     shuts down, we will get EOS upon calling `.next()`)
128    forward_reactor_rx: mpsc::Receiver<BackwardReactorCmd>,
129    /// A channel for receiving endpoint-bound stream messages from the StreamReactor(s)
130    /// (the stream messages are client-bound if we are a relay, or exit-bound if we are a client).
131    stream_rx: mpsc::Receiver<ReadyStreamMsg>,
132    /// A padding controller to which padding-related events should be reported.
133    padding_ctrl: PaddingController,
134    /// An event stream telling us about padding-related events.
135    padding_event_stream: PaddingEventStream,
136    /// Current rules for blocking traffic, according to the padding controller.
137    #[cfg(feature = "circ-padding")]
138    padding_block: Option<padding::StartBlocking>,
139}
140
141/// A control message aimed at the generic backward reactor.
142pub(crate) enum CtrlMsg<M> {
143    /// Inform the reactor that there's a flow control update for a given stream.
144    ///
145    /// The reactor will decide how to handle this update depending on the type of flow control and
146    /// the current state of the stream.
147    FlowCtrlUpdate {
148        /// The hop that the stream is on.
149        /// Relay circuits use `None`.
150        hop: Option<HopNum>,
151        /// The stream ID that the update is for.
152        stream_id: StreamId,
153        /// The type of flow control update, and any associated metadata.
154        msg: FlowCtrlMsg,
155    },
156    /// An implementation-dependent control message.
157    #[allow(unused)] // TODO(relay)
158    Custom(M),
159}
160
161/// A control command aimed at the generic backward reactor.
162pub(crate) enum CtrlCmd<C> {
163    /// An implementation-dependent control command.
164    #[allow(unused)] // TODO(relay)
165    Custom(C),
166}
167
168/// Trait for customizing the behavior of the backward reactor.
169///
170/// Used for plugging in the implementation-dependent (client vs relay)
171/// parts of the implementation into the generic one.
172pub(crate) trait BackwardHandler: ControlHandler {
173    /// The subclass of ChanMsg that can arrive on this type of circuit.
174    type CircChanMsg: TryFrom<AnyChanMsg, Error = crate::Error> + Send;
175
176    /// Encrypt a RelayCellBody that is moving in the backward direction.
177    fn encrypt_relay_cell(
178        &mut self,
179        cmd: ChanCmd,
180        body: &mut RelayCellBody,
181        hop: Option<HopNum>,
182    ) -> SendmeTag;
183
184    /// Handle a cell that was read from the Tor outbound channel.
185    ///
186    /// Returns an error if the cell should cause the reactor to shut down,
187    /// or a [`BackwardCellDisposition`] specifying how it should be handled.
188    fn handle_backward_cell(
189        &mut self,
190        circ_uniq_id: UniqId,
191        circ_id: CircId,
192        cell: Self::CircChanMsg,
193    ) -> StdResult<BackwardCellDisposition, ReactorError>;
194}
195
196/// What action to take in response to a cell arriving on our outbound Tor channel.
197pub(crate) enum BackwardCellDisposition {
198    /// Forward the cell, writing it to the inbound Tor channel.
199    Forward(AnyChanMsg),
200}
201
202impl<B: BackwardHandler> BackwardReactor<B> {
203    /// Create a new [`BackwardReactor`].
204    #[allow(clippy::too_many_arguments)] // TODO
205    pub(super) fn new<R: Runtime>(
206        runtime: R,
207        channel: &Arc<Channel>,
208        circ_id: CircId,
209        unique_id: UniqId,
210        inner: B,
211        hops: Arc<RwLock<CircHopList>>,
212        forward_reactor_rx: mpsc::Receiver<BackwardReactorCmd>,
213        control_rx: mpsc::UnboundedReceiver<CtrlMsg<B::CtrlMsg>>,
214        command_rx: mpsc::UnboundedReceiver<CtrlCmd<B::CtrlCmd>>,
215        padding_ctrl: PaddingController,
216        padding_event_stream: PaddingEventStream,
217        stream_rx: mpsc::Receiver<ReadyStreamMsg>,
218    ) -> Self {
219        let channel = Arc::clone(channel);
220        let inbound_chan_tx = CircuitCellSender::from_channel_sender(channel.sender());
221
222        Self {
223            time_provider: DynTimeProvider::new(runtime),
224            outbound_chan_rx: None,
225            channel,
226            inner,
227            hops,
228            inbound_chan_tx,
229            unique_id,
230            circ_id,
231            forward_reactor_rx,
232            control_rx,
233            command_rx,
234            stream_rx,
235            padding_ctrl,
236            padding_event_stream,
237            #[cfg(feature = "circ-padding")]
238            padding_block: None,
239        }
240    }
241
242    /// Helper for [`run`](Self::run).
243    ///
244    /// Handles cells arriving on the outbound Tor channel,
245    /// and writes cells to the inbound Tor channel.
246    ///
247    /// Because the Tor application streams, the `forward_reactor_rx` MPSC streams,
248    /// and the outbound Tor channel MPSC stream are driven concurrently using [`PollAll`],
249    /// this function can send up to 3 cells per call over the inbound Tor channel:
250    ///
251    ///    * a cell carrying Tor stream data
252    ///    * a cell received from the outbound Tor channel, if we are a relay
253    ///      (moving from the exit towards the client)
254    ///    * a circuit-level SENDME
255    ///
256    /// However, in practice, leaky pipe is not really used,
257    /// and so relays that have application streams (i.e. the exits),
258    /// are not going to have an outbound Tor channel,
259    /// and so this will only really drive Tor stream data,
260    /// delivering at most 2 cells per call.
261    async fn run_once(&mut self) -> StdResult<(), ReactorError> {
262        /// The maximum number of events we expect to handle per reactor loop.
263        ///
264        /// This is bounded by the number of futures we push into the PollAll.
265        const PER_LOOP_EVENT_COUNT: usize = 3;
266
267        // A collection of futures we plan to drive concurrently.
268        let mut poll_all =
269            PollAll::<PER_LOOP_EVENT_COUNT, Option<CircuitEvent<B::CircChanMsg>>>::new();
270
271        // Flush the backward Tor channel sink, and check it for readiness
272        //
273        // TODO(flushing): here and everywhere else we need to flush:
274        //
275        // Currently, we try to flush every time we want to write to the sink,
276        // but may be suboptimal.
277        //
278        // However, we don't actually *wait* for the flush to complete
279        // (we just make a bit of progress by calling poll_flush),
280        // so it's possible that this is actually tolerable.
281        // We should run some tests, and if this turns out to be a performance bottleneck,
282        // we'll have to rethink our flushing approach.
283        let backward_chan_ready = future::poll_fn(|cx| {
284            // The flush outcome doesn't matter,
285            // so we simply move on to the readiness check.
286            // The reason we don't wait on the flush is because we don't
287            // want to flush on *every* reactor loop, but we do want to make
288            // a bit of progress each time.
289            //
290            // (TODO: do we want to handle errors here?)
291            let _ = self.inbound_chan_tx.poll_flush_unpin(cx);
292
293            self.inbound_chan_tx.poll_ready_unpin(cx)
294        });
295
296        // Concurrently, drive :
297        //  1. a future that reads from the StreamReactor, to see if there are
298        //  any application streams that have a message to send
299        //  (this resolves to a message that needs to be delivered to the peer)
300        poll_all.push(async {
301            // Internally, each stream reactor checks if we're allowed to send anything
302            // that counts towards SENDME windows (and ceases to send us stream data if not)
303            //
304            // The reason we don't check that here is because stream_rx multiplexes stream data
305            // from all hops, and we have no way of knowing which hop will want to send us stream
306            // data next, and therefore we can't know which hop's CC object to use
307            self.stream_rx.next().await.map(CircuitEvent::Send)
308        });
309
310        //  2. the stream of commands coming from the ForwardReactor
311        //  (this resolves to a BackwardReactorCmd)
312        poll_all.push(async {
313            let event = match self.forward_reactor_rx.next().await {
314                Some(cmd) => CircuitEvent::Forwarded(cmd),
315                None => {
316                    // The forward reactor has crashed, so we have to shut down.
317                    CircuitEvent::ForwardShutdown
318                }
319            };
320
321            Some(event)
322        });
323
324        // 3. Messages moving from the outbound channel towards the inbound Tor channel,
325        // if we have an outbound Tor channel.
326        //
327        // NOTE: in practice, clients and exits won't have an outbound Tor channel,
328        // so for them this will be a no-op.
329        poll_all.push(async {
330            let event = if let Some(outbound_chan_rx) = self.outbound_chan_rx.as_mut() {
331                // Forward channel unexpectedly closed, we should close too
332                match outbound_chan_rx.next().await {
333                    Some(msg) => match msg.try_into() {
334                        Err(e) => CircuitEvent::ProtoViolation(e),
335                        Ok(cell) => CircuitEvent::Cell(cell),
336                    },
337                    None => {
338                        // The forward reactor has crashed, so we have to shut down.
339                        CircuitEvent::ForwardShutdown
340                    }
341                }
342            } else {
343                future::pending().await
344            };
345
346            Some(event)
347        });
348
349        let poll_all = async move {
350            // Avoid polling **any** of the futures if the outgoing sink is blocked.
351            //
352            // This implements backpressure: we avoid reading from our input sources
353            // if we know we're unable to write to the inbound Tor channel sink.
354            //
355            // More specifically, if our inbound Tor channel sink is full and can no longer
356            // accept cells, we stop reading:
357            //
358            //   1. From the application streams (received from StreamReactor), if there are any.
359            //
360            //   2. From the forward_reactor_rx channel, used by the forward reactor to send us
361            //
362            //     - a circuit-level SENDME that we have received, or
363            //     - a circuit-level SENDME that we need to deliver to the client
364            //
365            //     Not reading from the forward_reactor_rx channel, in turn, causes the forward reactor
366            //     to block and therefore stop reading from **its** input sources,
367            //     propagating backpressure all the way to the other endpoint of the circuit.
368            //
369            //   3. From the outbound Tor channel, if there is one.
370            //
371            // This will delay any SENDMEs the client or exit might have sent along
372            // the way, and therefore count as a congestion signal.
373            //
374            // TODO: memquota setup to make sure this doesn't turn into a memory DOS vector
375            let _ = backward_chan_ready.await;
376
377            // TODO: it's important to not block reading from the forward_reactor_rx channel on the chan
378            // sender readiness (for instance, we should not block the sending of SENDMEs
379            // if the channel is blocked on a padding-induced block).
380            //
381            // This means we will need to move the forward_reactor_rx handling out of the PollAll
382            // to the select_biased! below.
383            poll_all.await
384        };
385
386        let events = select_biased! {
387            res = self.command_rx.next().fuse() => {
388                let cmd = res.ok_or_else(|| ReactorError::Shutdown)?;
389                self.handle_cmd(cmd)?;
390                return Ok(());
391            }
392            res = self.control_rx.next().fuse() => {
393                let msg = res.ok_or_else(|| ReactorError::Shutdown)?;
394                if let Some(new_msg) = self.handle_msg(msg)? {
395                    let mut events = <PollAll::<_, _> as Future>::Output::new();
396                    events.push(Some(CircuitEvent::Send(new_msg)));
397                    events
398                } else {
399                    return Ok(());
400                }
401            }
402            res = self.padding_event_stream.next().fuse() => {
403                // If there's a padding event, we need to handle it immediately,
404                // because it might tell us to start blocking the inbound_chan_tx sink,
405                // which, in turn, means we need to stop trying to read from
406                // the application streams.
407                let event = res.ok_or_else(|| ReactorError::Shutdown)?;
408
409                cfg_if::cfg_if! {
410                    if #[cfg(feature = "circ-padding")] {
411                        self.run_padding_event(event).await?;
412                    } else {
413                        // If padding isn't enabled, we never generate a padding event,
414                        // so we can be sure this case will never be called.
415                        void::unreachable(event.0);
416                    }
417                }
418                return Ok(())
419            }
420            res = poll_all.fuse() => res,
421        };
422
423        // Note: there shouldn't be more than N < PER_LOOP_EVENT_COUNT events to handle
424        // per reactor loop. We need to be careful here, because we must avoid blocking
425        // the reactor.
426        //
427        // If handling more than one event per loop turns out to be a problem, we may
428        // need to dispatch this to a background task instead.
429        //
430        // TODO(relay): this loop is actually a problem.
431        // As mentioned in the run_once() docs, this will attempt to send up
432        // to 3 cells on the inbound tor Channel (or 2 cells, assuming no leaky pipe).
433        //
434        // The problem is that the readiness check above (see backward_chan_ready)
435        // only checks that the queue has enough room for 1 cell, not *2 cells*.
436        // Trying to send more than 2 cell when there is only room for one
437        // will cause the reactor to block (and because there is nothing
438        // driving the flushing of this channel, this will be a hard block).
439        //
440        // We need to rethink the strategy here (e.g. by flushing in parallel
441        // with handle_event())
442        for event in events.into_iter().flatten() {
443            self.handle_event(event).await?;
444        }
445
446        Ok(())
447    }
448
449    /// Handle a control command.
450    fn handle_cmd(&mut self, cmd: CtrlCmd<B::CtrlCmd>) -> StdResult<(), ReactorError> {
451        match cmd {
452            CtrlCmd::Custom(c) => self.inner.handle_cmd(c),
453        }
454    }
455
456    /// Handle a control message.
457    ///
458    /// This may result in a new stream message that needs to be sent backward.
459    fn handle_msg(
460        &mut self,
461        msg: CtrlMsg<B::CtrlMsg>,
462    ) -> StdResult<Option<ReadyStreamMsg>, ReactorError> {
463        match msg {
464            CtrlMsg::Custom(c) => {
465                // In the future we may also want `inner.handle_msg(c)` to return an
466                // `Option<ReadyStreamMsg>`, and we can pass it through.
467                let () = self.inner.handle_msg(c)?;
468                Ok(None)
469            }
470            CtrlMsg::FlowCtrlUpdate {
471                hop,
472                stream_id,
473                msg,
474            } => match msg {
475                FlowCtrlMsg::Sendme => {
476                    // Congestion control decides if we can send stream level SENDMEs or not.
477                    let (cell_fmt, cc) = self.hop_info(hop)?;
478                    let uses_stream_sendme = cc.lock().expect("poisoned").uses_stream_sendme();
479
480                    if !uses_stream_sendme {
481                        // Nothing to do, so discard the SENDME.
482                        //
483                        // TODO(arti#2068): We should do something better here,
484                        // like ensure that nothing sends `FlowCtrlMsg::Sendme` when it shouldn't,
485                        // and making this an error instead.
486                        return Ok(None);
487                    }
488
489                    let sendme = Sendme::new_empty();
490                    let msg = AnyRelayMsgOuter::new(Some(stream_id), sendme.into());
491
492                    Ok(Some(ReadyStreamMsg {
493                        hop,
494                        msg,
495                        relay_cell_format: cell_fmt,
496                        ccontrol: Arc::clone(&cc),
497                    }))
498                }
499            },
500        }
501    }
502
503    /// Perform some circuit-padding-based event on the specified circuit.
504    //
505    // TODO(DEDUP): this is almost identical to the client-side Conflux::run_padding_event()
506    #[cfg(feature = "circ-padding")]
507    async fn run_padding_event(
508        &mut self,
509        padding_event: PaddingEvent,
510    ) -> StdResult<(), ReactorError> {
511        use PaddingEvent as E;
512
513        match padding_event {
514            E::SendPadding(send_padding) => {
515                self.send_padding(send_padding).await?;
516            }
517            E::StartBlocking(start_blocking) => {
518                self.start_blocking_for_padding(start_blocking);
519            }
520            E::StopBlocking => {
521                self.stop_blocking_for_padding();
522            }
523        }
524        Ok(())
525    }
526
527    /// Handle a request from our padding subsystem to send a padding packet.
528    //
529    // TODO(DEDUP): this is almost identical to the client-side Client::send_padding()
530    #[cfg(feature = "circ-padding")]
531    async fn send_padding(&mut self, send_padding: padding::SendPadding) -> Result<()> {
532        use CircPaddingDisposition::*;
533
534        let target_hop = send_padding.hop;
535
536        match padding_disposition(
537            &send_padding,
538            &self.inbound_chan_tx,
539            self.padding_block.as_ref(),
540        ) {
541            QueuePaddingNormally => {
542                let queue_info = self.padding_ctrl.queued_padding(target_hop, send_padding);
543                self.queue_padding_cell_for_hop(target_hop, queue_info)
544                    .await?;
545            }
546            QueuePaddingAndBypass => {
547                let queue_info = self.padding_ctrl.queued_padding(target_hop, send_padding);
548                self.queue_padding_cell_for_hop(target_hop, queue_info)
549                    .await?;
550            }
551            TreatQueuedCellAsPadding => {
552                self.padding_ctrl
553                    .replaceable_padding_already_queued(target_hop, send_padding);
554            }
555        }
556        Ok(())
557    }
558
559    /// Enable padding-based blocking,
560    /// or change the rule for padding-based blocking to the one in `block`.
561    //
562    // TODO(DEDUP): copy of Client::start_blocking_for_padding()
563    #[cfg(feature = "circ-padding")]
564    pub(super) fn start_blocking_for_padding(&mut self, block: padding::StartBlocking) {
565        self.inbound_chan_tx.start_blocking();
566        self.padding_block = Some(block);
567    }
568
569    /// Disable padding-based blocking.
570    ///
571    // TODO(DEDUP): copy of Client::stop_blocking_for_padding()
572    #[cfg(feature = "circ-padding")]
573    pub(super) fn stop_blocking_for_padding(&mut self) {
574        self.inbound_chan_tx.stop_blocking();
575        self.padding_block = None;
576    }
577
578    /// Generate and encrypt a padding cell, and send it to a targeted hop.
579    ///
580    /// Ignores any padding-based blocking.
581    ///
582    // TODO(DEDUP): copy of Client::queue_padding_cell_for_hop()
583    #[cfg(feature = "circ-padding")]
584    async fn queue_padding_cell_for_hop(
585        &mut self,
586        target_hop: HopNum,
587        queue_info: Option<QueuedCellPaddingInfo>,
588    ) -> Result<()> {
589        use tor_cell::relaycell::msg::Drop as DropMsg;
590
591        let msg = AnyRelayMsgOuter::new(None, DropMsg::default().into());
592        let hopnum = Some(target_hop);
593
594        // TODO: the ccontrol state isn't actually needed here, because
595        // DROP cells don't count towards SENDME windows.
596        // Technically, we could avoid unnecessarily Arc::clone()ing the CC state
597        // here, and just extract the relay cell format.
598        // But for that we would need a specialized send_relay_cell_inner()-like function
599        // that doesn't take a CC object, or to make the CC object optional in
600        // send_relay_cell_inner().
601        let (relay_cell_format, ccontrol) = self.hop_info(hopnum)?;
602
603        self.send_relay_cell_inner(hopnum, relay_cell_format, msg, false, &ccontrol, queue_info)
604            .await
605    }
606
607    /// Determine how exactly to handle a request to handle padding.
608    #[cfg(feature = "circ-padding")]
609    #[allow(unused)] // TODO(relay)
610    fn padding_disposition(&self, send_padding: &padding::SendPadding) -> CircPaddingDisposition {
611        crate::circuit::padding::padding_disposition(
612            send_padding,
613            &self.inbound_chan_tx,
614            self.padding_block.as_ref(),
615        )
616    }
617
618    /// Handle a circuit event.
619    async fn handle_event(
620        &mut self,
621        event: CircuitEvent<B::CircChanMsg>,
622    ) -> StdResult<(), ReactorError> {
623        use CircuitEvent::*;
624
625        match event {
626            Cell(cell) => self.handle_backward_cell(cell).await,
627            Send(msg) => {
628                let ReadyStreamMsg {
629                    hop,
630                    relay_cell_format,
631                    msg,
632                    ccontrol,
633                } = msg;
634
635                self.send_relay_cell(hop, relay_cell_format, msg, false, &ccontrol)
636                    .await?;
637
638                Ok(())
639            }
640            Forwarded(cmd) => self.handle_reactor_cmd(cmd).await,
641            ForwardShutdown => {
642                // The forward reactor has crashed, so we have to shut down.
643                trace!(
644                    circ_uniq_id = %self.unique_id,
645                    backward_circ_id = %self.circ_id,
646                    "Backward relay reactor shutdown (forward reactor has closed)",
647                );
648
649                Err(ReactorError::Shutdown)
650            }
651            ProtoViolation(err) => Err(err.into()),
652        }
653    }
654
655    /// Return the RelayCellFormat and CC state of a given hop.
656    fn hop_info(
657        &self,
658        hopnum: Option<HopNum>,
659    ) -> Result<(RelayCellFormat, Arc<Mutex<CongestionControl>>)> {
660        let hops = self.hops.read().expect("poisoned lock");
661        let hop = hops.get(hopnum)?;
662        let relay_cell_format = hop.settings.relay_crypt_protocol().relay_cell_format();
663        let ccontrol = Arc::clone(&hop.ccontrol);
664
665        Ok((relay_cell_format, ccontrol))
666    }
667
668    /// Handle a command sent to us by the forward reactor.
669    async fn handle_reactor_cmd(&mut self, msg: BackwardReactorCmd) -> StdResult<(), ReactorError> {
670        use BackwardReactorCmd::*;
671
672        match msg {
673            SendRelayMsg { hop, msg } => {
674                self.send_relay_msg(hop, msg).await?;
675            }
676            HandleSendme { hop, sendme } => {
677                self.handle_sendme(hop, sendme).await?;
678                return Ok(());
679            }
680            #[cfg(feature = "relay")]
681            HandleCircuitExtended {
682                hop,
683                extended2,
684                outbound_chan_rx,
685            } => {
686                self.outbound_chan_rx = Some(outbound_chan_rx);
687                let msg = AnyRelayMsgOuter::new(None, extended2.into());
688                self.send_relay_msg(hop, msg).await?;
689
690                debug!(
691                    circ_uniq_id = %self.unique_id,
692                    backward_circ_id = %self.circ_id,
693                    "Extended circuit to the next hop"
694                );
695            }
696        }
697
698        Ok(())
699    }
700
701    /// Send a relay message to the specified hop.
702    async fn send_relay_msg(
703        &mut self,
704        hopnum: Option<HopNum>,
705        msg: AnyRelayMsgOuter,
706    ) -> StdResult<(), ReactorError> {
707        let (relay_cell_format, ccontrol) = self.hop_info(hopnum)?;
708        let cmd = msg.cmd();
709
710        // TODO(relay): remove this log once we add some tests
711        // and confirm relaying cells works as expected
712        // (in practice it will be too noisy to be useful, even at trace level).
713        trace!(
714            circ_uniq_id = %self.unique_id,
715            backward_circ_id = %self.circ_id,
716            hopnum=?hopnum,
717            cmd = %cmd,
718            "Sending backward cell"
719        );
720
721        self.send_relay_cell(hopnum, relay_cell_format, msg, false, &ccontrol)
722            .await?;
723
724        if cmd == RelayCmd::SENDME {
725            // TODO: does note_sendme_sent() need to be fallible?
726            // Neither Vegas nor the fixed-window impl ever return Err
727            ccontrol.lock().expect("poisoned lock").note_sendme_sent()?;
728        }
729
730        Ok(())
731    }
732
733    /// Handle a circuit-level SENDME (stream ID = 0).
734    ///
735    /// Returns an error if the SENDME does not have an authentication tag
736    /// (versions of Tor <=0.3.5 omit the SENDME tag, but we don't support
737    /// those any longer).
738    ///
739    /// Any error returned from this function will shut down the reactor.
740    ///
741    // TODO(DEDUP): duplicates the logic from the client-side Circuit::handle_sendme()
742    async fn handle_sendme(
743        &mut self,
744        hopnum: Option<HopNum>,
745        sendme: Sendme,
746    ) -> StdResult<(), ReactorError> {
747        let tag = sendme
748            .into_sendme_tag()
749            .ok_or_else(|| Error::CircProto("missing tag on circuit sendme".into()))?;
750
751        // NOTE: it's okay to await. We are only awaiting on the congestion_signals
752        // future which *should* resolve immediately
753        let signals = self.inbound_chan_tx.congestion_signals().await;
754
755        let hops = self.hops.read().expect("poisoned lock");
756        let hop = hops.get(hopnum)?;
757
758        // Update the CC object that we received a SENDME along
759        // with possible congestion signals.
760        hop.ccontrol
761            .lock()
762            .expect("poisoned lock")
763            .note_sendme_received(&self.time_provider, tag, signals)?;
764
765        Ok(())
766    }
767
768    /// Encode `msg` and encrypt it, returning the resulting cell
769    /// and tag that should be expected for an authenticated SENDME sent
770    /// in response to that cell.
771    ///
772    // TODO(DEDUP): duplicates the logic from the client-side Circuit::encode_relay_cell()
773    fn encode_relay_cell(
774        &mut self,
775        relay_format: RelayCellFormat,
776        hop: Option<HopNum>,
777        early: bool,
778        msg: AnyRelayMsgOuter,
779    ) -> Result<(AnyChanMsg, SendmeTag)> {
780        let mut body: RelayCellBody = msg
781            .encode(relay_format, &mut rand::rng())
782            .map_err(|e| Error::from_cell_enc(e, "relay cell body"))?
783            .into();
784        let cmd = if early {
785            ChanCmd::RELAY_EARLY
786        } else {
787            ChanCmd::RELAY
788        };
789
790        // Use the implementation-dependent encryption logic
791        let tag = self.inner.encrypt_relay_cell(cmd, &mut body, hop);
792        let msg = Relay::from(BoxedCellBody::from(body));
793        let msg = if early {
794            AnyChanMsg::RelayEarly(msg.into())
795        } else {
796            AnyChanMsg::Relay(msg)
797        };
798
799        Ok((msg, tag))
800    }
801
802    /// Encode `msg`, encrypt it, and send it to the 'hop'th hop.
803    ///
804    /// If there is insufficient outgoing *circuit-level* or *stream-level*
805    /// SENDME window, an error is returned instead.
806    ///
807    /// Does not check whether the cell is well-formed or reasonable.
808    async fn send_relay_cell(
809        &mut self,
810        hop: Option<HopNum>,
811        relay_cell_format: RelayCellFormat,
812        msg: AnyRelayMsgOuter,
813        early: bool,
814        ccontrol: &Arc<Mutex<CongestionControl>>,
815    ) -> Result<()> {
816        self.send_relay_cell_inner(hop, relay_cell_format, msg, early, ccontrol, None)
817            .await
818    }
819
820    /// As [`send_relay_cell`](Self::send_relay_cell), but takes an optional
821    /// [`QueuedCellPaddingInfo`] in `padding_info`.
822    ///
823    /// If `padding_info` is None, `msg` must be non-padding: we report it as such to the
824    /// padding controller.
825    ///
826    // TODO(DEDUP): this contains parts of Circuit::send_relay_cell_inner()
827    async fn send_relay_cell_inner(
828        &mut self,
829        hop: Option<HopNum>,
830        relay_cell_format: RelayCellFormat,
831        msg: AnyRelayMsgOuter,
832        early: bool,
833        ccontrol: &Arc<Mutex<CongestionControl>>,
834        padding_info: Option<QueuedCellPaddingInfo>,
835    ) -> Result<()> {
836        let c_t_w = sendme::cmd_counts_towards_windows(msg.cmd());
837        let (msg, tag) = self.encode_relay_cell(relay_cell_format, hop, early, msg)?;
838        let cell = AnyChanCell::new(Some(self.circ_id), msg);
839
840        // TODO: we use HopNum(0) if we're a relay (i.e. if the hop is None).
841        // Is that ok?
842        let hop = hop.unwrap_or_else(|| HopNum::from(0));
843        // Remember that we've enqueued this cell.
844        let padding_info = padding_info.or_else(|| self.padding_ctrl.queued_data(hop));
845
846        // Note: this future is always `Ready`, because we checked the sink for readiness
847        // before polling the async streams, so await won't block.
848        Pin::new(&mut self.inbound_chan_tx)
849            .send_unbounded((cell, padding_info))
850            .await?;
851
852        if c_t_w {
853            ccontrol
854                .lock()
855                .expect("poisoned lock")
856                .note_data_sent(&self.time_provider, &tag)?;
857        }
858
859        Ok(())
860    }
861
862    /// Handle a backward cell (moving from the exit towards the client).
863    async fn handle_backward_cell(&mut self, cell: B::CircChanMsg) -> StdResult<(), ReactorError> {
864        match self
865            .inner
866            .handle_backward_cell(self.unique_id, self.circ_id, cell)?
867        {
868            BackwardCellDisposition::Forward(cell) => {
869                let cell = AnyChanCell::new(Some(self.circ_id), cell);
870                self.inbound_chan_tx
871                    .send((cell, None))
872                    .await
873                    .map_err(ReactorError::Err)
874            }
875        }
876    }
877}
878
879impl<B: BackwardHandler> Drop for BackwardReactor<B> {
880    fn drop(&mut self) {
881        // This will send a DESTROY down the inbound Tor channel
882        let _ = self.channel.close_circuit(self.circ_id);
883    }
884}
885
886/// A circuit event that must be handled by the [`BackwardReactor`].
887enum CircuitEvent<M> {
888    /// We received a cell that needs to be handled.
889    ///
890    /// (The cell is client-bound if we are a relay, or exit-bound if we are a client).
891    Cell(M),
892    /// A stream has a RELAY cell that needs
893    /// to be packaged and written to our Tor channel.
894    ///
895    /// (The message is client-bound if we are a relay, or exit-bound if we are a client).
896    Send(ReadyStreamMsg),
897    /// We received a cell from the ForwardReactor that we need to handle.
898    ///
899    /// This might be
900    ///
901    ///   * a circuit-level SENDME that we have received, or
902    ///   * a circuit-level SENDME that we need to deliver to the client
903    Forwarded(BackwardReactorCmd),
904    /// The forward reactor has shut down.
905    ///
906    /// We need to shut down too.
907    ForwardShutdown,
908    /// Protocol violation.
909    ///
910    /// This can happen if we receive a channel message that is not supported on the channel.
911    ProtoViolation(Error),
912}
913
914/// Instructions from the forward reactor.
915pub(crate) enum BackwardReactorCmd {
916    /// A circuit SENDME we received from the other endpoint.
917    HandleSendme {
918        /// The hop the SENDME came on.
919        hop: Option<HopNum>,
920        /// The SENDME.
921        sendme: Sendme,
922    },
923    /// A message we need to send back to the other endpoint.
924    SendRelayMsg {
925        /// The hop to encode the message for.
926        hop: Option<HopNum>,
927        /// The message to send.
928        msg: AnyRelayMsgOuter,
929    },
930    /// This relay circuit was extended by another hop.
931    ///
932    /// This causes the reactor send the `extended2` message on its inbound channel,
933    /// and start reading from `outbound_chan_rx` in the main loop.
934    //
935    ///
936    // TODO: I wish we didn't need to expose this relay-specific variant
937    // in the generic reactor but we have no choice: abstracting it away
938    // means either introducing a mutex between the relay-side forward/backward
939    // handlers, or yet another mpsc between them.
940    #[cfg(feature = "relay")]
941    HandleCircuitExtended {
942        /// The hop to encode the message for.
943        ///
944        /// In practice, this is always None, because only relays use this.
945        hop: Option<HopNum>,
946        /// The cell to send to the specified hop,
947        extended2: Extended2,
948        /// The reading end of the outbound Tor channel, if we are not the last hop.
949        ///
950        /// Yields cells moving from the exit towards the client, if we are a middle relay.
951        outbound_chan_rx: CircuitRxReceiver,
952    },
953}
954
955/// A flow control update message.
956///
957/// TODO(DEDUP): This is a duplicate of the client's
958/// `crate::client::reactor::control::FlowCtrlMsg`.
959#[derive(Debug)]
960pub(crate) enum FlowCtrlMsg {
961    /// Send a SENDME message on this stream.
962    Sendme,
963}