activr 1.0.0

data/lib/activr/rails_ctx.rb

@@ -0,0 +1,37 @@
+module Activr
+
+  #
+  # Rails Context holder
+  #
+  class RailsCtx
+
+    class_attribute :controller
+    self.controller = nil
+
+    class << self
+
+      # Get current Rails View context
+      #
+      # @return [ActionView::Base] Rails view instance
+      def view_context
+        @view_context ||= if defined?(::Rails)
+          rails_controller = self.controller || begin
+            fake_controller = ApplicationController.new
+            fake_controller.request = ActionController::TestRequest.new if defined?(ActionController::TestRequest)
+            fake_controller
+          end
+
+          rails_controller.view_context
+        end
+      end
+
+      # Clear memoization of current Rails view context
+      def clear_view_context!
+        @view_context = nil
+      end
+
+    end # class << self
+
+  end # class RailsCtx
+
+end # module Activr

data/lib/activr/railtie.rb

@@ -0,0 +1,73 @@
+module Activr
+
+  # Hook into Rails
+  class Railtie < ::Rails::Railtie
+    initializer "activr.set_conf", :after => 'mongoid.load-config' do |app|
+      Activr.configure do |config|
+        # setup app path
+        activr_dir = File.join(::Rails.root, 'app', 'activr')
+        if !File.exists?(activr_dir)
+          activr_dir = File.join(::Rails.root, 'app')
+        end
+
+        config.app_path = activr_dir
+
+        use_mongoid_conn = Fwissr['/activr/mongodb/uri'].blank? &&
+                           (Fwissr['/activr/skip_mongoid_railtie'] != true) &&
+                           (ENV['ACTIVR_SKIP_MONGOID_RAILTIE'] != 'true') &&
+                           defined?(Mongoid)
+
+        if use_mongoid_conn
+          # get mongoid conf
+          if Mongoid::VERSION.start_with?("2.")
+            # Mongoid 2
+            config.mongodb[:uri] = "mongodb://#{Mongoid.master.connection.host}:#{Mongoid.master.connection.port}/#{Mongoid.master.name}"
+          elsif Mongoid.sessions[:default] && !Mongoid.sessions[:default][:uri].blank?
+            # Mongoid >= 3 with :uri setting
+            config.mongodb[:uri] = Mongoid.sessions[:default][:uri].dup
+          elsif Mongoid.sessions[:default] && !Mongoid.sessions[:default][:database].blank? && !Mongoid.sessions[:default][:hosts].blank?
+            # Mongoid >= 3 without :uri setting
+            config.mongodb[:uri] = "mongodb://#{Mongoid.sessions[:default][:hosts].first}/#{Mongoid.sessions[:default][:database]}"
+          end
+        end
+      end
+    end
+
+    initializer 'activr.autoload', :after => "activr.set_conf", :before => :set_autoload_paths do |app|
+      app.config.autoload_paths += [
+        File.join(Activr.config.app_path, 'activities'),
+        File.join(Activr.config.app_path, 'timelines'),
+      ]
+    end
+
+    initializer "activr.setup_async_hooks" do |app|
+      if defined?(::Resque) && (ENV['ACTIVR_FORCE_SYNC'] != 'true')
+        Activr.configure do |config|
+          config.async[:route_activity]  ||= Activr::Async::Resque::RouteActivity
+          config.async[:timeline_handle] ||= Activr::Async::Resque::TimelineHandle
+        end
+      end
+    end
+
+    initializer "activr.setup_action_controller" do |app|
+      ActiveSupport.on_load :action_controller do
+        self.class_eval do
+          before_filter do |controller|
+            Activr::RailsCtx.clear_view_context!
+            Activr::RailsCtx.controller = controller
+          end
+        end
+      end
+    end
+
+    rake_tasks do
+      load "activr/railties/activr.rake"
+    end
+
+    config.after_initialize do |app|
+      # setup registry
+      Activr.setup
+    end
+  end # class Railtie
+
+end # module Activr

data/lib/activr/railties/activr.rake

@@ -0,0 +1,14 @@
+namespace :activr do
+
+  desc "Create the indexes"
+  task :create_indexes => :environment do
+    ::Rails.application.eager_load!
+
+    Activr.setup
+
+    Activr.storage.create_indexes do |index_name|
+      puts "Created index: #{index_name}"
+    end
+  end
+
+end

data/lib/activr/registry.rb

@@ -0,0 +1,268 @@
+module Activr
+
+  #
+  # The registry holds all activities, entities, timelines and timeline entries classes defined in the application
+  #
+  # The registry singleton is accessible with {Activr.registry}
+  #
+  class Registry
+
+    # @return [Hash{Symbol=>Class}] model class associated to entity name
+    attr_reader :entity_classes
+
+    # @return [Hash{Class=>Array<Symbol>}] entity names for activity class
+    attr_reader :activity_entities
+
+    # Init
+    def initialize
+      @setup = false
+
+      @timelines         = nil
+      @timeline_entries  = nil
+      @activities        = nil
+      @entities          = nil
+      @models            = nil
+
+      @entity_classes    = { }
+      @activity_entities = { }
+
+      @timeline_entities_for_model = { }
+      @activity_entities_for_model = { }
+    end
+
+    # Setup registry
+    def setup
+      return if @setup
+
+      # eagger load all classes
+      self.activities
+      self.timelines
+      self.timeline_entries
+
+      @setup = true
+    end
+
+
+    #
+    # Classes
+    #
+
+    # Get all registered timelines
+    #
+    # @return [Hash{String=>Class}] A hash of `<timeline kind> => <timeline class>`
+    def timelines
+      @timelines ||= self.classes_from_path(Activr.timelines_path)
+    end
+
+    # Get class for given timeline kind
+    #
+    # @param timeline_kind [String] Timeline kind
+    # @return [Class] Timeline class
+    def class_for_timeline(timeline_kind)
+      result = self.timelines[timeline_kind]
+      raise "No class defined for timeline kind: #{timeline_kind}" if result.blank?
+      result
+    end
+
+    # Get all registered timeline entries
+    #
+    # @return [Hash{String=>Hash{String=>Class}}] A hash of `<timeline kind> => { <route kind> => <timeline entry class>, ... }`
+    def timeline_entries
+      @timeline_entries ||= begin
+        result = { }
+
+        self.timelines.each do |(timeline_kind, timeline_class)|
+          dir_name = Activr::Utils.kind_for_class(timeline_class)
+          dir_path = File.join(Activr.timelines_path, dir_name)
+
+          if !File.directory?(dir_path)
+            dir_name = Activr::Utils.kind_for_class(timeline_class, 'timeline')
+            dir_path = File.join(Activr.timelines_path, dir_name)
+          end
+
+          if File.directory?(dir_path)
+            result[timeline_kind] = { }
+
+            Dir["#{dir_path}/*.rb"].sort.inject(result[timeline_kind]) do |memo, file_path|
+              base_name = File.basename(file_path, '.rb')
+
+              # skip base class
+              if (base_name != "base_timeline_entry")
+                klass = "#{timeline_class.name}::#{base_name.camelize}".constantize
+
+                route_kind = if (match_data = base_name.match(/(.+)_timeline_entry$/))
+                  match_data[1]
+                else
+                  base_name
+                end
+
+                route = timeline_class.routes.find do |timeline_route|
+                  timeline_route.kind == route_kind
+                end
+
+                raise "Timeline entry class found for an unspecified timeline route: #{file_path} / routes: #{timeline_class.routes.inspect}" unless route
+                memo[route_kind] = klass
+              end
+
+              memo
+            end
+          end
+        end
+
+        result
+      end
+    end
+
+    # Get class for timeline entry corresponding to given route in given timeline
+    #
+    # @param timeline_kind [String] Timeline kind
+    # @param route_kind    [String] Route kind
+    # @return [Class] Timeline entry class
+    def class_for_timeline_entry(timeline_kind, route_kind)
+      (self.timeline_entries[timeline_kind] && self.timeline_entries[timeline_kind][route_kind]) || Activr::Timeline::Entry
+    end
+
+    # Get all registered activities
+    #
+    # @return [Hash{String=>Class}] A hash of `<activity kind> => <activity class>`
+    def activities
+      @activities ||= self.classes_from_path(Activr.activities_path)
+    end
+
+    # Get class for given activity
+    #
+    # @param activity_kind [String] Activity kind
+    # @return [Class] Activity class
+    def class_for_activity(activity_kind)
+      result = self.activities[activity_kind]
+      raise "No class defined for activity kind: #{activity_kind}" if result.blank?
+      result
+    end
+
+    # Get all registered entities
+    #
+    # @return [Hash{Symbol=>Array<Class>}] A hash of `:<entity name> => [ <activity class>, <activity class>, ... ]`
+    def entities
+      # loading activities triggers calls to #add_entity method
+      self.activities if @entities.blank?
+
+      @entities || { }
+    end
+
+    # Get all registered entities names
+    #
+    # @return [Array<Symbol>] List of entities names
+    def entities_names
+      @entities_names ||= self.entities.keys
+    end
+
+    # Register an entity
+    #
+    # @param entity_name    [Symbol] Entity name
+    # @param entity_options [Hash]   Entity options
+    # @param activity_klass [Class]  Activity class that uses that entity
+    def add_entity(entity_name, entity_options, activity_klass)
+      entity_name = entity_name.to_sym
+
+      if @entity_classes[entity_name] && (@entity_classes[entity_name].name != entity_options[:class].name)
+        # otherwise this would break timeline entries deletion mecanism
+        raise "Entity name #{entity_name} already used with class #{@entity_classes[entity_name]}, can't redefine it with class #{entity_options[:class]}"
+      end
+
+      # class for entity
+      @entity_classes[entity_name] = entity_options[:class]
+
+      # entities for activity
+      @activity_entities[activity_klass] ||= [ ]
+      @activity_entities[activity_klass] << entity_name
+
+      # entities
+      @entities ||= { }
+      @entities[entity_name] ||= { }
+
+      if !@entities[entity_name][activity_klass].blank?
+        raise "Entity name #{entity_name} already used for activity: #{activity_klass}"
+      end
+
+      @entities[entity_name][activity_klass] = entity_options
+    end
+
+    # Get all models that included mixin {Activr::Entity::ModelMixin}
+    #
+    # @return [Array<Class>] List of model classes
+    def models
+      # loading activities triggers models loading
+      self.activities if @models.blank?
+
+      @models || [ ]
+    end
+
+    # Register a model
+    #
+    # @param model_class [Class] Model class
+    def add_model(model_class)
+      @models ||= [ ]
+      @models << model_class
+    end
+
+    # Get all entities names for given model class
+    def activity_entities_for_model(model_class)
+      @activity_entities_for_model[model_class] ||= begin
+        result = [ ]
+
+        @entity_classes.each do |entity_name, entity_class|
+          result << entity_name if (entity_class == model_class)
+        end
+
+        result
+      end
+    end
+
+    # Get all entities names by timelines that can have a reference to given model class
+    #
+    # @param model_class [Class] Model class
+    # @return [Hash{Class=>Array<Symbol>}] Lists of entities names indexed by timeline class
+    def timeline_entities_for_model(model_class)
+      @timeline_entities_for_model[model_class] ||= begin
+        result = { }
+
+        self.timelines.each do |timeline_kind, timeline_class|
+          result[timeline_class] = [ ]
+
+          timeline_class.routes.each do |route|
+            entities_ary = @activity_entities[route.activity_class]
+            (entities_ary || [ ]).each do |entity_name|
+              result[timeline_class] << entity_name if (@entity_classes[entity_name] == model_class)
+            end
+          end
+
+          result[timeline_class].uniq!
+        end
+
+        result
+      end
+    end
+
+    # Find all classes in given directory
+    #
+    # @api private
+    #
+    # @param dir_path [String] Directory path
+    # @return [Hash{String=>Class}] Hash of `<kind> => <Class>`
+    def classes_from_path(dir_path)
+      Dir["#{dir_path}/*.rb"].sort.inject({ }) do |memo, file_path|
+        klass = File.basename(file_path, '.rb').camelize.constantize
+
+        if !memo[klass.kind].nil?
+          raise "Kind #{klass.kind} already used by class #{memo[klass.kind]} so can't use it for class #{klass}"
+        end
+
+        memo[klass.kind] = klass
+
+        memo
+      end
+    end
+
+  end # class Registry
+
+end # module Activr

data/lib/activr/storage.rb

@@ -0,0 +1,404 @@
+module Activr
+
+  #
+  # The storage is the component that uses the database driver to serialize/unserialize activities and timeline entries.
+  #
+  # The storage singleton is accessible with {Activr.storage}
+  #
+  class Storage
+
+    autoload :MongoDriver, 'activr/storage/mongo_driver'
+
+    # @return [MongoDriver] database driver
+    attr_reader :driver
+
+    def initialize
+      @driver = Activr::Storage::MongoDriver.new
+
+      @hooks = { }
+    end
+
+    # Is it a valid document id
+    #
+    # @param doc_id [Object] Document id to check
+    # @return [true, false]
+    def valid_id?(doc_id)
+      self.driver.valid_id?(doc_id)
+    end
+
+    # Is it a serialized document id
+    #
+    # @return [true,false]
+    def serialized_id?(doc_id)
+      self.driver.serialized_id?(doc_id)
+    end
+
+    # Unserialize a document id
+    #
+    # @param doc_id [Object] Document id
+    # @return [Object] Unserialized document id
+    def unserialize_id(doc_id)
+      self.driver.unserialize_id(doc_id)
+    end
+
+    # Unserialize given parameter only if it is a serialized document id
+    #
+    # @param doc_id [Object] Document id
+    # @return [Object] Unserialized or unmodified document id
+    def unserialize_id_if_necessary(doc_id)
+      self.serialized_id?(doc_id) ? self.unserialize_id(doc_id) : doc_id
+    end
+
+
+    #
+    # Activities
+    #
+
+    # Insert a new activity
+    #
+    # @param activity [Activity] Activity to insert
+    # @return [Object] The inserted activity id
+    def insert_activity(activity)
+      # serialize
+      activity_hash = activity.to_hash
+
+      # run hook
+      self.run_hook(:will_insert_activity, activity_hash)
+
+      # insert
+      self.driver.insert_activity(activity_hash)
+    end
+
+    # Find an activity
+    #
+    # @param activity_id [Object] Activity id to find
+    # @return [Activity, Nil] An activity instance or `nil` if not found
+    def find_activity(activity_id)
+      activity_hash = self.driver.find_activity(activity_id)
+      if activity_hash
+        # run hook
+        self.run_hook(:did_find_activity, activity_hash)
+
+        # unserialize
+        Activr::Activity.from_hash(activity_hash)
+      else
+        nil
+      end
+    end
+
+    # Find latest activities
+    #
+    # @note If you use others selectors then 'limit' argument and 'skip' option then you have to setup corresponding indexes in database.
+    #
+    # @param limit [Integer] Max number of activities to find
+    # @param options [Hash] Options hash
+    # @option options [Integer]           :skip     Number of activities to skip (default: 0)
+    # @option options [Time]              :before   Find activities generated before that datetime (excluding)
+    # @option options [Time]              :after    Find activities generated after that datetime (excluding)
+    # @option options [Hash{Sym=>String}] :entities Filter by entities values (empty means 'all values')
+    # @option options [Array<Class>]      :only     Find only these activities
+    # @option options [Array<Class>]      :except   Skip these activities
+    # @return [Array<Activity>] An array of activities
+    def find_activities(limit, options = { })
+      # default options
+      options = {
+        :skip     => 0,
+        :before   => nil,
+        :after    => nil,
+        :entities => { },
+        :only     => [ ],
+        :except   => [ ],
+      }.merge(options)
+
+      options[:only] = [ options[:only] ] if (options[:only] && !options[:only].is_a?(Array))
+
+      # find
+      result = self.driver.find_activities(limit, options).map do |activity_hash|
+        # run hook
+        self.run_hook(:did_find_activity, activity_hash)
+
+        # unserialize
+        Activr::Activity.from_hash(activity_hash)
+      end
+
+      result
+    end
+
+    # Count number of activities
+    #
+    # @note If you use one of options selectors then you have to setup corresponding indexes in database.
+    #
+    # @param options [Hash] Options hash
+    # @option options [Time]              :before   Find activities generated before that datetime (excluding)
+    # @option options [Time]              :after    Find activities generated after that datetime (excluding)
+    # @option options [Hash{Sym=>String}] :entities Filter by entities values (empty means 'all values')
+    # @option options [Array<Class>]      :only     Find only these activities
+    # @option options [Array<Class>]      :except   Skip these activities
+    # @return [Integer] Number of activities
+    def count_activities(options = { })
+      # default options
+      options = {
+        :before   => nil,
+        :after    => nil,
+        :entities => { },
+        :only     => [ ],
+        :except   => [ ],
+      }.merge(options)
+
+      options[:only] = [ options[:only] ] if (options[:only] && !options[:only].is_a?(Array))
+
+      # count
+      self.driver.count_activities(options)
+    end
+
+    # Find number of duplicate activities
+    #
+    # @param activity [Activity] Activity to search
+    # @param after [Time] Search after that datetime
+    # @return [Integer] Number of activity duplicates
+    def count_duplicate_activities(activity, after)
+      entities = { }
+
+      activity.entities.each do |entity_name, entity|
+        entities[entity_name.to_sym] = entity.model_id
+      end
+
+      self.count_activities({
+        :only     => activity.class,
+        :entities => entities,
+        :after    => after,
+      })
+    end
+
+    # Delete activities referring to given entity model instance
+    #
+    # @param model [Object] Model instance
+    def delete_activities_for_entity_model(model)
+      Activr.registry.activity_entities_for_model(model.class).each do |entity_name|
+        self.driver.delete_activities(:entities => { entity_name => model.id })
+      end
+    end
+
+
+    #
+    # Timeline Entries
+    #
+
+    # Insert a new timeline entry
+    #
+    # @param timeline_entry [Timeline::Entry] Timeline entry to insert
+    # @return [Object] Inserted timeline entry id
+    def insert_timeline_entry(timeline_entry)
+      # serialize
+      timeline_entry_hash = timeline_entry.to_hash
+
+      # run hook
+      self.run_hook(:will_insert_timeline_entry, timeline_entry_hash, timeline_entry.timeline.class)
+
+      # insert
+      self.driver.insert_timeline_entry(timeline_entry.timeline.kind, timeline_entry_hash)
+    end
+
+    # Find a timeline entry
+    #
+    # @param timeline    [Timeline] Timeline instance
+    # @param tl_entry_id [Object]   Timeline entry id
+    # @return [Timeline::Entry, Nil] Found timeline entry
+    def find_timeline_entry(timeline, tl_entry_id)
+      timeline_entry_hash = self.driver.find_timeline_entry(timeline.kind, tl_entry_id)
+      if timeline_entry_hash
+        # run hook
+        self.run_hook(:did_find_timeline_entry, timeline_entry_hash, timeline.class)
+
+        # unserialize
+        Activr::Timeline::Entry.from_hash(timeline_entry_hash, timeline)
+      else
+        nil
+      end
+    end
+
+    # Find timeline entries by descending timestamp
+    #
+    # @param timeline [Timeline] Timeline instance
+    # @param limit    [Integer]  Max number of entries to find
+    # @param options  [Hash]     Options hash
+    # @option options [Integer]                :skip Number of entries to skip (default: 0)
+    # @option options [Array<Timeline::Route>] :only An array of routes to fetch
+    # @return [Array<Timeline::Entry>] An array of timeline entries
+    def find_timeline(timeline, limit, options = { })
+      options = {
+        :skip => 0,
+        :only => [ ],
+      }.merge(options)
+
+      options[:only] = [ options[:only] ] if (options[:only] && !options[:only].is_a?(Array))
+
+      result = self.driver.find_timeline_entries(timeline.kind, timeline.recipient_id, limit, options).map do |timeline_entry_hash|
+        # run hook
+        self.run_hook(:did_find_timeline_entry, timeline_entry_hash, timeline.class)
+
+        # unserialize
+        Activr::Timeline::Entry.from_hash(timeline_entry_hash, timeline)
+      end
+
+      result
+    end
+
+    # Count number of timeline entries
+    #
+    # @param timeline [Timeline] Timeline instance
+    # @param options  [Hash]     Options hash
+    # @option options [Array<Timeline::Route>] :only An array of routes to count
+    # @return [Integer] Number of timeline entries in given timeline
+    def count_timeline(timeline, options = { })
+      options = {
+        :only => [ ],
+      }.merge(options)
+
+      options[:only] = [ options[:only] ] if (options[:only] && !options[:only].is_a?(Array))
+
+      self.driver.count_timeline_entries(timeline.kind, timeline.recipient_id, options)
+    end
+
+    # Delete timeline entries
+    #
+    # @param timeline [Timeline] Timeline instance
+    # @param options  [Hash] Options hash
+    # @option options [Time] :before Delete only timeline entries which timestamp is before that datetime (excluding)
+    # @option options [Hash{Sym=>String}] :entity Delete only timeline entries with these entities values
+    def delete_timeline(timeline, options = { })
+      # default options
+      options = {
+        :before   => nil,
+        :entities => { },
+      }.merge(options)
+
+      self.driver.delete_timeline_entries(timeline.kind, timeline.recipient_id, options)
+    end
+
+    # Delete timeline entries referring to given entity model instance
+    #
+    # @param model [Object] Model instance
+    def delete_timeline_entries_for_entity_model(model)
+      Activr.registry.timeline_entities_for_model(model.class).each do |timeline_class, entities|
+        entities.each do |entity_name|
+          self.driver.delete_timeline_entries(timeline_class.kind, nil, :entities => { entity_name => model.id })
+        end
+      end
+    end
+
+
+    #
+    # Indexes
+    #
+
+    # Ensure all necessary indexes
+    #
+    # @yield [String] Created index name
+    def create_indexes
+      self.driver.create_indexes
+    end
+
+
+    #
+    # Hooks
+    #
+
+    # Hook: run just before inserting an activity document in the database
+    #
+    # @example Insert the 'foo' meta into all activities
+    #
+    #   Activr.storage.will_insert_activity do |activity_hash|
+    #     activity_hash['meta'] ||= { }
+    #     activity_hash['meta']['foo'] = 'bar'
+    #   end
+    #
+    def will_insert_activity(&block)
+      register_hook(:will_insert_activity, block)
+    end
+
+    # Hook: run just after fetching an activity document from the database
+    #
+    # @example Ignore the 'foo' meta
+    #
+    #   Activr.storage.did_find_activity do |activity_hash|
+    #     if activity_hash['meta']
+    #       activity_hash['meta'].delete('foo')
+    #     end
+    #   end
+    #
+    def did_find_activity(&block)
+      register_hook(:did_find_activity, block)
+    end
+
+    # Hook: run just before inserting a timeline entry document in the database
+    #
+    # @example Insert the 'bar' field into all timeline entries documents
+    #
+    #   Activr.storage.will_insert_timeline_entry do |timeline_entry_hash, timeline_class|
+    #     timeline_entry_hash['bar'] = 'baz'
+    #   end
+    #
+    def will_insert_timeline_entry(&block)
+      register_hook(:will_insert_timeline_entry, block)
+    end
+
+    # Hook: run just after fetching a timeline entry document from the database
+    #
+    # @example Ignore the 'bar' field
+    #
+    #   Activr.storage.did_find_timeline_entry do |timeline_entry_hash, timeline_class|
+    #     timeline_entry_hash.delete('bar')
+    #   end
+    #
+    def did_find_timeline_entry(&block)
+      register_hook(:did_find_timeline_entry, block)
+    end
+
+
+    # Register a hook
+    #
+    # @api private
+    #
+    # @param name  [Symbol] Hook name
+    # @param block [Proc]   Hook code
+    def register_hook(name, block)
+      @hooks[name] ||= [ ]
+      @hooks[name] << block
+    end
+
+    # Get hooks
+    #
+    # @api private
+    # @note Returns all hooks if `name` is `nil`
+    #
+    # @param name [Symbol] Hook name
+    # @return [Array<Proc>] List of hooks
+    def hooks(name = nil)
+      name ? (@hooks[name] || [ ]) : @hooks
+    end
+
+    # Run a hook
+    #
+    # @api private
+    #
+    # @param name [Symbol] Hook name
+    # @param args [Array]  Hook arguments
+    def run_hook(name, *args)
+      return if @hooks[name].blank?
+
+      @hooks[name].each do |hook|
+        args.any? ? hook.call(*args) : hook.call
+      end
+    end
+
+    # Reset all hooks
+    #
+    # @api private
+    def clear_hooks!
+      @hooks = { }
+    end
+
+  end # class Storage
+
+end # module Activr