valkey-glide-rb 0.9.1 → 0.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8824baa9eb08b0496a2428dd1a0c4997d9716810ba75d607bbadd0c40a99dde
-  data.tar.gz: 23704fe50125575ad927860cabf0cae7f7ed9d915f651d049b608ca809fda2e9
+  metadata.gz: e3c28ac646b9b41dc630b6a28396af105cf70e38c20cdd2e74ac7dde1245b952
+  data.tar.gz: a417f802a018a41a16c8cfbfb1a12ba68af48eb4d6e176b48e936558a87a4bcf
 SHA512:
-  metadata.gz: 62a9bd00a4bc4f1cde9da036e86703a504f7a7ef355ffce8f254c5cf46ebb103c88242e20255a14d7adee3fbf3089db584c8703c5a5f89f9a7c0e04863254abb
-  data.tar.gz: 7a7b9672f5cd499878aef940198b3f48e58fff82d9a8468eb12ab3abc57446dd905326c44aa33145926fd1c28af226817937ac9cb3b69717b7f1d07b08e3fc0f
+  metadata.gz: '08c8c01d41da6be96ea35fbf0a582dd0676a63a96a69244d3ec14d58cbbf496935a6beafe992d750d65c100f43c54fd00bf3f0c69352b407808578821fc7eab9'
+  data.tar.gz: 606d32093482a5827a216bd77c371aec94b6de684cedcdeb9181dae117e1abef9feb6f5ff2d8ccda78c954504752d57dfed44a3296a46175fc4b709a50e45330

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,17 +570,21 @@ 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
 
       # Flattens Arrays and Hashes (to alternating key/value) and stringifies
-      # Integers/Floats, matching `redis-client`'s documented `#call`/`#call_v` behavior.
+      # Integers/Floats/Symbols, matching `redis-client`'s documented
+      # `#call`/`#call_v` behavior - including its type check: any leaf that
+      # isn't a String/Symbol/Integer/Float (e.g. `nil`) raises `TypeError`
+      # instead of being silently coerced to `""` via `#to_s`.
       #
       # @example
       #   flatten_call_args(["CMD", [1, [2, 3]], { "a" => 1, "b" => [2, 3] }])
@@ -597,8 +603,10 @@ class Valkey
             stack.concat(arg.reverse)
           when Hash
             arg.to_a.reverse_each { |pair| stack.concat(pair.reverse) }
-          else
+          when String, Symbol, Integer, Float
             acc << arg.to_s
+          else
+            raise TypeError, "Unsupported command argument type: #{arg.class}"
           end
         end
 

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)
@@ -249,8 +271,13 @@ class Valkey
       end
 
       def invoke_script(script, args: [], keys: [])
-        arg_ptrs, arg_lens = build_command_args(args)
-        keys_ptrs, keys_lens = build_command_args(keys)
+        # Must hold onto the returned buffers (_arg_bufs/_keys_bufs) for the
+        # lifetime of this method - they back arg_ptrs/keys_ptrs, and letting
+        # them go out of scope (e.g. by only capturing the first 2 return
+        # values) makes them eligible for GC before the native call below
+        # reads through those pointers, corrupting ARGV/KEYS with freed memory.
+        arg_ptrs, arg_lens, _arg_bufs, flattened_args = build_command_args(args)
+        keys_ptrs, keys_lens, _keys_bufs, flattened_keys = build_command_args(keys)
 
         route = ""
         route_buf = FFI::MemoryPointer.from_string(route)
@@ -258,22 +285,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,
+            flattened_keys.size,
+            keys_ptrs,
+            keys_lens,
+            flattened_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