diff --git a/src/service/http.rs b/src/service/http.rs index dd1743168c..77907e6716 100644 --- a/src/service/http.rs +++ b/src/service/http.rs @@ -5,19 +5,32 @@ use crate::body::Body; use crate::service::service::Service; use crate::{Request, Response}; -/// An asynchronous function from `Request` to `Response`. +/// An asynchronous function from [`Request`] to [`Response`]. +/// +/// This is a *sealed* trait, meaning that it can not be implemented directly. Rather, it is an +/// alias for [`Service`]s that accept a [`Request`] and return a [`Future`] that resolves to a +/// [`Response`]. External callers should implement [`Service`] instead. +/// +/// Rather than being generic over the request and response, this trait is generic across the +/// request [`Body`] and response [`Body`]. +/// +/// See the crate-level [`service`][crate::service] documentation for more information. +/// +/// See [`Service`] for more information. pub trait HttpService: sealed::Sealed { - /// The `Body` body of the `http::Response`. + /// The [`Body`] body of the [`Response`]. type ResBody: Body; - /// The error type that can occur within this `Service`. + /// The error type that can occur within this [`Service`]. /// - /// Note: Returning an `Error` to a hyper server will cause the connection - /// to be abruptly aborted. In most cases, it is better to return a `Response` - /// with a 4xx or 5xx status code. + /// Note: Returning an `Error` to a hyper server, the behavior depends on the protocol. In + /// most cases, hyper will cause the connection to be abruptly aborted. In most cases, it is + /// better to return a `Response` with a 4xx or 5xx status code. + /// + /// See [`Service::Error`] for more information. type Error: Into>; - /// The `Future` returned by this `Service`. + /// The [`Future`] returned by this [`Service`]. type Future: Future, Self::Error>>; #[doc(hidden)] diff --git a/src/service/service.rs b/src/service/service.rs index 42c18e727f..caded3f752 100644 --- a/src/service/service.rs +++ b/src/service/service.rs @@ -9,14 +9,26 @@ use std::future::Future; /// # Functional /// /// A `Service` is a function of a `Request`. It immediately returns a -/// `Future` representing the eventual completion of processing the +/// [`Future`] representing the eventual completion of processing the /// request. The actual request processing may happen at any time in the /// future, on any thread or executor. The processing may depend on calling /// other services. At some point in the future, the processing will complete, -/// and the `Future` will resolve to a response or error. +/// and the [`Future`] will resolve to a response or an error. /// /// At a high level, the `Service::call` function represents an RPC request. The /// `Service` value can be a server or a client. +/// +/// # Utilities +/// +/// The [`hyper-util`][util] crate provides facilities to bridge this trait to +/// other libraries, such as [`tower`][tower], which might provide their +/// own `Service` variants. +/// +/// See [`hyper_util::service`][util-service] for more information. +/// +/// [tower]: https://docs.rs/tower +/// [util]: https://docs.rs/hyper-util +/// [util-service]: https://docs.rs/hyper-util/latest/hyper_util/service/index.html pub trait Service { /// Responses given by the service. type Response; @@ -37,7 +49,7 @@ pub trait Service { /// - It prepares the way for async fn, /// since then the future only borrows `&self`, and thus a Service can concurrently handle /// multiple outstanding requests at once. - /// - It's clearer that Services can likely be cloned + /// - It's clearer that Services can likely be cloned. /// - To share state across clones, you generally need `Arc>` /// That means you're not really using the `&mut self` and could do with a `&self`. /// The discussion on this is here: