Merge branch 'high-level-features' into 'main'

Add "full" and "experimental" features to arti, arti-client, and below.

Closes #499

See merge request tpo/core/arti!584
This commit is contained in:
Nick Mathewson 2022-06-16 12:24:47 +00:00
commit 0223c91b26
13 changed files with 170 additions and 88 deletions

2
Cargo.lock generated
View File

@ -158,7 +158,9 @@ dependencies = [
"tokio",
"tokio-util",
"tor-basic-utils",
"tor-cell",
"tor-chanmgr",
"tor-checkable",
"tor-circmgr",
"tor-config",
"tor-dirmgr",

View File

@ -13,22 +13,31 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = ["tokio", "native-tls"]
# "full" is a top-level selector that turns on every feature, _EXCEPT FOR_:
# * Features that are experimental or unstable
# * Features that are testing-only
# * Features which are select a particular implementation or build flag and
# which therefore are not strictly additive.
# * Features which may introduce unnecessary licensing restrictions.
full = ["tokio", "async-std", "native-tls", "tor-rtcompat/full", "tor-proto/full", "tor-netdoc/full", "tor-dirmgr/full"]
async-std = ["tor-rtcompat/async-std"]
tokio = ["tor-rtcompat/tokio", "tor-proto/tokio"]
native-tls = ["tor-rtcompat/native-tls"]
rustls = ["tor-rtcompat/rustls"]
static = ["static-sqlite", "static-native-tls"]
static-sqlite = ["tor-dirmgr/static"]
static-native-tls = ["tor-rtcompat/static", "native-tls"]
dirfilter = ["tor-dirmgr/dirfilter"]
error_detail = []
# Enable experimental APIs that are not yet officially supported.
#
# These APIs are not covered by semantic versioning. Using this
# feature voids your "semver warrantee".
experimental = ["dirfilter", "experimental-api", "error_detail", "tor-proto/experimental", "tor-cell/experimental", "tor-checkable/experimental", "tor-netdoc/experimental", "tor-dirmgr/experimental", "tor-circmgr/experimental"]
experimental-api = []
dirfilter = ["tor-dirmgr/dirfilter"]
error_detail = []
[dependencies]
derive_builder = { version = "0.11.2", package = "derive_builder_fork_arti" }
@ -44,7 +53,9 @@ safelog = { path = "../safelog", version = "0.1.0" }
serde = { version = "1.0.103", features = ["derive"] }
thiserror = "1"
tor-basic-utils = { path = "../tor-basic-utils", version = "0.3.1" }
tor-cell = { path = "../tor-cell", version = "0.3.1" }
tor-chanmgr = { path = "../tor-chanmgr", version = "0.3.1" }
tor-checkable = { path = "../tor-checkable", version = "0.3.0" }
tor-circmgr = { path = "../tor-circmgr", version = "0.3.1" }
tor-config = { path = "../tor-config", version = "0.4.0" }
tor-dirmgr = { path = "../tor-dirmgr", version = "0.4.0" }

View File

@ -15,18 +15,17 @@
//!
//! Note that Arti is a work in progress; although we've tried to write all the
//! critical security components, you probably shouldn't use Arti in production
//! until it's a bit more mature. (That said, now is a _great_ time to try
//! our Arti on an experimental basis, so you can tell us what we need
//! to fix between now and the 1.0.0 release.)
//! until it's a bit more mature. (That said, now is a _great_ time to try our
//! Arti on an experimental basis, so you can tell us what we need to fix
//! between now and the 1.0.0 release.)
//!
//! Also note that the APIs for this crate are not all yet
//! completely stable. We'll try not to break things without good
//! reason, and we'll follow semantic versioning when we do, but
//! please expect a certain amount of breakage between now and 1.0.0.
//! Also note that the APIs for this crate are not all yet completely stable.
//! We'll try not to break things without good reason, and we'll follow semantic
//! versioning when we do, but please expect a certain amount of breakage
//! between now and 1.0.0.
//!
//! The APIs exposed by lower-level crates in Arti are _even more
//! unstable_; they will break more often than those from
//! `arti-client`, for less reason.
//! The APIs exposed by lower-level crates in Arti are _even more unstable_;
//! they will break more often than those from `arti-client`, for less reason.
//!
//! # Using `arti-client`
//!
@ -35,13 +34,13 @@
//!
//! ## Connecting to Tor
//!
//! Calling [`TorClient::create_bootstrapped`] establishes a connection to the Tor
//! network, pulling in necessary state about network consensus as required.
//! Calling [`TorClient::create_bootstrapped`] establishes a connection to the
//! Tor network, pulling in necessary state about network consensus as required.
//! This state gets persisted to the locations specified in the
//! [`TorClientConfig`].
//!
//! (This method requires you to initialize the client in an `async fn`. Consider
//! using the builder method, below, if that doesn't work for you.)
//! (This method requires you to initialize the client in an `async fn`.
//! Consider using the builder method, below, if that doesn't work for you.)
//!
//! ```no_run
//! # use anyhow::Result;
@ -63,12 +62,13 @@
//!
//! ## Creating a client and connecting later
//!
//! You might wish to create a Tor client immediately, without waiting for it to bootstrap (or
//! having to use an `await`). This can be done by making a [`TorClientBuilder`] with
//! [`TorClient::builder`], and calling [`TorClientBuilder::create_unbootstrapped`].
//! You might wish to create a Tor client immediately, without waiting for it to
//! bootstrap (or having to use an `await`). This can be done by making a
//! [`TorClientBuilder`] with [`TorClient::builder`], and calling
//! [`TorClientBuilder::create_unbootstrapped`].
//!
//! The returned client can be made to bootstrap when it is first used (the default), or not;
//! see [`BootstrapBehavior`] for more details.
//! The returned client can be made to bootstrap when it is first used (the
//! default), or not; see [`BootstrapBehavior`] for more details.
//!
//! ```no_run
//! # use anyhow::Result;
@ -155,35 +155,62 @@
//! runtimes; currently, both [Tokio](https://tokio.rs) and
//! [async-std](https://async.rs) are supported.
//!
//! The backend Arti uses for TCP connections ([`tor_rtcompat::TcpProvider`]) and for
//! creating TLS sessions ([`tor_rtcompat::TlsProvider`]) is also configurable using
//! this crate. This can be used to embed Arti in custom environments where you want
//! lots of control over how it uses the network.
//! The backend Arti uses for TCP connections ([`tor_rtcompat::TcpProvider`])
//! and for creating TLS sessions ([`tor_rtcompat::TlsProvider`]) is also
//! configurable using this crate. This can be used to embed Arti in custom
//! environments where you want lots of control over how it uses the network.
//!
//! [**View the `tor_rtcompat` crate documentation**](tor_rtcompat) for more about these features.
//! [**View the `tor_rtcompat` crate documentation**](tor_rtcompat) for more
//! about these features.
//!
//! # Feature flags
//!
//! * `tokio` (default) -- build with [Tokio](https://tokio.rs/) support
//! * `native-tls` (default) -- build with the [native-tls](https://github.com/sfackler/rust-native-tls)
//! crate for TLS support
//! * `async-std` -- build with [async-std](https://async.rs/) support
//! * `rustls` -- build with the [rustls](https://github.com/rustls/rustls) crate for TLS support
//! * `static` -- link with static versions of Arti's system dependencies, like SQLite and
//! OpenSSL (⚠ Warning ⚠: this feature will include a dependency on native-tls, even if you weren't
//! planning to use native-tls. If you only want to build with a static sqlite library, enable the
//! `static-sqlite` feature. We'll look for better solutions here in the future.)
//! * `static-sqlite` -- link with a static version of sqlite.
//! * `static-native-tls` -- link with a static version of `native-tls`. Enables `native-tls`.
//! * `experimental-api` -- build with experimental, unstable API support. Note
//! that these APIs are NOT covered by semantic versioning guarantees: we might
//! break them or remove them between patch versions.
//! * `error_detail` -- expose the `arti_client::Error` inner error type. Note
//! that this API is NOT covered by semantic versioning guarantees: we might
//! break it between patch versions.
//! ## Additive features
//!
//! Note that flags `tokio`, `native-tls`, `async-std`, `rustls` and `static` will enable
//! the flags of the same name on the [`tor_rtcompat`] crate.
//! * `tokio` (default) -- build with [Tokio](https://tokio.rs/) support
//! * `native-tls` (default) -- build with the
//! [native-tls](https://github.com/sfackler/rust-native-tls) crate for TLS
//! support
//! * `async-std` -- build with [async-std](https://async.rs/) support
//!
//! * `full` -- Build with all features above, along with all stable additive
//! features from other arti crates. (This does not include experimental
//! features. It also does not include features that select a particular
//! implementation to the exclusion of another, or those that set a build
//! flag.)
//!
//! * `rustls` -- build with the [rustls](https://github.com/rustls/rustls)
//! crate for TLS support. This is not included in `full`, since it uses the
//! `ring` crate, which uses the old (3BSD/SSLEay) OpenSSL license, which may
//! introduce licensing compatibility issues.
//!
//! Note that flags `tokio`, `native-tls`, `async-std`, `rustls` and `static`
//! will enable the flags of the same name on the [`tor_rtcompat`] crate.
//!
//! ## Build-flag related features
//!
//! * `static` -- link with static versions of Arti's system dependencies, like
//! SQLite and OpenSSL (⚠ Warning ⚠: this feature will include a dependency on
//! native-tls, even if you weren't planning to use native-tls. If you only
//! want to build with a static sqlite library, enable the `static-sqlite`
//! feature. We'll look for better solutions here in the future.)
//! * `static-sqlite` -- link with a static version of sqlite.
//! * `static-native-tls` -- link with a static version of `native-tls`. Enables
//! `native-tls`.
//!
//! ## Experimental and unstable features
//!
//! Note that the APIs enabled by these features are NOT covered by semantic
//! versioning guarantees: we might break them or remove them between patch
//! versions.
//!
//! * `experimental-api` -- build with experimental, unstable API support.
//! * `error_detail` -- expose the `arti_client::Error` inner error type.
//! * `dirfilter` -- expose the `DirFilter` API, which lets you modify a network
//! directory before it is used.
//!
//! * `experimental` -- Build with all experimental features above, along with
//! all experimental features from other arti crates.
// @@ begin lint list maintained by maint/add_warning @@
#![deny(missing_docs)]

View File

@ -13,6 +13,9 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = ["tokio", "native-tls"]
full = ["async-std", "tokio", "native-tls", "journald", "arti-client/full"]
async-std = ["arti-client/async-std", "tor-rtcompat/async-std", "async-ctrlc", "once_cell"]
tokio = ["tokio-crate", "arti-client/tokio", "tor-rtcompat/tokio"]
native-tls = ["arti-client/native-tls", "tor-rtcompat/native-tls"]
@ -22,6 +25,10 @@ static-sqlite = ["arti-client/static-sqlite"]
static-native-tls = ["arti-client/static-native-tls", "native-tls"]
journald = ["tracing-journald"]
# This feature flag enables experimental features that are not supported. Turning it on may
# void your API.
experimental = ["arti-client/experimental"]
[dependencies]
anyhow = "1.0.23"
arti-client = { package = "arti-client", path = "../arti-client", version = "0.4.0", default-features = false }

View File

@ -1,20 +1,20 @@
//! A minimal command line program for connecting to the tor network
//!
//! (If you want a more general Tor client library interface, use [`arti_client`].)
//! (If you want a more general Tor client library interface, use
//! [`arti_client`].)
//!
//! This crate is the primary command-line interface for
//! [Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to
//! implement [Tor](https://www.torproject.org/) in Rust.
//! Many other crates in Arti depend on it.
//! [Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to implement
//! [Tor](https://www.torproject.org/) in Rust. Many other crates in Arti depend
//! on it.
//!
//! Note that Arti is a work in progress; although we've tried to
//! write all the critical security components, you probably shouldn't
//! use Arti in production until it's a bit more mature.
//! Note that Arti is a work in progress; although we've tried to write all the
//! critical security components, you probably shouldn't use Arti in production
//! until it's a bit more mature.
//!
//! More documentation will follow as this program improves. For now,
//! just know that it can run as a simple SOCKS proxy over the Tor network.
//! It will listen on port 9150 by default, but you can override this in
//! the configuration.
//! More documentation will follow as this program improves. For now, just know
//! that it can run as a simple SOCKS proxy over the Tor network. It will listen
//! on port 9150 by default, but you can override this in the configuration.
//!
//! # Command-line interface
//!
@ -23,13 +23,13 @@
//! `arti` uses the [`clap`](https://docs.rs/clap/) crate for command-line
//! argument parsing; run `arti help` to get it to print its documentation.
//!
//! The only currently implemented subcommand is `arti proxy`; try
//! `arti help proxy` for a list of options you can pass to it.
//! The only currently implemented subcommand is `arti proxy`; try `arti help
//! proxy` for a list of options you can pass to it.
//!
//! # Configuration
//!
//! By default, `arti` looks for its configuration files in a
//! platform-dependent location.
//! By default, `arti` looks for its configuration files in a platform-dependent
//! location.
//!
//! | OS | Configuration File |
//! |---------|----------------------------------------------------|
@ -37,49 +37,68 @@
//! | macOS | `~/Library/Application Support/arti/arti.toml` |
//! | Windows | `\Users\<USERNAME>\AppData\Roaming\arti\arti.toml` |
//!
//! The configuration file is TOML. (We do not guarantee its stability.)
//! For an example see [`arti_defaults.toml`](./arti_defaults.toml).
//! The configuration file is TOML. (We do not guarantee its stability.) For an
//! example see [`arti_defaults.toml`](./arti_defaults.toml).
//!
//! # Compile-time features
//!
//! `tokio` (default): Use the tokio runtime library as our backend.
//! ## Additive features
//!
//! `async-std`: Use the async-std runtime library as our backend.
//! This feature has no effect unless building with `--no-default-features`
//! to disable tokio.
//! * `tokio` (default): Use the tokio runtime library as our backend.
//! * `async-std`: Use the async-std runtime library as our backend. This
//! feature has no effect unless building with `--no-default-features` to
//! disable tokio.
//! * `native-tls` -- Build with support for the `native_tls` TLS backend.
//! (default)
//! * `journald` -- Build with support for logging to the `journald` logging
//! backend (available as part of systemd.)
//!
//! `native-tls` -- Build with support for the `native_tls` TLS
//! backend. (default)
//! * `full` -- Build with all features above, along with all stable additive
//! features from other arti crates. (This does not include experimental
//! features. It also does not include features that select a particular
//! implementation to the exclusion of another, or those that set a build
//! flag.)
//!
//! `rustls` -- Build with support for the `rustls` TLS backend.
//! * `rustls` -- build with the [rustls](https://github.com/rustls/rustls)
//! TLS backend. This is not included in `full`, since it uses the
//! `ring` crate, which uses the old (3BSD/SSLEay) OpenSSL license, which may
//! introduce licensing compatibility issues.
//!
//! `static` -- Link with static versions of your system dependencies,
//! including sqlite and/or openssl. (⚠ Warning ⚠: this feature will
//! include a dependency on native-tls, even if you weren't planning
//! to use native-tls. If you only want to build with a static sqlite
//! library, enable the `static-sqlite` feature. We'll look for
//! better solutions here in the future.)
//! ## Build-flag related features
//!
//! `static-sqlite` -- Link with a static version of sqlite.
//! * `static` -- Link with static versions of your system dependencies,
//! including sqlite and/or openssl. (⚠ Warning ⚠: this feature will include
//! a dependency on native-tls, even if you weren't planning to use
//! native-tls. If you only want to build with a static sqlite library,
//! enable the `static-sqlite` feature. We'll look for better solutions here
//! in the future.)
//! * `static-sqlite` -- Link with a static version of sqlite.
//! * `static-native-tls` -- Link with a static version of `native-tls`. Enables
//! `native-tls`.
//!
//! `static-native-tls` -- Link with a static version of `native-tls`.
//! Enables `native-tls`.
//! ## Experimental features
//!
//! Note that the APIs enabled by these features are NOT covered by semantic
//! versioning guarantees: we might break them or remove them between patch
//! versions.
//!
//! * `experimental` -- Build with all experimental features above, along with
//! all experimental features from other arti crates.
//!
//! # Limitations
//!
//! There are many missing features. Among them: there's no onion
//! service support yet. There's no anti-censorship support. You
//! can't be a relay. There isn't any kind of proxy besides SOCKS.
//! There are many missing features. Among them: there's no onion service
//! support yet. There's no anti-censorship support. You can't be a relay.
//! There isn't any kind of proxy besides SOCKS.
//!
//! See the [README
//! file](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/README.md)
//! for a more complete list of missing features.
//! file](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/README.md) for
//! a more complete list of missing features.
//!
//! # Library for building command-line client
//!
//! This library crate contains code useful for making
//! a command line program similar to `arti`.
//! The API should not be considered stable.
//! This library crate contains code useful for making a command line program
//! similar to `arti`. The API should not be considered stable.
// @@ begin lint list maintained by maint/add_warning @@
#![deny(missing_docs)]

View File

@ -13,10 +13,11 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = []
experimental = ["experimental-udp"]
# Enable experimental UDP support.
experimental-udp = []
# Enable testing only API
testing = [ "experimental-udp" ]
testing = ["experimental-udp"]
[dependencies]
arrayref = "0.3"

View File

@ -12,6 +12,7 @@ categories = ["cryptography", "rust-patterns"]
repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
experimental = ["experimental-api"]
experimental-api = []
[dependencies]

View File

@ -12,10 +12,12 @@ categories = ["network-programming", "cryptography"]
repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
# Enable experimental APIs that are not yet officially supported.
#
# These APIs are not covered by semantic versioning. Using this
# feature voids your "semver warrantee".
experimental = ["experimental-api"]
experimental-api = []
[dependencies]

View File

@ -13,6 +13,9 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = ["mmap"]
full = ["routerdesc"]
experimental = ["experimental-api", "dirfilter"]
mmap = ["memmap2"]
static = ["rusqlite/bundled"]
# (Incomplete) support for downloading and storing router descriptors

View File

@ -14,6 +14,8 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = []
experimental = ["experimental-api"]
# Enable experimental APIs that are not yet officially supported.
#
# These APIs are not covered by semantic versioning. Using this

View File

@ -14,6 +14,9 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = []
full = ["routerdesc", "ns_consensus"]
experimental = ["build_docs", "experimental-api"]
# Enable code to build the objects that represent different network documents.
build_docs = ["rand"]

View File

@ -13,6 +13,8 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = []
full = ["tokio"]
experimental = ["hs", "ntor_v3"]
hs = []
ntor_v3 = []
tokio = ["tokio-crate", "tokio-util"]

View File

@ -14,6 +14,8 @@ repository = "https://gitlab.torproject.org/tpo/core/arti.git/"
[features]
default = []
full = ["async-std", "tokio", "native-tls", "rustls"]
async-std = ["async-std-crate", "async-io", "async_executors/async_std"]
tokio = ["tokio-crate", "tokio-util", "async_executors/tokio_tp"]
# TODO: This feature makes us link native-tls statically even if we