retained 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4a7991fa6200e314740535ab1bdb2291368f9ade
+  data.tar.gz: 7b14b392c420a4ddea336837024812995f341ccb
+SHA512:
+  metadata.gz: 7377288f5071fb2451156242d399a4b5d72c29ff88111c453dfc5951fb000d81acb363fd84150fa1b1db20a83024b566d641985999100164f34ff4a8f7837609
+  data.tar.gz: 90f1c51c1ee2c9da74490d226b1eaa86b64710053b997e4e50a09906a51631f2dd5e0f2a4e7a37f86d155f55cca4cb40b24dc6be66735f5fb4dee45f2f42b0ff

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/Gemfile

@@ -0,0 +1,15 @@
+source 'http://rubygems.org'
+
+gem 'redis', '~> 3.1.0'
+gem 'redis-bitops', '~> 0.2.1'
+gem 'activesupport', '~> 4.1.5'
+
+group :development do
+  gem 'minitest', '>= 0'
+  gem 'yard', '~> 0.7'
+  gem 'rdoc', '~> 3.12'
+  gem 'bundler', '~> 1.0'
+  gem 'jeweler', '~> 2.0.1'
+  gem 'simplecov', '>= 0'
+  gem 'timecop', '~> 0.7.1'
+end

data/Gemfile.lock

@@ -0,0 +1,84 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (4.1.5)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    addressable (2.3.6)
+    builder (3.2.2)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    docile (1.1.5)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    git (1.2.7)
+    github_api (0.12.1)
+      addressable (~> 2.3)
+      descendants_tracker (~> 0.0.4)
+      faraday (~> 0.8, < 0.10)
+      hashie (>= 3.2)
+      multi_json (>= 1.7.5, < 2.0)
+      nokogiri (~> 1.6.3)
+      oauth2
+    hashie (3.3.1)
+    highline (1.6.21)
+    i18n (0.6.11)
+    jeweler (2.0.1)
+      builder
+      bundler (>= 1.0)
+      git (>= 1.2.5)
+      github_api
+      highline (>= 1.6.15)
+      nokogiri (>= 1.5.10)
+      rake
+      rdoc
+    json (1.8.1)
+    jwt (1.0.0)
+    mini_portile (0.6.0)
+    minitest (5.4.0)
+    multi_json (1.10.1)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    nokogiri (1.6.3.1)
+      mini_portile (= 0.6.0)
+    oauth2 (1.0.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    rack (1.5.2)
+    rake (10.3.2)
+    rdoc (3.12.2)
+      json (~> 1.4)
+    redis (3.1.0)
+    redis-bitops (0.2.1)
+      redis
+    simplecov (0.9.0)
+      docile (~> 1.1.0)
+      multi_json
+      simplecov-html (~> 0.8.0)
+    simplecov-html (0.8.0)
+    thread_safe (0.3.4)
+    timecop (0.7.1)
+    tzinfo (1.1.0)
+      thread_safe (~> 0.1)
+    yard (0.8.7.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 4.1.5)
+  bundler (~> 1.0)
+  jeweler (~> 2.0.1)
+  minitest
+  rdoc (~> 3.12)
+  redis (~> 3.1.0)
+  redis-bitops (~> 0.2.1)
+  simplecov
+  timecop (~> 0.7.1)
+  yard (~> 0.7)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2014 Mike Saffitz
+
+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,94 @@
+# Retained: Activity & Retention Tracking at Scale
+
+Retained makes it easy to track activity and retention at scale in daily, hourly, or minute intervals using sparse Redis bitmaps.
+
+
+## Requirements
+
+* Ruby 2.0.0 or above
+* Redis
+
+## Installing Retained
+
+Use RubyGems to install Retained:
+
+	$ gem install retained
+	
+If you are using Bundler, you can also install it by adding it to your Gemfile:
+
+	gem 'retained'
+	
+Run `bundle install` to install.
+
+## Basic Usage 
+
+Retained works by tracking whether an **entity** was active within a reporting interval for a specific **group**. Entities can be anything you wish to track activity for, and are identified by a unique identifier that you provide to Retained.  Groups provide a scope for the entities activity.  For example, groups allow you to track activity by a User (entity) for a specific feature of your product.  Like entities, groups are identified by a unique identifier that you provide to Retained.
+
+### Retained Defaults
+
+Retained's default settings are to connect to Redis at `redis://localhost:6379`, to prefix all keys with `retained`, and to track activity within the `default` group at a daily interval.  **Note:**  All dates are stored internally as UTC.
+
+### Examples
+
+To track an entity with an id of `entity_id` as active for the current day:
+
+	Retained.retain('entity_id')
+
+To track an entity with an id of `entity_id` as active on another day:
+
+	Retained.retain('entity_id', period: Time.new(2013,10,1))
+	
+To query whether an entity was active on a given day:
+
+	Retained.active?('entity_id', period: Time.new(2014,3,21))
+
+To determine the total number of active entities on a given day:
+
+	Retained.total_active(period: Time.new(2014,2,10))
+
+## Advanced Usage
+
+### Configuration
+
+Retained can be configured with an alternate Redis connection string as well as an alternate prefix for keys:
+
+	Retained.configure do |config|
+	  config.redis = 'redis://example.org:6379'
+	  config.prefix = 'my_prefix',
+	end
+	
+You can also configure groups to use an alternate reporting interval-- either daily, hourly, or by minute.
+
+**Important!** Once set, a group's reporting interval **cannot** be changed. 
+
+For example, to configure a 'generated_report' group to use an hourly interval:
+
+	Retained.configure do |config|
+	  config.group('generated_report).do |group|
+	    group.reporting_interval = :hour
+	  end
+	end
+
+### Non-Singleton Use
+
+You can connect to multiple backends for Retained by instantiating a Retained tracker directly:
+
+	tracker = Retained::Tracker.new
+	tracker.configure do |config|
+	  config.redis = 'redis://other.example.org:6379'
+	end
+	tracker.retain('entity_id)
+
+## Contributing to retained
+
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+
+---
+Copyright (c) 2014 Mike Saffitz. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+require './lib/retained/version.rb'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://guides.rubygems.org/specification-reference/ for more options
+  gem.name = 'retained'
+  gem.homepage = 'http://github.com/msaffitz/retained'
+  gem.license = 'MIT'
+  gem.summary = %Q{Activity & Retention Tracking at Scale}
+  gem.description = %Q{
+    Easy tracking of activity and retention at scale in daily, hourly, or minute intervals
+    using sparse Redis bitmaps.
+  }
+  gem.email = 'm@saffitz.com'
+  gem.authors = ['Mike Saffitz']
+  gem.version = Retained::Version::STRING
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_spec.rb'
+  test.verbose = true
+end
+
+desc 'Code coverage detail'
+task :simplecov do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task['test'].execute
+end
+
+task :default => :test
+
+require 'yard'
+YARD::Rake::YardocTask.new

data/lib/retained/configuration.rb

@@ -0,0 +1,51 @@
+require 'retained/redis_connection'
+require 'retained/group_configuration'
+
+module Retained
+  class Configuration
+    attr_accessor :redis
+    attr_accessor :prefix
+    attr_reader :default_group
+    attr_reader :group_configs
+
+    def initialize
+      @redis = { url: 'redis://localhost:6379' }
+      @prefix = 'retained'
+      @default_group = 'default'
+      @group_configs = {}
+    end
+
+    # Retrieve the configuration for the group. A block may be provided
+    # to configure the group.
+    def group(group)
+      @group_configs[group.to_s] ||= fetch_group_configuration(group)
+
+      if block_given?
+        yield(@group_configs[group.to_s])
+        save_group_configuration(group, @group_configs[group.to_s])
+      else
+        @group_configs[group.to_s].set_defaults
+      end
+
+      @group_configs[group.to_s]
+    end
+
+    def redis_connection
+      @redis_connection ||= RedisConnection.new(redis)
+    end
+
+    private
+
+    def fetch_group_configuration(group)
+      redis_connection.sadd "#{prefix}:groups", group.to_s
+      GroupConfiguration.new(redis_connection.hgetall "#{prefix}:group_config:#{group}")
+    end
+
+    def save_group_configuration(group, configuration)
+      configuration.set_defaults
+      redis_connection.hmset "#{prefix}:group_config:#{group}", *configuration.to_hash
+      redis_connection.sadd "#{prefix}:groups", group.to_s
+      @group_configs[group.to_s] = configuration
+    end
+  end
+end

data/lib/retained/group_configuration.rb

@@ -0,0 +1,38 @@
+module Retained
+  class GroupConfiguration
+    attr_reader :reporting_interval
+
+    ReportingIntervals = %i(day hour minute).freeze
+
+    def initialize(options = {})
+      @reporting_interval = nil
+
+      options.each do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    def reporting_interval=(reporting_interval)
+      reporting_interval = reporting_interval.to_sym
+
+      if @reporting_interval && @reporting_interval != reporting_interval
+        fail 'Group reporting_interval is immutable once set'
+      elsif !ReportingIntervals.include?(reporting_interval)
+        fail ArgumentError, "Invalid reporting_interval: `#{reporting_interval}`.  Must be one of #{ReportingIntervals}"
+      end
+
+      @reporting_interval = reporting_interval
+    end
+
+    def set_defaults
+      @reporting_interval ||= :day
+    end
+
+    # Returns the configuration as a hash of key/values
+    def to_hash
+      {
+        reporting_interval: reporting_interval
+      }
+    end
+  end
+end

data/lib/retained/redis_connection.rb

@@ -0,0 +1,15 @@
+require 'redis'
+
+module Retained
+  class RedisConnection
+    attr_reader :client
+
+    def initialize(options = {})
+      @client = Redis.new(options)
+    end
+
+    def method_missing(method, *args, &block)
+      @client.send(method, *args, &block)
+    end
+  end
+end

data/lib/retained/tracker.rb

@@ -0,0 +1,77 @@
+require 'redis/bitops'
+require 'active_support/core_ext/time'
+require 'retained/configuration'
+
+module Retained
+  class Tracker
+    attr_accessor :config
+
+    def initialize(config = Configuration.new)
+      @config = config
+    end
+
+    def configure
+      yield(config)
+    end
+
+    # Tracks the entity as active at the period, or now if no period
+    # is provided.
+    def retain(entity, group: group, period: Time.now)
+      index = entity_index(entity, group)
+      bitmap = config.redis_connection.sparse_bitmap(key_period(group, period))
+      bitmap[index] = true
+    end
+
+    # Total active entities in the period, or now if now period,
+    # is provided.
+    def total_active(group: group, period: Time.now)
+      bitmap = config.redis_connection.sparse_bitmap(key_period(group, period))
+      bitmap.bitcount
+    end
+
+    # Returns true if the entity was active in the given period,
+    # or now if now period is provided.  If a group or an array of groups
+    # is provided activity will only be considered based on those groups.
+    def active?(entity, group: nil, period: Time.now)
+      group = [group] if group.is_a?(String)
+      group = groups if group == [] || !group
+
+      group.to_a.each do |g|
+        bitmap = config.redis_connection.sparse_bitmap(key_period(g, period))
+        index = entity_index(entity, g)
+        return bitmap[index] if bitmap[index]
+      end
+      false
+    end
+
+    # Returns an array of all groups
+    def groups
+      config.redis_connection.smembers "#{config.prefix}:groups"
+    end
+
+    # Returns the index (offset) of the entity within the group.
+    #
+    # Thanks to crashlytics for the monotonic_zadd approach taken here
+    # http://www.slideshare.net/crashlytics/crashlytics-on-redis-analytics
+    def entity_index(entity, group)
+      monotonic_zadd = <<LUA
+        local sequential_id = redis.call('zscore', KEYS[1], ARGV[1])
+        if not sequential_id then
+          sequential_id = redis.call('zcard', KEYS[1])
+          redis.call('zadd', KEYS[1], sequential_id, ARGV[1])
+        end
+        return sequential_id
+LUA
+
+      key = "#{config.prefix}:entity_ids:#{group}"
+      config.redis_connection.eval(monotonic_zadd, [key], [entity.to_s]).to_i
+    end
+
+    # Returns the key for the group at the period.  All periods are
+    # internally stored relative to UTC.
+    def key_period(group, period)
+      period = period.utc.send("beginning_of_#{config.group(group).reporting_interval}")
+      "#{config.prefix}:#{group}:#{period.to_i}"
+    end
+  end
+end

data/lib/retained/version.rb

@@ -0,0 +1,10 @@
+module Retained
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    BUILD = nil
+
+    STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
+  end
+end

data/lib/retained.rb

@@ -0,0 +1,13 @@
+require 'retained/tracker'
+require 'retained/version'
+require 'forwardable'
+
+module Retained
+  @tracker = Tracker.new
+
+  class << self
+    def method_missing(meth, *args, &block)
+      @tracker.send(meth, *args, &block)
+    end
+  end
+end

data/retained.gemspec

@@ -0,0 +1,84 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+# stub: retained 0.1.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "retained"
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib"]
+  s.authors = ["Mike Saffitz"]
+  s.date = "2014-09-21"
+  s.description = "\n    Easy tracking of activity and retention at scale in daily, hourly, or minute intervals\n    using sparse Redis bitmaps.\n  "
+  s.email = "m@saffitz.com"
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.md"
+  ]
+  s.files = [
+    ".document",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.md",
+    "Rakefile",
+    "lib/retained.rb",
+    "lib/retained/configuration.rb",
+    "lib/retained/group_configuration.rb",
+    "lib/retained/redis_connection.rb",
+    "lib/retained/tracker.rb",
+    "lib/retained/version.rb",
+    "retained.gemspec",
+    "test/configuration_spec.rb",
+    "test/group_configuration_spec.rb",
+    "test/helper.rb",
+    "test/tracker_spec.rb"
+  ]
+  s.homepage = "http://github.com/msaffitz/retained"
+  s.licenses = ["MIT"]
+  s.rubygems_version = "2.2.2"
+  s.summary = "Activity & Retention Tracking at Scale"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 4
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<redis>, ["~> 3.1.0"])
+      s.add_runtime_dependency(%q<redis-bitops>, ["~> 0.2.1"])
+      s.add_runtime_dependency(%q<activesupport>, ["~> 4.1.5"])
+      s.add_development_dependency(%q<minitest>, [">= 0"])
+      s.add_development_dependency(%q<yard>, ["~> 0.7"])
+      s.add_development_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_development_dependency(%q<simplecov>, [">= 0"])
+      s.add_development_dependency(%q<timecop>, ["~> 0.7.1"])
+    else
+      s.add_dependency(%q<redis>, ["~> 3.1.0"])
+      s.add_dependency(%q<redis-bitops>, ["~> 0.2.1"])
+      s.add_dependency(%q<activesupport>, ["~> 4.1.5"])
+      s.add_dependency(%q<minitest>, [">= 0"])
+      s.add_dependency(%q<yard>, ["~> 0.7"])
+      s.add_dependency(%q<rdoc>, ["~> 3.12"])
+      s.add_dependency(%q<bundler>, ["~> 1.0"])
+      s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+      s.add_dependency(%q<simplecov>, [">= 0"])
+      s.add_dependency(%q<timecop>, ["~> 0.7.1"])
+    end
+  else
+    s.add_dependency(%q<redis>, ["~> 3.1.0"])
+    s.add_dependency(%q<redis-bitops>, ["~> 0.2.1"])
+    s.add_dependency(%q<activesupport>, ["~> 4.1.5"])
+    s.add_dependency(%q<minitest>, [">= 0"])
+    s.add_dependency(%q<yard>, ["~> 0.7"])
+    s.add_dependency(%q<rdoc>, ["~> 3.12"])
+    s.add_dependency(%q<bundler>, ["~> 1.0"])
+    s.add_dependency(%q<jeweler>, ["~> 2.0.1"])
+    s.add_dependency(%q<simplecov>, [">= 0"])
+    s.add_dependency(%q<timecop>, ["~> 0.7.1"])
+  end
+end
+

data/test/configuration_spec.rb

@@ -0,0 +1,19 @@
+require 'helper'
+
+describe Retained::Configuration do
+  let(:configuration) { Retained::Configuration.new }
+
+  it 'configures groups' do
+    configuration.group('group_a') do |group|
+      group.reporting_interval = :day
+    end
+    configuration.group('group_a').reporting_interval.must_equal :day
+  end
+
+  it 'loads saved configuration' do
+    configuration.group('group_b') do |group|
+      group.reporting_interval = :minute
+    end
+    Retained::Configuration.new.group('group_b').reporting_interval.must_equal :minute
+  end
+end

data/test/group_configuration_spec.rb

@@ -0,0 +1,20 @@
+require 'helper'
+
+describe Retained::GroupConfiguration do
+  let(:group_configuration) { Retained::GroupConfiguration.new }
+
+  it 'reporting_interval is set' do
+    group_configuration.reporting_interval = :day
+    group_configuration.reporting_interval.must_equal :day
+  end
+
+  it 'reporting_interval cannot be changed once set' do
+    group_configuration.reporting_interval = :day
+    proc { group_configuration.reporting_interval = 'month' }.must_raise RuntimeError
+  end
+
+  it 'reporting_interval must be hour, minute, or day' do
+    proc { group_configuration.reporting_interval = :week }.must_raise ArgumentError
+    proc { group_configuration.reporting_interval = 'month' }.must_raise ArgumentError
+  end
+end

data/test/helper.rb

@@ -0,0 +1,32 @@
+require 'simplecov'
+
+module SimpleCov::Configuration
+  def clean_filters
+    @filters = []
+  end
+end
+
+SimpleCov.configure do
+  clean_filters
+  load_profile 'test_frameworks'
+end
+
+ENV['COVERAGE'] && SimpleCov.start do
+  add_filter '/.rvm/'
+end
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts 'Run `bundle install` to install missing gems'
+  exit e.status_code
+end
+require 'minitest/spec'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'retained'
+
+MiniTest.autorun

data/test/tracker_spec.rb

@@ -0,0 +1,106 @@
+require 'helper'
+require 'securerandom'
+require 'timecop'
+Timecop.safe_mode = true
+
+
+describe Retained::Tracker do
+  let(:tracker) { Retained::Tracker.new }
+
+  before(:each) do
+    tracker.config.redis_connection.flushdb
+  end
+
+  it 'retain tracks using the default group in the current period' do
+    Timecop.freeze(Time.new(2014, 8, 29, 9, 03, 35)) do
+     tracker.retain('entity_a')
+      prefix = tracker.config.prefix
+      group  = tracker.config.default_group
+      tracker.config.redis_connection.sparse_bitmap("#{prefix}:#{group}:1409328000")[0]
+    end
+  end
+
+  it 'retain tracks the entity for the period specified' do
+    period = Time.new(2014, 8, 30, 10, 47, 35)
+    tracker.retain('entity_a', group: 'group_a', period: period)
+
+    prefix = tracker.config.prefix
+    tracker.config.redis_connection.sparse_bitmap("#{prefix}:group_a:1409356800")[0]
+  end
+
+  it 'retain without a period tracks the entity for the current period' do
+    Timecop.freeze(Time.new(2014, 8, 29, 9, 03, 35)) do
+      tracker.retain('entity_a', group: 'group_a')
+
+      prefix = tracker.config.prefix
+      tracker.config.redis_connection.sparse_bitmap("#{prefix}:group_a:1409328000")[0]
+    end
+  end
+
+  it 'total_active returns the number of active entities in the default group in the period' do
+    period = Time.new(2014, 8, 30, 10, 47, 35)
+    (count = rand(100)).times do |i|
+      tracker.retain("entity_#{i}", period: period)
+    end
+    tracker.total_active(period: period).must_equal count
+  end
+
+  it 'total_active returns the number of active entities in the period' do
+    period = Time.new(2014, 8, 30, 10, 47, 35)
+    (count = rand(100)).times do |i|
+      tracker.retain("entity_#{i}", group: 'group_a', period: period)
+    end
+    tracker.total_active(group: 'group_a', period: period).must_equal count
+  end
+
+  it 'total_active without a period returns the number of active entities for the current period' do
+    (count = rand(100)).times do |i|
+      tracker.retain("entity_#{i}", group: 'group_a', period: Time.now)
+    end
+    tracker.total_active(group: 'group_a').must_equal count
+  end
+
+  describe 'active?' do
+    it 'returns true when the entity is active' do
+      Timecop.freeze do
+        tracker.retain('entity_a', group: 'group_a', period: Time.now)
+        tracker.active?('entity_a', group: 'group_a', period: Time.now).must_equal true
+        tracker.active?('entity_a', period: Time.now).must_equal true
+        tracker.active?('entity_a').must_equal true
+        tracker.active?('entity_a', group: ['group_a']).must_equal true
+      end
+    end
+
+    it 'returns false when the entity was not active' do
+      Timecop.freeze do
+        tracker.retain('entity_a', group: 'group_a', period: Time.now)
+        tracker.active?('entity_b').must_equal false
+        tracker.active?('entity_a', group: 'group_b').must_equal false
+      end
+    end
+  end
+
+  it 'entity_index returns the offset' do
+    group_a = SecureRandom.hex
+    entity_a = SecureRandom.hex
+    entity_b = SecureRandom.hex
+
+    tracker.entity_index(entity_a, group_a).must_equal 0
+    tracker.entity_index(entity_b, group_a).must_equal 1
+    tracker.entity_index(SecureRandom.hex, group_a).must_equal 2
+    tracker.entity_index(entity_a, SecureRandom.hex).must_equal 0
+    tracker.entity_index(entity_b, group_a).must_equal 1
+  end
+
+  it 'key_period returns the proper key for the given period' do
+    tracker.configure do |config|
+      config.group('hour') { |g| g.reporting_interval = :hour }
+      config.group('minute') { |g| g.reporting_interval = :minute }
+      config.group('day') { |g| g.reporting_interval = :day}
+    end
+
+    tracker.key_period('hour', Time.new(2014, 8, 30, 10, 35, 47, 0)).must_equal 'retained:hour:1409392800'
+    tracker.key_period('minute', Time.new(2014, 8, 30, 10, 35, 47, 5*3600)).must_equal 'retained:minute:1409376900'
+    tracker.key_period('day', Time.new(2014, 8, 30, 10, 35, 47, -2*3600)).must_equal 'retained:day:1409356800'
+  end
+end

metadata

@@ -0,0 +1,203 @@
+--- !ruby/object:Gem::Specification
+name: retained
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mike Saffitz
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: redis-bitops
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.1
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.1.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.1.5
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+description: "\n    Easy tracking of activity and retention at scale in daily, hourly,
+  or minute intervals\n    using sparse Redis bitmaps.\n  "
+email: m@saffitz.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.md
+files:
+- ".document"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/retained.rb
+- lib/retained/configuration.rb
+- lib/retained/group_configuration.rb
+- lib/retained/redis_connection.rb
+- lib/retained/tracker.rb
+- lib/retained/version.rb
+- retained.gemspec
+- test/configuration_spec.rb
+- test/group_configuration_spec.rb
+- test/helper.rb
+- test/tracker_spec.rb
+homepage: http://github.com/msaffitz/retained
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Activity & Retention Tracking at Scale
+test_files: []