message_dir 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,10 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in message.gemspec
+gemspec
+
+gem "simple_uuid"
+
+group :development do
+  gem "rspec"
+end

data/README.rdoc

@@ -0,0 +1,64 @@
+= Message dir
+
+A directory, with messages. Like your Maildir/
+
+Meant to be used to safely store incoming messages from any slow connection
+
+== Message dir DSL
+
+  # create
+  dir = MessageDir.new("/path/to/store")
+  msg = dir.new do |fh|
+    fh.puts info_from_slow_connection
+  end
+
+  # move a message to cur/
+  dir.cur(msg)
+  msg.cur!
+
+  # get a list of all messages
+  dir.messages
+
+  # get a list of all messages in new/
+  dir.messages(:new)
+
+  # or cur
+  dir.messages(:cur)
+
+  # work on a message (moves it to tmp/ for the duration of a block)
+  dir.process(msg, File::WRONLY|File::APPEND) do |fh|
+    fh.puts more_info
+  end
+
+  msg.process(File::WRONLY|File::TRUNC) do |fh|
+    fh.puts new_contents
+  end
+
+  # remove a message
+  msg = dir.messages(:new).first
+  dir.rm(msg) # => raise exception, we dont like to remove 'new' messages
+
+  msg = dir.msgs(:cur).first
+  msg.rm!
+
+  # lock a message
+  msg.lock! do
+    # something with the locked message
+  end
+  msg.locked? # => false
+
+  dir.lock(msg) do
+  end
+
+== Message acts as file
+
+A message is not an implementation of IO or File but it acts in the same way.
+Use that to your advantage.
+
+== Message safety
+
+A lot is done to ensure the safe handling of messages
+
+* Messages are created and processed in tmp/
+* A message fh is always opened with File::SYNC - slow but trustworthy
+* Locks are carried over processes (and crashes) using .lock files

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/lib/message_dir/message.rb

@@ -0,0 +1,131 @@
+class MessageDir
+  class Message
+    def initialize(master, path, uuid)
+      @master = master
+      @path   = path
+      @uuid   = uuid
+      @io     = nil
+
+      self.create if !File.exists?(self.path)
+      @locked = File.exists?(self.lock_file)
+      open
+    end
+
+    def self.load(master, path)
+      self.new(master, File.dirname(path), SimpleUUID::UUID.new(File.basename(path)))
+    end
+
+    def path
+      File.join(@path, @uuid.to_guid)
+    end
+
+    def guid
+      @uuid.to_guid
+    end
+
+    def spot
+      File.basename(@path).to_sym
+    end
+
+    def create
+      open(File::CREAT|File::WRONLY) do |f|
+        # write 1 byte and truncate to force existance of the file
+        f.syswrite("i")
+        f.truncate(0)
+      end
+    end
+
+    def process(mode=File::RDONLY, &block)
+      @master.process(self, mode, &block)
+    end
+
+    def open(mode=File::RDONLY, &block)
+      close
+
+      # make sure them files are synced
+      mode |= File::SYNC unless mode & File::SYNC == File::SYNC
+
+      @io = File.open(self.path, mode, &block)
+    end
+
+    def fh
+      @io
+    end
+
+    def move(path)
+      raise "Can't move a locked file" if locked?
+
+      close
+      FileUtils.mv(self.path, File.join(path, self.guid))
+      @path = path
+      open
+    end
+
+    def rm
+      @master.rm(self)
+    end
+
+    def close
+      @io.close unless closed?
+    rescue
+      true
+    end
+
+    def closed?
+      @io.closed?
+    rescue
+      return true
+    end
+
+    def cur!
+      @master.cur(self)
+    end
+
+    def ==(other)
+      other.path == self.path && self.guid == other.guid
+    end
+
+    def locked?
+      @locked == true ? true : false || File.exists?(lock_file)
+    end
+
+    def lock_file
+      "#{path}.lock"
+    end
+
+    def lock
+      return if locked?
+
+      File.open(lock_file, File::CREAT|File::WRONLY) do |lf|
+        res = lf.flock(File::LOCK_EX|File::LOCK_NB)
+        raise "Could not obtain a lock on the lock file" if res == false
+        lf.flock(File::LOCK_UN)
+      end
+
+      if block_given?
+        yield
+        unlock
+      else
+        @locked = true
+      end
+    end
+    alias_method :lock!, :lock
+
+    def unlock
+      File.open(lock_file, File::CREAT|File::WRONLY) do |lf|
+        res = lf.flock(File::LOCK_EX|File::LOCK_NB)
+        raise "Could not obtain a lock on the lock file" if res == false
+        lf.flock(File::LOCK_UN)
+        File.unlink(lock_file)
+      end
+      @locked = false
+    end
+
+    def method_missing(method, *args, &block)
+      super
+    rescue NameError, NoMethodError => e
+      @io.send(method, *args, &block)
+    end
+
+  end
+end

data/lib/message_dir/version.rb

@@ -0,0 +1,3 @@
+class MessageDir
+  VERSION = "0.0.1"
+end

data/lib/message_dir.rb

@@ -0,0 +1,110 @@
+require "message_dir/version"
+require "message_dir/message"
+require 'simple_uuid'
+require 'fileutils'
+
+class MessageDir
+  SPOTS = %w(tmp new cur)
+
+  attr_reader :path
+
+  def initialize(path)
+    @path = MessageDir::Path.new(path)
+
+    create_tree
+  end
+
+  def create_tree
+    SPOTS.each do |spot|
+      FileUtils.mkdir_p @path.send(spot)
+    end
+  end
+
+  def new(&block)
+    uuid = SimpleUUID::UUID.new
+    msg  = Message.new(self, path.new, uuid)
+
+    if block_given?
+      begin
+        msg.move(path.tmp)
+
+        msg.open(File::TRUNC|File::WRONLY) do |fh|
+          yield fh
+        end
+
+        msg.move(path.new)
+      rescue Exception => ex
+        # silently ignore errors
+      ensure
+        # make sure the message is written
+        msg.close
+      end
+    end
+
+    msg.open(File::RDONLY)
+    msg.seek(0,0)
+
+    return msg
+  end
+
+  def cur(msg)
+    return if msg.spot == :cur
+    msg.move(path.cur)
+  end
+
+  def messages(where=nil)
+    spots = where.nil? ? SPOTS : [ where ]
+
+    # find all the wanted paths
+    paths = spots.collect do |spot|
+      Dir[File.join(path.send(spot), '*')].select do |path|
+        path !~ /\.lock$/ && File.file?(path)
+      end
+    end.flatten
+
+    # load all the wanted messages
+    paths.collect do |path|
+      Message.load(self, path)
+    end
+  end
+  alias_method :msgs, :messages
+
+  def message(uuid)
+    uuid = uuid.to_guid if uuid.is_a? SimpleUUID::UUID
+    messages.select { |msg| msg.guid == uuid }.first
+  end
+
+  def process(msg, mode=File::RDONLY, &block)
+    raise "No block given" if !block_given?
+
+    # move to tmp and open with block for the given mode
+    before = msg.spot
+    msg.move(path.tmp) unless before == :tmp
+    msg.lock do
+      msg.open(mode, &block)
+    end
+
+    # move back re-open with default mode
+    msg.move(path.send(before)) unless before == :tmp
+    msg.open
+  end
+
+  def rm(msg)
+    return false if msg.locked?
+    File.unlink(msg.path) == 1 ? true : false
+  end
+
+  class Path
+    def initialize(root)
+      @root = root
+    end
+
+    def method_missing(method, *args, &block)
+      super
+    rescue NoMethodError => e
+      if [ :new, :cur, :tmp ].include?(method)
+        return File.join(@root, method.to_s)
+      end
+    end
+  end
+end

data/message_dir.gemspec

@@ -0,0 +1,22 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "message_dir/version"
+
+Gem::Specification.new do |s|
+  s.name        = "message_dir"
+  s.version     = MessageDir::VERSION
+  s.authors     = ["Hartog C. de Mik"]
+  s.email       = ["hartog.de.mik@gmail.com"]
+  s.homepage    = "https://github.com/coffeeaddict/message_dir"
+  s.summary     = %q{Maildir like messages}
+  s.description = %q{Handle slow network messages with care}
+
+  s.rubyforge_project = "message_dir"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency(%q<simple_uuid>, ['~> 0.2'])
+end

data/spec/objects/message_dir_spec.rb

@@ -0,0 +1,301 @@
+require 'spec_helper'
+require 'tmpdir'
+
+describe MessageDir do
+  before :each do
+    @path = Dir.mktmpdir(nil, '/tmp')
+  end
+
+  after :each do
+    FileUtils.remove_entry_secure @path
+  end
+
+  it "should create a tree structure at a designated directory" do
+    expect {
+      MessageDir.new(@path)
+    }.to change {
+      %w(tmp new cur).collect do |spot|
+        File.directory?(File.join(@path, spot))
+      end
+    }
+  end
+
+  subject { MessageDir.new(@path) }
+
+  it "should create a new message" do
+    msg = subject.new
+    File.exists?(msg.path).should == true
+    msg.path.should =~ Regexp.new(subject.path.new)
+  end
+
+  it "should provide new messages open for reading" do
+    msg = subject.new
+
+    msg.size.should == 0
+
+    expect { msg.syswrite("failure") }.to raise_error(IOError)
+  end
+
+  it "should provide new messages in block style" do
+    msg = subject.new do |fh|
+      fh.puts "I is a message"
+    end
+
+    msg.path.should =~ Regexp.new(subject.path.new)
+
+    msg.pos.should == 0
+
+    expect { msg.syswrite("failure") }.to raise_error(IOError)
+
+    msg.read.should == "I is a message\n"
+  end
+
+  it "should handle exceptions when creating messages" do
+    expect {
+      subject.new do |fh|
+        raise "an error"
+      end
+    }.to_not raise_error
+
+    msg = subject.new do |fh|
+      fh.puts "some info"
+      raise
+    end
+
+    msg.should_not be_nil
+    msg.read.should == "some info\n"
+  end
+
+  it "should place a new message in tmp during creation" do
+    msg = subject.new do |fh|
+      fh.puts "I am not in new"
+      raise
+    end
+
+    msg.path.should =~ Regexp.new(subject.path.tmp)
+  end
+
+  it "should move a message to cur" do
+    msg = subject.new do |fh|
+      fh.puts "I am now in cur"
+    end
+
+    msg.read.should == "I am now in cur\n"
+
+    subject.cur(msg)
+
+    msg.should_not be_closed
+    msg.path.should =~ Regexp.new(subject.path.cur)
+
+    msg.read.should == "I am now in cur\n"
+  end
+
+  it "should move a message to cur over the message" do
+    msg = subject.new do |fh|
+      fh.puts "i am to be curred"
+    end
+
+    msg.cur!
+
+    msg.should_not be_closed
+    msg.path.should =~ Regexp.new(subject.path.cur)
+    msg.read.should == "i am to be curred\n"
+  end
+
+  describe "listing messages" do
+    it "should list no messages when empty" do
+      subject.messages
+      subject.messages.should be_empty
+    end
+
+    it "should list all messages" do
+      3.times do |i|
+        msg = subject.new do |fh|
+          fh.puts "i am message #{i}"
+        end
+      end
+
+      subject.messages.count.should == 3
+    end
+
+    it "should list all messages in new" do
+      3.times do |i|
+        msg = subject.new do |fh|
+          fh.puts "i am message #{i}"
+        end
+
+        msg.cur! if i == 1
+      end
+
+      subject.msgs(:new).count.should == 2
+    end
+
+    it "should list all messages in cur" do
+      3.times do |i|
+        msg = subject.new do |fh|
+          fh.puts "i am message #{i}"
+        end
+
+        msg.cur! if i != 1
+      end
+
+      subject.msgs(:cur).count.should == 2
+    end
+
+    it "should list all messages in tmp" do
+      3.times do |i|
+        msg = subject.new do |fh|
+          fh.puts "i am message #{i}"
+        end
+        msg.move(subject.path.tmp)
+      end
+
+      subject.msgs(:tmp).count.should == 3
+    end
+  end
+
+  describe "accessing messages" do
+    before :each do
+      3.times { subject.new }
+      3.times { subject.new.cur! }
+    end
+
+    it "should provide access to a message in new" do
+      subject.msgs(:new).should be_any
+      subject.msgs(:new).first.should be_kind_of(MessageDir::Message)
+    end
+
+    it "should provide access to a message in cur" do
+      subject.msgs(:cur).should be_any
+      subject.msgs(:cur).first.should be_kind_of(MessageDir::Message)
+    end
+
+    it "should provide access to a message based on UUID" do
+      msg  = subject.msgs(:new).first
+      same = subject.message(msg.guid)
+
+      same.should be_kind_of(MessageDir::Message)
+
+      msg.should == same
+    end
+  end
+
+  describe "locking" do
+    before :each do
+      3.times { subject.new }
+    end
+
+    it "should not lock messages by default" do
+      msg = subject.msgs.first
+      msg.should_not be_locked
+    end
+
+    it "should lock messages" do
+      msg = subject.msgs.first
+      msg.lock
+      msg.should be_locked
+    end
+
+    it "should unlock messages" do
+      msg = subject.msgs.first
+      msg.lock
+      msg.should be_locked
+
+      msg.unlock
+      msg.should_not be_locked
+    end
+
+    it "should lock message in block style" do
+      msg = subject.msgs.first
+      msg.should_not be_locked
+
+      msg.lock do
+        msg.should be_locked
+
+        msg.open(File::WRONLY|File::APPEND) do |fh|
+          fh.puts "Placed in a locked file"
+        end
+      end
+
+      msg.should_not be_locked
+    end
+  end
+
+
+  describe "processing" do
+    before :each do
+      3.times do |i|
+        msg = subject.new do |fh|
+          fh.puts "I am new"
+        end
+
+        msg.cur! if i == 1
+      end
+    end
+
+    it "should process messages" do
+      msg = subject.msgs.first
+      subject.process(msg, File::WRONLY|File::TRUNC) do |fh|
+        fh.puts "I am processed"
+      end
+
+      msg.read.should == "I am processed\n"
+    end
+
+    it "should process messages read-only per default" do
+      msg = subject.msgs.first
+      msg.process do |fh|
+        expect { fh.syswrite(" ") }.to raise_error(IOError)
+      end
+    end
+
+    it "should move messages to tmp for processing" do
+      msg = subject.msgs(:cur).first
+
+      msg.process do |fh|
+        fh.path.should =~ Regexp.new(subject.path.tmp)
+        msg.path.should =~ Regexp.new(subject.path.tmp)
+      end
+
+      msg.path.should =~ Regexp.new(subject.path.cur)
+    end
+
+    it "should lock messages when processing" do
+      msg = subject.msgs(:cur).first
+      msg.should_not be_locked
+      msg.process do |fh|
+        msg.should be_locked
+        msg.lock_file.should =~ Regexp.new(subject.path.tmp)
+      end
+
+      msg.should_not be_locked
+    end
+  end
+
+  describe "removing" do
+    before :each do
+      3.times do |i|
+        msg = subject.new do |fh|
+          fh.puts "I am new"
+        end
+
+        msg.cur! if i == 1
+      end
+    end
+
+    it "should remove a message" do
+      msg = subject.msgs.last
+
+      subject.rm(msg).should be_true
+      File.exists?(msg.path).should be_false
+    end
+
+    it "should not remove a message when locked" do
+      msg = subject.msgs.last
+      msg.lock
+
+      msg.rm.should_not be_true
+      File.exists?(msg.path).should_not be_false
+    end
+  end
+end

data/spec/objects/message_spec_old.rb

@@ -0,0 +1,111 @@
+require 'spec_helper'
+require 'simple_uuid'
+
+describe MessageDir::Message do
+  before :all do
+    @dir = MessageDir.new(Dir.mktmpdir(nil, '/tmp'))
+  end
+
+  after :all do
+    FileUtils.remove_entry_secure @dir.path
+  end
+
+  describe "On initialize" do
+    before :each do
+      uuid = SimpleUUID::UUID.new
+      File.open(File.join(@dir.path, "new", uuid.to_guid), "w") do |f|
+        f.puts "hello"
+      end
+      @new = uuid.to_guid
+
+      uuid = SimpleUUID::UUID.new
+      File.open(File.join(@dir.path, "cur", uuid.to_guid), "w") do |f|
+        f.puts "world"
+      end
+      @cur = uuid.to_guid
+    end
+
+    it "should not open a message without a guid" do
+      msg = MessageDir::Message.new(@dir)
+      msg.fh.should be_nil
+    end
+
+    it "should not create a message with a non existing guid" do
+      msg = MessageDir::Message.new(@dir, "24319b5c-5cc8-11e1-8312-67c6faefd181")
+      msg.fh.should be_nil
+    end
+
+    it "should open a message with an existing guid" do
+      msg = MessageDir::Message.new(@dir, @new)
+      msg.fh.should be_kind_of(File)
+      msg.fh.should_not be_closed
+    end
+
+    it "should find a message in cur as well" do
+      msg = MessageDir::Message.new(@dir, @cur)
+      msg.fh.should be_kind_of(File)
+      msg.fh.should_not be_closed
+    end
+  end
+
+  describe "With new" do
+    before :each do
+      @msg = MessageDir::Message.new(@dir)
+    end
+
+    it "should create a message in new" do
+      @msg.new do |fh|
+        fh.puts "i am the new message"
+      end
+
+      @msg.uuid.should be_kind_of(SimpleUUID::UUID)
+      @msg.guid.should be_kind_of(String)
+      @msg.guid.should_not be_empty
+
+      @msg.fh.should_not be_closed
+      @msg.fh.read.should =~ /i am the new message/
+
+      @msg.spot.should == :new
+      @msg.path.should =~ /new\//
+    end
+
+    it "should keep a message in tmp while not done" do
+      Thread.new do
+        @msg.new do |fh|
+          fh.puts "a part"
+          sleep 4
+          fh.puts "and another"
+        end
+      end
+
+      sleep 1
+
+      files = Dir[File.join(@dir.path, "tmp", "*")]
+      files.count.should == 1
+    end
+  end
+
+  describe "Current" do
+    it "should move a message to cur/" do
+      msg = MessageDir::Message.new(@dir).new do |fh|
+        fh.puts "i am the message"
+      end
+
+      msg.spot.should == :new
+
+      msg.cur
+      msg.spot.should == :cur
+      msg.path.should =~ /cur\//
+    end
+
+    it "should keep an open filehandle" do
+      msg = MessageDir::Message.new(@dir).new do |fh|
+        fh.puts "i am the message"
+      end.cur
+
+      msg.spot.should == :cur
+      msg.fh.should_not be_closed
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'message_dir'
+require 'fileutils'

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: message_dir
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Hartog C. de Mik
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-03-07 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: simple_uuid
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "0.2"
+  type: :runtime
+  version_requirements: *id001
+description: Handle slow network messages with care
+email: 
+- hartog.de.mik@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- README.rdoc
+- Rakefile
+- lib/message_dir.rb
+- lib/message_dir/message.rb
+- lib/message_dir/version.rb
+- message_dir.gemspec
+- spec/objects/message_dir_spec.rb
+- spec/objects/message_spec_old.rb
+- spec/spec_helper.rb
+homepage: https://github.com/coffeeaddict/message_dir
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: message_dir
+rubygems_version: 1.8.16
+signing_key: 
+specification_version: 3
+summary: Maildir like messages
+test_files: []
+