muxis 0.3.0

High-performance Redis client for Rust with multiplexing
Documentation

Muxis

High-performance Redis client for Rust with multiplexing and cluster support

Version: 0.3.0 (Phase 3 Complete - Standalone API)

Rust License

Features

  • Complete RESP2 Protocol - Full Redis Serialization Protocol support
  • Multiplexed Connections - Multiple concurrent requests over single connection
  • Type-Safe Commands - Rust-native API with compile-time safety
  • 75+ Redis Commands - String, Hash, List, Set, Sorted Set operations
  • Connection Management - Timeouts, authentication, database selection
  • Security - Password and ACL authentication support
  • Production Ready - 192 tests (111 unit + 81 integration), zero warnings

Quick Start

use bytes::Bytes;
use muxis::{Client, Result};

#[tokio::main]
async fn main() -> Result<()> {
    // Connect to Redis
    let mut client = Client::connect("redis://127.0.0.1:6379").await?;

    // Set a value
    client.set("mykey", Bytes::from("Hello, Muxis!")).await?;

    // Get a value
    if let Some(value) = client.get("mykey").await? {
        println!("Value: {}", String::from_utf8_lossy(&value));
    }

    // Increment a counter
    let count = client.incr("counter").await?;
    println!("Counter: {}", count);

    // Delete keys
    client.del("mykey").await?;
    client.del("counter").await?;

    Ok(())
}

More examples available in the examples/ directory:

  • basic.rs - Basic Redis operations
  • builder.rs - Using ClientBuilder for configuration
  • pipeline.rs - Multiple commands in sequence
  • auth.rs - Authentication and database selection

Supported Commands

Phase 3 Complete: 75 Redis commands implemented across 5 categories

String Commands (7)

GET, SET, MGET, MSET, SETNX, SETEX, GETDEL, APPEND, STRLEN, INCR, DECR

Key Commands (8)

DEL, EXISTS, TYPE, EXPIRE, EXPIREAT, TTL, PERSIST, RENAME, SCAN

Hash Commands (13)

HSET, HGET, HMSET, HMGET, HGETALL, HDEL, HEXISTS, HLEN, HKEYS, HVALS, HINCRBY, HINCRBYFLOAT, HSETNX

List Commands (14)

LPUSH, RPUSH, LPOP, RPOP, LLEN, LRANGE, LINDEX, LSET, LREM, LTRIM, RPOPLPUSH, BLPOP, BRPOP, LPOS

Set Commands (13)

SADD, SREM, SPOP, SMEMBERS, SISMEMBER, SCARD, SRANDMEMBER, SDIFF, SINTER, SUNION, SDIFFSTORE, SINTERSTORE, SUNIONSTORE

Sorted Set Commands (20)

ZADD, ZREM, ZRANGE, ZRANGEBYSCORE, ZRANK, ZSCORE, ZCARD, ZCOUNT, ZINCRBY, ZREVRANGE, ZREVRANK, ZREMRANGEBYRANK, ZREMRANGEBYSCORE, ZPOPMIN, ZPOPMAX, BZPOPMIN, BZPOPMAX, ZLEXCOUNT, ZRANGEBYLEX, ZREMRANGEBYLEX

Connection Commands

PING, ECHO, AUTH, SELECT, CLIENT SETNAME

Usage Examples

Connection Configuration

use muxis::ClientBuilder;

let mut client = ClientBuilder::new()
    .address("redis://127.0.0.1:6379")
    .database(2)
    .build()
    .await?;

Basic Commands

use bytes::Bytes;

// String operations
client.set("user:1:name", Bytes::from("Alice")).await?;
let name = client.get("user:1:name").await?;

// Atomic operations
let views = client.incr("page:views").await?;
let likes = client.decr("post:dislikes").await?;

// Key deletion
client.del("key1").await?;
client.del("key2").await?;

// Ping server
let pong = client.ping().await?;

Multiplexed Concurrent Requests

use tokio::task;

// Spawn multiple concurrent requests
let handles: Vec<_> = (0..100)
    .map(|i| {
        let client = client.clone();
        task::spawn(async move {
            client.set(&format!("key:{}", i), &format!("value:{}", i)).await
        })
    })
    .collect();

// Wait for all requests to complete
for handle in handles {
    handle.await??;
}

Error Handling

use muxis::Error;

match client.get("mykey").await {
    Ok(Some(value)) => println!("Value: {:?}", value),
    Ok(None) => println!("Key not found"),
    Err(e) => println!("Error: {}", e),
}

Architecture

Muxis is organized as a single-crate library with well-defined modules:

Modules

  • muxis::proto: RESP protocol codec (encoder/decoder)
  • muxis::core: Connection management, multiplexing, and command execution
  • muxis::cluster: Cluster support (planned, feature-gated)
  • muxis::testing: Test utilities (feature-gated with test-utils)

Multiplexing Model

Muxis uses a sophisticated multiplexing architecture to handle concurrent requests efficiently:

┌─────────────────────────────────────────────────────────────┐
│                    MultiplexedConnection                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐         ┌──────────────┐                  │
│  │ Request Queue│ ──────> │ Writer Task  │ ────> TCP Socket │
│  │   (mpsc)     │         │              │                  │
│  └──────────────┘         └──────────────┘                  │
│                                                              │
│  ┌──────────────┐         ┌──────────────┐                  │
│  │ Pending Map  │ <────── │ Reader Task  │ <──── TCP Socket │
│  │ (VecDeque)   │         │              │                  │
│  └──────────────┘         └──────────────┘                  │
│                                                              │
│  Each request: Request sent via bounded channel              │
│  RESP ordered replies: Strict FIFO queue matching            │
└─────────────────────────────────────────────────────────────┘

Key Features:

  • Background writer task serializes commands and writes to socket
  • Background reader task reads frames and dispatches to waiting requests
  • Request ID tracking with oneshot channels for response delivery
  • Bounded request queue with backpressure
  • FIFO ordering guarantees for pipelined requests

Protocol Layer

The RESP2 protocol implementation provides:

  • Streaming parser for incremental frame decoding
  • Zero-copy encoding using bytes::Bytes
  • Buffer overflow protection (configurable 512MB max)
  • Safe handling of malformed input without panics

Performance

Muxis is designed for high performance:

  • Zero-copy parsing where possible using bytes::Bytes
  • Multiplexing eliminates connection overhead for concurrent operations
  • Bounded queues with backpressure prevent memory exhaustion
  • Tokio-native for efficient async I/O
  • Minimal allocations in hot paths

Security

  • URL validation: Strict parsing and scheme validation (redis:// and rediss://)
  • DOS protection: Configurable buffer limits prevent memory exhaustion attacks
  • Safe error handling: No panics in library code, all errors returned as Results
  • Timeout enforcement: Configurable timeouts for all I/O operations

Testing

Muxis has comprehensive test coverage:

  • 192 total tests: 111 unit tests + 81 integration tests + 7 doc tests
  • Protocol tests: Frame encoding/decoding with edge cases
  • Command tests: All 75 commands with unit and integration tests
  • Connection tests: Builder patterns, multiplexing, command execution
  • 100% public API documentation with runnable examples
  • Zero clippy warnings: Clean code following Rust best practices

Run tests:

# Unit tests (111 tests)
cargo test --all-features --lib

# Integration tests (81 tests, requires Redis at 127.0.0.1:6379)
cargo test --all-features -- --ignored

# Documentation tests (7 tests)
cargo test --doc --all-features

# All tests
cargo test --all-features

Development

Requirements

  • Rust 1.83 or later (enforced via rust-toolchain.toml)
  • Docker (for integration tests)

Building

# Build all crates
cargo build --all-targets --all-features

# Build release version
cargo build --release --all-targets --all-features

# Check without building (faster)
cargo check --all-targets --all-features

Code Quality

# Format code
cargo fmt --all

# Run clippy
cargo clippy --all-targets --all-features -- -D warnings

# Full quality check (required before commit)
cargo fmt --all && cargo clippy --all-targets --all-features -- -D warnings

Documentation

# Build documentation
cargo doc --all-features --no-deps

# Build and open in browser
cargo doc --all-features --no-deps --open

See AGENTS.md for detailed development guidelines.

Project Status

Muxis is in active development. Version 0.3.0 provides a solid foundation with RESP2 protocol support and multiplexed connections for standalone Redis servers.

v0.3.0 Changes:

  • Refactored from multi-crate workspace to single-crate architecture
  • Simplified public API with cleaner imports
  • Added comprehensive examples in examples/ directory
  • Improved module organization and documentation

Current status:

  • Phase 0: Repository scaffolding - COMPLETE
  • Phase 1: RESP codec + basic connection - COMPLETE
  • Phase 2: Multiplexing stable - COMPLETE
  • Phase 3+: See ROADMAP.md

Minimum Supported Rust Version (MSRV)

Muxis requires Rust 1.83 or later. The MSRV may be updated in minor version releases.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Key areas for contribution:

  • Additional Redis commands
  • Cluster support implementation
  • RESP3 protocol
  • Performance optimizations
  • Documentation improvements

License

Licensed under either of:

at your option.

Related Projects

Acknowledgments

Muxis is built on the shoulders of giants:

  • Tokio: Asynchronous runtime
  • bytes: Efficient byte buffer management
  • The Rust community for excellent async ecosystem