Enum EndpointError 

pub enum EndpointError {
    GoAwayUriAtServer,
    Session(SessionError),
    RequestId(RequestIdError),
    Subscription(SubscriptionError),
    Fetch(FetchError),
    Namespace(NamespaceError),
    TrackStatus(TrackStatusError),
    Setup(SetupError),
    UnknownRequest(u64),
    UnknownNamespace,
    NotActive,
    Draining,
    FilterNeedsRange,
    RepeatedGoAway,
    DuplicateTrackAlias {
        alias: u64,
        established: u64,
        offered: u64,
    },
    TrackAliasInUse {
        alias: u64,
        held: u64,
    },
    MixedForwardingPreference {
        alias: u64,
        established: ObjectForwardingPreference,
        offered: ObjectForwardingPreference,
    },
    EndOfTrackOutOfPlace {
        alias: u64,
        group: u64,
        object: u64,
        placement: EndOfTrackPlacement,
    },
    UpdateForUnknownRequest(u64),
    UnjoinableSubscription {
        fetch: u64,
        joining: u64,
    },
    WrongJoiningRefusal {
        fetch: u64,
        required: u64,
    },
    UnknownPeerNamespace,
    UnknownPeerNamespaceSubscription,
    PeerPrefixOverlap {
        request: u64,
        established: u64,
    },
    OwnPrefixOverlap {
        established: u64,
    },
    WrongOverlapRefusal {
        request: u64,
        required: u64,
    },
}

Errors that can occur during draft-11 endpoint operations.

Variants

GoAwayUriAtServer

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

Section 8.4: “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.

RequestId(RequestIdError)

A request 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.

UnknownRequest(u64)

The request ID does not match any known state machine.

UnknownNamespace

The track namespace does not match any known state machine.

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.

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 8.7, 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 8.9 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”.

This is the last draft that puts the alias in SUBSCRIBE and so the last that raises this at the publisher. From draft-12 the alias moves into SUBSCRIBE_OK and PUBLISH, and the endpoint that must close moves with it.

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: u64

The request whose live subscription holds the alias.

offered: u64

The request whose message arrived naming it for another track.

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.4 describes the code as “The endpoint attempted to use a Track Alias that was already in use”, and Section 8.7 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 Request 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.

held: u64

The request whose live subscription holds it.

MixedForwardingPreference

A track’s objects were framed two different ways.

Section 9: “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 Objects via both Subgroup streams and Datagrams in response to a SUBSCRIBE, 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.

What this draft reworded

The prohibition is the one drafts 07 through 10 state; the sentence after it is not. This draft names the two framings the rule is about rather than “different forwarding preferences”, and scopes it to objects answering a SUBSCRIBE — which is where its Section 9.1.1 puts the definition as well: “When in response to a SUBSCRIBE, an Object MUST be sent according to its Object Forwarding Preference”. A fetch stream is neither framing and settles nothing here either way.

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 9.1.1.1 describes Object Status 0x4, end of Track, as one whose “GroupID is either the largest group produced in this track and the ObjectID is one greater than the largest object produced in that group, or GroupID is one greater than the largest group produced in this track and the ObjectID is zero”, and states the consequence: “An object with this status that has a Group ID less than any other GroupID, or an ObjectID less than or equal to the largest in the specified group, is a protocol error, and the receiver MUST terminate the session.”

What this draft merged

Drafts 08 through 10 spell this against a status that means end of Track and Group, and carry a second status beside it for the end of the Track alone. This draft folded the two into 0x4 and kept the looser of the two conditions, which is why the Group ID may equal the largest group here and may not there.

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.

UpdateForUnknownRequest(u64)

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

Section 8.10: “A publisher SHOULD close the Session as a ‘Protocol Violation’ if the SUBSCRIBE_UPDATE violates either rule or if the subscriber specifies a Request 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 8.13: “If a publisher receives a Joining Fetch with a Request ID that does not correspond to an existing Subscribe in the same session, it MUST respond with a Fetch Error with code Invalid Joining Subscribe ID.”

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.

WrongJoiningRefusal

A Joining Fetch was refused under a code other than the one the same sentence names for it.

The reason travels with the refusal, so a subscriber told the wrong one retries the wrong thing: it can rebuild a fetch whose range was refused, and cannot rebuild one whose subscription is gone.

Fields

fetch: u64

The fetch being refused.

required: u64

The code the draft names for that refusal.

UnknownPeerNamespace

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

Section 8.23 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 5.1: “An UNSUBSCRIBE_ANNOUNCES withdraws a previous SUBSCRIBE_ANNOUNCES.”

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 8.24: “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 Namespace Prefix Overlap.”

Taken when the message arrives, which is the moment the sentence names, and read again when an answer is built: a request this endpoint may not accept is one no later call can accept.

The refusal itself is not this error. It is a message the peer is owed, so the request is recorded like any other and refused through the same call that refuses any other, under the code the sentence names.

Fields

request: u64

The request that arrived.

established: u64

The namespace subscription it overlaps.

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 Request ID is spent, 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.

Fields

established: u64

The namespace subscription this endpoint already has.

WrongOverlapRefusal

A namespace subscription that overlaps another was refused under a code other than the one the sentence names.

The same shape as EndpointError::WrongJoiningRefusal: a rule that names the code its refusal carries is not satisfied by a refusal under any other, because the peer reads the code to learn what went wrong.

Fields

request: u64

The request being refused.

required: u64

The code the sentence names for it.

Implementations

impl EndpointError

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

The code to close the session with, when draft-11 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<RequestIdError> for EndpointError

fn from(source: RequestIdError) -> 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<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.