background_bunnies 0.0.4 → 0.0.5

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 Johan Hernandez
+Copyright (c) 2013 Heapsource - http://www.heapsource.com
 
 MIT License
 
@@ -19,4 +19,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -15,10 +15,141 @@ And then execute:
 Or install it yourself as:
 
     $ gem install background_bunnies
+	
+## How it Works
 
-## Usage
+Background Bunnies are workers fed by producers and broadcasters.
 
-See the examples ;)
+* A producer will create jobs intended for bunnies of type `queue` and only one worker will process the job. This is the default configuration.
+* A broadcasters will produce jobs intented for bunnies of type `broadcast` and every single worker will receive the same job.
+
+## Work Queues
+
+A work client uses AMQP queues and only one bunny will perform the job, this is known as a work queue. This is the default configuration for all the bunnies.
+
+Example Bunny Worker:
+
+	require 'background_bunnies'
+	
+	class BackgroundBunnies::Workers::ImageTransform
+	  include BackgroundBunnies::Bunny
+	  group :images
+
+	  def process(job)
+		image_url = job.payload[:image_url] # https://encrypted.google.com/images/srpr/logo4w.png
+	    # perform image transformation here
+	  end
+	end
+	
+    BackgroundBunnies.configure(:main, "amqp://guest:guest@127.0.0.1")
+	BackgroundBunnies.run(:images) # block forever while running the workers
+
+Example Client:
+
+    BackgroundBunnies.configure(:main, "amqp://guest:guest@127.0.0.1")
+    producer = BackgroundBunnies::Workers::ImageTransform.create_producer :images
+	producer.enqueue(image_path: "https://encrypted.google.com/images/srpr/logo4w.png")
+
+## Broadcast
+
+A broadcast client uses AMQP queues to `fanout` the same job across many worker bunnies, bunnies will receive the job when mode `broadcast` is used.
+
+Example Bunny worker:
+
+	require 'background_bunnies'
+	
+	class BackgroundBunnies::Workers::RelyMessage
+	  include BackgroundBunnies::Bunny
+	  type :broadcast # tell the bunny worker it should use queue as broadcast
+	  group :messaging
+
+	  def process(job)
+		subject = job.payload[:subject] # "Spread this message across all the worker nodes"
+	    # do your thing here
+	  end
+	end
+	
+	BackgroundBunnies.configure(:main, "amqp://guest:guest@127.0.0.1")
+	BackgroundBunnies.run(:messaging) # block forever while running the workers
+
+Example Client:
+
+    BackgroundBunnies.configure(:main, "amqp://guest:guest@127.0.0.1")
+    producer = BackgroundBunnies::Workers::RelyMessage.create_brodacaster :messaging
+	producer.enqueue(subject: "Spread this message across all the worker nodes")
+
+## Error Handling
+
+In the case an exception is raised while executing the method `process`, the job will be put back on the queue so it can be processed in another time or by another worker. Even if the worker crashes, the job will be processed in another time or by another worker eventually.
+
+Bunnies provide a method you could override to determinate which errors should cause the job to be requeued or skipped.
+
+Return `true` if you want to skip the job, the default is requeue the job on every error.
+
+    def on_error(job, err)
+	  # true and the job will be skipped.
+	  # false and the job will be requeued. This is the default.
+    end
+
+
+## Configuring Connection Strings
+
+Bunnies will be executed together under the same configuration group. The default group is `:default`.
+
+A group share the same connection uri across the producers, broadcasters and bunnies:
+
+Example:
+
+    BackgroundBunnies.configure(:default, "amqp://guest:guest@127.0.0.1")
+
+## Executing a group of Workers
+
+Instead initializing and running a single worker manually, background bunnies executes in groups.
+
+	BackgroundBunnies.run(:default) # block forever while running the workers
+
+## Workers as custom Rake Tasks
+
+If you want to run your workers as a rake task in for example, a Rails app, you can create one as follows:
+
+Create a file in `lib/tasks/images.rb`:
+
+	namespace :mybunnies do
+	  task :images=>:environment do
+	    BackgroundBunnies.run(:images)
+	  end
+	end
+
+You can then run from the command line:
+
+	rake mybunnies:images
+
+## Logging
+
+In your worker bunnies you can use `log_error`, `log_warn` and `log_info` to log information formatted as part of BackgroundBunnies to `$stderr` and `$stdout`.
+
+Example:
+
+	def process(job)
+	  log_error "An error occurred"
+	  log_info "Something Happened"
+	  log_warn "Beware of this"
+	end
+
+Output:
+
+    [error] BackgroundBunnies -> Songs: An error occurred
+    [info] BackgroundBunnies -> Songs: Something Happened
+    [warn] BackgroundBunnies -> Songs: Beware of this
+	
+
+## Examples
+
+Check `/examples`.
+
+## LICENSE
+
+MIT
 
 ## Contributing
 

data/lib/background_bunnies/bunny.rb

@@ -102,6 +102,7 @@ module BackgroundBunnies
         @exchange = @channel.fanout(BackgroundBunnies.broadcast_exchange_name(queue_name))
         @queue.bind(@exchange)
       else
+        queue_options[:durable] = true
         @queue = @channel.queue(queue_name, queue_options)
       end
       @consumer = @queue.subscribe(:ack=>true) do |metadata, payload|
@@ -114,8 +115,12 @@ module BackgroundBunnies
           metadata.ack
         rescue =>err
           # processing went wrong, requeing message
-          on_error(job, err)
-          metadata.reject(:requeue=>true)
+          job = Job.new(nil, info, properties) unless job
+          unless on_error(job, err)
+            metadata.reject(:requeue=>true)
+          else
+            metadata.ack
+          end
         end
       end
     end
@@ -128,6 +133,14 @@ module BackgroundBunnies
       BackgroundBunnies.error "#{queue_name}: #{a}"
     end
 
+    def log_info(a)
+      BackgroundBunnies.info "#{queue_name}: #{a}"
+    end
+
+    def log_warn(a)
+      BackgroundBunnies.warn "#{queue_name}: #{a}"
+    end
+
     #
     # Process a Job. Implemented by the class.
     #

data/lib/background_bunnies/logger.rb

@@ -1,11 +1,11 @@
 module BackgroundBunnies
 
-  def self.log(a)
-    p "[log] BackgroundBunnies -> #{a}"
+  def self.warn(a)
+    $stderr.puts "[warn] BackgroundBunnies -> #{a}"
   end
 
   def self.info(a)
-    p "[info] BackgroundBunnies -> #{a}"
+    $stdout.puts "[info] BackgroundBunnies -> #{a}"
   end
 
   def self.error(a)

data/lib/background_bunnies/producer.rb

@@ -11,7 +11,7 @@ module BackgroundBunnies
       @connection = BackgroundBunnies.connect connection_or_group
       @queue_name = queue_name.to_s
       @channel = @connection.create_channel
-      @queue = @connection.queue(@queue_name)
+      @queue = @connection.queue(@queue_name, :durable=>true)
     end
 
     #

data/lib/background_bunnies/version.rb

@@ -1,3 +1,3 @@
 module BackgroundBunnies
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: background_bunnies
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-17 00:00:00.000000000 Z
+date: 2013-06-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny