boffin 0.1.0

data/lib/boffin/config.rb

@@ -0,0 +1,91 @@
+module Boffin
+  # Stores configuration state to be used in various parts of the app. You will
+  # likely not need to instantiate Config directly.
+  class Config
+
+    attr_writer \
+      :redis,
+      :namespace,
+      :hours_window_secs,
+      :days_window_secs,
+      :months_window_secs,
+      :cache_expire_secs
+
+    # @param [Hash] opts
+    #   The parameters to create a new Config instance
+    # @option opts [Redis] :redis
+    # @option opts [String] :namespace
+    # @option opts [Fixnum] :hours_window_secs
+    # @option opts [Fixnum] :days_window_secs
+    # @option opts [Fixnum] :months_window_secs
+    # @option opts [Fixnum] :cache_expire_secs
+    # @yield [self]
+    def initialize(opts = {}, &block)
+      yield(self) if block_given?
+      update(opts)
+    end
+
+    # Updates self with the values provided
+    # @param [Hash] updates
+    #   A hash of options to update the config instance with
+    # @return [self]
+    def update(updates = {})
+      tap do |conf|
+        updates.each_pair { |k, v| conf.send(:"#{k}=", v) }
+      end
+    end
+
+    # Creates a copy of self and updates the copy with the values provided
+    # @param [Hash] updates
+    #   A hash of options to merge with the instance
+    # @return [Config] the new Config instance with updated values
+    def merge(updates = {})
+      dup.update(updates)
+    end
+
+    # The Redis instance that will be used to store hit data
+    # @return [Redis] the active Redis connection
+    def redis
+      @redis ||= Redis.connect
+    end
+
+    # The namespace to prefix all Redis keys with. Defaults to `"boffin"` or
+    # `"boffin:<env>"` if `RACK_ENV` or `RAILS_ENV` are present in the
+    # environment.
+    # @return [String]
+    def namespace
+      @namespace ||= begin
+        if (env = ENV['RACK_ENV'] || ENV['RAILS_ENV'])
+          "boffin:#{env}"
+        else
+          "boffin"
+        end
+      end
+    end
+
+    # @return [Fixnum]
+    #   Number of seconds to maintain the hourly hit interval window
+    def hours_window_secs
+      @hours_window_secs ||= 3 * 24 * 3600 # 3 days
+    end
+
+    # @return [Fixnum]
+    #   Number of seconds to maintain the daily hit interval window
+    def days_window_secs
+      @days_window_secs ||= 3 * 30 * 24 * 3600 # 3 months
+    end
+
+    # @return [Fixnum]
+    #   Number of seconds to maintain the monthly hit interval window
+    def months_window_secs
+      @months_window_secs ||= 3 * 12 * 30 * 24 * 3600 # 3 years
+    end
+
+    # @return [Fixnum]
+    #   Number of seconds to cache the results of `Tracker.top`
+    def cache_expire_secs
+      @cache_expire_secs ||= 15 * 60 # 15 minutes
+    end
+
+  end
+end

data/lib/boffin/hit.rb

@@ -0,0 +1,83 @@
+module Boffin
+  # Represents a Hit instance, immutable once created. Interacting with and
+  # instantiating Hit directly is not necessary.
+  class Hit
+
+    # Creates a new Hit instance
+    #
+    # @param [Tracker] tracker
+    #   Tracker that is issuing the hit
+    # @param [Symbol] type
+    #   Hit type identifier
+    # @param [Object] instance
+    #   The instance that is being hit, any object that responds to
+    #   `#to_member`, `#id`, or `#to_s`
+    # @param [Array] uniquenesses
+    #   An array of which the first object is used to generate a session
+    #   identifier for hit uniqueness
+    def initialize(tracker, type, instance, uniquenesses = [])
+      @now      = Time.now
+      @sessid   = Utils.uniquenesses_as_session_identifier(uniquenesses)
+      @type     = type
+      @tracker  = tracker
+      @instance = instance
+      @member   = Utils.object_as_member(@instance)
+      store
+      freeze
+    end
+
+    private
+
+    # @return [Redis]
+    def redis
+      @tracker.redis
+    end
+
+    # @return [Keyspace]
+    def keyspace(*args)
+      @tracker.keyspace(*args)
+    end
+
+    # Stores the hit data in each time window interval key for the current time.
+    # If the hit is unique, also add the data to the keys in the unique keyspace.
+    def store
+      if track_hit
+        set_windows(true)
+      else
+        set_windows(false)
+      end
+    end
+
+    # Increments the {Keyspace#hit_count} key and adds the session member to
+    # {Keyspace#hits}.
+    # @return [true, false]
+    #   `true` if this hit is unique, `false` if it has been made before by the
+    #   same session identifer.
+    def track_hit
+      redis.incr(keyspace.hit_count(@type, @instance))
+      redis.zincrby(keyspace.hits(@type, @instance), 1, @sessid) == '1'
+    end
+
+    # Store the hit member across all time interval for the current window
+    # @param [true, false] uniq
+    #   If `true` the hit is also added to the keys scoped for unique hits
+    def set_windows(uniq)
+      INTERVAL_TYPES.each do |interval|
+        set_window_interval(interval, true) if uniq
+        set_window_interval(interval)
+      end
+    end
+
+    # Increments in the instance member in the sorted set under
+    # {Keyspace#hits_time_window}.
+    # @param [:hours, :days, :months] interval
+    # @param [true, false] uniq
+    #   Changes keyspace scope to keys under .uniq
+    def set_window_interval(interval, uniq = false)
+      key = keyspace(uniq).hits_time_window(@type, interval, @now)
+      redis.zincrby(key, 1, @member)
+      redis.expire(key, @tracker.config.send("#{interval}_window_secs"))
+    end
+
+  end
+end

data/lib/boffin/keyspace.rb

@@ -0,0 +1,147 @@
+module Boffin
+  # Responsible for generating keys to store hit data in Redis.
+  class Keyspace
+
+    attr_reader :config
+
+    # @param [Tracker] tracker
+    #   The Tracker that is using this Keyspace
+    # @param [true, false] is_uniq
+    #   If specified all keys will include .uniq after the root portion. Used
+    #   for easily scoping data for tracking unique hits.
+    def initialize(tracker, is_uniq = false)
+      @config = tracker.config
+      @ns     = tracker.namespace
+      @uniq   = is_uniq ? true : false
+    end
+
+    # @return [true, false]
+    #   `true` if this keyspace is scoped for unique data
+    def unique_namespace?
+      @uniq
+    end
+
+    # @param [Object] instance
+    #   Object that will be used to prefix the key namespace this is used for
+    #   keys that deal with object instances. (See {Utils#object_as_key})
+    # @return [String]
+    #   The root portion of a key: `boffin:listing`, `boffin:listing.5`, or
+    #   `boffin:listing.5:uniq`
+    def root(instance = nil)
+      slug = instance ? Utils.object_as_key(instance) : nil
+      "#{@config.namespace}:#{@ns}".tap { |s|
+        s << ".#{slug}" if slug
+        s << ":uniq"    if @uniq }
+    end
+
+    # @param [Array<Symbol>, Symbol] types
+    #   An array of hit types `[:views, :likes]`, or a singular hit type
+    #   `:views`
+    # @param [Object] instance
+    #   If provided, the keyspace will be scoped to a particilar instance, used
+    #   for hit counters: `boffin:listing.<instance>`
+    # @return [String]
+    #   The root portion of the hits keyspace: `boffin:listing:views`,
+    #   `boffin:listing.5:views`
+    def hits_root(types, instance = nil)
+      "#{root(instance)}:#{[types].flatten.join('_')}"
+    end
+
+    # Calculates the hit root and postfixes it with ":hits", this key is used
+    # for a sorted set that stores unique hit count data.
+    # @param [Array<Symbol>, Symbol] types
+    # @param [Object] instance
+    # @return [String]
+    # @see #hits_root
+    def hits(types, instance = nil)
+      "#{hits_root(types, instance)}:hits"
+    end
+
+    # Calculates the hit root and postfixes it with ":hit_count", this key is
+    # used to store a count of total hits ever made.
+    # @param [Array<Symbol>, Symbol] types
+    # @param [Object] instance
+    # @return [String]
+    # @see #hits_root
+    def hit_count(types, instance)
+      "#{hits_root(types, instance)}:hit_count"
+    end
+
+    # Returns a key that is used for storing the result set of a union for the
+    # provided window of time. Calls {#hits}, and then appends
+    # `:current.<unit>_<size>`
+    # @param [Array<Symbol>, Symbol] types
+    # @param [Symbol] unit
+    #   The time interval: `:hours`, `:days`, or `:months`
+    # @param [Fixnum] size
+    #   The window size of the specified time interval being calculated
+    # @return [String]
+    # @see #hits
+    def hits_union(types, unit, size)
+      "#{hits(types)}:current.#{unit}_#{size}"
+    end
+
+    # Returns a key that is used for storing the result set of a union of hit
+    # unions.
+    # @param [Hash] weighted_hit_types
+    #   The types and weights of hits of which a union was calculated:
+    #   `{ views: 1, likes: 2 }`
+    # @param [Symbol] unit
+    #   The time interval: `:hours`, `:days`, or `:months`
+    # @param [Fixnum] size
+    #   The window size of the specified time interval being calculated
+    # @return [String]
+    # @see #hits_union
+    def hits_union_multi(weighted_hit_types, unit, size)
+      types = weighted_hit_types.map { |type, weight| "#{type}_#{weight}" }
+      hits_union(types, unit, size)
+    end
+
+    # Generates a key that is used for storing hit data for a particular
+    # interval in time. You'll probably want to use {#hits_time_window} as it
+    # will generate the window string for you.
+    # @param [Symbol] type
+    #   The hit type that will use the generated key
+    # @param [String] window
+    #   Represents a period of time: `"2011-01-01-01"`, `"2011-01-01"`,
+    #   `"2011-01"`
+    # @return [String]
+    # @see #hits
+    # @see #hits_time_window
+    def hits_window(type, window)
+      "#{hits(type)}.#{window}"
+    end
+
+    # Generates keys for each interval in the calculated range of time
+    # @param [Symbol] type
+    #   The hit type that will use the generated key
+    # @param [Symbol] unit
+    #   The time interval: `:hours`, `:days`, or `:months`
+    # @param [Fixnum] size
+    #   The window size of the specified time interval being calculated
+    # @param [Time, Date] starting_at
+    #   The time at which to start counting back from
+    # @return [Array<String>]
+    #   An array of keys for the range of intervals
+    # @see #hits_time_window
+    # @see Utils#time_ago_range
+    def hit_time_windows(type, unit, size, starting_at = Time.now)
+      Utils.time_ago_range(starting_at, unit => size).
+        map { |time| hits_time_window(type, unit, time) }
+    end
+
+    # Generates a key for a sorted set that is used to store hit data for a
+    # particular interval of time. For example, the `:days` interval of
+    # 2011-08-26 11:24:41 would be 2011-08-26.
+    # @param [Symbol] type
+    #   The hit type that will use the generated key
+    # @param [Symbol] unit
+    #   The time interval: `:hours`, `:days`, or `:months`
+    # @param [Time] time
+    #   The time for which to extract an interval from.
+    def hits_time_window(type, unit, time)
+      hits_window(type, time.strftime(INTERVAL_FORMATS[unit]))
+    end
+
+  end
+end

data/lib/boffin/trackable.rb

@@ -0,0 +1,66 @@
+module Boffin
+  # Can be included into a class that responds to `#as_member`, `#to_i`, or
+  # `#to_s`. It's recommended to use {Boffin.track} to inject Trackable into a
+  # class. It provides the instance methods of Tracker scoped to the host class
+  # and its instances.
+  #
+  # @example
+  #   class MyModel < ActiveRecord::Base
+  #     include Boffin::Trackable
+  #     boffin.hit_types = [:views, :likes]
+  #   end
+  #
+  #   # Then record hits to instances of your model
+  #   @my_model = MyModel.find(1)
+  #   @my_model.hit(:views)
+  #
+  # See {file:README} for more examples.
+  module Trackable
+
+    # @private
+    def self.included(mod)
+      mod.extend(ClassMethods)
+    end
+
+    # Included as class methods in the host class
+    module ClassMethods
+      # @return [Tracker] The Tracker instance associated with the class
+      def boffin
+        @boffin ||= ::Boffin::Tracker.new(self)
+      end
+
+      # @param [Symbol, Hash] type_or_weights
+      # @param [Hash] opts
+      # @return [Array<String>, Array<Array>]
+      # @see Tracker#top
+      def top_ids(type_or_weights, opts = {})
+        boffin.top(type_or_weights, opts)
+      end
+    end
+
+    # @see Tracker#hit
+    # @return [Hit]
+    def hit(type, uniquenesses = [])
+      self.class.boffin.hit(type, self, uniquenesses)
+    end
+
+    # @see Tracker#hit_count
+    # @return [Fixnum]
+    def hit_count(type)
+      self.class.boffin.hit_count(type, self)
+    end
+
+    # @see Tracker#uhit_count
+    # @return [Fixnum]
+    def uhit_count(type)
+      self.class.boffin.uhit_count(type, self)
+    end
+
+    # @see Tracker#hit_count_for_session_id
+    # @return [Fixnum]
+    def hit_count_for_session_id(type, sess_obj)
+      self.class.boffin.hit_count_for_session_id(type, self, sess_obj)
+    end
+
+  end
+end

data/lib/boffin/tracker.rb

@@ -0,0 +1,229 @@
+module Boffin
+  class Tracker
+
+    attr_reader :namespace, :config
+    attr_accessor :hit_types
+
+    # @param [String, Symbol, #to_s] class_or_ns
+    #   A string, symbol or any object that responds to `#to_s` that will be
+    #   used to namespace this keys of this Tracker.
+    # @param [Array<Symbol>] hit_types
+    #   A list of hit types that this Tracker will allow, if empty then any
+    #   hit type will be allowed.
+    # @param [Config] config
+    #   A Config instance to use instead of Boffin.config
+    # @example
+    #   Tracker.new(MyModel, [:views, likes])
+    #   Tracker.new(:urls,   [:shares, :clicks])
+    def initialize(class_or_ns, hit_types = [], config = Boffin.config.dup)
+      @namespace = Utils.object_as_namespace(class_or_ns)
+      @hit_types = hit_types
+      @config    = config
+      @keyspace  = Keyspace.new(self)
+      @ukeyspace = Keyspace.new(self, true)
+    end
+
+    # @param [Symbol] hit_type
+    # @param [#as_member, #id, #to_s] instance
+    # @param [Array] uniquenesses
+    # @return [Hit]
+    # @raise Boffin::UndefinedHitTypeError
+    #   Raised if a list of hit types is available and the provided hit type is
+    #   not in the list.
+    def hit(hit_type, instance, uniquenesses = [])
+      validate_hit_type(hit_type)
+      Hit.new(self, hit_type, instance, uniquenesses)
+    end
+
+    # @param [Symbol] hit_type
+    # @param [#as_member, #id, #to_s] instance
+    # @return [Fixnum]
+    # @raise Boffin::UndefinedHitTypeError
+    #   Raised if a list of hit types is available and the provided hit type is
+    #   not in the list.
+    def hit_count(hit_type, instance)
+      validate_hit_type(hit_type)
+      redis.get(keyspace.hit_count(hit_type, instance)).to_i
+    end
+
+    # @param [Symbol] hit_type
+    # @param [#as_member, #id, #to_s] instance
+    # @return [Fixnum]
+    # @raise Boffin::UndefinedHitTypeError
+    #   Raised if a list of hit types is available and the provided hit type is
+    #   not in the list.
+    def uhit_count(hit_type, instance)
+      validate_hit_type(hit_type)
+      redis.zcard(keyspace.hits(hit_type, instance)).to_i
+    end
+
+    # @param [Symbol] hit_type
+    # @param [#as_member, #id, #to_s] instance
+    # @param [#as_member, #id, #to_s] sess_obj
+    # @return [Fixnum]
+    # @raise Boffin::UndefinedHitTypeError
+    #   Raised if a list of hit types is available and the provided hit type is
+    #   not in the list.
+    def hit_count_for_session_id(hit_type, instance, sess_obj)
+      validate_hit_type(hit_type)
+      sessid = Utils.object_as_session_identifier(sess_obj)
+      redis.zscore(keyspace.hits(hit_type, instance), sessid).to_i
+    end
+
+    # Performs set union across the specified number of hours, days, or months
+    # to calculate the members with the highest hit counts. The operation can
+    # be performed on one hit type, or multiple hit types with weights.
+    # @param [Symbol, Hash] type_or_weights
+    #   When Hash the set union is calculated 
+    # @param [Hash] opts
+    # @option opts [true, false] :unique (false)
+    #   If `true` then only unique hits are considered in the calculation
+    # @option opts [true, false] :counts (false)
+    #   If `true` then scores are returned along with the top members
+    # @option opts [:desc, :asc] :order (:desc)
+    #   The order of the results, in decending (most hits to least hits) or
+    #   ascending (least hits to most hits) order.
+    # @option opts [Fixnum] :hours
+    #   Perform union for hit counts over the last _n_ hours.
+    # @option opts [Fixnum] :days
+    #   Perform union for hit counts over the last _n_ days.
+    # @option opts [Fixnum] :months
+    #   Perform union for hit counts over the last _n_ months.
+    # @example Return IDs of most viewed and liked listings in the past 6 days with scores
+    #   @tracker.top({ views: 1, likes: 1 }, counts: true, days: 6)
+    # @example Return IDs of most viewed listings in the past 12 hours
+    #   @tracker.top(:views, hours: 12)
+    # @note
+    #   The result set returned is cached in Redis for the duration of
+    #   {Config#cache_expire_secs}
+    # @note
+    #   Only one of `:hours`, `:days`, or `:months` should be specified in the
+    #   options hash as they can not be combined.
+    # @raise Boffin::UndefinedHitTypeError
+    #   If a list of hit types is available and any of the provided hit types is
+    #   not in the list.
+    def top(type_or_weights, opts = {})
+      validate_hit_type(type_or_weights)
+      unit, size = *Utils.extract_time_unit(opts)
+      keyspace   = keyspace(opts[:unique])
+      if type_or_weights.is_a?(Hash)
+        multiunion(keyspace, type_or_weights, unit, size, opts)
+      else
+        union(keyspace, type_or_weights, unit, size, opts)
+      end
+    end
+
+    # @param [true, false] uniq
+    #   If `true` the unique-scoped keyspace is returned
+    # @return [Keyspace]
+    #   Keyspace associated with this tracker
+    def keyspace(uniq = false)
+      uniq ? @ukeyspace : @keyspace
+    end
+
+    # @return [Redis] The Redis connection for this Tracker's config
+    def redis
+      @config.redis
+    end
+
+    private
+
+    # Checks to see if `hit_type` exists in the list of hit types. If no
+    # elements exist in @hit_types then the check is skipped.
+    # @param [Symbol] hit_type
+    # @raise Boffin::UndefinedHitTypeError
+    #   Raised if a list of hit types is available and the provided hit type is
+    #   not in the list.
+    def validate_hit_type(hit_type)
+      return if @hit_types.empty?
+      (hit_type.is_a?(Hash) ? hit_type.keys : [hit_type]).each do |type|
+        next if @hit_types.include?(type)
+        raise UndefinedHitTypeError, "#{type} is not in the list of " \
+        "valid hit types for this Tracker, valid types are: " \
+        "#{@hit_types.inspect}"
+      end
+    end
+
+    # @param [Keyspace] ks
+    #   Keyspace to perform the union on
+    # @param [Symbol] hit_type
+    # @param [:hours, :days, :months] unit
+    # @param [Fixnum] size
+    #   Number of intervals to include in the union
+    # @param [Hash] opts
+    # @option opts [true, false] :counts (false)
+    # @option opts [:asc, :desc] :order (:desc)
+    # @return [Array<String>, Array<Array>]
+    # @see #zfetch
+    def union(ks, hit_type, unit, size, opts = {})
+      keys = ks.hit_time_windows(hit_type, unit, size)
+      zfetch(ks.hits_union(hit_type, unit, size), keys, opts)
+    end
+
+    # Performs {#union} for each hit type, then performs a union on those
+    # result sets with the provided weights.
+    # @param [Keyspace] ks
+    #   Keyspace to perform the union on
+    # @param [Hash] weights
+    # @param [Symbol] hit_type
+    # @param [:hours, :days, :months] unit
+    # @param [Fixnum] size
+    #   Number of intervals to include in the union
+    # @param [Hash] opts
+    # @option opts [true, false] :counts (false)
+    # @option opts [:asc, :desc] :order (:desc)
+    # @return [Array<String>, Array<Array>]
+    # @see #zfetch
+    def multiunion(ks, weights, unit, size, opts = {})
+      weights.keys.each { |t| union(ks, t, unit, size, opts) }
+      keys = weights.keys.map { |t| ks.hits_union(t, unit, size) }
+      zfetch(ks.hits_union_multi(weights, unit, size), keys, {
+        weights: weights.values
+      }.merge(opts))
+    end
+
+    # Checks to see if the result set exists (is cached), if it does the set is
+    # returned, otherwise a union of the keys is performed, cached, and
+    # returned.
+    # @param [String] storkey
+    #   Key to store the result set under
+    # @param [Array<String>] keys
+    # @param [Hash] opts
+    # @option opts [true, false] :counts (false)
+    # @option opts [:asc, :desc] :order (:desc)
+    # @see #zrange
+    def zfetch(storkey, keys, opts = {})
+      zrangeopts = {
+        counts: opts.delete(:counts),
+        order:  (opts.delete(:order) || :desc).to_sym }
+      if redis.zcard(storkey) == 0
+        redis.zunionstore(storkey, keys, opts)
+        redis.expire(storkey, @config.cache_expire_secs)
+      end
+      zrange(storkey, zrangeopts)
+    end
+
+    # Performs a range on a sorted set at key.
+    # @param [String] key
+    # @param [Hash] opts
+    # @option opts [true, false] :counts (false)
+    # @option opts [:asc, :desc] :order (:desc)
+    # @return [Array<String>, Array<Array>]
+    #   Returns an array of members in sorted order, optionally if the `:counts`
+    #   option is `true` it returns an array of pairs where the first value is
+    #   the member, and the second value is the member's score.
+    def zrange(key, opts)
+      args = [key, 0, -1, opts[:counts] ? { withscores: true } : {}]
+      result = case opts[:order]
+        when :asc  then redis.zrange(*args)
+        when :desc then redis.zrevrange(*args)
+      end
+      if opts[:counts]
+        result.each_slice(2).map { |mbr, score| [mbr, score.to_i] }
+      else
+        result
+      end
+    end
+
+  end
+end