eco-helpers 1.5.1 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6fbde8a22ee5efad00700ad096396a008f9a8f9ecaf8e2096f22b7730fa28d2
-  data.tar.gz: dc498ae2c6f853f92f3e2703d116a442c2814b2c0a230270e319fabf8678342c
+  metadata.gz: afef384678f171e737391056ca300ac9d9c813240d32422445ad1e256911be31
+  data.tar.gz: 82f7b611239cc9e5d58778d1db9ffaef7cef748360fd82abeba3df710c56ac60
 SHA512:
-  metadata.gz: 9cb6d878d32370e81c512b01de2da8c6c32abcd79d636f1d70189228445c0094acef7236ffc4447c0cdd79e05576c22ceeb4798160da8752d655ff71e35440fb
-  data.tar.gz: 14283f84d4fbdc87a160dcdb842a3b154987d606333018acc0a636bd2ee2db9a25167c0106b8c8ba5fc56b4107324c9afa07caaeebe9e219bdaac1aac9d21687
+  metadata.gz: 6516df10c5fbf6d48f8fa5bfdb993320a15043fecdcbe84c2927c6c84ab9fd817d298f9ae0806a6e43476d2342e862fbecb55ed14fc532bc4cf007f32a9ff7e6
+  data.tar.gz: 13763cf62b5d0741d0d23837f66480fcf678ac317d6ac726cdea0fbd12cb4ce048b57e3278053536c214661f9aa591a90a22e06b5a24720bba087459c6536d72

data/CHANGELOG.md

@@ -1,7 +1,87 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.5.1] - 2020-10-xx
+## [1.5.2] - 2020-10-29
+
+### Added
+  - **custom** usecases, policies and error handlers can now be **declared within its own class**
+    * helper classes to inherit from: `Eco::API::Custom::UseCase`, `Eco::API::Custom::Policy`, `Eco::API::Custom::ErrorHandler` and `Eco::API::Custom::Parser`
+    * please, notice that you should create new classes under the following namespaces
+      - `Custom::UseCase`: custom use cases
+      - `Custom::Policy`: custom policy
+      - `Custom::ErrorHandler`: custom error handler
+      - `Custom::Parser`: custom parser
+    * this also allows to inherit from existing defaults and models (models to come)
+  - implemented first **microcases** (evaluation stage): to be able to centralize common code between use cases
+    - see `Eco::API::MicroCases` class
+  - **command line** added `--help` to list all `usecases`, `options` and `filters`
+    * `--help -options` will print a documented overview of options
+    * `--help -filters` will print a documented overview of people filters
+    * `--help -input-filters` will print a documented overview of input data filters
+    * `--help -usecases` will print a documented overview of the usecases
+  - **command line** filters for `filter_tags` on:
+    * input data:  `-input-filter-tags-all`, `input-filter-tags-any`, `input-filter-tags-tree`
+    * people data: `-filter-tags-all`, `-filter-tags-any`, `-filter-tags-tree`
+  - **batch stats** & **batch policy**
+    * `Eco::API::Session::Batch::RequestStats`: included additional guide on what has been **blanked**.
+      - now on you should see how many have been blanked, i.e.: `blanked_email`, `blanked_filter_tags`, `blanked_policy_group_ids`, `blanked_supervisor_id`
+    * Moreover, the new `blanked_*` properties are available for `config.batch_policies` provided that you can limit the `max` and/or `min` expected on each batch **type**
+  - **csv** generation (`-people-to-csv` and `-people-to-csv -detailed`):
+     * now includes `"Has Account?"` new column
+     * removed the useless `send_invites` column
+  - **errors** improved error message when setting values to a `person` from an `entry`:
+    * it now shows the **row number**
+    * it now gives the specific value that failed in case of `Exception`
+  - `Eco::API::Common::DefaultPasers::LoginProvidersParser`: made native
+  - `Eco::API::UseCases::DefaultUsecases::TransferAccountCase`: added `-transer-account-from` usecase
+    * to allow actually transfer an account/user from one person to another in the org
+  - `Ecoportal::API::V1::Person#entry`: method to be able to have a reference to the update/creation input data entry.
+  - new filter methods for `Eco::API::Common::People::Entries` and `Eco::API::Organization::People`
+    * `#filter_tags_any` & `#filter_tags_all`: those that have any or all the target tags
+    * `#policy_group_ids_any` & `#policy_groups_all`: those that have any or all the target policy groups
+
+### Changed
+  - updated dependency on `ecoportal-api` gem
+  - **command line** some changes:
+    - renamed `-refresh-presets` to `-refresh-abilities`
+    - renamed `-recover-db` to `restore-db`
+  - removed `Eco::API::Session::Tasks`: all the helpers have been moved and documented as part of `Eco::API::MicroCases` (some have been renamed)
+    - as a consequence, removed method `Eco::API::Session#do`
+  - `Eco::API::Common::People::PersonEntry#to_hash` has been removed
+    - now you should use the more explicit `Eco::API::Common::People::PersonEntry#external_entry`
+  - **internal refactor** of `Eco::API::UseCases::DefaultCases`:
+    * made so they inherit from `Eco::API::Common::Loaders::UseCase` and cases are autoloaded during run-time
+  - **internal refactor** of input entries processing:
+    * `Eco::API::Common::People::PersonEntry` internal refactor
+      - need to make the code clearer and make the `parsing` and `serializing` symmetrical
+        - the `serializers` were expecting an `Ecoportal::API::V1::Person`, which was at a different to that of when the `parsers` kicked in.
+        - now it has been introduced the possibility to launch the serializer in a different stage of the process
+      - to keep backwards compatibility, now it is possible to define at which `phase` of the parsing/serializing each parser and each serializer should kick in, which entailed changes in other classes and a new parameter in some methods thereof...
+    * `Eco::Language::Models::ParserSerializer` offers `category` parameter so you can have multiple parsers and serializers per each parser/serializer (one per category).
+    * `Eco::API::Common::People::PersonParser` uses `category` to define a `phase` when the `parser` or the `serializer` should be active => the expected object in the parser `callback` will be different depending on at which phase it is active and therefore called
+      - for `parser` valid **phases** are `:internal` (default) and `:final`
+      - for `serializer` valid **phases** are `:person` (default), `:final` and `:internal`
+      - the expected output of such **callbacks** is the same as before: either the single `value` to return or a `Hash` with pair key/values of virtually-generated or existing-modified attributes of the source/input data passed to the parser
+
+### Fixed
+  - **command line**
+    * `-search-soft` was being ignored in orgs with org config `session.config.people.strict_search = true`
+    * Log connection information (**enabled**): it was not printing where the connection was being made
+    * enabled chaining between usecases: they will be processed in the order they hold in the command line
+  - Removed error double backtrace (now it should only show one)
+  - `Eco::API::Common::People::EntryFactory#entries` was not using `encoding` parameter properly.
+  - `Eco::API::Common::People::DefaultParsers::CSVParser` does at `strip` (trim) of the header names.
+  - `Eco::API::Organization::PresetsFactory#merge` was including abilities that were not included in the custom presets
+    - fix: it will include only those that are defined, provided that using it will not override account abilities that should not be targeted, such as `tasks`
+    - this new behavior will preserve account abilities that should be preserved; not targeted by the custom presets
+  - some use cases where giving incorrect row number, fixed so they do:
+    - `Eco::API::Common::People::EntryFactory#entries` adds `idx` key to each `entry`
+  - `Eco::API::Common::People::PersonEntry`: serialization process has been normalized (previously there were missing fields)
+    - this fix makes the `csv` with the complete set of fields that should be exported
+  - `Ecoportal::API::Internal::Person#account_added` fixed typo
+  - `Ecoportal::API::Session::Batch#get_people` should return `Array<Person>` invariably
+
+## [1.5.1] - 2020-10-08
 
 ### Added
   - `presets_values.json`: added the new ability `tasks` (eP release `1.5.3`)
@@ -37,7 +117,7 @@ All notable changes to this project will be documented in this file.
   ```
 ### Changed
   - internally: load `Eco::API::Common::Session` before `Eco::API::Common::People`
-  - `Eco::API::Common::Person::EntryFactory`: made child of `Eco::API::Common::Session::BaseSession`
+  - `Eco::API::Common::People::EntryFactory`: made child of `Eco::API::Common::Session::BaseSession`
   - refactored all the `api` connection creation for simplicity and to support multi api version
   - delegated `Eco::API::Session::Batch#get` to `Ecoportal::API::V1::People#get_all`
 

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 ecoPortal
+
+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/eco-helpers.gemspec

@@ -28,7 +28,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency "yard",      ">= 0.9.18", "< 0.10"
   s.add_development_dependency "redcarpet", ">= 3.5.0",  "< 3.6"
 
-  s.add_dependency 'ecoportal-api', '>= 0.7.1', '< 0.8'
+  s.add_dependency 'ecoportal-api', '>= 0.7.2', '< 0.8'
   s.add_dependency 'ecoportal-api-oozes', '>= 0.7.2', '< 0.8'
   s.add_dependency 'aws-sdk-s3',    '>= 1.64.0', '< 2'
   s.add_dependency 'aws-sdk-ses',   '>= 1.29.0', '< 2'

data/lib/eco/api.rb

@@ -7,7 +7,9 @@ module Eco
 end
 
 require_relative 'api/common'
+require_relative 'api/custom'
 require_relative 'api/usecases'
+require_relative 'api/microcases'
 require_relative 'api/policies'
 require_relative 'api/error'
 require_relative 'api/organization'

data/lib/eco/api/common.rb

@@ -7,6 +7,10 @@ end
 
 require_relative 'common/version_patches'
 require_relative 'common/class_helpers'
+require_relative 'common/class_auto_loader'
 require_relative 'common/class_hierarchy'
+require_relative 'common/class_meta_basics'
+require_relative 'common/base_loader'
+require_relative 'common/loaders'
 require_relative 'common/session'
 require_relative 'common/people'

data/lib/eco/api/common/base_loader.rb

@@ -0,0 +1,54 @@
+module Eco
+  module API
+    module Common
+      class BaseLoader
+        extend Eco::API::Common::ClassHelpers
+
+        class << self
+          attr_writer :name, :type
+
+          # The name that this case, policy or error handler will have.
+          def name(value = nil)
+            name_only_once! if value
+            set_created_at!
+            return @name ||= self.to_s unless value
+            @name = value
+          end
+
+          # Sort order
+          def <=>(other)
+            created_at <=> other.created_at
+          end
+
+          # If still not set, it sets the `created_at` class timestamp.
+          def set_created_at!
+            @created_at = Time.now unless @created_at
+          end
+
+          # Class creation timestamp, to be able to load them in the order they were declared.
+          def created_at
+            @created_at ||= Time.now
+          end
+
+          # Prevent the same class to be re-opened/re-named
+          def name_only_once!
+            raise "You have already declared #{self} or you are trying to give it a name twice" if @name
+          end
+
+        end
+
+        # This method will be called when the BaseLoader is created
+        # @note
+        #   - this method should implement the loading logics for the given `Children` class.
+        def initialize
+          raise "You should implement this method"
+        end
+
+        def name
+          self.class.name
+        end
+
+      end
+    end
+  end
+end

data/lib/eco/api/common/class_auto_loader.rb

@@ -0,0 +1,109 @@
+module Eco
+  module API
+    module Common
+      # Helpers for dynamic object loading based on class declaration
+      # @note
+      #   - this helpers aim to boost the usage of the ruby language in complex api configurations.
+      module ClassAutoLoader
+        include Eco::API::Common::ClassHelpers
+
+        # To enable the class autoloader, you should use this  method
+        def autoloads_children_of(klass)
+          class_resolver :autoloader_class, klass
+          @autoloaded_class = klass
+        end
+
+        # Resolves the class `autoloader_class` if it has been defined via `autoloads_children_of`
+        def autoloaded_class
+          return nil unless @autoloaded_class
+          autoloader_class
+        end
+
+        # To which restricted namespaces this class autoloads from
+        def autoloaded_namespaces(type = :include)
+          @autoloaded_namespaces       ||= {}
+          @autoloaded_namespaces[type] ||= []
+        end
+
+        # To restrict which namespaces it is allowed to load from
+        def autoload_namespace(*namespaces)
+          _autoload_namespace(:include, *namespaces)
+        end
+
+        # To ignore certain namespaces this class should not autoload from
+        def autoload_namespace_ignore(*namespaces)
+          _autoload_namespace(:ignore, *namespaces)
+        end
+
+        def _autoload_namespace(type, *namespaces)
+          autoloaded_namespaces(type).concat(namespaces) unless namespaces.empty?
+        end
+
+        # @param constant [Class, String] a class or namespace we want to check auto-load entitlement thereof.
+        # @return [Boolean] determines if a given namespace is entitled for autoloading
+        def autoload_class?(constant)
+          constants = "#{constant}".split("::").compact
+          autoload = true
+          unless autoloaded_namespaces(:include).empty?
+            autoload = autoloaded_namespaces(:include).any? do |ns|
+              "#{ns}".split("::").compact.zip(constants).all? {|(r, c)| r == c}
+            end
+          end
+          unless autoloaded_namespaces(:ignore).empty?
+            autoload &&= autoloaded_namespaces(:ignore).none? do |ns|
+              "#{ns}".split("::").compact.zip(constants).all? {|(r, c)| r == c}
+            end
+          end
+          autoload
+        end
+
+        # As children are loaded as they are declared, we should not load twice same children.
+        def autoloaded_children
+          @auto_loaded_children ||= []
+        end
+
+        # Children classes of `autoloader_class` that have not been created an instance of.
+        def unloaded_children
+          return [] unless autoloaded_class
+          new_detected = new_classes
+          known_class!(*new_detected)
+          descendants(parent_class: autoloaded_class, scope: new_detected).select do |child_class|
+            !autoloaded_children.include?(child_class) && autoload_class?(child_class)
+          end.sort
+        end
+
+        # It loads/creates a new instance of children classes pending to be loaded.
+        # @return [Boolean] `true` if there were children loaded, `false` otherwise.
+        def autoload_children(object)
+          return false if !autoloaded_class || @loading_children
+          pending_children = unloaded_children
+          return false if pending_children.empty?
+          @loading_children = true
+          pending_children.each do |klass|
+            @child = klass.new(object)
+            autoloaded_children.push(klass)
+          end
+          @loading_children = false
+          true
+        end
+
+        # Known namespaces serves the purpose to discover recently added namespaces
+        #   provided that the namespace discovery is optimized
+        def known_classes
+          @known_classes ||= []
+        end
+
+        # Add to known namespaces
+        def known_class!(*classes)
+          known_classes.concat(classes)
+        end
+
+        # List all new namespaces
+        def new_classes
+          ObjectSpace.each_object(::Class).to_a - known_classes
+        end
+
+      end
+    end
+  end
+end

data/lib/eco/api/common/class_helpers.rb

@@ -3,11 +3,14 @@ module Eco
     module Common
       module ClassHelpers
 
+        # Creates an class and instance object methods with name `name` to resolve `klass` name
         def class_resolver(name, klass)
           define_singleton_method(name) { resolve_class(klass) }
           define_method(name) { self.class.resolve_class(klass) }
         end
 
+        # With given a `klass` name it resolves to an actual `Class`
+        # @return [Class] the class that was being searched by name `klass`.
         def resolve_class(klass, exception: true)
           @resolved ||= {}
           @resolved[klass] ||=
@@ -59,6 +62,36 @@ module Eco
           end
         end
 
+        # Finds all child classes of the current class.
+        # @param parent_class [Class] the parent class we want to find children of.
+        # @param direct [Boolean] it will only include direct child classes.
+        # @param scope [nil, Array] to only look for descendants among the ones in `scope`.
+        # @return [Arrary<Class>] the child classes in hierarchy order.
+        def descendants(parent_class: self, direct: false, scope: nil)
+          scope ||= ObjectSpace.each_object(::Class)
+          return [] if scope.empty?
+          scope.select do |klass|
+            klass < parent_class
+          end.sort do |k1, k2|
+            next -1 if k2 < k1
+            next  1 if k1 < k2
+            0
+          end.tap do |siblings|
+            if direct
+              siblings.reject! do |si|
+                siblings.any? {|s| si < s}
+              end
+            end
+          end
+        end
+
+        # @param parent_class [Class] the parent class we want to find children of.
+        # @param direct [Boolean] it will only include direct child classes.
+        # @return [Boolean] `true` if the current class has child classes, and `false` otherwise.
+        def descendants?(parent_class: self, direct: false)
+          descendants(parent_class: parent_class, direct: direct).length > 0
+        end
+
       end
     end
   end

data/lib/eco/api/common/class_hierarchy.rb

@@ -19,7 +19,7 @@ module Eco
         end
 
         # Thanks to this step the format on the declaration of the model is flexible
-        # @param value [Hash, Enumerable, String, Symbol, nil]
+        # @param model [Hash, Enumerable, String, Symbol, nil]
         # @return [Hash, nil] where keys are `Symbol` s
         def parse_model(model)
           case model

data/lib/eco/api/common/class_meta_basics.rb

@@ -0,0 +1,16 @@
+module Eco
+  module API
+    module Common
+      module ClassMetaBasics
+
+        # Helps to define methods and keep track on them
+        def define(name, &block)
+          name = name.to_sym
+          @helpers[name] = block
+          define_method(name.to_sym, &block)
+        end
+
+      end
+    end
+  end
+end

data/lib/eco/api/common/loaders.rb

@@ -0,0 +1,13 @@
+module Eco
+  module API
+    module Common
+      module Loaders
+      end
+    end
+  end
+end
+
+require_relative 'loaders/use_case'
+require_relative 'loaders/policy'
+require_relative 'loaders/error_handler'
+require_relative 'loaders/parser'

data/lib/eco/api/common/loaders/error_handler.rb

@@ -0,0 +1,41 @@
+module Eco
+  module API
+    module Common
+      module Loaders
+        class ErrorHandler < Eco::API::Common::BaseLoader
+
+          class << self
+            attr_writer :error
+
+            # @return [Eco::API::Error] the error class, child of `Eco::API::Error`.
+            def error(value = nil)
+              unless value
+                return @error || raise("You should specify an error type for #{self.class}")
+              end
+              @error = value
+            end
+          end
+
+          def initialize(handlers)
+            raise "Expected Eco::API::Policies. Given #{handlers.class}" unless handlers.is_a?(Eco::API::Error::Handlers)
+            handlers.on(self.error, &self.method(:main))
+          end
+
+          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param session [Eco::API::Session] the current session where the usecase kicks in.
+          # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
+          # @param handler [Eco::API::Error::Hanlder] the `error handler` instance object.
+          # @param job [Eco::API::Session::Batch::Job] the `Batch::Job` made on purpose for this handler.
+          def main(people, session, options, handler, job)
+            raise "You should implement this method"
+          end
+
+          def error
+            self.class.error
+          end
+
+        end
+      end
+    end
+  end
+end