Skip to main content

vvv_engine/capabilities/
pagination.rs

1//! Shared delivery contracts and dispatch over the closed set of retained query kinds.
2use super::{context::ContextPage, search::SearchPage};
3use crate::graph::{Graph, query_snapshot::QuerySnapshot};
4use crate::query_store::{Checkpoint, QueryData, QueryRoot};
5use crate::{ContentId, Cursor, Engine, EngineError, SnapshotId};
6use serde::{Deserialize, Serialize};
7use std::{sync::Arc, time::Instant};
8
9#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
10#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
11#[serde(default, deny_unknown_fields)]
12pub struct PageBudget {
13    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = 64)))]
14    pub max_items: usize,
15    #[cfg_attr(feature = "schema", schemars(range(min = 1024, max = 1048576)))]
16    pub max_bytes: usize,
17}
18impl Default for PageBudget {
19    fn default() -> Self {
20        Self {
21            max_items: 20,
22            max_bytes: 16_384,
23        }
24    }
25}
26impl PageBudget {
27    pub const MAXIMUM: Self = Self {
28        max_items: 64,
29        max_bytes: 1_048_576,
30    };
31    pub fn validate(&self) -> Result<(), EngineError> {
32        if !(1..=Self::MAXIMUM.max_items).contains(&self.max_items)
33            || !(1024..=Self::MAXIMUM.max_bytes).contains(&self.max_bytes)
34        {
35            return Err(EngineError::InvalidBudget);
36        }
37        Ok(())
38    }
39    pub(crate) fn check(&self, value: &impl Serialize) -> Result<(), EngineError> {
40        let required_bytes = serde_json::to_vec(value).expect("page serializes").len();
41        if required_bytes > self.max_bytes {
42            return Err(EngineError::OutputLimit {
43                max_bytes: self.max_bytes,
44                required_bytes,
45            });
46        }
47        Ok(())
48    }
49}
50
51#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
52#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
53#[serde(default, deny_unknown_fields)]
54pub struct WorkBudget {
55    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = 512)))]
56    pub max_lookups: usize,
57    #[cfg_attr(feature = "schema", schemars(range(min = 1, max = 1024)))]
58    pub max_files: usize,
59}
60impl Default for WorkBudget {
61    fn default() -> Self {
62        Self {
63            max_lookups: 64,
64            max_files: 64,
65        }
66    }
67}
68impl WorkBudget {
69    pub const MAXIMUM: Self = Self {
70        max_lookups: 512,
71        max_files: 1024,
72    };
73    pub fn validate(&self) -> Result<(), EngineError> {
74        if !(1..=512).contains(&self.max_lookups) || !(1..=1024).contains(&self.max_files) {
75            return Err(EngineError::InvalidBudget);
76        }
77        Ok(())
78    }
79}
80
81#[derive(Debug, Clone, Serialize, Deserialize)]
82#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
83#[serde(untagged)]
84pub enum PageReply {
85    Search(SearchPage),
86    Context(ContextPage),
87    Relationships(super::relationships::Relationships),
88}
89impl PageReply {
90    pub fn next_cursor(&self) -> Option<&Cursor> {
91        match self {
92            Self::Search(p) => p.next_cursor.as_ref(),
93            Self::Context(p) => p.next_cursor.as_ref(),
94            Self::Relationships(p) => p.next_cursor.as_ref(),
95        }
96    }
97    pub fn snapshot(&self) -> &SnapshotId {
98        match self {
99            Self::Search(p) => &p.snapshot,
100            Self::Context(p) => &p.snapshot,
101            Self::Relationships(p) => &p.snapshot,
102        }
103    }
104}
105
106#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
107#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
108#[serde(deny_unknown_fields)]
109pub struct ContinueQuery {
110    pub cursor: Cursor,
111    #[serde(default)]
112    pub page: PageBudget,
113    #[serde(default, skip_serializing_if = "Option::is_none")]
114    pub work: Option<WorkBudget>,
115}
116impl ContinueQuery {
117    pub fn execute(self, engine: &Engine) -> Result<PageReply, EngineError> {
118        let _operation = engine.operation();
119        self.execute_in(engine)
120    }
121    pub(crate) fn execute_in(self, engine: &Engine) -> Result<PageReply, EngineError> {
122        self.page.validate()?;
123        if let Some(work) = &self.work {
124            work.validate()?;
125        }
126        let (mut session, checkpoint, mut graph) =
127            PageSession::resume(engine, &self.cursor, false)?;
128        let result = match checkpoint {
129            Checkpoint::Search(state) => {
130                if self.work.is_some() {
131                    return Err(EngineError::InvalidBudget);
132                }
133                state.page(engine, &mut session, self.page)
134            }
135            Checkpoint::Context(state) => state.page(
136                engine,
137                &mut graph,
138                &mut session,
139                self.page,
140                self.work.unwrap_or_default(),
141            ),
142            Checkpoint::Relationships(state) => {
143                let work = self.work.unwrap_or_default();
144                state.page(
145                    engine,
146                    &mut graph,
147                    &mut session,
148                    super::relationships::RelationshipBudget {
149                        max_items: self.page.max_items,
150                        max_bytes: self.page.max_bytes,
151                        max_lookups: work.max_lookups,
152                        max_files: work.max_files,
153                    },
154                )
155            }
156            Checkpoint::Excerpt(_) => Err(EngineError::InvalidCursor),
157        };
158        session.finish(engine, result)
159    }
160}
161
162pub(crate) struct PageSession {
163    pub id: u64,
164    pub root: Arc<QueryRoot>,
165    checkpoints: Vec<Checkpoint>,
166}
167impl PageSession {
168    pub(crate) fn new(
169        engine: &Engine,
170        snapshot: QuerySnapshot,
171        query: &impl Serialize,
172        data: QueryData,
173    ) -> Self {
174        let identity =
175            ContentId::of(&serde_json::to_string(&(&snapshot, query)).expect("query serializes"))
176                .into();
177        Self {
178            id: engine.queries().allocate(),
179            root: Arc::new(QueryRoot {
180                snapshot,
181                identity,
182                data,
183                revision: engine.query_revision(),
184                created: Instant::now(),
185            }),
186            checkpoints: vec![],
187        }
188    }
189    pub(crate) fn resume(
190        engine: &Engine,
191        cursor: &Cursor,
192        excerpt: bool,
193    ) -> Result<(Self, Checkpoint, Graph), EngineError> {
194        let lease =
195            engine
196                .queries()
197                .lease(cursor, excerpt, engine.query_revision(), Instant::now())?;
198        let (graph, snapshot) = match QuerySnapshot::capture(engine) {
199            Err(EngineError::StaleQuery | EngineError::StaleSource { .. }) => {
200                engine.check_read()?;
201                engine.queries().invalidate(lease.id);
202                return Err(EngineError::StaleQuery);
203            }
204            other => other?,
205        };
206        engine.check_read()?;
207        if snapshot != lease.root.snapshot {
208            engine.queries().invalidate(lease.id);
209            return Err(EngineError::StaleQuery);
210        }
211        Ok((
212            Self {
213                id: lease.id,
214                root: lease.root,
215                checkpoints: vec![],
216            },
217            lease.checkpoint,
218            graph,
219        ))
220    }
221    pub(crate) fn token(&self, engine: &Engine, checkpoint: &Checkpoint) -> Cursor {
222        engine.queries().cursor(self.id, checkpoint)
223    }
224    pub(crate) fn retain(&mut self, checkpoint: Checkpoint) {
225        self.checkpoints.push(checkpoint);
226    }
227    pub(crate) fn finish<T>(
228        self,
229        engine: &Engine,
230        result: Result<T, EngineError>,
231    ) -> Result<T, EngineError> {
232        let result = result.and_then(|answer| {
233            self.root.snapshot.validate(engine)?;
234            if self.root.revision != engine.query_revision() {
235                return Err(EngineError::StaleQuery);
236            }
237            Ok(answer)
238        });
239        engine.check_read()?;
240        match result {
241            Err(EngineError::StaleQuery | EngineError::StaleSource { .. }) => {
242                engine.queries().invalidate(self.id);
243                Err(EngineError::StaleQuery)
244            }
245            Err(error) => Err(error),
246            Ok(answer) => {
247                engine.publish_read(|| {
248                    engine
249                        .queries()
250                        .publish(self.id, self.root, self.checkpoints, Instant::now())
251                })?;
252                Ok(answer)
253            }
254        }
255    }
256}
257
258impl crate::report::Document {
259    pub(crate) fn page(reply: &PageReply) -> Self {
260        match reply {
261            PageReply::Search(page) => Self::search_page(page),
262            PageReply::Context(page) => Self::context_page(page),
263            PageReply::Relationships(page) => Self::relationships(page),
264        }
265    }
266}