redis 4.6.0 → 5.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e99f4e628112a227719d2000dc5b081893273cfbd51ae25bf00a8f6b6594061
-  data.tar.gz: 42a8e0cf75aebbc14cdf680b4bc1f7bbdec9e20b53f150c6443c01126960a959
+  metadata.gz: 7b000349da8b2f7ae8ed14909175306d2c719a9873bf1dabe05c4719ae96d0da
+  data.tar.gz: fdcda2f50f9d33265f7ba24d3f29a2e078fabe5240e1eaf01efae51e0b83eb0b
 SHA512:
-  metadata.gz: 8bc57fe306c601f27d32df4940d5632e9e7d75529f6ac5d42732b21fe04452a4a1ab89567492c6fb7249ef4d69ebb2c0b7c985e18b0ef4f9ee6fb816c31bcbda
-  data.tar.gz: 42b2f8c584d6f96d0fc783d0b36af0fd9415d1dbd43ad8fe7a980688e52fbdb51645a07960d9cb3faacf6696c460cf38a013e290d0b58d4bbbb07626f18f15c7
+  metadata.gz: 990972ebefe548f952cbf630708298f52c1856fa5a142a341f2548bd9173f03f0106d6b745c7e39cc5baa9f084d5fea5e4c0bf42cf1d42df94e404f3558d7816
+  data.tar.gz: e52615e0d5b7ca9d554ffc540fdfec524d2aed74ac1c7fc3c727d3096504aa81ff43a85b9e2ce7b21da87edf21ca5f92197171ff1b1c62fa85c7551839e9df83

data/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Unreleased
 
+# 5.0.6
+
+- Wait for an extra `config.read_timeout` in blocking commands rather than an arbitrary 100ms. See #1175.
+- Treat ReadOnlyError as ConnectionError. See #1168.
+
+# 5.0.5
+
+- Fix automatic disconnection when the process was forked. See #1157.
+
+# 5.0.4
+
+- Cast `ttl` argument to integer in `expire`, `setex` and a few others.
+
+# 5.0.3
+
+- Add `OutOfMemoryError` as a subclass of `CommandError`
+
+# 5.0.2
+
+- Fix `Redis#close` to properly reset the fork protection check.
+
+# 5.0.1
+
+- Added a fake `Redis::Connections.drivers` method to be compatible with older sidekiq versions.
+
+# 5.0.0
+
+- Eagerly and strictly cast Integer and Float parameters.
+- Allow to call `subscribe`, `unsubscribe`, `psubscribe` and `punsubscribe` from a subscribed client. See #1131.
+- Use `MD5` for hashing server nodes in `Redis::Distributed`. This should improve keys distribution among servers. See #1089.
+- Changed `sadd` and `srem` to now always return an Integer.
+- Added `sadd?` and `srem?` which always return a Boolean.
+- Added support for `IDLE` paramter in `xpending`.
+- Cluster support has been moved to a `redis-clustering` companion gem.
+- `select` no longer record the current database. If the client has to reconnect after `select` was used, it will reconnect to the original database.
+- Better support Float timeout in blocking commands. See #977.
+- `Redis.new` will now raise an error if provided unknown options.
+- Removed positional timeout in blocking commands (`BLPOP`, etc). Timeout now must be passed as an option: `r.blpop("key", timeout: 2.5)`
+- Removed `logger` option.
+- Removed `reconnect_delay_max` and `reconnect_delay`, you can pass precise sleep durations to `reconnect_attempts` instead.
+- Require Ruby 2.5+.
+- Removed the deprecated `queue` and `commit` methods. Use `pipelined` instead.
+- Removed the deprecated `Redis::Future#==`.
+- Removed the deprecated `pipelined` and `multi` signature. Commands now MUST be called on the block argument, not the original redis instance.
+- Removed `Redis.current`. You shouldn't assume there is a single global Redis connection, use a connection pool instead,
+  and libaries using Redis should accept a Redis instance (or connection pool) as a config. E.g. `MyLibrary.redis = Redis.new(...)`.
+- Removed the `synchrony` driver.
+- Removed `Redis.exists_returns_integer`, it's now always enabled.
+
+# 4.8.0
+
+* Introduce `sadd?` and `srem?` as boolean returning versions of `sadd` and `srem`.
+* Deprecate `sadd` and `srem` returning a boolean when called with a single argument.
+  To enable the redis 5.0 behavior you can set `Redis.sadd_returns_boolean = false`.
+* Deprecate passing `timeout` as a positional argument in blocking commands (`brpop`, `blop`, etc).
+
+# 4.7.1
+
+* Gracefully handle OpenSSL 3.0 EOF Errors (`OpenSSL::SSL::SSLError: SSL_read: unexpected eof while reading`). See #1106
+  This happens frequently on heroku-22.
+
+# 4.7.0
+
+* Support single endpoint architecture with SSL/TLS in cluster mode. See #1086.
+* `zrem` and `zadd` act as noop when provided an empty list of keys. See #1097.
+* Support IPv6 URLs.
+* Add `Redis#with` for better compatibility with `connection_pool` usage.
+* Fix the block form of `multi` called inside `pipelined`. Previously the `MUTLI/EXEC` wouldn't be sent. See #1073.
+
 # 4.6.0
 
 * Deprecate `Redis.current`.
@@ -37,7 +106,7 @@
 * `Redis#synchronize` is now private like it should always have been.
 
 * Add `Redis.silence_deprecations=` to turn off deprecation warnings.
-  If you don't wish to see warnings yet, you can set `Redis.silence_deprecations = false`.
+  If you don't wish to see warnings yet, you can set `Redis.silence_deprecations = true`.
   It is however heavily recommended to fix them instead when possible.
 * Add `Redis.raise_deprecations=` to turn deprecation warnings into errors.
   This makes it easier to identitify the source of deprecated APIs usage.

data/README.md

@@ -1,7 +1,6 @@
 # redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][inchpages-image]][inchpages-link]
 
-A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still
-providing an idiomatic interface.
+A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still providing an idiomatic interface.
 
 See [RubyDoc.info][rubydoc] for the API docs of the latest published gem.
 
@@ -38,10 +37,6 @@ redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15")
 The client expects passwords with special chracters to be URL-encoded (i.e.
 `CGI.escape(password)`).
 
-By default, the client will try to read the `REDIS_URL` environment variable
-and use that as URL to connect to. The above statement is therefore equivalent
-to setting this environment variable and calling `Redis.new` without arguments.
-
 To connect to Redis listening on a Unix socket, try:
 
 ```ruby
@@ -76,6 +71,26 @@ redis.get("mykey")
 All commands, their arguments, and return values are documented and
 available on [RubyDoc.info][rubydoc].
 
+## Connection Pooling and Thread safety
+
+The client does not provide connection pooling. Each `Redis` instance
+has one and only one connection to the server, and use of this connection
+is protected by a mutex.
+
+As such it is heavilly recommended to use the [`connection_pool` gem](https://github.com/mperham/connection_pool), e.g.:
+
+```ruby
+module MyApp
+  def self.redis
+    @redis ||= ConnectionPool::Wrapper.new do
+      Redis.new(url: ENV["REDIS_URL"])
+    end
+  end
+end
+
+MyApp.redis.incr("some-counter")
+```
+
 ## Sentinel support
 
 The client is able to perform automatic failover by using [Redis
@@ -111,64 +126,12 @@ If you want to [authenticate](https://redis.io/topics/sentinel#configuring-senti
 SENTINELS = [{ host: '127.0.0.1', port: 26380, password: 'mysecret' },
              { host: '127.0.0.1', port: 26381, password: 'mysecret' }]
 
-redis = Redis.new(host: 'mymaster', sentinels: SENTINELS, role: :master)
+redis = Redis.new(name: 'mymaster', sentinels: SENTINELS, role: :master)
 ```
 
 ## Cluster support
 
-`redis-rb` supports [clustering](https://redis.io/topics/cluster-spec).
-
-```ruby
-# Nodes can be passed to the client as an array of connection URLs.
-nodes = (7000..7005).map { |port| "redis://127.0.0.1:#{port}" }
-redis = Redis.new(cluster: nodes)
-
-# You can also specify the options as a Hash. The options are the same as for a single server connection.
-(7000..7005).map { |port| { host: '127.0.0.1', port: port } }
-```
-
-You can also specify only a subset of the nodes, and the client will discover the missing ones using the [CLUSTER NODES](https://redis.io/commands/cluster-nodes) command.
-
-```ruby
-Redis.new(cluster: %w[redis://127.0.0.1:7000])
-```
-
-If you want [the connection to be able to read from any replica](https://redis.io/commands/readonly), you must pass the `replica: true`. Note that this connection won't be usable to write keys.
-
-```ruby
-Redis.new(cluster: nodes, replica: true)
-```
-
-The calling code is responsible for [avoiding cross slot commands](https://redis.io/topics/cluster-spec#keys-distribution-model).
-
-```ruby
-redis = Redis.new(cluster: %w[redis://127.0.0.1:7000])
-
-redis.mget('key1', 'key2')
-#=> Redis::CommandError (CROSSSLOT Keys in request don't hash to the same slot)
-
-redis.mget('{key}1', '{key}2')
-#=> [nil, nil]
-```
-
-* The client automatically reconnects after a failover occurred, but the caller is responsible for handling errors while it is happening.
-* The client support permanent node failures, and will reroute requests to promoted slaves.
-* The client supports `MOVED` and `ASK` redirections transparently.
-
-## Storing objects
-
-Redis "string" types can be used to store serialized Ruby objects, for
-example with JSON:
-
-```ruby
-require "json"
-
-redis.set "foo", [1, 2, 3].to_json
-# => OK
-
-JSON.parse(redis.get("foo"))
-# => [1, 2, 3]
-```
+[Clustering](https://redis.io/topics/cluster-spec). is supported via the [`redis-clustering` gem](cluster/).
 
 ## Pipelining
 
@@ -191,6 +154,17 @@ end
 # => ["OK", 1]
 ```
 
+Commands must be called on the yielded objects. If you call methods
+on the original client objects from inside a pipeline, they will be sent immediately:
+
+```ruby
+redis.pipelined do |pipeline|
+  pipeline.set "foo", "bar"
+  redis.incr "baz" # => 1
+end
+# => ["OK"]
+```
+
 ### Executing commands atomically
 
 You can use `MULTI/EXEC` to run a number of commands in an atomic
@@ -210,21 +184,22 @@ end
 ### Futures
 
 Replies to commands in a pipeline can be accessed via the *futures* they
-emit (since redis-rb 3.0). All calls on the pipeline object return a
+emit. All calls on the pipeline object return a
 `Future` object, which responds to the `#value` method. When the
 pipeline has successfully executed, all futures are assigned their
 respective replies and can be used.
 
 ```ruby
+set = incr = nil
 redis.pipelined do |pipeline|
-  @set = pipeline.set "foo", "bar"
-  @incr = pipeline.incr "baz"
+  set = pipeline.set "foo", "bar"
+  incr = pipeline.incr "baz"
 end
 
-@set.value
+set.value
 # => "OK"
 
-@incr.value
+incr.value
 # => 1
 ```
 
@@ -236,7 +211,7 @@ it can't connect to the server a `Redis::CannotConnectError` error will be raise
 ```ruby
 begin
   redis.ping
-rescue StandardError => e
+rescue Redis::BaseError => e
   e.inspect
 # => #<Redis::CannotConnectError: Timed out connecting to Redis on 10.0.1.1:6380>
 
@@ -283,55 +258,37 @@ If no message is received after 5 seconds, the client will unsubscribe.
 
 ## Reconnections
 
-The client allows you to configure how many `reconnect_attempts` it should
-complete before declaring a connection as failed. Furthermore, you may want
-to control the maximum duration between reconnection attempts with
-`reconnect_delay` and `reconnect_delay_max`.
+**By default**, this gem will only **retry a connection once** and then fail, but
+the client allows you to configure how many `reconnect_attempts` it should
+complete before declaring a connection as failed.
 
 ```ruby
-Redis.new(
-  :reconnect_attempts => 10,
-  :reconnect_delay => 1.5,
-  :reconnect_delay_max => 10.0,
-)
+Redis.new(reconnect_attempts: 0)
+Redis.new(reconnect_attempts: 3)
 ```
 
-The delay values are specified in seconds. With the above configuration, the
-client would attempt 10 reconnections, exponentially increasing the duration
-between each attempt but it never waits longer than `reconnect_delay_max`.
-
-This is the retry algorithm:
+If you wish to wait between reconnection attempts, you can instead pass a list
+of durations:
 
 ```ruby
-attempt_wait_time = [(reconnect_delay * 2**(attempt-1)), reconnect_delay_max].min
+Redis.new(reconnect_attempts: [
+  0, # retry immediately
+  0.25, # retry a second time after 250ms
+  1, # retry a third and final time after another 1s
+])
 ```
 
-**By default**, this gem will only **retry a connection once** and then fail, but with the
-above configuration the reconnection attempt would look like this:
-
-#|Attempt wait time|Total wait time
-:-:|:-:|:-:
-1|1.5s|1.5s
-2|3.0s|4.5s
-3|6.0s|10.5s
-4|10.0s|20.5s
-5|10.0s|30.5s
-6|10.0s|40.5s
-7|10.0s|50.5s
-8|10.0s|60.5s
-9|10.0s|70.5s
-10|10.0s|80.5s
-
-So if the reconnection attempt #10 succeeds 70 seconds have elapsed trying
-to reconnect, this is likely fine in long-running background processes, but if
-you use Redis to drive your website you might want to have a lower
-`reconnect_delay_max` or have less `reconnect_attempts`.
+If you wish to disable reconnection only for some commands, you can use
+`disable_reconnection`:
 
-## SSL/TLS Support
+```ruby
+redis.get("some-key") # this may be retried
+redis.disable_reconnection do
+  redis.incr("some-counter") # this won't be retried.
+end
+```
 
-This library supports natively terminating client side SSL/TLS connections
-when talking to Redis via a server-side proxy such as [stunnel], [hitch],
-or [ghostunnel].
+## SSL/TLS Support
 
 To enable SSL support, pass the `:ssl => true` option when configuring the
 Redis client, or pass in `:url => "rediss://..."` (like HTTPS for Redis).
@@ -366,13 +323,7 @@ redis = Redis.new(
 )
 ```
 
-[stunnel]: https://www.stunnel.org/
-[hitch]: https://hitch-tls.org/
-[ghostunnel]: https://github.com/square/ghostunnel
-[OpenSSL::SSL::SSLContext documentation]: http://ruby-doc.org/stdlib-2.3.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html
-
-*NOTE:* SSL is only supported by the default "Ruby" driver
-
+[OpenSSL::SSL::SSLContext documentation]: http://ruby-doc.org/stdlib-2.5.0/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html
 
 ## Expert-Mode Options
 
@@ -386,17 +337,9 @@ redis = Redis.new(
    Improper use of `inherit_socket` will result in corrupted and/or incorrect
    responses.
 
-## Alternate drivers
+## hiredis binding
 
 By default, redis-rb uses Ruby's socket library to talk with Redis.
-To use an alternative connection driver it should be specified as option
-when instantiating the client object. These instructions are only valid
-for **redis-rb 3.0**. For instructions on how to use alternate drivers from
-**redis-rb 2.2**, please refer to an [older README][readme-2.2.2].
-
-[readme-2.2.2]: https://github.com/redis/redis-rb/blob/v2.2.2/README.md
-
-### hiredis
 
 The hiredis driver uses the connection facility of hiredis-rb. In turn,
 hiredis-rb is a binding to the official hiredis client library. It
@@ -406,41 +349,27 @@ extension, JRuby is not supported (by default).
 It is best to use hiredis when you have large replies (for example:
 `LRANGE`, `SMEMBERS`, `ZRANGE`, etc.) and/or use big pipelines.
 
-In your Gemfile, include hiredis:
+In your Gemfile, include `hiredis-client`:
 
 ```ruby
-gem "redis", "~> 3.0.1"
-gem "hiredis", "~> 0.4.5"
+gem "redis"
+gem "hiredis-client"
 ```
 
-When instantiating the client object, specify hiredis:
+If your application doesn't call `Bundler.require`, you may have
+to require it explictly:
 
 ```ruby
-redis = Redis.new(:driver => :hiredis)
-```
-
-### synchrony
-
-The synchrony driver adds support for [em-synchrony][em-synchrony].
-This makes redis-rb work with EventMachine's asynchronous I/O, while not
-changing the exposed API. The hiredis gem needs to be available as
-well, because the synchrony driver uses hiredis for parsing the Redis
-protocol.
-
-[em-synchrony]: https://github.com/igrigorik/em-synchrony
+require "hiredis-client"
+````
 
-In your Gemfile, include em-synchrony and hiredis:
-
-```ruby
-gem "redis", "~> 3.0.1"
-gem "hiredis", "~> 0.4.5"
-gem "em-synchrony"
-```
+This makes the hiredis driver the default.
 
-When instantiating the client object, specify synchrony:
+If you want to be certain hiredis is being used, when instantiating
+the client object, specify hiredis:
 
 ```ruby
-redis = Redis.new(:driver => :synchrony)
+redis = Redis.new(driver: :hiredis)
 ```
 
 ## Testing