redis 4.2.5 → 5.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 862e8133262fead707e4ca317b29d0e35425e3a7861ea1a52033bc91ba61bf6d
-  data.tar.gz: 5b2b32250d783fe58b0af54cc386f2568241644a0badc0b7247bb29b1ac94a93
+  metadata.gz: 1dde5fad5c2d0c73c390528b059ab36b185dd61a2c32e4f9be9512bb4516977b
+  data.tar.gz: cda581f3f9b0b4238f15b4b3ddf7566fb6ca02b60ee7951b903e8e195bd395cd
 SHA512:
-  metadata.gz: 2aab289f4f22b2f3a804ca7b0da4cf95e352a8d246611490d8d803edebbbc7e7c299355cd0b90e6f3ac8bc0d11e9bf3792a328c95847d32e1d984729afe66ed2
-  data.tar.gz: d9ec8ba4d314d099e909cdddf6dfb4c3c14b853b46f45c4909ac3ba10fb1880bd9a7b0465257fa91f9a4ea6c9f82723c16c177810ac15c89fab3790d7af31ad0
+  metadata.gz: 122fd647eda1a251370f32dfefb4711411b0ff9b0e9185cdb871c389c99d5b80a80d554a6b7787ed10e515291b1ebed6dceb2364f8c28021ce6fdedd3297d08e
+  data.tar.gz: 13aadc0709a9fc7779ad7ad1f64bb3d3b26da57eb44dd2ebd629d5ed2d34ea17c782337ce92e1047e7ae736df8b90eafb2e935e460f1b1af979621942dad772f

data/CHANGELOG.md

@@ -1,5 +1,172 @@
 # Unreleased
 
+# 5.0.7
+
+- Fix compatibility with `redis-client 0.15.0` when using Redis Sentinel. Fix #1209.
+
+# 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
+
+- Default client timeout decreased from 5 seconds to 1 second.
+- 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.1
+
+* Automatically reconnect after fork regardless of `reconnect_attempts`
+
+# 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`.
+* Deprecate calling commands on `Redis` inside `Redis#pipelined`. See #1059.
+  ```ruby
+  redis.pipelined do
+    redis.get("key")
+  end
+  ```
+
+  should be replaced by:
+
+  ```ruby
+  redis.pipelined do |pipeline|
+    pipeline.get("key")
+  end
+  ```
+* Deprecate calling commands on `Redis` inside `Redis#multi`. See #1059.
+  ```ruby
+  redis.multi do
+    redis.get("key")
+  end
+  ```
+
+  should be replaced by:
+
+  ```ruby
+  redis.multi do |transaction|
+    transaction.get("key")
+  end
+  ```
+* Deprecate `Redis#queue` and `Redis#commit`. See #1059.
+
+* Fix `zpopmax` and `zpopmin` when called inside a pipeline. See #1055.
+* `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 = 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.
+  It is recommended to set `Redis.raise_deprecations = true` in development and test environments.
+* Add new options to ZRANGE. See #1053.
+* Add ZRANGESTORE command. See #1053.
+* Add SCAN support for `Redis::Cluster`. See #1049.
+* Add COPY command. See #1053. See #1048.
+* Add ZDIFFSTORE command. See #1046.
+* Add ZDIFF command. See #1044.
+* Add ZUNION command. See #1042.
+* Add HRANDFIELD command. See #1040.
+
+# 4.5.1
+
+* Restore the accidential auth behavior of redis-rb 4.3.0 with a warning. If provided with the `default` user's password, but a wrong username,
+  redis-rb will first try to connect as the provided user, but then will fallback to connect as the `default` user with the provided password.
+  This behavior is deprecated and will be removed in Redis 4.6.0. Fix #1038.
+
+# 4.5.0
+
+* Handle parts of the command using incompatible encodings. See #1037.
+* Add GET option to SET command. See #1036.
+* Add ZRANDMEMBER command. See #1035.
+* Add LMOVE/BLMOVE commands. See #1034.
+* Add ZMSCORE command. See #1032.
+* Add LT/GT options to ZADD. See #1033.
+* Add SMISMEMBER command. See #1031.
+* Add EXAT/PXAT options to SET. See #1028.
+* Add GETDEL/GETEX commands. See #1024.
+* `Redis#exists` now returns an Integer by default, as warned since 4.2.0. The old behavior can be restored with `Redis.exists_returns_integer = false`.
+* Fix Redis < 6 detection during connect. See #1025.
+* Fix fetching command details in Redis cluster when the first node is unhealthy. See #1026.
+
+# 4.4.0
+
+* Redis cluster: fix cross-slot validation in pipelines. Fix ##1019.
+* Add support for `XAUTOCLAIM`. See #1018.
+* Properly issue `READONLY` when reconnecting to replicas. Fix #1017.
+* Make `del` a noop if passed an empty list of keys. See #998.
+* Add support for `ZINTER`. See #995.
+
+# 4.3.1
+
+* Fix password authentication against redis server 5 and older.
+
+# 4.3.0
+
+* Add the TYPE argument to scan and scan_each. See #985.
+* Support AUTH command for ACL. See #967.
+
 # 4.2.5
 
 * Optimize the ruby connector write buffering. See #964.

data/README.md

@@ -1,7 +1,6 @@
-# redis-rb [![Build Status][travis-image]][travis-link] [![Inline docs][inchpages-image]][inchpages-link] ![](https://github.com/redis/redis-rb/workflows/Test/badge.svg?branch=master)
+# redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][rdoc-master-image]][rdoc-master-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
@@ -54,6 +49,12 @@ To connect to a password protected Redis instance, use:
 redis = Redis.new(password: "mysecret")
 ```
 
+To connect a Redis instance using [ACL](https://redis.io/topics/acl), use:
+
+```ruby
+redis = Redis.new(username: 'myname', password: 'mysecret')
+```
+
 The Redis class exports methods that are named identical to the commands
 they execute. The arguments these methods accept are often identical to
 the arguments specified on the [Redis website][redis-commands]. For
@@ -70,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
@@ -82,7 +103,7 @@ To connect using Sentinel, use:
 SENTINELS = [{ host: "127.0.0.1", port: 26380 },
              { host: "127.0.0.1", port: 26381 }]
 
-redis = Redis.new(url: "redis://mymaster", sentinels: SENTINELS, role: :master)
+redis = Redis.new(name: "mymaster", sentinels: SENTINELS, role: :master)
 ```
 
 * The master name identifies a group of Redis instances composed of a master
@@ -105,64 +126,18 @@ 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).
+Also the name can be passed as an url:
 
 ```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]
+redis = Redis.new(name: "redis://mymaster", sentinels: SENTINELS, role: :master)
 ```
 
-* 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
+## Cluster support
 
-JSON.parse(redis.get("foo"))
-# => [1, 2, 3]
-```
+[Clustering](https://redis.io/topics/cluster-spec). is supported via the [`redis-clustering` gem](cluster/).
 
 ## Pipelining
 
@@ -178,13 +153,24 @@ commands to Redis and gathers their replies. These replies are returned
 by the `#pipelined` method.
 
 ```ruby
-redis.pipelined do
-  redis.set "foo", "bar"
-  redis.incr "baz"
+redis.pipelined do |pipeline|
+  pipeline.set "foo", "bar"
+  pipeline.incr "baz"
 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
@@ -194,9 +180,9 @@ the regular pipeline, the replies to the commands are returned by the
 `#multi` method.
 
 ```ruby
-redis.multi do
-  redis.set "foo", "bar"
-  redis.incr "baz"
+redis.multi do |transaction|
+  transaction.set "foo", "bar"
+  transaction.incr "baz"
 end
 # => ["OK", 1]
 ```
@@ -204,21 +190,22 @@ end
 ### Futures
 
 Replies to commands in a pipeline can be accessed via the *futures* they
-emit (since redis-rb 3.0). All calls inside a pipeline block 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
-redis.pipelined do
-  @set = redis.set "foo", "bar"
-  @incr = redis.incr "baz"
+set = incr = nil
+redis.pipelined do |pipeline|
+  set = pipeline.set "foo", "bar"
+  incr = pipeline.incr "baz"
 end
 
-@set.value
+set.value
 # => "OK"
 
-@incr.value
+incr.value
 # => 1
 ```
 
@@ -230,7 +217,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>
 
@@ -277,55 +264,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).
@@ -360,13 +329,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
 
@@ -380,17 +343,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
@@ -400,47 +355,33 @@ 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
 
 This library is tested against recent Ruby and Redis versions.
-Check [Travis][travis-link] for the exact versions supported.
+Check [Github Actions][gh-actions-link] for the exact versions supported.
 
 ## See Also
 
@@ -459,12 +400,11 @@ client and evangelized Redis in Rubyland. Thank you, Ezra.
 requests.
 
 
-[inchpages-image]: https://inch-ci.org/github/redis/redis-rb.svg
-[inchpages-link]:  https://inch-ci.org/github/redis/redis-rb
-[redis-commands]:  https://redis.io/commands
-[redis-home]:      https://redis.io
-[redis-url]:       http://www.iana.org/assignments/uri-schemes/prov/redis
-[travis-home]:     https://travis-ci.org/
-[travis-image]:    https://secure.travis-ci.org/redis/redis-rb.svg?branch=master
-[travis-link]:     https://travis-ci.org/redis/redis-rb
-[rubydoc]:         http://www.rubydoc.info/gems/redis
+[rdoc-master-image]: https://img.shields.io/badge/docs-rdoc.info-blue.svg
+[rdoc-master-link]:  https://rubydoc.info/github/redis/redis-rb
+[redis-commands]:    https://redis.io/commands
+[redis-home]:        https://redis.io
+[redis-url]:         https://www.iana.org/assignments/uri-schemes/prov/redis
+[gh-actions-image]:  https://github.com/redis/redis-rb/workflows/Test/badge.svg
+[gh-actions-link]:   https://github.com/redis/redis-rb/actions
+[rubydoc]:           https://rubydoc.info/gems/redis