Result Type

The SDK defines a type alias for all operations:

pub type Result<T> = std::result::Result<T, KubemqError>;

Use the ? operator to propagate errors through kubemq::Result<()>.

KubemqError

The primary error type returned by all SDK operations. Each variant carries context including a machine-readable ErrorCode, human-readable message, and recovery suggestion.

Variant	Code	Retryable	Description
`Transient`	`Transient`	Yes	Temporary failure (gRPC UNAVAILABLE, UNKNOWN, ABORTED)
`Timeout`	`Timeout`	Yes	Operation timed out (gRPC DEADLINE_EXCEEDED)
`Throttling`	`Throttling`	Yes	Rate limited (gRPC RESOURCE_EXHAUSTED)
`Authentication`	`Authentication`	No	Invalid/expired auth token (gRPC UNAUTHENTICATED)
`Authorization`	`Authorization`	No	Insufficient permissions (gRPC PERMISSION_DENIED)
`Validation`	`Validation`	No	Invalid request (empty channel, bad params)
`NotFound`	`NotFound`	No	Resource not found (gRPC NOT_FOUND)
`Fatal`	`Fatal`	No	Unrecoverable server error
`Cancellation`	`Cancellation`	No	Operation cancelled
`BufferFull`	`Backpressure`	No	Internal send buffer full
`StreamBroken`	`Transient`	No	Stream broken with unacknowledged messages
`ClientClosed`	`Fatal`	No	Client has been closed
`Transport`	`Fatal`	No	Low-level transport failure
`Handler`	`Fatal`	No	User callback returned an error

Error Methods

Method	Returns	Description
`is_retryable()`	`bool`	Whether the operation may succeed on retry
`code()`	`ErrorCode`	Machine-readable error classification
`suggestion()`	`&str`	Human-readable recovery guidance

Pattern Matching

main.rs

use kubemq::{ErrorCode, KubemqError};

match err.code() {
    ErrorCode::Transient => println!("Retry with backoff"),
    ErrorCode::Timeout => println!("Increase timeout"),
    ErrorCode::Authentication => println!("Check auth token"),
    ErrorCode::Validation => println!("Fix: {}", err.suggestion()),
    _ => println!("Error: {}", err),
}

Destructuring

main.rs

match result {
    Err(KubemqError::Validation { code, message, suggestion, .. }) => {
        println!("Code: {:?}, Message: {}, Suggestion: {}", code, message, suggestion);
    }
    Err(KubemqError::Transient { is_retryable, request_id, .. }) => {
        println!("Retryable: {}, Request: {}", is_retryable, request_id);
    }
    _ => {}
}

ErrorCode

Machine-readable error classification enum.

Variant	gRPC Codes	Retryable
`Transient`	UNKNOWN, ABORTED, UNAVAILABLE	Yes
`Timeout`	DEADLINE_EXCEEDED	Yes
`Throttling`	RESOURCE_EXHAUSTED	Yes
`Authentication`	UNAUTHENTICATED	No
`Authorization`	PERMISSION_DENIED	No
`Validation`	INVALID_ARGUMENT, ALREADY_EXISTS, FAILED_PRECONDITION, OUT_OF_RANGE	No
`NotFound`	NOT_FOUND	No
`Fatal`	UNIMPLEMENTED, INTERNAL, DATA_LOSS	No
`Cancellation`	CANCELLED	No
`Backpressure`	N/A (internal buffer full)	No

Subscription

Handle returned by subscribe_to_* methods. Use it to cancel an active subscription.

Method	Description
`unsubscribe()`	Cancel the subscription and wait for cleanup
`done()`	Wait until the subscription task completes

AsyncCallback

Type alias for subscription message handlers:

pub type AsyncCallback<T> =
    Box<dyn Fn(T) -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync>;

Used with Box::pin(async move { ... }) in subscription callbacks.

Types & Errors