Trait SessionPlugin 

pub trait SessionPlugin: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn create(&self, opts: CreateOptions) -> Result<SessionId, SessionError>;
    fn read(&self, id: &SessionId) -> Result<SessionRecord, SessionError>;
    fn update(
        &self,
        id: &SessionId,
        data_json: &str,
    ) -> Result<SessionId, SessionError>;
    fn touch(
        &self,
        id: &SessionId,
        ttl_ms: u64,
    ) -> Result<SessionId, SessionError>;
    fn delete(&self, id: &SessionId) -> Result<(), SessionError>;

    // Provided method
    fn is_healthy(&self) -> bool { ... }
}

Storage backend for sessions.

Implementations fall into two families:

1. Server-backed (@bext/session-redis, @bext/session-pg). The SessionId is a short random token used as a lookup key into an external store. update returns the same id it received; delete removes the record; touch bumps the TTL cheaply.

2. Client-backed (@bext/session-cookie). The SessionId is the encrypted, signed session payload itself — there is no server state. update returns a new id (the freshly-encrypted payload), delete is a no-op from the store’s perspective (the host clears the cookie), and touch can re-sign the payload with a refreshed expiry.

Callers MUST treat the id returned by create / update / touch as authoritative and write it back into the session cookie. Assuming the id is stable breaks cookie-only stores.

All methods take &self — implementations are expected to hold any mutable state behind their own synchronisation (e.g. a connection pool).

Required Methods

fn name(&self) -> &str

Unique identifier for this backend (e.g. "cookie", "redis").

fn create(&self, opts: CreateOptions) -> Result<SessionId, SessionError>

Create a new session. Returns the id the host should write into the session cookie.

fn read(&self, id: &SessionId) -> Result<SessionRecord, SessionError>

Look up an existing session. Returns NotFound if the id is unknown or has expired; Invalid if integrity checks fail.

fn update( &self, id: &SessionId, data_json: &str, ) -> Result<SessionId, SessionError>

Replace session data. Returns the id that should subsequently be used — for server-backed stores this is the same id; for cookie stores the id changes on every mutation.

fn touch(&self, id: &SessionId, ttl_ms: u64) -> Result<SessionId, SessionError>

Extend the session’s expiry without rewriting data. Returns the id that should subsequently be used (same caveat as update).

For server-backed stores this is a cheap TTL bump; for cookie stores it may re-sign the payload with a new expiry.

fn delete(&self, id: &SessionId) -> Result<(), SessionError>

Remove the session. For server-backed stores this deletes the record; for cookie stores this is a no-op (the host is expected to clear the cookie). Idempotent: deleting an unknown id is Ok(()).

Provided Methods

fn is_healthy(&self) -> bool

Health check. Default: always healthy. Server-backed stores should override this to ping their transport.

Implementors