pub struct State<S>(pub S);
Expand description
Extractor for state.
Note this extractor is not available to middleware. See “Accessing state in middleware” for how to access state in middleware.
With Router
use axum::{Router, routing::get, extract::State};
// the application state
//
// here you can put configuration, database connection pools, or whatever
// state you need
#[derive(Clone)]
struct AppState {}
let state = AppState {};
// create a `Router` that holds our state
let app = Router::with_state(state).route("/", get(handler));
async fn handler(
// access the state via the `State` extractor
// extracting a state of the wrong type results in a compile error
State(state): State<AppState>,
) {
// use `state`...
}
With MethodRouter
use axum::{routing::get, extract::State};
#[derive(Clone)]
struct AppState {}
let state = AppState {};
let method_router_with_state = get(handler)
// provide the state so the handler can access it
.with_state(state);
async fn handler(State(state): State<AppState>) {
// use `state`...
}
With Handler
use axum::{routing::get, handler::Handler, extract::State};
#[derive(Clone)]
struct AppState {}
let state = AppState {};
async fn handler(State(state): State<AppState>) {
// use `state`...
}
// provide the state so the handler can access it
let handler_with_state = handler.with_state(state);
axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
.serve(handler_with_state.into_make_service())
.await
.expect("server failed");
Substates
State
only allows a single state type but you can use From
to extract “substates”:
use axum::{Router, routing::get, extract::{State, FromRef}};
// the application state
#[derive(Clone)]
struct AppState {
// that holds some api specific state
api_state: ApiState,
}
// the api specific state
#[derive(Clone)]
struct ApiState {}
// support converting an `AppState` in an `ApiState`
impl FromRef<AppState> for ApiState {
fn from_ref(app_state: &AppState) -> ApiState {
app_state.api_state.clone()
}
}
let state = AppState {
api_state: ApiState {},
};
let app = Router::with_state(state)
.route("/", get(handler))
.route("/api/users", get(api_users));
async fn api_users(
// access the api specific state
State(api_state): State<ApiState>,
) {
}
async fn handler(
// we can still access to top level state
State(state): State<AppState>,
) {
}
For library authors
If you’re writing a library that has an extractor that needs state, this is the recommended way to do it:
use axum_core::extract::{FromRequestParts, FromRef};
use http::request::Parts;
use async_trait::async_trait;
use std::convert::Infallible;
// the extractor your library provides
struct MyLibraryExtractor;
#[async_trait]
impl<S> FromRequestParts<S> for MyLibraryExtractor
where
// keep `S` generic but require that it can produce a `MyLibraryState`
// this means users will have to implement `FromRef<UserState> for MyLibraryState`
MyLibraryState: FromRef<S>,
S: Send + Sync,
{
type Rejection = Infallible;
async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
// get a `MyLibraryState` from a reference to the state
let state = MyLibraryState::from_ref(state);
// ...
}
}
// the state your library needs
struct MyLibraryState {
// ...
}
Tuple Fields
0: S
Trait Implementations
sourceimpl<OuterState, InnerState> FromRequestParts<OuterState> for State<InnerState> where
InnerState: FromRef<OuterState>,
OuterState: Send + Sync,
impl<OuterState, InnerState> FromRequestParts<OuterState> for State<InnerState> where
InnerState: FromRef<OuterState>,
OuterState: Send + Sync,
type Rejection = Infallible
type Rejection = Infallible
If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response. Read more
impl<S: Copy> Copy for State<S>
Auto Trait Implementations
impl<S> RefUnwindSafe for State<S> where
S: RefUnwindSafe,
impl<S> Send for State<S> where
S: Send,
impl<S> Sync for State<S> where
S: Sync,
impl<S> Unpin for State<S> where
S: Unpin,
impl<S> UnwindSafe for State<S> where
S: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<S, B, T> FromRequest<S, B, ViaParts> for T where
B: 'static + Send,
S: Send + Sync,
T: FromRequestParts<S>,
impl<S, B, T> FromRequest<S, B, ViaParts> for T where
B: 'static + Send,
S: Send + Sync,
T: FromRequestParts<S>,
type Rejection = <T as FromRequestParts<S>>::Rejection
type Rejection = <T as FromRequestParts<S>>::Rejection
If the extractor fails it’ll use this “rejection” type. A rejection is a kind of error that can be converted into a response. Read more
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
sourcefn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
sourceimpl<T> PolicyExt for T where
T: ?Sized,
impl<T> PolicyExt for T where
T: ?Sized,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> where
S: Into<Dispatch>,
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more