Enum EndpointError 

pub enum EndpointError {
    Session(SessionError),
    RequestId(RequestIdError),
    Subscription(SubscriptionError),
    Fetch(FetchError),
    Fill(FillError),
    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,
    GoAwayFromRequestSender(u64),
    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,
    },
    ObjectExistenceContradicted {
        namespace: TrackNamespace,
        name: Vec<u8>,
        group: u64,
        object: u64,
    },
    StateNotifyForNonSubscription(u64),
    StateNotifyFromSubscriber(u64),
    StateNotifyThisEndpointMayNotSend(u64),
    UnrequestedFillStream(u64),
}

Errors that can occur during endpoint operations.

Variants

Session(SessionError)

RequestId(RequestIdError)

Subscription(SubscriptionError)

Fetch(FetchError)

Fill(FillError)

A LOCATION_FILTER or FILL_PARAMETERS value this endpoint was asked to build is one draft-23 does not define. Nothing was written.

Namespace(NamespaceError)

TrackStatus(TrackStatusError)

PublishFlow(PublishError)

Setup(SetupError)

UnknownRequest(u64)

ResponseOnControlStream

RequestUpdateOnControlStream

A REQUEST_UPDATE arrived on the control stream.

Draft-23 Table 5 gives REQUEST_UPDATE the Stream value “Request”, and Section 9.5 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 9.5 says MUST close the session.

RequestMessageOnControlStream(&'static str)

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

Draft-23 Table 5 gives all three the Stream value “Request”: NAMESPACE (0x8, Section 9.15) and NAMESPACE_DONE (0xE, Section 9.16) belong on the SUBSCRIBE_NAMESPACE request stream whose namespace they report, and PUBLISH_SKIPPED (0xF, Section 9.18) 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-23 Section 9.5: “An endpoint that receives a REQUEST_UPDATE other than in the two cases above MUST close the session with UNEXPECTED_MESSAGE.” TRACK_STATUS is called out in Section 9.12 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-23 Section 9.3: 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 INVALID_FIELD.”

RedirectUriAtServer

A server received a Redirect naming a Connect URI.

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

RedirectTrackNameOnNamespaceRequest(u64)

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

Draft-23 Section 9.4.2.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 INVALID_FIELD.”

GoAwayUriAtServer

A server received a GOAWAY carrying a New Session URI.

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

DuplicateRequestId(u64)

The peer reused a Request ID it had already spent.

Draft-23 Section 6.4.2.1: “If an endpoint receives a Request ID where the least significant bit is incorrect for the sender, it MUST close the session with INVALID_REQUEST_ID. If an endpoint detects 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-23 Section 6.3: “Bidirectional streams MUST NOT begin with any other message type unless negotiated. If they do, the peer MUST close the Session with UNEXPECTED_MESSAGE.”

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-23 Section 4.2, of SUBSCRIBE_NAMESPACE: “The publisher MUST send a single SUBSCRIBE_NAMESPACE_OK or SUBSCRIBE_NAMESPACE_ERROR as the first message on the response half of the stream; if the subscriber receives any other message first, it MUST close the session with UNEXPECTED_MESSAGE.” Section 3.6 says the same of SUBSCRIBE_TRACKS. Both names are Section 1.5’s shorthand for a REQUEST_OK and a REQUEST_ERROR.

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 9.3 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-23 Section 9.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 3.3.2 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 9.5 requires “exactly one REQUEST_UPDATE_OK or REQUEST_UPDATE_ERROR message indicating if the update was successful” — a REQUEST_OK or a REQUEST_ERROR, under Section 1.5’s names — 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, so on its stream 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 9.5.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.

GoAwayFromRequestSender(u64)

A GOAWAY on a request stream the peer opened.

Section 9.2: “Only the receiver of a request can send GOAWAY on its request stream. If the receiver of a request receives a GOAWAY on that request stream, it MUST close the session with a PROTOCOL_VIOLATION.”

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-23 Section 3.1.3: “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 3.1.3 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 12.1 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.”

Larger is Section 8.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 12.1 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 6.4.2.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.

ObjectExistenceContradicted

An Object both received and signalled as not existing.

Section 12.1: “An Object is received after it has been recorded as not existing, or is signalled as not existing after it was received (see Section 2.1.2).” Section 10.8 states the Prior Group ID Gap cases: “An endpoint receives an Object with a Prior Group ID Gap covering an Object it previously received” and “An endpoint receives an Object with a Group ID within a previously communicated gap.” A Malformed Track, answered by cancelling the track’s requests, not by a session close.

Fields

namespace: TrackNamespace

The Track Namespace of the track both signals are about.

name: Vec<u8>

The Track Name of the track both signals are about.

group: u64

The Group ID both signals name.

object: u64

The Object ID both signals name.

StateNotifyForNonSubscription(u64)

A PUBLISH_STATE_NOTIFY arrived for a request that is not a subscription.

Section 9.10: “PUBLISH_STATE_NOTIFY applies only to subscriptions, and is sent only by the publisher. An endpoint that receives a PUBLISH_STATE_NOTIFY for any other request type MUST close the session with UNEXPECTED_MESSAGE. A publisher that receives a PUBLISH_STATE_NOTIFY MUST close the session with ROLE_VIOLATION.”

This is the first half of that sentence. 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.

StateNotifyFromSubscriber(u64)

A PUBLISH_STATE_NOTIFY arrived from the subscriber.

The second half of the same sentence. A subscription’s publisher is the end that did not send the SUBSCRIBE, so one arriving on a stream this endpoint opened with a SUBSCRIBE is the publisher’s and one arriving on a stream the peer opened with a SUBSCRIBE is the subscriber’s — which is what this refuses, and what the section answers with a session close.

StateNotifyThisEndpointMayNotSend(u64)

A PUBLISH_STATE_NOTIFY was offered for a request this endpoint does not publish a subscription for. Nothing was written and no state moved.

The send-side mirror of the two above, and not fatal for the same reason EndpointError::TrackPropertiesOnOutgoingRequestOk is not: nothing reached the wire, so there is nothing for the peer to object to. What it prevents is handing a conforming peer a message Section 9.10 tells it to close the session over.

UnrequestedFillStream(u64)

A fill fetch stream opened against a request that asked for no fill.

Section 9.19.15 makes FILL_PARAMETERS the whole of the request: “A fill fetch stream is opened only when FILL_PARAMETERS is present.” A FETCH_HEADER naming a subscription that never asked is a stream this endpoint has nothing to attribute, and one naming a request that is not a subscription at all is worse.

Not a session close. Draft-23 states no rule for it — a fill fetch stream has no FETCH_OK and no REQUEST_ERROR, so there is no answer to send and no sentence naming a code — and the honest handling is STOP_SENDING on that stream alone, which Section 3.4.1 gives the subscriber outright and says “does not affect the subscription”.

Implementations

impl EndpointError

pub fn fault(&self) -> EndpointFault

Whose doing this is — the peer’s, or this endpoint’s, or a variant that cannot say.

The companion of EndpointError::session_error_code, which answers what the draft requires be done about it. Neither answers the other’s question and the pair is what a caller needs: a code without a side names nobody, and a side without a code is not grounds to publish anything.

Exhaustive, with no wildcard arm, so a variant added to this draft’s EndpointError is a compile error here rather than a silent arrival on the wrong side of the answer. See EndpointFault for the three answers and for the collision that made the third one necessary.

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

The code to close the session with, when draft-23 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.

Each code is the one the sentence stating the rule names (draft-23 Section 12.2 defines them).

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

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