redis-client 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ded07d814692a3e286f61a38a3d8129ef35189659124e73fd3e24e4e53a6a08b
-  data.tar.gz: 021c3dc9bf79717313a9f41e6bc29973cafbfe08ba15b2eb2b8560228939752b
+  metadata.gz: 398676851a40081cd70d1334fa845292b0df4b7036d6ae33d0fa3ae6fa7ee040
+  data.tar.gz: 0a17e311c65180dcd67f106bcaca6e1f08a441e38e9ffdbab9876e2b3f62bc0a
 SHA512:
-  metadata.gz: 52ebda137196361b56487d014cdbf5f188cd8822d92f955aeb39ee9fdea448051e38be2e68bf60616cdbeec1df942c25472a5d71e6b6c139ef96b1286db94d32
-  data.tar.gz: 495caeef04270d289eb58a5a1f0f52f19414db8d3efa0554edea041d165a3e14a33337156fa28c55c56fbee29b5683347d871fb7f84f79fea02371d1e0f605ce
+  metadata.gz: 196f490ad7632f4139099b6047c3973b8957be2df24a92f1ba9f5f7588360c2a89b04b487cd24251e4aabf6006bd51cece7429f9aeae75b9e5013cb00240bdfc
+  data.tar.gz: bee6d01afc6805fa70720c09b213841d719a4bb045b6694d5a1d9c9efe6a5875c403464b7451d0d0a4d8056467440306936250cd6f537d47b45ee962dfa90658

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Unreleased
 
-- hiredis: Workaround a compilation bug with Xcode 14.0, Fix: #58
+# 0.12.0
+
+- hiredis: fix a compilation issue on macOS and Ruby 3.2.0. See: #79
+- Close connection on MASTERDOWN errors. Similar to READONLY.
+- Add a `circuit_breaker` configuration option for cache servers and other disposable Redis servers. See #55 / #70
+
+# 0.11.2
+
+- Close connection on READONLY errors. Fix: #64
+- Handle Redis 6+ servers with a missing HELLO command. See: #67
+- Validate `url` parameters a bit more strictly. Fix #61
+
+# 0.11.1
+
+- hiredis: Workaround a compilation bug with Xcode 14.0. Fix: #58
 - Accept `URI` instances as `uri` parameter.
 
 # 0.11.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    redis-client (0.11.1)
+    redis-client (0.12.0)
       connection_pool
 
 GEM
@@ -19,7 +19,7 @@ GEM
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
-    rake-compiler (1.2.0)
+    rake-compiler (1.2.1)
       rake
     redis (4.6.0)
     regexp_parser (2.5.0)
@@ -38,7 +38,7 @@ GEM
     rubocop-minitest (0.19.1)
       rubocop (>= 0.90, < 2.0)
     ruby-progressbar (1.11.0)
-    stackprof (0.2.22)
+    stackprof (0.2.23)
     toxiproxy (2.0.2)
     unicode-display_width (2.2.0)
 

data/README.md

@@ -63,7 +63,7 @@ redis.call("GET", "mykey")
 ### Configuration
 
 - `url`: A Redis connection URL, e.g. `redis://example.com:6379/5`, a `rediss://` scheme enable SSL, and the path is interpreted as a database number.
-  Note that all other configurations take precedence, e.g. `RedisClient.config(url: "redis://localhost:3000" port: 6380)` will connect on port `6380`.
+  Note that all other configurations take precedence, e.g. `RedisClient.config(url: "redis://localhost:3000", port: 6380)` will connect on port `6380`.
 - `host`: The server hostname or IP address. Defaults to `"localhost"`.
 - `port`: The server port. Defaults to `6379`.
 - `path`: The path to a UNIX socket, if set `url`, `host` and `port` are ignored.
@@ -81,6 +81,7 @@ redis.call("GET", "mykey")
 - `read_timeout`: The read timeout, takes precedence over the general timeout when reading responses from the server.
 - `write_timeout`: The write timeout, takes precedence over the general timeout when sending commands to the server.
 - `reconnect_attempts`: Specify how many times the client should retry to send queries. Defaults to `0`. Makes sure to read the [reconnection section](#reconnection) before enabling it.
+- `circuit_breaker`: A Hash with circuit breaker configuration. Defaults to `nil`. See the [circuit breaker section](#circuit-breaker) for details.
 - `protocol:` The version of the RESP protocol to use. Default to `3`.
 - `custom`: A user owned value ignored by `redis-client` but available as `Config#custom`. This can be used to hold middleware configurations and other user specific metadatas.
 
@@ -426,24 +427,62 @@ It can be set as a number of retries:
 redis_config = RedisClient.config(reconnect_attempts: 1)
 ```
 
-Or as a list of sleep durations for implementing exponential backoff:
-
-```ruby
-redis_config = RedisClient.config(reconnect_attempts: [0, 0.05, 0.1])
-```
-
 **Important Note**: Retrying may cause commands to be issued more than once to the server, so in the case of
 non-idempotent commands such as `LPUSH` or `INCR`, it may cause consistency issues.
 
 To selectively disable automatic retries, you can use the `#call_once` method:
 
 ```ruby
-redis_config = RedisClient.config(reconnect_attempts: [0, 0.05, 0.1])
+redis_config = RedisClient.config(reconnect_attempts: 3)
 redis = redis_config.new_client
 redis.call("GET", "counter") # Will be retried up to 3 times.
 redis.call_once("INCR", "counter") # Won't be retried.
 ```
 
+### Exponential backoff
+
+Alternatively, `reconnect_attempts` accepts a list of sleep durations for implementing exponential backoff:
+
+```ruby
+redis_config = RedisClient.config(reconnect_attempts: [0, 0.05, 0.1])
+```
+
+This configuration is generally used when the Redis server is expected to failover or recover relatively quickly and
+that it's not really possibe to continue without issuing the command.
+
+When the Redis server is used as an ephemeral cache, circuit breakers are generally prefered.
+
+### Circuit Breaker
+
+When Redis is used as a cache and a connection error happens, you may not want to retry as it might take
+longer than to recompute the value. Instead it's likely preferable to mark the server as unavailable and let it
+recover for a while.
+
+[Circuit breakers are a pattern that does exactly that](https://en.wikipedia.org/wiki/Circuit_breaker_design_pattern).
+
+Configuation options:
+
+  - `error_threshold`. The amount of errors to encounter within `error_threshold_timeout` amount of time before opening the circuit, that is to start rejecting requests instantly.
+  - `error_threshold_timeout`. The amount of time in seconds that `error_threshold` errors must occur to open the circuit. Defaults to `error_timeout` seconds if not set.
+  - `error_timeout`. The amount of time in seconds until trying to query the resource again.
+  - `success_threshold`. The amount of successes on the circuit until closing it again, that is to start accepting all requests to the circuit.
+
+```ruby
+RedisClient.config(
+  circuit_breaker: {
+    # Stop querying the server after 3 errors happened in a 2 seconds window
+    error_threshold: 3,
+    error_threshold_timeout: 2,
+
+    # Try querying again after 1 second
+    error_timeout: 1,
+
+    # Stay in half-open state until 3 queries succeeded.
+    success_threshold: 3,
+  }
+)
+```
+
 ### Drivers
 
 `redis-client` ships with a pure Ruby socket implementation.

data/lib/redis_client/circuit_breaker.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+class RedisClient
+  class CircuitBreaker
+    module Middleware
+      def connect(config)
+        config.circuit_breaker.protect { super }
+      end
+
+      def call(_command, config)
+        config.circuit_breaker.protect { super }
+      end
+
+      def call_pipelined(_commands, config)
+        config.circuit_breaker.protect { super }
+      end
+    end
+
+    OpenCircuitError = Class.new(CannotConnectError)
+
+    attr_reader :error_timeout, :error_threshold, :error_threshold_timeout, :success_threshold
+
+    def initialize(error_threshold:, error_timeout:, error_threshold_timeout: error_timeout, success_threshold: 0)
+      @error_threshold = Integer(error_threshold)
+      @error_threshold_timeout = Float(error_threshold_timeout)
+      @error_timeout = Float(error_timeout)
+      @success_threshold = Integer(success_threshold)
+      @errors = []
+      @successes = 0
+      @state = :closed
+      @lock = Mutex.new
+    end
+
+    def protect
+      if @state == :open
+        refresh_state
+      end
+
+      case @state
+      when :open
+        raise OpenCircuitError, "Too many connection errors happened recently"
+      when :closed
+        begin
+          yield
+        rescue ConnectionError
+          record_error
+          raise
+        end
+      when :half_open
+        begin
+          result = yield
+          record_success
+          result
+        rescue ConnectionError
+          record_error
+          raise
+        end
+      else
+        raise "[BUG] RedisClient::CircuitBreaker unexpected @state (#{@state.inspect}})"
+      end
+    end
+
+    private
+
+    def refresh_state
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @lock.synchronize do
+        if @errors.last < (now - @error_timeout)
+          if @success_threshold > 0
+            @state = :half_open
+            @successes = 0
+          else
+            @errors.clear
+            @state = :closed
+          end
+        end
+      end
+    end
+
+    def record_error
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      expiry = now - @error_timeout
+      @lock.synchronize do
+        if @state == :closed
+          @errors.reject! { |t| t < expiry }
+        end
+        @errors << now
+        @successes = 0
+        if @state == :half_open || (@state == :closed && @errors.size >= @error_threshold)
+          @state = :open
+        end
+      end
+    end
+
+    def record_success
+      return unless @state == :half_open
+
+      @lock.synchronize do
+        return unless @state == :half_open
+
+        @successes += 1
+        if @successes >= @success_threshold
+          @state = :closed
+        end
+      end
+    end
+  end
+end

data/lib/redis_client/config.rb

@@ -14,7 +14,7 @@ class RedisClient
     module Common
       attr_reader :db, :password, :id, :ssl, :ssl_params, :command_builder, :inherit_socket,
         :connect_timeout, :read_timeout, :write_timeout, :driver, :connection_prelude, :protocol,
-        :middlewares_stack, :custom
+        :middlewares_stack, :custom, :circuit_breaker
 
       alias_method :ssl?, :ssl
 
@@ -36,7 +36,8 @@ class RedisClient
         command_builder: CommandBuilder,
         inherit_socket: false,
         reconnect_attempts: false,
-        middlewares: false
+        middlewares: false,
+        circuit_breaker: nil
       )
         @username = username
         @password = password
@@ -66,6 +67,11 @@ class RedisClient
         @reconnect_attempts = reconnect_attempts
         @connection_prelude = build_connection_prelude
 
+        circuit_breaker = CircuitBreaker.new(**circuit_breaker) if circuit_breaker.is_a?(Hash)
+        if @circuit_breaker = circuit_breaker
+          middlewares = [CircuitBreaker::Middleware] + (middlewares || [])
+        end
+
         middlewares_stack = Middlewares
         if middlewares && !middlewares.empty?
           middlewares_stack = Class.new(Middlewares)
@@ -155,6 +161,10 @@ class RedisClient
     )
       if url
         uri = URI(url)
+        unless uri.scheme == "redis" || uri.scheme == "rediss"
+          raise ArgumentError, "Invalid URL: #{url.inspect}"
+        end
+
         kwargs[:ssl] = uri.scheme == "rediss" unless kwargs.key?(:ssl)
 
         kwargs[:username] ||= uri.user if uri.password && !uri.user.empty?

data/lib/redis_client/connection_mixin.rb

@@ -17,7 +17,7 @@ class RedisClient
       write(command)
       result = read(timeout)
       @pending_reads -= 1
-      if result.is_a?(CommandError)
+      if result.is_a?(Error)
         result._set_command(command)
         raise result
       else
@@ -37,7 +37,7 @@ class RedisClient
         timeout = timeouts && timeouts[index]
         result = read(timeout)
         @pending_reads -= 1
-        if result.is_a?(CommandError)
+        if result.is_a?(Error)
           result._set_command(commands[index])
           exception ||= result
         end

data/lib/redis_client/ruby_connection/buffered_io.rb

@@ -142,7 +142,7 @@ class RedisClient
           when :wait_writable
             @io.to_io.wait_writable(@write_timeout) or raise WriteTimeoutError
           when nil
-            raise Errno::ECONNRESET
+            raise EOFError
           else
             raise "Unexpected `read_nonblock` return: #{bytes.inspect}"
           end

data/lib/redis_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class RedisClient
-  VERSION = "0.11.1"
+  VERSION = "0.12.0"
 end

data/lib/redis_client.rb

@@ -62,7 +62,7 @@ class RedisClient
       write_timeout: config.write_timeout
     )
       @config = config
-      @id = id
+      @id = id&.to_s
       @connect_timeout = connect_timeout
       @read_timeout = read_timeout
       @write_timeout = write_timeout
@@ -90,9 +90,17 @@ class RedisClient
   WriteTimeoutError = Class.new(TimeoutError)
   CheckoutTimeoutError = Class.new(TimeoutError)
 
-  class CommandError < Error
+  module HasCommand
     attr_reader :command
 
+    def _set_command(command)
+      @command = command
+    end
+  end
+
+  class CommandError < Error
+    include HasCommand
+
     class << self
       def parse(error_message)
         code = if error_message.start_with?("ERR Error running script")
@@ -107,22 +115,24 @@ class RedisClient
         klass.new(error_message)
       end
     end
-
-    def _set_command(command)
-      @command = command
-    end
   end
 
   AuthenticationError = Class.new(CommandError)
   PermissionError = Class.new(CommandError)
-  ReadOnlyError = Class.new(CommandError)
   WrongTypeError = Class.new(CommandError)
   OutOfMemoryError = Class.new(CommandError)
 
+  ReadOnlyError = Class.new(ConnectionError)
+  ReadOnlyError.include(HasCommand)
+
+  MasterDownError = Class.new(ConnectionError)
+  MasterDownError.include(HasCommand)
+
   CommandError::ERRORS = {
     "WRONGPASS" => AuthenticationError,
     "NOPERM" => PermissionError,
     "READONLY" => ReadOnlyError,
+    "MASTERDOWN" => MasterDownError,
     "WRONGTYPE" => WrongTypeError,
     "OOM" => OutOfMemoryError,
   }.freeze
@@ -662,7 +672,7 @@ class RedisClient
     prelude = config.connection_prelude.dup
 
     if id
-      prelude << ["CLIENT", "SETNAME", id.to_s]
+      prelude << ["CLIENT", "SETNAME", id]
     end
 
     # The connection prelude is deliberately not sent to Middlewares
@@ -681,14 +691,14 @@ class RedisClient
     end
 
     connection
-  rescue FailoverError
+  rescue FailoverError, CannotConnectError
     raise
   rescue ConnectionError => error
     raise CannotConnectError, error.message, error.backtrace
   rescue CommandError => error
-    if error.message.include?("ERR unknown command `HELLO`")
+    if error.message.match?(/ERR unknown command ['`]HELLO['`]/)
       raise UnsupportedServer,
-        "Your Redis server version is too old. redis-client requires Redis 6+. (#{config.server_url})"
+        "redis-client requires Redis 6+ with HELLO command available (#{config.server_url})"
     else
       raise
     end
@@ -696,5 +706,6 @@ class RedisClient
 end
 
 require "redis_client/pooled"
+require "redis_client/circuit_breaker"
 
 RedisClient.default_driver

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: redis-client
 version: !ruby/object:Gem::Version
-  version: 0.11.1
+  version: 0.12.0
 platform: ruby
 authors:
 - Jean Boussier
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-04 00:00:00.000000000 Z
+date: 2023-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -39,6 +39,7 @@ files:
 - Rakefile
 - lib/redis-client.rb
 - lib/redis_client.rb
+- lib/redis_client/circuit_breaker.rb
 - lib/redis_client/command_builder.rb
 - lib/redis_client/config.rb
 - lib/redis_client/connection_mixin.rb
@@ -74,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: Simple low-level client for Redis 6+