back_ops 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 646d949074659a0b194d5e7b74531f5a9189d9ff2e6f743138f4a77cfe0b38c6
-  data.tar.gz: b518e7e56dc5680efb5dc1122e25fceae2192e1f3a07c77fc31112a12f7fe365
+  metadata.gz: 2402fd610b98a0c4f967ba0356034598d273245453fb9f548684ab645c761dc0
+  data.tar.gz: 9490e355132e81b74dc894a670171612adef162a02843ce21588c4814a07446f
 SHA512:
-  metadata.gz: ecf941da420913829f16a23664205ba764c6de6bedfba890ee2df4aaaff2873566250c5d0f79c413fe6067fe12cdf633a2b4ab127aab61f8f05a2901be89e971
-  data.tar.gz: fc9147cd476a9ba12d091c3843360f6032ea572dca2be6f4d4c8287e40b36122844226fa389424e2f645bd09f54852b2af0b930f989fdec851537dd86851cdaa
+  metadata.gz: cc66e230494b0fcefa3ebd3d9fe61a85aabc72c7916e4ab2f309d9d796861213cea375a53b1054686d87f445d50b53ea5d6d58d7c79ffccc89e9ef0929d90046
+  data.tar.gz: 1deceefeaf3325cd4edab641f1be6736899c41e1ac209fe4e770c5331143441cc0b76498e7fc61b3aaa17c5b3bd443c90217913d887c5b7b35c85d3efb36b718

data/README.md

@@ -1,6 +1,6 @@
 # BackOps
 
-Back Ops is intended for background processing of jobs that require multiple tasks to be completed. It executes each task in sequence in a separate Sidekiq worker. This allows for jobs to be retryable if failures occur, but completed tasks are not retried. 
+Back Ops is intended for background processing of jobs that require multiple tasks to be completed. It executes each task in sequence in a separate Sidekiq worker. This allows for jobs to be retryable if failures occur, but completed tasks are not retried.
 
 Progress and error states are tracked in the database, so that that you are always aware of what was processed, and if any task fails, where the failure occured in the process, what the error message is, what the stack trace is, so you know what's happening and you can always retry the job from the failed task.
 
@@ -25,7 +25,7 @@ $ gem install back_ops
 Copy the migration from the gem to your application, then run migrations.
 
 ```bash
-$ rails g back_ops:install
+$ rails g back_ops:install --skip
 $ rails db:migrate
 ```
 
@@ -40,25 +40,28 @@ module Subscriptions
       def self.call(subscription)
         BackOps::Worker.perform_async({
           subscription_id: subscription.id
-        }, [
-          Subscriptions::Actions::Fulfillment::ChargeCreditCard,
-          Subscriptions::Actions::Fulfillment::SendEmailReceipt
-        ])
+        }, {
+          main: [
+            Subscriptions::Actions::Fulfillment::ChargeCreditCard,
+            Subscriptions::Actions::Fulfillment::SetupSubscription,
+            Subscriptions::Actions::Fulfillment::SendEmailReceipt
+          ]
+        })
       end
     end
   end
 end
 ```
 
-Each action receives the operation object which contains the context.
+Each action receives an object with access to all global variables as follows.
 
 ```ruby
 module Subscriptions
   module Actions
     module Fulfillment
       class ChargeCreditCard
-        def self.call(operation)
-          subscription_id = operation.get(:subscription_id)
+        def self.call(action)
+          subscription_id = action.get(:subscription_id)
           subscription = Subscription.find(subscription_id)
           # ...
         end
@@ -71,10 +74,91 @@ end
 You now also have full transparency into each operation and can view it in the admin section by invoking the following code.
 
 ```ruby
-params = { 'subscription_id' => subscription.id }
-operation = BackOps::Operation.includes(:actions).where("name = 'Subscriptions::Operations::Fulfillment' AND context @> ?", params.to_json).first
+operation = BackOps::Operation.includes(:actions).
+            where(name: 'Subscriptions::Operations::Fulfillment').
+            globals_contains(subscription_id: subscription.id).
+            first
 ```
 
+## Branches
+
+Sometimes you need to step through an operation based on conditions. You can accomplish this by using branches. To set this up, define a set of branches that your process can take up front, as follows:
+
+```ruby
+module Subscriptions
+  module Operations
+    class Fullfillment
+      def self.call(subscription)
+        BackOps::Worker.perform_async({
+          subscription_id: subscription.id
+        }, {
+          main: [
+            Subscriptions::Actions::Fulfillment::ChargeCreditCard,
+            Subscriptions::Actions::Fulfillment::SendEmailReceipt
+          ],
+          red_subscriptions: [
+            Subscriptions::Actions::Fulfillment::SetupRedSubscription
+          ],
+          blue_subscriptions: [
+            Subscriptions::Actions::Fulfillment::SetupBlueSubscription
+          ]
+        })
+      end
+    end
+  end
+end
+```
+
+You can then jump to these branches in the code as follows:
+
+```ruby
+module Subscriptions
+  module Actions
+    module Fulfillment
+      class ChargeCreditCard
+        def self.call(action)
+          subscription_id = action.get(:subscription_id)
+          subscription = Subscription.find(subscription_id)
+          # ...
+
+          # The following will force the next action
+          # to be the first action defined in the
+          # :red_subscriptions branch.
+          action.jump_to(:red_subscriptions) if subscription.is_red?
+
+          # OR
+
+          # The following will force the next action
+          # to be the specified action defined in the
+          # :blue_subscriptions branch.
+          action.jump_to(blue_subscriptions: Subscriptions::Actions::Fulfillment::SetupBlueSubscription) if subscription.is_blue?
+        end
+      end
+    end
+  end
+end
+
+# When you're done, jump back to the main branch as follows
+
+module Subscriptions
+  module Actions
+    module Fulfillment
+      class SetupBlueSubscription
+        def self.call(action)
+          subscription_id = action.get(:subscription_id)
+          subscription = Subscription.find(subscription_id)
+          # ...
+
+          action.jump_to(main: Subscriptions::Actions::Fulfillment::SendEmailReceipt)
+        end
+      end
+    end
+  end
+end
+```
+
+**NOTE:** Jump does not stop the rest of the action from being processed. It merely sets a pointer to the next action to be processed when the current action is complete. To exit out of an action, simply `return`.
+
 
 ## Contributing
 To contribute to this project. Clone the repo and create a branch for your changes. When complete, create a pull request into the `develop` branch of this project. Ensure that positive and negative test cases cover your changes and all tests pass.

data/lib/back_ops/action.rb

@@ -1,6 +1,6 @@
 module BackOps
   class Action < ActiveRecord::Base
-    
+
     # == Constants ============================================================
 
     # == Attributes ===========================================================
@@ -21,6 +21,83 @@ module BackOps
 
     self.table_name = 'back_ops_actions'
 
+    def self.after(action)
+      next_on_branch = BackOps::Action.where(operation: action.operation, branch: action.branch).
+                      where('back_ops_actions.order > ?', action.order).
+                      order(order: :asc).
+                      limit(1).
+                      first
+
+      return next_on_branch if next_on_branch.present?
+
+      BackOps::Action.where({
+          operation: action.operation,
+          branch: 'main',
+          completed_at: nil
+        }).
+        limit(1).
+        first
+    end
+
     # == Instance Methods =====================================================
+
+    def premature?
+      perform_at.present? && perform_at > Time.zone.now
+    end
+
+    def get(field)
+      self.operation.get(field)
+    end
+
+    def set(field, value)
+      self.operation.set(field, value)
+    end
+
+    def jump_to(pointer)
+      # :branch
+      # { branch: Action }
+      next_action = nil
+
+      if pointer.is_a?(Symbol)
+        next_action = self.operation.actions.
+                        where(branch: pointer).
+                        order(order: :asc).
+                        limit(1).
+                        first
+      elsif pointer.is_a?(Hash)
+        branch, name = pointer.first
+        next_action = self.operation.actions.
+                        where(name: name, branch: branch).
+                        order(order: :asc).
+                        limit(1).
+                        first
+      else
+        raise ArgumentError, 'jump_to only accepts as Symbol or a Hash'
+      end
+
+      raise "Could not jump_to(#{pointer.inspect}). Action not found." if next_action.nil?
+
+      self.operation.next_action = next_action
+      self.operation.save!
+    end
+
+    def mark_errored(e)
+      self.error_message = e.message
+      self.stack_trace = e.backtrace
+      self.errored_at = Time.zone.now
+
+      self.attempts_count += 1
+      self.save!
+    end
+
+    def mark_completed
+      self.errored_at = nil
+      self.error_message = nil
+      self.stack_trace = nil
+
+      self.completed_at = Time.zone.now
+      self.attempts_count += 1
+      self.save!
+    end
   end
 end

data/lib/back_ops/operation.rb

@@ -9,12 +9,18 @@ module BackOps
 
     # == Relationships ========================================================
 
+    belongs_to :next_action, class_name: 'BackOps::Action'
+
     has_many :actions, class_name: 'BackOps::Action'
 
     # == Validations ==========================================================
 
     # == Scopes ===============================================================
 
+    scope :globals_contains, ->(hash) {
+      where('globals @> ?', hash.to_json)
+    }
+
     # == Callbacks ============================================================
 
     # == Class Methods ========================================================
@@ -23,13 +29,22 @@ module BackOps
 
     # == Instance Methods =====================================================
 
+    def first_action
+      self.actions.
+        where(back_ops_actions: { branch: 'main' }).
+        order(order: :asc).
+        limit(1).
+        first
+    end
+
     def get(field)
-      context[field.to_s]
+      globals[field.to_s]
     end
 
     def set(field, value)
-      context[field.to_s] = value
+      globals[field.to_s] = value
       save!
     end
+
   end
 end

data/lib/back_ops/version.rb

@@ -1,3 +1,3 @@
 module BackOps
-  VERSION = '0.2.0'
+  VERSION = '1.0.0'
 end

data/lib/back_ops/worker.rb

@@ -13,39 +13,58 @@ module BackOps
 
     # == Class Methods ========================================================
 
-    def self.perform_async(context, actions)
-      operation = setup_operation_and_actions(context, actions)
+    def self.perform_async(globals, actions)
+      operation = setup_operation_and_actions(globals, actions)
       super(operation.id)
     end
 
-    def self.perform_in(interval, context, actions)
-      operation = setup_operation_and_actions(context, actions)
+    def self.perform_in(interval, globals, actions)
+      operation = setup_operation_and_actions(globals, actions)
       super(interval, operation.id)
     end
 
-    def self.perform_at(interval, context, action)
-      perform_in(interval, context, action)
+    def self.perform_at(interval, globals, action)
+      perform_in(interval, globals, action)
     end
 
-    def self.setup_operation_and_actions(context, actions)
-      raise ArgumentError, 'Cannot process empty actions' if actions.blank?
-      context.deep_stringify_keys!
+    def self.setup_operation_and_actions(globals, branches)
+      raise ArgumentError, 'Cannot process empty actions' if branches.blank?
+
+      globals ||= {}
+      globals.deep_stringify_keys!
 
       operation = BackOps::Operation.create_or_find_by({
-        params_hash: Digest::MD5.hexdigest("#{context}|#{actions}"),
+        params_hash: Digest::MD5.hexdigest("#{globals}|#{branches}"),
         name: ancestors[1]
       })
-      operation.context.merge!(context)
+      operation.globals.merge!(globals)
       operation.save!
-      
-      actions.each_with_index do |action, index|
-        BackOps::Action.create_or_find_by({
-          operation: operation,
-          name: action,
-          order: index
-        })
+
+      counter = 0
+
+      branches.each do |branch, actions|
+        actions.each do |action_with_options|
+          action_name, options = [*action_with_options]
+
+          options = {
+            'perform_at' => nil
+          }.merge(options.try(:deep_stringify_keys) || {})
+
+          action = BackOps::Action.create_or_find_by({
+            operation: operation,
+            branch: branch,
+            name: action_name,
+            perform_at: options['perform_at'],
+            order: counter
+          })
+
+          counter += 1
+        end
       end
 
+      operation.next_action = operation.first_action
+      operation.save!
+
       operation
     end
 
@@ -59,45 +78,39 @@ module BackOps
     private
 
     def process(operation)
-      action_items = BackOps::Action.where({
-        operation: operation,
-        completed_at: nil
-      }).order(order: :asc)
+      action = operation.next_action
+      return true if action.blank?
+      return process_next(operation, at: action.perform_at.to_f) if action.premature?
 
-      return true if action_items.blank?
-
-      active_item = action_items[0]
-      next_item = action_items[1]
-
-      if active_item.errored_at.present?
-        active_item.errored_at = nil
-        active_item.error_message = nil
-        active_item.stack_trace = nil
-        active_item.save!
-      end
-      
       begin
-        active_item.name.constantize.call(operation)
+        action.name.constantize.call(action)
+        action.mark_completed
 
-        active_item.completed_at = Time.zone.now
-        active_item.attempts_count += 1
-        active_item.save!
+        operation.next_action = BackOps::Action.after(action)
+        operation.save!
 
-        if next_item.present?
-          Sidekiq::Client.push('class' => self.class.name, 'args' => [operation.id])
+        if operation.next_action.present?
+          process_next(operation)
         else
-          operation.completed_at = active_item.completed_at
+          operation.completed_at = action.completed_at
           operation.save!
         end
-      rescue => e
-        active_item.error_message = e.message
-        active_item.stack_trace = e.backtrace
-        active_item.errored_at = Time.zone.now
-        active_item.attempts_count += 1
-        active_item.save!
 
+      rescue => e
+        action.mark_errored(e)
         raise
       end
     end
+
+    def process_next(operation, options = {})
+      options.deep_stringify_keys!
+
+      Sidekiq::Client.push({
+        'class' => self.class.name,
+        'args' => [operation.id]
+      }.merge(options))
+
+      true
+    end
   end
 end

data/lib/generators/back_ops/install_generator.rb

@@ -9,18 +9,19 @@ module BackOps
     source_root File.expand_path('templates', __dir__)
     desc 'Installs the BackOps migration file.'
 
-    def create_migration_file
+    def create_migrations
       migration_template(
-        'migration.rb',
+        'create_back_ops_tables.rb',
         'db/migrate/create_back_ops_tables.rb',
         migration_version: migration_version,
       )
+      migration_template(
+        'update_back_ops_tables_v1.rb',
+        'db/migrate/update_back_ops_tables_v1.rb',
+        migration_version: migration_version,
+      )
     end
 
-    # def self.next_migration_number(dirname)
-    #   ActiveRecord::Migration.next_migration_number(dirname)
-    # end
-
     private
 
     def migration_version

data/lib/generators/back_ops/templates/{migration.rb.tt → create_back_ops_tables.rb.tt}

@@ -5,18 +5,21 @@ class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version
     create_table :back_ops_operations do |t|
       t.string :name
       t.string :params_hash
-      t.jsonb :context, null: false, default: {}
+      t.jsonb :globals, null: false, default: {}
+      t.integer :next_action_id, limit: 8
       t.timestamp :completed_at
 
       t.timestamps
     end
 
     add_index :back_ops_operations, [:name, :params_hash]
-    
+
     create_table :back_ops_actions do |t|
       t.integer :operation_id, limit: 8
       t.integer :order, null: false, default: 0
+      t.text :branch
       t.text :name
+      t.timestamp :perform_at
       t.text :error_message
       t.text :stack_trace
       t.timestamp :errored_at

data/lib/generators/back_ops/templates/update_back_ops_tables_v1.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    add_column :back_ops_operations, :next_action_id, :integer, limit: 8
+    rename_column :back_ops_operations, :context, :globals
+
+    add_column :back_ops_actions, :branch, :text
+    add_column :back_ops_actions, :perform_at, :timestamp
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: back_ops
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Aaron Price
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-09 00:00:00.000000000 Z
+date: 2021-04-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -111,7 +111,8 @@ files:
 - lib/back_ops/version.rb
 - lib/back_ops/worker.rb
 - lib/generators/back_ops/install_generator.rb
-- lib/generators/back_ops/templates/migration.rb.tt
+- lib/generators/back_ops/templates/create_back_ops_tables.rb.tt
+- lib/generators/back_ops/templates/update_back_ops_tables_v1.rb.tt
 homepage: https://github.com/aaronprice/back_ops
 licenses:
 - MIT