mlist 0.1.9

data/lib/mlist/list.rb

@@ -0,0 +1,183 @@
+module MList
+  
+  # Represents the interface of the lists that a list manager must answer.
+  # This is distinct from the MList::MailList to allow for greater flexibility
+  # in processing email coming to a list - that is, whatever you include this
+  # into may re-define behavior appropriately.
+  #
+  # Your 'subscriber' instances MUST respond to :email_address. They may
+  # optionally respond to :display_name.
+  #
+  module List
+    
+    # Answers whether this list is active or not. All lists are active all the
+    # time by default.
+    #
+    def active?
+      true
+    end
+    
+    # Answers whether the subscriber is blocked from posting or not. This will
+    # not be asked when the list is not active (answers _active?_ as false).
+    #
+    def blocked?(subscriber)
+      false
+    end
+    
+    # Answers the footer content for this list. Default implementation is very
+    # simple.
+    #
+    def footer_content(message)
+      %Q{The "#{label}" mailing list\nPost messages: #{post_url}}
+    end
+    
+    # Answer a suitable label for the list, which will be used in various
+    # parts of content that is delivered to subscribers, etc.
+    #
+    def label
+      raise 'answer the list label'
+    end
+    
+    # Answers the headers that are to be included in the emails delivered for
+    # this list. Any entries that have a nil value will not be included in the
+    # delivered email.
+    #
+    def list_headers
+      {
+        'list-id'          => list_id,
+        'list-archive'     => archive_url,
+        'list-subscribe'   => subscribe_url,
+        'list-unsubscribe' => unsubscribe_url,
+        'list-owner'       => owner_url,
+        'list-help'        => help_url,
+        'list-post'        => post_url
+      }
+    end
+    
+    # Answers a unique, never changing value for this list.
+    #
+    def list_id
+      raise 'answer a unique, never changing value'
+    end
+    
+    # The web address where an archive of this list may be found, nil if there
+    # is no archive.
+    #
+    def archive_url
+      nil
+    end
+    
+    # Should the sender of an email be copied in the publication? Defaults to
+    # false. If _recipients_ includes the sender email address, it will be
+    # removed if this answers false.
+    #
+    # The sending subscriber is provided to support preferential answering.
+    #
+    def copy_sender?(subscriber)
+      false
+    end
+    
+    # The web address of the list help site, nil if this is not supported.
+    #
+    def help_url
+      nil
+    end
+    
+    # The email address of the list owner, nil if this is not supported.
+    #
+    def owner_url
+      nil
+    end
+    
+    # The email address where posts should be sent. Defaults to the address of
+    # the list.
+    #
+    def post_url
+      address
+    end
+    
+    # Should the reply-to header be set to the list's address? Defaults to
+    # true. If false is returned, the reply-to will be the subscriber address.
+    #
+    def reply_to_list?
+      true
+    end
+    
+    # The web url where subscriptions to this list may be created, nil if this
+    # is not supported.
+    #
+    def subscribe_url
+      nil
+    end
+    
+    # The web url where subscriptions to this list may be deleted, nil if this
+    # is not supported.
+    #
+    def unsubscribe_url
+      nil
+    end
+    
+    # A list is responsible for answering the recipient subscribers. The
+    # answer may or may not include the subscriber; _copy_sender?_ will be
+    # invoked and the subscriber will be added or removed from the Array.
+    #
+    # The sending subscriber is provided if the list would like to utilize it
+    # in calculating the recipients.
+    #
+    def recipients(subscriber)
+      subscribers
+    end
+    
+    # A list must answer the subscriber who's email address is that of the one
+    # provided. The default implementation will pick the first instance that
+    # answers subscriber.email_address == email_address. Your implementation
+    # should probably select just one record.
+    #
+    def subscriber(email_address)
+      subscribers.detect {|s| s.email_address == email_address}
+    end
+    
+    # A list must answer whether there is a subscriber who's email address is
+    # that of the one provided. This is checked before the subscriber is
+    # requested in order to allow for the lightest weight check possible; that
+    # is, your implementation could avoid loading the actual subscriber
+    # instance.
+    #
+    def subscriber?(email_address)
+      !subscriber(email_address).nil?
+    end
+    
+    # Methods that will be invoked on your implementation of Mlist::List when
+    # certain events occur during the processing of email sent to a list.
+    #
+    module Callbacks
+      
+      # Called when an email is a post to the list by a subscriber whom the
+      # list claims is blocked (answers true to _blocked?(subscriber)_). This
+      # will not be called if the list is inactive (answers false to
+      # _active?_);
+      #
+      def blocked_subscriber_post(email, subscriber)
+      end
+      
+      def bounce(email)
+      end
+      
+      # Called when an email is a post to the list while the list is inactive
+      # (answers false to _active?_). This will not be called if the email is
+      # from a non-subscribed sender. Instead, _non_subscriber_post_ will be
+      # called.
+      #
+      def inactive_post(email)
+      end
+      
+      # Called when an email is a post to the list from a non-subscribed
+      # sender. This will be called even if the list is inactive.
+      #
+      def non_subscriber_post(email)
+      end
+    end
+    include Callbacks
+    
+  end
+end

data/lib/mlist/mail_list.rb

@@ -0,0 +1,277 @@
+module MList
+  class MailList < ActiveRecord::Base
+    set_table_name 'mlist_mail_lists'
+    
+    # Provides the MailList for a given implementation of MList::List,
+    # connecting it to the provided email server for delivering posts.
+    #
+    def self.find_or_create_by_list(list, outgoing_server)
+      if list.is_a?(ActiveRecord::Base)
+        mail_list = find_or_create_by_manager_list_identifier_and_manager_list_type_and_manager_list_id(
+          list.list_id, list.class.base_class.name, list.id
+        )
+      else
+        mail_list = find_or_create_by_manager_list_identifier(list.list_id)
+        mail_list.manager_list = list
+      end
+      mail_list.outgoing_server = outgoing_server
+      mail_list
+    end
+    
+    include MList::Util::EmailHelpers
+    
+    belongs_to :manager_list, :polymorphic => true
+    
+    before_destroy :delete_unreferenced_email
+    has_many :messages, :class_name => 'MList::Message', :dependent => :delete_all
+    has_many :threads, :class_name => 'MList::Thread', :dependent => :delete_all
+    
+    delegate :address, :label, :post_url, :to => :list
+    
+    attr_accessor :outgoing_server
+    
+    # Creates a new MList::Message and delivers it to the subscribers of this
+    # list.
+    #
+    def post(email_or_attributes)
+      email = email_or_attributes
+      email = MList::EmailPost.new(email_or_attributes) unless email.is_a?(MList::EmailPost)
+      process_message messages.build(
+        :parent => email.reply_to_message,
+        :parent_identifier => email.parent_identifier,
+        :mail_list => self,
+        :subscriber => email.subscriber,
+        :recipients => list.recipients(email.subscriber),
+        :email => MList::Email.new(:source => email.to_s)
+      ), :search_parent => false, :copy_sender => email.copy_sender
+    end
+    
+    # Processes the email received by the MList::Server.
+    #
+    def process_email(email, subscriber)
+      recipients = list.recipients(subscriber)
+      process_message messages.build(
+        :mail_list => self,
+        :subscriber => subscriber,
+        :recipients => recipients,
+        :email => email
+      ), :copy_sender => list.copy_sender?(subscriber)
+    end
+    
+    # Answers the provided subject with superfluous 're:' and this list's
+    # labels removed.
+    #
+    #   clean_subject('[List Label] Re: The new Chrome Browser from Google') => 'Re: The new Chrome Browser from Google'
+    #   clean_subject('Re: [List Label] Re: The new Chrome Browser from Google') => 'Re: The new Chrome Browser from Google'
+    #
+    def clean_subject(string)
+      without_label = string.gsub(subject_prefix_regex, '')
+      if without_label =~ REGARD_RE
+        "Re: #{remove_regard(without_label)}"
+      else
+        without_label
+      end
+    end
+    
+    def find_parent_message(email)
+      if in_reply_to = email.header_string('in-reply-to')
+        message = messages.find(:first,
+          :conditions => ['identifier = ?', remove_brackets(in_reply_to)])
+        return message if message
+      end
+      
+      if email.references
+        reference_identifiers = email.references.collect {|rid| remove_brackets(rid)}
+        message = messages.find(:first,
+          :conditions => ['identifier in (?)', reference_identifiers],
+          :order => 'created_at desc')
+        return message if message
+      end
+      
+      if email.subject =~ REGARD_RE
+        message = messages.find(:first,
+          :conditions => ['subject = ?', remove_regard(clean_subject(email.subject))],
+          :order => 'created_at asc')
+        return message if message
+      end
+    end
+    
+    # The MList::List instance of the list manager.
+    #
+    def list
+      @list ||= manager_list
+    end
+    
+    def manager_list_with_dual_type=(list)
+      if list.is_a?(ActiveRecord::Base)
+        self.manager_list_without_dual_type = list
+        @list = list
+      else
+        self.manager_list_without_dual_type = nil
+        @list = list
+      end
+    end
+    alias_method_chain :manager_list=, :dual_type
+    
+    # Distinct footer start marker. It is important to realize that changing
+    # this could be problematic.
+    #
+    FOOTER_BLOCK_START    = "-~----~~----~----~----~----~---~~-~----~------~--~-~-"
+    
+    # Distinct footer end marker. It is important to realize that changing
+    # this could be problematic.
+    #
+    FOOTER_BLOCK_END      = "--~--~---~-----~--~----~-----~~~----~---~---~--~----~"
+    
+    private
+      FOOTER_BLOCK_START_RE = %r[#{FOOTER_BLOCK_START}]
+      FOOTER_BLOCK_END_RE   = %r[#{FOOTER_BLOCK_END}]
+      
+      # http://mail.python.org/pipermail/mailman-developers/2006-April/018718.html
+      def bounce_headers
+        # tmail would not correctly quote the label in the sender header, which would break smtp delivery
+        {'sender' => "<mlist-#{address}>", 'errors-to' => "#{label} <mlist-#{address}>"}
+      end
+      
+      def delete_unreferenced_email
+        conditions = %Q{
+          mlist_emails.id in (
+            select me.id from mlist_emails me left join mlist_messages mm on mm.email_id = me.id
+            where mm.mail_list_id = #{id}
+          ) AND mlist_emails.id not in (
+            select meb.id from mlist_emails meb left join mlist_messages mmb on mmb.email_id = meb.id
+            where mmb.mail_list_id != #{id}
+          )}
+        MList::Email.delete_all(conditions)
+      end
+      
+      def strip_list_footers(content)
+        if content =~ FOOTER_BLOCK_START_RE
+          in_footer_block = false
+          content = normalize_new_lines(content)
+          content = content.split("\n").reject do |line|
+            if in_footer_block
+              in_footer_block = line !~ FOOTER_BLOCK_END_RE
+              true
+            else
+              in_footer_block = line =~ FOOTER_BLOCK_START_RE
+            end
+          end.join("\n").rstrip
+        end
+        content
+      end
+      
+      # http://www.jamesshuggins.com/h/web1/list-email-headers.htm
+      def list_headers
+        headers = list.list_headers.dup
+        headers['x-beenthere'] = address
+        headers['x-mlist-version'] = MList.version.to_s
+        headers.update(bounce_headers)
+        headers.delete_if {|k,v| v.nil?}
+      end
+      
+      # Answer headers values which should be stripped from outgoing email.
+      #
+      def strip_headers
+        %w(return-receipt-to domainkey-signature dkim-signature)
+      end
+      
+      def process_message(message, options = {})
+        raise MList::DoubleDeliveryError.new(message) unless message.new_record?
+        
+        options = {
+          :search_parent => true,
+          :delivery_time => Time.now,
+          :copy_sender => false
+        }.merge(options)
+        
+        transaction do
+          thread = find_thread(message, options)
+          thread.updated_at = options[:delivery_time]
+          
+          delivery = prepare_delivery(message, options)
+          thread.messages << message
+          
+          self.updated_at = options[:delivery_time]
+          thread.save! && save!
+          
+          outgoing_server.deliver(delivery.tmail)
+        end
+        
+        message
+      end
+      
+      def prepare_delivery(message, options)
+        message.identifier = outgoing_server.generate_message_id
+        message.created_at = options[:delivery_time]
+        message.subject = clean_subject(message.subject)
+        
+        recipient_addresses = message.recipient_addresses
+        sender_address = message.subscriber.email_address
+        if options[:copy_sender]
+          recipient_addresses << sender_address unless recipient_addresses.include?(sender_address)
+        else
+          recipient_addresses.delete(sender_address)
+        end
+        
+        returning(message.delivery) do |delivery|
+          delivery.date ||= options[:delivery_time]
+          delivery.message_id = message.identifier
+          delivery.mailer = message.mailer
+          delivery.headers = list_headers
+          strip_headers.each {|e| delivery[e] = nil}
+          delivery.subject = list_subject(message.subject)
+          delivery.to = address
+          delivery.cc = []
+          delivery.bcc = recipient_addresses
+          delivery.reply_to ||= reply_to_header(message)
+          prepare_list_footer(delivery, message)
+        end
+      end
+      
+      def prepare_list_footer(delivery, message)
+        text_plain_part = delivery.text_plain_part
+        return unless text_plain_part
+        
+        content = strip_list_footers(text_plain_part.body)
+        content << "\n\n" unless content.end_with?("\n\n")
+        content << list_footer(message)
+        text_plain_part.body = content
+      end
+      
+      def list_footer(message)
+        content = list.footer_content(message)
+        "#{FOOTER_BLOCK_START}\n#{content}\n#{FOOTER_BLOCK_END}"
+      end
+      
+      def list_subject(string)
+        list_subject = string.dup
+        if list_subject =~ REGARD_RE
+          "Re: #{subject_prefix} #{remove_regard(list_subject)}"
+        else
+          "#{subject_prefix} #{list_subject}"
+        end
+      end
+      
+      def find_thread(message, options)
+        message.parent = find_parent_message(message.email) if message.email && options[:search_parent]
+        message.parent ? message.parent.thread : threads.build
+      end
+      
+      def reply_to_header(message)
+        if list.reply_to_list?
+          "#{label} #{bracket(address)}"
+        else
+          subscriber_name_and_address(message.subscriber)
+        end
+      end
+      
+      def subject_prefix_regex
+        @subject_prefix_regex ||= Regexp.new(Regexp.escape(subject_prefix) + ' ')
+      end
+      
+      def subject_prefix
+        @subject_prefix ||= "[#{label}]"
+      end
+  end
+end

data/lib/mlist/manager/database.rb

@@ -0,0 +1,48 @@
+module MList
+  module Manager
+    
+    class Database
+      include ::MList::Manager
+      
+      def create_list(address, attributes = {})
+        attributes = {
+          :address => address,
+          :label   => address.match(/\A(.*?)@/)[1]
+        }.merge(attributes)
+        List.create!(attributes)
+      end
+      
+      def lists(email)
+        lists = List.find_all_by_address(email.list_addresses)
+        email.list_addresses.map { |a| lists.detect {|l| l.address == a} }.compact
+      end
+      
+      def no_lists_found(email)
+        # TODO: Move to notifier
+      end
+      
+      class List < ActiveRecord::Base
+        include ::MList::List
+        
+        has_many :subscribers, :dependent => :delete_all
+        
+        def label
+          self[:label]
+        end
+        
+        def list_id
+          "#{self.class.name}#{id}"
+        end
+        
+        def subscribe(address)
+          subscribers.find_or_create_by_email_address(address)
+        end
+      end
+      
+      class Subscriber < ActiveRecord::Base
+        belongs_to :list
+      end
+    end
+    
+  end
+end

data/lib/mlist/manager/notifier.rb

@@ -0,0 +1,31 @@
+module MList
+  module Manager
+    
+    # Constructs the notices that are sent to list subscribers. Applications
+    # may subclass this to customize the content of a notice delivery.
+    #
+    class Notifier
+      
+      # Answers the delivery that will be sent to a subscriber when an
+      # MList::List indicates that the distribution of an email from that
+      # subscriber has been blocked.
+      #
+      def subscriber_blocked(list, email, subscriber)
+        delivery = MList::Util::TMailBuilder.new(TMail::Mail.new)
+        delivery.write_header('x-mlist-loop', 'notice')
+        delivery.write_header('x-mlist-notice', 'subscriber_blocked')
+        delivery.to = subscriber.email_address
+        delivery.from = "mlist-#{list.address}"
+        prepare_subscriber_blocked_content(list, email, subscriber, delivery)
+        delivery
+      end
+      
+      protected
+        def prepare_subscriber_blocked_content(list, email, subscriber, delivery)
+          delivery.set_content_type('text/plain')
+          delivery.body = %{Although you are a subscriber to this list, your message cannot be posted at this time. Please contact the administrator of the list.}
+        end
+    end
+    
+  end
+end

data/lib/mlist/manager.rb

@@ -0,0 +1,30 @@
+require 'mlist/manager/notifier'
+
+module MList
+  
+  # The interface of list managers.
+  #
+  # A module is provided instead of a base class to allow implementors to
+  # subclass whatever they like. Practically speaking, they can create an
+  # ActiveRecord subclass.
+  #
+  module Manager
+    
+    # Answers an enumeration of MList::List implementations to which the given
+    # email should be published.
+    #
+    def lists(email)
+      raise 'implement in your list manager'
+    end
+    
+    # Answers the MList::Manager::Notifier of this list manager. Includers of
+    # this module may initialize the @notifier instance variable with their
+    # own implementation/subclass to generate custom content for the different
+    # notices.
+    #
+    def notifier
+      @notifier ||= MList::Manager::Notifier.new
+    end
+  end
+  
+end