hotkv 1.0.0

data/lib/hotkv/commands/support.rb

@@ -0,0 +1,69 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  module Commands
+    # Small reply-shaping helpers shared by more than one command module.
+    # Plain module functions (not mixed in) so every command module can
+    # call them without fighting over method resolution order.
+    module Support
+      module_function
+
+      # RESP3 sends a native boolean for some replies; RESP2 sends the
+      # integer 0/1 for the same semantics. Normalizes either to a Ruby bool.
+      def truthy(reply)
+        reply == 1 || reply == true
+      end
+
+      # A member/score (or field/value, ...) reply comes back as a flat
+      # array [m1, s1, m2, s2, ...] in RESP2, or already paired up as
+      # [[m1, s1], [m2, s2], ...] in RESP3. Normalizes to the paired form,
+      # coercing each pair's second element with +value+ (Float() by
+      # default, since scores are the common case).
+      def pairify(reply, &value)
+        value ||= ->(v) { Wire.parse_float(v) }
+        return [] if reply.nil?
+
+        if !reply.empty? && reply.first.is_a?(Array)
+          reply.map { |(k, v)| [k, value.call(v)] }
+        else
+          reply.each_slice(2).map { |(k, v)| [k, value.call(v)] }
+        end
+      end
+
+      # Builds a Hash out of a HotKV fixed schema STATS/INFO reply, parsed
+      # BY FIELD NAME rather than positionally:
+      # a flat array of N pairs (name, value, name, value, ...) under
+      # RESP2, or a native map (already a Hash, string keyed) under RESP3
+      # (HELLO 3), which HotKV sends for these replies either way.
+      # +float_keys+ names the symbol keys whose value should be coerced
+      # with Float() instead of left as the server sent it (already an
+      # Integer for RESP `:` replies).
+      #
+      # A missing field is simply absent from the returned Hash (callers
+      # building a typed Struct fall back to its own defaults); an
+      # unrecognized field whose value cannot be parsed as a number (a
+      # server addition this SDK does not know how to coerce) keeps its
+      # raw value instead of raising. This is what keeps every STATS/INFO
+      # reply forward compatible with a server that adds fields.
+      def pairs_to_h(reply, float_keys: [])
+        h = {}
+        if reply.is_a?(Hash)
+          reply.each { |k, v| h[k.to_sym] = v }
+        else
+          (reply || []).each_slice(2) { |(k, v)| h[k.to_sym] = v }
+        end
+        float_keys.each do |k|
+          next unless h.key?(k)
+
+          begin
+            h[k] = Wire.parse_float(h[k])
+          rescue ArgumentError, TypeError
+            nil # keep the raw value; an unknown/malformed field must never break decoding
+          end
+        end
+        h
+      end
+    end
+  end
+end

data/lib/hotkv/connection.rb

@@ -0,0 +1,221 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require "socket"
+require "openssl"
+require "timeout"
+
+module HotKV
+  # A single RESP2/RESP3 socket connection to one HotKV server. Handles TCP
+  # and unix socket transport, TLS, HELLO 3 negotiation with RESP2 fallback,
+  # authentication, database selection and per operation timeouts. Not safe
+  # for concurrent use by multiple threads; HotKV::Pool is what makes the
+  # client thread safe.
+  class Connection
+    attr_reader :resp3
+    attr_accessor :last_used_at
+
+    def initialize(options)
+      @options = options
+      @socket = nil
+      @resp3 = false
+      @last_used_at = nil
+    end
+
+    def connected?
+      !@socket.nil?
+    end
+
+    # Opens the socket, negotiates the protocol and authenticates. Returns
+    # self so callers can chain `Connection.new(opts).connect`.
+    def connect
+      @socket = open_socket
+      negotiate_protocol
+      select_db
+      @last_used_at = now
+      self
+    rescue StandardError
+      close
+      raise
+    end
+
+    def close
+      @socket&.close
+    rescue IOError, SystemCallError
+      nil
+    ensure
+      @socket = nil
+    end
+
+    # Sends one command and returns its decoded reply.
+    def call(*args, raise_on_error: true)
+      write_command(args)
+      read_reply(raise_on_error: raise_on_error)
+    end
+
+    def write_command(args)
+      with_timeout(@options[:command_timeout]) { @socket.write(RESP.encode_command(args)) }
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError => e
+      close
+      raise Error::ConnectionError, "write failed: #{e.message}"
+    end
+
+    def read_reply(raise_on_error: true)
+      value = with_timeout(@options[:command_timeout]) { RESP.read_reply(@socket, raise_on_error: raise_on_error) }
+      @last_used_at = now
+      value
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError => e
+      close
+      raise Error::ConnectionError, "read failed: #{e.message}"
+    rescue Error::ProtocolError, Error::ConnectionError
+      close
+      raise
+    end
+
+    # Raw IO access for pipelines/pub-sub, which read several replies for
+    # a batch of commands they wrote themselves.
+    def io
+      @socket
+    end
+
+    def ping
+      call("PING")
+    end
+
+    def idle_seconds
+      return 0 if @last_used_at.nil?
+
+      now - @last_used_at
+    end
+
+    private
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def with_timeout(seconds)
+      return yield if seconds.nil? || seconds <= 0
+
+      Timeout.timeout(seconds, Error::TimeoutError, "operation timed out after #{seconds}s") { yield }
+    rescue Error::TimeoutError
+      close
+      raise
+    end
+
+    def open_socket
+      raw = with_timeout(@options[:connect_timeout]) { open_raw_socket }
+      raw.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1) if raw.is_a?(TCPSocket)
+      @options[:ssl] ? wrap_tls(raw) : raw
+    rescue Error::TimeoutError
+      raise
+    rescue SystemCallError, IOError, SocketError => e
+      raise Error::ConnectionError, "connect failed: #{e.message}"
+    end
+
+    def open_raw_socket
+      if @options[:path]
+        UNIXSocket.new(@options[:path])
+      else
+        TCPSocket.new(@options[:host], @options[:port])
+      end
+    end
+
+    # Wraps +raw+ in TLS. Unless :insecure_skip_verify is set the server's
+    # certificate chain is verified (against :ca_file when given, else the
+    # system trust store) and the certificate must match the host name, or the
+    # IP address, being connected to (:server_name overrides the name checked).
+    # The handshake counts against :connect_timeout.
+    def wrap_tls(raw)
+      ssl = nil
+      host = @options[:server_name] || @options[:host]
+      ssl = OpenSSL::SSL::SSLSocket.new(raw, tls_context)
+      ssl.hostname = host
+      ssl.sync_close = true
+      with_timeout(@options[:connect_timeout]) do
+        ssl.connect
+        ssl.post_connection_check(host) unless @options[:insecure_skip_verify]
+      end
+      ssl
+    rescue OpenSSL::SSL::SSLError, SystemCallError, IOError => e
+      close_quietly(ssl || raw)
+      raise Error::ConnectionError, "TLS handshake failed: #{e.message}"
+    rescue Error::TimeoutError
+      close_quietly(ssl || raw)
+      raise
+    end
+
+    def tls_context
+      ctx = OpenSSL::SSL::SSLContext.new
+      if @options[:insecure_skip_verify]
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+      else
+        ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        if @options[:ca_file]
+          ctx.ca_file = @options[:ca_file]
+        else
+          ctx.cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
+        end
+      end
+      ctx.cert = OpenSSL::X509::Certificate.new(File.read(@options[:cert_file])) if @options[:cert_file]
+      ctx.key = OpenSSL::PKey.read(File.read(@options[:key_file])) if @options[:key_file]
+      ctx
+    end
+
+    def close_quietly(io)
+      io&.close
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError
+      nil
+    end
+
+    def negotiate_protocol
+      # :resp3 defaults to true (HELLO 3, falling back to RESP2 only when
+      # the server rejects it); set to false to use RESP2 even against a
+      # server that does support RESP3.
+      if @options.fetch(:resp3, true) == false
+        @resp3 = false
+        legacy_handshake
+        return
+      end
+
+      write_command(hello_args)
+      reply = read_reply(raise_on_error: false)
+      if reply.is_a?(Error::ServerError)
+        raise reply unless hello_unsupported?(reply)
+
+        @resp3 = false
+        legacy_handshake
+      else
+        @resp3 = true
+      end
+    end
+
+    def hello_args
+      args = ["HELLO", "3"]
+      args.push("AUTH", @options[:username] || "default", @options[:password]) if @options[:password]
+      args.push("SETNAME", @options[:client_name]) if @options[:client_name]
+      args
+    end
+
+    def hello_unsupported?(err)
+      err.code == "NOPROTO" || (err.code == "ERR" && err.server_message =~ /unknown command/i)
+    end
+
+    def legacy_handshake
+      if @options[:password]
+        if @options[:username]
+          call("AUTH", @options[:username], @options[:password])
+        else
+          call("AUTH", @options[:password])
+        end
+      end
+      call("CLIENT", "SETNAME", @options[:client_name]) if @options[:client_name]
+    end
+
+    def select_db
+      return unless @options[:db] && !@options[:db].zero?
+
+      call("SELECT", @options[:db])
+    end
+  end
+end

data/lib/hotkv/errors.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
+  module Error
+    # Root of every error the SDK raises.
+    class Base < StandardError
+    end
+
+    # Could not establish, or lost, a connection to a server.
+    class ConnectionError < Base
+    end
+
+    # A connect, read, write or command timeout elapsed.
+    class TimeoutError < Base
+    end
+
+    # The server sent bytes that do not form a valid RESP2/RESP3 reply.
+    class ProtocolError < Base
+    end
+
+    # The URL, option hash or command arguments given to the client are invalid.
+    class ArgumentError < Base
+    end
+
+    # Base class for every `-ERR`/`-<CODE> ...` and RESP3 blob error (`!`)
+    # reply the server sends back for a command. `code` is the leading
+    # error token (e.g. "WRONGTYPE", "NOLICENSE", "ERR"); `server_message`
+    # is the full text the server sent.
+    class ServerError < Base
+      attr_reader :code, :server_message
+
+      def initialize(code, server_message)
+        @code = code
+        @server_message = server_message
+        super(server_message)
+      end
+
+      # Parses a raw error line (without the leading "-"/"!" type byte and
+      # without the trailing CRLF) into the most specific ServerError
+      # subclass known for its leading code word.
+      def self.from_message(message)
+        code, = message.split(" ", 2)
+        code ||= ""
+        klass = CODES[code] || CommandError
+        if klass <= ClusterRedirectError
+          klass.parse(code, message)
+        else
+          klass.new(code, message)
+        end
+      end
+    end
+
+    # Generic `-ERR ...` (and any other unrecognized code) reply.
+    class CommandError < ServerError
+    end
+
+    # `WRONGTYPE Operation against a key holding the wrong kind of value`
+    class WrongTypeError < ServerError
+    end
+
+    # `NOAUTH Authentication required.`
+    class NoAuthError < ServerError
+    end
+
+    # `WRONGPASS invalid username-password pair`
+    class WrongPassError < ServerError
+    end
+
+    # An enterprise/HotKV command whose license feature is not included
+    # in the currently loaded license. Distinct from every other server
+    # error so callers (and tests) can detect and skip on it.
+    class NotLicensedError < ServerError
+    end
+
+    # `READONLY You can't write against a read only replica.`
+    class ReadOnlyError < ServerError
+    end
+
+    # `EXECABORT Transaction discarded because of a previous error.`
+    class ExecAbortError < ServerError
+    end
+
+    # `NOSCRIPT No matching script.` Used internally to trigger EVAL fallback.
+    class NoScriptError < ServerError
+    end
+
+    # `CLUSTERDOWN The cluster is down.`
+    class ClusterDownError < ServerError
+    end
+
+    # `TRYAGAIN` transient cluster error, safe to retry shortly.
+    class TryAgainError < ServerError
+    end
+
+    # `CROSSSLOT Keys in request don't hash to the same slot.`
+    class CrossSlotError < ServerError
+    end
+
+    # Base for the two cluster redirection replies, MOVED and ASK. Carries
+    # the parsed hash slot and destination address.
+    class ClusterRedirectError < ServerError
+      attr_reader :slot, :host, :port
+
+      def initialize(code, server_message, slot, host, port)
+        @slot = slot
+        @host = host
+        @port = port
+        super(code, server_message)
+      end
+
+      def self.parse(code, message)
+        # "<CODE> <slot> <host>:<port>"
+        _, slot, hostport = message.split(" ")
+        host, port = hostport.to_s.rpartition(":").values_at(0, 2)
+        new(code, message, slot.to_i, host, port.to_i)
+      end
+    end
+
+    # `MOVED <slot> <host>:<port>`: the slot now permanently lives elsewhere.
+    class MovedError < ClusterRedirectError
+    end
+
+    # `ASK <slot> <host>:<port>`: the slot is mid migration, retry once
+    # against the target node after sending it ASKING.
+    class AskError < ClusterRedirectError
+    end
+
+    CODES = {
+      "WRONGTYPE" => WrongTypeError,
+      "NOAUTH" => NoAuthError,
+      "WRONGPASS" => WrongPassError,
+      "NOLICENSE" => NotLicensedError,
+      "READONLY" => ReadOnlyError,
+      "EXECABORT" => ExecAbortError,
+      "NOSCRIPT" => NoScriptError,
+      "CLUSTERDOWN" => ClusterDownError,
+      "TRYAGAIN" => TryAgainError,
+      "CROSSSLOT" => CrossSlotError,
+      "MOVED" => MovedError,
+      "ASK" => AskError
+    }.freeze
+    private_constant :CODES
+  end
+end

data/lib/hotkv/extensions.rb

@@ -0,0 +1,118 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+require_relative "namespaces/core"
+require_relative "namespaces/caching"
+require_relative "namespaces/amem"
+require_relative "namespaces/rag"
+require_relative "namespaces/ops"
+
+module HotKV
+  module Commands
+    # HotKV exclusive and AI command groups, exposed as
+    # namespaced helpers, one memoized accessor per family, e.g.
+    # `client.pcache.get(ns, prompt)` or `client.amem.conv_append(...)`.
+    # Also NEXPIRE/NTTL/NEXPIREAT, the three standalone nanosecond
+    # resolution TTL commands, as plain methods alongside EXPIRE/TTL.
+    module Extensions
+      # Nanosecond resolution relative TTL. -> 1 if set, 0 if key does not exist.
+      def nexpire(key, nanoseconds)
+        invoke("NEXPIRE", key, nanoseconds) { |r| r == 1 }
+      end
+
+      # -> remaining TTL in nanoseconds, -2 if key does not exist, -1 if no expiry.
+      def nttl(key)
+        invoke("NTTL", key)
+      end
+
+      # Nanosecond resolution absolute TTL (unix nanosecond timestamp).
+      def nexpireat(key, unix_nanoseconds)
+        invoke("NEXPIREAT", key, unix_nanoseconds) { |r| r == 1 }
+      end
+
+      def tag
+        @hotkv_ns_tag ||= Namespaces::Tag.new(self)
+      end
+
+      def gcra
+        @hotkv_ns_gcra ||= Namespaces::Gcra.new(self)
+      end
+
+      def vsim
+        @hotkv_ns_vsim ||= Namespaces::VSim.new(self)
+      end
+
+      def observe
+        @hotkv_ns_observe ||= Namespaces::Observe.new(self)
+      end
+
+      def alerts
+        @hotkv_ns_alerts ||= Namespaces::Alerts.new(self)
+      end
+
+      def hotkeys
+        @hotkv_ns_hotkeys ||= Namespaces::Hotkeys.new(self)
+      end
+
+      def scache
+        @hotkv_ns_scache ||= Namespaces::SCache.new(self)
+      end
+
+      def pcache
+        @hotkv_ns_pcache ||= Namespaces::PCache.new(self)
+      end
+
+      def tool_cache
+        @hotkv_ns_tool_cache ||= Namespaces::KeyedCache.new(self, "TOOL.CACHE")
+      end
+
+      def ncache
+        @hotkv_ns_ncache ||= Namespaces::KeyedCache.new(self, "NCACHE")
+      end
+
+      def guard
+        @hotkv_ns_guard ||= Namespaces::KeyedCache.new(self, "GUARD")
+      end
+
+      def rerank
+        @hotkv_ns_rerank ||= Namespaces::KeyedCache.new(self, "RERANK")
+      end
+
+      def llmstats
+        @hotkv_ns_llmstats ||= Namespaces::LLMStats.new(self)
+      end
+
+      def llmbudget
+        @hotkv_ns_llmbudget ||= Namespaces::LLMBudget.new(self)
+      end
+
+      def prompt
+        @hotkv_ns_prompt ||= Namespaces::Prompt.new(self)
+      end
+
+      def embed_dedup
+        @hotkv_ns_embed_dedup ||= Namespaces::EmbedDedup.new(self)
+      end
+
+      def amem
+        @hotkv_ns_amem ||= Namespaces::AMem.new(self)
+      end
+
+      def rag
+        @hotkv_ns_rag ||= Namespaces::RAG.new(self)
+      end
+
+      def ratelimit
+        @hotkv_ns_ratelimit ||= Namespaces::RateLimit.new(self)
+      end
+
+      def ts
+        @hotkv_ns_ts ||= Namespaces::TS.new(self)
+      end
+
+      def feature
+        @hotkv_ns_feature ||= Namespaces::Feature.new(self)
+      end
+    end
+  end
+end

data/lib/hotkv/future.rb

@@ -0,0 +1,55 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # Placeholder for the typed result of a command queued inside a pipeline
+  # or transaction. Every typed command method (get, hgetall, zrange, ...)
+  # is written once, in terms of #invoke, and works unchanged whether
+  # #invoke runs the command immediately (HotKV::Client) or queues it and
+  # hands back a Future to be resolved once the batch runs
+  # (HotKV::Pipeline, HotKV::Transaction). Not part of the public API:
+  # Pipeline#execute and Transaction#exec always resolve every Future
+  # before returning, so callers only ever see plain values or, for a
+  # command that itself failed, the HotKV::Error instance in its place.
+  class Future
+    def initialize(&transform)
+      @transform = transform
+      @resolved = false
+      @value = nil
+    end
+
+    # +raw+ is the decoded reply for this command, or a HotKV::Error::ServerError
+    # instance if the command itself failed. The transform block (the same
+    # block a typed command method passes to #invoke) never runs on an
+    # error reply, so it can assume a well formed raw value.
+    def resolve(raw)
+      @value = if raw.is_a?(Error::ServerError)
+                 raw
+               else
+                 @transform ? @transform.call(raw) : raw
+               end
+      @resolved = true
+      self
+    rescue StandardError => e
+      @value = e
+      @resolved = true
+      self
+    end
+
+    def resolve_error(err)
+      @value = err
+      @resolved = true
+      self
+    end
+
+    def resolved?
+      @resolved
+    end
+
+    def value
+      raise Error::Base, "future has not been resolved yet" unless @resolved
+
+      @value
+    end
+  end
+end

data/lib/hotkv/llm_price.rb

@@ -0,0 +1,53 @@
+# Copyright (c) 2026 HotKV Ltd
+# Licensed under the Apache License, Version 2.0. See LICENSE in the project root.
+
+module HotKV
+  # One LLMSTATS.PRICE table entry (the reply of
+  # Namespaces::LLMStats#price_get, and each element of #price_list).
+  # Prices are USD per 1,000,000 tokens. +source+ is "default" (built
+  # in), "custom" (set with #price_set) or "unpriced" (an unknown model:
+  # every price 0.0, not an error).
+  LLMPrice = Struct.new(
+    :model, :source, :priced, :retired, :input_usd_per_mtok, :output_usd_per_mtok,
+    :cache_read_usd_per_mtok, :cache_write_5m_usd_per_mtok, :cache_write_1h_usd_per_mtok,
+    keyword_init: true
+  ) do
+    def initialize(model: "", source: "", priced: false, retired: false, input_usd_per_mtok: 0.0,
+                   output_usd_per_mtok: 0.0, cache_read_usd_per_mtok: 0.0,
+                   cache_write_5m_usd_per_mtok: 0.0, cache_write_1h_usd_per_mtok: 0.0)
+      super
+    end
+
+    # Builds an LLMPrice from a {field_name (Symbol) => value} Hash
+    # already parsed by field name (see Commands::Support.pairs_to_h, with
+    # +float_keys: HotKV::LLMPrice::FLOAT_FIELDS+); unknown keys are
+    # ignored, missing ones fall back to this Struct's own defaults.
+    # +priced+/+retired+ arrive as the server's integer 0/1 and are
+    # normalized to true/false.
+    def self.from_fields(fields)
+      h = fields.select { |k, _| members.include?(k) }
+      h[:priced] = Commands::Support.truthy(h[:priced]) if h.key?(:priced)
+      h[:retired] = Commands::Support.truthy(h[:retired]) if h.key?(:retired)
+      new(**h)
+    end
+
+    # Formats +value+ as the plain decimal string LLMSTATS.PRICE SET
+    # requires: digits, optional ".", 1-6 fractional digits, no sign, no
+    # exponent (see Wire.usd). A String is passed through unchanged (the
+    # caller's own decimal string).
+    def self.format_price(value)
+      Wire.usd(value)
+    end
+  end
+
+  # The 5 price fields' names, i.e. the bulk string decimal fields a
+  # LLMSTATS.PRICE GET/LIST reply needs Float() coerced by
+  # Commands::Support.pairs_to_h. Assigned here, rather than inside the
+  # Struct.new block above, because a plain constant assignment inside a
+  # Struct.new block target's the block's own lexical scope (this file's
+  # top level), not the Struct subclass itself.
+  LLMPrice::FLOAT_FIELDS = %i[
+    input_usd_per_mtok output_usd_per_mtok cache_read_usd_per_mtok cache_write_5m_usd_per_mtok
+    cache_write_1h_usd_per_mtok
+  ].freeze
+end