arcly-stream 0.1.0

//! Telemetry hook — the injected replacement for `stream-center`'s global
//! Prometheus singleton (`sc_metrics::Metrics::global()`).
//!
//! The engine calls these methods on lifecycle transitions and (opt-in) per
//! frame. The **default no-op** means the pure engine has zero observability
//! dependencies; wire a real sink only when you want one.

use crate::bus::StreamEvent;
use crate::{MediaFrame, StreamKey};

/// Telemetry observer. All methods default to no-ops so implementors override
/// only what they care about. Compare `arcly-http`'s `AuditSink` / `HealthCheck`
/// injection points: behaviour is supplied by the host, never reached for
/// through global state.
pub trait Observer: Send + Sync + 'static {
    /// A stream lifecycle event was emitted.
    fn on_event(&self, _event: &StreamEvent) {}

    /// A publish session started in application `app`.
    fn on_publish_started(&self, _app: &str) {}

    /// A publish session ended in application `app`.
    fn on_publish_ended(&self, _app: &str) {}

    /// A frame was published. **Hot-path hook — keep it cheap.** The default
    /// is a no-op so the branch is trivially predicted away when no observer
    /// is installed.
    fn on_frame(&self, _key: &StreamKey, _frame: &MediaFrame) {}

    /// A subscriber fell behind the broadcast buffer and `skipped` frames were
    /// dropped from its view before it could read them. This is the canonical
    /// slow-consumer signal: alert on it. Fired by
    /// [`StreamHandle::subscribe_resilient`](crate::StreamHandle::subscribe_resilient).
    fn on_subscriber_lagged(&self, _key: &StreamKey, _skipped: u64) {}

    /// A chronically slow subscriber crossed its `max_lag` budget and was shed.
    /// Fired by [`Subscription::recv`](crate::Subscription::recv).
    fn on_subscriber_evicted(&self, _key: &StreamKey) {}

    /// An ingress rate limit was exceeded for `key`; the protocol handler should
    /// drop or backpressure the connection. Handlers call this from their
    /// ingest loop (e.g. when [`IngestRateLimit`](crate::protocol::IngestRateLimit)
    /// returns `false`).
    fn on_rate_limited(&self, _key: &StreamKey) {}

    /// A publish session was reaped for exceeding the engine's idle timeout.
    fn on_stream_reaped(&self, _key: &StreamKey) {}
}

/// The default observer. Selected automatically when the builder gets none.
#[derive(Debug, Default, Clone, Copy)]
pub struct NoopObserver;

impl Observer for NoopObserver {}