eco-helpers 1.0.13 → 1.0.14

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

@@ -45,7 +45,7 @@ module Eco
           params = {per_page: DEFAULT_BATCH_BLOCK}.merge(params)
 
           launch(data, method: :get, params: params, silent: silent).tap do |status|
-            status.type = :search
+            status.mode = :search
 
             entries = status.queue
             puts "\n"
@@ -86,10 +86,6 @@ module Eco
 
         private
 
-        def new_status(queue, method)
-          Batch::Status.new(enviro, queue: queue, method: method)
-        end
-
         def get(params: {}, silent: false)
           fatal "cannot batch get without api connnection, please provide a valid api connection!" unless people_api = api&.people
 
@@ -97,7 +93,7 @@ module Eco
           client = people_api.client
 
           looping = !params.key?(:page)
-          page = params[:page] || 1
+          page    = params[:page] || 1
 
           people = []; total_pages = nil
           cursor_id = nil
@@ -129,7 +125,7 @@ module Eco
         def client_get(client, params:, silent: false)
           response = client.get("/people", params: params)
           unless response.success?
-            msg = "Request failed - params: #{params}"
+            msg  = "Request failed - params: #{params}"
             msg += "\n Error message: - Status #{response.status}: #{response.body}"
             fatal msg
           end
@@ -147,9 +143,6 @@ module Eco
           return nil if !data || !data.is_a?(Enumerable)
           fatal "cannot batch #{method} without api connnection, please provide a valid api connection!" unless people_api = api&.people
 
-          # batch Status
-          status = new_status(data, method)
-
           # param q does not make sense here, even for GET method
           params   = {per_page: DEFAULT_BATCH_BLOCK}.merge(params)
           per_page = params[:per_page] || DEFAULT_BATCH_BLOCK
@@ -157,25 +150,26 @@ module Eco
           iteration  = 1; done = 0
           iterations = (data.length.to_f / per_page).ceil
 
-          data.each_slice(per_page) do |slice|
-            msg = "starting batch '#{method}' iteration #{iteration}/#{iterations}, with #{slice.length} entries of #{data.length} -- #{done} done"
-            logger.info(msg) unless silent
+          Eco::API::Session::Batch::Status.new(enviro, queue: data, method: method).tap do |status|
+            data.each_slice(per_page) do |slice|
+              msg = "starting batch '#{method}' iteration #{iteration}/#{iterations}, with #{slice.length} entries of #{data.length} -- #{done} done"
+              logger.info(msg) unless silent
 
-            people_api.batch do |batch|
-              slice.each do |person|
-                batch.public_send(method, person) do |response|
-                  faltal("Request with no response") unless !!response
-                  status[person] = response
+              people_api.batch do |batch|
+                slice.each do |person|
+                  batch.public_send(method, person) do |response|
+                    faltal("Request with no response") unless !!response
+                    status[person] = response
+                  end
                 end
-              end
-            end # next batch
+              end # next batch
 
-            iteration += 1
-            done += slice.length
-          end # next slice
+              iteration += 1
+              done += slice.length
+            end # next slice
 
-          status.errors.print unless silent
-          return status
+            status.errors.print unless silent
+          end
         end
 
       end
@@ -184,6 +178,10 @@ module Eco
 end
 
 require_relative 'batch/job'
+require_relative 'batch/feedback'
+require_relative 'batch/request_stats'
+require_relative 'batch/base_policy'
+require_relative 'batch/policies'
 require_relative 'batch/status'
 require_relative 'batch/errors'
 require_relative 'batch/jobs'

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

@@ -0,0 +1,283 @@
+module Eco
+  module API
+    class Session
+      class Batch
+        # Helper class to build a hiearchical model of policies
+        # @example Usage:
+        #     class PolicyModel < Eco::API::Session::Batch::BasePolicy
+        #       MODEL = {attr1: ["prop1a", "prop1b", {"prop1c": ["prop1c1"]}]}
+        #       self.model = MODEL
+        #       policy_attrs *model_attrs
+        #     end
+        #
+        #     policies = PolicyModel.new("batch_policy")
+        #     policies.attr1c do |attr1c|
+        #       attr1c.prop1c1.max = 30
+        #     end
+        #
+        # @attr_reader attr [Symbol] the Symbol `name` of the current policy
+        # @attr_reader max [Integer] `max` **allowed**  number of occurrences of the property
+        # @attr_reader min [Integer] `min` **required** number of occurrences of the property
+        class BasePolicy
+          extend Eco::API::Common::ClassHelpers
+
+          # @attr_reader model [Hash, nil] the `model` of the current `class`
+          class << self
+            attr_reader :model
+
+            # @param value [Hash, Enumerable, String, Symbol, nil] unparsed model to be assigned to the `class`
+            def model=(value)
+              @model = parse_model(value)
+            end
+
+            # @return [Array<String>] the `keys` of the current class' `model`
+            def model_attrs
+              (model && model.keys) || []
+            end
+
+            # Helper to normalize `key` into a correct `ruby` **constant name**
+            # @param key [String, Symbol] to be normalized
+            # @return [String] a correct constant name
+            def titleize(key)
+              str_name = key.to_s.strip.split(/[\-\_ ]/i).compact.map do |str|
+                str.slice(0).upcase + str.slice(1..-1).downcase
+              end.join("")
+            end
+
+            # If the class for `key` exists, it returns it. Otherwise it generates it.
+            # @note for this to work, `key` should be one of the submodels of the current class' `model`
+            # @return [Eco::API::Session::Batch::BasePolicy] or subclass thereof
+            def policy_class(key)
+              key             = key.to_sym.freeze
+              class_name      = titleize(key)
+              full_class_name = "#{self}::#{class_name}"
+
+              unless target_class = resolve_class(full_class_name, exception: false)
+                submodel = model[key]
+                target_class = Class.new(self) do |klass|
+                  klass.model = submodel
+                  policy_attrs *klass.model_attrs
+                end
+
+                self.const_set class_name, target_class
+              end
+
+              target_class
+            end
+
+            # Thanks to this step the format on the declaration of the model is flexible
+            # @param value [Hash, Enumerable, String, Symbol, nil]
+            # @return [Hash, nil] where keys are `Symbol` s
+            def parse_model(model)
+              case model
+              when String
+                return parse_model(model.to_sym)
+              when Symbol
+                return {model => nil}
+              when Hash
+                return model.each_with_object({}) do |(k,v), hash|
+                  hash[k.to_sym] = v
+                end
+              when Enumerable
+                return model.each_with_object({}) do |sub, hash|
+                  hash.merge!(parse_model(sub))
+                end
+              when NilClass
+                return nil
+              else
+                raise "Incorrect model declaration, allowed String, Symbol, Hash and Enumerable. Given: #{model.class}"
+              end
+            end
+
+            # Attributes of this level of the model that should be included
+            # @param attr [Symbol, String] each of the subpolicies of the model that should be available
+            def policy_attrs(*attrs)
+              attrs = attrs.map(&:to_sym)
+
+              attrs.each do |attr|
+                method = attr.to_s.freeze
+                var    = "@#{method}".freeze
+
+                define_method(method) do |&block|
+
+                  unless policy = self[attr]
+                    klass  = self.class.policy_class(attr)
+                    policy = self[attr] = klass.new(attr, _parent: self)
+                  end
+
+                  if block
+                    block.call(policy)
+                    self
+                  else
+                    policy
+                  end
+                end
+
+              end
+            end
+
+          end
+
+          include Enumerable
+
+          attr_reader   :attr
+          attr_accessor :max, :min
+
+          def initialize(attr = nil, _parent: self)
+            @_parent  = _parent
+            @attr     = attr.to_sym
+            @policies = {}
+          end
+
+          def attr(as_namespace: false)
+            return @attr if !as_namespace || root?
+            "#{@_parent.attr(as_namespace: true)}:#{@attr}"
+          end
+
+          # @note if there's no `min` defined, it always returns `true`
+          # @param value [Integer] value to check if it's in the minimum required
+          # @retrun [Boolen] `true` if `value` is grater or equal to `min`
+          def min?(value)
+            !min || !value|| (min <= value)
+          end
+
+          # @note if there's no `max` defined, it always returns `true`
+          # @param value [Integer] value to check if it's in the maximum allowed
+          # @retrun [Boolen] `true` if `value` is lesser or equal to `min`
+          def max?(value)
+            !max || !value || (max >= value)
+          end
+
+          # return [Integer] number of declared subpolicies
+          def length
+            count
+          end
+
+          # @return [Boolean] `true` if there are no active subpolicies, `false` otherwise
+          def empty?
+            count == 0
+          end
+
+          # @return [Boolean] `true` if there are active subpolicies, `false` otherwise
+          def subpolicies?
+            !empty?
+          end
+
+          def each(params: {}, &block)
+            return to_enum(:each) unless block
+            items.each(&block)
+          end
+
+          # @return [Array<Eco::API::Session::Batch::BasePolicy>] the active subpolicies
+          def items
+            @policies.values
+          end
+
+          # @param attr [Symbol, String] name of the policy
+          # @return [Boolean] if `attr` is an active subpolicy
+          def active?(attr)
+            @policies.key?(attr.to_sym)
+          end
+
+          # @param attr [Symbol, String] name of the policy
+          # @return [Array<Eco::API::Session::Batch::BasePolicy>] the used subpolicies
+          def [](attr)
+            @policies[attr.to_sym]
+          end
+
+          # @param attr [Symbol, String] name of the policy
+          # @param value [Expected object of Eco::API::Session::Batch::BasePolicy] a subpolicy to assign to a name `attr`
+          def []=(attr, value)
+            raise "Expected object of Eco::API::Session::Batch::BasePolicy. Given #{value.class}" unless value.is_a?(Eco::API::Session::Batch::BasePolicy)
+            @policies[attr.to_sym] = value
+          end
+
+          # @param model [Hash] plain hash (or hashable object) with the stats to check policy compliance against
+          # @param recurse [Boolean] to determine if we only check the current policy or also all active subpolicies
+          # @return [Boolean] `true` if `model` is compliant with the current policy
+          def compliant?(model, recurse: true)
+            unless hash = model_to_hash(model)
+              raise "Expected 'model' to be a Hash (or hashable) object. Given: #{model}"
+            end
+            value   = model_attr(hash)
+            good    = !model_attr?(hash) || (min?(value) && max?(value))
+            #pp "batch_policy: '#{attr}' - #{value}: 'min' #{min?(value)}; 'max' #{max?(value)}"
+            good  &&= all? {|active| active.compliant?(model, recurse: recurse)} if recurse
+            good
+          end
+
+          def validate!(model)
+            unless compliant?(model)
+              msg = self.uncompliance(model)
+              raise "Uncompliance Exception\n#{msg}"
+            end
+          end
+
+          # @param model [Hash] plain hash (or hashable object) with the stats to check policy compliance against
+          # @return [Array<Eco::API::Session::Batch::BasePolicy>] **non-compliant** policies for the `model`
+          def uncompliant(model)
+            each_with_object([]) do |active, arr|
+              arr.concat(active.uncompliant(model))
+            end.tap do |arr|
+              arr.unshift(self) unless compliant?(model, recurse: false)
+            end
+          end
+
+          # @param model [Hash] plain hash (or hashable object) with the stats to check policy compliance against
+          # @param recurse [Boolean] to determine if we only check the current policy or also all active subpolicies
+          # @return [String] message with what failed to meet compliance
+          def uncompliance(model, recurse: true)
+            unless hash = model_to_hash(model)
+              raise "Expected 'model' to be a Hash (or hashable) object. Given: #{model}"
+            end
+            msg = ""
+            unless compliant?(hash, recurse: false)
+              value = model_attr(hash)
+              msg += "'#{attr(as_namespace: true)}' fails to meet: "
+              msg += " [ min(#{min}) >=  #{value}] " unless min?(value)
+              msg += " [ max(#{max}) <=  #{value}] " unless max?(value)
+              msg += "\n"
+            end
+
+            if recurse
+              map do |active|
+                active.uncompliance(hash, recurse: true)
+              end.compact.tap do |msgs|
+                msg += "\n" + msgs.join("\n") unless msgs.empty?
+              end
+            end
+            msg
+          end
+
+          protected
+
+          # Internal helper to know if we are at the top/root of the hierarchical model
+          # @return [Boolean] `true` if this object is the top `root`, `false` otherwise
+          def root?
+            @_parent == self
+          end
+
+          def to_h
+            @policies
+          end
+
+          def model_attr?(hash)
+            hash.key?(self.attr) || hash.key?(self.attr.to_s)
+          end
+
+          def model_attr(hash)
+            hash[self.attr] || hash[self.attr.to_s] if model_attr?(hash)
+          end
+
+          private
+
+          def model_to_hash(model)
+            return model if model.is_a?(Hash)
+            model.to_h if model.respond_to?(:to_h)
+          end
+
+        end
+      end
+    end
+  end
+end

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

@@ -2,27 +2,34 @@ module Eco
   module API
     class Session
       class Batch
+        # Helper object linked to a `batch status`
         class Errors
 
+          # @attr_reader status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
           attr_reader :status
 
+          # @param status [Eco::API::Session::Batch::Status] `batch status` this `Errors` object is associated to.
           def initialize(status:)
-            "Expected Batch::Status as root. Given: #{status.class}" unless status.is_a?(Batch::Status)
+            "Expected Batch::Status as root. Given: #{status.class}" unless status.is_a?(Eco::API::Session::Batch::Status)
             @status = status
           end
 
+          # @see [Eco::API::Session::Batch::Status#queue]
           def queue
             status.queue
           end
 
+          # @see [Eco::API::Session::Batch::Status#method]
           def method
             status.method
           end
 
+          # @see [Eco::API::Session::Batch::Status#to_index]
           def to_index(*args)
             status.to_index(*args)
           end
 
+          # @return [Eco::API::Session] currently active `session`
           def session
             status.session
           end
@@ -31,13 +38,20 @@ module Eco
             status.logger
           end
 
+          # Was there any **error** as a result of this batch?
+          # @return [Boolean] `true` if any of the queried _entries_ got an unsuccessful `Ecoportal::API::Common::BatchResponse`
           def any?
             queue.any? {|query| !status[query].success?}
           end
 
+          # Input entries that got launched against the server.
+          # @raise [Exception] if there are elements of the final `queue` that did not get response
+          # @note discards those that did not get _response_ from the Server (so those that were not queried)
+          #   - please, observe that this can only happen if there were repeated entries in the `source_queue`
+          # @return [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>]
           def entries
             queue.each_with_index.map do |query, i|
-              unless status[i]
+              unless response = status[i]
                 msg  = "Error: query with no response. You might have duplicated entries in your queue.\n"
                 msg += "Queue length: #{queue.length}; Queue elements class: #{queue.first.class}\n"
                 msg += "Query with no response. Person: #{person_ref(query)}\n"
@@ -49,7 +63,7 @@ module Eco
                 raise msg
               end
 
-              status[i].success? ? nil : query
+              response.success? ? nil : query
             end.compact
           end
 

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

@@ -0,0 +1,112 @@
+module Eco
+  module API
+    class Session
+      class Batch
+        # @attr_reader job [Eco::API::Session::Batch::Job] `batch job` the feedback is associated with
+        class Feedback
+
+          attr_reader :job
+
+          # @param job [Eco::API::Session::Batch::Job] `batch job` the feedback is associated with
+          def initialize(job:)
+            raise "A Eco::API::Session::Batch::Job object is required. Given: #{job}" unless job.is_a?(Eco::API::Session::Batch::Job)
+            @job  = job
+          end
+
+          # @see Eco::API::Session::Batch::Job#name
+          # @return [String] name of the `batch job`
+          def name
+            job.name
+          end
+
+          # @see Eco::API::Session::Batch::Job#type
+          def type
+            job.type
+          end
+
+          # @see Eco::API::Session::Batch::Job#sets
+          def sets
+            job.sets
+          end
+
+          # @see Eco::API::Session::Batch::Job#options
+          def options
+            job.options
+          end
+
+          # Slightly modifies the behaviour of `as_update`, so schema detail fields show the `alt_id`
+          # @note for better feedback
+          # @param entry [Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          def as_update(entry)
+            case
+            when entry.is_a?(Hash)
+              hash = entry
+            else #entry.is_a?(Ecoportal::API::V1::Person)
+              if only_ids?
+                hash = {
+                  "id"          => entry.id,
+                  "external_id" => entry.external_id,
+                  "email"       => entry.email
+                }
+                hash = entry.as_json.slice("id", "external_id", "email")
+              else
+                hash = entry.as_update
+                if entry.details
+                  if hfields = hash.dig("details", "fields")
+                    hfields.each do |fld|
+                      fld.merge!("alt_id" => entry.details.get_field(fld["id"]).alt_id)
+                    end
+                  end
+                end
+              end
+            end
+            hash || {}
+          end
+
+          def request_stats(data)
+            @request_stats ||= Eco::API::Session::Batch::RequestStats.new(type: type, requests: data)
+          end
+
+          def generate(requests, max_chars: 800, only_stats: false)
+            msg = []
+            if !requests || !requests.is_a?(Enumerable) || requests.empty?
+              msg << "#{"*" * 20} Nothing for #{signature} so far :)  #{"*" * 20}"
+            else
+              sample_length = 1
+              sample = requests.slice(0, 20).map do |request|
+                max_chars     -= request.pretty_inspect.length
+                sample_length += 1 if max_chars > 0
+                request
+              end
+
+              header = "#{"*"*20}  #{signature} #{only_stats ? "" : "- Feedback Sample"} #{"*"*20}"
+              msg << header
+              unless only_stats
+                msg << "#{sample.slice(0, sample_length).pretty_inspect}"
+              end
+              msg << "#{"+"*5}  STATS  ++  #{type.to_s.upcase} length: #{requests.length}  #{"+"*5}"
+              msg << "#{request_stats(requests).message}"
+              msg << "*" * header.length
+            end
+            msg.join("\n")
+          end
+
+          private
+
+          def only_ids?
+            [:delete, :get].include?(type)
+          end
+
+          def signature
+            "Batch job \"#{name}\" ['#{type.to_s.upcase}': #{sets_title}]"
+          end
+
+          def sets_title
+            "#{sets.map {|s| s.to_s}.join(", ")}"
+          end
+
+        end
+      end
+    end
+  end
+end