bluecap 0.0.1

data/lib/bluecap/handlers/event.rb

@@ -0,0 +1,54 @@
+require 'date'
+
+module Bluecap
+  class Event
+
+    attr_reader :id, :name, :timestamp
+
+    # Initialize an Event handler.
+    #
+    # data - A Hash containing event data:
+    #        :id        - The Integer identifer of the user that generated
+    #                     the event.
+    #        :name      - The String type of event.
+    #        :timestamp - The Integer UNIX timestamp when the event was created,
+    #                     defaults to current time (optional).
+    #
+    # Examples
+    #
+    #    Bluecap::Event.new(
+    #      id: 3,
+    #      name: 'Created Account',
+    #      timestamp: 1341845456
+    #    )
+    def initialize(data)
+      @id = data.fetch(:id)
+      @name = data.fetch(:name)
+      @timestamp = data.fetch(:timestamp, Time.now.to_i)
+    end
+
+    # Converts the object's timestamp to a %Y%m%d String.
+    #
+    # Returns the String date.
+    def date
+      Time.at(@timestamp).strftime('%Y%m%d')
+    end
+
+    # Proxy for an event key.
+    #
+    # Returns the String key.
+    def key
+      Bluecap::Keys.event(@name, date)
+    end
+
+    # Store the user's event in a bitset of all the events matching that name
+    # for the date.
+    #
+    # Returns nil.
+    def handle
+      Bluecap.redis.setbit(key, @id, 1)
+
+      nil
+    end
+  end
+end

data/lib/bluecap/handlers/identify.rb

@@ -0,0 +1,40 @@
+module Bluecap
+  class Identify
+
+    attr_reader :name
+
+    # Initialize an Identify handler.
+    #
+    # name - A String to uniquely identify the user from the source system.
+    #
+    def initialize(name)
+      @name = name
+    end
+
+    # Returns an id to track a user in Bluecap, creating an id if one does not
+    # already exist.
+    #
+    #   Bluecap::Identify.new('Andy').handle
+    #   # => 1
+    #
+    #   Bluecap::Identify.new('Evelyn').handle
+    #   # => 2
+    #
+    # Returns the Integer id.
+    def handle
+      id = Bluecap.redis.hget('user.map', @name)
+      return id.to_i if id
+
+      id = Bluecap.redis.incr('user.ids')
+      if Bluecap.redis.hsetnx('user.map', @name, id)
+        return id
+      else
+        # Race condition, another process has set the id for this user.
+        # The unused id shouldn't cause inaccuracies in reporting since
+        # the position will be 0 in all bitsets across the system.
+        return redis.hget('user.map', @name).to_i
+      end
+    end
+
+  end
+end

data/lib/bluecap/handlers/null_handler.rb

@@ -0,0 +1,19 @@
+module Bluecap
+  class NullHandler
+
+    attr_reader :data
+
+    # Initialize a NullHandler.
+    def initialize(data)
+      @data = data
+    end
+
+    # Catch the handle message.
+    #
+    # Returns nothing.
+    def handle
+      Bluecap.log "NullHandler received message, contents: #{@data}"
+    end
+
+  end
+end

data/lib/bluecap/handlers/report.rb

@@ -0,0 +1,75 @@
+require 'date'
+require 'securerandom'
+
+module Bluecap
+  class Report
+
+    attr_reader :initial_event, :engagement_event, :attributes, :year_month
+
+    # Initialize a Report handler.
+    #
+    # data - A Hash containing options to scope the report by:
+    #        :initial_event     - The String event that cohorts shared.
+    #        :engagement_event  - The String event to track engagement by.
+    #        :attributes        - The Hash attributes of users (optional).
+    #        :start_date        - The String start date of the report.
+    #        :end_date          - The String end date of the report.
+    #
+    # Examples
+    #
+    #   Bluecap::Report.new(
+    #     initial_event: 'Created Account',
+    #     engagement_event: 'Logged In',
+    #     attributes: {
+    #       country: 'Australia',
+    #       gender: 'Female'
+    #     },
+    #     start_date: '20120401',
+    #     end_date: '20120430'
+    #   )
+    def initialize(data)
+      @initial_event = data.fetch(:initial_event)
+      @engagement_event = data.fetch(:engagement_event)
+      @attributes = data.fetch(:attributes, Hash.new)
+      @start_date = Date.parse(data.fetch(:start_date))
+      @end_date = Date.parse(data.fetch(:end_date))
+    end
+
+    def report_id
+      Bluecap.redis.incr('report.ids')
+    end
+
+    # Generates a report to track engagement of cohorts over time.
+    #
+    # Returns the String with report data in JSON format.
+    def handle
+      report = Hash.new
+      (@start_date...@end_date).each do |date|
+        cohort = Cohort.new(
+          :initial_event => @initial_event,
+          :attributes => @attributes,
+          :date => date,
+          :report_id => report_id
+        )
+
+        # The start date of the engagement is measured from the day after the
+        # initial event.
+        engagement = Engagement.new(
+          :cohort => cohort,
+          :engagement_event => engagement_event,
+          :start_date => date + 1,
+          :end_date => @end_date,
+          :report_id => report_id
+        )
+
+        cohort_results = Hash.new
+        cohort_results[:total] = cohort.total
+        cohort_results[:engagement] = engagement.measure
+        report[date.strftime('%Y%m%d')] = cohort_results
+      end
+
+      MultiJson.dump(report)
+    end
+
+  end
+end

data/lib/bluecap/keys.rb

@@ -0,0 +1,44 @@
+module Bluecap
+  module Keys
+
+    # Returns a cleaned version of a string for use in a Redis key. Strips,
+    # downcases, then treats any remaining characters like word separators
+    # as periods.
+    #
+    # str - The String to be cleaned.
+    #
+    # Examples
+    #
+    #   clean('Country')
+    #   # => "country"
+    #
+    #   clean('Logged In')
+    #   # => "logged.in"
+    #
+    # Returns the new String.
+    def self.clean(str)
+      str.strip.downcase.gsub(/[^a-z0-9]/, '.')
+    end
+
+    # Returns a key used to store the events for a day.
+    #
+    # Examples
+    #
+    #    Bluecap::Keys.event 'Sign Up', '20120710'
+    #    # => "events:sign.up:20120710"
+    #
+    # Returns the String key.
+    def self.event(name, date)
+      "events:#{clean(name)}:#{date}"
+    end
+
+    def self.cohort(report_id, cohort_id)
+      "reports:cohort:#{report_id}:#{cohort_id}"
+    end
+
+    def self.engagement(report_id, cohort_id, date)
+      "reports:e:#{report_id}:#{cohort_id}:#{date}"
+    end
+
+  end
+end

data/lib/bluecap/message.rb

@@ -0,0 +1,39 @@
+module Bluecap
+  class Message
+
+    # Initialize a Message with data.
+    #
+    # data - The String JSON message to parse.
+    def initialize(data)
+      @data = MultiJson.load(data, symbolize_keys: true)
+    end
+
+    # The signature of the handler that should respond to the message.
+    #
+    # Examples
+    #
+    #    message = Message.new('{"identify": "Evelyn"}')
+    #    message.recipient
+    #    # => :identify
+    #
+    # Returns the Symbol recipient of the messsage.
+    def recipient
+      @data.first[0].to_sym if @data.first
+    end
+
+    # The contents of the message.
+    #
+    # Examples
+    #
+    #    message = Message.new('{"identify": "Evelyn"}')
+    #    message.contents
+    #    # => "Evelyn"
+    #
+    # Returns the contents of the message; the data type is different based on
+    # the contents of the message.
+    def contents
+      @data.first[1]
+    end
+
+  end
+end

data/lib/bluecap/server.rb

@@ -0,0 +1,72 @@
+require 'socket'
+
+module Bluecap
+  module Server
+
+    # Returns a Hash of handlers, creating a new empty hash if none have
+    # previously been set.
+    def self.handlers
+      @handlers ||= {
+        attributes: Bluecap::Attributes,
+        event: Bluecap::Event,
+        identify: Bluecap::Identify,
+        report: Bluecap::Report
+      }
+    end
+
+    # Assign handlers to respond to new data.
+    #
+    # handlers - A Hash of lookup keys to handler classes.
+    #
+    # Examples
+    #
+    #   handlers = {
+    #     event: Bluecap::Event,
+    #     identify: Bluecap::Identify
+    #   }
+    #
+    # Returns nothing.
+    def self.handlers=(handlers)
+      @handlers = handlers
+    end
+
+    def process(message)
+      klass = Bluecap::Server.handlers.fetch(message.recipient, Bluecap::NullHandler)
+      port, ip_address = Socket.unpack_sockaddr_in(get_peername)
+      Bluecap.log "Message received for #{message.recipient} handler from #{ip_address}:#{port}"
+      handler = klass.new(message.contents)
+      handler.handle
+    end
+
+    # Process a message received from a client, sending a response if
+    # necessary.
+    #
+    # data - The String containing JSON received from the client.
+    #
+    # Examples
+    #
+    #    receive_data('{"identify": "Andy"}')
+    #
+    # Returns nothing.
+    def receive_data(data)
+      begin
+        message = Bluecap::Message.new(data)
+        response = process(message)
+        send_data(response) if response
+      rescue Exception => e
+        Bluecap.log e
+      end
+    end
+
+    # Starts a TCP server running on the EventMachine loop.
+    #
+    # Returns nothing.
+    def self.run
+      EventMachine::run do
+        EventMachine::start_server(Bluecap.host, Bluecap.port, Bluecap::Server)
+        Bluecap.log "Server started on #{Bluecap.host}:#{Bluecap.port}"
+      end
+    end
+
+  end
+end

data/spec/attributes_spec.rb

@@ -0,0 +1,43 @@
+require 'helper'
+
+describe Bluecap::Attributes do
+
+  before do
+    Bluecap.redis.flushall
+  end
+
+  subject do
+    Bluecap::Attributes.new :id => 3,
+      :attributes => {:country => 'Australia', :gender => 'Female'}
+  end
+
+  it 'should create attributes key' do
+    subject.key('gender', 'female').should == 'attributes:gender:female'
+  end
+
+  it 'should create attributes key using cleaned name and date' do
+    subject.key(' COUNTRY', 'Australia').should == 'attributes:country:australia'
+  end
+
+  it 'should create keys for multiple attributes' do
+    subject.keys.should =~ ['attributes:country:australia',
+                            'attributes:gender:female']
+  end
+
+  it 'should track attributes for user by setting corresponding bits to 1' do
+    data = {
+      attributes: {
+        gender: 'female',
+        country: 'australia',
+      },
+      id: 5
+    }
+
+    subject.handle
+
+    # Check that bits have changed.
+    Bluecap.redis.getbit('attributes:gender:female', subject.id).should == 1
+    Bluecap.redis.getbit('attributes:country:australia', subject.id).should == 1
+  end
+
+end

data/spec/cohort_spec.rb

@@ -0,0 +1,77 @@
+require 'helper'
+require 'date'
+
+describe Bluecap::Cohort do
+
+  before do
+    Bluecap.redis.flushall
+
+    @date = Date.parse('20120701')
+    @initial_event = 'Sign Up'
+    @attributes = {:country => 'Australia', :gender => 'Female'}
+    @users = {
+      :evelyn => Bluecap::Identify.new('Evelyn').handle,
+      :charlotte => Bluecap::Identify.new('Charlotte').handle
+    }
+    @users.values.each do |id|
+      event = Bluecap::Event.new :id => id,
+        :name => @initial_event,
+        :timestamp => @date.to_time.to_i
+      event.handle
+
+      attribute = Bluecap::Attributes.new  :id => id,
+        :attributes => @attributes
+      attribute.handle
+    end
+  end
+
+  it 'should find cohort total for date' do
+    cohort = Bluecap::Cohort.new :initial_event => @initial_event,
+      :date => @date,
+      :report_id => 1
+
+    cohort.total.should == 2
+  end
+
+  it 'should not include in cohort if initial event did not occur on date' do
+    sarah = Bluecap::Identify.new('Sarah').handle
+    event = Bluecap::Event.new :id => sarah,
+      :name => @initial_event,
+      :timestamp => (@date + 1).to_time.to_i
+    event.handle
+
+    cohort = Bluecap::Cohort.new :initial_event => @initial_event,
+      :date => @date,
+      :report_id => 1
+    cohort.total.should == 2
+  end
+
+  it 'should allow cohorts to be constructed with attributes of users' do
+    cohort = Bluecap::Cohort.new :initial_event => @initial_event,
+      :date => @date,
+      :attributes => @attributes,
+      :report_id => 1
+
+    cohort.total.should == 2
+  end
+
+  it 'shold not include in cohort if attributes are not matched' do
+    sarah = Bluecap::Identify.new('Sarah').handle
+    event = Bluecap::Event.new :id => sarah,
+      :name => @initial_event,
+      :timestamp => @date.to_time.to_i
+    event.handle
+    attributes = @attributes.clone
+    attributes[:country] = 'New Zealand'
+    attribute = Bluecap::Attributes.new :id => sarah,
+      :attributes => attributes
+    attribute.handle
+
+    cohort = Bluecap::Cohort.new :initial_event => @initial_event,
+      :date => @date,
+      :attributes => @attributes,
+      :report_id => 1
+    cohort.total.should == 2
+  end
+
+end