phytrace_sdk/
lib.rs

1//! # PhyTrace SDK for Rust
2//!
3//! The PhyTrace SDK provides a comprehensive toolkit for integrating autonomous systems
4//! with the PhyWare data platform. It enables robots, autonomous vehicles, and other
5//! autonomous systems to capture telemetry data, normalize it to the PhyTrace Unified
6//! Data Model (UDM), and stream it to PhyCloud endpoints in real-time.
7//!
8//! ## Features
9//!
10//! - **UDM Models**: Strongly-typed Rust structs for all 23 UDM domains
11//! - **Event Builder**: Fluent API for constructing UDM events
12//! - **Validation**: Schema and business rule validation at the source
13//! - **Provenance**: Cryptographic signing and chain-of-custody tracking
14//! - **Transport**: HTTP (default), with gRPC/MQTT/WebSocket stubs for future
15//! - **Reliability**: Edge buffering, retry with backoff, circuit breaker, batching
16//! - **Agent**: High-level orchestrator for production deployments
17//!
18//! ## Quick Start
19//!
20//! ```rust,no_run
21//! use phytrace_sdk::{
22//!     UdmEvent, SourceType, EventType,
23//!     models::domains::{LocationDomain, MotionDomain},
24//! };
25//!
26//! fn main() -> Result<(), Box<dyn std::error::Error>> {
27//!     // Build a UDM event using the fluent API
28//!     let event = UdmEvent::new(SourceType::Amr)
29//!         .with_event_type(EventType::TelemetryPeriodic)
30//!         .with_location(LocationDomain {
31//!             latitude: Some(41.8781),
32//!             longitude: Some(-87.6298),
33//!             heading_deg: Some(45.0),
34//!             ..Default::default()
35//!         })
36//!         .with_motion(MotionDomain {
37//!             speed_mps: Some(1.2),
38//!             ..Default::default()
39//!         });
40//!
41//!     println!("Event ID: {}", event.event_id);
42//!     Ok(())
43//! }
44//! ```
45//!
46//! ## Feature Flags
47//!
48//! - `http` (default): Enables HTTP transport via `reqwest`
49//! - `grpc`: Enables gRPC transport (future)
50//! - `mqtt`: Enables MQTT transport (future)
51//! - `websocket`: Enables WebSocket transport (future)
52//!
53//! ## Architecture
54//!
55//! ```text
56//! ┌─────────────────────────────────────────────────────────────────┐
57//! │                      PhyTrace SDK (Rust)                        │
58//! │                                                                 │
59//! │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
60//! │  │   Models    │  │    Core     │  │  Transport  │              │
61//! │  │  (UDM)      │→ │  (Builder,  │→ │  (HTTP,     │              │
62//! │  │             │  │  Validate)  │  │   Mock)     │              │
63//! │  └─────────────┘  └─────────────┘  └─────────────┘              │
64//! │         │                │                │                     │
65//! │         └────────────────┼────────────────┘                     │
66//! │                          ↓                                      │
67//! │  ┌─────────────────────────────────────────────────────────┐    │
68//! │  │                    Reliability                          │    │
69//! │  │  (Buffer, Retry, Circuit Breaker, Batch)                │    │
70//! │  └─────────────────────────────────────────────────────────┘    │
71//! │                          ↓                                      │
72//! │  ┌─────────────────────────────────────────────────────────┐    │
73//! │  │                  PhyTraceAgent                          │    │
74//! │  │  (Orchestration, Config, Lifecycle)                     │    │
75//! │  └─────────────────────────────────────────────────────────┘    │
76//! └─────────────────────────────────────────────────────────────────┘
77//! ```
78
79#![warn(missing_docs)]
80#![warn(rustdoc::missing_crate_level_docs)]
81#![cfg_attr(docsrs, feature(doc_cfg))]
82
83// Public modules
84pub mod agent;
85pub mod core;
86pub mod emitters;
87pub mod error;
88pub mod models;
89pub mod reliability;
90pub mod transport;
91
92#[cfg(feature = "ffi")]
93pub mod ffi;
94
95// Re-exports for convenience
96pub use agent::PhyTraceAgent;
97pub use core::builder::EventBuilder;
98pub use core::config::PhyTraceConfig;
99pub use core::provenance::ProvenanceSigner;
100pub use core::validation::{validate_event, ValidationLevel, Validator};
101pub use emitters::periodic::PeriodicEmitter;
102pub use error::{PhyTraceError, PhyTraceResult};
103pub use models::enums::{EventType, OperationalMode, OperationalState, SafetyState, SourceType};
104pub use models::event::{Provenance, UdmEvent};
105pub use reliability::batch::BatchProcessor;
106pub use reliability::buffer::FileBuffer;
107pub use reliability::retry::RetryHandler;
108#[cfg(feature = "http")]
109pub use transport::http::HttpTransport;
110pub use transport::mock::MockTransport;
111pub use transport::traits::{BatchResult, SendResult, Transport, TransportStats};
112
113/// SDK version string
114pub const SDK_VERSION: &str = env!("CARGO_PKG_VERSION");
115
116/// UDM schema version supported by this SDK
117pub const UDM_VERSION: &str = "0.0.3";
phytrace_sdk/lib.rs

phytrace_sdk/
lib.rs
