scoped_cache_keys 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b96bac82675a12d0d185510840185d0829a897d4f08242ccf94922cfa45d1afd
-  data.tar.gz: 87efd06a51cf71fb41d3b8193ed8f5f56378951101c8ffa341910e82e26c2386
+  metadata.gz: 599264adc7feb1e042fde17a4473126615907cfd03e27172d9355f9c5dfc6308
+  data.tar.gz: bd9335f025963374103c7fd8a0a897606e977b02568ba1a5816cc55a7f8f9afd
 SHA512:
-  metadata.gz: a62968c83bfddb74ad349eaf0865700e65186bbc28bdcfdefbf156dfb00956e2b611ff0a2f5c4ca9b92653fb0442b2f99f91ef6908b33cf6bef7f035b941e96d
-  data.tar.gz: 3eb0de9f214f5855fc0d21cd3bbe1b8e504f68d428f92902ffbd6ea96895d12990cc275087e14eefc24fd595f5bb593fada8c27c8d1c676c3b91c350d612b90c
+  metadata.gz: 9740614f52aeb1c14a7462ac11c1c4a496146402a7973f76991651bd3480ebf2e95754af17962ebecb2f1dab544fe56c7555f86b0d578be7032f374acbe26bf2
+  data.tar.gz: 9d2dc9a88572ef4991280a50bd9c764041d96d9996f8bc548b07cde2ecc614d7e5a619979099cc92c33af497b79816cfc5c8691fa0f56bd681261bd49bc058fc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    scoped_cache_keys (0.2.0)
+    scoped_cache_keys (0.3.0)
 
 GEM
   remote: https://rubygems.org/

data/Readme.md

@@ -1,16 +1,92 @@
-Add scoped_cache_key / expire_scoped_cache_key to your models for caching/sweeping of model-related caches.
+scoped_cache_keys
+=================
+
+Add `scoped_cache_key` / `expire_scoped_cache_key` to your models for caching/sweeping of model-related caches.
+
+Overview
+--------
+
+`scoped_cache_keys` enables you to "scope" multiple cache entries together, such that they can be expired
+together in a single operation.
+
+This saves the trouble of having to delete several individual cache entries, and improves the consistency
+of your cache entries by having them all expire together.
+
+Model-related caches in a Rails application often consist of multiple cache entries, which should be
+consistent with each other.
+
+For instance, you might have a cache entry which is a key->value mapping for a model, but another
+cache entry which is a value->key mapping.
 
 Install
-=======
+-------
 
 ```bash
 gem "scoped_cache_keys"
 ```
 
 Usage
-=====
+-----
+
+To use `scoped_cached_keys`, use `include ScopedCacheKeys` in your model declaration:
+
+```ruby
+class User < ActiveRecord::Base
+  include ScopedCacheKeys
+  ...
+end
+```
+
+### scoped_cache_key ###
+
+The `scoped_cache_key` method returns a key that will change whenever `expire_scoped_cache_key` is called.
+The cache key will be scoped to the model object that `scoped_cache_key` is invoked on, along with
+whatever scope is passed:
+
+```ruby
+  account.scoped_cache_key(:orders)
+```
+
+Options: Any caching options that are passed to `Rails.cache` methods may be passed to `scoped_cache_key`.
+For example:
+
+```ruby
+  account.scoped_cache_key(:orders, expires_in: 10.minutes)
+```
+
+The key that is returned can be treated as a "base key," that is, concatenated with other strings to form
+other cache keys. All such cache keys will become unreachable, and thus "expired," when
+`expire_scoped_cache_key` is called.
+
+### expire_scoped_cache_key ###
+
+The `expire_scoped_cache_key` method will expire a scoped cache key obtained with `scoped_cache_key`.
+Example:
+
+```ruby
+  account.expire_scoped_cache_key(:orders)
+```
+
+Options: The optional `delay` parameter specifies an amount of time to delay before actually expiring
+the scoped cache key. Example:
+
+```ruby
+  account.expire_scoped_cache_key(:orders, delay: 5.seconds)
+```
+
+The `delay` parameter can be useful for contending with database replication lag. When many concurrent 
+processes access the scoped cache entries, one or more may immediately try to rebuild the cache
+the instant that `expire_scoped_cache_key` completes. This could happen so quickly that the database
+replicas may not be caught up with the model changes that were just committed. Alternately, one
+could force the models to be queried from the primary database to avoid such race conditions.
+
+The expiration delay may also be set at a global level:
+
+```ruby
+    ScopedCacheKeys.expire_scoped_cache_key_delay = 10.seconds
+```
 
-Gives you a key that will change whenever expire_scoped_cache_key is called.
+### Example ###
 
 ```
     <% cache user.scoped_cache_key :products do %>
@@ -34,7 +110,7 @@ Gives you a key that will change whenever expire_scoped_cache_key is called.
 ```
 
 Author
-======
+------
 [Zendesk](http://zendesk.com)<br/>
 michael@grosser.it<br/>
 License: MIT

data/lib/scoped_cache_keys/version.rb

@@ -1,3 +1,3 @@
 module ScopedCacheKeys
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/scoped_cache_keys.rb

@@ -1,13 +1,26 @@
 require 'scoped_cache_keys/version'
 
 module ScopedCacheKeys
+  class << self
+    # If set, expire_scoped_cache_key will delay expiration by this many seconds
+    # globally.
+    attr_accessor :expire_scoped_cache_key_delay
+  end
+
   def scoped_cache_key(scope, options = nil)
     base_key = Rails.cache.fetch(build_scoped_cache_key([scope]), options) { Time.now.to_f }
     build_scoped_cache_key [scope, base_key]
   end
 
-  def expire_scoped_cache_key(scope)
-    Rails.cache.delete(build_scoped_cache_key(scope))
+  def expire_scoped_cache_key(scope, delay: nil)
+    delay ||= ScopedCacheKeys.expire_scoped_cache_key_delay
+    key = build_scoped_cache_key(scope)
+    if delay
+      entry = Rails.cache.read(key)
+      Rails.cache.write(key, entry, expires_in: delay) if entry
+    else
+      Rails.cache.delete(key)
+    end
   end
 
   private

data/spec/scoped_cache_keys_spec.rb

@@ -45,6 +45,12 @@ describe ScopedCacheKeys do
         user.updated_at = 1.week.ago
       }.to_not change{ user.scoped_cache_key(:foo) }
     end
+
+    it "accepts cache options such as expired_in" do
+      key = user.scoped_cache_key(:foo, expires_in: 10.seconds)
+      Timecop.travel(11.seconds.from_now)
+      user.scoped_cache_key(:foo).should_not == key
+    end
   end
 
   describe "#expire_scoped_cache_key" do
@@ -59,5 +65,25 @@ describe ScopedCacheKeys do
         user.expire_scoped_cache_key :bar
       }.to_not change{ user.scoped_cache_key(:foo) }
     end
+
+    it "expires a specific scope after a specified delay" do
+      key = user.scoped_cache_key :foo
+      user.expire_scoped_cache_key :foo, delay: 5.seconds
+      Timecop.travel(4.seconds.from_now)
+      user.scoped_cache_key(:foo).should == key
+      Timecop.travel(2.seconds.from_now)
+      user.scoped_cache_key(:foo).should_not == key
+    end
+
+    it "expires a specific scope after a specified global delay" do
+      ScopedCacheKeys.expire_scoped_cache_key_delay = 10.seconds
+      key = user.scoped_cache_key :foo
+      user.expire_scoped_cache_key :foo
+      Timecop.travel(9.seconds.from_now)
+      user.scoped_cache_key(:foo).should == key
+      Timecop.travel(2.seconds.from_now)
+      user.scoped_cache_key(:foo).should_not == key
+      ScopedCacheKeys.expire_scoped_cache_key_delay = nil
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: scoped_cache_keys
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Grosser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-11-02 00:00:00.000000000 Z
+date: 2022-12-02 00:00:00.000000000 Z
 dependencies: []
 description: 
 email: michael@grosser.it