battle_ship 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6c1a6e6b2bbce4d90f39d7a4d50b9064eb2c25a8
+  data.tar.gz: 201bfa26abb91dbfcd900ba21483ef289ab86a70
+SHA512:
+  metadata.gz: eb495f4cfce3a23eed57d2a06836a3c100a6548b00c066f1fcf7d578fa581dff4d882d90cef1dc02cec4d334f24bed05e5cd175b17403556f209e615f65b0290
+  data.tar.gz: bf4cd384fbb12a719bd81fcbf44865424e5e458528dca3a04c54e61ec3d3cd34e99b370426a1e64b3c8df98840b39b9b71eda28ab9e0277b7710c0a1d1bbe8ed

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in battle_ship.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 DavidRagone
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# BattleShip
+
+### Keep track of your cache hits & misses
+
+#### Description
+If you make use of Rails.cache methods (e.g. #fetch, #read, #write), you may be
+curious what your success is with your caching strategies. Perhaps you cache
+some user objects, sessions, etc. How do you know whether it's working? What if
+it's mostly misses?
+
+BattleShip provides an api that wraps Rails.cache methods. It takes a namespace
+by which it will aggregate data on your cache hits and misses.
+
+#### Warnings, Caveats, etc.
+Battleship is a gem that expects there to be a class called __Rails__ with a .cache
+method. This .cache method must implement the following:
+  - fetch
+  - read
+  - write
+  - increment
+
+This cache must also be able to complete _atomic increment_ operations with the #increment method
+
+This is early development days for BattleShip. Please feel free to open an issue
+here with either questions or suggestions. And, of course, contributions are
+welcome.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'battle_ship'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install battle_ship
+
+## Usage
+
+Instead of calling Rails.cache, call BattleShip. Instead of passing a key, pass
+in both a namespace (e.g., sessions or users) and a unique id (e.g. auth_token
+or user.id).
+
+After adding to your Gemfile, use BattleShip where you would previously have
+used Rails.cache.
+* Caching User objects? Call ```BattleShip.write("user", user.id, user)``` for a
+  given user object
+* This will store the user object just as if you had called ```Rails.cache.write("user_#{user.id}", user)```
+* The benefit comes when you call read: ```BattleShip.read("user", 1)```
+* If you have a value cached, BattleShip will increment the key at "user_hit" by
+  1 (hence the need for atomic increment operations)
+* If there is no value found, BattleShip will increment the key at "user_miss"
+
+At any time, you can access the current number of hits and misses by calling
+BattleShip.hits(:namespace) and BattleShip.misses(:namespace), where :namespace
+is any given namespace you have used (e.g. 'user', as above). This can be passed
+as a symbol or string.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## To Do
+
+1. Add config method with any necessary config
+2. Create specs specifically using redis-store and memcache-store, document here

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/battle_ship.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'battle_ship/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "battle_ship"
+  spec.version       = BattleShip::VERSION
+  spec.authors       = ["DavidRagone"]
+  spec.email         = ["dmragone@gmail.com"]
+  spec.description   = %q{Wrapper class for Rails.cache related methods to track cache hits & misses}
+  spec.summary       = %q{Wrapper for Rails.cache methods}
+  spec.homepage      = "http://www.dmragone.com"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/battle_ship/core.rb

@@ -0,0 +1,62 @@
+module BattleShip
+  class << self
+    def read(namespace, uid)
+      value = cache.read(namespaced(namespace, uid))
+      increment_hit_or_miss(namespace, value)
+      value
+    end
+
+    def write(namespace, uid, value, options = nil)
+      cache.write(namespaced(namespace, uid), value, options)
+    end
+
+    def fetch(namespace, uid, options = nil)
+      # http://mudge.name/2011/01/26/passing-blocks-in-ruby-without-block.html
+      namespaced = namespaced(namespace, uid)
+      increment_hit_or_miss(namespace, cache.read(namespaced))
+      if block_given?
+        cache.fetch(namespaced, options, &Proc.new)
+      else
+        cache.fetch(namespaced, options)
+      end
+    end
+
+    def decrement(namespace, uid, amount = 1, options = nil)
+      cache.decrement(namespaced(namespace, uid), amount, options)
+    end
+
+    def delete(namespace, uid, options = nil)
+      cache.delete(namespaced(namespace, uid), options)
+    end
+
+    def exist?(namespace, uid, options = nil)
+      cache.exist?(namespaced(namespace, uid), options)
+    end
+
+    def increment(namespace, uid, amount = 1, options = nil)
+      cache.increment(namespaced(namespace, uid), amount, options)
+    end
+
+    def hits(namespace)
+      cache.read("#{namespace}_hit")
+    end
+
+    def misses(namespace)
+      cache.read("#{namespace}_miss")
+    end
+
+    private
+    def increment_hit_or_miss(namespace, value, amount = 1, options = nil)
+      hit_or_miss = value.nil? ? '_miss' : '_hit'
+      cache.increment(namespace.to_s << hit_or_miss, amount, options)
+    end
+
+    def namespaced(namespace, uid)
+      namespace.to_s << '_' << uid.to_s
+    end
+
+    def cache
+      Rails.cache
+    end
+  end
+end

data/lib/battle_ship/pass_through.rb

@@ -0,0 +1,27 @@
+module BattleShip
+  class << self
+    def cleanup(options = nil)
+      cache.cleanup(options)
+    end
+
+    def clear(options = nil)
+      cache.clear(options)
+    end
+
+    def delete_matched(matcher, options = nil)
+      cache.delete_matched(matcher, options)
+    end
+
+    def mute
+      cache.mute
+    end
+
+    def read_multi(*names)
+      cache.read_multi(*names)
+    end
+
+    def silence!
+      cache.silence!
+    end
+  end
+end

data/lib/battle_ship/version.rb

@@ -0,0 +1,3 @@
+module BattleShip
+  VERSION = "0.0.1"
+end

data/lib/battle_ship.rb

@@ -0,0 +1,6 @@
+module BattleShip
+end
+
+require "battle_ship/version"
+require "battle_ship/core"
+require "battle_ship/pass_through"

data/spec/lib/battle_ship_spec.rb

@@ -0,0 +1,280 @@
+require 'spec_helper'
+
+class Rails
+  def self.cache
+    Cache
+  end
+end
+class Cache
+  def self.read(k)
+  end
+  def self.increment(k,a=1,o=nil)
+  end
+  def self.fetch(k,o=nil)
+    if block_given?
+      yield
+    end
+  end
+end
+
+describe BattleShip do
+  describe ".read" do
+    shared_examples_for :read do
+      it "retrieves value from Rails.cache.read" do
+        Cache.should_receive(:read).with("namespace_#{uniqueid}")
+        BattleShip.read(:namespace, uniqueid)
+      end
+
+      it "returns value from Rails.cache.read" do
+        Cache.stub(:read) { 'a value' }
+        BattleShip.read(:foo, :bar).should eq 'a value'
+      end
+
+      it "increments namespace hit counter when value is non-nil" do
+        Cache.stub(:read) { 'a value' }
+        Cache.should_receive(:increment).with('foo_hit', 1, nil)
+        BattleShip.read(:foo, :bar)
+      end
+
+      it "increments namespace miss counter when value is nil" do
+        Cache.stub(:read) { nil }
+        Cache.should_receive(:increment).with('foo_miss', 1, nil)
+        BattleShip.read(:foo, :bar)
+      end
+    end
+
+    context 'when uniqueid is a symbol' do
+      let(:uniqueid) { :foo }
+      it_behaves_like :read
+    end
+
+    context 'when uniqueid is a string' do
+      let(:uniqueid) { 'foo' }
+      it_behaves_like :read
+    end
+
+    context 'when uniqueid is a number' do
+      let(:uniqueid) { 4 }
+      it_behaves_like :read
+    end
+  end
+
+  describe ".write" do
+    shared_examples_for :write do
+      it "writes value to Rails.cache.write using given key" do
+        Cache.should_receive(:write).with("namespace_#{uniqueid}", value, nil)
+        BattleShip.write(:namespace, uniqueid, value)
+      end
+    end
+
+    context 'when uniqueid is a symbol' do
+      let(:uniqueid) { :foo }
+      let(:value) { :bar }
+      it_behaves_like :write
+    end
+
+    context 'when uniqueid is a string' do
+      let(:uniqueid) { 'foo' }
+      let(:value) { 'bar' }
+      it_behaves_like :write
+    end
+
+    context 'when uniqueid is a number' do
+      let(:uniqueid) { 4 }
+      let(:value) { 5 }
+      it_behaves_like :write
+    end
+  end
+
+  describe ".fetch" do
+    shared_examples_for :fetch do
+      it "retrieves value from Rails.cache.fetch" do
+        Cache.should_receive(:fetch)
+        subject
+      end
+
+      it "returns value from Rails.cache.fetch" do
+        Cache.stub(:fetch) { 'a value' }
+        subject.should eq 'a value'
+      end
+
+      it "increments namespace hit counter when value is non-nil" do
+        Cache.stub(:fetch) { 'a value' }
+        Cache.stub(:read) { 'a value' }
+        Cache.should_receive(:increment).with('foo_hit', 1, nil)
+        subject
+      end
+
+      it "increments namespace miss counter when value is nil" do
+        Cache.stub(:fetch) { nil }
+        Cache.should_receive(:increment).with('foo_miss', 1, nil)
+        subject
+      end
+    end
+    context "when block given" do
+      subject { described_class.fetch(:foo, :bar) { 'a different value' } }
+      it_behaves_like :fetch
+
+      context "when value absent" do
+        it "should set the value" do
+          subject
+          subject.should eq 'a different value'
+        end
+      end
+    end
+
+    context "when block absent" do
+      subject { described_class.fetch(:foo, :bar) }
+      it_behaves_like :fetch
+    end
+  end
+
+  describe ".cleanup" do
+    let(:options) { { } }
+    it "passes to underlying" do
+      Cache.should_receive(:cleanup).with(options)
+      BattleShip.cleanup(options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:cleanup).with(nil)
+      BattleShip.cleanup
+    end
+  end
+
+  describe ".clear" do
+    let(:options) { { } }
+    it "passes to underlying" do
+      Cache.should_receive(:clear).with(options)
+      BattleShip.clear(options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:clear).with(nil)
+      BattleShip.clear
+    end
+  end
+
+  describe ".decrement" do
+    let(:options) { { } }
+    let(:namespace) { 'name' }
+    let(:uid) { '1' }
+    let(:amount) { 2 }
+    it "passes to underlying" do
+      Cache.should_receive(:decrement).with('name_1', amount, options)
+      BattleShip.decrement(namespace, uid, amount, options)
+    end
+
+    it "defaults amount to 1" do
+      Cache.should_receive(:decrement).with('name_1', 3, options)
+      BattleShip.decrement(namespace, uid, 3, options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:decrement).with('name_1', 1, nil)
+      BattleShip.decrement(namespace, uid)
+    end
+  end
+
+  describe ".delete" do
+    let(:namespace) { 'name' }
+    let(:uid) { 1 }
+    let(:options) { { } }
+    it "passes to underlying" do
+      Cache.should_receive(:delete).with('name_1', options)
+      BattleShip.delete(namespace, uid, options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:delete).with('name_1', nil)
+      BattleShip.delete(namespace, uid)
+    end
+  end
+
+  describe ".delete_matched" do
+    let(:matcher) { 'something*' }
+    let(:options) { { } }
+    it "passes to underlying" do
+      Cache.should_receive(:delete_matched).with(matcher, options)
+      BattleShip.delete_matched(matcher, options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:delete_matched).with(matcher, nil)
+      BattleShip.delete_matched(matcher)
+    end
+  end
+
+  describe ".exist?" do
+    let(:namespace) { 'name' }
+    let(:uid) { 1 }
+    let(:options) { { } }
+    it "passes to underlying" do
+      Cache.should_receive(:exist?).with('name_1', options)
+      BattleShip.exist?(namespace, uid, options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:exist?).with('name_1', nil)
+      BattleShip.exist?(namespace, uid)
+    end
+  end
+
+  describe ".increment" do
+    let(:options) { { } }
+    let(:namespace) { 'name' }
+    let(:uid) { '1' }
+    let(:amount) { 2 }
+    it "passes to underlying" do
+      Cache.should_receive(:increment).with('name_1', amount, options)
+      BattleShip.increment(namespace, uid, amount, options)
+    end
+
+    it "defaults amount to 1" do
+      Cache.should_receive(:increment).with('name_1', 3, options)
+      BattleShip.increment(namespace, uid, 3, options)
+    end
+
+    it "does not require options" do
+      Cache.should_receive(:increment).with('name_1', 1, nil)
+      BattleShip.increment(namespace, uid)
+    end
+  end
+
+  describe ".hits" do
+    it "returns the hits" do
+      Cache.should_receive(:read).with("foo_hit") { 4 }
+      BattleShip.hits(:foo).should eq 4
+    end
+  end
+
+  describe ".misses" do
+    it "returns the hits" do
+      Cache.should_receive(:read).with("foo_miss") { 4 }
+      BattleShip.misses(:foo).should eq 4
+    end
+  end
+
+  describe ".mute" do
+    it "passes to underlying" do
+      Cache.should_receive(:mute)
+      BattleShip.mute
+    end
+  end
+
+  describe ".read_multi" do
+    # *names - options is last
+    let(:names) { ['1', '2', '3'] }
+    it "passes to underlying" do
+      Cache.should_receive(:read_multi).with(names)
+      BattleShip.read_multi(names)
+    end
+  end
+
+  describe ".silence!" do
+    it "passes to underlying" do
+      Cache.should_receive(:silence!)
+      BattleShip.silence!
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,12 @@
+require 'battle_ship'
+
+RSpec.configure do |config|
+  # Use color in STDOUT
+  config.color_enabled = true
+  #
+  #     # Use color not only in STDOUT but also in pagers and files
+  config.tty = true
+  #
+  #         # Use the specified formatter
+  config.formatter = :documentation # :progress, :html, :textmate
+end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: battle_ship
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- DavidRagone
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !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: rspec
+  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'
+description: Wrapper class for Rails.cache related methods to track cache hits & misses
+email:
+- dmragone@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- battle_ship.gemspec
+- lib/battle_ship.rb
+- lib/battle_ship/core.rb
+- lib/battle_ship/pass_through.rb
+- lib/battle_ship/version.rb
+- spec/lib/battle_ship_spec.rb
+- spec/spec_helper.rb
+homepage: http://www.dmragone.com
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: Wrapper for Rails.cache methods
+test_files:
+- spec/lib/battle_ship_spec.rb
+- spec/spec_helper.rb