maily_herald 0.8.0 → 0.9.1

data/app/models/maily_herald/log.rb

@@ -1,4 +1,21 @@
 module MailyHerald
+  # Stores information about email delivery to entity.
+  #
+  # It is associated with entity object and {Dispatch}.
+  # Log can have following statuses:
+  # - +scheduled+ - email hasn't been processed yet,
+  # - +delivered+ - email was sent to entity,
+  # - +skipped+ - email deliver was skipped (i.e. due to conditions not met),
+  # - +error+ - there was an error during email delivery.
+  #
+  # @attr [Fixnum]    entity_id      Entity association id.
+  # @attr [String]    entity_type    Entity association type.
+  # @attr [String]    entity_email   Delivery email. Stored in case associated entity gets deleted.
+  # @attr [Fixnum]    mailing_id     {Dispatch} association id.
+  # @attr [Sumbol]    status         
+  # @attr [Hash]      data           Custom log data.
+  # @attr [DateTime]  processing_at  Timestamp of {Dispatch} processing.
+  #                                  Can be either future (when in +scheduled+ state) or past.
   class Log < ActiveRecord::Base
     AVAILABLE_STATUSES = [:scheduled, :delivered, :skipped, :error]
 
@@ -20,13 +37,29 @@ module MailyHerald
     scope       :error,         lambda { where(status: :error) }
     scope       :scheduled,     lambda { where(status: :scheduled) }
     scope       :processed,     lambda { where(status: [:delivered, :skipped, :error]) }
+    scope       :not_skipped,   lambda { where("status != 'skipped'") }
+    scope       :like_email,    lambda {|query| where("maily_herald_logs.entity_email LIKE (?)", "%#{query}%") }
 
     serialize   :data,          Hash
 
+    # Contains `Mail::Message` object that was delivered.
+    #
+    # Present only in logs of state `delivered` and obtained via
+    # `Mailing.run` method.
+    attr_accessor :mail
+
     if Rails::VERSION::MAJOR == 3
       attr_accessible :status, :data
     end
 
+    # Creates Log object for given {Dispatch} and entity.
+    #
+    # @param mailing [Dispatch]
+    # @param entity [ActiveRecord::Base]
+    # @param attributes [Hash] log attributes
+    # @option attributes [Time] :processing_at (DateTime.now)
+    # @option attributes [Symbol] :status
+    # @option attributes [Hash] :data
     def self.create_for mailing, entity, attributes = {}
       log = Log.new
       log.set_attributes_for mailing, entity, attributes
@@ -34,6 +67,14 @@ module MailyHerald
       log
     end
 
+    # Sets Log instance attributes.
+    #
+    # @param mailing [Dispatch]
+    # @param entity [ActiveRecord::Base]
+    # @param attributes [Hash] log attributes
+    # @option attributes [Time] :processing_at (DateTime.now)
+    # @option attributes [Symbol] :status
+    # @option attributes [Hash] :data
     def set_attributes_for mailing, entity, attributes = {}
       self.mailing = mailing
       self.entity = entity
@@ -63,5 +104,43 @@ module MailyHerald
     def scheduled?
       self.status == :scheduled
     end
+
+    def processed?
+      [:delivered, :skipped, :error].include?(self.status)
+    end
+
+    # Set attributes of a schedule so it has 'skipped' status.
+    def skip reason
+      if self.status == :scheduled
+        self.status = :skipped
+        self.data[:skip_reason] = reason
+        true
+      end
+    end
+
+    # Set attributes of a schedule so it is postponed.
+    def postpone_delivery
+      if !self.data[:delivery_attempts] || self.data[:delivery_attempts].length < 3
+        self.data[:original_processing_at] ||= self.processing_at
+        self.data[:delivery_attempts] ||= []
+        self.data[:delivery_attempts].push(date_at: Time.now, action: :postpone, reason: :not_processable)
+        self.processing_at = Time.now + 1.day
+        true
+      end
+    end
+
+    # Set attributes of a schedule so it has 'delivered' status.
+    # @param content Body of delivered email.
+    def deliver content
+      self.status = :delivered
+      self.data[:content] = content
+    end
+
+    # Set attributes of a schedule so it has 'error' status.
+    # @param msg Error description.
+    def error msg
+      self.status = :error
+      self.data[:msg] = msg
+    end
   end
 end

data/app/models/maily_herald/mailing.rb

@@ -12,11 +12,14 @@ module MailyHerald
     
     validates   :subject,       presence: true, if: :generic_mailer?
     validates   :template,      presence: true, if: :generic_mailer?
+    validate    :mailer_validity
     validate    :template_syntax
     validate    :validate_conditions
 
     before_validation do
       write_attribute(:name, self.title.downcase.gsub(/\W/, "_")) if self.title && (!self.name || self.name.empty?)
+      write_attribute(:conditions, nil) if !self.has_conditions_proc? && self.conditions.try(:empty?)
+      write_attribute(:from, nil) if self.from.try(:empty?)
     end
 
     after_initialize do
@@ -24,6 +27,58 @@ module MailyHerald
         self.override_subscription = false
         self.mailer_name = :generic
       end
+
+      if @conditions_proc
+        self.conditions = "proc"
+      end
+    end
+
+    after_save do
+      if @conditions_proc
+        MailyHerald.conditions_procs[self.id] = @conditions_proc
+      end
+    end
+
+    # Sets mailing conditions.
+    #
+    # @param v String with Liquid expression or `Proc` that evaluates to `true` or `false`.
+    def conditions= v
+      if v.respond_to? :call
+        @conditions_proc = v
+      else
+        write_attribute(:conditions, v)
+      end
+    end
+
+    # Returns time as string with Liquid expression or Proc.
+    def conditions
+      @conditions_proc || MailyHerald.conditions_procs[self.id] || read_attribute(:conditions)
+    end
+
+    def has_conditions_proc?
+      @conditions_proc || MailyHerald.conditions_procs[self.id]
+    end
+
+    def conditions_changed?
+      if has_conditions_proc?
+        @conditions_proc != MailyHerald.conditions_procs[self.id]
+      else
+        super
+      end
+    end
+
+    def general_scheduling?
+      self.start_at.is_a?(String) && Time.parse(self.start_at).is_a?(Time)
+    rescue
+      false
+    end
+
+    def individual_scheduling?
+      !general_scheduling?
+    end
+
+    def ad_hoc?
+      self.class == AdHocMailing
     end
 
     def periodical?
@@ -42,6 +97,7 @@ module MailyHerald
       read_attribute(:mailer_name).to_sym
     end
 
+    # Returns {Mailer} class used by this Mailing.
     def mailer
       if generic_mailer?
         MailyHerald::Mailer
@@ -50,29 +106,51 @@ module MailyHerald
       end
     end
 
-    def has_conditions?
-      self.conditions && !self.conditions.empty?
-    end
-
+    # Checks whether Mailing uses generic mailer.
     def generic_mailer?
       self.mailer_name == :generic
     end
 
+    # Checks whether Mailig has conditions defined.
+    def has_conditions?
+      self.conditions && (has_conditions_proc? || !self.conditions.empty?)
+    end
+
+    # Checks whether entity meets conditions of this Mailing.
+    #
+    # @raise [ArgumentError] if the conditions do not evaluate to boolean.
     def conditions_met? entity
-      subscription = self.list.subscription_for(entity)
+      subscription = Subscription.get_from(entity) || self.list.subscription_for(entity)
 
-      if self.list.context.attributes
-        evaluator = Utils::MarkupEvaluator.new(self.list.context.drop_for(entity, subscription))
-        evaluator.evaluate_conditions(self.conditions)
+      if has_conditions_proc?
+        !!conditions.call(entity, subscription)
       else
-        true
+        if self.list.context.attributes
+          evaluator = Utils::MarkupEvaluator.new(self.list.context.drop_for(entity, subscription))
+          evaluator.evaluate_conditions(self.conditions)
+        else
+          true
+        end
       end
     end
 
+    # Checks whether conditions evaluate properly for given entity.
+    def test_conditions entity
+      conditions_met?(entity)
+      true
+    rescue StandardError => e
+      false
+    end
+
+    # Returns destination email address for given entity.
     def destination entity
       self.list.context.destination_for(entity)
     end
 
+    # Renders email body for given entity.
+    #
+    # Reads {#template} attribute and renders it using Liquid within the context
+    # for provided entity.
     def render_template entity
       subscription = self.list.subscription_for(entity)
       return unless subscription
@@ -81,6 +159,10 @@ module MailyHerald
       perform_template_rendering drop, self.template
     end
 
+    # Renders email subject line for given entity.
+    #
+    # Reads {#subject} attribute and renders it using Liquid within the context
+    # for provided entity.
     def render_subject entity
       subscription = self.list.subscription_for(entity)
       return unless subscription
@@ -89,40 +171,63 @@ module MailyHerald
       perform_template_rendering drop, self.subject
     end
 
-    def build_mail entity
+    # Builds `Mail::Message` object for given entity.
+    #
+    # Depending on {#mailer_name} value it uses either generic mailer (from {Mailer} class)
+    # or custom mailer.
+    def build_mail schedule
       if generic_mailer?
-        Mailer.generic(entity, self)
+        Mailer.generic(schedule, self)
       else
-        self.mailer.send(self.name, entity)
+        self.mailer.send(self.name, schedule)
       end
     end
 
-    def deliver_to entity
-      build_mail(entity).deliver
-    end
-
     protected
 
+    # Sends mailing to given entity.
+    #
+    # Performs actual sending of emails; should be called in background.
+    #
+    # Returns `Mail::Message`.
+    def deliver schedule
+      build_mail(schedule).deliver
+    rescue StandardError => e
+      MailyHerald.logger.log_processing(self, schedule.entity, prefix: "Error", level: :error) 
+      schedule.update_attributes(status: :error, data: {msg: "#{e.to_s}\n\n#{e.backtrace.join("\n")}"})
+      return nil
+    end
+
     # Called from Mailer, block required
-    def deliver_with_mailer_to entity
+    def deliver_with_mailer schedule
+      entity = schedule.entity
+
       unless processable?(entity)
-        MailyHerald.logger.log_processing(self, entity, prefix: "Not processable", level: :debug) 
-        return 
+        # Most likely the entity went out of the context scope.
+        # Let's leave the log for now just in case it comes back into the scope.
+        MailyHerald.logger.log_processing(self, entity, prefix: "Not processable. Delaying schedule by one day", level: :debug) 
+        skip_reason = in_scope?(entity) ? :not_processable : :not_in_scope
+        schedule.skip(skip_reason) unless schedule.postpone_delivery
+        return schedule
       end
 
       unless conditions_met?(entity)
         MailyHerald.logger.log_processing(self, entity, prefix: "Conditions not met", level: :debug) 
-        return {status: :skipped}
+        schedule.skip(:conditions_unmet)
+        return schedule
       end
 
       mail = yield # Let mailer do his job
 
       MailyHerald.logger.log_processing(self, entity, mail, prefix: "Processed") 
+      schedule.deliver(mail.to_s)
 
-      return {status: :delivered, data: {content: mail.to_s}}
+      return schedule
     rescue StandardError => e
-      MailyHerald.logger.log_processing(self, entity, prefix: "Error", level: :error) 
-      return {status: :error, data: {msg: "#{e.to_s}\n\n#{e.backtrace.join("\n")}"}}
+      MailyHerald.logger.log_processing(self, schedule.entity, prefix: "Error", level: :error) 
+      schedule.error("#{e.to_s}\n\n#{e.backtrace.join("\n")}")
+
+      return schedule
     end
 
     private
@@ -136,9 +241,29 @@ module MailyHerald
     end
 
     def validate_conditions
-      evaluator = Utils::MarkupEvaluator.test_conditions(self.conditions)
+      return true if has_conditions_proc?
+
+      result = Utils::MarkupEvaluator.test_conditions(self.conditions)
+
+      errors.add(:conditions, "is not a boolean value") unless result
     rescue StandardError => e
       errors.add(:conditions, e.to_s) 
     end
+
+    def validate_start_at
+      return true if has_start_at_proc?
+
+      result = Utils::MarkupEvaluator.test_start_at(self.start_at)
+
+      errors.add(:start_at, "is not a time value") unless result
+    rescue StandardError => e
+      errors.add(:start_at, e.to_s) 
+    end
+
+    def mailer_validity
+      !!mailer unless generic_mailer?
+    rescue
+      errors.add(:mailer_name, :invalid)
+    end
   end
 end

data/app/models/maily_herald/one_time_mailing.rb

@@ -1,26 +1,131 @@
 module MailyHerald
   class OneTimeMailing < Mailing
     validates   :list,          presence: true
+    validates   :start_at,      presence: true
+    validate    :validate_start_at
 
-    # Returns array of Mail::Message
+    after_save :update_schedules_callback, if: Proc.new{|m| m.state_changed? || m.start_at_changed? || m.override_subscription?}
+
+    # Sends mailing to all subscribed entities.
+    #
+    # Performs actual sending of emails; should be called in background.
+    #
+    # Returns array of {MailyHerald::Log} with actual `Mail::Message` objects stored
+    # in {MailyHerald::Log.mail} attributes.
     def run
-      self.list.subscriptions.collect do |subscription|
-        entity = subscription.entity
+      # TODO better scope here to exclude schedules for users outside context scope
+      schedules.where("processing_at <= (?)", Time.now).collect do |schedule|
+        if schedule.entity
+          mail = deliver schedule
+          schedule.reload
+          schedule.mail = mail
+          schedule
+        else
+          MailyHerald.logger.log_processing(schedule.mailing, {class: schedule.entity_type, id: schedule.entity_id}, prefix: "Removing schedule for non-existing entity") 
+          schedule.destroy
+        end
+      end
+    end
+
+    # Returns collection of processed {Log}s for given entity.
+    def processed_logs entity
+      Log.ordered.for_entity(entity).for_mailing(self).processed
+    end
+
+    # Sets the delivery schedule for given entity
+    #
+    # New schedule will be created or existing one updated.
+    # Schedule is {Log} object of type "schedule".
+    def set_schedule_for entity
+      if processed_logs(entity).last
+        # this mailing is sent only once
+        log = schedule_for(entity)
+        log.try(:destroy)
+        return
+      end
 
-        next unless processable?(entity)
+      subscribed = self.list.subscribed?(entity)
+      start_time = start_processing_time(entity)
 
-        deliver_to entity
+      if !self.start_at || !enabled? || !start_time || !(self.override_subscription? || subscribed)
+        log = schedule_for(entity)
+        log.try(:destroy)
+        return
       end
+
+      log = schedule_for(entity)
+
+      log ||= Log.new
+      log.with_lock do
+        log.set_attributes_for(self, entity, {
+          status: :scheduled,
+          processing_at: start_time,
+        })
+        log.save!
+      end
+      log
     end
 
-    # Returns single Mail::Message
-    def deliver_with_mailer_to entity
-      attrs = super entity
-      Log.create_for(self, entity, attrs) if attrs
+    # Sets delivery schedules of all entities in mailing scope.
+    #
+    # New schedules will be created or existing ones updated.
+    def set_schedules
+      self.list.context.scope_with_subscription(self.list, :outer).each do |entity|
+        MailyHerald.logger.debug "Updating schedule of #{self} one-time for entity ##{entity.id} #{entity}"
+        set_schedule_for entity
+      end
+    end
+
+    # Returns {Log} object which is the delivery schedule for given entity.
+    def schedule_for entity
+      schedules.for_entity(entity).first
+    end
+
+    # Returns collection of all delivery schedules ({Log} collection).
+    def schedules
+      Log.ordered.scheduled.for_mailing(self)
+    end
+
+    # Returns processing time for given entity.
+    #
+    # This is the time when next mailing should be sent based on
+    # {#start_at} mailing attribute.
+    def start_processing_time entity
+      subscription = self.list.subscription_for(entity)
+
+      if has_start_at_proc?
+        start_at.call(entity, subscription)
+      else
+        evaluator = Utils::MarkupEvaluator.new(self.list.context.drop_for(entity, subscription))
+
+        evaluator.evaluate_start_at(self.start_at)
+      end
     end
 
     def to_s
       "<OneTimeMailing: #{self.title || self.name}>"
     end
+
+    private
+
+    def deliver_with_mailer schedule
+      current_time = Time.now
+
+      schedule.with_lock do
+        # make sure schedule hasn't been processed in the meantime
+        if schedule && schedule.processing_at <= current_time && schedule.scheduled?
+          schedule = super(schedule)
+          if schedule
+            schedule.processing_at = current_time if schedule.processed?
+            schedule.save!
+          end
+        end
+      end if schedule
+    end
+
+    def update_schedules_callback
+      Rails.env.test? ? set_schedules : MailyHerald::ScheduleUpdater.perform_in(10.seconds, self.id)
+    end
+
   end
 end