session

Session

Per-request session backed by an OTP actor for mutability in immutable Gleam. All session operations send messages to the actor. Middleware reads final state after the handler returns to persist changes.

Types

Session

opaque </>

Opaque session handle passed through Context. Wraps either a live actor subject or a no-op empty session for boot-time Context construction before any request arrives.

pub opaque type Session

Values

all

</>

pub fn all(session: Session) -> dict.Dict(String, String)

Returns all session data as a dictionary.

empty

</>

pub fn empty() -> Session

Creates a no-op session for boot-time Context construction. All reads return empty values, all writes are silently ignored. Safe to use before any request arrives.

flash

</>

pub fn flash(session: Session, key: String, value: String) -> Nil

Sets a flash message available only on the next request. Flash data is stored separately and cleared after being read once by the next request’s middleware.

forget

</>

pub fn forget(session: Session, key: String) -> Nil

Removes a key from the session.

get

</>

pub fn get(session: Session, key: String) -> Result(String, Nil)

Retrieves a value from the session by key.

get_flash

</>

pub fn get_flash(session: Session, key: String) -> String

Reads a flash value set by the previous request. Returns the value or an empty string if not found.

get_flash_or

</>

pub fn get_flash_or(
  session: Session,
  key: String,
) -> Result(String, Nil)

Reads a flash value set by the previous request. Returns a Result for when you need to distinguish between a missing key and an empty value.

has

</>

pub fn has(session: Session, key: String) -> Bool

Checks whether a key exists in the session.

has_flash

</>

pub fn has_flash(session: Session, key: String) -> Bool

Checks whether a flash key exists from the previous request.

id

</>

pub fn id(session: Session) -> String

Returns the session ID.

invalidate

</>

pub fn invalidate(session: Session) -> Nil

Clears all session data and generates a new session ID. The old session will be destroyed in the store by middleware.

put

</>

pub fn put(session: Session, key: String, value: String) -> Nil

Stores a key-value pair in the session.

regenerate

</>

pub fn regenerate(session: Session) -> Nil

Generates a new session ID but keeps existing data. Useful after authentication to prevent session fixation.

start_cookie

</>

pub fn start_cookie() -> Nil

Initializes a cookie-based session store. Session data is stored directly in a signed cookie — no server-side persistence. Suitable for small payloads under ~4KB. The store is cached in persistent_term for fast access.