tor_proto/tunnel/
msghandler.rs

Help
1//! A message handler trait for use with
2//! [`ClientCirc::start_conversation`](super::ClientCirc::start_conversation).
3//!
4//! Although this is similar to `stream::cmdcheck`, I am deliberately leaving
5//! them separate. Conceivably they should be unified at some point down the
6//! road?
7use tor_cell::relaycell::msg::AnyRelayMsg;
8use tor_cell::relaycell::{AnyRelayMsgOuter, RelayMsg, UnparsedRelayMsg};
9
10use crate::{Error, Result};
11
12use crate::tunnel::reactor::MetaCellDisposition;
13
14use super::HopLocation;
15
16/// An object that checks whether incoming control messages are acceptable on a
17/// circuit, and delivers them to a client if so.
18///
19/// The handler is supplied to
20/// [`ClientCirc::start_conversation`](super::ClientCirc::start_conversation).  It
21/// is used to check any incoming message whose stream ID is 0, and which would
22/// otherwise not be accepted on a given circuit.
23///
24/// (The messages that `tor-proto` will handle on its own, and _not_ deliver, are
25/// are DESTROY, DATA, SENDME, ...)  Ordinarily, any unexpected control
26/// message will cause the circuit to exit with an error.
27pub trait MsgHandler {
28    /// Check whether this message is an acceptable one to receive in reply to
29    /// our command, and handle it if so.
30    ///
31    /// Typically, this handler should perform only simple checks, before
32    /// delivering the message to another task via some kind of channel if
33    /// further processing is needed.
34    ///
35    /// In particular,
36    /// if the circuit might be in use for anything else
37    /// (eg there might be concurrent data flow)
38    /// the implementor should avoid any expensive computations
39    /// or highly contended locks, to avoid blocking the circuit reactor.
40    ///
41    /// If this function returns an error, the circuit will be closed.
42    fn handle_msg(&mut self, msg: AnyRelayMsg) -> Result<MetaCellDisposition>;
43}
44
45/// Wrapper for `MsgHandler` to implement `MetaCellHandler`
46pub(crate) struct UserMsgHandler<T> {
47    /// From which hop to we expect to get messages?
48    hop: HopLocation,
49    /// The handler itself.
50    handler: T,
51}
52
53impl<T> UserMsgHandler<T> {
54    /// Create a new UserMsgHandler to be the MetaCellHandler for incoming
55    /// control messages a given circuit.
56    pub(crate) fn new(hop: HopLocation, handler: T) -> Self {
57        Self { hop, handler }
58    }
59}
60
61impl<T: MsgHandler + Send> super::reactor::MetaCellHandler for UserMsgHandler<T> {
62    fn expected_hop(&self) -> HopLocation {
63        self.hop
64    }
65
66    fn handle_msg(
67        &mut self,
68        msg: UnparsedRelayMsg,
69        _reactor: &mut super::reactor::circuit::Circuit,
70    ) -> Result<MetaCellDisposition> {
71        let cell: AnyRelayMsgOuter = msg.decode().map_err(|err| Error::BytesErr {
72            object: "cell for message handler",
73            err,
74        })?;
75        let (stream_id, msg) = cell.into_streamid_and_msg();
76        if stream_id.is_some() {
77            return Err(Error::CircProto(format!(
78                "Invalid message type {} received with stream ID",
79                msg.cmd()
80            )));
81        }
82        self.handler.handle_msg(msg)
83    }
84}
tor_proto/tunnel/msghandler.rs

tor_proto/tunnel/
msghandler.rs
