boffin 0.1.0

data/.gitignore

@@ -0,0 +1,4 @@
+.yardoc
+doc
+Gemfile.lock
+pkg

data/.rspec

@@ -0,0 +1,2 @@
+--colour
+-fs

data/.yardopts

@@ -0,0 +1,8 @@
+-m markdown
+--markup-provider redcarpet
+--hide-void-return
+--no-cache
+-
+README.md
+CHANGELOG.md
+LICENSE

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+0.1.0
+
+ * Initial public release

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+gemspec
+
+group :development do
+  gem 'rake'
+  gem 'redcarpet'
+  gem 'yard', git: 'https://github.com/lsegal/yard.git'
+end

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (C) 2011 Carsten Nielsen
+
+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,302 @@
+Boffin
+======
+
+Hit tracking library for Ruby using [Redis](http://redis.io)
+
+About
+-----
+
+Boffin is a library for tracking hits to things in your Ruby application. Things
+can be IDs of records in a database, strings representing tags or topics, URLs
+of webpages, names of places, whatever you desire. Boffin is able to provide
+lists of those things based on most hits, least hits, it can even report on
+weighted combinations of different types of hits.
+
+Resources
+---------
+
+ * [Source Code](https://github.com/heycarsten/boffin)
+ * [Issue Tracker](https://github.com/heycarsten/boffin/issues)
+ * [Test Suite](https://github.com/heycarsten/boffin/tree/master/spec)
+ * [License](https://github.com/heycarsten/boffin/blob/master/LICENSE)
+
+Getting started
+---------------
+
+You need a functioning [Redis](http://redis.io) installation. Once Redis is
+installed you can start it by running `redis-server`, this will run Redis in the
+foreground.
+
+You can use Boffin in many different contexts, but the most common one is
+probably that of a Rails or Sinatra application. Just add `boffin` to your
+[Gemfile](http://gembundler.com):
+
+```ruby
+gem 'boffin'
+```
+
+For utmost performance on *nix-based systems, require
+[hiredis](https://github.com/pietern/hiredis-rb) before you require Boffin:
+
+```ruby
+gem 'hiredis'
+gem 'boffin'
+```
+
+Configuration
+-------------
+
+Most of Boffin's default configuration options are quite reasonable, but they
+are easy to change if required:
+
+```ruby
+Boffin.configure do |c|
+  c.redis              = MyApp.redis             # Redis.connect by default
+  c.namespace          = "tracking:#{MyApp.env}" # Redis key namespace
+  c.hours_window_secs  = 3.days     # Time to maintain hourly interval data
+  c.days_window_secs   = 3.months   # Time to maintain daily interval data
+  c.months_window_secs = 3.years    # Time to maintain monthly interval data
+  c.cache_expire_secs  = 15.minutes # Time to cache Tracker#top result sets
+end
+```
+
+Tracking
+--------
+
+A Tracker is responsible for maintaining a namespace for hits. For our examples
+we will have a model called `Listing` it represents a listing in our realty
+web app. We want to track when someone likes, shares, or views a listing.
+
+Our example web app uses [Sinatra](http://sinatrarb.com) as its framework, and
+[Sequel](http://sequel.rubyforge.org)::Model as its ORM. It's important to note
+that Boffin has no requirements on any of these things, it can be used to track
+any Ruby class in any environment.
+
+Start by telling Boffin to make the Listing model trackable:
+
+```ruby
+Boffin.track(Listing)
+```
+
+**_or_**
+
+```ruby
+class Listing < Sequel::Model
+  include Boffin::Trackable
+end
+```
+
+You can optionally specify the types of hits that are acceptable, this is good
+practice and will save frustrating moments where you accidentally type `:view`
+instead of `:views`, to do that:
+
+```ruby
+Boffin.track(Listing, [:likes, :shares, :views])
+```
+
+**_or_**
+
+```ruby
+class Listing < Sequel::Model
+  include Boffin::Trackable
+  boffin.hit_types = [:likes, :shares, :views]
+end
+```
+
+**_or_**
+
+```ruby
+class Listing < Sequel::Model
+  Boffin.track(self, [:likes, :shares, :views])
+end
+```
+
+Now to track hits on instances of the Listing model, simply:
+
+```ruby
+get '/listings/:id' do
+  @listing = Listing[params[:id]]
+  @listing.hit(:views)
+  haml :'listings/show'
+end
+```
+
+However you will probably want to provide Boffin with some uniqueness to
+identify hits from particular users or sessions:
+
+```ruby
+get '/listings/:id' do
+  @listing = Listing[params[:id]]
+  @listing.hit(:views, [current_user, session[:id]])
+  haml :'listings/show'
+end
+```
+
+Boffin now adds uniqueness to the hit in the form of `current_user.id` if
+available. If `current_user` is nil, Boffin then uses `session[:id]`. You can
+provide as many uniquenesses as you'd like, the first one that is not blank
+(`nil`, `false`, `[]`, `{}`, or `''`) will be used.
+
+It could get a bit tedious having to add `[current_user, session[:id]]` whenever
+we want to hit an instance, so let's create a helper:
+
+```ruby
+helpers do
+  def hit(trackable, type)
+    trackable.hit(type, [current_user, session[:id]])
+  end
+end
+```
+
+For these examples we are in the context of a Sinatra application, but this is
+applicable to a Rails application as well:
+
+```ruby
+class ApplicationController < ActionController::Base
+  protected
+  def hit(trackable, type)
+    trackable.hit(type, [current_user, session[:session_id]])
+  end
+end
+```
+
+You get the idea, now storing a hit is as easy as:
+
+```ruby
+get '/listings/:id' do
+  @listing = Listing[params[:id]]
+  hit @listing, :views
+  haml :'listings/show'
+end
+```
+
+Reporting
+---------
+
+After some hits have been tracked, you can start to do some queries:
+
+**Get a count of all views for an instance**
+
+```ruby
+@listing.hit_count(:views)
+```
+
+**Get count of unique views for an instance**
+
+```ruby
+@listing.uhit_count(:views)
+```
+
+**Get IDs of the most viewed listings in the past 5 days**
+
+```ruby
+Listing.top_ids(:views, days: 5)
+```
+
+**Get IDs of the least viewed listings (that were viewed) in the past 8 hours**
+
+```ruby
+Listing.top_ids(:views, hours: 8, order: 'asc')
+```
+
+**Get IDs and hit counts of the most liked listings in the past 5 days**
+
+```ruby
+Listing.top_ids(:likes, days: 5, counts: true)
+```
+
+**Get IDs of the most liked, viewed, and shared listings with likes weighted
+higher than views in the past 12 hours**
+
+```ruby
+Listing.top_ids({ likes: 2, views: 1, shares: 3 }, hours: 12)
+```
+
+**Get IDs and combined/weighted scores of the most liked, and viewed listings in
+the past 7 days**
+
+```ruby
+Listing.top_ids({ likes: 2, views: 1 }, hours: 12, counts: true)
+```
+
+Boffin records hits in time intervals: hours, days, and months. Each interval
+has a window of time that it is available before it expires; these windows are
+configurable. It's also important to note that the results returned by these
+methods are cached for the duration of `Boffin.config.cache_expire_secs`. See
+**Configuration** above.
+
+More
+====
+
+Not just for models
+-------------------
+
+As stated before, you can use Boffin to track anything. Maybe you'd like to
+track your friends' favourite and least favourite colours:
+
+```ruby
+@tracker = Boffin::Tracker.new(:colours, [:faves, :unfaves])
+
+@tracker.hit(:faves,   'red',    ['lena'])
+@tracker.hit(:unfaves, 'blue',   ['lena'])
+@tracker.hit(:faves,   'green',  ['soren'])
+@tracker.hit(:unfaves, 'red',    ['soren'])
+@tracker.hit(:faves,   'green',  ['jens'])
+@tracker.hit(:unfaves, 'yellow', ['jens'])
+
+@tracker.top(:faves, months: 1)
+```
+
+Or, perhaps you'd like to clone Twitter? Using Boffin, all the work is
+essentially done for you*:
+
+```ruby
+WordsTracker = Boffin::Tracker.new(:words, [:searches, :tweets])
+
+get '/search' do
+  @tweets = Tweet.search(params[:q])
+  params[:q].split.each { |word| WordsTracker.hit(:searches, word) }
+  haml :'search/show'
+end
+
+post '/tweets' do
+  @tweet = Tweet.create(params[:tweet])
+  if @tweet.valid?
+    @tweet.words.each { WordsTracker.hit(:tweets, word) }
+    redirect to("/tweets/#{@tweet.id}")
+  else
+    haml :'tweets/form'
+  end
+end
+
+get '/trends' do
+  @words = WordsTracker.top({ tweets: 3, searches: 1 }, hours: 5)
+  haml :'trends/index'
+end
+```
+_*This is a joke._
+
+TODO
+----
+
+ * Ability to hit multiple instances in one command
+ * Ability to get hit-count range for an instance
+ * Some nice examples with pretty things
+ * ORM adapters for niceness and tighter integration
+ * Examples of how to turn IDs back into instances
+ * Reporting DSL thingy
+ * Web framework integration (helpers for tracking hits)
+ * Ability to blend unique hits with raw hits
+ * Ability to unhit an instance (if a model instance is destroyed for example)
+
+FAQ
+---
+
+### What's with the name?
+
+Well, it means [this](http://en.wikipedia.org/wiki/Boffin). For the purposes of
+this project, its use is very tongue-in-cheek.
+
+### Are you British?
+
+No, I'm just weird, but [this guy](http://github.com/aanand) is a real British person.

data/Rakefile

@@ -0,0 +1,14 @@
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rake'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+task default: :spec

data/boffin.gemspec

@@ -0,0 +1,29 @@
+require File.expand_path('../lib/boffin/version', __FILE__)
+
+Gem::Specification.new do |s|
+  s.name              = 'boffin'
+  s.version           = Boffin::VERSION
+  s.platform          = Gem::Platform::RUBY
+  s.date              = Date.today.strftime('%F')
+  s.homepage          = 'http://github.com/heycarsten/boffin'
+  s.author            = 'Carsten Nielsen'
+  s.email             = 'heycarsten@gmail.com'
+  s.summary           = 'Hit tracking library for Ruby using Redis'
+  s.has_rdoc          = 'yard'
+  s.rubyforge_project = 'boffin'
+  s.files             = `git ls-files`.split(?\n)
+  s.test_files        = `git ls-files -- spec/*`.split(?\n)
+  s.require_paths     = ['lib']
+
+  s.add_dependency             'redis',   '>= 2.2'
+  s.add_development_dependency 'rspec',   '~> 2.6'
+  s.add_development_dependency 'timecop'
+
+  s.description = <<-END
+Boffin is a library for tracking hits to things in your Ruby application. Things
+can be IDs of records in a database, strings representing tags or topics, URLs
+of webpages, names of places, whatever you desire. Boffin is able to provide
+lists of those things based on most hits, least hits, it can even report on
+weighted combinations of different types of hits.
+  END
+end

data/lib/boffin.rb

@@ -0,0 +1,87 @@
+require 'base64'
+require 'date'
+require 'time'
+require 'redis'
+require 'boffin/version'
+require 'boffin/utils'
+require 'boffin/config'
+require 'boffin/keyspace'
+require 'boffin/tracker'
+require 'boffin/hit'
+require 'boffin/trackable'
+
+# Boffin is a library for tracking hits to things in your Ruby application.
+# Things can be IDs of records in a database, strings representing tags or
+# topics, URLs of webpages, names of places, whatever you desire. Boffin is able
+# to provide lists of those things based on most hits, least hits, it can even
+# report on weighted combinations of different types of hits.
+#
+# Refer to the {file:README} for further information and examples.
+module Boffin
+  # The member to use when no session identifier is available for unique hit
+  # tracking
+  NIL_SESSION_MEMBER = 'boffin:nilsession'
+
+  # The way Time should be formatted for each interval type
+  INTERVAL_FORMATS = {
+    hours:  '%F-%H',
+    days:   '%F',
+    months: '%Y-%m' }
+
+  # Different interval types
+  INTERVAL_TYPES = INTERVAL_FORMATS.keys
+
+  # Raised by Tracker when hit types are passed to it that are not included in
+  # its list of valid hit types.
+  class UndefinedHitTypeError < StandardError; end
+
+  # Set or get the default Config instance
+  # @param [Hash] opts
+  #   (see {Config#initialize})
+  # @return [Config]
+  #   the default Config instance
+  # @yield [Config.new]
+  #   Passes the block to {Config#initialize}
+  # @example Getting the default config instance
+  #   Boffin.config
+  # @example Setting the default config instance with a block
+  #   Boffin.config do |conf|
+  #     conf.namespace = 'something:special'
+  #   end
+  # @example Setting the default config instance with a Hash
+  #   Boffin.config(namespace: 'something:cool')
+  def self.config(opts = {}, &block)
+    @config ||= Config.new(opts, &block)
+  end
+
+  # Creates a new Tracker instance. If passed a class, Trackable is injected
+  # into it.
+  # @param [Class, Symbol] class_or_ns
+  #   A class or symbol to use as a namespace for the Tracker
+  # @param [optional Array <Symbol>] hit_types
+  #   A list of valid hit types for the Tracker
+  # @return [Tracker]
+  # @example Tracking an ActiveRecord model
+  #   Boffin.track(MyModel, [:views, :likes])
+  #
+  #   # This does the same thing:
+  #   class MyModel
+  #     include Boffin::Tracker
+  #     boffin.hit_types = [:views, :likes]
+  #   end
+  # @example Creating a tracker without fancy injecting-ness
+  #   ThingsTracker = Boffin.track(:things)
+  #
+  #   # This does the same thing:
+  #   ThingsTracker = Boffin::Tracker.new(:things)
+  def self.track(class_or_ns, hit_types = [])
+    case class_or_ns
+    when String, Symbol
+      Tracker.new(class_or_ns, hit_types)
+    else
+      class_or_ns.send(:include, Trackable)
+      class_or_ns.boffin.hit_types = hit_types
+      class_or_ns.boffin
+    end
+  end
+end