Skip to main content

oxigeo_ws/
lib.rs

1//! OxiGeo WebSocket Streaming
2//!
3//! This crate provides WebSocket support for real-time geospatial data streaming.
4//!
5//! # Features
6//!
7//! - **WebSocket Server**: Axum-based WebSocket server with connection management
8//! - **WebSocket Client**: Async client with reconnection support
9//! - **Message Protocol**: Multiple formats (JSON, MessagePack, Binary) with compression
10//! - **Tile Streaming**: Real-time map tile delivery with delta encoding
11//! - **Feature Streaming**: GeoJSON feature updates with change detection
12//! - **Event Streaming**: System events, progress updates, and notifications
13//! - **Subscription Management**: Spatial, temporal, and attribute-based filtering
14//! - **Backpressure Control**: Automatic throttling and flow control
15//!
16//! # Examples
17//!
18//! ## Server
19//!
20//! ```rust,no_run
21//! use oxigeo_ws::server::WebSocketServer;
22//!
23//! #[tokio::main]
24//! async fn main() -> oxigeo_ws::error::Result<()> {
25//!     let server = WebSocketServer::builder()
26//!         .bind("0.0.0.0:9001")?
27//!         .max_connections(10000)
28//!         .build();
29//!
30//!     server.run().await?;
31//!     Ok(())
32//! }
33//! ```
34//!
35//! ## Client
36//!
37//! ```rust,no_run
38//! use oxigeo_ws::client::WebSocketClient;
39//!
40//! #[tokio::main]
41//! async fn main() -> oxigeo_ws::error::Result<()> {
42//!     let mut client = WebSocketClient::connect("ws://localhost:9001/ws").await?;
43//!
44//!     // Subscribe to tiles
45//!     let sub_id = client.subscribe_tiles(
46//!         [-122.5, 37.5, -122.0, 38.0],
47//!         10..14
48//!     ).await?;
49//!
50//!     // Get tile stream
51//!     let mut tiles = client.tile_stream();
52//!     while let Some(tile) = tiles.next_tile().await {
53//!         println!("Received tile: {:?}", tile.coords());
54//!     }
55//!
56//!     Ok(())
57//! }
58//! ```
59
60#![deny(missing_docs)]
61#![warn(clippy::unwrap_used)]
62
63pub mod auth;
64pub mod client;
65pub mod error;
66pub mod protocol;
67pub mod server;
68pub mod stream;
69pub mod subscription;
70
71/// WebSocket handlers
72pub mod handlers {
73    /// Event streaming handler
74    pub mod events;
75    /// Feature streaming handler
76    pub mod features;
77    /// Tile streaming handler
78    pub mod tiles;
79}
80
81// Re-export commonly used types
82pub use auth::{AuthConfig, AuthPrincipal, Role};
83pub use client::{ClientConfig, WebSocketClient};
84pub use error::{Error, Result};
85pub use protocol::{
86    ChangeType, Compression, EventType, Message, MessageFormat, SubscriptionFilter,
87};
88pub use server::{ServerConfig, WebSocketServer};
89pub use stream::{
90    BackpressureController, BackpressureState, DeltaEncoder, EventData, EventStream, FeatureData,
91    FeatureStream, MessageStream, TileData, TileStream,
92};
93pub use subscription::{Subscription, SubscriptionManager, SubscriptionType};
94
95/// Prelude module for convenient imports
96pub mod prelude {
97    pub use crate::client::{ClientConfig, WebSocketClient};
98    pub use crate::error::{Error, Result};
99    pub use crate::protocol::{
100        ChangeType, Compression, EventType, Message, MessageFormat, SubscriptionFilter,
101    };
102    pub use crate::server::{ServerConfig, WebSocketServer};
103    pub use crate::stream::{
104        BackpressureController, BackpressureState, DeltaEncoder, EventData, EventStream,
105        FeatureData, FeatureStream, MessageStream, TileData, TileStream,
106    };
107    pub use crate::subscription::{Subscription, SubscriptionManager, SubscriptionType};
108}
109
110#[cfg(test)]
111mod tests {
112    use super::*;
113
114    #[test]
115    fn test_exports() {
116        // Just verify that key types are exported
117        let _: Option<Error> = None;
118        let _: Option<Message> = None;
119    }
120}