velesdb_server/handlers/graph/
types.rs

1//! Graph types for VelesDB REST API.
2//!
3//! Contains request/response types for graph operations.
4
5use serde::{Deserialize, Serialize};
6use utoipa::{IntoParams, ToSchema};
7
8/// A single traversal result item.
9#[derive(Debug, Clone, Serialize, ToSchema)]
10pub struct TraversalResultItem {
11    /// Target node ID reached.
12    pub target_id: u64,
13    /// Depth of traversal (number of hops from source).
14    pub depth: u32,
15    /// Path taken (list of edge IDs).
16    pub path: Vec<u64>,
17}
18
19/// Query parameters for edge operations.
20#[derive(Debug, Deserialize, IntoParams)]
21pub struct EdgeQueryParams {
22    /// Filter edges by label (e.g., "KNOWS", "FOLLOWS").
23    #[param(example = "KNOWS")]
24    pub label: Option<String>,
25}
26
27/// Request for graph traversal.
28#[derive(Debug, Deserialize, ToSchema)]
29pub struct TraverseRequest {
30    /// Source node ID to start traversal from.
31    pub source: u64,
32    /// Traversal strategy: "bfs" or "dfs".
33    #[serde(default = "default_strategy")]
34    pub strategy: String,
35    /// Maximum traversal depth.
36    #[serde(default = "default_max_depth")]
37    pub max_depth: u32,
38    /// Maximum number of results to return.
39    #[serde(default = "default_limit")]
40    pub limit: usize,
41    /// Optional cursor for pagination (not implemented yet).
42    pub cursor: Option<String>,
43    /// Filter by relationship types (empty = all types).
44    #[serde(default)]
45    pub rel_types: Vec<String>,
46}
47
48fn default_strategy() -> String {
49    "bfs".to_string()
50}
51
52fn default_max_depth() -> u32 {
53    3
54}
55
56fn default_limit() -> usize {
57    100
58}
59
60/// Response from graph traversal.
61#[derive(Debug, Serialize, ToSchema)]
62pub struct TraverseResponse {
63    /// List of traversal results.
64    pub results: Vec<TraversalResultItem>,
65    /// Cursor for next page (if applicable).
66    pub next_cursor: Option<String>,
67    /// Whether more results are available.
68    pub has_more: bool,
69    /// Traversal statistics.
70    pub stats: TraversalStats,
71}
72
73/// Statistics from traversal operation.
74#[derive(Debug, Serialize, ToSchema)]
75pub struct TraversalStats {
76    /// Number of nodes visited.
77    pub visited: usize,
78    /// Maximum depth reached.
79    pub depth_reached: u32,
80}
81
82/// Response for node degree query.
83#[derive(Debug, Serialize, ToSchema)]
84pub struct DegreeResponse {
85    /// Number of incoming edges.
86    pub in_degree: usize,
87    /// Number of outgoing edges.
88    pub out_degree: usize,
89}
90
91/// Response containing edges.
92#[derive(Debug, Serialize, ToSchema)]
93pub struct EdgesResponse {
94    /// List of edges.
95    pub edges: Vec<EdgeResponse>,
96    /// Total count of edges returned.
97    pub count: usize,
98}
99
100/// A single edge in the response.
101#[derive(Debug, Serialize, ToSchema)]
102pub struct EdgeResponse {
103    /// Edge ID.
104    pub id: u64,
105    /// Source node ID.
106    pub source: u64,
107    /// Target node ID.
108    pub target: u64,
109    /// Edge label (relationship type).
110    pub label: String,
111    /// Edge properties.
112    pub properties: serde_json::Value,
113}
114
115/// Request to add an edge to the graph.
116#[derive(Debug, Deserialize, ToSchema)]
117pub struct AddEdgeRequest {
118    /// Edge ID.
119    pub id: u64,
120    /// Source node ID.
121    pub source: u64,
122    /// Target node ID.
123    pub target: u64,
124    /// Edge label (relationship type).
125    pub label: String,
126    /// Edge properties.
127    #[serde(default)]
128    pub properties: serde_json::Value,
129}
130
131// ============================================================================
132// SSE Streaming Types (EPIC-058 US-003)
133// ============================================================================
134
135/// Query parameters for streaming graph traversal.
136#[derive(Debug, Deserialize, IntoParams)]
137pub struct StreamTraverseParams {
138    /// Source node ID to start traversal from.
139    #[param(example = 123)]
140    pub start_node: u64,
141    /// Traversal algorithm: "bfs" or "dfs".
142    #[serde(default = "default_algorithm")]
143    #[param(example = "bfs")]
144    pub algorithm: String,
145    /// Maximum traversal depth.
146    #[serde(default = "default_stream_max_depth")]
147    #[param(example = 5)]
148    pub max_depth: u32,
149    /// Maximum number of results to stream.
150    #[serde(default = "default_stream_limit")]
151    #[param(example = 1000)]
152    pub limit: usize,
153    /// Filter by relationship types (comma-separated).
154    #[serde(default)]
155    #[param(example = "KNOWS,FOLLOWS")]
156    pub relationship_types: Option<String>,
157}
158
159fn default_algorithm() -> String {
160    "bfs".to_string()
161}
162
163fn default_stream_max_depth() -> u32 {
164    5
165}
166
167fn default_stream_limit() -> usize {
168    1000
169}
170
171/// SSE event: A node reached during traversal.
172#[derive(Debug, Serialize, ToSchema)]
173pub struct StreamNodeEvent {
174    /// Target node ID.
175    pub id: u64,
176    /// Depth from source.
177    pub depth: u32,
178    /// Path of edge IDs taken to reach this node.
179    pub path: Vec<u64>,
180}
181
182/// SSE event: Periodic statistics update.
183#[derive(Debug, Serialize, ToSchema)]
184pub struct StreamStatsEvent {
185    /// Number of nodes visited so far.
186    pub nodes_visited: usize,
187    /// Elapsed time in milliseconds.
188    pub elapsed_ms: u64,
189}
190
191/// SSE event: Traversal completed.
192#[derive(Debug, Serialize, ToSchema)]
193pub struct StreamDoneEvent {
194    /// Total nodes returned.
195    pub total_nodes: usize,
196    /// Maximum depth reached.
197    pub max_depth_reached: u32,
198    /// Total elapsed time in milliseconds.
199    pub elapsed_ms: u64,
200}
201
202/// SSE event: Error occurred.
203#[derive(Debug, Serialize, ToSchema)]
204pub struct StreamErrorEvent {
205    /// Error message.
206    pub error: String,
207}
velesdb_server/handlers/graph/types.rs

velesdb_server/handlers/graph/
types.rs
