moqtap-client 0.3.0

//! Client event types emitted by a MoQT connection.

use moqtap_codec::dispatch::{
    AnyControlMessage, AnyDatagramHeader, AnyFetchHeader, AnySubgroupHeader,
};
use moqtap_codec::draft18::data_stream::{FetchHeader, SubgroupHeader, SubgroupObject};

/// Direction of a message or stream relative to this endpoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Direction {
    /// Sent (outgoing).
    Send,
    /// Received (incoming).
    Receive,
}

/// Data stream type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum StreamKind {
    /// Subgroup data stream.
    Subgroup,
    /// Fetch data stream.
    Fetch,
    /// Datagram.
    Datagram,
}

/// Events emitted by a MoQT connection.
///
/// This enum is `#[non_exhaustive]` -- new variants may be added in minor
/// releases. Downstream `match` arms should include a wildcard `_ =>` branch.
#[non_exhaustive]
#[derive(Debug, Clone)]
pub enum ClientEvent {
    /// MoQT setup handshake completed.
    SetupComplete {
        /// The negotiated MoQT version (from ALPN in draft-18).
        negotiated_version: u64,
    },

    /// A control message was sent or received.
    ControlMessage {
        /// Whether the message was sent or received.
        direction: Direction,
        /// The decoded control message.
        message: AnyControlMessage,
        /// The raw wire bytes of the framed message (type + length + payload).
        /// `None` if raw capture is not available.
        raw: Option<Vec<u8>>,
    },

    /// A data stream was opened.
    StreamOpened {
        /// Whether we opened (Send) or accepted (Receive) the stream.
        direction: Direction,
        /// The type of data stream.
        stream_kind: StreamKind,
        /// Transport-level stream identifier.
        stream_id: u64,
    },

    /// A data stream header was decoded after the stream opened.
    DataStreamHeader {
        /// Transport-level stream identifier.
        stream_id: u64,
        /// Whether we opened (Send) or accepted (Receive) the stream.
        direction: Direction,
        /// The parsed subgroup header.
        header: AnySubgroupHeader,
    },

    /// A fetch response stream header was decoded.
    FetchStreamHeader {
        /// Transport-level stream identifier.
        stream_id: u64,
        /// Whether we opened (Send) or accepted (Receive) the stream.
        direction: Direction,
        /// The parsed fetch header.
        header: AnyFetchHeader,
    },

    /// A subgroup object header was decoded on a subgroup stream.
    SubgroupObjectReceived {
        /// Transport-level stream identifier.
        stream_id: u64,
        /// Direction (Send when emitted from a writer, Receive from a reader).
        direction: Direction,
        /// The decoded subgroup header (for context).
        subgroup_header: SubgroupHeader,
        /// The decoded subgroup object.
        object: SubgroupObject,
    },

    /// A fetch header was decoded on a fetch stream.
    FetchHeaderReceived {
        /// Transport-level stream identifier.
        stream_id: u64,
        /// Direction (Send when emitted from a writer, Receive from a reader).
        direction: Direction,
        /// The decoded fetch header.
        header: FetchHeader,
    },

    /// A datagram was sent or received.
    DatagramReceived {
        /// Whether sent or received.
        direction: Direction,
        /// The parsed datagram header.
        header: AnyDatagramHeader,
        /// Size of the payload in bytes.
        payload_len: usize,
    },

    /// A data stream was closed.
    StreamClosed {
        /// Transport-level stream identifier.
        stream_id: u64,
        /// Error code (0 = clean close).
        error_code: u64,
    },

    /// Session entered draining state (GOAWAY received).
    Draining {
        /// The new session URI from the GOAWAY message.
        new_session_uri: Vec<u8>,
    },

    /// Connection was closed.
    Closed {
        /// Application error code.
        code: u32,
        /// Human-readable reason.
        reason: Vec<u8>,
    },

    /// A transport or protocol error occurred.
    Error {
        /// Error description.
        error: String,
    },
}