# Struct actix_session::SessionMiddleware

source ·

    pub struct SessionMiddleware<Store: SessionStore> { /* private fields */ }

Expand description

A middleware for session management in Actix Web applications.

`SessionMiddleware` takes care of a few jobs:

- Instructs the session storage backend to create/update/delete/retrieve the state attached to a session according to its status and the operations that have been performed against it;
- Set/remove a cookie, on the client side, to enable a user to be consistently associated with the same session across multiple HTTP requests.

Use `SessionMiddleware::new` to initialize the session framework using the default parameters. To create a new instance of `SessionMiddleware` you need to provide:

- an instance of the session storage backend you wish to use (i.e. an implementation of `SessionStore`);
- a secret key, to sign or encrypt the content of client-side session cookie.

## §How did we choose defaults?

You should not regret adding `actix-session` to your dependencies and going to production using the default configuration. That is why, when in doubt, we opt to use the most secure option for each configuration parameter.

We expose knobs to change the default to suit your needs—i.e., if you know what you are doing, we will not stop you. But being a subject-matter expert should not be a requirement to deploy reasonably secure implementation of sessions.

## §Examples

    use actix_web::{web, App, HttpServer, HttpResponse, Error};
    use actix_session::{Session, SessionMiddleware, storage::RedisActorSessionStore};
    use actix_web::cookie::Key;

    // The secret key would usually be read from a configuration file/environment variables.
    fn get_secret_key() -> Key {
        // [...]
    }

    #[actix_web::main]
    async fn main() -> std::io::Result<()> {
        let secret_key = get_secret_key();
        let redis_connection_string = "127.0.0.1:6379";
        HttpServer::new(move ||
                App::new()
                // Add session management to your application using Redis for session state storage
                .wrap(
                    SessionMiddleware::new(
                        RedisActorSessionStore::new(redis_connection_string),
                        secret_key.clone()
                    )
                )
                .default_service(web::to(|| HttpResponse::Ok())))
            .bind(("127.0.0.1", 8080))?
            .run()
            .await
    }

If you want to customise use `builder` instead of `new`:

    use actix_web::{App, cookie::{Key, time}, Error, HttpResponse, HttpServer, web};
    use actix_session::{Session, SessionMiddleware, storage::RedisActorSessionStore};
    use actix_session::config::PersistentSession;

    // The secret key would usually be read from a configuration file/environment variables.
    fn get_secret_key() -> Key {
        // [...]
    }

    #[actix_web::main]
    async fn main() -> std::io::Result<()> {
        let secret_key = get_secret_key();
        let redis_connection_string = "127.0.0.1:6379";
        HttpServer::new(move ||
                App::new()
                // Customise session length!
                .wrap(
                    SessionMiddleware::builder(
                        RedisActorSessionStore::new(redis_connection_string),
                        secret_key.clone()
                    )
                    .session_lifecycle(
                        PersistentSession::default()
                            .session_ttl(time::Duration::days(5))
                    )
                    .build(),
                )
                .default_service(web::to(|| HttpResponse::Ok())))
            .bind(("127.0.0.1", 8080))?
            .run()
            .await
    }

## Implementations§

source §

### impl<Store: SessionStore> SessionMiddleware<Store>

source

#### pub fn new(store: Store, key: Key) -> Self

Use `SessionMiddleware::new` to initialize the session framework using the default parameters.

To create a new instance of `SessionMiddleware` you need to provide:

- an instance of the session storage backend you wish to use (i.e. an implementation of `SessionStore`);
- a secret key, to sign or encrypt the content of client-side session cookie.

source

#### pub fn builder(store: Store, key: Key) -> SessionMiddlewareBuilder<Store>

A fluent API to configure `SessionMiddleware`.

It takes as input the two required inputs to create a new instance of `SessionMiddleware`:

- an instance of the session storage backend you wish to use (i.e. an implementation of `SessionStore`);
- a secret key, to sign or encrypt the content of client-side session cookie.

## Trait Implementations§

source §

### impl<Store: Clone + SessionStore> Clone for SessionMiddleware<Store>

source §

#### fn clone(&self) -> SessionMiddleware<Store>

Returns a copy of the value. Read more
1.0.0 · source §

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
source §

### impl<S, B, Store> Transform<S, ServiceRequest> for SessionMiddleware<Store>
where S: Service<ServiceRequest, Response = ServiceResponse<B>, Error = Error> + 'static, S::Future: 'static, B: MessageBody + 'static, Store: SessionStore + 'static,

§

#### type Response = ServiceResponse<B>

Responses produced by the service.
§

#### type Error = Error

Errors produced by the service.
§

#### type Transform = InnerSessionMiddleware<S, Store>

The `TransformService` value created by this factory
§

#### type InitError = ()

Errors produced while building a transform service.
§

#### type Future = Ready<Result<<SessionMiddleware<Store> as Transform<S, ServiceRequest>>::Transform, <SessionMiddleware<Store> as Transform<S, ServiceRequest>>::InitError>>

The future response value.
source §

#### fn new_transform(&self, service: S) -> Self::Future

Creates and returns a new Transform component, asynchronously

## Auto Trait Implementations§

§

### impl<Store> RefUnwindSafe for SessionMiddleware<Store>
where Store: RefUnwindSafe,

§

### impl<Store> !Send for SessionMiddleware<Store>

§

### impl<Store> !Sync for SessionMiddleware<Store>

§

### impl<Store> Unpin for SessionMiddleware<Store>

§

### impl<Store> UnwindSafe for SessionMiddleware<Store>
where Store: RefUnwindSafe,

## Blanket Implementations§

source §

### impl<T> Any for T
where T: 'static + ?Sized,

source §

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source §

### impl<T> Borrow<T> for T
where T: ?Sized,

source §

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source §

### impl<T> BorrowMut<T> for T
where T: ?Sized,

source §

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source §

### impl<T> From<T> for T

source §

#### fn from(t: T) -> T

Returns the argument unchanged.

§

### impl<T> Instrument for T

§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [`Span`], returning an `Instrumented` wrapper. Read more
§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
source §

### impl<T, U> Into<U> for T
where U: From<T>,

source §

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source §

### impl<T> Same for T

§

#### type Output = T

Should always be `Self`
source §

### impl<T> ToOwned for T
where T: Clone,

§

#### type Owned = T

The resulting type after obtaining ownership.
source §

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source §

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source §

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source §

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source §

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source §

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

#### fn vzip(self) -> V

§

### impl<T> WithSubscriber for T

§

#### 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
§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more