mirror of https://github.com/ctz/rustls
docs: provide more pointers for examples
This commit provides more pointers to our existing examples and additionally provides guidance about Rusts being low-level. Users that just want to make an HTTPS request should probably use a crate built on top of Rustls. Similarly, users in the Tokio ecosystem should look at tokio-rustls.
This commit is contained in:
parent
0d7c256c32
commit
0d4b2dfa52
20
README.md
20
README.md
|
@ -110,11 +110,23 @@ Rustls requires Rust 1.61 or later.
|
|||
[crypto::CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/trait.CryptoProvider.html
|
||||
|
||||
# Example code
|
||||
There are two example programs which use
|
||||
[mio](https://github.com/carllerche/mio) to do asynchronous IO.
|
||||
|
||||
Our [examples] directory contains demos that show how to handle I/O using the
|
||||
[`stream::Stream`] helper, as well as more complex asynchronous I/O using [`mio`].
|
||||
If you're already using Tokio for an async runtime you may prefer to use
|
||||
[`tokio-rustls`] instead of interacting with rustls directly.
|
||||
|
||||
The [`mio`] based examples are the most complete, and discussed below. Users
|
||||
new to Rustls may prefer to look at the simple client/server examples before
|
||||
diving in to the more complex MIO examples.
|
||||
|
||||
[examples]: examples/
|
||||
[`stream::Stream`]: https://docs.rs/rustls/latest/rustls/struct.Stream.html
|
||||
[`mio`]: https://docs.rs/mio/latest/mio/
|
||||
[`tokio-rustls`]: https://docs.rs/tokio-rustls/latest/tokio_rustls/
|
||||
|
||||
## Client example program
|
||||
The client example program is named `tlsclient-mio`. The interface looks like:
|
||||
The MIO client example program is named `tlsclient-mio`. The interface looks like:
|
||||
|
||||
```tlsclient-mio
|
||||
Connects to the TLS server at hostname:PORT. The default PORT
|
||||
|
@ -173,7 +185,7 @@ Connection closed
|
|||
```
|
||||
|
||||
## Server example program
|
||||
The server example program is named `tlsserver-mio`. The interface looks like:
|
||||
The MIO server example program is named `tlsserver-mio`. The interface looks like:
|
||||
|
||||
```tlsserver-mio
|
||||
Runs a TLS server on :PORT. The default PORT is 443.
|
||||
|
|
|
@ -77,11 +77,23 @@
|
|||
//! [crypto::CryptoProvider]: https://docs.rs/rustls/latest/rustls/crypto/trait.CryptoProvider.html
|
||||
//!
|
||||
//! ## Design Overview
|
||||
//!
|
||||
//! Rustls is a low-level library. If your goal is to make HTTPS connections you may prefer
|
||||
//! to use a library built on top of Rustls like [hyper] or [ureq].
|
||||
//!
|
||||
//! [hyper]: https://crates.io/crates/hyper
|
||||
//! [ureq]: https://crates.io/crates/ureq
|
||||
//!
|
||||
//! ### Rustls does not take care of network IO
|
||||
//! It doesn't make or accept TCP connections, or do DNS, or read or write files.
|
||||
//!
|
||||
//! There's example client and server code which uses mio to do all needed network
|
||||
//! IO.
|
||||
//! Our [examples] directory contains demos that show how to handle I/O using the
|
||||
//! [`stream::Stream`] helper, as well as more complex asynchronous I/O using [`mio`].
|
||||
//! If you're already using Tokio for an async runtime you may prefer to use [`tokio-rustls`] instead
|
||||
//! of interacting with rustls directly.
|
||||
//!
|
||||
//! [examples]: examples/README.md
|
||||
//! [`tokio-rustls`]: https://github.com/rustls/tokio-rustls
|
||||
//!
|
||||
//! ### Rustls provides encrypted pipes
|
||||
//! These are the [`ServerConnection`] and [`ClientConnection`] types. You supply raw TLS traffic
|
||||
|
@ -231,9 +243,10 @@
|
|||
//!
|
||||
//! # Examples
|
||||
//!
|
||||
//! [`tlsserver-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsserver-mio.rs)
|
||||
//! You can find several client and server examples of varying complexity in the [examples]
|
||||
//! directory, including [`tlsserver-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsserver-mio.rs)
|
||||
//! and [`tlsclient-mio`](https://github.com/rustls/rustls/blob/main/examples/src/bin/tlsclient-mio.rs)
|
||||
//! are full worked examples using [`mio`].
|
||||
//! - full worked examples using [`mio`].
|
||||
//!
|
||||
//! [`mio`]: https://docs.rs/mio/latest/mio/
|
||||
//!
|
||||
|
|
Loading…
Reference in New Issue