Skip to main content

loco_rs/controller/middleware/
mod.rs

1//! Base Middleware for Loco Application
2//!
3//! This module defines the various middleware components that Loco provides.
4//! Each middleware is responsible for handling different aspects of request
5//! processing, such as authentication, logging, CORS, compression, and error
6//! handling. The middleware can be easily configured and applied to the
7//! application's router.
8
9#[cfg(feature = "auth_session")]
10pub mod auth_session;
11pub mod catch_panic;
12pub mod compression;
13pub mod cors;
14pub mod etag;
15pub mod fallback;
16pub mod format;
17pub mod limit_payload;
18pub mod logger;
19pub mod powered_by;
20pub mod remote_ip;
21pub mod request_id;
22pub mod secure_headers;
23#[cfg(feature = "embedded_assets")]
24pub mod static_assets_embedded;
25#[cfg(feature = "embedded_assets")]
26pub use static_assets_embedded as static_assets;
27
28#[cfg(not(feature = "embedded_assets"))]
29pub mod static_assets;
30pub mod timeout;
31
32use axum::Router as AXRouter;
33use serde::{Deserialize, Serialize};
34
35use crate::{app::AppContext, environment::Environment, Result};
36
37/// Trait representing the behavior of middleware components in the application.
38/// When implementing a new middleware, make sure to go over this checklist:
39/// * The name of the middleware should be an ID that is similar to the field
40///   name in configuration (look at how `serde` calls it)
41/// * Default value implementation should be paired with `serde` default
42///   handlers and default serialization implementation. Which means deriving
43///   `Default` will _not_ work. You can use `serde_json` and serialize a new
44///   config from an empty value, which will cause `serde` default value
45///   handlers to kick in.
46/// * If you need completely blank values for configuration (for example for
47///   testing), implement an `::empty() -> Self` call ad-hoc.
48pub trait MiddlewareLayer {
49    /// Returns the name of the middleware.
50    /// This should match the name of the property in the containing
51    /// `middleware` section in configuration (as named by `serde`)
52    fn name(&self) -> &'static str;
53
54    /// Returns whether the middleware is enabled or not.
55    /// If the middleware is switchable, take this value from a configuration
56    /// value
57    fn is_enabled(&self) -> bool {
58        true
59    }
60
61    /// Returns middleware config.
62    ///
63    /// # Errors
64    /// when could not convert middleware to [`serde_json::Value`]
65    fn config(&self) -> serde_json::Result<serde_json::Value>;
66
67    /// Applies the middleware to the given Axum router and returns the modified
68    /// router.
69    ///
70    /// # Errors
71    ///
72    /// If there is an issue when adding the middleware to the router.
73    fn apply(&self, app: AXRouter<AppContext>) -> Result<AXRouter<AppContext>>;
74}
75
76/// A middleware config with every field at its serde default.
77///
78/// Decodes an empty YAML mapping, the same path the config file takes, so
79/// this reuses that decoding code rather than compiling a second copy for
80/// another format.
81pub(crate) fn defaults<T: serde::de::DeserializeOwned>() -> T {
82    serde_yaml::from_value(serde_yaml::Value::Mapping(serde_yaml::Mapping::new()))
83        .expect("every middleware config field has a serde default")
84}
85
86#[allow(clippy::unnecessary_lazy_evaluations)]
87#[must_use]
88pub fn default_middleware_stack(ctx: &AppContext) -> Vec<Box<dyn MiddlewareLayer>> {
89    // Shortened reference to middlewares
90    let middlewares = &ctx.config.server.middlewares;
91
92    #[allow(unused_mut)]
93    let mut stack: Vec<Box<dyn MiddlewareLayer>> =
94        vec![
95            // Limit Payload middleware with a default if none
96            Box::new(middlewares.limit_payload.clone().unwrap_or_default()),
97            // CORS middleware with a default if none
98            Box::new(middlewares.cors.clone().unwrap_or_else(|| cors::Cors {
99                enable: false,
100                ..Default::default()
101            })),
102            // Catch Panic middleware with a default if none
103            Box::new(
104                middlewares
105                    .catch_panic
106                    .clone()
107                    .unwrap_or_else(|| catch_panic::CatchPanic { enable: true }),
108            ),
109            // Etag middleware with a default if none
110            Box::new(
111                middlewares
112                    .etag
113                    .clone()
114                    .unwrap_or_else(|| etag::Etag { enable: true }),
115            ),
116            // Remote IP middleware with a default if none
117            Box::new(middlewares.remote_ip.clone().unwrap_or_else(|| {
118                remote_ip::RemoteIpMiddleware {
119                    enable: false,
120                    ..Default::default()
121                }
122            })),
123            // Compression middleware with a default if none
124            Box::new(
125                middlewares
126                    .compression
127                    .clone()
128                    .unwrap_or_else(|| compression::Compression { enable: false }),
129            ),
130            // Timeout Request middleware with a default if none
131            Box::new(
132                middlewares
133                    .timeout_request
134                    .clone()
135                    .unwrap_or_else(|| timeout::TimeOut {
136                        enable: false,
137                        ..Default::default()
138                    }),
139            ),
140            // Static Assets middleware with a default if none
141            Box::new(middlewares.static_assets.clone().unwrap_or_else(|| {
142                static_assets::StaticAssets {
143                    enable: false,
144                    ..Default::default()
145                }
146            })),
147            // Secure Headers middleware with a default if none
148            Box::new(middlewares.secure_headers.clone().unwrap_or_else(|| {
149                secure_headers::SecureHeader {
150                    enable: false,
151                    ..Default::default()
152                }
153            })),
154            // Logger middleware with default logger configuration
155            Box::new(logger::new(
156                &middlewares
157                    .logger
158                    .clone()
159                    .unwrap_or_else(|| logger::Config { enable: true }),
160                &ctx.environment,
161            )),
162            // Request ID middleware with a default if none
163            Box::new(
164                middlewares
165                    .request_id
166                    .clone()
167                    .unwrap_or_else(|| request_id::RequestId { enable: true }),
168            ),
169            // Fallback middleware with a default if none
170            Box::new(
171                middlewares
172                    .fallback
173                    .clone()
174                    .unwrap_or_else(|| fallback::Fallback {
175                        enable: ctx.environment != Environment::Production,
176                        ..Default::default()
177                    }),
178            ),
179            // Powered by middleware with a default identifier
180            Box::new(powered_by::new(ctx.config.server.ident.as_deref())),
181        ];
182    // Writes server-side session changes before the response is sent; only
183    // active with `auth.session.store: database | redis`.
184    #[cfg(feature = "auth_session")]
185    stack.insert(1, Box::new(auth_session::AuthSession::new(ctx)));
186    stack
187}
188
189/// Ergonomic, Rails-style edits to a middleware stack.
190///
191/// Operates on a `Vec<Box<dyn MiddlewareLayer>>`, for use inside
192/// [`crate::app::Hooks::middlewares`] when you want to tweak the default stack
193/// (from [`default_middleware_stack`]) rather than rebuild it.
194///
195/// Middlewares are matched by [`MiddlewareLayer::name`]. Positions are relative
196/// to the stack `Vec`. Note the application order: the stack is applied in `Vec`
197/// order and each middleware wraps the router, so a middleware **later** in the
198/// `Vec` runs **earlier** in request processing (tower is LIFO).
199///
200/// If no middleware matches `name`, the operation logs a warning; `insert_before`
201/// / `insert_after` still append the new middleware (so it is not silently
202/// dropped), while `replace` / `delete` leave the stack unchanged.
203pub trait MiddlewareStackExt {
204    /// Insert `middleware` immediately before the first middleware named `name`.
205    fn insert_before(&mut self, name: &str, middleware: Box<dyn MiddlewareLayer>) -> &mut Self;
206    /// Insert `middleware` immediately after the first middleware named `name`.
207    fn insert_after(&mut self, name: &str, middleware: Box<dyn MiddlewareLayer>) -> &mut Self;
208    /// Replace the first middleware named `name` with `middleware`.
209    fn replace(&mut self, name: &str, middleware: Box<dyn MiddlewareLayer>) -> &mut Self;
210    /// Remove the first middleware named `name`.
211    fn delete(&mut self, name: &str) -> &mut Self;
212}
213
214impl MiddlewareStackExt for Vec<Box<dyn MiddlewareLayer>> {
215    fn insert_before(&mut self, name: &str, middleware: Box<dyn MiddlewareLayer>) -> &mut Self {
216        if let Some(idx) = self.iter().position(|m| m.name() == name) {
217            self.insert(idx, middleware);
218        } else {
219            tracing::warn!(
220                middleware = name,
221                "insert_before: no middleware named `{name}` in the stack; appending instead"
222            );
223            self.push(middleware);
224        }
225        self
226    }
227
228    fn insert_after(&mut self, name: &str, middleware: Box<dyn MiddlewareLayer>) -> &mut Self {
229        if let Some(idx) = self.iter().position(|m| m.name() == name) {
230            self.insert(idx + 1, middleware);
231        } else {
232            tracing::warn!(
233                middleware = name,
234                "insert_after: no middleware named `{name}` in the stack; appending instead"
235            );
236            self.push(middleware);
237        }
238        self
239    }
240
241    fn replace(&mut self, name: &str, middleware: Box<dyn MiddlewareLayer>) -> &mut Self {
242        if let Some(idx) = self.iter().position(|m| m.name() == name) {
243            self[idx] = middleware;
244        } else {
245            tracing::warn!(
246                middleware = name,
247                "replace: no middleware named `{name}` in the stack; leaving stack unchanged"
248            );
249        }
250        self
251    }
252
253    fn delete(&mut self, name: &str) -> &mut Self {
254        if let Some(idx) = self.iter().position(|m| m.name() == name) {
255            self.remove(idx);
256        } else {
257            tracing::warn!(
258                middleware = name,
259                "delete: no middleware named `{name}` in the stack; leaving stack unchanged"
260            );
261        }
262        self
263    }
264}
265
266/// Server middleware configuration structure.
267#[derive(Default, Debug, Clone, Deserialize, Serialize)]
268pub struct Config {
269    /// Compression for the response.
270    pub compression: Option<compression::Compression>,
271
272    /// Etag cache headers.
273    pub etag: Option<etag::Etag>,
274
275    /// Limit the payload request.
276    pub limit_payload: Option<limit_payload::LimitPayload>,
277
278    /// Logger and augmenting trace id with request data
279    pub logger: Option<logger::Config>,
280
281    /// Catch any code panic and log the error.
282    pub catch_panic: Option<catch_panic::CatchPanic>,
283
284    /// Setting a global timeout for requests
285    pub timeout_request: Option<timeout::TimeOut>,
286
287    /// CORS configuration
288    pub cors: Option<cors::Cors>,
289
290    /// Serving static assets
291    #[serde(rename = "static")]
292    pub static_assets: Option<static_assets::StaticAssets>,
293
294    /// Sets a set of secure headers
295    pub secure_headers: Option<secure_headers::SecureHeader>,
296
297    /// Resolves the client's remote IP from a single, configured, trusted
298    /// source (a header such as `X-Forwarded-For`, or the raw socket) when
299    /// behind a proxy or load balancer.
300    pub remote_ip: Option<remote_ip::RemoteIpMiddleware>,
301
302    /// Configure fallback behavior when hitting a missing URL
303    pub fallback: Option<fallback::Fallback>,
304
305    /// Request ID
306    pub request_id: Option<request_id::RequestId>,
307}
308
309#[cfg(test)]
310mod stack_ext_tests {
311    use super::{MiddlewareLayer, MiddlewareStackExt};
312
313    struct DummyMw(&'static str);
314    impl MiddlewareLayer for DummyMw {
315        fn name(&self) -> &'static str {
316            self.0
317        }
318        fn config(&self) -> serde_json::Result<serde_json::Value> {
319            Ok(serde_json::Value::Null)
320        }
321        fn apply(
322            &self,
323            app: axum::Router<crate::app::AppContext>,
324        ) -> crate::Result<axum::Router<crate::app::AppContext>> {
325            Ok(app)
326        }
327    }
328
329    fn stack(names: &[&'static str]) -> Vec<Box<dyn MiddlewareLayer>> {
330        names
331            .iter()
332            .map(|n| Box::new(DummyMw(n)) as Box<dyn MiddlewareLayer>)
333            .collect()
334    }
335
336    fn names(stack: &[Box<dyn MiddlewareLayer>]) -> Vec<&'static str> {
337        stack.iter().map(|m| m.name()).collect()
338    }
339
340    #[test]
341    fn insert_before_hit() {
342        let mut s = stack(&["a", "b", "c"]);
343        s.insert_before("b", Box::new(DummyMw("x")));
344        assert_eq!(names(&s), vec!["a", "x", "b", "c"]);
345    }
346
347    #[test]
348    fn insert_after_hit() {
349        let mut s = stack(&["a", "b", "c"]);
350        s.insert_after("b", Box::new(DummyMw("x")));
351        assert_eq!(names(&s), vec!["a", "b", "x", "c"]);
352    }
353
354    #[test]
355    fn insert_before_miss_appends() {
356        let mut s = stack(&["a", "b", "c"]);
357        s.insert_before("nope", Box::new(DummyMw("x")));
358        assert_eq!(names(&s), vec!["a", "b", "c", "x"]);
359    }
360
361    #[test]
362    fn insert_after_miss_appends() {
363        let mut s = stack(&["a", "b", "c"]);
364        s.insert_after("nope", Box::new(DummyMw("x")));
365        assert_eq!(names(&s), vec!["a", "b", "c", "x"]);
366    }
367
368    #[test]
369    fn replace_hit() {
370        let mut s = stack(&["a", "b", "c"]);
371        s.replace("b", Box::new(DummyMw("x")));
372        assert_eq!(names(&s), vec!["a", "x", "c"]);
373        assert_eq!(s.len(), 3);
374    }
375
376    #[test]
377    fn replace_miss_no_op() {
378        let mut s = stack(&["a", "b", "c"]);
379        s.replace("nope", Box::new(DummyMw("x")));
380        assert_eq!(names(&s), vec!["a", "b", "c"]);
381    }
382
383    #[test]
384    fn delete_hit() {
385        let mut s = stack(&["a", "b", "c"]);
386        s.delete("b");
387        assert_eq!(names(&s), vec!["a", "c"]);
388        assert_eq!(s.len(), 2);
389    }
390
391    #[test]
392    fn delete_miss_no_op() {
393        let mut s = stack(&["a", "b", "c"]);
394        s.delete("nope");
395        assert_eq!(names(&s), vec!["a", "b", "c"]);
396        assert_eq!(s.len(), 3);
397    }
398
399    #[test]
400    fn chaining_returns_mut_self() {
401        let mut s = stack(&["a", "b", "c"]);
402        s.insert_before("a", Box::new(DummyMw("x")))
403            .insert_after("c", Box::new(DummyMw("y")))
404            .replace("b", Box::new(DummyMw("z")))
405            .delete("a");
406        assert_eq!(names(&s), vec!["x", "z", "c", "y"]);
407    }
408}