que-rails 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 0a34fa7c415b733e7f209815c1e0c7e86fe97b05
+  data.tar.gz: c1f2c10098b3a8357e239b441fd3f340115e6322
+SHA512:
+  metadata.gz: 55be461274eee4ec9a36d8076df7571ac040b5eaa670a2e7ff7501282d2f89baef51c87f8b3e784a1fd219145ac25f8f81bd764dd84f3a119f7666ad80022466
+  data.tar.gz: dff6ae37ab8bc01943a5a043465ed6bd8959302eca679433c953f6c41ea4468b943622b26f2d3a75e3dcd0840504e3bb8317e14490688b8af0ee43095c612d52

data/.gitignore

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

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--order random

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in que-rails.gemspec
+gemspec
+
+group :test do
+  gem 'rspec', '~> 2.14.1'
+  gem 'pry'
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Chris Hanks
+
+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,178 @@
+# que-rails (Unreleased, do not use)
+
+`que-rails` contains assorted tools that integrate the [Que job queue](https://github.com/chanks/que) into a Rails application. It provides rake tasks and a railtie that handles spinning up the background worker pool.
+
+This document covers basic information on setting up and using Que in a standard Rails application, and assumes you're using Rails 4. *`que-rails` isn't tested with versions of Rails before 4, and may or may not work with them.* For information on more advanced usage of Que, see its [documentation](https://github.com/chanks/que/tree/master/docs).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'que-rails'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install que-rails
+
+## Usage
+
+First, generate and run a migration for the `que_jobs` table.
+
+    $ bin/rails generate que:install
+    $ bin/rake db:migrate
+
+Create a class for each type of job you want to run:
+
+``` ruby
+# app/jobs/charge_credit_card.rb
+class ChargeCreditCard < Que::Job
+  # Default settings for this job. These are optional - without them, jobs
+  # will default to priority 100 and run immediately.
+  @priority = 10
+  @run_at = proc { 1.minute.from_now }
+
+  def run(user_id, options)
+    # Do stuff.
+    user = User.find(user_id)
+    card = CreditCard.find(options[:credit_card_id])
+
+    ActiveRecord::Base.transaction do
+      # Write any changes you'd like to the database.
+      user.update :charged_at => Time.now
+      card.update :charged_at => Time.now
+
+      # It's best to destroy the job in the same transaction as any other
+      # changes you make. Que will destroy the job for you after the run
+      # method if you don't do it yourself, but if your job writes to the
+      # DB but doesn't destroy the job in the same transaction, it's
+      # possible that the job could be repeated in the event of a crash.
+      destroy
+    end
+  end
+end
+```
+
+See the docs on [how to write a reliable job](https://github.com/chanks/que/blob/master/docs/writing_reliable_jobs.md) for more information on writing different types of jobs safely.
+
+Queue your job. Again, it's best to do this in a transaction with other changes you're making. Also note that any arguments you pass will be serialized to JSON and back again, so stick to simple types (strings, integers, floats, hashes, and arrays).
+
+``` ruby
+ActiveRecord::Base.transaction do
+  # Persist credit card information
+  card = CreditCard.create(params[:credit_card])
+  ChargeCreditCard.enqueue(current_user.id, :credit_card_id => card.id)
+end
+```
+
+You can also add options to run the job after a specific time, or with a specific priority:
+
+``` ruby
+# The default priority is 100, and a lower number means a higher priority. 5 would be very important.
+ChargeCreditCard.enqueue current_user.id, :credit_card_id => card.id, :run_at => 1.day.from_now, :priority => 5
+```
+
+To determine what happens when a job is queued, you can set Que's mode in your application configuration. There are a few options for the mode:
+
+  * `config.que.mode = :off` - In this mode, queueing a job will simply insert it into the database - the current process will make no effort to run it. You should use this if you want to use a dedicated process to work tasks (there's a rake task to do this, see below). This is the default when running `bin/rails console`.
+  * `config.que.mode = :async` - In this mode, a pool of background workers is spun up, each running in their own thread. This is the default when running `bin/rails server`. See the docs for [more information on managing workers](https://github.com/chanks/que/blob/master/docs/managing_workers.md).
+  * `config.que.mode = :sync` - In this mode, any jobs you queue will be run in the same thread, synchronously (that is, `MyJob.enqueue` runs the job and won't return until it's completed). This makes your application's behavior easier to test, so it's the default in the test environment.
+
+If you're using ActiveRecord to dump your database's schema, you'll probably want to [set schema_format to :sql](http://guides.rubyonrails.org/migrations.html#types-of-schema-dumps) so that Que's table structure is managed correctly.
+
+### Forking Servers
+
+If you want to run a worker pool in your web process and you're using a forking webserver like Phusion Passenger (in smart spawning mode), Unicorn or Puma (in some configurations), you'll want to set `Que.mode = :off` in your application configuration and only start up the worker pool in the child processes after the DB connection has been reestablished.
+
+#### Puma
+
+    # config/puma.rb
+    on_worker_boot do
+      ActiveRecord::Base.establish_connection
+
+      Que.mode = :async
+    end
+
+#### Unicorn
+
+    # config/unicorn.rb
+    after_fork do |server, worker|
+      ActiveRecord::Base.establish_connection
+
+      Que.mode = :async
+    end
+
+#### Phusion Passenger
+
+    # config.ru
+    if defined?(PhusionPassenger)
+      PhusionPassenger.on_event(:starting_worker_process) do |forked|
+        if forked
+          Que.mode = :async
+        end
+      end
+    end
+
+### Other ORMs
+
+If you're using an ORM other than ActiveRecord, you'll need to pass Que the connection manually. For instance, if you're using Sequel, you could do this after you initialize the database connection:
+
+    # config/initializers/sequel.rb
+    DB = Sequel.connect(ENV['DATABASE_URL'])
+    Que.connection = DB
+
+### Rake Tasks
+
+If you don't want to burden your web processes with too much work and want to run workers in a background process instead, similar to how most other queues work, `que-rails` provides a rake task:
+
+    # Run a pool of 4 workers:
+    rake que:work
+
+    # Or configure the number of workers:
+    QUE_WORKER_COUNT=8 rake que:work
+
+Other options available via environment variables are `QUE_QUEUE` to determine which named queue jobs are pulled from, and `QUE_WAKE_INTERVAL` to determine how long workers will wait to poll again when there are no jobs available. For example, to run 2 workers that run jobs from the "other_queue" queue and wait a half-second between polls, you could do:
+
+    QUE_QUEUE=other_queue QUE_WORKER_COUNT=2 QUE_WAKE_INTERVAL=0.5 rake que:work
+
+### Additional Configuration
+
+You can use the config.que object in your application config files to do whatever other setup you'd like. For example, you'll probably want to define an error handler, in order to pass errors raised by jobs to whatever tracking system you use:
+
+    config.que.error_handler = proc { |error| ... }
+
+You can also manually set the number of workers in each process:
+
+    config.que.worker_count = 8
+
+### Thread Safety
+
+If your application code is not thread-safe, you won't want any workers to be processing jobs while anything else is happening in the Ruby process. So, you'll want to turn the worker pool off by default:
+
+    config.que.mode = :off
+
+This will prevent Que from trying to process jobs in the background of your web processes. In order to actually work jobs, you'll want to run a single worker at a time, and to do so via a separate rake task, like so:
+
+    QUE_WORKER_COUNT=1 rake que:work
+
+## Gem TODO
+
+- Spec multiple versions of Rails, not just one.
+- Spec the `rake que:work` task and its various options.
+- Spec the generator more thoroughly.
+- Spec that things don't fail when ActiveRecord isn't being used.
+- Spec that Que can be configured successfully in an initializer or in the application or environment config files. This includes things like wake_interval, worker_count, etc.
+- Spec that the worker pool starts up when Rails is running as a server, but not when running as a console or when running other rake tasks (like `db:migrate` or `routes`).
+- Spec that the code samples for using Que with forking webservers all work (Unicorn, Phusion Passenger, Puma).
+- Add handlers for common error services (Honeybadger, etc).
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/que-rails/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

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

data/lib/generators/que/install_generator.rb

@@ -0,0 +1,22 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'active_record'
+
+module Que
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
+
+    namespace 'que:install'
+    self.source_paths << File.join(File.dirname(__FILE__), 'templates')
+    desc "Generates a migration to add Que's job table."
+
+    def self.next_migration_number(dirname)
+      next_migration_number = current_migration_number(dirname) + 1
+      ActiveRecord::Migration.next_migration_number(next_migration_number)
+    end
+
+    def create_migration_file
+      migration_template 'add_que.rb', 'db/migrate/add_que.rb'
+    end
+  end
+end

data/lib/generators/que/templates/add_que.rb

@@ -0,0 +1,11 @@
+class AddQue < ActiveRecord::Migration
+  def self.up
+    # The current version as of this migration's creation.
+    Que.migrate! :version => 3
+  end
+
+  def self.down
+    # Completely removes Que's job queue.
+    Que.migrate! :version => 0
+  end
+end

data/lib/que-rails.rb

@@ -0,0 +1 @@
+require 'que/rails'

data/lib/que/rails.rb

@@ -0,0 +1,9 @@
+require 'rails'
+require 'que'
+require 'que/rails/railtie'
+require 'que/rails/version'
+
+module Que
+  module Rails
+  end
+end

data/lib/que/rails/railtie.rb

@@ -0,0 +1,30 @@
+module Que
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.que = Que
+
+      Que.logger     = proc { ::Rails.logger }
+      Que.mode       = :sync if ::Rails.env.test?
+      Que.connection = ::ActiveRecord if defined? ::ActiveRecord
+
+      rake_tasks do
+        load 'que/rails/rake_tasks.rb'
+      end
+
+      initializer 'que.setup' do
+        ::ActiveSupport.on_load :after_initialize do
+          # Only start up the worker pool if running as a server.
+          Que.mode ||= defined?(::Rails::Server) ? :async : :off
+
+          at_exit do
+            if Que.mode == :async
+              $stdout.puts "Finishing Que's current jobs before exiting..."
+              Que.mode = :off
+              $stdout.puts "Que's jobs finished, exiting..."
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/que/rails/rake_tasks.rb

@@ -0,0 +1,46 @@
+namespace :que do
+  desc "Process Que's jobs using a worker pool"
+  task :work => :environment do
+    require 'logger'
+
+    Que.logger        = Logger.new(STDOUT)
+    Que.logger.level  = Logger.const_get((ENV['QUE_LOG_LEVEL'] || 'INFO').upcase)
+    Que.worker_count  = (ENV['QUE_WORKER_COUNT'] || 4).to_i
+    Que.wake_interval = (ENV['QUE_WAKE_INTERVAL'] || 0.1).to_f
+    Que.mode          = :async
+
+    # When changing how signals are caught, be sure to test the behavior with
+    # the rake task in tasks/safe_shutdown.rb.
+
+    stop = false
+    %w( INT TERM ).each do |signal|
+      trap(signal) {stop = true}
+    end
+
+    at_exit do
+      $stdout.puts "Finishing Que's current jobs before exiting..."
+      Que.mode = :off
+      $stdout.puts "Que's jobs finished, exiting..."
+    end
+
+    loop do
+      sleep 0.01
+      break if stop
+    end
+  end
+
+  desc "Migrate Que's job table to the most recent version (creating it if it doesn't exist)"
+  task :migrate => :environment do
+    Que.migrate! :version => (ENV['QUE_MIGRATE_VERSION'] || Que::Migrations::CURRENT_VERSION).to_i
+  end
+
+  desc "Drop Que's job table"
+  task :drop => :environment do
+    Que.drop!
+  end
+
+  desc "Clear Que's job table"
+  task :clear => :environment do
+    Que.clear!
+  end
+end

data/lib/que/rails/version.rb

@@ -0,0 +1,5 @@
+module Que
+  module Rails
+    VERSION = '0.0.1'
+  end
+end

data/que-rails.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'que/rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'que-rails'
+  spec.version       = Que::Rails::VERSION
+  spec.authors       = ["Chris Hanks"]
+  spec.email         = ["christopher.m.hanks@gmail.com"]
+  spec.summary       = %q{Que for Rails}
+  spec.description   = %q{Railtie, Generators and other magic to integrate the Que job queue with Rails applications.}
+  spec.homepage      = 'https://github.com/chanks/que-rails'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'que', '~> 0.9'
+  spec.add_dependency 'railties', '~> 4.1.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'sequel'
+  spec.add_development_dependency 'pg'
+end

data/spec/configuration_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe "Que::Rails::Railtie" do
+  it "should set Que's logger to the Rails logger" do
+    rails_runner('puts Que.logger == Rails.logger').should == 'true'
+  end
+
+  it "should use ActiveRecord's DB connection" do
+    rails_runner('puts Que.execute("SELECT 1 AS one")').should == '{"one"=>1}'
+  end
+
+  it "should leave Que off by default when run as rails runner" do
+    rails_runner('puts Que.mode.inspect').should == ':off'
+  end
+
+  it "should start Que in :sync mode when in test mode" do
+    rails_runner('puts Que.mode.inspect', :variables => 'RAILS_ENV=test').should == ':sync'
+  end
+end

data/spec/rake_tasks_spec.rb

@@ -0,0 +1,23 @@
+require 'spec_helper'
+
+describe "que-rails rake tasks" do
+  it "should include a task for migrating Que's job table" do
+    in_path($app_copy_path) do
+      DB.table_exists?(:que_jobs).should be true
+      `QUE_MIGRATE_VERSION=0 rake que:migrate`
+      DB.table_exists?(:que_jobs).should be false
+      `rake que:migrate`
+      DB.table_exists?(:que_jobs).should be true
+
+      DB[:que_jobs].insert(job_class: 'Que::Job')
+      DB[:que_jobs].count.should == 1
+      `rake que:clear`
+      DB[:que_jobs].count.should == 0
+
+      `rake que:drop`
+      DB.table_exists?(:que_jobs).should be false
+      `rake que:migrate`
+      DB.table_exists?(:que_jobs).should be true
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,40 @@
+require 'sequel'
+
+DB = Sequel.connect ENV['DATABASE_URL'] || "postgres:///que_rails_test_app_development"
+
+require 'support/helpers'
+
+puts "Testing Que's integration with #{`rails -v`}"
+
+$test_app_path = "spec/tmp/que_rails_test_app"
+$app_copy_path = "spec/tmp/app_copy"
+
+FileUtils.rm_rf($test_app_path)
+FileUtils.rm_rf($app_copy_path)
+
+# Drop spec directory.
+directory = File.dirname(__FILE__).split('/')[0..-2].join('/')
+
+# Skip bundle install until we add que-rails.
+`rails new #{$test_app_path} -B -d postgresql`
+
+append_to_file "#{$test_app_path}/Gemfile", "gem 'que-rails', :path => '#{directory}'"
+
+in_path $test_app_path do
+  `bundle`
+  `rails generate que:install`
+  `rake db:drop`
+  `rake db:create`
+  `rake db:migrate`
+end
+
+FileUtils.cp_r($test_app_path, $app_copy_path)
+
+# def add_to_config(str)
+#   environment = File.read("#{$app_copy_path}/config/application.rb")
+#   if environment =~ /(\n\s*end\s*end\s*)\Z/
+#     File.open("#{$app_copy_path}/config/application.rb", 'w') do |f|
+#       f.puts $` + "\n#{str}\n" + $1
+#     end
+#   end
+# end

data/spec/support/helpers.rb

@@ -0,0 +1,11 @@
+def append_to_file(file, text)
+  File.open(file, 'a') { |f| f.puts text }
+end
+
+def in_path(path, &block)
+  Bundler.with_clean_env { Dir.chdir(path, &block) }
+end
+
+def rails_runner(ruby, options = {})
+  in_path($app_copy_path) { `#{options[:variables]} rails r '#{ruby}'`.strip }
+end

metadata

@@ -0,0 +1,151 @@
+--- !ruby/object:Gem::Specification
+name: que-rails
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Chris Hanks
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: que
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Railtie, Generators and other magic to integrate the Que job queue with
+  Rails applications.
+email:
+- christopher.m.hanks@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/que/install_generator.rb
+- lib/generators/que/templates/add_que.rb
+- lib/que-rails.rb
+- lib/que/rails.rb
+- lib/que/rails/railtie.rb
+- lib/que/rails/rake_tasks.rb
+- lib/que/rails/version.rb
+- que-rails.gemspec
+- spec/configuration_spec.rb
+- spec/rake_tasks_spec.rb
+- spec/spec_helper.rb
+- spec/support/helpers.rb
+homepage: https://github.com/chanks/que-rails
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Que for Rails
+test_files:
+- spec/configuration_spec.rb
+- spec/rake_tasks_spec.rb
+- spec/spec_helper.rb
+- spec/support/helpers.rb