Struct gotham::middleware::session::NewSessionMiddleware

pub struct NewSessionMiddleware<B, T> where
    B: NewBackend,
    T: Default + Serialize + for<'de> Deserialize<'de> + Send + 'static,  { /* fields omitted */ }

Added to a Pipeline, this spawns the per-request SessionMiddleware

There are two ways to construct the NewSessionMiddleware, but with_session_type must be called before the middleware is useful:

1. Using the Default implementation, which sets up an in-memory session store. When constructed this way, sessions are unable to be shared between multiple application servers, and are lost on restart:

   NewSessionMiddleware::default()

2. Using the NewSessionMiddleware::new function, and providing a backend. The Default implementation uses MemoryBackend, but this can be changed by providing your own:

   NewSessionMiddleware::new(MemoryBackend::default())

Before the middleware can be used, it must be associated with a session type provided by the application. This gives type-safe storage for all session data:

#[derive(Default, Serialize, Deserialize)]
struct MySessionType {
    items: Vec<String>,
}

NewSessionMiddleware::default().with_session_type::<MySessionType>()

For plaintext HTTP servers, the insecure method must also be called to instruct the middleware not to set the secure flag on the cookie.

Implementations

impl<B> NewSessionMiddleware<B, ()> where
    B: NewBackend, 

pub fn new(b: B) -> NewSessionMiddleware<B, ()>

Create a NewSessionMiddleware value for the provided backend and with a blank session type. with_session_type must be called before the result is useful.

impl<B, T> NewSessionMiddleware<B, T> where
    B: NewBackend,
    T: Default + Serialize + for<'de> Deserialize<'de> + Send + 'static, 

pub fn with_cookie_path<P>(self, path: P) -> NewSessionMiddleware<B, T> where
    P: AsRef<str>, 

Configures the session cookie to be set at a more restrictive path.

NewSessionMiddleware::default()
    .with_session_type::<MySessionType>()
    .with_cookie_path("/app".to_string())

pub fn insecure(self) -> NewSessionMiddleware<B, T>

Configures the NewSessionMiddleware not to send the secure flag along with the cookie. This is required for plaintext HTTP connections.

NewSessionMiddleware::default()
    .with_session_type::<MySessionType>()
    .insecure()

pub fn with_cookie_name<S>(self, name: S) -> NewSessionMiddleware<B, T> where
    S: AsRef<str>, 

Configures the NewSessionMiddleware to use an alternate cookie name. The default cookie name is _gotham_session.

When a cookie name with a cookie prefix is used, the other options are forced to be correct (ignoring overridden settings from the application). i.e.:

• For a cookie prefix of __Secure-, the cookie attributes will include Secure
• For a cookie prefix of __Host-, the cookie attributes will include Secure; Path=/ and not include Domain=

If the session cookie configuration set by the application does not match the prefix, a warning will be logged upon startup and the cookie prefix options will override what was provided by the application.

NewSessionMiddleware::default()
    .with_session_type::<MySessionType>()
    .with_cookie_name("_myapp_session")

pub fn with_cookie_domain<S>(self, domain: S) -> NewSessionMiddleware<B, T> where
    S: AsRef<str>, 

Configures the NewSessionMiddleware to use a Domain attribute with the provided value.

NewSessionMiddleware::default()
    .with_session_type::<MySessionType>()
    .with_cookie_domain("example.com")

pub fn allow_cross_site_usage(self) -> NewSessionMiddleware<B, T>

Removes the SameSite cookie attribute, allowing cross-site requests to include the cookie.

By default, the session cookie will be set with SameSite=lax, which ensures cross-site requests will include the cookie if and only if they are top-level navigations which use a “safe” (in the RFC7231 sense) HTTP method.

See: https://tools.ietf.org/html/draft-ietf-httpbis-cookie-same-site-00#section-4.1

NewSessionMiddleware::default()
    .with_session_type::<MySessionType>()
    .allow_cross_site_usage()

pub fn with_strict_same_site_enforcement(self) -> NewSessionMiddleware<B, T>

Sets the “SameSite” cookie attribute value to “strict”.

This will ensure that the cookie is never sent for cross-site requests (including top-level navigations).

By default, the session cookie will be set with “SameSite=lax”, which ensures cross-site requests will include the cookie if and only if they are top-level navigations which use a “safe” (in the RFC7231 sense) HTTP method.

NewSessionMiddleware::default()
    .with_session_type::<MySessionType>()
    .with_strict_same_site_enforcement()

pub fn with_session_type<U>(self) -> NewSessionMiddleware<B, U> where
    U: Default + Serialize + for<'de> Deserialize<'de> + Send + 'static, 

Changes the session type to the provided type parameter. This is required to override the default (unusable) session type of ().

#[derive(Default, Serialize, Deserialize)]
struct MySessionType {
    items: Vec<String>,
}

NewSessionMiddleware::default().with_session_type::<MySessionType>()

Trait Implementations

impl<B, T> Clone for NewSessionMiddleware<B, T> where
    B: NewBackend,
    T: Default + Serialize + for<'de> Deserialize<'de> + Send + 'static, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Default for NewSessionMiddleware<MemoryBackend, ()>

fn default() -> NewSessionMiddleware<MemoryBackend, ()>

Returns the “default value” for a type.

impl<B, T> NewMiddleware for NewSessionMiddleware<B, T> where
    B: NewBackend,
    T: Default + Serialize + for<'de> Deserialize<'de> + Send + 'static, 

type Instance = SessionMiddleware<B::Instance, T>

The type of Middleware created by the NewMiddleware.

fn new_middleware(&self) -> Result<Self::Instance>

Create and return a new Middleware value.