pub enum EndpointError {
Show 31 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,
DuplicateRequestId(u64),
NotARequest(MessageType),
NotAResponse(MessageType),
UnexpectedOnPeerRequestStream(MessageType),
NoUpdateToAnswer(u64),
WrongUpdateFailureStatus {
request: u64,
required: u64,
},
NotActive,
Draining,
RepeatedGoAway,
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,
},
OwnPrefixOverlap {
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 9.16: “the subscriber cannot send REQUEST_UPDATE”. A track status is the one request kind that sentence excludes, and Section 9.10’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-17 Section 9.10: “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-17’s message table has no Stream column — drafts 18 and 19 added one — so the placement is stated in the prose of each message’s own section, and all three say the same thing. NAMESPACE (0x8) “is sent on the response stream of a SUBSCRIBE_NAMESPACE request” (Section 9.18). “All NAMESPACE_DONE messages are in response to a SUBSCRIBE_NAMESPACE” (Section 9.19), and “All PUBLISH_BLOCKED messages are in response to a SUBSCRIBE_NAMESPACE” (Section 9.21) — draft-17 has no SUBSCRIBE_TRACKS, so its PUBLISH_BLOCKED answers the same request the other two do.
Section 9.20 makes the stream the correlation: the publisher “will send matching NAMESPACE messages on the response stream”. 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-17 Section 9.5: “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-17 Section 9.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-17 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 is not one of this draft’s responses 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.
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.10 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 9.10.1: “When a subscription update is unsuccessful, the publisher MUST also terminate the subscription with PUBLISH_DONE with error code UPDATE_FAILED.” Drafts 18 and 19 reword it as “When a REQUEST_UPDATE is unsuccessful … by sending a PUBLISH_DONE”, which is the same obligation a wording later.
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.
DuplicateTrackAlias
The peer named a Track Alias it is already using for another track.
Draft-17 states it twice, once per message. Section 9.9: “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 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.” Section 9.11 is the same sentence with PUBLISH in place of SUBSCRIBE_OK.
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 9.11 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 on a Track 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.1 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 9.14.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 9.20: “A subscriber cannot make overlapping namespace subscriptions on a single session. Within a session, if a publisher receives a SUBSCRIBE_NAMESPACE with a Track Namespace Prefix that shares a common prefix with an established namespace subscription, it MUST respond with REQUEST_ERROR with error code 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
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.” Drafts 18 and 19 drop it, and neither has this error.
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.
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-17 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 9.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()