Merge 76d75a37f1 into 3c2907da41

Add comprehensive documentation for middleware development in Actix Web, including:
- Detailed explanation of middleware concepts and execution flow
- Clear description of middleware traits and their responsibilities
- Guidelines for body type handling
- Best practices for middleware development
- Error handling recommendations
- Usage scenarios and anti-patterns

Co-authored-by: chenjjiaa <chenjjiaaa@gmail.com>

actix-files/CHANGES.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Option to supply multiple index fallbacks now supported.
 - Minimum supported Rust version (MSRV) is now 1.75.
 
 ## 0.6.6

actix-files/src/files.rs

@@ -38,7 +38,7 @@ use crate::{
 pub struct Files {
     mount_path: String,
     directory: PathBuf,
-    index: Option<String>,
+    indexes: Vec<String>,
     show_index: bool,
     redirect_to_slash: bool,
     default: Rc<RefCell<Option<Rc<HttpNewService>>>>,
@@ -61,7 +61,7 @@ impl Clone for Files {
     fn clone(&self) -> Self {
         Self {
             directory: self.directory.clone(),
-            index: self.index.clone(),
+            indexes: self.indexes.clone(),
             show_index: self.show_index,
             redirect_to_slash: self.redirect_to_slash,
             default: self.default.clone(),
@@ -108,7 +108,7 @@ impl Files {
         Files {
             mount_path: mount_path.trim_end_matches('/').to_owned(),
             directory: dir,
-            index: None,
+            indexes: Vec::new(),
             show_index: false,
             redirect_to_slash: false,
             default: Rc::new(RefCell::new(None)),
@@ -192,15 +192,19 @@ impl Files {
         self
     }
 
-    /// Set index file
+    /// Set an index file
     ///
     /// Shows specific index file for directories instead of
     /// showing files listing.
     ///
+    /// This function can be called multiple times to configure
+    /// a list of index fallbacks with their priority set to the
+    /// order of their addition.
+    ///
     /// If the index file is not found, files listing is shown as a fallback if
     /// [`Files::show_files_listing()`] is set.
     pub fn index_file<T: Into<String>>(mut self, index: T) -> Self {
-        self.index = Some(index.into());
+        self.indexes.push(index.into());
         self
     }
 
@@ -357,7 +361,7 @@ impl ServiceFactory<ServiceRequest> for Files {
     fn new_service(&self, _: ()) -> Self::Future {
         let mut inner = FilesServiceInner {
             directory: self.directory.clone(),
-            index: self.index.clone(),
+            indexes: self.indexes.clone(),
             show_index: self.show_index,
             redirect_to_slash: self.redirect_to_slash,
             default: None,

actix-files/src/service.rs

@@ -29,7 +29,7 @@ impl Deref for FilesService {
 
 pub struct FilesServiceInner {
     pub(crate) directory: PathBuf,
-    pub(crate) index: Option<String>,
+    pub(crate) indexes: Vec<String>,
     pub(crate) show_index: bool,
     pub(crate) redirect_to_slash: bool,
     pub(crate) default: Option<HttpService>,
@@ -141,7 +141,7 @@ impl Service<ServiceRequest> for FilesService {
             if path.is_dir() {
                 if this.redirect_to_slash
                     && !req.path().ends_with('/')
-                    && (this.index.is_some() || this.show_index)
+                    && (!this.indexes.is_empty() || this.show_index)
                 {
                     let redirect_to = format!("{}/", req.path());
 
@@ -152,15 +152,18 @@ impl Service<ServiceRequest> for FilesService {
                     ));
                 }
 
-                match this.index {
-                    Some(ref index) => {
-                        let named_path = path.join(index);
-                        match NamedFile::open_async(named_path).await {
-                            Ok(named_file) => Ok(this.serve_named_file(req, named_file)),
-                            Err(_) if this.show_index => Ok(this.show_index(req, path)),
-                            Err(err) => this.handle_err(err, req).await,
-                        }
-                    }
+                let index = this
+                    .indexes
+                    .iter()
+                    .map(|i| path.join(i))
+                    .find(|p| p.exists());
+
+                match index {
+                    Some(ref named_path) => match NamedFile::open_async(named_path).await {
+                        Ok(named_file) => Ok(this.serve_named_file(req, named_file)),
+                        Err(_) if this.show_index => Ok(this.show_index(req, path)),
+                        Err(err) => this.handle_err(err, req).await,
+                    },
                     None if this.show_index => Ok(this.show_index(req, path)),
                     None => Ok(ServiceResponse::from_err(
                         FilesError::IsDirectory,

actix-http/CHANGES.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Properly wake Payload receivers when feeding errors or EOF
+
 ## 3.11.1
 
 - Prevent more hangs after client disconnects.

actix-http/Cargo.toml

@@ -156,7 +156,7 @@ serde_json = "1.0"
 static_assertions = "1"
 tls-openssl = { package = "openssl", version = "0.10.55" }
 tls-rustls_023 = { package = "rustls", version = "0.23" }
-tokio = { version = "1.38.2", features = ["net", "rt", "macros"] }
+tokio = { version = "1.38.2", features = ["net", "rt", "macros", "sync"] }
 
 [lints]
 workspace = true

actix-http/src/h1/payload.rs

@@ -200,11 +200,13 @@ impl Inner {
     #[inline]
     fn set_error(&mut self, err: PayloadError) {
         self.err = Some(err);
+        self.wake();
     }
 
     #[inline]
     fn feed_eof(&mut self) {
         self.eof = true;
+        self.wake();
     }
 
     #[inline]
@@ -253,8 +255,13 @@ impl Inner {
 
 #[cfg(test)]
 mod tests {
+    use std::{task::Poll, time::Duration};
+
+    use actix_rt::time::timeout;
     use actix_utils::future::poll_fn;
+    use futures_util::{FutureExt, StreamExt};
     use static_assertions::{assert_impl_all, assert_not_impl_any};
+    use tokio::sync::oneshot;
 
     use super::*;
 
@@ -263,6 +270,67 @@ mod tests {
 
     assert_impl_all!(Inner: Unpin, Send, Sync);
 
+    const WAKE_TIMEOUT: Duration = Duration::from_secs(2);
+
+    fn prepare_waking_test(
+        mut payload: Payload,
+        expected: Option<Result<(), ()>>,
+    ) -> (oneshot::Receiver<()>, actix_rt::task::JoinHandle<()>) {
+        let (tx, rx) = oneshot::channel();
+
+        let handle = actix_rt::spawn(async move {
+            // Make sure to poll once to set the waker
+            poll_fn(|cx| {
+                assert!(payload.poll_next_unpin(cx).is_pending());
+                Poll::Ready(())
+            })
+            .await;
+            tx.send(()).unwrap();
+
+            // actix-rt is single-threaded, so this won't race with `rx.await`
+            let mut pend_once = false;
+            poll_fn(|_| {
+                if pend_once {
+                    Poll::Ready(())
+                } else {
+                    // Return pending without storing wakers, we already did on the previous
+                    // `poll_fn`, now this task will only continue if the `sender` wakes us
+                    pend_once = true;
+                    Poll::Pending
+                }
+            })
+            .await;
+
+            let got = payload.next().now_or_never().unwrap();
+            match expected {
+                Some(Ok(_)) => assert!(got.unwrap().is_ok()),
+                Some(Err(_)) => assert!(got.unwrap().is_err()),
+                None => assert!(got.is_none()),
+            }
+        });
+        (rx, handle)
+    }
+
+    #[actix_rt::test]
+    async fn wake_on_error() {
+        let (mut sender, payload) = Payload::create(false);
+        let (rx, handle) = prepare_waking_test(payload, Some(Err(())));
+
+        rx.await.unwrap();
+        sender.set_error(PayloadError::Incomplete(None));
+        timeout(WAKE_TIMEOUT, handle).await.unwrap().unwrap();
+    }
+
+    #[actix_rt::test]
+    async fn wake_on_eof() {
+        let (mut sender, payload) = Payload::create(false);
+        let (rx, handle) = prepare_waking_test(payload, None);
+
+        rx.await.unwrap();
+        sender.feed_eof();
+        timeout(WAKE_TIMEOUT, handle).await.unwrap().unwrap();
+    }
+
     #[actix_rt::test]
     async fn test_unread_data() {
         let (_, mut payload) = Payload::create(false);

actix-web-actors/Cargo.toml

@@ -24,7 +24,7 @@ allowed_external_types = [
 actix = { version = ">=0.12, <0.14", default-features = false }
 actix-codec = "0.5"
 actix-http = "3"
-actix-web = { version = "4", default-features = false }
+actix-web = { version = "4", default-features = false, features = ["ws"] }
 
 bytes = "1"
 bytestring = "1"

actix-web/CHANGES.md

@@ -4,6 +4,7 @@
 
 - `actix_web::response::builder::HttpResponseBuilder::streaming()` now sets `Content-Type` to `application/octet-stream` if `Content-Type` does not exist.
 - `actix_web::response::builder::HttpResponseBuilder::streaming()` now calls `actix_web::response::builder::HttpResponseBuilder::no_chunking()` if `Content-Length` is set by user.
+- Add `ws` crate feature (on-by-default) which forwards to `actix-http` and guards some of its `ResponseError` impls.
 
 ## 4.11.0
 

actix-web/Cargo.toml

@@ -67,6 +67,7 @@ default = [
   "http2",
   "unicode",
   "compat",
+  "ws",
 ]
 
 # Brotli algorithm content-encoding support
@@ -85,9 +86,12 @@ cookies = ["dep:cookie"]
 # Secure & signed cookies
 secure-cookies = ["cookies", "cookie/secure"]
 
-# HTTP/2 support (including h2c).
+# HTTP/2 support (including h2c)
 http2 = ["actix-http/http2"]
 
+# WebSocket support
+ws = ["actix-http/ws"]
+
 # TLS via OpenSSL
 openssl = ["__tls", "http2", "actix-http/openssl", "actix-tls/accept", "actix-tls/openssl"]
 
@@ -131,7 +135,7 @@ actix-service = "2"
 actix-tls = { version = "3.4", default-features = false, optional = true }
 actix-utils = "3"
 
-actix-http = { version = "3.11", features = ["ws"] }
+actix-http = "3.11"
 actix-router = { version = "0.5.3", default-features = false, features = ["http"] }
 actix-web-codegen = { version = "4.3", optional = true, default-features = false }
 

actix-web/src/error/response_error.rs

@@ -7,7 +7,6 @@ use std::{
     io::{self, Write as _},
 };
 
-use actix_http::Response;
 use bytes::BytesMut;
 
 use crate::{
@@ -126,20 +125,24 @@ impl ResponseError for actix_http::error::PayloadError {
     }
 }
 
-impl ResponseError for actix_http::ws::ProtocolError {}
-
 impl ResponseError for actix_http::error::ContentTypeError {
     fn status_code(&self) -> StatusCode {
         StatusCode::BAD_REQUEST
     }
 }
 
+#[cfg(feature = "ws")]
 impl ResponseError for actix_http::ws::HandshakeError {
     fn error_response(&self) -> HttpResponse<BoxBody> {
-        Response::from(self).map_into_boxed_body().into()
+        actix_http::Response::from(self)
+            .map_into_boxed_body()
+            .into()
     }
 }
 
+#[cfg(feature = "ws")]
+impl ResponseError for actix_http::ws::ProtocolError {}
+
 #[cfg(test)]
 mod tests {
     use super::*;

actix-web/src/middleware/authors-guide.md

@@ -2,16 +2,80 @@
 
 ## What Is A Middleware?
 
+Middleware in Actix Web is a powerful mechanism that allows you to add additional behavior to request/response processing. It enables you to:
+
+- Pre-process incoming requests (e.g., path normalization, authentication)
+- Post-process outgoing responses (e.g., logging, compression)
+- Modify application state through ServiceRequest
+- Access external services (e.g., sessions, caching)
+
+Middleware is registered for each App, Scope, or Resource and executed in the reverse order of registration. This means the last registered middleware is the first to process the request.
+
 ## Middleware Traits
 
+Actix Web's middleware system is built on two main traits:
+
+1. `Transform<S, Req>`: The builder trait that creates the actual Service. It's responsible for:
+
+   - Creating new middleware instances
+   - Assembling the middleware chain
+   - Handling initialization errors
+
+2. `Service<Req>`: The trait that represents the actual middleware functionality. It:
+   - Processes requests and responses
+   - Can modify both request and response
+   - Can short-circuit request processing
+   - Must be implemented for the middleware to work
+
 ## Understanding Body Types
 
+When working with middleware, it's important to understand body types:
+
+- Middleware can work with different body types for requests and responses
+- The `MessageBody` trait is used to handle different body types
+- You can use `EitherBody` when you need to handle multiple body types
+- Be careful with body consumption - once a body is consumed, it cannot be read again
+
 ## Best Practices
 
+1. Keep middleware focused and single-purpose
+2. Handle errors appropriately and propagate them correctly
+3. Be mindful of performance impact
+4. Use appropriate body types and handle them correctly
+5. Consider middleware ordering carefully
+6. Document your middleware's behavior and requirements
+7. Test your middleware thoroughly
+
 ## Error Propagation
 
+Proper error handling is crucial in middleware:
+
+1. Always propagate errors from the inner service
+2. Use appropriate error types
+3. Handle initialization errors
+4. Consider using custom error types for specific middleware errors
+5. Document error conditions and handling
+
 ## When To (Not) Use Middleware
 
+Use middleware when you need to:
+
+- Add cross-cutting concerns
+- Modify requests/responses globally
+- Add authentication/authorization
+- Add logging or monitoring
+- Handle compression or caching
+
+Avoid middleware when:
+
+- The functionality is specific to a single route
+- The operation is better handled by a service
+- The overhead would be too high
+- The functionality can be implemented more simply
+
 ## Author's References
 
 - `EitherBody` + when is middleware appropriate: https://discord.com/channels/771444961383153695/952016890723729428
+- Actix Web Documentation: https://docs.rs/actix-web
+- Service Trait Documentation: https://docs.rs/actix-service
+- MessageBody Trait Documentation: https://docs.rs/actix-web/latest/actix_web/body/trait.MessageBody.html