valkey-glide-rb 0.9.1 → 0.9.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8824baa9eb08b0496a2428dd1a0c4997d9716810ba75d607bbadd0c40a99dde
-  data.tar.gz: 23704fe50125575ad927860cabf0cae7f7ed9d915f651d049b608ca809fda2e9
+  metadata.gz: 17396d39342cbcc8a293f5e8b252e1689841b436664c630e330d06b0a1cff9c9
+  data.tar.gz: 7fa260b6afbb060a1c79a8dcb264aae5b211a24e69b042c720e242d39b7b3ab9
 SHA512:
-  metadata.gz: 62a9bd00a4bc4f1cde9da036e86703a504f7a7ef355ffce8f254c5cf46ebb103c88242e20255a14d7adee3fbf3089db584c8703c5a5f89f9a7c0e04863254abb
-  data.tar.gz: 7a7b9672f5cd499878aef940198b3f48e58fff82d9a8468eb12ab3abc57446dd905326c44aa33145926fd1c28af226817937ac9cb3b69717b7f1d07b08e3fc0f
+  metadata.gz: e96a09b0077bd54a30722201d03ccd8bb8baf7a47c0005d5c3d87441bfeb015479181548dce68bd1e882ee9e266be4658e68b2562e32dca6c48c101ca4e0e2cc
+  data.tar.gz: dbee972964d0a2e54dbf7f4916c2bab6427525ace1d97a679845409b9d55390419631c8407df7502ca9b3561bd51ea0bba1ebecd8bbef680cdaa45b5ba28f405

data/.rubocop.yml

@@ -35,7 +35,7 @@ Metrics/CyclomaticComplexity:
   Enabled: false
 
 Metrics/MethodLength:
-  Max: 20
+  Max: 50
   Exclude:
     - 'lib/valkey.rb'
     - 'lib/valkey/opentelemetry.rb'

data/lib/valkey/bindings.rb

@@ -123,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,
@@ -226,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
@@ -242,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

data/lib/valkey/commands/cluster_commands.rb

@@ -124,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
 
@@ -141,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.
@@ -157,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
 
@@ -235,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.
@@ -99,9 +106,10 @@ class Valkey
 
       # 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.
@@ -205,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.

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).

data/lib/valkey/commands/generic_commands.rb

@@ -394,9 +394,10 @@ class Valkey
 
       # Return a random key from the keyspace.
       #
-      # @return [String]
-      def randomkey
-        send_command(RequestType::RANDOM_KEY)
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [String, nil]
+      def randomkey(route: nil)
+        send_command(RequestType::RANDOM_KEY, [], route: route)
       end
 
       # Rename a key. If the new key already exists it is overwritten.
@@ -552,11 +553,12 @@ class Valkey
       # @param [Array<String, Integer, Float, Array, Hash>] argv command name and its arguments
       # @param [Hash] kwargs trailing command flags; truthy values emit the upcased flag name,
       #   non-boolean values also emit the stringified value; falsy/nil values are dropped
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Object] the raw reply, with no type-casting based on the command name
       #
       # @see https://valkey.io/commands/
-      def call(*argv, **kwargs)
-        send_command(RequestType::CUSTOM_COMMAND, flatten_call_args(argv).concat(call_flags(kwargs)))
+      def call(*argv, route: nil, **kwargs)
+        send_command(RequestType::CUSTOM_COMMAND, flatten_call_args(argv).concat(call_flags(kwargs)), route: route)
       end
 
       # Send any command as a single Array of arguments and get the raw reply back.
@@ -568,11 +570,12 @@ class Valkey
       #   valkey.call_v(["MGET"] + keys)
       #
       # @param [Array<String, Integer, Float, Array, Hash>] argv command name and its arguments
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Object] the raw reply, with no type-casting based on the command name
       #
       # @see https://valkey.io/commands/
-      def call_v(argv)
-        send_command(RequestType::CUSTOM_COMMAND, flatten_call_args(argv))
+      def call_v(argv, route: nil)
+        send_command(RequestType::CUSTOM_COMMAND, flatten_call_args(argv), route: route)
       end
 
       private

data/lib/valkey/commands/scripting_commands.rb

@@ -108,8 +108,12 @@ class Valkey
 
         result = Bindings.store_script(buf, script.bytesize)
 
-        hash_buffer = Bindings::ScriptHashBuffer.new(result)
-        hash_buffer[:ptr].read_string(hash_buffer[:len])
+        begin
+          hash_buffer = Bindings::ScriptHashBuffer.new(result)
+          hash_buffer[:ptr].read_string(hash_buffer[:len])
+        ensure
+          Bindings.free_script_hash_buffer(result) if result && !result.null?
+        end
       end
 
       # Execute a Lua script on the server.
@@ -133,13 +137,22 @@ class Valkey
       # @example Execute script that returns different data types
       #   valkey.eval("return {1, 'hello', true, nil}")
       #     # => [1, "hello", true, nil]
+      # @example Positional form, matching redis-rb's eval(script, keys, argv)
+      #   valkey.eval("return KEYS[1] .. ARGV[1]", ["mykey"], ["myarg"])
+      #     # => "mykeynyarg"
       # Since the eval is not available in the rust backend
       # using the load and invoke script
-      def eval(script, keys: [], args: [])
+      def eval(script, *rest, keys: nil, args: nil)
         # Validate script parameter
         raise ArgumentError, "script must be a string" unless script.is_a?(String)
         raise ArgumentError, "script cannot be empty" if script.empty?
 
+        # Accept redis-rb's flexible positional form - eval(script, keys, argv)
+        # - in addition to the keyword form, mirroring the same treatment
+        # applied to evalsha (see that method for the full rationale).
+        keys ||= rest[0] || []
+        args ||= rest[1] || []
+
         # Validate and convert keys and args to strings
         begin
           keys = Array(keys).map(&:to_s)
@@ -177,13 +190,22 @@ class Valkey
       #   rescue Valkey::CommandError => e
       #     puts "Script not found: #{e.message}"
       #   end
+      # @example Positional form, matching redis-rb's evalsha(sha, keys, argv)
+      #   valkey.evalsha(sha, ["user"], ["123"])
+      #     # => "user:123"
       # Since evalsha is not available in rust backend
       # using invoke script
-      def evalsha(sha, keys: [], args: [])
+      def evalsha(sha, *rest, keys: nil, args: nil)
         # Validate SHA1 hash parameter
         raise ArgumentError, "sha1 hash must be a string" unless sha.is_a?(String)
         raise ArgumentError, "sha1 hash must be a 40-character hexadecimal string" unless valid_sha1?(sha)
 
+        # Accept redis-rb's flexible positional form - evalsha(sha, keys, argv)
+        # - in addition to the keyword form, so code written against redis-rb's
+        # API (e.g. redis_display_id) doesn't need to special-case this client.
+        keys ||= rest[0] || []
+        args ||= rest[1] || []
+
         # Validate and convert keys and args to strings
         begin
           keys = Array(keys).map(&:to_s)
@@ -258,22 +280,26 @@ class Valkey
         # Use from_string to ensure proper null termination
         sha = FFI::MemoryPointer.from_string(script)
 
-        res = Bindings.invoke_script(
-          @connection,
-          0,
-          sha,
-          keys.size,
-          keys_ptrs,
-          keys_lens,
-          args.size,
-          arg_ptrs,
-          arg_lens,
-          route_buf,
-          route.bytesize,
-          0 # span_ptr for OpenTelemetry (0 = no span)
-        )
-
-        convert_response(res)
+        begin
+          res = Bindings.invoke_script(
+            @connection,
+            0,
+            sha,
+            keys.size,
+            keys_ptrs,
+            keys_lens,
+            args.size,
+            arg_ptrs,
+            arg_lens,
+            route_buf,
+            route.bytesize,
+            0 # span_ptr for OpenTelemetry (0 = no span)
+          )
+
+          convert_response(res)
+        ensure
+          Bindings.free_command_result(res) if res && !res.null?
+        end
       end
 
       private

data/lib/valkey/commands/server_commands.rb

@@ -9,16 +9,18 @@ class Valkey
     module ServerCommands
       # Asynchronously rewrite the append-only file.
       #
-      # @return [String] `OK`
-      def bgrewriteaof
-        send_command(RequestType::BG_REWRITE_AOF)
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [String]
+      def bgrewriteaof(route: nil)
+        send_command(RequestType::BG_REWRITE_AOF, [], route: route)
       end
 
       # Asynchronously save the dataset to disk.
       #
-      # @return [String] `OK`
-      def bgsave
-        send_command(RequestType::BG_SAVE)
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [String]
+      def bgsave(route: nil)
+        send_command(RequestType::BG_SAVE, [], route: route)
       end
 
       # Get or set server configuration parameters.
@@ -35,18 +37,16 @@ class Valkey
       # Sends the CONFIG GET command with the given arguments.
       #
       # @param [Array<String>] args Configuration parameters to get
-      # @return [Hash, String] Returns a Hash if multiple parameters are requested,
-      #   otherwise returns a String with the value.
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [Hash, String]
       #
       # @example Get all configuration parameters
       #   config_get('*')
       #
       # @example Get a specific parameter
       #   config_get('maxmemory')
-      #
-      # @note Returns a Hash with parameter names as keys and values as values when multiple params requested.
-      def config_get(*args)
-        send_command(RequestType::CONFIG_GET, args) do |reply|
+      def config_get(*args, route: nil)
+        send_command(RequestType::CONFIG_GET, args, route: route) do |reply|
           if reply.is_a?(Array)
             Hash[*reply]
           else
@@ -60,55 +60,60 @@ class Valkey
       # Sends the CONFIG SET command with the given key-value pairs.
       #
       # @param [Array<String>] args Key-value pairs to set configuration
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] Returns "OK" if successful
       #
       # @example Set maxmemory to 100mb
       #   config_set('maxmemory', '100mb')
-      def config_set(*args)
-        send_command(RequestType::CONFIG_SET, args)
+      def config_set(*args, route: nil)
+        send_command(RequestType::CONFIG_SET, args, route: route)
       end
 
       # Reset the server's statistics.
       #
       # Sends the CONFIG RESETSTAT command.
       #
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] Returns "OK" if successful
       #
       # @example
       #   config_resetstat
-      def config_resetstat
-        send_command(RequestType::CONFIG_RESET_STAT)
+      def config_resetstat(route: nil)
+        send_command(RequestType::CONFIG_RESET_STAT, [], route: route)
       end
 
       # Rewrite the server configuration file.
       #
       # Sends the CONFIG REWRITE command.
       #
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] Returns "OK" if successful
       #
       # @example
       #   config_rewrite
-      def config_rewrite
-        send_command(RequestType::CONFIG_REWRITE)
+      def config_rewrite(route: nil)
+        send_command(RequestType::CONFIG_REWRITE, [], route: route)
       end
 
       # Return the number of keys in the selected database.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Integer]
-      def dbsize
-        send_command(RequestType::DB_SIZE)
+      def dbsize(route: nil)
+        send_command(RequestType::DB_SIZE, [], route: route)
       end
 
       # Remove all keys from all databases.
       #
       # @param [Hash] options
       #   - `:async => Boolean`: async flush (default: false)
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] `OK`
-      def flushall(options = nil)
+      def flushall(options = nil, route: nil)
         if options && options[:async]
-          send_command(RequestType::FLUSH_ALL, ["async"])
+          send_command(RequestType::FLUSH_ALL, ["async"], route: route)
         else
-          send_command(RequestType::FLUSH_ALL)
+          send_command(RequestType::FLUSH_ALL, [], route: route)
         end
       end
 
@@ -116,42 +121,56 @@ class Valkey
       #
       # @param [Hash] options
       #   - `:async => Boolean`: async flush (default: false)
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String] `OK`
-      def flushdb(options = nil)
+      def flushdb(options = nil, route: nil)
         if options && options[:async]
-          send_command(RequestType::FLUSH_DB, ["async"])
+          send_command(RequestType::FLUSH_DB, ["async"], route: route)
         else
-          send_command(RequestType::FLUSH_DB)
+          send_command(RequestType::FLUSH_DB, [], route: route)
         end
       end
 
       # Get information and statistics about the server.
       #
-      # @param [String, Symbol] cmd e.g. "commandstats"
-      # @return [Hash<String, String>]
-      def info(cmd = nil)
-        send_command(RequestType::INFO, [cmd].compact) do |reply|
-          if reply.is_a?(String)
-            reply = Utils::HashifyInfo.call(reply)
-
-            if cmd && cmd.to_s == "commandstats"
-              # Extract nested hashes for INFO COMMANDSTATS
-              reply = reply.to_h do |k, v|
-                v = v.split(",").map { |e| e.split("=") }
-                [k[/^cmdstat_(.*)$/, 1], v.to_h]
-              end
-            end
+      # @param cmd [String, Symbol, nil] section name (e.g. "commandstats")
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
+      # @return [Hash]
+      def info(cmd = nil, route: nil)
+        send_command(RequestType::INFO, [cmd].compact, route: route) do |reply|
+          if reply.is_a?(Hash)
+            reply.transform_values { |v| parse_info_reply(v, cmd) }
+          elsif reply.is_a?(String)
+            parse_info_reply(reply, cmd)
+          else
+            reply
           end
+        end
+      end
+
+      private
 
-          reply
+      def parse_info_reply(reply, cmd)
+        reply = Utils::HashifyInfo.call(reply)
+
+        if cmd && cmd.to_s == "commandstats"
+          reply = reply.to_h do |k, v|
+            v = v.split(",").map { |e| e.split("=") }
+            [k[/^cmdstat_(.*)$/, 1], v.to_h]
+          end
         end
+
+        reply
       end
 
+      public
+
       # Get the UNIX time stamp of the last successful save to disk.
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Integer]
-      def lastsave
-        send_command(RequestType::LAST_SAVE)
+      def lastsave(route: nil)
+        send_command(RequestType::LAST_SAVE, [], route: route)
       end
 
       # Listen for all requests received by the server in real time.
@@ -172,9 +191,10 @@ class Valkey
 
       # Synchronously save the dataset to disk.
       #
+      # @param route [Valkey::Route, nil] cluster routing.
       # @return [String]
-      def save
-        send_command(RequestType::SAVE)
+      def save(route: nil)
+        send_command(RequestType::SAVE, [], route: route)
       end
 
       # Synchronously save the dataset to disk and then shut down the server.
@@ -215,10 +235,11 @@ class Valkey
       # @example
       #   r.time # => [ 1333093196, 606806 ]
       #
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [Array<Integer>] tuple of seconds since UNIX epoch and
       #   microseconds in the current second
-      def time
-        send_command(RequestType::TIME)
+      def time(route: nil)
+        send_command(RequestType::TIME, [], route: route)
       end
 
       # RequestType::DEBUG not exist
@@ -517,7 +538,8 @@ class Valkey
 
       # Display some computer art and the Valkey version.
       #
-      # @param [Integer] version optional version number for different art
+      # @param version [Integer, nil] optional version number for different art
+      # @param route [Valkey::Route, nil] cluster routing. When routed, may return a Hash of node => value.
       # @return [String] ASCII art and version information
       #
       # @example
@@ -528,9 +550,9 @@ class Valkey
       #     # => "Valkey ver. 7.0.0\n..."
       #
       # @see https://valkey.io/commands/lolwut/
-      def lolwut(version = nil)
+      def lolwut(version = nil, route: nil)
         args = version ? ["VERSION", version.to_s] : []
-        send_command(RequestType::LOLWUT, args)
+        send_command(RequestType::LOLWUT, args, route: route)
       end
 
       # Internal command used for replication (partial resynchronization).

data/lib/valkey/commands/string_commands.rb

@@ -129,7 +129,14 @@ class Valkey
       # @param [String] value
       # @return [Boolean] whether the key was set or not
       def setnx(key, value)
-        send_command(RequestType::SET_NX, [key, value])
+        # &Utils::Boolify (not glide-core's generic Boolean-coercion table) is
+        # deliberately used here: glide-core's per-command coercion is keyed by
+        # command name alone, so it can't distinguish this dedicated SETNX
+        # RequestType from a raw `customCommand(["SETNX", ...])` call, which
+        # other GLIDE bindings' existing contracts expect to keep returning a
+        # plain 0/1 integer. Doing the conversion here keeps it scoped to this
+        # one Ruby-level method - see hexists/hsetnx for the same pattern.
+        send_command(RequestType::SET_NX, [key, value], &Utils::Boolify)
       end
 
       # Set one or more values.

data/lib/valkey/commands/transaction_commands.rb

@@ -16,8 +16,12 @@ class Valkey
       #   end # => ["OK", 6]
       #
       # @yield [multi] the commands that are called inside this block are cached
-      #   and written to the server upon returning from it
-      # @yieldparam [Valkey] multi `self`
+      #   locally (no server round-trip per command) and sent to the server as a
+      #   single atomic batch once the block returns - GLIDE wraps them in a real
+      #   MULTI/EXEC transaction internally. If the block raises, nothing has been
+      #   sent to the server yet, so the exception simply propagates - there is no
+      #   transaction to discard.
+      # @yieldparam [Valkey::Pipeline] multi collects the block's commands
       #
       # @return [Array<...>]
       #   - an array with replies
@@ -26,17 +30,12 @@ class Valkey
       # @see #unwatch
       def multi
         if block_given?
-          begin
-            @in_multi_block = true
-            start_multi
-            yield(self)
-            exec
-          rescue StandardError
-            discard
-            raise
-          ensure
-            @in_multi_block = false
-          end
+          pipeline = Pipeline.new
+          yield pipeline
+
+          return [] if pipeline.commands.empty?
+
+          send_batch_commands(pipeline.commands, exception: true, is_atomic: true)
         else
           start_multi
           self
@@ -114,11 +113,12 @@ class Valkey
       # @see #discard
       def exec
         if @in_multi
+          queued_commands = @queued_commands
           begin
             begin
               result = send_command(RequestType::EXEC)
               # If EXEC returns an error object (from array), it's already handled
-              result
+              result.is_a?(Array) ? reconvert_queued_replies(result, queued_commands) : result
             rescue CommandError => e
               # If EXEC itself raises an error (like when transaction is aborted),
               # return an array with the error to match expected behavior in tests
@@ -157,8 +157,59 @@ class Valkey
         @queued_commands = []
       end
 
+      # Commands whose reply is boolean when run standalone (via native return-type
+      # coercion server-side), but arrives as a raw 0/1 integer inside an EXEC array,
+      # since that coercion is keyed by the single command actually being run - which,
+      # for a queued command, is EXEC itself, not the original command.
+      #
+      # This list mirrors glide-core's own Boolean-coercion table in
+      # `value_conversion.rs::expected_type_for_cmd` (HEXISTS, HSETNX, EXPIRE, EXPIREAT,
+      # PEXPIRE, PEXPIREAT, SISMEMBER, PERSIST, SMOVE, PFADD, RENAMENX, MOVE, COPY,
+      # MSETNX, XGROUP DESTROY, XGROUP CREATECONSUMER) MINUS the commands whose Ruby
+      # method already passes its own explicit conversion block (`hexists`/`hsetnx`
+      # use `&Utils::Boolify`; `xgroup_destroy`/`xgroup_createconsumer` use a custom
+      # bool->int block). Those are already handled correctly by the `if block`
+      # branch below, before this list is even consulted - listing them here too
+      # would be redundant, not wrong. Every RequestType below calls `send_command`
+      # with NO block at all, so this static list is the only place their boolean-ness
+      # is recorded.
+      #
+      # NOTE: SETNX is deliberately NOT in glide-core's coercion table (and so isn't
+      # here as a "no block" entry either) - it's `redis-rb`-style boolean-ness only,
+      # not something the server/`glide-core` treats as boolean, since coercion there
+      # is keyed by command name alone and can't distinguish this dedicated RequestType
+      # from a raw `customCommand(["SETNX", ...])` call, which other bindings' existing
+      # contracts expect to keep returning a plain integer. `setnx`'s own Ruby method
+      # passes `&Utils::Boolify` directly instead - see string_commands.rb - so it's
+      # already covered by the `if block` branch, same as hexists/hsetnx.
+      BOOLEAN_REQUEST_TYPES = [
+        RequestType::EXPIRE, RequestType::EXPIRE_AT, RequestType::PEXPIRE, RequestType::PEXPIRE_AT,
+        RequestType::PERSIST, RequestType::SISMEMBER, RequestType::S_MOVE, RequestType::PFADD,
+        RequestType::RENAME_NX, RequestType::MOVE, RequestType::COPY, RequestType::MSET_NX
+      ].freeze
+
       private
 
+      # Re-applies each queued command's own reply conversion (e.g. `&Utils::Boolify`)
+      # to EXEC's raw array, since redis-rb's Future-based design does the equivalent
+      # (a Future remembers its conversion and re-applies it once EXEC resolves), but
+      # queued commands here go through the plain single-command path with no such
+      # memory - see BOOLEAN_REQUEST_TYPES above for the case with no explicit block.
+      def reconvert_queued_replies(result, queued_commands)
+        return result unless result.size == queued_commands.size
+
+        result.each_with_index.map do |value, i|
+          command_type, _args, block = queued_commands[i]
+          if block
+            block.call(value)
+          elsif BOOLEAN_REQUEST_TYPES.include?(command_type)
+            Utils::Boolify.call(value)
+          else
+            value
+          end
+        end
+      end
+
       # Start a MULTI block if one isn't already active.
       #
       # This mirrors the behaviour of popular Valkey/Redis clients where

data/lib/valkey/route.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+class Valkey
+  # Represents a cluster routing directive. Passed as `route:` to commands
+  # that support explicit cluster routing (no-key commands like DBSIZE, INFO,
+  # PING, FLUSHALL, FUNCTION_*, etc.).
+  #
+  # When `route:` is provided the command response type depends on the route:
+  # single-node routes return the value directly, multi-node routes return a
+  # Hash of `"host:port" => value`.
+  #
+  # @example
+  #   client.dbsize(route: Valkey::Route.all_primaries)
+  #   client.ping(route: Valkey::Route.random)
+  #   client.info(route: Valkey::Route.all_nodes)
+  #
+  # @see https://valkey.io/topics/cluster-spec
+  class Route
+    class << self
+      # Route to all nodes (primaries + replicas).
+      # @note Don't use with write commands — they could be routed to replicas and fail.
+      # @return [Route]
+      def all_nodes
+        new(:all_nodes)
+      end
+
+      # Route to all primary nodes.
+      # @return [Route]
+      def all_primaries
+        new(:all_primaries)
+      end
+
+      # Route to a random node.
+      # @note Don't use with write commands — they could be randomly routed to a replica and fail.
+      # @return [Route]
+      def random
+        new(:random)
+      end
+
+      # Route to a specific slot by ID.
+      # @param slot_id [Integer] slot number (0–16383)
+      # @param slot_type [Symbol] :primary or :replica
+      # @return [Route]
+      def slot_id(slot_id, slot_type = :primary)
+        new(:slot_id, slot_id: slot_id.to_i, slot_type: slot_type)
+      end
+
+      # Route to the node owning a specific key's slot.
+      # @param key [String] the key whose slot determines routing
+      # @param slot_type [Symbol] :primary or :replica
+      # @return [Route]
+      def slot_key(key, slot_type = :primary)
+        new(:slot_key, slot_key: key.to_s, slot_type: slot_type)
+      end
+
+      # Route to a specific node by address.
+      # @param host [String] hostname or IP
+      # @param port [Integer] port number
+      # @return [Route]
+      def by_address(host, port)
+        new(:by_address, hostname: host.to_s, port: port.to_i)
+      end
+    end
+
+    # Build the FFI RouteInfo struct for passing to command_with_route_info.
+    #
+    # Returns both the struct and any pinned memory buffers that must remain
+    # alive until the FFI call completes.
+    #
+    # @return [Array(Bindings::RouteInfo, Array)] the struct and pinned buffers
+    def to_ffi
+      info = Bindings::RouteInfo.new
+      info[:route_type] = @route_type
+      info[:slot_id] = @slot_id || 0
+      info[:slot_type] = @slot_type || :primary
+      info[:port] = @port || 0
+
+      pinned = [] # prevent GC of string buffers during FFI call
+      info[:slot_key] = pin_string(@slot_key, pinned)
+      info[:hostname] = pin_string(@hostname, pinned)
+
+      [info, pinned]
+    end
+
+    private
+
+    # Pin a string into an FFI pointer (or NULL if nil), appending the buffer
+    # to +pinned+ so it is not garbage-collected before the FFI call completes.
+    def pin_string(str, pinned)
+      return FFI::Pointer::NULL unless str
+
+      buf = FFI::MemoryPointer.from_string(str)
+      pinned << buf
+      buf
+    end
+
+    def initialize(route_type, slot_id: nil, slot_key: nil, slot_type: :primary, hostname: nil, port: nil)
+      @route_type = route_type
+      @slot_id = slot_id
+      @slot_key = slot_key
+      @slot_type = slot_type
+      @hostname = hostname
+      @port = port
+    end
+  end
+end

data/lib/valkey/utils.rb

@@ -102,6 +102,11 @@ class Valkey
     HashifyStreamEntries = lambda { |reply|
       return [] if reply.nil?
 
+      # In cluster mode, MAP responses come as Hash: {id => [fields], ...}
+      if reply.is_a?(Hash)
+        return reply.map { |entry_id, values| [entry_id, values.is_a?(Array) ? values.flatten : []] }
+      end
+
       return [] if !reply.is_a?(Array) || reply.empty?
 
       # Reply format: [[entry_id, [field1, value1, field2, value2, ...]], ...]

data/lib/valkey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Valkey
-  VERSION = "0.9.1"
+  VERSION = "0.9.2"
 end

data/lib/valkey.rb

@@ -16,6 +16,7 @@ require "valkey/errors"
 require "valkey/pubsub_callback"
 require "valkey/pipeline"
 require "valkey/opentelemetry"
+require "valkey/route"
 
 class Valkey
   include Utils
@@ -287,6 +288,9 @@ class Valkey
     @connection = res[:conn_ptr]
     Bindings.free_connection_response(response_ptr)
 
+    # Store cluster mode flag for response handling (MAP returns Hash in cluster, Array in standalone)
+    @cluster_mode = options[:cluster_mode] ? true : false
+
     # Track transactional state for `MULTI` / `EXEC` / `DISCARD` helpers.
     # This avoids Ruby warnings about uninitialised instance variables and
     # gives us a single source of truth for whether we're inside a TX.
@@ -357,7 +361,7 @@ class Valkey
   # `test/valkey/connection_lifecycle_test.rb`) call it directly with an
   # explicit receiver to issue commands with no dedicated wrapper method yet
   # (e.g. `DEBUG SLEEP`, raw `HSET` in vector search fixtures).
-  def send_command(command_type, command_args = [], &block)
+  def send_command(command_type, command_args = [], route: nil, &block)
     # Validate connection. A nil/null pointer means the client was closed (or
     # never established a usable connection); surface it as a typed error with
     # the same "the client is closed" wording the sibling GLIDE clients use
@@ -365,9 +369,6 @@ class Valkey
     raise ConnectionError, "the client is closed" if @connection.nil? || @connection.null? || @connection.address.zero?
 
     channel = 0
-    route = ""
-
-    route_buf = FFI::MemoryPointer.from_string(route)
 
     # Handle empty command_args case
     if command_args.empty?
@@ -402,20 +403,43 @@ class Valkey
     end
 
     begin
-      res = Bindings.command(
-        @connection,
-        channel,
-        command_type,
-        command_args.size,
-        arg_ptrs,
-        arg_lens,
-        route_buf,
-        route.bytesize,
-        span_ptr
-      )
+      if route
+        # Use command_with_route_info when an explicit route is provided.
+        route_info, _pinned_bufs = route.to_ffi
+        res = Bindings.command_with_route_info(
+          @connection,
+          channel,
+          command_type,
+          command_args.size,
+          arg_ptrs,
+          arg_lens,
+          route_info.to_ptr,
+          FFI::Pointer::NULL, # response_buf (NULL = normal response path)
+          0,                  # response_buf_len
+          span_ptr
+        )
+      else
+        # Use legacy command() for unrouted calls to preserve existing behavior.
+        route_str = ""
+        route_buf = FFI::MemoryPointer.from_string(route_str)
+        res = Bindings.command(
+          @connection,
+          channel,
+          command_type,
+          command_args.size,
+          arg_ptrs,
+          arg_lens,
+          route_buf,
+          route_str.bytesize,
+          span_ptr
+        )
+      end
 
-      result = convert_response(res, &block)
+      result = convert_response(res, return_map_as_hash: @cluster_mode, &block)
     ensure
+      # Free the native CommandResult (arena + response + error) to prevent memory leak
+      Bindings.free_command_result(res) if res && !res.null?
+
       # Always drop the span if one was created, even if command fails
       if span_ptr != 0
         begin
@@ -433,7 +457,9 @@ class Valkey
         RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD,
         RequestType::WATCH, RequestType::UNWATCH
       ]
-      @queued_commands << [command_type, command_args.dup] if !tx_commands.include?(command_type) && result == "QUEUED"
+      if !tx_commands.include?(command_type) && result == "QUEUED"
+        @queued_commands << [command_type, command_args.dup, block]
+      end
     end
 
     result
@@ -441,23 +467,29 @@ class Valkey
 
   private
 
-  def send_batch_commands(commands, exception: true)
+  def send_batch_commands(commands, exception: true, is_atomic: false)
     # WORKAROUND: The underlying Glide FFI backend has stability issues when
-    # batching transactional commands like MULTI / EXEC / DISCARD. To avoid
-    # native crashes we fall back to issuing those commands sequentially
-    # instead of via `Bindings.batch`.
-    tx_types = [RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD]
-
-    if commands.any? { |(command_type, _args, _block)| tx_types.include?(command_type) }
-      results = []
-
-      commands.each do |command_type, command_args, block|
-        res = send_command(command_type, command_args)
-        res = block.call(res) if block
-        results << res
-      end
+    # batching LITERAL MULTI / EXEC / DISCARD commands (e.g. a `pipelined` block
+    # that manually calls `pipeline.multi`/`pipeline.exec`). To avoid native
+    # crashes we fall back to issuing those commands sequentially instead of via
+    # `Bindings.batch`. This never applies to a real `is_atomic: true` batch
+    # (see `multi`'s block form) - that path never contains literal MULTI/EXEC
+    # commands, since the server-side transaction wrapping is handled by GLIDE
+    # itself based on the `is_atomic` flag, not by commands in the list.
+    unless is_atomic
+      tx_types = [RequestType::MULTI, RequestType::EXEC, RequestType::DISCARD]
+
+      if commands.any? { |(command_type, _args, _block)| tx_types.include?(command_type) }
+        results = []
+
+        commands.each do |command_type, command_args, block|
+          res = send_command(command_type, command_args)
+          res = block.call(res) if block
+          results << res
+        end
 
-      return results
+        return results
+      end
     end
 
     cmds = []
@@ -487,7 +519,7 @@ class Valkey
     batch_info = Bindings::BatchInfo.new
     batch_info[:cmd_count] = cmds.size
     batch_info[:cmds] = cmd_ptrs
-    batch_info[:is_atomic] = false
+    batch_info[:is_atomic] = is_atomic
 
     batch_options = Bindings::BatchOptionsInfo.new
     batch_options[:retry_server_error] = true
@@ -527,6 +559,9 @@ class Valkey
 
       results = convert_response(res)
     ensure
+      # Free the native CommandResult (arena + response + error) to prevent memory leak
+      Bindings.free_command_result(res) if res && !res.null?
+
       # Always drop the span if one was created
       if span_ptr != 0
         begin
@@ -587,7 +622,7 @@ class Valkey
     [arg_ptrs, arg_lens, buffers]
   end
 
-  def convert_response(res, &block)
+  def convert_response(res, return_map_as_hash: false, &block)
     result = Bindings::CommandResult.new(res)
 
     if result[:response].null?
@@ -643,8 +678,8 @@ class Valkey
           map[map_key] = map_value
         end
 
-        # technically it has to return a Hash, but as of now we return just one pair
-        map.to_a.flatten(1) # Flatten to get pairs
+        # Return as Hash in cluster mode, flatten to pairs in standalone mode.
+        return_map_as_hash ? map : map.to_a.flatten(1)
       when ResponseType::SETS
         ptr = response_item[:sets_value]
         count = response_item[:sets_value_len].to_i
@@ -673,7 +708,10 @@ class Valkey
 
     response = convert_response.call(result)
 
-    if block_given?
+    # Don't run the caller's converter (e.g. Utils::Boolify) over the MULTI-queued
+    # "QUEUED" sentinel - send_command's own `result == "QUEUED"` check (used to
+    # track queued commands) needs to see the literal string, not e.g. `true`.
+    if block_given? && response != "QUEUED"
       block.call(response)
     else
       response

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: valkey-glide-rb
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.9.2
 platform: ruby
 authors:
 - Valkey GLIDE Maintainers
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-17 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -82,6 +82,7 @@ files:
 - lib/valkey/request_error_type.rb
 - lib/valkey/request_type.rb
 - lib/valkey/response_type.rb
+- lib/valkey/route.rb
 - lib/valkey/utils.rb
 - lib/valkey/version.rb
 homepage: https://github.com/valkey-io/valkey-glide-ruby