From f14800be20429edf7bc363ce0d2bbe0b0f98c181 Mon Sep 17 00:00:00 2001 From: fakeshadow <24548779@qq.com> Date: Wed, 7 Feb 2024 00:57:46 +0800 Subject: [PATCH 1/2] populate more doc sessions. --- web/src/middleware/mod.rs | 33 ++++++++++++++++++++++++--------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/web/src/middleware/mod.rs b/web/src/middleware/mod.rs index 877e1c2a..f987aa6d 100644 --- a/web/src/middleware/mod.rs +++ b/web/src/middleware/mod.rs @@ -1,8 +1,8 @@ //! middleware types. //! -//! Middleware in xitca-web is powered by [Service] and [ServiceExt] trait. -//! [Service] trait provides logic for building and execute middleware. -//! [ServiceExt] trait provides combinator methods of applying middleware. +//! Middleware in xitca-web is powered by [`Service`] and [`ServiceExt`] trait. +//! [`Service`] trait provides logic for building and execute middleware. +//! [`ServiceExt`] trait provides combinator methods of applying middleware. //! //! # Quick start //! ```rust @@ -110,7 +110,7 @@ //! # todo!() //! # } //! ``` -//! For detailed explanation of application state please reference [App::with_state] +//! For detailed explanation of application state please reference [`App::with_state`] //! //! ## Generic type for http body //! ```rust @@ -143,7 +143,7 @@ //! # todo!() //! # } //! ``` -//! For http body type mutation please reference the `Type Mutation` part below. +//! For http body type mutation please reference the [`Type Mutation`](#type-mutation) part below. //! //! # Variants //! ## async function as middleware @@ -273,10 +273,25 @@ //! - `enclosed` and `enclosed_fn` share the same ordering rule however they are mixed in usage //! //! # Type mutation -//! -//! [App::with_state]: crate::App::with_state -//! [Service]: crate::service::Service -//! [ServiceExt]: crate::service::ServiceExt +//! - In [`WebContext<'_, C, B>`] type the last generic type param `B` is for http body type. +//! middleware and service are free to transform it's type and constraint it's inner/next service +//! to accept the new type as it's request http body type. [`DeCompress`] and [`Limit`] middleware are +//! examples of this practice. [`TypeEraser`] middleware on the other hand can be used to reserve the +//! type mutation and restore `B` type to it's default as [`RequestBody`] type. In this case web context +//! can be written in short form as [`WebContext<'_, C>`]. +//! - [`WebResponse`] type share the characteristic as web context type. The `B` type can be transform +//! into new type by services and middleware while type eraser is able to reverse the process. +//! +//! [`App::with_state`]: crate::App::with_state +//! [`Service`]: crate::service::Service +//! [`ServiceExt`]: crate::service::ServiceExt +//! [`WebContext<'_, C, B>`]: crate::WebContext +//! [`WebContext<'_, C>`]: crate::WebContext +//! [`Decompress`]: crate::middleware::decompress::Decompress +//! [`Limit`]: crate::middleware::limit::Limit +//! [`TypeEraser`]: crate::middleware::eraser::TypeEraser +//! [`RequestBody`]: crate::body::RequestBody +//! [`WebResponse`]: crate::http::WebResponse #[cfg(any(feature = "compress-br", feature = "compress-gz", feature = "compress-de"))] pub mod compress; From 50b844cfd7b4b631fb25735b996365709dd4e3ac Mon Sep 17 00:00:00 2001 From: fakeshadow <24548779@qq.com> Date: Wed, 7 Feb 2024 01:05:02 +0800 Subject: [PATCH 2/2] more doc. --- web/src/middleware/compress.rs | 1 + web/src/middleware/decompress.rs | 1 + web/src/middleware/limit.rs | 7 ++++--- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/web/src/middleware/compress.rs b/web/src/middleware/compress.rs index f5b7b146..f6954f29 100644 --- a/web/src/middleware/compress.rs +++ b/web/src/middleware/compress.rs @@ -9,6 +9,7 @@ use crate::service::Service; /// # Type mutation /// `Compress` would mutate response body type from `B` to `Coder`. Service enclosed /// by it must be able to handle it's mutation or utilize [TypeEraser] to erase the mutation. +/// For more explanation please reference [type mutation](crate::middleware#type-mutation). /// /// [WebRequest]: crate::http::WebRequest /// [WebResponse]: crate::http::WebResponse diff --git a/web/src/middleware/decompress.rs b/web/src/middleware/decompress.rs index 51844492..58a637e6 100644 --- a/web/src/middleware/decompress.rs +++ b/web/src/middleware/decompress.rs @@ -9,6 +9,7 @@ use crate::service::Service; /// # Type mutation /// `Decompress` would mutate request body type from `B` to `Coder`. Service enclosed /// by it must be able to handle it's mutation or utilize [TypeEraser] to erase the mutation. +/// For more explanation please reference [type mutation](crate::middleware#type-mutation). /// /// [WebContext]: crate::WebContext /// [TypeEraser]: crate::middleware::eraser::TypeEraser diff --git a/web/src/middleware/limit.rs b/web/src/middleware/limit.rs index 808e8ea5..6ab44973 100644 --- a/web/src/middleware/limit.rs +++ b/web/src/middleware/limit.rs @@ -23,10 +23,11 @@ use crate::{ /// General purposed limitation middleware. Limiting request/response body size etc. /// /// # Type mutation -/// `Limit` would mutate request body type from `B` to `Limit`. Service enclosed -/// by it must be able to handle it's mutation or utilize [TypeEraser] to erase the mutation. +/// [`Limit`] would mutate request body type from `B` to [`Limit`]. Service enclosed by it must be +/// able to handle it's mutation or utilize [`TypeEraser`] to erase the mutation. +/// For more explanation please reference [`type mutation`](crate::middleware#type-mutation). /// -/// [TypeEraser]: crate::middleware::eraser::TypeEraser +/// [`TypeEraser`]: crate::middleware::eraser::TypeEraser #[derive(Copy, Clone)] pub struct Limit { request_body_size: usize,