pub struct Session<'store> { /* private fields */ }
Expand description
The current HTTP session.
§Implementation notes
§Not Clone
The session is a stateful object that holds the client-side and server-side state
of the session, tracking all changes to both states. As a result, Session
does
not implement the Clone
trait.
§Not Send
nor Sync
The session object is designed to be used within the lifetime of the request it refers to. When Pavex receives a new request, it assigns it to a specific worker thread, where all the processing for that request takes place.
Given the above, we optimized Session
’s internals for single-thread usage
and decided not to implement Send
and Sync
for it.
Implementations§
Source§impl<'store> Session<'store>
impl<'store> Session<'store>
Sourcepub fn new(
store: &'store SessionStore,
config: &'store SessionConfig,
incoming_session: Option<IncomingSession>,
) -> Self
pub fn new( store: &'store SessionStore, config: &'store SessionConfig, incoming_session: Option<IncomingSession>, ) -> Self
Create a new HTTP session.
It is a continuation of the existing session if there was a valid session cookie attached to the request. It is a brand-new session otherwise.
Source§impl Session<'_>
All the operations you can perform on the server-side state of your session.
impl Session<'_>
All the operations you can perform on the server-side state of your session.
Sourcepub async fn get<T: DeserializeOwned>(
&self,
key: &str,
) -> Result<Option<T>, ServerGetError>
pub async fn get<T: DeserializeOwned>( &self, key: &str, ) -> Result<Option<T>, ServerGetError>
Get the value associated with key
from the server-side state.
If the value is not found, None
is returned.
If the value is found, but it cannot be deserialized into the expected type,
an error is returned.
If you don’t need to deserialize the value, or you’d like to handle the deserialization
yourself, use get_raw
instead.
Sourcepub async fn insert<T, Key>(
&mut self,
key: Key,
value: T,
) -> Result<Option<Value>, ServerInsertError>
pub async fn insert<T, Key>( &mut self, key: Key, value: T, ) -> Result<Option<Value>, ServerInsertError>
Insert a value for the given key in the server-side state.
If the state didn’t have an entry for this key, the value is inserted and None
is returned.
If the state did have an entry for this key, its value is updated and the old
value is returned in its raw JSON form.
The provided value is serialized to JSON prior to being stored. If
the serialization fails, an error is returned. If you’d prefer to
take care of the serialization yourself, use insert_raw
instead.
Sourcepub async fn remove<T: DeserializeOwned>(
&mut self,
key: &str,
) -> Result<Option<T>, ServerRemoveError>
pub async fn remove<T: DeserializeOwned>( &mut self, key: &str, ) -> Result<Option<T>, ServerRemoveError>
Remove the value associated with key
from the server-side state.
If the key doesn’t exist, None
is returned.
If the key exists, the removed value is returned, deserialized into the type you specify as T
.
If the removed value cannot be deserialized, an error is returned.
If you’re not interested in the removed value, or you don’t want to deserialize it,
use remove_raw
instead.
Sourcepub async fn is_empty(&self) -> Result<bool, LoadError>
pub async fn is_empty(&self) -> Result<bool, LoadError>
Returns true
if there are no values in the server-side state.
Sourcepub async fn get_raw<'a>(
&'a self,
key: &str,
) -> Result<Option<&'a Value>, LoadError>
pub async fn get_raw<'a>( &'a self, key: &str, ) -> Result<Option<&'a Value>, LoadError>
Get the value associated with key
from the server-side state.
Sourcepub async fn insert_raw<Key>(
&mut self,
key: Key,
value: Value,
) -> Result<Option<Value>, LoadError>
pub async fn insert_raw<Key>( &mut self, key: Key, value: Value, ) -> Result<Option<Value>, LoadError>
Insert a value for the given key in the server-side state.
If the state didn’t have an entry for this key, the value is inserted and None
is returned.
If the state did have an entry for this key, its value is updated and the old
value is returned in its raw JSON form.
The provided value must be a JSON value, which will be stored as-is, without any
further manipulation. If you’d prefer to let pavex_session
handle the serialization,
use insert
instead.
Sourcepub async fn remove_raw(
&mut self,
key: &str,
) -> Result<Option<Value>, LoadError>
pub async fn remove_raw( &mut self, key: &str, ) -> Result<Option<Value>, LoadError>
Remove the value associated with key
from the server-side state.
If the key exists, the removed value is returned.
The value is returned as it was stored in the server-side state, without any deserialization.
If you want to deserialize the value as a specific type, use remove
instead.
Sourcepub fn delete(&mut self)
pub fn delete(&mut self)
Delete the session record from the store.
This doesn’t destroy the whole session—you must invoke Session::invalidate
if that’s your goal.
Sourcepub async fn clear(&mut self) -> Result<(), LoadError>
pub async fn clear(&mut self) -> Result<(), LoadError>
Remove all key-value pairs from the server-side state.
This doesn’t delete the session record from the store—you must invoke
Session::delete
if you want to delete the record altogether.
This doesn’t invalidate the session—you must invoke Session::invalidate
if you want to delete the session altogether.
Sourcepub fn cycle_id(&mut self)
pub fn cycle_id(&mut self)
Generate a new session identifier and attach it to this session. The session state is preserved on both the client-side and the server-side.
This method is useful for security reasons, as it can help prevent session fixation attacks.
Sourcepub fn invalidate(&mut self)
pub fn invalidate(&mut self)
Invalidate the session.
The server-side session state will be marked for deletion. The client-side cookie will be removed from the client using a removal cookie.
After calling this method, the session is considered invalid and should not be used anymore. All further operations on the session will be no-ops.
Sourcepub fn is_invalidated(&self) -> bool
pub fn is_invalidated(&self) -> bool
Check if the session has been invalidated.
See Session::invalidate
for more information.
Source§impl Session<'_>
Control when the server-side state is synchronized with the store.
impl Session<'_>
Control when the server-side state is synchronized with the store.
Sourcepub async fn sync(&mut self) -> Result<(), SyncError>
pub async fn sync(&mut self) -> Result<(), SyncError>
Sync the in-memory representation of the server-side state with the store.
In most cases, you don’t need to invoke this method manually: it is
done for you by finalize_session
,
the post-processing middleware that attaches the session cookie to
the response returned to the client.
Sourcepub async fn force_load(&self) -> Result<(), LoadError>
pub async fn force_load(&self) -> Result<(), LoadError>
Load the server-side state from the store. This method does nothing if the server-side state has already been loaded.
After calling this method, the server-side state will be loaded
and cached in memory, so that subsequent calls to get_raw
,
insert_raw
, and remove_raw
will operate on the in-memory state.
Sourcepub async fn finalize(
&mut self,
) -> Result<Option<ResponseCookie<'static>>, FinalizeError>
pub async fn finalize( &mut self, ) -> Result<Option<ResponseCookie<'static>>, FinalizeError>
Sync the current server-side state with the chosen storage backend. If necessary, it returns a cookie to be attached to the outgoing response in order to sync the client-side state.
Source§impl Session<'_>
APIs for manipulating the client-side session state.
impl Session<'_>
APIs for manipulating the client-side session state.
Sourcepub fn client(&self) -> ClientSessionState<'_>
pub fn client(&self) -> ClientSessionState<'_>
Read values from the client-side state attached to this session.
Sourcepub fn client_mut(&mut self) -> ClientSessionStateMut<'_>
pub fn client_mut(&mut self) -> ClientSessionStateMut<'_>
Read or mutate the client-side state attached to this session.
Trait Implementations§
Auto Trait Implementations§
impl<'store> !Freeze for Session<'store>
impl<'store> !RefUnwindSafe for Session<'store>
impl<'store> !Send for Session<'store>
impl<'store> !Sync for Session<'store>
impl<'store> Unpin for Session<'store>
impl<'store> !UnwindSafe for Session<'store>
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere
T: ?Sized,
§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
§Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
§Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling [Attribute
] value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
§Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
[Quirk
] value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
§Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
§fn clear(&self) -> Painted<&T>
👎Deprecated since 1.0.1: renamed to resetting()
due to conflicts with Vec::clear()
.
The clear()
method will be removed in a future release.
fn clear(&self) -> Painted<&T>
resetting()
due to conflicts with Vec::clear()
.
The clear()
method will be removed in a future release.§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the [Condition
] value
applies. Replaces any previous condition.
See the crate level docs for more details.
§Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);