boffin 0.1.0

data/lib/boffin/utils.rb

@@ -0,0 +1,171 @@
+module Boffin
+  # A collection of utility methods that are used throughout the library
+  module Utils
+
+    # The number of seconds in an hour
+    SECONDS_IN_HOUR  = 3600
+
+    # Number of seconds in a day
+    SECONDS_IN_DAY   = 24 * SECONDS_IN_HOUR
+
+    # Number of seconds in a month
+    SECONDS_IN_MONTH = 30 * SECONDS_IN_DAY
+
+    # Number of seconds for a single value of each unit
+    SECONDS_IN_UNIT  = {
+      hours:  SECONDS_IN_HOUR,
+      days:   SECONDS_IN_DAY,
+      months: SECONDS_IN_MONTH
+    }
+
+    module_function
+
+    # @param [#to_s] thing
+    #   A Module, Class, String, or anything in which the underscored value of
+    #   `#to_s` is desirable.
+    # @return [String]
+    #   The underscored version of `#to_s` on thing
+    # @note
+    #   Originally pulled from ActiveSupport::Inflector
+    def underscore(thing)
+      thing.to_s.dup.tap do |word|
+        word.gsub!(/::/, '_')
+        word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+        word.tr!('-', '_')
+        word.downcase!
+      end
+    end
+
+    # @param [Object] obj any Ruby object
+    # @return [true, false]
+    #   `true` if the provided object is blank, examples of blank objects are:
+    #   `[]`, `{}`, `nil`, `false`, `''`.
+    def blank?(obj)
+      obj.respond_to?(:empty?) ? obj.empty? : !obj
+    end
+
+    # Pulls time interval information from a hash of options.
+    # @example
+    #   extract_time_unit(this: 'is ignored', days: 6, so_is: 'this')
+    #   #=> [:days, 6]
+    # @param [Hash] hsh
+    #   Any Hash that contains amoungst its keys one of `:hours`, `:days`, or
+    #   `:months`.
+    # @return [Array]
+    #   A two-element array containing the unit-type (`:hours`, `:days`, or
+    #   `:months`) and the value.
+    def extract_time_unit(hsh)
+      case
+      when hsh.key?(:hours)  then [:hours,  hsh[:hours]]
+      when hsh.key?(:days)   then [:days,   hsh[:days]]
+      when hsh.key?(:months) then [:months, hsh[:months]]
+      else
+        raise ArgumentError, 'no time unit exists in the hash provided'
+      end
+    end
+
+    # @example
+    #   time_ago(Time.local(2011, 1, 3), days: 2)
+    #   # => 2011-01-01 00:00:00
+    # @param [Time] time
+    #   The initial time that the offset will be calculated from
+    # @param [Hash] unit
+    #   (see {#extract_time_unit})
+    # @return [Time]
+    #   The time in the past offset by the specified amount
+    def time_ago(time, unit)
+      unit, unit_value = *extract_time_unit(unit)
+      time - (unit_value * SECONDS_IN_UNIT[unit])
+    end
+
+    # @param [Time] upto
+    #   The base time of which to calculate the range from
+    # @param [Hash] unit
+    #   (see {#extract_time_unit})
+    # @return [Array<Time>]
+    #   An array of times in the calculated range
+    # @example
+    #   time_ago_range(Time.local(2011, 1, 5), days: 3)
+    #   # => [2011-01-03 00:00:00, 2011-01-04 00:00:00, 2011-01-05 00:00:00]
+    def time_ago_range(upto, unit)
+      unit, size = *extract_time_unit(unit)
+      ago = time_ago(upto, unit => (size - 1))
+      max, count, times = upto.to_i, ago.to_i, []
+      begin
+        times << Time.at(count)
+      end while (count += SECONDS_IN_UNIT[unit]) <= max
+      times
+    end
+
+    # Generates a set member based off the first object in the provided array
+    # that is not `nil`. If the array is empty or only contains `nil` elements
+    # then {Boffin::NIL_SESSION_MEMBER} is returned.
+    # @param [Array] aspects
+    #   An array of which the first non-nil element is passed to
+    #   {#object_as_session_identifier}
+    # @return [String]
+    def uniquenesses_as_session_identifier(aspects)
+      if (obj = aspects.flatten.reject { |u| blank?(u) }.first)
+        object_as_session_identifier(obj)
+      else
+        NIL_SESSION_MEMBER
+      end
+    end
+
+    # @param [String, Symbol, Object] obj
+    # @return [String]
+    #   Returns a string that can be used as a namespace in Redis keys
+    def object_as_namespace(obj)
+      case obj
+      when String, Symbol
+        obj.to_s
+      else
+        underscore(obj)
+      end
+    end
+
+    # @param [#as_member, #id, #to_s] obj
+    # @param [Hash] opts
+    # @option opts [true, false] :namespace
+    #   If `true` the generated value will be prefixed with a namespace
+    # @option opts [true, false] :encode
+    #   If `true` and object fails to respond to `#as_member` or `#id`, the
+    #   generated value will be Base64 encoded.
+    # @return [String]
+    def object_as_identifier(obj, opts = {})
+      if obj.respond_to?(:as_member) || obj.respond_to?(:id)
+        ''.tap do |s|
+          s << "#{underscore(obj.class)}:" if opts[:namespace]
+          s << (obj.respond_to?(:as_member) ? obj.as_member : obj.id).to_s
+        end
+      else
+        opts[:encode] ? Base64.strict_encode64(obj.to_s) : obj.to_s
+      end
+    end
+
+    # @return [String]
+    # @param [#as_member, #id, #to_s] obj
+    # @return [String] A string that can be used as a member in
+    #   {Keyspace#hits_time_window}.
+    # @see #object_as_identifier
+    def object_as_member(obj)
+      object_as_identifier(obj)
+    end
+
+    # @param [#as_member, #id, #to_s] obj
+    # @return [String] A string that can be used as a member in {Keyspace#hits}.
+    # @see #object_as_identifier
+    def object_as_session_identifier(obj)
+      object_as_identifier(obj, namespace: true)
+    end
+
+    # @param [#as_member, #id, #to_s] obj
+    # @return [String] A string that can be used as part of a Redis key
+    # @see #object_as_identifier
+    def object_as_key(obj)
+      object_as_identifier(obj, encode: true)
+    end
+
+  end
+end

data/lib/boffin/version.rb

@@ -0,0 +1,4 @@
+module Boffin
+  # Version of this Boffin release
+  VERSION = '0.1.0'
+end

data/spec/boffin/config_spec.rb

@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+describe Boffin::Config do
+  describe '#namespace' do
+    specify { subject.namespace.should == 'boffin' }
+
+    it 'includes the Rails environment when available' do
+      ENV['RAILS_ENV'] = 'production'
+      Boffin::Config.new.namespace.should == 'boffin:production'
+      ENV['RAILS_ENV'] = nil
+    end
+
+    it 'includes the Rack environment when available' do
+      ENV['RACK_ENV'] = 'staging'
+      Boffin::Config.new.namespace.should == 'boffin:staging'
+      ENV['RACK_ENV'] = nil
+    end
+  end
+
+  describe '#new' do
+    it 'returns a default config instance with no arguments' do
+      Boffin::Config.new.should be_a Boffin::Config
+    end
+
+    it 'can be sent a block' do
+      conf = Boffin::Config.new { |c| c.namespace = 'hihi' }
+      conf.namespace.should == 'hihi'
+    end
+
+    it 'can be sent a hash' do
+      conf = Boffin::Config.new(namespace: 'hello')
+      conf.namespace.should == 'hello'
+    end
+  end
+
+  describe '#merge' do
+    it 'copies the existing instance' do
+      newconf = subject.merge(namespace: 'carsten')
+      newconf.namespace.should == 'carsten'
+      subject.namespace.should == 'boffin'
+    end
+  end
+
+  describe '#redis' do
+    it 'calls Redis.connect by default' do
+      Boffin::Config.new.redis.should be_a Redis
+    end
+  end
+
+  describe '#hours_window_secs' do
+    specify { subject.hours_window_secs.should == 3 * 24 * 3600 } # 3 days
+  end
+
+  describe '#days_window_secs' do
+    specify { subject.days_window_secs.should == 3 * 30 * 24 * 3600 } # 3 months
+  end
+
+  describe '#months_window_secs' do
+    specify { subject.months_window_secs.should == 3 * 12 * 30 * 24 * 3600 } # 3 years
+  end
+
+  describe '#cache_expire_secs' do
+    specify { subject.cache_expire_secs.should == 900 } # 15 minutes
+  end
+end

data/spec/boffin/hit_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+
+describe Boffin::Hit, '::new' do
+  before do
+    SpecHelper.flush_keyspace!
+    @tracker = Boffin::Tracker.new(MockDitty)
+    @ditty   = MockDitty.new
+    @user    = MockUser.new
+    Timecop.travel(Time.local(2011, 1, 1))
+  end
+
+  after do
+    Timecop.return
+  end
+
+  it 'stores hit data under the appropriate keys' do
+    Boffin::Hit.new(@tracker, :tests, @ditty, [nil, @user])
+    [:hours, :days, :months].each do |interval|
+      @tracker.top(:tests, interval => 1, counts: true).
+        should == [['1', 1]]
+      @tracker.top(:tests, interval => 1, counts: true, unique: true).
+        should == [['1', 1]]
+    end
+    @tracker.hit_count(:tests, @ditty).should == 1
+    @tracker.uhit_count(:tests, @ditty).should == 1
+  end
+
+  it 'does not store data under unique keys if the hit is not unique' do
+    Boffin::Hit.new(@tracker, :tests, @ditty, [nil, @user])
+    Boffin::Hit.new(@tracker, :tests, @ditty, [nil, @user])
+    [:hours, :days, :months].each do |interval|
+      @tracker.top(:tests, interval => 1, counts: true).
+        should == [['1', 2]]
+      @tracker.top(:tests, interval => 1, counts: true, unique: true).
+        should == [['1', 1]]
+    end
+    @tracker.hit_count_for_session_id(:tests, @ditty, @user).should == 2
+    @tracker.hit_count(:tests, @ditty).should == 2
+    @tracker.uhit_count(:tests, @ditty).should == 1
+  end
+
+end

data/spec/boffin/keyspace_spec.rb

@@ -0,0 +1,85 @@
+require 'spec_helper'
+
+describe Boffin::Keyspace do
+  before :all do
+    @tracker  = Boffin::Tracker.new(MockDitty)
+    @tracker.config.namespace = 'b'
+    @ks  = @tracker.keyspace
+    @uks = @tracker.keyspace(true)
+  end
+
+  describe '#root' do
+    specify { @ks.root.should == 'b:mock_ditty' }
+    specify { @uks.root.should == 'b:mock_ditty:uniq' }
+  end
+
+  describe '#hits' do
+    specify do
+      @ks.hits([:views, :likes]).should == 'b:mock_ditty:views_likes:hits'
+    end
+
+    specify do
+      @ks.hits(:views).should == 'b:mock_ditty:views:hits'
+    end
+
+    specify do
+      @ks.hits(:views, MockDitty.new).should == 'b:mock_ditty.1:views:hits'
+    end
+  end
+
+  describe '#hit_count' do
+    specify do
+      @ks.hit_count(:views, MockDitty.new).should == 'b:mock_ditty.1:views:hit_count'
+    end
+  end
+
+  describe '#hits_union' do
+    specify do
+      @ks.hits_union(:views, :days, 5).
+        should == 'b:mock_ditty:views:hits:current.days_5'
+    end
+  end
+
+  describe '#hits_union_multi' do
+    specify do
+      @ks.hits_union_multi({ views: 1, likes: 3 }, :days, 5).
+        should == 'b:mock_ditty:views_1_likes_3:hits:current.days_5'
+    end
+  end
+
+  describe '#hits_window' do
+    specify do
+      @ks.hits_window(:views, '*').should == 'b:mock_ditty:views:hits.*'
+    end
+  end
+
+  describe '#hits_time_window' do
+    before do
+      @time = Time.local(2011, 1, 1, 23)
+    end
+
+    Boffin::INTERVAL_TYPES.each do |format|
+      describe "given #{format} based window" do
+        specify do
+          strf = Boffin::INTERVAL_FORMATS[format]
+          @ks.hits_time_window(:views, format, @time).
+            should == "b:mock_ditty:views:hits.#{@time.strftime(strf)}"
+        end
+      end
+    end
+  end
+
+  describe '#hit_time_windows' do
+    before do
+      @time = Time.local(2011, 1, 1, 23)
+    end
+
+    it 'generates keys each interval in the range' do
+      @ks.hit_time_windows(:views, :days, 3, @time).should == [
+        'b:mock_ditty:views:hits.2010-12-30',
+        'b:mock_ditty:views:hits.2010-12-31',
+        'b:mock_ditty:views:hits.2011-01-01'
+      ]
+    end
+  end
+end

data/spec/boffin/trackable_spec.rb

@@ -0,0 +1,38 @@
+require 'spec_helper'
+
+describe Boffin::Trackable do
+  before :all do
+    SpecHelper.flush_keyspace!
+    @mock = MockTrackableInjected.new(1)
+    @mock.hit(:views, ['sess.1'])
+    @mock.hit(:views, ['sess.1'])
+  end
+
+  it 'can be included' do
+    MockTrackableIncluded.boffin.hit_types.should == [:views, :likes]
+  end
+
+  it 'can be injected' do
+    MockTrackableInjected.boffin.hit_types.should == [:views, :likes]
+  end
+
+  it 'provides ::boffin as an accessor to the Tracker instance' do
+    MockTrackableInjected.boffin.should be_a Boffin::Tracker
+  end
+
+  it 'delegates ::top_ids to the Tracker instance' do
+    MockTrackableInjected.top_ids(:views, days: 1).should == ['1']
+  end
+
+  it 'delegates #hit_count to the Tracker instance' do
+    @mock.hit_count(:views).should == 2
+  end
+
+  it 'delegates #uhit_count to the Tracker instance' do
+    @mock.uhit_count(:views).should == 1
+  end
+
+  it 'delegates #hit_count_for_session_id to the Tracker instance' do
+    @mock.hit_count_for_session_id(:views, 'sess.1').should == 2
+  end
+end

data/spec/boffin/tracker_spec.rb

@@ -0,0 +1,162 @@
+require 'spec_helper'
+
+describe Boffin::Tracker do
+  before :all do
+    SpecHelper.flush_keyspace!
+    @tracker   = Boffin::Tracker.new(MockDitty, [:views, :likes, :shares])
+    @instance1 = MockDitty.new(100)
+    @instance2 = MockDitty.new(200)
+    @instance3 = MockDitty.new(300)
+    @instance4 = MockDitty.new(400)
+    @user1     = MockUser.new(1)
+    @user2     = MockUser.new(2)
+    @date      = Date.today
+
+    Timecop.freeze(@date - 2) do
+      @tracker.hit(:views, @instance3)
+      @tracker.hit(:likes, @instance3, [@user1])
+      @tracker.hit(:views, @instance3, ['sess.1'])
+      @tracker.hit(:views, @instance3, ['sess.2'])
+      @tracker.hit(:views, @instance3, [@user2])
+      @tracker.hit(:likes, @instance1, [nil, nil])
+      @tracker.hit(:views, @instance3, ['sess.4'])
+      @tracker.hit(:views, @instance3, [@user1])
+      @tracker.hit(:views, @instance2, [@user2])
+      @tracker.hit(:views, @instance3, [@user2])
+      @tracker.hit(:likes, @instance3)
+      @tracker.hit(:views, @instance3, ['sess.1'])
+      @tracker.hit(:views, @instance3)
+      @tracker.hit(:likes, @instance3, [@user1])
+      @tracker.hit(:views, @instance3, ['sess.1'])
+    end
+
+    Timecop.freeze(@date - 1) do
+      @tracker.hit(:views, @instance1)
+      @tracker.hit(:likes, @instance2, [@user1])
+      @tracker.hit(:views, @instance2, ['sess.4'])
+      @tracker.hit(:views, @instance2, [nil, @user1])
+      @tracker.hit(:views, @instance2, ['sess.3'])
+      @tracker.hit(:views, @instance1, ['sess.3'])
+      @tracker.hit(:views, @instance1, [@user1])
+      @tracker.hit(:views, @instance2, ['sess.2'])
+      @tracker.hit(:views, @instance1, [@user1])
+      @tracker.hit(:views, @instance1, [@user2])
+    end
+
+    @tracker.hit(:views, @instance3, ['sess.2'])
+    @tracker.hit(:views, @instance2, [@user2])
+    @tracker.hit(:likes, @instance2)
+    @tracker.hit(:views, @instance2, [@user1])
+    @tracker.hit(:views, @instance1, ['sess.4'])
+    @tracker.hit(:views, @instance3, ['sess.3'])
+    @tracker.hit(:views, @instance1, [@user1])
+    @tracker.hit(:views, @instance1, [@user2])
+  end
+
+  describe '#hit' do
+    it 'throws an error if the hit type is not in the list' do
+      -> { @tracker.hit(:view, @instance1) }.
+        should raise_error Boffin::UndefinedHitTypeError
+    end
+  end
+
+  describe '#hit_count' do
+    it 'throws an error if the hit type is not in the list' do
+      -> { @tracker.hit_count(:view, @instance1) }.
+        should raise_error Boffin::UndefinedHitTypeError
+    end
+
+    it 'returns the raw hit count for the instance' do
+      @tracker.hit_count(:views, @instance1).should == 8
+    end
+
+    it 'returns 0 for an instance that was never hit' do
+      @tracker.hit_count(:views, 'neverhit').should == 0
+    end
+  end
+
+  describe '#uhit_count' do
+    it 'throws an error if the hit type is not in the list' do
+      -> { @tracker.uhit_count(:view, @instance1) }.
+        should raise_error Boffin::UndefinedHitTypeError
+    end
+
+    it 'returns the unique hit count for the instance' do
+      @tracker.uhit_count(:views, @instance1).should == 5
+    end
+
+    it 'returns 0 for an instance that was never hit' do
+      @tracker.hit_count(:likes, @instance4).should == 0
+    end
+  end
+
+  describe '#hit_count_for_session_id' do
+    it 'throws an error if the hit type is not in the list' do
+      -> { @tracker.hit_count_for_session_id(:view, @instance1, 'sess.1') }.
+        should raise_error Boffin::UndefinedHitTypeError
+    end
+
+    it 'returns the number of times the instance was hit by the session id' do
+      @tracker.hit_count_for_session_id(:views, @instance3, 'sess.1').should == 3
+    end
+
+    it 'returns a count of 0 if the session id never hit the instance' do
+      @tracker.hit_count_for_session_id(:views, @instance1, 'nohit').should == 0
+    end
+  end
+
+  describe '#top' do
+    it 'throws an error if passed hit type is invalid' do
+      -> { @tracker.top(:view, days: 3) }.
+        should raise_error Boffin::UndefinedHitTypeError
+    end
+
+    it 'throws an error if passed weights with hit type that is invalid' do
+      -> { @tracker.top({ view: 1 }, days: 3) }.
+        should raise_error Boffin::UndefinedHitTypeError
+    end
+
+    it 'returns ids ordered by hit counts of weighted totals' do
+      ids = @tracker.top({ views: 1, likes: 2 }, days: 3)
+      ids.should == ['300', '200', '100']
+    end
+
+    it 'returns ids ordered by total counts of a specific hit type' do
+      ids = @tracker.top(:views, days: 3)
+      ids.should == ['300', '100', '200']
+    end
+
+    it 'returns ids in ascending order when passed { order: "asc" } as an option' do
+      ids = @tracker.top(:views, days: 3, order: 'asc')
+      ids.should == ['200', '100', '300']
+    end
+
+    it 'returns ids and counts when passed { counts: true } as an option' do
+      ids = @tracker.top(:views, days: 3, counts: true)
+      ids.should == [
+        ['300', 12],
+        ['100', 8],
+        ['200', 7]
+      ]
+    end
+
+    it 'returns ids based on unique hit data when passed { unique: true } as an option' do
+      ids = @tracker.top(:views, days: 3, counts: true, unique: true)
+      ids.should == [
+        ['300', 7],
+        ['200', 5],
+        ['100', 5]
+      ]
+    end
+  end
+
+  describe '#keyspace' do
+    it 'returns a keyspace' do
+      @tracker.keyspace.unique_namespace?.should be_false
+    end
+
+    it 'returns a unique keyspace when passed true' do
+      @tracker.keyspace(true).unique_namespace?.should be_true
+    end
+  end
+end