Struct trillium_sessions::SessionHandler
source · pub struct SessionHandler<Store> { /* private fields */ }
Expand description
§Handler to enable sessions.
See crate-level docs for an overview of this crate’s approach to sessions and security.
Implementations§
source§impl<Store: SessionStore> SessionHandler<Store>
impl<Store: SessionStore> SessionHandler<Store>
sourcepub fn new(store: Store, secret: impl AsRef<[u8]>) -> Self
pub fn new(store: Store, secret: impl AsRef<[u8]>) -> Self
Constructs a SessionHandler from the given
[async_session::SessionStore
] and secret. The secret
MUST be
at least 32 bytes long, and MUST be cryptographically random to be
secure. It is recommended to retrieve this at runtime from the
environment instead of compiling it into your application.
§Panics
SessionHandler::new will panic if the secret is fewer than 32 bytes.
§Defaults
The defaults for SessionHandler are:
- cookie path: “/”
- cookie name: “trillium.sid”
- session ttl: one day
- same site: strict
- save unchanged: enabled
- older secrets: none
§Customization
Although the above defaults are appropriate for most applications, they can be overridden. Please be careful changing these settings, as they can weaken your application’s security:
// this logic will be unique to your deployment
let secrets_var = std::env::var("TRILLIUM_SESSION_SECRETS").unwrap();
let session_secrets = secrets_var.split(' ').collect::<Vec<_>>();
let handler = (
CookiesHandler::new(),
SessionHandler::new(MemoryStore::new(), session_secrets[0])
.with_cookie_name("custom.cookie.name")
.with_cookie_path("/some/path")
.with_cookie_domain("trillium.rs")
.with_same_site_policy(SameSite::Strict)
.with_session_ttl(Some(Duration::from_secs(1)))
.with_older_secrets(&session_secrets[1..])
.without_save_unchanged()
);
Sets a cookie path for this session handler. The default for this value is “/”
sourcepub fn with_session_ttl(self, session_ttl: Option<Duration>) -> Self
pub fn with_session_ttl(self, session_ttl: Option<Duration>) -> Self
Sets a session ttl. This will be used both for the cookie expiry and also for the session-internal expiry.
The default for this value is one day. Set this to None to not set a cookie or session expiry. This is not recommended.
Sets the name of the cookie that the session is stored with or in.
If you are running multiple trillium applications on the same domain, you will need different values for each application. The default value is “trillium.sid”
sourcepub fn without_save_unchanged(self) -> Self
pub fn without_save_unchanged(self) -> Self
Disables the save_unchanged
setting. When save_unchanged
is enabled, a session will cookie will always be set. With
save_unchanged
disabled, the session data must be modified
from the Default
value in order for it to save. If a session
already exists and its data unmodified in the course of a
request, the session will only be persisted if
save_unchanged
is enabled.
sourcepub fn with_same_site_policy(self, policy: SameSite) -> Self
pub fn with_same_site_policy(self, policy: SameSite) -> Self
Sets the same site policy for the session cookie. Defaults to SameSite::Strict. See incrementally better cookies for more information about this setting
Sets the domain of the cookie.
sourcepub fn with_older_secrets(self, secrets: &[impl AsRef<[u8]>]) -> Self
pub fn with_older_secrets(self, secrets: &[impl AsRef<[u8]>]) -> Self
Sets optional older signing keys that will not be used to sign cookies, but can be used to validate previously signed cookies.
Trait Implementations§
source§impl<Store: SessionStore> Debug for SessionHandler<Store>
impl<Store: SessionStore> Debug for SessionHandler<Store>
source§impl<Store: SessionStore> Handler for SessionHandler<Store>
impl<Store: SessionStore> Handler for SessionHandler<Store>
source§fn run<'life0, 'async_trait>(
&'life0 self,
conn: Conn,
) -> Pin<Box<dyn Future<Output = Conn> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn run<'life0, 'async_trait>(
&'life0 self,
conn: Conn,
) -> Pin<Box<dyn Future<Output = Conn> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
source§fn before_send<'life0, 'async_trait>(
&'life0 self,
conn: Conn,
) -> Pin<Box<dyn Future<Output = Conn> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn before_send<'life0, 'async_trait>(
&'life0 self,
conn: Conn,
) -> Pin<Box<dyn Future<Output = Conn> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
source§fn init<'life0, 'life1, 'async_trait>(
&'life0 mut self,
_info: &'life1 mut Info,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
fn init<'life0, 'life1, 'async_trait>(
&'life0 mut self,
_info: &'life1 mut Info,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
'life0: 'async_trait,
'life1: 'async_trait,
Self: 'async_trait,
source§fn has_upgrade(&self, _upgrade: &Upgrade<BoxedTransport>) -> bool
fn has_upgrade(&self, _upgrade: &Upgrade<BoxedTransport>) -> bool
Handler::upgrade
. The first
handler that responds true to this will receive ownership of the
trillium::Upgrade
in a subsequent call to Handler::upgrade
source§fn upgrade<'life0, 'async_trait>(
&'life0 self,
_upgrade: Upgrade<BoxedTransport>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
fn upgrade<'life0, 'async_trait>(
&'life0 self,
_upgrade: Upgrade<BoxedTransport>,
) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>where
'life0: 'async_trait,
Self: 'async_trait,
Handler::has_upgrade
and will only be called once for this
upgrade. There is no return value, and this function takes
exclusive ownership of the underlying transport once this is
called. You can downcast the transport to whatever the source
transport type is and perform any non-http protocol communication
that has been negotiated. You probably don’t want this unless
you’re implementing something like websockets. Please note that
for many transports such as TcpStreams, dropping the transport
(and therefore the Upgrade) will hang up / disconnect.