light-service-ext 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 337b734063a899dc19d0a5d6591b127015473b682cd98a3d4c0454e3425ccdef
-  data.tar.gz: 17bd81121eb9be17e5f81bb050e86d43edf82eb358bfe2034cfd1f27ddde1475
+  metadata.gz: a72952c78aab0b82bbce081bd1c2ab955ef264a9fbb5186a9ead3a429eaa504e
+  data.tar.gz: 43cb1863bac420a7150573a0e24cc141bd2384e36cfc4440dbd12f2fce276e93
 SHA512:
-  metadata.gz: 6315693fe915515d1c1def2c80af6bc6b68b7f6268fb4cb9e3303da344d8284b95719ab219fc3c601c646f2169edfd894f222770f269c7e422b748ff1945e398
-  data.tar.gz: 3249c9ef1fecde4b3312685fc2b68a46a1f41466bf89f81ce4db00f6bf9327cbe70c8b2c475c23c48dd24f8df486f0d618a0604fd367c663a5cdbf39f3f4776a
+  metadata.gz: cabc217b43f33aa0771de27613eeecd83f425786e93946ed14d716523814a4af7045d464ae16841b6d3e2db20a8b0f4d780190363ad130bf934c100b962ba1f1
+  data.tar.gz: 5ab3b2151ebb98e80b65a24717a628d7e9f60f206b25c258a05d32e3d57c85e832d99b92905f4883e2d770e9240da85e611771b2497d17f7c87687e670b82838

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [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] - YYYY-MM-DD
+
+- Updates `README.md` with detailed information on features provided

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,194 @@ Or install it yourself as:
 
     $ gem install light-service-ext
 
-## Usage
+## 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
+- `:api_responses` ~> contains a list of external API interactions mostly for recording/debugging purposes
+- `: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
+- `:outcome` denotes the current status of the organizer with one of the following flags:
+  - `LightServiceExt::Outcome::COMPLETE`
+
+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 },
+#      params: {}, 
+#      errors: {}, 
+#      successful_actions: [], 
+#      api_responses: [], 
+#      allow_raise_on_failure: true 
+#    }
+````
+
+#### 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(**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' } }`
+
+
+## ApplicationOrganizer
+
+> Adds the following support
+
+### Useful methods
+
+- `.reduce_if_success(<list of actions>)` prevents execution of action/step in the case of context failure or `:errors` present
+- `.with_context(&block)` calls given block with `:ctx` argument
+- `.execute_if` ~> Useful if you want the current `Organizer` to act as a `Orchestrator` and call another organizer
+  - *ONLY* modifies the current organizer/orchestrator's as a result of executing `organizer_or_action_class_or_proc` if manually applied by a given `result_callback` Proc
+  - Executed `steps` do modify the current organizer/orchestrator's context without the need for manual intervention
+  - Arguments:
+    - `condition_block` (required) ~> given block is called with current `context` argument
+    - `organizer_or_action_class_or_proc` (required) ~> only executed if `condition_block` evaluates to `true`
+      - must be one of `ApplicationOrganizer`, `ApplicationAction`, `Proc`
+    - `apply_ctx_transform` (optional)
+      - given block is called prior to `organizer_or_action_class_or_proc` being executed 
+      - e.g. `apply_ctx_transform: -> (context) { context[:params][:user_id] = record(context)&.id }`
+      - returned value gets passed to `organizer_or_action_class_or_proc` call
+    - `result_callback` (optional)
+      - given block is called after `organizer_or_action_class_or_proc` has been executed
+      - Useful in the case where you want to augment the current organizer's context based on the context returned from the `organizer_or_action_class_or_proc` call
+      - e.g. `result_callback: -> (ctx:, result:) { ctx[:params] = result[:params] }`
+        - `ctx:` represents the main `organizer/orchestrator's` context
+        - `result:` represents the context returned from the executed `organizer_or_action_class_or_proc`
+    - `steps` (optional) ~> calls current `organizer/orchestrator's` actions/steps and called once `organizer_or_action_class_or_proc` has been processed
+      - *PLEASE NOTE* called regardless of the result from the `organizer_or_action_class_or_proc` call unless you *manually* fail the current context or add `:errors`
+  
+#### 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
+
+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(user: user)
+    reduce_with({ input: input }, steps)
+  end
+end
+```
+
+#### 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`
+
+### 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
+
+## 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/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

@@ -13,10 +13,38 @@ module LightServiceExt
       private
 
       def default_attrs
-        { errors: {}, params: {}, successful_actions: [], api_responses: [], allow_raise_on_failure: true }.freeze
+        { errors: {}, params: {}, successful_actions: [], api_responses: [],
+          allow_raise_on_failure: LightServiceExt.config.allow_raise_on_failure?,
+          internal_only: { error_info: nil } }.freeze
       end
     end
 
+    def add_params(**params)
+      return if params.blank?
+
+      self[:params].merge!(params.dup)
+    end
+
+    def add_internal_only(**attrs)
+      return if attrs.blank?
+
+      self[:internal_only].merge!(attrs.dup)
+    end
+
+    def add_errors(**errors)
+      return if errors.blank?
+
+      self[:errors].merge!(errors.dup)
+      nil
+    end
+
+    def add_errors!(**errors)
+      return if errors.blank?
+
+      add_errors(**errors)
+      fail_and_return!
+    end
+
     def invoked_action
       self[:invoked_action]
     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.transform_values(&:first))
     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

@@ -2,6 +2,6 @@
 
 module LightServiceExt
   module Outcome
-    COMPLETE = "all_steps_complete"
+    COMPLETE = :all_steps_complete
   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.transform_values(&:first) 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/version.rb

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

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/AbcSize
+
+module LightServiceExt
+  module WithErrorHandler
+    def with_error_handler(ctx:)
+      @result = yield || ApplicationContext.make_with_defaults
+    rescue Rails::ActiveRecordError => e
+      error_info = ErrorInfo.new(e, fatal: false)
+      ctx.add_internal_only(error_info: error_info)
+      ctx.add_errors(**error_info.errors)
+
+      LightServiceExt.config.logger.error(error_info.error_summary)
+
+      ctx.fail!
+      ctx
+    rescue StandardError => e
+      error_info = ErrorInfo.new(e, fatal: false)
+      LightServiceExt.config.logger.error(error_info.error_summary)
+
+      raise
+    end
+  end
+end
+# rubocop:enable Metrics/AbcSize

data/lib/light-service-ext.rb

@@ -1,16 +1,38 @@
 # frozen_string_literal: true
 
-require "light-service-ext/version"
-require "light-service-ext/constants"
-require "light-service-ext/regex"
-require "light-service-ext/error_info"
-require "light-service-ext/context_error"
-require "light-service-ext/application_context"
-require "light-service-ext/application_contract"
-require "light-service-ext/around_action_execute_extension"
-require "light-service-ext/application_action"
-require "light-service-ext/all_actions_complete_action"
-require "light-service-ext/application_validator_action"
-require "light-service-ext/application_organizer"
+%w[
+version
+constants
+regex
+error_info
+context_error
+configuration
+with_error_handler
+application_context
+application_contract
+around_action_execute_extension
+application_action
+all_actions_complete_action
+application_validator_action
+application_organizer
+].each do |filename|
+  require File.expand_path("../light-service-ext/#{filename}", Pathname.new(__FILE__).realpath)
+end
 
-module LightServiceExt; end
+
+
+module LightServiceExt
+  class << self
+    def config
+      self.configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/light-service-ext.gemspec

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "lib/light-service-ext/version"
+require File.expand_path('../lib/light-service-ext/version', __FILE__)
 
 Gem::Specification.new do |gem|
   gem.authors = ["Desmond O'Leary"]
@@ -26,6 +26,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency 'dry-struct', '~> 1.6'
   gem.add_runtime_dependency 'dry-validation', '~> 1.10'
   gem.add_runtime_dependency 'json', '~> 2.6', '>= 2.6.3'
+  gem.add_runtime_dependency 'activesupport', '>= 5'
 
   gem.add_development_dependency("rake", "~> 13.0.6")
   gem.add_development_dependency("rspec", "~> 3.12.0")

data/spec/light-service-ext/application_action_spec.rb

@@ -0,0 +1,39 @@
+module LightServiceExt
+  RSpec.describe ApplicationAction do
+    FakeApplicationAction = Class.new(described_class) do
+      executed do |context|
+        value = context.dig(:input, :callback).call
+        context.add_params(value: value)
+        context.add_errors!(value: value)
+      end
+    end
+
+    let(:organizer_class) do
+      Class.new(ApplicationOrganizer) do
+        def self.steps
+          [FakeApplicationAction]
+        end
+      end
+    end
+
+    let(:value) { 'some-value' }
+    let(:callback) { -> { value } }
+    let(:input) { { callback: callback } }
+    let(:ctx) do
+      LightService::Testing::ContextFactory
+        .make_from(organizer_class)
+        .for(FakeApplicationAction)
+        .with(callback: callback)
+    end
+
+    subject(:context) do
+      FakeApplicationAction.execute(ctx)
+    end
+
+    it 'adds value returned by callback to params' do
+      expect(context.keys).to include(:input, :errors, :params)
+
+      expect(context[:params]).to eql({ value: value })
+    end
+  end
+end