valkey-glide-rb 0.9.0 → 0.9.2

data/examples/opentelemetry.rb

@@ -41,10 +41,29 @@ end
 client.del("otel_key", "otel_pipe_1")
 client.close
 
+# Distributed tracing: register a parent_span_context_provider so command spans
+# become children of the app's current trace instead of independent root spans.
+# Here we hand-roll a fake W3C trace context (no dependency on the real
+# opentelemetry-ruby gem); in a real app this would read from
+# ::OpenTelemetry::Trace.current_span.context (see README).
+fake_trace_id = "4bf92f3577b34da6a3ce929d0e0e4736"
+fake_span_id = "00f067aa0ba902b7"
+
+Valkey::OpenTelemetry.set_parent_span_context_provider do
+  { trace_id: fake_trace_id, span_id: fake_span_id, trace_flags: 1, tracestate: nil }
+end
+
+client = Valkey.new(host: host, port: port)
+client.set("otel_traced_key", "value") # span will be a child of fake_trace_id/fake_span_id
+client.close
+
+Valkey::OpenTelemetry.set_parent_span_context_provider(nil)
+
 # Allow exporter flush
 sleep 2
 
 puts "OpenTelemetry initialized: #{Valkey::OpenTelemetry.initialized?}"
 puts "Traces file: #{TRACES_FILE} (#{File.size?(TRACES_FILE) || 0} bytes)"
 puts "Metrics file: #{METRICS_FILE} (#{File.size?(METRICS_FILE) || 0} bytes)"
-puts "Done."
+puts "Done. Inspect #{TRACES_FILE} - the SET span for otel_traced_key should have " \
+     "trace_id=#{fake_trace_id} and parent_span_id=#{fake_span_id}."

data/lib/valkey/bindings.rb

@@ -4,6 +4,23 @@ class Valkey
   module Bindings
     extend FFI::Library
 
+    # Detect whether the current Linux system uses musl libc (e.g., Alpine Linux).
+    # Uses a three-check cascade — any single match is sufficient.
+    def self.musl_libc?
+      return false unless FFI::Platform::OS == "linux"
+
+      # Check 1: RUBY_PLATFORM contains 'musl' (e.g., Alpine-built Ruby)
+      return true if RUBY_PLATFORM.include?("musl")
+
+      # Check 2: /etc/alpine-release exists (Alpine Linux indicator)
+      return true if File.exist?("/etc/alpine-release")
+
+      # Check 3: RbConfig target_os contains 'musl'
+      return true if RbConfig::CONFIG["target_os"].to_s.include?("musl")
+
+      false
+    end
+
     # Determine platform-specific library extension and directory name
     def self.platform_info
       os = if FFI::Platform.mac?
@@ -40,7 +57,7 @@ class Valkey
                      when "darwin"
                        "#{arch}-apple-darwin"
                      when "linux"
-                       "#{arch}-unknown-linux-gnu"
+                       musl_libc? ? "#{arch}-unknown-linux-musl" : "#{arch}-unknown-linux-gnu"
                      when "windows"
                        "#{arch}-pc-windows-msvc"
                      end
@@ -106,6 +123,33 @@ class Valkey
       )
     end
 
+    # Mirrors Rust's `RouteType` enum (valkey-glide/ffi/src/lib.rs)
+    RouteType = enum(
+      :all_nodes, 0,
+      :all_primaries,
+      :random,
+      :slot_id,
+      :slot_key,
+      :by_address
+    )
+
+    # Mirrors Rust's `SlotType` enum (a mirror of `SlotAddr`)
+    SlotType = enum(
+      :primary, 0,
+      :replica
+    )
+
+    class RouteInfo < FFI::Struct
+      layout(
+        :route_type, RouteType,
+        :slot_id, :int32,        # slot number (for SlotId route)
+        :slot_key, :pointer,     # *const c_char (for SlotKey route; NULL otherwise)
+        :slot_type, SlotType,
+        :hostname, :pointer,     # *const c_char (for ByAddress route; NULL otherwise)
+        :port, :int32            # port number (for ByAddress route)
+      )
+    end
+
     class BatchOptionsInfo < FFI::Struct
       layout(
         :retry_server_error, :bool,
@@ -209,6 +253,23 @@ class Valkey
       :pointer # *mut ConnectionResponse
     ], :void
 
+    attach_function :free_command_result, [
+      :pointer # *mut CommandResult
+    ], :void
+
+    attach_function :free_script_hash_buffer, [
+      :pointer # *mut ScriptHashBuffer
+    ], :void
+
+    attach_function :drop_script, [
+      :pointer, # *mut u8 (hash bytes)
+      :ulong    # usize (hash length)
+    ], :pointer # returns *mut c_char (null on success, error string on failure)
+
+    attach_function :free_drop_script_error, [
+      :pointer # *mut c_char (error from drop_script)
+    ], :void
+
     attach_function :close_client, [
       :pointer # client_adapter_ptr
     ], :void
@@ -225,6 +286,19 @@ class Valkey
       :ulong        # span_ptr (u64)
     ], :pointer, blocking: true # returns *mut CommandResult, releases GVL during I/O
 
+    attach_function :command_with_route_info, [
+      :pointer,     # client_adapter_ptr
+      :ulong,       # request_id
+      :int,         # command_type (RequestType)
+      :ulong,       # arg_count
+      :pointer,     # args (pointer to usize[])
+      :pointer,     # args_len (pointer to c_ulong[])
+      :pointer,     # route_info (*const RouteInfo, or NULL for no route)
+      :pointer,     # response_buf (NULL = normal response path)
+      :ulong,       # response_buf_len (0 if response_buf is NULL)
+      :ulong        # span_ptr (u64)
+    ], :pointer, blocking: true # returns *mut CommandResult, releases GVL during I/O
+
     attach_function :batch, [
       :pointer,        # client_ptr
       :ulong,          # callback_index
@@ -309,6 +383,21 @@ class Valkey
 
     attach_function :create_batch_otel_span, [], :uint64 # returns span pointer (u64) or 0 on failure
 
+    attach_function :create_otel_span_with_trace_context, [
+      :int,    # request_type (RequestType enum value)
+      :string, # trace_id (32-char lowercase hex, or nil for an independent span)
+      :string, # span_id (16-char lowercase hex, or nil for an independent span)
+      :uint8,  # trace_flags
+      :string  # trace_state (W3C tracestate header, or nil)
+    ], :uint64 # returns span pointer (u64); falls back to an independent span on invalid context
+
+    attach_function :create_batch_otel_span_with_trace_context, [
+      :string, # trace_id (32-char lowercase hex, or nil for an independent span)
+      :string, # span_id (16-char lowercase hex, or nil for an independent span)
+      :uint8,  # trace_flags
+      :string  # trace_state (W3C tracestate header, or nil)
+    ], :uint64 # returns span pointer (u64); falls back to an independent batch span on invalid context
+
     attach_function :drop_otel_span, [
       :uint64 # span_ptr to close
     ], :void

data/lib/valkey/commands/cluster_commands.rb

@@ -71,13 +71,30 @@ class Valkey
         send_command(RequestType::CLUSTER_DEL_SLOTS_RANGE, [start_slot, end_slot])
       end
 
+      # Valid modes for CLUSTER FAILOVER: FORCE, TAKEOVER.
+      CLUSTER_FAILOVER_MODES = %i[force takeover].freeze
+
       # Force a failover of the cluster.
       #
-      # @param [String] force force the failover
+      # Must be sent to a replica node. Without a mode, performs a coordinated
+      # failover (the primary is asked to pause clients and hand over). +:force+
+      # promotes the replica without coordinating with the primary (useful when
+      # the primary is unreachable); +:takeover+ promotes it without any cluster
+      # consensus (most aggressive — risks data loss / split brain).
+      #
+      # @param [Symbol, nil] mode optional failover mode: +:force+ or +:takeover+
       # @return [String] `"OK"`
-      def cluster_failover(force = nil)
+      # @raise [ArgumentError] if +mode+ is not nil, +:force+, or +:takeover+
+      # @see https://valkey.io/commands/cluster-failover/
+      def cluster_failover(mode = nil)
         args = []
-        args << "FORCE" if force
+        unless mode.nil?
+          unless CLUSTER_FAILOVER_MODES.include?(mode)
+            raise ArgumentError, "invalid CLUSTER FAILOVER mode #{mode.inspect}: expected :force or :takeover"
+          end
+
+          args << mode.to_s.upcase
+        end
         send_command(RequestType::CLUSTER_FAILOVER, args)
       end
 
@@ -107,10 +124,15 @@ class Valkey
 
       # Get information about the cluster.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Hash<String, String>] cluster information
-      def cluster_info
-        send_command(RequestType::CLUSTER_INFO) do |reply|
-          Utils::HashifyInfo.call(reply)
+      def cluster_info(route: nil)
+        send_command(RequestType::CLUSTER_INFO, [], route: route) do |reply|
+          if reply.is_a?(Hash)
+            reply.transform_values { |v| Utils::HashifyInfo.call(v) }
+          else
+            Utils::HashifyInfo.call(reply)
+          end
         end
       end
 
@@ -124,9 +146,10 @@ class Valkey
 
       # Get information about cluster links.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Array<Hash>] array of link information
-      def cluster_links
-        send_command(RequestType::CLUSTER_LINKS)
+      def cluster_links(route: nil)
+        send_command(RequestType::CLUSTER_LINKS, [], route: route)
       end
 
       # Meet another node in the cluster.
@@ -140,24 +163,31 @@ class Valkey
 
       # Get the ID of the current node.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [String] node ID
-      def cluster_myid
-        send_command(RequestType::CLUSTER_MY_ID)
+      def cluster_myid(route: nil)
+        send_command(RequestType::CLUSTER_MY_ID, [], route: route)
       end
 
       # Get the shard ID of the current node.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [String] shard ID
-      def cluster_myshardid
-        send_command(RequestType::CLUSTER_MY_SHARD_ID)
+      def cluster_myshardid(route: nil)
+        send_command(RequestType::CLUSTER_MY_SHARD_ID, [], route: route)
       end
 
       # Get information about all nodes in the cluster.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Array<Hash>] array of node information
-      def cluster_nodes
-        send_command(RequestType::CLUSTER_NODES) do |reply|
-          Utils::HashifyClusterNodes.call(reply)
+      def cluster_nodes(route: nil)
+        send_command(RequestType::CLUSTER_NODES, [], route: route) do |reply|
+          if reply.is_a?(Hash)
+            reply.transform_values { |v| Utils::HashifyClusterNodes.call(v) }
+          else
+            Utils::HashifyClusterNodes.call(reply)
+          end
         end
       end
 
@@ -218,9 +248,10 @@ class Valkey
 
       # Get information about cluster shards.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Array<Hash>] array of shard information
-      def cluster_shards
-        send_command(RequestType::CLUSTER_SHARDS)
+      def cluster_shards(route: nil)
+        send_command(RequestType::CLUSTER_SHARDS, [], route: route)
       end
 
       # Get information about slave nodes (deprecated, use cluster_replicas).

data/lib/valkey/commands/connection_commands.rb

@@ -18,18 +18,25 @@ class Valkey
 
       # Ping the server.
       #
-      # @param [optional, String] message
-      # @return [String] `PONG`
-      def ping(message = nil)
-        send_command(RequestType::PING, [message].compact)
+      # @param message [String, nil] optional message to echo back
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [String]
+      #
+      # @example
+      #   ping             #=> "PONG"
+      #   ping("hello")    #=> "hello"
+      #   ping(route: Valkey::Route.all_nodes)  #=> Hash (multi-node)
+      def ping(message = nil, route: nil)
+        send_command(RequestType::PING, [message].compact, route: route)
       end
 
       # Echo the given string.
       #
-      # @param [String] value
+      # @param value [String]
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [String]
-      def echo(value)
-        send_command(RequestType::ECHO, [value])
+      def echo(value, route: nil)
+        send_command(RequestType::ECHO, [value], route: route)
       end
 
       # Change the selected database for the current connection.
@@ -94,14 +101,15 @@ class Valkey
       #   client(:set_name, "my_app")  # => "OK"
       #   client(:list)                # => [{"id" => "1", ...}, ...]
       def client(subcommand, *args)
-        send("client_#{subcommand.to_s.downcase}", *args)
+        public_send("client_#{subcommand.to_s.downcase}", *args)
       end
 
       # Get the current client's ID.
       #
-      # @return [Integer] Unique client ID
-      def client_id
-        send_command(RequestType::CLIENT_ID)
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [Integer]
+      def client_id(route: nil)
+        send_command(RequestType::CLIENT_ID, [], route: route)
       end
 
       # Get the current client's name.
@@ -136,8 +144,10 @@ class Valkey
 
         send_command(RequestType::CLIENT_LIST, args) do |reply|
           reply.lines.map do |line|
-            entries = line.chomp.split(/[ =]/)
-            entries.each_slice(2).to_a.to_h
+            line.chomp.split.each_with_object({}) do |pair, hash|
+              key, value = pair.split("=", 2)
+              hash[key] = value || ""
+            end
           end
         end
       end
@@ -203,9 +213,10 @@ class Valkey
 
       # Unpause client processing.
       #
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] `OK`
-      def client_unpause
-        send_command(RequestType::CLIENT_UNPAUSE)
+      def client_unpause(route: nil)
+        send_command(RequestType::CLIENT_UNPAUSE, [], route: route)
       end
 
       # Configure client reply mode.
@@ -290,6 +301,12 @@ class Valkey
         send_command(RequestType::CLIENT_NO_TOUCH, [mode.to_s.upcase])
       end
 
+      # Client-side caching commands are intentionally private.
+      #
+      # GLIDE's managed client-side caching is not yet implemented in the Ruby client
+      # These commands are not meant to be called directly and will be kept private.
+      private :client_tracking, :client_caching, :client_tracking_info, :client_getredir
+
       private
 
       def build_client_tracking_args(options)
@@ -299,8 +316,9 @@ class Valkey
           when :redirect
             args << "REDIRECT" << value.to_s
           when :prefix
-            args << "PREFIX"
-            Array(value).each { |prefix| args << prefix }
+            # Valkey requires the PREFIX keyword before each prefix value,
+            # e.g. PREFIX foo PREFIX bar.
+            Array(value).each { |prefix| args << "PREFIX" << prefix }
           when :bcast
             args << "BCAST" if value
           when :optin

data/lib/valkey/commands/function_commands.rb

@@ -14,11 +14,12 @@ class Valkey
       #     # => "OK"
       #
       # @param [String] library_name the library name to delete
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] "OK"
       #
       # @see https://valkey.io/commands/function-delete/
-      def function_delete(library_name)
-        send_command(RequestType::FUNCTION_DELETE, [library_name])
+      def function_delete(library_name, route: nil)
+        send_command(RequestType::FUNCTION_DELETE, [library_name], route: route)
       end
 
       # Return the serialized payload of loaded libraries.
@@ -27,11 +28,12 @@ class Valkey
       #   valkey.function_dump
       #     # => <binary string>
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [String] the serialized payload
       #
       # @see https://valkey.io/commands/function-dump/
-      def function_dump
-        send_command(RequestType::FUNCTION_DUMP)
+      def function_dump(route: nil)
+        send_command(RequestType::FUNCTION_DUMP, [], route: route)
       end
 
       # Delete all libraries.
@@ -48,10 +50,11 @@ class Valkey
       #
       # @param [Boolean] async flush asynchronously
       # @param [Boolean] sync flush synchronously
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] "OK"
       #
       # @see https://valkey.io/commands/function-flush/
-      def function_flush(async: false, sync: false)
+      def function_flush(async: false, sync: false, route: nil)
         args = []
 
         if async
@@ -60,7 +63,7 @@ class Valkey
           args << "SYNC"
         end
 
-        send_command(RequestType::FUNCTION_FLUSH, args)
+        send_command(RequestType::FUNCTION_FLUSH, args, route: route)
       end
 
       # Kill a function that is currently executing.
@@ -69,11 +72,12 @@ class Valkey
       #   valkey.function_kill
       #     # => "OK"
       #
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] "OK"
       #
       # @see https://valkey.io/commands/function-kill/
-      def function_kill
-        send_command(RequestType::FUNCTION_KILL)
+      def function_kill(route: nil)
+        send_command(RequestType::FUNCTION_KILL, [], route: route)
       end
 
       # Return information about the functions and libraries.
@@ -90,10 +94,11 @@ class Valkey
       #
       # @param [String] library_name filter by library name pattern
       # @param [Boolean] with_code include the library code in the response
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Array<Hash>] array of library information
       #
       # @see https://valkey.io/commands/function-list/
-      def function_list(library_name: nil, with_code: false)
+      def function_list(library_name: nil, with_code: false, route: nil)
         args = []
 
         if library_name
@@ -103,7 +108,7 @@ class Valkey
 
         args << "WITHCODE" if with_code
 
-        send_command(RequestType::FUNCTION_LIST, args)
+        send_command(RequestType::FUNCTION_LIST, args, route: route)
       end
 
       # Load a library to Valkey.
@@ -118,15 +123,16 @@ class Valkey
       #
       # @param [String] function_code the source code
       # @param [Boolean] replace replace the library if it exists
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] the library name that was loaded
       #
       # @see https://valkey.io/commands/function-load/
-      def function_load(function_code, replace: false)
+      def function_load(function_code, replace: false, route: nil)
         args = []
         args << "REPLACE" if replace
         args << function_code
 
-        send_command(RequestType::FUNCTION_LOAD, args)
+        send_command(RequestType::FUNCTION_LOAD, args, route: route)
       end
 
       # Restore libraries from a payload.
@@ -147,15 +153,16 @@ class Valkey
       #
       # @param [String] serialized_value the serialized payload from FUNCTION DUMP
       # @param [String] policy the restore policy: "FLUSH", "APPEND", or "REPLACE"
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] "OK"
       #
       # @see https://valkey.io/commands/function-restore/
-      def function_restore(serialized_value, policy: nil)
+      def function_restore(serialized_value, policy: nil, route: nil)
         args = [serialized_value]
 
         args << policy.to_s.upcase if policy
 
-        send_command(RequestType::FUNCTION_RESTORE, args)
+        send_command(RequestType::FUNCTION_RESTORE, args, route: route)
       end
 
       # Return information about the function that's currently running.
@@ -164,11 +171,12 @@ class Valkey
       #   valkey.function_stats
       #     # => {"running_script" => {...}, "engines" => {...}}
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Hash] function execution statistics
       #
       # @see https://valkey.io/commands/function-stats/
-      def function_stats
-        send_command(RequestType::FUNCTION_STATS)
+      def function_stats(route: nil)
+        send_command(RequestType::FUNCTION_STATS, [], route: route)
       end
 
       # Invoke a function.
@@ -183,12 +191,13 @@ class Valkey
       # @param [String] function the function name
       # @param [Array<String>] keys the keys to pass to the function
       # @param [Array<String>] args the arguments to pass to the function
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Object] the function result
       #
       # @see https://valkey.io/commands/fcall/
-      def fcall(function, keys: [], args: [])
+      def fcall(function, keys: [], args: [], route: nil)
         command_args = [function, keys.size] + keys + args
-        send_command(RequestType::FCALL, command_args)
+        send_command(RequestType::FCALL, command_args, route: route)
       end
 
       # Invoke a read-only function.
@@ -200,12 +209,13 @@ class Valkey
       # @param [String] function the function name
       # @param [Array<String>] keys the keys to pass to the function
       # @param [Array<String>] args the arguments to pass to the function
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Object] the function result
       #
       # @see https://valkey.io/commands/fcall_ro/
-      def fcall_ro(function, keys: [], args: [])
+      def fcall_ro(function, keys: [], args: [], route: nil)
         command_args = [function, keys.size] + keys + args
-        send_command(RequestType::FCALL_READ_ONLY, command_args)
+        send_command(RequestType::FCALL_READ_ONLY, command_args, route: route)
       end
 
       # Control function registry (convenience method).