Struct Session

Source
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>

Source

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.

Source

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.

Source

pub async fn insert<T, Key>( &mut self, key: Key, value: T, ) -> Result<Option<Value>, ServerInsertError>
where T: Serialize, Key: Into<Cow<'static, str>>,

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.

Source

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.

Source

pub async fn is_empty(&self) -> Result<bool, LoadError>

Returns true if there are no values in the server-side state.

Source

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.

Source

pub async fn insert_raw<Key>( &mut self, key: Key, value: Value, ) -> Result<Option<Value>, LoadError>
where Key: Into<Cow<'static, str>>,

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn client(&self) -> ClientSessionState<'_>

Read values from the client-side state attached to this session.

Source

pub fn client_mut(&mut self) -> ClientSessionStateMut<'_>

Read or mutate the client-side state attached to this session.

Trait Implementations§

Source§

impl Debug for Session<'_>

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

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> 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.

§

impl<T> Paint for T
where T: ?Sized,

§

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 primary(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Primary].

§Example
println!("{}", value.primary());
§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Fixed].

§Example
println!("{}", value.fixed(color));
§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to [Color :: Rgb].

§Example
println!("{}", value.rgb(r, g, b));
§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Black].

§Example
println!("{}", value.black());
§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Red].

§Example
println!("{}", value.red());
§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Green].

§Example
println!("{}", value.green());
§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Yellow].

§Example
println!("{}", value.yellow());
§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Blue].

§Example
println!("{}", value.blue());
§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Magenta].

§Example
println!("{}", value.magenta());
§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: Cyan].

§Example
println!("{}", value.cyan());
§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: White].

§Example
println!("{}", value.white());
§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlack].

§Example
println!("{}", value.bright_black());
§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightRed].

§Example
println!("{}", value.bright_red());
§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightGreen].

§Example
println!("{}", value.bright_green());
§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightYellow].

§Example
println!("{}", value.bright_yellow());
§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightBlue].

§Example
println!("{}", value.bright_blue());
§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.bright_magenta());
§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightCyan].

§Example
println!("{}", value.bright_cyan());
§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to [Color :: BrightWhite].

§Example
println!("{}", value.bright_white());
§

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>

Returns self with the bg() set to [Color :: Primary].

§Example
println!("{}", value.on_primary());
§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Fixed].

§Example
println!("{}", value.on_fixed(color));
§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to [Color :: Rgb].

§Example
println!("{}", value.on_rgb(r, g, b));
§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Black].

§Example
println!("{}", value.on_black());
§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Red].

§Example
println!("{}", value.on_red());
§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Green].

§Example
println!("{}", value.on_green());
§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Yellow].

§Example
println!("{}", value.on_yellow());
§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Blue].

§Example
println!("{}", value.on_blue());
§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Magenta].

§Example
println!("{}", value.on_magenta());
§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: Cyan].

§Example
println!("{}", value.on_cyan());
§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: White].

§Example
println!("{}", value.on_white());
§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlack].

§Example
println!("{}", value.on_bright_black());
§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightRed].

§Example
println!("{}", value.on_bright_red());
§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightGreen].

§Example
println!("{}", value.on_bright_green());
§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightYellow].

§Example
println!("{}", value.on_bright_yellow());
§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightBlue].

§Example
println!("{}", value.on_bright_blue());
§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightMagenta].

§Example
println!("{}", value.on_bright_magenta());
§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightCyan].

§Example
println!("{}", value.on_bright_cyan());
§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to [Color :: BrightWhite].

§Example
println!("{}", value.on_bright_white());
§

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 bold(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Bold].

§Example
println!("{}", value.bold());
§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Dim].

§Example
println!("{}", value.dim());
§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Italic].

§Example
println!("{}", value.italic());
§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Underline].

§Example
println!("{}", value.underline());

Returns self with the attr() set to [Attribute :: Blink].

§Example
println!("{}", value.blink());

Returns self with the attr() set to [Attribute :: RapidBlink].

§Example
println!("{}", value.rapid_blink());
§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Invert].

§Example
println!("{}", value.invert());
§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Conceal].

§Example
println!("{}", value.conceal());
§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to [Attribute :: Strike].

§Example
println!("{}", value.strike());
§

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 mask(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Mask].

§Example
println!("{}", value.mask());
§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Wrap].

§Example
println!("{}", value.wrap());
§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Linger].

§Example
println!("{}", value.linger());
§

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.

Returns self with the quirk() set to [Quirk :: Clear].

§Example
println!("{}", value.clear());
§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Resetting].

§Example
println!("{}", value.resetting());
§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: Bright].

§Example
println!("{}", value.bright());
§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to [Quirk :: OnBright].

§Example
println!("{}", value.on_bright());
§

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);
§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new [Painted] with a default [Style]. Read more
§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

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

Source§

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>,

Source§

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