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