composite_cache_store 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 689876c5fc7b2bd00343817eac73b522a0687482aaaeb1058a471c7fcac275e7
-  data.tar.gz: dba46b9f25d1302377dd0fb64c9765a8c6016545f78fdb57444282e6b4d94cd8
+  metadata.gz: 8e8b3140f8d6d37fd4b5c876b550863f13a4dc134142e1cbc7115c63d167a3d4
+  data.tar.gz: b16ced0803e2be6075d8fe80a6e532285a0f9aed1fef63a6d8cd0092563a1c9d
 SHA512:
-  metadata.gz: a04ad705343eea18cdd44d399cbd2264b11fa7eb91a6be8c0d98960b8937510abd77a780a95c816217bf2752cf7fde885dbf423b04aaee11024280876e19f994
-  data.tar.gz: 72bcee27ef6647b444582c481dfa011fedbb587d540537d193a3f1042965bf16e7cb740ed059f6483b7926afdd99dd2b84fe80715665ea8908dcf2c3efc1ca0f
+  metadata.gz: cdf5f5918114b2f7f148be7518131ed141df10ee1d8d6f0c5096859e3185b0f0698c9df1b47e9dd0525aeb9a8feb4113c28dff0538d281b417621711cc48f1a3
+  data.tar.gz: 2ed7a6b022cedcb8fa079e9d8d70a02b42c934b1d1b2d15bcc208c3480e422cc79e6ecdd039420f445103e08e4ca1f98b43f821054f6cd9624b88ac9766c5386

data/README.md

@@ -1,39 +1,53 @@
-# CompositeCacheStore
-
-### A composite cache store comprised of layered ActiveSupport::Cache::Store instances
+<p align="center">
+  <h1 align="center">CompositeCacheStore 🚀</h1>
+  <p align="center">
+    <a href="http://blog.codinghorror.com/the-best-code-is-no-code-at-all/">
+      <img alt="Lines of Code" src="https://img.shields.io/badge/loc-137-47d299.svg" />
+    </a>
+    <a href="https://codeclimate.com/github/hopsoft/composite_cache_store/maintainability">
+      <img src="https://api.codeclimate.com/v1/badges/80bcd3acced072534a3a/maintainability" />
+    </a>
+    <a href="https://rubygems.org/gems/composite_cache_store">
+      <img alt="GEM Version" src="https://img.shields.io/gem/v/composite_cache_store?color=168AFE&include_prereleases&logo=ruby&logoColor=FE1616">
+    </a>
+    <a href="https://rubygems.org/gems/composite_cache_store">
+      <img alt="GEM Downloads" src="https://img.shields.io/gem/dt/composite_cache_store?color=168AFE&logo=ruby&logoColor=FE1616">
+    </a>
+    <a href="https://github.com/testdouble/standard">
+      <img alt="Ruby Style" src="https://img.shields.io/badge/style-standard-168AFE?logo=ruby&logoColor=FE1616" />
+    </a>
+    <a href="https://github.com/hopsoft/composite_cache_store/actions/workflows/tests.yml">
+      <img alt="Tests" src="https://github.com/hopsoft/composite_cache_store/actions/workflows/tests.yml/badge.svg" />
+    </a>
+    <a href="https://github.com/sponsors/hopsoft">
+      <img alt="Sponsors" src="https://img.shields.io/github/sponsors/hopsoft?color=eb4aaa&logo=GitHub%20Sponsors" />
+    </a>
+    <br>
+    <a href="https://ruby.social/@hopsoft">
+      <img alt="Ruby.Social Follow" src="https://img.shields.io/mastodon/follow/000008274?domain=https%3A%2F%2Fruby.social&label=%40hopsoft&style=social">
+    </a>
+    <a href="https://twitter.com/hopsoft">
+      <img alt="Twitter Follow" src="https://img.shields.io/twitter/url?label=%40hopsoft&style=social&url=https%3A%2F%2Ftwitter.com%2Fhopsoft">
+    </a>
+  </p>
+  <h2 align="center">Boost application speed and maximize user satisfaction with layered caching</h2>
+</p>
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
 
-  - [Why a composite cache?](#why-a-composite-cache)
   - [Sponsors](#sponsors)
+  - [Why a composite cache?](#why-a-composite-cache)
+  - [Eventual consistentency](#eventual-consistentency)
   - [Dependencies](#dependencies)
   - [Installation](#installation)
   - [Setup](#setup)
-    - [Ruby on Rails](#ruby-on-rails)
   - [Usage](#usage)
   - [License](#license)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 
-## Why a composite cache?
-
-Most web applications implement some form of caching mechanics to improve performance.
-Sufficiently large applications often employ a persistence service to back the cache.
-_(Redis, Memcache, etc.)_ These services make it possible to use a shared cache between multiple machines/processes.
-
-While these services are robust and performant, they can also be a source of latency and are potential bottlenecks.
-__A composite (or layered) cache can mitigate these risks__
-by reducing traffic and backpressure on the persistence service.
-
-Consider a composite cache that wraps a remote Redis-backed "layer 2 cache" with a local in-memory "layer 1 cache".
-When both caches are warm, a read hit on the local in-memory "layer 1 cache" returns instantly and avoids the overhead of
-inter-process communication (IPC) and/or network traffic _(with its attendant data marshaling and socket/wire noise)_
-associated with accessing the remote Redis-backed "layer 2 cache".
-
-To summarize: __Reads prioritize the inner cache and fall back to the outer cache.__
-
 ## Sponsors
 
 <p align="center">
@@ -45,6 +59,48 @@ To summarize: __Reads prioritize the inner cache and fall back to the outer cach
   </a>
 </p>
 
+## Why a composite cache?
+
+Layered caching allows you to stack multiple caches with different scopes, lifetimes, and levels of reliability.
+A technique that yields several benefits.
+
+- __Improved performance__
+- __Higher throughput__
+- __Reduced load__
+- __Enhanced capacity/scalability__
+
+Inner cache layer(s) provide the fastest reads as they're close to the application, _typically in-memory within the same process_.
+Outer layers are slower _(still fast)_ but are shared by multiple processes and servers.
+
+<img height="250" src="https://ik.imagekit.io/hopsoft/composite_cache_store_jnHZcjAuK.svg?updatedAt=1679445477496" />
+
+You can configure each layer with different expiration times, eviction policies, and storage mechanisms.
+You're in control of balancing the trade-offs between performance and data freshness.
+
+__Inner layers are supersonic while outer layers are speedy.__
+
+The difference between a cache hit on a local in-memory store versus a cache hit on a remote store
+is similar to making a grocery run in a
+[Bugatti Chiron Super Sport 300+](https://www.bugatti.com/models/chiron-models/chiron-super-sport-300/)
+compared to making the same trip on a bicyle, but all cache layers will be much faster than the underlying operations.
+For example, a complete cache miss _(that triggers database queries and view rendering)_ would be equivalent to making this trip riding a sloth.
+
+## Eventual consistentency
+
+Layered caching techniques exhibit some of the same traits as [distributed systems](https://en.wikipedia.org/wiki/Eventual_consistency)
+because inner layers may hold onto __stale data__ until their entries expire.
+__Be sure to configure inner layers appropriately with shorter lifetimes__.
+
+This behavior is similar to the
+[`race_condition_ttl`](https://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html#method-i-fetch-label-Options)
+option in `ActiveSupport::Cache::Store` which helps to avoid race conditions whenever multiple threads/processes try to write to the same cache entry simultaneously.
+
+__Be mindful of the potential gotchas.__
+
+- __Data consistency__ - it's possible to end up with inconsistent or stale data
+- __Over-caching__ - caching too much can lead to increased memory usage and even slower performance
+- __Bugs/Testing__ - difficult bugs can be introduced with sophisticated caching techniques
+
 ## Dependencies
 
 - [ActiveSupport `>= 6.0`](https://github.com/rails/rails/tree/main/activesupport)
@@ -57,31 +113,39 @@ bundle add "composite_cache_store"
 
 ## Setup
 
-### Ruby on Rails
-
-```ruby
-# config/environments/production.rb
-module Example
-  class Application < Rails::Application
-    config.cache_store = :redis_cache_store, { url: "redis://example.com:6379/1" }
-  end
-end
-```
+Here's an example of how you might set up layered caching in a Rails application.
 
 ```ruby
 # config/initializers/composite_cache_store.rb
 def Rails.composite_cache
   @composite_cache ||= CompositeCacheStore.new(
-    # Layer 1 cache (inner) - employs an LRU eviction policy
-    ActiveSupport::Cache::MemoryStore.new(
-      expires_in: 15.minutes, # constrain entry lifetime so the local cache doesn't drift out of sync
-      size: 32.megabytes # constrain max memory used by the local cache
-    ),
-
-    # Layer 2 cache (outer)
-    Rails.cache, # use whatever makes sense for your app
-
-    # additional layers are optional
+    layers: [
+      # Layer 1 cache (fastest)
+      # Most beneficial for high traffic volume
+      # Isolated to the process running an application instance
+      ActiveSupport::Cache::MemoryStore.new(
+        expires_in: 15.minutes,
+        size: 32.megabytes
+      ),
+
+      # Layer 2 cache (faster)
+      # Most beneficial for moderate traffic volume
+      # Isolated to the machine running N-number of application instances,
+      # and shared by all application processes on the machine
+      ActiveSupport::Cache::RedisCacheStore.new(
+        url: "redis://localhost:6379/0",
+        expires_in: 2.hours
+      ),
+
+      # Layer 3 cache (fast)
+      # Global cache shared by all application processes on all machines
+      ActiveSupport::Cache::RedisCacheStore.new(
+        url: "redis://remote.example.com:6379/0",
+        expires_in: 7.days
+      ),
+
+      # additional layers are optional
+    ]
   )
 end
 ```
@@ -91,12 +155,18 @@ end
 A composite cache is ideal for mitigating hot spot latency in frequently invoked areas of the codebase.
 
 ```ruby
-# method that's invoked frequently by multiple processes
+# method that's invoked frequently by multiple processes/machines
 def hotspot
-  # NOTE: expiration options are only applied to the outermost cache
-  #       inner caches use their globally configured expiration policy
-  Rails.composite_cache.fetch("example/slow/operation", expires_in: 12.hours) do
-    # a slow operation
+  Rails.composite_cache.fetch("example", expires_in: 12.hours) do
+    # reserve for high frequency access of slow operations
+    #
+    # examples:
+    # - api invocations
+    # - database queries
+    # - template renders
+    # - etc.
+
+    frequently_accessed_slow_operation
   end
 end
 ```

data/Rakefile

@@ -2,9 +2,38 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
+require "paint"
+
+# versions of rails to test against
+rails_versions = %w[
+  v5.2.8.1
+  v6.1.7.3
+  v7.0.4.3
+  edge
+]
 
 task default: :test
 
-Minitest::TestTask.create(:test) do |t|
+Minitest::TestTask.create(:minitest) do |t|
   t.test_globs = ["test/**/*_test.rb"]
 end
+
+task :test do
+  ENV["COMPOSITE_CACHE_STORE_ENV"] = "test"
+  rails_versions.each do |rails_version|
+    ENV["RAILS_VERSION"] = (rails_version == "edge") ? nil : rails_version
+    puts Paint % ["Bundling activesupport %{version} from github ", :blue, :underline, version: [rails_version, "sky blue", :underline]]
+    print Paint["required for tests provided by rails... ", "slate gray"]
+    `bundle update activesupport`
+    puts "done!\n\n"
+    Rake::Task["minitest"].invoke
+    Rake::Task["minitest"].reenable unless rails_version == rails_versions.last
+  end
+ensure
+  if ENV["GITHUB_ACTIONS"] != "true"
+    ENV["COMPOSITE_CACHE_STORE_ENV"] = nil
+    print Paint["Restoring bundle with activesupport from rubygems... ", :blue]
+    `bundle update activesupport`
+    puts "done!"
+  end
+end

data/lib/composite_cache_store/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class CompositeCacheStore
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/lib/composite_cache_store.rb

@@ -4,146 +4,172 @@ require "active_support/all"
 require_relative "composite_cache_store/version"
 
 class CompositeCacheStore
-  DEFAULT_LAYER_1_OPTIONS = {
-    expires_in: 5.minutes,
-    size: 16.megabytes
-  }
-
-  DEFAULT_LAYER_2_OPTIONS = {
-    expires_in: 1.day,
-    size: 32.megabytes
-  }
-
-  attr_reader :layers
+  attr_reader :options, :layers
+  attr_accessor :logger
 
   # Returns a new CompositeCacheStore instance
-  def initialize(*layers)
-    if layers.blank?
-      layers << ActiveSupport::Cache::MemoryStore.new(DEFAULT_LAYER_1_OPTIONS)
-      layers << ActiveSupport::Cache::MemoryStore.new(DEFAULT_LAYER_2_OPTIONS)
-    end
+  def initialize(options = {})
+    options = options.dup || {}
+    layers = options.delete(:layers) || []
+
+    raise ArgumentError.new("A layered cache requires more than 1 layer!") unless layers.size > 1
 
-    message = "All layers must be instances of ActiveSupport::Cache::Store"
-    layers.each do |layer|
-      raise ArgumentError.new(message) unless layer.is_a?(ActiveSupport::Cache::Store)
+    unless layers.all? { |layer| layer.is_a? ActiveSupport::Cache::Store }
+      raise ArgumentError.new("All layers must be instances of ActiveSupport::Cache::Store!")
     end
 
-    layers.freeze
-    @layers = layers
+    @layers = layers.freeze
+    @logger = options[:logger]
+    @options = options
   end
 
-  def cleanup(...)
-    layers.each { |store| store.cleanup(...) }
+  def read(name, options = nil)
+    value = nil
+    warm_layer = layers.find { |layer| layer_read?(layer, name, options) { |val| value = val } }
+    yield(value, warm_layer) if block_given?
+    value
   end
 
-  def clear(...)
-    layers.each { |store| store.clear(...) }
+  def read_multi(*names)
+    value = {}
+    warm_layer = layers.find { |layer| layer_read_multi?(layer, *names) { |val| value.merge!(val) } }
+    yield(value, warm_layer) if block_given?
+    value
   end
 
-  def decrement(...)
-    layers.each { |store| store.decrement(...) }
+  def fetch(name, options = nil, &block)
+    options ||= {}
+
+    if options[:force]
+      raise ArgumentError, "Missing block: Calling `Cache#fetch` with `force: true` requires a block." unless block
+      value = block&.call(name)
+      layers.each { |layer| layer.write(name, value, options) }
+      return value
+    end
+
+    read(name, options) do |value, warm_layer|
+      value ||= block&.call(name) unless warm_layer
+
+      layers.each do |layer|
+        break if layer == warm_layer
+        layer.write(name, value, options) unless value.nil? && options[:skip_nil]
+      end
+
+      return value
+    end
   end
 
-  def delete(...)
-    layers.each { |store| store.delete(...) }
+  def fetch_multi(*names, &block)
+    raise ArgumentError, "Missing block: `Cache#fetch_multi` requires a block." unless block
+
+    keys = names.dup
+    options = keys.extract_options!
+
+    if options[:force]
+      value = keys.each_with_object({}) { |key, memo| memo[key] = block&.call(key) }
+      layers.each { |layer| layer.write_multi(value, options) }
+      return value
+    end
+
+    read_multi(*names) do |value, warm_layer|
+      unless warm_layer
+        missing_keys = keys - value.keys
+        missing_keys.each { |key| value[key] = block&.call(key) }
+      end
+
+      value.compact! if options[:skip_nil]
+
+      layers.each do |layer|
+        break if layer == warm_layer
+        layer.write_multi(value, options)
+      end
+
+      # return ordered hash value
+      return keys.each_with_object({}) { |key, memo| memo[key] = value[key] }
+    end
   end
 
-  def delete_matched(...)
-    layers.each { |store| store.delete_matched(...) }
+  def write(name, value, options = nil)
+    layers.map { |layer| layer.write(name, value, options) }.last
   end
 
-  def delete_multi(...)
-    layers.each { |store| store.delete_multi(...) }
+  def write_multi(hash, options = nil)
+    layers.map { |layer| layer.write_multi(hash, options) }.last
   end
 
-  def exist?(...)
-    layers.each do |store|
-      return true if store.exist?(...)
-    end
-    false
+  def delete(...)
+    layers.map { |layer| layer.delete(...) }.last
   end
 
-  def fetch(*args, &block)
-    f = ->(store) do
-      return store.fetch(*args, &block) if store == layers.last
-      store.fetch(*args) { f.call(layers[layers.index(store) + 1]) }
-    end
-    f.call(layers.first)
+  def delete_multi(...)
+    layers.map { |layer| layer.delete_multi(...) }.last
   end
 
-  def fetch_multi(*args, &block)
-    fm = ->(store) do
-      return store.fetch_multi(*args, &block) if store == layers.last
-      store.fetch_multi(*args) { fm.call(layers[layers.index(store) + 1]) }
-    end
-    fm.call(layers.first)
+  def delete_matched(...)
+    layers.map { |layer| layer.delete_matched(...) }.last
   end
 
-  def increment(...)
-    layers.each { |store| store.increment(...) }
+  def increment(name, amount = 1, options = nil)
+    provisional_layers.each { |layer| layer.delete(name, options) }
+    layers.last.increment(name, amount, options)
   end
 
-  def mute
-    m = ->(store) do
-      return store.mute { yield } if store == layers.last
-      store.mute { m.call(layers[layers.index(store) + 1]) }
-    end
-    m.call(layers.first)
+  def decrement(name, amount = 1, options = nil)
+    provisional_layers.each { |layer| layer.delete(name, options) }
+    layers.last.decrement(name, amount, options)
   end
 
-  def read(*args)
-    r = ->(store) do
-      return store.read(*args) if store == layers.last
-      store.fetch(*args) { r.call(layers[layers.index(store) + 1]) }
-    end
-    r.call(layers.first)
+  def cleanup(...)
+    layers.map { |layer| layer.cleanup(...) }.last
   end
 
-  def read_multi(...)
-    missed_layers = []
-    layers.each do |store|
-      hash = store.read_multi(...)
-      if hash.present?
-        missed_layers.each { |s| s.write_multi(hash) }
-        return hash
-      end
-      missed_layers << store
-    end
-    {}
+  def clear(...)
+    layers.map { |layer| layer.clear(...) }.last
   end
 
-  def silence!
-    layers.each { |store| store.silence! }
+  def exist?(...)
+    layers.any? { |layer| layer.exist?(...) }
   end
 
-  def write(name, value, options = nil)
-    layers.each do |store|
-      store.write name, value, permitted_options(store, options)
-    end
+  def mute
+    layers.map { |layer| layer.mute { yield } }.last
   end
 
-  def write_multi(hash, options = nil)
-    layers.each do |store|
-      store.write_multi hash, permitted_options(store, options)
-    end
+  def silence!
+    layers.map { |layer| layer.silence! }.last
   end
 
   private
 
-  def permitted_options(store, options = {})
-    return options if options.blank?
-    return options if keep_expiration?(store, options)
-    options.except(:expires_in, :expires_at)
+  def provisional_layers
+    layers.take layers.size - 1
+  end
+
+  def layer_read?(layer, name, options)
+    if layer.respond_to?(:with_local_cache)
+      layer.with_local_cache do
+        value = layer.read(name, options)
+        yield value
+        value || layer.exist?(name, options)
+      end
+    else
+      value = layer.read(name, options)
+      yield value
+      value || layer.exist?(name, options)
+    end
   end
 
-  def keep_expiration?(store, options = {})
-    return true if store == layers.last
-    return true unless store.options[:expires_in]
+  def layer_read_multi?(layer, *names)
+    keys = names.dup
+    keys.extract_options!
 
-    expires_in = options[:expires_in]
-    expires_in ||= Time.current - options[:expires_at] if options[:expires_at]
-    return false unless expires_in
+    value = if layer.respond_to?(:with_local_cache)
+      layer.with_local_cache { layer.read_multi(*names) }
+    else
+      layer.read_multi(*names)
+    end
 
-    expires_in < store.options[:expires_in]
+    yield value
+    value.size == keys.size
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: composite_cache_store
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-14 00:00:00.000000000 Z
+date: 2023-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -52,6 +52,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
@@ -67,7 +81,49 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: standardrb
+  name: pry-doc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: tocer
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="