moqtap-codec 0.5.0

//! Draft-10 error, status and termination code registries.
//!
//! Draft-10 predates the IANA registries introduced in draft-14. Each registry
//! here is an inline `Code | Reason` table in the draft body, and the Reason
//! column is the only name the draft gives a code point — there are no ALLCAPS
//! symbolic names to transcribe. Every variant therefore carries the draft's
//! Reason text verbatim in backticks so the mapping from Rust name to draft row
//! stays checkable, followed by the draft's own prose where the draft supplies
//! any.
//!
//! `from_u64` returns `None` for a code this draft does not define. Peers do
//! send codes from other drafts and from private extensions, so an unknown code
//! is a normal decoding outcome rather than an error.
//!
//! Six registries are transcribed here, and they cover seven messages.
//! ANNOUNCE_CANCEL carries an Error Code field with no table of its own, and
//! Section 8.22 says why: "ANNOUNCE_CANCEL uses the same error codes as
//! ANNOUNCE_ERROR". So its codes are [`AnnounceErrorCode`], and there is no
//! seventh enum because there is no seventh registry.

/// Session termination codes (draft-10, Section 3.4 "Termination").
///
/// Sent in the QUIC CONNECTION_CLOSE frame, or in the
/// CLOSE_WEBTRANSPORT_SESSION capsule when WebTransport is used. The draft
/// states the application MAY use any error message and SHOULD use a relevant
/// code from this table.
///
/// The table assigns 0x0 through 0x6 and then jumps to 0x10. Draft-10 declares
/// no reserved range over 0x7 to 0xF, so those values are simply unassigned and
/// `from_u64` rejects them.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum SessionErrorCode {
    /// `No Error` — the session is being terminated without an error.
    NoError = 0x0,
    /// `Internal Error` — an implementation specific error occurred.
    InternalError = 0x1,
    /// `Unauthorized` — the endpoint breached an agreement, which MAY have been
    /// pre-negotiated by the application.
    Unauthorized = 0x2,
    /// `Protocol Violation` — the remote endpoint performed an action that was
    /// disallowed by the specification.
    ProtocolViolation = 0x3,
    /// `Duplicate Track Alias` — the endpoint attempted to use a Track Alias
    /// that was already in use.
    DuplicateTrackAlias = 0x4,
    /// `Parameter Length Mismatch` — Section 3.4 lists this code but does not
    /// describe it; Section 8.1 requires a receiver that understands a
    /// parameter type to terminate the session with this code when the length
    /// implied by that type does not match the Parameter Length field.
    ParameterLengthMismatch = 0x5,
    /// `Too Many Subscribes` — the session was closed because the subscriber
    /// used a Subscribe ID equal or larger than the current Maximum Subscribe
    /// ID.
    TooManySubscribes = 0x6,
    /// `GOAWAY Timeout` — the session was closed because the peer took too long
    /// to close the session in response to a GOAWAY message (Section 8.3).
    /// Section 3.5 adds that a server SHOULD terminate the session with this
    /// code after a sufficient timeout if there are still open subscriptions or
    /// fetches on the connection.
    GoawayTimeout = 0x10,
    /// `Control Message Timeout` — the session was closed because the peer took
    /// too long to respond to a control message.
    ControlMessageTimeout = 0x11,
    /// `Data Stream Timeout` — the session was closed because the peer took too
    /// long to send data expected on an open data stream. This includes fields
    /// of a stream header or an object header within a data stream. An endpoint
    /// that times out waiting for a new object header on an open subgroup
    /// stream MAY send a STOP_SENDING on that stream, terminate the
    /// subscription, or close the session with an error.
    DataStreamTimeout = 0x12,
}

/// SUBSCRIBE_ERROR codes (draft-10, Section 8.8 "SUBSCRIBE_ERROR").
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum SubscribeErrorCode {
    /// `Internal Error`
    InternalError = 0x0,
    /// `Unauthorized`
    Unauthorized = 0x1,
    /// `Timeout`
    Timeout = 0x2,
    /// `Not Supported`
    NotSupported = 0x3,
    /// `Track Does Not Exist`
    TrackDoesNotExist = 0x4,
    /// `Invalid Range` — Section 8.6 directs a publisher that cannot satisfy
    /// the requested start or end, or whose end has already been published, to
    /// send SUBSCRIBE_ERROR with this code. A publisher MUST NOT send objects
    /// from outside the requested start and end.
    InvalidRange = 0x5,
    /// `Retry Track Alias` — the subscriber SHOULD re-issue the SUBSCRIBE with
    /// the Track Alias carried in the SUBSCRIBE_ERROR message instead. If that
    /// Track Alias is already in use, the subscriber MUST close the connection
    /// with a Duplicate Track Alias error.
    RetryTrackAlias = 0x6,
}

/// SUBSCRIBE_DONE status codes (draft-10, Section 8.11 "SUBSCRIBE_DONE").
///
/// The draft calls these status codes rather than error codes: a subscription
/// that ends normally is also reported through this registry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum SubscribeDoneStatusCode {
    /// `Internal Error`
    InternalError = 0x0,
    /// `Unauthorized`
    Unauthorized = 0x1,
    /// `Track Ended`
    TrackEnded = 0x2,
    /// `Subscription Ended`
    SubscriptionEnded = 0x3,
    /// `Going Away`
    GoingAway = 0x4,
    /// `Expired`
    Expired = 0x5,
    /// `Too Far Behind` — the publisher MAY terminate the subscription with
    /// this status if the subscriber exceeds the publisher's resource limits by
    /// failing to consume objects at a sufficient rate.
    TooFarBehind = 0x6,
}

/// FETCH_ERROR codes (draft-10, Section 8.14 "FETCH_ERROR").
///
/// Draft-10 is internally inconsistent about this registry, and the variants
/// below follow the table rather than the prose. Section 8.12 states that a
/// publisher MUST return FETCH_ERROR with error code `No Objects` when the
/// requested start is past the latest published group, and Section 8.12.1
/// states the same for a joining fetch against a track with no published
/// content. Neither the table in Section 8.14 nor any other table in draft-10
/// assigns `No Objects` a number, so it cannot be represented here and a peer
/// that sends it has no value this draft could have told it to use. Draft-11 is
/// the first to assign the code, as 0x6, which is where it has stayed since.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum FetchErrorCode {
    /// `Internal Error`
    InternalError = 0x0,
    /// `Unauthorized`
    Unauthorized = 0x1,
    /// `Timeout`
    Timeout = 0x2,
    /// `Not Supported`
    NotSupported = 0x3,
    /// `Track Does Not Exist`
    TrackDoesNotExist = 0x4,
    /// `Invalid Range`
    InvalidRange = 0x5,
}

/// ANNOUNCE_ERROR codes (draft-10, Section 8.20 "ANNOUNCE_ERROR").
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum AnnounceErrorCode {
    /// `Internal Error`
    InternalError = 0x0,
    /// `Unauthorized`
    Unauthorized = 0x1,
    /// `Timeout`
    Timeout = 0x2,
    /// `Not Supported`
    NotSupported = 0x3,
    /// `Uninterested`
    Uninterested = 0x4,
}

/// SUBSCRIBE_ANNOUNCES_ERROR codes (draft-10, Section 8.25
/// "SUBSCRIBE_ANNOUNCES_ERROR").
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum SubscribeAnnouncesErrorCode {
    /// `Internal Error`
    InternalError = 0x0,
    /// `Unauthorized`
    Unauthorized = 0x1,
    /// `Timeout`
    Timeout = 0x2,
    /// `Not Supported`
    NotSupported = 0x3,
    /// `Namespace Prefix Unknown`
    NamespacePrefixUnknown = 0x4,
}

impl SessionErrorCode {
    /// Every session termination code draft-10 assigns, in ascending wire order.
    ///
    /// This is the set [`Self::from_u64`] accepts, written out so that it can
    /// be enumerated: nothing can iterate an enum's variants, so a caller that
    /// wants the registry has to be handed it. Writing it down is also what
    /// lets a test state its claims about the registry itself rather than about
    /// the range some sweep happens to reach.
    pub const ALL: &[SessionErrorCode] = &[
        SessionErrorCode::NoError,
        SessionErrorCode::InternalError,
        SessionErrorCode::Unauthorized,
        SessionErrorCode::ProtocolViolation,
        SessionErrorCode::DuplicateTrackAlias,
        SessionErrorCode::ParameterLengthMismatch,
        SessionErrorCode::TooManySubscribes,
        SessionErrorCode::GoawayTimeout,
        SessionErrorCode::ControlMessageTimeout,
        SessionErrorCode::DataStreamTimeout,
    ];

    /// Convert a raw u64 to a `SessionErrorCode`, if draft-10 defines it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x0 => Some(SessionErrorCode::NoError),
            0x1 => Some(SessionErrorCode::InternalError),
            0x2 => Some(SessionErrorCode::Unauthorized),
            0x3 => Some(SessionErrorCode::ProtocolViolation),
            0x4 => Some(SessionErrorCode::DuplicateTrackAlias),
            0x5 => Some(SessionErrorCode::ParameterLengthMismatch),
            0x6 => Some(SessionErrorCode::TooManySubscribes),
            0x10 => Some(SessionErrorCode::GoawayTimeout),
            0x11 => Some(SessionErrorCode::ControlMessageTimeout),
            0x12 => Some(SessionErrorCode::DataStreamTimeout),
            _ => None,
        }
    }

    /// Return the raw u64 value of this error code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}

impl SubscribeErrorCode {
    /// Every SUBSCRIBE_ERROR code draft-10 assigns, in ascending wire order.
    ///
    /// This is the set [`Self::from_u64`] accepts, written out so that it can
    /// be enumerated: nothing can iterate an enum's variants, so a caller that
    /// wants the registry has to be handed it. Writing it down is also what
    /// lets a test state its claims about the registry itself rather than about
    /// the range some sweep happens to reach.
    pub const ALL: &[SubscribeErrorCode] = &[
        SubscribeErrorCode::InternalError,
        SubscribeErrorCode::Unauthorized,
        SubscribeErrorCode::Timeout,
        SubscribeErrorCode::NotSupported,
        SubscribeErrorCode::TrackDoesNotExist,
        SubscribeErrorCode::InvalidRange,
        SubscribeErrorCode::RetryTrackAlias,
    ];

    /// Convert a raw u64 to a `SubscribeErrorCode`, if draft-10 defines it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x0 => Some(SubscribeErrorCode::InternalError),
            0x1 => Some(SubscribeErrorCode::Unauthorized),
            0x2 => Some(SubscribeErrorCode::Timeout),
            0x3 => Some(SubscribeErrorCode::NotSupported),
            0x4 => Some(SubscribeErrorCode::TrackDoesNotExist),
            0x5 => Some(SubscribeErrorCode::InvalidRange),
            0x6 => Some(SubscribeErrorCode::RetryTrackAlias),
            _ => None,
        }
    }

    /// Return the raw u64 value of this error code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}

impl SubscribeDoneStatusCode {
    /// Every SUBSCRIBE_DONE status code draft-10 assigns, in ascending wire order.
    ///
    /// This is the set [`Self::from_u64`] accepts, written out so that it can
    /// be enumerated: nothing can iterate an enum's variants, so a caller that
    /// wants the registry has to be handed it. Writing it down is also what
    /// lets a test state its claims about the registry itself rather than about
    /// the range some sweep happens to reach.
    pub const ALL: &[SubscribeDoneStatusCode] = &[
        SubscribeDoneStatusCode::InternalError,
        SubscribeDoneStatusCode::Unauthorized,
        SubscribeDoneStatusCode::TrackEnded,
        SubscribeDoneStatusCode::SubscriptionEnded,
        SubscribeDoneStatusCode::GoingAway,
        SubscribeDoneStatusCode::Expired,
        SubscribeDoneStatusCode::TooFarBehind,
    ];

    /// Convert a raw u64 to a `SubscribeDoneStatusCode`, if draft-10 defines it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x0 => Some(SubscribeDoneStatusCode::InternalError),
            0x1 => Some(SubscribeDoneStatusCode::Unauthorized),
            0x2 => Some(SubscribeDoneStatusCode::TrackEnded),
            0x3 => Some(SubscribeDoneStatusCode::SubscriptionEnded),
            0x4 => Some(SubscribeDoneStatusCode::GoingAway),
            0x5 => Some(SubscribeDoneStatusCode::Expired),
            0x6 => Some(SubscribeDoneStatusCode::TooFarBehind),
            _ => None,
        }
    }

    /// Return the raw u64 value of this status code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}

impl FetchErrorCode {
    /// Every FETCH_ERROR code draft-10 assigns, in ascending wire order.
    ///
    /// This is the set [`Self::from_u64`] accepts, written out so that it can
    /// be enumerated: nothing can iterate an enum's variants, so a caller that
    /// wants the registry has to be handed it. Writing it down is also what
    /// lets a test state its claims about the registry itself rather than about
    /// the range some sweep happens to reach.
    pub const ALL: &[FetchErrorCode] = &[
        FetchErrorCode::InternalError,
        FetchErrorCode::Unauthorized,
        FetchErrorCode::Timeout,
        FetchErrorCode::NotSupported,
        FetchErrorCode::TrackDoesNotExist,
        FetchErrorCode::InvalidRange,
    ];

    /// Convert a raw u64 to a `FetchErrorCode`, if draft-10 defines it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x0 => Some(FetchErrorCode::InternalError),
            0x1 => Some(FetchErrorCode::Unauthorized),
            0x2 => Some(FetchErrorCode::Timeout),
            0x3 => Some(FetchErrorCode::NotSupported),
            0x4 => Some(FetchErrorCode::TrackDoesNotExist),
            0x5 => Some(FetchErrorCode::InvalidRange),
            _ => None,
        }
    }

    /// Return the raw u64 value of this error code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}

impl AnnounceErrorCode {
    /// Every ANNOUNCE_ERROR code draft-10 assigns, in ascending wire order.
    ///
    /// This is the set [`Self::from_u64`] accepts, written out so that it can
    /// be enumerated: nothing can iterate an enum's variants, so a caller that
    /// wants the registry has to be handed it. Writing it down is also what
    /// lets a test state its claims about the registry itself rather than about
    /// the range some sweep happens to reach.
    pub const ALL: &[AnnounceErrorCode] = &[
        AnnounceErrorCode::InternalError,
        AnnounceErrorCode::Unauthorized,
        AnnounceErrorCode::Timeout,
        AnnounceErrorCode::NotSupported,
        AnnounceErrorCode::Uninterested,
    ];

    /// Convert a raw u64 to an `AnnounceErrorCode`, if draft-10 defines it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x0 => Some(AnnounceErrorCode::InternalError),
            0x1 => Some(AnnounceErrorCode::Unauthorized),
            0x2 => Some(AnnounceErrorCode::Timeout),
            0x3 => Some(AnnounceErrorCode::NotSupported),
            0x4 => Some(AnnounceErrorCode::Uninterested),
            _ => None,
        }
    }

    /// Return the raw u64 value of this error code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}

impl SubscribeAnnouncesErrorCode {
    /// Every SUBSCRIBE_ANNOUNCES_ERROR code draft-10 assigns, in ascending wire order.
    ///
    /// This is the set [`Self::from_u64`] accepts, written out so that it can
    /// be enumerated: nothing can iterate an enum's variants, so a caller that
    /// wants the registry has to be handed it. Writing it down is also what
    /// lets a test state its claims about the registry itself rather than about
    /// the range some sweep happens to reach.
    pub const ALL: &[SubscribeAnnouncesErrorCode] = &[
        SubscribeAnnouncesErrorCode::InternalError,
        SubscribeAnnouncesErrorCode::Unauthorized,
        SubscribeAnnouncesErrorCode::Timeout,
        SubscribeAnnouncesErrorCode::NotSupported,
        SubscribeAnnouncesErrorCode::NamespacePrefixUnknown,
    ];

    /// Convert a raw u64 to a `SubscribeAnnouncesErrorCode`, if draft-10
    /// defines it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x0 => Some(SubscribeAnnouncesErrorCode::InternalError),
            0x1 => Some(SubscribeAnnouncesErrorCode::Unauthorized),
            0x2 => Some(SubscribeAnnouncesErrorCode::Timeout),
            0x3 => Some(SubscribeAnnouncesErrorCode::NotSupported),
            0x4 => Some(SubscribeAnnouncesErrorCode::NamespacePrefixUnknown),
            _ => None,
        }
    }

    /// Return the raw u64 value of this error code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}

/// TRACK_STATUS Status Code values (draft-10, Section 8.17).
///
/// The draft defines these as a prose list rather than as a `Code`/`Reason`
/// table, so they are named from the prose. It is stricter about this field
/// than about the error registries above: the Status Code "MUST hold one of the
/// following values" and "Any other value in the Status Code field is a
/// malformed message", so [`TrackStatusCode::from_u64`] answering `None` is a
/// decode failure rather than a merely unrecognised code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u64)]
pub enum TrackStatusCode {
    /// The track is in progress, and subsequent fields contain the highest
    /// group and object ID for that track.
    InProgress = 0x00,
    /// The track does not exist. Subsequent fields MUST be zero, and any other
    /// value is a malformed message.
    TrackDoesNotExist = 0x01,
    /// The track has not yet begun. Subsequent fields MUST be zero, and any
    /// other value is a malformed message.
    NotYetBegun = 0x02,
    /// The track has finished, so there is no live edge. Subsequent fields
    /// contain the highest group and object ID known.
    Finished = 0x03,
    /// The publisher is a relay that cannot obtain the current track status
    /// from upstream. Subsequent fields contain the largest group and object
    /// ID known.
    RelayStatusUnavailable = 0x04,
}

impl TrackStatusCode {
    /// Convert a raw u64 to a `TrackStatusCode`, if this draft assigns it.
    pub fn from_u64(v: u64) -> Option<Self> {
        match v {
            0x00 => Some(TrackStatusCode::InProgress),
            0x01 => Some(TrackStatusCode::TrackDoesNotExist),
            0x02 => Some(TrackStatusCode::NotYetBegun),
            0x03 => Some(TrackStatusCode::Finished),
            0x04 => Some(TrackStatusCode::RelayStatusUnavailable),
            _ => None,
        }
    }

    /// Whether this code requires the fields after it to be zero.
    ///
    /// Section 8.17 says of 0x01 "Subsequent fields MUST be zero, and any other
    /// value is a malformed message", and the same of 0x02. The other three
    /// codes describe those fields as carrying a real location, so they place
    /// no requirement on them.
    pub fn requires_zero_location(self) -> bool {
        matches!(self, TrackStatusCode::TrackDoesNotExist | TrackStatusCode::NotYetBegun)
    }

    /// Return the raw u64 value of this status code.
    pub fn as_u64(self) -> u64 {
        self as u64
    }
}