cached_resource 2.2.0 → 2.3.0

data/README.md

@@ -8,14 +8,12 @@ CachedResource is a Ruby gem whose goal is to increase the performance of intera
 CachedResource has been tested with the following Ruby versions:
 
 * 1.8.7
-* 1.9.2
-* 1.9.3
+* 1.9.2, 1.9.3
 
 CachedResource is designed to be framework agnostic, but will hook into Rails for caching and logging.  If there is a `Rails.cache` and/or a `Rails.logger`, then it _should_ be OK.  It is known to work with the following Rails versions:
 
 * 3.1.3
-* 3.2.2
-* 3.2.3
+* 3.2.2, 3.2.3
 
 ## Configuration
 **Set up CachedResource across all ActiveResources:**
@@ -35,14 +33,16 @@ CachedResource accepts the following options:
 
 * `:enabled` Default: `true`
 * `:ttl` The time in seconds until the cache should expire. Default: `604800`
-* `:collection_synchronize` Use collections to generate cache entries for individuals.  Update the existing cached principal collection with new individuals.  Default: `false`
+* `:ttl_randomization` Enable ttl randomization. Default: `false`
+* `:ttl_randomization_scale` A Range from which a random value will be selected to scale the ttl. Default: `1..2`
+* `:collection_synchronize` Use collections to generate cache entries for individuals.  Update the existing cached principal collection when retrieving subsets of the principal collection or individuals.  Default: `false`
 * `:collection_arguments` The arguments that identify the principal collection request. Default: `[:all]`
 * `:logger` The logger to which CachedResource messages should be written. Default: The `Rails.logger` if available, or an `ActiveSupport::BufferedLogger`
 * `:cache` The cache store that CacheResource should use. Default: The `Rails.cache` if available, or an `ActiveSupport::Cache::MemoryStore`
 
 You can set them like this:
 
-	cached_resource :cache => MyCacheStore.new, :ttl => 60, :collection_synchronize => true, :logger => MyLogger.new, :enabled => false
+	cached_resource :cache => MyCacheStore.new, :ttl => 60, :collection_synchronize => true, :logger => MyLogger.new
 
 You can also change them on the fly.
 
@@ -58,11 +58,19 @@ Set the cache expiry time to 60 seconds.
 
 	MyActiveResource.cached_resource.ttl = 60
 
+Enable cache expiry time randomization, allowing it to fall randomly between 60 and 120 seconds.
+
+	MyActiveResource.cached_resource.ttl_randomization = true
+
+Change the cache expiry time randomization scale so that the cache expiry time falls randomly between 30 and 180 seconds.
+
+	MyActiveResource.cached_resource.ttl_randomization_scale = 0.5..3
+
 Enable collection synchronization.  This will cause a call to `MyActiveResource.all` to also create cache entries for each of its members.  So, for example, a later call to `MyActiveResource.find(1)` will be read from the cache instead of requested from the remote service.
 
 	MyActiveResource.cached_resource.collection_synchronize = true
 
-Change the arguments that identify the principal collection request.  If for some reason you are concerned with a collection that is retrieved at a non-standard URL, you may specify the Ruby arguments that produce that URL.  When `collection_synchronize` is `true`, the collection returned from a request that matches these arguments will be cached and later updated when one of its members is retrieved.
+Change the arguments that identify the principal collection request.  If for some reason you are concerned with a collection that is retrieved at a "non-standard" URL, you may specify the Ruby arguments that produce that URL.  When `collection_synchronize` is `true`, the collection returned from a request that matches these arguments will be cached and later updated when one of its members or a subset is retrieved.
 
 	MyActiveResource.cached_resource.collection_arguments = [:all, :params => {:name => "Bob"}]
 
@@ -104,7 +112,6 @@ Feedback is greatly appreciated! Check out this project's [issue tracker](https:
 This may change at any time.
 
 * Callbacks on before and after reload
-* Cache expiry randomization
 * Consider checksums to improve the determination of freshness/changédness
 
 

data/lib/cached_resource/caching.rb

@@ -92,7 +92,7 @@ module CachedResource
       # The key is processed to make sure it is valid.
       def cache_write(key, object)
         key = cache_key(Array(key)) unless key.is_a? String
-        result = cached_resource.cache.write(key, object, :expires_in => cached_resource.ttl)
+        result = cached_resource.cache.write(key, object, :expires_in => cached_resource.generate_ttl)
         result && cached_resource.logger.info("#{CachedResource::Configuration::LOGGER_PREFIX} WRITE #{key}")
         result
       end

data/lib/cached_resource/configuration.rb

@@ -16,6 +16,8 @@ module CachedResource
     # defaults. The following options exist for cached resource:
     # :enabled, default: true
     # :ttl, default: 604800
+    # :ttl_randomization, default: false,
+    # :ttl_randomization_scale, default: 1..2,
     # :collection_synchronize, default: false,
     # :collection_arguments, default: [:all]
     # :cache, default: Rails.cache or ActiveSupport::Cache::MemoryStore.new,
@@ -24,6 +26,8 @@ module CachedResource
       super({
         :enabled => true,
         :ttl => 604800,
+        :ttl_randomization => false,
+        :ttl_randomization_scale => 1..2,
         :collection_synchronize => false,
         :collection_arguments => [:all],
         :cache => defined?(Rails.cache)  && Rails.cache || CACHE,
@@ -31,6 +35,13 @@ module CachedResource
       }.merge(options))
     end
 
+    # Determine the time until a cache entry should expire.  If ttl_randomization
+    # is enabled, then a the set ttl will be multiplied by a random
+    # value from ttl_randomization_scale.
+    def generate_ttl
+      ttl_randomization && randomized_ttl || ttl
+    end
+
     # Enables caching.
     def on!
       self.enabled = true
@@ -41,6 +52,20 @@ module CachedResource
       self.enabled = false
     end
 
-  end
-end
+    private
+
+    # Get a randomized ttl value between ttl * ttl_randomization_scale begin
+    # and ttl * ttl_randomization_scale end
+    def randomized_ttl
+      ttl * sample_range(ttl_randomization_scale)
+    end
+
+    # Choose a random value from within the given range, optionally
+    # seeded by seed.
+    def sample_range(range, seed=nil)
+      srand seed if seed
+      rand * (range.end - range.begin) + range.begin
+    end
 
+  end
+end

data/lib/cached_resource/version.rb

@@ -1,3 +1,3 @@
 module CachedResource
-  VERSION = "2.2.0"
+  VERSION = "2.3.0"
 end

data/spec/cached_resource/caching_spec.rb

@@ -2,7 +2,7 @@ require 'spec_helper'
 
 describe CachedResource do
 
-  before(:all) do
+  before(:each) do
     class Thing < ActiveResource::Base
       self.site = "http://api.thing.com"
       cached_resource
@@ -17,7 +17,7 @@ describe CachedResource do
     @other_thing_json = @other_thing.to_json
   end
 
-  after(:all) do
+  after(:each) do
     Thing.cached_resource.cache.clear
     Object.send(:remove_const, :Thing)
   end
@@ -229,6 +229,27 @@ describe CachedResource do
         Thing.cached_resource.cache.read("thing/all")[0].name.should_not == result.name
       end
     end
+
+    describe "when ttl randomization is enabled" do
+      before(:each) do
+        @ttl = 1
+        Thing.cached_resource.ttl = @ttl
+        Thing.cached_resource.ttl_randomization = true
+        Thing.cached_resource.send(:sample_range, 1..2, @ttl)
+        # next ttl 1.72032449344216
+      end
+
+      it "should generate a random ttl" do
+        Thing.cached_resource.cache.should_receive(:write)
+        Thing.cached_resource.cache.stub(:write) do |key, value, options|
+          # we know the ttl should not be the same as the set ttl
+          options[:expires_in].should_not == @ttl
+        end
+
+        Thing.find(1)
+      end
+
+    end
   end
 
   describe "when disabled" do

data/spec/cached_resource/configuration_spec.rb

@@ -110,22 +110,8 @@ describe "CachedResource::Configuration" do
       Foo.cached_resource.object_id.should_not == Bar.cached_resource.object_id
     end
 
-    it "they should have the same cache" do
-      Foo.cached_resource.cache.should == Bar.cached_resource.cache
-      Foo.cached_resource.cache.object_id.should == Bar.cached_resource.cache.object_id
-    end
-
-    it "they should have the same ttl" do
-      Foo.cached_resource.ttl.should == Bar.cached_resource.ttl
-    end
-
-    it "they should have the same logger" do
-      Foo.cached_resource.logger.should == Bar.cached_resource.logger
-      Foo.cached_resource.logger.object_id.should == Bar.cached_resource.logger.object_id
-    end
-
-    it "they should have the same enablement" do
-      Foo.cached_resource.enabled.should == Bar.cached_resource.enabled
+    it "they should have the same attributes" do
+      Foo.cached_resource.instance_variable_get(:@table).should == Bar.cached_resource.instance_variable_get(:@table)
     end
 
   end
@@ -181,8 +167,7 @@ describe "CachedResource::Configuration" do
     end
 
     it "should have the specified options" do
-      cr = Foo.cached_resource
-      cr.ttl.should == 60
+      Foo.cached_resource.ttl.should == 60
     end
 
     it "should have the default options for anything unspecified" do
@@ -193,8 +178,42 @@ describe "CachedResource::Configuration" do
       cr.collection_synchronize.should == false
       cr.collection_arguments.should == [:all]
       cr.custom.should == nil
+      cr.ttl_randomization.should == false
+      cr.ttl_randomization_scale.should == (1..2)
     end
 
   end
 
+  # At the moment, not too keen on implementing some fancy
+  # randomness validator.
+  describe "when ttl randomization is enabled" do
+    before(:each) do
+      @ttl = 1
+      configuration.ttl = @ttl
+      configuration.ttl_randomization = true
+      configuration.send(:sample_range, 1..2, @ttl)
+      # next ttl: 1.72032449344216
+    end
+
+    it "it should produce a random ttl between ttl and ttl * 2" do
+      generated_ttl = configuration.generate_ttl
+      generated_ttl.should_not == 10
+      (@ttl..(2 * @ttl)).should include(generated_ttl)
+    end
+
+    describe "when a ttl randomization scale is set" do
+      before(:each) do
+        @lower = 0.5
+        @upper = 1
+        configuration.ttl_randomization_scale = @lower..@upper
+        # next ttl 0.860162246721079
+      end
+
+      it "should produce a random ttl between ttl * lower bound and ttl * upper bound" do
+        lower = @ttl * @lower
+        upper = @ttl * @upper
+        (lower..upper).should include(configuration.generate_ttl)
+      end
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cached_resource
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-08 00:00:00.000000000 Z
+date: 2012-05-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &70156223360120 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,15 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *70156223360120
 - !ruby/object:Gem::Dependency
   name: activeresource
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &70156223383920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -37,15 +32,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *70156223383920
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &70156223383060 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -53,15 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *70156223383060
 - !ruby/object:Gem::Dependency
   name: nilio
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &70156223382540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -69,15 +54,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *70156223382540
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: !ruby/object:Gem::Requirement
+  requirement: &70156223382020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -85,12 +65,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+  version_requirements: *70156223382020
 description: Enables request-based caching for ActiveResource
 email: email@suspi.net
 executables: []
@@ -133,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.21
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
 summary: Caching for ActiveResource
@@ -141,4 +116,3 @@ test_files:
 - spec/cached_resource/caching_spec.rb
 - spec/cached_resource/configuration_spec.rb
 - spec/spec_helper.rb
-has_rdoc: