walrq-client 0.1.0

Async high-performance client SDK for the walrq distributed queue engine
Documentation

walrq-client

Async high-performance client SDK for the walrq distributed queue engine.

Features

  • Automatic Cluster Discovery & Topology Routing: Connects to seed nodes and tracks partition leaders automatically.
  • Connection Pooling: Multiplexes requests across pooled persistent TCP connections.
  • Transparent Wire Compression: Zstd compression on wire payloads over 64 bytes.
  • Client-Side Micro-Batching: Sharded buffer channels batch concurrent pushes into efficient bulk network operations.

Installation

Add to Cargo.toml:

[dependencies]
walrq-client = "0.1.0"
bytes = "1.10"
tokio = { version = "1", features = ["full"] }

Or via CLI:

cargo add walrq-client

Quick Start

use bytes::Bytes;
use walrq_client::{ClientConfig, WalrClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to cluster seed nodes
    let seeds = vec!["127.0.0.1:50051".to_string()];
    let client = WalrClient::with_config(seeds, ClientConfig::default());

    // Producer: push single message
    let msg_id = client.push("jobs", Bytes::from("task-payload"), 0).await?;
    println!("Enqueued message: {}", msg_id);

    // Producer: push batch
    let batch = vec![Bytes::from("task-1"), Bytes::from("task-2")];
    let ids = client.push_batch("jobs", batch).await?;
    println!("Enqueued batch IDs: {:?}", ids);

    // Consumer: poll messages (queue, visibility_timeout_sec, batch_size)
    let messages = client.poll("jobs", 30, 10).await?;
    for msg in messages {
        println!("Received: {} (body: {:?})", msg.message_id, msg.payload);

        // Acknowledge processed message
        let acked = client.ack("jobs", &msg.message_id, &msg.receipt_handle).await?;
        println!("Ack status: {}", acked);
    }

    Ok(())
}

Repository

Source code and server engine: https://github.com/bri0/walr-queue

License

MIT