cache-flow 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1faaeb46dbeead28ac84f7239bf0250f59ab9f07
-  data.tar.gz: 1edf5ec8dc2281d998a178069dbf9627a48ea708
+  metadata.gz: 3d7b21c0d817d299288b5ea34aaa1719a5e840bf
+  data.tar.gz: e9d850f930165b67041ba30ea54b2b274bfb3256
 SHA512:
-  metadata.gz: 43c598901b37528145c21c9ba1ab9a1926139a428ec4c0f8cfb802fd7df3d78d17e22ee9a02997fc94f852b8e53641447cfdff81af273863798c1b9b679bd855
-  data.tar.gz: ee94fae2c808f3fdfb3a58ec40437bfa691aefc04fa57302754fd54b1a10ed0352e298054089e13981e0d70aafcb5c3c66cec0871de98f02ff4079421d620f30
+  metadata.gz: a01f5246b7dd20757943cce80f9ec8934e4b1261801b8cbfede6bc15a17e9f2623bb7a45e85cbdf666bd45745845189bb8697b85591277f9664d7efe3ea0e5b3
+  data.tar.gz: 11af009a5d4924d12bb2dedbcc60ceb7b23e14ff64ec2d88fd279f8306e4b5a6604263f089ef18a4ba9cde452c7318c54e839d36d01395028031b44034f8dbfe

data/.rspec

@@ -0,0 +1,4 @@
+--colour
+--tty
+--format documentation
+--drb

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,43 @@
+PATH
+  remote: .
+  specs:
+    cache-flow (0.0.5)
+      activesupport (>= 3.1.0)
+      i18n (= 0.7.0)
+      tzinfo (= 0.3.38)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (4.0.3)
+      i18n (~> 0.6, >= 0.6.4)
+      minitest (~> 4.2)
+      multi_json (~> 1.3)
+      thread_safe (~> 0.1)
+      tzinfo (~> 0.3.37)
+    diff-lcs (1.2.5)
+    i18n (0.7.0)
+    minitest (4.7.5)
+    multi_json (1.11.0)
+    rspec (3.2.0)
+      rspec-core (~> 3.2.0)
+      rspec-expectations (~> 3.2.0)
+      rspec-mocks (~> 3.2.0)
+    rspec-core (3.2.2)
+      rspec-support (~> 3.2.0)
+    rspec-expectations (3.2.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-mocks (3.2.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.2.0)
+    rspec-support (3.2.2)
+    thread_safe (0.3.5)
+    tzinfo (0.3.38)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  cache-flow!
+  rspec (= 3.2.0)

data/Readme.markdown

@@ -0,0 +1,83 @@
+# Cache Flow
+
+### What is Cache Flow?
+Cache Flow is a gem that helps you distribute when your cache expires over a defined period of time. The problem this attempts to solve is detailed below, but in essence this gives you the ability to bust your cache randomly so that your cache doesn't bust all at the same time (ex: using the current day as the cache key) resulting in large DB CPU spikes (like in the screenshot below).
+
+### Usage
+* Install the gem
+
+```shell
+gem install cache-flow
+```
+
+* Open up your console
+
+```ruby
+# If in irb, you'll need to do the following
+require 'cache-flow'
+
+# Configure CacheFlow in your initializers (config/initializers/cache_flow.rb):
+CacheFlow.configure do |config|
+  config.default_options = {
+    time_zone: "Eastern Time (US & Canada)",
+    hour_range_start: 17,
+    hour_range_end: 20
+  }
+end
+
+# Try the following
+CacheFlow.new.generate_expiry
+
+# In action
+Rails.cache("count_of_never_nudes_in_world", expires_in: CacheFlow.new.generate_expiry) do
+  "Dozens!"
+end
+
+```
+
+So what does Cache Flow do? It generates a random expiration time in between the range of time you configured from now (random time in the future in between your defined range - Time.now.to_i). The Rails cache `expires_in` option accepts a number that is seconds from now that the cache should expire so we chose 1-4am PST for the defined range of when we want our cache to expire since our server's traffic load is light during that window of time.
+
+### Background - Straight Cache Homey
+To understand the problem Cache Flow is solving, it's helpful to under [how caching works in Rails](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html). There are two common cache busting techniques for the Rails cache store. The first is to use a dynamic cache key that busts itself. Example:
+`Rails.cache.fetch("item-path-#{self.id}-#{Date.today.to_s}") { UrlBuilder.new(self).build }`
+
+The cache key generated looks like this: `"item-path-959595-2014-06-18"`. In this example, the first time you call `Rails.cache.fetch`, it will store the returned value from `UrlBuilder.new(self).build`  in your cache store and it will be accessible using the cache key you provided. For subsequent `Rails.cache.fetch` calls, it will first look in cache (before executing the code in the block) to see if there's a value for the cache key and if so, it will return the value from memcached (or whatever your cache store is) without executing the code within the block you provide to `Rails.cache.fetch`. This is the essence of caching - getting the same value without having to execute the code every time. If the code you're executing is costly (ex: pulling from the database), caching can yield great performance gains.
+
+So when the cache key is `"item-path-#{self.id}-#{Date.today.to_s}"`, the cache will expire when the server's clock moves to the next day. Rails will look for a value with the key `item-path-959595-2014-06-19` in your cache store and will find nothing. In this case, the code runs again and the value is stored for another day.
+
+What's wrong with this technique? Well, possibly nothing, but if that caching technique is used everywhere, a lot of cache will be busting at the exact moment a new day starts on the server. Since our server runs in UTC, a lot of our cache was busting at 5pm (or 4pm depending on daylight savings time). This meant our servers were working extra hard at that time of the day. Our database server, in particular, saw a massive CPU spike at that time every day.
+![screenshot 2014-06-17 17 48 43](https://cloud.githubusercontent.com/assets/341055/3309720/f2ee7db2-f6a3-11e3-99db-463cca44d553.png)
+
+So...how about that other cache busting technique? It's the `:expires_in` option you can pass into `Rails.cache.fetch`. It works like this:
+
+```ruby
+def buster_bluth
+  puts "I'm a monster!"
+  "Hey Brother"
+end
+
+# 3.minutes = 180
+Rails.cache.fetch("any_unique_key", expires_in: 3.minutes) { buster_bluth }
+# Output after running:
+# I'm a monster!
+# => "Hey Brother"
+
+# Wait 10 seconds
+Rails.cache.fetch("any_unique_key", expires_in: 3.minutes) { buster_bluth }
+# Output after running again:
+# => "Hey Brother"
+
+# wait 3 minutes
+Rails.cache.fetch("any_unique_key", expires_in: 3.minutes) { buster_bluth }
+# Output after running:
+# I'm a monster!
+# => "Hey Brother"
+```
+This is why Cache Flow was created. We wanted to utilize `expires_in` functionality to manage when our cache busts in a predictable way. With Cache Flow, you don't have to worry about when your cache store will bust - you just let Cache Flow take care of that. Straight cache, homey.
+
+![http://blackathlete.net/wp-content/uploads/2013/12/cash.gif](http://blackathlete.net/wp-content/uploads/2013/12/cash.gif)
+
+### To Do
+* Allow time period to bridge the night (ex: hour_range_start: 21, hour_range_end: 6)
+* Add thorough tests (use Delorean to create very specific example tests)
+* Add validations

data/cache-flow.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name        = 'cache-flow'
+  s.version     = '0.0.5'
+  s.date        = '2014-06-18'
+  s.summary     = 'A gem to manage when your cache expires.'
+  s.description = 'Define a window of time to have all your cache expire randomly within.'
+  s.authors     = ['Dan DeMeyere']
+  s.email       = 'dan.demeyere@gmail.com'
+  s.files       = `git ls-files`.split("\n")
+  s.homepage    = 'https://github.com/dandemeyere/cache-flow'
+  s.license     = 'MIT'
+  s.add_dependency('activesupport','>= 3.1.0')
+  s.add_dependency('i18n','0.7.0')
+  s.add_dependency('tzinfo', '0.3.38')
+  s.add_development_dependency('rspec', '3.2.0')
+end

data/lib/cache-flow.rb

@@ -1,30 +1,4 @@
 require 'active_support'
 require 'active_support/time'
-
-class CacheFlow
-  # Put all these constants into a configurable setting hash
-  TIME_ZONE = "Pacific Time (US & Canada)"
-  # Hour based on 24 hour clock
-  HOUR_RANGE_START = 1
-  HOUR_RANGE_END = 4
-  attr_accessor :frequency
-
-  def initialize(frequency = "daily")
-    self.frequency = frequency
-  end
-
-  def generate_expiry
-    # Rails :expires_in accepts seconds from now to expire the key in
-    case frequency
-    when "daily"
-      random_time_in_range(24.hours.from_now)
-    end
-  end
-
-  def random_time_in_range(day_to_bust)
-    time_to_bust = day_to_bust.in_time_zone(TIME_ZONE).beginning_of_day
-    range_start = time_to_bust + HOUR_RANGE_START.hours
-    range_end = time_to_bust + HOUR_RANGE_END.hours
-    rand(range_start.to_i..range_end.to_i) - Time.now.to_i
-  end
-end
+require 'cache-flow/cache-flow'
+require 'cache-flow/configuration'

data/lib/cache-flow/cache-flow.rb

@@ -0,0 +1,24 @@
+class CacheFlow
+  attr_accessor :frequency
+  attr_reader :options
+
+  def initialize(frequency = "daily", options = {})
+    @options = CacheFlow.configuration.default_options.merge(options)
+    @frequency = frequency
+  end
+
+  def generate_expiry
+    # Rails :expires_in accepts seconds from now to expire the key in
+    case frequency
+    when "daily"
+      random_time_in_range(24.hours.from_now)
+    end
+  end
+
+  def random_time_in_range(day_to_bust)
+    time_to_bust = day_to_bust.in_time_zone(options[:time_zone]).beginning_of_day
+    range_start = time_to_bust + options[:hour_range_start].hours
+    range_end = time_to_bust + options[:hour_range_end].hours
+    rand(range_start.to_i..range_end.to_i) - Time.now.to_i
+  end
+end

data/lib/cache-flow/configuration.rb

@@ -0,0 +1,38 @@
+class CacheFlow
+  class Configuration
+    attr_accessor :default_options
+    # Put all these constants into a configurable setting hash
+    # Hour range based on 24 hour clock
+
+    def initialize
+      @default_options = {
+        time_zone: "Pacific Time (US & Canada)",
+        hour_range_start: 1,
+        hour_range_end: 4
+      }
+    end
+  end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  # Configure CacheFlow in your initializers:
+  # example file location: config/initializers/cache_flow.rb
+  # example code:
+  # CacheFlow.configure do |config|
+  #   config.default_options = {
+  #     time_zone: "Eastern Time (US & Canada)",
+  #     hour_range_start: 17,
+  #     hour_range_end: 20
+  #   }
+  # end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/spec/cache_flow_spec.rb

@@ -0,0 +1,45 @@
+require 'spec_helper.rb'
+
+describe CacheFlow do
+  context '#initialize' do
+    it "should initialize with the frequency" do
+      expect(subject.frequency).to eql 'daily'
+    end
+
+    it "should have the correct default options set" do
+      expect(subject.options).to eql({
+        time_zone: "Pacific Time (US & Canada)",
+        hour_range_start: 1,
+        hour_range_end: 4
+      })
+    end
+  end
+
+  context " configuration " do
+    it "should be configurable" do
+      CacheFlow.configure do |config|
+        config.default_options = {
+          time_zone: "Eastern Time (US & Canada)",
+          hour_range_start: 17,
+          hour_range_end: 20
+        }
+      end
+
+      expect(subject.options).to eql({
+        time_zone: "Eastern Time (US & Canada)",
+        hour_range_start: 17,
+        hour_range_end: 20
+      })
+    end
+  end
+
+  context '#generate_expiry' do
+    it "should return seconds" do
+      expect(subject.generate_expiry.class).to eql Fixnum
+    end
+
+    it "should return seconds in the future" do
+      expect(subject.generate_expiry).to be > 0
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+Bundler.setup
+
+# require 'cache-flow'
+require './lib/cache-flow.rb'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cache-flow
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Dan DeMeyere
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.9
+        version: 0.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.6.9
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
@@ -58,21 +58,30 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.2.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.2.0
 description: Define a window of time to have all your cache expire randomly within.
 email: dan.demeyere@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .rspec
+- Gemfile
+- Gemfile.lock
+- Readme.markdown
+- cache-flow.gemspec
 - lib/cache-flow.rb
+- lib/cache-flow/cache-flow.rb
+- lib/cache-flow/configuration.rb
+- spec/cache_flow_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/dandemeyere/cache-flow
 licenses:
 - MIT