valkey-rb 1.0.0

data/lib/valkey/commands/pubsub_commands.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Commands
+    # This module contains commands related to Valkey Pub/Sub.
+    #
+    # @see https://valkey.io/commands/#pubsub
+    #
+    module PubSubCommands
+      # Subscribe to one or more channels.
+      #
+      # @example Subscribe to channels
+      #   valkey.subscribe("channel1", "channel2")
+      #     # => "OK"
+      #
+      # @param [Array<String>] channels the channels to subscribe to
+      # @return [String] "OK"
+      #
+      # @see https://valkey.io/commands/subscribe/
+      def subscribe(*channels)
+        send_command(RequestType::SUBSCRIBE, channels)
+      end
+
+      # Unsubscribe from one or more channels.
+      #
+      # @example Unsubscribe from channels
+      #   valkey.unsubscribe("channel1", "channel2")
+      #     # => "OK"
+      # @example Unsubscribe from all channels
+      #   valkey.unsubscribe
+      #     # => "OK"
+      #
+      # @param [Array<String>] channels the channels to unsubscribe from (empty for all)
+      # @return [String] "OK"
+      #
+      # @see https://valkey.io/commands/unsubscribe/
+      def unsubscribe(*channels)
+        send_command(RequestType::UNSUBSCRIBE, channels)
+      end
+
+      # Subscribe to one or more patterns.
+      #
+      # @example Subscribe to patterns
+      #   valkey.psubscribe("news.*", "events.*")
+      #     # => "OK"
+      #
+      # @param [Array<String>] patterns the patterns to subscribe to
+      # @return [String] "OK"
+      #
+      # @see https://valkey.io/commands/psubscribe/
+      def psubscribe(*patterns)
+        send_command(RequestType::PSUBSCRIBE, patterns)
+      end
+
+      # Unsubscribe from one or more patterns.
+      #
+      # @example Unsubscribe from patterns
+      #   valkey.punsubscribe("news.*", "events.*")
+      #     # => "OK"
+      # @example Unsubscribe from all patterns
+      #   valkey.punsubscribe
+      #     # => "OK"
+      #
+      # @param [Array<String>] patterns the patterns to unsubscribe from (empty for all)
+      # @return [String] "OK"
+      #
+      # @see https://valkey.io/commands/punsubscribe/
+      def punsubscribe(*patterns)
+        send_command(RequestType::PUNSUBSCRIBE, patterns)
+      end
+
+      # Publish a message to a channel.
+      #
+      # @example Publish a message
+      #   valkey.publish("channel1", "Hello, World!")
+      #     # => 2
+      #
+      # @param [String] channel the channel to publish to
+      # @param [String] message the message to publish
+      # @return [Integer] the number of clients that received the message
+      #
+      # @see https://valkey.io/commands/publish/
+      def publish(channel, message)
+        send_command(RequestType::PUBLISH, [channel, message])
+      end
+
+      # Subscribe to one or more shard channels.
+      #
+      # @example Subscribe to shard channels
+      #   valkey.ssubscribe("shard1", "shard2")
+      #     # => "OK"
+      #
+      # @param [Array<String>] channels the shard channels to subscribe to
+      # @return [String] "OK"
+      #
+      # @see https://valkey.io/commands/ssubscribe/
+      def ssubscribe(*channels)
+        send_command(RequestType::SSUBSCRIBE, channels)
+      end
+
+      # Unsubscribe from one or more shard channels.
+      #
+      # @example Unsubscribe from shard channels
+      #   valkey.sunsubscribe("shard1", "shard2")
+      #     # => "OK"
+      # @example Unsubscribe from all shard channels
+      #   valkey.sunsubscribe
+      #     # => "OK"
+      #
+      # @param [Array<String>] channels the shard channels to unsubscribe from (empty for all)
+      # @return [String] "OK"
+      #
+      # @see https://valkey.io/commands/sunsubscribe/
+      def sunsubscribe(*channels)
+        send_command(RequestType::SUNSUBSCRIBE, channels)
+      end
+
+      # Publish a message to a shard channel.
+      #
+      # @example Publish a message to a shard channel
+      #   valkey.spublish("shard1", "Hello, Shard!")
+      #     # => 1
+      #
+      # @param [String] channel the shard channel to publish to
+      # @param [String] message the message to publish
+      # @return [Integer] the number of clients that received the message
+      #
+      # @see https://valkey.io/commands/spublish/
+      def spublish(channel, message)
+        send_command(RequestType::SPUBLISH, [channel, message])
+      end
+
+      # List active channels.
+      #
+      # @example List all active channels
+      #   valkey.pubsub_channels
+      #     # => ["channel1", "channel2"]
+      # @example List active channels matching a pattern
+      #   valkey.pubsub_channels("news.*")
+      #     # => ["news.sports", "news.tech"]
+      #
+      # @param [String] pattern optional pattern to filter channels
+      # @return [Array<String>] list of active channels
+      #
+      # @see https://valkey.io/commands/pubsub-channels/
+      def pubsub_channels(pattern = nil)
+        args = pattern ? [pattern] : []
+        send_command(RequestType::PUBSUB_CHANNELS, args)
+      end
+
+      # Get the number of unique patterns subscribed to.
+      #
+      # @example Get pattern count
+      #   valkey.pubsub_numpat
+      #     # => 3
+      #
+      # @return [Integer] the number of patterns
+      #
+      # @see https://valkey.io/commands/pubsub-numpat/
+      def pubsub_numpat
+        send_command(RequestType::PUBSUB_NUM_PAT)
+      end
+
+      # Get the number of subscribers for channels.
+      #
+      # @example Get subscriber counts
+      #   valkey.pubsub_numsub("channel1", "channel2")
+      #     # => ["channel1", 5, "channel2", 3]
+      #
+      # @param [Array<String>] channels the channels to check
+      # @return [Array] channel names and subscriber counts
+      #
+      # @see https://valkey.io/commands/pubsub-numsub/
+      def pubsub_numsub(*channels)
+        send_command(RequestType::PUBSUB_NUM_SUB, channels)
+      end
+
+      # List active shard channels.
+      #
+      # @example List all active shard channels
+      #   valkey.pubsub_shardchannels
+      #     # => ["shard1", "shard2"]
+      # @example List active shard channels matching a pattern
+      #   valkey.pubsub_shardchannels("shard.*")
+      #     # => ["shard.1", "shard.2"]
+      #
+      # @param [String] pattern optional pattern to filter shard channels
+      # @return [Array<String>] list of active shard channels
+      #
+      # @see https://valkey.io/commands/pubsub-shardchannels/
+      def pubsub_shardchannels(pattern = nil)
+        args = pattern ? [pattern] : []
+        send_command(RequestType::PUBSUB_SHARD_CHANNELS, args)
+      end
+
+      # Get the number of subscribers for shard channels.
+      #
+      # @example Get shard subscriber counts
+      #   valkey.pubsub_shardnumsub("shard1", "shard2")
+      #     # => ["shard1", 2, "shard2", 1]
+      #
+      # @param [Array<String>] channels the shard channels to check
+      # @return [Array] shard channel names and subscriber counts
+      #
+      # @see https://valkey.io/commands/pubsub-shardnumsub/
+      def pubsub_shardnumsub(*channels)
+        send_command(RequestType::PUBSUB_SHARD_NUM_SUB, channels)
+      end
+
+      # Control pub/sub operations (convenience method).
+      #
+      # @example List active channels
+      #   valkey.pubsub(:channels)
+      #     # => ["channel1", "channel2"]
+      # @example Get pattern count
+      #   valkey.pubsub(:numpat)
+      #     # => 3
+      # @example Get subscriber counts
+      #   valkey.pubsub(:numsub, "channel1", "channel2")
+      #     # => ["channel1", 5, "channel2", 3]
+      # @example List active shard channels
+      #   valkey.pubsub(:shardchannels)
+      #     # => ["shard1", "shard2"]
+      # @example Get shard subscriber counts
+      #   valkey.pubsub(:shardnumsub, "shard1", "shard2")
+      #     # => ["shard1", 2, "shard2", 1]
+      #
+      # @param [String, Symbol] subcommand the subcommand (channels, numpat, numsub, shardchannels, shardnumsub)
+      # @param [Array] args arguments for the subcommand
+      # @return [Object] depends on subcommand
+      def pubsub(subcommand, *args)
+        subcommand = subcommand.to_s.downcase
+        send("pubsub_#{subcommand}", *args)
+      end
+    end
+  end
+end

data/lib/valkey/commands/scripting_commands.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+class Valkey
+  module Commands
+    # this module contains commands related to list data type.
+    #
+    # @see https://valkey.io/commands/#scripting
+    #
+    module ScriptingCommands
+      # Control remote script registry.
+      #
+      # @example Load a script
+      #   sha = valkey.script(:load, "return 1")
+      #     # => <sha of this script>
+      # @example Check if a script exists
+      #   valkey.script(:exists, sha)
+      #     # => true
+      # @example Check if multiple scripts exist
+      #   valkey.script(:exists, [sha, other_sha])
+      #     # => [true, false]
+      # @example Flush the script registry
+      #   valkey.script(:flush)
+      #     # => "OK"
+      # @example Kill a running script
+      #   valkey.script(:kill)
+      #     # => "OK"
+      #
+      # @param [String] subcommand e.g. `exists`, `flush`, `load`, `kill`
+      # @param [Array<String>] args depends on subcommand
+      # @return [String, Boolean, Array<Boolean>, ...] depends on subcommand
+      #
+      # @see #eval
+      # @see #evalsha
+      def script(subcommand, args = nil, options: {})
+        subcommand = subcommand.to_s.downcase
+
+        if args.nil?
+          send("script_#{subcommand}", **options)
+        else
+          send("script_#{subcommand}", args)
+        end
+
+        # if subcommand == "exists"
+        #   arg = args.first
+        #
+        #   send_command([:script, :exists, arg]) do |reply|
+        #     reply = reply.map { |r| Boolify.call(r) }
+        #
+        #     if arg.is_a?(Array)
+        #       reply
+        #     else
+        #       reply.first
+        #     end
+        #   end
+        # else
+        #   send_command([:script, subcommand] + args)
+        # end
+      end
+
+      def script_flush(sync: false, async: false)
+        args = []
+
+        if async
+          args << "async"
+        elsif sync
+          args << "sync"
+        end
+
+        send_command(RequestType::SCRIPT_FLUSH, args)
+      end
+
+      def script_exists(args)
+        send_command(RequestType::SCRIPT_EXISTS, Array(args)) do |reply|
+          if args.is_a?(Array)
+            reply
+          else
+            reply.first
+          end
+        end
+      end
+
+      def script_kill
+        send_command(RequestType::SCRIPT_KILL)
+      end
+
+      # Set the debug mode for subsequent scripts executed with EVAL.
+      #
+      # @param [String] mode debug mode: "YES", "SYNC", or "NO"
+      # @return [String] "OK"
+      #
+      # @example Enable script debugging
+      #   valkey.script_debug("YES")
+      #     # => "OK"
+      # @example Disable script debugging
+      #   valkey.script_debug("NO")
+      #     # => "OK"
+      #
+      # @see https://valkey.io/commands/script-debug/
+      def script_debug(mode)
+        send_command(RequestType::SCRIPT_DEBUG, [mode.to_s.upcase])
+      end
+
+      def script_load(script)
+        script = script.first if script.is_a?(Array)
+
+        buf = FFI::MemoryPointer.new(:char, script.bytesize)
+        buf.put_bytes(0, script)
+
+        result = Bindings.store_script(buf, script.bytesize)
+
+        hash_buffer = Bindings::ScriptHashBuffer.new(result)
+        hash_buffer[:ptr].read_string(hash_buffer[:len])
+      end
+
+      # Execute a Lua script on the server.
+      #
+      # @param [String] script the Lua script to execute
+      # @param [Array<String>] keys array of key names that the script will access
+      # @param [Array<Object>] args array of arguments to pass to the script
+      # @return [Object] the result of the script execution
+      # @raise [ArgumentError] if script is empty
+      # @raise [CommandError] if script execution fails
+      #
+      # @example Execute a simple script
+      #   valkey.eval("return 1")
+      #     # => 1
+      # @example Execute script with keys and arguments
+      #   valkey.eval("return KEYS[1] .. ARGV[1]", keys: ["mykey"], args: ["myarg"])
+      #     # => "mykeynyarg"
+      # @example Execute script with multiple keys and arguments
+      #   valkey.eval("return #KEYS + #ARGV", keys: ["key1", "key2"], args: ["arg1", "arg2", "arg3"])
+      #     # => 5
+      # @example Execute script that returns different data types
+      #   valkey.eval("return {1, 'hello', true, nil}")
+      #     # => [1, "hello", true, nil]
+      # Since the eval is not available in the rust backend
+      # using the load and invoke script
+      def eval(script, keys: [], args: [])
+        # Validate script parameter
+        raise ArgumentError, "script must be a string" unless script.is_a?(String)
+        raise ArgumentError, "script cannot be empty" if script.empty?
+
+        # Validate and convert keys and args to strings
+        begin
+          keys = Array(keys).map(&:to_s)
+          args = Array(args).map(&:to_s)
+        rescue StandardError => e
+          raise ArgumentError, "failed to convert keys or args to strings: #{e.message}"
+        end
+
+        # Load script to get SHA1 hash, then execute via invoke_script
+        sha = script_load(script)
+        invoke_script(sha, keys: keys, args: args)
+      end
+
+      # Execute a cached Lua script by its SHA1 hash.
+      #
+      # @param [String] sha the SHA1 hash of the script to execute
+      # @param [Array<String>] keys array of key names that the script will access
+      # @param [Array<Object>] args array of arguments to pass to the script
+      # @return [Object] the result of the script execution
+      # @raise [ArgumentError] if SHA1 hash format is invalid
+      # @raise [CommandError] if script is not found or execution fails
+      #
+      # @example Execute a cached script
+      #   sha = valkey.script_load("return 1")
+      #   valkey.evalsha(sha)
+      #     # => 1
+      # @example Execute cached script with parameters
+      #   script = "return KEYS[1] .. ':' .. ARGV[1]"
+      #   sha = valkey.script_load(script)
+      #   valkey.evalsha(sha, keys: ["user"], args: ["123"])
+      #     # => "user:123"
+      # @example Handle script not found error
+      #   begin
+      #     valkey.evalsha("nonexistent_sha", keys: [], args: [])
+      #   rescue Valkey::CommandError => e
+      #     puts "Script not found: #{e.message}"
+      #   end
+      # Since evalsha is not available in rust backend
+      # using invoke script
+      def evalsha(sha, keys: [], args: [])
+        # 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)
+
+        # Validate and convert keys and args to strings
+        begin
+          keys = Array(keys).map(&:to_s)
+          args = Array(args).map(&:to_s)
+        rescue StandardError => e
+          raise ArgumentError, "failed to convert keys or args to strings: #{e.message}"
+        end
+
+        # Execute cached script via invoke_script
+        invoke_script(sha, keys: keys, args: args)
+      end
+
+      # Execute a read-only Lua script on the server.
+      #
+      # This is a read-only variant of EVAL that cannot execute commands
+      # that modify data. It can be routed to read replicas.
+      #
+      # @param [String] script the Lua script to execute
+      # @param [Array<String>] keys array of key names that the script will access
+      # @param [Array<Object>] args array of arguments to pass to the script
+      # @return [Object] the result of the script execution
+      #
+      # @example Execute a read-only script
+      #   valkey.eval_ro("return redis.call('get', KEYS[1])", keys: ["mykey"])
+      #     # => "myvalue"
+      #
+      # @see https://valkey.io/commands/eval_ro/
+      def eval_ro(script, keys: [], args: [])
+        raise ArgumentError, "script must be a string" unless script.is_a?(String)
+        raise ArgumentError, "script cannot be empty" if script.empty?
+
+        keys = Array(keys).map(&:to_s)
+        args = Array(args).map(&:to_s)
+
+        sha = script_load(script)
+        invoke_script(sha, keys: keys, args: args)
+      end
+
+      # Execute a cached read-only Lua script by its SHA1 hash.
+      #
+      # This is a read-only variant of EVALSHA that cannot execute commands
+      # that modify data. It can be routed to read replicas.
+      #
+      # @param [String] sha the SHA1 hash of the script to execute
+      # @param [Array<String>] keys array of key names that the script will access
+      # @param [Array<Object>] args array of arguments to pass to the script
+      # @return [Object] the result of the script execution
+      #
+      # @example Execute a cached read-only script
+      #   sha = valkey.script_load("return redis.call('get', KEYS[1])")
+      #   valkey.evalsha_ro(sha, keys: ["mykey"])
+      #     # => "myvalue"
+      #
+      # @see https://valkey.io/commands/evalsha_ro/
+      def evalsha_ro(sha, keys: [], args: [])
+        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)
+
+        keys = Array(keys).map(&:to_s)
+        args = Array(args).map(&:to_s)
+
+        invoke_script(sha, keys: keys, args: args)
+      end
+
+      def invoke_script(script, args: [], keys: [])
+        arg_ptrs, arg_lens = build_command_args(args)
+        keys_ptrs, keys_lens = build_command_args(keys)
+
+        route = ""
+        route_buf = FFI::MemoryPointer.from_string(route)
+
+        sha = FFI::MemoryPointer.new(:char, script.bytesize + 1)
+        sha.put_bytes(0, script)
+
+        res = Bindings.invoke_script(
+          @connection,
+          0,
+          sha,
+          keys.size,
+          keys_ptrs,
+          keys_lens,
+          args.size,
+          arg_ptrs,
+          arg_lens,
+          route_buf,
+          route.bytesize
+        )
+
+        convert_response(res)
+      end
+
+      private
+
+      # Validate SHA1 hash format (40-character hexadecimal string)
+      def valid_sha1?(sha)
+        sha.is_a?(String) && sha.length == 40 && sha.match?(/\A[a-fA-F0-9]{40}\z/)
+      end
+    end
+  end
+end