ruote-resque 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NmE2NDVmYTU0NzNmNWZkZTk5MjgxYWZlOGQ4YTk0MDNjOWFmMDZmNg==
+  data.tar.gz: !binary |-
+    M2M3YTFmMmM2YmQ3NTgwNDg4MDhlMzE2ODNhMDI5YzgyOGI2NDBlMA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    YTUwNjUzMzA5N2MzOGYzZjY5NWYwOGZjZTk2YTY5ZjNkM2U1M2E4NGQwMTE4
+    OTQ1YWE0YmJhYTA5ODkyZjEzYmM3Y2ZkY2JjYWRjZmVkMjliNmJkNTMyOGEx
+    OWVkZGYyYTc1ZjA4OWY3YTY0MDQ1MDA1ODU0ODYwOTE2YzU5ZDE=
+  data.tar.gz: !binary |-
+    NGZiMTY5MjU1ZmY1NWQ1ZjVlNDYyYjJmNzAyZDFjMDgyY2Y2NTE2YmQ0MWYy
+    NzlhMTU5MDY4NTQ3NzY0ZGYwODViZjFjNTE3YjM3N2QzNmZhODNiYTM4OGY4
+    NWE2ZGRjZDVhMmVmYmI5ZTVjZDQ5MzgxYTVlNmU0NDYwZjIxNTc=

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.rubocop.yml

@@ -0,0 +1,4 @@
+LineLength:
+  Enabled: false
+HashSyntax:
+  Enabled: false

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+bundler_args: --without development
+rvm:
+  - "1.8.7"
+  - "1.9.2"
+  - "1.9.3"
+  - "2.0.0"
+  - jruby-18mode
+  - jruby-19mode
+  - rbx-18mode
+  - rbx-19mode
+script: bundle exec rspec spec
+services:
+  - redis-server

data/.yardopts

@@ -0,0 +1,4 @@
+--markup=markdown
+--files LICENSE
+--title ruote-resque
+--readme README.md

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ruote-resque.gemspec
+gemspec
+
+gem "ruote", :git => 'git://github.com/jmettraux/ruote.git'
+gem "json"
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'coveralls', :require => false
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Adrien Kohlbecker
+
+MIT License
+
+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.md

@@ -0,0 +1,156 @@
+[![Build Status](https://travis-ci.org/adrienkohlbecker/ruote-resque.png)](https://travis-ci.org/adrienkohlbecker/ruote-resque) [![Coverage Status](https://coveralls.io/repos/adrienkohlbecker/ruote-resque/badge.png?branch=master)](https://coveralls.io/r/adrienkohlbecker/ruote-resque) [![Code Climate](https://codeclimate.com/github/adrienkohlbecker/ruote-resque.png)](https://codeclimate.com/github/adrienkohlbecker/ruote-resque) [![Dependency Status](https://gemnasium.com/adrienkohlbecker/ruote-resque.png)](https://gemnasium.com/adrienkohlbecker/ruote-resque)
+
+# Ruote::Resque
+
+- **Homepage**: [github.com/adrienkohlbecker/ruote-resque](https://github.com/adrienkohlbecker/ruote-resque)
+- **Rdoc**: [rdoc.info/gems/ruote-resque](http://rdoc.info/gems/ruote-resque)
+- **Author**: Adrien Kohlbecker
+- **License**: MIT License
+- **Latest Version**: 0.1.0
+- **Release Date**: June 23, 2013
+
+## Synopsis
+
+Ruote::Resque allows a Ruote engine to delegates the work of it's participants to Resque workers.
+
+Common use cases include:
+
+- You run a lot of jobs and need the reliability of Resque to process your jobs
+- You have a Resque system you need to integrate with
+- You want a separation of concerns between process orchestration and actual execution
+
+## How it works
+
+- The library uses a specific Resque queue for message passing.
+- Participants are empty shells that just queue jobs to Resque, and the job itself replies (via an after_perform hook) with the mutated workitem.
+- Under the hood, a thread polls the reply queue every five seconds for new replies.
+- When a reply is received, the process continues with the new workitem.
+
+Note that:
+
+- Ruote is not needed as a dependency on the Resque side.
+- Error handling is supported on both sides (exceptions show up both on the Resque failure backend and in ruote-kit)
+
+## Usage
+
+### Set Up
+
+#### Inside your Ruote instance
+
+Add to your Ruote instance gemfile :
+
+```ruby
+# The version released on RubyGems is old and not supported.
+# Note that ruote is not a hard dependency of ruote-resque,
+# to allow for lightweight use as a client (see below)
+gem 'ruote', :git => 'git://github.com/jmettraux/ruote.git'
+gem 'ruote-resque'
+```
+
+Then when booting your engine do this :
+
+```ruby
+require 'ruote/resque'
+
+# Run the poller thread.
+Ruote::Resque::Receiver.new(dashboard)
+```
+
+#### Inside your Resque worker instance
+
+Add to your Resque worker instance gemfile :
+
+```ruby
+gem 'ruote-resque', :require => false
+```
+
+Then when booting your worker do this :
+
+```ruby
+# You should not require the full library inside your worker, the client will suffice
+require 'ruote/resque/client'
+```
+
+### Participants
+
+```ruby
+# Inside your worker, add Ruote::Resque::Job to your jobs
+class MyAwesomeJob
+  extend Ruote::Resque::Job
+
+  @queue = :my_queue
+
+  def self.perform(workitem)
+    workitem['fields']['be_awesome'] = true
+  end
+end
+
+# Inside your Ruote instance
+Ruote::Resque.register(dashboard) do
+  be_awesome 'MyAwesomeJob', :my_queue
+end
+```
+
+There are two other ways to register participants:
+
+```ruby
+Ruote::Resque.register(dashboard) do
+  participant 'be_awesome', 'MyAwesomeJob', :my_queue
+end
+
+# OR (not recommended)
+
+dashboard.register_participant 'be_awesome', Ruote::Resque::Participant, :class => 'MyAwesomeJob', :queue => :my_queue
+```
+
+Note that you can pass options to the participant:
+
+```ruby
+Ruote::Resque.register(dashboard) do
+  be_awesome 'MyAwesomeJob', :my_queue, :forget => true
+end
+```
+
+### Configuration
+
+```ruby
+# Configure the library (optional, default values shown)
+# You should duplicate this configuration on both
+# your Ruote instance and your Resque instance
+Ruote::Resque.configure do |config|
+  config.reply_queue = :ruote_replies
+  config.logger = Logger.new(STDOUT).tap { |log| log.level = Logger::INFO }
+  config.interval = 5
+end
+
+# Override the default error handler (optional, but recommended. Default is to log at ERROR level)
+# Do this in your Ruote instance
+class Ruote::Resque::Receiver
+  def handle_error(e)
+    MyErrorHandler.handle(e)
+  end
+end
+```
+
+## Requirements
+
+A functional installation of [Ruote](http://ruote.rubyforge.org) and [Resque](http://github.com/resque/resque) is needed.
+Note that at the time of writing the release of Ruote on rubygems is very old and not supported. Use it from git.
+
+ruote-resque has been tested on Ruby 1.8+.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Do some changes
+4. Run the tests (`bundle exec rspec`)
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create new Pull Request
+
+## Changelog
+
+- **June 23, 2013**: 0.1.0 release
+    - Initial release
+

data/Rakefile

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

data/lib/ruote/resque.rb

@@ -0,0 +1,40 @@
+# encoding: UTF-8
+
+require 'ruote'
+require 'ruote/resque/client'
+require 'ruote/resque/participant'
+require 'ruote/resque/participant_registrar'
+require 'ruote/resque/receiver'
+
+module Ruote
+  # Ruote::Resque allows a Ruote engine to delegates the work of it's participants
+  # to Resque workers.
+  #
+  # Common use cases include:
+  #
+  # - You run a lot of jobs and need the reliability of Resque to process your jobs
+  # - You have a Resque system you need to integrate with
+  # - You want a separation of concerns between process orchestration and actual execution
+  #
+  # See the {file:README} for usage instructions
+  module Resque
+
+    # Registers resque participants using a DSL.
+    # @example Using the dsl
+    #     Ruote::Resque.register dashboard do
+    #       be_awesome MyAwesomeJob, :my_queue
+    #       be_really_awesome 'MyReallyAwesomeJob', :my_queue, :forget => true
+    #     end
+    # @example Using the participant method
+    #     Ruote::Resque.register dashboard do
+    #       participant /be_.*/, BeSomething, :my_queue
+    #     end
+    # @param [Ruote::Dashboard] dashboard the ruote dashboard
+    # @return [void]
+    def self.register(dashboard, &block)
+      registrar = Ruote::Resque::ParticipantRegistrar.new(dashboard)
+      registrar.instance_eval(&block)
+    end
+
+  end
+end

data/lib/ruote/resque/client.rb

@@ -0,0 +1,62 @@
+# encoding: UTF-8
+
+require 'logger'
+require 'ruote/resque/job'
+require 'ruote/resque/reply_job'
+require 'ruote/resque/version'
+
+module Ruote
+  module Resque
+
+    # A basic configuration object
+    # @example Setting up ruote-resque (default values shown)
+    #     Ruote::Resque.configure do |config|
+    #       config.reply_queue = :ruote_replies
+    #       config.logger = Logger.new(STDOUT).tap { |log| log.level = Logger::INFO }
+    #       config.interval = 5
+    #     end
+    class Configuration
+      # The queue used for message passing between Resque jobs and Ruote (defaults to `:ruote_replies`)
+      attr_accessor :reply_queue
+      # The logger used (defaults to STDOUT with log level INFO)
+      attr_accessor :logger
+      # The interval used by {Receiver} when polling Resque
+      attr_accessor :interval
+    end
+
+    class << self
+
+      # Returns the current {Configuration}
+      attr_accessor :configuration
+
+      # Enqueues a ReplyJob with the given arguments.
+      # @return true if the job was queued, nil if the job was rejected by a before_enqueue hook.
+      # @example
+      #     Ruote::Resque.reply(workitem)
+      def reply(*args)
+        ::Resque.enqueue(Ruote::Resque::ReplyJob, *args)
+      end
+
+      # @return [Logger] the logger to be used inside ruote-resque
+      def logger
+        configuration.logger
+      end
+
+      # This method allows you to customize the ruote-resque configuration.
+      # @see Configuration
+      # @yield [Configuration]
+      # @return [void]
+      def configure
+        self.configuration ||= Ruote::Resque::Configuration.new
+        yield(configuration) if block_given?
+      end
+    end
+  end
+end
+
+# setup default configuration
+Ruote::Resque.configure do |config|
+  config.reply_queue = :ruote_replies
+  config.logger = Logger.new(STDOUT).tap { |log| log.level = Logger::INFO }
+  config.interval = 5
+end

data/lib/ruote/resque/job.rb

@@ -0,0 +1,47 @@
+# encoding: UTF-8
+
+module Ruote
+module Resque
+
+  # Include this module inside your Resque jobs to enable
+  # them to respond to Ruote.
+  #
+  # - Note that the arity should be 1 for the `self.perform` method.
+  # - The workitem will be sent as a Hash. (via `Ruote::Workitem#to_h`)
+  #
+  # @example
+  #     class MyAwesomeJob
+  #       extend Ruote::Resque::Job
+  #
+  #       def self.perform(workitem)
+  #         workitem['fields']['awesome'] = true
+  #       end
+  #     end
+  module Job
+
+    # after_perform hook to send a reply to the Ruote process.
+    # @param [Hash] workitem the workitem sent to the current Job
+    # @return [void]
+    def after_perform_reply_to_ruote(workitem)
+      Ruote::Resque.reply(workitem)
+    end
+
+    # on_failure hook to send a reply to the Ruote process.
+    # Will collect the exception details and send them along.
+    # @param [Exception] exception the raised exception
+    # @param [Hash] workitem the workitem sent to the current Job.
+    #   TODO: this may be mutated from the original workitem, handle it.
+    # @return [void]
+    def on_failure_reply_to_ruote(exception, workitem)
+
+      klass = exception.class.to_s
+      message = exception.message
+      backtrace = exception.backtrace
+
+      Ruote::Resque.reply(klass, message, backtrace, workitem)
+    end
+
+  end
+
+end
+end

data/lib/ruote/resque/participant.rb

@@ -0,0 +1,86 @@
+# encoding: UTF-8
+
+# A module to be included in your Resque jobs
+# to be able to register them as participants.
+#
+# Note that the participant should have a queue, either via the `@queue` variable
+# when the class is accessible to Ruote, or via the `:queue` option on registration
+#
+# @example Register a participant
+#     # This is defined on a remote Resque worker
+#     # You do not need to extend Participant in this case
+#     class MyAwesomeJob
+#       extend Ruote::Resque::Job
+#       @queue = :my_queue
+#
+#       def self.perform(workitem)
+#         workitem['fields']['awesome'] = true
+#       end
+#     end
+#
+#     # Use it like this in your Ruote process
+#     engine.register_participant 'be_awesome', Ruote::Resque::Participant, :class => 'MyAwesomeJob', :queue => :my_queue
+#     # Or register it va the DSL
+#     Ruote::Resque.register(dashboard) do
+#       be_awesome 'MyAwesomeJob', :my_queue
+#     end
+# A resque participant implementation.
+class Ruote::Resque::Participant
+  include Ruote::LocalParticipant
+
+  # Called with the options on `engine.register_participant`
+  # @param [Hash] opts
+  # @option opts [#to_s] :class (self.class) the job class to enqueue when called
+  # @option opts [#to_s] :queue (Resque.queue_from_class(class)) the queue to enqueue the job in
+  # @option opts [Boolean] :forget (false) wait for the worker's reply if false
+  def initialize(opts = {})
+
+    @job_klass = opts.delete('class')
+    @job_queue = opts.delete('queue')
+    @should_forget = opts.delete('forget') || false
+
+    # Called here to raise eventual exceptions on initialization
+    ::Resque.validate(@job_klass, @job_queue)
+
+  end
+
+  # Called when the participant is handed a workitem.
+  # Enqueues the job to Resque
+  # @return [void]
+  def on_workitem
+
+    payload = encode_workitem(workitem)
+    ::Resque::Job.create(@job_queue, @job_klass, payload)
+
+    reply if @should_forget
+
+  end
+
+  # Called when Ruote has to cancel an active workitem for this participant.
+  # Destroys the job from the Resque queue.
+  #
+  # Note that if the job is being processed by the worker or if the job has been processed but the reply has not,
+  # this method will do nothing.
+  # @return [Boolean] wether the job was deleted or not.
+  def on_cancel
+
+    payload = encode_workitem(applied_workitem)
+    ::Resque::Job.destroy(@job_queue, @job_klass, payload)
+
+  end
+
+  # Returns a representation of a workitem that is suitable for use in Resque.
+  # @param [Ruote::Workitem] workitem
+  # @return [Hash] the workitem as a hash
+  def encode_workitem(workitem)
+
+    workitem.to_h
+
+  end
+
+  # Returns true because enqueing a job in Resque is sufficiently fast to happen in the main thread.
+  # @return [true]
+  def do_not_thread
+    true
+  end
+end