redis 3.2.2 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 183e90b7d3961182b8b5b20b1295b6dd9d30df12
-  data.tar.gz: 60023071a61af0e34d85b0a999db0bc5877070ad
+SHA256:
+  metadata.gz: d5ff2ee4b6a6f2b087ac26bf96a3c1769cf42f70ea90008361157f7ef04cdb14
+  data.tar.gz: f2c24654294c4fa81a5cff4ddb545bc59e6f85b64ee61273278cb1e286a4edb8
 SHA512:
-  metadata.gz: a1d93f8ee26f3dfecb10d223d178e4f78aa399d3bc8a78a4db479f0e6d89bd77c97d9e113b0138d102fbecf3d0a4452ce5f0da9412e069726c3b1fd7bb7bf7a4
-  data.tar.gz: 1a2077544497d0f2a1cd9035677dc1d514a9395b070b10f380e8fcc35cbbbbbae898e1b4ad3e7ff44e2fb96930330cb66b021ccaa726451c2c15276ff26b0011
+  metadata.gz: 0d88c6621659a178dca04d3ca62f25520f5f1a846b6300f93fb008966551fb4795a3e6c37810f99ea18f77a6292b955fa180ae3e06f8c90df7e6a3ca27087ae1
+  data.tar.gz: 1427cc268e867872388f214184d23a5c6062104fcb9d1e50d6026dd9daf6e51b9833866fee9fcf80c7a64e4de705295de8399d8e8ac22fa890bf358bd63ff707

data/CHANGELOG.md

@@ -1,16 +1,178 @@
-# 4.x (unreleased)
-
-## Planned breaking changes:
-* `Redis#client` will no longer expose the underlying `Redis::Client`;
-  it has not yet been determined how 4.0 will expose the underlying
-  functionality, but we will make every attempt to provide a final minor
-  release of 3.x that provides the new interfaces in order to facilitate
-  a smooth transition.
-
-* Ruby 1.8.7 (and the 1.8 modes of JRuby and Rubinius) will no longer be
-  supported; 1.8.x entered end-of-life in June of 2012 and stopped receiving
-  security updates in June of 2013; continuing to support it would prevent
-  the use of newer features of Ruby.
+# Unreleased
+
+# 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.
+
+# 4.2.4
+
+* Fix bytesize calculations in the ruby connector, and work on a copy of the buffer. Fix #961, #962.
+
+# 4.2.3
+
+* Use io/wait instead of IO.select in the ruby connector. See #960.
+* Use exception free non blocking IOs in the ruby connector. See #926.
+* Prevent corruption of the client when an interrupt happen during inside a pipeline block. See #945.
+
+# 4.2.2
+
+* Fix `WATCH` support for `Redis::Distributed`. See #941.
+* Fix handling of empty stream responses. See #905, #929.
+
+# 4.2.1
+
+* Fix `exists?` returning an actual boolean when called with multiple keys. See #918.
+* Setting `Redis.exists_returns_integer = false` disables warning message about new behaviour. See #920.
+
+# 4.2.0
+
+* Convert commands to accept keyword arguments rather than option hashes. This both help catching typos, and reduce needless allocations.
+* Deprecate the synchrony driver. It will be removed in 5.0 and hopefully maintained as a separate gem. See #915.
+* Make `Redis#exists` variadic, will return an Integer if called with multiple keys.
+* Add `Redis#exists?` to get a Boolean if any of the keys exists.
+* `Redis#exists` when called with a single key will warn that future versions will return an Integer.
+  Set `Redis.exists_returns_integer = true` to opt-in to the new behavior.
+* Support `keepttl` ooption in `set`. See #913.
+* Optimized initialization of Redis::Cluster. See #912.
+* Accept sentinel options even with string key. See #599.
+* Verify TLS connections by default. See #900.
+* Make `Redis#hset` variadic. It now returns an integer, not a boolean. See #910.
+
+# 4.1.4
+
+* Alias `Redis#disconnect` as `#close`. See #901.
+* Handle clusters with multiple slot ranges. See #894.
+* Fix password authentication to a redis cluster. See #889.
+* Handle recursive MOVED responses. See #882.
+* Increase buffer size in the ruby connector. See #880.
+* Fix thread safety of `Redis.queue`. See #878.
+* Deprecate `Redis::Future#==` as it's likely to be a mistake. See #876.
+* Support `KEEPTTL` option for SET command. See #913.
+
+# 4.1.3
+
+* Fix the client hanging forever when connecting with SSL to a non-SSL server. See #835.
+
+# 4.1.2
+
+* Fix several authentication problems with sentinel. See #850 and #856.
+* Explicitly drop Ruby 2.2 support.
+
+
+# 4.1.1
+
+* Fix error handling in multi blocks. See #754.
+* Fix geoadd to accept arrays like georadius and georadiusbymember. See #841.
+* Fix georadius command failing when long == lat. See #841.
+* Fix timeout error in xread block: 0. See #837.
+* Fix incompatibility issue with redis-objects. See #834.
+* Properly handle Errno::EADDRNOTAVAIL on connect.
+* Fix password authentication to sentinel instances. See #813.
+
+# 4.1.0
+
+* Add Redis Cluster support. See #716.
+* Add streams support. See #799 and #811.
+* Add ZPOP* support. See #812.
+* Fix issues with integer-like objects as BPOP timeout
+
+# 4.0.3
+
+* Fix raising command error for first command in pipeline. See #788.
+* Fix the gemspec to stop exposing a `build` executable. See #785.
+* Add `:reconnect_delay` and `:reconnect_delay_max` options. See #778.
+
+# 4.0.2
+
+* Added `Redis#unlink`. See #766.
+
+* `Redis.new` now accept a custom connector via `:connector`. See #591.
+
+* `Redis#multi` no longer perform empty transactions. See #747.
+
+* `Redis#hdel` now accepts hash keys as multiple arguments like `#del`. See #755.
+
+* Allow to skip SSL verification. See #745.
+
+* Add Geo commands: `geoadd`, `geohash`, `georadius`, `georadiusbymember`, `geopos`, `geodist`. See #730.
+
+# 4.0.1
+
+* `Redis::Distributed` now supports `mget` and `mapped_mget`. See #687.
+
+* `Redis::Distributed` now supports `sscan` and `sscan_each`. See #572.
+
+* `Redis#connection` returns a hash with connection information.
+  You shouldn't need to call `Redis#_client`, ever.
+
+* `Redis#flushdb` and `Redis#flushall` now support the `:async` option. See #706.
+
+
+# 4.0
+
+* Removed `Redis.connect`. Use `Redis.new`.
+
+* Removed `Redis#[]` and `Redis#[]=` aliases.
+
+* Added support for `CLIENT` commands. The lower-level client can be
+  accessed via `Redis#_client`.
+
+* Dropped official support for Ruby < 2.2.2.
+
+# 3.3.5
+
+* Fixed Ruby 1.8 compatibility after backporting `Redis#connection`. See #719.
+
+# 3.3.4 (yanked)
+
+* `Redis#connection` returns a hash with connection information.
+  You shouldn't need to call `Redis#_client`, ever.
+
+# 3.3.3
+
+* Improved timeout handling after dropping Timeout module.
+
+# 3.3.2
+
+* Added support for `SPOP` with COUNT. See #628.
+
+* Fixed connection glitches when using SSL. See #644.
+
+# 3.3.1
+
+* Remove usage of Timeout::timeout, refactor into using low level non-blocking writes.
+  This fixes a memory leak due to Timeout creating threads on each invocation.
+
+# 3.3.0
+
+* Added support for SSL/TLS. Redis doesn't support SSL natively, so you still
+  need to run a terminating proxy on Redis' side. See #496.
+
+* Added `read_timeout` and `write_timeout` options. See #437, #482.
+
+* Added support for pub/sub with timeouts. See #329.
+
+* Added `Redis#call`, `Redis#queue` and `Redis#commit` as a more minimal API to
+  the client.
+
+* Deprecated `Redis#disconnect!` in favor of `Redis#close`.
 
 # 3.2.2
 

data/README.md

@@ -1,46 +1,18 @@
-# redis-rb [![Build Status][travis-image]][travis-link] [![Inline docs][inchpages-image]][inchpages-link]
+# redis-rb [![Build Status][gh-actions-image]][gh-actions-link] [![Inline docs][inchpages-image]][inchpages-link]
 
-[travis-image]: https://secure.travis-ci.org/redis/redis-rb.png?branch=master
-[travis-link]: http://travis-ci.org/redis/redis-rb
-[travis-home]: http://travis-ci.org/
-[inchpages-image]: http://inch-ci.org/github/redis/redis-rb.png
-[inchpages-link]: http://inch-ci.org/github/redis/redis-rb
+A Ruby client that tries to match [Redis][redis-home]' API one-to-one, while still
+providing an idiomatic interface.
 
-A Ruby client library for [Redis][redis-home].
-
-[redis-home]: http://redis.io
-
-A Ruby client that tries to match Redis' API one-to-one, while still
-providing an idiomatic interface. It features thread-safety, client-side
-sharding, pipelining, and an obsession for performance.
-
-## Upgrading from 2.x to 3.0
-
-Please refer to the [CHANGELOG][changelog-3.0.0] for a summary of the
-most important changes, as well as a full list of changes.
-
-[changelog-3.0.0]: https://github.com/redis/redis-rb/blob/master/CHANGELOG.md#300
+See [RubyDoc.info][rubydoc] for the API docs of the latest published gem.
 
 ## Getting started
 
-To install **redis-rb**, run the following command:
+Install with:
 
 ```
-  gem install redis
+$ gem install redis
 ```
 
-Or if you are using **bundler**, add 
-
-```
-  gem 'redis', '~>3.2'
-```
-
-to your `Gemfile`, and run `bundle install`
-
-As of version 2.0 this client only targets Redis version 2.0 and higher.
-You can use an older version of this client if you need to interface
-with a Redis instance older than 2.0, but this is no longer supported.
-
 You can connect to Redis by instantiating the `Redis` class:
 
 ```ruby
@@ -54,16 +26,17 @@ listening on `localhost`, port 6379. If you need to connect to a remote
 server or a different port, try:
 
 ```ruby
-redis = Redis.new(:host => "10.0.1.1", :port => 6380, :db => 15)
+redis = Redis.new(host: "10.0.1.1", port: 6380, db: 15)
 ```
 
 You can also specify connection options as a [`redis://` URL][redis-url]:
 
 ```ruby
-redis = Redis.new(:url => "redis://:p4ssw0rd@10.0.1.1:6380/15")
+redis = Redis.new(url: "redis://:p4ssw0rd@10.0.1.1:6380/15")
 ```
 
-[redis-url]: http://www.iana.org/assignments/uri-schemes/prov/redis
+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
@@ -72,13 +45,19 @@ to setting this environment variable and calling `Redis.new` without arguments.
 To connect to Redis listening on a Unix socket, try:
 
 ```ruby
-redis = Redis.new(:path => "/tmp/redis.sock")
+redis = Redis.new(path: "/tmp/redis.sock")
 ```
 
 To connect to a password protected Redis instance, use:
 
 ```ruby
-redis = Redis.new(:password => "mysecret")
+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
@@ -86,8 +65,6 @@ they execute. The arguments these methods accept are often identical to
 the arguments specified on the [Redis website][redis-commands]. For
 instance, the `SET` and `GET` commands can be called like this:
 
-[redis-commands]: http://redis.io/commands
-
 ```ruby
 redis.set("mykey", "hello world")
 # => "OK"
@@ -96,24 +73,22 @@ redis.get("mykey")
 # => "hello world"
 ```
 
-All commands, their arguments and return values are documented, and
-available on [rdoc.info][rdoc].
-
-[rdoc]: http://rdoc.info/github/redis/redis-rb/
+All commands, their arguments, and return values are documented and
+available on [RubyDoc.info][rubydoc].
 
 ## Sentinel support
 
-The client is able to perform automatic failovers by using [Redis
+The client is able to perform automatic failover by using [Redis
 Sentinel](http://redis.io/topics/sentinel).  Make sure to run Redis 2.8+
 if you want to use this feature.
 
 To connect using Sentinel, use:
 
 ```ruby
-SENTINELS = [{:host => "127.0.0.1", :port => 26380},
-             {:host => "127.0.0.1", :port => 26381}]
+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(url: "redis://mymaster", sentinels: SENTINELS, role: :master)
 ```
 
 * The master name identifies a group of Redis instances composed of a master
@@ -130,10 +105,60 @@ but a few so that if one is down the client will try the next one. The client
 is able to remember the last Sentinel that was able to reply correctly and will
 use it for the next requests.
 
+If you want to [authenticate](https://redis.io/topics/sentinel#configuring-sentinel-instances-with-authentication) Sentinel itself, you must specify the `password` option per instance.
+
+```ruby
+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)
+```
+
+## 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 only stores strings as values. If you want to store an object, you
-can use a serialization mechanism such as JSON:
+Redis "string" types can be used to store serialized Ruby objects, for
+example with JSON:
 
 ```ruby
 require "json"
@@ -211,7 +236,7 @@ it can't connect to the server a `Redis::CannotConnectError` error will be raise
 ```ruby
 begin
   redis.ping
-rescue Exception => e
+rescue StandardError => e
   e.inspect
 # => #<Redis::CannotConnectError: Timed out connecting to Redis on 10.0.1.1:6380>
 
@@ -222,6 +247,132 @@ end
 
 See lib/redis/errors.rb for information about what exceptions are possible.
 
+## Timeouts
+
+The client allows you to configure connect, read, and write timeouts.
+Passing a single `timeout` option will set all three values:
+
+```ruby
+Redis.new(:timeout => 1)
+```
+
+But you can use specific values for each of them:
+
+```ruby
+Redis.new(
+  :connect_timeout => 0.2,
+  :read_timeout    => 1.0,
+  :write_timeout   => 0.5
+)
+```
+
+All timeout values are specified in seconds.
+
+When using pub/sub, you can subscribe to a channel using a timeout as well:
+
+```ruby
+redis = Redis.new(reconnect_attempts: 0)
+redis.subscribe_with_timeout(5, "news") do |on|
+  on.message do |channel, message|
+    # ...
+  end
+end
+```
+
+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`.
+
+```ruby
+Redis.new(
+  :reconnect_attempts => 10,
+  :reconnect_delay => 1.5,
+  :reconnect_delay_max => 10.0,
+)
+```
+
+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:
+
+```ruby
+attempt_wait_time = [(reconnect_delay * 2**(attempt-1)), reconnect_delay_max].min
+```
+
+**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`.
+
+## SSL/TLS Support
+
+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].
+
+To enable SSL support, pass the `:ssl => true` option when configuring the
+Redis client, or pass in `:url => "rediss://..."` (like HTTPS for Redis).
+You will also need to pass in an `:ssl_params => { ... }` hash used to
+configure the `OpenSSL::SSL::SSLContext` object used for the connection:
+
+```ruby
+redis = Redis.new(
+  :url        => "rediss://:p4ssw0rd@10.0.1.1:6381/15",
+  :ssl_params => {
+    :ca_file => "/path/to/ca.crt"
+  }
+)
+```
+
+The options given to `:ssl_params` are passed directly to the
+`OpenSSL::SSL::SSLContext#set_params` method and can be any valid attribute
+of the SSL context. Please see the [OpenSSL::SSL::SSLContext documentation]
+for all of the available attributes.
+
+Here is an example of passing in params that can be used for SSL client
+certificate authentication (a.k.a. mutual TLS):
+
+```ruby
+redis = Redis.new(
+  :url        => "rediss://:p4ssw0rd@10.0.1.1:6381/15",
+  :ssl_params => {
+    :ca_file => "/path/to/ca.crt",
+    :cert    => OpenSSL::X509::Certificate.new(File.read("client.crt")),
+    :key     => OpenSSL::PKey::RSA.new(File.read("client.key"))
+  }
+)
+```
+
+[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
+
 
 ## Expert-Mode Options
 
@@ -294,35 +445,31 @@ redis = Redis.new(:driver => :synchrony)
 
 ## Testing
 
-This library is tested using [Travis][travis-home], where it is tested
-against the following interpreters and drivers:
+This library is tested against recent Ruby and Redis versions.
+Check [Github Actions][gh-actions-link] for the exact versions supported.
+
+## See Also
 
-* MRI 1.8.7 (drivers: ruby, hiredis)
-* MRI 1.9.2 (drivers: ruby, hiredis, synchrony)
-* MRI 1.9.3 (drivers: ruby, hiredis, synchrony)
-* MRI 2.0.0 (drivers: ruby, hiredis, synchrony)
-* JRuby 1.7 (1.8 mode) (drivers: ruby)
-* JRuby 1.7 (1.9 mode) (drivers: ruby)
+- [async-redis](https://github.com/socketry/async-redis) — An [async](https://github.com/socketry/async) compatible Redis client.
 
 ## Contributors
 
-(ordered chronologically with more than 5 commits, see `git shortlog -sn` for
-all contributors)
-
-* Ezra Zygmuntowicz
-* Taylor Weibley
-* Matthew Clark
-* Brian McKinney
-* Luca Guidi
-* Salvatore Sanfilippo
-* Chris Wanstrath
-* Damian Janowski
-* Michel Martens
-* Nick Quaranto
-* Pieter Noordhuis
-* Ilya Grigorik
+Several people contributed to redis-rb, but we would like to especially
+mention Ezra Zygmuntowicz. Ezra introduced the Ruby community to many
+new cool technologies, like Redis. He wrote the first version of this
+client and evangelized Redis in Rubyland. Thank you, Ezra.
 
 ## Contributing
 
 [Fork the project](https://github.com/redis/redis-rb) and send pull
-requests. You can also ask for help at `#redis-rb` on Freenode.
+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
+[gh-actions-image]: https://github.com/redis/redis-rb/workflows/Test/badge.svg
+[gh-actions-link]:  https://github.com/redis/redis-rb/actions
+[rubydoc]:          http://www.rubydoc.info/gems/redis