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    /// Create a paged load execution payload.
28    #[must_use]
29    pub const fn new(response: EntityResponse<E>, continuation_cursor: Option<Vec<u8>>) -> Self {
30        Self {
31            response,
32            continuation_cursor,
33        }
34    }
35
36    /// Borrow the paged response rows.
37    #[must_use]
38    pub const fn response(&self) -> &EntityResponse<E> {
39        &self.response
40    }
41
42    /// Borrow an iterator over paged rows in response order.
43    pub fn iter(&self) -> std::slice::Iter<'_, Row<E>> {
44        self.response.iter()
45    }
46
47    /// Borrow the optional continuation cursor bytes.
48    #[must_use]
49    pub fn continuation_cursor(&self) -> Option<&[u8]> {
50        self.continuation_cursor.as_deref()
51    }
52
53    /// Consume this payload and return `(response, continuation_cursor)`.
54    #[must_use]
55    pub fn into_parts(self) -> (EntityResponse<E>, Option<Vec<u8>>) {
56        (self.response, self.continuation_cursor)
57    }
58}
59
60impl<'a, E: EntityKind> IntoIterator for &'a PagedLoadExecution<E> {
61    type Item = &'a Row<E>;
62    type IntoIter = std::slice::Iter<'a, Row<E>>;
63
64    fn into_iter(self) -> Self::IntoIter {
65        self.iter()
66    }
67}
68
69///
70/// PagedLoadExecutionWithTrace
71///
72/// Cursor-paged load response plus optional execution trace details.
73///
74
75#[derive(Debug)]
76pub struct PagedLoadExecutionWithTrace<E: EntityKind> {
77    response: EntityResponse<E>,
78    continuation_cursor: Option<Vec<u8>>,
79    execution_trace: Option<ExecutionTrace>,
80}
81
82impl<E: EntityKind> PagedLoadExecutionWithTrace<E> {
83    /// Create a traced paged load execution payload.
84    #[must_use]
85    pub const fn new(
86        response: EntityResponse<E>,
87        continuation_cursor: Option<Vec<u8>>,
88        execution_trace: Option<ExecutionTrace>,
89    ) -> Self {
90        Self {
91            response,
92            continuation_cursor,
93            execution_trace,
94        }
95    }
96
97    /// Borrow the paged response rows.
98    #[must_use]
99    pub const fn response(&self) -> &EntityResponse<E> {
100        &self.response
101    }
102
103    /// Borrow an iterator over paged rows in response order.
104    pub fn iter(&self) -> std::slice::Iter<'_, Row<E>> {
105        self.response.iter()
106    }
107
108    /// Borrow the optional continuation cursor bytes.
109    #[must_use]
110    pub fn continuation_cursor(&self) -> Option<&[u8]> {
111        self.continuation_cursor.as_deref()
112    }
113
114    /// Borrow optional execution trace details.
115    #[must_use]
116    pub const fn execution_trace(&self) -> Option<&ExecutionTrace> {
117        self.execution_trace.as_ref()
118    }
119
120    /// Borrow compact execution metrics derived from the optional execution trace.
121    #[must_use]
122    pub fn execution_metrics(&self) -> Option<ExecutionMetrics> {
123        self.execution_trace.as_ref().map(ExecutionTrace::metrics)
124    }
125
126    /// Consume this payload and drop trace details.
127    #[must_use]
128    pub fn into_execution(self) -> PagedLoadExecution<E> {
129        PagedLoadExecution {
130            response: self.response,
131            continuation_cursor: self.continuation_cursor,
132        }
133    }
134
135    /// Consume this payload and return `(response, continuation_cursor, trace)`.
136    #[must_use]
137    pub fn into_parts(self) -> (EntityResponse<E>, Option<Vec<u8>>, Option<ExecutionTrace>) {
138        (
139            self.response,
140            self.continuation_cursor,
141            self.execution_trace,
142        )
143    }
144}
145
146impl<'a, E: EntityKind> IntoIterator for &'a PagedLoadExecutionWithTrace<E> {
147    type Item = &'a Row<E>;
148    type IntoIter = std::slice::Iter<'a, Row<E>>;
149
150    fn into_iter(self) -> Self::IntoIter {
151        self.iter()
152    }
153}
icydb_core/db/response/paged.rs

icydb_core/db/response/
paged.rs
