opera 0.5.0 → 0.5.1

data/docs/examples/success-blocks.md

@@ -0,0 +1,68 @@
+# Success Blocks
+
+Steps inside a `success` block continue executing even if they return `false`. Errors added inside a success block **do** stop execution of subsequent non-success steps. Use success blocks for side effects that shouldn't halt the pipeline on falsy returns (e.g., sending emails, logging).
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  success :populate
+
+  step :create
+  step :update
+
+  success do
+    step :send_email
+    step :output
+  end
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def populate
+    context[:attributes] = {}
+    context[:valid] = false
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  end
+
+  def update
+    profile.update(updated_at: 1.day.ago)
+  end
+
+  # NOTE: We can add an error in this step and it won't break the execution
+  def send_email
+    result.add_error('mailer', 'Missing dependency')
+    mailer&.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: context[:profile] }
+  end
+end
+```
+
+## Example output
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  current_account: Account.find(1)
+})
+#<Opera::Operation::Result:0x007fd0248e5638 @errors={"mailer"=>["Missing dependency"]}, @information={}, @executions=[:profile_schema, :populate, :create, :update, :send_email, :output], @output={:model=>#<Profile id: 40, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2019-01-03 12:21:35", updated_at: "2019-01-02 12:21:35", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+```

data/docs/examples/transactions.md

@@ -0,0 +1,227 @@
+# Transactions
+
+Wrap multiple steps in a database transaction. If any step adds an error or raises an exception, the transaction is rolled back.
+
+## Configuration
+
+Set the transaction class either globally or per-operation:
+
+```ruby
+# Global
+Opera::Operation::Config.configure do |config|
+  config.transaction_class = ActiveRecord::Base
+  config.transaction_method = :transaction     # default
+  config.transaction_options = { requires_new: true }  # optional
+end
+
+# Per-operation
+class MyOperation < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = Profile
+  end
+end
+```
+
+## Failing transaction
+
+When a step inside a transaction fails, the entire transaction is rolled back:
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = Profile
+  end
+
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  transaction do
+    step :create
+    step :update
+  end
+
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  end
+
+  def update
+    profile.update(example_attr: :Example)
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+### Example with non-existing attribute
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+D, [2020-08-14T16:13:30.946466 #2504] DEBUG -- :   Account Load (0.5ms)  SELECT  "accounts".* FROM "accounts" WHERE "accounts"."deleted_at" IS NULL AND "accounts"."id" = $1 LIMIT $2  [["id", 1], ["LIMIT", 1]]
+D, [2020-08-14T16:13:30.960254 #2504] DEBUG -- :    (0.2ms)  BEGIN
+D, [2020-08-14T16:13:30.983981 #2504] DEBUG -- :   SQL (0.7ms)  INSERT INTO "profiles" ("first_name", "last_name", "created_at", "updated_at", "account_id") VALUES ($1, $2, $3, $4, $5) RETURNING "id"  [["first_name", "foo"], ["last_name", "bar"], ["created_at", "2020-08-14 16:13:30.982289"], ["updated_at", "2020-08-14 16:13:30.982289"], ["account_id", 1]]
+D, [2020-08-14T16:13:30.986233 #2504] DEBUG -- :    (0.2ms)  ROLLBACK
+D, [2020-08-14T16:13:30.988231 #2504] DEBUG -- :    unknown attribute 'example_attr' for Profile. (ActiveModel::UnknownAttributeError)
+```
+
+## Passing transaction
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = Profile
+  end
+
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  transaction do
+    step :create
+    step :update
+  end
+
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  end
+
+  def update
+    profile.update(updated_at: 1.day.ago)
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+### Example with updating timestamp
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+D, [2020-08-17T12:10:44.842392 #2741] DEBUG -- :   Account Load (0.7ms)  SELECT  "accounts".* FROM "accounts" WHERE "accounts"."deleted_at" IS NULL AND "accounts"."id" = $1 LIMIT $2  [["id", 1], ["LIMIT", 1]]
+D, [2020-08-17T12:10:44.856964 #2741] DEBUG -- :    (0.2ms)  BEGIN
+D, [2020-08-17T12:10:44.881332 #2741] DEBUG -- :   SQL (0.7ms)  INSERT INTO "profiles" ("first_name", "last_name", "created_at", "updated_at", "account_id") VALUES ($1, $2, $3, $4, $5) RETURNING "id"  [["first_name", "foo"], ["last_name", "bar"], ["created_at", "2020-08-17 12:10:44.879684"], ["updated_at", "2020-08-17 12:10:44.879684"], ["account_id", 1]]
+D, [2020-08-17T12:10:44.886168 #2741] DEBUG -- :   SQL (0.6ms)  UPDATE "profiles" SET "updated_at" = $1 WHERE "profiles"."id" = $2  [["updated_at", "2020-08-16 12:10:44.883164"], ["id", 47]]
+D, [2020-08-17T12:10:44.898132 #2741] DEBUG -- :    (10.3ms)  COMMIT
+#<Opera::Operation::Result:0x0000556528f29058 @errors={}, @information={}, @executions=[:profile_schema, :create, :update, :send_email, :output], @output={:model=>#<Profile id: 47, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-17 12:10:44", updated_at: "2020-08-16 12:10:44", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+```
+
+## Using finish! inside a transaction
+
+Calling `finish!` inside a transaction stops execution without rolling back -- the transaction commits successfully:
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  step :build_record
+  step :create
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def build_record
+    self.profile = current_account.profiles.build(params)
+    self.profile.force_name_validation = true
+  end
+
+  def create
+    self.profile = profile.save
+    finish!
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output(model: profile)
+  end
+end
+```
+
+### Call
+
+```ruby
+result = Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x007fc2c59a8460 @errors={}, @information={}, @executions=[:profile_schema, :build_record, :create]>
+```

data/docs/examples/validations.md

@@ -0,0 +1,139 @@
+# Validations
+
+Opera supports `Dry::Validation::Result` and `Opera::Operation::Result` as return types from validate steps. Validations accumulate errors -- all validations run even if earlier ones fail, so the caller gets all errors at once.
+
+## Example with sanitizing parameters
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  step :create
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      configure { config.input_processor = :sanitizer }
+
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(context[:profile_schema_output])
+  end
+
+  def send_email
+    return true unless mailer
+
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+# NOTE: Last name is missing in output model
+#<Opera::Operation::Result:0x000055e36a1fab78 @errors={}, @information={}, @executions=[:profile_schema, :create, :send_email, :output], @output={:model=>#<Profile id: 44, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: nil, created_at: "2020-08-17 11:07:08", updated_at: "2020-08-17 11:07:08", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+```
+
+## Example with old (ActiveModel) validations
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :mailer
+  end
+
+  validate :profile_schema
+
+  step :build_record
+  step :old_validation
+  step :create
+  step :send_email
+  step :output
+
+  def profile_schema
+    Dry::Validation.Schema do
+      required(:first_name).filled
+    end.call(params)
+  end
+
+  def build_record
+    self.profile = current_account.profiles.build(params)
+    self.profile.force_name_validation = true
+  end
+
+  def old_validation
+    return true if profile.valid?
+
+    result.add_information(missing_validations: "Please check dry validations")
+    result.add_errors(profile.errors.messages)
+
+    false
+  end
+
+  def create
+    profile.save
+  end
+
+  def send_email
+    mailer.send_mail(profile: profile)
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+end
+```
+
+### Call with valid parameters
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo,
+  last_name: :bar
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x0000560ebc9e7a98 @errors={}, @information={}, @executions=[:profile_schema, :build_record, :old_validation, :create, :send_email, :output], @output={:model=>#<Profile id: 41, user_id: nil, linkedin_uid: nil, picture: nil, headline: nil, summary: nil, first_name: "foo", last_name: "bar", created_at: "2020-08-14 19:15:12", updated_at: "2020-08-14 19:15:12", agree_to_terms_and_conditions: nil, registration_status: "", account_id: 1, start_date: nil, supervisor_id: nil, picture_processing: false, statistics: {}, data: {}, notification_timestamps: {}, suggestions: {}, notification_settings: {}, contact_information: []>}>
+```
+
+### Call with INVALID parameters
+
+```ruby
+Profile::Create.call(params: {
+  first_name: :foo
+}, dependencies: {
+  mailer: MyMailer,
+  current_account: Account.find(1)
+})
+
+#<Opera::Operation::Result:0x0000560ef76ba588 @errors={:last_name=>["can't be blank"]}, @information={:missing_validations=>"Please check dry validations"}, @executions=[:build_record, :old_validation]>
+```

data/docs/examples/within.md

@@ -0,0 +1,166 @@
+# Within
+
+`within` wraps one or more steps with a method you define on the operation. The method must `yield` to execute the nested steps. If it does not yield, the nested steps are skipped. Normal break conditions (errors, `finish!`) still apply inside the block.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account
+  end
+
+  step :build
+
+  within :read_from_replica do
+    step :check_duplicate
+    step :validate_quota
+  end
+
+  step :create
+  step :output
+
+  def build
+    self.profile = current_account.profiles.build(params)
+  end
+
+  def check_duplicate
+    result.add_error(:base, 'already exists') if Profile.exists?(email: params[:email])
+  end
+
+  def validate_quota
+    result.add_error(:base, 'quota exceeded') if current_account.profiles.count >= 100
+  end
+
+  def create
+    profile.save!
+  end
+
+  def output
+    result.output = { model: profile }
+  end
+
+  private
+
+  def read_from_replica(&block)
+    ActiveRecord::Base.connected_to(role: :reading, &block)
+  end
+end
+```
+
+## Inline usage
+
+The wrapper method can also be used inline inside any step method when you need the wrapper for only part of that method's logic:
+
+```ruby
+def some_step
+  value = read_from_replica { Profile.count }
+  result.output = { count: value }
+end
+
+private
+
+def read_from_replica(&block)
+  ActiveRecord::Base.connected_to(role: :reading, &block)
+end
+```
+
+## Mixing step and operation inside within
+
+`within` can wrap any combination of `step` and `operation` instructions. All of them execute inside the wrapper, and their outputs are available in context afterwards as usual.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :quota_checker
+  end
+
+  within :read_from_replica do
+    step :check_duplicate
+    operation :fetch_quota
+  end
+
+  step :create
+  step :output
+
+  def check_duplicate
+    result.add_error(:base, 'already exists') if Profile.exists?(email: params[:email])
+  end
+
+  def fetch_quota
+    quota_checker.call(params: params)
+  end
+
+  def create
+    self.profile = current_account.profiles.create(params)
+  end
+
+  def output
+    result.output = { model: profile, quota: context[:fetch_quota_output] }
+  end
+
+  private
+
+  def read_from_replica(&block)
+    ActiveRecord::Base.connected_to(role: :reading, &block)
+  end
+end
+```
+
+## Nesting within inside a transaction
+
+`within` can be placed inside a `transaction` block alongside other instructions. If any step or operation inside `within` fails, the error propagates up and the transaction is rolled back as normal.
+
+```ruby
+class Profile::Create < Opera::Operation::Base
+  configure do |config|
+    config.transaction_class = ActiveRecord::Base
+  end
+
+  context do
+    attr_accessor :profile
+  end
+
+  dependencies do
+    attr_reader :current_account, :quota_checker, :audit_logger
+  end
+
+  transaction do
+    within :read_from_replica do
+      step :check_duplicate
+      operation :fetch_quota
+    end
+    operation :write_audit_log
+  end
+
+  step :output
+
+  def check_duplicate
+    result.add_error(:base, 'already exists') if Profile.exists?(email: params[:email])
+  end
+
+  def fetch_quota
+    quota_checker.call(params: params)
+  end
+
+  def write_audit_log
+    audit_logger.call(params: params)
+  end
+
+  def output
+    result.output = { quota: context[:fetch_quota_output] }
+  end
+
+  private
+
+  def read_from_replica(&block)
+    ActiveRecord::Base.connected_to(role: :reading, &block)
+  end
+end
+```

data/lib/opera/operation/config.rb

@@ -17,7 +17,7 @@ module Opera
         @instrumentation_class = self.class.instrumentation_class
 
         @mode = self.class.mode || DEVELOPMENT_MODE
-        @reporter = custom_reporter || self.class.reporter
+        @reporter = self.class.reporter
 
         validate!
       end
@@ -26,10 +26,6 @@ module Opera
         yield self
       end
 
-      def custom_reporter
-        Rails.application.config.x.reporter.presence if defined?(Rails)
-      end
-
       private
 
       def validate!
@@ -47,7 +43,7 @@ module Opera
         end
 
         def development_mode?
-          mode == DEFAULT_MODE
+          mode == DEVELOPMENT_MODE
         end
 
         def production_mode?

data/lib/opera/operation/executor.rb

@@ -20,15 +20,24 @@ module Opera
       end
 
       def evaluate_instructions(instructions = [])
-        instruction_copy = Marshal.load(Marshal.dump(instructions))
-
-        while instruction_copy.any?
-          instruction = instruction_copy.shift
+        instructions.each do |instruction|
           evaluate_instruction(instruction)
           break if break_condition
         end
       end
 
+      # Executes the operation method named in the instruction, instruments it,
+      # and records the execution. This is the shared primitive that all executors
+      # use to invoke a step method without mutating the instruction hash.
+      def execute_step(instruction)
+        method = instruction[:method]
+
+        Instrumentation.new(operation).instrument(name: "##{method}", level: :step) do
+          result.add_execution(method) unless production_mode?
+          operation.send(method)
+        end
+      end
+
       # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity
       def evaluate_instruction(instruction)
         case instruction[:kind]

data/lib/opera/operation/instructions/executors/finish_if.rb

@@ -6,8 +6,7 @@ module Opera
       module Executors
         class FinishIf < Executor
           def call(instruction)
-            instruction[:kind] = :step
-            operation.finish! if super
+            operation.finish! if execute_step(instruction)
           end
         end
       end

data/lib/opera/operation/instructions/executors/operation.rb

@@ -6,8 +6,7 @@ module Opera
       module Executors
         class Operation < Executor
           def call(instruction)
-            instruction[:kind] = :step
-            operation_result = super
+            operation_result = execute_step(instruction)
             save_information(operation_result)
 
             if operation_result.success?

data/lib/opera/operation/instructions/executors/operations.rb

@@ -9,8 +9,7 @@ module Opera
 
           # rubocop:disable Metrics/MethodLength
           def call(instruction)
-            instruction[:kind] = :step
-            operations_results = super
+            operations_results = execute_step(instruction)
 
             case operations_results
             when Array

data/lib/opera/operation/instructions/executors/step.rb

@@ -6,12 +6,7 @@ module Opera
       module Executors
         class Step < Executor
           def call(instruction)
-            method = instruction[:method]
-
-            Instrumentation.new(operation).instrument(name: "##{method}", level: :step) do
-              operation.result.add_execution(method) unless production_mode?
-              operation.send(method)
-            end
+            execute_step(instruction)
           end
         end
       end