aiwilliams-mlist 0.0.0

data/README

@@ -0,0 +1,63 @@
+= mlist
+
+http://aiwilliams.github.com/mlist
+
+== DESCRIPTION:
+
+An insane attempt to build a mail list server library that can be used
+other applications very easily. The first target is Ruby applications
+that can load MList models for direct integration. It will later have
+a RESTful API so that non-Ruby applications can easily integrate. That
+may depend heavily on community involvement...
+
+== FEATURES/PROBLEMS:
+
+There is a LOT to do: segmenting, spam filtering, HTML conversion, i18n,
+backscatter - only the Mailman developers know what else. I have enough
+experience to know that rewrites are NEVER as easy as they seem. I begin
+this with fear and trepidation. Alas, I go boldly forward.
+
+== SYNOPSIS:
+
+Let's say you want your web application to have a mailing list feature.
+Let's also say you care about the UI, and you don't want to learn all
+about creating the correct HTML structures for a mailing list. You want to
+have lots of power for searching the mail, and you have your own strategy
+for managing the lists. You love Ruby.
+
+== REQUIREMENTS:
+
+You'll need some gems.
+
+* activesupport
+* activerecord
+* tmail
+
+== INSTALL:
+
+* FIX (sudo gem install, anything else)
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Adam Williams (aiwilliams)
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,27 @@
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+
+require 'rubygems'
+require 'spec/rake/spectask'
+
+task :default => :spec
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.spec_opts = ['--options', 'spec/spec.opts']
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = 'mlist'
+    s.summary = 'A Ruby mailing list library designed to be integrated into other applications.'
+    s.email = 'adam@thewilliams.ws'
+    s.files = FileList["[A-Z]*", "{lib,rails}/**/*"].exclude("tmp,**/tmp")
+    s.homepage = "http://github.com/aiwilliams/mlist"
+    s.description = s.summary
+    s.authors = ['Adam Williams']
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 0
+:patch: 0
+:major: 0

data/lib/mlist.rb

@@ -0,0 +1,13 @@
+require 'tmail'
+require 'activerecord'
+
+require 'mlist/util'
+require 'mlist/message'
+require 'mlist/list'
+require 'mlist/mail_list'
+require 'mlist/email_server'
+require 'mlist/server'
+require 'mlist/thread'
+
+module MList
+end

data/lib/mlist/email_server.rb

@@ -0,0 +1,3 @@
+require 'mlist/email_server/email'
+require 'mlist/email_server/base'
+require 'mlist/email_server/fake'

data/lib/mlist/email_server/base.rb

@@ -0,0 +1,22 @@
+module MList
+  module EmailServer
+    class Base
+      def initialize
+        @receivers = []
+      end
+      
+      def deliver(email)
+        raise 'Implement actual delivery mechanism in subclasses'
+      end
+      
+      def receive(tmail)
+        email = EmailServer::Email.new(tmail)
+        @receivers.each { |r| r.receive(email) }
+      end
+      
+      def receiver(rx)
+        @receivers << rx
+      end
+    end
+  end
+end

data/lib/mlist/email_server/email.rb

@@ -0,0 +1,47 @@
+module MList
+  module EmailServer
+    
+    # The interface to an incoming email.
+    #
+    # My primary goal is to decouple the MList::EmailServer from the
+    # MList::Server, this class acting as the bridge.
+    #
+    class Email
+      
+      # TODO Provide the email_server to the instances
+      def initialize(tmail)
+        @tmail = tmail
+      end
+      
+      def from_address
+        @tmail.from.first
+      end
+      
+      # Answers the usable destination addresses of the email.
+      #
+      # TODO: Provide intelligence to this that allows it to ignore addresses
+      # that are not for the domain of the email_server.
+      #
+      def list_addresses
+        bounce? ? @tmail.header_string('to').match(/\Amlist-(.*)\Z/)[1] : @tmail.to
+      end
+      
+      # Answers true if this email is a bounce.
+      #
+      # TODO Delegate to the email_server's bounce detector.
+      #
+      def bounce?
+        @tmail.header_string('to') =~ /mlist-/
+      end
+      
+      # Answers unique copies of the underlying TMail::Mail instance,
+      # providing assurance that the MList::Server and it's sub-systems don't
+      # stomp all over each other by getting a reference to a single
+      # TMail::Mail instance.
+      #
+      def tmail
+        TMail::Mail.parse(@tmail.to_s)
+      end
+    end
+  end
+end

data/lib/mlist/email_server/fake.rb

@@ -0,0 +1,16 @@
+module MList
+  module EmailServer
+    class Fake < Base
+      attr_reader :deliveries
+      
+      def initialize
+        super
+        @deliveries = []
+      end
+      
+      def deliver(tmail)
+        @deliveries << tmail
+      end
+    end
+  end
+end

data/lib/mlist/list.rb

@@ -0,0 +1,49 @@
+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.
+  #
+  module List
+    def bounce(email)
+      
+    end
+    
+    def host
+      address.match(/@(.*)\Z/)[1]
+    end
+    
+    def list_headers
+      {
+        'list-id'          => list_id,
+        'list-archive'     => (archive_url rescue nil),
+        'list-subscribe'   => (subscribe_url rescue nil),
+        'list-unsubscribe' => (unsubscribe_url rescue nil),
+        'list-owner'       => (owner_url rescue nil),
+        'list-help'        => (help_url rescue nil),
+        'list-post'        => post_url
+      }
+    end
+    
+    def list_id
+      "#{label} <#{address}>"
+    end
+    
+    def name
+      address.match(/\A(.*?)@/)[1]
+    end
+    
+    def post_url
+      address
+    end
+    
+    def recipients(message)
+      subscriptions.collect(&:address) - [message.from_address]
+    end
+    
+    def subscriber?(address)
+      !subscriptions.detect {|s| s.address == address}.nil?
+    end
+  end
+end

data/lib/mlist/mail_list.rb

@@ -0,0 +1,77 @@
+module MList
+  class MailList < ActiveRecord::Base
+    def self.find_or_create_by_list(list)
+      mail_list = find_or_create_by_identifier(list.list_id)
+      mail_list.manager_list = list
+      mail_list
+    end
+    
+    has_many :messages, :dependent => :delete_all
+    has_many :threads, :dependent => :delete_all
+    
+    attr_accessor :manager_list
+    delegate :address, :recipients, :subscriptions,
+             :to => :manager_list
+    
+    def post(email_server, message)
+      return unless process?(message)
+      prepare_delivery(message)
+      deliver(message, email_server)
+    end
+    
+    def been_there?(message)
+      message.header_string('x-beenthere') == address
+    end
+    
+    # http://mail.python.org/pipermail/mailman-developers/2006-April/018718.html
+    def bounce_headers
+      {'sender'    => "mlist-#{address}",
+       'errors-to' => "mlist-#{address}"}
+    end
+    
+    def deliver(message, email_server)
+      transaction do
+        email_server.deliver(message.tmail)
+        thread = find_thread(message)
+        thread.messages << message
+        thread.save!
+      end
+    end
+    
+    def find_thread(message)
+      if message.reply?
+        threads.find(:first,
+          :joins => :messages,
+          :readonly => false,
+          :conditions => ['messages.identifier = ?', message.parent_identifier]
+        )
+      else
+        threads.build
+      end
+    end
+    
+    # http://www.jamesshuggins.com/h/web1/list-email-headers.htm
+    def list_headers
+      headers = manager_list.list_headers
+      headers['x-beenthere'] = address
+      headers.update(bounce_headers)
+      headers.delete_if {|k,v| v.nil?}
+    end
+    
+    def prepare_delivery(message)
+      prepare_list_headers(message)
+      message.to = address
+      message.bcc = recipients(message)
+    end
+    
+    def prepare_list_headers(message)
+      list_headers.each do |k,v|
+        message.write_header(k,v)
+      end
+    end
+    
+    def process?(message)
+      !been_there?(message) && !recipients(message).blank?
+    end
+  end
+end

data/lib/mlist/manager/database.rb

@@ -0,0 +1,34 @@
+module MList
+  module Manager
+    
+    class Database
+      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} }
+      end
+      
+      class List < ActiveRecord::Base
+        include ::MList::List
+        
+        has_many :subscriptions, :dependent => :delete_all
+        
+        def subscribe(address)
+          subscriptions.find_or_create_by_address(address)
+        end
+      end
+      
+      class Subscription < ActiveRecord::Base
+        belongs_to :list
+      end
+    end
+    
+  end
+end

data/lib/mlist/message.rb

@@ -0,0 +1,107 @@
+module MList
+  
+  # The persisted version of an email that is processed by MList::MailLists.
+  #
+  # The tmail object referenced by these are unique, though they may reference
+  # the 'same' originating email.
+  #
+  class Message < ActiveRecord::Base
+    belongs_to :mail_list
+    
+    attr_writer :header_sanitizers
+    before_save :serialize_tmail
+    
+    def charset
+      'utf-8'
+    end
+    
+    def delete_header(name)
+      tmail[name] = nil
+    end
+    
+    def from_address
+      tmail.from.first
+    end
+    
+    def parent_identifier
+      if in_reply_to = header_string('in-reply-to')
+        identifier = in_reply_to
+      elsif references = read_header('references')
+        identifier = references.ids.first
+      else
+        parent_message = mail_list.messages.find(:first,
+          :conditions => ['messages.subject = ?', remove_regard(subject)],
+          :order => 'created_at asc'
+        )
+        identifier = parent_message.identifier if parent_message
+      end
+      remove_brackets(identifier) if identifier
+    end
+    
+    def read_header(name)
+      tmail[name]
+    end
+    
+    def reply?
+      !parent_identifier.nil?
+    end
+    
+    def write_header(name, value)
+      tmail[name] = sanitize_header(name, value)
+    end
+    
+    def tmail=(tmail)
+      write_attribute(:identifier, remove_brackets(tmail.header_string('message-id')))
+      write_attribute(:subject, tmail.subject)
+      @tmail = tmail
+    end
+    
+    def tmail
+      @tmail ||= TMail::Mail.parse(email_text)
+    end
+    
+    def to=(recipients)
+      tmail.to = sanitize_header('to', recipients)
+    end
+    
+    def bcc=(recipients)
+      tmail.bcc = sanitize_header('bcc', recipients)
+    end
+    
+    # Provide delegation to *most* of the underlying TMail::Mail methods,
+    # excluding those overridden by this class and the [] and []= methods. We
+    # must maintain the ActiveRecord interface over that of the TMail::Mail
+    # interface.
+    #
+    def method_missing(symbol, *args, &block) # :nodoc:
+      if @tmail && @tmail.respond_to?(symbol) && !(symbol == :[] || symbol == :[]=)
+        @tmail.__send__(symbol, *args, &block)
+      else
+        super
+      end
+    end
+    
+    def sanitize_header(name, *values)
+      header_sanitizer(name).call(charset, *values)
+    end
+    
+    private
+      def header_sanitizer(name)
+        @header_sanitizers ||= Util.default_header_sanitizers
+        @header_sanitizers[name]
+      end
+      
+      def remove_brackets(string)
+        string =~ /\A<(.*?)>\Z/ ? $1 : string
+      end
+      
+      def remove_regard(string)
+        stripped = string.strip
+        stripped =~ /\Are:\s+(.*?)\Z/i ? $1 : stripped
+      end
+      
+      def serialize_tmail
+        write_attribute(:email_text, @tmail.to_s)
+      end
+  end
+end

data/lib/mlist/server.rb

@@ -0,0 +1,36 @@
+module MList
+  class Server
+    attr_reader :list_manager, :email_server
+    
+    def initialize(config)
+      @list_manager = config[:list_manager]
+      @email_server = config[:email_server]
+      @email_server.receiver(self)
+    end
+    
+    def receive(email)
+      lists = list_manager.lists(email)
+      if email.bounce?
+        process_bounce(lists.first, email)
+      else
+        process_post(lists, email)
+      end
+    end
+    
+    protected
+      def process_bounce(list, email)
+        list.bounce(email)
+      end
+      
+      def process_post(lists, email)
+        lists.each do |list|
+          if list.subscriber?(email.from_address)
+            mail_list = MailList.find_or_create_by_list(list)
+            mail_list.post(email_server, MList::Message.new(:mail_list => mail_list, :tmail => email.tmail))
+          else
+            list.non_subscriber_posted(email)
+          end
+        end
+      end
+  end
+end

data/lib/mlist/thread.rb

@@ -0,0 +1,6 @@
+module MList
+  class Thread < ActiveRecord::Base
+    belongs_to :mail_list
+    has_many :messages, :dependent => :delete_all
+  end
+end

data/lib/mlist/util.rb

@@ -0,0 +1,9 @@
+require 'mlist/util/quoting'
+require 'mlist/util/header_sanitizer'
+
+module MList
+  module Util
+    mattr_accessor :default_header_sanitizers
+    self.default_header_sanitizers = HeaderSanitizerHash.new
+  end
+end

data/lib/mlist/util/header_sanitizer.rb

@@ -0,0 +1,63 @@
+module MList
+  module Util
+    
+    class QuotingSanitizer
+      include Quoting
+      
+      def initialize(method, bracket_urls)
+        @method, @bracket_urls = method, bracket_urls
+      end
+      
+      def bracket_urls(values)
+        values.map do |value|
+          if value.include?('<') && value.include?('>')
+            value
+          else
+            "<#{value}>"
+          end
+        end
+      end
+      
+      def call(charset, *values)
+        values = bracket_urls(values.flatten) if @bracket_urls
+        send(@method, charset, *values)
+      end
+    end
+    
+    class HeaderSanitizerHash
+      def initialize
+        @hash = Hash.new
+        initialize_default_sanitizers
+      end
+      
+      def initialize_default_sanitizers
+        self['to']       = quoter(:quote_any_address_if_necessary)
+        self['cc']       = quoter(:quote_any_address_if_necessary)
+        self['bcc']      = quoter(:quote_any_address_if_necessary)
+        self['from']     = quoter(:quote_any_address_if_necessary)
+        self['reply-to'] = quoter(:quote_any_address_if_necessary)
+        self['subject']  = quoter(:quote_any_if_necessary)
+        
+        self['List-Help']        = quoter(:quote_address_if_necessary)
+        self['List-Subscribe']   = quoter(:quote_address_if_necessary)
+        self['List-Unsubscribe'] = quoter(:quote_address_if_necessary)
+        self['List-Post']        = quoter(:quote_address_if_necessary)
+        self['List-Owner']       = quoter(:quote_address_if_necessary)
+        self['List-Archive']     = quoter(:quote_address_if_necessary)
+      end
+      
+      def [](key)
+        @hash[key.downcase] ||= lambda { |charset, value| value }
+      end
+      
+      def []=(key, value)
+        @hash[key.downcase] = value
+      end
+      
+      def quoter(method, bracket_urls = true)
+        QuotingSanitizer.new(method, bracket_urls)
+      end
+    end
+    
+  end
+end

data/lib/mlist/util/quoting.rb

@@ -0,0 +1,70 @@
+module MList
+  module Util
+    
+    # Copyright (c) 2004-2008 David Heinemeier Hansson
+    #
+    # Taken from ActionMailer. Modified to make charset first argument in all
+    # signatures, allowing for a consistent pattern of invocation.
+    #
+    module Quoting #:nodoc:
+      # Convert the given text into quoted printable format, with an instruction
+      # that the text be eventually interpreted in the given charset.
+      def quoted_printable(charset, text)
+        text = text.gsub( /[^a-z ]/i ) { quoted_printable_encode($&) }.
+                    gsub( / /, "_" )
+        "=?#{charset}?Q?#{text}?="
+      end
+
+      # Convert the given character to quoted printable format, taking into
+      # account multi-byte characters (if executing with $KCODE="u", for instance)
+      def quoted_printable_encode(character)
+        result = ""
+        character.each_byte { |b| result << "=%02x" % b }
+        result
+      end
+
+      # A quick-and-dirty regexp for determining whether a string contains any
+      # characters that need escaping.
+      if !defined?(CHARS_NEEDING_QUOTING)
+        CHARS_NEEDING_QUOTING = /[\000-\011\013\014\016-\037\177-\377]/
+      end
+
+      # Quote the given text if it contains any "illegal" characters
+      def quote_if_necessary(charset, text)
+        text = text.dup.force_encoding(Encoding::ASCII_8BIT) if text.respond_to?(:force_encoding)
+
+        (text =~ CHARS_NEEDING_QUOTING) ?
+          quoted_printable(charset, text) :
+          text
+      end
+
+      # Quote any of the given strings if they contain any "illegal" characters
+      def quote_any_if_necessary(charset, *args)
+        args.map { |v| quote_if_necessary(charset, v) }
+      end
+
+      # Quote the given address if it needs to be. The address may be a
+      # regular email address, or it can be a phrase followed by an address in
+      # brackets. The phrase is the only part that will be quoted, and only if
+      # it needs to be. This allows extended characters to be used in the
+      # "to", "from", "cc", "bcc" and "reply-to" headers.
+      def quote_address_if_necessary(charset, address)
+        if Array === address
+          address.map { |a| quote_address_if_necessary(charset, a) }
+        elsif address =~ /^(\S.*)\s+(<.*>)$/
+          address = $2
+          phrase = quote_if_necessary(charset, $1.gsub(/^['"](.*)['"]$/, '\1'))
+          "\"#{phrase}\" #{address}"
+        else
+          address
+        end
+      end
+
+      # Quote any of the given addresses, if they need to be.
+      def quote_any_address_if_necessary(charset, *args)
+        args.map { |v| quote_address_if_necessary(charset, v) }
+      end
+    end
+
+  end
+end

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: aiwilliams-mlist
+version: !ruby/object:Gem::Version 
+  version: 0.0.0
+platform: ruby
+authors: 
+- Adam Williams
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-26 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: A Ruby mailing list library designed to be integrated into other applications.
+email: adam@thewilliams.ws
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- README
+- VERSION.yml
+- lib/mlist
+- lib/mlist/email_server
+- lib/mlist/email_server/base.rb
+- lib/mlist/email_server/email.rb
+- lib/mlist/email_server/fake.rb
+- lib/mlist/email_server.rb
+- lib/mlist/list.rb
+- lib/mlist/mail_list.rb
+- lib/mlist/manager
+- lib/mlist/manager/database.rb
+- lib/mlist/message.rb
+- lib/mlist/server.rb
+- lib/mlist/thread.rb
+- lib/mlist/util
+- lib/mlist/util/header_sanitizer.rb
+- lib/mlist/util/quoting.rb
+- lib/mlist/util.rb
+- lib/mlist.rb
+has_rdoc: false
+homepage: http://github.com/aiwilliams/mlist
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A Ruby mailing list library designed to be integrated into other applications.
+test_files: []
+