Struct ValkeyStore 

pub struct ValkeyStore { /* private fields */ }

Available on crate feature valkey only.

A SessionStore on Valkey or Redis, standalone or Cluster.

Every write that touches more than one key runs as a Lua script, so it is atomic across any number of processes sharing the server. Requires Valkey 7.2+ or Redis 7.0+.

Cluster

Connect with connect_cluster or from_cluster. Keys are split into 256 fixed buckets, and every key carries its bucket as a hash tag ({bb}), so a session, its tokens and its indexes always live in one hash slot and each script runs on one node. The bucket is the last byte of the session id, the first byte of a token’s hash, or the first byte of the SHA-256 of a subject. Guard mines tokens so that a session’s tokens share its bucket; the store rejects writes where they do not.

The subject index is the one structure that spans buckets: a session id sits in its subject’s set while the session lives in its own bucket, so subject-wide operations are eventually consistent. delete_subject_sessions moves the set aside, deletes each session in its bucket and then drops the moved ids. If the caller crashes in between, the leftover ids stay pending and the next revoke for the subject finishes them. A session created while a revoke runs is either revoked or its creator gets an error and the session is removed. list_subject_sessions includes sessions that are mid-revoke.

delete_expired and delete_events_before visit all 256 buckets.

Data layout

All keys start with the key prefix followed by the bucket tag, written B here (for example sg:{0a}:). Timestamps are microseconds since the Unix epoch as decimal integers.

Key	Type	Contents
B s:{session id}	hash	subject, created, auth, seen, expires, step_up, baseline (JSON), origin (JSON, absent before 0.2), cur (current token), seq (token counter), exp_ms
B t:{token hash hex}	hash	sid, seq (issue order), issued, used, sup (superseded)
B k:{session id}	sorted set	the session’s token hashes, scored by seq
B u:{subject}	set	session ids of a subject (in the subject’s bucket)
B ur:{subject}	set	ids of a subject being revoked (in the subject’s bucket)
B x	sorted set	session ids scored by expires_at
B i	sorted set	session ids scored by last_seen_at
B e	sorted set	events as JSON, scored by at
B c:{session id}:{kind}	string	time of the last session event claim
B c:s:{subject}:{kind}	string	time of the last subject alert claim (subject’s bucket)
B cz	sorted set	{session id}:{kind} and s:{subject}:{kind} claims scored by claim time

Session, token and per-session token-set keys expire at the session’s absolute expiry and subject sets at their last session’s expiry, so Valkey cleans up even if delete_expired never runs. Because those TTLs follow the server’s wall clock, sessions whose expires_at is already in the past vanish immediately. Claim keys expire after their window.

Subjects are passed to scripts as data, never as code.

Cheap to clone; clones share the connection.

Implementations

impl ValkeyStore

pub fn new(conn: ConnectionManager) -> Self

A store on an existing connection, with the default key prefix sg:.

pub fn from_cluster(conn: ClusterConnection) -> Self

A store on an existing Cluster connection, with the default key prefix sg:.

pub async fn connect_cluster<T: IntoConnectionInfo>( nodes: impl IntoIterator<Item = T>, ) -> Result<Self, RedisError>

Connects to a Valkey or Redis Cluster through any of its nodes (redis://, rediss:// or valkey:// URLs), with the default key prefix sg:.

Errors

If a URL is invalid or no node is reachable.

pub async fn connect(url: &str) -> Result<Self, RedisError>

Connects to url (redis://, rediss:// or valkey://), with the default key prefix sg:.

Errors

If the URL is invalid or the server is unreachable.

pub fn key_prefix(self, prefix: impl Into<String>) -> Self

Prefixes every key with prefix, so several apps can share one server. Defaults to sg:.

Panics

If prefix contains { or }: the store puts its own hash tag after the prefix, and a brace in the prefix would change which slot keys land in.

Trait Implementations

impl Clone for ValkeyStore

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ValkeyStore

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

Formats the value using the given formatter.

impl SessionStore for ValkeyStore

fn sharded(&self) -> bool

Whether the store partitions data into buckets that must be co-located.

async fn insert_session( &self, session: &SessionRecord, token: &TokenHash, ) -> Result<(), StoreError>

Stores a new session with token as its current token (issued_at = created_at, unused, not superseded).

async fn find_by_token( &self, token: &TokenHash, ) -> Result<Option<TokenLookup>, StoreError>

Finds the session holding token, current or superseded.

async fn apply(&self, update: &SessionUpdate) -> Result<bool, StoreError>

Applies update atomically, in this order:

async fn delete_session(&self, session_id: Uuid) -> Result<bool, StoreError>

Deletes a session and its tokens. Returns whether it existed.

async fn delete_subject_sessions( &self, subject: &str, ) -> Result<Vec<Uuid>, StoreError>

Deletes every session of subject (canonical JSON). Returns the ids it deleted.

async fn list_subject_sessions( &self, subject: &str, ) -> Result<Vec<SessionRecord>, StoreError>

Every session of subject (canonical JSON), including expired ones not yet purged.

async fn delete_expired( &self, now: DateTime<Utc>, idle_cutoff: DateTime<Utc>, ) -> Result<u64, StoreError>

Deletes sessions with expires_at <= now or last_seen_at <= idle_cutoff. Returns how many.

async fn record_event(&self, event: &SessionEvent) -> Result<(), StoreError>

Appends a security event. Stores without an event log may discard it.

async fn delete_events_before( &self, cutoff: DateTime<Utc>, ) -> Result<u64, StoreError>

Deletes events with at < cutoff. Returns how many. Also deletes event claims older than cutoff.

async fn claim_event( &self, scope: ClaimScope<'_>, kind: EventKind, now: DateTime<Utc>, window: TimeDelta, ) -> Result<bool, StoreError>

Claims the right to report a kind event for scope, for deduplication across processes. Succeeds (true) unless a claim for the same scope and kind was made after now - window, and records now as the new claim when it does. Session and subject claims are independent. Must be atomic across processes.