Lines Matching full:middleware
4 - [Applying middleware](#applying-middleware)
5 - [Commonly used middleware](#commonly-used-middleware)
7 - [Writing middleware](#writing-middleware)
8 - [Routing to services/middleware and backpressure](#routing-to-servicesmiddleware-and-backpressure)
9 - [Accessing state in middleware](#accessing-state-in-middleware)
10 - [Passing state from middleware to handlers](#passing-state-from-middleware-to-handlers)
11 - [Rewriting request URI in middleware](#rewriting-request-uri-in-middleware)
15 axum is unique in that it doesn't have its own bespoke middleware system and
17 [`tower-http`] middleware all work with axum.
19 While its not necessary to fully understand tower to write or use middleware
24 # Applying middleware
26 axum allows you to add middleware just about anywhere
32 ## Applying multiple middleware
34 Its recommended to use [`tower::ServiceBuilder`] to apply multiple middleware at
63 # Commonly used middleware
65 Some commonly used middleware are:
80 When you add middleware with [`Router::layer`] (or similar) all previously added
81 routes will be wrapped in the middleware. Generally speaking, this results in
82 middleware being executed from bottom to top.
103 Think of the middleware as being layered like an onion where each new layer
134 It's a little more complicated in practice because any middleware is free to
138 As previously mentioned its recommended to add multiple middleware using
168 Executing middleware top to bottom is generally easier to understand and follow
171 # Writing middleware
173 axum offers many ways of writing middleware, at different levels of abstraction
176 ## `axum::middleware::from_fn`
178 Use [`axum::middleware::from_fn`] to write your middleware when:
182 - You don't intend to publish your middleware as a crate for others to use.
183 Middleware written like this are only compatible with axum.
185 ## `axum::middleware::from_extractor`
187 Use [`axum::middleware::from_extractor`] to write your middleware when:
190 as a middleware. If you only need your type as a middleware prefer
191 [`middleware::from_fn`].
206 - You don't intend to publish your middleware as a crate for others to use.
210 For maximum control (and a more low level API) you can write you own middleware
213 Use [`tower::Service`] with `Pin<Box<dyn Future>>` to write your middleware when:
215 - Your middleware needs to be configurable for example via builder methods on
217 - You do intend to publish your middleware as a crate for others to use.
220 A decent template for such a middleware could be:
278 Use [`tower::Service`] with manual futures to write your middleware when:
280 - You want your middleware to have the lowest possible overhead.
281 - Your middleware needs to be configurable for example via builder methods on
283 - You do intend to publish your middleware as a crate for others to use, perhaps
288 tower's ["Building a middleware from scratch"][tower-from-scratch-guide]
291 # Error handling for middleware
294 However middleware is one possible way to introduce errors into an application.
315 // this middleware goes above `TimeoutLayer` because it will receive
330 # Routing to services/middleware and backpressure
349 should avoid routing to a service (or using a middleware) that _does_ care
359 One possible approach is to only apply backpressure sensitive middleware
384 However when applying middleware around your whole application in this way
390 middleware you don't have to worry about any of this.
392 # Accessing state in middleware
394 How to make state available to middleware depends on how the middleware is
397 ## Accessing state in `axum::middleware::from_fn`
399 Use [`axum::middleware::from_fn_with_state`](crate::middleware::from_fn_with_state).
407 middleware::{self, Next},
473 # Passing state from middleware to handlers
475 State can be passed from middleware to handlers using [request extensions]:
483 middleware::{self, Next},
517 // extract the current user, set by the middleware
525 .route_layer(middleware::from_fn(auth));
533 # Rewriting request URI in middleware
535 Middleware added with [`Router::layer`] will run after routing. That means it
536 cannot be used to run middleware that rewrites the request URI. By the time the
537 middleware runs the routing is already done.
539 The workaround is to wrap the middleware around the entire `Router` (this works
548 middleware::Next,
558 let middleware = axum::middleware::from_fn(rewrite_request_uri);
563 // this way the middleware will run before `Router` receives the request
564 let app_with_middleware = middleware.layer(app);
577 [`axum::middleware::from_fn`]: fn@crate::middleware::from_fn
578 [`middleware::from_fn`]: fn@crate::middleware::from_fn
579 …-guide]: https://github.com/tower-rs/tower/blob/master/guides/building-a-middleware-from-scratch.md
584 [`axum::middleware::from_extractor`]: fn@crate::middleware::from_extractor