redis 4.4.0 → 5.0.7

data/lib/redis/commands/lists.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+class Redis
+  module Commands
+    module Lists
+      # Get the length of a list.
+      #
+      # @param [String] key
+      # @return [Integer]
+      def llen(key)
+        send_command([:llen, key])
+      end
+
+      # Remove the first/last element in a list, append/prepend it to another list and return it.
+      #
+      # @param [String] source source key
+      # @param [String] destination destination key
+      # @param [String, Symbol] where_source from where to remove the element from the source list
+      #     e.g. 'LEFT' - from head, 'RIGHT' - from tail
+      # @param [String, Symbol] where_destination where to push the element to the source list
+      #     e.g. 'LEFT' - to head, 'RIGHT' - to tail
+      #
+      # @return [nil, String] the element, or nil when the source key does not exist
+      #
+      # @note This command comes in place of the now deprecated RPOPLPUSH.
+      #     Doing LMOVE RIGHT LEFT is equivalent.
+      def lmove(source, destination, where_source, where_destination)
+        where_source, where_destination = _normalize_move_wheres(where_source, where_destination)
+
+        send_command([:lmove, source, destination, where_source, where_destination])
+      end
+
+      # Remove the first/last element in a list and append/prepend it
+      # to another list and return it, or block until one is available.
+      #
+      # @example With timeout
+      #   element = redis.blmove("foo", "bar", "LEFT", "RIGHT", timeout: 5)
+      #     # => nil on timeout
+      #     # => "element" on success
+      # @example Without timeout
+      #   element = redis.blmove("foo", "bar", "LEFT", "RIGHT")
+      #     # => "element"
+      #
+      # @param [String] source source key
+      # @param [String] destination destination key
+      # @param [String, Symbol] where_source from where to remove the element from the source list
+      #     e.g. 'LEFT' - from head, 'RIGHT' - from tail
+      # @param [String, Symbol] where_destination where to push the element to the source list
+      #     e.g. 'LEFT' - to head, 'RIGHT' - to tail
+      # @param [Hash] options
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
+      #
+      # @return [nil, String] the element, or nil when the source key does not exist or the timeout expired
+      #
+      def blmove(source, destination, where_source, where_destination, timeout: 0)
+        where_source, where_destination = _normalize_move_wheres(where_source, where_destination)
+
+        command = [:blmove, source, destination, where_source, where_destination, timeout]
+        send_blocking_command(command, timeout)
+      end
+
+      # Prepend one or more values to a list, creating the list if it doesn't exist
+      #
+      # @param [String] key
+      # @param [String, Array<String>] value string value, or array of string values to push
+      # @return [Integer] the length of the list after the push operation
+      def lpush(key, value)
+        send_command([:lpush, key, value])
+      end
+
+      # Prepend a value to a list, only if the list exists.
+      #
+      # @param [String] key
+      # @param [String] value
+      # @return [Integer] the length of the list after the push operation
+      def lpushx(key, value)
+        send_command([:lpushx, key, value])
+      end
+
+      # Append one or more values to a list, creating the list if it doesn't exist
+      #
+      # @param [String] key
+      # @param [String, Array<String>] value string value, or array of string values to push
+      # @return [Integer] the length of the list after the push operation
+      def rpush(key, value)
+        send_command([:rpush, key, value])
+      end
+
+      # Append a value to a list, only if the list exists.
+      #
+      # @param [String] key
+      # @param [String] value
+      # @return [Integer] the length of the list after the push operation
+      def rpushx(key, value)
+        send_command([:rpushx, key, value])
+      end
+
+      # Remove and get the first elements in a list.
+      #
+      # @param [String] key
+      # @param [Integer] count number of elements to remove
+      # @return [nil, String, Array<String>] the values of the first elements
+      def lpop(key, count = nil)
+        command = [:lpop, key]
+        command << Integer(count) if count
+        send_command(command)
+      end
+
+      # Remove and get the last elements in a list.
+      #
+      # @param [String] key
+      # @param [Integer] count number of elements to remove
+      # @return [nil, String, Array<String>] the values of the last elements
+      def rpop(key, count = nil)
+        command = [:rpop, key]
+        command << Integer(count) if count
+        send_command(command)
+      end
+
+      # Remove the last element in a list, append it to another list and return it.
+      #
+      # @param [String] source source key
+      # @param [String] destination destination key
+      # @return [nil, String] the element, or nil when the source key does not exist
+      def rpoplpush(source, destination)
+        send_command([:rpoplpush, source, destination])
+      end
+
+      # Remove and get the first element in a list, or block until one is available.
+      #
+      # @example With timeout
+      #   list, element = redis.blpop("list", :timeout => 5)
+      #     # => nil on timeout
+      #     # => ["list", "element"] on success
+      # @example Without timeout
+      #   list, element = redis.blpop("list")
+      #     # => ["list", "element"]
+      # @example Blocking pop on multiple lists
+      #   list, element = redis.blpop(["list", "another_list"])
+      #     # => ["list", "element"]
+      #
+      # @param [String, Array<String>] keys one or more keys to perform the
+      #   blocking pop on
+      # @param [Hash] options
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
+      #
+      # @return [nil, [String, String]]
+      #   - `nil` when the operation timed out
+      #   - tuple of the list that was popped from and element was popped otherwise
+      def blpop(*args)
+        _bpop(:blpop, args)
+      end
+
+      # Remove and get the last element in a list, or block until one is available.
+      #
+      # @param [String, Array<String>] keys one or more keys to perform the
+      #   blocking pop on
+      # @param [Hash] options
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
+      #
+      # @return [nil, [String, String]]
+      #   - `nil` when the operation timed out
+      #   - tuple of the list that was popped from and element was popped otherwise
+      #
+      # @see #blpop
+      def brpop(*args)
+        _bpop(:brpop, args)
+      end
+
+      # Pop a value from a list, push it to another list and return it; or block
+      # until one is available.
+      #
+      # @param [String] source source key
+      # @param [String] destination destination key
+      # @param [Hash] options
+      #   - `:timeout => [Float, Integer]`: timeout in seconds, defaults to no timeout
+      #
+      # @return [nil, String]
+      #   - `nil` when the operation timed out
+      #   - the element was popped and pushed otherwise
+      def brpoplpush(source, destination, timeout: 0)
+        command = [:brpoplpush, source, destination, timeout]
+        send_blocking_command(command, timeout)
+      end
+
+      # Pops one or more elements from the first non-empty list key from the list
+      # of provided key names. If lists are empty, blocks until timeout has passed.
+      #
+      # @example Popping a element
+      #   redis.blmpop(1.0, 'list')
+      #   #=> ['list', ['a']]
+      # @example With count option
+      #   redis.blmpop(1.0, 'list', count: 2)
+      #   #=> ['list', ['a', 'b']]
+      #
+      # @params timeout [Float] a float value specifying the maximum number of seconds to block) elapses.
+      #   A timeout of zero can be used to block indefinitely.
+      # @params key [String, Array<String>] one or more keys with lists
+      # @params modifier [String]
+      #  - when `"LEFT"` - the elements popped are those from the left of the list
+      #  - when `"RIGHT"` - the elements popped are those from the right of the list
+      # @params count [Integer] a number of elements to pop
+      #
+      # @return [Array<String, Array<String, Float>>] list of popped elements or nil
+      def blmpop(timeout, *keys, modifier: "LEFT", count: nil)
+        raise ArgumentError, "Pick either LEFT or RIGHT" unless modifier == "LEFT" || modifier == "RIGHT"
+
+        args = [:lmpop, keys.size, *keys, modifier]
+        args << "COUNT" << Integer(count) if count
+
+        send_blocking_command(args, timeout)
+      end
+
+      # Pops one or more elements from the first non-empty list key from the list
+      # of provided key names.
+      #
+      # @example Popping a element
+      #   redis.lmpop('list')
+      #   #=> ['list', ['a']]
+      # @example With count option
+      #   redis.lmpop('list', count: 2)
+      #   #=> ['list', ['a', 'b']]
+      #
+      # @params key [String, Array<String>] one or more keys with lists
+      # @params modifier [String]
+      #  - when `"LEFT"` - the elements popped are those from the left of the list
+      #  - when `"RIGHT"` - the elements popped are those from the right of the list
+      # @params count [Integer] a number of elements to pop
+      #
+      # @return [Array<String, Array<String, Float>>] list of popped elements or nil
+      def lmpop(*keys, modifier: "LEFT", count: nil)
+        raise ArgumentError, "Pick either LEFT or RIGHT" unless modifier == "LEFT" || modifier == "RIGHT"
+
+        args = [:lmpop, keys.size, *keys, modifier]
+        args << "COUNT" << Integer(count) if count
+
+        send_command(args)
+      end
+
+      # Get an element from a list by its index.
+      #
+      # @param [String] key
+      # @param [Integer] index
+      # @return [String]
+      def lindex(key, index)
+        send_command([:lindex, key, Integer(index)])
+      end
+
+      # Insert an element before or after another element in a list.
+      #
+      # @param [String] key
+      # @param [String, Symbol] where `BEFORE` or `AFTER`
+      # @param [String] pivot reference element
+      # @param [String] value
+      # @return [Integer] length of the list after the insert operation, or `-1`
+      #   when the element `pivot` was not found
+      def linsert(key, where, pivot, value)
+        send_command([:linsert, key, where, pivot, value])
+      end
+
+      # Get a range of elements from a list.
+      #
+      # @param [String] key
+      # @param [Integer] start start index
+      # @param [Integer] stop stop index
+      # @return [Array<String>]
+      def lrange(key, start, stop)
+        send_command([:lrange, key, Integer(start), Integer(stop)])
+      end
+
+      # Remove elements from a list.
+      #
+      # @param [String] key
+      # @param [Integer] count number of elements to remove. Use a positive
+      #   value to remove the first `count` occurrences of `value`. A negative
+      #   value to remove the last `count` occurrences of `value`. Or zero, to
+      #   remove all occurrences of `value` from the list.
+      # @param [String] value
+      # @return [Integer] the number of removed elements
+      def lrem(key, count, value)
+        send_command([:lrem, key, Integer(count), value])
+      end
+
+      # Set the value of an element in a list by its index.
+      #
+      # @param [String] key
+      # @param [Integer] index
+      # @param [String] value
+      # @return [String] `OK`
+      def lset(key, index, value)
+        send_command([:lset, key, Integer(index), value])
+      end
+
+      # Trim a list to the specified range.
+      #
+      # @param [String] key
+      # @param [Integer] start start index
+      # @param [Integer] stop stop index
+      # @return [String] `OK`
+      def ltrim(key, start, stop)
+        send_command([:ltrim, key, Integer(start), Integer(stop)])
+      end
+
+      private
+
+      def _bpop(cmd, args, &blk)
+        timeout = if args.last.is_a?(Hash)
+          options = args.pop
+          options[:timeout]
+        end
+
+        timeout ||= 0
+        unless timeout.is_a?(Integer) || timeout.is_a?(Float)
+          raise ArgumentError, "timeout must be an Integer or Float, got: #{timeout.class}"
+        end
+
+        args.flatten!(1)
+        command = [cmd].concat(args)
+        command << timeout
+        send_blocking_command(command, timeout, &blk)
+      end
+
+      def _normalize_move_wheres(where_source, where_destination)
+        where_source      = where_source.to_s.upcase
+        where_destination = where_destination.to_s.upcase
+
+        if where_source != "LEFT" && where_source != "RIGHT"
+          raise ArgumentError, "where_source must be 'LEFT' or 'RIGHT'"
+        end
+
+        if where_destination != "LEFT" && where_destination != "RIGHT"
+          raise ArgumentError, "where_destination must be 'LEFT' or 'RIGHT'"
+        end
+
+        [where_source, where_destination]
+      end
+    end
+  end
+end

data/lib/redis/commands/pubsub.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class Redis
+  module Commands
+    module Pubsub
+      # Post a message to a channel.
+      def publish(channel, message)
+        send_command([:publish, channel, message])
+      end
+
+      def subscribed?
+        !@subscription_client.nil?
+      end
+
+      # Listen for messages published to the given channels.
+      def subscribe(*channels, &block)
+        _subscription(:subscribe, 0, channels, block)
+      end
+
+      # Listen for messages published to the given channels. Throw a timeout error
+      # if there is no messages for a timeout period.
+      def subscribe_with_timeout(timeout, *channels, &block)
+        _subscription(:subscribe_with_timeout, timeout, channels, block)
+      end
+
+      # Stop listening for messages posted to the given channels.
+      def unsubscribe(*channels)
+        _subscription(:unsubscribe, 0, channels, nil)
+      end
+
+      # Listen for messages published to channels matching the given patterns.
+      def psubscribe(*channels, &block)
+        _subscription(:psubscribe, 0, channels, block)
+      end
+
+      # Listen for messages published to channels matching the given patterns.
+      # Throw a timeout error if there is no messages for a timeout period.
+      def psubscribe_with_timeout(timeout, *channels, &block)
+        _subscription(:psubscribe_with_timeout, timeout, channels, block)
+      end
+
+      # Stop listening for messages posted to channels matching the given patterns.
+      def punsubscribe(*channels)
+        _subscription(:punsubscribe, 0, channels, nil)
+      end
+
+      # Inspect the state of the Pub/Sub subsystem.
+      # Possible subcommands: channels, numsub, numpat.
+      def pubsub(subcommand, *args)
+        send_command([:pubsub, subcommand] + args)
+      end
+    end
+  end
+end

data/lib/redis/commands/scripting.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+class Redis
+  module Commands
+    module Scripting
+      # Control remote script registry.
+      #
+      # @example Load a script
+      #   sha = redis.script(:load, "return 1")
+      #     # => <sha of this script>
+      # @example Check if a script exists
+      #   redis.script(:exists, sha)
+      #     # => true
+      # @example Check if multiple scripts exist
+      #   redis.script(:exists, [sha, other_sha])
+      #     # => [true, false]
+      # @example Flush the script registry
+      #   redis.script(:flush)
+      #     # => "OK"
+      # @example Kill a running script
+      #   redis.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)
+        subcommand = subcommand.to_s.downcase
+
+        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
+
+      # Evaluate Lua script.
+      #
+      # @example EVAL without KEYS nor ARGV
+      #   redis.eval("return 1")
+      #     # => 1
+      # @example EVAL with KEYS and ARGV as array arguments
+      #   redis.eval("return { KEYS, ARGV }", ["k1", "k2"], ["a1", "a2"])
+      #     # => [["k1", "k2"], ["a1", "a2"]]
+      # @example EVAL with KEYS and ARGV in a hash argument
+      #   redis.eval("return { KEYS, ARGV }", :keys => ["k1", "k2"], :argv => ["a1", "a2"])
+      #     # => [["k1", "k2"], ["a1", "a2"]]
+      #
+      # @param [Array<String>] keys optional array with keys to pass to the script
+      # @param [Array<String>] argv optional array with arguments to pass to the script
+      # @param [Hash] options
+      #   - `:keys => Array<String>`: optional array with keys to pass to the script
+      #   - `:argv => Array<String>`: optional array with arguments to pass to the script
+      # @return depends on the script
+      #
+      # @see #script
+      # @see #evalsha
+      def eval(*args)
+        _eval(:eval, args)
+      end
+
+      # Evaluate Lua script by its SHA.
+      #
+      # @example EVALSHA without KEYS nor ARGV
+      #   redis.evalsha(sha)
+      #     # => <depends on script>
+      # @example EVALSHA with KEYS and ARGV as array arguments
+      #   redis.evalsha(sha, ["k1", "k2"], ["a1", "a2"])
+      #     # => <depends on script>
+      # @example EVALSHA with KEYS and ARGV in a hash argument
+      #   redis.evalsha(sha, :keys => ["k1", "k2"], :argv => ["a1", "a2"])
+      #     # => <depends on script>
+      #
+      # @param [Array<String>] keys optional array with keys to pass to the script
+      # @param [Array<String>] argv optional array with arguments to pass to the script
+      # @param [Hash] options
+      #   - `:keys => Array<String>`: optional array with keys to pass to the script
+      #   - `:argv => Array<String>`: optional array with arguments to pass to the script
+      # @return depends on the script
+      #
+      # @see #script
+      # @see #eval
+      def evalsha(*args)
+        _eval(:evalsha, args)
+      end
+
+      private
+
+      def _eval(cmd, args)
+        script = args.shift
+        options = args.pop if args.last.is_a?(Hash)
+        options ||= {}
+
+        keys = args.shift || options[:keys] || []
+        argv = args.shift || options[:argv] || []
+
+        send_command([cmd, script, keys.length] + keys + argv)
+      end
+    end
+  end
+end

data/lib/redis/commands/server.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+class Redis
+  module Commands
+    module Server
+      # Asynchronously rewrite the append-only file.
+      #
+      # @return [String] `OK`
+      def bgrewriteaof
+        send_command([:bgrewriteaof])
+      end
+
+      # Asynchronously save the dataset to disk.
+      #
+      # @return [String] `OK`
+      def bgsave
+        send_command([:bgsave])
+      end
+
+      # Get or set server configuration parameters.
+      #
+      # @param [Symbol] action e.g. `:get`, `:set`, `:resetstat`
+      # @return [String, Hash] string reply, or hash when retrieving more than one
+      #   property with `CONFIG GET`
+      def config(action, *args)
+        send_command([:config, action] + args) do |reply|
+          if reply.is_a?(Array) && action == :get
+            Hashify.call(reply)
+          else
+            reply
+          end
+        end
+      end
+
+      # Manage client connections.
+      #
+      # @param [String, Symbol] subcommand e.g. `kill`, `list`, `getname`, `setname`
+      # @return [String, Hash] depends on subcommand
+      def client(subcommand, *args)
+        send_command([:client, subcommand] + args) do |reply|
+          if subcommand.to_s == "list"
+            reply.lines.map do |line|
+              entries = line.chomp.split(/[ =]/)
+              Hash[entries.each_slice(2).to_a]
+            end
+          else
+            reply
+          end
+        end
+      end
+
+      # Return the number of keys in the selected database.
+      #
+      # @return [Integer]
+      def dbsize
+        send_command([:dbsize])
+      end
+
+      # Remove all keys from all databases.
+      #
+      # @param [Hash] options
+      #   - `:async => Boolean`: async flush (default: false)
+      # @return [String] `OK`
+      def flushall(options = nil)
+        if options && options[:async]
+          send_command(%i[flushall async])
+        else
+          send_command([:flushall])
+        end
+      end
+
+      # Remove all keys from the current database.
+      #
+      # @param [Hash] options
+      #   - `:async => Boolean`: async flush (default: false)
+      # @return [String] `OK`
+      def flushdb(options = nil)
+        if options && options[:async]
+          send_command(%i[flushdb async])
+        else
+          send_command([:flushdb])
+        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([:info, cmd].compact) do |reply|
+          if reply.is_a?(String)
+            reply = HashifyInfo.call(reply)
+
+            if cmd && cmd.to_s == "commandstats"
+              # Extract nested hashes for INFO COMMANDSTATS
+              reply = Hash[reply.map do |k, v|
+                v = v.split(",").map { |e| e.split("=") }
+                [k[/^cmdstat_(.*)$/, 1], Hash[v]]
+              end]
+            end
+          end
+
+          reply
+        end
+      end
+
+      # Get the UNIX time stamp of the last successful save to disk.
+      #
+      # @return [Integer]
+      def lastsave
+        send_command([:lastsave])
+      end
+
+      # Listen for all requests received by the server in real time.
+      #
+      # There is no way to interrupt this command.
+      #
+      # @yield a block to be called for every line of output
+      # @yieldparam [String] line timestamp and command that was executed
+      def monitor
+        synchronize do |client|
+          client = client.pubsub
+          client.call_v([:monitor])
+          loop do
+            yield client.next_event
+          end
+        end
+      end
+
+      # Synchronously save the dataset to disk.
+      #
+      # @return [String]
+      def save
+        send_command([:save])
+      end
+
+      # Synchronously save the dataset to disk and then shut down the server.
+      def shutdown
+        synchronize do |client|
+          client.disable_reconnection do
+            client.call_v([:shutdown])
+          rescue ConnectionError
+            # This means Redis has probably exited.
+            nil
+          end
+        end
+      end
+
+      # Make the server a slave of another instance, or promote it as master.
+      def slaveof(host, port)
+        send_command([:slaveof, host, port])
+      end
+
+      # Interact with the slowlog (get, len, reset)
+      #
+      # @param [String] subcommand e.g. `get`, `len`, `reset`
+      # @param [Integer] length maximum number of entries to return
+      # @return [Array<String>, Integer, String] depends on subcommand
+      def slowlog(subcommand, length = nil)
+        args = [:slowlog, subcommand]
+        args << Integer(length) if length
+        send_command(args)
+      end
+
+      # Internal command used for replication.
+      def sync
+        send_command([:sync])
+      end
+
+      # Return the server time.
+      #
+      # @example
+      #   r.time # => [ 1333093196, 606806 ]
+      #
+      # @return [Array<Integer>] tuple of seconds since UNIX epoch and
+      #   microseconds in the current second
+      def time
+        send_command([:time]) do |reply|
+          reply&.map(&:to_i)
+        end
+      end
+
+      def debug(*args)
+        send_command([:debug] + args)
+      end
+    end
+  end
+end