Skip to main content

ic_db/store/query/aggregate/jobs/
pages.rs

1//! Bounded pages over immutable completed groups; no additional durable state.
2use super::{
3    super::{Completed, Groups, MAX_GROUPS, admit_output},
4    JobHandle, JobOutcome,
5    storage::Record,
6};
7use crate::Error;
8
9/// One page of completed retained groups. Keep `next` when mapping `rows`.
10#[derive(Debug)]
11pub struct GroupPage<T> {
12    /// Completed groups in the bound query's selected total order.
13    pub rows: Vec<T>,
14    /// None marks the end of the selected result, including the query's total limit.
15    pub next: Option<GroupCursor>,
16}
17
18/// Logical position in one completed retained job, not an authorization token.
19/// Positions are revalidated against the selected result; caller edits can skip
20/// rows intentionally but cannot change the result or advance input progress.
21#[derive(Clone, Debug, PartialEq, Eq)]
22pub struct GroupCursor {
23    handle: JobHandle,
24    position: u8,
25}
26impl GroupCursor {
27    /// Encode a fixed 28-byte transport cursor.
28    #[must_use]
29    pub fn to_bytes(&self) -> Vec<u8> {
30        let mut bytes = vec![1];
31        bytes.extend(self.handle.to_bytes());
32        bytes.push(self.position);
33        bytes
34    }
35
36    /// Decode bounded framing; resume also checks the live job and result bounds.
37    /// # Errors
38    /// Refuses unsupported versions, malformed handles or positions outside 1..=32.
39    pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
40        if bytes.len() != 28 || bytes[0] != 1 || !(1..=MAX_GROUPS as u8).contains(&bytes[27]) {
41            return Err(Error::InvalidCursor);
42        }
43        Ok(Self {
44            handle: JobHandle::from_bytes(&bytes[1..27]).map_err(|_| Error::InvalidCursor)?,
45            position: bytes[27],
46        })
47    }
48}
49
50#[derive(Clone, Copy)]
51pub(in crate::store::query::aggregate) struct PageRequest<'a> {
52    pub size: usize,
53    pub after: Option<&'a GroupCursor>,
54}
55
56pub(super) fn admit(
57    page: Option<PageRequest<'_>>,
58    handle: &JobHandle,
59    record: &Record,
60) -> Result<(), Error> {
61    if let Some(cursor) = page.and_then(|page| page.after)
62        && (cursor.handle != *handle
63            || !matches!(record.phase, JobOutcome::Complete(()) | JobOutcome::Expired))
64    {
65        return Err(Error::InvalidCursor);
66    }
67    Ok(())
68}
69
70pub(super) fn group_page<T>(
71    groups: Groups,
72    limit: usize,
73    bytes: usize,
74    page: Option<PageRequest<'_>>,
75    handle: &JobHandle,
76    decode: fn(&[u8], Completed) -> Result<T, Error>,
77) -> Result<(GroupPage<T>, usize), Error> {
78    // Finalize every group before selection; even an excluded overflow must refuse.
79    let mut rows = groups.into_output()?;
80    rows.truncate(limit);
81    let (range, next, used) = select(&rows, bytes, page, handle)?;
82    let rows = rows
83        .drain(range)
84        .map(|(key, value)| decode(&key, value))
85        .collect::<Result<_, _>>()?;
86    Ok((GroupPage { rows, next }, used))
87}
88
89fn select(
90    rows: &[(Vec<u8>, Completed)],
91    bytes: usize,
92    page: Option<PageRequest<'_>>,
93    handle: &JobHandle,
94) -> Result<(std::ops::Range<usize>, Option<GroupCursor>, usize), Error> {
95    let start = page
96        .and_then(|page| page.after)
97        .map_or(0, |cursor| usize::from(cursor.position));
98    if start > rows.len() {
99        return Err(Error::InvalidCursor);
100    }
101    let capacity = page.map_or(rows.len(), |page| page.size);
102    let mut end = start;
103    let mut used = 0;
104    for (key, value) in rows.iter().skip(start).take(capacity) {
105        let size = key.len() + value.encoded_len();
106        if page.is_some() && size > bytes - used {
107            if end == start {
108                return Err(Error::RowTooLarge);
109            }
110            break; // Retry the unreturned group on the next page.
111        }
112        admit_output(size, bytes, &mut used)?;
113        end += 1;
114    }
115    let next = (end < rows.len()).then(|| GroupCursor {
116        handle: handle.clone(),
117        position: end as u8,
118    });
119    Ok((start..end, next, used))
120}