maily_herald 0.8.0 → 0.9.1

data/app/mailers/maily_herald/mailer.rb

@@ -2,16 +2,16 @@ module MailyHerald
   class Mailer < ActionMailer::Base
     attr_reader :entity
 
-    def generic entity, mailing
-      destination = mailing.destination(entity)
-      subject = mailing.render_subject(entity)
-      content = mailing.render_template(entity)
+    def generic entity
+      destination = @maily_herald_mailing.destination(entity)
+      subject = @maily_herald_mailing.render_subject(entity)
+      content = @maily_herald_mailing.render_template(entity)
 
       opts = {
         to: destination, 
         subject: subject
       }
-      opts[:from] = mailing.from if mailing.from.present?
+      opts[:from] = @maily_herald_mailing.from if @maily_herald_mailing.from.present?
 
       mail(opts) do |format|
         format.text { render text: content }
@@ -21,12 +21,22 @@ module MailyHerald
     class << self
       #TODO make it instance method so we get access to instance attributes
       def deliver_mail(mail) #:nodoc:
+        unless mail.maily_herald_data
+          MailyHerald.logger.error("Unable to send message. Invalid mailing provided.")
+          return
+        end
+
         mailing = mail.maily_herald_data[:mailing]
         entity = mail.maily_herald_data[:entity]
+        schedule = mail.maily_herald_data[:schedule]
 
+        if !schedule && mailing.respond_to?(:schedule_delivery_to)
+          # Implicitly create schedule for ad hoc delivery when called using Mailer.foo(entity).deliver syntax
+          schedule = mail.maily_herald_data[:schedule] = mailing.schedule_delivery_to(entity)
+        end
 
-        if mailing && entity
-          mailing.deliver_with_mailer_to(entity) do
+        if schedule
+          mailing.send(:deliver_with_mailer, schedule) do
             ActiveSupport::Notifications.instrument("deliver.action_mailer") do |payload|
               self.set_payload_for_mail(payload, mail)
               yield # Let Mail do the delivery actions
@@ -34,12 +44,7 @@ module MailyHerald
             mail
           end
         else
-          MailyHerald.logger.log_processing(mailing, entity, mail, prefix: "Delivery outside Maily")
-
-          ActiveSupport::Notifications.instrument("deliver.action_mailer") do |payload|
-            self.set_payload_for_mail(payload, mail)
-            yield # Let Mail do the delivery actions
-          end
+          MailyHerald.logger.log_processing(mailing, entity, mail, prefix: "Attempt to deliver email without schedule. No mail was sent", level: :debug)
         end
       end
     end
@@ -48,9 +53,11 @@ module MailyHerald
       return @_message if @_mail_was_called && headers.blank? && !block
 
       # Assign instance variables availabe for template
-      @maily_subscription = @_message.maily_herald_data[:subscription]
-      @maily_entity = @_message.maily_herald_data[:entity]
-      @maily_mailing = @_message.maily_herald_data[:mailing]
+      if @_message.maily_herald_data
+        @maily_subscription = @_message.maily_herald_data[:subscription]
+        @maily_entity = @_message.maily_herald_data[:entity]
+        @maily_mailing = @_message.maily_herald_data[:mailing]
+      end
 
       super
     end
@@ -70,20 +77,31 @@ module MailyHerald
         end
       end
 
-      mailing = args[0].to_s == "generic" ? args[2] : MailyHerald.dispatch(args[0])
-      entity = args[1]
+      if args[1].is_a?(MailyHerald::Log)
+        @maily_herald_schedule = args[1]
+        @maily_herald_mailing = @maily_herald_schedule.mailing
+        @maily_herald_entity = @maily_herald_schedule.entity
+      else
+        @maily_herald_mailing = args[0].to_s == "generic" ? args[2] : MailyHerald.dispatch(args[0])
+        @maily_herald_entity = args[1]
+      end
 
-      @_message.maily_herald_data = {
-        mailing: mailing,
-        entity: entity,
-        subscription: mailing.subscription_for(entity),
-      }
+      if @maily_herald_mailing
+        @_message.maily_herald_data = {
+          schedule: @maily_herald_schedule,
+          mailing: @maily_herald_mailing,
+          entity: @maily_herald_entity,
+          subscription: @maily_herald_mailing.subscription_for(@maily_herald_entity),
+        }
+      end
 
       lookup_context.skip_default_locale!
-      super
+      super(args[0], @maily_herald_entity)
 
-      @_message.to = mailing.destination(entity) unless @_message.to
-      @_message.from = mailing.from unless @_message.from
+      if @maily_herald_mailing
+        @_message.to = @maily_herald_mailing.destination(@maily_herald_entity) unless @_message.to
+        @_message.from = @maily_herald_mailing.from unless @_message.from
+      end
 
       @_message
     end

data/app/models/maily_herald/ad_hoc_mailing.rb

@@ -0,0 +1,109 @@
+module MailyHerald
+  class AdHocMailing < Mailing
+    validates   :list,          presence: true
+
+    # Schedules mailing delivery to all entities in the scope at given `time`.
+    #
+    # This always creates new {MailyHerald::Log} objects of type `schedule`.
+    #
+    # @param time [Time] time of delivery
+    def schedule_delivery_to_all time = Time.now
+      self.list.context.scope_with_subscription(self.list, :outer).each do |entity|
+        MailyHerald.logger.debug "Adding schedule of #{self} ad-hoc for entity ##{entity.id} #{entity}"
+        schedule_delivery_to entity, time
+      end
+    end
+
+    # Schedules mailing delivery to `entity` at given `time`.
+    #
+    # This always creates new {MailyHerald::Log} object of type `schedule`.
+    #
+    # @param entity [ActiveRecord::Base]
+    # @param time [Time] time of delivery
+    def schedule_delivery_to entity, time = Time.now
+      subscribed = self.list.subscribed?(entity)
+
+      if !enabled? || !(self.override_subscription? || subscribed)
+        return
+      end
+
+      log = Log.new
+      log.with_lock do
+        log.set_attributes_for(self, entity, {
+          status: :scheduled,
+          processing_at: time,
+        })
+        log.save!
+      end
+      log
+    end
+
+    # Sends mailing to all subscribed entities who have delivery scheduled.
+    #
+    # 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
+      # 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
+
+    # 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
+      subscribed = self.list.subscribed?(entity)
+
+      if !enabled? || !(self.override_subscription? || subscribed)
+        log = schedule_for(entity)
+        log.try(:destroy)
+        return
+      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
+
+    def to_s
+      "<AdHocMailing: #{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
+
+  end
+end

data/app/models/maily_herald/dispatch.rb

@@ -1,11 +1,42 @@
 module MailyHerald
+  # Main dispatch class.
+  #
+  # Inherited by all {Mailing} classes.
+  # Each Dispatch instance need to have associated {List}.
+  # Dispatch can be in one of three states:
+  # - +enabled+
+  # - +disabled+
+  # - +archived+
+  #
+  # @attr [String]    type            Polymorphic type.
+  # @attr [Fixnum]    sequence_id     {Sequence} association id.
+  # @attr [Fixnum]    list_id         {List} association id.
+  # @attr [String]    conditions      Delivery conditions as Liquid expression.
+  # @attr [String]    mailer_name     {Mailer} class name. 
+  #                                   This refers to {Mailer} used by Dispatch while sending emails.
+  # @attr [String]    name            Dispatch name.
+  # @attr [String]    title           Dispatch title.
+  # @attr [String]    from            Sender email address. 
+  #                                   If not provided, action_mailer.default_options[:from} is used.
+  #                                   Valid only for {Mailing}.
+  # @attr [String]    state
+  # @attr [String]    subject         Email subject as Liquid template.
+  #                                   Valid only for {Mailing}.
+  # @attr [String]    template        Email body template as Liquid template.
+  #                                   Valid only for {Mailing}.
+  # @attr [String]    absolute_delay  Email delivery delay from beginning of sequence.
+  #                                   Valid only for {SequenceMailing}.
+  # @attr [String]    period          Email delivery period.
+  #                                   Valid only for {PeriodicalMailing}.
+  # @attr [String]    override_subscription Defines whether email should be sent regardless of 
+  #                                   entity subscription state.
   class Dispatch < ActiveRecord::Base
     belongs_to  :list,          class_name: "MailyHerald::List"
 
     validates   :list,          presence: true
     validates   :state,         presence: true, inclusion: {in: [:enabled, :disabled, :archived]}
     validate do |dispatch|
-      dispatch.errors.add(:base, "Can't change this dispatch because it is locked.") if dispatch.locked?
+      dispatch.errors.add(:base, "Can't change this dispatch because it is locked.") if dispatch.changes.present? && dispatch.locked?
     end
     before_destroy do |dispatch|
       if dispatch.locked?
@@ -21,10 +52,52 @@ module MailyHerald
     scope       :archived,      lambda { where(state: :archived) }
     scope       :not_archived,  lambda { where("state != (?)", :archived) }
 
-    scope       :sequence,      lambda { where(type: Sequence) }
+    scope       :ad_hoc_mailing, lambda { where(type: AdHocMailing) }
     scope       :one_time_mailing, lambda { where(type: OneTimeMailing) }
     scope       :periodical_mailing, lambda { where(type: PeriodicalMailing) }
+    scope       :sequence,      lambda { where(type: Sequence) }
+
+    before_validation do
+      if @start_at_proc
+        self.start_at = "proc"
+      end
+    end
+
+    after_save do
+      if @start_at_proc
+        MailyHerald.start_at_procs[self.id] = @start_at_proc
+      end
+    end
+
+    # Sets start_at value of {OneTimeMailing}, {PeriodicalMailing} and {SequenceMailing}.
+    #
+    # @param v String with Liquid expression or `Proc` that evaluates to `Time`.
+    def start_at= v
+      if v.respond_to? :call
+        @start_at_proc = v
+      else
+        super(v.is_a?(Time) ? v.to_s : v)
+      end
+    end
 
+    # Returns time as string with Liquid expression or Proc.
+    def start_at
+      @start_at_proc || MailyHerald.start_at_procs[self.id] || read_attribute(:start_at)
+    end
+
+    def has_start_at_proc?
+      !!(@start_at_proc || MailyHerald.start_at_procs[self.id])
+    end
+
+    def start_at_changed?
+      if has_start_at_proc?
+        @start_at_proc != MailyHerald.start_at_procs[self.id]
+      else
+        super
+      end
+    end
+
+    # Returns dispatch state as symbol
     def state
       read_attribute(:state).to_sym
     end
@@ -59,18 +132,38 @@ module MailyHerald
       write_attribute(:state, "archived")
     end
 
+    # Sets {List} associated with this dispatch
+    #
+    # @param l {List} name or {List} object
     def list= l
       l = MailyHerald::List.find_by_name(l.to_s) if l.is_a?(String) || l.is_a?(Symbol)
       super(l)
     end
 
+    def subscription_valid? entity
+      self.override_subscription? || self.list.subscribed?(entity)
+    end
+
+    def in_scope? entity
+      self.list.context.scope.exists?(entity)
+    end
+
+    # Checks if dispatch can be sent to given entity.
+    #
+    # Following checks are performed:
+    # - dispatch is enabled,
+    # - subscription is overriden or user is subscribed to dispatch list,
+    # - entity belongs to list {Context} scope.
+    #
+    # @param entity [ActiveRecord::Base] Recipient
     def processable? entity
-      self.enabled? && (self.override_subscription? || self.list.subscribed?(entity)) && self.list.context.scope.exists?(entity)
+      self.enabled? && subscription_valid?(entity) && in_scope?(entity)
     end
 
+    # Check if dispatch is locked.
+    # @see MailyHerald.dispatch_locked?
     def locked?
       MailyHerald.dispatch_locked?(self.name)
     end
-
   end
 end

data/app/models/maily_herald/list.rb

@@ -1,4 +1,13 @@
 module MailyHerald
+  # Represents subscriptions list.
+  #
+  # Entities can be subscribed to lists by creating {Subscription} object for them.
+  #
+  # List have {Context} assigned. Only entities from Context scope can be subscribed to list.
+  #
+  # @attr [String]    name
+  # @attr [String]    title
+  # @attr [String]    context_name    Name of the {Context} used by List.
   class List < ActiveRecord::Base
     include MailyHerald::Autonaming
 
@@ -9,6 +18,8 @@ module MailyHerald
     has_many :dispatches, class_name: "MailyHerald::Dispatch"
     has_many :subscriptions, class_name: "MailyHerald::Subscription"
 
+    validates :context, presence: true
+
     validate do |list|
       list.errors.add(:base, "Can't change this list because it is locked.") if list.locked?
     end
@@ -19,67 +30,85 @@ module MailyHerald
       end
     end
 
+    # Returns {Context} object associated with List.
     def context
       @context ||= MailyHerald.context self.context_name
     end
 
+    # Subscribes entity to List.
+    #
+    # @param entity [Object] Entity object. Need to be in the {Context} scope.
     def subscribe! entity
       s = subscription_for(entity) 
       s ? s.activate! : s = create_subscription_for(entity, true)
       s
     end
 
+    # Unsubscribes entity from List.
+    #
+    # @param entity [Object] Entity object.
     def unsubscribe! entity
       s = subscription_for(entity) 
       s ? s.deactivate! : s = create_subscription_for(entity, false)
       s
     end
 
+    # Checks whether entity is subscribed to List.
     def subscribed? entity
-      subscription_for(entity).try(:active?)
+      s = Subscription.get_from(entity) || subscription_for(entity)
+      s.try(:active?)
     end
 
-    # true if user has inactive subscription or never been subscribed
+    # Checks whether entity is not subscribed to List.
+    #
+    # True if user has inactive subscription or never been subscribed.
     def unsubscribed? entity
-      s = subscription_for(entity)
+      s = Subscription.get_from(entity) || subscription_for(entity)
       s ? !s.active? : true
     end
 
-    # true only if user was intentionally unsubscribed
+    # Checks whether entity has been removed from List.
+    #
+    # True only if user was intentionally unsubscribed.
     def opted_out? entity
       s = subscription_for(entity)
       s ? !s.active? : false
     end
 
+    # Returns subscription for given entity.
     def subscription_for entity
       self.subscriptions.for_entity(entity).first
     end
 
+    # Returns number of List subscribers.
     def active_subscription_count
       subscribers.count(:id)
     end
 
-    # Returns entities within the context's scope with active subscription
+    # Returns entities within the context's scope with active subscription.
     def subscribers
       context.scope_with_subscription(self).where("#{Subscription.table_name}.active = (?)", true).where("#{Subscription.table_name}.list_id = (?)", self.id)
     end
 
-    # Returns entities within the context's scope with inactive subscription
+    # Returns entities within the context's scope with inactive subscription.
     def opt_outs
       context.scope_with_subscription(self).where("#{Subscription.table_name}.active = (?)", false).where("#{Subscription.table_name}.list_id = (?)", self.id)
     end
 
-    # Returns entities within the context's scope without subscription
+    # Returns entities within the context's scope without subscription.
     def potential_subscribers
       sq = context.scope_with_subscription(self, :outer).where("#{Subscription.table_name}.list_id = (?)", self.id).pluck("#{context.model.table_name}.id")
       context.scope.where(context.model.arel_table[:id].not_in(sq))
     end
 
+    # Returns {Log} objects collection related to this List.
     def logs
       #Log.for_mailings(self.dispatches.select("id"))
       Log.for_mailings(Dispatch.where("sequence_id IN (?) OR list_id = (?)", Sequence.where(list_id: self.id).select("id"), self.id).select("id"))
     end
 
+    # Check if List is locked.
+    # @see MailyHerald.list_locked?
     def locked?
       MailyHerald.list_locked?(self.name)
     end