redis-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d53aaf68e8bf2bc7160a8b708d86c40d13a229a2bfa88734ada0ae03839d6330
+  data.tar.gz: 7ebc1e2e488dbd0bc7895db4714237e893408f017222922cc94faec4b7646e7c
+SHA512:
+  metadata.gz: 397746e753c9c44e6b6f7d046b9e8cb389c25c7a8d8dea40e7ab81c099f328d4f34c1d77d7c2c66c0ea7b12056f282a76c3dc5a700b1acee49b89cddc509070d
+  data.tar.gz: a2fcda7b8bbef1a0988fcd7434306da5769dbcf1ad91b5f790186646eedd1b21fa289b044bacd3f3b91486f8d06e73c51d608f92662bcb366e3d3e871a138b40

data/.rubocop.yml

@@ -0,0 +1,190 @@
+AllCops:
+  TargetRubyVersion: 2.5
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'test/**/*'
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/LineEndStringConcatenationIndentation:
+  EnforcedStyle: indented
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Lint/RescueException:
+  Enabled: false
+
+Lint/SuppressedException:
+  Enabled: false
+
+Lint/AssignmentInCondition:
+  Enabled: false
+
+Lint/UnifiedInteger:
+  Enabled: false
+
+Lint/UnderscorePrefixedVariableName:
+  Enabled: false
+
+Lint/EmptyBlock:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Style/Alias:
+  EnforcedStyle: prefer_alias_method
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+Style/ParallelAssignment:
+  Enabled: false
+
+Style/NumericPredicate:
+  Enabled: false
+
+Style/NumericLiterals:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/SignalException:
+  Exclude:
+    - 'lib/redis/connection/synchrony.rb'
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/MultipleComparison:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/Semicolon:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Lint/NonLocalExitFromIterator:
+  Enabled: false
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
+
+Layout/ElseAlignment:
+  Enabled: false
+
+Layout/RescueEnsureAlignment:
+  Enabled: false
+
+Naming/HeredocDelimiterNaming:
+  Enabled: false
+
+Naming/FileName:
+  Enabled: false
+
+Naming/RescuedExceptionsVariableName:
+  Enabled: false
+
+Naming/AccessorMethodName:
+  Exclude:
+    - lib/redis/connection/ruby.rb
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: false
+
+Style/HashTransformValues:
+  Enabled: false
+
+Style/SymbolProc:
+  Exclude:
+    - 'test/**/*'
+
+Style/SoleNestedConditional:
+  Enabled: false
+
+Style/GlobalVars:
+  Exclude:
+    - 'ext/**/*'
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Style/StderrPuts:
+  Enabled: false
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/CombinableLoops:
+  Enabled: false
+
+Style/DocumentDynamicEvalDefinition:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+# 0.1.0
+
+- Initial Release

data/Gemfile

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in redis-client.gemspec
+gemspec
+
+gem "connection_pool"
+gem "minitest"
+gem "rake", "~> 13.0"
+gem "rake-compiler"
+gem "rubocop"
+gem "rubocop-minitest"
+gem "toxiproxy"
+
+group :benchmark do
+  gem "benchmark-ips"
+  gem "hiredis"
+  gem "redis", "~> 4.6"
+  gem "stackprof", platform: :mri
+end
+
+gem "byebug", platform: :mri

data/Gemfile.lock

@@ -0,0 +1,67 @@
+PATH
+  remote: .
+  specs:
+    redis-client (0.0.0)
+      connection_pool
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.2)
+    benchmark-ips (2.10.0)
+    byebug (11.1.3)
+    connection_pool (2.2.5)
+    hiredis (0.6.3)
+    hiredis (0.6.3-java)
+    minitest (5.15.0)
+    parallel (1.21.0)
+    parser (3.1.1.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rake-compiler (1.1.9)
+      rake
+    redis (4.6.0)
+    regexp_parser (2.2.1)
+    rexml (3.2.5)
+    rubocop (1.25.1)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.16.0)
+      parser (>= 3.1.1.0)
+    rubocop-minitest (0.14.0)
+      rubocop (>= 0.90, < 2.0)
+    ruby-progressbar (1.11.0)
+    stackprof (0.2.19)
+    toxiproxy (2.0.0)
+    unicode-display_width (2.1.0)
+
+PLATFORMS
+  ruby
+  universal-java-18
+  x86_64-darwin-20
+  x86_64-linux
+
+DEPENDENCIES
+  benchmark-ips
+  byebug
+  connection_pool
+  hiredis
+  minitest
+  rake (~> 13.0)
+  rake-compiler
+  redis (~> 4.6)
+  redis-client!
+  rubocop
+  rubocop-minitest
+  stackprof
+  toxiproxy
+
+BUNDLED WITH
+   2.3.8

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Shopify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,347 @@
+# RedisClient
+
+`redis-client` is a simple, low-level, client for Redis 6+.
+
+Contrary to the `redis` gem, `redis-client` doesn't try to map all redis commands to Ruby constructs,
+it merely is a thin wrapper on top of the RESP3 protocol.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'redis-client'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install redis-client
+
+## Usage
+
+To use `RedisClient` you first define a connection configuration, from which you can create a connection pool:
+
+```ruby
+redis_config = RedisClient.config(host: "10.0.1.1", port: 6380, db: 15)
+redis = redis_config.new_pool(timeout: 0.5, size: Integer(ENV.fetch("RAILS_MAX_THREADS", 5)))
+
+redis.call("PING") # => "PONG"
+```
+
+If you are issuing multiple commands in a raw, but can't pipeline them, it's best to use `#with` to avoid going through the connection checkout
+several times:
+
+```ruby
+redis.with do |r|
+  r.call("SET", "mykey", "hello world") # => "OK"
+  r.call("GET", "mykey") # => "hello world"
+end
+```
+
+If you are working in a single threaded environment, or wish to use your own connection pooling mechanism,
+you can obtain a raw client with `#new_client`
+
+```ruby
+redis_config = RedisClient.config(host: "10.0.1.1", port: 6380, db: 15)
+redis = redis_config.new_client
+redis.call("PING") # => "PONG"
+```
+
+NOTE: Raw `RedisClient` instances must not be shared between threads. Make sure to read the section on [thread safety](#thread-safety).
+
+For simple use cases where only a single connection is needed, you can use the `RedisClient.new` shortcut:
+
+```ruby
+redis = RedisClient.new
+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 tht all other configurtions 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.
+- `ssl`: Wether to connect using SSL or not.
+- `ssl_params`: A configuration Hash passed to [`OpenSSL::SSL::SSLContext#set_params`](https://www.rubydoc.info/stdlib/openssl/OpenSSL%2FSSL%2FSSLContext:set_params), notable options include:
+  - `cert`: The path to the client certificate (e.g. `client.crt`).
+  - `key`: The path to the client key (e.g. `client.key`).
+  - `ca_file`: The certificate authority to use, useful for self signed certificates (e.g. `ca.crt`),
+- `db`: The database to select after connecting, defaults to `0`.
+- `id` ID for the client connection, assigns name to current connection by sending `CLIENT SETNAME`.
+- `username` Username to authenticate against server, defaults to `"default"`.
+- `password` Password to authenticate against server.
+- `timeout`: The general timeout in seconds, default to `1.0`.
+- `connect_timeout`: The connection timeout, takes precedence over the general timeout when connecting to the server.
+- `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.
+
+### Sentinel support
+
+The client is able to perform automatic failover by using [Redis Sentinel](https://redis.io/docs/manual/sentinel/).
+
+To connect using Sentinel, use:
+
+```ruby
+redis_config = RedisClient.sentinel(
+  name: "mymaster",
+  sentinels: [
+    { host: "127.0.0.1", port: 26380 },
+    { host: "127.0.0.1", port: 26381 },
+  ],
+  role: :master,
+)
+```
+
+* The name identifies a group of Redis instances composed of a master and one or more replicas (`mymaster` in the example).
+
+* It is possible to optionally provide a role. The allowed roles are `:master`
+and `:replica`. When the role is `:replica`, the client will try to connect to a
+random replica of the specified master. If a role is not specified, the client
+will connect to the master.
+
+* When using the Sentinel support you need to specify a list of sentinels to
+connect to. The list does not need to enumerate all your Sentinel instances,
+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.
+
+### Type support
+
+Only a select few Ruby types are supported as arguments beside strings.
+
+Integer and Float are supported:
+
+```ruby
+redis.call("SET", "mykey", 42)
+redis.call("SET", "mykey", 1.23)
+```
+
+is equivalent to:
+
+```ruby
+redis.call("SET", "mykey", 42.to_s)
+redis.call("SET", "mykey", 1.23.to_s)
+```
+
+Arrays are flattened as arguments:
+
+```ruby
+redis.call("LPUSH", "list", [1, 2, 3], 4)
+```
+
+is equivalent to:
+
+```ruby
+redis.call("LPUSH", "list", "1", "2", "3", "4")
+```
+
+Hashes are flatenned as well:
+
+```ruby
+redis.call("HMSET", "hash", foo: 1, bar: 2)
+redis.call("SET", "key", "value", ex: 5)
+```
+
+is equivalent to:
+
+```ruby
+redis.call("HMSET", "hash", "foo", "1", "bar", "2")
+redis.call("SET", "key", "value", "ex", "5")
+```
+
+Any other type requires the caller to explictly cast the argument as a string.
+
+### Blocking commands
+
+For blocking commands such as `BRPOP`, a custom timeout duration can be passed as first argument of the `#blocking_call` method:
+
+```
+redis.blocking_call(timeout, "BRPOP", "key", 0)
+```
+
+If `timeout` is reached, `#blocking_call` returns `nil`.
+
+`timeout` is expressed in seconds, you can pass `false` or `0` to mean no timeout.
+
+### Scan commands
+
+For easier use of the [`SCAN` family of commands](https://redis.io/commands/scan), `#scan`, `#sscan`, `#hscan` and `#zscan` methods are provided
+
+```ruby
+redis.scan("MATCH", "pattern:*") do |key|
+  ...
+end
+```
+
+```ruby
+redis.sscan("myset", "MATCH", "pattern:*") do |key|
+  ...
+end
+```
+
+For `HSCAN` and `ZSCAN`, pairs are yielded
+
+```ruby
+redis.hscan("myhash", "MATCH", "pattern:*") do |key, value|
+  ...
+end
+```
+
+```ruby
+redis.zscan("myzset") do |element, score|
+  ...
+end
+```
+
+In all cases the `cursor` parameter must be omitted and starts at `0`.
+
+### Pipelining
+
+When multiple commands are executed sequentially, but are not dependent, the calls can be pipelined.
+This means that the client doesn't wait for reply of the first command before sending the next command.
+The advantage is that multiple commands are sent at once, resulting in faster overall execution.
+
+The client can be instructed to pipeline commands by using the `#pipelined method`.
+After the block is executed, the client sends all commands to Redis and gathers their replies.
+These replies are returned by the `#pipelined` method.
+
+```ruby
+redis.pipelined do |pipeline|
+  pipeline.call("SET", "foo", "bar") # => nil
+  pipeline.call("INCR", "baz") # => nil
+end
+# => ["OK", 1]
+```
+
+### Transactions
+
+You can use [`MULTI/EXEC` to run a number of commands in an atomic fashion](https://redis.io/topics/transactions).
+This is similar to executing a pipeline, but the commands are
+preceded by a call to `MULTI`, and followed by a call to `EXEC`. Like
+the regular pipeline, the replies to the commands are returned by the
+`#multi` method.
+
+```ruby
+redis.multi do |transaction|
+  transaction.call("SET", "foo", "bar") # => nil
+  transaction.call("INCR", "baz") # => nil
+end
+# => ["OK", 1]
+```
+
+For optimistic locking, the watched keys can be passed to the `#multi` method:
+
+```ruby
+redis.multi(watch: ["title"]) do |transaction|
+  title = redis.call("GET", "title")
+  transaction.call("SET", "title", title.upcase)
+end
+# => ["OK"] / nil
+```
+
+If the transaction wasn't successful, `#multi` will return `nil`.
+
+Note that transactions using optimistic locking aren't automatically retried uppon connection errors.
+
+### Publish / Subscribe
+
+Pub/Sub related commands must be called on a dedicated `PubSub` object:
+
+```ruby
+redis = RedisClient.new
+pubsub = redis.pubsub
+pubsub.call("SUBSCRIBE", "channel-1", "channel-2")
+
+loop do
+  if message = pubsub.next_event(timeout)
+    message # => ["subscribe", "channel-1", 1]
+  else
+    # no new message was received in the allocated timeout
+  end
+end
+```
+
+## Production
+
+### Timeouts
+
+The client allows you to configure connect, read, and write timeouts.
+Passing a single `timeout` option will set all three values:
+
+```ruby
+RedisClient.config(timeout: 1).new
+```
+
+But you can use specific values for each of them:
+
+```ruby
+RedisClient.config(
+  connect_timeout: 0.2,
+  read_timeout: 1.0,
+  write_timeout: 0.5,
+).new
+```
+
+All timeout values are specified in seconds.
+
+### Reconnection
+
+`redis-client` support automatic reconnection after network errors via the `reconnect_attempts:` configuration option.
+
+It can be set as a number of retries:
+
+```ruby
+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 = redis_config.new_client
+redis.call("GET", "counter") # Will be retried up to 3 times.
+redis.call_once("INCR", "counter") # Won't be retried.
+```
+
+## Notable differences with the `redis` gem
+
+### Thread Safety
+
+Contrary to the `redis` gem, `redis-client` doesn't protect against concurrent access.
+To use `redis-client` in concurrent environments, you MUST use a connection pool, or
+have one client per Thread or Fiber.
+
+### Fork Safety
+
+`redis-client` doesn't try to detect forked processes. You MUST disconnect all clients before forking your process.
+
+```ruby
+redis.close
+Process.fork ...
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/redis-rb/redis-client.