document_query.rs (9404B)
1 //! Bounded opaque document inventory. A continuation is not a frozen snapshot. 2 #[cfg(test)] 3 mod selection_tests; 4 #[cfg(test)] 5 mod tests; 6 use super::{Error, ProjectionDocument, ProjectionGeneration, ProjectionId, valid_document_key}; 7 8 pub const PROJECTION_DOCUMENT_QUERY_LIMIT_MAX: u16 = 256; 9 pub const PROJECTION_DOCUMENT_PAGE_BYTES_MAX: usize = super::PROJECTION_DOCUMENT_VALUE_MAX_BYTES; 10 11 /// Inclusive opaque key interval within one independently selected generation. 12 #[derive(Clone, Debug, Eq, PartialEq)] 13 pub struct ProjectionDocumentKeyRange { 14 first: String, 15 last: String, 16 } 17 18 impl ProjectionDocumentKeyRange { 19 pub fn new(first: String, last: String) -> Result<Self, Error> { 20 if !valid_document_key(&first) || !valid_document_key(&last) || first > last { 21 return Err(Error::InvalidProjectionDocument); 22 } 23 Ok(Self { first, last }) 24 } 25 pub fn first(&self) -> &str { 26 &self.first 27 } 28 pub fn last(&self) -> &str { 29 &self.last 30 } 31 fn contains(&self, key: &str) -> bool { 32 self.first.as_str() <= key && key <= self.last.as_str() 33 } 34 } 35 36 #[derive(Clone, Copy, Debug, Eq, PartialEq)] 37 pub enum ProjectionDocumentGenerations { 38 Exact(ProjectionGeneration), 39 All, 40 } 41 42 #[derive(Clone, Debug, Eq, PartialEq)] 43 pub struct ProjectionDocumentQuery { 44 projection_id: ProjectionId, 45 generations: ProjectionDocumentGenerations, 46 limit: u16, 47 after: Option<(ProjectionGeneration, String)>, 48 key_range: Option<ProjectionDocumentKeyRange>, 49 payload_budget: usize, 50 } 51 52 impl ProjectionDocumentQuery { 53 pub fn new( 54 projection_id: ProjectionId, 55 generations: ProjectionDocumentGenerations, 56 limit: u16, 57 ) -> Result<Self, Error> { 58 ProjectionId::parse(projection_id.as_str())?; 59 if let ProjectionDocumentGenerations::Exact(generation) = generations { 60 ProjectionGeneration::new(*generation.as_bytes())?; 61 } 62 if limit == 0 || limit > PROJECTION_DOCUMENT_QUERY_LIMIT_MAX { 63 return Err(Error::InvalidProjectionDocument); 64 } 65 Ok(Self { 66 projection_id, 67 generations, 68 limit, 69 after: None, 70 key_range: None, 71 payload_budget: PROJECTION_DOCUMENT_PAGE_BYTES_MAX, 72 }) 73 } 74 pub fn with_cursor(mut self, cursor: &ProjectionDocumentCursor) -> Result<Self, Error> { 75 if self.projection_id != cursor.projection_id 76 || self.generations != cursor.generations 77 || self.key_range != cursor.key_range 78 { 79 return Err(Error::InvalidProjectionDocument); 80 } 81 self.after = Some(cursor.after.clone()); 82 Ok(self) 83 } 84 /// Configure selection before seeking; a continuation cannot widen this interval. 85 pub fn with_key_range(mut self, range: ProjectionDocumentKeyRange) -> Result<Self, Error> { 86 if !matches!(self.generations, ProjectionDocumentGenerations::Exact(_)) 87 || self.after.is_some() 88 { 89 return Err(Error::InvalidProjectionDocument); 90 } 91 self.key_range = Some(range); 92 Ok(self) 93 } 94 /// Seek a caller-validated key in this exact generation, without a retained snapshot. 95 /// This does not prove that the position exists or freeze application read scope. 96 pub fn with_after_key(mut self, key: String) -> Result<Self, Error> { 97 let ProjectionDocumentGenerations::Exact(generation) = self.generations else { 98 return Err(Error::InvalidProjectionDocument); 99 }; 100 if !valid_document_key(&key) 101 || self 102 .key_range 103 .as_ref() 104 .is_some_and(|range| !range.contains(&key)) 105 { 106 return Err(Error::InvalidProjectionDocument); 107 } 108 self.after = Some((generation, key)); 109 Ok(self) 110 } 111 /// Lower the encoded-payload ceiling before provider allocation. Metadata remains 112 /// bounded by the record limit plus one lookahead; callers charge their decoding. 113 pub fn with_payload_budget(mut self, bytes: usize) -> Result<Self, Error> { 114 if bytes == 0 || bytes > PROJECTION_DOCUMENT_PAGE_BYTES_MAX { 115 return Err(Error::InvalidProjectionDocument); 116 } 117 self.payload_budget = bytes; 118 Ok(self) 119 } 120 pub const fn payload_budget(&self) -> usize { 121 self.payload_budget 122 } 123 pub const fn key_range(&self) -> Option<&ProjectionDocumentKeyRange> { 124 self.key_range.as_ref() 125 } 126 pub fn projection_id(&self) -> &ProjectionId { 127 &self.projection_id 128 } 129 pub const fn generations(&self) -> ProjectionDocumentGenerations { 130 self.generations 131 } 132 pub const fn limit(&self) -> u16 { 133 self.limit 134 } 135 pub fn after(&self) -> Option<(ProjectionGeneration, &str)> { 136 self.after 137 .as_ref() 138 .map(|(generation, key)| (*generation, key.as_str())) 139 } 140 pub fn matches(&self, generation: ProjectionGeneration, key: &str) -> bool { 141 (match self.generations { 142 ProjectionDocumentGenerations::Exact(expected) => generation == expected, 143 ProjectionDocumentGenerations::All => true, 144 }) && self.after().is_none_or(|after| (generation, key) > after) 145 && self 146 .key_range 147 .as_ref() 148 .is_none_or(|range| range.contains(key)) 149 } 150 } 151 152 /// In-process continuation; the next call independently supplies its scope. 153 #[derive(Clone, Debug, Eq, PartialEq)] 154 pub struct ProjectionDocumentCursor { 155 projection_id: ProjectionId, 156 generations: ProjectionDocumentGenerations, 157 after: (ProjectionGeneration, String), 158 key_range: Option<ProjectionDocumentKeyRange>, 159 } 160 161 /// An absent document is explicit corruption requiring caller reconciliation. 162 #[derive(Clone, Eq, PartialEq)] 163 pub struct ProjectionDocumentRecord { 164 generation: ProjectionGeneration, 165 key: String, 166 document: Option<ProjectionDocument>, 167 } 168 impl ProjectionDocumentRecord { 169 pub fn new( 170 generation: ProjectionGeneration, 171 document: ProjectionDocument, 172 ) -> Result<Self, Error> { 173 ProjectionGeneration::new(*generation.as_bytes())?; 174 Ok(Self { 175 generation, 176 key: document.key().to_owned(), 177 document: Some(document), 178 }) 179 } 180 pub fn corrupt(generation: ProjectionGeneration, key: String) -> Result<Self, Error> { 181 ProjectionGeneration::new(*generation.as_bytes())?; 182 if !valid_document_key(&key) { 183 return Err(Error::CorruptProjectionDocument); 184 } 185 Ok(Self { 186 generation, 187 key, 188 document: None, 189 }) 190 } 191 pub const fn generation(&self) -> ProjectionGeneration { 192 self.generation 193 } 194 pub fn key(&self) -> &str { 195 &self.key 196 } 197 pub const fn document(&self) -> Option<&ProjectionDocument> { 198 self.document.as_ref() 199 } 200 } 201 impl std::fmt::Debug for ProjectionDocumentRecord { 202 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { 203 formatter 204 .debug_struct("ProjectionDocumentRecord") 205 .field("generation", &self.generation) 206 .field("key", &self.key) 207 .field("corrupt", &self.document.is_none()) 208 .finish() 209 } 210 } 211 212 #[derive(Clone, Debug, Eq, PartialEq)] 213 pub struct ProjectionDocumentPage { 214 records: Vec<ProjectionDocumentRecord>, 215 next_cursor: Option<ProjectionDocumentCursor>, 216 } 217 impl ProjectionDocumentPage { 218 /// Backends must bound bytes read, including invalid payloads, before constructing a page. 219 pub fn new( 220 query: &ProjectionDocumentQuery, 221 records: Vec<ProjectionDocumentRecord>, 222 has_more: bool, 223 ) -> Result<Self, Error> { 224 if records.len() > usize::from(query.limit) || (has_more && records.is_empty()) { 225 return Err(Error::InvalidProjectionDocument); 226 } 227 let mut previous = query.after(); 228 let mut bytes = 0; 229 for record in &records { 230 let position = (record.generation, record.key()); 231 if !query.matches(position.0, position.1) 232 || previous.is_some_and(|last| position <= last) 233 { 234 return Err(Error::InvalidProjectionDocument); 235 } 236 bytes += record 237 .document() 238 .map_or(0, |document| document.value().len()); 239 if bytes > query.payload_budget { 240 return Err(Error::InvalidProjectionDocument); 241 } 242 previous = Some(position); 243 } 244 let next_cursor = if has_more { 245 previous.map(|(generation, key)| ProjectionDocumentCursor { 246 projection_id: query.projection_id.clone(), 247 generations: query.generations, 248 after: (generation, key.to_owned()), 249 key_range: query.key_range.clone(), 250 }) 251 } else { 252 None 253 }; 254 Ok(Self { 255 records, 256 next_cursor, 257 }) 258 } 259 pub fn records(&self) -> &[ProjectionDocumentRecord] { 260 &self.records 261 } 262 pub const fn next_cursor(&self) -> Option<&ProjectionDocumentCursor> { 263 self.next_cursor.as_ref() 264 } 265 pub fn into_records(self) -> Vec<ProjectionDocumentRecord> { 266 self.records 267 } 268 }