vpopmail 1.0.0

data/README

@@ -0,0 +1,59 @@
+= VPOPMail
+
+VPOPMail is a library that helps to manipulate vpopmail (http://www.inter7.com/vpopmail), a software package to provide an easy way to manage virtual email domains.
+
+This library can be used to write email filters, spam learners, etc.
+
+= Requirements
+
+* Ruby 1.8.* (or newer).  Only tested under Linux, should be fine under any Unix.
+
+* Installed {vpopmail}[http://www.inter7.com/vpopmail] software.
+* Installed {spamassassin}[http://spamassassin.apache.org] for spam learning.
+
+= Gem requirements
+
+{RubyMail}[http://rubyforge.org/projects/rubymail] 0.17 or newer
+
+= Documentation
+
+The documentation is in RDoc format in the doc subdirectory.
+
+= Install
+
+Type the following while in the package directory:
+
+  ruby install.rb config
+  ruby install.rb setup
+  ruby install.rb install
+
+You may need special permissions to execute the last line.  If you
+want to just install RubyMail to a custom location, just copy the
+rmail subdirectory manually.
+
+= Support
+
+To reach the author of ruby-vpopmail, send mail to gildas@breizh.org.
+
+= License
+
+Copyright (c) 2006 Gildas Cherruel
+
+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,102 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+require File.join(File.dirname(__FILE__), 'lib', 'vpopmail')
+
+PKG_BUILD     = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+PKG_NAME      = 'vpopmail'
+PKG_VERSION   = VPOPMail::VERSION::STRING + PKG_BUILD
+PKG_FILE_NAME = "#{PKG_NAME}-#{PKG_VERSION}"
+
+RELEASE_NAME  = "REL #{PKG_VERSION}"
+
+RUBY_FORGE_PROJECT = "ruby-vpopmail"
+RUBY_FORGE_USER    = "gildasc"
+
+PKG_FILES = FileList[
+    "lib/**/*", "test/**/*", "examples/**/*", "doc/**/*", "[A-Z]*", "install.rb", "Rakefile"
+].exclude(/\bCVS\b|~$/)
+
+
+# Generate the RDoc documentation
+
+Rake::RDocTask.new { |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "Ruby VPOPMail -- VPOPMail interface for Ruby"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.template = "#{ENV['template']}.rb" if ENV['template']
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+}
+
+# Create compressed packages
+
+spec = Gem::Specification.new do |s|
+  s.name    = PKG_NAME
+  s.version = PKG_VERSION
+  s.summary = "Ruby VPOPMail interface"
+  s.description = %q{VPOPMail interface for Ruby. Allows to write filters, spam learners, etc. using the vpopmail software package.}
+
+  s.files  = FileList["{lib,examples}/**/*"].exclude("rdoc").to_a
+  s.files += [ "Rakefile", "install.rb", "README" ]
+  
+  s.add_dependency('rmail', '>= 0.17' + PKG_BUILD)
+
+  s.require_path = 'lib'
+  s.autorequire  = 'vpopmail'
+
+  s.has_rdoc = true
+  s.extra_rdoc_files = %w( README )
+  s.rdoc_options.concat ['--main',  'README']
+  
+  s.author = "Gildas Cherruel"
+  s.email = "gildas@breizh.org"
+  s.homepage = "http://ruby-vpopmail.rubyforge.org"
+  s.rubyforge_project = "ruby-vpopmail"
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+
+  for file_name in FileList["lib/vpopmail/**/*.rb"]
+    f = File.open(file_name)
+
+    while line = f.gets
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+    
+    total_lines     += lines
+    total_codelines += codelines
+    
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end
+
+
+# Publishing ------------------------------------------------------
+
+desc "Publish the release files to RubyForge."
+task :release => [ :package ] do
+  `rubyforge login`
+
+  for ext in %w( gem tgz zip )
+    release_command = "rubyforge add_release #{PKG_NAME} #{PKG_NAME} 'REL #{PKG_VERSION}' pkg/#{PKG_NAME}-#{PKG_VERSION}.#{ext}"
+    puts release_command
+    system(release_command)
+  end
+end

data/examples/emailcheck.rb

@@ -0,0 +1,11 @@
+require 'log4r'
+require 'vpopmail'
+
+logname = File.basename(__FILE__, '.rb')
+log = Log4r::Logger.new(logname)
+log.add(Log4r::FileOutputter.new(logname, :filename => logname + '.log', :level => Log4r::DEBUG))
+VPOPMail::logger = log
+
+log.info "Starting emailcheck"
+valid = VPOPMail::Message.validAddress?(ARGV[0], 'postmaster@breizh.org')
+puts "Address #{ARGV[0]} is " + (valid ? "valid" : "invalid")

data/examples/vlearn.rb

@@ -0,0 +1,113 @@
+#!/usr/bin/env ruby
+require 'getoptlong'
+require 'vpopmail'
+
+$CFG = {	"Junk Folder"         => "Junk E-mails",
+		"Learn SPAM Folder"   => "Learn Junk",
+		"Learn HAM Folder"    => "Learn Good",
+		"archive user"        => "postmaster",
+		"archive SPAM Folder" => "SPAM",
+		"archive HAM Folder"  => "HAM",
+	}
+
+$VERBOSE = true
+$OPTS    = GetoptLong.new(
+		["--domain",  "-d", GetoptLong::REQUIRED_ARGUMENT],
+		["--folder",  "-f", GetoptLong::REQUIRED_ARGUMENT],
+		["--ham",           GetoptLong::NO_ARGUMENT],
+		["--help",    "-h", GetoptLong::NO_ARGUMENT],
+		["--silent",  "-s", GetoptLong::NO_ARGUMENT],
+		["--spam",          GetoptLong::NO_ARGUMENT],
+		["--user",    "-u", GetoptLong::REQUIRED_ARGUMENT],
+		["--verbose", "-v", GetoptLong::NO_ARGUMENT])
+
+#------------------------------------------------------------------------------------------
+# function: Verbose {{{
+def Verbose(p_string)
+	puts p_string if $VERBOSE
+end # }}}
+
+# function: usage {{{
+def usage(p_error = nil, p_errno = 0, p_wantQuit = true)
+	puts "Usage: vlearn.rb [options] [filename]"
+	puts "Error: #{p_error}" if ! p_error.nil?
+	puts "Options:"
+	puts "  -d domain, --domain=domain Will work only on this vpopmail domain. (Default: all)"
+	puts "  -u user, --user=user       Will work only on this vpopmail user. (Default: all)"
+	puts "  --ham                      Will consider messages as good messages"
+	puts "  --spam                     Will consider messages as spam/junk messages"
+	puts "  -h, --help                 Prints this help."
+	puts "  -s, --silent               Proceed silently."
+	puts "  -v, --verbose              Proceed verbosely."
+	exit p_errno if p_wantQuit
+end # }}}
+
+# function: loadFolder {{{
+def loadFolder(p_user, p_name = nil)
+	begin
+		return VPOPMail::Folder.new(p_user, p_name)
+	rescue Errno::ENOENT => p_e
+		Verbose "User postmaster: Folder #{p_name} does not exist"
+		return nil
+	end
+end # }}}
+
+# main {{{
+domainname = nil
+foldername = nil
+username   = nil
+kind       = nil
+
+$OPTS.each {|opt, arg|
+	case opt
+		when "--domain"  then domainname = arg
+		when "--folder"  then foldername = arg
+		when "--user"    then username   = arg
+		when "--ham"     then kind       = "ham"
+		when "--spam"    then kind       = "spam"
+		when "--help"    then usage()
+		when "--silent"  then $VERBOSE = false
+		when "--verbose" then $VERBOSE = true
+	end
+}
+
+if !domainname.nil? and !username.nil? and !foldername.nil? then
+	domain = VPOPMail::Domain.FindDomains(domainname)[0]
+	Verbose "Analyzing domain #{domain.name}"
+	user   = VPOPMail::User.FindUsers(domain, username)[0]
+	Verbose "Analyzing user #{user.name}"
+	folder = VPOPMail::Folder.new(user, foldername)
+	Verbose "Analyzing folder #{folder}, size = #{folder.size}"
+	messageid = ARGV[0]
+
+	if !messageid.nil? and !messageid.empty? then
+		message = VPOPMail::Message.new(folder, messageid)
+		Verbose "Processing: #{message.id}"
+		message.markAs(kind) if !kind.nil?
+	else
+		folder.each {|message|
+			Verbose "Processing: #{message.id}"
+			message.markAs(kind) if !kind.nil?
+		}
+	end
+else
+	VPOPMail::Domain.FindDomains.each { |domain|
+		Verbose "Analyzing domain #{domain.name}"
+		archiveUser = VPOPMail::User.FindUsers(domain, $CFG["archive user"])[0]
+		archiveSPAM = loadFolder(archiveUser, $CFG["archive SPAM Folder"])
+		archiveHAM  = loadFolder(archiveUser, $CFG["archive HAM Folder"])
+
+		VPOPMail::User.FindUsers(domain).each { |user|
+			Verbose "Analyzing user #{user.name}"
+			junkFolder  = loadFolder(user, $CFG["Junk Folder"])
+			learnFolder = loadFolder(user, $CFG["Learn SPAM Folder"])
+			learnFolder.learnAs("spam", junkFolder, archiveSPAM) if !learnFolder.nil?
+
+			inboxFolder = loadFolder(user, nil)
+			learnFolder = loadFolder(user, $CFG["Learn HAM Folder"])
+			learnFolder.learnAs("ham", inboxFolder, archiveHAM) if !learnFolder.nil?
+		}
+	}
+end
+exit 0
+# }}}

data/install.rb

@@ -0,0 +1,30 @@
+require 'rbconfig'
+require 'find'
+require 'ftools'
+
+include Config
+
+# this was adapted from rdoc's install.rb by ways of Log4r
+
+$sitedir = CONFIG["sitelibdir"]
+unless $sitedir
+  version = CONFIG["MAJOR"] + "." + CONFIG["MINOR"]
+  $libdir = File.join(CONFIG["libdir"], "ruby", version)
+  $sitedir = $:.find {|x| x =~ /site_ruby/ }
+  if !$sitedir
+    $sitedir = File.join($libdir, "site_ruby")
+  elsif $sitedir !~ Regexp.quote(version)
+    $sitedir = File.join($sitedir, version)
+  end
+end
+
+# the acual gruntwork
+Dir.chdir("lib")
+
+Find.find("vpopmail", "vpopmail.rb") { |f|
+  if f[-3..-1] == ".rb"
+    File::install(f, File.join($sitedir, *f.split(/\//)), 0644, true)
+  else
+    File::makedirs(File.join($sitedir, *f.split(/\//)))
+  end
+}

data/lib/vpopmail.rb

@@ -0,0 +1,47 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: vpopmail.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'vpopmail/domain'
+require 'vpopmail/user'
+require 'vpopmail/imapdb'
+require 'vpopmail/folder'
+require 'vpopmail/message'
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+#++
+# The VPOPMail module contains all classes used to manipulate {vpopmail}[http://www.inter7.com/vpopmail] objects
+module VPOPMail
+
+	#--------------------------------------------------------------------------------------
+	# Versionning # {{{
+	module VERSION #:nodoc:
+		MAJOR   = 1
+		MINOR   = 0
+		TINY    = 0
+		BUILD   = %q$Id: vpopmail.rb 4 2006-10-07 23:18:13Z gildasc $
+		STRING  = [MAJOR, MINOR, TINY].join('.')
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# module function: logger= {{{
+	#++
+	# Assigns the Logger object to all classes of the VPOPMail module.
+	# <tt>p_logger</tt> must comply to the Logger class.
+	def VPOPMail.logger=(p_logger)
+		Domain.logger  = p_logger
+		User.logger    = p_logger
+		Folder.logger  = p_logger
+		Message.logger = p_logger
+		IMAPDB.logger  = p_logger
+	end # }}}
+end # }}}

data/lib/vpopmail/config.rb

@@ -0,0 +1,22 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: config.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+#++
+module VPOPMail
+
+# CFG contains default values for manipulating the vpopmail software package
+CFG = { "VPOP Bin"           => "/home/vpopmail/bin",
+        "SPAM Mark"          => "***SPAM*** ",
+        "SPAM Subject Field" => "X-Spam-Prev-Subject",
+        "IMAPDB"             => "courierimapuiddb",
+      }
+
+end # }}}

data/lib/vpopmail/domain.rb

@@ -0,0 +1,105 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: domain.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+require 'rmail'
+require 'rexml/document'
+require 'vpopmail/config'
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+#++
+module VPOPMail
+
+#------------------------------------------------------------------------------------------
+# class: Domain {{{
+#++
+# The Domain class represents a virtual domain in {vpopmail}[http://www.inter7.com/vpopmail]
+class Domain
+	attr_reader :name, :path
+	attr_writer :name, :path
+
+	#--------------------------------------------------------------------------------------
+	# class attribute: logger {{{
+	#++
+	@@logger = nil
+	def self.logger ;            @@logger ; end
+	def self.logger=(p_object) ; @@logger = p_object ; end
+	def logger(p_object) ;       @@logger ; end
+	def logger=(p_object) ;      @@logger = p_object ; end
+	# }}}
+
+	#----------------------------------------------------------------------------------
+	# method: initialize {{{
+	#++
+	# Creates a new Domain object
+	def initialize
+		@name = @path = ""
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# class method: FindDomains {{{
+	#++
+	# Finds all virtual domains that match the pattern <tt>p_name</tt>. If the pattern
+	# is not present, finds all virtual domains.
+	# Returns an array of Domain objects.
+	def Domain.FindDomains(p_name = nil)
+		cmdString = "#{VPOPMail::CFG['VPOP Bin']}/vdominfo -n -d"
+		if !p_name.nil? and !p_name.empty? then
+			raise ArgumentError unless p_name.kind_of?(String)
+			cmdString = cmdString + " #{p_name}"
+		end
+		cmd = IO.popen(cmdString, "w+")
+		cmd.close_write
+
+		domains = Array.new
+		domain  = Domain.new
+		getName = true
+		while line = cmd.gets do
+			line = line.gsub(/[\r\n]*$/, "")
+			next if line.empty?
+			if getName then
+				domain.name = line
+			else
+				domain.path = line
+				domains << domain
+				domain = Domain.new
+			end
+			getName = !getName
+		end
+		return domains
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: postmaster {{{
+	#++
+	# Calculates the default postmaster email address if the Domain.
+	# If <tt>p_name</tt> is present, it will be used instead of 'postmaster'
+	# Returns a RMail::Address object
+	def postmaster(p_name = 'postmaster')
+		return RMail::Address.parse("#{name}@#{@name}")[0]
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_xml {{{
+	#++
+	# Returns the REXML::Document that represents the Domain object
+	def to_xml
+		return REXML::Document.new("<Domain name=\"#{@name}\" path=\"#{@path}\" />")
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_s {{{
+	#++
+	# Returns the String representation of the Domain object
+	def to_s
+		return "Domain #{@name} stored in #{@path}"
+	end # }}}
+end # }}}
+
+end # }}}

data/lib/vpopmail/folder.rb

@@ -0,0 +1,131 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: folder.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+require 'rexml/document'
+require 'vpopmail/config'
+require 'vpopmail/domain'
+require 'vpopmail/user'
+require 'vpopmail/imapdb'
+require 'vpopmail/message'
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+#++
+module VPOPMail
+
+#------------------------------------------------------------------------------------------
+# class: Folder {{{
+#++
+# The Folder class represents a Maildir folder
+class Folder
+	attr_reader :name, :path, :curpath, :newpath, :tmppath, :imapdb, :user
+
+	#--------------------------------------------------------------------------------------
+	# class attribute: logger {{{
+	@@logger = nil
+	def self.logger ;            @@logger ; end
+	def self.logger=(p_object) ; @@logger = p_object ; end
+	def logger(p_object) ;       @@logger ; end
+	def logger=(p_object) ;      @@logger = p_object ; end
+	# }}}
+
+	#----------------------------------------------------------------------------------
+	# method: initialize {{{
+	#++
+	# Creates a new Folder object after <tt>p_name</tt> and owned by the User <tt>p_user</tt>
+	# If <tt>p_name</tt> is not given opens the Inbox.
+	#
+	# Initializes the IMAPDB Database for the given Folder and set the working directory
+	# to the <i>cur</i> Maildir folder.
+	#
+	# Raises a SystemCallError if the Maildir folder does not exist
+	def initialize(p_user, p_name = nil)
+		@user = p_user
+		@name = p_name
+		@name = "INBOX" if @name.nil? or @name.empty?
+		@path = p_user.path + File::SEPARATOR + "Maildir"
+		@path = @path + File::SEPARATOR + '.' + @name if @name !~ /inbox/i
+		@path = @path
+		@curpath = @path + File::SEPARATOR + "cur"
+		@newpath = @path + File::SEPARATOR + "new"
+		@tmppath = @path + File::SEPARATOR + "tmp"
+		@dir     = Dir.new(@curpath) # This will raise a if the path does not exist
+		@imapdb  = IMAPDB.new(self)
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: domain {{{
+	#++
+	# Gives the Domain of the User that owns the Folder
+	def domain
+		return @user.domain
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: size {{{
+	#++
+	# Gives the number of Message objects stored in the Folder
+	def size
+		return @dir.entries.size - 2 # . and .. should not be counted
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: each {{{
+	#++
+	# Apply the <i>block</i> to all Message objects stored in the Folder
+	# Returns <b>self</b>
+	def each #p_block
+		@dir.each { |entry|
+			next if entry == "."
+			next if entry == ".."
+			message = Message.new(self, entry)
+			yield(message)
+		}
+		self
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: learnAs {{{
+	#++
+	# Learns all Message objects as <tt>p_kind</tt>.
+	# Moves them to the <tt>p_properFolder</tt> Folder if present.
+	# And makes a copy of each Message to the <tt>p_archiveFolder</tt> if present.
+	# This allows to re-train the spam analyzer with a bunch of ham and spam messages later on.
+	#
+	# Returns <b>self</b>
+	def learnAs(p_kind = "spam", p_properFolder = nil, p_archiveFolder = nil)
+		raise ArgumentError unless p_kind == "spam" or p_kind == "ham"
+		self.each {|message|
+			logger.info "Processing message #{message.id}" if !@@logger.nil?
+			message.learnAs(p_kind)
+			message.copyTo(p_archiveFolder) if !p_archiveFolder.nil?
+			message.markAs(p_kind)
+			message.moveTo(p_properFolder)  if !p_properFolder.nil?
+		}
+		self
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_xml {{{
+	#++
+	# Returns the REXML::Document that represents the Folder object
+	def to_xml
+		return REXML::Document.new("<Folder name=\"#{@name}\" path=\"#{@path}\" />")
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_s {{{
+	#++
+	# Returns the String representation of the Domain object
+	def to_s
+		return "Folder #{@name}, path=\"#{@path}\""
+	end # }}}
+end # }}}
+
+end # }}}

data/lib/vpopmail/imapdb.rb

@@ -0,0 +1,154 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: imapdb.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+require 'rexml/document'
+require 'vpopmail/config'
+require 'vpopmail/domain'
+require 'vpopmail/user'
+require 'vpopmail/message'
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+#++
+module VPOPMail
+
+#------------------------------------------------------------------------------------------
+# class: IMAPDB {{{
+#++
+# The IMAPDB class is used to manipulate the status of Message object in a Folder
+class IMAPDB
+	attr_reader :name, :path
+
+	#--------------------------------------------------------------------------------------
+	# class attribute: logger {{{
+	@@logger = nil
+	def self.logger ;            @@logger ; end
+	def self.logger=(p_object) ; @@logger = p_object ; end
+	def logger(p_object) ;       @@logger ; end
+	def logger=(p_object) ;      @@logger = p_object ; end
+	# }}}
+
+	#----------------------------------------------------------------------------------
+	# method: initialize {{{
+	#++
+	# Creates a new IMAPDB object attached to the Folder <tt>p_folder</tt>
+	#
+	# Uses <b>VPOPMail::CFG["IMAPDB"]</b> as the name of the file that contains the IMAP database.
+	def initialize(p_folder)
+		raise ArgumentError unless p_folder.kind_of?(Folder)
+		@name     = VPOPMail::CFG["IMAPDB"]
+		@folder   = p_folder
+		@path     = @folder.path
+		@filename = @folder.path + File::SEPARATOR + @name
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: update {{{
+	#++
+	# Marks the Message <tt>p_message</tt> as updated in the IMAP Database.
+	def update(p_message)
+		raise ArgumentError unless p_message.kind_of?(Message)
+		lines = self.load
+		return if lines.empty?
+
+		# Search and destroy the message in the IMAPDB
+		lines.delete_if {|line| line =~ /^\d+ #{p_message.id}/}
+
+		# Add the message at the end with the highest uid
+		lines << "#{@newuid} #{p_message.id}\n"
+		@newuid = @newuid.to_i + 1
+		lines[0] = "1 #{@uidv} #{@newuid}\n"
+
+		self.save(lines)
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: add {{{
+	#++
+	# Adds the Message <tt>p_message</tt> to the IMAP Database.
+	def add(p_message)
+		raise ArgumentError unless p_message.kind_of?(Message)
+		lines = self.load
+		return if lines.empty?
+
+		# Search the message in the IMAPDB
+		lines.each {|line| return if line =~ /^\d+ #{p_message.id}/}
+
+		# Add the message at the end with the highest uid
+		lines << "#{@newuid} #{p_message.id}\n"
+		@newuid = @newuid.to_i + 1
+		lines[0] = "1 #{@uidv} #{@newuid}\n"
+
+		self.save(lines)
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: delete {{{
+	#++
+	# Deletes the Message <tt>p_message</tt> from the IMAP Database.
+	def delete(p_message)
+		raise ArgumentError unless p_message.kind_of?(Message)
+		lines = self.load
+		return if lines.empty?
+
+		# Search and destroy the message in the IMAPDB
+		deleted = lines.delete_if {|line| line =~ /^\d+ #{p_message.id}/}
+		return if deleted.empty?
+
+		self.save(lines)
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_xml {{{
+	#++
+	# Returns the REXML::Document that represents the IMAPDB object
+	def to_xml
+		return REXML::Document.new("<IMAPDB name=\"#{@name}\" path=\"#{@path}\" />")
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_s {{{
+	#++
+	# Returns the String representation of the Domain object
+	def to_s
+		return "IMAP Database @name, path=\"#{@path}\""
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: load {{{
+	#++
+	# Loads the IMAPDB in memory from its file.
+	def load
+		begin
+			lines = IO.readlines(@filename)
+		rescue Errno::ENOENT
+			logger.warning "Folder #{@folder.name}: IMAPDB does not exist, nothing to do" if !@@logger.nil?
+			return Array.new
+		end
+		if lines[0] !~ /^1 (\d+) (\d+)/ then
+			logger.error "Folder #{@folder.name}: Wrong IMAPDB version, aborting" if !@@logger.nil?
+			return Array.new
+		end
+		@uidv   = $1
+		@newuid = $2
+		logger.info "Folder #{@folder.name}: uidv=#{@uidv}, new uid=#{@newuid}" if !@@logger.nil?
+		return lines
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: save {{{
+	#++
+	# Saves the IMAPDB to its file.
+	def save(p_lines)
+		File.open(@filename, 'w') { |file| file.puts p_lines }
+		logger.info "Folder #{@folder.name}: IMAPDB saved" if !@@logger.nil?
+	end # }}}
+end # }}}
+
+end # }}}

data/lib/vpopmail/message.rb

@@ -0,0 +1,311 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: message.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+require 'rexml/document'
+require 'rmail'
+require 'net/smtp'
+require 'net/dns'
+require 'vpopmail/config'
+require 'vpopmail/domain'
+require 'vpopmail/user'
+require 'vpopmail/imapdb'
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: Net {{{
+#++
+module Net # :nodoc: all
+#------------------------------------------------------------------------------------------
+# class: SMTP {{{
+#++
+class SMTP
+	#--------------------------------------------------------------------------------------
+	# method: validAddress? {{{
+	#++
+	def validAddress?(p_address, p_local)
+		begin
+			mailfrom p_local
+			rcptto p_address
+	  		getok('RSET')
+		rescue SMTPFatalError
+			begin
+				getok('RSET')
+			rescue
+			end
+			return false
+		rescue Exception => p_e
+			STDERR.puts "Unknown Error! #{p_e}"
+			return false
+		end
+		return true
+	end # }}}
+
+end # }}}
+end # }}}
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+#++
+module VPOPMail
+
+#------------------------------------------------------------------------------------------
+# class: Message {{{
+#++
+# The Message class represents an email message stored in a Folder
+class Message
+	attr_reader :filename, :id, :path, :info, :flags
+
+	#--------------------------------------------------------------------------------------
+	# class attribute: logger {{{
+	@@logger = nil
+	def self.logger ;            @@logger ; end
+	def self.logger=(p_object) ; @@logger = p_object ; end
+	def logger(p_object) ;       @@logger ; end
+	def logger=(p_object) ;      @@logger = p_object ; end
+	# }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: initialize {{{
+	#++
+	# Creates a new Message object after stored in the Folder <tt>p_folder</tt>.
+	#
+	# <tt>p_name</tt> contains the name of the file that contains the email.
+	# <tt>p_name</tt> follows the Maildir filename formatt as described in
+	# http://cr.yp.to/proto/maildir.html
+	def initialize(p_folder, p_name)
+		# The name analysis comes from http://cr.yp.to/proto/maildir.html
+		raise ArgumentError unless p_folder.kind_of?(Folder)
+		@folder   = p_folder
+		@filename = p_name
+		@id       = p_name
+		@info     = nil
+		@flags    = nil
+		if p_name =~ /.*:(\d),([A-Z]*)$/ then
+			@info  = $1
+			@flags = $2
+			@id    = p_name.gsub(/:\d,[A-Z]*$/, '')
+		end
+		self.load
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# class method: validAddress? {{{
+	#++
+	# Tells if the RMail::Address <tt>p_address</tt> is valid or not. Uses <tt>p_local</tt>
+	# as the origin email address when querying the mail server of <tt>p_address</tt>
+	#
+	# This methods queries the DNS of the domain contains in <tt>p_address</tt> for its
+	# MX Servers. Then it will use the SMTP protocol to query the MX servers for the validity
+	# of <tt>p_address</tt>
+	def self.validAddress?(p_address, p_local)
+		p_address = RMail::Address.parse(p_address)[0] if !p_address.kind_of? RMail::Address
+		p_local   = RMail::Address.parse(p_local)[0]   if !p_local.kind_of? RMail::Address
+
+		logger.info "Checking Domain: #{p_address.domain}" if !@@logger.nil?
+		resolver = Net::DNS::Resolver.new
+		logger.debug "#{resolver.inspect}"
+		answer   = resolver.query(p_address.domain, Net::DNS::MX)
+		logger.debug "#{answer.inspect}"
+		if answer.nil? or answer.header.anCount == 0
+			logger.warn "No nameserver found for domain: #{resolver.errorstring}" if !@@logger.nil?
+			return false
+		end
+		hosts = answer.answer.sort {|x, y| x.preference <=> y.preference}
+
+		hosts.each { |host|
+			logger.info "Connecting to MX #{host.exchange}" if !@@logger.nil?
+			begin
+				Net::SMTP.start(host.exchange, 25, p_local.domain) { |smtp|
+					logger.debug "Validating #{p_address.address}" if !@@logger.nil?
+					return smtp.validAddress?(p_address.address, p_local.address)
+				}
+			rescue Errno::ETIMEDOUT => p_e
+				# That means the MX Host does not answer
+				logger.warn "timeout in querying #{host.exchange}" if !@@logger.nil?
+			rescue Exception => p_e
+				logger.error "Unknown error: #{p_e}" if !@@logger.nil?
+			end
+		}
+		return false
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: validAddress? {{{
+	#++
+	# Tells if the RMail::Address <tt>p_address</tt> is valid or not. Extracts
+	# the origin email address when querying the mail server of <tt>p_address</tt>
+	# from the current Message
+	#
+	# See Message.validAddress?
+	def validAddress?(p_address)
+		return Message.validAddress?(p_address, @folder.domain.postmaster)
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: markAs {{{
+	#++
+	# Marks the Message as <i>ham</i> or <i>spam</i>
+	#
+	# Raises an ArgumentError if <tt>p_kind</tt> contains another value.
+	def markAs(p_kind)
+		logger.info "Marking message as #{p_kind}" if !@@logger.nil?
+		field  = VPOPMail::CFG["SPAM Subject Field"]
+		header = @rmail.header
+		case p_kind
+			when /spam/i
+				if !header.field?(field) then
+					header[field] = header.subject || ''
+					header.subject = VPOPMail::CFG["SPAM Mark"] + (header.subject || '')
+					self.save
+				else
+					logger.info "Message #{@id} is already marked as SPAM" if !@@logger.nil?
+				end
+			when /ham/i
+				if header.field?(field) then
+					logger.debug "There is a #{field} field,\nSubject: #{header.subject}\nSPAM:    #{header[field]}" if !@@logger.nil?
+					header.subject = header[field]
+					header.delete(field)
+					self.save
+				else
+					logger.info "Message #{@id} is already marked as HAM" if !@@logger.nil?
+				end
+			else
+				raise ArgumentError, "Bad kind: #{p_kind}", caller
+		end
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: learnAs {{{
+	#++
+	# Learns the Message as <i>ham</i> or <i>spam</i> using
+	# {spamassassin}[http://spamassassin.apache.org]
+	def learnAs(p_kind)
+		raise ArgumentError unless p_kind == "spam" or p_kind == "ham"
+		logger.info "Learning message as #{p_kind}" if !@@logger.nil?
+		debug     = "-D bayes,learn,dns"
+		debug     = ""
+		cmdString = "/usr/bin/sa-learn --single #{debug} --username=vpopmail --#{p_kind}"
+		cmd       = IO.popen(cmdString, "w+")
+		RMail::Serialize.write(cmd, @rmail)
+		cmd.close_write
+
+		while line = cmd.gets do
+			line = line.gsub(/[\r\n]*$/, "")
+			next if line.empty?
+			logger.debug "SA-Learn: #{line}" if !@@logger.nil?
+		end
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: load {{{
+	#++
+	# Loads the Message from its file in its <tt>@rmail</tt> attribute (RMail::Message)
+	def load
+		if @filename == @id then
+			path = @folder.newpath + File::SEPARATOR + @filename
+		else
+			path   = @folder.curpath + File::SEPARATOR + @filename
+		end
+		logger.info "Loading #{path}" if !@@logger.nil?
+		begin
+			@rmail = File.open(path) { |file| RMail::Parser.read(file) }
+			stat   = File.stat(path)
+			@uid   = stat.uid
+			@gid   = stat.gid
+			logger.debug "Loaded. uid=#{@uid}, gid=#{@gid}" if !@@logger.nil?
+		rescue Errno::ENOENT
+			logger.error "Cannot load #{path}" if !@@logger.nil?
+			exit -1
+		end
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: save {{{
+	#++
+	# Saves the Message to its file, by serializing its <tt>@rmail</tt> attribute.
+	def save
+		@folder.imapdb.update(self)
+		path = @folder.newpath + File::SEPARATOR + @id
+		logger.info "Saving #{path}" if !@@logger.nil?
+		File.open(path, "w") { |file| RMail::Serialize.write(file, @rmail) }
+		File.chmod(0644, path)
+		File.chown(@uid, @gid, path)
+		File.delete(@folder.curpath + File::SEPARATOR + @filename)
+		@filename = @id
+		@info     = nil
+		@flags    = nil
+		logger.debug "Saved. new filename: #{@filename}" if !@@logger.nil?
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: copyTo {{{
+	#++
+	# Copies the Message to the Folder <tt>p_folder</tt>
+	def copyTo(p_folder)
+		logger.info "Copying to folder #{p_folder.name}" if !@@logger.nil?
+		p_folder.imapdb.add(self)
+		path = p_folder.newpath + File::SEPARATOR + @id
+		File.open(path, "w") { |file| RMail::Serialize.write(file, @rmail) }
+		File.chmod(0644, path)
+		File.chown(@uid, @gid, path)
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: deleteFrom {{{
+	#++
+	# Deletes the Message from the Folder <tt>p_folder</tt>
+	def deleteFrom(p_folder)
+		logger.info "Deleting from folder #{p_folder.name}" if !@@logger.nil?
+		p_folder.imapdb.delete(self)
+		begin
+			File.delete(p_folder.curpath + File::SEPARATOR + @filename)
+		rescue => p_e
+			begin
+				File.delete(p_folder.newpath + File::SEPARATOR + @filename)
+			rescue => p_e
+				logger.error "Problem while deleting: #{p_e}" if !@@logger.nil?
+			end
+		end
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: moveTo {{{
+	#++
+	# Moves the Message to the Folder <tt>p_folder</tt>
+	def moveTo(p_folder)
+		logger.info "Moving to folder #{p_folder.name}" if !@@logger.nil?
+		self.copyTo(p_folder)
+		self.deleteFrom(@folder)
+		logger.info "Reloading from #{p_folder.name}" if !@@logger.nil?
+		@folder = p_folder
+		self.load
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: to_xml {{{
+	#++
+	# Returns the REXML::Document that represents the Message object
+	def to_xml
+		xml  = "<Message id=\"#{@id}\""
+		xml += " info=\"#{@info}\""   if !@info.nil?
+		xml += " flags=\"#{@flags}\"" if !@flags.nil?
+		xml += " path=\"#{@path}\" />"
+		return REXML::Document.new(xml)
+	end # }}}
+
+	#--------------------------------------------------------------------------------------
+	# method: to_s {{{
+	#++
+	# Returns the String representation of the Message object
+	def to_s
+		return "Message #{@id}, info=#{@info}, flags=#{@flags}, path=\"#{@path}\""
+	end # }}}
+end # }}}
+
+end # }}}

data/lib/vpopmail/user.rb

@@ -0,0 +1,89 @@
+#--
+# Copyright (c) 2006 Gildas Cherruel
+# Read COPYRIGHT in the root of VPOPMail library for copyright info
+# Creator: gildasc@rubyforg.org
+# Author:  $Author: gildasc $
+# Version: $Id: user.rb 4 2006-10-07 23:18:13Z gildasc $
+#++
+
+require 'vpopmail/config'
+require 'vpopmail/domain'
+
+#------------------------------------------------------------------------------------------
+#------------------------------------------------------------------------------------------
+# module: VPOPMail {{{
+module VPOPMail
+
+#------------------------------------------------------------------------------------------
+# class: User {{{
+class User
+	attr_reader :name, :path, :domain
+	attr_writer :name, :path
+
+	#--------------------------------------------------------------------------------------
+	# class attribute: logger {{{
+	@@logger = nil
+	def self.logger ;            @@logger ; end
+	def self.logger=(p_object) ; @@logger = p_object ; end
+	def logger(p_object) ;       @@logger ; end
+	def logger=(p_object) ;      @@logger = p_object ; end
+	# }}}
+
+	#----------------------------------------------------------------------------------
+	# method: initialize {{{
+	def initialize(p_domain)
+		@name   = @path = ""
+		@domain = p_domain
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# class method: FindUsers {{{
+	def self.FindUsers(p_domain, p_name = nil)
+		raise ArgumentError unless p_domain.kind_of?(Domain)
+		cmdString = "#{VPOPMail::CFG['VPOP Bin']}/vuserinfo -n -d"
+		if p_name.nil? or p_name.empty? then
+			cmdString = cmdString + " -D #{p_domain.name}"
+		else
+			raise ArgumentError unless p_name.kind_of?(String)
+			cmdString = cmdString + " #{p_name}@#{p_domain.name}"
+		end
+		cmd = IO.popen(cmdString, "w+")
+		cmd.close_write
+
+		users = Array.new
+		user  = User.new(p_domain)
+		getName = true
+		while line = cmd.gets do
+			line = line.gsub(/[\r\n]*$/, "")
+			next if line.empty?
+			if getName then
+				user.name = line
+			else
+				user.path = line
+				users << user
+				user = User.new(p_domain)
+			end
+			getName = !getName
+		end
+		return users
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_xml {{{
+	def to_xml
+		return "<User name=\"#{@name}\" path=\"#{@path}\" />"
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# method: to_s {{{
+	def to_s
+		return to_xml
+	end # }}}
+
+	#----------------------------------------------------------------------------------
+	# Access Control {{{
+	public :name, :path, :name=, :path=
+	# }}}
+end # }}}
+
+end # }}}

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: vpopmail
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+date: 2006-10-08
+summary: Ruby VPOPMail interface
+require_paths: 
+  - lib
+email: gildas@breizh.org
+homepage: http://ruby-vpopmail.rubyforge.org
+rubyforge_project: ruby-vpopmail
+description: "VPOPMail interface for Ruby. Allows to write filters, spam learners, etc. using
+  the vpopmail software package."
+autorequire: vpopmail
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+  version: 
+platform: ruby
+authors: 
+  - Gildas Cherruel
+files: 
+  - lib/vpopmail
+  - lib/vpopmail.rb
+  - lib/vpopmail/config.rb
+  - lib/vpopmail/domain.rb
+  - lib/vpopmail/folder.rb
+  - lib/vpopmail/imapdb.rb
+  - lib/vpopmail/message.rb
+  - lib/vpopmail/user.rb
+  - examples/emailcheck.rb
+  - examples/vlearn.rb
+  - Rakefile
+  - install.rb
+  - README
+test_files: []
+rdoc_options: 
+  - "--main"
+  - README
+extra_rdoc_files: 
+  - README
+executables: []
+extensions: []
+requirements: []
+dependencies: 
+  - !ruby/object:Gem::Dependency 
+    name: rmail
+    version_requirement: 
+    version_requirements: !ruby/object:Gem::Version::Requirement 
+      requirements: 
+        - 
+          - ">="
+          - !ruby/object:Gem::Version 
+            version: "0.17"
+      version: