hotkv 1.0.0

data/lib/hotkv/resp.rb

@@ -0,0 +1,176 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # A plain Ruby String subclass that remembers the three letter format tag
+  # ("txt" or "mkd") a RESP3 verbatim string (`=`) reply carried. Behaves as
+  # an ordinary String everywhere; only +format+ is extra.
+  class VerbatimString < String
+    attr_reader :format
+
+    def initialize(content, format)
+      super(content)
+      @format = format
+    end
+  end
+
+  # Low level RESP2/RESP3 request encoder and reply decoder. Every reply
+  # type in the protocol is handled: simple string, error, integer, bulk
+  # string, array, null, boolean, double, big number, blob error, verbatim
+  # string, map, set, attribute and push. Operates on any object that
+  # responds to #gets(separator) and #read(length) the way IO and StringIO
+  # do, so it needs no live socket to be unit tested.
+  module RESP
+    CRLF = "\r\n".b
+    private_constant :CRLF
+
+    module_function
+
+    # Encodes +args+ (Strings, Symbols, Integers, Floats, ...) as one RESP
+    # array of bulk strings, the wire form every RESP server
+    # expects a client request in, regardless of RESP2 or RESP3.
+    def encode_command(args)
+      out = String.new(+"*#{args.length}\r\n", encoding: Encoding::BINARY)
+      args.each do |a|
+        s = to_wire_string(a)
+        out << "$" << s.bytesize.to_s << CRLF << s << CRLF
+      end
+      out
+    end
+
+    # Strings go out byte for byte. Integers use their decimal text. Every
+    # other number (Float, BigDecimal, Rational) is written by Wire.float:
+    # plain decimal, never an exponent such as "1.0e-05", which the server's
+    # stricter numeric parsers refuse.
+    def to_wire_string(arg)
+      case arg
+      when String then arg.b
+      when Integer then arg.to_s.b
+      when Numeric then Wire.float(arg).b
+      else arg.to_s.b
+      end
+    end
+
+    # Reads exactly one reply from +io+.
+    #
+    # +raise_on_error+ governs only the value this call itself returns: when
+    # true (the default) a top level error reply is raised as a
+    # HotKV::Error::ServerError subclass; when false it is returned as that
+    # exception instance instead. Either way, an error found while decoding
+    # an element nested inside an array/map/set/push is always returned
+    # inline as the exception instance (never raised), so one failed command
+    # inside a MULTI/EXEC or pipeline reply never discards the rest of it.
+    def read_reply(io, raise_on_error: true)
+      value = read_value(io)
+      raise value if raise_on_error && value.is_a?(Error::ServerError)
+
+      value
+    end
+
+    def read_value(io)
+      line = read_line(io)
+      type = line.getbyte(0)
+      raise Error::ProtocolError, "malformed RESP reply: empty line where a type byte was expected" if type.nil?
+
+      body = line.byteslice(1..-1)
+      begin
+        decode(type, body, io)
+      rescue ArgumentError, RangeError => e
+        raise Error::ProtocolError, "malformed RESP reply near #{line.inspect}: #{e.message}"
+      end
+    end
+
+    def decode(type, body, io)
+      case type
+      when 43 then body                                    # '+' simple string
+      when 45 then Error::ServerError.from_message(body)    # '-' error
+      when 58 then Integer(body)                            # ':' integer
+      when 36 then read_bulk(io, body)                      # '$' bulk string
+      when 42 then read_array(io, body)                     # '*' array
+      when 95 then nil                                      # '_' null
+      when 35 then body == "t"                              # '#' boolean
+      when 44 then read_double(body)                        # ',' double
+      when 40 then Integer(body)                            # '(' big number
+      when 33 then Error::ServerError.from_message(read_bulk(io, body)) # '!' blob error
+      when 61 then read_verbatim(io, body)                  # '=' verbatim string
+      when 37 then read_map(io, body)                       # '%' map
+      when 126 then read_multi(io, body)                    # '~' set
+      when 62 then read_multi(io, body)                     # '>' push
+      when 124 then read_attribute(io, body)                # '|' attribute (transparent)
+      else
+        raise Error::ProtocolError, "unknown RESP type byte #{type.chr.inspect}"
+      end
+    end
+
+    def read_line(io)
+      line = io.gets(CRLF)
+      raise Error::ConnectionError, "connection closed by server" if line.nil?
+      raise Error::ConnectionError, "connection closed by server (truncated reply line)" unless line.chomp!(CRLF)
+
+      line
+    end
+
+    def read_exact(io, n)
+      return "".b if n.zero?
+
+      data = io.read(n)
+      raise Error::ConnectionError, "connection closed by server (expected #{n} bytes)" if data.nil? || data.bytesize != n
+
+      data
+    end
+
+    def read_bulk(io, len_str)
+      len = Integer(len_str)
+      return nil if len.negative?
+
+      data = read_exact(io, len)
+      terminator = read_exact(io, 2)
+      raise Error::ProtocolError, "malformed bulk string terminator" unless terminator == CRLF
+
+      data
+    end
+
+    def read_verbatim(io, len_str)
+      payload = read_bulk(io, len_str)
+      return nil if payload.nil?
+
+      VerbatimString.new(payload.byteslice(4..-1) || "".b, payload.byteslice(0, 3))
+    end
+
+    def read_double(body)
+      case body
+      when "inf" then Float::INFINITY
+      when "-inf" then -Float::INFINITY
+      when "nan" then Float::NAN
+      else Float(body)
+      end
+    end
+
+    def read_array(io, len_str)
+      len = Integer(len_str)
+      return nil if len.negative? # RESP2 null array
+
+      Array.new(len) { read_value(io) }
+    end
+
+    def read_multi(io, len_str)
+      Array.new(Integer(len_str)) { read_value(io) }
+    end
+
+    def read_map(io, len_str)
+      count = Integer(len_str)
+      h = {}
+      count.times { h[read_value(io)] = read_value(io) }
+      h
+    end
+
+    def read_attribute(io, len_str)
+      count = Integer(len_str)
+      count.times do
+        read_value(io)
+        read_value(io)
+      end
+      read_value(io) # the attribute precedes and annotates the value that follows it
+    end
+  end
+end

data/lib/hotkv/transaction.rb

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Server side MULTI/EXEC transaction. Every command queued inside the
+  # block given to HotKV::Client#multi (or HotKV::WatchSession#multi) is
+  # sent to the server immediately and queued there; #exec runs EXEC and
+  # resolves every queued command's Future from the resulting array.
+  #
+  #   result = client.multi do |tx|
+  #     tx.set("a", "1")
+  #     tx.incr("a")
+  #   end
+  #   result # => ["OK", 2], or nil if a watched key changed first
+  class Transaction
+    include Commands::All
+
+    def initialize(connection)
+      @connection = connection
+      @queue = []
+    end
+
+    def command(*args, &transform)
+      invoke(*args, &transform)
+    end
+    alias_method :call, :command
+
+    # Sends +args+ to the server right away (MULTI is already active), so a
+    # bad command is caught as soon as it is queued, exactly like the
+    # server itself does.
+    def invoke(*args, &transform)
+      @connection.write_command(args)
+      reply = @connection.read_reply(raise_on_error: false)
+      future = Future.new(&transform)
+      if reply.is_a?(Error::ServerError)
+        future.resolve_error(reply)
+        @queue << [true, future]
+      else
+        @queue << [false, future]
+      end
+      future
+    end
+
+    def size
+      @queue.size
+    end
+
+    # Runs EXEC and resolves every queued Future. Returns a plain Array of
+    # resolved values (or per command Error instances) in queue order, or
+    # nil if the transaction was aborted because a watched key changed.
+    def exec
+      @connection.write_command(["EXEC"])
+      raw = @connection.read_reply(raise_on_error: false)
+      return nil if raw.nil?
+      raise raw if raw.is_a?(Error::ServerError)
+
+      idx = 0
+      @queue.each do |(already_resolved, future)|
+        next if already_resolved
+
+        future.resolve(raw[idx])
+        idx += 1
+      end
+      @queue.map { |(_resolved, future)| future.value }
+    end
+  end
+
+  # Yielded by HotKV::Client#watch. Bound to a single connection for the
+  # life of the watch block so that reads used to decide whether to
+  # transact, and the eventual transaction itself, see a consistent view
+  # and share the same WATCH state. Supports every typed command method
+  # (run immediately against the watched connection) plus #multi to start
+  # the actual MULTI/EXEC transaction.
+  class WatchSession
+    include Commands::All
+
+    def initialize(connection)
+      @connection = connection
+      @multi_started = false
+    end
+
+    def multi_started?
+      @multi_started
+    end
+
+    def invoke(*args)
+      raw = @connection.call(*args, raise_on_error: false)
+      raise raw if raw.is_a?(Error::ServerError)
+
+      block_given? ? yield(raw) : raw
+    end
+
+    def command(*args)
+      invoke(*args) { |raw| raw }
+    end
+    alias_method :call, :command
+
+    # Starts MULTI on the watched connection, yields a Transaction to queue
+    # commands on, and runs EXEC. Returns whatever Transaction#exec returns.
+    def multi
+      raise Error::ArgumentError, "multi requires a block" unless block_given?
+
+      @connection.call("MULTI")
+      @multi_started = true
+      tx = Transaction.new(@connection)
+      begin
+        yield tx
+      rescue StandardError
+        @connection.call("DISCARD", raise_on_error: false)
+        raise
+      end
+      tx.exec
+    end
+  end
+end

data/lib/hotkv/url.rb

@@ -0,0 +1,100 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require "uri"
+
+module HotKV
+  # Parses HotKV connection URLs into the option hash HotKV::Client#initialize
+  # understands. Accepts the native `hotkv://` / `hotkvs://` (TLS) schemes and,
+  # for drop in migration from other clients, `redis://` / `rediss://` and the
+  # unix socket forms `hotkv+unix://` / `redis+unix://`.
+  module URL
+    TLS_SCHEMES = %w[hotkvs rediss].freeze
+    PLAIN_SCHEMES = %w[hotkv redis].freeze
+    UNIX_SCHEMES = %w[hotkv+unix redis+unix].freeze
+    DEFAULT_PORT = 6379
+
+    module_function
+
+    # Returns a Hash of connection options parsed out of +url+, using only
+    # the keys that were present in the URL. HotKV::Client merges this under
+    # its explicit keyword options, so an explicit keyword always wins.
+    def parse(url)
+      raise Error::ArgumentError, "url must be a String, got #{url.class}" unless url.is_a?(String)
+
+      uri = begin
+        URI.parse(url)
+      rescue URI::InvalidURIError => e
+        raise Error::ArgumentError, "invalid HotKV URL #{url.inspect}: #{e.message}"
+      end
+      scheme = uri.scheme&.downcase
+      opts = {}
+
+      if UNIX_SCHEMES.include?(scheme)
+        path = uri.path
+        path = uri.opaque if path.nil? || path.empty?
+        raise Error::ArgumentError, "#{scheme}:// URL must include a socket path" if path.nil? || path.empty?
+
+        opts[:path] = path
+      elsif TLS_SCHEMES.include?(scheme) || PLAIN_SCHEMES.include?(scheme)
+        opts[:ssl] = TLS_SCHEMES.include?(scheme)
+        opts[:host] = (uri.host && !uri.host.empty?) ? uri.host : "127.0.0.1"
+        opts[:port] = uri.port || DEFAULT_PORT
+      else
+        raise Error::ArgumentError,
+              "unsupported HotKV URL scheme #{uri.scheme.inspect}, expected hotkv://, hotkvs://, " \
+              "redis://, rediss:// or a +unix variant"
+      end
+
+      apply_userinfo!(opts, uri.userinfo)
+      apply_path_db!(opts, uri.path) unless UNIX_SCHEMES.include?(scheme)
+      apply_query!(opts, uri.query)
+      opts
+    end
+
+    def apply_userinfo!(opts, userinfo)
+      return unless userinfo
+
+      if userinfo.include?(":")
+        user, pass = userinfo.split(":", 2)
+      else
+        user, pass = userinfo, nil
+      end
+      opts[:username] = URI.decode_www_form_component(user) if user && !user.empty?
+      opts[:password] = URI.decode_www_form_component(pass) if pass
+    end
+    private_class_method :apply_userinfo!
+
+    def apply_path_db!(opts, path)
+      return if path.nil?
+
+      db = path.sub(%r{\A/}, "")
+      opts[:db] = Integer(db) unless db.empty?
+    rescue ArgumentError
+      raise Error::ArgumentError, "invalid database index in URL path #{path.inspect}"
+    end
+    private_class_method :apply_path_db!
+
+    QUERY_BOOLEANS = %w[insecure_skip_verify skip_verify].freeze
+    private_constant :QUERY_BOOLEANS
+
+    def apply_query!(opts, query)
+      return if query.nil? || query.empty?
+
+      URI.decode_www_form(query).each do |key, value|
+        case key
+        when "db", "database" then opts[:db] = Integer(value)
+        when "client_name", "clientname" then opts[:client_name] = value
+        when "connect_timeout" then opts[:connect_timeout] = Float(value)
+        when "timeout", "command_timeout", "read_timeout" then opts[:command_timeout] = Float(value)
+        when "ca_file", "sslcacert" then opts[:ca_file] = value
+        when "cert_file", "sslcert" then opts[:cert_file] = value
+        when "key_file", "sslkey" then opts[:key_file] = value
+        when "server_name", "sni" then opts[:server_name] = value
+        when *QUERY_BOOLEANS then opts[:insecure_skip_verify] = %w[1 true yes].include?(value.to_s.downcase)
+        end
+      end
+    end
+    private_class_method :apply_query!
+  end
+end

data/lib/hotkv/usage.rb

@@ -0,0 +1,42 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # One model call's token usage: the token usage group shared by
+  # PCACHE.SET, SCACHE.SET, every keyed cache SET (TOOL.CACHE/NCACHE/
+  # GUARD/RERANK) and LLMBUDGET.CONSUME.
+  #
+  # Recording a TokenUsage with a cache entry lets a later cache hit
+  # attribute its tokens, and once the model is priced its exact cost, to
+  # the namespace's usage_saved_* stats fields.
+  #
+  # +model+ is required; every count defaults to 0 and is left off the
+  # wire when zero (MODEL itself is always sent once a TokenUsage is
+  # given):
+  #
+  #   usage = HotKV::TokenUsage.new(model: "claude-sonnet-5", input_tokens: 120, output_tokens: 40)
+  #   client.pcache.set(ns, prompt, response, usage: usage)
+  TokenUsage = Struct.new(
+    :model, :input_tokens, :output_tokens, :cache_read_tokens, :cache_write_5m_tokens,
+    :cache_write_1h_tokens,
+    keyword_init: true
+  ) do
+    def initialize(model:, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0,
+                   cache_write_5m_tokens: 0, cache_write_1h_tokens: 0)
+      super
+    end
+
+    # The `MODEL <model> [INPUT n] [OUTPUT n] [CACHEREAD n] [CACHEWRITE5M
+    # n] [CACHEWRITE1H n]` KEY VALUE pairs this usage adds to a command's
+    # trailing options.
+    def wire_args
+      args = ["MODEL", model]
+      args.push("INPUT", input_tokens) unless input_tokens.zero?
+      args.push("OUTPUT", output_tokens) unless output_tokens.zero?
+      args.push("CACHEREAD", cache_read_tokens) unless cache_read_tokens.zero?
+      args.push("CACHEWRITE5M", cache_write_5m_tokens) unless cache_write_5m_tokens.zero?
+      args.push("CACHEWRITE1H", cache_write_1h_tokens) unless cache_write_1h_tokens.zero?
+      args
+    end
+  end
+end

data/lib/hotkv/version.rb

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Current release version of the hotkv gem.
+  VERSION = "1.0.0"
+end

data/lib/hotkv/wire.rb

@@ -0,0 +1,145 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Formatting of numeric command arguments, in one place.
+  #
+  # Ruby's Float#to_s switches to exponent form for small and large values
+  # ("1.0e-05", "1.0e+16"). Several server parsers refuse that form: the
+  # fixed point USD parser behind LLMBUDGET.SET and LLMSTATS.PRICE SET accepts
+  # plain digits only, with no exponent. Every Float, BigDecimal or Rational a
+  # caller hands to a command is therefore written by #float: plain decimal,
+  # the shortest digits that round trip, never an exponent, never locale
+  # dependent (no String#% or Kernel#format involved).
+  module Wire
+    module_function
+
+    FLOAT_PARTS = /\A(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?\z/.freeze
+    private_constant :FLOAT_PARTS
+
+    # Plain decimal text for +value+ (Integer, Float, BigDecimal, Rational).
+    # Infinity becomes "inf"/"-inf" (what the server's score parsers accept);
+    # NaN raises HotKV::Error::ArgumentError.
+    def float(value)
+      case value
+      when Integer then value.to_s
+      when Float then float_text(value)
+      when Rational then float_text(value.to_f)
+      when Numeric
+        raise Error::ArgumentError, "cannot format #{value.class} as a number" if value.respond_to?(:real?) && !value.real?
+
+        decimal_text(value)
+      else
+        raise Error::ArgumentError, "expected a number, got #{value.inspect}"
+      end
+    end
+
+    # Parses a float out of a server reply. Numbers pass through; Strings
+    # follow strtod, which is what the server prints with: "inf", "+inf",
+    # "-inf", "infinity" and "nan" (any case) as well as ordinary decimals and
+    # exponent forms. Kernel#Float alone refuses "inf", which a RESP2 reply
+    # gives for an infinite sorted set score.
+    def parse_float(value)
+      return value.to_f if value.is_a?(Numeric)
+      raise TypeError, "can't convert #{value.class} into Float" unless value.is_a?(String)
+
+      case value.downcase
+      when "inf", "+inf", "infinity", "+infinity" then Float::INFINITY
+      when "-inf", "-infinity" then -Float::INFINITY
+      when "nan", "+nan", "-nan" then Float::NAN
+      else Float(value)
+      end
+    end
+
+    # Returns +value+ unchanged after refusing NaN and +/-Infinity, for the
+    # arguments where the server accepts finite numbers only (INCRBYFLOAT,
+    # coordinates, similarity thresholds, vector components, ...). Non numeric
+    # values (Strings, nil) are passed through for the server to judge.
+    def finite(value)
+      if value.is_a?(Numeric) && !value.is_a?(Integer) && !value.is_a?(Rational)
+        raise Error::ArgumentError, "expected a finite number, got #{value}" if value.nan? || value.infinite?
+      end
+      value
+    end
+
+    # Applies #finite to every component of +vector+ and returns an Array.
+    def finite_vector(vector)
+      Array(vector).map { |component| finite(component) }
+    end
+
+    # Comma joined plain decimal components, the form RAG.INGEST VECTORS and
+    # RAG.SEARCH VECTOR take.
+    def csv_vector(vector)
+      Array(vector).map { |component| float(finite(component)) }.join(",")
+    end
+
+    # A US dollar amount in the fixed point form the server's money parser
+    # takes: digits, an optional dot and at most 6 decimals (micro dollars),
+    # no sign, no exponent, never ".5" or "5.". Numbers are rounded to the
+    # nearest micro dollar; negative, NaN and infinite values raise, and so
+    # does a non zero amount too small to survive the rounding (it would
+    # otherwise silently become 0, which means "no limit" to LLMBUDGET.SET).
+    # Strings pass through untouched for the server to validate.
+    def usd(value)
+      return value if value.is_a?(String)
+      raise Error::ArgumentError, "expected a USD amount, got #{value.inspect}" unless value.is_a?(Numeric)
+
+      text = float(value)
+      raise Error::ArgumentError, "USD amount must be finite, got #{value}" if text.end_with?("inf")
+      raise Error::ArgumentError, "USD amount must not be negative, got #{value}" if text.start_with?("-") && text != "-0"
+
+      micros = (Rational(text) * 1_000_000).round
+      raise Error::ArgumentError, "USD amount #{text} is below one micro dollar" if micros.zero? && Rational(text) != 0
+
+      whole, frac = micros.divmod(1_000_000)
+      return whole.to_s if frac.zero?
+
+      "#{whole}.#{frac.to_s.rjust(6, '0').sub(/0+\z/, '')}"
+    end
+
+    def float_text(value)
+      raise Error::ArgumentError, "NaN is not a valid number" if value.nan?
+      return(value.positive? ? "inf" : "-inf") if value.infinite?
+
+      expand(value.to_s)
+    end
+    private_class_method :float_text
+
+    # BigDecimal goes through its own decimal string (BigDecimal#to_s("F"))
+    # so it is exact and needs no require of the bigdecimal library; any other
+    # Numeric goes through Float.
+    def decimal_text(value)
+      if value.class.name == "BigDecimal"
+        return float_text(value.to_f) if value.nan? || value.infinite?
+
+        return expand(value.to_s("F"))
+      end
+      float_text(Float(value))
+    end
+    private_class_method :decimal_text
+
+    # Rewrites "1.0e-05", "-2.5E+3", "0.1e-4", "123.456", "1e22" as plain
+    # decimal text with no exponent and no needless trailing zeros.
+    def expand(text)
+      m = FLOAT_PARTS.match(text) or raise Error::ArgumentError, "cannot format #{text.inspect} as a decimal"
+      sign, int, frac, exp = m.captures
+      digits = int + (frac || "")
+      point = int.length + exp.to_i # digits[0, point] is the integer part
+      if point <= 0
+        int_part = "0"
+        frac_part = ("0" * -point) + digits
+      elsif point >= digits.length
+        int_part = digits + ("0" * (point - digits.length))
+        frac_part = ""
+      else
+        int_part = digits[0, point]
+        frac_part = digits[point..]
+      end
+      int_part = int_part.sub(/\A0+(?=\d)/, "")
+      frac_part = frac_part.sub(/0+\z/, "")
+      out = frac_part.empty? ? int_part : "#{int_part}.#{frac_part}"
+      sign == "-" && out != "0" ? "-#{out}" : out
+    end
+    private_class_method :expand
+  end
+end

data/lib/hotkv.rb

@@ -0,0 +1,28 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require_relative "hotkv/version"
+require_relative "hotkv/errors"
+require_relative "hotkv/url"
+require_relative "hotkv/wire"
+require_relative "hotkv/resp"
+require_relative "hotkv/connection"
+require_relative "hotkv/pool"
+require_relative "hotkv/future"
+require_relative "hotkv/usage"
+require_relative "hotkv/llm_price"
+require_relative "hotkv/commands/all"
+require_relative "hotkv/pipeline"
+require_relative "hotkv/transaction"
+require_relative "hotkv/pubsub"
+require_relative "hotkv/cluster/crc16"
+require_relative "hotkv/cluster"
+require_relative "hotkv/client"
+require_relative "hotkv/ai/call_result"
+require_relative "hotkv/ai/prompt_cache"
+require_relative "hotkv/ai/semantic_cache"
+
+# Official HotKV Ruby SDK. Start with HotKV::Client for a single server,
+# or HotKV::Cluster for a HotKV Cluster deployment.
+module HotKV
+end