Document "full", "experimental" in toplevel crate documentation.
Also, unify the features documentation format for those two crates, and document previously undocumented features there.
This commit is contained in:
Nick Mathewson
parent
ef4364f465
commit
923a7c55e3
|
|
@ -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,59 @@
|
|||
//! 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
|
||||
//! * `rustls` -- build with the [rustls](https://github.com/rustls/rustls)
|
||||
//! crate for TLS 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.)
|
||||
//!
|
||||
//! 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)]
|
||||
|
|
|
|||
|
|
@ -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,64 @@
|
|||
//! | 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)
|
||||
//! * `rustls` -- Build with support for the `rustls` TLS backend.
|
||||
//! * `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.
|
||||
//! ## Build-flag related features
|
||||
//!
|
||||
//! `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` -- 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-sqlite` -- Link with a static version of sqlite.
|
||||
//! ## Experimental features
|
||||
//!
|
||||
//! `static-native-tls` -- Link with a static version of `native-tls`.
|
||||
//! Enables `native-tls`.
|
||||
//! 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)]
|
||||
|
|
|
|||
Loading…
Reference in New Issue