Sideroo

Declarative and auditable object-oriented library for Redis

Sideroo is Object Oriented Redis (ooredis) spelled backward.

1. Motivations

This gem is aimed to provide

a declarative Redis key definition

class TopStoriesCache < Sideroo::Set
  key_pattern 'top_stories:{country}:{category}'
  description 'Cache top stories by ID per country and category'
  example 'top_stories:us:romance'
  key_regex /^top_stories\:(\w{2})\:([^\:]+)$/ # OPTIONAL - read docs below
end

TopStoriesCache.dimensions # ['country', 'category']

an intuitive Redis key initialization & attr_accessor

cache = TopStoriesCache.new(country: 'us', category: 'romance')
# instead of repeating key = "top_stories:#{country}:#{category}"

cache.country # us
cache.genre # romance

object-oriented methods for each Redis data type

# Redis Set methods
cache.sadd(story_id) # instead of redis.sadd(key, story_id)
cache.smembers # instead of redis.smembers(key)
cache.sismember(member) # instead of redis.sismember(key, member)

an auditable Redis key management

TopStoriesCache.count # key count
TopStoriesCache.all.map(&:key) # list all keys
TopStoriesCache.flush # delete all keys of the same pattern

# Support `where` for key searching
# `each`, `map` for enumerable
TopStoriesCache.where(category: 'romance').each do |set|
  # ...
end

Potential self-generated documentation for Redis usage
```
Sideroo.report # COMING SOON
```

All of these are done while maintaining a thin abstraction on top of redis gem.

2. Installation

Add this line to your application's Gemfile:

gem 'sideroo'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install sideroo

3. Usage

3.0. Configurations - REQUIRED

Sideroo.configure do |c|
  c.redis_client = Redis.new
end

Sideroo provides a thin OOP abstraction on top of redis-rb. Therefore, it's recommended to use redis-rb (with / without redis-namespace). Any Redis clients with the same interfaces are fine too.

Most of the usage are just to abstract the key argument into the internal state of the obj.

Examples

For Redis Set

# in Redis
key = "namespace:#{dimension_1}:#{dimension_2}"
redis_client.scard(key)
redis_client.sadd(key, member)

# in Sideroo
class MySet < Sideroo::Set
  key_pattern 'namespace:{dimension_1}:{dimension_2}'
end

sideroo_set = MySet.new(
  dimension_1: value_1,
  dimension_2: value_2,
)
sideroo_set.scard
sideroo_set.sadd(member)

3.1. Define a Redis usage

Each Redis usages usually

have a key pattern
use a certain Redis data type

Sideroo provides what you need and more.

There are some configurations you can specify for each use-cases.

`key_pattern` - String - required

Pattern used by the use-case

key_pattern 'top_stories:{country}:{category}'

`key_regex` - Regexp - optional

Regex for better pattern matching for search. See more in Section 5.

Can be 100% optional if key namespacing is done well.

key_regex /^top_stories\:(\w{2})\:([^\:]+)$/

`description` - String - optional

Provide description to the use-cases.

description 'Cache top stories per country and category'

`example` - String - optional

Example of actual Redis keys would be used. If specified, you can utilize example_valid? check to validate key_regex in your specs.

example 'top_stories:us:romance'

Dynamic initalization

When there are dynamic components inside the key pattern, e.g. top_stories:{country}:{category}, the constructor would detect and require country and category during initialization.

# Static cache key
class TopUserCache < Sideroo::List
  key_pattern 'top_users' # REQUIRED
  description 'Cache 50 top users worldwide'
end

# 1-dimension cache key
class CountryPolicyCache < Sideroo::String
  key_pattern 'policy:{country}' # REQUIRED
  key_regex /^page\:(\w{2})$/ # Optional. To resolve key conflicts with other usages if any.
  description 'Cache Policy page per country'
end

CountryPolicyCache.new # MissingKeys: Missing country
CountryPolicyCache.new(country: 'us') # Good
CountryPolicyCache.new(gender: 'us') # UnexpectedKeys: Unexpected keys gender

# 2-dimension cache key
class TopStoriesCache < Sideroo::List
  key_pattern 'top_stories:{country}:{category}'
  description 'Cache top stories by ID per country and category'
end

TopStoriesCache.new # MissingKeys: Missing country, category
TopStoriesCache.new(country: 'us') # MissingKeys: Missing category
TopStoriesCache.new(country: 'us', category: 'romance') # GOOD
TopStoriesCache.new(country: 'us', cateogry: 'romance', random_key: 'random_value') # UnexpectedKeys: Unexpected keys random_key

3.2. Object-oriented methods for each data type

class CountryPageCache < Sideroo::String
  key_pattern 'page:{country}'
  key_regex /^page\:(\w{2})$/
end

# The key-value params are auto detected
page_cache = CountryPageCache.new(country: country)
page_cache.get

class TopStoriesCache < Sideroo::List
  key_pattern 'top_stories:{country}:{category}'
  description 'Cache top stories by ID per country and category'
end

# The key-value params are auto detected
cache = TopStoryCache.new(country: 'sg', category: 10)
cache.lpush(story_id)
cache.set(story_id) # NoMethodError - since `set` is not a method of List type

3.3. Search and Enumerable

class TopStoriesCache < Sideroo::Set
  key_pattern 'top_stories:{country}:{category}'
  description 'Cache top stories by ID per country and category'
end

top_stories:sg:10
top_stories:sg:20
top_stories:us:10
top_stories:us:12

TopStoriesCache.all # Not recommended for large db
TopStoriesCache.all.to_a

TopStoriesCache.where(country: 'sg').to_a

# Loop through `top_stories:sg:*`
TopStoriesCache.where(country: 'sg').each do |list|
  list.key # top_stories:sg:10
  list.smembers # return story ids
  # ...
end

TopStoriesCache.where(country: 'sg').map do |list|
  #...
end

TopStoriesCache.where(country: 'sg').count

3.4. Report & Generate documentation - COMING SOON

Sideroo.report

TBD

3.5. Audit keys

TopStoriesCache.count # Scan and count

TopStoriesCache.all.to_a # NOT RECOMMENDED if there are too many keys

3.6. Flush keys

TopStoriesCache.flush # Delete all keys of TopStoriesCache

4. Data Types

Sideroo provides support for 7 main Redis data types.

All key-related Redis methods are supported by all below types.