nilclass-maildir 0.4.1

data/.gitignore

@@ -0,0 +1,3 @@
+pkg/*
+benchmarks/scratch.rb
+.DS_Store

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Aaron Suggs
+
+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/README.rdoc

@@ -0,0 +1,113 @@
+= Maildir
+
+A ruby library for reading and writing messages in the maildir format.
+
+== What's so great about the maildir format
+
+See http://cr.yp.to/proto/maildir.html and http://en.wikipedia.org/wiki/Maildir
+
+As Daniel J. Berstein puts it: "Two words: no locks." The maildir format allows multiple processes to read and write arbitrary messages without file locks.
+
+New messages are initially written to a "tmp" directory with an automatically-generated unique filename. After the message is written, it's moved to the "new" directory where other processes may read it.
+
+While the maildir format was created for email, it works well for arbitrary data. This library can read & write email messages or arbitrary data. See Pluggable serializers for more.
+
+== Install
+
+ sudo gem install maildir
+
+== Usage
+
+Create a maildir in /home/aaron/mail
+
+  maildir = Maildir.new("/home/aaron/mail") # creates tmp, new, and cur dirs
+  # call Maildir.new("/home/aaron/mail", false) to skip directory creation.
+
+Add a new message. This creates a new file with the contents "Hello World!"; returns the path fragment to the file. Messages are written to the tmp dir then moved to new.
+
+  message = maildir.add("Hello World!")
+
+List new messages
+
+  maildir.list(:new) # => [message]
+
+Move the message from "new" to "cur" to indicate that some process has retrieved the message.
+
+  message.process
+
+Indeed, the message is in cur, not new.
+
+  maildir.list(:new) # => []
+  maildir.list(:cur) # => [message]
+
+Add some flags to the message to indicate state. See "What can I put in info" at http://cr.yp.to/proto/maildir.html for flag conventions.
+
+  message.add_flag("S") # Mark the message as "seen"
+  message.add_flag("F") # Mark the message as "flagged"
+  message.remove_flag("F") # unflag the message
+  message.add_flag("T") # Mark the message as "trashed"
+
+Get a key to uniquely identify the message
+
+  key = message.key
+
+Load the contents of the message
+
+  data = message.data
+
+Find the message based using the key
+
+  message_copy = maildir.get(key)
+  message == message_copy # => true
+
+Delete the message from disk
+
+  message.destroy # => returns the frozen message
+  maildir.list(:cur) # => []
+
+== Pluggable serializers
+
+By default, message data are written and read from disk as a string. It's often desirable to process the string into a useful object. Maildir supports configurable serializers to convert message data into a useful object.
+
+The following serializers are included:
+
+* Maildir::Serializer::Base (the default)
+* Maildir::Serializer::Mail
+* Maildir::Serializer::Marshal
+* Maildir::Serializer::JSON
+* Maildir::Serializer::YAML
+
+Maildir::Serializer::Base simply reads and writes strings to disk.
+
+  Maildir::Message.serializer # => Maildir::Serializer::Base.new (by default)
+  message = maildir.add("Hello World!") # writes "Hello World!" to disk
+  message.data # => "Hello World!"
+
+The Mail serializer takes a ruby Mail object (http://github.com/mikel/mail) and writes RFC2822 email messages.
+
+  require 'maildir/serializer/mail'
+  Maildir::Message.serializer = Maildir::Serializer::Mail.new
+  mail = Mail.new(...)
+  message = maildir.add(mail) # writes an RFC2822 message to disk
+  message.data == mail # => true; data is parsed as a Mail object
+
+The Marshal, JSON, and YAML serializers work similarly. E.g.:
+
+  require 'maildir/serializer/json'
+  Maildir::Message.serializer = Maildir::Serializer::JSON.new
+  my_data = {"foo" => nil, "my_array" => [1,2,3]}
+  message = maildir.add(my_data) # writes {"foo":null,"my_array":[1,2,3]}
+  message.data == my_data # => true
+
+It's trivial to create a custom serializer. Implement the following two methods:
+
+  load(path)
+  dump(data, path)
+
+== Credits
+
+niklas | brueckenschlaeger, http://github.com/nilclass added subdir & courierimapkeywords support
+
+== Copyright
+
+Copyright (c) 2010 Aaron Suggs. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,32 @@
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/test*.rb']
+  t.verbose = true
+end
+
+task :default => :test
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "nilclass-maildir"
+    gemspec.summary = "Read & write messages in the maildir format"
+    gemspec.description = "A ruby library for reading and writing arbitrary messages in DJB's maildir format"
+    gemspec.email = "aaron@ktheory.com"
+    gemspec.homepage = "http://github.com/ktheory/maildir"
+    gemspec.authors = ["Aaron Suggs", "Niklas E. Cathor"]
+    gemspec.add_development_dependency "shoulda", ">= 0"
+    gemspec.add_development_dependency "mail", ">= 0"
+    gemspec.add_development_dependency "json", ">= 0"
+    gemspec.add_development_dependency "ktheory-fakefs", ">= 0"
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler"
+end
+
+desc "Run benchmarks"
+task :bench do
+  load File.join(File.dirname(__FILE__), "benchmarks", "runner")
+end

data/VERSION

@@ -0,0 +1 @@
+0.4.1

data/benchmarks/runner

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+$:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+require 'maildir'
+require 'benchmark'
+
+maildir_path = ENV['MAILDIR'] || "./tmp"
+maildir = Maildir.new(maildir_path)
+
+n = 300
+message = "Write #{n} messages:"
+tms = Benchmark.bmbm(message.size) do |x|
+   x.report(message) { n.times { maildir.add("") } }
+end
+
+puts "#{n/tms.first.real} messages per second"
+
+
+message = "List new:"
+tms = Benchmark.bm(message.size) do |x|
+  x.report(message) { n.times { maildir.list_keys(:new)} }
+end
+
+# require 'ruby-prof'
+# result = RubyProf.profile do
+#   n.times { maildir.list_keys(:new) }
+# end
+# 
+# # Print a graph profile to text
+# printer = RubyProf::GraphPrinter.new(result)
+# printer.print(STDOUT, 0)

data/lib/maildir.rb

@@ -0,0 +1,115 @@
+require 'fileutils' # For create_directories
+class Maildir
+
+  SUBDIRS = [:tmp, :new, :cur].freeze
+  READABLE_DIRS = SUBDIRS.reject{|s| :tmp == s}.freeze
+
+  include Comparable
+
+  attr_reader :path
+
+  # Create a new maildir at +path+. If +create+ is true, will ensure that the
+  # required subdirectories exist.
+  def initialize(path, create = true)
+    @path = File.expand_path(path)
+    @path = File.join(@path, '/') # Ensure path has a trailing slash
+    @path_regexp = /^#{Regexp.quote(@path)}/ # For parsing directory listings
+    create_directories if create
+  end
+
+  # Compare maildirs by their paths.
+  # If maildir is a different class, return nil.
+  # Otherwise, return 1, 0, or -1.
+  def <=>(maildir)
+    # Return nil if comparing different classes
+    return nil unless self.class === maildir
+
+    self.path <=> maildir.path
+  end
+
+  # Friendly inspect method
+  def inspect
+    "#<#{self.class} path=#{@path}>"
+  end
+
+  # define methods tmp_path, new_path, & cur_path
+  SUBDIRS.each do |subdir|
+    define_method "#{subdir}_path" do
+      File.join(path, subdir.to_s)
+    end
+  end
+
+  # Ensure subdirectories exist. This can safely be called multiple times, but
+  # must hit the disk. Avoid calling this if you're certain the directories
+  # exist.
+  def create_directories
+    SUBDIRS.each do |subdir|
+      subdir_path = File.join(path, subdir.to_s)
+      FileUtils.mkdir_p(subdir_path)
+    end
+  end
+
+  # Returns an arry of messages from :new or :cur directory, sorted by key.
+  # If options[:limit] is specified, returns only so many keys.
+  #
+  # E.g.
+  #  maildir.list(:new) # => all new messages
+  #  maildir.list(:cur, :limit => 10) # => 10 oldest messages in cur
+  def list(dir, options = {})
+    unless SUBDIRS.include? dir.to_sym
+      raise ArgumentError, "dir must be :new, :cur, or :tmp"
+    end
+
+    keys = get_dir_listing(dir)
+
+    # Sort the keys (chronological order)
+    # TODO: make sorting configurable
+    keys.sort!
+
+    # Apply the limit after sorting
+    if limit = options[:limit]
+      keys = keys[0,limit]
+    end
+
+    # Map keys to message objects
+    keys.map{|key| get(key)}
+  end
+
+  # Writes data object out as a new message. Returns a Maildir::Message. See
+  # Maildir::Message.create for more.
+  def add(data)
+    Maildir::Message.create(self, data)
+  end
+
+  # Returns a message object for key
+  def get(key)
+    Maildir::Message.new(self, key)
+  end
+
+  # Deletes the message for key by calling destroy() on the message.
+  def delete(key)
+    get(key).destroy
+  end
+
+  # Finds messages in the tmp folder that have not been modified since
+  # +time+. +time+ defaults to 36 hours ago.
+  def get_stale_tmp(time = Time.now - 129600)
+    list(:tmp).select do |message|
+      (mtime = message.mtime) && mtime < time
+    end
+  end
+
+  protected
+  # Returns an array of keys in dir
+  def get_dir_listing(dir)
+    search_path = File.join(self.path, dir.to_s, '*')
+    keys = Dir.glob(search_path)
+    #  Remove the maildir's path from the keys
+    keys.each do |key|
+      key.sub!(@path_regexp, "")
+    end
+  end
+end
+require 'maildir/unique_name'
+require 'maildir/serializer/base'
+require 'maildir/message'

data/lib/maildir/keywords.rb

@@ -0,0 +1,111 @@
+# implements IMAP Keywords as used by the Courier Mail Server
+# see http://www.courier-mta.org/imap/README.imapkeywords.html for details
+
+require 'ftools'
+require 'maildir'
+module Maildir::Keywords
+  def self.included(base)
+    Maildir::Message.send(:include, MessageExtension)
+  end
+  
+  def keyword_dir
+    @keyword_dir ||= File.join(path, 'courierimapkeywords')
+    Dir.mkdir(@keyword_dir) unless File.directory?(@keyword_dir)
+    return @keyword_dir
+  end
+
+  # process contents of courierimapkeywords/ directory as described in README.imapkeywords
+  def read_keywords
+    messages = (list(:cur) + list(:new)).inject({}) { |m, msg| m[msg.unique_name] = msg ; m }
+    t = Time.now.to_i / 300
+    keywords = []
+    state = :head
+    # process :list
+    list_file = File.join(keyword_dir, ':list')
+    File.open(list_file).each_line do |line|
+      line.strip!
+      if state == :head
+        if line.empty?
+          state = :messages
+          next
+        end
+        keywords << line
+      else
+        key, ids = line.split(':')
+        if msg = messages[key]
+          msg.set_keywords(ids.split(/\s/).map {|id| keywords[id.to_i - 1] })
+        end
+      end
+    end if File.exist?(list_file)
+    # collect keyword files
+    keyword_files = (Dir.entries(keyword_dir) - %w(. .. :list)).inject({}) do |keyword_files, file|
+      if file =~ /^\.(\d+)\.(.*)$/
+        n = $1
+        key = $2
+      else
+        n = t + 1
+        key = file
+        File.move(File.join(keyword_dir, file), File.join(keyword_dir, ".#{n}.#{key}"))
+      end
+      if msg = messages[key]
+        (keyword_files[key] ||= []) << [n, key]
+      else # message doesn't exist
+        fname = File.join(keyword_dir, file)
+        if File.stat(fname).ctime < (Time.now - (15 * 60))
+          File.unlink(fname)
+        end
+      end
+      next(keyword_files)
+    end
+    # process keyword files
+    keyword_files.each_pair do |key, files|
+      files.sort! { |a, b| a[0] <=> b[0] }
+      files[0..-2].each { |f| File.unlink(File.join(keyword_dir, ".#{f.join('.')}")) } if files.last[0] < t
+      msg = messages[key]
+      file = (File.exist?(File.join(keyword_dir, files.last[1])) ? files.last[1] : ".#{files.last.join('.')}")
+      current_keywords = File.read(File.join(keyword_dir, file)).split(/\s+/)
+      msg.set_keywords(current_keywords)
+      if (add = (current_keywords - keywords)).any?
+        keywords += add
+      end
+    end
+    # rebuild :list
+    @keywords = {}
+    tmp_file = File.join(path, 'tmp', ':list')
+    File.open(tmp_file, 'w') { |f|
+      f.write(keywords.join("\n")+"\n\n")
+      messages.each_pair do |key, msg|
+        next unless msg.keywords
+        f.puts([key, msg.keywords.map{|kw| keywords.index(kw) + 1 }.sort.join(' ')].join(':'))
+        @keywords[key] = msg.keywords
+      end
+    }
+    File.move(tmp_file, list_file)
+  end
+
+  def keywords(key)
+    read_keywords unless @keywords
+    @keywords[key] || []
+  end
+
+  module MessageExtension
+    def keywords
+      return @keywords if @keywords
+      @maildir.keywords(unique_name)
+    end
+
+    # sets given keywords on the message.
+    def keywords=(list)
+      tmp_fname = File.join(@maildir.path, 'tmp', unique_name)
+      File.open(tmp_fname, 'w') { |f| f.write(list.join("\n")) }
+      File.move(tmp_fname, File.join(@maildir.keyword_dir, unique_name))
+    end
+
+    # sets @keywords to the given list
+    def set_keywords(list)
+      @keywords = list
+    end
+  end
+end
+
+Maildir.send(:include, Maildir::Keywords)

data/lib/maildir/message.rb

@@ -0,0 +1,241 @@
+class Maildir::Message
+  # COLON seperates the unique name from the info
+  COLON = ':'
+  # The default info, to which flags are appended
+  INFO = "2,"
+
+  include Comparable
+
+  # Create a new message in maildir with data.
+  # The message is first written to the tmp dir, then moved to new. This is
+  # a shortcut for:
+  #   message = Maildir::Message.new(maildir)
+  #   message.write(data)
+  def self.create(maildir, data)
+    message = self.new(maildir)
+    message.write(data)
+    message
+  end
+
+  # The serializer processes data before it is written to disk and after
+  # reading from disk.
+  # Default serializer
+  @@serializer = Maildir::Serializer::Base.new
+
+  # Get the serializer
+  def self.serializer
+    @@serializer
+  end
+
+  # Set the serializer
+  def self.serializer=(serializer)
+    @@serializer = serializer
+  end
+
+  attr_reader :dir, :unique_name, :info
+
+  # Create a new, unwritten message or instantiate an existing message.
+  # If key is nil, create a new message:
+  #   Message.new(maildir) # => a new, unwritten message
+  #
+  # If +key+ is not nil, instantiate a message object for the message at
+  # +key+.
+  #   Message.new(maildir, key) # => an existing message
+  def initialize(maildir, key=nil)
+    @maildir = maildir
+    if key.nil?
+      @dir = :tmp
+      @unique_name = Maildir::UniqueName.create
+    else
+      parse_key(key)
+    end
+
+    unless Maildir::SUBDIRS.include? dir
+      raise ArgumentError, "State must be in #{Maildir::SUBDIRS.inspect}"
+    end
+  end
+
+  # Compares messages by their paths.
+  # If message is a different class, return nil.
+  # Otherwise, return 1, 0, or -1.
+  def <=>(message)
+    # Return nil if comparing different classes
+    return nil unless self.class === message
+
+    self.path <=> message.path
+  end
+
+  # Friendly inspect method
+  def inspect
+    "#<#{self.class} key=#{key} maildir=#{@maildir.inspect}>"
+  end
+
+  # Returns the class' serializer
+  def serializer
+    @@serializer
+  end
+
+  # Writes data to disk. Can only be called on messages instantiated without
+  # a key (which haven't been written to disk). After successfully writing
+  # to disk, rename the message to the new dir
+  #
+  # Returns the message's key
+  def write(data)
+    raise "Can only write to messages in tmp" unless :tmp == @dir
+
+    # Write out contents to tmp
+    serializer.dump(data, path)
+
+    rename(:new)
+  end
+
+  # Move a message from new to cur, add info.
+  # Returns the message's key
+  def process
+    rename(:cur, INFO)
+  end
+
+  # Set info on a message.
+  # Returns the message's key if successful, false otherwise.
+  def info=(info)
+    raise "Can only set info on cur messages" unless :cur == @dir
+    rename(:cur, info)
+  end
+
+  FLAG_NAMES = {
+    :passed => 'P',
+    :replied => 'R',
+    :seen => 'S',
+    :trashed => 'T',
+    :draft => 'D',
+    :flagged => 'F'
+  }
+
+  FLAG_NAMES.each_pair do |key, value|
+    define_method("#{key}?".to_sym) do
+      flags.include?(value)
+    end
+    define_method("#{key}!".to_sym) do
+      add_flag(value)
+    end
+  end
+
+  # Returns an array of single letter flags applied to the message
+  def flags
+    @info.sub(INFO,'').split('')
+  end
+
+  # Sets the flags on a message.
+  # Returns the message's key if successful, false otherwise.
+  def flags=(*flags)
+    self.info = INFO + sort_flags(flags.flatten.join(''))
+  end
+
+  # Adds a flag to a message.
+  # Returns the message's key if successful, false otherwise.
+  def add_flag(flag)
+    self.flags = (flags << flag.upcase)
+  end
+
+  # Removes a flag from a message.
+  # Returns the message's key if successful, false otherwise.
+  def remove_flag(flag)
+    self.flags = flags.delete_if{|f| f == flag.upcase}
+  end
+
+  # Returns the filename of the message
+  def filename
+    [unique_name, info].compact.join(COLON)
+  end
+
+  # Returns the key to identify the message
+  def key
+    File.join(dir.to_s, filename)
+  end
+
+  # Returns the full path to the message
+  def path
+    File.join(@maildir.path, key)
+  end
+
+  # Returns the message's data from disk.
+  # If the path doesn't exist, freeze's the object and raises Errno:ENOENT
+  def data
+    guard(true) { serializer.load(path) }
+  end
+
+  # Updates the modification and access time. Returns 1 if successful, false
+  # otherwise.
+  def utime(atime, mtime)
+    guard { File.utime(atime, mtime, path) }
+  end
+
+  # Returns the message's atime, or false if the file doesn't exist.
+  def atime
+    guard { File.atime(path) }
+  end
+
+  # Returns the message's mtime, or false if the file doesn't exist.
+  def mtime
+    guard { File.mtime(path) }
+  end
+
+  # Deletes the message path and freezes the message object
+  def destroy
+    guard { File.delete(path) }
+    freeze
+  end
+
+  protected
+
+  # Guard access to the file system by rescuing Errno::ENOENT, which happens
+  # if the file is missing. When +blocks+ fails and +reraise+ is false, returns
+  # false, otherwise reraises Errno::ENOENT
+  def guard(reraise = false, &block)
+    begin
+      yield
+    rescue Errno::ENOENT
+      if @old_key
+        # Restore ourselves to the old state
+        parse_key(@old_key)
+      end
+
+      # Don't allow further modifications
+      freeze
+
+      reraise ? raise : false
+    end
+  end
+
+  # Sets dir, unique_name, and info based on the key
+  def parse_key(key)
+    @dir, filename = key.split(File::SEPARATOR)
+    @dir = @dir.to_sym
+    @unique_name, @info = filename.split(COLON)
+  end
+
+  # Ensure the flags are uppercase and sorted
+  def sort_flags(flags)
+    flags.split('').map{|f| f.upcase}.sort!.uniq.join('')
+  end
+
+  def old_path
+    File.join(@maildir.path, @old_key)
+  end
+
+  # Renames the message. Returns the new key if successful, false otherwise.
+  def rename(new_dir, new_info=nil)
+    # Save the old key so we can revert to the old state
+    @old_key = key
+
+    # Set the new state
+    @dir = new_dir
+    @info = new_info if new_info
+
+    guard do
+      File.rename(old_path, path) unless old_path == path
+      @old_key = nil # So guard() doesn't reset to a bad state
+      return key
+    end
+  end
+end