eco-helpers 1.0.13 → 1.0.14

data/lib/eco/api/session/batch/status.rb

@@ -2,26 +2,36 @@ module Eco
   module API
     class Session
       class Batch
-        class Status < Common::Session::BaseSession
-          @types = [:exact, :search]
+        # @attr_reader source_queue [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>]
+        #   The queue as it was originally made (it could contain duplicates)
+        # @attr_reader queue [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>]
+        #   `source_queue` with no repeated elements (**note**: observe that the elimination of duplicates could fail)
+        # @attr_reader mode [Symbol] the `mode` that the `batch` was run with
+        # @attr_reader root [Eco::API::Session::Job] the `job` that launched the `batch`
+        class Status < Eco::API::Common::Session::BaseSession
+          @modes = [:exact, :search]
 
           attr_reader :source_queue
-          attr_reader :queue, :method, :type
+          attr_reader :queue, :method, :mode
           attr_reader :root
 
           class << self
-            attr_reader :types
+            attr_reader :modes
 
-            def valid_type?(value)
-              types.include?(value)
+            def valid_mode?(value)
+              modes.include?(value)
             end
           end
 
-          def initialize(e, queue:, method:, type: :exact)
+          # @param e [Eco::API::Common::Session::Environment] requires a session environmen, as any child of `Eco::API::Common::Session::BaseSession`
+          # @param queue  [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>] the `source_queue`
+          # @param method [Symbol] the type of `batch operation`
+          # @param mode [Symbol] the mode of `batch operation` (search)
+          def initialize(e, queue:, method:, mode: :exact)
             super(e)
             fatal("In batch operations you must batch an Enumerable. Received: #{queue}")  unless queue && queue.is_a?(Enumerable)
 
-            self.type     = type
+            self.mode     = mode
             @method       = method
             @source_queue = queue
 
@@ -41,33 +51,58 @@ module Eco
             @people_match = Array.new(@queue.length, [])
           end
 
+          # Nativelly to this gem, a batch against the server is lauched by an Eco::API::Session::Job.
+          # When the batch returns the `BatchStatus`, the `Job` assigns itself as `root` of it.
+          # @param object [Eco::API::Session::Job]
           def root=(object)
             @root = object
           end
 
-          def type=(value)
-            fatal("Invalid :type '#{value}. You must specify type: as one of #{self.class.types} ") unless self.class.valid_type?(value)
-            @type = value
+          def mode=(value)
+            fatal("Invalid :mode '#{value}. You must specify mode: as one of #{self.class.modes} ") unless self.class.valid_mode?(value)
+            @mode = value
           end
 
+          # @return [Eco::API::Session::Batch::Errors] errors object helper
           def errors
-            @errors ||= Batch::Errors.new(status: self)
+            @errors ||= Eco::API::Session::Batch::Errors.new(status: self)
           end
 
+          # Get the assciated `reponse` of an input entry object `key`
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person] these are the **index options**:
+          #   1. `Integer`: index/position of the entry in the final `queue`
+          #   2. `Hash`: entry queries can be raw `Hash` objects
+          #   3. `Person` object: the most common case is to use the person wrapper classes of the `Ecoportal::API` namespace.
+          # @return response key [Ecoportal::API::Common::BatchResponse]
           def [](key)
             @responses[to_index(key)]
           end
 
-
+          # Associates an input entry object `key` to its `response`
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @see Eco::API::Session::Batch::Status#[] for `key` options
+          # @param response key [Ecoportal::API::Common::BatchResponse]
           def []=(key, response)
             @responses[to_index(key)] = response
           end
 
+          # The _person_ we got from the Server wrapped to the `Person` object for the input entry object `key`
+          # @note it only makes sense when the batch method used was `get`
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @see Eco::API::Session::Batch::Status#[] for `key` options
+          # return [Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
           def person(key)
             return self[key].result if success?(key)
             nil
           end
 
+          # The _person_ we got from the Server wrapped to the `Person` object for the input entry object `key`
+          # @note
+          #   - it only makes sense when the _batch method_ used was `get` with `q`
+          #   - **found using a search criteria** (`mode` == `:search`), as opposite to find the person directly by `external_id`
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @see Eco::API::Session::Batch::Status#[] for `key` options
+          # return [Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
           def person_match(key)
             @person_match[to_index(key)]
           end
@@ -84,44 +119,56 @@ module Eco
             @people_match[to_index(key)] = people
           end
 
+          # Has the _entry_ `key` been queried to the server?
+          # @param key [Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @return [Boolean] `true` if input entry `key` has an associated `Ecoportal::API::Common::BatchResponse`
           def received?(key)
             !!self[key]
           end
 
+          # Has the _entry_ `key` 's query to the server been successful
+          # @param key [Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @return [Boolean] `true` if input entry `key` has not had a server Error during the query
           def success?(key)
             self[key]&.success?
           end
 
+          # When the batch _method_ has been `get`, it gathers into an `Array` the people found.
+          # @note here is where the used `mode` gets relevance:
+          #   - while `:exact` mode will keep the order of found people as per order of final `queue`
+          #   - `:search` mode will just gather the results (order won't match)
+          # @raise [Exception] when the `method` of the batch operation was other than `get`
+          # @return [Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>] all the people that has been found.
           def people
             fatal "This batch wasn't a 'get'. Can't obtain people without 'get' method" unless method == :get
-            #out = Eco::API::Organization::People.new([])
-            if type == :exact
+            if mode == :exact
               out = Array(queue.length)
               @responses.each_with_index do |response, i|
-                # out = out.merge([response.result]) if respose.success?
                 out[i] = response.result if response.success?
               end
-            elsif type == :search
+            elsif mode == :search
               out = []
               queue.each_with_index.map do |entry, i|
                 pers   = person(entry)
                 pers ||= person_match(entry)
                 ppl    = pers ? [pers] : people_match(entry)
                 out += ppl
-                # out = out.merge(ppl) unless ppl.empty?
               end
             end
             out
           end
 
+          # Helper to transform any `key` to an `Integer` index
+          # @return [Integer] the index that `key` has in the final `queue`
           def to_index(key)
             key.is_a?(Integer) ? valid_index(index: key) : valid_index(entry: key)
           end
 
+          # _Index_ validator to make this object reliable
           def valid_index(index: nil, entry: nil)
             index ||= @hash[entry]
             unless index && index < @queue.length
-              fatal "You must provide either the index or the original entry object of the batch"
+              fatal "You must provide either the index on the final 'queue' or the original entry object of the batch"
             end
             index
           end

data/lib/eco/api/session/config.rb

@@ -274,6 +274,16 @@ module Eco
           end
         end
 
+        def batch_policies
+          @batch_policies = self["batch_policies"] ||= Eco::API::Session::Batch::Policies.new("batch_policy")
+          if block_given?
+            yield(@batch_policies)
+            self
+          else
+            @batch_policies
+          end
+        end
+
         def error_handlers
           @error_handlers = self["error_handlers"] ||= Eco::API::Error::Handlers.new
           if block_given?

data/lib/eco/api/session/config/workflow.rb

@@ -32,7 +32,7 @@ module Eco
             def get_model(key)
               raise "Expected Symbol. Given: #{key.class}" unless key.is_a?(Symbol)
               workflow = @workflow[key]
-              raise "Expected Array. Given #{model.class}" unless !workflow || workflow.is_a?(Hash)
+              raise "Expected Hash. Given #{model.class}" unless !workflow || workflow.is_a?(Hash)
 
               class_name      = titleize(key.to_s)
               full_class_name = "#{self}::#{class_name}"

data/lib/eco/api/usecases/default_cases/set_default_tag_case.rb

@@ -14,7 +14,7 @@ module Eco
                 msg = "There is no tagtree definition in the configuration files\n" +
                       "For this usecase to work out you need to define it."
                 session.logger.fatal(msg)
-                exit
+                raise msg
               end
 
               # IMPORTANT: this two lines ensure that only people to be updated is selected
@@ -22,8 +22,9 @@ module Eco
               people = people.account_present
 
               if people.length <= 0
-                session.logger.info("There are no people with account... aborting script")
-                exit
+                msg = "There are no people with account... aborting script"
+                session.logger.info(msg)
+                raise msg
               end
 
               update   = session.job_group("main").new("update", usecase: usecase, type: :update, sets: :account)

data/lib/eco/api/usecases/default_cases/switch_supervisor_case.rb

@@ -8,32 +8,37 @@ module Eco
             @cases.define("switch-supervisor", type: :transform) do |people, session, options, usecase|
 
               unless old_id = options.dig(:super, :old)
-                session.logger.error("You haven't specified the original supervisor. Aborting...")
-                exit
+                msg = "You haven't specified the original supervisor. Aborting..."
+                session.logger.error(msg)
+                exit(1)
               end
 
               # we could be setting the supervisor to nil
               unless options[:super].key?(:new)
-                session.logger.error("You haven't specified the new supervisor. Aborting...")
-                exit
+                msg = "You haven't specified the new supervisor. Aborting..."
+                session.logger.error(msg)
+                exit(1)
               end
 
               new_id =  options.dig(:super, :new)
 
               unless old_sup = people.person(id: old_id, external_id: old_id, email: old_id)
-                session.logger.error("Couldn't find any user with that id (old-super): '#{old_id}'. Aborting...")
-                exit
+                msg = "Couldn't find any user with that id (old-super): '#{old_id}'. Aborting..."
+                session.logger.error(msg)
+                exit(1)
               end
 
               unless new_sup = people.person(id: new_id, external_id: new_id, email: new_id)
-                session.logger.error("Couldn't find any user with that id (new-super): '#{new_id}'. Aborting...")
-                exit
+                msg = "Couldn't find any user with that id (new-super): '#{new_id}'. Aborting..."
+                session.logger.error(msg)
+                exit(1)
               end
 
               people = people.supervisor_id(old_sup.id)
               unless people.length > 0
-                session.logger.error("There are no people with supervisor #{old_sup.external_id} (#{old_sup.name} - #{old_sup.email}). Aborting...")
-                exit
+                msg = "There are no people with supervisor #{old_sup.external_id} (#{old_sup.name} - #{old_sup.email}). Aborting..."
+                session.logger.error(msg)
+                exit(1)
               end
 
               session.logger.info("Going to change supervisor '#{old_sup.name}' (#{old_sup.external_id}) to '#{new_sup.name}' (#{new_sup.external_id})")

data/lib/eco/cli/config/default/filters.rb

@@ -50,8 +50,9 @@ ASSETS.cli.config do |cnf|
       sch_id   = session.schemas.to_id(sch_name)
 
       unless sch_id
-        puts "You need to specify the schema id"
-        exit
+        msg = "You need to specify the schema id"
+        session.logger.error(msg)
+        exit(1)
       end
 
       options.deep_merge!(people: {filter: {details: {schema_id: sch_id}}})

data/lib/eco/cli/config/default/options.rb

@@ -6,6 +6,18 @@ ASSETS.cli.config do |cnf|
       options[:simulate] = true
     end
 
+    options_set.add("-skip-batch-policy") do |options|
+      options.deep_merge!(skip: {batch_policy: true})
+    end
+
+    options_set.add("-skip-api-policies") do |options|
+      options.deep_merge!(skip: {api_policies: true})
+    end
+
+    options_set.add("-feed-only-stats") do |options|
+      options.deep_merge!(feedback: {only_stats: true})
+    end
+
     options[:end_get] = true
     options_set.add("-no-get") do |options|
       options[:end_get] = false

data/lib/eco/cli/config/default/usecases.rb

@@ -21,14 +21,16 @@ ASSETS.cli.config do |cnf|
     cases.add("-set-supervisor-from", :sync, case_name: "set-supervisor")
     cases.add("-switch-supervisor", :transform, case_name: "switch-supervisor") do |people, session, options|
       unless old_id = SCR.get_arg("-old-super", with_param: true)
-        session.logger.error("You must specify an -old-super to target whose supervisor is changing")
-        exit
+        msg = "You must specify an -old-super to target whose supervisor is changing"
+        session.logger.error(msg)
+        exit(1)
       end
       options.deep_merge!(super: {old: old_id})
 
       unless new_id = SCR.get_arg("-new-super", with_param: true)
-        session.logger.error("You must specify the -new-super id. To reset to nil the supervisor, please, specify nil.")
-        exit
+        msg = "You must specify the -new-super id. To reset to nil the supervisor, please, specify nil."
+        session.logger.error(msg)
+        exit(1)
       end
       new_id = new_id == "nil"? nil : new_id
       options.deep_merge!(super: {new: new_id})

data/lib/eco/cli/config/default/workflow.rb

@@ -32,8 +32,9 @@ ASSETS.cli.config do |config|
 
     wf.on(:usecases) do |wf_cases, io|
       unless config.usecases.process(io: io)
-        io.session.logger.warn("No update operation specified... quitting")
-        exit
+        msg = "No update operation specified... quitting"
+        io.session.logger.warn(msg)
+        exit(1)
       end
       io
     end

data/lib/eco/cli/scripting/args_helpers.rb

@@ -42,7 +42,7 @@ module Eco
           if !filename
               if required
                 puts "you need to specify a file '#{key} file'"
-                exit
+                exit(1)
               end
           elsif  !(File.exists?(filename) || File.exists?(File.expand_path(filename)))
             if should_exist && required

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = "1.0.13"
+  VERSION = "1.0.14"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 1.0.13
+  version: 1.0.14
 platform: ruby
 authors:
 - Oscar Segura
@@ -308,10 +308,14 @@ files:
 - lib/eco/api/policies/policy.rb
 - lib/eco/api/session.rb
 - lib/eco/api/session/batch.rb
+- lib/eco/api/session/batch/base_policy.rb
 - lib/eco/api/session/batch/errors.rb
+- lib/eco/api/session/batch/feedback.rb
 - lib/eco/api/session/batch/job.rb
 - lib/eco/api/session/batch/jobs.rb
 - lib/eco/api/session/batch/jobs_groups.rb
+- lib/eco/api/session/batch/policies.rb
+- lib/eco/api/session/batch/request_stats.rb
 - lib/eco/api/session/batch/status.rb
 - lib/eco/api/session/config.rb
 - lib/eco/api/session/config/api.rb