From d80f3198ea73b619060ae6891c9ca52b60edbe88 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 1 Mar 2022 11:30:20 +0000 Subject: [PATCH 1/4] arti-client: Add stability warning to config module --- crates/arti-client/src/config.rs | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/crates/arti-client/src/config.rs b/crates/arti-client/src/config.rs index 9344773bc..96aee60d1 100644 --- a/crates/arti-client/src/config.rs +++ b/crates/arti-client/src/config.rs @@ -1,6 +1,15 @@ //! Types and functions to configure a Tor client. //! //! Some of these are re-exported from lower-level crates. +//! +/// # ⚠ Stability Warning ⚠ +/// +/// The design of this structure, and of the configuration system for +/// Arti, is likely to change significantly before the release of Arti +/// 1.0.0. The layout of options within this structure is also likely +/// to change. For more information see ticket [#285]. +/// +/// [#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285 use derive_builder::Builder; use serde::Deserialize; From 5533fef4f39727c69aabf6d7e9e3e02d92c59033 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 1 Mar 2022 11:42:14 +0000 Subject: [PATCH 2/4] arti-hyper: Drop obsolete comment about not doing TLS --- crates/arti-hyper/src/lib.rs | 2 -- 1 file changed, 2 deletions(-) diff --git a/crates/arti-hyper/src/lib.rs b/crates/arti-hyper/src/lib.rs index f321eacfe..80dd5baf1 100644 --- a/crates/arti-hyper/src/lib.rs +++ b/crates/arti-hyper/src/lib.rs @@ -93,8 +93,6 @@ impl tor_error::HasKind for ConnectionError { /// A `hyper` connector to proxy HTTP connections via the Tor network, using Arti. /// -/// Only supports plaintext HTTP for now. -/// /// TC is the TLS to used *across* Tor to connect to the origin server. /// This is a different Rust type to the TLS used *by* Tor to connect to relays etc. /// It might even be a different underlying TLS implementation From b083ae661e6d2862b38cfc15aee022b9aed4dca3 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 1 Mar 2022 11:52:59 +0000 Subject: [PATCH 3/4] arti-hyper: Expand docs --- crates/arti-hyper/src/lib.rs | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/crates/arti-hyper/src/lib.rs b/crates/arti-hyper/src/lib.rs index 80dd5baf1..643a52f07 100644 --- a/crates/arti-hyper/src/lib.rs +++ b/crates/arti-hyper/src/lib.rs @@ -91,9 +91,15 @@ impl tor_error::HasKind for ConnectionError { } } -/// A `hyper` connector to proxy HTTP connections via the Tor network, using Arti. +/// **Main entrypoint**: `hyper` connector to make HTTP\[S] connections via Tor, using Arti. +/// +/// An `ArtiHttpConnector` combines an Arti Tor client, and a TLS implementation, +/// in a form that can be provided to hyper +/// (e.g. to [`hyper::client::Builder`]'s `build` method) +/// so that hyper can speak HTTP and HTTPS to origin servers via Tor. /// /// TC is the TLS to used *across* Tor to connect to the origin server. +/// For example, it could be a [`tls_api_native_tls::TlsConnector`]. /// This is a different Rust type to the TLS used *by* Tor to connect to relays etc. /// It might even be a different underlying TLS implementation /// (although that is usually not a particularly good idea). @@ -124,6 +130,14 @@ impl ArtiHttpConnector { /// Wrapper type that makes an Arti `DataStream` implement necessary traits to be used as /// a `hyper` connection object (mainly `Connection`). +/// +/// This might represent a bare HTTP connection across Tor, +/// or it might represent an HTTPS connection through Tor to an origin server, +/// `TC::TlsStream` as the TLS layer. +/// +/// An `ArtiHttpConnection` is constructed by hyper's use of the [`ArtiHttpConnector`] +/// implementation of [`hyper::service::Service`], +/// and then used by hyper as the transport for hyper's HTTP implementation. #[pin_project] pub struct ArtiHttpConnection { /// The stream From 4fa78e3f440fc5a01eef11b78318755d6cb6a7bb Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 1 Mar 2022 11:08:52 +0000 Subject: [PATCH 4/4] arti-hyper: Upgrade from an example to an "adaptation layer" --- crates/arti-hyper/src/lib.rs | 8 ++++++++ doc/Architecture.md | 2 +- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/crates/arti-hyper/src/lib.rs b/crates/arti-hyper/src/lib.rs index 643a52f07..f39320a5b 100644 --- a/crates/arti-hyper/src/lib.rs +++ b/crates/arti-hyper/src/lib.rs @@ -1,4 +1,12 @@ //! High-level layer for making http(s) requests the Tor network as a client. +//! +//! This can be used by applications which embed Arti, +//! and could also be used as an example of how to build on top of [`arti_client`]. +//! +//! There is an example program [`hyper.rs`] which uses `arti-hyper` +//! to connect to Tor and make a single HTTP\[S] request. +//! +//! [`hyper.rs`]: #![deny(missing_docs)] #![warn(noop_method_call)] diff --git a/doc/Architecture.md b/doc/Architecture.md index 476a9c199..e14b5aa0e 100644 --- a/doc/Architecture.md +++ b/doc/Architecture.md @@ -107,7 +107,7 @@ before Arti 1.0.0. `arti-bench`: A testing crate for running performance tests. -`arti-hyper`: An example crate, using `arti_client` as a backend for the +`arti-hyper`: Adaptation layer for using `arti_client` as a backend for the `hyper` HTTP library. ## Design considerations, privacy considerations.