Crate sonos_stream 

Internal implementation detail of sonos-sdk. Not intended for direct use.

Sonos Stream - Event Streaming and Subscription Management

This crate provides a modern event streaming and subscription management system for Sonos devices. It integrates with SonosClient’s subscription lifecycle management, provides transparent event/polling fallback, and exposes events through an optimized iterator interface designed for state management.

Key Features

• Transparent Event/Polling Switching: Automatically switches between UPnP events and polling based on firewall detection and event availability
• Proactive Firewall Detection: Uses existing callback-server infrastructure to immediately detect firewall blocking and start polling without delay
• Optimal State Management: Provides both sync and async iterator interfaces, with sync being best practice for local state management
• Changes Only Pattern: Events contain only deltas, consumers handle initial state via queries
• Intelligent Fallback: Automatically falls back to polling when events are unavailable
• Resource Efficient: Shares HTTP clients and connection pools across operations

Basic Usage

use sonos_stream::{EventBroker, BrokerConfig, Service};

let mut broker = EventBroker::new(BrokerConfig::default()).await?;

// Register speakers with automatic duplicate protection
let reg1 = broker.register_speaker_service("192.168.1.100".parse()?, Service::AVTransport).await?;

// Process events with optimal sync iterator for state management
let mut events = broker.event_iterator();
for event in events.iter() {
    // Handle events - transparent switching between UPnP events and polling
}

Architecture

The crate is structured around several key components:

• EventBroker - Main interface for registration and event streaming
• registry - Speaker/service pair registration with duplicate protection
• subscription - Integration with SonosClient’s ManagedSubscription lifecycle
• polling - Intelligent polling system with service-specific strategies
• events - Event processing, enrichment, and iterator interfaces

Re-exports

pub use broker::EventBroker;

pub use broker::PollingReason;

pub use broker::RegistrationResult;

pub use config::BrokerConfig;

pub use error::BrokerError;

pub use error::PollingError;

pub use error::RegistryError;

pub use error::SubscriptionError;

pub use events::iterator::EventIterator;

pub use events::types::EnrichedEvent;

pub use events::types::EventData;

pub use events::types::EventSource;

pub use registry::RegistrationId;

pub use registry::SpeakerServicePair;

Modules

broker

Main EventBroker implementation

config

Configuration types for the sonos-stream crate

error

Error types for the sonos-stream crate

events

Event processing and streaming

polling

Polling system for transparent event fallback

registry

Speaker and service registration with duplicate protection

subscription

Subscription management and event detection

Enums

FirewallStatus

Status of firewall detection for a device.

Service

Represents the different UPnP services exposed by Sonos devices