icydb_core/db/response/
paged.rs

1//! Module: response::paged
2//! Responsibility: paged load response payload contracts.
3//! Does not own: query execution, pagination planning, or cursor token protocol.
4//! Boundary: response DTOs returned by session/query execution APIs.
5
6use crate::{
7    db::{
8        diagnostics::{ExecutionMetrics, ExecutionTrace},
9        response::{EntityResponse, Row},
10    },
11    traits::EntityKind,
12};
13
14///
15/// PagedLoadExecution
16///
17/// Cursor-paged load response with optional continuation cursor bytes.
18///
19
20#[derive(Debug)]
21pub struct PagedLoadExecution<E: EntityKind> {
22    response: EntityResponse<E>,
23    continuation_cursor: Option<Vec<u8>>,
24}
25
26impl<E: EntityKind> PagedLoadExecution<E> {
27    /// Borrow the paged response rows.
28    #[must_use]
29    pub const fn response(&self) -> &EntityResponse<E> {
30        &self.response
31    }
32
33    /// Borrow an iterator over paged rows in response order.
34    pub fn iter(&self) -> std::slice::Iter<'_, Row<E>> {
35        self.response.iter()
36    }
37
38    /// Borrow the optional continuation cursor bytes.
39    #[must_use]
40    pub fn continuation_cursor(&self) -> Option<&[u8]> {
41        self.continuation_cursor.as_deref()
42    }
43
44    /// Consume this payload and return response rows plus continuation cursor.
45    #[must_use]
46    pub fn into_response_and_cursor(self) -> (EntityResponse<E>, Option<Vec<u8>>) {
47        (self.response, self.continuation_cursor)
48    }
49}
50
51impl<'a, E: EntityKind> IntoIterator for &'a PagedLoadExecution<E> {
52    type Item = &'a Row<E>;
53    type IntoIter = std::slice::Iter<'a, Row<E>>;
54
55    fn into_iter(self) -> Self::IntoIter {
56        self.iter()
57    }
58}
59
60///
61/// PagedLoadExecutionWithTrace
62///
63/// Cursor-paged load response plus optional execution trace details.
64///
65
66#[derive(Debug)]
67pub struct PagedLoadExecutionWithTrace<E: EntityKind> {
68    response: EntityResponse<E>,
69    continuation_cursor: Option<Vec<u8>>,
70    execution_trace: Option<ExecutionTrace>,
71}
72
73impl<E: EntityKind> PagedLoadExecutionWithTrace<E> {
74    /// Create a traced paged load execution payload.
75    #[must_use]
76    pub const fn new(
77        response: EntityResponse<E>,
78        continuation_cursor: Option<Vec<u8>>,
79        execution_trace: Option<ExecutionTrace>,
80    ) -> Self {
81        Self {
82            response,
83            continuation_cursor,
84            execution_trace,
85        }
86    }
87
88    /// Borrow the paged response rows.
89    #[must_use]
90    pub const fn response(&self) -> &EntityResponse<E> {
91        &self.response
92    }
93
94    /// Borrow an iterator over paged rows in response order.
95    pub fn iter(&self) -> std::slice::Iter<'_, Row<E>> {
96        self.response.iter()
97    }
98
99    /// Borrow the optional continuation cursor bytes.
100    #[must_use]
101    pub fn continuation_cursor(&self) -> Option<&[u8]> {
102        self.continuation_cursor.as_deref()
103    }
104
105    /// Borrow optional execution trace details.
106    #[must_use]
107    pub const fn execution_trace(&self) -> Option<&ExecutionTrace> {
108        self.execution_trace.as_ref()
109    }
110
111    /// Borrow compact execution metrics derived from the optional execution trace.
112    #[must_use]
113    pub fn execution_metrics(&self) -> Option<ExecutionMetrics> {
114        self.execution_trace.as_ref().map(ExecutionTrace::metrics)
115    }
116
117    /// Consume this payload and drop trace details.
118    #[must_use]
119    pub fn into_execution(self) -> PagedLoadExecution<E> {
120        PagedLoadExecution {
121            response: self.response,
122            continuation_cursor: self.continuation_cursor,
123        }
124    }
125
126    /// Consume this payload and return response rows, continuation cursor, and trace.
127    #[must_use]
128    pub fn into_response_cursor_and_trace(
129        self,
130    ) -> (EntityResponse<E>, Option<Vec<u8>>, Option<ExecutionTrace>) {
131        (
132            self.response,
133            self.continuation_cursor,
134            self.execution_trace,
135        )
136    }
137}
138
139impl<'a, E: EntityKind> IntoIterator for &'a PagedLoadExecutionWithTrace<E> {
140    type Item = &'a Row<E>;
141    type IntoIter = std::slice::Iter<'a, Row<E>>;
142
143    fn into_iter(self) -> Self::IntoIter {
144        self.iter()
145    }
146}
icydb_core/db/response/paged.rs

icydb_core/db/response/
paged.rs
