candygram 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Stephen Eley
+
+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.markdown

@@ -0,0 +1,103 @@
+# Candygram
+
+__"Candygram for Mongo!"__ — _Blazing Saddles_
+
+Candygram is a job queueing system for the MongoDB database.  It is loosely based on the **delayed_job** gem for ActiveRecord and the **Resque** gem for Redis, with the following interesting distinctions:
+
+* Delayed running can be added to any class with `include Candygram::Delivery`.
+* Objects with the Delivery module included get magic _*\_later_ variants on every instance method to enqueue the method call.  (_*\_in_ and _*\_at_ variants coming soon to specify a time of execution.)
+* Object states and method arguments are serialized as BSON to take best advantage of Mongo's efficiency.
+* A centralized dispatcher forks runners to handle each job, with maximum limits defined per class.
+* The job queue is a capped collection; because jobs are never deleted, recent history can be analyzed and failure states reported.
+
+## Installation
+
+Come on, you've done this before:
+
+    $ sudo gem install candygram
+    
+Candygram requires the **mongo** gem, and you'll probably be much happier if you install the **mongo\_ext** gem as well. The author uses only Ruby 1.9, but it _should_ work in Ruby 1.8.  If it doesn't, please report a bug in Github's issue tracking system.
+
+## Configuration
+
+Both the Delivery and the Dispatcher modules take some configuration
+parameters to connect to the proper Mongo collection:
+    
+    # Makes a default connection to 'localhost' if you don't override it
+    Candygram.connection = Mongo::Connection.new(_params_)  
+    
+    # Creates a default 'candygram' database if you don't override it
+    Candygram.database = 'my_database'
+    
+    # Creates a default 'candygram_queue' collection if you don't -- you get the picture.
+    Candygram.queue = Candygram.database.collection('my_queue')
+    # Or, to make a brand new queue with the proper indexes:
+    Candygram.create_queue('my_queue', 1048576) # 1MB capped collection
+    
+## Creating Jobs
+
+You can set up any Ruby class to delay method executions by including the Delivery module: 
+  
+    require 'candygram'
+    
+    class Explosive
+      include Candygram::Delivery  
+      CANDYGRAM_MAX = 5  # Optional; limits simultaneous runners per dispatcher
+
+      def kaboom(planet)
+        "A #{planet}-shattering kaboom!"
+      end
+    end
+
+You can continue to use the class as you normally would, of course.  If you want to queue a method to run later, just add _\_later_ to the method name:
+
+    e = Explosive.new
+    e.kaboom_later('Mars')
+
+This will serialize the object _e_ (including any instance variables) into a Mongo document, along with the method name and the argument.  The Candygram dispatcher will find it the next time it looks for jobs to run.  It will fork a separate process to unpack the object, call the `kaboom` method, and save the return value in the job document for later reference.
+
+## Dispatching
+
+Nice Rake tasks and Rails generators and such are still pending.  In the meantime, you can easily make your own dispatch script and call it with Rake or cron or trained beagle or what-have-you:
+
+    require 'candygram'
+    require 'my_environment'  # Whatever else you need to make your classes visible
+    
+    # Config parameters can be passed as a hash to `new` or by setting attributes.
+    d = Candygram::Dispatch.new  
+    d.frequency = 10     # Check for jobs every 10 seconds (default 5)
+    d.max_per_class = 20 # Simultaneous runners per class (default 10)
+    d.quiet = true       # Don't announce work on standard output (default false)
+    
+    # This is the central method that loops and checks for work...
+    d.run
+    
+    # You can kill the loop with CTRL-C or a 'kill' of course, or by
+    # calling 'd.finish' (but to make that work, you'd need to access 
+    # it from a separate thread).
+
+The dispatcher forks a separate process for each job in the queue, constrained by the per-class limits set by the CANDYGRAM_MAX constant in the class or by the **max\_per\_class** configuration variable.  It keeps track of its child PIDs and will wait for them to finish if shut down gracefully.  Jobs are locked so that dispatchers on multiple servers can be run against the same queue.
+
+Job runners push status information onto the document to indicate time of running and completion.  Future enhancements will likely include some reporting on this data, detection and rerunning on exception or timeout, and (possibly) optimization based on average run times.
+  
+## Limitations
+
+* You cannot pass blocks or procs to delayed methods.  There's just no robust way to capture and serialize the things.
+* Objects with singleton methods or module extensions outside their class will lose them.
+* Object classes must accept the `.new` method without any parameters.  It's probably a good idea not to pass objects that have complex initialization.
+* In general, objects that maintain state in any way cleverer than their instance variables will become stupid and probably unpredictable.
+* Circular object graphs will probably cause explosions.
+* Because it uses `fork`, this won't run on Windows.  (A limitation which bothers me not one iota.)
+
+## Big Important Disclaimer
+
+This is still very very alpha software.  I needed this for a couple of my own projects, but I'm pushing it into the wild _before_ proving it on those projects; if I don't, I'll probably lose energy and forget to do all the gem bundling and such.  It's not nearly as robust yet as I hope to make it: there's a lot more I want to do for handling error cases and making the dispatcher easy to keep running.
+
+I welcome your suggestions and bug reports using the Github issue tracker.  I'm happy to take pull requests as well.  If you use this for any interesting projects, please drop me a line and let me know about it -- eventually I may compile a list.
+
+Have Fun.
+
+
+## Copyright
+
+Copyright (c) 2009 Stephen Eley. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "candygram"
+    gem.summary = %Q{Delayed job queueing for MongoMapper}
+    gem.description = %Q{Candygram provides a job queue for the MongoDB document-oriented database, inspired by delayed_job and Resque. It uses the MongoMapper ORM and allows you to queue method calls for execution ASAP or at any time in the future.}
+    gem.email = "sfeley@gmail.com"
+    gem.homepage = "http://github.com/SFEley/candygram"
+    gem.authors = ["Stephen Eley"]
+    gem.add_dependency "mongo", ">= 0.18"
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0.5.2"
+    gem.add_development_dependency "mocha", ">= 0.9.7"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/candygram.rb

@@ -0,0 +1,10 @@
+module Candygram
+  DEFAULT_DATABASE = 'candygram'
+  DEFAULT_QUEUE = 'candygram_queue'
+  DEFAULT_QUEUE_SIZE = 10 * 1024 * 1024  # 10 MB
+end
+
+require 'mongo'
+require 'candygram/connection'
+require 'candygram/delivery'
+require 'candygram/dispatch'

data/lib/candygram/connection.rb

@@ -0,0 +1,64 @@
+module Candygram
+  
+  # The MongoDB connection object. Creates a default connection to localhost if not explicitly told otherwise.
+  def self.connection
+    @connection ||= Mongo::Connection.new
+  end
+  
+  # Accepts a new MongoDB connection, closing any current ones
+  def self.connection=(val)
+    @connection.close if @connection
+    @connection = val
+  end
+  
+  # The Mongo database object.  If you just want the name, use #database instead.
+  def self.db
+    @db ||= Mongo::DB.new(DEFAULT_DATABASE, connection)
+  end
+  
+  # Sets the Mongo database object. Unless you want to pass specific options or bypass the 
+  # Candygram connection object completely, it's probably easier to use the #database= method 
+  # and give it the name.
+  def self.db=(val)
+    @db = val
+  end
+  
+  # The name of the Mongo database object.
+  def self.database
+    db.name
+  end
+  
+  # Creates a Mongo database object with the given name and default options.
+  def self.database=(val)
+    self.db = Mongo::DB.new(val, connection)
+  end
+  
+  # The delivery queue collection. If not set, creates a capped collection with a default
+  # name of 'candygram_queue' and a default cap size of 100MB.
+  def self.queue
+    @queue or begin
+      if db.collection_names.include?(DEFAULT_QUEUE)
+        @queue = db[DEFAULT_QUEUE]
+      else
+        @queue = create_queue
+      end
+    end
+  end
+  
+  # Sets the delivery queue to an existing collection.  Assumes you know what you're doing 
+  # and have made all the proper indexes and such.  If not, use the #create_queue method instead.
+  def self.queue=(val)
+    @queue = val
+  end
+  
+  # Creates a new capped collection with the given name and cap size, and sets the indexes needed
+  # for efficient Candygram delivery.
+  def self.create_queue(name=DEFAULT_QUEUE, size=DEFAULT_QUEUE_SIZE)
+    @queue = db.create_collection(name, :capped => true, :size => size)
+    # Make indexes here...
+    @queue.create_index('deliver_at')
+    @queue.create_index('locked')
+    @queue.create_index('result')
+    @queue
+  end
+end

data/lib/candygram/delivery.rb

@@ -0,0 +1,37 @@
+require 'candygram/connection'
+require 'candygram/wrapper'
+
+module Candygram
+  # The special sauce that allows an object to place its method calls into the job queue. 
+  module Delivery
+    
+    # Lazily adds magic Candygram delivery methods to the class.
+    def method_missing(name, *args)
+      if name =~ /(\S+)_later$/
+        self.class.class_eval <<-LATER
+          def #{name}(*args)
+            send_candygram("#{$1}", *args)
+          end
+          LATER
+        send(name, *args)
+      else
+        super
+      end
+    end
+    
+  protected
+    # Does the tricky work of adding the method call to the MongoDB queue. Dollars to donuts that
+    # this method name doesn't conflict with anything you're already using...
+    def send_candygram(method, *args)
+      gram = {
+        :class => self.class.name,
+        :package => Wrapper.wrap_object(self),
+        :method => method,
+        :arguments => Wrapper.wrap_array(args),
+        :created_at => Time.now.utc,
+        :deliver_at => Time.now.utc
+      }
+      Candygram.queue << gram
+    end
+  end
+end

data/lib/candygram/dispatch.rb

@@ -0,0 +1,136 @@
+require 'candygram/connection'
+require 'candygram/wrapper'
+require 'candygram/utility'
+
+module Candygram
+  # Pays attention to the Candygram work queue and forks runners to do the work as needed.
+  class Dispatch
+    include Utility
+    
+    attr_accessor :frequency, :quiet, :max_per_class
+    attr_reader :runners
+    
+    # Returns a Dispatch object that will keep checking the Candygram work queue and forking runners.
+    # @option options [Integer] :frequency How often to check the queue (in seconds). Defaults to 5.
+    def initialize(options={})
+      @frequency = options.delete(:frequency) || 5
+      @max_per_class = options.delete(:max_per_class) || 10
+      @quiet = options.delete(:quiet)
+      @runners = {}
+      @index = {}
+    end  
+    
+    # Loops over the work queue.  You can stop it any time with the #finish method if running in a 
+    # separate thread. 
+    def run
+      Kernel.trap("CLD") do 
+        pid = Process.wait
+        remove_runner(pid)
+      end
+      
+      until @finish
+        deliveries = check_queue
+        deliveries.each do |del|
+          if slot_open?(del) && lock_delivery(del)
+            puts "Delivering #{del["class"]}\##{del["method"]} at #{Time.now}" unless quiet
+            # Close our connection so that we don't get too many weird copies
+            Candygram.connection = nil
+            child = fork do
+              # We're the runner
+              set_status(del, 'running')
+              package = Wrapper.unwrap(del["package"])
+              args = Wrapper.unwrap(del["arguments"])
+              result = package.send(del["method"].to_sym, *args)
+              finish_delivery(del, result)
+              Candygram.connection = nil
+              exit
+            end
+            # We're the parent
+            add_runner del["class"], child
+            sleep(0.2)  # Give connections time to wrap up
+          end
+        end
+        sleep frequency
+      end
+      until @index.empty?
+        sleep(0.1) # We trust our trap
+      end
+    end
+    
+    # Tells the #run method to stop running. It's a simple loop condition, not preemptive, so if the 
+    # dispatcher is sleeping you may have to wait up to _frequency_ seconds before it really ends.
+    def finish
+      @finish = true
+    end
+    
+    # Pushes a new PID onto the 'runners' hash.
+    def add_runner(klass, pid)
+      @runners[klass] ||= []
+      @runners[klass] << pid
+      @index[pid] = klass
+    end
+    
+    # Takes a PID off of the 'runners' hash.
+    def remove_runner(pid)
+      klass = @index.delete(pid)
+      @runners[klass].delete(pid)
+    end
+    
+  protected
+    # Looks for new work to do
+    def check_queue
+      # The interesting options hash for our new work query
+      check = {
+        :deliver_at => {'$lte' => Time.now.utc},
+        :result => {'$exists' => false},
+        :locked => {'$exists' => false}
+      }
+      Candygram.queue.find(check).to_a
+    end
+    
+    # Sets the 'locked' value of the job to prevent anyone else from taking it.
+    # Returns true on success, false on failure.
+    def lock_delivery(del)
+      r = Candygram.queue.update({'_id' => del['_id'], 'locked' => {'$exists' => false}}, # query
+                                 {'$set' => {'locked' => dispatch_id}},  # update
+                                 :safe => true)
+      update_succeeded?(r)
+    rescue Mongo::OperationFailure
+      false
+    end
+
+    # Removes the 'locked' value of the job.
+    def unlock_delivery(del)
+      Candygram.queue.update({'_id' => del['_id']}, {'$set' => {'locked' => nil}})
+    end
+    
+    # Logs the result of the method call to the delivery.  If the result is nil it will be logged
+    # as the word "nil".
+    def finish_delivery(del, result)
+      Candygram.queue.update({'_id' => del['_id']}, {'$set' => {'result' => (result.nil? ? 'nil' : Wrapper.wrap(result))}})
+      unlock_delivery(del)
+      set_status(del,'completed')
+    end
+    
+    # Checks whether we've hit the maximum number of simultaneous runners for this particular class.
+    # Limits are determined by (in order of precedence):
+    # 1. The value of a CANDYGRAM_MAX constant set in the class being delivered;
+    # 2. The max_per_class attribute of the Dispatch object;
+    # 3. The generic default of 10.
+    def slot_open?(del)
+      klass = Kernel.const_get(del["class"])
+      if klass.const_defined?(:CANDYGRAM_MAX)
+        limit = klass::CANDYGRAM_MAX
+      else
+        limit = max_per_class
+      end
+      (@runners[del["class"]] ? @runners[del["class"]].length < limit : true)
+    end
+  
+  private
+    # A unique identifier for this dispatcher. Includes local IP address and PID.
+    def dispatch_id
+      local_ip + '/' + Process.pid.to_s
+    end
+  end  
+end

data/lib/candygram/utility.rb

@@ -0,0 +1,47 @@
+require 'socket'
+
+module Candygram
+  
+  # Various methods that may be useful to both delivery and dispatch.
+  module Utility
+    
+    # Returns the IP address of this machine relative to the MongoDB server.
+    # From: http://coderrr.wordpress.com/2008/05/28/get-your-local-ip-address/
+    def local_ip
+      @local_ip or begin
+        orig, Socket.do_not_reverse_lookup = Socket.do_not_reverse_lookup, true  # turn off reverse DNS resolution temporarily
+
+        @local_ip = UDPSocket.open do |s|
+          s.connect Candygram.connection.host, 1
+          s.addr.last
+        end
+      ensure
+        Socket.do_not_reverse_lookup = orig
+      end
+    end
+    
+    # Parses Mongo's somewhat inscrutable results from Collection.update when :safe => true
+    # and returns whether or not the value was updated.  The basic output looks like this:
+    # [[{"err"=>nil, "updatedExisting"=>false, "n"=>0, "ok"=>1.0}], 1, 0]
+    def update_succeeded?(result)
+      result[0][0]["updatedExisting"]
+    end
+    
+    # Pushes a new status message onto the job.  Includes an identifier for this process and a timestamp.
+    def set_status(del, state)
+      Candygram.queue.update({'_id' => del['_id']}, {'$push' => {'status' => status_hash(state)}})
+    end
+    
+  protected
+    # Returns an embedded document suitable for pushing onto a delivery's status array.
+    def status_hash(state)
+      message = {
+        'ip' => local_ip,
+        'pid' => Process.pid,
+        'state' => state,
+        'at' => Time.now.utc
+      }
+    end
+  end
+end
+    

data/lib/candygram/wrapper.rb

@@ -0,0 +1,116 @@
+require 'date'  # Only so we know what one is. Argh.
+
+module Candygram
+  # Utility methods to serialize and unserialize objects into BSON
+  module Wrapper
+    
+    BSON_SAFE = [String, 
+                NilClass, 
+                TrueClass, 
+                FalseClass, 
+                Fixnum, 
+                Float, 
+                Time,
+                Regexp,
+                ByteBuffer, 
+                Mongo::ObjectID, 
+                Mongo::Code,
+                Mongo::DBRef]
+    
+    # Makes an object safe for the sharp pointy edges of MongoDB. Types properly serialized
+    # by the BSON.serialize call get passed through unmolested; others are unpacked and their
+    # pieces individually shrink-wrapped.
+    def self.wrap(thing)
+      # Pass the simple cases through
+      return thing if BSON_SAFE.include?(thing.class)
+      case thing
+      when Symbol
+        wrap_symbol(thing)
+      when Array
+        wrap_array(thing)
+      when Hash
+        wrap_hash(thing)
+      when Numeric  # The most obvious are in BSON_SAFE, but not all
+        thing
+      when Date
+        thing.to_time
+      else
+        wrap_object(thing)  # Our catchall machinery
+      end
+    end
+    
+    # Takes an array and returns the same array with unsafe objects wrapped
+    def self.wrap_array(array)
+      array.map {|element| wrap(element)}
+    end
+    
+    # Takes a hash and returns it with both keys and values wrapped
+    def self.wrap_hash(hash)
+      wrapped = {}
+      hash.each {|k, v| wrapped[wrap(k)] = wrap(v)}
+      wrapped
+    end
+    
+    # Returns a string that's distinctive enough for us to unwrap later and produce the same symbol
+    def self.wrap_symbol(symbol)
+      "__sym_" + symbol.to_s
+    end
+    
+    # Returns a nested hash containing the class and instance variables of the object.  It's not the
+    # deepest we could ever go (it doesn't handle singleton methods, etc.) but it's a start.
+    def self.wrap_object(object)
+      wrapped = {"class" => object.class.name}
+      ivars = {}
+      object.instance_variables.each do |ivar|
+        # Different Ruby versions spit different things out for instance_variables.  Annoying.
+        ivar_name = '@' + ivar.to_s.sub(/^@/,'')
+        ivars[ivar_name] = wrap(object.instance_variable_get(ivar_name))
+      end
+      wrapped["ivars"] = ivars unless ivars.empty?
+      {"__object_" => wrapped}
+    end
+    
+    # Undoes any complicated magic from the Wrapper.wrap method.  Almost everything falls through
+    # untouched except for symbol strings and hashed objects.
+    def self.unwrap(thing)
+      case thing
+      when Hash
+        if thing["__object_"]
+          unwrap_object(thing)
+        else
+          unwrap_hash(thing)
+        end
+      when Array
+        thing.map {|element| unwrap(element)}
+      when /^__sym_(.+)/
+        $1.to_sym
+      else
+        thing
+      end
+    end
+    
+    # Traverses the hash, unwrapping both keys and values.  Returns the hash that results.
+    def self.unwrap_hash(hash)
+      unwrapped = {}
+      hash.each {|k,v| unwrapped[unwrap(k)] = unwrap(v)}
+      unwrapped
+    end
+    
+    # Turns a hashed object back into an object of the stated class, setting any captured instance 
+    # variables.  The main limitation is that the object's class *must* respond to Class.new without 
+    # any parameters; we will not attempt to guess at any complex initialization behavior.
+    def self.unwrap_object(hash)
+      if innards = hash["__object_"]
+        klass = Kernel.const_get(innards["class"])
+        object = klass.new
+        if innards["ivars"]
+          innards["ivars"].each do |name, value|
+            object.instance_variable_set(name, unwrap(value))
+          end
+        end
+        object
+      end
+    end 
+  end
+end 
+  

data/spec/candygram/connection_spec.rb

@@ -0,0 +1,52 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Candygram do
+  it "creates a default connection" do
+    Candygram.connection.host.should == 'localhost'
+    Candygram.connection.port.should == 27017
+  end
+  
+  it "accepts an explicit connection" do
+    this = Mongo::Connection.new 'db.mongohq.com'  # Works as of time of writing
+    Candygram.connection = this
+    Candygram.connection.host.should == 'db.mongohq.com'
+  end
+  
+  it "has a default database" do
+    Candygram.database.should == 'candygram_test'
+  end
+  
+  it "accepts a new database name" do
+    Candygram.database = 'candygram_foo'
+    Candygram.db.name.should == 'candygram_foo'
+  end
+
+  it "accepts an actual DB object" do
+    d = Mongo::DB.new('candygram_bar', Candygram.connection)
+    Candygram.db = d
+    Candygram.database.should == 'candygram_bar'
+  end
+  
+  it "creates a default queue" do
+    Candygram.queue.name.should == "candygram_queue"
+    Candygram.queue.options['capped'].should be_true
+  end
+  
+  it "accepts another collection for the queue" do
+    Candygram.queue = Candygram.db.create_collection('foo')
+    Candygram.queue.name.should == 'foo'
+  end
+
+  it "can create a collection for the queue" do
+    q = Candygram.create_queue('bar')
+    q.should be_a_kind_of(Mongo::Collection)
+    q.options['capped'].should be_true
+  end
+  
+  after(:each) do  # Clear state from our tests
+    Candygram.queue = nil
+    Candygram.db = nil
+    Candygram.connection = nil
+  end
+  
+end

data/spec/candygram/delivery_spec.rb

@@ -0,0 +1,52 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+describe Candygram::Delivery do
+
+  before(:each) do
+    @this = Explosive.new
+  end
+    
+  it "adds the method to the delivery queue" do
+    @this.kaboom_later
+    Candygram.queue.find(:class => /Explosive/, :method => "kaboom").count.should == 1
+  end
+  
+  it "captures the arguments passed to the method" do
+    id = @this.repeated_kaboom_later('Venus', 15)
+    doc = Candygram.queue.find_one(id)
+    doc['arguments'].should == ['Venus', 15]
+  end
+  
+  it "takes an object as an argument" do
+    m = Missile.new
+    id = @this.object_kaboom_later('Pluto', 6, m)
+    doc = Candygram.queue.find_one(id)
+    doc['arguments'][2].should be_a_kind_of(Hash)
+  end
+  
+  it "sets the time it was created" do
+    id = @this.kaboom_later
+    (Time.now.utc - Candygram.queue.find_one(id)['created_at']).should < 2
+  end
+  
+  it "wraps itself up as its own package" do
+    @this.weight = 15
+    id = @this.kaboom_later
+    unwrap = Candygram::Wrapper.unwrap(Candygram.queue.find_one(id)['package'])
+    unwrap.should be_an(Explosive)
+    unwrap.weight.should == 15
+  end
+  
+  describe "for _later" do
+    it "can queue a method call using _later" do
+      @this.kaboom_later.should_not be_nil
+    end
+
+    it "sets the time for delivery to now" do
+      id = @this.kaboom_later
+      (Time.now.utc - Candygram.queue.find_one(id)['deliver_at']).should < 2
+    end
+    
+  end
+
+end

data/spec/candygram/dispatch_spec.rb

@@ -0,0 +1,93 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module Candygram
+  describe Candygram::Dispatch do
+    before(:each) do
+      c = Mongo::Connection.new
+      d = Mongo::DB.new(DEFAULT_DATABASE, c)
+      @queue = d.collection('candygram_queue')
+      @dispatch = Dispatch.new(:frequency => 1)
+      @exp = Explosive.new
+    end
+    
+    def run_dispatch(cycles=1)
+      t = Thread.new do
+        @dispatch.run
+      end
+      sleep(cycles)
+      yield if block_given?
+      @dispatch.finish
+      t.join(20) or raise "Dispatch never completed!"
+    end
+    
+    it "knows how often to check the database" do
+      d = Dispatch.new(:frequency => 5)
+      d.frequency.should == 5
+    end
+    
+    it "runs until aborted" do
+      run_dispatch.should_not be_nil
+    end
+    
+    it "checks the queue for new work on each cycle" do
+      Candygram.queue.expects(:find).times(2..3)
+      run_dispatch(2.5)
+    end
+    
+    it "locks any jobs it finds" do
+      @exp.slow_kaboom_later
+      run_dispatch(2) do
+        @queue.find_one(:locked => {"$exists" => true}).should_not be_nil
+      end
+    end
+    
+    it "forks a runner for its work" do
+      pid = Process.pid
+      @exp.slow_kaboom_later
+      run_dispatch(2) do
+        j = @queue.find_one(:locked => {"$exists" => true})
+        j["status"][0]["pid"].should_not == pid
+      end
+    end
+    
+    it "keeps track of its runners" do
+      3.times { @exp.slow_kaboom_later }
+      run_dispatch(4) do
+        @dispatch.runners['Explosive'].length.should == 3
+      end
+    end
+    
+    it "runs the method" do
+      @exp.kaboom_later
+      run_dispatch
+      j = @queue.find_one('result' => {'$exists' => true})
+      j["result"].should == "An earth-shattering kaboom!"
+    end
+    
+    it "unlocks the delivery upon completion" do
+      @exp.kaboom_later
+      run_dispatch
+      j = @queue.find_one('result' => {'$exists' => true})
+      j["locked"].should be_nil
+    end
+    
+    it "clears the runner record when it's done working" do
+      3.times { @exp.kaboom_later }
+      run_dispatch
+      sleep(1)
+      @dispatch.runners['Explosive'].should be_empty
+    end
+      
+    it "keeps track of maximum instances for each class" do
+      10.times { @exp.slow_kaboom_later }
+      run_dispatch(3) do
+        a = @queue.find(:locked => {"$exists" => false})
+        a.count.should == 5
+        sleep(10)
+        a = @queue.find(:locked => {"$exists" => false})
+        a.count.should == 0
+      end
+    end
+        
+  end
+end

data/spec/candygram/wrapper_spec.rb

@@ -0,0 +1,178 @@
+require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+
+module Candygram
+  describe Candygram::Wrapper do
+    describe "wrapping" do
+  
+      it "can wrap an array of simple arguments" do
+        a = ["Hi", 1, nil, 17.536]
+        Wrapper.wrap_array(a).should == a
+      end
+    
+      it "can wrap a string" do
+        Wrapper.wrap("Hi").should == "Hi"
+      end
+
+      it "can wrap nil" do
+        Wrapper.wrap(nil).should == nil
+      end
+    
+      it "can wrap true" do
+        Wrapper.wrap(true).should be_true
+      end
+    
+      it "can wrap false" do
+        Wrapper.wrap(false).should be_false
+      end
+    
+      it "can wrap an integer" do
+        Wrapper.wrap(5).should == 5
+      end
+    
+      it "can wrap a float" do
+        Wrapper.wrap(17.950).should == 17.950
+      end
+    
+      it "can wrap an already serialized bytestream" do
+        b = BSON.serialize(:foo => 'bar')
+        Wrapper.wrap(b).should == b
+      end
+    
+      it "can wrap an ObjectID" do
+        i = Mongo::ObjectID.new
+        Wrapper.wrap(i).should == i
+      end
+  
+      it "can wrap the time" do
+        t = Time.now
+        Wrapper.wrap(t).should == t
+      end
+    
+      it "can wrap a regular expression" do
+        r = /ha(l+)eluja(h?)/i
+        Wrapper.wrap(r).should == r
+      end
+    
+      it "can wrap a Mongo code object (if we ever need to)" do
+        c = Mongo::Code.new('5')
+        Wrapper.wrap(c).should == c
+      end
+    
+      it "can wrap a Mongo DBRef (if we ever need to)" do
+        d = Mongo::DBRef.new('foo', Mongo::ObjectID.new)
+        Wrapper.wrap(d).should == d
+      end
+    
+      it "can wrap a date as a time" do
+        d = Date.today
+        Wrapper.wrap(d).should == Date.today.to_time
+      end
+    
+      it "can wrap other numeric types (which might throw exceptions later but oh well)" do
+        c = Complex(2, 5)
+        Wrapper.wrap(c).should == c
+      end
+    
+      it "can wrap a symbol in a way that preserves its symbolic nature" do
+        Wrapper.wrap(:oldglory).should == "__sym_oldglory"
+      end
+    
+      it "wraps an array recursively" do
+        a = [5, 'hi', [':symbol', 0], nil]
+        Wrapper.wrap(a).should == a
+      end
+      
+      it "wraps a hash's keys" do
+        h = {"foo" => "bar", :yoo => "yar"}
+        Wrapper.wrap(h).keys.should == ["foo", "__sym_yoo"]
+      end
+    
+      it "wraps a hash's values" do
+        h = {:foo => :bar, :yoo => [:yar, 5]}
+        Wrapper.wrap(h).values.should == ["__sym_bar", ["__sym_yar", 5]]
+      end
+      
+      it "rejects procs"
+      
+      describe "objects" do
+        before(:each) do
+          @missile = Missile.new
+          @missile.payload = "15 megatons"
+          @missile.rocket = [2, Object.new]
+          @this = Wrapper.wrap(@missile)
+        end
+        
+        it "returns a hash" do
+          @this.should be_a(Hash)
+        end
+        
+        it "keys the hash to be an object" do
+          @this.keys.should == ["__object_"]
+        end
+        
+        it "knows the object's class" do
+          @this["__object_"]["class"].should == "Missile"
+        end
+        
+        it "captures all the instance variables" do
+          ivars = @this["__object_"]["ivars"]
+          ivars.should have(2).elements
+          ivars["@payload"].should == "15 megatons"
+          ivars["@rocket"][1]["__object_"]["class"].should == "Object"
+        end
+        
+        it "avoids circular dependencies"
+        
+      end
+    end
+    
+    describe "unwrapping" do
+      before(:each) do
+        @wrapped = {"__object_" => {
+          "class" => "Missile",
+          "ivars" => {
+            "@payload" => "6 kilotons",
+            "@rocket" => [1, {"__object_" => {
+              "class" => "Object"
+            }}]
+          }
+        }}
+      end
+      it "passes most things through untouched" do
+        Wrapper.unwrap(5).should == 5
+      end
+      
+      it "turns symbolized strings back into symbols" do
+        Wrapper.unwrap("__sym_blah").should == :blah
+      end
+      
+      it "turns hashed objects back into objects" do
+        obj = Wrapper.unwrap(@wrapped)
+        obj.should be_a(Missile)
+        obj.payload.should == "6 kilotons"
+        obj.rocket[0].should == 1
+        obj.rocket[1].should be_an(Object)
+      end
+        
+      it "traverses a hash and unwraps whatever it needs to" do
+        hash = {"__sym_foo" => "__sym_bar", "missile" => @wrapped}
+        unwrapped = Wrapper.unwrap(hash)
+        unwrapped[:foo].should == :bar
+        unwrapped["missile"].should be_a(Missile)
+      end
+      
+      it "traverses an array and unwraps whatever it needs to" do
+        array = ["__sym_foo", 5, @wrapped, nil, "hi"]
+        unwrapped = Wrapper.unwrap(array)
+        unwrapped[0].should == :foo
+        unwrapped[1].should == 5
+        unwrapped[2].should be_a(Missile)
+        unwrapped[3].should be_nil
+        unwrapped[4].should == "hi"
+      end
+    
+    end
+      
+  
+  end
+end

data/spec/candygram_spec.rb

@@ -0,0 +1,2 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec.watchr

@@ -0,0 +1,12 @@
+# See: http://github.com/mynyml/watchr/
+
+require 'redgreen'
+require 'autowatchr'
+
+Autowatchr.new(self) do |config|
+  config.test_dir = 'spec'
+  config.test_re = "^#{config.test_dir}/(.*)_spec\.rb$"
+  config.test_file = '%s_spec.rb'
+end
+# watch ( 'spec/.*_spec\.rb' ) { |spec| system("ruby #{spec[0]}")}
+# watch ( 'lib/(.*).rb' ) { |lib| system("ruby spec/#{spec[1]}_spec.rb")}

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'candygram'
+require 'mocha'
+require 'spec'
+require 'spec/autorun'
+
+# Override the default database so that we don't clobber any production queues by chance
+Candygram.const_set(:DEFAULT_DATABASE, "candygram_test")
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir[File.expand_path(File.join(File.dirname(__FILE__),'support','**','*.rb'))].each {|f| require f}
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+  
+  # "I say we take off and nuke the place from orbit. It's the only way to be sure."
+  config.after(:each) {Candygram.connection.drop_database(Candygram::DEFAULT_DATABASE)}
+end

data/spec/support/explosive.rb

@@ -0,0 +1,25 @@
+# A test class that we can make deliveries with and easily check results.
+class Explosive
+  include Candygram::Delivery
+  CANDYGRAM_MAX = 5
+  
+  attr_accessor :weight
+  
+  def kaboom
+    "An earth-shattering kaboom!"
+  end
+  
+  def repeated_kaboom(planet, repeat)
+    "A #{planet}-shattering kaboom #{repeat} times!"
+  end
+  
+  def object_kaboom(planet, repeat, object)
+    "A #{planet}-shattering kaboom #{repeat} times using a #{object.class.name}!"
+  end
+  
+  # To test that locking is performed properly
+  def slow_kaboom
+    sleep(5)
+    "Waited 5 seconds...  NOW we kaboom."
+  end
+end

data/spec/support/missile.rb

@@ -0,0 +1,10 @@
+# A simple, non-Candygrammed class to test argument encoding
+class Missile
+  attr_accessor :payload
+  attr_accessor :rocket
+  
+  def explode
+    "Dropped the #{payload}."
+  end
+end
+

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification 
+name: candygram
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Stephen Eley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-31 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mongo
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.18"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: yard
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.5.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.9.7
+    version: 
+description: Candygram provides a job queue for the MongoDB document-oriented database, inspired by delayed_job and Resque. It uses the MongoMapper ORM and allows you to queue method calls for execution ASAP or at any time in the future.
+email: sfeley@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- lib/candygram.rb
+- lib/candygram/connection.rb
+- lib/candygram/delivery.rb
+- lib/candygram/dispatch.rb
+- lib/candygram/utility.rb
+- lib/candygram/wrapper.rb
+- spec/candygram/connection_spec.rb
+- spec/candygram/delivery_spec.rb
+- spec/candygram/dispatch_spec.rb
+- spec/candygram/wrapper_spec.rb
+- spec/candygram_spec.rb
+- spec/spec.opts
+- spec/spec.watchr
+- spec/spec_helper.rb
+- spec/support/explosive.rb
+- spec/support/missile.rb
+has_rdoc: true
+homepage: http://github.com/SFEley/candygram
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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.3.5
+signing_key: 
+specification_version: 3
+summary: Delayed job queueing for MongoMapper
+test_files: 
+- spec/candygram/connection_spec.rb
+- spec/candygram/delivery_spec.rb
+- spec/candygram/dispatch_spec.rb
+- spec/candygram/wrapper_spec.rb
+- spec/candygram_spec.rb
+- spec/spec_helper.rb
+- spec/support/explosive.rb
+- spec/support/missile.rb