lev 4.3.0 → 4.3.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZGMxZTI5ZTEzM2M2Yzc0OWFhMzRmMDg0MDdjZDI3ZmRlNDhmZjM0Mg==
+    NTU2OGIyM2MxZDQzZmYwMGVkNmZkZWRiZmE2YjMzZmE2NDQ2MDM3Zg==
   data.tar.gz: !binary |-
-    NjkwYjg3YTJjOWEyMThlMjk1YjdiY2RmMDI1YmJhNmQ4ZjUyOGQ2Ng==
+    Mjk0OTU3NDBhM2E4MjNmMWRhNmZlMzFhYWU4YjMxNTdiMjEwOWE0MQ==
 SHA512:
   metadata.gz: !binary |-
-    YmM3ZDY1MzdlMWQxMjhjMjFjNDhiYTBjOWY0ZjA1YjVjYTlhMzVjODZjNjg3
-    NGYxOWIwNGQ2OWVmNWE0MjViYTgwYTYxMTZiY2QxYzk4Njg3NWUwZDNkYTk3
-    MmZhMWY1YWEwMjM1ZWFhZGIwZjU5MTY4ZDAyMDFmNWY5MTk2ZGQ=
+    YTU4ZmQ3YjExMGNlNjI4MjNkYWRkOWNkM2YxOTkwYTM4ZGEyY2VlMjM4Y2Ew
+    MmFiOTg4YTE3YTU5OTdlZWY3NmQzNWEyNGQyMmFiMzNjZmRjMDA3ODZmYzFk
+    OWE0NjU2ZDgyOTljZTg2MGU1MmJjMWEyODIxYjI4ZTI2NzQ5ZTE=
   data.tar.gz: !binary |-
-    ZWJhZTc3NjFlNDc2MTI2MWZiNjg2YjAyNGFkYmE3ZjRhY2QzZWEyZWE1MDEw
-    NDg4ZjMwNGI3NDQ2ZGE0NGI3Mjg0YjFkZDgxZGFlNzA2ZDMxM2NiNjAxNWJk
-    NzMxM2Y2ODJiYzVlNDMxNzQ1ZDk0OWVkZWQyMzYyNTFhZmRiODc=
+    ZjM2ZjFmMTBkMGVkMDgxMWMwOGQ2ZDBmYjY1YWI5ZmFkMTc5ODdlYWFkMDFj
+    YmEwMWE0NzU5ODg4MDY0ODA2NTE2ZjdlNWU0NDk0MjI0NDgxOGZkNTA2MGNj
+    YThlY2E2NDMxNzEyZjNiNjExMzFmN2IzMzI0NTdjOTI5ZjY3MzY=

data/README.md

@@ -433,14 +433,49 @@ class MyRoutine
 end
 ```
 
-By default also, jobs use ActiveJob::Base as the class, but you can configure this:
+Routines run as ActiveJobs can also publish their status somewhere it can be listened to (e.g. to Redis).
+
+Routines have a `status` object and can call the following methods:
+
+* `set_progress(at, out_of = nil)` sets the current progress; can either pass a float between 0.0 and 1.0 or
+  a counter towards a total, e.g. `set_progress(67,212)`.
+* `queued!` Sets the status to 'queued'
+* `working!` Sets the status to 'working'
+* `completed!` Sets the status to 'completed'
+* `failed!` Sets the status to 'failed'
+* `killed!` Sets the status to 'killed'
+* `save(hash)` Takes a hash of key value pairs and writes those keys and values to the status; there are several reserved keys which cannot be used (and which will blow up if you try to use them)
+* `add_error(is_fatal, error)` takes a boolean and a Lev `Error` object and adds its data to an array of `errors` in the status hash.
+
+All routines have such a status object.  For plain vanilla routines not run as an active job, the status calls are no-ops.  When a routine is invoked with `perform_later`, the status object actually records the statuses to a store of your choice.  The store is configured in the Lev configuration block, e.g.:
 
 ```ruby
 Lev.configure do |config|
-  config.active_job_class = TrackableJob
+  config.status_store = whatever
 end
 ```
 
+The store needs to respond to the following methods:
+
+1. fetch(key)
+2. write(key, value)
+
+The default store is essentially a hash (implemented in `Lev::MemoryStore`).  Any `ActiveSupport::Cache::Store` will work.
+
+A routine's status can be retrieved with `Lev::Status.get(uuid_here)`.  This just returns a simple hash.  Notable keys are
+
+* `'progress'` which returns the progress as a number between 0.0 and 1.0
+* `'status'` which returns one of the status strings shown above
+* `'errors'` which (if present) is an error of error hashes
+* `'uuid'` the UUID of the routine / status
+
+Other routine-specific keys (set with a `save` call) are also present.
+
+**Notes:**
+
+1. Don't try to write a status store that uses the ActiveRecord database, as the database changes would only be seen when the routine completes and its transaction is committed.
+2. Job killing hasn't been implemented yet, but shouldn't be too bad.  For routines run in a transaction (which are frankly the only ones you'd want to kill), we can likely kill them by raising an exception or similar to cause a rollback (will need to have good tests to prove that).
+
 ## Handlers
 
 Handlers are specialized routines that take user input (e.g. form data) and then take an action based on that input.  Because all Handlers are Routines, everything discussed above applies to them.

data/lib/lev.rb

@@ -24,6 +24,10 @@ require "lev/form_builder"
 require "lev/delegate_to_routine"
 require "lev/transaction_isolation"
 
+require 'lev/active_job'
+require 'lev/memory_store'
+require 'lev/status'
+require 'lev/black_hole_status'
 
 module Lev
   class << self
@@ -55,14 +59,16 @@ module Lev
       attr_accessor :security_transgression_error
       attr_accessor :illegal_argument_error
       attr_accessor :raise_fatal_errors
-      attr_accessor :active_job_class
+      attr_accessor :status_store
+      attr_accessor :status_store_namespace
 
       def initialize
         @form_error_class = 'error'
         @security_transgression_error = Lev::SecurityTransgression
         @illegal_argument_error = Lev::IllegalArgument
         @raise_fatal_errors = false
-        @active_job_class = defined?(ActiveJob) ? ActiveJob::Base : nil
+        @status_store = Lev::MemoryStore.new
+        @status_store_namespace = "lev_status"
         super
       end
     end

data/lib/lev/active_job.rb

@@ -0,0 +1,33 @@
+if defined?(::ActiveJob)
+  module Lev
+    module ActiveJob
+      class Base < ::ActiveJob::Base
+        def self.perform_later(routine_class, *args, &block)
+          queue_as routine_class.active_job_queue
+          args.push(routine_class.to_s)
+
+          # To enable tracking of this job's status, create a new Status object
+          # and push it on to the arguments so that in `perform` it can be peeled
+          # off and handed to the routine instance.  The Status UUID is returned
+          # so that callers can track the status.
+          status = Lev::Status.new
+          status.queued!
+          args.push(status.uuid)
+
+          super(*args, &block)
+
+          status.uuid
+        end
+
+        def perform(*args, &block)
+          # Pop arguments added by perform_later
+          uuid = args.pop
+          routine_class = Kernel.const_get(args.pop)
+
+          routine_instance = routine_class.new(Lev::Status.new(uuid))
+          routine_instance.call(*args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/lev/black_hole_status.rb

@@ -0,0 +1,26 @@
+module Lev
+  class BlackHoleStatus
+
+    # Provide null object pattern methods for status setters; routines should
+    # not be checking their own status (they should know it), and outside callers
+    # should not be checking status unless the status object is a real one.
+
+    def set_progress(*); end
+    def save(*); end
+    def add_error(*); end
+
+    Lev::Status::STATES.each do |state|
+      define_method("#{state}!") do; end
+    end
+
+    def self.method_missing(method_sym, *args, &block)
+      if Lev::Status.new.respond_to?(method_sym)
+        raise NameError,
+              "'#{method_sym}' is Lev::Status query method, and those cannot be called on BlackHoleStatus"
+      else
+        super
+      end
+    end
+
+  end
+end

data/lib/lev/errors.rb

@@ -4,12 +4,29 @@ module Lev
   #
   class Errors < Array
 
+    def initialize(routine_status = nil, raise_fatal_errors = false)
+      @routine_status = routine_status || BlackHoleStatus.new
+      @raise_fatal_errors = raise_fatal_errors
+    end
+
     def add(fail, args={})
       args[:kind] ||= :lev
       error = Error.new(args)
+
       return if ignored_error_procs.any?{|proc| proc.call(error)}
       self.push(error)
-      throw :fatal_errors_encountered if fail
+
+      routine_status.add_error(error, is_fatal: fail)
+
+      if fail
+        routine_status.failed!
+
+        if raise_fatal_errors
+          raise StandardError, args.to_a.map { |i| i.join(' ') }.join(' - ')
+        else
+          throw :fatal_errors_encountered
+        end
+      end
     end
 
     def ignore(arg)
@@ -37,6 +54,9 @@ module Lev
 
   protected
 
+    attr_reader :routine_status
+    attr_reader :raise_fatal_errors
+
     def ignored_error_procs
       @ignored_error_procs ||= []
     end

data/lib/lev/memory_store.rb

@@ -0,0 +1,17 @@
+module Lev
+  class MemoryStore
+
+    def initialize
+      @store = {}
+    end
+
+    def fetch(key)
+      @store[key]
+    end
+
+    def write(key, value)
+      @store[key] = value
+    end
+
+  end
+end

data/lib/lev/routine.rb

@@ -185,12 +185,14 @@ module Lev
       attr_reader :outputs
       attr_reader :errors
 
-      def initialize
-        @outputs = Outputs.new
-        @errors = Errors.new
+      def initialize(outputs, errors)
+        @outputs = outputs
+        @errors = errors
       end
     end
 
+    attr_reader :uuid
+
     def self.included(base)
       base.extend(ClassMethods)
     end
@@ -206,27 +208,10 @@ module Lev
         result.outputs.send(@express_output)
       end
 
-      if defined?(ActiveJob)
-        def active_job_class
-          @active_job_class ||= const_set("ActiveJob",
-            Class.new(Lev.configuration.active_job_class) do
-              queue_as do
-                parent_routine.active_job_queue
-              end
-
-              def parent_routine
-                self.class.parent
-              end
-
-              def perform(*args, &block)
-                parent_routine.call(*args, &block)
-              end
-            end
-          )
-        end
-
+      if defined?(::ActiveJob)
         def perform_later(*args, &block)
-          active_job_class.perform_later(*args, &block)
+          # Delegate to a subclass of Lev::Routine::ActiveJob::Base
+          Lev::ActiveJob::Base.perform_later(self, *args, &block)
         end
 
         def active_job_queue
@@ -282,6 +267,8 @@ module Lev
     def call(*args, &block)
       @after_transaction_blocks = []
 
+      status.working!
+
       in_transaction do
         catch :fatal_errors_encountered do
           begin
@@ -298,6 +285,8 @@ module Lev
         block.call
       end
 
+      status.completed! if !errors?
+
       result
     end
 
@@ -402,11 +391,7 @@ module Lev
     end
 
     def fatal_error(args={})
-      if topmost_runner.class.raise_fatal_errors?
-        raise StandardError, args.to_a.map { |i| i.join(' ') }.join(' - ')
-      else
-        errors.add(true, args)
-      end
+      errors.add(true, args)
     end
 
     def nonfatal_error(args={})
@@ -431,13 +416,29 @@ module Lev
       @after_transaction_blocks.push(block)
     end
 
+    # Note that the parent may neglect to call super, leading to this method never being called.
+    # Do not perform any initialization here that cannot be safely skipped
+    def initialize(status = nil)
+      # If someone cares about the status, they'll pass it in; otherwise all
+      # status updates go into the bit bucket.
+      @status = status
+    end
+
   protected
 
-    def result
-      @result ||= Result.new
+    attr_writer :runner
+
+    def status
+       @status ||= Lev::BlackHoleStatus.new
     end
 
-    attr_writer :runner
+    def result
+      @result ||= Result.new(
+        Outputs.new,
+        Errors.new(status,
+                   topmost_runner.class.raise_fatal_errors?)
+      )
+    end
 
     def outputs
       result.outputs

data/lib/lev/status.rb

@@ -0,0 +1,125 @@
+require 'json'
+
+module Lev
+  class Status
+    STATE_QUEUED = 'queued'
+    STATE_WORKING = 'working'
+    STATE_COMPLETED = 'completed'
+    STATE_FAILED = 'failed'
+    STATE_KILLED = 'killed'
+
+    STATES = [
+      STATE_QUEUED,
+      STATE_WORKING,
+      STATE_COMPLETED,
+      STATE_FAILED,
+      STATE_KILLED
+    ].freeze
+
+    attr_reader :uuid
+
+    def initialize(uuid = nil)
+      @uuid = uuid || SecureRandom.uuid
+      save
+    end
+
+    def self.find(uuid)
+      if status = store.fetch(status_key(uuid))
+        JSON.parse(status)
+      else
+        nil
+      end
+    end
+
+    def set_progress(at, out_of = nil)
+      progress = compute_fractional_progress(at, out_of)
+
+      data_to_set = { progress: progress }
+      data_to_set[:state] = STATE_COMPLETED if 1.0 == progress
+
+      set(data_to_set)
+    end
+
+    STATES.each do |state|
+      define_method("#{state}!") do
+        set(state: state)
+      end
+    end
+
+    def save(hash = {})
+      if has_reserved_keys?(hash)
+        raise IllegalArgument,
+              "Caller cannot specify any reserved keys (#{RESERVED_KEYS})"
+      else
+        set(hash)
+      end
+    end
+
+    def add_error(error, options = { })
+      options = { is_fatal: false }.merge(options)
+      push('errors', { is_fatal: options[:is_fatal],
+                       code: error.code,
+                       message: error.message })
+    end
+
+    def get(key)
+      self.class.find(uuid)[key]
+    end
+
+    protected
+    RESERVED_KEYS = [:progress, :uuid, :state, :errors]
+
+    def self.store
+      # Nice to get the store from lev config each time so it isn't serialized
+      # when activejobs are sent off to places like redis
+      Lev.configuration.status_store
+    end
+
+    def set(incoming_hash)
+      if existing_settings = self.class.find(uuid)
+        incoming_hash = existing_settings.merge(incoming_hash)
+      end
+
+      self.class.store.write(status_key, incoming_hash.to_json)
+    end
+
+    def status_key
+      self.class.status_key(uuid)
+    end
+
+    def self.status_key(uuid)
+      "#{Lev.configuration.status_store_namespace}:#{uuid}"
+    end
+
+    def has_reserved_keys?(hash)
+      (hash.keys.collect(&:to_sym) & RESERVED_KEYS).any?
+    end
+
+    def push(key, new_item)
+      new_value = (get(key) || []).push(new_item)
+      set(key => new_value)
+    end
+
+    STATES.each do |state|
+      define_method("#{state}?") do
+        get('state') == state
+      end
+    end
+
+    def compute_fractional_progress(at, out_of)
+      if at.nil?
+        raise IllegalArgument, "Must specify at least `at` argument to `progress` call"
+      elsif at < 0
+        raise IllegalArgument, "progress cannot be negative (at=#{at})"
+      elsif out_of && out_of < at
+        raise IllegalArgument, "`out_of` must be greater than `at` in `progress` calls"
+      elsif out_of.nil? && (at < 0 || at > 1)
+        raise IllegalArgument, "If `out_of` not specified, `at` must be in the range [0.0, 1.0]"
+      end
+
+      at.to_f / (out_of || 1).to_f
+    end
+
+  end
+end
+

data/lib/lev/version.rb

@@ -1,3 +1,3 @@
 module Lev
-  VERSION = "4.3.0"
+  VERSION = "4.3.1"
 end

data/spec/active_job_routines_spec.rb

@@ -1,15 +1,7 @@
-require 'active_job'
 require 'spec_helper'
 
-ActiveJob::Base.queue_adapter = :test
-ActiveJob::Base.logger = ::Logger.new(nil)
-
 RSpec.describe 'ActiveJob routines' do
   context 'default configuration' do
-    before do
-      Lev.configure { |c| c.active_job_class = ActiveJob::Base } # default
-    end
-
     class LaterRoutine
       lev_routine active_job_queue: :something_else
 
@@ -29,29 +21,4 @@ RSpec.describe 'ActiveJob routines' do
       expect(queue_name).to eq('something_else')
     end
   end
-
-  context 'specialized configuration' do
-    before do
-      Lev.configure { |c| c.active_job_class = SomeOtherJobBase }
-    end
-
-    class SomeOtherJobBase
-      def self.queue_as(*args); end
-      def self.perform_later; end
-    end
-
-    class NewLaterRoutine
-      lev_routine
-      protected
-      def exec; end
-    end
-
-    it 'allows configuration of the class' do
-      allow(SomeOtherJobBase).to receive(:perform_later)
-
-      expect(Lev.configuration.active_job_class).to eq(SomeOtherJobBase)
-      NewLaterRoutine.perform_later
-      expect(SomeOtherJobBase).to have_received(:perform_later)
-    end
-  end
 end

data/spec/routine_spec.rb

@@ -111,7 +111,7 @@ describe Lev::Routine do
       begin
         RaiseFatalError.call
       rescue => e
-        expect(e.message).to eq('code broken - such disaster')
+        expect(e.message).to eq('code broken - such disaster - kind lev')
       end
     end
   end

data/spec/spec_helper.rb

@@ -4,6 +4,12 @@
 # loaded once.
 #
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'active_job'
+
+ActiveJob::Base.queue_adapter = :test
+ActiveJob::Base.logger = ::Logger.new(nil)
+
 RSpec.configure do |config|
   config.run_all_when_everything_filtered = true
   config.filter_run :focus

data/spec/statused_routines_spec.rb

@@ -0,0 +1,158 @@
+require 'spec_helper'
+
+class StatusedRoutine
+  lev_routine
+
+  protected
+  def exec
+    status.set_progress(9, 10)
+  end
+end
+
+RSpec.describe 'Statused Routines' do
+  subject(:status) { Lev::Status.new }
+
+  context 'in a routine' do
+    it 'queues the status object on queue' do
+      uuid = StatusedRoutine.perform_later
+      status = Lev::Status.find(uuid)
+
+      expect(status['state']).to eq(Lev::Status::STATE_QUEUED)
+    end
+
+    context 'inline activejob mode' do
+      before { ::ActiveJob::Base.queue_adapter = :inline }
+      after { ::ActiveJob::Base.queue_adapter = :test }
+
+      it 'sets status to working when called' do
+        expect_any_instance_of(Lev::Status).to receive(:working!)
+        StatusedRoutine.perform_later
+      end
+
+      it 'completes the status object on completion, returning other data' do
+        uuid = StatusedRoutine.perform_later
+        status = Lev::Status.find(uuid)
+        expect(status['state']).to eq(Lev::Status::STATE_COMPLETED)
+        expect(status['progress']).to eq(0.9)
+      end
+    end
+  end
+
+  describe '#save' do
+    it 'prevents the use of reserved keys' do
+      expect {
+        status.save(progress: 'blocked')
+      }.to raise_error(Lev::IllegalArgument)
+
+      expect {
+        status.save(uuid: 'blocked')
+      }.to raise_error(Lev::IllegalArgument)
+
+      expect {
+        status.save(state: 'blocked')
+      }.to raise_error(Lev::IllegalArgument)
+
+      expect {
+        status.save(errors: 'blocked')
+      }.to raise_error(Lev::IllegalArgument)
+    end
+
+    it 'saves the hash given and writes them to the status' do
+      status.save(something: 'else')
+      expect(status.get('something')).to eq('else')
+    end
+  end
+
+  describe '#add_error' do
+    it 'adds the error object data to the status object' do
+      errors = Lev::Error.new(code: 'bad', message: 'awful')
+      status.add_error(errors)
+      expect(status.get('errors')).to eq([{ 'is_fatal' => false,
+                                            'code' => 'bad',
+                                            'message' => 'awful' }])
+    end
+  end
+
+  describe 'dynamic status setters/getters' do
+    it 'is queued' do
+      expect(status).not_to be_queued
+      status.queued!
+      expect(status).to be_queued
+    end
+
+    it 'is working' do
+      expect(status).not_to be_working
+      status.working!
+      expect(status).to be_working
+    end
+
+    it 'is completed' do
+      expect(status).not_to be_completed
+      status.completed!
+      expect(status).to be_completed
+    end
+
+    it 'is failed' do
+      expect(status).not_to be_failed
+      status.failed!
+      expect(status).to be_failed
+    end
+
+    it 'is killed' do
+      expect(status).not_to be_killed
+      status.killed!
+      expect(status).to be_killed
+    end
+  end
+
+  describe '#set_progress' do
+    it 'sets the progress key on the status object' do
+      status.set_progress(8, 10)
+      progress = status.get('progress')
+      expect(progress).to eq(0.8)
+    end
+
+    context 'when `out_of` is supplied' do
+      it 'requires a positive `at` float or integer' do
+        expect {
+          status.set_progress(nil, 1)
+        }.to raise_error(Lev::IllegalArgument)
+
+        expect {
+          status.set_progress(-1, 1)
+        }.to raise_error(Lev::IllegalArgument)
+
+        expect {
+          status.set_progress(2, 5)
+        }.not_to raise_error
+      end
+
+      it 'requires `out_of` to be greater than `at`' do
+        expect {
+          status.set_progress(15, 8)
+        }.to raise_error(Lev::IllegalArgument)
+
+        expect {
+          status.set_progress(5, 10)
+        }.not_to raise_error
+      end
+    end
+
+    context 'without out_of specified' do
+      it 'requires `at` to be a float between 0.0 and 1.0' do
+        expect {
+          status.set_progress(1.1)
+        }.to raise_error(Lev::IllegalArgument)
+
+        expect {
+          status.set_progress(-1)
+        }.to raise_error(Lev::IllegalArgument)
+
+        expect {
+          status.set_progress(0.78)
+        }.not_to raise_error
+      end
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lev
 version: !ruby/object:Gem::Version
-  version: 4.3.0
+  version: 4.3.1
 platform: ruby
 authors:
 - JP Slavinsky
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-12 00:00:00.000000000 Z
+date: 2015-07-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -217,7 +217,9 @@ files:
 - README.md
 - Rakefile
 - lib/lev.rb
+- lib/lev/active_job.rb
 - lib/lev/better_active_model_errors.rb
+- lib/lev/black_hole_status.rb
 - lib/lev/delegate_to_routine.rb
 - lib/lev/error.rb
 - lib/lev/error_transferer.rb
@@ -228,9 +230,11 @@ files:
 - lib/lev/handle_with.rb
 - lib/lev/handler.rb
 - lib/lev/handler_helper.rb
+- lib/lev/memory_store.rb
 - lib/lev/object.rb
 - lib/lev/outputs.rb
 - lib/lev/routine.rb
+- lib/lev/status.rb
 - lib/lev/term_mapper.rb
 - lib/lev/transaction_isolation.rb
 - lib/lev/utilities.rb
@@ -246,6 +250,7 @@ files:
 - spec/spec_helper.rb
 - spec/sprocket_handler_spec.rb
 - spec/sprocket_spec.rb
+- spec/statused_routines_spec.rb
 - spec/support/create_sprocket.rb
 - spec/support/delegated_routine.rb
 - spec/support/delegating_routine.rb
@@ -290,6 +295,7 @@ test_files:
 - spec/spec_helper.rb
 - spec/sprocket_handler_spec.rb
 - spec/sprocket_spec.rb
+- spec/statused_routines_spec.rb
 - spec/support/create_sprocket.rb
 - spec/support/delegated_routine.rb
 - spec/support/delegating_routine.rb