Struct Client 

pub struct Client { /* private fields */ }

An async client connected to a single ember server.

Buffers reads and writes internally. Not thread-safe — use one Client per task, or wrap in an Arc<Mutex<_>> if sharing is needed.

Implementations

impl Client

pub async fn get(&mut self, key: &str) -> Result<Option<Bytes>, ClientError>

Returns the value for key, or None if it does not exist.

pub async fn set( &mut self, key: &str, value: impl AsRef<[u8]>, ) -> Result<(), ClientError>

Sets key to value with no expiry.

pub async fn set_ex( &mut self, key: &str, value: impl AsRef<[u8]>, seconds: u64, ) -> Result<(), ClientError>

Sets key to value with an expiry of seconds.

pub async fn del(&mut self, keys: &[&str]) -> Result<i64, ClientError>

Deletes one or more keys. Returns the number of keys that were removed.

pub async fn exists(&mut self, keys: &[&str]) -> Result<i64, ClientError>

Returns the number of supplied keys that exist.

pub async fn expire( &mut self, key: &str, seconds: u64, ) -> Result<bool, ClientError>

Sets a timeout of seconds on key. Returns true if the timeout was set, false if the key does not exist.

pub async fn persist(&mut self, key: &str) -> Result<bool, ClientError>

Removes any existing timeout on key. Returns true if the timeout was removed, false if the key has no timeout or does not exist.

pub async fn ttl(&mut self, key: &str) -> Result<i64, ClientError>

Returns the remaining TTL in seconds. Returns -2 if the key does not exist, -1 if it has no expiry.

pub async fn pttl(&mut self, key: &str) -> Result<i64, ClientError>

Returns the remaining TTL in milliseconds.

pub async fn incr(&mut self, key: &str) -> Result<i64, ClientError>

Increments the integer stored at key by 1. Returns the new value.

pub async fn decr(&mut self, key: &str) -> Result<i64, ClientError>

Decrements the integer stored at key by 1. Returns the new value.

pub async fn incrby( &mut self, key: &str, delta: i64, ) -> Result<i64, ClientError>

Increments the integer stored at key by delta. Returns the new value.

pub async fn decrby( &mut self, key: &str, delta: i64, ) -> Result<i64, ClientError>

Decrements the integer stored at key by delta. Returns the new value.

pub async fn append( &mut self, key: &str, value: impl AsRef<[u8]>, ) -> Result<i64, ClientError>

Appends value to the string at key. Returns the new length.

pub async fn mget( &mut self, keys: &[&str], ) -> Result<Vec<Option<Bytes>>, ClientError>

Returns the values for multiple keys. Missing keys are None.

pub async fn mset<V: AsRef<[u8]>>( &mut self, pairs: &[(&str, V)], ) -> Result<(), ClientError>

Sets multiple key-value pairs atomically.

pub async fn getdel(&mut self, key: &str) -> Result<Option<Bytes>, ClientError>

Returns the value of key and deletes it atomically. Returns None if the key does not exist.

pub async fn lpush<V: AsRef<[u8]>>( &mut self, key: &str, values: &[V], ) -> Result<i64, ClientError>

Prepends values to the list at key. Returns the new list length.

pub async fn rpush<V: AsRef<[u8]>>( &mut self, key: &str, values: &[V], ) -> Result<i64, ClientError>

Appends values to the list at key. Returns the new list length.

pub async fn lpop(&mut self, key: &str) -> Result<Option<Bytes>, ClientError>

Removes and returns the first element of the list at key.

pub async fn rpop(&mut self, key: &str) -> Result<Option<Bytes>, ClientError>

Removes and returns the last element of the list at key.

pub async fn lrange( &mut self, key: &str, start: i64, stop: i64, ) -> Result<Vec<Bytes>, ClientError>

Returns the elements of the list between start and stop (inclusive).

pub async fn llen(&mut self, key: &str) -> Result<i64, ClientError>

Returns the length of the list at key. Returns 0 for missing keys.

pub async fn hset<V: AsRef<[u8]>>( &mut self, key: &str, pairs: &[(&str, V)], ) -> Result<i64, ClientError>

Sets field/value pairs on the hash at key. Returns the number of new fields added.

pub async fn hget( &mut self, key: &str, field: &str, ) -> Result<Option<Bytes>, ClientError>

Returns the value at field in the hash at key, or None if either does not exist.

pub async fn hgetall( &mut self, key: &str, ) -> Result<Vec<(Bytes, Bytes)>, ClientError>

Returns all field-value pairs in the hash at key.

pub async fn hdel( &mut self, key: &str, fields: &[&str], ) -> Result<i64, ClientError>

Deletes fields from the hash at key. Returns the number removed.

pub async fn hexists( &mut self, key: &str, field: &str, ) -> Result<bool, ClientError>

Returns true if field exists in the hash at key.

pub async fn hlen(&mut self, key: &str) -> Result<i64, ClientError>

Returns the number of fields in the hash at key.

pub async fn hincrby( &mut self, key: &str, field: &str, delta: i64, ) -> Result<i64, ClientError>

Increments the integer stored at field in the hash at key by delta. Returns the new value.

pub async fn hkeys(&mut self, key: &str) -> Result<Vec<Bytes>, ClientError>

Returns all field names in the hash at key.

pub async fn hvals(&mut self, key: &str) -> Result<Vec<Bytes>, ClientError>

Returns all values in the hash at key.

pub async fn sadd( &mut self, key: &str, members: &[&str], ) -> Result<i64, ClientError>

Adds members to the set at key. Returns the number added.

pub async fn srem( &mut self, key: &str, members: &[&str], ) -> Result<i64, ClientError>

Removes members from the set at key. Returns the number removed.

pub async fn smembers(&mut self, key: &str) -> Result<Vec<Bytes>, ClientError>

Returns all members of the set at key.

pub async fn sismember( &mut self, key: &str, member: &str, ) -> Result<bool, ClientError>

Returns true if member belongs to the set at key.

pub async fn scard(&mut self, key: &str) -> Result<i64, ClientError>

Returns the cardinality (number of members) of the set at key.

pub async fn zadd( &mut self, key: &str, members: &[(f64, &str)], ) -> Result<i64, ClientError>

Adds members to the sorted set at key. Each member is a (score, name) pair. Returns the number of new members added.

pub async fn zrange( &mut self, key: &str, start: i64, stop: i64, ) -> Result<Vec<Bytes>, ClientError>

Returns members of the sorted set between rank start and stop (0-based, inclusive).

pub async fn zrange_withscores( &mut self, key: &str, start: i64, stop: i64, ) -> Result<Vec<(Bytes, f64)>, ClientError>

Like zrange, but also returns scores as (member, score) pairs.

pub async fn zscore( &mut self, key: &str, member: &str, ) -> Result<Option<f64>, ClientError>

Returns the score of member in the sorted set, or None if absent.

pub async fn zrank( &mut self, key: &str, member: &str, ) -> Result<Option<i64>, ClientError>

Returns the rank of member in the sorted set (0-based, ascending score order), or None if absent.

pub async fn zrem( &mut self, key: &str, members: &[&str], ) -> Result<i64, ClientError>

Removes members from the sorted set at key. Returns the number removed.

pub async fn zcard(&mut self, key: &str) -> Result<i64, ClientError>

Returns the number of members in the sorted set at key.

pub async fn ping(&mut self) -> Result<(), ClientError>

Sends a PING and expects a PONG response.

pub async fn dbsize(&mut self) -> Result<i64, ClientError>

Returns the number of keys in the current database.

pub async fn flushdb(&mut self) -> Result<(), ClientError>

Removes all keys from the current database.

pub async fn strlen(&mut self, key: &str) -> Result<i64, ClientError>

Returns the length of the string at key. Returns 0 for missing keys.

pub async fn incr_by_float( &mut self, key: &str, delta: f64, ) -> Result<f64, ClientError>

Increments the float stored at key by delta. Returns the new value.

pub async fn key_type(&mut self, key: &str) -> Result<String, ClientError>

Returns the type of the value stored at key as a string: "string", "list", "set", "zset", "hash", or "none".

pub async fn keys(&mut self, pattern: &str) -> Result<Vec<Bytes>, ClientError>

Returns all keys matching pattern.

Use "*" to return every key. This is a blocking O(N) scan — prefer Client::scan in production.

pub async fn rename( &mut self, key: &str, newkey: &str, ) -> Result<(), ClientError>

Renames key to newkey. Returns an error if key does not exist.

pub async fn scan( &mut self, cursor: u64, count: Option<u32>, pattern: Option<&str>, ) -> Result<ScanPage, ClientError>

Incrementally iterates keys in the keyspace.

Pass cursor: 0 to start a new iteration. Continue calling with the returned cursor until the cursor is 0 again. An optional pattern filters by glob and count hints at the page size (server may return more or fewer).

pub async fn pexpire( &mut self, key: &str, millis: u64, ) -> Result<bool, ClientError>

Sets a timeout of millis milliseconds on key. Returns true if the timeout was set, false if the key does not exist.

pub async fn hmget( &mut self, key: &str, fields: &[&str], ) -> Result<Vec<Option<Bytes>>, ClientError>

Returns values for multiple fields in the hash at key. Missing fields are None.

pub async fn echo(&mut self, message: &str) -> Result<Bytes, ClientError>

Echoes message back from the server. Useful for round-trip testing.

pub async fn unlink(&mut self, keys: &[&str]) -> Result<i64, ClientError>

Deletes keys asynchronously. Behaves like del but frees memory in the background for large values. Returns the number of keys removed.

pub async fn info( &mut self, section: Option<&str>, ) -> Result<String, ClientError>

Returns server information. Pass Some("keyspace") for a specific section, or None for all sections.

pub async fn bgsave(&mut self) -> Result<String, ClientError>

Triggers a background snapshot (BGSAVE). Returns the server status message.

pub async fn bgrewriteaof(&mut self) -> Result<String, ClientError>

Triggers an AOF rewrite in the background (BGREWRITEAOF). Returns the server status message.

pub async fn slowlog_get( &mut self, count: Option<u32>, ) -> Result<Vec<SlowlogEntry>, ClientError>

Returns up to count recent slow-log entries, or all entries if count is None.

pub async fn slowlog_len(&mut self) -> Result<i64, ClientError>

Returns the number of entries currently in the slow log.

pub async fn slowlog_reset(&mut self) -> Result<(), ClientError>

Clears all entries from the slow log.

pub async fn publish( &mut self, channel: &str, message: impl AsRef<[u8]>, ) -> Result<i64, ClientError>

Publishes message to channel. Returns the number of subscribers that received the message.

pub async fn pubsub_channels( &mut self, pattern: Option<&str>, ) -> Result<Vec<Bytes>, ClientError>

Returns the names of active pub/sub channels. Pass Some(pattern) to filter by glob, or None for all channels.

pub async fn pubsub_numsub( &mut self, channels: &[&str], ) -> Result<Vec<(Bytes, i64)>, ClientError>

Returns the subscriber counts for the given channels as (channel, count) pairs.

pub async fn pubsub_numpat(&mut self) -> Result<i64, ClientError>

Returns the number of active pattern subscriptions across all clients.

pub async fn subscribe( self, channels: &[&str], ) -> Result<Subscriber, ClientError>

Puts the connection into subscriber mode on channels.

The connection is consumed and a Subscriber is returned. Use a separate Client for regular commands while subscribed.

pub async fn psubscribe( self, patterns: &[&str], ) -> Result<Subscriber, ClientError>

Same as subscribe but subscribes to glob patterns with PSUBSCRIBE.

pub async fn expiretime(&mut self, key: &str) -> Result<i64, ClientError>

Returns the absolute unix expiry timestamp in seconds, or -1 if no expiry, -2 if key missing.

pub async fn pexpiretime(&mut self, key: &str) -> Result<i64, ClientError>

Returns the absolute unix expiry timestamp in milliseconds, or -1 if no expiry, -2 if key missing.

pub async fn expireat( &mut self, key: &str, timestamp: u64, ) -> Result<bool, ClientError>

Sets expiry at an absolute unix timestamp (seconds). Returns true if the timeout was set.

pub async fn pexpireat( &mut self, key: &str, timestamp_ms: u64, ) -> Result<bool, ClientError>

Sets expiry at an absolute unix timestamp (milliseconds). Returns true if the timeout was set.

pub async fn getset( &mut self, key: &str, value: impl AsRef<[u8]>, ) -> Result<Option<Bytes>, ClientError>

Sets key to value, returning the old value. Returns None if the key didn’t exist.

pub async fn msetnx<V: AsRef<[u8]>>( &mut self, pairs: &[(&str, V)], ) -> Result<bool, ClientError>

Sets multiple key-value pairs only if none of the keys already exist. Returns true if all keys were set, false if any key existed.

pub async fn getbit( &mut self, key: &str, offset: u64, ) -> Result<i64, ClientError>

Returns the bit value at offset in the string stored at key.

pub async fn setbit( &mut self, key: &str, offset: u64, value: u8, ) -> Result<i64, ClientError>

Sets or clears the bit at offset. Returns the original bit value.

pub async fn bitcount( &mut self, key: &str, range: Option<(i64, i64, &str)>, ) -> Result<i64, ClientError>

Counts set bits in the string at key.

range: optional (start, end, unit) where unit is "BYTE" or "BIT".

pub async fn bitpos( &mut self, key: &str, bit: u8, range: Option<(i64, i64, &str)>, ) -> Result<i64, ClientError>

Finds the first set (bit=1) or clear (bit=0) bit in the string at key.

range: optional (start, end, unit) where unit is "BYTE" or "BIT".

pub async fn bitop( &mut self, op: &str, dest: &str, keys: &[&str], ) -> Result<i64, ClientError>

Performs a bitwise operation between strings.

op is "AND", "OR", "XOR", or "NOT". Result is stored at dest. Returns the length of the resulting string.

pub async fn smove( &mut self, src: &str, dst: &str, member: &str, ) -> Result<bool, ClientError>

Atomically moves member from src to dst. Returns true if the move succeeded.

pub async fn sintercard( &mut self, keys: &[&str], limit: usize, ) -> Result<i64, ClientError>

Returns the cardinality of the intersection of multiple sets. limit=0 means no limit.

pub async fn lmpop( &mut self, keys: &[&str], left: bool, count: usize, ) -> Result<Option<(String, Vec<Bytes>)>, ClientError>

Pops up to count elements from the first non-empty list in keys.

left=true pops from the head, left=false from the tail. Returns None if all lists are empty, or Some((key, elements)).

pub async fn hrandfield( &mut self, key: &str, count: Option<i64>, ) -> Result<Vec<Bytes>, ClientError>

Returns random field(s) from the hash at key.

count=None returns a single field name as a one-element Vec. Positive count returns that many distinct fields; negative allows repeats.

pub async fn hrandfield_withvalues( &mut self, key: &str, count: i64, ) -> Result<Vec<(Bytes, Bytes)>, ClientError>

Returns random field-value pairs from the hash at key.

count controls how many pairs to return (positive = distinct, negative = allow repeats).

pub async fn zmpop( &mut self, keys: &[&str], min: bool, count: usize, ) -> Result<Option<(String, Vec<(Bytes, f64)>)>, ClientError>

Pops up to count elements from the first non-empty sorted set in keys.

min=true pops minimum-score members, min=false pops maximum-score members. Returns None if all sorted sets are empty, or Some((key, members)).

pub async fn zrandmember( &mut self, key: &str, count: Option<i64>, ) -> Result<Vec<Bytes>, ClientError>

Returns random member(s) from the sorted set at key.

count=None returns a single member name. Positive count returns distinct members; negative allows repeats.

pub async fn zrandmember_withscores( &mut self, key: &str, count: i64, ) -> Result<Vec<(Bytes, f64)>, ClientError>

Returns random member-score pairs from the sorted set at key.

count controls how many pairs to return (positive = distinct, negative = allow repeats).

pub async fn execute_pipeline( &mut self, pipeline: Pipeline, ) -> Result<Vec<Frame>, ClientError>

Executes all commands queued in pipeline as a single batch.

Returns one raw Frame per command in the same order they were queued. An empty pipeline returns an empty Vec without touching the network.

Use this when you need full control over decoding the responses (e.g. mixed command types in one batch). For homogeneous batches the typed builder methods on Pipeline pair well with a manual decode loop.

impl Client

pub async fn connect(host: &str, port: u16) -> Result<Self, ClientError>

Connects to an ember server over plain TCP.

Times out after 5 seconds if the server is unreachable.

pub async fn connect_tls( host: &str, port: u16, tls: &TlsClientConfig, ) -> Result<Self, ClientError>

Connects to an ember server with TLS.

Performs the TCP connection and TLS handshake within the 5-second connect timeout.

pub async fn send(&mut self, args: &[&str]) -> Result<Frame, ClientError>

Sends a command and returns the server’s RESP3 response.

Arguments are serialized as a RESP3 array of bulk strings, which is the standard client-to-server wire format.

Example

let mut client = Client::connect("127.0.0.1", 6379).await?;
let pong = client.send(&["PING"]).await?;
let value = client.send(&["GET", "mykey"]).await?;

pub async fn auth(&mut self, password: &str) -> Result<(), ClientError>

Authenticates with the server using the AUTH command.

Returns Ok(()) on success, or ClientError::AuthFailed if the server rejects the password.

pub async fn disconnect(&mut self)

Gracefully disconnects from the server.

Sends QUIT so the server can clean up, then shuts down the transport. Errors are ignored — this is best-effort cleanup.