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::super::{
3    Completed, GroupCount, GroupValue, Groups, MAX_GROUPS, admit_output, decode_group_count,
4    decode_group_value,
5};
6use super::{JobHandle, JobOutcome, storage::Record};
7use crate::{Error, Value};
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    /// Decode bounded framing; resume also checks the live job and result bounds.
36    /// # Errors
37    /// Refuses unsupported versions, malformed handles or positions outside 1..=32.
38    pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
39        if bytes.len() != 28 || bytes[0] != 1 || !(1..=MAX_GROUPS as u8).contains(&bytes[27]) {
40            return Err(Error::InvalidCursor);
41        }
42        Ok(Self {
43            handle: JobHandle::from_bytes(&bytes[1..27]).map_err(|_| Error::InvalidCursor)?,
44            position: bytes[27],
45        })
46    }
47}
48
49#[derive(Clone, Copy)]
50pub(in crate::store::query::aggregate) struct PageRequest<'a> {
51    pub size: usize,
52    pub after: Option<&'a GroupCursor>,
53}
54
55pub(super) fn admit(
56    page: Option<PageRequest<'_>>,
57    handle: &JobHandle,
58    record: &Record,
59) -> Result<(), Error> {
60    if let Some(cursor) = page.and_then(|page| page.after)
61        && (cursor.handle != *handle
62            || !matches!(record.phase, JobOutcome::Complete(()) | JobOutcome::Expired))
63    {
64        return Err(Error::InvalidCursor);
65    }
66    Ok(())
67}
68
69pub(super) fn count_page<K: Value>(
70    groups: Groups,
71    limit: usize,
72    bytes: usize,
73    page: Option<PageRequest<'_>>,
74    handle: &JobHandle,
75) -> Result<(GroupPage<GroupCount<K>>, usize), Error> {
76    let (raw, bytes) = select(groups, limit, bytes, page, handle)?;
77    Ok((
78        GroupPage {
79            rows: raw
80                .rows
81                .into_iter()
82                .map(|(key, value)| decode_group_count(&key, value))
83                .collect::<Result<_, _>>()?,
84            next: raw.next,
85        },
86        bytes,
87    ))
88}
89
90pub(super) fn value_page<K: Value, R: Value>(
91    groups: Groups,
92    limit: usize,
93    bytes: usize,
94    page: Option<PageRequest<'_>>,
95    handle: &JobHandle,
96) -> Result<(GroupPage<GroupValue<K, R>>, usize), Error> {
97    let (raw, bytes) = select(groups, limit, bytes, page, handle)?;
98    Ok((
99        GroupPage {
100            rows: raw
101                .rows
102                .into_iter()
103                .map(|(key, value)| decode_group_value(&key, value))
104                .collect::<Result<_, _>>()?,
105            next: raw.next,
106        },
107        bytes,
108    ))
109}
110
111// Finalize every group before selection; even an excluded overflow must refuse.
112// Recomputing at most 32 completed values avoids a durable output cache or cursor.
113type EncodedPage = GroupPage<(Vec<u8>, Completed)>;
114fn select(
115    groups: Groups,
116    limit: usize,
117    bytes: usize,
118    page: Option<PageRequest<'_>>,
119    handle: &JobHandle,
120) -> Result<(EncodedPage, usize), Error> {
121    let mut rows = groups.into_output()?;
122    rows.truncate(limit);
123    let start = page
124        .and_then(|page| page.after)
125        .map_or(0, |cursor| usize::from(cursor.position));
126    if start > rows.len() {
127        return Err(Error::InvalidCursor);
128    }
129    let capacity = page.map_or(limit, |page| page.size);
130    let mut end = start;
131    let mut used = 0;
132    for (key, value) in rows.iter().skip(start).take(capacity) {
133        let size = key.len() + value.encoded_len();
134        if page.is_some() && size > bytes - used {
135            if end == start {
136                return Err(Error::RowTooLarge);
137            }
138            break; // Retry the unreturned group on the next page.
139        }
140        admit_output(size, bytes, &mut used)?;
141        end += 1;
142    }
143    let next = (end < rows.len()).then(|| GroupCursor {
144        handle: handle.clone(),
145        position: end as u8,
146    });
147    let selected = rows.drain(start..end).collect();
148    Ok((
149        GroupPage {
150            rows: selected,
151            next,
152        },
153        used,
154    ))
155}