hotkv 1.0.0

data/lib/hotkv/commands/admin.rb

@@ -0,0 +1,36 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require_relative "../namespaces/admin"
+
+module HotKV
+  module Commands
+    # Accessors for the administrative command families: ACL (core) and the
+    # licensed TENANT, IAM, AUDIT, ENCRYPTION and REPLICATION families.
+    module Admin
+      def acl
+        @hotkv_ns_acl ||= Namespaces::ACL.new(self)
+      end
+
+      def tenant
+        @hotkv_ns_tenant ||= Namespaces::Tenant.new(self)
+      end
+
+      def iam
+        @hotkv_ns_iam ||= Namespaces::IAM.new(self)
+      end
+
+      def audit
+        @hotkv_ns_audit ||= Namespaces::Audit.new(self)
+      end
+
+      def encryption
+        @hotkv_ns_encryption ||= Namespaces::Encryption.new(self)
+      end
+
+      def replication
+        @hotkv_ns_replication ||= Namespaces::Replication.new(self)
+      end
+    end
+  end
+end

data/lib/hotkv/commands/all.rb

@@ -0,0 +1,49 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require_relative "support"
+require_relative "strings"
+require_relative "keys"
+require_relative "lists"
+require_relative "sets"
+require_relative "hashes"
+require_relative "sorted_sets"
+require_relative "streams"
+require_relative "geo"
+require_relative "bitmaps"
+require_relative "hyperloglog"
+require_relative "server"
+require_relative "scripting"
+require_relative "scan"
+require_relative "publishing"
+require_relative "probabilistic"
+require_relative "admin"
+require_relative "../extensions"
+
+module HotKV
+  module Commands
+    # Every standard command family, mixed
+    # into HotKV::Client, HotKV::Cluster, HotKV::Pipeline,
+    # HotKV::Transaction and HotKV::WatchSession alike. Each of these
+    # classes only has to implement #invoke(*args, &transform) itself.
+    module All
+      include Strings
+      include Keys
+      include Lists
+      include Sets
+      include Hashes
+      include SortedSets
+      include Streams
+      include Geo
+      include Bitmaps
+      include HyperLogLog
+      include Server
+      include Scripting
+      include Scan
+      include Publishing
+      include Probabilistic
+      include Admin
+      include Extensions
+    end
+  end
+end

data/lib/hotkv/commands/bitmaps.rb

@@ -0,0 +1,52 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Bitmap commands.
+    module Bitmaps
+      def setbit(key, offset, value)
+        invoke("SETBIT", key, offset, value)
+      end
+
+      def getbit(key, offset)
+        invoke("GETBIT", key, offset)
+      end
+
+      # :bit_mode selects BIT range indexing (byte indexing is the default).
+      def bitcount(key, start = nil, stop = nil, bit_mode: false)
+        args = ["BITCOUNT", key]
+        if start
+          args.push(start, stop)
+          args.push("BIT") if bit_mode
+        end
+        invoke(*args)
+      end
+
+      def bitpos(key, bit, start = nil, stop = nil, bit_mode: false)
+        args = ["BITPOS", key, bit]
+        if start
+          args.push(start)
+          args.push(stop) if stop
+          args.push("BIT") if bit_mode
+        end
+        invoke(*args)
+      end
+
+      def bitop(operation, destination, *source_keys)
+        invoke("BITOP", operation, destination, *source_keys.flatten)
+      end
+
+      # Raw escape hatch for BITFIELD: pass the GET/SET/INCRBY/OVERFLOW
+      # sub-operations exactly as the command syntax lists them, e.g.
+      # bitfield("k", "INCRBY", "u8", 0, 10, "GET", "u8", 0).
+      def bitfield(key, *operations)
+        invoke("BITFIELD", key, *operations.flatten)
+      end
+
+      def bitfield_ro(key, *operations)
+        invoke("BITFIELD_RO", key, *operations.flatten)
+      end
+    end
+  end
+end

data/lib/hotkv/commands/geo.rb

@@ -0,0 +1,146 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Geospatial commands.
+    module Geo
+      # +entries+ is a flat [lon, lat, member, ...] list, or an Array of
+      # [lon, lat, member] triples.
+      def geoadd(key, entries, nx: false, xx: false, ch: false)
+        args = ["GEOADD", key]
+        args.push("NX") if nx
+        args.push("XX") if xx
+        args.push("CH") if ch
+        args.concat(finite_geo_entries(entries.flatten))
+        invoke(*args)
+      end
+
+      # -> Array of [lon, lat] Float pairs (nil for a member not found).
+      def geopos(key, *members)
+        invoke("GEOPOS", key, *members.flatten) { |r| r.map { |p| p.nil? ? nil : p.map { |v| Wire.parse_float(v) } } }
+      end
+
+      def geodist(key, member1, member2, unit: "m")
+        invoke("GEODIST", key, member1, member2, unit) { |r| r.nil? ? nil : Wire.parse_float(r) }
+      end
+
+      def geohash(key, *members)
+        invoke("GEOHASH", key, *members.flatten)
+      end
+
+      # Exactly one of :member or :lonlat (a [lon, lat] pair) selects the
+      # search center; exactly one of :radius (a [radius, unit] pair) or
+      # :box (a [width, height, unit] triple) selects the search area.
+      def geosearch(key, member: nil, lonlat: nil, radius: nil, box: nil, asc: nil, desc: nil, count: nil,
+                    any: false, withcoord: false, withdist: false, withhash: false)
+        args = ["GEOSEARCH", key]
+        args.concat(geosearch_origin(member, lonlat))
+        args.concat(geosearch_area(radius, box))
+        args.push("ASC") if asc
+        args.push("DESC") if desc
+        if count
+          args.push("COUNT", count)
+          args.push("ANY") if any
+        end
+        args.push("WITHCOORD") if withcoord
+        args.push("WITHDIST") if withdist
+        args.push("WITHHASH") if withhash
+        invoke(*args) { |r| geosearch_result(r, withcoord, withdist, withhash) }
+      end
+
+      def geosearchstore(destination, source, member: nil, lonlat: nil, radius: nil, box: nil, count: nil,
+                         any: false, storedist: false)
+        args = ["GEOSEARCHSTORE", destination, source]
+        args.concat(geosearch_origin(member, lonlat))
+        args.concat(geosearch_area(radius, box))
+        if count
+          args.push("COUNT", count)
+          args.push("ANY") if any
+        end
+        args.push("STOREDIST") if storedist
+        invoke(*args)
+      end
+
+      # Deprecated GEORADIUS: members within +radius+ (+unit+ m/km/ft/mi) of
+      # a longitude/latitude. Options as #geosearch plus :store/:storedist
+      # (destination key; then the reply is the stored count).
+      def georadius(key, lon, lat, radius, unit, store: nil, storedist: nil, **opts)
+        args = ["GEORADIUS", key, Wire.finite(lon), Wire.finite(lat), Wire.finite(radius), unit]
+        georadius_run(args, opts, store, storedist)
+      end
+
+      # Read-only GEORADIUS.
+      def georadius_ro(key, lon, lat, radius, unit, **opts)
+        args = ["GEORADIUS_RO", key, Wire.finite(lon), Wire.finite(lat), Wire.finite(radius), unit]
+        georadius_run(args, opts, nil, nil)
+      end
+
+      # Deprecated GEORADIUSBYMEMBER: like #georadius around an existing member.
+      def georadiusbymember(key, member, radius, unit, store: nil, storedist: nil, **opts)
+        args = ["GEORADIUSBYMEMBER", key, member, Wire.finite(radius), unit]
+        georadius_run(args, opts, store, storedist)
+      end
+
+      # Read-only GEORADIUSBYMEMBER.
+      def georadiusbymember_ro(key, member, radius, unit, **opts)
+        args = ["GEORADIUSBYMEMBER_RO", key, member, Wire.finite(radius), unit]
+        georadius_run(args, opts, nil, nil)
+      end
+
+      private
+
+      def georadius_run(args, opts, store, storedist)
+        unknown = opts.keys - %i[withcoord withdist withhash count any asc desc]
+        raise Error::ArgumentError, "unknown georadius option(s): #{unknown.join(', ')}" unless unknown.empty?
+
+        args.push("WITHCOORD") if opts[:withcoord]
+        args.push("WITHDIST") if opts[:withdist]
+        args.push("WITHHASH") if opts[:withhash]
+        if opts[:count]
+          args.push("COUNT", opts[:count])
+          args.push("ANY") if opts[:any]
+        end
+        args.push("ASC") if opts[:asc]
+        args.push("DESC") if opts[:desc]
+        args.push("STORE", store) if store
+        args.push("STOREDIST", storedist) if storedist
+        withcoord, withdist, withhash = opts.values_at(:withcoord, :withdist, :withhash)
+        invoke(*args) { |r| (store || storedist) ? r : geosearch_result(r, withcoord, withdist, withhash) }
+      end
+
+      # Longitude and latitude must be finite numbers; the member name that
+      # follows each pair is left alone.
+      def finite_geo_entries(flat)
+        flat.each_with_index.map { |v, i| (i % 3) == 2 ? v : Wire.finite(v) }
+      end
+
+      def geosearch_origin(member, lonlat)
+        return ["FROMMEMBER", member] if member
+        return ["FROMLONLAT", Wire.finite(lonlat[0]), Wire.finite(lonlat[1])] if lonlat
+
+        raise Error::ArgumentError, "geosearch needs :member or :lonlat"
+      end
+
+      def geosearch_area(radius, box)
+        return ["BYRADIUS", Wire.finite(radius[0]), radius[1]] if radius
+        return ["BYBOX", Wire.finite(box[0]), Wire.finite(box[1]), box[2]] if box
+
+        raise Error::ArgumentError, "geosearch needs :radius or :box"
+      end
+
+      def geosearch_result(reply, withcoord, withdist, withhash)
+        return reply unless withcoord || withdist || withhash
+
+        reply.map do |row|
+          row = Array(row)
+          entry = { member: row.shift }
+          entry[:dist] = Wire.parse_float(row.shift) if withdist
+          entry[:hash] = Integer(row.shift) if withhash
+          entry[:coord] = row.shift.map { |v| Wire.parse_float(v) } if withcoord
+          entry
+        end
+      end
+    end
+  end
+end

data/lib/hotkv/commands/hashes.rb

@@ -0,0 +1,169 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Hash commands, including the per field expiry (HEXPIRE/HTTL) family.
+    module Hashes
+      # Accepts a Hash, or a flat [field, value, field, value, ...] list.
+      def hset(key, hash_or_pairs)
+        invoke("HSET", key, *flatten_pairs(hash_or_pairs))
+      end
+
+      def hsetnx(key, field, value)
+        invoke("HSETNX", key, field, value) { |r| r == 1 }
+      end
+
+      def hget(key, field)
+        invoke("HGET", key, field)
+      end
+
+      def hmget(key, *fields)
+        invoke("HMGET", key, *fields.flatten)
+      end
+
+      # Normalizes to a Hash regardless of whether the server replied with
+      # a RESP3 map or a RESP2 flat array.
+      def hgetall(key)
+        invoke("HGETALL", key) { |r| r.is_a?(Hash) ? r : r.each_slice(2).to_h }
+      end
+
+      def hdel(key, *fields)
+        invoke("HDEL", key, *fields.flatten)
+      end
+
+      def hexists(key, field)
+        invoke("HEXISTS", key, field) { |r| r == 1 }
+      end
+
+      def hlen(key)
+        invoke("HLEN", key)
+      end
+
+      def hkeys(key)
+        invoke("HKEYS", key)
+      end
+
+      def hvals(key)
+        invoke("HVALS", key)
+      end
+
+      def hincrby(key, field, amount)
+        invoke("HINCRBY", key, field, amount)
+      end
+
+      def hincrbyfloat(key, field, amount)
+        invoke("HINCRBYFLOAT", key, field, Wire.finite(amount)) { |r| Wire.parse_float(r) }
+      end
+
+      def hstrlen(key, field)
+        invoke("HSTRLEN", key, field)
+      end
+
+      def hrandfield(key, count = nil, withvalues: false)
+        return invoke("HRANDFIELD", key) if count.nil?
+
+        args = ["HRANDFIELD", key, count]
+        args.push("WITHVALUES") if withvalues
+        invoke(*args) { |r| withvalues ? Support.pairify(r) { |v| v } : r }
+      end
+
+      # Field level TTL (seconds). Returns one status Integer per field: 1
+      # set, 0 condition not met, -2 no such field/key.
+      def hexpire(key, seconds, *fields, nx: false, xx: false, gt: false, lt: false)
+        invoke(*hfield_ttl_args("HEXPIRE", key, seconds, fields.flatten, nx, xx, gt, lt))
+      end
+
+      def hpexpire(key, milliseconds, *fields, nx: false, xx: false, gt: false, lt: false)
+        invoke(*hfield_ttl_args("HPEXPIRE", key, milliseconds, fields.flatten, nx, xx, gt, lt))
+      end
+
+      def hexpireat(key, unix_seconds, *fields, nx: false, xx: false, gt: false, lt: false)
+        invoke(*hfield_ttl_args("HEXPIREAT", key, unix_seconds, fields.flatten, nx, xx, gt, lt))
+      end
+
+      def hpexpireat(key, unix_milliseconds, *fields, nx: false, xx: false, gt: false, lt: false)
+        invoke(*hfield_ttl_args("HPEXPIREAT", key, unix_milliseconds, fields.flatten, nx, xx, gt, lt))
+      end
+
+      def httl(key, *fields)
+        invoke("HTTL", key, "FIELDS", fields.flatten.length, *fields.flatten)
+      end
+
+      def hpttl(key, *fields)
+        invoke("HPTTL", key, "FIELDS", fields.flatten.length, *fields.flatten)
+      end
+
+      def hexpiretime(key, *fields)
+        invoke("HEXPIRETIME", key, "FIELDS", fields.flatten.length, *fields.flatten)
+      end
+
+      def hpexpiretime(key, *fields)
+        invoke("HPEXPIRETIME", key, "FIELDS", fields.flatten.length, *fields.flatten)
+      end
+
+      def hpersist(key, *fields)
+        invoke("HPERSIST", key, "FIELDS", fields.flatten.length, *fields.flatten)
+      end
+
+      # Deprecated form of #hset that replies OK. Returns true.
+      def hmset(key, hash_or_pairs)
+        invoke("HMSET", key, *flatten_pairs(hash_or_pairs)) { |r| r == "OK" }
+      end
+
+      # Gets the values of +fields+ and deletes them atomically (HGETDEL). Returns the values in order, nil for a missing field.
+      def hgetdel(key, *fields)
+        flat = fields.flatten
+        invoke("HGETDEL", key, "FIELDS", flat.length, *flat)
+      end
+
+      # Gets the values of +fields+ and sets (:ex/:px/:exat/:pxat) or removes
+      # (:persist) their TTLs (HGETEX).
+      def hgetex(key, *fields, ex: nil, px: nil, exat: nil, pxat: nil, persist: false)
+        flat = fields.flatten
+        args = ["HGETEX", key]
+        args.push("EX", ex) if ex
+        args.push("PX", px) if px
+        args.push("EXAT", exat) if exat
+        args.push("PXAT", pxat) if pxat
+        args.push("PERSIST") if persist
+        args.push("FIELDS", flat.length, *flat)
+        invoke(*args)
+      end
+
+      # Sets fields, all or none, with an optional TTL (HSETEX).
+      # +hash_or_pairs+ is a Hash or a flat [field, value, ...] list. :fnx
+      # sets only when none of the fields exists, :fxx only when all do; TTL
+      # is one of :ex/:px/:exat/:pxat/:keepttl. Returns true when set.
+      def hsetex(key, hash_or_pairs, fnx: false, fxx: false, ex: nil, px: nil, exat: nil, pxat: nil, keepttl: false)
+        flat = flatten_pairs(hash_or_pairs)
+        args = ["HSETEX", key]
+        args.push("FNX") if fnx
+        args.push("FXX") if fxx
+        args.push("EX", ex) if ex
+        args.push("PX", px) if px
+        args.push("EXAT", exat) if exat
+        args.push("PXAT", pxat) if pxat
+        args.push("KEEPTTL") if keepttl
+        args.push("FIELDS", flat.length / 2, *flat)
+        invoke(*args) { |r| r == 1 }
+      end
+
+      private
+
+      def flatten_pairs(hash_or_pairs)
+        hash_or_pairs.is_a?(Hash) ? hash_or_pairs.flatten(1) : hash_or_pairs.flatten(1)
+      end
+
+      def hfield_ttl_args(cmd, key, ttl, fields, nx, xx, gt, lt)
+        args = [cmd, key, ttl]
+        args.push("NX") if nx
+        args.push("XX") if xx
+        args.push("GT") if gt
+        args.push("LT") if lt
+        args.push("FIELDS", fields.length, *fields)
+        args
+      end
+    end
+  end
+end

data/lib/hotkv/commands/hyperloglog.rb

@@ -0,0 +1,21 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # HyperLogLog commands.
+    module HyperLogLog
+      def pfadd(key, *elements)
+        invoke("PFADD", key, *elements.flatten) { |r| r == 1 }
+      end
+
+      def pfcount(*keys)
+        invoke("PFCOUNT", *keys.flatten)
+      end
+
+      def pfmerge(destination, *source_keys)
+        invoke("PFMERGE", destination, *source_keys.flatten) { |r| r == "OK" }
+      end
+    end
+  end
+end

data/lib/hotkv/commands/keys.rb

@@ -0,0 +1,170 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Generic key space and expiry commands.
+    module Keys
+      def del(*keys)
+        invoke("DEL", *keys.flatten)
+      end
+
+      def unlink(*keys)
+        invoke("UNLINK", *keys.flatten)
+      end
+
+      def exists(*keys)
+        invoke("EXISTS", *keys.flatten)
+      end
+
+      def type(key)
+        invoke("TYPE", key)
+      end
+
+      # Sets a relative TTL, in seconds. :nx/:xx/:gt/:lt mirror EXPIRE's
+      # write condition flags.
+      def expire(key, seconds, nx: false, xx: false, gt: false, lt: false)
+        invoke(*expire_args("EXPIRE", key, seconds, nx, xx, gt, lt)) { |r| r == 1 }
+      end
+
+      def pexpire(key, milliseconds, nx: false, xx: false, gt: false, lt: false)
+        invoke(*expire_args("PEXPIRE", key, milliseconds, nx, xx, gt, lt)) { |r| r == 1 }
+      end
+
+      def expireat(key, unix_seconds, nx: false, xx: false, gt: false, lt: false)
+        invoke(*expire_args("EXPIREAT", key, unix_seconds, nx, xx, gt, lt)) { |r| r == 1 }
+      end
+
+      def pexpireat(key, unix_milliseconds, nx: false, xx: false, gt: false, lt: false)
+        invoke(*expire_args("PEXPIREAT", key, unix_milliseconds, nx, xx, gt, lt)) { |r| r == 1 }
+      end
+
+      def ttl(key)
+        invoke("TTL", key)
+      end
+
+      def pttl(key)
+        invoke("PTTL", key)
+      end
+
+      def expiretime(key)
+        invoke("EXPIRETIME", key)
+      end
+
+      def pexpiretime(key)
+        invoke("PEXPIRETIME", key)
+      end
+
+      def persist(key)
+        invoke("PERSIST", key) { |r| r == 1 }
+      end
+
+      def rename(key, new_key)
+        invoke("RENAME", key, new_key) { |r| r == "OK" }
+      end
+
+      def renamenx(key, new_key)
+        invoke("RENAMENX", key, new_key) { |r| r == 1 }
+      end
+
+      def keys(pattern = "*")
+        invoke("KEYS", pattern)
+      end
+
+      def randomkey
+        invoke("RANDOMKEY")
+      end
+
+      def dump(key)
+        invoke("DUMP", key)
+      end
+
+      def restore(key, ttl, serialized_value, replace: false, absttl: false, idletime: nil, freq: nil)
+        args = ["RESTORE", key, ttl, serialized_value]
+        args.push("REPLACE") if replace
+        args.push("ABSTTL") if absttl
+        args.push("IDLETIME", idletime) if idletime
+        args.push("FREQ", freq) if freq
+        invoke(*args) { |r| r == "OK" }
+      end
+
+      def copy(source, destination, db: nil, replace: false)
+        args = ["COPY", source, destination]
+        args.push("DB", db) if db
+        args.push("REPLACE") if replace
+        invoke(*args) { |r| r == 1 }
+      end
+
+      def move(key, db)
+        invoke("MOVE", key, db) { |r| r == 1 }
+      end
+
+      def touch(*keys)
+        invoke("TOUCH", *keys.flatten)
+      end
+
+      def object_encoding(key)
+        invoke("OBJECT", "ENCODING", key)
+      end
+
+      def object_refcount(key)
+        invoke("OBJECT", "REFCOUNT", key)
+      end
+
+      def object_idletime(key)
+        invoke("OBJECT", "IDLETIME", key)
+      end
+
+      def object_freq(key)
+        invoke("OBJECT", "FREQ", key)
+      end
+
+      # SORT of a list, set or sorted set. :by is a pattern ("nosort" skips
+      # sorting), :limit an [offset, count] pair, :get a pattern or Array of
+      # patterns, :order "ASC"/"DESC", :alpha sorts lexicographically, :store
+      # a destination key (then the reply is the stored element count).
+      def sort(key, by: nil, limit: nil, get: nil, order: nil, alpha: false, store: nil)
+        invoke(*sort_args("SORT", key, by, limit, get, order, alpha), *(store ? ["STORE", store] : []))
+      end
+
+      # Read-only SORT (no :store).
+      def sort_ro(key, by: nil, limit: nil, get: nil, order: nil, alpha: false)
+        invoke(*sort_args("SORT_RO", key, by, limit, get, order, alpha))
+      end
+
+      # Blocks until +numreplicas+ replicas acknowledge this connection's
+      # writes or +timeout+ milliseconds pass. Returns the replica count.
+      def wait(numreplicas, timeout)
+        invoke("WAIT", numreplicas, timeout)
+      end
+
+      # WAITAOF: waits until writes are fsynced to the local AOF
+      # (+numlocal+ 0 or 1) and to +numreplicas+ replicas' AOFs. Returns
+      # [local_acks, replica_acks].
+      def waitaof(numlocal, numreplicas, timeout)
+        invoke("WAITAOF", numlocal, numreplicas, timeout)
+      end
+
+      private
+
+      def sort_args(cmd, key, by, limit, get, order, alpha)
+        args = [cmd, key]
+        args.push("BY", by) unless by.nil?
+        args.push("LIMIT", limit[0], limit[1]) if limit
+        Array(get).each { |pattern| args.push("GET", pattern) }
+        args.push(order.to_s.upcase) if order
+        args.push("ALPHA") if alpha
+        args
+      end
+
+      def expire_args(cmd, key, ttl, nx, xx, gt, lt)
+        args = [cmd, key, ttl]
+        args.push("NX") if nx
+        args.push("XX") if xx
+        args.push("GT") if gt
+        args.push("LT") if lt
+        args
+      end
+    end
+  end
+end