activr 1.0.0

data/lib/activr/async.rb

@@ -0,0 +1,92 @@
+module Activr
+
+  #
+  # Async hooks module
+  #
+  # The async hooks module permits to plug any job system to run some part if Activr code asynchronously.
+  #
+  # Possible hooks are:
+  #   - :route_activity - An activity must me routed by the Dispatcher
+  #   - :timeline_handle - An activity must be handled by a timeline
+  #
+  # A hook class:
+  #   - must implement a `#enqueue` method, used to enqueue the async job
+  #   - must call `Activr::Async.<hook_name>` method in the async job
+  #
+  # Hook classes to use are specified thanks to the `config.async` hash.
+  #
+  # When Resque is detected inside a Rails application then defaults hooks are provided out of the box (see the {Activr::Async::Resque} module).
+  #
+  # @example The default :route_activity hook handler when Resque is detected in a Rails application:
+  #
+  #   # config
+  #   Activr.configure do |config|
+  #     config.async[:route_activity] ||= Activr::Async::Resque::RouteActivity
+  #   end
+  #
+  #   class Activr::Async::Resque::RouteActivity
+  #     @queue = 'activr_route_activity'
+  #
+  #     class << self
+  #       def enqueue(activity)
+  #         ::Resque.enqueue(self, activity.to_hash)
+  #       end
+  #
+  #       def perform(activity_hash)
+  #         # unserialize argument
+  #         activity_hash = Activr::Activity.unserialize_hash(activity_hash)
+  #         activity = Activr::Activity.from_hash(activity_hash)
+  #
+  #         # call hook
+  #         Activr::Async.route_activity(activity)
+  #       end
+  #     end # class << self
+  #   end # class RouteActivity
+  #
+  module Async
+
+    autoload :Resque, 'activr/async/resque'
+
+    class << self
+      # Run hook
+      #
+      # If an async class is defined for that hook name then it is used to process
+      # the hook asynchronously, else the hooked code is executed immediately.
+      #
+      # @param name [Symbol] Hook name to run
+      # @param args [Array]  Hook parameters
+      def hook(name, *args)
+        if Activr.config.async[name] && (ENV['ACTIVR_FORCE_SYNC'] != 'true')
+          # async
+          Activr.config.async[name].enqueue(*args)
+        else
+          # sync
+          self.__send__(name, *args)
+        end
+      end
+
+
+      #
+      # Hooks
+      #
+
+      # Hook: route an activity
+      #
+      # @param activity [Activity] Activity to route
+      def route_activity(activity)
+        Activr.dispatcher.route(activity)
+      end
+
+      # Hook: timeline handles an activity thanks to given route
+      #
+      # @param timeline [Timeline]        Timeline that handles the activity
+      # @param activity [Activity]        Activity to handle
+      # @param route    [Timeline::Route] The route causing that activity handling
+      def timeline_handle(timeline, activity, route)
+        timeline.handle_activity(activity, route)
+      end
+    end # class << self
+
+  end # module Async
+
+end # module Activr

data/lib/activr/async/resque.rb

@@ -0,0 +1,58 @@
+require 'resque'
+
+#
+# The defaults hook classes when Resque is detected inside a Rails application
+#
+module Activr::Async::Resque
+
+  # Class to handle :route_activity hook thanks to a Resque job
+  class RouteActivity
+    @queue = 'activr_route_activity'
+
+    class << self
+      # Enqueue job
+      def enqueue(activity)
+        ::Resque.enqueue(self, activity.to_hash)
+      end
+
+      # Perform job
+      def perform(activity_hash)
+        # unserialize argument
+        activity_hash = Activr::Activity.unserialize_hash(activity_hash)
+        activity = Activr::Activity.from_hash(activity_hash)
+
+        # call hook
+        Activr::Async.route_activity(activity)
+      end
+    end # class << self
+  end # class RouteActivity
+
+  # Class to handle :timeline_handle hook thanks to a Resque job
+  class TimelineHandle
+    @queue = 'activr_timeline_handle'
+
+    class << self
+      # Enqueue job
+      def enqueue(timeline, activity, route)
+        ::Resque.enqueue(self, timeline.kind, timeline.recipient_id, activity.to_hash, route.kind)
+      end
+
+      # Perform job
+      def perform(timeline_kind, recipient_id, activity_hash, route_kind)
+        # unserialize arguments
+        recipient_id = Activr.storage.unserialize_id_if_necessary(recipient_id)
+        activity_hash = Activr::Activity.unserialize_hash(activity_hash)
+
+        timeline_klass = Activr.registry.class_for_timeline(timeline_kind)
+
+        timeline = timeline_klass.new(recipient_id)
+        activity = Activr::Activity.from_hash(activity_hash)
+        route    = timeline_klass.route_for_kind(route_kind)
+
+        # call hook
+        Activr::Async.timeline_handle(timeline, activity, route)
+      end
+    end # class << self
+  end # class TimelineHandle
+
+end # module Activr::Async::Resque

data/lib/activr/configuration.rb

@@ -0,0 +1,40 @@
+module Activr
+
+  #
+  # That module gives configuration behaviour to includer
+  #
+  # @see ActiveSupport::Configurable
+  #
+  module Configuration
+
+    extend ActiveSupport::Concern
+
+    include ActiveSupport::Configurable
+
+    included do
+      # default config
+      config.app_path = Dir.pwd
+      config.skip_dup_period = nil
+
+      config.mongodb = {
+        :uri            => 'mongodb://127.0.0.1/activr',
+        :col_prefix     => nil,
+        :activities_col => nil,
+        :timelines_col  => nil,
+      }
+
+      config.async = { }
+
+      # compiles reader methods so we don't have to go through method_missing
+      config.compile_methods!
+
+      # fetch config from fwissr
+      config.app_path        = Fwissr['/activr/app_path']             unless Fwissr['/activr/app_path'].blank?
+      config.skip_dup_period = Fwissr['/activr/skip_dup_period']      unless Fwissr['/activr/skip_dup_period'].blank?
+      config.mongodb.merge!(Fwissr['/activr/mongodb'].symbolize_keys) unless Fwissr['/activr/mongodb'].blank?
+      config.async.merge!(Fwissr['/activr/async'].symbolize_keys)     unless Fwissr['/activr/async'].blank?
+    end
+
+  end # module Configuration
+
+end # module Activr

data/lib/activr/dispatcher.rb

@@ -0,0 +1,70 @@
+module Activr
+
+  #
+  # The dispatcher is the component that is in charge of routing activities to timelines.
+  #
+  # The dispatcher singleton is accessible with {Activr.dispatcher}
+  #
+  class Dispatcher
+
+    # Route an activity
+    #
+    # @param activity [Activity] Activity to route
+    # @return [Integer] The number of resolved recipients that will handle activity
+    def route(activity)
+      raise "Activity must be stored before routing: #{activity.inspect}" if !activity.stored?
+
+      result = 0
+
+      activity.run_callbacks(:route) do
+        # iterate on all timelines
+        Activr.registry.timelines.values.each do |timeline_class|
+          # check if timeline refuses that activity
+          next unless timeline_class.should_route_activity?(activity)
+
+          # store activity in timelines
+          self.recipients_for_timeline(timeline_class, activity).each do |recipient, route|
+            result += 1
+
+            timeline = timeline_class.new(recipient)
+            if timeline.should_handle_activity?(activity, route)
+              Activr::Async.hook(:timeline_handle, timeline, activity, route)
+            end
+          end
+        end
+      end
+
+      result
+    end
+
+    # Find recipients for given activity in given timeline
+    #
+    # @api private
+    #
+    # @param timeline_class [Class]    Timeline class
+    # @param activity       [Activity] Activity instance
+    # @return [Hash{Object=>Timeline::Route}] Recipients with corresponding Routes
+    def recipients_for_timeline(timeline_class, activity)
+      result = { }
+
+      routes = timeline_class.routes_for_activity(activity.class)
+      routes.each do |route|
+        route.resolve(activity).each do |recipient|
+          recipient_id = timeline_class.recipient_id(recipient)
+
+          # keep only one route per recipient
+          if result[recipient_id].nil?
+            result[recipient_id] = { :rcpt => recipient, :route => route }
+          end
+        end
+      end
+
+      result.inject({ }) do |memo, (recipient_id, infos)|
+        memo[infos[:rcpt]] = infos[:route]
+        memo
+      end
+    end
+
+  end # class Dispatcher
+
+end # module Activr

data/lib/activr/entity.rb

@@ -0,0 +1,103 @@
+module Activr
+
+  #
+  # An Entity represents one of your application model involved in activities
+  #
+  class Entity
+
+    autoload :ModelMixin, 'activr/entity/model_mixin'
+
+    # @return [Symbol] entity name
+    attr_reader :name
+
+    # @return [Hash] entity options
+    attr_reader :options
+
+    # @return [Activity] activity owning that entity
+    attr_reader :activity
+
+    # @return [Class] entity model class
+    attr_reader :model_class
+
+    # @return [Objecy] entity model id
+    attr_reader :model_id
+
+
+    # @param name    [String] Entity name
+    # @param value   [Object] Model instance or model id
+    # @param options [Hash] Options hash
+    # @option (see Activity.entity)
+    # @option options [Activity] :activity Entity belongs to that activity
+    def initialize(name, value, options = { })
+      @name = name
+      @options = options.dup
+
+      @activity    = @options.delete(:activity)
+      @model_class = @options.delete(:class)
+
+      if Activr.storage.valid_id?(value)
+        @model_id = value
+
+        raise "Missing :class option for #{name} / #{value}: #{options.inspect}" if @model_class.nil?
+        raise "Model class MUST implement #find method" unless @model_class.respond_to?(:find)
+      else
+        @model = value
+
+        if (@model_class && (@model_class != @model.class))
+          raise "Model class mismatch: #{@model_class} != #{@model.class}"
+        end
+
+        @model_class ||= @model.class
+        @model_id = @model.id
+      end
+    end
+
+    # Get model instance
+    #
+    # @return [Object] Model instance
+    def model
+      @model ||= self.model_class.find(self.model_id)
+    end
+
+    # Humanize entity
+    #
+    # @param options [hash] Options
+    # @option options [true,false] :html Generate HTML ?
+    # @return [String] Humanized sentence
+    def humanize(options = { })
+      result   = nil
+      htmlized = false
+
+      humanize_meth = @options[:humanize]
+      if humanize_meth.nil? && (self.model.respond_to?(:humanize))
+        humanize_meth = :humanize
+      end
+
+      if humanize_meth
+        case self.model.method(humanize_meth).arity
+        when 1
+          result = self.model.__send__(humanize_meth, options)
+          htmlized = true
+        else
+          result = self.model.__send__(humanize_meth)
+        end
+      end
+
+      if result.nil? && @options[:default]
+        result = @options[:default]
+      end
+
+      if !result.nil? && options[:html] && !htmlized && Activr::RailsCtx.view_context
+        # let Rails sanitize and htmlize the entity
+        result = Activr::RailsCtx.view_context.sanitize(result)
+        result = Activr::RailsCtx.view_context.link_to(result, self.model)
+      end
+
+      result ||= ""
+
+      result
+    end
+
+  end # class Entity
+
+end # module Activr

data/lib/activr/entity/model_mixin.rb

@@ -0,0 +1,117 @@
+#
+# Including that module in your model class adds these methods: {#activities}, {#activities_count} and
+# {#delete_activities!}.
+#
+# If you plan to call either {#activities} or {#activities_count} methods then set the `:feed_index => true`
+# entity setting to ensure that an index is correctly setup when running the `rake activr:create_indexes` task.
+#
+# If you plan to call {#delete_activities!} method then you should set the `:deletable => true` entity setting
+# to ensure that a deletion index is correctly setup when running the `rake activr:create_indexes` task.
+#
+# @example Model:
+#   class User
+#
+#     # inject sugar methods
+#     include Activr::Entity::ModelMixin
+#
+#     activr_entity :feed_index => true, :deletable => true
+#
+#     include Mongoid::Document
+#
+#     field :_id, :type => String
+#     field :first_name, :type => String
+#     field :last_name, :type => String
+#
+#     def fullname
+#       "#{self.first_name} #{self.last_name}"
+#     end
+#
+#     after_destroy :delete_activities!
+#
+#   end
+#
+# @example Usage:
+#   user = User.find('john')
+#
+#   puts "#{user.fullname} has #{user.activities_count} activites. Here are the 10 most recent:"
+#
+#   user.activities(10).each do |activity|
+#     puts activity.humanize
+#   end
+#
+module Activr::Entity::ModelMixin
+
+  extend ActiveSupport::Concern
+
+  included do
+    # Entity settings
+    class_attribute :activr_entity_settings, :instance_writer => false
+    self.activr_entity_settings = { :feed_index => false, :deletable => false, :name => nil }
+
+    # Register model
+    Activr.registry.add_model(self)
+  end
+
+  # Class methods for the {ModelMixin} mixin
+  module ClassMethods
+
+    # Get entity name to use for activity feed queries
+    #
+    # @api private
+    #
+    # @return [Symbol]
+    def activr_entity_feed_actual_name
+      self.activr_entity_settings[:name] || Activr::Utils.kind_for_class(self).to_sym
+    end
+
+
+    #
+    # Class interface
+    #
+
+    # Set a custom entity name to use in entity activity feed queries
+    #
+    # @note By default, the entity name is inferred from the model class name
+    # @todo Add documentation in README for that
+    #
+    # @param settings [Hash] Entity settings
+    # @option settings [Boolean] :deletable  Entity is deletable ? (default: `false`)
+    # @option settings [String]  :name       Custom entity name to use in entity activity feed queries (default is inferred from model class name)
+    # @option settings [Boolean] :feed_index Ensure entity activity feed index ? (default: `false`)
+    def activr_entity(settings)
+      self.activr_entity_settings = self.activr_entity_settings.merge(settings)
+    end
+
+  end # module ClassMethods
+
+  # sugar
+  def activr_entity_feed_actual_name
+    self.class.activr_entity_feed_actual_name
+  end
+
+  # Fetch activities
+  #
+  # @param limit [Integer] Max number of activities to fetch
+  # @param options (see Storage#find_activities)
+  # @return [Array<Activity>] A list of activities
+  def activities(limit, options = { })
+    Activr.activities(limit, options.merge(self.activr_entity_feed_actual_name => self.id))
+  end
+
+  # Get total number of activities
+  #
+  # @return [Integer] The total number of activities
+  def activities_count
+    Activr.activities_count(self.activr_entity_feed_actual_name => self.id)
+  end
+
+  # Delete all activities and timeline entries that reference that entity
+  def delete_activities!
+    # delete activities
+    Activr.storage.delete_activities_for_entity_model(self)
+
+    # delete timeline entries
+    Activr.storage.delete_timeline_entries_for_entity_model(self)
+  end
+
+end # module Activr::Entity::ModelMixin