ruvio-client 0.2.0

RESP2 client for the Ruvio key-value server
Documentation

ruvio-client

Blocking RESP2 client for Ruvio. Connecting does not send CLIENT SETINFO or HELLO. One Client is one TCP connection. Methods take &mut self and are named after the command they send. They cover every command Ruvio supports. execute and execute_many send any argument list, as redis-cli would.

use std::time::Duration;
use ruvio_client::Client;

let mut db = Client::connect("127.0.0.1", 6379)?;
db.set("session:ada", "hello")?;
let value = db.get_string("session:ada")?;
db.incr("visits")?;
db.expire("session:ada", Duration::from_secs(60))?;
db.hset("user:1", &[("name", "Ada"), ("plan", "pro")])?;
db.zadd("leaderboard", &[("player1", 100.0), ("player2", 80.0)])?;
let top = db.zrevrange_with_scores("leaderboard", 0, 9)?;

Connecting

One client is bound to one logical database. Database 0 sends nothing. Any other index sends SELECT before the connect call returns.

use std::net::{IpAddr, Ipv4Addr, SocketAddr};
use ruvio_client::{Client, ClientOptions};

let mut cache = Client::connect_database("127.0.0.1", 6379, 2)?;
let mut sessions = Client::connect_ip(IpAddr::V4(Ipv4Addr::LOCALHOST), 6379, 3)?;
let mut main = Client::connect_addr(SocketAddr::from(([10, 0, 0, 5], 6379)), 0)?;
let mut secured = Client::connect_with(ClientOptions {
    host: "10.0.0.5".into(),
    username: Some("app".into()),
    password: Some("secret".into()),
    database: 4,
    ..ClientOptions::default()
})?;

select switches the same connection, and into_database does the same and returns the client. flushdb, flushall, swapdb, and move_key send FLUSHDB, FLUSHALL, SWAPDB, and MOVE.

A password is sent as AUTH only when ClientOptions::password is set. A server error reply leaves the connection usable. A broken read or write does not.

Commands

Family Methods
Strings get, get_string, set, set_with, set_expires_at, set_keep_ttl, set_and_get, mget, mset, getset, append, strlen, incr, incr_by, decr, decr_by
Keys del, unlink, exists, key_type, rename, scan, dbsize, expire, pexpire, expire_at, ttl, pttl, persist
Lists lpush, rpush, lpop, lpop_count, rpop, rpop_count, llen, lindex, lrange, ltrim, blpop, brpop
Sets sadd, srem, sismember, scard, smembers, sinter, sunion, sdiff, sinterstore, sunionstore, sdiffstore, smove, spop, spop_count, srandmember, srandmember_count
Hashes hset, hget, hdel, hlen, hgetall, hmget, hexists, hkeys, hvals, hincr_by, hsetnx, hstrlen, hscan
Sorted sets zadd, zadd_with, zadd_incr, zincr_by, zrange, zrevrange, zrange_with_scores, zrevrange_with_scores, zrange_by_score_with_scores, zrem, zcard, zscore, zrank, zrevrank
Bloom filters bf_reserve, bf_add, bf_exists
Streams xadd, xadd_maxlen, xlen, xrange, xrevrange, xdel, xtrim_maxlen, xread, xgroup_create, xreadgroup, xgroup_destroy, xgroup_setid, xgroup_delconsumer, xack, xpending_summary, xpending, xclaim, xclaim_ids
Transactions multi, exec, discard, watch, unwatch
Scripts and functions eval, evalsha, script_load, script_exists, script_flush, script_kill, fcall, function_load, function_list, function_delete
Pub/Sub publish, spublish, subscribe, unsubscribe, psubscribe, punsubscribe, ssubscribe, sunsubscribe, next_message, read_message
Server ping, ping_message, info, config_get, save, bgsave, select, flushdb, flushall, swapdb, move_key, hello, client_getname, client_setname, client_tracking, cluster_slots, cluster_nodes
ACL acl_whoami, acl_users, acl_list, acl_getuser, acl_cat, acl_setuser

SortedSetAddOptions, StreamReadOptions, StreamPendingFilter, and StreamClaimOptions carry the optional ZADD, XREAD/XREADGROUP, XPENDING, and XCLAIM arguments. eval, evalsha, and fcall take keys and arguments separately and send keys.len() as the key count.

Inside MULTI the server answers QUEUED instead of the typed reply, so queue commands with execute and read the results from exec:

db.watch(&["balance"])?;
db.multi()?;
db.execute(&["INCRBY", "balance", "10"])?;
db.execute(&["GET", "balance"])?;
let replies = db.exec()?; // None when a watched key changed

After subscribe, psubscribe, or ssubscribe, next_message blocks until the next message, pmessage, or smessage. set_read_timeout bounds that wait.

Tests

cargo test runs the unit tests. RUVIO_TEST_ADDR=127.0.0.1:16390 cargo test also runs tests/live.rs against a server on that address. Those tests use databases 0 to 7 and flush them.

0.2.0

  • Typed methods for every command Ruvio supports.
  • ClientOptions::database, connect_database, connect_ip, connect_addr, select, into_database, and database.
  • set_expires_at (PXAT), set_keep_ttl (KEEPTTL), set_and_get (GET), and ping_message.
  • expire sends PEXPIRE when the duration is not whole seconds. It used to round up to the next second.
  • RespValue::as_integer, as_array, and is_null.
  • The minimum Rust version is 1.87.