Update README.md files from rustdoc.

## Overview

The `arti-client` crate aims to provide a safe, easy-to-use API for

applications that want to use Tor network to anonymize their

traffic.  It hides most of the underlying detail, letting other

crates decide how exactly to use the Tor crate.

applications that want to use the Tor network to anonymize their traffic.

This crate is part of

[Arti](https://gitlab.torproject.org/tpo/core/arti/), a project to

implement [Tor](https://www.torproject.org/) in Rust.

It is the 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.

This crate is part of [Arti](https://gitlab.torproject.org/tpo/core/arti/),

a project to implement [Tor](https://www.torproject.org/) in Rust. It is the

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 ⚠

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.  (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 all of the APIs for this crate, and for Arti in

general, are not the least bit stable.  If you use this code,

please expect your software to break on a regular basis.

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.

## Using `arti-client`

The main entry point for this crate is the [`TorClient`], an object that lets you make

connections over the Tor network.

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.

Calling [`TorClient::bootstrap`] 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`].

## Using `arti-client`

A client can then be used to make connections over Tor with [`TorClient::connect`], which

accepts anything implementing [`IntoTorAddr`]. This returns a [`DataStream`], an anonymized

TCP stream type that implements [`AsyncRead`](futures::io::AsyncRead) and

[`AsyncWrite`](futures::io::AsyncWrite), as well as the Tokio versions of those traits if

the `tokio` crate feature is enabled.

The main entry point for this crate is the [`TorClient`], an object that

lets you make connections over the Tor network.

The [`TorAddr`] type is intended to ensure that DNS lookups are done via the Tor network

instead of locally. Doing local DNS resolution can leak information about which hostnames you're

connecting to to your local DNS resolver (i.e. your ISP), so it's much better to let Arti

do it for you to maintain privacy.

### Connecting to Tor

If you really want to connect to a raw IP address and know what you're doing, take a look at

[`TorAddr::dangerously_from`] -- but be careful!

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`].

### Example: making connections over Tor

(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.)

```rust

// The client configuration describes how to connect to the Tor network,

// and what directories to use for storing persistent state.

let config = TorClientConfig::default();

// Arti needs a handle to an async runtime in order to spawn tasks and use the

// network. (See "Multiple runtime support" below.)

let rt = tor_rtcompat::tokio::TokioNativeTlsRuntime::current()?;

// Start the Arti client, and let it bootstrap a connection to the Tor network.

// (This takes a while to gather the necessary directory information.

// It uses cached information when possible.)

let tor_client = TorClient::bootstrap(rt, config).await?;

let tor_client = TorClient::create_bootstrapped(config).await?;

```

### 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`].

The returned client can be made to bootstrap when it is first used (the default), or not;

see [`BootstrapBehavior`] for more details.

```rust

// Specifying `BootstrapBehavior::OnDemand` means the client will automatically

// bootstrap when it is used. `Manual` exists if you'd rather have full control.

let tor_client = TorClient::builder()

    .bootstrap_behavior(BootstrapBehavior::OnDemand)

    .create_unbootstrapped()?;

```

### Using the client

A client can then be used to make connections over Tor with

[`TorClient::connect`], which accepts anything implementing [`IntoTorAddr`].

This returns a [`DataStream`], an anonymized TCP stream type that implements

[`AsyncRead`](futures::io::AsyncRead) and

[`AsyncWrite`](futures::io::AsyncWrite), as well as the Tokio versions of

those traits if the `tokio` crate feature is enabled.

### Example: making connections over Tor

```rust

#

// Initiate a connection over Tor to example.com, port 80.

let mut stream = tor_client.connect(("example.com", 80)).await?;

### More advanced usage

This version of Arti includes basic support for "stream isolation": the ability to ensure that

different TCP connections ('streams') go over different Tor circuits (and thus different exit

nodes, making them originate from different IP addresses).

This version of Arti includes basic support for "stream isolation": the

ability to ensure that different TCP connections ('streams') go over

different Tor circuits (and thus different exit nodes, making them originate

from different IP addresses).

This is useful to avoid deanonymizing

users by correlation: for example, you might want a Tor connection to your bank and a Tor

connection to an online forum to use different circuits, to avoid the possibility of the two

This is useful to avoid deanonymizing users by correlation: for example, you

might want a Tor connection to your bank and a Tor connection to an online

forum to use different circuits, to avoid the possibility of the two

identities being linked by having the same source IP.

Streams can be isolated in two ways:

- by calling [`TorClient::isolated_client`], which returns a new [`TorClient`] whose streams

  will use a different circuit

- by generating [`IsolationToken`]s, and passing them in via [`StreamPrefs`] to

  [`TorClient::connect`].

- by calling [`TorClient::isolated_client`], which returns a new

  [`TorClient`] whose streams will use a different circuit

- by generating [`IsolationToken`]s, and passing them in via [`StreamPrefs`]

  to [`TorClient::connect`].

## Multiple runtime support

Arti uses the [`tor_rtcompat`] crate to support multiple asynchronous runtimes; currently,

both [Tokio](https://tokio.rs) and [async-std](https://async.rs) are supported.

Functions in this crate, like [`TorClient::bootstrap`],

will expect a type that implements [`tor_rtcompat::Runtime`], which can be obtained:

Arti uses the [`tor_rtcompat`] crate to support multiple asynchronous

runtimes; currently, both [Tokio](https://tokio.rs) and

[async-std](https://async.rs) are supported.

- for Tokio:

  - by calling [`tor_rtcompat::tokio::PreferredRuntime::current()`], if a Tokio reactor is already running

  - by calling [`tor_rtcompat::tokio::PreferredRuntime::create()`], to start a new reactor if one is not

    already running

  - as above, but explicitly specifying [`TokioNativeTlsRuntime`](tor_rtcompat::tokio::TokioNativeTlsRuntime)

    or [`TokioRustlsRuntime`](tor_rtcompat::tokio::TokioRustlsRuntime) in place of `PreferredRuntime`.

- for async-std:

  - by calling [`tor_rtcompat::async_std::PreferredRuntime::current()`], which will create a runtime or

    retrieve the existing one, if one has already been started

  - as above, but explicitly specifying [`AsyncStdNativeTlsRuntime`](tor_rtcompat::async_std::AsyncStdNativeTlsRuntime)

    or [`AsyncStdRustlsRuntime`](tor_rtcompat::async_std::AsyncStdRustlsRuntime) in place of `PreferredRuntime`.

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.

## Feature flags

`tokio` -- (Default) Build with support for the Tokio backend.

`async-std` -- Build with support for the `async_std` backend.

`native-tls` (default), `rustls` -- Select TLS libraries to support. 

`static` -- Link with static versions of your system dependencies,

including sqlite and/or openssl.

`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` -- Make the `TorError` type transparent, and expose the `Error` within.

Note that the resulting APIs are not stable.

* `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.

Note that flags `tokio`, `native-tls`, `async-std`, `rustls` and `static` will enable

the flags of the same name on the [`tor_rtcompat`] crate.

License: MIT OR Apache-2.0

It provides a client configuration tool using using `serde` and `config`,

plus extra features defined here for convenience.

## ⚠ Stability Warning ⚠

The design of this crate, and of the configuration system for

Arti, is likely to change significantly before the release of Arti

1.0.0.  For more information see ticket [#285].

[#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285

License: MIT OR Apache-2.0

High-level layer for making http(s) requests the Tor network as a client.

## Feature flags

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`].

`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.

There is an example program [`hyper.rs`] which uses `arti-hyper`

to connect to Tor and make a single HTTP\[S] request.

`native-tls` (default), `rustls` -- Select TLS libraries to use for Tor's purposes.

(The end-to-end TLS to the origin server is separate, and handled via `tls-api`.)

[`hyper.rs`]: <https://gitlab.torproject.org/tpo/core/arti/-/blob/main/crates/arti-hyper/examples/hyper.rs>

License: MIT OR Apache-2.0

`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)

`static`: Try to link a single static binary.

`rustls` -- Build with support for the `rustls` TLS backend.

`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`.

## Limitations

It provides low-level types for handling configuration values.

## ⚠ Stability Warning ⚠

The design of this crate, and of the configuration system for

Arti, is likely to change significantly before the release of Arti

1.0.0.  For more information see ticket [#285].

[#285]: https://gitlab.torproject.org/tpo/core/arti/-/issues/285

License: MIT OR Apache-2.0