From afeaf2eff69126e70b1730bd38237833911d2097 Mon Sep 17 00:00:00 2001 From: Ed Morley <501702+edmorley@users.noreply.github.com> Date: Sat, 26 Feb 2022 15:48:41 +0000 Subject: [PATCH] Document that the client/server features are now opt-in Adds documentation for the switch to the `client` and `server` features now being opt-in, rather than enabled by default (see #54). I experimented with also enabling the nightly-only `doc_cfg` / `doc_auto_cfg` features (see rust-lang/rust/issues/43781, which can be used on `docs.rs` since it builds docs with nightly), however: - the features don't currently work well with the re-exports in the crate root, so require every struct/trait to be manually annotated. - the rendering isn't great - the crate landing page wrapping ended up broken So for now it seems best to not use that. I did adjust the `docs.rs` config in `Cargo.toml` to ensure docs are actually generated for all features, since previously the docs were almost empty. I also fixed a few typos / markdown syntax errors. --- Cargo.toml | 3 +++ README.md | 16 +++++++++++++--- src/client.rs | 8 ++++---- src/lib.rs | 15 +++++++-------- src/server.rs | 2 +- src/uri.rs | 4 ++-- 6 files changed, 30 insertions(+), 18 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index fc2c070..7d18aa5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -41,3 +41,6 @@ required-features = ["server", "hyper/runtime"] [[test]] name = "server_client" required-features = ["client", "server", "hyper/runtime"] + +[package.metadata.docs.rs] +all-features = true diff --git a/README.md b/README.md index ecbd5b1..1e52a3e 100644 --- a/README.md +++ b/README.md @@ -43,11 +43,21 @@ not needed. Examples of Unix daemons that provide this kind of host local interf ## Installation -Add the following to your `Cargo.toml` file +By default `hyperlocal` does not enable any [feature flags](https://doc.rust-lang.org/cargo/reference/features.html), +so you will need to enable the appropriate features for your use-case. + +For server usage, add the following to your `Cargo.toml` file: + +```toml +[dependencies] +hyperlocal = { version = "0.8", features = ["server"] } +``` + +Or for client usage: ```toml [dependencies] -hyperlocal = "0.8" +hyperlocal = { version = "0.8", features = ["client"] } ``` ## Usage @@ -103,7 +113,7 @@ It's a Unix system. I know this. Configure your `Hyper` client using `hyper::Client::builder()`. Hyper's client interface makes it easy to send typical HTTP methods like `GET`, `POST`, `DELETE` with factory -methods, `get`, `post`, `delete`, etc. These require an argument that can be tranformed into a `hyper::Uri`. +methods, `get`, `post`, `delete`, etc. These require an argument that can be transformed into a `hyper::Uri`. Since Unix domain sockets aren't represented with hostnames that resolve to ip addresses coupled with network ports, your standard over the counter URL string won't do. Instead, use a `hyperlocal::Uri`, which represents both file path to the domain diff --git a/src/client.rs b/src/client.rs index fe96edb..13b5aa8 100644 --- a/src/client.rs +++ b/src/client.rs @@ -57,7 +57,7 @@ impl tokio::io::AsyncRead for UnixStream { } } -/// the `[UnixConnector]` can be used to construct a `[hyper::Client]` which can +/// The [`UnixConnector`] can be used to construct a [`hyper::Client`] which can /// speak to a unix domain socket. /// /// # Example @@ -70,8 +70,8 @@ impl tokio::io::AsyncRead for UnixStream { /// ``` /// /// # Note -/// If you don't need access to the low-level `[hyper::Client]` builder -/// interface, consider using the `[UnixClientExt]` trait instead. +/// If you don't need access to the low-level [`hyper::Client`] builder +/// interface, consider using the [`UnixClientExt`] trait instead. #[derive(Clone, Copy, Debug, Default)] pub struct UnixConnector; @@ -129,7 +129,7 @@ fn parse_socket_path(uri: &Uri) -> Result { } } -/// Extention trait for constructing a hyper HTTP client over a Unix domain +/// Extension trait for constructing a hyper HTTP client over a Unix domain /// socket. pub trait UnixClientExt { /// Construct a client which speaks HTTP over a Unix domain socket diff --git a/src/lib.rs b/src/lib.rs index 0a64652..043c61b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,22 +9,21 @@ //! `hyperlocal` provides [Hyper](http://github.com/hyperium/hyper) bindings //! for [Unix domain sockets](https://github.com/tokio-rs/tokio/tree/master/tokio-net/src/uds/). //! -//! See the [`UnixClientExt`] docs for -//! how to configure clients. +//! See the [`UnixClientExt`] docs for how to configure clients. //! -//! See the -//! [`UnixServerExt`] docs for how to -//! configure servers. +//! See the [`UnixServerExt`] docs for how to configure servers. //! //! The [`UnixConnector`] can be used in the [`hyper::Client`] builder //! interface, if required. //! //! # Features //! -//! - Client- enables the client extension trait and connector. *Enabled by -//! default*. +//! By default `hyperlocal` does not enable any [feature flags](https://doc.rust-lang.org/cargo/reference/features.html). //! -//! - Server- enables the server extension trait. *Enabled by default*. +//! The following features are available: +//! +//! - **`client`** — Enables the client extension trait and connector. +//! - **`server`** — Enables the server extension trait. #[cfg(feature = "client")] mod client; diff --git a/src/server.rs b/src/server.rs index c477e17..6c1dea2 100644 --- a/src/server.rs +++ b/src/server.rs @@ -34,7 +34,7 @@ pub(crate) mod conn { Ok(Self { listener }) } - /// Creates a new `SocketIncoming` from Tokio's `UnixListener` + /// Creates a new `SocketIncoming` from Tokio's [`UnixListener`]. /// /// ```rust,ignore /// let socket = SocketIncoming::from_listener(unix_listener); diff --git a/src/uri.rs b/src/uri.rs index 23fb167..bf92922 100644 --- a/src/uri.rs +++ b/src/uri.rs @@ -1,7 +1,7 @@ use hyper::Uri as HyperUri; use std::path::Path; -/// A convenience type that can be used to construct Unix Domain Socket URIs +/// A convenience type that can be used to construct Unix Domain Socket URIs. /// /// This type implements `Into`. /// @@ -18,7 +18,7 @@ pub struct Uri { } impl Uri { - /// Create a new `[Uri]` from a socket address and a path + /// Create a new [`Uri`] from a socket address and a path. /// /// # Panics /// Will panic if path is not absolute and/or a malformed path string.