Enum EndpointError 

pub enum EndpointError {
    Session(SessionError),
    RequestId(RequestIdError),
    Subscription(SubscriptionError),
    Fetch(FetchError),
    Namespace(NamespaceError),
    TrackStatus(TrackStatusError),
    PublishFlow(PublishError),
    Setup(SetupError),
    UnknownRequest(u64),
    ResponseOnControlStream,
    RequestUpdateOnControlStream,
    RequestMessageOnControlStream(&'static str),
    UnexpectedRequestUpdate(u64),
    TrackPropertiesOnNonTrackStatus(u64),
    RedirectUriAtServer,
    RedirectTrackNameOnNamespaceRequest(u64),
    GoAwayUriAtServer,
    DuplicateRequestId(u64),
    NotARequest(MessageType),
    NotAResponse(MessageType),
    UnexpectedOnPeerRequestStream(MessageType),
    ResponseBeforeTheFirstResponse(u64, MessageType),
    TrackPropertiesOnOutgoingRequestOk(u64),
    TooManyRequestUpdates(u64, u64),
    FilterMustBeRejected(u64, FilterRejection),
    NoUpdateToAnswer(u64),
    WrongUpdateFailureStatus {
        request: u64,
        required: u64,
    },
    NotActive,
    Draining,
    RepeatedGoAway,
    RepeatedGoAwayOnRequestStream(u64),
    DuplicateTrackAlias {
        alias: u64,
        established: u64,
        offered: u64,
    },
    TrackAliasInUse {
        alias: u64,
        held: u64,
    },
    ObjectPastFinalObject {
        alias: u64,
        group: u64,
        object: u64,
        final_group: u64,
        final_object: u64,
    },
    UnjoinableSubscription {
        fetch: u64,
        joining: u64,
    },
    WrongJoiningRefusal {
        fetch: u64,
        required: u64,
    },
    PeerPrefixOverlap {
        request: u64,
        established: u64,
    },
    WrongOverlapRefusal {
        request: u64,
        required: u64,
    },
}

Errors that can occur during endpoint operations.

Variants

Session(SessionError)

RequestId(RequestIdError)

Subscription(SubscriptionError)

Fetch(FetchError)

Namespace(NamespaceError)

TrackStatus(TrackStatusError)

PublishFlow(PublishError)

Setup(SetupError)

UnknownRequest(u64)

ResponseOnControlStream

RequestUpdateOnControlStream

A REQUEST_UPDATE arrived on the control stream.

Draft-19 Table 5 gives REQUEST_UPDATE the Stream value “Request”, and Section 10.9 requires it on the same bidi stream as the request it modifies. One on the control stream modifies nothing, which makes it a case Section 10.9 says MUST close the session.

RequestMessageOnControlStream(&'static str)

A NAMESPACE, NAMESPACE_DONE or PUBLISH_SKIPPED arrived on the control stream.

Draft-19 Table 5 gives all three the Stream value “Request”: NAMESPACE (0x8, Section 10.16) and NAMESPACE_DONE (0xE, Section 10.17) belong on the SUBSCRIBE_NAMESPACE request stream whose namespace they report, and PUBLISH_SKIPPED (0xF, Section 10.20) on the SUBSCRIBE_TRACKS stream whose namespace it names a skipped track in — “All PUBLISH_SKIPPED messages are in response to a SUBSCRIBE_TRACKS”. Only SETUP is “Control” alone; GOAWAY is the one message the table lists as “Control, Request”. One of these three on the control stream names no request, so nothing can be done with it.

UnexpectedRequestUpdate(u64)

A REQUEST_UPDATE named a request that cannot be updated, or none.

Draft-19 Section 10.9: “An endpoint that receives a REQUEST_UPDATE other than in the two cases above MUST close the session with a PROTOCOL_VIOLATION.” TRACK_STATUS is called out in Section 10.14 as one such case: “the subscriber cannot send REQUEST_UPDATE.”

TrackPropertiesOnNonTrackStatus(u64)

Track Properties on a REQUEST_OK answering something other than a TRACK_STATUS.

Draft-19 Section 10.5: they “are empty in PUBLISH_OK, REQUEST_UPDATE_OK, SUBSCRIBE_NAMESPACE_OK and PUBLISH_NAMESPACE_OK. If an endpoint receives Track Properties in one of these messages it MUST close the session with a PROTOCOL_VIOLATION.”

RedirectUriAtServer

A server received a Redirect naming a Connect URI.

Draft-19 Section 10.6.1: “If a server receives a Redirect with a non-zero Connect URI Length it MUST close the session with a PROTOCOL_VIOLATION.” As with GOAWAY, only a client is redirected.

RedirectTrackNameOnNamespaceRequest(u64)

A Redirect answering a namespace-scoped request carried a Track Name.

Draft-19 Section 10.6.1: “Track Name is not meaningful for namespace-scoped requests (SUBSCRIBE_NAMESPACE, PUBLISH_NAMESPACE, SUBSCRIBE_TRACKS) and MUST be empty; an endpoint that receives a non-empty Track Name in a Redirect for a namespace-scoped request MUST close the session with a PROTOCOL_VIOLATION.” Draft-18 names the same rule with SUBSCRIBE_TRACKS left out of the list.

GoAwayUriAtServer

A server received a GOAWAY carrying a New Session URI.

Draft-19 Section 10.4: “If a server receives a GOAWAY with a non-zero New Session URI Length it MUST close the session with a PROTOCOL_VIOLATION.” Only a client can be redirected.

DuplicateRequestId(u64)

The peer reused a Request ID it had already spent.

Draft-19 Section 10.1: “If an endpoint receives a Request ID where the least significant bit is incorrect for the sender, or a duplicate Request ID, it MUST close the session with INVALID_REQUEST_ID.”

NotARequest(MessageType)

A bidirectional stream the peer opened began with a message that does not open a request stream.

Draft-19 Section 3.3: “Bidirectional streams MUST NOT begin with any other message type unless negotiated. If they do, the peer MUST close the Session with a PROTOCOL_VIOLATION.”

NotAResponse(MessageType)

A message that this endpoint may not write on a request stream the peer opened was handed to the responder path. Nothing was written and no state moved.

UnexpectedOnPeerRequestStream(MessageType)

A message arrived on a request stream the peer opened that may not follow a request there.

This endpoint is the responder on such a stream, so a response arriving on it is the peer answering its own request.

ResponseBeforeTheFirstResponse(u64, MessageType)

A namespace-scoped request’s response half opened with something other than REQUEST_OK or REQUEST_ERROR.

Draft-19 Sections 10.18 and 10.19, of SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS alike: “The publisher will respond with REQUEST_OK or REQUEST_ERROR on the response half of the stream. If the subscriber receives any message other than a REQUEST_OK or a REQUEST_ERROR as the first message on the response half of the stream, then it MUST close the session with a PROTOCOL_VIOLATION.”

TrackPropertiesOnOutgoingRequestOk(u64)

Track Properties were put on a REQUEST_OK answering something other than a TRACK_STATUS, on the way out. Nothing was written.

The send-side mirror of TrackPropertiesOnNonTrackStatus: Section 10.5 answers receiving them with a session close, so writing them would hand a conforming peer a reason to close this session. This one is not fatal — nothing reached the wire, so there is nothing for the peer to object to.

TooManyRequestUpdates(u64, u64)

A REQUEST_UPDATE arrived on a stream that had already used up the concurrency this endpoint advertised.

Draft-19 Section 10.3.1.7: “If an endpoint receives a REQUEST_UPDATE on a stream that already has MAX_REQUEST_UPDATES outstanding REQUEST_UPDATEs, it MUST close the session with TOO_MANY_REQUEST_UPDATES.”

FilterMustBeRejected(u64, FilterRejection)

A REQUEST_OK was offered for a request whose Range Filters this endpoint is required to reject.

Not fatal, and deliberately not raised where the filter arrives. Every Range Filter rule in Section 5.1.3 is answered with a REQUEST_ERROR, and a REQUEST_ERROR names the Request ID of the request it answers — so the request has to be taken before it can be refused. What this stops is the other answer: accepting the request the draft says to reject leaves the subscriber with a subscription whose filters this endpoint never agreed to apply, and a publisher that then forwards by its own reading of them.

NoUpdateToAnswer(u64)

A REQUEST_OK or REQUEST_ERROR was offered as the answer to a REQUEST_UPDATE on a stream with no update waiting for one.

Section 10.9 requires “exactly one REQUEST_OK or REQUEST_ERROR message indicating if the update was successful”, so an answer with nothing to answer is one the peer will read as belonging to an update it never sent. Not fatal: nothing was written.

A SUBSCRIBE is answered with SUBSCRIBE_OK and a FETCH with FETCH_OK, so on those two streams a REQUEST_OK can be nothing but an update’s answer and this is what a mistimed one produces. On the five kinds REQUEST_OK answers itself, the first one is the request’s and only the ones after it can reach here.

WrongUpdateFailureStatus

An update was refused and the subscription it belongs to was then ended under some status other than the one that names why.

Section 10.9.1: “When a REQUEST_UPDATE is unsuccessful, the publisher MUST also terminate the subscription by sending a PUBLISH_DONE with error code UPDATE_FAILED.” The REQUEST_ERROR is half of what that sentence asks for and the termination is the other half, so this endpoint holds the request to it: whatever else the caller writes first, the termination it does write says so.

Fields

request: u64

The request whose update was refused.

required: u64

The status code the termination must carry.

NotActive

Draining

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.

RepeatedGoAwayOnRequestStream(u64)

A second GOAWAY arrived on one request’s stream.

The count is per stream rather than per session: this draft lets a GOAWAY migrate a single request, so one on each of two request streams is two first GOAWAYs and not a repeat.

Tuple Fields

0: u64

The Request ID of the stream that carried both.

DuplicateTrackAlias

The peer named a Track Alias it is already using for another track.

Draft-19 Section 11.1: “The same Track Alias MUST NOT be used by a publisher to refer to two different Tracks simultaneously in the same session. If a subscriber receives a PUBLISH or SUBSCRIBE_OK that uses the same Track Alias as a different Track with an Established subscription, it MUST close the session with error DUPLICATE_TRACK_ALIAS.”

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 Established 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 11.1 states it as a prohibition on the publisher before it states what the subscriber does about one: “The same Track Alias MUST NOT be used by a publisher to refer to two different Tracks simultaneously in the same session.”

The message is refused instead of built, and nothing else moves: no Request ID is spent, no publish flow 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 flow holds it.

ObjectPastFinalObject

An object arriving after the track’s final object.

Section 2.4.2 lists the condition: “An Object is received whose Group and Object ID are larger than the final Object in the Track. The final Object in a Track is the Object with Status END_OF_TRACK or the last Object sent in a FETCH whose response indicated End of Track.”

Larger is Section 1.4.2’s comparison and not a reading of the words. That section puts one Location below another when “A.Group < B.Group || (A.Group == B.Group && A.Object < B.Object)”, so an Object in a later group is past the end whatever its own Object ID is.

A Malformed Track and not a session error, and on this draft not a message either. Section 2.4.2 answers its whole list at once with “it MUST cancel any corresponding subscription or fetches for that Track from that publisher”, where cancelling a request is the transport operation Section 3.3.3 describes. This is the error half; the requests to cancel are named by Endpoint::requests_for_malformed_track.

Fields

alias: u64

The Track Alias the offending object named.

group: u64

The Group ID it named.

object: u64

The Object ID it named.

final_group: u64

The Group ID of the object the track ended at.

final_object: u64

The Object ID of the object the track ended at.

UnjoinableSubscription

A Joining Fetch named a subscription this session cannot join.

Section 10.12.2: “If a publisher receives a Joining Fetch with a Request ID that does not correspond to a subscription in the same session in the Established or Pending (subscriber) states, it MUST return a REQUEST_ERROR with error code INVALID_JOINING_REQUEST_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.

PeerPrefixOverlap

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

Section 10.18: “Within a session, if a publisher receives a SUBSCRIBE_NAMESPACE with a Track Namespace Prefix that shares a common prefix with an established SUBSCRIBE_NAMESPACE, it MUST respond with REQUEST_ERROR with error code PREFIX_OVERLAP.”

Section 10.19: “Within a session, if a publisher receives a SUBSCRIBE_TRACKS with a Track Namespace Prefix that shares a common prefix with an established SUBSCRIBE_TRACKS, it MUST respond with REQUEST_ERROR with error code PREFIX_OVERLAP.”

Section 10.6.2: “SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS have independent overlap spaces, so a SUBSCRIBE_NAMESPACE and a SUBSCRIBE_TRACKS may share the same prefix.”

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.

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-19 says this error is fatal to the session rather than to one request.

None means the error is recoverable: the caller may report it and keep the session running. Some means the draft requires a close, and the endpoint has already moved its own session state to SessionState::Closed — the code is what the transport should carry.

The two codes are not interchangeable. Section 3.3 gives PROTOCOL_VIOLATION for a bidirectional stream that begins with the wrong message type; Section 10.1 gives INVALID_REQUEST_ID for a Request ID with the wrong least significant bit or a duplicate one. A peer checking close codes can tell the two apart, so this must too.

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<PublishError> for EndpointError

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