pjson_rs/application/queries/mod.rs
1//! Queries - Read operations that don't change system state
2
3use crate::application::dto::{PriorityDto, SessionIdDto, StreamIdDto};
4use crate::domain::{
5 SessionState,
6 aggregates::{
7 StreamSession,
8 stream_session::{SessionHealth, SessionStats},
9 },
10 entities::{Frame, Stream},
11};
12use chrono::{DateTime, Utc};
13use serde::{Deserialize, Serialize};
14
15/// Get session information by ID
16#[derive(Debug, Clone, Serialize, Deserialize)]
17pub struct GetSessionQuery {
18 /// Identifier of the session to retrieve.
19 pub session_id: SessionIdDto,
20}
21
22/// Get all active sessions
23#[derive(Debug, Clone, Serialize, Deserialize)]
24pub struct GetActiveSessionsQuery {
25 /// Maximum number of sessions to return.
26 pub limit: Option<usize>,
27 /// Number of sessions to skip before returning results.
28 pub offset: Option<usize>,
29}
30
31/// Get stream information by ID
32#[derive(Debug, Clone, Serialize, Deserialize)]
33pub struct GetStreamQuery {
34 /// Identifier of the parent session.
35 pub session_id: SessionIdDto,
36 /// Identifier of the stream to retrieve.
37 pub stream_id: StreamIdDto,
38}
39
40/// Get all streams for a session
41#[derive(Debug, Clone, Serialize, Deserialize)]
42pub struct GetStreamsForSessionQuery {
43 /// Identifier of the parent session.
44 pub session_id: SessionIdDto,
45 /// When `true`, includes streams that are no longer active.
46 pub include_inactive: bool,
47}
48
49/// Get session health status
50#[derive(Debug, Clone, Serialize, Deserialize)]
51pub struct GetSessionHealthQuery {
52 /// Identifier of the session whose health is being queried.
53 pub session_id: SessionIdDto,
54}
55
56/// Get frames for a stream with filtering
57#[derive(Debug, Clone, Serialize, Deserialize)]
58pub struct GetStreamFramesQuery {
59 /// Identifier of the parent session.
60 pub session_id: SessionIdDto,
61 /// Identifier of the stream whose frames are being queried.
62 pub stream_id: StreamIdDto,
63 /// Return only frames whose sequence number is greater than this value.
64 pub since_sequence: Option<u64>,
65 /// Return only frames whose priority satisfies this filter.
66 pub priority_filter: Option<PriorityDto>,
67 /// Maximum number of frames to return.
68 pub limit: Option<usize>,
69}
70
71/// Get session statistics and metrics
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct GetSessionStatsQuery {
74 /// Identifier of the session whose statistics are being queried.
75 pub session_id: SessionIdDto,
76}
77
78/// Get system-wide statistics
79#[derive(Debug, Clone, Serialize, Deserialize)]
80pub struct GetSystemStatsQuery {
81 /// When `true`, includes historical (closed) sessions in aggregates.
82 pub include_historical: bool,
83}
84
85/// Search sessions by criteria
86#[derive(Debug, Clone, Serialize, Deserialize)]
87pub struct SearchSessionsQuery {
88 /// Filters that returned sessions must satisfy.
89 pub filters: SessionFilters,
90 /// Field to order results by.
91 pub sort_by: Option<SessionSortField>,
92 /// Direction of the sort applied to `sort_by`.
93 pub sort_order: Option<SortOrder>,
94 /// Maximum number of sessions to return.
95 pub limit: Option<usize>,
96 /// Number of sessions to skip before returning results.
97 pub offset: Option<usize>,
98}
99
100/// Session filtering criteria
101#[derive(Debug, Clone, Serialize, Deserialize, Default)]
102pub struct SessionFilters {
103 /// Match sessions whose state equals this value exactly (case-sensitive, no
104 /// substring matching — e.g. `SessionState::Active`, not `"active"` or `"activ"`).
105 /// Accepted spellings are exactly [`SessionState`]'s serialized variant names:
106 /// `Initializing`, `Active`, `Closing`, `Completed`, `Failed`.
107 pub state: Option<SessionState>,
108 /// Match sessions created at or after this timestamp.
109 pub created_after: Option<DateTime<Utc>>,
110 /// Match sessions created at or before this timestamp.
111 pub created_before: Option<DateTime<Utc>>,
112 /// Match sessions whose client info contains this string.
113 pub client_info: Option<String>,
114 /// Match sessions that currently have (or do not have) active streams.
115 pub has_active_streams: Option<bool>,
116}
117
118/// Fields to sort sessions by.
119///
120/// Re-exported from the domain layer: [`SessionPagination`](crate::domain::ports::SessionPagination)
121/// consumes the same type directly, so a query's `sort_by` needs no conversion
122/// before reaching the repository port.
123pub use crate::domain::ports::SessionSortField;
124
125/// Sort order
126///
127/// Deserializes from its canonical `snake_case` spelling (`ascending`/`descending`) plus
128/// the short `asc`/`desc` aliases accepted by the HTTP `sort_order` query parameter; only
129/// deserialization accepts the aliases — serialized output is always the canonical form.
130#[derive(Debug, Clone, Serialize, Deserialize)]
131#[serde(rename_all = "snake_case")]
132pub enum SortOrder {
133 /// Ascending order (smallest first).
134 #[serde(alias = "asc")]
135 Ascending,
136 /// Descending order (largest first).
137 #[serde(alias = "desc")]
138 Descending,
139}
140
141/// Query response types
142/// Response for session queries
143#[derive(Debug, Clone, Serialize, Deserialize)]
144pub struct SessionResponse {
145 /// The retrieved session aggregate.
146 pub session: StreamSession,
147}
148
149/// Response for multiple sessions queries
150#[derive(Debug, Clone, Serialize, Deserialize)]
151pub struct SessionsResponse {
152 /// Sessions returned in this page.
153 pub sessions: Vec<StreamSession>,
154 /// Total number of sessions matching the query, ignoring pagination.
155 pub total_count: usize,
156 /// Whether more sessions exist beyond this page.
157 pub has_more: bool,
158}
159
160/// Response for stream queries
161#[derive(Debug, Clone, Serialize, Deserialize)]
162pub struct StreamResponse {
163 /// The retrieved stream entity.
164 pub stream: Stream,
165}
166
167/// Response for multiple streams queries
168#[derive(Debug, Clone, Serialize, Deserialize)]
169pub struct StreamsResponse {
170 /// Streams returned by the query.
171 pub streams: Vec<Stream>,
172}
173
174/// Response for frame queries
175#[derive(Debug, Clone, Serialize, Deserialize)]
176pub struct FramesResponse {
177 /// Frames returned in this page.
178 pub frames: Vec<Frame>,
179 /// Total number of frames matching the query, ignoring pagination.
180 pub total_count: usize,
181}
182
183/// Response for health queries
184#[derive(Debug, Clone, Serialize, Deserialize)]
185pub struct HealthResponse {
186 /// Health snapshot of the session.
187 pub health: SessionHealth,
188}
189
190/// Response for session stats queries
191#[derive(Debug, Clone, Serialize, Deserialize)]
192pub struct SessionStatsResponse {
193 /// Identifier of the session whose statistics are reported.
194 pub session_id: SessionIdDto,
195 /// Aggregate domain statistics for the session.
196 pub stats: SessionStats,
197 /// Number of streams currently attached to the session.
198 pub stream_count: usize,
199 /// Number of streams currently in an active state.
200 pub active_stream_count: usize,
201 /// Timestamp when the session was created.
202 pub created_at: DateTime<Utc>,
203 /// Timestamp when the session was last updated.
204 pub updated_at: DateTime<Utc>,
205 /// Duration in milliseconds since session creation, or `None` if not yet completed.
206 pub duration_ms: Option<i64>,
207}
208
209/// System statistics response
210#[derive(Debug, Clone, Serialize, Deserialize)]
211pub struct SystemStatsResponse {
212 /// Total number of sessions ever created.
213 pub total_sessions: u64,
214 /// Number of sessions currently active.
215 pub active_sessions: u64,
216 /// Total number of streams ever created.
217 pub total_streams: u64,
218 /// Number of streams currently active.
219 pub active_streams: u64,
220 /// Total number of frames ever emitted.
221 pub total_frames: u64,
222 /// Total number of payload bytes ever emitted.
223 pub total_bytes: u64,
224 /// Average session lifetime in seconds across completed sessions.
225 pub average_session_duration_seconds: f64,
226 /// Throughput in frames emitted per second across the system.
227 pub frames_per_second: f64,
228 /// Throughput in payload bytes emitted per second across the system.
229 pub bytes_per_second: f64,
230 /// Number of seconds the system has been running.
231 pub uptime_seconds: u64,
232}