tor_chanmgr/transport.rs
1//! Code to define the notion of a "Transport" and implement a default transport.
2
3use async_trait::async_trait;
4use futures::{AsyncRead, AsyncWrite};
5use tor_linkspec::OwnedChanTarget;
6
7pub(crate) mod default;
8pub mod proxied;
9
10pub(crate) use default::DefaultTransport;
11
12#[cfg(feature = "pt-client")]
13#[cfg_attr(docsrs, doc(cfg(feature = "experimental-api")))]
14pub use proxied::ExternalProxyPlugin;
15pub use proxied::ProxyError;
16use tor_proto::peer::PeerAddr;
17use tor_rtcompat::StreamOps;
18
19/// A convenient API for defining transports for use in Tor and elsewhere.
20///
21/// This type's role is to let the implementor just define a replacement way to
22/// pass bytes around, and return something that we can use in place of a
23/// TcpStream.
24///
25/// This is the trait you should probably implement if you want to define a new
26/// [`ChannelFactory`](crate::factory::ChannelFactory) that performs Tor over
27/// TLS over some stream-like type, and you only want to define the stream-like
28/// type.
29///
30/// To convert a [`TransportImplHelper`] into a
31/// [`ChannelFactory`](crate::factory::ChannelFactory), wrap it in a
32/// `ChanBuilder`.
33//
34// TODO: Maybe move this to a separate crate so that tor-ptmgr can be
35// used without having to depend on chanmgr.
36#[async_trait]
37pub trait TransportImplHelper {
38 /// The type of the resulting stream.
39 type Stream: AsyncRead + AsyncWrite + StreamOps + Send + Sync + 'static;
40
41 /// Implements the transport: make a TCP connection (possibly tunneled over
42 /// whatever protocol) if possible.
43 ///
44 /// This method does does not necessarily handle retries or timeouts,
45 /// although some of its implementations may.
46 ///
47 /// This method does not necessarily handle every kind of transport. If the
48 /// caller provides a target with the wrong
49 /// [`TransportId`](tor_linkspec::TransportId), this method should return
50 /// [`Error::NoSuchTransport`](crate::Error::NoSuchTransport).
51 async fn connect(&self, target: &OwnedChanTarget) -> crate::Result<(PeerAddr, Self::Stream)>;
52}