Struct Session

Source

pub struct Session<S: SessionStore> { /* private fields */ }

Expand description

A parsed on-demand session store.

Implementations§

Source §

impl<S> Session<S>
where S: SessionStore,

Source

pub fn new(inner: Arc<Inner<S>>) -> Self

Creates a new Session instance.

Source

pub async fn get<T>(&self, field: &str) -> Result<Option<T>, Error>
where T: Send + Sync + DeserializeOwned,

Retrieves the value of a field from the session store.

§Example

use ruts::{Session};
use fred::clients::Client;
use serde::Deserialize;
use ruts::store::memory::MemoryStore;

#[derive(Clone, Deserialize)]
struct User {
    id: i64,
    name: String,
}

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    session.get::<User>("user").await.unwrap();
}

Source

pub async fn get_all(&self) -> Result<Option<SessionMap>, Error>

This method performs one bulk query to the store and returns a wrapper that allows for lazy, on-demand deserialization of each field.

Source

pub async fn insert<T>( &self, field: &str, value: &T, field_ttl_secs: Option<i64>, ) -> Result<bool, Error>
where T: Send + Sync + Serialize + 'static,

Inserts a value into the session store under the given field.

The behavior of field_ttl_secs determines how this field affects session persistence:

-1: Marks this field as persistent. The session key itself will also be persisted, making the associated cookie persistent. This does not alter the TTL of other fields in the session.
0: Removes this field from the store. The session behaves as if remove was called on this field.
> 0: Sets a TTL (in seconds) for this field. The session TTL is updated according to:
- If the session key is already persistent, its TTL remains unchanged.
- If the field TTL is less than the current session TTL, the session TTL remains unchanged.
- If the field TTL is greater than the current session TTL, the session TTL is updated to match the field TTL.

Returns true if the field-value pair was successfully inserted or updated, and false if the operation resulted in deletion (e.g., TTL = 0 for a non-existent session).

§Example

use ruts::{Session};
use fred::clients::Client;
use serde::Serialize;
use ruts::store::memory::MemoryStore;

#[derive(Serialize)]
struct User {
    id: i64,
    name: String,
}

async fn example_handler(session: Session<MemoryStore>) {
    let user = User { id: 34895634, name: "John Doe".to_string() };
    // Insert the field with a TTL of 5 seconds
    session.insert("app", &user, Some(5)).await.unwrap();
}

Source

pub async fn update<T>( &self, field: &str, value: &T, field_ttl_secs: Option<i64>, ) -> Result<bool, Error>
where T: Send + Sync + Serialize + 'static,

Updates a value in the session store.

If the key doesn’t exist, it will be inserted.

-1: Marks this field as persistent. The session key itself will also be persisted, making the associated cookie persistent. This does not alter the TTL of other fields in the session.
0: Removes this field from the store. The session behaves as if remove was called on this field.
> 0: Sets a TTL (in seconds) for this field. The session TTL is updated according to:
- If the session key is already persistent, its TTL remains unchanged.
- If the field TTL is less than the current session TTL, the session TTL remains unchanged.
- If the field TTL is greater than the current session TTL, the session TTL is updated to match the field TTL.

Returns true if the field-value pair was successfully inserted or updated, and false if the operation resulted in deletion (e.g., TTL = 0 for a non-existent session).

§Example

use ruts::{Session};
use fred::clients::Client;
use serde::Serialize;
use ruts::store::memory::MemoryStore;

#[derive(Serialize)]
struct User {
    id: i64,
    name: String,
}

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    let user = User {id: 21342365, name: String::from("Jane Doe")};

    let updated = session.update("app", &user, Some(5)).await.unwrap();
}

Source

pub async fn remove(&self, field: &str) -> Result<bool, Error>

Removes a field along with its value from the session store.

Returns true if the field was successfully removed.

§Example

use ruts::{Session};
use fred::clients::Client;
use ruts::store::memory::MemoryStore;

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    let removed = session.remove("user").await.unwrap();
}

Source

pub async fn delete(&self) -> Result<bool, Error>

Deletes the entire session from the store.

Returns true if the session was successfully deleted.

§Example

use ruts::{Session};
use fred::clients::Client;
use ruts::store::memory::MemoryStore;

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    let deleted = session.delete().await.unwrap();
}

Source

pub async fn expire(&self, ttl_secs: i64) -> Result<bool, Error>

Updates the cookie’s max-age and session expiry time in the store.

A value of -1 persists the session.
A value of 0 immediately expires the session and deletes it.

Returns true if the expiry was successfully updated.

§Example

use ruts::{Session};
use fred::clients::Client;
use ruts::store::memory::MemoryStore;

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    session.expire(30).await.unwrap();
}

Source

pub fn set_expiration(&self, seconds: i64)

Updates the cookie max-age.

Any subsequent call to insert, update or regenerate within this request cycle will use this value.

Source

pub async fn regenerate(&self) -> Result<Option<Id>, Error>

Regenerates the session with a new ID.

Returns the new session ID if successful.

§Example

use ruts::{Session};
use fred::clients::Client;
use ruts::store::memory::MemoryStore;

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    let id = session.regenerate().await.unwrap();
}

Note: This does not renew the session expiry.

Source

pub fn prepare_regenerate(&self) -> Id

Prepares a new session ID to be used in the next store operation. The new ID will be used to rename the current session (if it exists) when the next insert or update operation is performed.

§Example

use ruts::Session;
use fred::clients::Client;
use ruts::store::memory::MemoryStore;

async fn some_handler_could_be_axum(session: Session<MemoryStore>) {
    let new_id = session.prepare_regenerate();
    // The next update/insert operation will use this new ID
    session.update("field", &"value", None).await.unwrap();
}