light-service-ext 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08cca14ee81b2019a34e6ce11e69a02769a5f91249c075b11e236570734c895c'
-  data.tar.gz: 3c5fd91b35a3390394fe647cac366c5b8d6ea783894ab62fa877488c3935555c
+  metadata.gz: 962aaba417524bf102f137c7f62dd622b440701dc106c6afa8372bcb4c2c36ec
+  data.tar.gz: 71430081be864aee8f985f67adc936ce46c078a8e19f9e476e4337f5d1d89ca0
 SHA512:
-  metadata.gz: 7c226a4d2d1338c4f83be7ead8bf5c54bb297abb1c20f5d99efd89f5463820a53843ccc3257944a97e3f981e1929847e6fabf14dc489ea26203bfa20335c1570
-  data.tar.gz: a26b62d93f3ea08babb2a3f1ec371df6df15f7065ac4617ef92462f884a21e5dff67b566b4ad39fd922c852568892ff54864494d20556ac0322aab5a3efb54a9
+  metadata.gz: d05157f2a3b4f92591046ef6a51b5fdd55dc9f8d7eeb3fd314529b71a6981bd71bb1d382c58bdd3c3d8bf71cf46095637682b94c35aad37dc9770fba9caef935
+  data.tar.gz: 52144674f23c819c5680d4ab53d54260b1919abaf2bd46ed3fe05351bf169056981c8c89ce762f1a4ad837605ba96b9ab12dc2ff9d63f51e074525c2ae728cb2

data/.rubocop.yml

@@ -236,3 +236,12 @@ RSpec/MultipleMemoizedHelpers:
 
 RSpec/PredicateMatcher:
   Enabled: false
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/SubjectStub:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
-## [0.1.0] - 2023-02-07
+## [0.1.0] - 2023-02-15
 
 - Initial release
+
+## [0.1.1] - 2023-02-15
+
+- Fixing issue with with use of `relative_path` inside of `light-service-ext.gemspec`
+
+## [0.1.2] - 2023-02-24
+
+- Updates `README.md` with detailed information on features provided
+
+## [0.1.3] - 2023-02-25
+
+- Adds `Orchestration` of organizers via `ApplicationOrchestrator` functionality to support calling an organizer(s) inside an orchestrator without polluting the orchestrator context from changes to the called organizer
+- Updates `README.md` with detailed information on features provided
+- Records Actions
+  - adds better error handling
+  - records api_responses to organizer's context from each action filled with `current_api_response`
+  - fails the organizer's context if action returned `errors`

data/README.md

@@ -1,8 +1,11 @@
-# LightServiceExt
+![LightService](https://raw.githubusercontent.com/adomokos/light-service/master/resources/light-service.png)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/light-service-ext`. To experiment with that code, run `bin/console` for an interactive prompt.
+# Light Service Extensions
 
-TODO: Delete this and the text above, and describe your gem
+Aims to enhance [light-service](https://github.com/adomokos/light-service) to enhance this powerful and flexible service skeleton framework with an emphasis on simplicity
+
+## Console
+run `bin/console` for an interactive prompt.
 
 ## Installation
 
@@ -20,9 +23,230 @@ Or install it yourself as:
 
     $ gem install light-service-ext
 
-## Usage
+## ApplicationOrganizer
+> Adds the following support
+
+#### Error Handling
+> Provided by `.with_error_handler`
+
+- Records errors via `issue_error_report!` into context as exemplified below:
+```ruby
+  {
+    errors: {
+            base: "some-exception-message",
+            internal_only: {
+                    type: 'ArgumentError',
+                    message: "`user_id` must be a number",
+                    exception: "ArgumentError : `user_id` must be a number",
+                    backtrace: [], # filtered backtrace via `[ActiveSupport::BacktraceCleaner](https://api.rubyonrails.org/classes/ActiveSupport/BacktraceCleaner.html)`
+                    error: original_captured_exception
+            }
+    }
+  }
+```
+
+- Captures `model validation` exceptions and record the messages to the organizer's `:errors` context field
+  - Supports the following exceptions by default
+    - `ActiveRecord::Errors`
+    - `ActiveModel::Errors`
+- Raises any non validation errors up the stack
+
+#### API Responses
+- records api responses set by an action's `:api_response` context field
+- Stored inside of the organizer's `:api_responses` field
+
+#### Retrieve Record
+> Allows for a block to be defined on an organizer in order to retrieve the model record
+
+#### Failing The Context
+- Prevents further action's been executed in the following scenarios:
+  - All actions complete determined by organizer's `:outcome` context field set to `LightServiceExt::Outcome::COMPLETE`
+
+#### Example
+
+```ruby
+class TaxCalculator < LightServiceExt::ApplicationOrganizer
+  self.retrieve_record = -> (ctx:) { User.find_by(email: ctx.params[:email]) }
+
+  def self.call(input)
+    user = record(ctx: input) # `.record` method executes proc provided to `retrieve_record`
+    input = { user: user }.merge(input)
+    
+    super(input)
+  end
+  
+  def self.steps
+    [TaxValidator, CalcuateTaxAction]
+  end
+end
+```
+
+## ApplicationOrchestrator
+> Useful if you want the current `Organizer` to act as a `Orchestrator` and call another organizer
+
+- *ONLY* modifies the orchestrator context from executing `organizer_steps` if manually applied via `each_organizer_result` Proc
+
+### method overrides
+- `organizer_steps` ~ must be a list of organizers to be called prior to orchestrator's actions
+
+### Example
+
+```ruby
+class TaxCalculatorReport < LightServiceExt::ApplicationOrchestrator
+  self.retrieve_record = -> (ctx:) { User.find_by(email: ctx.params[:email]) }
+
+  def self.call(input)
+    user = record(ctx: input) # `.record` method executes proc provided to `retrieve_record`
+    input = { user: user }.merge(user: user)
+    reduce_with({ input: input }, steps)
+    
+    super(input.merge({ user: user })) do |current_organizer_ctx, orchestrator_ctx:|
+      orchestrator_ctx.add_params(current_organizer_ctx.params.slice(:user_id)) # manually add params from executed organizer(s) 
+    end
+  end
+
+  def organizer_steps
+    [TaxCalculator]
+  end
+
+  def steps
+    [TaxReportAction]
+  end
+end
+```
+
+## ApplicationAction
+
+#### Useful methods
+- TODO
+
+#### Invoked Action
+- *NOTE* Action's `executed` block gets called by the underlying `LightService::Action`
+  - this means in order to call your action's methods you need to invoke it from `invoked_action:` instead of `self`
+- `invoked_action:` added to current action's context before it gets executed
+  - Consist of an instance of the current action that implements `LightServiceExt::ApplicationAction`
+
+## ApplicationContract
+
+- Enhances `Dry::Validation::Contract` with the following methods:
+  - `#keys` ~> returns names of params defined
+  - `#t` ~> returns translation messages in context with the current organizer
+    - Arguments:
+      - `key` e.g. :not_found
+      - `base_path:` e.g. :user
+      - `**opts` options passed into underlying Rails i18n translate call
+    - E.g. `t(:not_found, base_path: 'business_create', scope: 'user')` would execute
+      - => `I18n.t('business_create.user.not_found', opts.except(:scope))`
+
+## ApplicationValidatorAction
+
+> Responsible for mapping, filtering and validating the context `input:` field
+
+- `executed` block does the following:
+  - Appends `params:` field to the current context with the mapped and filtered values
+  - Appends errors returned from a `ApplicationContract` [dry-validation](https://github.com/dry-rb/dry-validation) contract to the current context's `errors:` field
+    - *NOTE* fails current context if `errors:` present
+
+##### Useful Accessors
+
+- `.contract_class` ~> sets the [dry-validation](https://github.com/dry-rb/dry-validation) contract to be applied by the current validator action
+- `.params_mapper_class` ~> sets the mapper class that must implement `.map_from(context)` and return mapped `:input` values
+
+ 
+## ApplicationContext
+
+> Adds useful defaults to the organizer/orchestrator context
+- `:input` ~> values originally provided to organizer get moved here for better isolation
+- `:params` 
+  - stores values `filtered` and `mapped` from original `input`
+  - outcomes/return values provided by any action that implements `LightServiceExt::ApplicationAction`
+- `:errors`
+  - validation errors processed by `LightServiceExt::ApplicationValidatorAction` [dry-validation](https://github.com/dry-rb/dry-validation) contract
+  - manually added by an action e.g. `{ errors: { email: 'not found' } }`
+- `:successful_actions` ~> provides a list of actions processed mostly useful for debugging purposes e.g. `['SomeActionClassName']`
+- `invoked_action` ~> instance of action to being called.
+- `:current_api_response` ~> action issued api response
+- `:api_responses` ~> contains a list of external API interactions mostly for recording/debugging purposes (**internal only**)
+- `:allow_raise_on_failure` ~> determines whether or not to throw a `RaiseOnContextError` error up the stack in the case of validation errors and/or captured exceptions
+- `:status` denotes the current status of the organizer with one of the following flags:
+  - `LightServiceExt::Status::COMPLETE`
+  - `LightServiceExt::Status::INCOMPLETE`
+- `:last_failed_context` ~ copy of context that failed e.g. with `errors` field present
+- `internal_only` ~ includes the likes of raised error summary and should never be passed to endpoint responses
+Example
+
+````ruby
+input = { order: order }
+overrides = {} # optionally override `params`, `errors` and `allow_raise_on_failure`
+LightServiceExt::ApplicationContext.make_with_defaults(input, overrides)
+
+# => { input: { order: order },
+#      errors: { email: ['not found'] },
+#      params: { user_id: 1 },
+#      status: Status::INCOMPLETE,
+#      invoked_action: SomeActionInstance,
+#      successful_actions: ['SomeActionClassName'],
+#      current_api_response: { user_id: 1, status: 'ACTIVE' },
+#      api_responses: [ { user_id: 1, status: 'ACTIVE' } ],
+#      last_failed_context: {input: { order: order }, params: {}, ...},
+#      allow_raise_on_failure: true,
+#      internal_only: { error_info: ErrorInfoInstance }
+#    }
+````
+
+#### Useful methods
+- `.add_params(**params)`
+  - Adds given args to context's `params` field
+  - e.g. `add_params(user_id: 1) # => { params: { user_id: 1 } }`
+
+- `add_errors!`
+  - Adds given args to to context's `errors` field
+  - Fails and returns from current action/organizer's context
+  - e.g. `add_to_errors!(email: 'not found') # => { errors: { email: 'not found' } }`
+
+- `.add_errors(**errors)`
+  - Adds given args to to context's `errors` field
+  - DOES NOT fails current context
+  - e.g. `add_to_errors(email: 'not found') # => { errors: { email: 'not found' } }`
+
+- `.add_status(status)`
+  - Should be one of Statuses e.g. `Status::COMPLETE` 
+  - e.g. `add_status(Status::COMPLETE) # => { status: Status::COMPLETE }`
+
+- `.add_internal_only(attrs)`
+  - e.g. `add_internal_only(request_id: 54) # => { internal_only: { error_info: nil, request_id: 54 }  }`
+- `add_to_successful_actions(action_name_or_names)` ~> adds action names successfully executed
+
+## ContextError
+
+> Provides all the information related to an exception/validation errors captured by the current organizer
+
+#### Useful methods
+- `#error_info` ~> `ErrorInfo` instance
+- `#context` ~> state of context provided
+- `#error` ~> original exception
+- `#message` ~> summarizes which action failed etc.
+
+## ErrorInfo
+- Summarize captured exception
+
+#### Useful accessors
+- `non_fatal_errors` ~> takes a list of error class names considered to be non fatal exceptions
+
+#### Useful methods
+- `#error` ~> captured exception
+- `#type` ~> exception class name e.g. `ArgumentError`
+- `#message` ~> error message
+- `title` ~> combined error class name and error message e.g. `ArgumentError : email must be present`
+- `#fatal_error?`
+- `#error_summary` ~> summarizes exception with message and cleaned backtrace via `ActiveSupport::BacktraceCleaner`
+
+## Regex
 
-TODO: Write usage instructions here
+#### Useful methods
+- `.match?(type, value)` e.g. `LightServiceExt::Regex.match?(email:, 'email@domain.com')`
+  - supported `type`:
+    - :email
 
 ## Development
 

data/dev/setup.rb

@@ -5,8 +5,10 @@
 require 'json'
 require 'light-service'
 require 'dry-validation'
+require 'rspec/core'
 
-Dir.glob("lib/**/*.rb").each do |f|
-  require File.join(__dir__, '..', f)
-end
+require 'active_support/core_ext/array'
+require 'active_support/configurable'
 
+require File.expand_path("../../lib/light-service-ext", Pathname.new(__FILE__).realpath)
+require File.expand_path("../../spec/spec_helper", Pathname.new(__FILE__).realpath)

data/lib/light-service-ext/all_actions_complete_action.rb

@@ -9,7 +9,7 @@ module LightServiceExt
 
       raise ContextError.new(ctx: context) if raise_error
 
-      context[:outcome] = Outcome::COMPLETE
+      context.add_status(Status::COMPLETE)
     end
   end
 end

data/lib/light-service-ext/application_action.rb

@@ -4,27 +4,6 @@ module LightServiceExt
   class ApplicationAction
     extend LightService::Action
 
-    class << self
-      def add_params(ctx, **params)
-        add_to_context(ctx, :params, **params)
-      end
-
-      def add_errors(ctx, **errors)
-        add_to_context(ctx, :errors, **errors)
-
-        ctx.fail_and_return! if ctx[:errors].present?
-      end
-
-      private
-
-      def add_to_context(ctx, key, **args)
-        return if ctx.nil?
-
-        ctx[key].merge!(args.dup)
-        nil
-      end
-    end
-
     def self.inherited(base)
       base.singleton_class.prepend AroundActionExecuteExtension
       super

data/lib/light-service-ext/application_context.rb

@@ -2,27 +2,75 @@
 
 module LightServiceExt
   class ApplicationContext < LightService::Context
-    OVERRIDABLE_DEFAULT_KEYS = %i[errors params allow_raise_on_failure].freeze
-
     class << self
       def make_with_defaults(input = {}, overrides = {})
-        allowed_overrides = overrides.slice(*OVERRIDABLE_DEFAULT_KEYS)
-        make({ input: input.symbolize_keys }.merge(default_attrs, allowed_overrides))
+        defaults = default_attrs
+        allowed_override_keys = defaults.keys.excluding(:input)
+        allowed_overrides = overrides.slice(*allowed_override_keys)
+        make({ input: input.symbolize_keys }.merge(defaults, allowed_overrides))
       end
 
       private
 
       def default_attrs
-        { errors: {}, params: {}, successful_actions: [], api_responses: [], allow_raise_on_failure: true }.freeze
+        {
+          errors: {},
+          params: {},
+          status: Status::INCOMPLETE,
+          invoked_action: nil,
+          successful_actions: [],
+          current_api_response: nil,
+          api_responses: [],
+          last_failed_context: nil,
+          allow_raise_on_failure: LightServiceExt.config.allow_raise_on_failure?,
+          internal_only: { error_info: nil }
+        }.freeze
       end
     end
 
-    def invoked_action
-      self[:invoked_action]
+    def add_params(**params)
+      add_attrs_to_ctx(:params, params)
+    end
+
+    def add_errors(**errors)
+      add_attrs_to_ctx(:errors, errors)
+    end
+
+    def add_errors!(**errors)
+      return if errors.blank?
+
+      add_errors(**errors)
+      fail_and_return!
+    end
+
+    def add_status(status)
+      add_value_to_ctx(:status, status)
+    end
+
+    def add_current_api_response(api_response)
+      add_value_to_ctx(:current_api_response, api_response)
+    end
+
+    def add_last_failed_context(failed_context)
+      return if failed_context.nil? || failed_context.try(:success?)
+
+      add_value_to_ctx(:last_failed_context, failed_context)
+    end
+
+    def add_internal_only(**attrs)
+      add_attrs_to_ctx(:internal_only, **attrs)
+    end
+
+    def add_to_api_responses(*api_response)
+      add_collection_to_ctx(:api_responses, *api_response)
     end
 
-    def validation_errors
-      self[:errors]
+    def add_to_successful_actions(*action_name)
+      add_collection_to_ctx(:successful_actions, *action_name)
+    end
+
+    def add_invoked_action(invoked_action)
+      add_value_to_ctx(:invoked_action, invoked_action)
     end
 
     def allow_raise_on_failure?
@@ -38,5 +86,26 @@ module LightServiceExt
     def respond_to_missing?(method_name, include_private = false)
       key?(method_name) || super
     end
+
+    private
+
+    def add_value_to_ctx(key, value)
+      self[key] = value
+      nil
+    end
+
+    def add_attrs_to_ctx(key, **attrs)
+      return if attrs.blank?
+
+      self[key].merge!(attrs)
+      nil
+    end
+
+    def add_collection_to_ctx(key, *values)
+      return if values.empty?
+
+      self[key] = self[key].concat(values).compact
+      nil
+    end
   end
 end

data/lib/light-service-ext/application_orchestrator.rb

@@ -0,0 +1,32 @@
+module LightServiceExt
+  class ApplicationOrchestrator < ApplicationOrganizer
+    class << self
+      def call(context, &each_organizer_result)
+        orchestrator_ctx = process_each_organizer(ApplicationContext.make_with_defaults(context),
+                                                  &each_organizer_result)
+        with(orchestrator_ctx).around_each(RecordActions).reduce(all_steps)
+      end
+
+      def organizer_steps
+        raise NotImplementedError
+      end
+
+      def process_each_organizer(orchestrator_ctx, &each_organizer_result)
+        organizer_steps.each do |step_class|
+          exec_method = exec_method_for(step_class)
+          current_organizer_ctx = step_class.send(exec_method, orchestrator_ctx.input)
+          yield(current_organizer_ctx, orchestrator_ctx: orchestrator_ctx) if each_organizer_result
+        end
+        orchestrator_ctx
+      end
+
+      private
+
+      def exec_method_for(klass)
+        return :call if klass.is_a?(LightService::Organizer) || klass.is_a?(Proc)
+
+        :execute
+      end
+    end
+  end
+end

data/lib/light-service-ext/application_organizer.rb

@@ -4,12 +4,28 @@ module LightServiceExt
   class ApplicationOrganizer
     extend LightService::Organizer
 
-    def self.call(context)
-      with(ApplicationContext.make_with_defaults(context)).reduce(steps)
-    end
+    class << self
+      def call(context)
+        with(ApplicationContext.make_with_defaults(context))
+          .around_each(RecordActions)
+          .reduce(all_steps)
+      end
+
+      def steps
+        raise NotImplementedError
+      end
+
+      def reduce_if_success(steps)
+        reduce_if(->(ctx) { ctx.success? && ctx[:errors].blank? }, steps)
+      end
+
+      private
+
+      def all_steps
+        return steps.push(AllActionsCompleteAction) if steps.is_a?(Array)
 
-    def self.steps
-      raise NotImplementedError
+        [steps].push(AllActionsCompleteAction)
+      end
     end
   end
 end

data/lib/light-service-ext/application_validator_action.rb

@@ -7,8 +7,8 @@ module LightServiceExt
 
     executed do |context|
       validator = map_and_validate_inputs(context)
-      add_params(context, **validator.to_h)
-      add_errors(context, **validator.errors.to_h.transform_values(&:first))
+      context.add_params(**validator.to_h)
+      context.add_errors!(**validator.errors.to_h)
     end
 
     class << self

data/lib/light-service-ext/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module LightServiceExt
+  class Configuration
+    include ActiveSupport::Configurable
+
+    config_accessor(:allow_raise_on_failure, default: true)
+    config_accessor(:non_fatal_error_classes, default: [])
+    config_accessor(:default_non_fatal_error_classes) { ['Rails::ActiveRecordError'.safe_constantize] }
+    config_accessor(:logger) { (defined? Rails.logger).nil? ? Logger.new($stdout) : Rails.logger }
+
+    def allow_raise_on_failure?
+      !!allow_raise_on_failure
+    end
+
+    def non_fatal_errors
+      (default_non_fatal_error_classes + non_fatal_error_classes).compact.uniq.map(&:to_s).freeze
+    end
+
+    def fatal_error?(exception)
+      !non_fatal_errors.exclude?(exception.class.name)
+    end
+
+    def non_fatal_error?(exception)
+      non_fatal_errors.include?(exception.class.name)
+    end
+  end
+end

data/lib/light-service-ext/constants.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module LightServiceExt
-  module Outcome
-    COMPLETE = "all_steps_complete"
+  module Status
+    COMPLETE = :all_steps_complete
+    INCOMPLETE = :steps_incomplete
   end
 end

data/lib/light-service-ext/error_info.rb

@@ -29,6 +29,13 @@ module LightServiceExt
       TEXT
     end
 
+    def errors
+      model = error && (error.try(:model) || error.try(:record))
+      return model.errors.messages if model.present?
+
+      { base: message }
+    end
+
     def to_h
       {
         type: type,
@@ -36,7 +43,8 @@ module LightServiceExt
         exception: title,
         backtrace: clean_backtrace[0, 3]&.join("\n"),
         error: error,
-        fatal_error?: fatal_error?
+        fatal_error?: fatal_error?,
+        errors: errors
       }
     end
 
@@ -45,7 +53,7 @@ module LightServiceExt
     end
 
     def clean_backtrace
-      @clean_backtrace ||= if defined? Rails
+      @clean_backtrace ||= if defined? Rails.backtrace_cleaner
                              Rails.backtrace_cleaner.clean(backtrace || [])
                            else
                              backtrace || []
@@ -53,15 +61,7 @@ module LightServiceExt
     end
 
     def non_fatal_error?
-      error.nil? || self.class.non_fatal_errors.map(&:to_s).include?(type)
-    end
-
-    class << self
-      attr_writer :non_fatal_errors
-
-      def non_fatal_errors
-        @non_fatal_errors ||= []
-      end
+      error.nil? || LightServiceExt.config.non_fatal_error?(error)
     end
   end
 end

data/lib/light-service-ext/record_actions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module LightServiceExt
+  class RecordActions
+    extend WithErrorHandler
+
+    def self.call(context)
+      with_error_handler(ctx: context) do
+        result = yield
+        return context if outcomes_complete?(ctx: context, result: result)
+
+        merge_api_responses!(ctx: context, result: result)
+      end
+    end
+
+    class << self
+      def merge_api_responses!(ctx:, result:)
+        invoked_action = result.invoked_action
+        return if invoked_action.nil?
+
+        ctx.add_to_successful_actions(invoked_action.name)
+        ctx.add_to_api_responses(result.current_api_response)
+        ctx
+      end
+
+      def outcomes_complete?(ctx:, result:)
+        if result.status == Status::COMPLETE
+          ctx.add_status(result.status)
+
+          if ctx.errors.present?
+            ctx.add_last_failed_context(result.to_h)
+            ctx.fail!
+          end
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end

data/lib/light-service-ext/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LightServiceExt
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end