icydb_core/db/query/
read_intent.rs

1//! Module: query::read_intent
2//! Responsibility: hardcoded read-intent caps for public semantic terminals.
3//! Does not own: planner proof, executor routing, or public policy builders.
4//! Boundary: one internal authority for 0.198 engine-owned read-intent limits.
5
6use crate::db::query::admission::{
7    DEFAULT_BOUNDED_READ_MAX_ROWS, DEFAULT_BOUNDED_READ_RESPONSE_BYTES,
8};
9use candid::CandidType;
10use serde::Deserialize;
11
12pub(in crate::db::query) const PUBLIC_PAGE_DEFAULT_ROWS: u32 = DEFAULT_BOUNDED_READ_MAX_ROWS;
13pub(in crate::db::query) const PUBLIC_PAGE_MAX_ROWS: u32 = DEFAULT_BOUNDED_READ_MAX_ROWS;
14pub(in crate::db::query) const PUBLIC_PAGE_MAX_RESPONSE_BYTES: u32 =
15    DEFAULT_BOUNDED_READ_RESPONSE_BYTES;
16
17pub(in crate::db::query) const COMPLETE_SMALL_MAX_ROWS: u32 = DEFAULT_BOUNDED_READ_MAX_ROWS;
18pub(in crate::db::query) const COMPLETE_SMALL_LOOKAHEAD_ROWS: u32 = 1;
19pub(in crate::db::query) const COMPLETE_SMALL_EXECUTION_LIMIT: u32 =
20    COMPLETE_SMALL_MAX_ROWS + COMPLETE_SMALL_LOOKAHEAD_ROWS;
21pub(in crate::db::query) const ADMIN_BATCH_ROWS: u32 = DEFAULT_BOUNDED_READ_MAX_ROWS;
22
23/// Semantic read intent selected by a caller-facing terminal.
24///
25/// This is diagnostic metadata only. It does not grant access, choose planner
26/// routes, or configure admission policy.
27#[derive(CandidType, Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq)]
28pub enum ReadIntentKind {
29    /// No semantic read intent was attached to this diagnostic payload.
30    #[default]
31    Unspecified,
32
33    /// Low-level execution over the effective bounded row window.
34    BoundedRowWindow,
35
36    /// Boolean existence check.
37    ExistenceCheck,
38
39    /// Request-owned public cursor page.
40    PublicPage,
41
42    /// Complete small-set read that fails instead of silently truncating.
43    CompleteSmallSet,
44
45    /// Exact aggregate terminal such as count, sum, min, max, or average.
46    ExactAggregate,
47
48    /// Trusted/admin cursor batch with engine-owned batch size.
49    TrustedAdminBatch,
50}
51
52/// Internal public-page request shape.
53///
54/// The requested limit is a caller preference, not a custom policy. IcyDB
55/// clamps it to the engine-owned public page cap before admission/execution.
56#[derive(Clone, Debug, Default, Eq, PartialEq)]
57pub(in crate::db::query) struct PageRequest {
58    limit: Option<u32>,
59    cursor: Option<String>,
60}
61
62impl PageRequest {
63    /// Build a first-page request with one requested page size.
64    #[must_use]
65    pub(in crate::db::query) const fn first(limit: u32) -> Self {
66        Self {
67            limit: Some(limit),
68            cursor: None,
69        }
70    }
71
72    /// Build a continuation request with one requested page size and cursor.
73    #[must_use]
74    pub(in crate::db::query) fn next(limit: u32, cursor: impl Into<String>) -> Self {
75        Self {
76            limit: Some(limit),
77            cursor: Some(cursor.into()),
78        }
79    }
80
81    pub(in crate::db::query) const fn effective_limit(&self) -> u32 {
82        match self.limit {
83            Some(0) => 1,
84            Some(limit) if limit > PUBLIC_PAGE_MAX_ROWS => PUBLIC_PAGE_MAX_ROWS,
85            Some(limit) => limit,
86            None => PUBLIC_PAGE_DEFAULT_ROWS,
87        }
88    }
89
90    pub(in crate::db::query) fn into_cursor(self) -> Option<String> {
91        self.cursor
92    }
93}
94
95/// Request-owned trusted/admin batch continuation shape.
96///
97/// The batch size is engine-owned. Callers may only supply an opaque cursor
98/// for continuation, and the terminal remains gated to trusted read lanes.
99#[derive(Clone, Debug, Default, Eq, PartialEq)]
100pub struct AdminBatchRequest {
101    cursor: Option<String>,
102}
103
104impl AdminBatchRequest {
105    /// Build a first-batch request.
106    #[must_use]
107    pub const fn new() -> Self {
108        Self { cursor: None }
109    }
110
111    /// Build a continuation request with an opaque cursor.
112    #[must_use]
113    pub fn next(cursor: impl Into<String>) -> Self {
114        Self {
115            cursor: Some(cursor.into()),
116        }
117    }
118
119    /// Return this request with an opaque continuation cursor.
120    #[must_use]
121    pub fn with_cursor(mut self, cursor: impl Into<String>) -> Self {
122        self.cursor = Some(cursor.into());
123        self
124    }
125
126    /// Return the opaque continuation cursor, if supplied.
127    #[must_use]
128    pub fn cursor(&self) -> Option<&str> {
129        self.cursor.as_deref()
130    }
131
132    pub(in crate::db::query) fn into_cursor(self) -> Option<String> {
133        self.cursor
134    }
135}
icydb_core/db/query/read_intent.rs

icydb_core/db/query/
read_intent.rs
