visibility_index.rs (3988B)
1 //! Bounded canonical visibility-index preparation contracts. 2 3 use super::EventSourceToken; 4 use crate::Error; 5 6 /// Validated logical work envelope for one canonical index preparation call. 7 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 8 pub struct VisibilityIndexBounds { 9 rows: u16, 10 bytes: u64, 11 } 12 13 impl VisibilityIndexBounds { 14 /// Validates 1..=64 source rows and 1..=16 MiB of logical allocation charge. 15 pub fn new(rows: u16, bytes: u64) -> Result<Self, Error> { 16 if rows == 0 || rows > 64 || bytes == 0 || bytes > 16 * 1024 * 1024 { 17 return Err(Error::InvalidVisibilityIndexBounds); 18 } 19 Ok(Self { rows, bytes }) 20 } 21 22 /// Maximum source rows materialized in this call. 23 pub const fn rows(self) -> u16 { 24 self.rows 25 } 26 27 /// Maximum conservative logical allocation charge in this call. 28 pub const fn bytes(self) -> u64 { 29 self.bytes 30 } 31 32 /// Charges retained bytes, decoded variable data and derived metadata. 33 /// 34 /// This conservative envelope is not a measurement of allocator RSS. 35 #[doc(hidden)] 36 pub fn charge(signed_bytes: u64) -> Result<u64, Error> { 37 signed_bytes 38 .checked_mul(16) 39 .and_then(|value| value.checked_add(4096)) 40 .ok_or(Error::SpaceInsufficient) 41 } 42 } 43 44 /// Durable progress observed after one canonical index preparation transaction. 45 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 46 pub struct VisibilityIndexProgress { 47 token: EventSourceToken, 48 source_sequence: u64, 49 replay_epoch: u64, 50 processed_rows: u16, 51 processed_keys: u16, 52 charged_bytes: u64, 53 complete: bool, 54 } 55 56 impl VisibilityIndexProgress { 57 #[doc(hidden)] 58 pub const fn new( 59 token: EventSourceToken, 60 source_sequence: u64, 61 replay_epoch: u64, 62 processed_rows: u16, 63 charged_bytes: u64, 64 complete: bool, 65 ) -> Self { 66 Self { 67 token, 68 source_sequence, 69 replay_epoch, 70 processed_rows, 71 processed_keys: 0, 72 charged_bytes, 73 complete, 74 } 75 } 76 77 /// Source fence read inside the completed preparation transaction. 78 pub const fn token(self) -> EventSourceToken { 79 self.token 80 } 81 /// Last initial-backfill sequence durably prepared; it never restarts on admission. 82 pub const fn source_sequence(self) -> u64 { 83 self.source_sequence 84 } 85 /// Last durable changed-event replay epoch. 86 pub const fn replay_epoch(self) -> u64 { 87 self.replay_epoch 88 } 89 /// Actual source rows materialized, including repeated changed rows. 90 pub const fn processed_rows(self) -> u16 { 91 self.processed_rows 92 } 93 /// Affected deletion keys refreshed within the same total row-unit budget. 94 pub const fn processed_keys(self) -> u16 { 95 self.processed_keys 96 } 97 98 #[doc(hidden)] 99 pub const fn with_processed_keys(mut self, keys: u16) -> Self { 100 self.processed_keys = keys; 101 self 102 } 103 /// Conservative logical allocation charge of this call. 104 pub const fn charged_bytes(self) -> u64 { 105 self.charged_bytes 106 } 107 /// Whether canonical metadata matches `token`; it is not a consumer-content claim. 108 pub const fn is_complete(self) -> bool { 109 self.complete 110 } 111 } 112 113 #[cfg(test)] 114 mod tests { 115 use super::*; 116 117 #[test] 118 fn work_envelope_rejects_zero_and_one_over_without_relaxing_caps() { 119 assert!(VisibilityIndexBounds::new(64, 16 * 1024 * 1024).is_ok()); 120 for (rows, bytes) in [(0, 1), (65, 1), (1, 0), (1, 16 * 1024 * 1024 + 1)] { 121 assert_eq!( 122 VisibilityIndexBounds::new(rows, bytes), 123 Err(Error::InvalidVisibilityIndexBounds) 124 ); 125 } 126 assert_eq!(VisibilityIndexBounds::charge(10).unwrap(), 4256); 127 assert_eq!( 128 VisibilityIndexBounds::charge(u64::MAX), 129 Err(Error::SpaceInsufficient) 130 ); 131 } 132 }