diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5ba0a788d..9793745b7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -107,52 +107,6 @@ link to your forked arti repository at:
>
> https://gitlab.torproject.org/_name_/arti/-/merge_requests
-## Using Arti with Torbrowser
-
-A good first step to start hacking on arti might be to hook it up with your
-Tor Browser. Please note that arti is still a work in progress and hence you
-should assume that it **provides no security** at the moment.
-
-To do so, we will launch arti independently from Tor Browser. Build arti with
-`cargo build --release`. After that launch it with some basic
-configuration parameters:
-
- $ ./target/release/arti proxy -l debug -p 9150
-
-This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
-Tor Browser and instruct it to use that SOCKS port.
-
-### Linux
-
- $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
-
-### OS X
-
- $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
-
-### Windows
-
-Create a shortcut with the `Target` set to:
-
- C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
-
-and `Start in` set to:
-
- "C:\path\to\Tor Browser\Browser"
-
-(You may need to adjust the actual path to wherever you have put your Tor
-Browser.)
-
-When you start Tor browser, it will give you a big red error page because
-Arti isn't offering it a control port interface. But it will still work!
-Try [check.torproject.org](https://check.torproject.org/) to be sure.
-
-The resulting Tor Browser should be using arti. Note that onion services
-won't work (Arti doesn't have them yet), and neither will any feature
-depending on Tor's control-port protocol.
-
-Enjoy hacking on arti!
-
## Where are some good places to start hacking?
You might want to begin by looking around the
@@ -203,3 +157,5 @@ implementation.
When building the docs with `cargo doc`, use `--all-features`, or you may
find broken links. (We welcome fixes to links broken with `--all-features`.)
+
+Enjoy hacking on arti!
diff --git a/README.md b/README.md
index ad687efdd..b526da4c7 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,6 @@ Arti is a project to produce an embeddable, production-quality implementation
of the [Tor](https://www.torproject.org/) anonymity protocols in the
[Rust](https://www.rust-lang.org/) programming language.
-Arti is **not ready for production use**; [see below](#status) for more information.
-
## Links:
* [Official source repository](https://gitlab.torproject.org/tpo/core/arti)
@@ -49,32 +47,32 @@ needlessly hard to understand and improve.
## Current status
-Arti is a work-in-progress. It can connect to the Tor network, bootstrap a
+Arti can connect to the Tor network, bootstrap a
view of the Tor directory, and make anonymized connections over the network.
+Now that Arti has reached version 1.0.0, we believe it is suitable for
+actual use to anonymise connections.
-We're not _aware_ of any critical security features missing in Arti; but
-however, since Arti is comparatively new software, you should probably be
-cautious about using it in production.
+There are a number of areas (especially at the lower layers) where APIs
+(especially internal APIs) are not stable,
+and are likely to change them.
+Right now that includes the command line interface to the `arti` program.
-Now that Arti has reached version 0.1.0, we believe it is suitable for
-_experimental_ embedding within other Rust applications. We will try to keep
-the API as exposed by the top-level `arti_client` crate more or less stable
-over time. (We may have to break existing programs from time to time, but we
-will try not to do so without a very good reason. Either way, we will try to
-follow Rust's semantic versioning best practices.)
+And of course it's still very new so there are likely to be bugs.
-## Trying it out today
+## Building and using Arti
Arti can act as a SOCKS proxy that uses the Tor network.
+We expect to be providing official binaries soon.
+But, for now, you need to obtain a
+[Rust](https://www.rust-lang.org/) development environment,
+and build it yourself.
+
To try it out, compile and run the `arti` binary using the below. It will open a
SOCKS proxy on port 9150.
$ cargo run -p arti --release -- proxy
-Again, do not use this program yet if you seriously need anonymity, privacy,
-security, or stability.
-
You can build a binary (but not run it) with:
$ cargo build -p arti --release
@@ -86,19 +84,23 @@ look at [the troubleshooting guide](doc/TROUBLESHOOTING.md).
### Custom compile-time options
-Arti has a number of configurable [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html) that,
-among other things, can affect which asynchronous runtime to use. Use
+Arti has a number of configurable
+[Cargo features](https://doc.rust-lang.org/cargo/reference/features.html)
+that, among other things, can affect which asynchronous runtime to use.
- $ cargo doc -p arti --open
+See in the
+[Arti crate-level docs](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html#compile-time-features)
+for details.
-to view the Arti crate-level docs in your browser, which contain a full list.
+## Using Arti as a library
-You can pass these features to Cargo while building with `--features` (note that you might need `--no-default-features`
-in order to not use the default runtime choices, too). For example, to use `async-std` instead of Tokio:
+The `arti` command line utility is built on top of the
+[`arti_client`](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html)
+library (and its dependencies).
- $ cargo run -p arti --no-default-features --features async-std,native-tls -- proxy
-
-Use `target/release/arti --version` to see what features the currently built Arti binary is using.
+That library's API will allow you to
+make connections over the Tor network,
+and obtain streams/sinks useable from async Rust.
## Minimum supported Rust Version
@@ -149,13 +151,13 @@ get our project manager to sign off on them.
* Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
* Target audience: **initial users**
- * [ ] Stable API
+ * [x] Stable API (mostly)
* [ ] Stable CLI
- * [ ] Stable configuration format
- * [ ] Automatic detection and response of more kinds of network problems
- * [ ] At least as secure as C Tor
- * [ ] Client performance similar to C Tor
- * [ ] More performance work
+ * [x] Stable configuration format
+ * [x] Automatic detection and response of more kinds of network problems
+ * [x] At least as secure as C Tor
+ * [x] Client performance similar to C Tor
+ * [x] More performance work
* [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
* Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?)
diff --git a/crates/arti-client/README.md b/crates/arti-client/README.md
index 70d61ba87..466dc5bcd 100644
--- a/crates/arti-client/README.md
+++ b/crates/arti-client/README.md
@@ -13,18 +13,27 @@ highest-level library crate in Arti, and the one that nearly all client-only
programs should use. Most of its functionality is provided by lower-level
crates in Arti.
-### ⚠ Warnings ⚠
+### Shape of the API, and relationship to other crates
-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.)
+The API here is great if you are building an application in async Rust
+and want your Tor connections as async streams (`AsyncRead`/`AsyncWrite`).
+If you are wanting to make HTTP requests,
+look at [arti_hyper](https://tpo.pages.torproject.net/core/doc/rust/arti_hyper/index.html)).
+
+If you are trying to glue Arti to some other programming language,
+right now your best bet is probably to spawn the
+[`arti` CLI](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html)
+SOCKS proxy,
+as a subprocess.
+We don't yet offer an API that would be nice to expose via FFI;
+we intend to add this in the future.
+
+### ⚠ Warnings ⚠
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.
+between now and us declaring `arti-client` 1.x.
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.
diff --git a/crates/arti-client/src/config.rs b/crates/arti-client/src/config.rs
index a3cd89b75..a44df889f 100644
--- a/crates/arti-client/src/config.rs
+++ b/crates/arti-client/src/config.rs
@@ -1,15 +1,6 @@
//! 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 derive_more::AsRef;
diff --git a/crates/arti-client/src/lib.rs b/crates/arti-client/src/lib.rs
index 282f7a548..f01cfff9c 100644
--- a/crates/arti-client/src/lib.rs
+++ b/crates/arti-client/src/lib.rs
@@ -12,18 +12,27 @@
//! programs should use. Most of its functionality is provided by lower-level
//! crates in Arti.
//!
-//! ## ⚠ Warnings ⚠
+//! ## Shape of the API, and relationship to other crates
//!
-//! 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.)
+//! The API here is great if you are building an application in async Rust
+//! and want your Tor connections as async streams (`AsyncRead`/`AsyncWrite`).
+//! If you are wanting to make HTTP requests,
+//! look at [arti_hyper](https://tpo.pages.torproject.net/core/doc/rust/arti_hyper/index.html)).
+//!
+//! If you are trying to glue Arti to some other programming language,
+//! right now your best bet is probably to spawn the
+//! [`arti` CLI](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html)
+//! SOCKS proxy,
+//! as a subprocess.
+//! We don't yet offer an API that would be nice to expose via FFI;
+//! we intend to add this in the future.
+//!
+//! ## ⚠ Warnings ⚠
//!
//! 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.
+//! between now and us declaring `arti-client` 1.x.
//!
//! 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.
diff --git a/crates/arti/README.md b/crates/arti/README.md
index 2cd3f6dd2..d63ea0c59 100644
--- a/crates/arti/README.md
+++ b/crates/arti/README.md
@@ -1,22 +1,26 @@
# arti
-A minimal command line program for connecting to the tor network
+A minimal command line program for connecting to the Tor network
(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.
+[Tor](https://www.torproject.org/) in Rust.
-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.
+Currently Arti can 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.
+You can direct programs to connect via that SOCKS port,
+and their connections will be anonymized via Tor.
+Note: you might not want to run a conventional web browser this way.
+Browsers leak much private information.
+To browse the web anonymously,
+we recommend [using Tor Browser](#using-arti-with-tor-browser).
-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.
+Arti is still advancing rapidly; we are adding features and eventually
+we hope it will be able to replace C Tor.
## Command-line interface
@@ -39,8 +43,69 @@ location.
| macOS | `~/Library/Application Support/arti/arti.toml` |
| Windows | `\Users\\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.
+For an example see `arti-example-config.toml`
+(a copy of which is in the source tree,
+and also
+[in the Arti repository](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti/src/arti-example-config.toml)).
+That example config file documents the configuration options.
+
+More detailed information about for the individual fields is available in the documentation
+for the Rust APIs [`ApplicationConfigBuilder`] and
+[`TorClientConfigBuilder`](arti_client::config::TorClientConfigBuilder).
+
+## Using Arti with Tor Browser
+
+It is possible to hook up Arti with
+[Tor Browser](https://www.torproject.org/download/).
+
+To do so, we will launch arti independently from Tor Browser. Build arti with
+`cargo build --release`. After that launch it with some basic
+configuration parameters:
+
+```
+$ ./target/release/arti proxy -l debug -p 9150
+```
+
+This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
+Tor Browser and instruct it to use that SOCKS port.
+
+#### Linux
+
+```
+$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
+```
+
+#### OS X
+
+```
+$ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
+```
+
+#### Windows
+
+Create a shortcut with the `Target` set to:
+
+```
+C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
+```
+
+and `Start in` set to:
+
+```
+"C:\path\to\Tor Browser\Browser"
+```
+
+(You may need to adjust the actual path to wherever you have put your Tor
+Browser.)
+
+When you start Tor browser, it will give you a big red error page because
+Arti isn't offering it a control port interface. But it will still work!
+Try [check.torproject.org](https://check.torproject.org/) to be sure.
+
+The resulting Tor Browser should be using arti. Note that onion services
+won't work (Arti doesn't have them yet), and neither will any feature
+depending on Tor's control-port protocol.
## Compile-time features
@@ -113,7 +178,7 @@ 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
+See the [repository README
file](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/README.md) for
a more complete list of missing features.
diff --git a/crates/arti/src/lib.rs b/crates/arti/src/lib.rs
index a2696344e..0d5474f2b 100644
--- a/crates/arti/src/lib.rs
+++ b/crates/arti/src/lib.rs
@@ -1,21 +1,25 @@
#![cfg_attr(docsrs, feature(doc_auto_cfg, doc_cfg))]
-//! A minimal command line program for connecting to the tor network
+//! A minimal command line program for connecting to the Tor network
//!
//! (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.
+//! [Tor](https://www.torproject.org/) in Rust.
//!
-//! 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.
+//! Currently Arti can 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.
+//! You can direct programs to connect via that SOCKS port,
+//! and their connections will be anonymized via Tor.
+//! Note: you might not want to run a conventional web browser this way.
+//! Browsers leak much private information.
+//! To browse the web anonymously,
+//! we recommend [using Tor Browser](#using-arti-with-tor-browser).
//!
-//! 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.
+//! Arti is still advancing rapidly; we are adding features and eventually
+//! we hope it will be able to replace C Tor.
//!
//! # Command-line interface
//!
@@ -38,8 +42,69 @@
//! | macOS | `~/Library/Application Support/arti/arti.toml` |
//! | Windows | `\Users\\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.
+//! For an example see `arti-example-config.toml`
+//! (a copy of which is in the source tree,
+//! and also
+//! [in the Arti repository](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti/src/arti-example-config.toml)).
+//! That example config file documents the configuration options.
+//!
+//! More detailed information about for the individual fields is available in the documentation
+//! for the Rust APIs [`ApplicationConfigBuilder`] and
+//! [`TorClientConfigBuilder`](arti_client::config::TorClientConfigBuilder).
+//!
+//! # Using Arti with Tor Browser
+//!
+//! It is possible to hook up Arti with
+//! [Tor Browser](https://www.torproject.org/download/).
+//!
+//! To do so, we will launch arti independently from Tor Browser. Build arti with
+//! `cargo build --release`. After that launch it with some basic
+//! configuration parameters:
+//!
+//! ```text
+//! $ ./target/release/arti proxy -l debug -p 9150
+//! ```
+//!
+//! This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
+//! Tor Browser and instruct it to use that SOCKS port.
+//!
+//! ### Linux
+//!
+//! ```text
+//! $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
+//! ```
+//!
+//! ### OS X
+//!
+//! ```text
+//! $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
+//! ```
+//!
+//! ### Windows
+//!
+//! Create a shortcut with the `Target` set to:
+//!
+//! ```text
+//! C:\Windows\System32\cmd.exe /c "SET TOR_SKIP_LAUNCH=1&& SET TOR_SOCKS_PORT=9150&& START /D ^"C:\path\to\Tor Browser\Browser^" firefox.exe"
+//! ```
+//!
+//! and `Start in` set to:
+//!
+//! ```text
+//! "C:\path\to\Tor Browser\Browser"
+//! ```
+//!
+//! (You may need to adjust the actual path to wherever you have put your Tor
+//! Browser.)
+//!
+//! When you start Tor browser, it will give you a big red error page because
+//! Arti isn't offering it a control port interface. But it will still work!
+//! Try [check.torproject.org](https://check.torproject.org/) to be sure.
+//!
+//! The resulting Tor Browser should be using arti. Note that onion services
+//! won't work (Arti doesn't have them yet), and neither will any feature
+//! depending on Tor's control-port protocol.
//!
//! # Compile-time features
//!
@@ -112,7 +177,7 @@
//! 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
+//! See the [repository README
//! file](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/README.md) for
//! a more complete list of missing features.
//!