Enum Error 

#[non_exhaustive]
pub enum Error {
    Transport(String),
    Decode(DecodeError),
    Version,
    UnexpectedStream,
    BoundsExceeded(BoundsExceeded),
    InvalidPath(InvalidPattern),
    Duplicate,
    Cancel,
    Timeout,
    Old,
    App(u16),
    NotFound,
    Unroutable,
    WrongSize,
    ProtocolViolation,
    Unauthorized,
    UnexpectedMessage,
    Unsupported,
    Encode(EncodeError),
    TooManyParameters,
    UnknownAlpn(String),
    Dropped,
    Closed,
    Lagged,
    FrameTooLarge,
    GroupTooLarge,
    FrameOpen,
    TimestampMismatch,
    Evicted,
    GoingAway,
    GoawayTimeout,
    MalformedTrack,
    SessionClosed,
    Session(SessionError),
    Stream(StreamError),
    Remote(u32),
}

Failures in this crate, both local conditions and codes received off the wire.

Local conditions are the flat variants (Cancel, NotFound, Lagged, and so on): this side decided what went wrong. Codes received from a peer are nested in Self::Session or Self::Stream, preserving the registry and the numeric value. Self::Remote is an unrecognized request-rejection code (the IETF request registry), not a session or stream unknown.

The two registries are the wire. Mapping a local condition onto a code is SessionError::from / StreamError::from; folding the flat variants into those registries is a later decision.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Transport(String)

The underlying QUIC/WebTransport connection failed; carries the backend’s message.

Decode(DecodeError)

A message off the wire could not be parsed.

Version

Version negotiation failed, or the negotiated version lacks a requested feature (e.g. a FETCH against a version without fetch support). Mostly a connect-time error, but the feature-gap case can surface mid-session, so it can’t simply move to a connect-only error type.

UnexpectedStream

A known stream type arrived where this version or state does not allow it. Closes the session as a protocol violation, or resets just the stream when it can be refused on its own.

BoundsExceeded(BoundsExceeded)

An integer was too large for the QUIC varint range.

InvalidPath(InvalidPattern)

A path holds a segment no pattern can spell (* or **), so it can never be announced or matched.

Duplicate

A duplicate ID was used

Cancel

Nobody is reading any more, so the producer stopped. Not a failure.

Timeout

It took too long to open or transmit a stream.

Old

The group is older than the latest group and dropped.

App(u16)

An application-chosen close code. Bounded to u16 and offset past the library’s reserved range (+ 64) on the wire by SessionError::to_code / StreamError::to_code, so app codes never collide with protocol ones.

The width asymmetry with Self::Remote is deliberate: App is a code this side chooses to send, while Remote carries a raw code received off the wire that didn’t map to a known variant, which can be any u32.

NotFound

The requested broadcast or track does not exist at the peer.

Unroutable

A broadcast was requested that is neither announced nor served by a dynamic router, so there is no route to it.

WrongSize

A frame’s payload length disagreed with its declared size.

ProtocolViolation

The peer broke a protocol rule; the session is unusable.

Unauthorized

The requested path or operation is not granted, either by the peer’s token or by the scope of the handle it was requested through.

UnexpectedMessage

A valid message arrived in a state where it is not allowed.

Unsupported

The peer asked for a feature this endpoint does not implement.

Encode(EncodeError)

A message could not be serialized for the negotiated version.

TooManyParameters

A message carried more parameters than this endpoint accepts.

UnknownAlpn(String)

The peer offered an ALPN this endpoint doesn’t recognize, so no version could be negotiated. A connect-time error.

Dropped

The producer was dropped without finishing, so the content is incomplete.

Closed

The handle was already closed by this side.

Lagged

The reader asked for a frame the group never held: below crate::group::Producer::start_at, or skipped past a splice. Named from the consumer’s side; distinct from Self::GroupTooLarge, which aborts the whole group when a write exceeds the cache budget, and from Self::Evicted, which drops a whole group under the pool’s memory pressure.

FrameTooLarge

A frame declared a payload size larger than the receiver accepts.

GroupTooLarge

A write would grow the group past its cache budget (byte size or frame count). The write is refused and the group is aborted, so every reader sees the same failure rather than a prefix some of them missed.

FrameOpen

A whole-frame write was refused because a frame is already open on the group.

A crate::group::Producer streaming a frame with create_frame blocks the whole-frame writes on every clone of that producer until it finishes, since appending around it would reorder the group.

TimestampMismatch

A frame’s timestamp doesn’t match its track’s negotiated timescale: it’s missing on a timed track, present on an untimed track, or carries a different scale than the track advertised.

Evicted

The group was evicted by its own track to pay eviction debt under memory pressure (see cache::Pool). Unlike Self::Old, the group was still within the publisher’s window; it can be re-fetched.

GoingAway

The session is going away (a GOAWAY was received); new subscribe and announce-interest requests are rejected while existing subscriptions keep flowing.

GoawayTimeout

The peer did not close the session within the GOAWAY drain deadline.

Sent as the session termination code when the draining side force-closes after the advertised deadline expires (see crate::goaway::Goaway::timeout).

MalformedTrack

The peer could not parse the track’s content.

SessionClosed

The stream was torn down because the session closed. The specific reason travels on the session close, not here.

Session(SessionError)

A session-scoped protocol error, with its registry and verbatim code.

Produced by from_transport for a session close, and by converting a SessionError. Local conditions use the specific variants above.

Stream(StreamError)

A stream-scoped protocol error, with its registry and verbatim code.

The stream counterpart to Self::Session. The two registries are disjoint, so the same integer is a different failure in each.

Remote(u32)

An unrecognized request-rejection code (the IETF request registry).

Session and stream unknowns are Self::Session / Self::Stream, not this.

Implementations

impl Error

pub fn session(&self) -> Option<&SessionError>

The session-scoped protocol error, if this was received as one.

pub fn stream(&self) -> Option<&StreamError>

The stream-scoped protocol error, if this was received as one.

pub fn from_transport(err: impl Error) -> Self

Convert a transport error into an Error, decoding session close and stream reset codes through their respective registries.

The two spaces are disjoint, so which one applies depends on what failed: a session close decodes via SessionError::from_code, a stream reset via StreamError::from_code. Reading a stream reset with the session table (or the reverse) silently mistranslates, since e.g. 0 is “no error” for a session but an internal error for a stream.

Trait Implementations

impl Clone for Error

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl Error for Error

fn session_error(&self) -> Option<(u32, String)>

Returns the error code and reason if this was an application error.

fn stream_error(&self) -> Option<u32>

Returns the error code if this was a stream error.

impl From<&Error> for SessionError

Which session code to send for a local error.

Lossy on purpose: Error describes what went wrong locally, while the registry is what the peer can act on. Anything stream-scoped reaching a session close is a bug on our side, so it degrades to SessionError::Internal rather than inventing a code.

fn from(err: &Error) -> Self

Converts to this type from the input type.

impl From<&Error> for StreamError

Which stream code to send for a local error.

Session-scoped conditions route through StreamError::Session, which flattens to SESSION_CLOSED on the wire.

fn from(err: &Error) -> Self

Converts to this type from the input type.

impl From<BoundsExceeded> for Error

fn from(source: BoundsExceeded) -> Self

Converts to this type from the input type.

impl From<DecodeError> for Error

fn from(source: DecodeError) -> Self

Converts to this type from the input type.

impl From<EncodeError> for Error

fn from(source: EncodeError) -> Self

Converts to this type from the input type.

impl From<InvalidPattern> for Error

fn from(source: InvalidPattern) -> Self

Converts to this type from the input type.

impl From<SessionError> for Error

Preserve the session registry when carrying a protocol error.

fn from(err: SessionError) -> Self

Converts to this type from the input type.

impl From<StreamError> for Error

Preserve the stream registry when carrying a protocol error.

fn from(err: StreamError) -> Self

Converts to this type from the input type.