Enum Error 

#[non_exhaustive]
pub enum Error {
    Transport {
        context: &'static str,
        source: Error,
    },
    ConnectionClosed {
        peer: String,
    },
    Timeout {
        api_key: ApiKey,
        elapsed: Duration,
    },
    Authentication(String),
    Authorization(ErrorCode),
    Broker {
        code: ErrorCode,
        message: Option<String>,
    },
    Decode {
        context: &'static str,
        source: Box<dyn Error + Sync + Send>,
    },
    ReadOnly {
        api_key: ApiKey,
    },
    UnsupportedApi {
        api_key: ApiKey,
        broker: Option<(i16, i16)>,
        ours: Option<(i16, i16)>,
    },
    Unsupported(String),
    InvalidRequest(String),
}

The error taxonomy, re-exported.

One type across the workspace: see the crate docs for why it is defined a layer down. Anything that can go wrong talking to a broker.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Transport

The socket failed, or never opened.

Fields

context: &'static str

What we were doing.

source: Error

The underlying I/O error.

ConnectionClosed

The connection is gone. Every in-flight request resolves to this rather than hanging — a UI backend that leaks a hung future per dead broker stops working long before anyone notices why.

Fields

peer: String

Which broker, for the log line that follows.

Timeout

The caller’s deadline passed.

Fields

api_key: ApiKey

The request that ran out of time.

elapsed: Duration

How long it had.

Authentication(String)

The credentials were rejected, or the handshake could not agree.

Authorization(ErrorCode)

The principal authenticated but is not permitted to do this.

Broker

The broker answered with an error code.

Fields

code: ErrorCode

The classified code.

message: Option<String>

The broker’s own message, when the response carries one.

Decode

A response did not parse.

Distinct from every other variant because it means we are wrong: a version negotiated badly, or a schema drifted.

Fields

context: &'static str

What we were decoding.

source: Box<dyn Error + Sync + Send>

The underlying decode failure.

ReadOnly

A read-only client refused a mutating request before touching the network. See ApiKey::is_mutating.

Fields

api_key: ApiKey

The key that was refused.

UnsupportedApi

No version of this API is speakable by both ends.

Usually our side is the binding one: kafka-protocol 0.17 ships Kafka 4.0 schemas and the broker is newer.

Fields

api_key: ApiKey

The key.

broker: Option<(i16, i16)>

The broker’s (min, max), if it advertised the key at all.

ours: Option<(i16, i16)>

Our (min, max), if this build knows the key.

Unsupported(String)

The caller asked for something the protocol or this build cannot express — an unnamed API key, a sentinel that needs a schema version we cannot encode. An honest blocker, not a workaround.

InvalidRequest(String)

A request was malformed before it went out.

Implementations

impl Error

pub fn transport(context: &'static str, source: Error) -> Error

Wrap an I/O error with context.

pub fn decode( context: &'static str, source: impl Into<Box<dyn Error + Sync + Send>>, ) -> Error

Wrap a decode failure with context.

pub fn from_code(code: ErrorCode, message: Option<String>) -> Error

Build the right variant for a broker error code.

Authentication and authorization codes are lifted out of Error::Broker here rather than at every call site, because a caller that forgets renders “not authorized” as a generic failure.

pub fn code(&self) -> Option<ErrorCode>

The broker code, when there is one.

pub fn retriable(&self) -> bool

Whether retrying could plausibly succeed.

A dead connection counts: the pool will open a new one. A decode failure does not — retrying a schema mismatch just burns the same bytes again.

pub fn needs_metadata_refresh(&self) -> bool

Whether handling this error should refresh the metadata snapshot.

pub fn needs_coordinator_refresh(&self) -> bool

Whether handling this error should invalidate a cached coordinator.

Trait Implementations

impl Clone for Error

One failure often has to be reported to many callers: every record in a rejected produce batch, every partition in a request whose connection died. Without Clone each of those sites has to invent a way to fan an error out, and they invent different ones.

Two variants cannot be duplicated faithfully and are reconstructed:

• Error::Transport keeps its std::io::ErrorKind and its rendering, but a cloned io::Error loses the raw OS error code.
• Error::Decode keeps its source’s rendering rather than its concrete type, so downcasting the clone will not find the original.

Everything Error::retriable, Error::code, Error::needs_metadata_refresh and Display read is preserved exactly, which is the whole of what callers branch on. Derived rather than hand- written is not an option — io::Error and a boxed source are not Clone.

fn clone(&self) -> Error

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Error for Error

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.