hotkv 1.0.0

data/lib/hotkv/commands/lists.rb

@@ -0,0 +1,113 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # List commands.
+    module Lists
+      def lpush(key, *values)
+        invoke("LPUSH", key, *values.flatten)
+      end
+
+      def rpush(key, *values)
+        invoke("RPUSH", key, *values.flatten)
+      end
+
+      def lpushx(key, *values)
+        invoke("LPUSHX", key, *values.flatten)
+      end
+
+      def rpushx(key, *values)
+        invoke("RPUSHX", key, *values.flatten)
+      end
+
+      # Without :count, returns the popped element or nil. With :count,
+      # returns an Array of popped elements (possibly empty) or nil when
+      # the key does not exist.
+      def lpop(key, count = nil)
+        count ? invoke("LPOP", key, count) : invoke("LPOP", key)
+      end
+
+      def rpop(key, count = nil)
+        count ? invoke("RPOP", key, count) : invoke("RPOP", key)
+      end
+
+      def llen(key)
+        invoke("LLEN", key)
+      end
+
+      def lrange(key, start, stop)
+        invoke("LRANGE", key, start, stop)
+      end
+
+      def lindex(key, index)
+        invoke("LINDEX", key, index)
+      end
+
+      def lset(key, index, value)
+        invoke("LSET", key, index, value) { |r| r == "OK" }
+      end
+
+      def linsert(key, where, pivot, value)
+        invoke("LINSERT", key, where, pivot, value)
+      end
+
+      def lrem(key, count, value)
+        invoke("LREM", key, count, value)
+      end
+
+      def ltrim(key, start, stop)
+        invoke("LTRIM", key, start, stop) { |r| r == "OK" }
+      end
+
+      def rpoplpush(source, destination)
+        invoke("RPOPLPUSH", source, destination)
+      end
+
+      def lmove(source, destination, wherefrom, whereto)
+        invoke("LMOVE", source, destination, wherefrom, whereto)
+      end
+
+      def lpos(key, element, rank: nil, count: nil, maxlen: nil)
+        args = ["LPOS", key, element]
+        args.push("RANK", rank) if rank
+        args.push("COUNT", count) if count
+        args.push("MAXLEN", maxlen) if maxlen
+        invoke(*args)
+      end
+
+      # -> [key, values] on success, or nil when every source list was empty.
+      def lmpop(keys, where, count: nil)
+        args = ["LMPOP", keys.length, *keys, where]
+        args.push("COUNT", count) if count
+        invoke(*args)
+      end
+
+      def blpop(*keys, timeout: 0)
+        invoke("BLPOP", *keys.flatten, timeout)
+      end
+
+      def brpop(*keys, timeout: 0)
+        invoke("BRPOP", *keys.flatten, timeout)
+      end
+
+      def blmove(source, destination, wherefrom, whereto, timeout: 0)
+        invoke("BLMOVE", source, destination, wherefrom, whereto, timeout)
+      end
+
+      # Pops from the first non-empty list of +keys+ (LMPOP) or waits up to
+      # +timeout+ seconds (BLMPOP). +where+ is "LEFT" or "RIGHT". Returns
+      # [key, [elements]] or nil on timeout.
+      def blmpop(keys, where, timeout: 0, count: nil)
+        args = ["BLMPOP", timeout, keys.length, *keys, where]
+        args.push("COUNT", count) if count
+        invoke(*args)
+      end
+
+      # Deprecated blocking RPOPLPUSH.
+      def brpoplpush(source, destination, timeout: 0)
+        invoke("BRPOPLPUSH", source, destination, timeout)
+      end
+    end
+  end
+end

data/lib/hotkv/commands/probabilistic.rb

@@ -0,0 +1,23 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require_relative "../namespaces/probabilistic"
+
+module HotKV
+  module Commands
+    # Bloom filter, Count-Min Sketch and Top-K accessors.
+    module Probabilistic
+      def bf
+        @hotkv_ns_bf ||= Namespaces::BF.new(self)
+      end
+
+      def cms
+        @hotkv_ns_cms ||= Namespaces::CMS.new(self)
+      end
+
+      def topk
+        @hotkv_ns_topk ||= Namespaces::TopK.new(self)
+      end
+    end
+  end
+end

data/lib/hotkv/commands/publishing.rb

@@ -0,0 +1,46 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Publishing and Pub/Sub introspection. Subscribing is not here: it needs
+    # a connection of its own, see Client#subscribe.
+    module Publishing
+      # Publishes +message+ to +channel+. Returns the number of subscribers
+      # that received it.
+      def publish(channel, message)
+        invoke("PUBLISH", channel, message)
+      end
+
+      # Publishes +message+ to a shard channel (SPUBLISH).
+      def spublish(channel, message)
+        invoke("SPUBLISH", channel, message)
+      end
+
+      # Active channels, optionally only those matching the glob +pattern+.
+      def pubsub_channels(pattern = nil)
+        pattern.nil? ? invoke("PUBSUB", "CHANNELS") : invoke("PUBSUB", "CHANNELS", pattern)
+      end
+
+      # Hash of channel => subscriber count for the given channels.
+      def pubsub_numsub(*channels)
+        invoke("PUBSUB", "NUMSUB", *channels.flatten) { |r| r.is_a?(Hash) ? r : r.each_slice(2).to_h }
+      end
+
+      # Number of pattern subscriptions.
+      def pubsub_numpat
+        invoke("PUBSUB", "NUMPAT")
+      end
+
+      # Active shard channels, optionally only those matching +pattern+.
+      def pubsub_shardchannels(pattern = nil)
+        pattern.nil? ? invoke("PUBSUB", "SHARDCHANNELS") : invoke("PUBSUB", "SHARDCHANNELS", pattern)
+      end
+
+      # Hash of shard channel => subscriber count.
+      def pubsub_shardnumsub(*channels)
+        invoke("PUBSUB", "SHARDNUMSUB", *channels.flatten) { |r| r.is_a?(Hash) ? r : r.each_slice(2).to_h }
+      end
+    end
+  end
+end

data/lib/hotkv/commands/scan.rb

@@ -0,0 +1,82 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # SCAN family: one-shot cursor calls plus Enumerator based iterators
+    # that page through an entire key space, hash, set or sorted set.
+    module Scan
+      # -> [next_cursor, keys]. next_cursor is "0" once the scan completes.
+      def scan(cursor = "0", match: nil, count: nil, type: nil)
+        args = ["SCAN", cursor]
+        args.push("MATCH", match) if match
+        args.push("COUNT", count) if count
+        args.push("TYPE", type) if type
+        invoke(*args)
+      end
+
+      # Enumerator over every key, paging with SCAN until exhausted.
+      def scan_each(match: nil, count: nil, type: nil, &block)
+        return to_enum(:scan_each, match: match, count: count, type: type) unless block
+
+        each_scan_page(:scan, [], match: match, count: count, type: type) { |page| page.each(&block) }
+      end
+
+      def hscan(key, cursor = "0", match: nil, count: nil, novalues: false)
+        args = ["HSCAN", key, cursor]
+        args.push("MATCH", match) if match
+        args.push("COUNT", count) if count
+        args.push("NOVALUES") if novalues
+        invoke(*args)
+      end
+
+      def hscan_each(key, match: nil, count: nil, &block)
+        return to_enum(:hscan_each, key, match: match, count: count) unless block
+
+        each_scan_page(:hscan, [key], match: match, count: count) { |page| page.each_slice(2) { |(f, v)| yield f, v } }
+      end
+
+      def sscan(key, cursor = "0", match: nil, count: nil)
+        args = ["SSCAN", key, cursor]
+        args.push("MATCH", match) if match
+        args.push("COUNT", count) if count
+        invoke(*args)
+      end
+
+      def sscan_each(key, match: nil, count: nil, &block)
+        return to_enum(:sscan_each, key, match: match, count: count) unless block
+
+        each_scan_page(:sscan, [key], match: match, count: count) { |page| page.each(&block) }
+      end
+
+      def zscan(key, cursor = "0", match: nil, count: nil)
+        args = ["ZSCAN", key, cursor]
+        args.push("MATCH", match) if match
+        args.push("COUNT", count) if count
+        invoke(*args)
+      end
+
+      def zscan_each(key, match: nil, count: nil, &block)
+        return to_enum(:zscan_each, key, match: match, count: count) unless block
+
+        each_scan_page(:zscan, [key], match: match, count: count) do |page|
+          page.each_slice(2) { |(m, s)| yield m, Wire.parse_float(s) }
+        end
+      end
+
+      private
+
+      def each_scan_page(method, prefix_args, match:, count:, type: nil, novalues: nil)
+        cursor = "0"
+        loop do
+          kwargs = { match: match, count: count }
+          kwargs[:type] = type if method == :scan
+          kwargs[:novalues] = novalues if method == :hscan && !novalues.nil?
+          cursor, page = public_send(method, *prefix_args, cursor, **kwargs)
+          yield page
+          break if cursor == "0"
+        end
+      end
+    end
+  end
+end

data/lib/hotkv/commands/scripting.rb

@@ -0,0 +1,128 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require "digest"
+
+module HotKV
+  module Commands
+    # Lua scripting commands.
+    module Scripting
+      def eval_script(script, keys: [], args: [])
+        invoke("EVAL", script, keys.length, *keys, *args)
+      end
+
+      # Runs EVALSHA for +sha+ (or Digest::SHA1.hexdigest(script) when
+      # :script is given instead of :sha); on NOSCRIPT, falls back to a
+      # plain EVAL of :script if one was given. The fallback only fires
+      # for an immediate call (HotKV::Client, inside a #watch block); a
+      # queued Pipeline/Transaction call cannot inspect its own reply
+      # before the batch runs, so there it behaves like a plain EVALSHA.
+      def evalsha(sha = nil, script: nil, keys: [], args: [])
+        sha ||= Digest::SHA1.hexdigest(script)
+        invoke("EVALSHA", sha, keys.length, *keys, *args)
+      rescue Error::NoScriptError
+        raise unless script
+
+        invoke("EVAL", script, keys.length, *keys, *args)
+      end
+
+      def script_load(script)
+        invoke("SCRIPT", "LOAD", script)
+      end
+
+      def script_exists(*shas)
+        invoke("SCRIPT", "EXISTS", *shas.flatten) { |r| r.map { |v| v == 1 } }
+      end
+
+      def script_flush
+        invoke("SCRIPT", "FLUSH") { |r| r == "OK" }
+      end
+
+      # Read-only EVAL (the script may not write).
+      def eval_ro(script, keys: [], args: [])
+        invoke("EVAL_RO", script, keys.length, *keys, *args)
+      end
+
+      # Read-only EVALSHA.
+      def evalsha_ro(sha, keys: [], args: [])
+        invoke("EVALSHA_RO", sha, keys.length, *keys, *args)
+      end
+
+      # Stops a running script (NOTBUSY if none is running).
+      def script_kill
+        invoke("SCRIPT", "KILL") { |r| r == "OK" }
+      end
+
+      # Calls a function registered by FUNCTION LOAD.
+      def fcall(function, keys: [], args: [])
+        invoke("FCALL", function, keys.length, *keys, *args)
+      end
+
+      # FCALL for a function flagged no-writes.
+      def fcall_ro(function, keys: [], args: [])
+        invoke("FCALL_RO", function, keys.length, *keys, *args)
+      end
+
+      # Loads a function library (`#!lua name=<lib>` header). Returns the
+      # library name. :replace overwrites an existing library of that name.
+      def function_load(code, replace: false)
+        replace ? invoke("FUNCTION", "LOAD", "REPLACE", code) : invoke("FUNCTION", "LOAD", code)
+      end
+
+      def function_delete(library)
+        invoke("FUNCTION", "DELETE", library) { |r| r == "OK" }
+      end
+
+      # Libraries as an Array of Hashes ("library_name", "engine",
+      # "functions" => [{"name", "description", "flags"}], plus "library_code"
+      # with :withcode).
+      def function_list(libraryname: nil, withcode: false)
+        args = ["FUNCTION", "LIST"]
+        args.push("LIBRARYNAME", libraryname) if libraryname
+        args.push("WITHCODE") if withcode
+        invoke(*args) { |r| r.map { |lib| lib.is_a?(Hash) ? lib : function_entry(lib) } }
+      end
+
+      # Deletes every library. +mode+ is "ASYNC" or "SYNC".
+      def function_flush(mode = nil)
+        mode ? invoke("FUNCTION", "FLUSH", mode) { |r| r == "OK" } : invoke("FUNCTION", "FLUSH") { |r| r == "OK" }
+      end
+
+      # Serialized libraries (binary String) for #function_restore.
+      def function_dump
+        invoke("FUNCTION", "DUMP")
+      end
+
+      # Restores a #function_dump payload. +policy+: "APPEND", "REPLACE" or "FLUSH".
+      def function_restore(payload, policy = nil)
+        args = ["FUNCTION", "RESTORE", payload]
+        args.push(policy) if policy
+        invoke(*args) { |r| r == "OK" }
+      end
+
+      # Hash with "running_script" and "engines".
+      def function_stats
+        invoke("FUNCTION", "STATS") { |r| r.is_a?(Hash) ? r : { "running_script" => r[1], "engines" => engines_hash(r[3]) } }
+      end
+
+      # Stops a running function.
+      def function_kill
+        invoke("FUNCTION", "KILL") { |r| r == "OK" }
+      end
+
+      private
+
+      def function_entry(flat)
+        entry = flat.each_slice(2).to_h
+        entry["functions"] = entry["functions"].map { |f| f.is_a?(Hash) ? f : f.each_slice(2).to_h } if entry["functions"]
+        entry
+      end
+
+      def engines_hash(flat)
+        return flat if flat.is_a?(Hash)
+
+        flat.each_slice(2).to_h { |(name, stats)| [name, stats.is_a?(Hash) ? stats : stats.each_slice(2).to_h] }
+      end
+    end
+  end
+end

data/lib/hotkv/commands/server.rb

@@ -0,0 +1,175 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Server and connection commands.
+    module Server
+      def ping(message = nil)
+        message ? invoke("PING", message) : invoke("PING")
+      end
+
+      def echo(message)
+        invoke("ECHO", message)
+      end
+
+      def info(section = nil)
+        section ? invoke("INFO", section) : invoke("INFO")
+      end
+
+      def dbsize
+        invoke("DBSIZE")
+      end
+
+      def flushdb(async: false)
+        args = ["FLUSHDB"]
+        args.push(async ? "ASYNC" : "SYNC")
+        invoke(*args) { |r| r == "OK" }
+      end
+
+      def flushall(async: false)
+        args = ["FLUSHALL"]
+        args.push(async ? "ASYNC" : "SYNC")
+        invoke(*args) { |r| r == "OK" }
+      end
+
+      def time
+        invoke("TIME") { |r| [Integer(r[0]), Integer(r[1])] }
+      end
+
+      def lastsave
+        invoke("LASTSAVE")
+      end
+
+      def config_get(parameter)
+        invoke("CONFIG", "GET", parameter) { |r| r.is_a?(Hash) ? r : r.each_slice(2).to_h }
+      end
+
+      def config_set(parameter, value)
+        invoke("CONFIG", "SET", parameter, value) { |r| r == "OK" }
+      end
+
+      def config_resetstat
+        invoke("CONFIG", "RESETSTAT") { |r| r == "OK" }
+      end
+
+      def client_setname(name)
+        invoke("CLIENT", "SETNAME", name) { |r| r == "OK" }
+      end
+
+      def client_getname
+        invoke("CLIENT", "GETNAME")
+      end
+
+      def client_id
+        invoke("CLIENT", "ID")
+      end
+
+      def client_info
+        invoke("CLIENT", "INFO")
+      end
+
+      def client_list
+        invoke("CLIENT", "LIST")
+      end
+
+      def select(db)
+        invoke("SELECT", db) { |r| r == "OK" }
+      end
+
+      def swapdb(index1, index2)
+        invoke("SWAPDB", index1, index2) { |r| r == "OK" }
+      end
+
+      # Replication role: ["master", offset, [[host, port, offset], ...]] or
+      # ["slave", host, port, state, offset].
+      def role
+        invoke("ROLE")
+      end
+
+      # Saves a snapshot now, blocking the server until done.
+      def save
+        invoke("SAVE") { |r| r == "OK" }
+      end
+
+      # Saves a snapshot in the background. Returns the status line.
+      def bgsave(schedule: false)
+        schedule ? invoke("BGSAVE", "SCHEDULE") : invoke("BGSAVE")
+      end
+
+      # Rewrites the append-only file in the background. Returns the status line.
+      def bgrewriteaof
+        invoke("BGREWRITEAOF")
+      end
+
+      # Slow log entries (the newest +count+, default 10).
+      def slowlog_get(count = nil)
+        count ? invoke("SLOWLOG", "GET", count) : invoke("SLOWLOG", "GET")
+      end
+
+      def slowlog_len
+        invoke("SLOWLOG", "LEN")
+      end
+
+      def slowlog_reset
+        invoke("SLOWLOG", "RESET") { |r| r == "OK" }
+      end
+
+      # Bytes used by the value at +key+ (nil if missing); :samples limits
+      # the nested elements sampled.
+      def memory_usage(key, samples: nil)
+        samples ? invoke("MEMORY", "USAGE", key, "SAMPLES", samples) : invoke("MEMORY", "USAGE", key)
+      end
+
+      # Number of commands the server knows.
+      def command_count
+        invoke("COMMAND", "COUNT")
+      end
+
+      # The keys +command+ (a full command line as separate arguments) touches.
+      def command_getkeys(*command)
+        invoke("COMMAND", "GETKEYS", *command.flatten)
+      end
+
+      # Suspends client command processing for +milliseconds+ on the whole
+      # server. +mode+ is "WRITE" or "ALL". Lift it with #client_unpause.
+      def client_pause(milliseconds, mode = nil)
+        mode ? invoke("CLIENT", "PAUSE", milliseconds, mode) { |r| r == "OK" } : invoke("CLIENT", "PAUSE", milliseconds) { |r| r == "OK" }
+      end
+
+      def client_unpause
+        invoke("CLIENT", "UNPAUSE") { |r| r == "OK" }
+      end
+
+      # Marks the pooled connection that runs it as exempt from (or subject
+      # to) client eviction. +enabled+ true/false. Applies to one pooled
+      # connection only, so it is mostly useful on a pool_size 1 client.
+      def client_no_evict(enabled)
+        invoke("CLIENT", "NO-EVICT", enabled ? "ON" : "OFF") { |r| r == "OK" }
+      end
+
+      # As #client_no_evict, for the LRU/LFU touch on reads.
+      def client_no_touch(enabled)
+        invoke("CLIENT", "NO-TOUCH", enabled ? "ON" : "OFF") { |r| r == "OK" }
+      end
+
+      # CLIENT SETINFO LIB-NAME / LIB-VER on the pooled connection that runs it.
+      def client_setinfo(attribute, value)
+        invoke("CLIENT", "SETINFO", attribute, value) { |r| r == "OK" }
+      end
+
+      # Unblocks the client blocked with id +client_id+. +reason+ is
+      # "TIMEOUT" or "ERROR". Returns true when a client was unblocked.
+      def client_unblock(client_id, reason = nil)
+        args = ["CLIENT", "UNBLOCK", client_id]
+        args.push(reason) if reason
+        invoke(*args) { |r| r == 1 }
+      end
+
+      # Closes the connection with id +client_id+. Returns the number closed.
+      def client_kill_id(client_id)
+        invoke("CLIENT", "KILL", "ID", client_id)
+      end
+    end
+  end
+end

data/lib/hotkv/commands/sets.rb

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Set commands.
+    module Sets
+      def sadd(key, *members)
+        invoke("SADD", key, *members.flatten)
+      end
+
+      def srem(key, *members)
+        invoke("SREM", key, *members.flatten)
+      end
+
+      def smembers(key)
+        invoke("SMEMBERS", key)
+      end
+
+      def sismember(key, member)
+        invoke("SISMEMBER", key, member) { |r| Support.truthy(r) }
+      end
+
+      def smismember(key, *members)
+        invoke("SMISMEMBER", key, *members.flatten) { |r| r.map { |m| Support.truthy(m) } }
+      end
+
+      def scard(key)
+        invoke("SCARD", key)
+      end
+
+      def spop(key, count = nil)
+        count ? invoke("SPOP", key, count) : invoke("SPOP", key)
+      end
+
+      def srandmember(key, count = nil)
+        count ? invoke("SRANDMEMBER", key, count) : invoke("SRANDMEMBER", key)
+      end
+
+      def sinter(*keys)
+        invoke("SINTER", *keys.flatten)
+      end
+
+      def sunion(*keys)
+        invoke("SUNION", *keys.flatten)
+      end
+
+      def sdiff(*keys)
+        invoke("SDIFF", *keys.flatten)
+      end
+
+      def sintercard(keys, limit: nil)
+        args = ["SINTERCARD", keys.length, *keys]
+        args.push("LIMIT", limit) if limit
+        invoke(*args)
+      end
+
+      def sinterstore(destination, *keys)
+        invoke("SINTERSTORE", destination, *keys.flatten)
+      end
+
+      def sunionstore(destination, *keys)
+        invoke("SUNIONSTORE", destination, *keys.flatten)
+      end
+
+      def sdiffstore(destination, *keys)
+        invoke("SDIFFSTORE", destination, *keys.flatten)
+      end
+
+      def smove(source, destination, member)
+        invoke("SMOVE", source, destination, member) { |r| r == 1 }
+      end
+    end
+  end
+end