rust/rustls
rust
/
rustls
mirror of https://github.com/ctz/rustls
1
0
Fork 0
Code Issues Releases Wiki Activity

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:
Daniel McCarney 2024-01-02 10:25:39 -05:00
parent 0d7c256c32
commit 0d4b2dfa52
2 changed files with 33 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
README.md
View File

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

21
rustls/src/lib.rs
View File

@ -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/
//!