ShieldedCache

ShieldedCache

ShieldedCache is a caching module for Elixir.

What Makes It Special?

ShieldedCache enables a type of CDN Shielding on your cache that allows you to return stale results while simultaneously refreshing your data. This allows you to always return data to your client incredibly fast after the first request is made, while still refreshing data in an async way to keep subsequent requests fresh.

Installation

If available in Hex, the package can be installed by adding shielded_cache to your list of dependencies in mix.exs:

def deps do
  [
    {:shielded_cache, ">= 0.0.0"}
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://spotim.hexdocs.pm/shielded_cache.

Usage

To use the ShieldedCache, simply add use ShieldedCache along with the necessary options to the top of your module, and define the fetch/1 callback, which is used to fetch the data for the cache.

There are two options you must define: cache_name and caching_module, and one optional option, ttl.

cache_name is the identifier of your cache, and should be an atom (in the form of a module name, see the example below).

caching_module is the module used for cache storage. This module should conform to the ShieldedCache.Cache behaviour, which will enforce the necessary functions for the cache, and what their return types should be.

ttl is the number of millisecods until the values in the cache expire, which defaults to 10_000.

There are currently 3 caching modules built in to the ShieldedCache library: ShieldedCache.Cache.LocalAgent, ShieldedCache.Cache.Redis, and ShieldedCache.Cache.RedixSingleton.

If using ShieldedCache.Cache.RedixSingleton, you must also define a third option: caching_module_name. This defines the name of the Redix process that you would like to use as your client to your Redis instance.

ShieldedCache.Cache.LocalAgent

This caching module stores your caching data in an Elixir Agent process supervised by the cache supervisor.

ShieldedCache.Cache.Redis

This caching module initializes a pool of Redix clients for the specified cache, and stores your caching data in Redis.

Configuration Options

There are two configuration options available here: redis_pool_size, which defaults to 1, and redis_url, which defaults to redis://localhost:6379.

To configure these, add the following to your config.exs:

config :shielded_cache,
  redis_url: "<YOUR REDIS URL>",
  redis_pool_size: <YOUR REDIS POOL SIZE AS INTEGER>,

ShieldedCache.Cache.RedisCluster

This caching module initializes a pool of Redix clients for the specified cache, and stores your caching data in a Redis cluster (see Redis Cluster).

Configuration Options

This caching module is built on top of the redix_cluster library, which was forked, modernized, fixed, and refactored recently by Spot.IM.

With this library, there are various configuration options available: cluster_nodes, which defaults to an empty list, pool_size, which defaults to 5, and pool_max_overflow, which defaults to 0.

To configure these, add the following to your config.exs (Note the name of the application is redix_cluster and not shielded_cache):

config :redix_cluster,
  cluster_nodes: [
    %{host: "myredishost", port: 6379}
  ],
  pool_size: 5,
  pool_max_overflow: 0

ShieldedCache.Cache.RedixSingleton

This caching module assumes that you have already created a Redix client, and utilizes it when making calls to the cache.

If using this caching module, you must also define a third option to your cache: caching_module_name. This defines the name of the Redix process that you would like to use as your client to your Redis instance.

Simple Caching Example

The following is a simple caching module that uses the built in ShieldedCache.Cache.LocalAgent caching module.

defmodule ExampleShieldedCache do
  use ShieldedCache,
    cache_name: ExampleShieldedCache,
    caching_module: ShieldedCache.Cache.LocalAgent

  def fetch(cache_request) do
    {:ok, "WOW #{DateTime.utc_now()}"}
  end
end