q 0.0.0 → 0.0.1

data/README.md

@@ -1,24 +1,179 @@
-q is for Journal
-================
-
-Why 'q'?  Because 'j' was alread established as a rubygem
-and I wanted to completely re-write ["j is for Journal"](https://github.com/hooobs/j) 
-because it's been a failed attempt from the start.
-
-What is 'q'?  It's a command-line activity tracker.  You tell
-it what you're working on and (optionally) when you worked on 
-it in natural language and it'll record that information for you.
-
-The app is backed by sqlite, so no messy text files are necessary and
-hopefully search features will be easy to implement.
-
-Laundry List
-------------
-
- * add entries for the current time
- * add entries for past and future dates in natural language (chronic)
- * list entries with pretty formatting and fuzzy time (also chronic)
- * search entries
- * hash tags
- * some kind of fancy interbutt/cloud integration
- * import/export feature
+## Q
+
+Forget queue boilerplate: focus on your code.
+
+## Install
+
+In your `Gemfile` add:
+
+```ruby
+gem 'q'
+```
+
+Then run `$ bundle install`
+
+## What
+
+Q is an interface for your background queues. Are you using Resque, Sidekiq, delayed_job, queue_classic, or some other queue? Awesome sauce, because with `Q` you can write your queuing code once and re-use against different backends.
+
+```ruby
+Q.setup do |config|
+  config.queue = :resque
+end
+```
+
+Now in your code when you need to enqueue something first you need to add the `Q::Methods` module:
+
+```ruby
+class Poro
+  include Q::Methods
+end
+```
+
+Now you can define tasks using the `queue` class method like this:
+
+```ruby
+class Poro
+  include Q::Methods
+
+  queue(:send_issues) do |id, state|
+    user   = User.find(id)
+    issues = user.issues.where(state: state).all
+    UserMailer.send_issues(user: user, issues: issues).deliver
+  end
+end
+```
+
+Here we're building a background task called `send_issues` that will send out an email when executed.
+
+Now that the task is defined, you can enqueue a `send_issues` job to be executed later by calling `queue` and then `send_issues` like this:
+
+```ruby
+user  = User.last
+state = 'open'
+Poro.queue.send_issues(user.id, state)
+```
+
+The Q interface expects json-able objects, numbers, arrays, hashes, etc. This is important if you want your code to be re-usable across multiple queue backends.
+
+## No Queue? No Problem
+
+The `Q` library comes with a threaded queue that does not need a backend (such as Redis) by default, so you can write your code today and figure out what queue you want to use tomorrow.
+
+Note: that this threaded queue is very basic and should not be used in production. If you stop your Ruby process while there are jobs in memory you will lose your jobs see [threaded_in_memory_queue](https://github.com/schneems/threaded_in_memory_queue) for more information.
+
+## Starting your Queue
+
+Most background queue libraries must be run in a seperate process. The `Q` library makes starting these background tasks easy.
+
+Make sure there is a Rake task named `:environment` that loads your app (Rails provides one by default). Then add this line to your `Procfile`:
+
+```
+worker: bundle exec rake q:work
+```
+
+Now if you are running on Heroku the background task will automatically be run. Locally you can run the task manually by executing:
+
+```sh
+$ bundle exec rake q:work
+```
+
+Or through your `Procfile` with foreman:
+
+```sh
+$ foreman start
+```
+
+If your queueing library supports any custom environment variables or flags you can add them to your `rake q:work` command and they will be passed to the supporting background queue's task.
+
+Note: the default threaded queue does not need to be started as it runs in your web process
+
+## Config
+
+You can configure the behavior of your background queue using `Q.queue_config`. For example if you are using Resque and want to run commands inline you could execute:
+
+```ruby
+Q.queue_config.inline = true
+```
+
+Now any calls to `enqueue` will bypass resque and be run immediately. Different queues will have different configuration options so you will need to see their docs for configuration options.
+
+You can access this config in the setup command:
+
+```ruby
+Q.setup do |config|
+  config.queue = :resque
+  config.queue_config.inline = true
+end
+```
+
+It also accepts a block:
+
+```ruby
+Q.queue_config do |config|
+  config.inline = true
+end
+```
+
+Don't confuse `queue_config` which will configure your background queue (such as Resque) with `setup` which configures the `Q` library itself.
+
+## Diverging Backends
+
+As much as we try to make all front end code similar, you'll still need to setup your queue. To make sqitching back and forth easier, we provide a `Q.env` object that responds to the backend you are using such as `Q.env.resque?`.
+
+That way you could keep multiple queue configurations in your app and it won't raise any errors if you're running a different backend.
+
+```ruby
+if Q.env.resque?
+  # config resque here
+end
+
+if Q.env.sidekiq?
+  # configure sidekiq here
+else
+```
+
+## Supported Queue Backends
+
+```
+config.queue = :sidekiq
+config.queue = :resque
+config.queue = :threaded
+```
+
+Coming soon:
+
+```
+config.queue = :delayed_job
+```
+
+
+
+## Blocks
+
+You can set default values in blocks like this:
+
+```ruby
+queue(:foo) do |id, state = 'open', username = 'schneems'|
+  # ...
+end
+```
+
+You can have an unlimited amount of args using a splat:
+
+```ruby
+queue(:foo) do |id, *args|
+  # ...
+end
+```
+
+
+## Q Authors
+
+Did you write a background queuing library? Want to add support for the `Q` interface? Check out the [QUEUE_AUTHORS.md](QUEUE_AUTHORS.md) file to get started.
+
+## License
+
+Brought to you by [@schneems](http://twitter.com/schneems)
+
+MIT

data/Rakefile

@@ -1 +1,14 @@
+# encoding: UTF-8
 require 'bundler/gem_tasks'
+
+require 'rake'
+require 'rake/testtask'
+
+task :default => [:test]
+
+test_task = Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end

data/lib/q.rb

@@ -1,5 +1,82 @@
-require "q/version"
+require 'proc_to_lambda'
 
 module Q
-  # Your code goes here...
+  class Queue
+  end
 end
+
+require 'q/version'
+require 'q/helpers'
+require 'q/errors'
+require 'q/methods/base'
+require 'q/methods'
+require 'q/tasks'
+
+module Q
+  extend Q::Helpers
+  DEFAULT_QUEUE = ->{ @env = :threaded; Q::Methods::Threaded }
+  FALSEY_HASH   = Hash.new(false)
+
+  def self.queue
+    @queue_method || DEFAULT_QUEUE.call
+  end
+
+  def self.setup(&block)
+    yield self
+  end
+
+  def self.env
+    name = queue.to_s.split("::").last
+    @env ||= Q.underscore(name)
+
+    OpenStruct.new(FALSEY_HASH.merge("#{@env}?" => true))
+  end
+
+  def self.reset_queue!
+    @queue_method = nil
+    @env          = nil
+  end
+
+  def self.module_from_klass_name(name)
+    unless defined?(Q::Methods.const_get(name))
+      require "q/methods/#{name}"
+    end
+    return Q::Methods.const_get(name)
+  rescue LoadError => e
+    raise LoadError, "Could not find queue: #{name}, expected to be defined in q/methods/#{name}\n" + e.message
+  rescue NameError => e
+    raise NameError, "Could not load queue: #{name}, expected to be defined in q/methods/#{name}\n" + e.message
+  end
+
+  def self.module_from_queue_name(queue_name)
+    module_from_klass_name(camelize(queue_name))
+  end
+
+  def self.queue_lookup
+    @queue_lookup ||= Hash.new do |hash, key|
+      hash[key] = -> {
+        require "q/methods/#{key}"
+        const = Q.camelize(key)
+        ::Q::Methods.const_get(const)
+      }
+    end
+    @queue_lookup
+  end
+
+  def self.queue=(queue)
+    if queue.is_a?(Module)
+      @queue_method = queue
+    else
+      @env = queue
+      @queue_method = queue_lookup[queue].call
+    end
+  end
+
+  def self.queue_config(&block)
+    @config_class ||= queue::QueueConfig.call
+    yield @config_class if block_given?
+    @config_class
+  end
+end
+
+require 'q/methods/threaded_in_memory_queue'

data/lib/q/errors.rb

@@ -0,0 +1,32 @@
+module Q
+  class StandardError < ::StandardError; end
+
+  class MissingClassError < StandardError
+    def initialize(base, missing_klass)
+      msg = "#{base} must define '#{missing_klass}' class with a call method"
+      super(msg)
+    end
+  end
+
+  class InstanceQueueDefinitionError < StandardError
+    def initialize(obj)
+      msg = "Cannot define a queue on an instance: #{obj}. Try defining it directly on the class #{obj.class}"
+      super(msg)
+    end
+  end
+
+  class DuplicateQueueClassError < StandardError
+    def initialize(base, duplicate_klass)
+      msg = "Cannot create queue class: '#{duplicate_klass}' because #{duplicate_klass} is already defined on #{base}"
+      super(msg)
+    end
+  end
+
+  class DuplicateQueueMethodError < StandardError
+    def initialize(base, method)
+      msg = "Cannot create queue method: '#{method}'. Method already exists on #{base}.queue, cannot overwrite"
+      msg << "Originally defined at #{base.queue.method(method).source_location}"
+      super(msg)
+    end
+  end
+end

data/lib/q/helpers.rb

@@ -0,0 +1,25 @@
+module Q
+  module Helpers
+    def camelize(term)
+      string = term.to_s
+      string = string.sub(/^[a-z\d]*/) { $&.capitalize }
+      string = string.gsub(/(?:_|(\/))([a-z\d]*)/i) { "#{$2.capitalize}" }.gsub('/', '::')
+      string
+    end
+
+    def underscore(term)
+      string = term.to_s
+      string = string.sub(/^[a-z\d]*/) { "#{$&.downcase}_" }
+      string = string.gsub(/^_/, '')
+      string
+    end
+
+    def const_defined_on?(on, const)
+      on.constants.include?(const.to_sym)
+    end
+
+    def proc_to_lambda(block = nil, &proc)
+      ::ProcToLambda.to_lambda(block || proc)
+    end
+  end
+end

data/lib/q/methods.rb

@@ -0,0 +1,30 @@
+module Q
+  module Methods
+    include Q::Methods::Base
+
+    class QueueConfig
+      def self.call
+        Q.queue::QueueConfig
+      end
+    end
+
+    class QueueTask
+      def self.call(*rake_args)
+        Q.queue::QueueTask.call(rake_args)
+      end
+    end
+
+    class QueueBuild
+      def self.call(options={}, &job)
+        Q.queue::QueueBuild.call(options, &job)
+      end
+    end
+
+    class QueueMethod
+      def self.call(options = {})
+        Q.queue::QueueMethod.call(options)
+      end
+    end
+  end
+end
+Q::Method = Q::Methods

data/lib/q/methods/base.rb

@@ -0,0 +1,53 @@
+module Q
+  module Methods
+    module Base
+      def self.included(base)
+        base.const_set("Queue", Class.new(::Q::Queue)) unless base.const_get("Queue") != ::Queue
+
+        included = base.method(:included) if base.respond_to?(:included)
+        base.define_singleton_method(:included) do |target|
+          included.call(target) unless included.nil?
+
+          raise Q::MissingClassError.new(base, :QueueMethod) unless Q.const_defined_on?(base, :QueueMethod)
+          raise Q::MissingClassError.new(base, :QueueBuild)  unless Q.const_defined_on?(base, :QueueBuild)
+          raise Q::MissingClassError.new(base, :QueueTask)   unless Q.const_defined_on?(base, :QueueTask)
+          raise Q::MissingClassError.new(base, :QueueConfig) unless Q.const_defined_on?(base, :QueueConfig)
+
+          target.extend(ClassMethods)
+          target.send(:include, InstanceMethods)
+
+          target.class_variable_set(:@@_q_klass, base)            unless target.class_variable_defined?(:@@_q_klass)
+          target.class_variable_set(:@@_q_queue, base::Queue.new) unless target.class_variable_defined?(:@@_q_queue)
+        end
+      end
+
+      module InstanceMethods
+        def queue
+          raise Q::InstanceQueueDefinitionError.new(self) if block_given?
+          self.class.queue
+        end
+      end
+
+      module ClassMethods
+        def queue(*args, &block)
+          queue = self.class_variable_get(:@@_q_queue)
+
+          return queue unless block_given?
+
+          queue_name   = args.shift
+          job          = Q.proc_to_lambda(&block)
+
+          raise "first argument #{queue_name.inspect} must be a symbol to define a queue" unless queue_name.is_a?(Symbol)
+
+          options = { base:             self,
+                      queue_name:       queue_name,
+                      queue_klass_name: Q.camelize(queue_name) }
+
+          queue_klass = self.class_variable_get(:@@_q_klass)
+          queue_klass::QueueBuild.call(options, &job)
+          queue_klass::QueueMethod.call(options)
+        end
+      end
+    end
+  end
+end