pub enum EndpointError {
Show 35 variants
Session(SessionError),
RequestId(RequestIdError),
Subscription(SubscriptionError),
Fetch(FetchError),
Namespace(NamespaceError),
TrackStatus(TrackStatusError),
PublishFlow(PublishError),
Setup(SetupError),
UnknownRequest(u64),
NotASubscription(u64),
ResponseOnControlStream,
RequestUpdateOnControlStream,
RequestMessageOnControlStream(&'static str),
GoAwayUriAtServer,
TrackPropertiesOnNonTrackStatus(u64),
RedirectUriAtServer,
RedirectTrackNameOnNamespaceRequest(u64),
DuplicateRequestId(u64),
NotARequest(MessageType),
NotAResponse(MessageType),
UnexpectedOnPeerRequestStream(MessageType),
ResponseBeforeTheFirstResponse(u64, MessageType),
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,
},
}Expand description
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)
NotASubscription(u64)
A REQUEST_UPDATE named a track status.
Section 10.14: “the subscriber cannot send REQUEST_UPDATE”. A track status is the one request kind that sentence excludes, and Section 10.9’s list of the requests an update may modify leaves it out for the same reason.
Separate from EndpointError::UnknownRequest, which says the
identifier names nothing at all. This one says it names something, and
that what it names cannot be updated.
ResponseOnControlStream
RequestUpdateOnControlStream
A REQUEST_UPDATE arrived on the control stream.
Draft-18 Section 10.9: “The sender of a request … can later send a REQUEST_UPDATE on the same bidi stream as the request to modify it.” The stream is what names the request being modified, so a REQUEST_UPDATE with no stream around it identifies nothing.
RequestMessageOnControlStream(&'static str)
A NAMESPACE, NAMESPACE_DONE or PUBLISH_BLOCKED arrived on the control stream.
Draft-18 Table 5 gives all three the Stream value “Request”. NAMESPACE (0x8) “is sent on the response stream of a SUBSCRIBE_NAMESPACE request” (Section 10.16) and NAMESPACE_DONE (0xE) answers the same request — “All NAMESPACE_DONE messages are in response to a SUBSCRIBE_NAMESPACE” (Section 10.17). PUBLISH_BLOCKED (0xF) answers the other one: “All PUBLISH_BLOCKED messages are in response to a SUBSCRIBE_TRACKS” (Section 10.20). 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 there is nothing it could be reporting on.
GoAwayUriAtServer
A server received a GOAWAY carrying a New Session URI.
Draft-18 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.
TrackPropertiesOnNonTrackStatus(u64)
Track Properties arrived on a REQUEST_OK answering something other than a TRACK_STATUS.
Draft-18 Section 10.5: they “are populated in TRACK_STATUS_OK; 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-18 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-18 Section 10.6.1: “Track Name is not meaningful for namespace-scoped requests (SUBSCRIBE_NAMESPACE, PUBLISH_NAMESPACE) 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.”
DuplicateRequestId(u64)
The peer reused a Request ID it had already spent.
Draft-18 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-18 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-18 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.”
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.
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
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.
DuplicateTrackAlias
The peer named a Track Alias it is already using for another track.
Draft-18 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
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
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.2 describes. This is the error half; the
requests to cancel are named by
Endpoint::requests_for_malformed_track.
Fields
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.
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.
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
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.
Implementations§
Source§impl EndpointError
impl EndpointError
Sourcepub fn session_error_code(&self) -> Option<SessionErrorCode>
pub fn session_error_code(&self) -> Option<SessionErrorCode>
The code to close the session with, when draft-18 says this error is fatal to the session rather than to one request.
None means the error is recoverable: the caller may report it, reset
the one stream it concerns, 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§
Source§impl Debug for EndpointError
impl Debug for EndpointError
Source§impl Display for EndpointError
impl Display for EndpointError
Source§impl Error for EndpointError
impl Error for EndpointError
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()