localjob 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: becc6c53c0de0692e654c0e4fd8b220b13baa424
+  data.tar.gz: 770a92796d0fedf97c3d66728e039b3d966e7f92
+SHA512:
+  metadata.gz: f56f0b1ae32cda8650cd0e6375278ad34bf16c00db257a180d1070c980c7eee422f7e604afcbbe013c7da7c0ae403d2f0a7c795987fd52330f101fd19f3a985e
+  data.tar.gz: 3ecf92a571bd824625ea348b5f0ccdf8e4f5b7e3ba2fc3ab468a1915c90a768f5a250803d71a8a1caf41387c21d237320f605c250e6edcf4bdbcc035d4b1c90f

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/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in localjob.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Simon Eskildsen
+
+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,57 @@
+# Localjob
+
+Localjob is a simple, self-contained background queue built on top of [POSIX
+message queues][pmq]. Workers and the app pushing to the queue must reside on
+the same machine. It's the sqlite of background queues (although sqlite scales
+further than Localjob). Here's a post about [how it works][blog].
+
+Localjob is for early-development situations where you don't need a
+full-featured background queue, but just want to get started with something
+simple that does not rely on any external services. A bigger goal with the
+project is to be able to migrate to another background queue system by switching
+adapter: `Localjob.adapter = Resque` to switch to Resque, without changes to
+your own code.
+
+The POSIX message queue is persistent till reboot. You will need to tune system
+parameters for your application, please consult [posix-mqueue][pmq-gem]'s
+documentation.
+
+Localjob works on Ruby >= 2.0.0 and Linux.
+
+WIP not everything works as advertised, but try it out and report anything that
+doesn't work! It's not released as a gem yet, so add the following to your
+Gemfile to use it:
+
+```ruby
+gem 'localjob', git: "git@github.com:Sirupsen/localjob.git"
+```
+
+## Usage
+
+Localjobs have the following format:
+
+```ruby
+class EmailJob
+  def initialize(user_id, email)
+    @user, @email = User.find(user_id), email
+  end
+
+  def perform
+    @email.deliver_to(@user)
+  end
+end
+```
+
+To queue a job, create an instance of it and push it to the queue:
+
+```ruby
+queue = Localjob.new
+queue << EmailJob.new(current_user.id, welcome_email)
+```
+
+Then spawn a worker with `localjob work`. It takes a few arguments, like `-d` to
+deamonize itself. `localjob help work` to list all options.
+
+[pmq]: http://linux.die.net/man/7/mq_overview
+[pmq-gem]: https://github.com/Sirupsen/posix-mqueue
+[blog]: http://sirupsen.com/unix-background-queue/

data/Rakefile

@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+task :default => :test
+
+require 'rake/testtask'
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+end

data/bin/localjob

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+require 'localjob'
+require 'localjob/cli'
+
+Localjob::CLI.start(ARGV)

data/lib/localjob/channel.rb

@@ -0,0 +1,25 @@
+class Localjob
+  class Channel
+    attr_accessor :queues
+
+    def initialize(queues)
+      @queues = [queues].flatten.map { |q| queue_from_name(q) }
+    end
+
+    def <<(queue)
+      @queues << queue_from_name(queue)
+    end
+
+    def shift
+      (queue,), = IO.select(@queues)
+      queue.shift
+    rescue POSIX::Mqueue::QueueEmpty
+      retry
+    end
+
+    private
+    def queue_from_name(queue)
+      queue.instance_of?(Localjob) ? queue : Localjob.new(queue)
+    end
+  end
+end

data/lib/localjob/cli.rb

@@ -0,0 +1,66 @@
+require 'thor'
+
+class Localjob
+  class CLI < Thor
+    option :queues,    aliases: ["-q"], type: :string, default: "localjob"
+    option :require,   aliases: ["-r"], type: :string, default: "."
+    option :pid_file,  aliases: ["-p"], type: :string
+    option :daemon,    aliases: ["-d"], type: :boolean
+    desc "work", "Start worker to process jobs"
+    def work
+      load_environment options[:require]
+
+      queues = options[:queues].split(",")
+      Localjob::Worker.new(queues, options.slice(:daemon, :pid_file)).work
+    end
+
+    desc "size", "Outputs the size of queues"
+    option :queues, aliases: ["-q"], type: :string, default: "localjob"
+    def size
+      queues = options[:queues].split(",")
+      queues.each do |queue|
+        puts "Size of /#{queue}: #{Localjob.new(queue).size}/#{msg_max}"
+      end
+    end
+
+    desc "destroy", "Destroys all queues passed"
+    option :queues, aliases: ["-q"], type: :string, default: "localjob"
+    def destroy
+      options[:queues].split(",").each do |queue|
+        Localjob.new(queue).destroy
+      end
+    end
+
+    desc "list", "Lists all queues"
+    def list
+      unless File.exists?("/dev/mqueue")
+        system "mkdir /dev/mqueue"
+        system "mount -t mqueue none /dev/mqueue"
+      end
+
+      system "ls -l /dev/mqueue"
+    end
+
+    private
+    def load_environment(file)
+      if rails?(file)
+        require 'rails'
+        require File.expand_path("#{file}/config/environment.rb")
+        ::Rails.application.eager_load!
+      elsif File.file?(file)
+        require File.expand_path(file)
+      else
+        puts "No require path passed, requires -r if not in Rails"
+        exit
+      end
+    end
+
+    def rails?(file)
+      File.exists?(File.expand_path("#{file}/config/environment.rb"))
+    end
+
+    def msg_max
+      @msg_max ||= File.read("/proc/sys/fs/mqueue/msg_max")
+    end
+  end
+end

data/lib/localjob/version.rb

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

data/lib/localjob/worker.rb

@@ -0,0 +1,65 @@
+class Localjob
+  class Worker
+    attr_accessor :logger, :channel
+    attr_reader :options
+
+    def initialize(queues, logger: Logger.new(STDOUT), **options)
+      @channel, @logger = Channel.new(queues), logger
+      @options = options
+      @shutdown = false
+    end
+
+    def process(job)
+      logger.info "Worker #{pid}: #{job.inspect}"
+      job.perform
+    end
+
+    def pid
+      Process.pid
+    end
+
+    def work
+      logger.info "Worker #{pid} now listening!"
+      trap_signals
+      create_pid_file(@options[:pid_file])
+      deamonize if @options[:deamon]
+      loop { shift_and_process }
+    end
+
+    private
+
+    def shift_and_process
+      exit! if @shutdown
+
+      job = wait { @channel.shift }
+      process job
+    rescue Object => e
+      logger.error "Worker #{pid} job failed: #{job}"
+      logger.error "#{$!}\n#{$@.join("\n")}"
+    end
+
+    def trap_signals
+      Signal.trap("QUIT") { graceful_shutdown }
+    end
+
+    def wait
+      @waiting = true
+      job = yield
+      @waiting = false
+      job
+    end
+
+    def deamonize
+      Process.daemon(true, true)
+    end
+
+    def create_pid_file(path)
+      File.open(path, 'w') { |f| f << self.pid } if path
+    end
+
+    def graceful_shutdown
+      exit! if @waiting
+      @shutdown = true
+    end
+  end
+end

data/lib/localjob.rb

@@ -0,0 +1,48 @@
+require 'posix/mqueue'
+require 'yaml'
+require 'logger'
+
+require "localjob/version"
+require 'localjob/channel'
+require 'localjob/worker'
+
+class Localjob
+  attr_reader :queue_name
+
+  def initialize(queue = "localjob")
+    @queue_name = fix_queue_name(queue)
+  end
+
+  def serializer
+    YAML
+  end
+
+  def queue
+    @queue ||= POSIX::Mqueue.new(@queue_name)
+  end
+
+  def <<(object)
+    queue.timedsend serializer.dump(object)
+  end
+
+  def size
+    queue.size
+  end
+
+  def shift
+    serializer.load queue.timedreceive
+  end
+
+  def destroy
+    queue.unlink
+  end
+
+  def to_io
+    queue.to_io
+  end
+
+  private
+  def fix_queue_name(queue)
+    queue.start_with?('/') ? queue : "/#{queue}"
+  end
+end

data/localjob.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'localjob/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "localjob"
+  spec.version       = Localjob::VERSION
+  spec.authors       = ["Simon Eskildsen"]
+  spec.email         = ["sirup@sirupsen.com"]
+  spec.description   = %q{Simple, self-contained background queue built on top of POSIX message queues.}
+  spec.summary       = %q{Simple, self-contained background queue built on top of POSIX message queues. It only works on Linux.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  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 "posix-mqueue", "0.0.9"
+  spec.add_dependency "thor", "0.18.1"
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "mocha"
+end

data/test/jobs.rb

@@ -0,0 +1,11 @@
+class WalrusJob < Struct.new(:action)
+  def perform
+    "Nice try, but there's no way I'll #{action}.."
+  end
+end
+
+class AngryWalrusJob < Struct.new(:angryness)
+  def perform
+    raise "I am this angry: #{angryness}"
+  end
+end

data/test/localjob_test.rb

@@ -0,0 +1,36 @@
+require 'test_helper'
+
+class LocaljobTest < LocaljobTestCase
+  def setup
+    @localjob = queue
+  end
+
+  def test_push_should_put_a_job_in_queue
+    @localjob << WalrusJob.new("move")
+    assert_equal 1, @localjob.size
+  end
+
+  def test_pop_from_queue
+    @localjob << WalrusJob.new("move")
+
+    job = @localjob.shift
+    assert_instance_of WalrusJob, job
+    assert_equal "move", job.action
+  end
+
+  def test_throws_error_if_message_is_too_large
+    assert_raises Errno::EMSGSIZE do
+      @localjob << AngryWalrusJob.new("f" * @localjob.queue.msgsize)
+    end
+  end
+
+  def test_handles_multiple_queues
+    @localjob << WalrusJob.new("move")
+
+    other = queue("other-queue")
+    other << WalrusJob.new("dance")
+
+    assert_equal 1, @localjob.size
+    assert_equal 1, other.size
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,44 @@
+require 'minitest/unit'
+require 'minitest/autorun'
+$:<< File.dirname(__FILE__) + "/../lib"
+require 'localjob'
+require "mocha/setup"
+require 'jobs'
+
+class LocaljobTestCase < MiniTest::Unit::TestCase
+  protected
+  # This is a method to make sure the logger is set right.
+  def worker(queues = ["/localjob-test"])
+    Localjob::Worker.new(queues, logger: logger)
+  end
+
+  # This is a method to make sure all queues are registred and destroyed after
+  # each teach run.
+  def queue(name = "/localjob-test")
+    @queues ||= []
+    queue = Localjob.new(name)
+    @queues << queue
+    queue
+  end
+
+  def teardown
+    clear_queue
+  end
+
+  def logger
+    return @logger if @logger
+
+    output_file = ENV["DEBUG"] ? STDOUT : "/dev/null"
+    @logger = Logger.new(output_file)
+  end
+
+  def clear_queue
+    @queues.each(&:destroy) if @queues
+
+    # This forces the GC to garbage collect, and thus close file descriptioners
+    # in POSIX::Mqueue. Otherwise we'll get flooded with warnings. This is to
+    # ensure a clean state everytime with a new message queue for each test.
+    # It's slower. But safe.
+    GC.start
+  end
+end

data/test/worker_test.rb

@@ -0,0 +1,85 @@
+require 'test_helper'
+
+class WorkerTest < LocaljobTestCase
+  def setup
+    @localjob = queue
+    @worker   = worker
+  end
+
+  def test_pop_and_send_to_worker
+    WalrusJob.any_instance.expects(:perform)
+
+    @localjob << WalrusJob.new("move")
+
+    job = @localjob.shift
+    @worker.process(job)
+  end
+
+  def test_working_off_queue_in_child
+    @localjob << WalrusJob.new("move")
+
+    fork do
+      job = @localjob.shift
+      @worker.process(job)
+    end
+
+    Process.wait
+    assert_equal 0, @localjob.size
+  end
+
+  def test_sigquit_terminates_the_worker
+    @localjob << WalrusJob.new("move")
+
+    assert_equal 1, @localjob.size
+
+    pid = fork { @worker.work }
+
+    Process.kill("QUIT", pid)
+    Process.wait
+
+    assert_equal 0, @localjob.size
+  end
+
+  def test_doesnt_stop_on_error
+    @localjob << AngryWalrusJob.new(100)
+    @localjob << WalrusJob.new("be happy")
+
+    pid = fork { @worker.work }
+
+    # Hack to account for race condition, 0.01s should be plenty
+    sleep 0.01
+    Process.kill("QUIT", pid)
+    Process.wait
+
+    assert_equal 0, @localjob.size
+  end
+
+  def test_workers_listen_on_multiple_queues
+    @localjob << WalrusJob.new("move")
+
+    other = queue("other-queue")
+    other << WalrusJob.new("dance")
+
+    @worker.channel << 'other-queue'
+
+    pid = fork { @worker.work }
+
+    # Hack to account for race condition, 0.01s should be plenty
+    sleep 0.01
+    Process.kill("QUIT", pid)
+    Process.wait
+
+    assert_equal 0, @localjob.size
+    assert_equal 0, other.size
+  end
+
+  def test_worker_doesnt_die_on_bad_serialization
+    @localjob.queue.timedsend "--- !ruby/object:Whatever {}\n"
+
+    pid = fork { @worker.work }
+
+    sleep 0.01
+    Process.kill("QUIT", pid)
+    Process.wait
+  end
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: localjob
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Simon Eskildsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: posix-mqueue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.0.9
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !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: mocha
+  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: Simple, self-contained background queue built on top of POSIX message
+  queues.
+email:
+- sirup@sirupsen.com
+executables:
+- localjob
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/localjob
+- lib/localjob.rb
+- lib/localjob/channel.rb
+- lib/localjob/cli.rb
+- lib/localjob/version.rb
+- lib/localjob/worker.rb
+- localjob.gemspec
+- test/jobs.rb
+- test/localjob_test.rb
+- test/test_helper.rb
+- test/worker_test.rb
+homepage: ''
+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.0.3
+signing_key: 
+specification_version: 4
+summary: Simple, self-contained background queue built on top of POSIX message queues.
+  It only works on Linux.
+test_files:
+- test/jobs.rb
+- test/localjob_test.rb
+- test/test_helper.rb
+- test/worker_test.rb