redis 4.0.0.rc1 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d72ccd62dcdffae216b836b1e3655bf7f632e4e9
-  data.tar.gz: 0cf0966047ed05199088049df15d2ec01bbcd412
+SHA256:
+  metadata.gz: d5ff2ee4b6a6f2b087ac26bf96a3c1769cf42f70ea90008361157f7ef04cdb14
+  data.tar.gz: f2c24654294c4fa81a5cff4ddb545bc59e6f85b64ee61273278cb1e286a4edb8
 SHA512:
-  metadata.gz: e7196307b6ae34d4a23001617acae003c7fc71ccfea7d7f5900bb19dc2a22d5f83292859fb793945b0274b6750f0f31a98397fc2666bf5507eb00313f0efcdbf
-  data.tar.gz: c20a6e85b2e3b3ccbbeeec274e134be97597fccd45e3798a9c7d687df0ff150588b05b441eb34b465d22c43b972e76498e31f2e8c03534b76a9a1dcbff024781
+  metadata.gz: 0d88c6621659a178dca04d3ca62f25520f5f1a846b6300f93fb008966551fb4795a3e6c37810f99ea18f77a6292b955fa180ae3e06f8c90df7e6a3ca27087ae1
+  data.tar.gz: 1427cc268e867872388f214184d23a5c6062104fcb9d1e50d6026dd9daf6e51b9833866fee9fcf80c7a64e4de705295de8399d8e8ac22fa890bf358bd63ff707

data/CHANGELOG.md

@@ -1,14 +1,154 @@
-# 4.0 (unreleased)
+# 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.
 
-* Removed `Redis::Distributed`.
-
 * 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.

data/README.md

@@ -1,8 +1,9 @@
-# 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]
 
 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.
 
 ## Getting started
 
@@ -34,6 +35,9 @@ You can also specify connection options as a [`redis://` URL][redis-url]:
 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.
@@ -50,6 +54,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
@@ -95,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"
@@ -176,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>
 
@@ -211,6 +271,7 @@ 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|
     # ...
@@ -220,6 +281,51 @@ 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
 
@@ -227,7 +333,7 @@ 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
+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:
@@ -340,7 +446,11 @@ redis = Redis.new(:driver => :synchrony)
 ## 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
+
+- [async-redis](https://github.com/socketry/async-redis) — An [async](https://github.com/socketry/async) compatible Redis client.
 
 ## Contributors
 
@@ -352,15 +462,14 @@ 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.
-
-
-[inchpages-image]: https://inch-ci.org/github/redis/redis-rb.png
-[inchpages-link]:  https://inch-ci.org/github/redis/redis-rb
-[redis-commands]:  http://redis.io/commands
-[redis-home]:      http://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.png?branch=master
-[travis-link]:     https://travis-ci.org/redis/redis-rb
-[rubydoc]:         http://www.rubydoc.info/gems/redis
+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