eco-helpers 1.1.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 749e298478fcb12ab365f02ef46b78189c7208da89ec7e685b32ec77ba414fac
-  data.tar.gz: e440ad822d6a825bf4185ee9489955fca000b52c85196d633a78c8d2bde59a1e
+  metadata.gz: a2efa416d986a9c212bc99ec69bf667778392737f0c635d54a18d19ff8bced9b
+  data.tar.gz: 7747bbfa3253f537d08b65148f8fc7418b0f4190d2754873daeb0b9fc5642b41
 SHA512:
-  metadata.gz: 50de4fee6dd471172367acb718ebc83323ea36ac74ae53f96c7e3aa32cc531160b0f2fd5f62458576c39a349d74a88efdb478d3a658b95ec191c509e038a5fa4
-  data.tar.gz: 741993e6d9445b8f55e611b2315299a477bbaaf6f928f4a87e8ab6f88576fadcec5032c9df590222dd10d2e8b569c193b8bc0e16ce97984f595cd155722e3993
+  metadata.gz: 60457d180398b01377aaeb6bced7c57fb24010da7acecbca8cbdac46a16d617759a23175e6b7be8c2b8eb4ec3834119e5173d8f2ff14212493a3db35298441ed
+  data.tar.gz: 5fab0a498910811d86f63419193aa02d1aebd52d4a1c63db1d11c173d9905f651e47c1082090ef0a83236f8c1d48d2c206572d25b1881b05dddc6cbc4be69c0e

data/lib/eco/api/common/session/environment.rb

@@ -35,7 +35,7 @@ module Eco
             @sftp        ||= Eco::API::Common::Session::SFTP.new(enviro: self)
           end
 
-          def s3upoader
+          def s3uploader
             @s3uploader  ||= Eco::API::Common::Session::S3Uploader.new(enviro: self)
           end
 

data/lib/eco/api/common/session/mailer.rb

@@ -7,6 +7,7 @@ module Eco
       module Session
         class Mailer
 
+          # @param enviro [Eco::API::Common::Session::Environment]
           def initialize (enviro:)
             raise "Required Environment object (enviro:). Given: #{enviro}" if enviro && !enviro.is_a?(Eco::API::Common::Session::Environment)
             @enviro = enviro
@@ -16,10 +17,10 @@ module Eco
           # @param to [String] destination email address
           # @param subject [String] subject of the email
           # @param body [String] `html` or plain text message
-          def mail(to:, subject:, body:)
+          def mail(to: nil, subject:, body:)
             ses.send_email(
               destination: {
-                to_addresses: [to].flatten,
+                to_addresses: [fetch_to(to)].flatten,
               },
               source:  fetch_from,
               message: {
@@ -64,6 +65,10 @@ module Eco
             @enviro.config || {}
           end
 
+          def fetch_to(value = nil)
+            value || config.mailer.to
+          end
+
           def fetch_from(value = nil)
             value || config.mailer.from
           end

data/lib/eco/api/common/session/s3_uploader.rb

@@ -8,6 +8,7 @@ module Eco
         class S3Uploader
           attr_reader :prefix
 
+          # @param enviro [Eco::API::Common::Session::Environment]
           def initialize (enviro:)
             raise "Required Environment object (enviro:). Given: #{enviro}" if enviro && !enviro.is_a?(Eco::API::Common::Session::Environment)
             @enviro    = enviro
@@ -15,6 +16,10 @@ module Eco
             @timestamp = Time.now.iso8601
           end
 
+          # Uploads `content` to S3 as `filename`
+          # @param filename [String] the name of the object to be created on S3
+          # @param content [String] that to be uploaded
+          # @return [String] S3 path to the uploaded `filename` object
           def upload(filename, content)
             if obj = new_s3_object(filename)
               log_upload(obj) do
@@ -24,16 +29,24 @@ module Eco
             return full_path(obj)
           end
 
+          # Uploads a single file
+          # @param path [String] the target file to be uploaded
+          # @return [String] S3 path to the uploaded `path` file
           def upload_file(path)
             File.open(path, "rb") do |f|
               upload(File.basename(path), f)
             end
           end
 
-          def upload_directory(path)
-            path   = File.expand_path(path)
-            prefix = File.expand_path(File.join(path, ".."))
-            Dir.glob(File.join(path, "**/*")).sort.map do |file|
+          # @note it will skip subfolders
+          # @param path [String] the target directory to be uploaded
+          # @param recurse [Boolean] deepen in the folder structure? (`false`: default)
+          # @return [Array<String>] S3 paths to all the uploaded files of `path` directory
+          def upload_directory(path, recurse: false)
+            path      = File.expand_path(path)
+            prefix    = File.expand_path(File.join(path, ".."))
+            wildcard  = recurse ? "**/*" : "*"
+            Dir.glob(File.join(path, wildcard)).sort.map do |file|
               next unless File.file?(file) # Skip directories
               key = file.sub(prefix,"").gsub(/\\/,"/").sub(/^\/+/,"")
 
@@ -43,11 +56,15 @@ module Eco
             end.compact
           end
 
-          def path_to_link(path)
+          # @param path [String] a full path to a S3 object
+          # @return [String] `link` to the S3 object on console
+          def link(path)
             unless path.is_a?(Enumerable)
-             return "https://s3.console.aws.amazon.com/s3/object/#{path.sub("s3://","")}?region=#{fetch_region}&tab=overview"
+              return nil unless path.is_a?(String)
+              return "https://s3.console.aws.amazon.com/s3/object/#{path.sub("s3://","")}?region=#{fetch_region}&tab=overview"
+             return link
            end
-           path.map {|pth| path_to_link(pth)}
+           path.map {|pth| link(pth)}
           end
 
           private

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

@@ -7,5 +7,6 @@ module Eco
   end
 end
 
+require_relative 'version_patches/exception'
 require_relative 'version_patches/hash'
 require_relative 'version_patches/ecoportal_api'

data/lib/eco/api/common/version_patches/exception.rb

@@ -0,0 +1,8 @@
+class ::Exception
+  def patch_full_message
+    msg = []
+    msg << "#{backtrace.shift} #{message} (#{self.class.to_s})"
+    backtrace.each {|bt| msg << "#{" "*8}from #{bt}"}
+    msg.join("\n")
+  end
+end

data/lib/eco/api/session.rb

@@ -201,10 +201,14 @@ module Eco
         job_groups.launch(simulate: simulate)
       end
 
+      def summary
+        job_groups.summary
+      end
+
       # Sends an email
       # @see Eco::API::Common::Session::Mailer#mail
-      def mail_to(**kargs)
-        mail.mail(**kargs)
+      def mail(**kargs)
+        mailer.mail(**kargs)
       end
 
       # Uploads content into a file, a file or a directory to S3
@@ -214,17 +218,23 @@ module Eco
       # @param content [String] content to be uploaded (requires `file`)
       # @param file [String] name of the file to be uploaded
       # @param directory [String] name of source directory to be uploaded
-      # @return [String, Array<String>] paths to S3
-      def s3upload(content: nil, file: nil, directory: nil)
-        if content && file
-          s3uploader.upload(file, content)
+      # @param recurse [Boolean] used with `directory`: deepen in the folder structure? (`false`: default)
+      # @param link [Boolean] **return** _link(s)_ (`true`) or _path(s)_ (`false`: default)
+      # @return [String, Array<String>] either paths to S3 objects if `link` is `false`, or _link_ otherwise
+      def s3upload(content: nil, file: nil, directory: nil, recurse: false, link: false)
+        if content == :target
+          path = self.do.s3upload_targets
+        elsif content && file
+          path = s3uploader.upload(file, content)
         elsif file
-          s3uploader.upload_file(file)
+          path = s3uploader.upload_file(file)
         elsif directory
-          s3uploader.upload_directory(directory)
+          path = s3uploader.upload_directory(directory, recurse: recurse)
         else
           logger.error("To use Session.s3upload, you must specify either directory, file or content and file name")
         end
+        return path unless link
+        s3uploader.link(path)
       end
 
       private

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

@@ -167,8 +167,6 @@ module Eco
               iteration += 1
               done += slice.length
             end # next slice
-
-            status.errors.print unless silent
           end
         end
 

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

@@ -38,13 +38,13 @@ module Eco
             status.logger
           end
 
-          # Was there any **error** as a result of this batch?
+          # Was there any _Sever_ (reply) **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.
+          # Input entries that got **error** response from 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`
@@ -63,7 +63,7 @@ module Eco
                 raise msg
               end
 
-              response.success? ? nil : query
+              response.success?? nil : query
             end.compact
           end
 
@@ -117,10 +117,18 @@ module Eco
             end
           end
 
+          def message
+            msgs = strs
+            if msgs.length > 0
+              "There were #{msgs.length} errors:\n" + msgs.join("\n")
+            else
+              "There were no errors for the current batch '#{method}'!! ;)"
+            end
+          end
+
           def print
             msgs = strs
             if msgs.length > 0
-              logger.info()
               logger.error("There were #{msgs.length} errors:\n" + msgs.join("\n"))
             else
               logger.info("There were no errors for the current batch '#{method}'!! ;)")

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

@@ -34,7 +34,12 @@ module Eco
             job.options
           end
 
-          # Slightly modifies the behaviour of `as_update`, so schema detail fields show the `alt_id`
+          # @see Eco::API::Session::Batch::Job#requests
+          def job_requests
+            job.requests
+          end
+
+          # Slightly modifies the behaviour of `Ecoportal::API::Common::BaseModel#as_update`, so schema details fields show the `alt_id`
           # @note for better feedback
           # @param entry [Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
           def as_update(entry)
@@ -63,32 +68,43 @@ module Eco
             hash || {}
           end
 
-          def request_stats(data)
-            @request_stats ||= Eco::API::Session::Batch::RequestStats.new(type: type, requests: data)
+          # @note if `requests` is not provided, it uses the last requests of the parent `Batch::Job` `job`
+          # @param requests [Enumerable<Hash>] raw requests as they would be sent to the _Server_
+          # @return [Eco::API::Session::Batch::RequestStats] the stats object of the current requests
+          def request_stats(requests = nil)
+            requests ||= job.requests
+            return @request_stats if @request_stats && requests == job.requests
+            @request_stats ||= Eco::API::Session::Batch::RequestStats.new(type: type, requests: requests)
           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}"
+          # Generates the lines of feedback of the current requests
+          # @note if `requests` is not provided, it uses the last requests of the parent `Batch::Job` `job`
+          # @param requests [Enumerable<Hash>] raw requests as they would be sent to the _Server_
+          # @param max_charts [Integer] the max number of characters for the current feedback message
+          # @param only_stats [Boolean] whether or not should only include a brief summary of stats
+          # @return [String] the feedback message
+          def generate(requests = nil, max_chars: 800, only_stats: false)
+            requests ||= job.requests
+            [].tap do |msg|
+              if !requests || !requests.is_a?(Enumerable) || requests.empty?
+                msg << "#{"*" * 20} Nothing for #{signature} so far :)  #{"*" * 20}"
+              else
+                header = "#{"*"*20}  #{signature} - Feedback Sample #{"*"*20}"
+                msg << header unless only_stats
+                unless only_stats
+                  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
+                  msg << "#{sample.slice(0, sample_length).pretty_inspect}"
+                end
+                msg << "#{"+"*5}  STATS  (job '#{name}')  +++  #{type.to_s.upcase} length: #{requests.length}  #{"+"*5}"
+                msg << "#{request_stats(requests).message}"
+                msg << "*" * header.length unless only_stats
               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.join("\n")
           end
 
           private

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

@@ -66,16 +66,6 @@ module Eco
             usecase?? usecase.options : {}
           end
 
-          def match?(type:, sets:)
-            sets = [sets].flatten
-            type == self.type && (sets.order == self.sets.order)
-          end
-
-          # @return [Boolean] has been this `batch job` launched?
-          def pending?
-            @pending
-          end
-
           # Adds an entry(ies) to the job queue.
           # @param entry [Person, Enumberable<Person>] the person(s) we want to update, carrying the changes to be done.
           # @param unique [Boolean] specifies if repeated entries should be avoided in the queue.
@@ -97,6 +87,35 @@ module Eco
             end
           end
 
+          #def match?(type:, sets:)
+          #  sets = [sets].flatten
+          #  type == self.type && (sets.order == self.sets.order)
+          #end
+
+          # @return [Boolean] has been this `batch job` launched?
+          def pending?
+            @pending
+          end
+
+          # @note it requires launch to be firstly invoked
+          # @raise [Exception] if 'launch' has not firstly invoked
+          # @return [Enumbrable<Hash>] the last requests that the queue will generate
+          def requests
+            raise "Method missuse. Firstly 'launch' should be invoked" unless instance_variable_defined?(:@requests)
+            @requests
+          end
+
+          # @see Eco::API::Session::Batch::Feedback#request_stats
+          def request_stats(requests = nil)
+            feedback.request_stats(requests || self.requests)
+          end
+
+          # @see Eco::API::Session::Batch::Status#errors?
+          # @return [Boolean] `true` if there were Server errors, `false` otherwise
+          def errors?
+            status && status.errors?
+          end
+
           # Helper/shortcut to obtain a people object out of `input`
           # @note if `input` is not provided, it will use `queue`
           # @return [Eco::API::Organization::People]
@@ -105,36 +124,71 @@ module Eco
           end
 
           # Processes the `queue` and, unless `simulate` is `true`, launches against the server:
-          #   1. if the entries of `queue` got pending _callbacks_ (delayed changes), it processes them
-          #   2. unless type == `:create`: if there's a defined `api_excluded` _callback_ it calls it (see `Eco::API::Session::Config::People#api_excluded`)
-          #   3. transforms the result to a `Eco::API::Organization::People` object
-          #   4. if there are `api policies` defined, it passes the entries through them in order (see `Eco::API::Session::Config#policies`)
-          #   5. at this point all the transformations have taken place...
-          #   6. only include the entries that, after all above, still hold pending changes (`!as_update.empty?`) to be launched as update
-          #   7. if we are **not** in `dry-run` (or `simulate`), launch the batch request against the server (see `Eco::API::Session::Batch#launch`)
-          #   8. next, it links the resulting batch `status` to this `Batch::Job` (see `Eco::API::Session::Batch::Status`)
-          #   9. the post launch kicks in, and for success requests, it consolidates the associated entries (see `Ecoportal::API::V1::Person#consolidate!`)
-          #  10. launches specific error handlers, if there were **errors** from the Server as a result of the `batch.launch`, and there are `Error::Handlers` defined
-          #  11. if we are **not** in `dry-run` (or `simulate`), it backs up the raw queries launched to the Server
+          #   1. pre_processes the queue obtaining the `requests`:
+          #     - if the entries of `queue` got pending _callbacks_ (delayed changes), it processes them
+          #     - unless type == `:create`: if there's a defined `api_excluded` _callback_ it calls it (see `Eco::API::Session::Config::People#api_excluded`)
+          #     - transforms the result to a `Eco::API::Organization::People` object
+          #     - if there are `api policies` defined, it passes the entries through them in order (see `Eco::API::Session::Config#policies`)
+          #       - this step is **skipped** if the option `-skip-api-policies` was used in the command line
+          #     - at this point all the transformations have taken place...
+          #     - only include the entries that, after all above, still hold pending changes (`!as_update.empty?`) to be launched as update
+          #   2. pre launch checks against the `requests`:
+          #     - it generates `stats` (`Eco::API::Session::Batch::RequestStats`) out of the requests
+          #     - if there is a batch policy declared for the current job `type`, it checks compliance against `stats` (`Eco::API::Session::Batch::Policies`),
+          #       - a non-compliant batch will stop the current session by raising an `Exception`
+          #       - this setp is **skipped** if the option `-skip-batch-policy` was used in the command line
+          #   3. if we are **not** in `dry-run` (or `simulate`), it:
+          #     - backs up the raw queries (`requests`) launched to the Server, if we are **not** in `dry-run` (or `simulate`)
+          #     - **launches the batch** request against the _Server_ (see `Eco::API::Session::Batch#launch`)
+          #     - links the resulting batch `status` to this `Batch::Job` (see `Eco::API::Session::Batch::Status`)
+          #     - prints any `errors` replied by the _Server_
+          #   4. the post launch kicks in, and:
+          #     - for success requests, it consolidates the associated entries (see `Ecoportal::API::V1::Person#consolidate!`)
+          #     - launches specific error handlers, if there were **errors** from the Server as a result of the `batch.launch`, and there are `Error::Handlers` defined
+          # @return [Eco::API::Session::Batch::Status]
           def launch(simulate: false)
-            pqueue   = processed_queue
-            requests = pqueue.map {|e| as_update(e)}
+            pqueue    = processed_queue
+            @requests = pqueue.map {|e| as_update(e)}
 
             pre_checks(requests, simulate: simulate)
 
-            if !simulate
+            unless simulate
               if pqueue.length > 0
                 backup_update(requests)
-                @status = session.batch.launch(pqueue, method: type)
-                @status.root = self
+                session.batch.launch(pqueue, method: type).tap do |job_status|
+                  @status     = job_status
+                  status.root = self
+                  status.errors.print
+                end
               end
             end
 
-            post_launch(queue: pqueue, simulate: simulate)
+            unless requests.empty?
+              logger.info("--- simulate mode (dry-run) --  job '#{name}' -- this would have launched #{type.to_s.upcase}") if simulate
+            end
 
-            logger.info("Simulate: this would have launched: '#{type}'") if simulate
+            post_launch(queue: pqueue, simulate: simulate)
             @pending = false
-            return @status
+            return status
+          end
+
+          # Provides a text summary of the current status
+          # @note if `launch` was not invoked, it specifies so
+          # @return [String] the summary
+          def summary
+            [].tap do |msg|
+              if pending?
+                msg << "PENDING - Batch #{type.to_s.upcase} - job '#{name}' - length: #{@queue.length}"
+              else
+                msg  << feedback.generate(requests, only_stats: true)
+                if batch_policy && !batch_policy.compliant?(request_stats)
+                  msg << "Batch Policy Uncompliance:"
+                  msg << batch_policy.uncompliance(request_stats)
+                end
+
+                msg << status.errors.message unless !status
+              end
+            end.join("\n")
           end
 
           private
@@ -178,28 +232,29 @@ module Eco
             msg        = feedback.generate(requests, max_chars: max_chars, only_stats: only_stats)
             logger.info(msg)
 
-            @request_stats = feedback.request_stats(requests)
-            if simulate && batch_policy && !batch_policy.compliant?(@request_stats)
+            # batch_policy
+            stats      = request_stats(requests)
+            if simulate && batch_policy && !batch_policy.compliant?(stats)
               logger.warn("Batch Policy Uncompliance: this and next batches will be aborted!")
-              logger.warn(batch_policy.uncompliance(@request_stats))
+              logger.warn(batch_policy.uncompliance(stats))
             elsif batch_policy
               # will throw an Exception if the policy request_stats is not compliant
-              batch_policy.validate!(@request_stats)
+              batch_policy.validate!(stats)
             end
           end
 
           def post_launch(queue: [], simulate: false)
-            if !simulate && @status
-              @status.queue.map do |entry|
-                if @status.success?(entry)
+            if !simulate && status
+              status.queue.map do |entry|
+                if status.success?(entry)
                   entry.consolidate! if entry.respond_to?(:consolidate!)
                 #else # do not entry.reset! (keep track on changes still)
                 end
               end
               # launch_error handlers
               handlers = session.config.error_handlers
-              if @status.errors.any? && !handlers.empty?
-                err_types = @status.errors.by_type
+              if status.errors.any? && !handlers.empty?
+                err_types = status.errors.by_type
                 handlers.each do |handler|
                   if entries = err_types[handler.name]
                     handler.launch(people: people(entries), session: session, options: options)

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

@@ -3,6 +3,7 @@ module Eco
     class Session
       class Batch
         class Jobs < API::Common::Session::BaseSession
+          include Enumerable
           attr_reader :name
 
           def initialize(e, name:)
@@ -16,6 +17,23 @@ module Eco
             @callbacks = {}
           end
 
+          def length
+            count
+          end
+
+          def empty?
+            count == 0
+          end
+
+          def each(params: {}, &block)
+            return to_enum(:each) unless block
+            items.each(&block)
+          end
+
+          def items
+            @jobs.values
+          end
+
           def [](name)
             @jobs[name]
           end
@@ -41,30 +59,48 @@ module Eco
           end
 
           def pending?
-            @jobs.keys.any? {|key| @jobs[key].pending?}
+            any? {|job| job.pending?}
           end
 
           def launch(simulate: false)
-            group_status = {}
-            @jobs.each do |name, job|
+            each do |job|
               if job.pending?
-                group_status[job] = job_status = job.launch(simulate: simulate)
-                callback = @callbacks[job]
+                status[job] = job_status = job.launch(simulate: simulate)
+                callback    = @callbacks[job]
                 callback.call(job, job_status) if callback
               end
             end
 
-            return group_status
+            return status
           end
 
           def find_jobs(type:)
-            @jobs.each_with_object([]) do |(k, jb), jbs|
-              if jb.type == type
-                jbs.push(jb)
+            each_with_object([]) do |job, jbs|
+              jbs.push(job) if job.type == type
+            end
+          end
+
+          def status
+            if block_given?
+              status.each do |job, job_status|
+                yield(job, job_status)
               end
+              self
+            else
+              @jobs_status ||= {}
             end
           end
 
+          def errors?
+            any? {|job| job.errors?}
+          end
+
+          def summary
+            [].tap do |msg|
+              map {|job| msg << job.summary}
+            end.join("\n")
+          end
+
         end
       end
     end

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

@@ -20,6 +20,8 @@ module Eco
             end
           end
 
+          include Enumerable
+
           def initialize(e)
             super(e)
             reset
@@ -31,6 +33,23 @@ module Eco
             @callbacks = {}
           end
 
+          def length
+            count
+          end
+
+          def empty?
+            count == 0
+          end
+
+          def each(params: {}, &block)
+            return to_enum(:each) unless block
+            items.each(&block)
+          end
+
+          def items
+            @groups.values
+          end
+
           def [](name)
             @groups[name]
           end
@@ -56,28 +75,48 @@ module Eco
           end
 
           def pending?
-            @groups.any? {|group| group.pending?}
+            any? {|group| group.pending?}
           end
 
           def launch(simulate: false)
-            groups_status = {}
-            @order.each.with_index do |group, idx|
+            @order.each_with_index do |group, idx|
               if group.pending?
-                groups_status[group] = group_status = group.launch(simulate: simulate)
+                status[group] = group_status = group.launch(simulate: simulate)
                 callback = @callbacks[group]
                 callback.call(group, group_status) if callback
                 self.class.counter(DELAY_BETWEEN_GROUPS) if !simulate && idx < @order.length - 1
               end
             end
-            return groups_status
+            return status
           end
 
           def find_jobs(type:)
-            @groups.each_with_object([]) do |(k, gr), jbs|
-              jbs.concat(gr.find_jobs(type: type))
+            each_with_object([]) do |group, jbs|
+              jbs.concat(group.find_jobs(type: type))
             end
           end
 
+          def status
+            if block_given?
+              status.each do |group, group_status|
+                yield(group, group_status)
+              end
+              self
+            else
+              @groups_status ||= {}
+            end
+          end
+
+          def errors?
+            any? {|group| group.errors?}
+          end
+
+          def summary
+            [].tap do |msg|
+              map {|group| msg << group.summary}
+            end.join("\n")
+          end
+
         end
       end
     end

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

@@ -72,6 +72,12 @@ module Eco
             @errors ||= Eco::API::Session::Batch::Errors.new(status: self)
           end
 
+          # @see  Eco::API::Session::Batch::Errors#any?
+          # @return [Boolean] `true` if there were Server errors, `false` otherwise
+          def errors?
+            errors.any?
+          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`

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

@@ -4,6 +4,14 @@ module Eco
       class Config
         class Mailer < BaseConfig
 
+          def to=(value)
+            self["to"] = value
+          end
+
+          def to
+            self["to"]
+          end
+          
           def from=(value)
             self["from"] = value
           end

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

@@ -44,6 +44,14 @@ module Eco
             self["region"]
           end
 
+          def target_files=(value)
+            self["target_files"]       = [value].flatten
+          end
+
+          def target_files
+            self["target_files"]
+          end
+
           def target_directories=(value)
             self["target_directories"] = [value].flatten
           end

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

@@ -11,7 +11,8 @@ module Eco
             usecases:    nil,
             launch_jobs: nil,
             post_launch: {usecases: nil, launch_jobs: nil},
-            end:         nil
+            end:         nil,
+            close:       nil
           }
 
           class << self
@@ -67,21 +68,38 @@ module Eco
             @after    = []
           end
 
+          # Has this stage run yet?
+          # @note it does **not** include _sub-stages_ that run `before`
+          # @return [Boolean] `true` if it has run, `false` otherwise
           def pending?
             @pending
           end
 
+          # Do not run this stage!
           def skip!
             @skip    = true
             @pending = false
           end
 
+          # Has this stage been marked as to be skipped
+          # @return [Boolean] depends on this order:
+          #   - `true` if `skip!` was called
+          #   - `false` if the current _stage_ is `root?` (the top stage of the hierarchy)
+          #   - `true` if its parent task is to be skipped
           def skip?
             return @skip if instance_variable_defined?(:@skip)
             return false if root?
             @_parent.skip?
           end
 
+          # Used in **configuration** time **to configure** the _workflow_ of the target (sub)stage `key`
+          # @note if a `block` is provided it will `yield` the target stage immediately
+          # @param key [Symbol, nil] cases:
+          #   - if `key` is not provided, it targets the _current stage_
+          #   - if `key` is provided, it targets the specific _sub-stage_
+          # @yield [stage_workflow] further _workflow_ configuration `for` the target stage `key`
+          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def for(key = nil)
             raise "A block should be given." unless block_given?
             if !key
@@ -92,6 +110,16 @@ module Eco
             self
           end
 
+          # Used in **configuration** time **to define** the **behaviour**  the target (sub)stage `key`
+          # @note if a `block` is provided it will **not** `yield` the target stage immediately, but when the _workflow_ reaches the stage
+          # @param key [Symbol, nil] cases:
+          #   - if `key` is not provided, it targets the _current stage_
+          #   - if `key` is provided, it targets the specific _sub-stage_
+          # @yield [stage_workflow, io] the behaviour of the target stage `key` when the _workflow_ reaches it
+          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @yieldreturn io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def on(key = nil, &block)
             raise "A block should be given." unless block
             if !key
@@ -102,6 +130,30 @@ module Eco
             self
           end
 
+          # When there is an `Exception`, you might have defined some `callback` to do something with it (i.e. register, email)
+          # @yield [exception, io] the `callback` to do something with an `Exception` raised within this _workflow_ stage
+          # @yieldparam exception [Exception] the exception object that was raised
+          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @yieldreturn io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
+          def rescue(&block)
+            return @rescue unless block
+            @rescue = block
+            self
+          end
+
+          # Used in **configuration** time **add previous** `callbacks` **before** the `on` _callback_ of the (sub)stage `key` is actually `run`
+          # @note
+          #   - it will **not** `yield` it immediately, but when the _workflow_ reaches the target stage
+          #   - in this case, you can define multiple `callbacks`
+          # @param key [Symbol, nil] cases:
+          #   - if `key` is not provided, it targets the _current stage_
+          #   - if `key` is provided, it targets the specific _sub-stage_
+          # @yield [stage_workflow, io] one of the things to do **before** the `on` _callback_ of the (sub)stage `key` is actually `run`
+          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @yieldreturn io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def before(key = nil, &block)
             raise "A block should be given." unless block
             if !key
@@ -112,6 +164,18 @@ module Eco
             self
           end
 
+          # Used in **configuration** time **add previous** `callbacks` **after** the `on` _callback_ of the (sub)stage `key` is actually `run`
+          # @note
+          #   - it will **not** `yield` it immediately, but when the _workflow_ reaches the target stage
+          #   - in this case, you can define multiple `callbacks`
+          # @param key [Symbol, nil] cases:
+          #   - if `key` is not provided, it targets the _current stage_
+          #   - if `key` is provided, it targets the specific _sub-stage_
+          # @yield [stage_workflow, io] one of the things to do **after** the `on` _callback_ of the (sub)stage `key` is actually `run`
+          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @yieldreturn io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def after(key = nil, &block)
             raise "A block should be given." unless block
             if !key
@@ -122,29 +186,58 @@ module Eco
             self
           end
 
+          # Used in run time to **execute the workflow** of the (sub)stage `key`
+          # @note if a `block` is **not** provided:
+          #   - it will run the `before` _callbacks_ defined during the configuration time
+          #   - it will run the _workflow_ of any defined _**substage**_ of the `key` stage
+          #   - it will run the `on` _callback_ defined during the configuration time
+          #   - it will mark the stage as **not** `pending?`.
+          #   - it will run the `after` _callbacks_ defined during the configuration time
+          # @note if a `block` is provided:
+          #   - it will **not** run the workflow of the substages to `key` stage
+          #   - it will **not** run the `callback` for `on` defined during the configuration time
+          #   - it will rather `yield` the target stage after all the `before` _callbacks_ have been run
+          #   - aside of this, the rest will be the same as when the _block_ is provided (see previous note)
+          # @param key [Symbol, nil] cases:
+          #   - if `key` is not provided, it targets the _current stage_
+          #   - if `key` is provided, it targets the specific _sub-stage_
+          # @yield [stage_workflow, io] if a `block` is provided, see `note`
+          # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_ referred by `key`
+          # @yieldparam io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @yieldreturn io [Eco::API::UseCases::BaseIO] the input/output object carried througout all the _workflow_
+          # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
           def run(key = nil, io:, &block)
-            if key
-              io = stage(key).run(io: io, &block)
-            elsif pending?
-              @before.each {|c| io = c.call(self, io)}
-
-              unless skip?
-                io.session.logger.debug("(Workflow: #{path}) running now")
-                if block
-                  io = block.call(self, io)
-                else
-                  existing_stages.each {|stg| io = stg.run(io: io)}
-
-                  unless ready?
-                    msg = "(Workflow: #{path}) 'on' callback is not defined, nor block given"
-                    io.session.logger.debug(msg)
+            begin
+              if key
+                io = stage(key).run(io: io, &block)
+              elsif pending?
+                @before.each {|c| io = c.call(self, io)}
+
+                unless skip?
+                  io.session.logger.debug("(Workflow: #{path}) running now")
+                  if block
+                    io = block.call(self, io)
+                  else
+                    existing_stages.each {|stg| io = stg.run(io: io)}
+
+                    unless ready?
+                      msg = "(Workflow: #{path}) 'on' callback is not defined, nor block given"
+                      io.session.logger.debug(msg)
+                    end
+                    io = @on.call(self, io) if ready?
                   end
-                  io = @on.call(self, io) if ready?
+                  @pending = false
                 end
-                @pending = false
-              end
 
-              @after.each  {|c| io = c.call(self, io)}
+                @after.each  {|c| io = c.call(self, io)}
+              end
+            rescue SystemExit
+              exit
+            rescue Interrupt => i
+              raise i
+            rescue Exception => e
+              self.rescue.call(e, io) if self.rescue
+              raise e
             end
             io
           end

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

@@ -115,6 +115,17 @@ module Eco
           Eco::API::Organization::People.new(people)
         end
 
+        def s3upload_targets
+          [].tap do |paths|
+            session.config.s3storage.target_files.each_with_object(paths) do |file, arr|
+              arr.push(session.s3upload(file: file))
+            end
+            session.config.s3storage.target_directories.each_with_object(paths) do |folder, arr|
+              arr.concat(session.s3upload(directory: folder))
+            end
+          end
+        end
+
         private
 
         # MODIFIERS

data/lib/eco/cli.rb

@@ -20,13 +20,9 @@ module Eco
       end
     end
 
-    def workflow
-      @workflow ||= Eco::CLI::Workflow.new(cli: self)
-    end
-
     def run(session:)
       io = Eco::API::UseCases::BaseIO.new(session: session, options: options)
-      
+      #session.workflow.run(io: io)
       session.workflow(io: io) do |wf, io|
         io = wf.run(:options, io: io)
         io = wf.run(:load, io: io)

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

@@ -2,6 +2,13 @@ ASSETS.cli.config do |config|
   ASSETS.config.workflow do |wf|
 
     io = nil
+    # default rescue
+    wf.rescue do |exception, io|
+      #io.session.logger.error(exception.patch_full_message)
+      wf.run(:close, io: io)
+      io
+    end
+
     wf.on(:options) do |wf_options, io|
       io = io.new(options:   config.options_set.process(io: io))
     end

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = "1.1.2"
+  VERSION = "1.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.3
 platform: ruby
 authors:
 - Oscar Segura
@@ -288,6 +288,7 @@ files:
 - lib/eco/api/common/version_patches/ecoportal_api/base_model.rb
 - lib/eco/api/common/version_patches/ecoportal_api/external_person.rb
 - lib/eco/api/common/version_patches/ecoportal_api/internal_person.rb
+- lib/eco/api/common/version_patches/exception.rb
 - lib/eco/api/common/version_patches/hash.rb
 - lib/eco/api/common/version_patches/hash/deep_merge.rb
 - lib/eco/api/eco_faker.rb