Crate kubemq 

KubeMQ Rust SDK

Client library for the KubeMQ message broker. Supports Events, Events Store, Commands, Queries, and Queues messaging patterns over gRPC with automatic reconnection, TLS/mTLS, and structured error handling.

Features

• Events (Pub/Sub) — fire-and-forget fan-out messaging via Event
• Events Store — persistent events with replay via EventStore and EventsStoreSubscription
• Queues — transactional message queues with ack/nack/requeue via QueueMessage
• Commands — request-response with timeout via Command and CommandResponse
• Queries — request-response with caching via Query and QueryResponse
• Auto-reconnection — configurable retry with exponential backoff via RetryPolicy
• TLS / mTLS — secure connections via TlsConfig
• Auth tokens — static or dynamic authentication via CredentialProvider

Quick Start

use kubemq::prelude::*;

#[tokio::main]
async fn main() -> kubemq::Result<()> {
    let client = KubemqClient::builder()
        .host("localhost")
        .port(50000)
        .build()
        .await?;

    let info = client.ping().await?;
    println!("Connected to {} v{}", info.host, info.version);

    client.close().await?;
    Ok(())
}

Error Handling

All fallible operations return Result<T>, which is an alias for std::result::Result<T, KubemqError>. Use KubemqError::is_retryable() to determine if an operation can be retried, and KubemqError::code() for machine-readable classification.

Modules

channel_type

String constants identifying the five KubeMQ channel types.

prelude

Commonly used types and traits re-exported for convenience.

queue_downstream_type

Backward-compatible i32 constants for QueueDownstreamType variants.

Structs

AckAllQueueMessagesRequest

Request to acknowledge all pending messages in a queue channel.

AckAllQueueMessagesResponse

Response from an acknowledge-all queue messages operation.

ChannelInfo

Information about a KubeMQ channel returned by KubemqClient::list_channels().

ChannelStats

Directional message statistics for a channel.

ClientConfig

Client configuration for connecting to a KubeMQ broker.

ClientConfigBuilder

Builder for creating a ClientConfig and connecting a KubemqClient.

Command

Outbound command request for the RPC (Command/Query) pattern.

CommandBuilder

Builder for constructing Command instances using a fluent API.

CommandReceive

A command received from a subscription callback.

CommandReply

Outbound command reply sent by a subscriber via KubemqClient::send_command_response().

CommandReplyBuilder

Builder for constructing CommandReply instances using a fluent API.

CommandResponse

Response received after sending a command via KubemqClient::send_command().

Event

Outbound fire-and-forget event message for the Pub/Sub pattern.

EventBuilder

Builder for constructing Event instances using a fluent API.

EventReceive

An event received from a subscription callback.

EventStore

Outbound persistent event message for the Events Store (Pub/Sub) pattern.

EventStoreBuilder

Builder for constructing EventStore instances using a fluent API.

EventStoreReceive

A persistent event received from an Events Store subscription callback.

EventStoreResult

Result of a single event store send operation.

EventStoreStreamHandle

Handle for a bidirectional event store send stream.

EventStreamHandle

Handle for a bidirectional event send stream.

EventStreamResult

Per-event result returned from a streaming send via EventStreamHandle.

KubemqClient

Thread-safe KubeMQ client. Clone is cheap (Arc-based).

PollRequest

Configuration for a queue poll operation.

PollResponse

Response from a queue poll operation containing received messages.

Query

Outbound query request for the RPC (Command/Query) pattern.

QueryBuilder

Builder for constructing Query instances using a fluent API.

QueryReceive

A query received from a subscription callback.

QueryReply

Outbound query reply sent by a subscriber via KubemqClient::send_query_response().

QueryReplyBuilder

Builder for constructing QueryReply instances using a fluent API.

QueryResponse

Response received after sending a query via KubemqClient::send_query().

QueueDownstreamMessage

A received queue message with per-message settlement methods.

QueueDownstreamReceiver

Persistent queue downstream receiver for polling and settling messages.

QueueMessage

A message for the Queue (point-to-point) messaging pattern.

QueueMessageAttributes

Server-assigned attributes present on received queue messages.

QueueMessageBuilder

Builder for constructing QueueMessage instances using a fluent API.

QueuePolicy

Delivery policy for a queue message.

QueueSendResult

Result of a single queue message send operation.

QueueUpstreamHandle

Handle for a bidirectional queue upstream (send) stream.

QueueUpstreamResult

Per-batch result from a queue upstream send operation.

RetryPolicy

Retry policy for transient operation errors and subscription reconnection.

ServerInfo

Information about the KubeMQ broker returned by KubemqClient::ping().

StaticTokenProvider

A CredentialProvider that returns a fixed token with no expiration.

Subscription

Handle for an active event, event-store, command, or query subscription.

TlsConfig

TLS configuration for connecting to a KubeMQ server.

Enums

ConnectionState

The connection state of a KubemqClient.

ErrorCode

Machine-readable error codes for classifying KubemqError variants.

EventsStoreSubscription

Specifies where an Events Store subscription should begin reading.

JitterMode

Jitter mode applied to exponential backoff calculations.

KubemqError

The primary error type returned by all SDK operations.

QueueDownstreamType

Request types for the queue downstream stream protocol.

Constants

VERSION

SDK version string.

Traits

CredentialProvider

Credential provider for authentication.

Type Aliases

AsyncCallback

Async callback signature for subscription message handlers.

AsyncNotifyCallback

Async notification callback for lifecycle events.

Result

Convenience alias for std::result::Result<T, KubemqError>.