use std::any::Any;
use std::collections::HashMap;
use std::error::Error;
use std::fmt::{self, Debug, Formatter};
use std::hash::{Hash, Hasher};
use std::marker::PhantomData;
use std::sync::{Arc, Mutex, RwLock, RwLockReadGuard};
#[cfg(test)]
use std::sync::{Barrier, TryLockError};
use crate::redact::Locked;
struct KeyToken {
_non_zero_sized: u8,
}
#[derive(Clone)]
struct SlotId(Arc<KeyToken>);
impl PartialEq for SlotId {
fn eq(&self, other: &Self) -> bool {
Arc::ptr_eq(&self.0, &other.0)
}
}
impl Eq for SlotId {}
impl Hash for SlotId {
fn hash<H: Hasher>(&self, state: &mut H) {
Arc::as_ptr(&self.0).hash(state);
}
}
pub struct Key<T> {
token: Arc<KeyToken>,
marker: PhantomData<fn(T) -> T>,
}
#[expect(
clippy::new_without_default,
reason = "ADR-006 forbids Default because every key creation must be explicit"
)]
impl<T> Key<T> {
#[must_use]
pub fn new() -> Self {
Self {
token: Arc::new(KeyToken { _non_zero_sized: 0 }),
marker: PhantomData,
}
}
fn slot_id(&self) -> SlotId {
SlotId(Arc::clone(&self.token))
}
}
impl<T> Clone for Key<T> {
fn clone(&self) -> Self {
Self {
token: Arc::clone(&self.token),
marker: PhantomData,
}
}
}
impl<T> Debug for Key<T> {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Key")
.field("slot", &Arc::as_ptr(&self.token))
.finish()
}
}
impl<T> PartialEq for Key<T> {
fn eq(&self, other: &Self) -> bool {
Arc::ptr_eq(&self.token, &other.token)
}
}
impl<T> Eq for Key<T> {}
impl<T> Hash for Key<T> {
fn hash<H: Hasher>(&self, state: &mut H) {
Arc::as_ptr(&self.token).hash(state);
}
}
pub trait SnapshotValue: Clone + Send + Sync + 'static {}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum WriteError {
LeaseReleased,
}
impl fmt::Display for WriteError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::LeaseReleased => formatter.write_str("session-state lease released"),
}
}
}
impl Error for WriteError {}
trait StoredSnapshotValue: Send + Sync {
fn clone_stored(&self) -> Box<dyn StoredSnapshotValue>;
fn as_any(&self) -> &dyn Any;
}
impl<T: SnapshotValue> StoredSnapshotValue for T {
fn clone_stored(&self) -> Box<dyn StoredSnapshotValue> {
Box::new(self.clone())
}
fn as_any(&self) -> &dyn Any {
self
}
}
type StoredMap = HashMap<SlotId, Box<dyn StoredSnapshotValue>>;
struct Core {
values: RwLock<StoredMap>,
}
impl Core {
fn debug_handle(&self, name: &str, formatter: &mut Formatter<'_>) -> fmt::Result {
let mut handle = formatter.debug_struct(name);
match self.values.try_read() {
Ok(values) => handle.field("slots", &values.len()),
Err(_contended_or_poisoned) => handle.field("slots", &Locked),
}
.finish()
}
fn new() -> Self {
Self {
values: RwLock::new(HashMap::new()),
}
}
fn load<T: SnapshotValue>(&self, key: &Key<T>) -> Option<T> {
let values = self.values.read().expect("session-state lock poisoned");
values
.get(&key.slot_id())
.map(|value| stored_clone::<T>(&**value))
}
}
struct Lease {
active: RwLock<bool>,
#[cfg(test)]
write_overlap: Mutex<Option<Arc<WriteOverlap>>>,
}
#[cfg(test)]
struct WriteOverlap {
admitted: Barrier,
proceed: Barrier,
}
#[cfg(test)]
impl WriteOverlap {
fn new() -> Self {
Self {
admitted: Barrier::new(2),
proceed: Barrier::new(2),
}
}
}
#[cfg(test)]
pub(super) struct WriteOverlapControl {
overlap: Arc<WriteOverlap>,
lease: Arc<Lease>,
}
#[cfg(test)]
impl WriteOverlapControl {
pub(super) fn wait_for_admission(&self) {
self.overlap.admitted.wait();
}
pub(super) fn assert_release_is_blocked(&self) {
assert!(
matches!(self.lease.active.try_write(), Err(TryLockError::WouldBlock)),
"an admitted write must hold the lease read guard"
);
}
pub(super) fn release_write(&self) {
self.overlap.proceed.wait();
}
}
#[cfg(test)]
impl Lease {
fn pause_admitted_write(&self) {
let overlap = self
.write_overlap
.lock()
.expect("test write-overlap lock must be healthy")
.clone();
if let Some(overlap) = overlap {
overlap.admitted.wait();
overlap.proceed.wait();
*self
.write_overlap
.lock()
.expect("test write-overlap lock must be healthy") = None;
}
}
}
pub struct Reader {
core: Arc<Core>,
}
impl Debug for Reader {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
self.core.debug_handle("Reader", formatter)
}
}
impl Reader {
#[must_use]
pub fn load<T: SnapshotValue>(&self, key: &Key<T>) -> Option<T> {
self.core.load(key)
}
pub(crate) fn clone_handle(&self) -> Self {
Self {
core: Arc::clone(&self.core),
}
}
}
struct CallbackWritePermitInner {
active: RwLock<bool>,
}
#[derive(Clone)]
pub(crate) struct CallbackWritePermit {
inner: Arc<CallbackWritePermitInner>,
}
impl CallbackWritePermit {
fn new() -> Self {
Self {
inner: Arc::new(CallbackWritePermitInner {
active: RwLock::new(true),
}),
}
}
pub(crate) fn revoke(&self) {
let mut active = self
.inner
.active
.write()
.expect("callback write-permit lock poisoned");
*active = false;
}
}
pub struct Writer {
core: Arc<Core>,
lease: Arc<Lease>,
callback_permit: Option<Arc<CallbackWritePermitInner>>,
}
impl Debug for Writer {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
self.core.debug_handle("Writer", formatter)
}
}
impl Writer {
#[must_use]
pub fn load<T: SnapshotValue>(&self, key: &Key<T>) -> Option<T> {
self.core.load(key)
}
pub fn set<T: SnapshotValue>(&self, key: &Key<T>, value: &T) -> Result<Option<T>, WriteError> {
self.with_write(|values| {
values
.insert(key.slot_id(), Box::new(value.clone()))
.map(|previous| stored_clone::<T>(&*previous))
})
}
pub fn load_or_store<T: SnapshotValue>(
&self,
key: &Key<T>,
value: &T,
) -> Result<(T, bool), WriteError> {
self.with_write(|values| {
if let Some(existing) = values.get(&key.slot_id()) {
(stored_clone::<T>(&**existing), true)
} else {
let stored = value.clone();
let returned = stored.clone();
values.insert(key.slot_id(), Box::new(stored));
(returned, false)
}
})
}
pub fn delete<T: SnapshotValue>(&self, key: &Key<T>) -> Result<Option<T>, WriteError> {
self.with_write(|values| {
values
.remove(&key.slot_id())
.map(|previous| stored_clone::<T>(&*previous))
})
}
#[must_use]
pub fn staged(&self) -> StagedWriter {
StagedWriter {
writer: Self {
core: Arc::clone(&self.core),
lease: Arc::clone(&self.lease),
callback_permit: self.callback_permit.clone(),
},
state: Mutex::new(StageState::Active(HashMap::new())),
}
}
#[must_use]
pub fn reader(&self) -> Reader {
Reader {
core: Arc::clone(&self.core),
}
}
pub(crate) fn clone_with_callback_permit(&self) -> (Self, CallbackWritePermit) {
let permit = CallbackWritePermit::new();
let writer = Self {
core: Arc::clone(&self.core),
lease: Arc::clone(&self.lease),
callback_permit: Some(Arc::clone(&permit.inner)),
};
(writer, permit)
}
fn admit_callback_write(&self) -> Result<Option<RwLockReadGuard<'_, bool>>, WriteError> {
let Some(permit) = &self.callback_permit else {
return Ok(None);
};
let active = permit
.active
.read()
.expect("callback write-permit lock poisoned");
if !*active {
return Err(WriteError::LeaseReleased);
}
Ok(Some(active))
}
fn with_write<R>(&self, operation: impl FnOnce(&mut StoredMap) -> R) -> Result<R, WriteError> {
let _callback_permit = self.admit_callback_write()?;
let active = self
.lease
.active
.read()
.expect("session lease lock poisoned");
if !*active {
return Err(WriteError::LeaseReleased);
}
#[cfg(test)]
self.lease.pause_admitted_write();
let mut values = self
.core
.values
.write()
.expect("session-state lock poisoned");
Ok(operation(&mut values))
}
fn commit(&self, overlay: &HashMap<SlotId, StagedSlot>) -> Result<(), WriteError> {
self.with_write(|values| {
let mut candidate = clone_map(values);
for (id, slot) in overlay {
match slot {
StagedSlot::SnapshotValue(value) => {
candidate.insert(id.clone(), value.clone_stored());
}
StagedSlot::Deleted => {
candidate.remove(id);
}
}
}
*values = candidate;
})
}
pub(crate) fn release(&self) {
let mut active = self
.lease
.active
.write()
.expect("session lease lock poisoned");
*active = false;
}
}
enum StagedSlot {
SnapshotValue(Box<dyn StoredSnapshotValue>),
Deleted,
}
enum StageState {
Active(HashMap<SlotId, StagedSlot>),
Resolved,
}
impl Debug for StageState {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::Active(overlay) => formatter
.debug_tuple("Active")
.field(&overlay.len())
.finish(),
Self::Resolved => formatter.write_str("Resolved"),
}
}
}
pub struct StagedWriter {
writer: Writer,
state: Mutex<StageState>,
}
impl Debug for StagedWriter {
fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
let mut staged = formatter.debug_struct("StagedWriter");
staged.field("writer", &self.writer);
match self.state.try_lock() {
Ok(state) => staged.field("stage", &*state),
Err(_contended_or_poisoned) => staged.field("stage", &Locked),
}
.finish()
}
}
impl StagedWriter {
#[must_use]
pub fn load<T: SnapshotValue>(&self, key: &Key<T>) -> Option<T> {
let state = self.state.lock().expect("staged-state lock poisoned");
match &*state {
StageState::Active(overlay) => staged_load(overlay, &self.writer, key),
StageState::Resolved => self.writer.load(key),
}
}
pub fn set<T: SnapshotValue>(&self, key: &Key<T>, value: &T) -> Result<Option<T>, WriteError> {
let mut state = self.state.lock().expect("staged-state lock poisoned");
match &mut *state {
StageState::Active(overlay) => {
let _callback_permit = self.writer.admit_callback_write()?;
let previous = staged_load(overlay, &self.writer, key);
overlay.insert(
key.slot_id(),
StagedSlot::SnapshotValue(Box::new(value.clone())),
);
Ok(previous)
}
StageState::Resolved => self.writer.set(key, value),
}
}
pub fn load_or_store<T: SnapshotValue>(
&self,
key: &Key<T>,
value: &T,
) -> Result<(T, bool), WriteError> {
let mut state = self.state.lock().expect("staged-state lock poisoned");
match &mut *state {
StageState::Active(overlay) => {
let _callback_permit = self.writer.admit_callback_write()?;
if let Some(existing) = staged_load(overlay, &self.writer, key) {
Ok((existing, true))
} else {
let stored = value.clone();
let returned = stored.clone();
overlay.insert(key.slot_id(), StagedSlot::SnapshotValue(Box::new(stored)));
Ok((returned, false))
}
}
StageState::Resolved => self.writer.load_or_store(key, value),
}
}
pub fn delete<T: SnapshotValue>(&self, key: &Key<T>) -> Result<Option<T>, WriteError> {
let mut state = self.state.lock().expect("staged-state lock poisoned");
match &mut *state {
StageState::Active(overlay) => {
let _callback_permit = self.writer.admit_callback_write()?;
let previous = staged_load(overlay, &self.writer, key);
overlay.insert(key.slot_id(), StagedSlot::Deleted);
Ok(previous)
}
StageState::Resolved => self.writer.delete(key),
}
}
pub fn commit(&self) -> Result<(), WriteError> {
let mut state = self.state.lock().expect("staged-state lock poisoned");
let StageState::Active(overlay) = std::mem::replace(&mut *state, StageState::Resolved)
else {
return Ok(());
};
self.writer.commit(&overlay)
}
pub fn discard(&self) {
let mut state = self.state.lock().expect("staged-state lock poisoned");
*state = StageState::Resolved;
}
}
#[cfg(test)]
pub(super) fn hold_value_lock(reader: &Reader, held: &Barrier, release: &Barrier) {
let _guard = reader
.core
.values
.write()
.expect("test lock starts healthy");
held.wait();
release.wait();
}
#[cfg(test)]
pub(super) fn hold_stage_lock(staged: &StagedWriter, held: &Barrier, release: &Barrier) {
let _guard = staged.state.lock().expect("staged-state lock poisoned");
held.wait();
release.wait();
}
fn staged_load<T: SnapshotValue>(
overlay: &HashMap<SlotId, StagedSlot>,
writer: &Writer,
key: &Key<T>,
) -> Option<T> {
match overlay.get(&key.slot_id()) {
Some(StagedSlot::SnapshotValue(value)) => Some(stored_clone::<T>(&**value)),
Some(StagedSlot::Deleted) => None,
None => writer.load(key),
}
}
fn stored_clone<T: SnapshotValue>(value: &dyn StoredSnapshotValue) -> T {
value
.as_any()
.downcast_ref::<T>()
.unwrap_or_else(|| panic!("session-state slot type invariant violated"))
.clone()
}
fn clone_map(values: &StoredMap) -> StoredMap {
values
.iter()
.map(|(id, value)| (id.clone(), value.clone_stored()))
.collect()
}
pub(crate) struct Store {
core: Arc<Core>,
}
impl Store {
pub(crate) fn new() -> Self {
Self {
core: Arc::new(Core::new()),
}
}
pub(crate) fn reader(&self) -> Reader {
Reader {
core: Arc::clone(&self.core),
}
}
pub(crate) fn acquire(&self) -> Writer {
Writer {
core: Arc::clone(&self.core),
lease: Arc::new(Lease {
active: RwLock::new(true),
#[cfg(test)]
write_overlap: Mutex::new(None),
}),
callback_permit: None,
}
}
#[cfg(test)]
pub(super) fn corrupt<T, U>(&self, key: &Key<T>, value: U)
where
U: SnapshotValue,
{
self.core
.values
.write()
.expect("session-state lock poisoned")
.insert(key.slot_id(), Box::new(value));
}
}
#[cfg(test)]
pub(super) fn install_write_overlap(writer: &Writer) -> WriteOverlapControl {
let overlap = Arc::new(WriteOverlap::new());
*writer
.lease
.write_overlap
.lock()
.expect("test write-overlap lock must be healthy") = Some(Arc::clone(&overlap));
WriteOverlapControl {
overlap,
lease: Arc::clone(&writer.lease),
}
}