diff --git a/src/service/glue.rs b/src/service/glue.rs index 35aa0964..ceff86f5 100644 --- a/src/service/glue.rs +++ b/src/service/glue.rs @@ -7,14 +7,22 @@ use std::{ use super::Oneshot; -/// A tower service converted into a hyper service. +/// A tower [`Service`][tower-svc] converted into a hyper [`Service`][hyper-svc]. +/// +/// This wraps an inner tower service `S` in a [`hyper::service::Service`] implementation. See +/// the module-level documentation of [`service`][crate::service] for more information about using +/// [`tower`][tower] services and middleware with [`hyper`]. +/// +/// [hyper-svc]: hyper::service::Service +/// [tower]: https://docs.rs/tower/latest/tower/ +/// [tower-svc]: https://docs.rs/tower/latest/tower/trait.Service.html #[derive(Debug, Copy, Clone)] pub struct TowerToHyperService { service: S, } impl TowerToHyperService { - /// Create a new `TowerToHyperService` from a tower service. + /// Create a new [`TowerToHyperService`] from a tower service. pub fn new(tower_service: S) -> Self { Self { service: tower_service, @@ -39,6 +47,9 @@ where pin_project! { /// Response future for [`TowerToHyperService`]. + /// + /// This future is acquired by [`call`][hyper::service::Service::call]ing a + /// [`TowerToHyperService`]. pub struct TowerToHyperServiceFuture where S: tower_service::Service, diff --git a/src/service/mod.rs b/src/service/mod.rs index 33370ca3..34796431 100644 --- a/src/service/mod.rs +++ b/src/service/mod.rs @@ -1,4 +1,25 @@ //! Service utilities. +//! +//! [`hyper::service`] provides a [`Service`][hyper-svc] trait, representing an asynchronous +//! function from a `Request` to a `Response`. This provides an interface allowing middleware for +//! network application to be written in a modular and reusable way. +//! +//! This submodule provides an assortment of utilities for working with [`Service`][hyper-svc]s. +//! See the module-level documentation of [`hyper::service`] for more information. +//! +//! # Tower +//! +//! While [`hyper`] uses its own notion of a [`Service`][hyper-svc] internally, many other +//! libraries use a library such as [`tower`][tower] to provide the fundamental model of an +//! asynchronous function. +//! +//! The [`TowerToHyperService`] type provided by this submodule can be used to bridge these +//! ecosystems together. By wrapping a [`tower::Service`][tower-svc] in [`TowerToHyperService`], +//! it can be passed into [`hyper`] interfaces that expect a [`hyper::service::Service`]. +//! +//! [hyper-svc]: hyper::service::Service +//! [tower]: https://docs.rs/tower/latest/tower/ +//! [tower-svc]: https://docs.rs/tower/latest/tower/trait.Service.html #[cfg(feature = "service")] mod glue;