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_rtcompat::StreamOps;
17
18/// A convenient API for defining transports for use in Tor and elsewhere.
19///
20/// This type's role is to let the implementor just define a replacement way to
21/// pass bytes around, and return something that we can use in place of a
22/// TcpStream.
23///
24/// This is the trait you should probably implement if you want to define a new
25/// [`ChannelFactory`](crate::factory::ChannelFactory) that performs Tor over
26/// TLS over some stream-like type, and you only want to define the stream-like
27/// type.
28///
29/// To convert a [`TransportImplHelper`] into a
30/// [`ChannelFactory`](crate::factory::ChannelFactory), wrap it in a
31/// `ChanBuilder`.
32//
33// TODO: Maybe move this to a separate crate so that tor-ptmgr can be
34// used without having to depend on chanmgr.
35#[async_trait]
36pub trait TransportImplHelper {
37 /// The type of the resulting stream.
38 type Stream: AsyncRead + AsyncWrite + StreamOps + Send + Sync + 'static;
39
40 /// Implements the transport: make a TCP connection (possibly tunneled over
41 /// whatever protocol) if possible.
42 ///
43 /// This method does does not necessarily handle retries or timeouts,
44 /// although some of its implementations may.
45 ///
46 /// This method does not necessarily handle every kind of transport. If the
47 /// caller provides a target with the wrong
48 /// [`TransportId`](tor_linkspec::TransportId), this method should return
49 /// [`Error::NoSuchTransport`](crate::Error::NoSuchTransport).
50 async fn connect(
51 &self,
52 target: &OwnedChanTarget,
53 ) -> crate::Result<(OwnedChanTarget, Self::Stream)>;
54}