level_up 0.1.0 → 0.2.0

data/CHANGELOG.txt

@@ -1,2 +1,9 @@
+== 0.2.0 Hungry Beast
+  * Configurable size of saved backtrace when rescuing from an error
+  * Renamed 'states' into 'tasks'
+  * Renamed 'move_to', 'retry_in' and 'manual_task' methods into 'move_to!', 'retry_in!' and 'manual_task'
+  * New 'class_name' option to allow overriding a task class when declaring it
+  * Bug fixes and improvements
+
 == 0.1.0 Apprentice Warrior
   * First release

data/README.md

@@ -5,17 +5,17 @@
 ## What ?
 
 If you are building a web app, chances are good you have some jobs to design and execute in order to provide services to your customers.
-Generally, that means handling automated tasks, manual human tasks, calls to external services, failures, timers and retries.
-LevelUp lets you build all of these and compose them to create a runnable job. Concretely, you will define a state graph, where each state
-represents a task and contains its own business logic implemented in ruby. Jobs can be performed synchronously in the
-current thread or asynchronously by background workers. Three methods are available in each state to control the job flow: move_to(new_state), retry_in(delay), manual_task(task_description).
+Generally, that means handling computer-based or manual tasks, calls to external services, failures, timers and retries.
+LevelUp lets you build all of these and compose them to create a runnable job. Concretely, you will define a task graph, where each task contains
+its own business logic implemented in ruby. Jobs can be performed synchronously in the current thread or asynchronously by background workers.
+Three methods are available in each state to control the job flow: move_to!(task_name), retry_in!(delay), manual_task!(task_description).
 
 ## Why use LevelUp ?
 
-Designing your jobs graphically with states and transitions can be more easier than directly writing code, especially for non-technical people.
+Designing your jobs graphically with tasks and transitions can be more easier than directly writing code, especially for non-technical people.
 Graphs can be drawn, printed, shared and analysed making it easier to let everyone know what the system is doing at specific points in time.
-From a developers point of view, it’s clearer to separate the different parts of a job into isolated states. Class based states are reusable
-in multiple jobs to avoid code duplication. For example, you can use the Template design pattern to implement the generic part of a state
+From a developers point of view, it’s clearer to separate the different parts of a job into isolated states. Class-based tasks are reusable
+in multiple jobs to avoid code duplication. For example, you can use the Template design pattern to implement the generic part of a task
 in a parent class and implement specialized parts in children classes.
 
 ## Requirements
@@ -71,13 +71,13 @@ config.level_up.http_password = "your-password"
 ## Writing Job Models
 
 ```ruby
-# app/jobs/hard_job.rb
+# app/models/hard_job.rb
 class HardJob < LevelUp::Job
-  # states and transitions
+  # tasks and transitions
   job do
-    state :start, moves_to: :first_task
-    state :first_task, moves_to: :second_task
-    state :second_task, moves_to: :end
+    task :start, transitions: :first_task
+    task :first_task, transitions: :second_task
+    task :second_task, transitions: :end
   end
 
   def first_task
@@ -90,14 +90,14 @@ class HardJob < LevelUp::Job
 end
 ```
 
-### State objects
+### Task classes
 
-You can also define state logic in a class instead of a method.
+You can also define task logic in a class instead of a method.
 
 ```ruby
-app/jobs/hard_job/first_task.rb
+app/models/hard_job/first_task.rb
 module HardJob
-  class FirstTask < LevelUp::State
+  class FirstTask < LevelUp::Task
     def run
       # logic goes here
     end
@@ -106,9 +106,9 @@ end
 ```
 
 ```ruby
-app/jobs/hard_job/second_task.rb
+app/models/hard_job/second_task.rb
 module HardJob
-  class SecondTask < LevelUp::State
+  class SecondTask < LevelUp::Task
     def run
       # logic goes here
     end
@@ -118,35 +118,35 @@ end
 
 ### Flow control
 
-Inside a state, you can call 3 methods to control the job flow:
+Inside a task, you can call 3 methods to control the job flow:
 
-#### move_to(state_name)
+#### move_to!(task_name)
 
-Leave the current state and run the specified state.
+Leave the current task and run the specified one.
 ```ruby
 # example:
-move_to :second_task
+move_to! :second_task
 ```
 
-#### retry_in(delay)
+#### retry_in!(delay)
 
-Stop the execution and queue a new delayed_job to re-run the current state after the specified delay in seconds.
+Stop the execution and enqueue a new delayed_job to re-run the current task after the specified delay in seconds.
 
 ```ruby
 # example:
-retry_in 1.hour
+retry_in! 1.hour
 ```
 
-#### task(description)
-Stop the execution and set the task and task_description attributes to notify a manual human intervention.
+#### manual_task!(description)
+Stop the execution and set the manual_task and manual_task_description attributes to notify that some work need to be done manually.
 
 ```ruby
 # example:
-task "check payment information"
+manual_task! "check payment information"
 ```
 
 You can also raise a StandardError (or a subclass) to stop the execution and set the error attribute.
-The time, the state and the error backtrace will be saved.
+The time, the task and the error backtrace will be saved.
 
 ## Running Jobs
 In your code:

data/app/controllers/level_up/jobs_controller.rb

@@ -68,10 +68,10 @@ module LevelUp
 
     def move
       job = Job.find params[:id]
-      if job.boot_async!(params[:state])
-        redirect_to job_path(j), notice: "Moved to #{params[:state]}!"
+      if job.boot_async!(params[:task])
+        redirect_to job_path(job), notice: "Moved to #{params[:task]}!"
       else
-        flash[:error] = "Error while moving to #{params[:state]}"
+        flash[:error] = "Error while moving to #{params[:task]}"
         redirect_to job_path(job)
       end
     end
@@ -91,22 +91,21 @@ module LevelUp
       g.edge[:color] = '#000000'
       g.edge[:arrowhead] = 'open'
 
-      states = {}
-      job.states.each do |state|
-        states[state] = g.add_nodes(state.to_s.humanize.downcase)
-        if state == :start
-          states[state][:fillcolor] = '#5db1a4'
-          states[state][:color] = '#048282'
-
-        elsif state == :end
-          states[state][:fillcolor] = '#b40d28'
-          states[state][:color] = '#600615'
+      tasks = {}
+      job.tasks.each do |task|
+        tasks[task] = g.add_nodes(task.to_s.humanize.downcase)
+        if task == :start
+          tasks[task][:fillcolor] = '#5db1a4'
+          tasks[task][:color] = '#048282'
+        elsif task == :end
+          tasks[task][:fillcolor] = '#b40d28'
+          tasks[task][:color] = '#600615'
         end
       end
 
-      job.states.each do |state|
-        job.transitions(state).each do |transition|
-          g.add_edges(states[state], states[transition])
+      job.tasks.each do |task|
+        job.transitions(task).each do |transition|
+          g.add_edges(tasks[task], tasks[transition])
         end
       end
 

data/app/helpers/level_up/home_helper.rb

@@ -1,7 +1,11 @@
 module LevelUp
   module HomeHelper
     def job_entry(job)
-      link_to "#{job.key} @ #{I18n.l(job.created_at, format: :long)}", job_path(job)
+      if job
+        link_to "#{job.key} @ #{I18n.l(job.created_at, format: :long)}", job_path(job)
+      else
+        '-'
+      end
     end
   end
 end

data/app/models/level_up/job.rb

@@ -1,17 +1,19 @@
 module LevelUp
-  class StateNotFound < StandardError; end
+  class TaskNotFound < StandardError; end
 
   class Job < ActiveRecord::Base
 
-    attr_accessible :key, :state, :timer, :task, :error, :created_at, :updated_at, :started_at, :ended_at, :canceled_at
-    belongs_to :delayed_job, class_name: "::Delayed::Job"
+    attr_accessible :key, :task, :timer, :manual_task, :manual_task_description, :error,
+                    :created_at, :updated_at, :started_at, :ended_at, :canceled_at
 
-    attr_accessor :next_state
+    belongs_to :delayed_job, class_name: '::Delayed::Job'
 
-    scope :queued, lambda { where("delayed_job_id is not null") }
+    attr_accessor :next_task
+
+    scope :queued, lambda { where('delayed_job_id is not null') }
     scope :error, lambda { where(error: true) }
     scope :timer, lambda { where(timer: true) }
-    scope :task, lambda { where(task: true) }
+    scope :manual_task, lambda { where(manual_task: true) }
 
     serialize :backtrace
 
@@ -20,7 +22,11 @@ module LevelUp
         @schema ||= {}
       end
 
-      def states
+      def task_classes
+        @task_classes ||= {}
+      end
+
+      def tasks
         self.schema.keys
       end
 
@@ -31,17 +37,18 @@ module LevelUp
         end
       end
 
-      def state(name, options = {})
-        options.reverse_merge!({moves_to: []})
-        transitions = options[:moves_to].kind_of?(Symbol) ? Array(options[:moves_to]) : options[:moves_to]
+      def task(name, options = {})
+        options.reverse_merge!({transitions: []})
+        transitions = options[:transitions].kind_of?(Symbol) ? Array(options[:transitions]) : options[:transitions]
         schema[name] = transitions
+        task_classes[name] = options[:class_name] if options.key?(:class_name)
       end
 
-      def transitions(state)
-        if self.schema.has_key?(state)
-          self.schema[state]
+      def transitions(task_name)
+        if self.schema.has_key?(task_name)
+          self.schema[task_name]
         else
-          raise StateNotFound, state
+          raise TaskNotFound, task_name
         end
       end
     end
@@ -55,8 +62,8 @@ module LevelUp
       clear!(event_name)
       step!(event_name, allow_transition, allow_retry)
 
-      if next_state
-        event!(next_state, allow_transition, allow_retry)
+      if next_task
+        event!(next_task, allow_transition, allow_retry)
       elsif retry_at
         retry!
       end
@@ -67,15 +74,15 @@ module LevelUp
       clear_error_attributes
       clear_task_attributes
 
-      self.next_state = nil
+      self.next_task = nil
       self.retry_at = nil
-      self.state = event_name if event_name
+      self.task = event_name if event_name
       save
     end
 
     def step!(event_name, allow_transition, allow_retry)
       begin
-        run_state(event_name, allow_transition, allow_retry)
+        run_task(event_name, allow_transition, allow_retry)
       rescue => ex
         set_error(ex)
       ensure
@@ -89,7 +96,7 @@ module LevelUp
       boot_async!(nil, run_at: retry_at)
     end
 
-    def boot_async!(event_name = nil, options = {})
+    def boot_async!(event_name=nil, options={})
       begin
         Delayed::Job.transaction do
           self.delayed_job = delay(options).event!(event_name)
@@ -110,8 +117,8 @@ module LevelUp
       save
     end
 
-    def state?(name)
-      self.state == name.to_s
+    def task?(name)
+      self.task == name.to_s
     end
 
     def cancellable?
@@ -122,59 +129,60 @@ module LevelUp
       !self.delayed_job.nil?
     end
 
-    def states
-      self.class.states
+    def tasks
+      self.class.tasks
     end
 
-    def transitions(state)
-      self.class.transitions(state)
+    def transitions(task_name)
+      self.class.transitions(task_name)
     end
 
-    def state_transitions
-      self.transitions(self.state.to_sym)
+    def task_transitions
+      self.transitions(self.task.to_sym)
     end
 
     def schema
       self.class.schema
     end
 
-    def move_to(state_name)
-      throw :move_to, state_name
+    def move_to!(task_name)
+      throw :move_to, task_name
     end
 
-    def retry_in(delay, error=nil)
+    def retry_in!(delay, error=nil)
       throw :retry_in, delay: delay, error: error
     end
 
-    def manual_task(description)
-      throw :task, description
+    def manual_task!(description)
+      throw :manual_task, description
     end
 
     protected
-      def run_state(state_name, allow_transition, allow_retry)
-        if state_name and respond_to?(state_name)
-          State.new(self, allow_transition, allow_retry).execute(self, state_name)
+      def run_task(task_name, allow_transition, allow_retry)
+        task_name ||= self.task
+
+        if respond_to?(task_name)
+          Task.new(self, allow_transition, allow_retry).execute(self, task_name)
         else
-          state_class = if state?(:start)
-            State::Start
-          elsif state?(:end)
-            State::End
-          elsif state?(:cancel)
-            State::Cancel
+          task_class = if self.class.task_classes.key?(task_name.to_sym)
+            self.class.task_classes[task_name.to_sym].constantize
+          elsif task?(:start)
+            Task::Start
+          elsif task?(:end)
+            Task::End
+          elsif task?(:cancel)
+            Task::Cancel
           else
-            state_name ? next_state_class(state_name) : current_state_class
+            next_task_class(task_name)
           end
-          state = state_class.new(self, allow_transition, allow_retry)
-          state.execute(state, :run)
-        end
-      end
 
-      def current_state_class
-        "#{self.class.name}::#{state.camelize}".constantize
+          task_instance = task_class.new(self, allow_transition, allow_retry)
+          task_instance.execute(task_instance, :run)
+        end
       end
 
-      def next_state_class(state_name)
-        "#{self.class.name}::#{state_name.camelize}".constantize
+      def next_task_class(task_name)
+        "#{self.class.name}::#{task_name.camelize}".constantize
       end
 
       def set_error(error=nil)
@@ -189,8 +197,10 @@ module LevelUp
 
       def set_error_details(error)
         self.failed_at = DateTime.now.utc
-        self.failed_in = state
-        self.backtrace = [error.message] | error.backtrace.take(5)
+        self.failed_in = self.task
+        if Configuration.backtrace_size > 0
+          self.backtrace = [error.message] | error.backtrace.take(Configuration.backtrace_size - 1)
+        end
       end
 
       def clear_error_attributes
@@ -205,8 +215,8 @@ module LevelUp
       end
 
       def clear_task_attributes
-        self.task = false
-        self.task_description = nil
+        self.manual_task = false
+        self.manual_task_description = nil
       end
   end
 end

data/app/models/level_up/{state → task}/cancel.rb

@@ -1,5 +1,5 @@
 module LevelUp
-  class State::Cancel < LevelUp::State
+  class Task::Cancel < LevelUp::Task
     def run
       job.canceled_at = DateTime.now.utc
     end

data/app/models/level_up/{state → task}/end.rb

@@ -1,5 +1,5 @@
 module LevelUp
-  class State::End < LevelUp::State
+  class Task::End < LevelUp::Task
     def run
       job.ended_at = DateTime.now.utc
     end

data/app/models/level_up/task/start.rb

@@ -0,0 +1,8 @@
+module LevelUp
+  class Task::Start < LevelUp::Task
+    def run
+      job.started_at = DateTime.now.utc
+      move_to! job.transitions(:start).first
+    end
+  end
+end

data/app/models/level_up/{state.rb → task.rb}

@@ -1,5 +1,5 @@
 module LevelUp
-  class State
+  class Task
 
     attr_accessor :job, :allow_transition, :allow_retry
 
@@ -10,11 +10,11 @@ module LevelUp
     end
 
     def execute(receiver, method_name)
-      next_state = retry_params = task_description = nil
+      task_name = retry_params = task_description = nil
       ActiveRecord::Base.transaction do
-        next_state = catch(:move_to) do
+        task_name = catch(:move_to) do
           retry_params = catch(:retry_in) do
-            task_description = catch(:task) do
+            task_description = catch(:manual_task) do
               receiver.send(method_name)
               nil
             end
@@ -25,7 +25,7 @@ module LevelUp
       end
 
       if self.allow_transition
-        self.job.next_state = next_state
+        self.job.next_task = task_name
       end
 
       if retry_params and self.allow_retry
@@ -33,21 +33,21 @@ module LevelUp
       end
 
       if task_description
-        self.job.task = true
-        self.job.task_description = task_description
+        self.job.manual_task = true
+        self.job.manual_task_description = task_description
       end
     end
 
-    def move_to(state_name)
-      self.job.move_to(state_name)
+    def move_to!(task_name)
+      self.job.move_to!(task_name)
     end
 
-    def retry_in(delay, error=nil)
-      self.job.retry_in(delay, error)
+    def retry_in!(delay, error=nil)
+      self.job.retry_in!(delay, error)
     end
 
-    def manual_task(description)
-      self.job.manual_task(description)
+    def manual_task!(description)
+      self.job.manual_task!(description)
     end
   end
 end

data/app/views/level_up/home/index.html.erb

@@ -27,12 +27,12 @@
 
   <div class="grid-6">
     <div class="job-status-stats task">
-      <div class="title"><h2><span class="bullet"></span>Task</h2></div>
-      <div class="number"><%= link_to LevelUp::Job.task.size, jobs_path(search: {task_eq: true}) %></div>
+      <div class="title"><h2><span class="bullet"></span>Manual Task</h2></div>
+      <div class="number"><%= link_to LevelUp::Job.manual_task.size, jobs_path(search: {manual_task_eq: true}) %></div>
       <div class="stats">
         <ul>
-          <li><label>Most recent:</label><%= job_entry(LevelUp::Job.task.first) %></li>
-          <li><label>Oldest:</label><%= job_entry(LevelUp::Job.task.last) %></li>
+          <li><label>Most recent:</label><%= job_entry(LevelUp::Job.manual_task.first) %></li>
+          <li><label>Oldest:</label><%= job_entry(LevelUp::Job.manual_task.last) %></li>
         </ul>
       </div>
     </div>

data/app/views/level_up/jobs/edit.html.erb

@@ -20,16 +20,16 @@
             <%= f.text_field :key %>
           </li>
           <li>
-            <%= f.label :state %>
-            <%= f.select :state, options_for_select(@job.states, @job.state) %>
+            <%= f.label :task %>
+            <%= f.select :task, options_for_select(@job.tasks, @job.task) %>
           </li>
           <li>
             <%= f.label :timer %>
             <%= f.check_box :timer %>
           </li>
           <li>
-            <%= f.label :task %>
-            <%= f.check_box :task %>
+            <%= f.label :manual_task %>
+            <%= f.check_box :manual_task %>
           </li>
           <li>
             <%= f.label :error %>

data/app/views/level_up/jobs/index.html.erb

@@ -21,9 +21,9 @@
           <%= f.select :timer_eq,
                        options_for_select([["Any", nil], ["Yes", true], ["No", false]], @search_params[:timer_eq]) %>
 
-          <%= f.label :task_eq, "Task" %>:
-          <%= f.select :task_eq,
-                       options_for_select([["Any", nil], ["Yes", true], ["No", false]], @search_params[:task_eq]) %>
+          <%= f.label :manual_task_eq, "Manual Task" %>:
+          <%= f.select :manual_task_eq,
+                       options_for_select([["Any", nil], ["Yes", true], ["No", false]], @search_params[:manual_task_eq]) %>
 
           <%= f.label :error_eq, "Error" %>:
           <%= f.select :error_eq,
@@ -40,10 +40,10 @@
         <tr>
           <th>Key</th>
           <th>Type</th>
-          <th>State</th>
+          <th>Task</th>
           <th>Queued</th>
           <th>Timer</th>
-          <th>Task</th>
+          <th>Manual Task</th>
           <th>Error</th>
           <th>Created at</th>
         </tr>
@@ -53,10 +53,10 @@
           <tr>
             <td><%= link_to job.key, job_path(job) %></td>
             <td><%= job.type %></td>
-            <td><%= job.state.humanize.downcase %></td>
+            <td><%= job.task.humanize.downcase %></td>
             <td><%= status_tag job.delayed_job, :purple %></td>
             <td><%= status_tag job.timer, :blue %></td>
-            <td><%= status_tag job.task, :orange %></td>
+            <td><%= status_tag job.manual_task, :orange %></td>
             <td><%= status_tag job.error, :red %></td>
             <td><%= l(job.created_at, format: :long) %></td>
           </tr>

data/app/views/level_up/jobs/show.html.erb

@@ -16,10 +16,10 @@
         <li><label>ID:</label><%= @job.id %></li>
         <li><label>Key:</label><%= @job.key %></li>
         <li><label>Type:</label><%= @job.type %></li>
-        <li><label>State:</label><%= @job.state.humanize.downcase %></li>
+        <li><label>Task:</label><%= @job.task.humanize.downcase %></li>
         <li><label>Queued:</label><%= status_tag @job.delayed_job, :purple %></li>
         <li><label>Timer:</label><%= status_tag @job.timer, :blue %></li>
-        <li><label>Task:</label><%= status_tag @job.task, :orange %></li>
+        <li><label>Manual Task:</label><%= status_tag @job.manual_task, :orange %></li>
         <li><label>Error:</label><%= status_tag @job.error, :red %></li>
         <li><label>Created at:</label><%= l(@job.created_at) %></li>
         <li><label>Updated at:</label><%= l(@job.updated_at) %></li>
@@ -47,7 +47,7 @@
   <div class="grid-4">
     <div class="simple-panel job-commands">
       <h2>Job commands</h2>
-      <% if @job.state?(:end) %>
+      <% if @job.task?(:end) %>
         Ended
       <% elsif @job.queued? %>
         <div class="command">
@@ -58,7 +58,7 @@
       <% else %>
         <div class="command">
           <%= form_tag run_job_path(@job) do %>
-            <%= submit_tag "Rerun the current state" %>
+            <%= submit_tag "Rerun the current task" %>
           <% end %>
         </div>
         <div class="command">
@@ -66,9 +66,9 @@
             <%= submit_tag "Reboot" %>
           <% end %>
         </div>
-        <% @job.state_transitions.each do |t| %>
+        <% @job.task_transitions.each do |t| %>
         <div class="command">
-          <%= form_tag move_job_path(@job, state: t) do %>
+          <%= form_tag move_job_path(@job, task: t) do %>
             <% submit_tag "Move to: #{t.to_s.titleize}" %>
           <% end %>
         </div>

data/db/migrate/20130212111454_create_level_up_jobs.rb

@@ -4,11 +4,11 @@ class CreateLevelUpJobs < ActiveRecord::Migration
       t.string :type
       t.integer :delayed_job_id
       t.string :key
-      t.string :state, default: "start"
+      t.string :task, default: 'start'
       t.boolean :error, default: false
       t.boolean :timer, default: false
-      t.boolean :task, default: false
-      t.text :task_description
+      t.boolean :manual_task, default: false
+      t.text :manual_task_description
       t.datetime :failed_at
       t.string :failed_in
       t.text :backtrace
@@ -21,7 +21,7 @@ class CreateLevelUpJobs < ActiveRecord::Migration
 
     add_index :level_up_jobs, :type
     add_index :level_up_jobs, :delayed_job_id
-    add_index :level_up_jobs, :state
+    add_index :level_up_jobs, :task
     add_index :level_up_jobs, :key
   end
 end