Struct gotham::middleware::session::NewSessionMiddleware

source · [−]

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

Expand description

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:

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()
```
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

source

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

source

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.

source

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

source

pub fn with_cookie_path(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())

source

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()

source

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")

source

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")

source

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()

source

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()

source

pub fn with_session_type(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>()