distkit
Concepts

Errors

One DistkitError enum, and a no-panic policy.

Library code in distkit never panics. Anything that can go wrong comes back through a single error type, DistkitError, so ? works uniformly across counters, locks, and rate limiting.

DistkitError

pub enum DistkitError {
    InvalidRedisKey(String),       // a key failed validation
    CounterError(CounterError),    // counter operation failed   (feature = "counter")
    LockError(LockError),          // lock operation failed       (feature = "lock")
    RedisError(redis::RedisError), // transport or Lua script error
    MutexPoisoned(&'static str),   // an internal sync primitive was poisoned
    CustomError(String),           // catch-all
    TrypemaError(TrypemaError),    // rate limiting failed        (feature = "trypema")
}

The feature-gated variants only exist when the matching feature is enabled, so you never match on a primitive you didn't compile in.

From is implemented for the inner error types, which is why ? just works:

let key = DistkitRedisKey::try_from("user_123".to_string())?; // InvalidRedisKey on failure
counter.inc(&key, 1).await?;                                  // RedisError / CounterError on failure

Lock errors

Lock-specific failures are modeled separately as LockError, surfaced through DistkitError::LockError:

pub enum LockError {
    AcquireFail,                  // a non-blocking acquire would have to wait
    Timeout { waited: Duration }, // a bounded acquire ran out of time
    NotOwner,                     // tried to release a lock you don't hold
    InvalidTtl(i64),              // ttl must be positive
    InvalidOwner,                 // owner id must not be empty
}

AcquireFail and Timeout are the two you handle routinely - they mean "the lock is busy", not "something broke". See Guard state & errors for how this interacts with lock guards.

too many results to unpack

distkit 0.7.0 and earlier versions can return this Redis error from the instance-aware counters:

Redis Error: ResponseError: user_script:16: too many results to unpack

The error occurs when the counter holds more than approximately 8,000 keys and one instance dies. Then all counter calls fail, and the counter does not recover. clear_on_instance fails in the same way when one instance holds more than approximately 8,000 keys.

To correct this, upgrade to the release that follows 0.7.0. The counter recovers on its first call after the upgrade. No manual Redis step is necessary. See the changelog.