1use std::error;
9use std::fmt;
10use std::sync::{Arc, RwLock};
11#[cfg(test)]
12use std::sync::{Barrier, Mutex, TryLockError};
13
14use super::item::Item;
15use crate::redact::Locked;
16
17#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
28pub struct Version(u64);
29
30impl Version {
31 pub const ZERO: Self = Self(0);
33
34 pub const MAX: Self = Self(u64::MAX);
36
37 #[must_use]
39 pub const fn from_u64(value: u64) -> Self {
40 Self(value)
41 }
42
43 #[must_use]
45 pub const fn as_u64(self) -> u64 {
46 self.0
47 }
48
49 fn checked_add(self, delta: u64) -> Option<Self> {
50 self.0.checked_add(delta).map(Self)
51 }
52}
53
54impl fmt::Display for Version {
55 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
56 self.0.fmt(formatter)
57 }
58}
59
60#[derive(Clone, Debug)]
66pub struct Snapshot {
67 version: Version,
68 items: Arc<Vec<Item>>,
69}
70
71impl Snapshot {
72 #[must_use]
74 pub fn new(version: Version, items: Vec<Item>) -> Self {
75 Self::from_shared(version, Arc::new(items))
76 }
77
78 const fn from_shared(version: Version, items: Arc<Vec<Item>>) -> Self {
79 Self { version, items }
80 }
81
82 pub(crate) fn with_version(self, version: Version) -> Self {
83 Self {
84 version,
85 items: self.items,
86 }
87 }
88
89 #[must_use]
91 pub const fn version(&self) -> Version {
92 self.version
93 }
94
95 #[must_use]
97 pub fn items(&self) -> &[Item] {
98 self.items.as_slice()
99 }
100
101 #[must_use]
106 pub fn into_parts(self) -> (Version, Vec<Item>) {
107 let items = Arc::try_unwrap(self.items).unwrap_or_else(|items| items.as_ref().clone());
108 (self.version, items)
109 }
110
111 #[cfg(test)]
112 pub(crate) fn shares_items_with(&self, other: &Self) -> bool {
113 Arc::ptr_eq(&self.items, &other.items)
114 }
115
116 #[cfg(test)]
117 pub(crate) fn items_backing_ptr(&self) -> *const Vec<Item> {
118 Arc::as_ptr(&self.items)
119 }
120}
121
122#[derive(Clone, Copy, Debug, Eq, PartialEq)]
124#[non_exhaustive]
125pub enum Error {
126 #[non_exhaustive]
128 VersionConflict {
129 expected: Version,
131 actual: Version,
133 },
134 #[non_exhaustive]
136 VersionOverflow {
137 current: Version,
139 delta: u64,
141 },
142 Poisoned,
146}
147
148impl fmt::Display for Error {
149 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
150 match self {
151 Self::VersionConflict { expected, actual } => write!(
152 formatter,
153 "transcript version conflict: expected {expected}, actual {actual}"
154 ),
155 Self::VersionOverflow { current, delta } => write!(
156 formatter,
157 "transcript version overflow: current {current}, increment {delta}"
158 ),
159 Self::Poisoned => formatter.write_str("transcript store lock poisoned"),
160 }
161 }
162}
163
164impl error::Error for Error {}
165
166struct State {
167 version: Version,
168 items: Arc<Vec<Item>>,
169 staged_tail: Option<Vec<Item>>,
170}
171
172impl State {
173 fn has_staged_items(&self) -> bool {
174 self.staged_tail
175 .as_ref()
176 .is_some_and(|tail| !tail.is_empty())
177 }
178
179 fn materialize_staged_items(&mut self) {
180 let Some(mut tail) = self.staged_tail.take() else {
181 return;
182 };
183 if tail.is_empty() {
184 self.staged_tail = Some(tail);
185 return;
186 }
187 Arc::make_mut(&mut self.items).append(&mut tail);
188 self.staged_tail = Some(Vec::new());
189 }
190
191 fn snapshot(&self) -> Snapshot {
192 debug_assert!(!self.has_staged_items());
193 Snapshot::from_shared(self.version, Arc::clone(&self.items))
194 }
195
196 fn into_snapshot(mut self) -> Snapshot {
197 self.materialize_staged_items();
198 Snapshot::from_shared(self.version, self.items)
199 }
200
201 fn into_snapshot_with_suffix(mut self, mut suffix: Vec<Item>) -> Snapshot {
202 if let Some(tail) = &mut self.staged_tail {
203 tail.append(&mut suffix);
204 } else {
205 Arc::make_mut(&mut self.items).append(&mut suffix);
206 }
207 self.into_snapshot()
208 }
209}
210
211struct Core {
212 state: RwLock<State>,
213 #[cfg(test)]
214 commit_overlap: Mutex<Option<Arc<CommitOverlap>>>,
215}
216
217#[cfg(test)]
218struct CommitOverlap {
219 writer_ready: Barrier,
220 reader_contending: Barrier,
221 commit_release: Barrier,
222}
223
224#[cfg(test)]
225impl CommitOverlap {
226 fn new() -> Self {
227 Self {
228 writer_ready: Barrier::new(2),
229 reader_contending: Barrier::new(3),
230 commit_release: Barrier::new(2),
231 }
232 }
233}
234
235#[cfg(test)]
236pub(super) struct CommitOverlapControl {
237 overlap: Arc<CommitOverlap>,
238}
239
240#[cfg(test)]
241impl CommitOverlapControl {
242 pub(super) fn wait_for_writer(&self) {
243 self.overlap.writer_ready.wait();
244 }
245
246 pub(super) fn wait_for_reader(&self) {
247 self.overlap.reader_contending.wait();
248 }
249
250 pub(super) fn release_writer(&self) {
251 self.overlap.commit_release.wait();
252 }
253}
254
255impl Core {
256 fn debug_handle(&self, name: &str, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
263 let mut handle = formatter.debug_struct(name);
264 match self.state.try_read() {
265 Ok(state) => handle.field("version", &state.version),
266 Err(_contended_or_poisoned) => handle.field("version", &Locked),
267 }
268 .finish()
269 }
270
271 #[cfg(test)]
272 fn test_before_read(&self) {
273 let overlap = self
274 .commit_overlap
275 .lock()
276 .expect("test overlap lock must be healthy")
277 .clone();
278 if let Some(overlap) = overlap {
279 assert!(
284 matches!(self.state.try_read(), Err(TryLockError::WouldBlock)),
285 "overlap seam requires the production write lock to be held"
286 );
287 overlap.reader_contending.wait();
288 }
289 }
290
291 #[cfg(test)]
292 fn test_before_commit(&self) {
293 let overlap = self
294 .commit_overlap
295 .lock()
296 .expect("test overlap lock must be healthy")
297 .clone();
298 if let Some(overlap) = overlap {
299 overlap.writer_ready.wait();
303 overlap.reader_contending.wait();
304 overlap.commit_release.wait();
305 *self
306 .commit_overlap
307 .lock()
308 .expect("test overlap lock must be healthy") = None;
309 }
310 }
311
312 fn items(&self) -> Result<Vec<Item>, Error> {
313 self.snapshot().map(|snapshot| snapshot.into_parts().1)
314 }
315
316 fn snapshot(&self) -> Result<Snapshot, Error> {
317 #[cfg(test)]
318 self.test_before_read();
319 {
320 let state = self.state.read().map_err(|_| Error::Poisoned)?;
321 if !state.has_staged_items() {
322 return Ok(state.snapshot());
323 }
324 }
325
326 let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
327 state.materialize_staged_items();
328 Ok(state.snapshot())
329 }
330
331 fn version(&self) -> Result<Version, Error> {
332 #[cfg(test)]
333 self.test_before_read();
334 let state = self.state.read().map_err(|_| Error::Poisoned)?;
335 Ok(state.version)
336 }
337
338 fn append_batch(
339 &self,
340 mut candidate: Vec<Item>,
341 expected: Option<Version>,
342 ) -> Result<Version, Error> {
343 let delta = candidate.len() as u64;
346 let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
347 if let Some(expected) = expected {
348 if state.version != expected {
349 return Err(Error::VersionConflict {
350 expected,
351 actual: state.version,
352 });
353 }
354 }
355 let next = state
356 .version
357 .checked_add(delta)
358 .ok_or(Error::VersionOverflow {
359 current: state.version,
360 delta,
361 })?;
362 #[cfg(test)]
363 self.test_before_commit();
364 if let Some(tail) = &mut state.staged_tail {
365 tail.append(&mut candidate);
366 } else {
367 Arc::make_mut(&mut state.items).append(&mut candidate);
368 }
369 state.version = next;
370 Ok(next)
371 }
372
373 fn replace(&self, candidate: Vec<Item>, expected: Option<Version>) -> Result<Version, Error> {
374 let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
375 if let Some(expected) = expected {
376 if state.version != expected {
377 return Err(Error::VersionConflict {
378 expected,
379 actual: state.version,
380 });
381 }
382 }
383 let next = state.version.checked_add(1).ok_or(Error::VersionOverflow {
384 current: state.version,
385 delta: 1,
386 })?;
387 #[cfg(test)]
388 self.test_before_commit();
389 state.items = Arc::new(candidate);
390 if let Some(tail) = &mut state.staged_tail {
391 tail.clear();
392 }
393 state.version = next;
394 Ok(next)
395 }
396
397 fn replace_snapshot(&self, candidate: Snapshot, expected: Version) -> Result<Version, Error> {
398 if let Some(next) = expected.checked_add(1) {
402 assert_eq!(
403 candidate.version(),
404 next,
405 "snapshot installed at a live boundary must carry that boundary's successor version"
406 );
407 }
408 let mut state = self.state.write().map_err(|_| Error::Poisoned)?;
409 if state.version != expected {
410 return Err(Error::VersionConflict {
411 expected,
412 actual: state.version,
413 });
414 }
415 let next = state.version.checked_add(1).ok_or(Error::VersionOverflow {
416 current: state.version,
417 delta: 1,
418 })?;
419 #[cfg(test)]
420 self.test_before_commit();
421 state.items = candidate.items;
422 if let Some(tail) = &mut state.staged_tail {
423 tail.clear();
424 }
425 state.version = next;
426 Ok(next)
427 }
428}
429
430#[derive(Clone)]
442pub struct Store {
443 core: Arc<Core>,
444}
445
446impl fmt::Debug for Store {
447 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
448 self.core.debug_handle("Store", formatter)
449 }
450}
451
452impl Store {
453 #[must_use]
455 pub fn new() -> Self {
456 Self::from_items(Vec::new())
457 }
458
459 #[must_use]
461 pub fn from_items(items: Vec<Item>) -> Self {
462 Self::from_state(Version::ZERO, items)
463 }
464
465 #[must_use]
471 pub fn restore(snapshot: Snapshot) -> Self {
472 let Snapshot { version, items } = snapshot;
473 Self::from_shared_state(version, items, None)
474 }
475
476 pub(crate) fn fork(&self) -> Result<Self, Error> {
477 let snapshot = self.core.snapshot()?;
478 Ok(Self::from_shared_state(
479 snapshot.version,
480 snapshot.items,
481 Some(Vec::new()),
482 ))
483 }
484
485 pub(crate) fn version(&self) -> Result<Version, Error> {
486 self.core.version()
487 }
488
489 pub(crate) fn into_snapshot(self) -> Result<Snapshot, Error> {
490 match Arc::try_unwrap(self.core) {
491 Ok(core) => core
492 .state
493 .into_inner()
494 .map(State::into_snapshot)
495 .map_err(|_| Error::Poisoned),
496 Err(core) => core.snapshot(),
497 }
498 }
499
500 pub(crate) fn into_snapshot_with_suffix(self, suffix: Vec<Item>) -> Result<Snapshot, Error> {
501 match Arc::try_unwrap(self.core) {
502 Ok(core) => core
503 .state
504 .into_inner()
505 .map(|state| state.into_snapshot_with_suffix(suffix))
506 .map_err(|_| Error::Poisoned),
507 Err(core) => {
508 let mut snapshot = core.snapshot()?;
509 Arc::make_mut(&mut snapshot.items).extend(suffix);
510 Ok(snapshot)
511 }
512 }
513 }
514
515 #[cfg(test)]
516 pub(crate) fn into_items(self) -> Result<Vec<Item>, Error> {
517 self.into_snapshot().map(|snapshot| snapshot.into_parts().1)
518 }
519
520 fn from_state(version: Version, items: Vec<Item>) -> Self {
521 Self::from_shared_state(version, Arc::new(items), None)
522 }
523
524 fn from_shared_state(
525 version: Version,
526 items: Arc<Vec<Item>>,
527 staged_tail: Option<Vec<Item>>,
528 ) -> Self {
529 Self {
530 core: Arc::new(Core {
531 state: RwLock::new(State {
532 version,
533 items,
534 staged_tail,
535 }),
536 #[cfg(test)]
537 commit_overlap: Mutex::new(None),
538 }),
539 }
540 }
541
542 #[must_use]
544 pub fn reader(&self) -> Reader {
545 Reader {
546 core: Arc::clone(&self.core),
547 }
548 }
549
550 #[must_use]
552 pub fn snapshot_reader(&self) -> SnapshotReader {
553 SnapshotReader {
554 core: Arc::clone(&self.core),
555 }
556 }
557
558 #[must_use]
560 pub fn appender(&self) -> Appender {
561 Appender {
562 core: Arc::clone(&self.core),
563 }
564 }
565
566 #[must_use]
568 pub fn replacer(&self) -> Replacer {
569 Replacer {
570 core: Arc::clone(&self.core),
571 }
572 }
573}
574
575impl Default for Store {
576 fn default() -> Self {
577 Self::new()
578 }
579}
580
581#[derive(Clone)]
594pub struct Reader {
595 core: Arc<Core>,
596}
597
598impl fmt::Debug for Reader {
599 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
600 self.core.debug_handle("Reader", formatter)
601 }
602}
603
604impl Reader {
605 pub fn items(&self) -> Result<Vec<Item>, Error> {
613 self.core.items()
614 }
615}
616
617#[derive(Clone)]
625pub struct SnapshotReader {
626 core: Arc<Core>,
627}
628
629impl fmt::Debug for SnapshotReader {
630 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
631 self.core.debug_handle("SnapshotReader", formatter)
632 }
633}
634
635impl SnapshotReader {
636 pub fn snapshot(&self) -> Result<Snapshot, Error> {
644 self.core.snapshot()
645 }
646
647 pub fn version(&self) -> Result<Version, Error> {
653 self.core.version()
654 }
655}
656
657#[derive(Clone)]
669pub struct Appender {
670 core: Arc<Core>,
671}
672
673impl fmt::Debug for Appender {
674 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
675 self.core.debug_handle("Appender", formatter)
676 }
677}
678
679impl Appender {
680 pub fn append(&self, item: Item) -> Result<Version, Error> {
689 self.core.append_batch(vec![item], None)
690 }
691
692 pub fn append_batch(&self, items: Vec<Item>) -> Result<Version, Error> {
706 self.core.append_batch(items, None)
707 }
708
709 pub fn append_batch_if_version(
725 &self,
726 items: Vec<Item>,
727 expected: Version,
728 ) -> Result<Version, Error> {
729 self.core.append_batch(items, Some(expected))
730 }
731}
732
733#[derive(Clone)]
744pub struct Replacer {
745 core: Arc<Core>,
746}
747
748impl fmt::Debug for Replacer {
749 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
750 self.core.debug_handle("Replacer", formatter)
751 }
752}
753
754impl Replacer {
755 pub fn replace(&self, items: Vec<Item>) -> Result<Version, Error> {
764 self.core.replace(items, None)
765 }
766
767 pub fn replace_if_version(
783 &self,
784 items: Vec<Item>,
785 expected: Version,
786 ) -> Result<Version, Error> {
787 self.core.replace(items, Some(expected))
788 }
789
790 pub(crate) fn install_snapshot_if_version(
791 &self,
792 snapshot: Snapshot,
793 expected: Version,
794 ) -> Result<Version, Error> {
795 self.core.replace_snapshot(snapshot, expected)
796 }
797}
798
799#[cfg(test)]
800pub(super) fn install_commit_overlap(store: &Store) -> CommitOverlapControl {
801 let overlap = Arc::new(CommitOverlap::new());
802 *store
803 .core
804 .commit_overlap
805 .lock()
806 .expect("test overlap lock must be healthy") = Some(Arc::clone(&overlap));
807 CommitOverlapControl { overlap }
808}
809
810#[cfg(test)]
815pub(super) fn hold_write_lock(store: &Store, held: &Barrier, release: &Barrier) {
816 let _guard = store.core.state.write().expect("test lock starts healthy");
817 held.wait();
818 release.wait();
819}
820
821#[cfg(test)]
822pub(crate) fn poison(store: &Store) {
823 let _guard = store.core.state.write().expect("test lock starts healthy");
824 panic!("intentional transcript-store poison");
825}
826
827#[cfg(feature = "serde")]
836mod serde_impl {
837 use std::fmt::{self, Formatter};
838
839 use serde_core::de::{
840 Deserialize, Deserializer, Error as DeError, MapAccess, SeqAccess, Visitor,
841 };
842 use serde_core::ser::{Serialize, SerializeStruct, Serializer};
843
844 use super::{Snapshot, Version};
845 use crate::wire::{self, IdentifierSeed};
846
847 const SNAPSHOT_FIELDS: &[&str] = &["version", "items"];
848
849 impl Serialize for Version {
850 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
851 where
852 S: Serializer,
853 {
854 serializer.serialize_u64(self.0)
855 }
856 }
857
858 impl<'de> Deserialize<'de> for Version {
859 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
860 where
861 D: Deserializer<'de>,
862 {
863 u64::deserialize(deserializer).map(Self::from_u64)
864 }
865 }
866
867 impl Serialize for Snapshot {
868 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
869 where
870 S: Serializer,
871 {
872 let mut record = serializer.serialize_struct("Snapshot", 2)?;
873 record.serialize_field("version", &self.version)?;
874 record.serialize_field("items", self.items())?;
875 record.end()
876 }
877 }
878
879 impl<'de> Deserialize<'de> for Snapshot {
880 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
881 where
882 D: Deserializer<'de>,
883 {
884 deserializer.deserialize_struct("Snapshot", SNAPSHOT_FIELDS, SnapshotVisitor)
885 }
886 }
887
888 struct SnapshotVisitor;
889
890 impl<'de> Visitor<'de> for SnapshotVisitor {
891 type Value = Snapshot;
892
893 fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
894 formatter.write_str("a transcript snapshot")
895 }
896
897 fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
898 where
899 A: SeqAccess<'de>,
900 {
901 let version = wire::element(&mut sequence, 0)?;
902 let items = wire::element(&mut sequence, 1)?;
903 wire::end(&mut sequence, 2)?;
904 Ok(Snapshot::new(version, items))
905 }
906
907 fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
908 where
909 A: MapAccess<'de>,
910 {
911 let mut version = None;
912 let mut items = None;
913 while let Some(field) = entries.next_key_seed(IdentifierSeed(SNAPSHOT_FIELDS))? {
914 match field.0.as_str() {
915 "version" => wire::accept(&mut version, entries.next_value()?, "version")?,
916 "items" => wire::accept(&mut items, entries.next_value()?, "items")?,
917 unknown => return Err(A::Error::unknown_field(unknown, SNAPSHOT_FIELDS)),
918 }
919 }
920 Ok(Snapshot::new(
921 wire::require(version, "version")?,
922 wire::require(items, "items")?,
923 ))
924 }
925 }
926}