clean_actions 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b6ce7dad0e85ad8963eaeae13b7ebed2286e4cfb337aefea479bfad654f8b01c
+  data.tar.gz: a2e81f2e47694e43b8c8c417c4b3849f1f5f76ac87c13762f683363178059ab5
+SHA512:
+  metadata.gz: 0137b1b214dbc703c3b1e0c339e96be565748370f8c4d387d516bfcdca147b6107543e89b560f772418040c46c1c1222127218aba65d5621e758572f316b6574
+  data.tar.gz: e8be5458cc24adc7cd75b5fc08a78a66b475f2d06298c106eaea20794702fe34cf235ee554659b8ac6e5c91a6a4095149511d5c0f8619a0166409542b593c8e9

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change log
+
+## main
+
+# 0.1.0 (21-09-2023)
+
+- Initial version ([@DmitryTsepelev])
+
+[@DmitryTsepelev]: https://github.com/DmitryTsepelev

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 DmitryTsepelev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,289 @@
+# CleanActions
+
+[![Gem Version](https://badge.fury.io/rb/clean_actions.svg)](https://rubygems.org/gems/clean_actions)
+[![Tests status](https://github.com/DmitryTsepelev/clean_actions/actions/workflows/test.yml/badge.svg)](https://github.com/DmitryTsepelev/clean_actions/actions/workflows/test.yml)
+![](https://ruby-gem-downloads-badge.herokuapp.com/clean_actions?type=total)
+
+A modern modular service object toolkit for Rails, that respects database transactions and adds type checks to returned values.
+
+```ruby
+class AddItemToCart < CleanActions::Base
+  includes Dry::Initializer
+
+  option :user
+  option :item
+
+  # This will report an error if someone accidentally returns wrong instance from #perform_actions.
+  returns OrderItem
+
+  # Such checks are happening inside the transaction right before #perform_actions, so
+  # you can halt early.
+  fail_with(:banned_user) { @user.banned? }
+
+  # This method is executed inside the database transaction.
+  # If transaction was opened by another action, which called this one - savepoint won't be created.
+  # Last line will be used as a returned value.
+  def perform_actions
+    @order = CreateOrder.call(user: @user) # if CreateOrder fails - transaction will be rolled back
+    @order.order_items.create!(item: @item) # if something else fails here - transaction will be rolled back as well
+  end
+
+  # This method will be called for each action after whole transaction commits successfully.
+  def after_commit
+    ItemAddedSubscription.trigger(order: @order)
+  end
+end
+```
+
+## Usage
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clean_actions'
+```
+
+## Writing your actions
+
+Inherit your actions from `CleanActions::Base`, which by defaut includes [typed returns](/README.md#Typed-Returns) and [fail_with](/README.md#Fail-With).
+
+> If you want to exclude something — inherit from `CleanActions::Action` and configure all includes you need.
+
+You should implement at least one of two methods—`#perform_actions` or `#after_commit`:
+
+```ruby
+class AddItemToCart < CleanActions::Base
+  def perform_actions
+    @order = CreateOrder.call(user: @user)
+    @order_item = @order.order_items
+      .create_with(quantity: 0)
+      .find_or_create_by!(item: @item)
+  end
+
+  def after_commit
+    NotifyUserAboutUpdatedOrderItemJob.perform_later(order_item: @order_item)
+  end
+end
+```
+
+When first action is called, it will be wrapped to the database transaction, and all actions called by it will be inside the same transaction. All `#perform_actions` will happen inside the transaction (and rolled back if needed). After that, in case of successful commit, all `#after_commit` actions will happen in order.
+
+## Error handling
+
+If something goes wrong and transaction will raise an error—it will cause transaction to be rolled back. Errors should not be used as a way to manage a control flow, so all unhandled exceptions raised inside actions, will be reraised.
+
+However, if you do expect an error—it's better to represent it as a returned value. Use `#fail!(:reason)` for that:
+
+```ruby
+class AddItemToCart < CleanActions::Base
+  def perform_actions
+    fail!(:shop_is_closed)
+  end
+end
+
+AddItemToCart.call # => CleanActions::ActionFailure(reason: :shop_is_closed)
+```
+
+## Typed Returns
+
+Have you ever been in situation, when it's not clear, what will be returned by the class? Do you have some type system in your project? While you are setting it up—use typed returns:
+
+```ruby
+class FetchOrder < CleanActions::Base
+  returns Order
+
+  option :order_id
+
+  def perform_actions
+    User.find(order_id)
+  end
+end
+
+FetchOrder.call(42) # => "expected FetchOrder to return Order, returned User" is logged
+```
+
+The last line of `#perform_actions` will be returned. Note that if you have this module on but configure nothing—action will return `nil`.
+
+## Isolation levels
+
+By default transactions are executed in `READ COMMITTED` level. You can override it for a specific aciton:
+
+```ruby
+class FetchOrder < CleanActions::Base
+  with_isolation_level :repeatable_read
+
+  option :order_id
+
+  def perform_actions
+    # actions
+  end
+end
+
+FetchOrder.call(42) # => "expected FetchOrder to return Order, returned User" is logged
+```
+
+Also, you can configure it for the whole project:
+
+```ruby
+CleanActions.config.isolation_level = :serializable
+```
+
+## Savepoints
+
+If you want to run one action inside another but want a nested one be inside the ([SAVEPOINT](https://www.postgresql.org/docs/current/sql-savepoint.html))—use `with_savepoint`:
+
+```ruby
+class AddItemToCart < CleanActions::Base
+  def perform_actions
+    @order = CreateOrder.call(user: @user, with_savepoint: true)
+  end
+end
+```
+
+Note that `after_commit` still happens when the transaction from the root action is commited.
+
+## Error configuration
+
+When something weird happens during the action execution, the message is sent to the Rails log. Also, errors are _raised_ in development and test environments. To change that you can use `.config` object:
+
+```ruby
+CleanActions.config.raise_errors = true
+```
+
+Here is a list of errors affected by this config:
+
+- type mismatch from (Typed Returns)[/README.md#Typed-Returns];
+- action with (#before_transaction)[/README.md#before_transaction] is called inside the transaction;
+- invalid isolation levels;
+- action calls from unexpected places.
+
+## Advanced Lifecycle
+
+This section contains some additional hooks to improve your actions.
+
+### before_transaction
+
+If you want to do something outside the transaction (e.g., some IO operation)—use `before_transaction`:
+
+```ruby
+class SyncData < CleanActions::Base
+  def before_transaction
+    @response = ApiClient.fetch
+  end
+
+  def perform_actions
+    # use response
+  end
+end
+```
+
+Please note, that error will be risen if this action will be called from another action (and transaction will be already in progress):
+
+```ruby
+class OtherAction < CleanActions::Base
+  def perform_actions
+    SyncData.call
+  end
+end
+
+OtherAction.call # => "SyncData#before_transaction was called inside the transaction"  is logged
+```
+
+⚠️ Do not call other actions from this method!
+
+### before_actions
+
+If you want to do something before action — use `#before_action` callback, that is run inside the transaction but before `#perform_actions`:
+
+```ruby
+class AddItemToCart < CleanActions::Base
+  def before_actions
+    @order = Order.find(order_id)
+  end
+
+  def perform_actions
+    # use order
+  end
+end
+```
+
+⚠️ Do not call other actions from this method!
+
+### fail_with
+
+Fail with is a syntax sugar over `#fail!` to decouple pre–checks from the execution logic. Take a look at the improved example from the [Error Handling](/README.md#Error-Handling) section:
+
+```ruby
+class AddItemToCart < CleanActions::Base
+  fail_with(:shop_is_closed) { Time.now.hour.in?(10..18) }
+
+  def perform_actions
+    # only when shop is open
+  end
+end
+```
+
+If you want to check that action can be called successfully (at least, preconditions are met) — you can use `#dry_call`, which will run _all_ preconditions and return all failures:
+
+```ruby
+class CheckNumber < CleanActions::Base
+  fail_with(:fail1) { @value == 1 }
+  fail_with(:fail_odd) { @value.odd? }
+
+  def initialize(value:)
+    @value = value
+  end
+end
+
+CheckNumber.dry_call(value: 1) # => [CleanActions::ActionFailure.new(:fail_odd), CleanActions::ActionFailure.new(:fail1)]
+```
+
+⚠️ Do not call other actions from this method!
+
+### rollback
+
+Actions rollback things inside `#perform_actions` in case of failure because of the database transactions. However, what if you want to rollback something non–transactional?
+
+Well, if you sent an email or enqueued background job—you cannot do much,. Just in case, you want do something—here is a `#rollback` method that happens only when action fails.
+
+```ruby
+class DumbCounter < CleanActions::Base
+  def perform_actions
+    Thread.current[:counter] ||= 0
+    Thread.current[:counter] += 1
+    fail!(:didnt_i_say_its_a_dumb_counter)
+  end
+
+  def rollback
+    Thread.current[:counter] ||= 0
+    Thread.current[:counter] -= 1
+  end
+end
+
+DumbCounter.call
+Thread.current[:counter] # => 0
+```
+
+### ensure
+
+Opened file inside `#perform_actions` or want to do some other cleanup even when action fails? Use `#ensure`:
+
+```ruby
+class UseFile < CleanActions::Base
+  def perform_actions
+    @file = File.open # ...
+  end
+
+  def ensure
+    @file.close
+  end
+end
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/DmitryTsepelev/clean_actions.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/clean_actions/action.rb

@@ -0,0 +1,71 @@
+module CleanActions
+  class Action
+    class << self
+      def call(with_savepoint: false, **kwargs)
+        new(**kwargs).call(with_savepoint: with_savepoint)
+      end
+
+      def before_actions(&block)
+        before_actions_blocks << block
+      end
+
+      def before_actions_blocks
+        @before_actions_blocks ||= []
+      end
+
+      def with_isolation_level(isolation_level)
+        IsolationLevelValidator.validate(isolation_level)
+
+        @isolation_level = isolation_level
+      end
+
+      def isolation_level
+        @isolation_level ||= CleanActions.config.isolation_level
+      end
+    end
+
+    def call(with_savepoint: false)
+      if TransactionRunner.action_calls_restricted_by
+        ErrorReporter.report("calling action #{self.class.name} is resticted inside ##{TransactionRunner.action_calls_restricted_by}")
+      end
+
+      TransactionRunner.restrict_action_calls_by(:before_transaction) { perform_before_transaction }
+
+      TransactionRunner.new(self).run(with_savepoint: with_savepoint) do
+        TransactionRunner.restrict_action_calls_by(:before_actions) do
+          self.class.before_actions_blocks.each { |b| instance_eval(&b) }
+        end
+
+        perform_actions
+      end
+    end
+
+    def fail!(reason)
+      raise ActionFailure.new(reason)
+    end
+
+    def perform_actions
+    end
+
+    def after_commit
+    end
+
+    def ensure
+    end
+
+    def rollback
+    end
+
+    private
+
+    def perform_before_transaction
+      return unless respond_to?(:before_transaction)
+
+      if Thread.current[:transaction_started]
+        ErrorReporter.report("#{self.class.name}#before_transaction was called inside the transaction")
+      end
+
+      before_transaction
+    end
+  end
+end

data/lib/clean_actions/action_failure.rb

@@ -0,0 +1,14 @@
+module CleanActions
+  class ActionFailure < ActiveRecord::Rollback
+    attr_reader :reason
+
+    def initialize(reason)
+      @reason = reason
+      super
+    end
+
+    def ==(other)
+      reason == other.reason
+    end
+  end
+end

data/lib/clean_actions/base.rb

@@ -0,0 +1,6 @@
+module CleanActions
+  class Base < Action
+    include TypedReturns
+    include FailWith
+  end
+end

data/lib/clean_actions/configuration.rb

@@ -0,0 +1,20 @@
+module CleanActions
+  class Configuration
+    attr_accessor :raise_errors
+
+    def initialize
+      @raise_errors = Rails.env.development? || Rails.env.test?
+    end
+
+    def isolation_level=(isolation_level)
+      IsolationLevelValidator.validate(isolation_level, allow_serializable: true)
+      @isolation_level = isolation_level
+    end
+
+    def isolation_level
+      @isolation_level ||= :read_committed
+    end
+
+    alias_method :raise_errors?, :raise_errors
+  end
+end

data/lib/clean_actions/error_reporter.rb

@@ -0,0 +1,9 @@
+module CleanActions
+  class ErrorReporter
+    def self.report(message)
+      Rails.logger.info(message)
+
+      raise message if CleanActions.config.raise_errors?
+    end
+  end
+end

data/lib/clean_actions/fail_with.rb

@@ -0,0 +1,25 @@
+module CleanActions
+  module FailWith
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    def dry_call
+      self.class.before_actions_blocks.each_with_object([]) do |b, failures|
+        instance_eval(&b)
+      rescue CleanActions::ActionFailure => f
+        failures << f
+      end
+    end
+
+    module ClassMethods
+      def fail_with(failure_reason, &block)
+        before_actions { fail!(failure_reason) if instance_eval(&block) }
+      end
+
+      def dry_call(**kwargs)
+        new(**kwargs).dry_call
+      end
+    end
+  end
+end

data/lib/clean_actions/isolation_level_validator.rb

@@ -0,0 +1,26 @@
+module CleanActions
+  class IsolationLevelValidator
+    VALID_ISOLATION_LEVELS = %i[read_uncommited read_committed repeatable_read]
+
+    class << self
+      def validate(isolation_level, allow_serializable: false)
+        if isolation_level == :serializable
+          unless allow_serializable
+            ErrorReporter.report("serializable isolation should only be used for a whole project, please use global config")
+          end
+
+          return
+        end
+
+        return if VALID_ISOLATION_LEVELS.include?(isolation_level)
+
+        ErrorReporter.report("invalid isolation level #{isolation_level} for #{name}")
+      end
+
+      def can_be_nested(isolation_level)
+        CleanActions.config.isolation_level == :serializable ||
+          VALID_ISOLATION_LEVELS.index(isolation_level) <= VALID_ISOLATION_LEVELS.index(Thread.current[:root_isolation_level])
+      end
+    end
+  end
+end

data/lib/clean_actions/transaction_runner.rb

@@ -0,0 +1,83 @@
+module CleanActions
+  class TransactionRunner
+    class << self
+      def restrict_action_calls_by(method)
+        Thread.current[:action_calls_restricted_by] = method
+        yield
+      ensure
+        Thread.current[:action_calls_restricted_by] = nil
+      end
+
+      def action_calls_restricted_by
+        Thread.current[:action_calls_restricted_by]
+      end
+    end
+
+    def initialize(action)
+      @action = action
+    end
+
+    def run(with_savepoint: false, &block)
+      performed_actions << @action
+
+      if Thread.current[:transaction_started]
+        unless IsolationLevelValidator.can_be_nested(action_isolation_level)
+          ErrorReporter.report <<~MSG
+            action #{@action.class.name} requires #{action_isolation_level}, run inside #{Thread.current[:root_isolation_level]}
+          MSG
+        end
+
+        if with_savepoint
+          return ActiveRecord::Base.transaction(requires_new: true) { block.call }
+        else
+          return block.call
+        end
+      end
+
+      start_transaction(&block)
+    end
+
+    private
+
+    delegate :restrict_action_calls_by, to: :class
+
+    def start_transaction(&block)
+      Thread.current[:transaction_started] = true
+      Thread.current[:root_isolation_level] = action_isolation_level
+
+      ActiveRecord::Base.transaction(isolation: action_isolation_level) do
+        block.call.tap { restrict_action_calls_by(:after_commit) { run_after_commit_actions } }
+      rescue => e
+        run_rollback_blocks
+        raise e unless e.is_a?(ActionFailure)
+
+        e
+      end
+    ensure
+      Thread.current[:root_isolation_level] = nil
+      Thread.current[:transaction_started] = false
+      run_ensure_blocks
+      Thread.current[:performed_actions] = []
+    end
+
+    def action_isolation_level
+      @action.class.isolation_level
+    end
+
+    def run_after_commit_actions
+      performed_actions.each(&:after_commit)
+    end
+
+    def run_ensure_blocks
+      performed_actions.each(&:ensure)
+    end
+
+    def run_rollback_blocks
+      performed_actions.each(&:rollback)
+    end
+
+    def performed_actions
+      Thread.current[:performed_actions] ||= []
+    end
+  end
+end

data/lib/clean_actions/typed_returns.rb

@@ -0,0 +1,35 @@
+module CleanActions
+  module TypedReturns
+    def self.included(base)
+      base.prepend(PrependedMethods)
+      base.extend(ClassMethods)
+    end
+
+    module PrependedMethods
+      def call(**)
+        returned_value = super
+
+        return returned_value if returned_value.is_a?(ActionFailure)
+
+        if self.class.returned_classes.nil?
+          returned_value = nil
+        elsif self.class.returned_classes.none? { returned_value.is_a?(_1) }
+          ErrorReporter.report(
+            "expected #{self.class.name} to return #{self.class.returned_classes.map(&:name).join(", ")}, " \
+            "returned #{returned_value.inspect}"
+          )
+        end
+
+        returned_value
+      end
+    end
+
+    module ClassMethods
+      attr_reader :returned_classes
+
+      def returns(*klasses)
+        @returned_classes = klasses
+      end
+    end
+  end
+end

data/lib/clean_actions/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CleanActions
+  VERSION = "0.1.0"
+end

data/lib/clean_actions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+require "clean_actions/configuration"
+require "clean_actions/error_reporter"
+require "clean_actions/isolation_level_validator"
+require "clean_actions/fail_with"
+require "clean_actions/typed_returns"
+require "clean_actions/action_failure"
+require "clean_actions/transaction_runner"
+require "clean_actions/action"
+require "clean_actions/base"
+require "clean_actions/version"
+
+module CleanActions
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: clean_actions
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- DmitryTsepelev
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-09-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: prometheus-client
+  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:
+email:
+- dmitry.a.tsepelev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/clean_actions.rb
+- lib/clean_actions/action.rb
+- lib/clean_actions/action_failure.rb
+- lib/clean_actions/base.rb
+- lib/clean_actions/configuration.rb
+- lib/clean_actions/error_reporter.rb
+- lib/clean_actions/fail_with.rb
+- lib/clean_actions/isolation_level_validator.rb
+- lib/clean_actions/transaction_runner.rb
+- lib/clean_actions/typed_returns.rb
+- lib/clean_actions/version.rb
+homepage: https://github.com/DmitryTsepelev/clean_actions
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/DmitryTsepelev/clean_actions/issues
+  changelog_uri: https://github.com/DmitryTsepelev/clean_actions/blob/master/CHANGELOG.md
+  documentation_uri: https://github.com/DmitryTsepelev/clean_actions/blob/master/README.md
+  homepage_uri: https://github.com/DmitryTsepelev/clean_actions
+  source_code_uri: https://github.com/DmitryTsepelev/clean_actions
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A modern modular service object toolkit for Rails, that respects database
+  transactions and adds type checks to returned values.
+test_files: []