Enum EndpointError 

pub enum EndpointError {
    GoAwayUriAtServer,
    Session(SessionError),
    SubscribeId(SubscribeIdError),
    Subscription(SubscriptionError),
    Fetch(FetchError),
    Namespace(NamespaceError),
    TrackStatus(TrackStatusError),
    Setup(SetupError),
    UnknownSubscribe(u64),
    UnknownNamespace,
    UnknownTrackStatus,
    UnknownPeerTrackStatus,
    NotActive,
    Draining,
    FilterNeedsRange,
    MalformedSetupParameter(u64),
    PeerSubscribeIdNotIncreasing(u64, u64),
    RepeatedGoAway,
    DuplicateTrackAlias {
        alias: u64,
        established_side: SubscribeSide,
        established: u64,
        offered_side: SubscribeSide,
        offered: u64,
    },
    TrackAliasInUse {
        alias: u64,
        side: SubscribeSide,
        held: u64,
    },
    MixedForwardingPreference {
        alias: u64,
        established: ObjectForwardingPreference,
        offered: ObjectForwardingPreference,
    },
    EndOfTrackOutOfPlace {
        alias: u64,
        group: u64,
        object: u64,
        placement: EndOfTrackPlacement,
    },
    UpdateForUnknownSubscribe(u64),
    UnjoinableSubscription {
        fetch: u64,
        joining: u64,
    },
    UnknownPeerNamespace,
    UnknownPeerNamespaceSubscription,
    PeerPrefixOverlap,
    OwnPrefixOverlap,
}

Errors that can occur during draft-08 endpoint operations.

Variants

GoAwayUriAtServer

A GOAWAY carrying a New Session URI arrived at a server.

Section 7.3: “If a server receives a GOAWAY with a non-zero New Session URI Length it MUST terminate the session with a Protocol Violation.” Migration is something a server offers a client, never the other way round.

Session(SessionError)

A session-level state machine error.

SubscribeId(SubscribeIdError)

A subscribe ID allocation or validation error.

Subscription(SubscriptionError)

A subscription state machine error.

Fetch(FetchError)

A fetch state machine error.

Namespace(NamespaceError)

A namespace state machine error.

TrackStatus(TrackStatusError)

A track status state machine error.

Setup(SetupError)

A setup negotiation error.

UnknownSubscribe(u64)

The subscribe ID does not match any known state machine.

UnknownNamespace

The track namespace does not match any known state machine.

UnknownTrackStatus

The (namespace, track) pair does not match any known track status request.

UnknownPeerTrackStatus

A message about a track status named a track the peer has not asked about.

Section 7.12 makes the request the subscriber’s: “A potential subscriber sends a ‘TRACK_STATUS_REQUEST’ message on the control stream to obtain information about the current status of a given track.” What an answer answers is therefore a request the peer made, so the record it reaches for is the one this endpoint keeps of what the peer has asked about.

Separate from EndpointError::UnknownTrackStatus, which is the same miss on the requests this endpoint made, so a caller can tell which of the two maps came up empty.

NotActive

The session is not in the Active state.

Draining

The session is draining and cannot accept new requests.

FilterNeedsRange

A filter that names a start location was asked for through a helper that has no start location to give it.

MalformedSetupParameter(u64)

A setup parameter’s value could not be read as the type its key implies.

Tuple Fields

0: u64

Key of the offending parameter.

PeerSubscribeIdNotIncreasing(u64, u64)

A Subscribe ID the peer chose did not increase on the last one it used.

Tuple Fields

0: u64

The Subscribe ID that arrived.

1: u64

The highest Subscribe ID the peer had used before it.

RepeatedGoAway

A second GOAWAY arrived on the control stream.

The GOAWAY that says the peer is going away is one message, and the draft answers a repeat of it with a session close rather than with an error about the second message: there is no state a second one could move that the first has not already moved.

DuplicateTrackAlias

A Track Alias names two tracks at once.

Section 7.4, on the Track Alias the subscriber chooses in SUBSCRIBE: “If the Track Alias is already being used for a different track, the publisher MUST close the session with a Duplicate Track Alias error”. Section 7.16 states the other end of the same rule, on the alias a SUBSCRIBE_ERROR may offer to retry with: “If this Track Alias is already in use, the subscriber MUST close the connection with a Duplicate Track Alias error”.

The session is over: this endpoint’s own state has moved to Closed and the code the transport should close with is in EndpointError::session_error_code.

Fields

alias: u64

The alias both tracks are named by.

established_side: SubscribeSide

Which end opened the subscription that holds the alias.

established: u64

That subscription’s identifier, in its own end’s sequence.

offered_side: SubscribeSide

Which end opened the subscription naming it for another track.

offered: u64

That subscription’s identifier, in its own end’s sequence.

TrackAliasInUse

This endpoint was asked to give a Track Alias to a second track.

The same rule as EndpointError::DuplicateTrackAlias read at the end that chooses the alias. Section 3.5 describes the code as “The endpoint attempted to use a Track Alias that was already in use”, and Section 7.4 says what the receiving publisher does about it, so a SUBSCRIBE built this way is one the peer must answer by ending the session.

The message is refused instead, and nothing else moves: no Subscribe ID is spent, no subscription is created, and the session stays as it was. The alias never reaches the peer, so there is nothing for the peer to close over.

Fields

alias: u64

The alias that is already spoken for.

side: SubscribeSide

Which end opened the subscription holding it.

held: u64

That subscription’s identifier, in its own end’s sequence.

MixedForwardingPreference

A track’s objects were framed two different ways.

Section 8: “Every Track has a single ‘Object Forwarding Preference’ and the Original Publisher MUST NOT mix different forwarding preferences within a single track. If a subscriber receives different forwarding preferences for a track, it SHOULD close the session with an error of ‘Protocol Violation’.”

The framing is the preference: an object on a subgroup stream has the Subgroup preference and an object in a datagram has the Datagram one, so the track’s first object settles the property and this is every later object measured against it.

Fields

alias: u64

The Track Alias the offending object named.

established: ObjectForwardingPreference

The framing the track’s earlier objects settled on.

offered: ObjectForwardingPreference

The framing the offending object used.

EndOfTrackOutOfPlace

An object saying the track ended somewhere the track has already passed.

Section 8.1.1.1 describes Object Status 0x4, end of Track and Group, as one whose “GroupID is the largest group produced in this track and the ObjectId is one greater than the largest object produced in that group”, and states the consequence: “An object with this status that has a Group ID less than any other Group ID, or an Object ID less than or equal to the largest in the group, is a protocol error, and the receiver MUST terminate the session.”

Status 0x5, end of Track, is one notch stricter in the same paragraph: “An object with this status that has a Group ID less than or equal to any other Group ID, or an Object ID other than zero, is a protocol error, and the receiver MUST terminate the session.” Its Object-ID half needs no record and the codec refuses it on the header; its Group ID half is this.

Fields

alias: u64

The Track Alias the offending object named.

group: u64

The Group ID it named.

object: u64

The Object ID it named.

placement: EndOfTrackPlacement

Which half of the condition it broke, and what it was measured against.

UpdateForUnknownSubscribe(u64)

A SUBSCRIBE_UPDATE named an identifier no subscription the peer opened has ever been given.

Section 7.5: “A publisher SHOULD close the Session as a ‘Protocol Violation’ if the SUBSCRIBE_UPDATE violates either rule or if the subscriber specifies a Subscribe ID that has not existed within the Session.”

SHOULD, so this is reported and the session is left running. From draft-12 the same sentence says MUST, and there the session ends. An endpoint that wants the close on these drafts has everything it needs to make it: the error names the identifier that was not found.

A subscription that has ended is not this: it existed. That is why the record of an inbound SUBSCRIBE outlives the subscription, and why an update naming an ended one is refused by the flow rather than by this error.

UnjoinableSubscription

A Joining Fetch named a subscription this session cannot join.

Section 7.7: “If a publisher receives a Joining Fetch with a Subscribe ID that does not correspond to an existing Subscribe, it MUST respond with a Fetch Error.”

A refusal and not a session close, so the session runs on and the error names both identifiers: the fetch to refuse, and the subscription it asked to join.

Fields

fetch: u64

The fetch that named it.

joining: u64

The identifier it named.

UnknownPeerNamespace

A message about an announcement named a namespace the peer has not announced.

Section 7.11 says what a cancellation is for: the subscriber “will stop sending new subscriptions for tracks within the provided Track Namespace”. What a withdrawal ends and a cancellation revokes is an announcement the peer made, so the record they reach for is the one this endpoint keeps of the peer’s announcements.

Separate from EndpointError::UnknownNamespace, which is the same miss on the announcements this endpoint made, so a caller can tell which of the two maps came up empty.

UnknownPeerNamespaceSubscription

A message about a namespace subscription named a prefix the peer has not subscribed to.

Section 7.14: “A subscriber issues a UNSUBSCRIBE_ANNOUNCES message to a publisher indicating it is no longer interested in ANNOUNCE and UNANNOUNCE messages for the specified track namespace prefix.”

What a withdrawal ends is a namespace subscription the peer made, so the record it reaches for is the one this endpoint keeps of the peer’s. A namespace subscription this endpoint made is withdrawn by Endpoint::unsubscribe_announces, which is the same message travelling the other way and answers with EndpointError::UnknownNamespace.

PeerPrefixOverlap

The peer subscribed to a namespace prefix overlapping one it is already subscribed to.

Section 7.13: “A subscriber cannot make overlapping namespace subscriptions on a single session. Within a session, if a publisher receives a SUBSCRIBE_ANNOUNCES with a Track Namespace Prefix that is a prefix of an earlier SUBSCRIBE_ANNOUNCES or vice versa, it MUST respond with SUBSCRIBE_ANNOUNCES_ERROR, with error code SUBSCRIBE_ANNOUNCES_OVERLAP.”

The request is refused where it arrives and nothing is written down for it, which is the only outcome this draft can express. SUBSCRIBE_ANNOUNCES carries no Request ID here, so the acceptance, the refusal and the withdrawal all name a Track Namespace Prefix and nothing else. Two namespace subscriptions under one prefix would therefore have answers that cannot be told apart, and an equal prefix is the first case the sentence above names.

The code the sentence gives the refusal, SUBSCRIBE_ANNOUNCES_OVERLAP, is named in prose and appears in no registry this draft defines, so there is no number for this crate to put on the wire. A caller that wants to send the refusal builds it from the message it has just been handed.

OwnPrefixOverlap

This endpoint was asked to subscribe to a namespace prefix overlapping one it is already subscribed to.

The first half of the same sentence, which is addressed to the subscriber: “A subscriber cannot make overlapping namespace subscriptions on a single session.”

The message is refused instead of built, and nothing else moves: no state machine is created and the session stays as it was. The request never reaches the peer, so there is nothing for the peer to refuse.

A subscription that has been withdrawn still counts, because the publisher’s half of the sentence weighs a new prefix against “an earlier SUBSCRIBE_ANNOUNCES” rather than against a live one. Drafts from 12 on say “active” instead, and there a withdrawn one stops counting.

Implementations

impl EndpointError

pub fn session_error_code(&self) -> Option<SessionErrorCode>

The code to close the session with, when draft-08 answers this error with a close rather than leaving it to the one request it concerns.

None means the error is recoverable: the caller may report it, give up on the request it concerns, and keep the session running. Some means the draft ends the session, and the endpoint has already moved its own state to Closed - the code is what the transport should carry.

The table grows one rule at a time, and a rule joins it with a gate that drives the bytes at a real connection and reads the close code back off the wire. An arm added without one asserts nothing: from inside the process the session ends either way, and only the peer can tell the difference.

Trait Implementations

impl Debug for EndpointError

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

Formats the value using the given formatter.

impl Display for EndpointError

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

Formats the value using the given formatter.

impl Error for EndpointError

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 From<EndpointError> for ConnectionError

fn from(source: EndpointError) -> Self

Converts to this type from the input type.

impl From<FetchError> for EndpointError

fn from(source: FetchError) -> Self

Converts to this type from the input type.

impl From<NamespaceError> for EndpointError

fn from(source: NamespaceError) -> Self

Converts to this type from the input type.

impl From<SessionError> for EndpointError

fn from(source: SessionError) -> Self

Converts to this type from the input type.

impl From<SetupError> for EndpointError

fn from(source: SetupError) -> Self

Converts to this type from the input type.

impl From<SubscribeIdError> for EndpointError

fn from(source: SubscribeIdError) -> Self

Converts to this type from the input type.

impl From<SubscriptionError> for EndpointError

fn from(source: SubscriptionError) -> Self

Converts to this type from the input type.

impl From<TrackStatusError> for EndpointError

fn from(source: TrackStatusError) -> Self

Converts to this type from the input type.