Unverified Commit 27020be3 authored by Harry Barber's avatar Harry Barber Committed by GitHub
Browse files

Improve service documentation (#2020) 



Co-authored-by: default avatarLuca Palmieri <20745048+LukeMathWalker@users.noreply.github.com>

* Add module documentation to `plugin.rs`.

* Remove reference to `FromRequest` in `FromParts`.

* Improve `Route` documentation.
parent a1fde3be

rust-runtime/aws-smithy-http-server/src/plugin/mod.rs

+47 −0
Original line number Diff line number Diff line
@@ -3,6 +3,53 @@ 
 * SPDX-License-Identifier: Apache-2.0

 */



//! The plugin system allows you to build middleware with an awareness of the operation it is applied to.

//!

//! The system centers around the [`Plugin`] trait. In addition, this module provides helpers for composing and

//! combining [`Plugin`]s.

//!

//! # Filtered application of a HTTP [`Layer`](tower::Layer)

//!

//! ```

//! # use aws_smithy_http_server::plugin::*;

//! # let layer = ();

//! # struct GetPokemonSpecies;

//! # impl GetPokemonSpecies { const NAME: &'static str = ""; };

//! // Create a `Plugin` from a HTTP `Layer`

//! let plugin = HttpLayer(layer);

//!

//! // Only apply the layer to operations with name "GetPokemonSpecies"

//! let plugin = filter_by_operation_name(plugin, |name| name == GetPokemonSpecies::NAME);

//! ```

//!

//! # Construct a [`Plugin`] from a closure that takes as input the operation name

//!

//! ```

//! # use aws_smithy_http_server::plugin::*;

//! // A `tower::Layer` which requires the operation name

//! struct PrintLayer {

//!     name: &'static str

//! }

//!

//! // Create a `Plugin` using `PrintLayer`

//! let plugin = plugin_from_operation_name_fn(|name| PrintLayer { name });

//! ```

//!

//! # Combine [`Plugin`]s

//!

//! ```

//! # use aws_smithy_http_server::plugin::*;

//! # let a = (); let b = ();

//! // Combine `Plugin`s `a` and `b`

//! let plugin = PluginPipeline::new()

//!     .push(a)

//!     .push(b);

//! ```

//!

//! As noted in the [`PluginPipeline`] documentation, the plugins' runtime logic is executed in registration order,

//! meaning that `a` is run _before_ `b` in the example above.

//!



mod closure;

mod filter;

mod identity;

rust-runtime/aws-smithy-http-server/src/request/mod.rs

+2 −2
Original line number Diff line number Diff line
@@ -119,8 +119,8 @@ impl<B> RequestParts<B> { 
    }

}



/// Provides a protocol aware extraction from a [`Request`]. This borrows the

/// [`Parts`], in contrast to [`FromRequest`].

// NOTE: We cannot reference `FromRequest` here, as a point of contrast, as it's `doc(hidden)`.

/// Provides a protocol aware extraction from a requests [`Parts`].

pub trait FromParts<Protocol>: Sized {

    type Rejection: IntoResponse<Protocol>;

rust-runtime/aws-smithy-http-server/src/routing/route.rs

+4 −1
Original line number Diff line number Diff line
@@ -46,12 +46,15 @@ use tower::{ 
    Service, ServiceExt,

};



/// How routes are stored inside a [`Router`](super::Router).

/// A HTTP [`Service`] representing a single route.

///

/// The construction of [`Route`] from a named HTTP [`Service`] `S`, erases the type of `S`.

pub struct Route<B = Body> {

    service: BoxCloneService<Request<B>, Response<BoxBody>, Infallible>,

}



impl<B> Route<B> {

    /// Constructs a new [`Route`] from a well-formed HTTP service which is cloneable.

    pub fn new<T>(svc: T) -> Self

    where

        T: Service<Request<B>, Response = Response<BoxBody>, Error = Infallible> + Clone + Send + 'static,