kredis

Kredis

Kredis (Keyed Redis) encapsulates higher-level types and data structures around a single key, so you can interact with them as coherent objects rather than isolated procedural commands. These higher-level structures can be configured as attributes within Active Models and Active Records using a declarative DSL.

Kredis is configured using env-aware YAML files, using Rails.application.config_for, so you can locate the data structures on separate Redis instances, if you've reached a scale where a single shared instance is no longer sufficient.

Kredis provides namespacing support for keys such that you can safely run parallel testing against the data structures without different tests trampling each others data.

Examples

Kredis provides typed scalars for strings, integers, decimals, floats, booleans, datetimes, and JSON hashes:

…

There are data structures for counters, enums, flags, lists, unique lists, sets, and slots:

…

Models

You can use all these structures in models:

…

Default values

You can set a default value for all types. For example:

list = Kredis.list "favorite_colors", default: [ "red", "green", "blue" ]

# or, in a model
class Person < ApplicationRecord
  kredis_string :name, default: "Unknown"
  kredis_list :favorite_colors, default: [ "red", "green", "blue" ]
end

There's a performance overhead to consider though. When you first read or write an attribute in a model, Kredis will check if the underlying Redis key exists, while watching for concurrent changes, and if it does not, write the specified default value.

This means that using default values in a typical Rails app additional Redis calls (WATCH, EXISTS, UNWATCH) will be executed for each Kredis attribute with a default value read or written during a request.

Callbacks

You can also define after_change callbacks that trigger on mutations:

class Person < ApplicationRecord
  kredis_list :names, after_change: ->(p) {  }
  kredis_unique_list :skills, limit: 2, after_change: :skillset_changed

  def skillset_changed
  end
end

Multiple Redis servers

And using structures on a different than the default shared redis instance, relying on config/redis/secondary.yml:

one_string = Kredis.string "mystring"
two_string = Kredis.string "mystring", config: :secondary

one_string.value = "just on shared"
two_string.value != one_string.value

Installation

1. Run ./bin/bundle add kredis
2. Run ./bin/rails kredis:install to add a default configuration at config/redis/shared.yml

Additional configurations can be added under config/redis/*.yml and referenced when a type is created. For example, Kredis.string("mystring", config: :strings) would lookup config/redis/strings.yml.

Kredis passes the configuration to Redis.new to establish the connection. See the Redis documentation for other configuration options.

If you don't have config/redis/shared.yml (or use another named configuration), Kredis will default to look in env for REDIS_URL, then fallback to a default URL of redis://127.0.0.1:6379/0.

Redis support

Kredis works with Redis server 4.0+, with the Redis Ruby client version 4.2+. Redis Cluster is not supported.

Setting SSL options on Redis Connections

If you need to connect to Redis with SSL, the recommended approach is to set your Redis instance manually by adding an entry to the Kredis::Connections.connections hash. Below an example showing how to connect to Redis using Client Authentication:

Kredis::Connections.connections[:shared] = Redis.new(
  url: ENV["REDIS_URL"],
  ssl_params: {
    cert_store: OpenSSL::X509::Store.new.tap { |store|
      store.add_file(Rails.root.join("config", "ca_cert.pem").to_s)
    },

    cert: OpenSSL::X509::Certificate.new(File.read(
      Rails.root.join("config", "client.crt")
    )),

    key: OpenSSL::PKey::RSA.new(
      Rails.application.credentials.redis[:client_key]
    ),

    verify_mode: OpenSSL::SSL::VERIFY_PEER
  }
)

The above code could be added to either config/environments/production.rb or an initializer. Please ensure that your client private key, if used, is stored your credentials file or another secure location.

Configure how the redis client is created

You can configure how the redis client is created by setting config.kredis.connector in your application.rb:

config.kredis.connector = ->(config) { SomeRedisProxy.new(config) }

By default Kredis will use Redis.new(config).

Development

A development console is available by running bin/console.

From there, you can experiment with Kredis. e.g.

>> str = Kredis.string "mystring"
  Kredis  (0.1ms)  Connected to shared
=>
#<Kredis::Types::Scalar:0x0000000134c7d938
...
>> str.value = "hello, world"
  Kredis Proxy (2.4ms)  SET mystring ["hello, world"]
=> "hello, world"
>> str.value

Run tests with bin/test.

debug can be used in the development console and in the test suite by inserting a breakpoint, e.g. debugger.

License

Kredis is released under the MIT License.