Struct SessionMap

Source

pub struct SessionMap { /* private fields */ }

Expand description

Thread-safe map of session keys (typically domains) to proxy bindings.

All operations acquire short-lived locks to minimise contention.

§Example

use stygian_proxy::session::SessionMap;
use std::time::Duration;
use uuid::Uuid;

let map = SessionMap::new();
let id = Uuid::new_v4();
map.bind("example.com", id, Duration::from_secs(60));
assert_eq!(map.lookup("example.com"), Some(id));

Implementations§

Source §

impl SessionMap

Source

pub fn new() -> Self

Create an empty session map.

Source

pub fn lookup(&self, key: &str) -> Option<Uuid>

Look up the proxy bound to key, returning None when no session exists or the existing session has expired.

Expired entries are lazily removed on the next bind or purge_expired call.

Source

pub fn bind(&self, key: &str, proxy_id: Uuid, ttl: Duration)

Bind key to proxy_id with the given TTL. Overwrites any existing session for the same key.

Source

pub fn purge_expired(&self) -> usize

Remove all expired sessions, returning the number removed.

Source

pub fn unbind(&self, key: &str)

Remove a specific session by key.

Source

pub fn active_count(&self) -> usize

Returns the number of active (non-expired) sessions.

Source

pub fn acquire_session( &self, domain: &str, vendor: VendorId, policy_map: &VendorStickinessMap, ) -> SessionDecision

Acquire (or refresh) a sticky session for (domain, vendor) according to policy_map.

Translates the 2026 guide’s per-vendor stickiness matrix (VendorStickinessMap::with_builtin_defaults) into a typed SessionDecision:

StickinessPolicy::StickyForever and StickinessPolicy::StickyForTtl → reuse an existing binding when present, otherwise emit SessionDecision::AcquireAndBind with the policy TTL (or Duration::MAX for StickyForever).
StickinessPolicy::FreshPerDomain → evict any existing binding for domain and emit SessionDecision::AcquireFresh.
StickinessPolicy::FreshPerRequest → emit SessionDecision::AcquireFresh (no binding to evict).
StickinessPolicy::StickyForRequestCount → emitted as SessionDecision::AcquireFresh. The request-count stickiness is documented as a no-op at this layer because the SessionMap does not count requests per session; operators that need per-request counting should switch to StickyForTtl instead.

Unknown vendors (those without an explicit entry in policy_map) fall back to StickinessPolicy::FreshPerRequest (the safest default) and so always emit SessionDecision::AcquireFresh.

This method is pure — it never blocks on async I/O and never touches the rotation strategy — so it is safe to call from the hot acquisition path.

§Example

use stygian_proxy::session::{SessionDecision, SessionMap};
use stygian_proxy::stickiness::VendorStickinessMap;
use stygian_proxy::types::VendorId;
use std::time::Duration;
use uuid::Uuid;

let map = SessionMap::new();
let policy = VendorStickinessMap::with_builtin_defaults();

// Pre-bind as if the manager already acquired a proxy.
let proxy_id = Uuid::new_v4();
map.bind("example.com", proxy_id, Duration::from_mins(30));

// Subsequent `acquire_session` for `Akamai` reuses the binding.
let decision = map.acquire_session("example.com", VendorId::Akamai, &policy);
assert_eq!(decision, SessionDecision::UseSticky(proxy_id));

// `PerimeterX` always evicts the binding and asks for fresh
// (FreshPerDomain semantics from the 2026 guide).
let decision = map.acquire_session("example.com", VendorId::PerimeterX, &policy);
assert_eq!(decision, SessionDecision::AcquireFresh);
assert_eq!(map.lookup("example.com"), None, "PerimeterX evicts the binding");