sonos_stream/
lib.rs

1//! Internal implementation detail of [`sonos-sdk`](https://crates.io/crates/sonos-sdk). Not intended for direct use.
2//!
3//! # Sonos Stream - Event Streaming and Subscription Management
4//!
5//! This crate provides a modern event streaming and subscription management system for Sonos devices.
6//! It integrates with SonosClient's subscription lifecycle management, provides transparent event/polling
7//! fallback, and exposes events through an optimized iterator interface designed for state management.
8//!
9//! ## Key Features
10//!
11//! - **Transparent Event/Polling Switching**: Automatically switches between UPnP events and polling
12//!   based on firewall detection and event availability
13//! - **Proactive Firewall Detection**: Uses existing callback-server infrastructure to immediately
14//!   detect firewall blocking and start polling without delay
15//! - **Optimal State Management**: Provides both sync and async iterator interfaces, with sync being
16//!   best practice for local state management
17//! - **Changes Only Pattern**: Events contain only deltas, consumers handle initial state via queries
18//! - **Intelligent Fallback**: Automatically falls back to polling when events are unavailable
19//! - **Resource Efficient**: Shares HTTP clients and connection pools across operations
20//!
21//! ## Basic Usage
22//!
23//! ```rust,ignore
24//! use sonos_stream::{EventBroker, BrokerConfig, Service};
25//!
26//! let mut broker = EventBroker::new(BrokerConfig::default()).await?;
27//!
28//! // Register speakers with automatic duplicate protection
29//! let reg1 = broker.register_speaker_service("192.168.1.100".parse()?, Service::AVTransport).await?;
30//!
31//! // Process events with optimal sync iterator for state management
32//! let mut events = broker.event_iterator();
33//! for event in events.iter() {
34//!     // Handle events - transparent switching between UPnP events and polling
35//! }
36//! ```
37//!
38//! ## Architecture
39//!
40//! The crate is structured around several key components:
41//!
42//! - [`EventBroker`] - Main interface for registration and event streaming
43//! - [`registry`] - Speaker/service pair registration with duplicate protection
44//! - [`subscription`] - Integration with SonosClient's ManagedSubscription lifecycle
45//! - [`polling`] - Intelligent polling system with service-specific strategies
46//! - [`events`] - Event processing, enrichment, and iterator interfaces
47
48pub mod broker;
49pub mod config;
50pub mod error;
51pub mod events;
52pub mod polling;
53pub mod registry;
54pub mod subscription;
55
56// Re-export main types for easy access
57pub use broker::{EventBroker, PollingReason, RegistrationResult};
58pub use config::BrokerConfig;
59pub use error::{BrokerError, PollingError, RegistryError, SubscriptionError};
60pub use events::iterator::EventIterator;
61pub use events::types::{EnrichedEvent, EventData, EventSource};
62pub use registry::{RegistrationId, SpeakerServicePair};
63
64// Re-export types from dependencies that users commonly need
65pub use callback_server::firewall_detection::FirewallStatus;
66pub use sonos_api::Service;
67
68#[cfg(test)]
69mod tests {
70    use super::*;
71
72    #[test]
73    fn test_crate_exports() {
74        // Ensure all main types are properly exported
75        let _config = BrokerConfig::default();
76
77        // Test that we can create RegistrationId and SpeakerServicePair
78        let _reg_id = RegistrationId::new(1);
79        let _pair = SpeakerServicePair {
80            speaker_ip: "192.168.1.100".parse().unwrap(),
81            service: Service::AVTransport,
82        };
83    }
84}
sonos_stream/lib.rs

sonos_stream/
lib.rs
