AnyCache ·

AnyCache - a simplest cache wrapper that provides a minimalistic generic interface for all well-known cache storages and includes a minimal set of necessary operations: fetch, read, write, delete, fetch_multi, read_multi, write_multi, delete_matched, expire, persist, exist?, clear, cleanup, increment, decrement.

Supported clients:

• Redis (gem redis) (redis storage)
• Redis::Store (gem redis-store) (redis storage)
• Dalli::Client (gem dalli) (memcached storage)
• ActiveSupport::Cache::RedisCacheStore (gem activesupport) (redis cache storage)
• ActiveSupport::Cache::DalliStore (gem dalli) (dalli store)
• ActiveSupport::Cache::MemCacheStore (gem activesupport) (memcache storage)
• ActiveSupport::Cache::FileStore (gem activesupport) (file storage)

• ActiveSupport::Cache::MemoryStore (gem activesupport) (in memory storage)

• [Coming Soon] File-based configuration;

• [Coming Soon] Simple in-memory hash-based cache client

• [Coming Soon] Simple key-value storage based on PostgreSQL

• [Coming Soon] Support for ActiveSupport::Cache::NullStore

• [Coming Soon] Naive NullStore implementation;

---

Installation

gem 'any_cache'

bundle install
# --- or ---
gem install any_cache

require 'any_cache'

---

Usage / Table of Contents

• Creation
  • Manual creation
  • Config-based creation
    • AnyCache with Redis
    • AnyCache with Redis::Store
    • AnyCache with Dalli::Client
    • AnyCache with ActiveSupport::Cache::RedisCacheStore
    • AnyCache with ActiveSupport::Cache::DalliStore
    • AnyCache with ActiveSupport::Cache::MemCacheStore
    • AnyCache with ActiveSupport::Cache::FileStore
    • AnyCache with ActiveSupport::Cache::MemoryStore
  • Many cache storages
  • Custom cache clients
• Logging
• Operations
  • Fetch / Fetch Multi
  • Read / Read Multi
  • Write / Write Multi
  • Delete / Delete Matched
  • Increment / Decrement
  • Expire
  • Persist
  • Existence
  • Clear
  • Cleanup
• Plugins
• Roadmap

---

Creation

To instantiate AnyCache instance you have to provide a client. Client - an independent driver that works with a corresponding cache storage (external dependency).

Supported clients:

• Redis
• Redis::Store
• Dalli::Client
• ActiveSupport::Cache::RedisCacheStore
• ActiveSupport::Cache::DalliStore
• ActiveSupport::Cache::MemCacheStore
• ActiveSupport::Cache::FileStore
• ActiveSupport::Cache::MemoryStore

AnyCache can be instantiated by two ways:

• with explicit client object instantiated manually (read);
• via configuration (read);

Manual creation

Custom instantiation with explicit client objects:

# 1) create client object
client = Redis.new(...)
# -- or --
client = Redis::Store.new(...)
# -- or --
client = Dalli::Client.new(...)
# -- or --
client = ActiveSupport::Cache::RedisCacheStore.new(...)
# -- or --
client = ActiveSupport::Cache::DalliStore.new(...)
# -- or --
client = ActiveSupport::Cache::MemCacheStore.new(...)
# -- or --
client = ActiveSupport::Cache::FileStore.new(...)
# -- or --
client = ActiveSupport::Cache::MemoryStore.new(...)

# 2) build AnyCache instance
cache_store = AnyCache.build(client) # => <AnyCache:0x00007f990527f268 ...>

Config-based creation

You can configure AnyCache globally or create subclasses and configure each of them. After that storage instantiation works via .build method without explicit attributes.

• AnyCache.configure is used for configuration;
• config.driver is used for determine which client should be used;
• config.__driver_name__.options stores client-related options;

Supported drivers:

• :redis - Redis;
• :redis_store - Redis::Client;
• :dalli - Dalli::Client;
• :as_redis_cache_store - ActiveSupport::Cache::RedisCacheStore;
• :as_dalli_store - ActiveSupport::Cache::DalliStore;
• :as_mem_cache_store - ActiveSupport::Cache::MemCacheStore;
• :as_file_store - ActiveSupport::Cache::FileStore;
• :as_memory_store - ActiveSupport::Cache::MemoryStore;

AnyCache with Redis:

require 'redis'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :redis
  conf.redis.options = { ... } # Redis-related options
end

cache_store = AnyCache.build

AnyCache with Redis::Store:

require 'redis-store'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :redis_store
  conf.redis_store.options = { ... } # Redis::Store-related options
end

cache_store = AnyCache.build

AnyCache with Dalli::Client:

require 'dalli'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :dalli
  conf.dalli.servers = ... # string or array of strings
  conf.dalli.options = { ... } # Dalli::Client-related options
end

cache_store = AnyCache.build

AnyCache with ActiveSupport::Cache::RedisCacheStore:

require 'redis'
require 'active_support'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :as_redis_cache_store
  conf.as_redis_cache_store.options = { ... } # ActiveSupport::Cache::RedisCacheStore-related options
end

cache_store = AnyCache.build

AnyCache with ActiveSupport::Cache::DalliStore:

require 'dalli'
require 'active_support'
require 'any_cache'

AnyCache.enable_patch!(:dalli_store) # NOTE: actual for Dalli <= 2.7.8

AnyCache.configure do |conf|
  conf.driver = :as_dalli_store
  conf.as_dalli_store.servers = ... # string or array of strings
  conf.as_dalli_store.options = { ... } # ActiveSupport::Cache::DalliStore-related options
end

cache_store = AnyCache.build

AnyCache with ActiveSupport::Cache::MemCacheStore:

require 'active_support'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :as_mem_cache_store
  conf.as_mem_cache_store.servers = ... # string or array of strings
  conf.as_mem_cache_store.options = { ... } # ActiveSupport::Cache::MemCacheStore-related options
end

cache_store = AnyCache.build

AnyCache with ActiveSupport::Cache::FileStore:

require 'active_support'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :as_file_store
  conf.as_file_store.cache_path = '/path/to/cache'
  conf.as_file_store.options = { ... } # ActiveSupport::Cache::FileStore-related options
end

cache_store = AnyCache.build

AnyCache with ActiveSupport::Cache::MemoryStore:

require 'activesupport'
require 'any_cache'

AnyCache.configure do |conf|
  conf.driver = :as_memory_store
  conf.as_memory_store.options = { ... } # ActiveSupport::Cache::MemoryStore-related options
end

cache_store = AnyCache.build

Many cache storages

You can inherit AnyCache class and create and configure as many cache storages as you want:

class RedisCache < AnyCache
  configure do |conf|
    conf.driver = :redis
  end
end

class DalliCache < AnyCache
  configure do |conf|
    conf.driver = :dalli
  end
end

redis_cache = RedisCache.build
dalli_cache = DalliCache.build

Custom cache clients

If you want to use your own cache client implementation, you should provide an object that responds to:

• #fetch(key, [**options]) (doc)
• #fetch_multi(*keys, [**options]) (doc)
• #read(key, [**options]) (doc)
• #read_multi(*keys, [**options]) (doc)
• #write(key, value, [**options]) (doc)
• #write_multi(entries, [**options]) (doc)
• #delete(key, [**options]) (doc)
• #delete_matched(pattern, [**options]) (doc)
• #increment(key, amount, [**options]) (doc)
• #decrement(key, amount, [**options]) (doc)
• #expire(key, [**options]) (doc)
• #persist(key, [**options]) (doc)
• #exist?(key, [**options]) (doc)
• #clear([**options]) (doc)
• #cleanup([**options]) (doc)

class MyCacheClient
  # ...

  def read(key, **)
    # ...
  end

  def write(key, value, **)
    # ...
  end

  # ...
end

AnyCache.build(MyCacheClient.new)

---

Logging

AnyCache logs all its operations. By default, AnyCache uses a simple STDOUT logger with Logger::INFO level. Logging is performed with level configured in logger object.

Logger configuration:

# --- use your own logger ---
AnyCache.configure do |conf|
  conf.logger = MyLoggerObject.new
end

# --- disable logging ---
AnyCache.configure do |conf|
  conf.logger = nil
end

# --- (used by default) ---
AnyCache.configure do |conf|
  conf.logger = AnyCache::Logging::Logger.new(STDOUT)
end

# --- (your cache client inherited from AnyCache) ---
YourCacheClient.configure do |conf|
  # same configs as above
end

Log message format:

[AnyCache<CACHER_NAME>/Activity<OPERATION_NAME>]: performed <OPERATION_NAME> operation with
params: INSPECTED_ARGUMENTS and options: INSPECTED_OPTIONS

• progname
  • CACHER_NAME - class name of your cache class;
  • OPERATION_NAME - performed operation (read, write, fetch and etc);
• message
  • INSPECTED_ARGUMENTS - a set of operation arguments;
  • INSPECTED_OPTIONS - a set of operation options;

any_cache.write("data", 123, expires_in: 60)
# I, [2018-09-07T10:04:56.649960 #15761]  INFO -- [AnyCache<AnyCache>/Activity<write>]: performed <write> operation with attributes: ["data", 123] and options: {:expires_in=>60}.

any_cache.clear
# I, [2018-09-07T10:05:26.999847 #15761]  INFO -- [AnyCache<AnyCache>/Activity<clear>]: performed <clear> operation with attributes: [] and options: {}.

Operations

AnyCache provides a following operation set:

• fetch / fetch_multi
• read / read_multi
• write / write_multi
• delete / delete_matched
• increment / decrement
• expire
• persist
• clear
• exist?

---

Fetch

• AnyCache#fetch(key, [force:], [expires_in:], [&fallback])
  • works in ActiveSupport::Cache::Store#fetch-manner;
  • fetches data from the cache using the given key;
  • if a fallback block has been passed and data with the given key does not exist - that block will be called with the given key and the return value will be written to the cache;
  • use raw: true if you want to fetch incrementable/decrementable entry;

# --- entry exists ---
cache_store.fetch("data") # => "some_data"
cache_store.fetch("data") { "new_data" } # => "some_data"

# --- entry does not exist ---
cache_store.fetch("data") # => nil
cache_store.fetch("data") { |key| "new_data" } # => "new_data"
cache_store.fetch("data") # => "new_data"

# --- new entry with expiration time ---
cache_store.fetch("data") # => nil
cache_store.fetch("data", expires_in: 8) { |key| "new_#{key}" } # => "new_data"
cache_store.fetch("data") # => "new_data"
# ...sleep 8 seconds...
cache_store.fetch("data") # => nil

# --- force update/rewrite ---
cache_store.fetch("data") # => "some_data"
cache_store.fetch("data", expires_in: 8, force: true) { |key| "new_#{key}" } # => "new_data"
cache_store.fetch("data") # => "new_data"
# ...sleep 8 seconds...
cache_store.fetch("data") # => nil

---

Fetch Multi

• AnyCache#fetch_multi(*keys, [force:], [expires_in:], [&fallback])
  • get a set of entries in hash form from the cache storage using given keys;
  • works in #fetch manner but with a series of entries;
  • nonexistent entries will be fetched with nil values;
  • use raw: true if you want to fetch incrementable/decrementable entries;

# --- fetch entries ---
cache_store.fetch_multi("data", "second_data", "last_data")
# => returns:
{
  "data" => "data", # existing entry
  "second_data" => nil, # nonexistent entry
  "last_data" => nil # nonexistent entry
}

# --- fetch etnries and define non-existent entries ---
cache_store.fetch_multi("data", "second_data", "last_data") { |key| "new_#{key}" }
# => returns:
{
  "data" => "data", # entry with OLD value
  "second_data" => "new_second_data", # entry with NEW DEFINED value
  "last_data" => "new_last_data" # entry with NEW DEFINED value
}

# --- force rewrite all entries ---
cache_store.fetch_multi("data", "second_data", "last_data", force: true) { |key| "force_#{key}" }
# => returns
{
  "data" => "force_data", # entry with REDEFINED value
  "second_data" => "force_second_data", # entry with REDEFINED value
  "last_data" => "force_last_data" # entry with REDEFINED value
}

---

Read

• AnyCache#read(key) - get an entry value from the cache storage
  • pass raw: true if you want to read incrementable/decrementable entries;

# --- entry exists ---
cache_store.read("data") # => "some_data"

# --- entry doesnt exist ---
cache_store.read("data") # => nil

# --- read incrementable/decrementable entry ---
cache_store.read("data", raw: true) # => "2" (for example)

---

Read Multi

• AnyCache#read_multi(*keys)
  • get entries from the cache storage in hash form;
  • nonexistent entries will be fetched with nil values;
  • pass raw: true if you want to read incrementable/decrementable entries;

cache_store.read_multi("data", "another_data", "last_data", "super_data")
# => returns
{
  "data" => "test", # existing entry
  "another_data" => nil, # nonexistent entry
  "last_data" => "some_data", # exisitng enry
  "super_data" => nil # existing entry
}

# --- read incrementable/decrementable entries ---
cache_store.read_multi("data", "another_data", raw: true)
# => returns
{
  "data" => "1",
  "another_data" => "2",
}

---

Write

• AnyCache#write(key, value, [expires_in:]) - write a new entry to the cache storage;
  • pass raw: true if you want to store incrementable/decrementable entries;

# --- permanent entry ---
cache_store.write("data", 123)

# --- temporal entry (expires in 60 seconds) ---
cache_store.write("data", 123, expires_in: 60)

# --- incrementable/decrementable entry ---
cache_store.write("data", 123, raw: true)

---

Write Multi

• AnyCache#write_multi(**entries) - write a set of permanent entries to the cache storage;
  • pass raw: true if you want to store incrementable/decrementable entries;

cache_store.write_multi("data" => "test", "another_data" => 123)

# --- incrementable/decrementable entries ---
cache_store.write_multi("data" => 1, "another_data" => 2, raw: true)

---

Delete

• AnyCache#delete(key) - remove entry from the cache storage;

cache_store.delete("data")

---

Delete Matched

• AnyCache#delete_matched(pattern)
  • removes all entries with keys matching the pattern;
  • currently unsupported: :dalli, :as_mem_cache_store, :as_dalli_store;

# --- using a regepx ---
cache_store.delete_matched(/\A*test*\z/i)

# --- using a string ---
cache_store.delete_matched("data")

---

Increment

• AnyCache#increment(key, amount = 1, [expires_in:]) - increment entry's value by the given amount and set the new expiration time if needed;
  • can increment only nonexistent entries OR entries that were written with raw: true option;

# --- increment existing entry ---
cache_store.write("data", 1, raw: true) # you must provide :raw => true for incrementable entries

# --- increment by default value (1) ---
cache_store.increment("data") # => 2

# --- increment by custom value ---
cache_store.increment("data", 12) # => 14

# --- increment and expire after 31 seconds
cache_store.incrmeent("data", expires_in: 31) # => 15

# --- increment nonexistent entry (create new entry) ---
cache_store.increment("another_data", 5, expires_in: 5) # => 5

# --- read incrementable entry ---
cache_store.read("data", raw: true) # you must provide :raw => true for incrementable entries

---

Decrement

• AnyCache#decrement(key, amount = 1, [expires_in:]) - decrement entry's value by the given amount and set the new expiration time if needed;
  • can decrement only nonexistent entries OR entries that were written with raw: true option;

# --- decrement existing entry ---
cache_store.write("data", 15, raw: true) # you must provide :raw => true for decrementable entries

# --- decrement by default value (1) ---
cache_store.decrement("data") # => 14

# --- decrement by custom value ---
cache_store.decrement("data", 10) # => 4

# --- decrement and expire after 5 seconds
cache_store.decrememnt("data", expirs_in: 5) # => 3

# --- decrement nonexistent entry (create new entry) ---
cache_store.decrememnt("another_data", 2, expires_in: 10) # => -2 (or 0 for Dalli::Client)

# --- read decrementable entry ---
cache_store.read("data", raw: true) # you must provide :raw => true for decrementable entries

---

Expire

• AnyCache#expire(key, [expires_in:]) - expire entry immediately or set the new expiration time;

# --- expire immediately ---
cache_store.expire("data")

# --- set new expiration time (in seconds) --
cache_store.expire("data", expires_in: 36)

---

Persist

• AnyCache#persist(key) - change entry's expiration time to permanent;

# --- create temporal entry (30 seconds) ---
cache_store.write("data", { a: 1 }, expires_in: 30)

# --- remove entry expiration (make it permanent) ---
cache_store.persist("data")

---

Existence

• AnyCache#exist?(key) - determine if an entry exists;

# --- entry exists ---
cache_store.exist?("data") # => true

# --- entry does not exist ---
cache_store.exist?("another-data") # => false

---

Clear

• AnyCache#clear() - clear cache database;

# --- prepare cache data ---
cache_store.write("data", { a: 1, b: 2 })
cache_store.write("another_data", 123_456)

cache_store.read("data") # => { a: 1, b: 2 }
cache_store.read("another_data") # => 123_456

# --- clear cache ---
cache_store.clear

cache_store.read("data") # => nil
cache_store.read("another_data") # => nil

---

Cleanup

• AnyCache#cleanup() - remove expired entries from cache database (make sense only for :as_file_store and :as_memory_store cache clients);

# --- prepare cache data ---
cache_store.write("data", "123", expires_in: 5)
cache_store.write("another_data", "456", expires_in: 10)

# --- waiting for cache exiration (10 seconds) ---
cache_store.cleanup # remove expired entries from database (release disk space for example)

---

Plugins

AnyCache provides a set of plugins and an interface for controllable plugin registering and loading.

# --- show names of registered plugins ---
AnyCache.plugins # => array of strings

# --- load specific plugin ---
AnyCache.plugin(:plugin_name) # or AnyCache.plugin('plugin_name')

---

Build

• see bin/rspec

bin/rspec --test-redis # run specs with Redis
bin/rspec --test-redis-store # run specs with Redis::Store
bin/rspec --test-dalli # run specs with Dalli::Client
bin/rspec --test-as-redis-cache-store # run specs with ActiveSupport::Cache::RedisCacheStore
bin/rspec --test-as-dalli-store # run specs with ActiveSupport::Cache::DalliStore
bin/rspec --test-as-mem-cache-store # run specs with ActiveSupport::Cache::MemCacheStore
bin/rspec --test-as-file-store # run specs with ActiveSupport::Cache::FileStore
bin/rspec --test-as-memory-store # run specs with ActiveSupport::Cache::MemoryStore

---

Roadmap

• centralized Logging API (core API);
• instrumentation layer (public API);
• more robust delegation API (core API);
• global and configurable default expiration time (public API);
• #delete_matched for memcached-based cache storages (core/public API);
• rails integration (public API);

---

Contributing

• Fork it (https://github.com/0exp/any_cache/fork)
• Create your feature branch (git checkout -b feature/my-new-feature)
• Commit your changes (git commit -am 'Add some feature')
• Push to the branch (git push origin feature/my-new-feature)
• Create new Pull Request

License

Released under MIT License.

Authors

Created by Rustam Ibragimov