lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

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 }