hotkv 1.0.0

data/lib/hotkv/namespaces/ops.rb

@@ -0,0 +1,166 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Namespaces
+    # RATELIMIT.* (needs the RateLimiting license feature).
+    class RateLimit
+      def initialize(client)
+        @client = client
+      end
+
+      def create(name, limit, window_ms, algo: nil, refill: nil, drain: nil)
+        args = ["RATELIMIT.CREATE", name, limit, window_ms]
+        args.push("ALGO", algo) if algo
+        args.push("REFILL", Wire.finite(refill)) if refill
+        args.push("DRAIN", Wire.finite(drain)) if drain
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def check(name, key, cost: nil)
+        args = ["RATELIMIT.CHECK", name, key]
+        args.push("COST", cost) if cost
+        @client.invoke(*args) { |r| result(r) }
+      end
+
+      def peek(name, key)
+        @client.invoke("RATELIMIT.PEEK", name, key) { |r| result(r) }
+      end
+
+      def reset(name, key)
+        @client.invoke("RATELIMIT.RESET", name, key) { |r| r == "OK" }
+      end
+
+      def stats(name)
+        @client.invoke("RATELIMIT.STATS", name) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      def drop(name)
+        @client.invoke("RATELIMIT.DROP", name) { |r| r == "OK" }
+      end
+
+      def list
+        @client.invoke("RATELIMIT.LIST")
+      end
+
+      private
+
+      def result(r)
+        { allowed: r[0] == 1, remaining: r[1], retry_after_ms: r[2], limit: r[3], current: r[4] }
+      end
+    end
+
+    # TS.* (time series; needs the TimeSeries license feature).
+    class TS
+      def initialize(client)
+        @client = client
+      end
+
+      def create(key, retention: nil, labels: nil)
+        args = ["TS.CREATE", key]
+        args.push("RETENTION", retention) if retention
+        args.push("LABELS", *labels.flat_map { |k, v| [k, v] }) if labels && !labels.empty?
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      def add(key, value, timestamp: "*")
+        @client.invoke("TS.ADD", key, timestamp, Wire.finite(value))
+      end
+
+      def range(key, from_ms, to_ms, count: nil)
+        args = ["TS.RANGE", key, from_ms, to_ms]
+        args.push("COUNT", count) if count
+        @client.invoke(*args) { |r| r.map { |(ts, v)| [ts, Wire.parse_float(v)] } }
+      end
+
+      def agg(key, from_ms, to_ms, bucket_ms, agg_type)
+        @client.invoke("TS.AGG", key, from_ms, to_ms, bucket_ms, agg_type) { |r| r.map { |(ts, v)| [ts, Wire.parse_float(v)] } }
+      end
+
+      def info(key)
+        @client.invoke("TS.INFO", key) { |r| Commands::Support.pairs_to_h(r, float_keys: %i[lastValue]) }
+      end
+
+      def delete(key)
+        @client.invoke("TS.DELETE", key) { |r| r == "OK" }
+      end
+
+      def retention(key, retention_ms)
+        @client.invoke("TS.RETENTION", key, retention_ms) { |r| r == "OK" }
+      end
+
+      def downsample(src_key, dest_key, agg_type, bucket_ms)
+        @client.invoke("TS.DOWNSAMPLE", src_key, dest_key, agg_type, bucket_ms) { |r| r == "OK" }
+      end
+
+      def list(label: nil, value: nil)
+        args = ["TS.LIST"]
+        args.push("LABEL", label, value) if label
+        @client.invoke(*args)
+      end
+    end
+
+    # FEATURE.* (feature store; needs the FeatureStore license feature).
+    class Feature
+      def initialize(client)
+        @client = client
+      end
+
+      # +schema+: a Hash {name => type} or a flat [name, type, ...] list.
+      def create(group, description, schema)
+        @client.invoke("FEATURE.CREATE", group, description, "SCHEMA", *flatten_kv(schema)) { |r| r == "OK" }
+      end
+
+      def set(group, entity, values)
+        @client.invoke("FEATURE.SET", group, entity, *flatten_kv(values)) { |r| r == "OK" }
+      end
+
+      # FEATURE.SET with an explicit stamp: +unix_ms+ is the time (Unix
+      # milliseconds, within 100 years of now) the entity is stamped with.
+      def setat(group, entity, unix_ms, values)
+        @client.invoke("FEATURE.SETAT", group, entity, unix_ms, *flatten_kv(values)) { |r| r == "OK" }
+      end
+
+      def get(group, entity, features = nil)
+        args = ["FEATURE.GET", group, entity]
+        args.concat(Array(features)) if features
+        @client.invoke(*args) { |r| result(r) }
+      end
+
+      def batch(group, entities, features: nil)
+        args = ["FEATURE.BATCH", group, *entities]
+        args.push("FEATURES", *features) if features
+        @client.invoke(*args) { |r| r.map { |row| result(row) } }
+      end
+
+      def schema(group)
+        @client.invoke("FEATURE.SCHEMA", group)
+      end
+
+      def list
+        @client.invoke("FEATURE.LIST")
+      end
+
+      def drop(group)
+        @client.invoke("FEATURE.DROP", group) { |r| r == "OK" }
+      end
+
+      def stats(group)
+        @client.invoke("FEATURE.STATS", group) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      private
+
+      def flatten_kv(hash_or_pairs)
+        hash_or_pairs.is_a?(Hash) ? hash_or_pairs.flatten(1) : hash_or_pairs.flatten
+      end
+
+      def result(row)
+        return nil if row.nil?
+
+        flat, updated_at_ms, freshness_ms = row
+        { values: flat.each_slice(2).to_h, updated_at_ms: updated_at_ms, freshness_ms: freshness_ms }
+      end
+    end
+  end
+end

data/lib/hotkv/namespaces/probabilistic.rb

@@ -0,0 +1,180 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Namespaces
+    # Bloom filter (BF.*). Replies that are booleans on RESP3 and 0/1 on
+    # RESP2 are normalized to true/false.
+    class BF
+      INFO_LABELS = {
+        capacity: "Capacity", size: "Size", filters: "Number of filters",
+        items: "Number of items inserted", expansion: "Expansion rate"
+      }.freeze
+
+      def initialize(client)
+        @client = client
+      end
+
+      # Creates a filter. +error_rate+ is the target false positive rate
+      # (0 < rate < 1), +capacity+ the items it is sized for before it grows.
+      def reserve(key, error_rate, capacity, expansion: nil, nonscaling: false)
+        args = ["BF.RESERVE", key, error_rate, capacity]
+        args.push("EXPANSION", expansion) if expansion
+        args.push("NONSCALING") if nonscaling
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      # Adds +item+; true when it was new, false when it may already exist.
+      def add(key, item)
+        @client.invoke("BF.ADD", key, item) { |r| Commands::Support.truthy(r) }
+      end
+
+      def madd(key, *items)
+        @client.invoke("BF.MADD", key, *items.flatten) { |r| r.map { |v| Commands::Support.truthy(v) } }
+      end
+
+      # Adds items, creating the filter with the options when missing.
+      def insert(key, items, capacity: nil, error: nil, expansion: nil, nocreate: false, nonscaling: false)
+        args = ["BF.INSERT", key]
+        args.push("CAPACITY", capacity) if capacity
+        args.push("ERROR", error) if error
+        args.push("EXPANSION", expansion) if expansion
+        args.push("NOCREATE") if nocreate
+        args.push("NONSCALING") if nonscaling
+        args.push("ITEMS", *Array(items))
+        @client.invoke(*args) { |r| r.map { |v| Commands::Support.truthy(v) } }
+      end
+
+      # True when +item+ may be in the filter (false: definitely not).
+      def exists(key, item)
+        @client.invoke("BF.EXISTS", key, item) { |r| Commands::Support.truthy(r) }
+      end
+
+      def mexists(key, *items)
+        @client.invoke("BF.MEXISTS", key, *items.flatten) { |r| r.map { |v| Commands::Support.truthy(v) } }
+      end
+
+      # Number of items added.
+      def card(key)
+        @client.invoke("BF.CARD", key)
+      end
+
+      # Hash of "Capacity", "Size", "Number of filters", "Number of items
+      # inserted", "Expansion rate"; with +field+ (:capacity, :size, :filters,
+      # :items, :expansion) a Hash of just that one.
+      def info(key, field = nil)
+        args = ["BF.INFO", key]
+        args.push(field.to_s.upcase) if field
+        @client.invoke(*args) do |r|
+          if r.is_a?(Hash) then r
+          elsif field then { INFO_LABELS.fetch(field.to_s.downcase.to_sym, field.to_s) => r.first } # RESP2: just the value
+          else r.each_slice(2).to_h
+          end
+        end
+      end
+
+      # One chunk of the filter: [next_iterator, data]. Start with iterator 0;
+      # a returned iterator of 0 ends the dump.
+      def scandump(key, iterator)
+        @client.invoke("BF.SCANDUMP", key, iterator)
+      end
+
+      def loadchunk(key, iterator, data)
+        @client.invoke("BF.LOADCHUNK", key, iterator, data) { |r| r == "OK" }
+      end
+    end
+
+    # Count-Min Sketch (CMS.*).
+    class CMS
+      def initialize(client)
+        @client = client
+      end
+
+      def initbydim(key, width, depth)
+        @client.invoke("CMS.INITBYDIM", key, width, depth) { |r| r == "OK" }
+      end
+
+      def initbyprob(key, error, probability)
+        @client.invoke("CMS.INITBYPROB", key, error, probability) { |r| r == "OK" }
+      end
+
+      # +increments+ is a Hash or a flat [item, increment, ...] list. Returns
+      # the new estimated counts in order.
+      def incrby(key, increments)
+        flat = increments.is_a?(Hash) ? increments.flatten(1) : increments.flatten
+        @client.invoke("CMS.INCRBY", key, *flat)
+      end
+
+      def query(key, *items)
+        @client.invoke("CMS.QUERY", key, *items.flatten)
+      end
+
+      # Hash with "width", "depth" and "count".
+      def info(key)
+        @client.invoke("CMS.INFO", key) { |r| r.is_a?(Hash) ? r : r.each_slice(2).to_h }
+      end
+
+      # Replaces +destination+ with the (optionally weighted) sum of +sources+.
+      def merge(destination, sources, weights: nil)
+        args = ["CMS.MERGE", destination, sources.length, *sources]
+        args.push("WEIGHTS", *weights) if weights
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+    end
+
+    # Top-K (TOPK.*).
+    class TopK
+      def initialize(client)
+        @client = client
+      end
+
+      def reserve(key, topk, width: nil, depth: nil, decay: nil)
+        args = ["TOPK.RESERVE", key, topk]
+        given = [width, depth, decay].count { |v| !v.nil? }
+        raise Error::ArgumentError, "width, depth and decay go together: give all three or none" unless [0, 3].include?(given)
+
+        args.push(width, depth, decay) if given == 3
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      # Counts the items; each reply element is the item pushed out of the
+      # list, or nil.
+      def add(key, *items)
+        @client.invoke("TOPK.ADD", key, *items.flatten)
+      end
+
+      # +increments+ is a Hash or a flat [item, increment, ...] list.
+      def incrby(key, increments)
+        flat = increments.is_a?(Hash) ? increments.flatten(1) : increments.flatten
+        @client.invoke("TOPK.INCRBY", key, *flat)
+      end
+
+      def query(key, *items)
+        @client.invoke("TOPK.QUERY", key, *items.flatten) { |r| r.map { |v| Commands::Support.truthy(v) } }
+      end
+
+      def count(key, *items)
+        @client.invoke("TOPK.COUNT", key, *items.flatten)
+      end
+
+      # The list, highest count first; with :withcount an Array of
+      # [item, count] pairs.
+      def list(key, withcount: false)
+        return @client.invoke("TOPK.LIST", key) unless withcount
+
+        @client.invoke("TOPK.LIST", key, "WITHCOUNT") do |r|
+          r.first.is_a?(Array) ? r : r.each_slice(2).to_a
+        end
+      end
+
+      # Hash with "k", "width", "depth" and "decay" (Float).
+      def info(key)
+        @client.invoke("TOPK.INFO", key) do |r|
+          h = r.is_a?(Hash) ? r : r.each_slice(2).to_h
+          h["decay"] = Wire.parse_float(h["decay"]) if h.key?("decay")
+          h
+        end
+      end
+    end
+  end
+end

data/lib/hotkv/namespaces/rag.rb

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Namespaces
+    # RAG.* (needs the RAGPipeline license feature): a
+    # retrieval pipeline with hybrid vector + BM25 search.
+    class RAG
+      def initialize(client)
+        @client = client
+      end
+
+      def create(name, dimensions, strategy: nil, chunk_size: nil, chunk_overlap: nil)
+        args = ["RAG.CREATE", name, dimensions]
+        args.push("STRATEGY", strategy) if strategy
+        args.push("CHUNK_SIZE", chunk_size) if chunk_size
+        args.push("CHUNK_OVERLAP", chunk_overlap) if chunk_overlap
+        @client.invoke(*args) { |r| r == "OK" }
+      end
+
+      # +meta+: a Hash of metadata key/values to attach to +doc_id+.
+      # +vectors+: an Array of embedding vectors (each an Array of Floats),
+      # one per chunk the server will split +text+ into.
+      def ingest(pipeline, doc_id, text, meta: nil, vectors: nil)
+        args = ["RAG.INGEST", pipeline, doc_id, text]
+        args.push("META", *meta.flat_map { |k, v| [k, v] }) if meta && !meta.empty?
+        args.push("VECTORS", *vectors.map { |v| Wire.csv_vector(v) }) if vectors && !vectors.empty?
+        @client.invoke(*args)
+      end
+
+      def search(pipeline, query_text, k: nil, alpha: nil, vector: nil, filter: nil)
+        args = ["RAG.SEARCH", pipeline, query_text]
+        args.push("K", k) if k
+        args.push("ALPHA", Wire.finite(alpha)) if alpha
+        args.push("VECTOR", Wire.csv_vector(vector)) if vector
+        args.push("FILTER", *filter.flat_map { |fk, fv| [fk, fv] }) if filter && !filter.empty?
+        @client.invoke(*args) { |r| r.map { |row| search_row(row) } }
+      end
+
+      def stats(pipeline)
+        @client.invoke("RAG.STATS", pipeline) { |r| Commands::Support.pairs_to_h(r) }
+      end
+
+      def drop(pipeline)
+        @client.invoke("RAG.DROP", pipeline) { |r| r == "OK" }
+      end
+
+      def list
+        @client.invoke("RAG.LIST")
+      end
+
+      private
+
+      def search_row(row)
+        chunk_id, doc_id, text, score, vector_score, bm25_score, *rest = row
+        meta = {}
+        rest.each_slice(2) { |(k, v)| meta[k] = v }
+        { chunk_id: chunk_id, doc_id: doc_id, text: text, score: Wire.parse_float(score),
+          vector_score: Wire.parse_float(vector_score), bm25_score: Wire.parse_float(bm25_score), meta: meta }
+      end
+    end
+  end
+end

data/lib/hotkv/pipeline.rb

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Client side command batching: every command queued inside the block
+  # given to HotKV::Client#pipelined is written to the server in one burst
+  # and all replies are read back in one pass, cutting round trips to one.
+  # Supports every typed command method the client does (Pipeline includes
+  # the same command modules), plus the raw #command escape hatch.
+  #
+  #   results = client.pipelined do |p|
+  #     p.set("a", "1")
+  #     p.incr("a")
+  #   end
+  #   results # => ["OK", 2]
+  #
+  # A command that itself fails does not abort the batch: its slot in the
+  # returned array holds the HotKV::Error instance instead of a value.
+  class Pipeline
+    include Commands::All
+
+    def initialize(connection)
+      @connection = connection
+      @queue = []
+    end
+
+    # Queues a raw command, returning a Future resolved to its decoded
+    # reply (or the error) once #execute runs.
+    def command(*args, &transform)
+      invoke(*args, &transform)
+    end
+    alias_method :call, :command
+
+    def invoke(*args, &transform)
+      future = Future.new(&transform)
+      @queue << [args, future]
+      future
+    end
+
+    def size
+      @queue.size
+    end
+
+    # Writes every queued command and reads back every reply, in order.
+    # Returns a plain Array of resolved values (or per command Error
+    # instances); never raises for an individual command's failure.
+    def execute
+      return [] if @queue.empty?
+
+      @queue.each { |(args, _future)| @connection.write_command(args) }
+      @queue.each { |(_args, future)| future.resolve(@connection.read_reply(raise_on_error: false)) }
+      @queue.map { |(_args, future)| future.value }
+    ensure
+      @queue = []
+    end
+  end
+end

data/lib/hotkv/pool.rb

@@ -0,0 +1,123 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require "monitor"
+
+module HotKV
+  # A bounded pool of HotKV::Connection objects, safe for concurrent use by
+  # multiple threads. Connections idle for longer than +idle_timeout+
+  # seconds are health checked with PING before being handed out again, and
+  # discarded (not returned to the caller) if the check fails.
+  class Pool
+    def initialize(options, size:, idle_timeout:, pool_timeout:)
+      @options = options
+      @size = size
+      @idle_timeout = idle_timeout
+      @pool_timeout = pool_timeout
+      @available = []
+      @created = 0
+      @monitor = Monitor.new
+      @resource = @monitor.new_cond
+      @shutdown = false
+    end
+
+    # Checks out a connection, yields it, and always returns it to the pool
+    # (or discards it, if it turned out to be broken).
+    def with_connection
+      conn = checkout
+      healthy = true
+      begin
+        yield conn
+      rescue Error::ConnectionError, Error::TimeoutError
+        healthy = false
+        raise
+      ensure
+        if healthy
+          checkin(conn)
+        else
+          conn.close
+          @monitor.synchronize do
+            @created -= 1
+            @resource.signal
+          end
+        end
+      end
+    end
+
+    def checkout(timeout: @pool_timeout)
+      deadline = timeout ? monotonic_now + timeout : nil
+      @monitor.synchronize do
+        loop do
+          raise Error::ConnectionError, "connection pool has been shut down" if @shutdown
+
+          while (conn = @available.pop)
+            if healthy?(conn)
+              return conn
+            else
+              conn.close
+              @created -= 1
+            end
+          end
+          if @created < @size
+            @created += 1
+            break
+          end
+          wait_time = deadline ? deadline - monotonic_now : nil
+          raise Error::ConnectionError, "timed out waiting for a pooled connection" if deadline && wait_time <= 0
+
+          @resource.wait(wait_time)
+        end
+      end
+      begin
+        Connection.new(@options).connect
+      rescue StandardError
+        @monitor.synchronize do
+          @created -= 1
+          @resource.signal
+        end
+        raise
+      end
+    end
+
+    def checkin(conn)
+      @monitor.synchronize do
+        if @shutdown || !conn.connected?
+          conn.close
+          @created -= 1
+        else
+          @available.push(conn)
+        end
+        @resource.signal
+      end
+    end
+
+    def shutdown
+      @monitor.synchronize do
+        @shutdown = true
+        @available.each(&:close)
+        @available.clear
+        @created = 0
+        @resource.broadcast
+      end
+    end
+
+    def size
+      @monitor.synchronize { @created }
+    end
+
+    private
+
+    def healthy?(conn)
+      return false unless conn.connected?
+
+      conn.ping if @idle_timeout && conn.idle_seconds > @idle_timeout
+      true
+    rescue Error::ConnectionError, Error::TimeoutError
+      false
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/hotkv/pubsub.rb

@@ -0,0 +1,60 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Yielded by HotKV::Client#subscribe, #psubscribe and #ssubscribe. Register
+  # callbacks for the frames a subscription connection receives; the
+  # subscribe family methods also double as a way to change the
+  # subscription while the loop is running, when called with channel/pattern
+  # arguments and no block:
+  #
+  #   client.subscribe("news") do |on|
+  #     on.message { |channel, payload| puts "#{channel}: #{payload}" }
+  #     on.subscribe { |channel, total| puts "listening on #{channel}" }
+  #   end
+  #
+  #   client.subscribe("news") do |on|
+  #     on.message do |channel, payload|
+  #       on.unsubscribe if payload == "stop" # ends the loop once confirmed
+  #     end
+  #   end
+  class PubSub
+    CALLBACK_KINDS = %i[message pmessage smessage subscribe unsubscribe psubscribe punsubscribe ssubscribe
+                         sunsubscribe].freeze
+    COMMAND_KINDS = %i[subscribe unsubscribe psubscribe punsubscribe ssubscribe sunsubscribe].freeze
+
+    def initialize
+      @callbacks = Hash.new { |h, k| h[k] = [] }
+      @connection = nil
+    end
+
+    def bind(connection)
+      @connection = connection
+      self
+    end
+
+    def dispatch(kind, *args)
+      @callbacks[kind].each { |cb| cb.call(*args) }
+    end
+
+    CALLBACK_KINDS.each do |kind|
+      define_method(kind) do |*args, &block|
+        if block
+          @callbacks[kind] << block
+          self
+        elsif COMMAND_KINDS.include?(kind)
+          send_wire(kind, args)
+        else
+          raise Error::ArgumentError, "#{kind} needs a block to register a callback"
+        end
+      end
+    end
+
+    private
+
+    def send_wire(kind, targets)
+      @connection.write_command(targets.empty? ? [kind.to_s.upcase] : [kind.to_s.upcase, *targets])
+      nil
+    end
+  end
+end