timberline-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bd1b6647a272ed349fa5841ea5c034cc5d08113c
-  data.tar.gz: 91c83bda9ed02f63524e2f3dcc5c89f205e7d220
+  metadata.gz: 166b9a7d89b80420e9b0072e2f18a20c393a8cb8
+  data.tar.gz: b6a3be0f462f3a92a0a1ca452d650da96de826e1
 SHA512:
-  metadata.gz: d760c7a1f26209a068f3c7f378b531ed3e81a3f4f3e1c8f983e6450c28865c7e364fd363fd3804b2b5fbb8f50366ccf350b784695e0d71b75c0538960420ba76
-  data.tar.gz: 0d952ff2409dbf5d29f42eb24e27ebaf8357d45dde94fbdb5fdeb317089b1341d55d0286abb8378ded345746022d6e98aa1531d5b9f6e84e46dd7f823dd61cee
+  metadata.gz: cc1f6396cf3b87cc2f3d8fc85026a6310de21a8a215539632f387aad31e8256835fdb05c62dcc055c151167934593a24a413ce7a95953987a1f18d9ea637447d
+  data.tar.gz: dd79ad8efb7782543047877e749bccca601376c9f5470b0f0efa60bd0088d3c1ebb217012405c7e64d1ece94218c2df0c9e1b5be551d11f2d88e7ea1a2b78f41

data/CHANGELOG

@@ -1,3 +1,6 @@
+0.2.0
+  - Add Timberline::Rails::ActiveRecord and Timberline::Rails::ActiveRecordWorker support
+  - Upgrade to Timberline v0.7.0 with Worker support
 0.1.0
   - First public release of Timberline-Rails
   - Add Rails-specific configuration logic for loading config/timberline.yml

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    timberline-rails (0.1.0)
-      timberline (~> 0.6.0)
+    timberline-rails (0.2.0)
+      timberline (~> 0.7.0)
 
 GEM
   remote: http://rubygems.org/
@@ -34,13 +34,14 @@ GEM
       rspec-support (~> 3.0.0)
     rspec-support (3.0.0)
     slop (3.5.0)
-    timberline (0.6.0)
+    timberline (0.7.0)
       daemons
       redis
       redis-expiring-set
       redis-namespace
       trollop
     trollop (2.0)
+    yard (0.8.7.4)
 
 PLATFORMS
   ruby
@@ -50,3 +51,4 @@ DEPENDENCIES
   rake
   rspec (~> 3.0.0)
   timberline-rails!
+  yard

data/README.markdown

@@ -1,5 +1,8 @@
 # Timberline-Rails
 
+![](https://travis-ci.org/treehouse/timberline-rails.svg) 
+[![Gem Version](https://badge.fury.io/rb/timberline-rails.svg)](http://badge.fury.io/rb/timberline-rails)
+
 ## Purpose
 
 Timberline-Rails adds some extra functionality to
@@ -11,22 +14,53 @@ in the context of a Rails application.
 ### Configuration
 
 In base Timberline, you have a few options for configuration, from defining a
-`TIMBERLINE\_YAML` constant that points to a yaml config file to defining the
+`TIMBERLINE_YAML` constant that points to a yaml config file to defining the
 configuration in code using `Timberline.configure`. Timberline-Rails adds in
 automatic detection for a config file at `config/timberline.yml` in your Rails
 app, complete with environment support (just like database.yml).
 
-## Usage
+### Timberline::Rails::ActiveRecord and Timberline::Rails::ActiveRecordWorker
 
-Timberline-Rails works exactly like Timberline; just make sure that you have
-`timberline-rails` listed in your Gemfile and you're good to go.
+In order to make running jobs in the background as easy as possible,
+Timberline-Rails comes with two new items to help:
+
+#### Timberline::Rails::ActiveRecord
+
+This is a module that you can include in your ActiveRecord models to give you
+an easy DSL for marking certain methods to always run in the background.
+
+Example:
+
+    class User < ActiveRecord::Model
+      include Timberline::Rails::ActiveRecord
+      
+      # specify the queue for jobs to run on
+      timberline_queue "user_jobs"
 
-## TODO
+      def send_some_email
+        ...
+      end
+      # Now whenever send_some_email gets called, we put a message onto the "user_jobs" queue
+      # rather than calling the method directly.
+      delay_method :send_some_email
+    end
 
-Still to be done:
+#### Timberline::Rails::ActiveRecordWorker
 
-- **Rails Workers** - implement workers that expect to operate on ActiveRecord objects
-  so you can quickly and easily background tasks in Rails.
+This is a worker designed to parse messages put on a queue by Timberline::Rails::ActiveRecord.
+To continue our example from above:
+
+    # run this script with rails/runner or use some other means to load your Rails environment
+    
+    Timberline::Rails::ActiveRecordWorker.new("user_jobs").watch
+
+...and items will be pulled off of the `user_jobs` queue and processed (in this case,
+we'll look up the appropriate User record and call `#send_some_email` on it directly).=
+
+## Usage
+
+Timberline-Rails works exactly like Timberline; just make sure that you have
+`timberline-rails` listed in your Gemfile and you're good to go.
 
 ## Contributions
 

data/lib/timberline/rails/active_record.rb

@@ -0,0 +1,76 @@
+class Timberline
+  class Rails
+    # Timberline::Rails::ActiveRecord will add some extra logic
+    # to your ActiveRecord models so that you can quickly and
+    # easily defer certain methods to background processing.
+    #
+    # Although this module is primarily intended for use with
+    # ActiveRecord models, it will actually work with any class
+    # that implements the following methods:
+    # - primary_key - a method that returns a String representing the
+    #   primary_key for this model (for ActiveRecord this is usually "id")
+    # - find_by_[primary_key] - a method that returns an object matching
+    #   the specified primary key, or nil if it does not exist (e.g. "find_by_id")
+    #
+    # @see Timberline::Rails::ActiveRecordWorker
+    #
+    # @example using Timberline::Rails::ActiveRecord to process an email in the background
+    #   class User < ActiveRecord::Base
+    #     include Timberline::Rails::ActiveRecord
+    #
+    #     timberline_queue "users"
+    #     
+    #     def send_some_email
+    #       # do stuff to send the email
+    #     end
+    #     delay_method :send_some_email
+    #   end
+    #
+    module ActiveRecord
+      def self.included(klass)
+        klass.class_eval do
+          extend Timberline::Rails::ActiveRecord::ClassMethods  
+        end
+      end
+      
+      # Class methods that get added to any class that includes Timberline::Rails::ActiveRecord.
+      #
+      module ClassMethods
+        # Set the queue name for this model. Required.
+        # @param [String] queue_name the name of the queue that this model will use
+        #   to process jobs.
+        #
+        def timberline_queue(queue_name)
+          @timberline_queue = Timberline.queue(queue_name)
+        end
+
+        # Push an item onto the queue specified for this model.
+        # @see delay_method
+        #
+        def timberline_push(content, metadata = {})
+          if @timberline_queue.nil?
+            raise "You must specify a queue name using .timberline_queue first"
+          end
+          @timberline_queue.push(content, metadata)
+        end
+
+        # Mark a method as one that needs to be executed in the background.
+        # @param [Symbol, String] method_name the name of the method to execute in the background.
+        #   This method will be aliased to synchronous_[method_name] in the event
+        #   that it needs to be called directly.
+        #
+        def delay_method(method_name)
+          alias_method "synchronous_#{method_name}", method_name
+          define_method "timberline_#{method_name}" do 
+            model_name = self.class.name
+            model_key = self.send(self.class.primary_key)
+            self.class.timberline_push({ model_name: model_name, 
+                                         model_key: model_key, 
+                                         method_name: method_name })
+          end
+          alias_method method_name, "timberline_#{method_name}"
+        end
+      end
+    end
+  end
+end

data/lib/timberline/rails/active_record_worker.rb

@@ -0,0 +1,57 @@
+class Timberline
+  class Rails
+    # The ActiveRecordWorker is designed to process items put on
+    # the queue by Timberline::Rails::ActiveRecord. It processes items
+    # off of the queue, instantiates the specified model, and calls the 
+    # specified synchronous method. If the Timberline::Rails::ActiveRecord
+    # module is not in use on the model, and the synchronous_method_name method
+    # is not defined, the worker will attempt to call method_name instead, so
+    # that the worker can still be used for jobs that fit the Timberline::Rails::ActiveRecord
+    # format even when the module itself has not been used to dispatch the job.
+    #
+    # @see Timberline::Rails::ActiveRecord
+    #
+    class ActiveRecordWorker < ::Timberline::Worker
+      
+      # Processes items off of a Timberline::Rails::ActiveRecord-compatible
+      # queue.
+      #
+      # @param [Timberline::Envelope] item an Envelope whose contents should be
+      #   a hash containing three keys: method_name (the name of the method to call
+      #   on the model), model_name (the name of the model on which to call the method),
+      #   and model_key (the primary key of the model, for lookup purposes).
+      #
+      # @see Timberline::Rails::ActiveRecord::ClassMethods#delay_method
+      # @see Timberline::Worker#watch
+      def process_item(item)  
+        contents = item.contents
+        method_name = contents["method_name"]
+        model_name = contents["model_name"]
+        model_key = contents["model_key"]
+        klass = model_name.split('::').reduce(Module, :const_get)
+        model = klass.send("find_by_#{klass.primary_key}", model_key) 
+        if model.nil?
+          # Retry because there may have been a race condition
+          item.retry_reason = "Model not found"
+          retry_item(item)
+        else
+          if model.respond_to? "synchronous_#{method_name}"
+            model.send("synchronous_#{method_name}")
+          elsif model.respond_to? method_name
+            model.send(method_name)
+          else
+            item.error_reason = "Method not found on model"
+            error_item(item)
+          end
+        end
+      rescue ItemErrored, ItemRetried => e
+        # throw ItemErrored and ItemRetried back up the chain
+        raise e
+      rescue Exception => e
+        item.error_reason = e.message
+        item.error_backtrace = e.backtrace
+        error_item(item)
+      end
+    end
+  end
+end

data/lib/timberline/rails/exceptions.rb

@@ -0,0 +1,8 @@
+class Timberline
+  class Rails
+    # Raised when Timberline::Rails::ActiveRecord is included in a
+    # model that does not implement required functionality.
+    # @see Timberline::Rails::ActiveRecord
+    class InvalidModelError < StandardError; end
+  end
+end

data/lib/timberline/rails/version.rb

@@ -1,5 +1,6 @@
 class Timberline
   class Rails
-    VERSION = "0.1.0"
+    # The canonical version of Timberline-Rails
+    VERSION = "0.2.0"
   end
 end

data/lib/timberline-rails.rb

@@ -1,8 +1,16 @@
 require 'timberline'
 require 'timberline/rails/version'
+require 'timberline/rails/exceptions'
+require 'timberline/rails/active_record'
+require 'timberline/rails/active_record_worker'
 
 class Timberline
+  # Re-open the Timberline::Config class from Timberline
   class Config
+    # Load config/timberline.yml from the Rails root if it exists.
+    # If it doesn't, or if we're somehow not in a Rails application,
+    # just use the default Timberline behavior for instantiating
+    # Config objects.
     def rails_initialize
       if defined? ::Rails
         config_file = File.join(::Rails.root, 'config', 'timberline.yml')

data/spec/lib/timberline/rails/active_record_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe Timberline::Rails::ActiveRecord do
+  describe "including in a class" do
+    subject { SpecSupport::FakeRails::FakeModel }
+
+    it "defines the timberline_queue method" do
+      expect(subject).to respond_to :timberline_queue
+    end
+
+    it "defines the timberline_push method" do
+      expect(subject).to respond_to :timberline_push
+    end
+
+    it "defines the delay_method method" do
+      expect(subject).to respond_to :delay_method
+    end
+  end
+
+  describe "using delay_method" do
+    subject { SpecSupport::FakeRails::FakeModel.new }
+    let(:method_name) { "some_method" }
+
+    it "aliases the old method to synchronous_method_name" do
+      expect(subject).to respond_to("synchronous_#{method_name}")
+    end
+
+    it "sets up a new method at timberline_method_name" do
+      expect(subject).to respond_to("timberline_#{method_name}")
+    end
+
+    it "replaces the old method with timberline_method_name" do
+      expect(subject.method("timberline_#{method_name}")).to eq(subject.method(method_name))
+    end
+  end
+
+  describe "calling a delayed method" do
+    subject { SpecSupport::FakeRails::FakeModel.new }
+    let(:queue) { SpecSupport::FakeRails::FakeModel.instance_variable_get("@timberline_queue") }
+    let(:expected_data) { { model_name: "SpecSupport::FakeRails::FakeModel", 
+                            model_key: 1, 
+                            method_name: :some_method } }
+
+    it "pushes data about the method onto the queue" do
+      expect(queue).to receive(:push).with(expected_data, {})
+      subject.some_method
+    end
+  end
+end

data/spec/lib/timberline/rails/active_record_worker_spec.rb

@@ -0,0 +1,99 @@
+require 'spec_helper'
+
+describe Timberline::Rails::ActiveRecordWorker do
+  subject { Timberline::Rails::ActiveRecordWorker.new("fake_queue") }
+  let(:queue) { Timberline.queue("fake_queue") }
+  let(:item) do 
+    queue.push({ model_name: "SpecSupport::FakeRails::FakeModel",
+                 model_key: 1,
+                 method_name: :some_method })
+    queue.pop
+  end
+
+  describe "#process_item" do
+    context "when handling a method that has been delayed by Timberline::Rails::ActiveRecord" do
+      it "attempts to lookup the model" do
+        expect(SpecSupport::FakeRails::FakeModel)
+          .to receive(:find_by_id).with(1).and_call_original
+        subject.process_item(item)
+      end
+
+      it "calls the appropriate method on the model" do
+        expect_any_instance_of(SpecSupport::FakeRails::FakeModel)
+          .to receive(:synchronous_some_method)
+        subject.process_item(item)
+      end
+    end
+
+    context "when handling a method that has not been delayed by Timberline::Rails::ActiveRecord" do
+      before do
+        item.contents["method_name"] = :some_other_method
+      end
+
+      it "attempts to lookup the model" do
+        expect(SpecSupport::FakeRails::FakeModel)
+          .to receive(:find_by_id).with(1).and_call_original
+        subject.process_item(item)
+      end
+
+      it "calls the appropriate method on the model" do
+        expect_any_instance_of(SpecSupport::FakeRails::FakeModel)
+          .to receive(:some_other_method)
+        subject.process_item(item)
+      end
+    end
+
+    context "If the model can't be found" do
+      before do
+        allow(SpecSupport::FakeRails::FakeModel).to receive(:find_by_id) { nil }
+      end
+
+      it "retries the item" do
+        expect(subject).to receive(:retry_item).with(item)
+        subject.process_item(item)
+      end
+
+      it "gives the item a retry_reason" do
+        expect { subject.process_item(item) }.to raise_error(Timberline::ItemRetried)
+        expect(item.retry_reason).to include("Model not found")
+      end
+    end
+
+    context "If the method doesn't exist on the model" do
+      before do
+        item.contents["method_name"] = "gibberish"
+      end
+
+      it "errors the item" do
+        expect(subject).to receive(:error_item).with(item)
+        subject.process_item(item)
+      end
+
+      it "gives the item an error_reason" do
+        expect { subject.process_item(item) }.to raise_error(Timberline::ItemErrored)
+        expect(item.error_reason).to include("Method not found")
+      end
+    end
+
+    context "If the method raises an exception of its own" do
+      before do
+        allow_any_instance_of(SpecSupport::FakeRails::FakeModel).to receive(:synchronous_some_method) { raise "This doesn't work" }
+      end
+
+      it "errors the item" do
+        expect(subject).to receive(:error_item).with(item)
+        subject.process_item(item)
+      end
+
+      it "provides an error_reason" do
+        expect { subject.process_item(item) }.to raise_error(Timberline::ItemErrored)
+        expect(item.error_reason).to include("This doesn't work")
+      end
+
+      it "provides an error_backtrace" do
+        expect { subject.process_item(item) }.to raise_error(Timberline::ItemErrored)
+        expect(item.error_backtrace).to be_a Array
+      end
+    end
+  end
+end

data/spec/support/fake_rails.rb

@@ -13,5 +13,32 @@ module SpecSupport
     def self.destroy_fake_env
       Object.send(:remove_const, :Rails)
     end
+
+    class FakeModel
+      include Timberline::Rails::ActiveRecord
+
+      timberline_queue "fake_queue"
+
+      def self.primary_key
+        "id"
+      end
+
+      def self.find_by_id(id)
+        FakeModel.new
+      end
+
+      def id
+        1
+      end
+
+      def some_method
+        # left blank
+      end
+      delay_method :some_method
+
+      def some_other_method
+        # left blank
+      end
+    end
   end
 end

data/timberline-rails.gemspec

@@ -18,9 +18,10 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_runtime_dependency "timberline", "~> 0.6.0"
+  s.add_runtime_dependency "timberline", "~> 0.7.0"
 
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec", '~> 3.0.0'
   s.add_development_dependency "pry"
+  s.add_development_dependency "yard"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: timberline-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Tommy Morgan
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-06 00:00:00.000000000 Z
+date: 2014-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: timberline
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.7.0
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,20 @@ dependencies:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: Timberline is a simple and extensible queuing system built in Ruby and
   backed by Redis. It makes as few assumptions as possible about how you want to interact
   with your queues while also allowing for some functionality that should be universally
@@ -85,9 +99,14 @@ files:
 - README.markdown
 - Rakefile
 - lib/timberline-rails.rb
+- lib/timberline/rails/active_record.rb
+- lib/timberline/rails/active_record_worker.rb
+- lib/timberline/rails/exceptions.rb
 - lib/timberline/rails/version.rb
 - spec/fake_rails/config/timberline.yml
-- spec/lib/config_spec.rb
+- spec/lib/timberline/config_spec.rb
+- spec/lib/timberline/rails/active_record_spec.rb
+- spec/lib/timberline/rails/active_record_worker_spec.rb
 - spec/spec_helper.rb
 - spec/support/fake_rails.rb
 - spec/support/timberline_reset.rb
@@ -116,3 +135,4 @@ signing_key:
 specification_version: 4
 summary: Rails logic and niceties for the Timberline queueing system.
 test_files: []
+has_rdoc: