agentic_reality/types/
topology.rs

1//! Topology awareness types — "What surrounds me?"
2
3use serde::{Deserialize, Serialize};
4use std::collections::HashMap;
5
6use super::ids::{DependencyId, IncarnationId, NeighborId, ObserverId, ServiceId};
7use super::resource::LatencyStats;
8
9/// Complete deployment topology map.
10#[derive(Debug, Clone, Serialize, Deserialize)]
11pub struct DeploymentTopologyMap {
12    pub self_position: TopologyPosition,
13    pub upstream: Vec<UpstreamEntity>,
14    pub downstream: Vec<DownstreamEntity>,
15    pub siblings: Vec<SiblingEntity>,
16    pub dependents: Vec<DependentEntity>,
17    pub observers: Vec<ObserverEntity>,
18    pub full_graph: Option<TopologyGraph>,
19    pub topology_health: TopologyHealth,
20}
21
22/// The agent's position in the topology.
23#[derive(Debug, Clone, Serialize, Deserialize)]
24pub struct TopologyPosition {
25    pub layer: StackLayer,
26    pub edge_distance: u32,
27    pub core_distance: u32,
28    pub criticality: f64,
29    pub redundancy: u32,
30}
31
32#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
33pub enum StackLayer {
34    Edge,
35    Gateway,
36    Application,
37    Service,
38    Data,
39    Infrastructure,
40}
41
42impl std::fmt::Display for StackLayer {
43    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
44        match self {
45            Self::Edge => write!(f, "edge"),
46            Self::Gateway => write!(f, "gateway"),
47            Self::Application => write!(f, "application"),
48            Self::Service => write!(f, "service"),
49            Self::Data => write!(f, "data"),
50            Self::Infrastructure => write!(f, "infrastructure"),
51        }
52    }
53}
54
55#[derive(Debug, Clone, Serialize, Deserialize)]
56pub struct UpstreamEntity {
57    pub id: ServiceId,
58    pub name: String,
59    pub health: HealthStatus,
60    pub latency: LatencyStats,
61    pub traffic_share: f64,
62}
63
64/// A downstream dependency.
65#[derive(Debug, Clone, Serialize, Deserialize)]
66pub struct DownstreamEntity {
67    pub id: DependencyId,
68    pub service: ServiceId,
69    pub entity_type: DownstreamType,
70    pub health: HealthStatus,
71    pub latency: LatencyStats,
72    pub criticality: DependencyCriticality,
73    pub fallback: Option<String>,
74    pub connection: ConnectionState,
75}
76
77#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
78pub enum DownstreamType {
79    Database,
80    Cache,
81    Queue,
82    Service,
83    ExternalApi,
84    Storage,
85    SearchIndex,
86    MlModel,
87}
88
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
90pub enum HealthStatus {
91    Healthy,
92    Degraded,
93    Unhealthy,
94    Unknown,
95}
96
97impl std::fmt::Display for HealthStatus {
98    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
99        match self {
100            Self::Healthy => write!(f, "healthy"),
101            Self::Degraded => write!(f, "degraded"),
102            Self::Unhealthy => write!(f, "unhealthy"),
103            Self::Unknown => write!(f, "unknown"),
104        }
105    }
106}
107
108#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
109pub enum DependencyCriticality {
110    Essential,
111    Important,
112    Useful,
113    Optional,
114}
115
116#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
117pub enum ConnectionState {
118    Connected,
119    Connecting,
120    Disconnected,
121    Failed,
122    CircuitOpen,
123}
124
125/// A sibling instance.
126#[derive(Debug, Clone, Serialize, Deserialize)]
127pub struct SiblingEntity {
128    pub incarnation: IncarnationId,
129    pub neighbor_id: NeighborId,
130    pub health: HealthStatus,
131    pub load: LoadLevel,
132    pub network_distance_ms: f64,
133    pub offload_capable: bool,
134    pub sync_status: SyncStatus,
135    pub last_contact: i64,
136}
137
138#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
139pub enum LoadLevel {
140    Idle,
141    Light,
142    Moderate,
143    Heavy,
144    Overloaded,
145}
146
147#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
148pub enum SyncStatus {
149    InSync,
150    Lagging,
151    Diverged,
152    Unknown,
153}
154
155/// An entity that depends on this agent.
156#[derive(Debug, Clone, Serialize, Deserialize)]
157pub struct DependentEntity {
158    pub id: ServiceId,
159    pub name: String,
160    pub criticality: DependencyCriticality,
161    pub last_request: Option<i64>,
162}
163
164/// An entity observing this agent.
165#[derive(Debug, Clone, Serialize, Deserialize)]
166pub struct ObserverEntity {
167    pub id: ObserverId,
168    pub observer_type: ObserverType,
169    pub observing: Vec<String>,
170    pub frequency_secs: u64,
171    pub healthy: bool,
172    pub trust: f64,
173}
174
175#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
176pub enum ObserverType {
177    Metrics,
178    Logging,
179    Tracing,
180    Apm,
181    Security,
182    Audit,
183    Custom,
184    Human,
185}
186
187/// Full topology graph (optional).
188#[derive(Debug, Clone, Serialize, Deserialize)]
189pub struct TopologyGraph {
190    pub nodes: Vec<TopologyNode>,
191    pub edges: Vec<TopologyEdge>,
192}
193
194#[derive(Debug, Clone, Serialize, Deserialize)]
195pub struct TopologyNode {
196    pub id: String,
197    pub name: String,
198    pub node_type: String,
199    pub health: HealthStatus,
200}
201
202#[derive(Debug, Clone, Serialize, Deserialize)]
203pub struct TopologyEdge {
204    pub from: String,
205    pub to: String,
206    pub edge_type: String,
207    pub weight: f64,
208}
209
210/// Health of the overall topology.
211#[derive(Debug, Clone, Serialize, Deserialize)]
212pub struct TopologyHealth {
213    pub score: f64,
214    pub weak_links: Vec<String>,
215    pub single_points_of_failure: Vec<String>,
216    pub redundancy_score: f64,
217}
218
219/// Service mesh perception.
220#[derive(Debug, Clone, Serialize, Deserialize)]
221pub struct ServiceMeshPerception {
222    pub visible_services: Vec<VisibleService>,
223    pub relationships: Vec<ServiceRelationship>,
224    pub mesh_health: MeshHealth,
225    pub traffic_patterns: Vec<TrafficPattern>,
226}
227
228#[derive(Debug, Clone, Serialize, Deserialize)]
229pub struct VisibleService {
230    pub id: ServiceId,
231    pub name: String,
232    pub version: String,
233    pub health: HealthStatus,
234    pub endpoints: Vec<String>,
235}
236
237#[derive(Debug, Clone, Serialize, Deserialize)]
238pub struct ServiceRelationship {
239    pub from: ServiceId,
240    pub to: ServiceId,
241    pub relationship_type: RelationshipType,
242    pub latency: LatencyStats,
243}
244
245#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
246pub enum RelationshipType {
247    Calls,
248    CalledBy,
249    Publishes,
250    Subscribes,
251    Replicates,
252    Caches,
253}
254
255#[derive(Debug, Clone, Serialize, Deserialize)]
256pub struct MeshHealth {
257    pub score: f64,
258    pub partitions: u32,
259    pub unhealthy_services: u32,
260}
261
262#[derive(Debug, Clone, Serialize, Deserialize)]
263pub struct TrafficPattern {
264    pub pattern_type: TrafficPatternType,
265    pub description: String,
266    pub confidence: f64,
267}
268
269#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
270pub enum TrafficPatternType {
271    Normal,
272    Spike,
273    Decline,
274    Oscillating,
275    Migrating,
276}
277
278/// Neighbor awareness.
279#[derive(Debug, Clone, Serialize, Deserialize)]
280pub struct NeighborAwareness {
281    pub neighbors: Vec<Neighbor>,
282    pub cooperation_opportunities: Vec<CooperationOpportunity>,
283}
284
285#[derive(Debug, Clone, Serialize, Deserialize)]
286pub struct Neighbor {
287    pub id: NeighborId,
288    pub name: String,
289    pub neighbor_type: NeighborType,
290    pub health: HealthStatus,
291    pub distance_ms: f64,
292    pub capabilities: Vec<String>,
293}
294
295#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
296pub enum NeighborType {
297    Replica,
298    Complementary,
299    Competing,
300    Supporting,
301    Monitoring,
302    Gateway,
303    Proxy,
304}
305
306#[derive(Debug, Clone, Serialize, Deserialize)]
307pub struct CooperationOpportunity {
308    pub with: NeighborId,
309    pub cooperation_type: CooperationType,
310    pub benefit: String,
311    pub feasibility: f64,
312}
313
314#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
315pub enum CooperationType {
316    LoadBalancing,
317    DataSharing,
318    Failover,
319    Pipeline,
320    Aggregation,
321    Consensus,
322}
323
324/// Dependency awareness.
325#[derive(Debug, Clone, Serialize, Deserialize)]
326pub struct DependencyAwareness {
327    pub tree: DependencyTree,
328    pub critical_path: Vec<DependencyId>,
329    pub health_summary: HashMap<DependencyId, HealthStatus>,
330}
331
332#[derive(Debug, Clone, Serialize, Deserialize)]
333pub struct DependencyTree {
334    pub root: DependencyId,
335    pub children: Vec<DependencyTree>,
336    pub service: ServiceId,
337    pub criticality: DependencyCriticality,
338}
agentic_reality/types/topology.rs

agentic_reality/types/
topology.rs
