Review fixes

README.md

@@ -193,8 +193,7 @@ TODO: need to come up with an appropriate example.
 
 ## Examples
 
-You can run some examples at `examples/` folder:
-
+You can find examples of gem usage at `examples/` folder:
 ```
 ruby examples/download_and_move_file.rb
 ```

examples/download_and_move_file.rb

@@ -2,42 +2,62 @@
 
 require 'uber_task'
 require 'colorize'
+require 'tmpdir'
 
 require_relative 'download_file'
 require_relative 'move_file'
+require_relative 'failing_task'
+
+EXISTENT_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/README.md'
+NON_EXESTENT_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/NON_EXISTENT.md'
+NON_VITAL_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/NON_VITAL.md'
 
 module Examples
   class DownloadAndMoveFile
-    def self.run(source:, download_path:, move_path:)
-      UberTask.run('Download and move file', retry_count: 2) do
+    def self.run(uri:, download_path:, move_path:)
+      UberTask.run('Download and move file') do
         UberTask.on_success do
           UberTask.logger.info(
             'Top-level task was completed successfully!'.green,
           )
         end
 
-        UberTask.on_subtask_error do
-          UberTask.logger.info(
-            'Unexpected subtask error can be caught on top-level task ' \
-            'and an early return can be made, ' \
-            'isn\'t that cool!?'.underline,
-          )
-          return # Try to remove this line and see what happens!
-        end
+        UberTask.on_subtask_error do |_task, event, err|
+          case err
+          # Network errors occuring in subtasks are handled here in top-level
+          when OpenURI::HTTPError
+            UberTask.retry(reason: err, wait: 5)
+          # Subtasks can be skipped
+          when Examples::FailingTask::Error
+            UberTask.logger.info(
+              'Encountered expected error, skipping...'.yellow,
+            )
 
-        # Notice that we are passing `vital: true` option so that
-        # an early return can be made if task fails
-        begin
-          Examples::DownloadFile.run(
-            source: source,
-            to: download_path,
-            vital: true,
-          )
-        rescue StandardError => err
-          UberTask.logger.info "Failed to download file -- #{err.message}"
-          return
+            UberTask.skip
+          else
+            UberTask.logger.error(
+              "Encountered unexpected error - #{err.message}".red,
+            )
+            event.handled
+          end
         end
 
+        Examples::DownloadFile.run(
+          uri: NON_VITAL_FILE_URI,
+          to: download_path,
+          retry_count: 1,
+          vital: false, # execution won't stop when this task fails
+        )
+
+        Examples::FailingTask.run
+
+        Examples::DownloadFile.run(
+          uri: uri,
+          to: download_path,
+          retry_count: 3,
+          vital: true, # execution will stop if this task fails
+        )
+
         Examples::MoveFile.run(from: download_path, to: move_path)
       end
     end
@@ -46,35 +66,21 @@ def self.run(source:, download_path:, move_path:)
 
 if __FILE__ == $PROGRAM_NAME
   Dir.mktmpdir do |dir|
-    download_path = File.join(dir, 'test')
-    move_path = File.join(dir, 'new_path')
+    download_path = File.join(dir, 'download_path')
+    move_path = File.join(dir, 'move_path')
 
     puts '--- Running successfull case ---'
     Examples::DownloadAndMoveFile.run(
-      source: VALID_FILE_URI,
+      uri: EXISTENT_FILE_URI,
       download_path: download_path,
       move_path: move_path,
     )
 
     puts "\n--- Running case which fails to download file ---\n"
     Examples::DownloadAndMoveFile.run(
-      source: NON_EXESTENT_FILE_URI,
+      uri: NON_EXESTENT_FILE_URI,
       download_path: download_path,
       move_path: move_path,
     )
-
-    puts "\n--- Running case with invalid download path ---\n"
-    Examples::DownloadAndMoveFile.run(
-      source: VALID_FILE_URI,
-      download_path: '/invalid_path',
-      move_path: move_path,
-    )
-
-    puts "\n--- Running case with invalid move path ---\n"
-    Examples::DownloadAndMoveFile.run(
-      source: VALID_FILE_URI,
-      download_path: download_path,
-      move_path: '/invalid_path',
-    )
   end
 end

examples/download_file.rb

@@ -3,84 +3,35 @@
 require 'uber_task'
 require 'colorize'
 require 'open-uri'
-require 'tmpdir'
-
-VALID_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/README.md'
-NON_EXESTENT_FILE_URI = 'https://github.com/shakacode/uber_task/raw/main/NON_EXISTENT.md'
 
 module Examples
   class DownloadFile
-    def self.run(to:, source: VALID_FILE_URI, **task_options)
+    def self.run(uri:, to:, **task_options)
       UberTask.run(
         'Download file from external source',
-        default_retry_wait: 3,
-        retry_count: 5,
-        vital: false,
+        default_retry_wait: 5,
+        retry_count: 3,
         **task_options,
       ) do
-        UberTask.on_retry do
+        UberTask.on_success do
           UberTask.logger.info(
-            "Retrying to download file from #{source}...".yellow,
+            "Downloaded file #{uri} and saved it at #{to}".green,
           )
         end
 
-        UberTask.on_success do
+        UberTask.on_retry do
           UberTask.logger.info(
-            "Downloaded file #{source} and saved it at #{to}".green,
+            "Retrying to download file from #{uri}...".yellow,
           )
         end
 
-        save_external_file!(source: source, to: to)
+        save_external_file!(uri: uri, to: to)
       end
     end
 
-    def self.save_external_file!(source:, to:)
-      URI.parse(source).open { |io| File.write(to, io.read) }
-    rescue OpenURI::HTTPError => err
-      raise UberTask::RetryTask.new(reason: err.message)
+    def self.save_external_file!(uri:, to:)
+      URI.parse(uri).open { |io| File.write(to, io.read) }
     end
     private_class_method :save_external_file!
   end
 end
-
-if __FILE__ == $PROGRAM_NAME
-  Dir.mktmpdir do |dir|
-    filepath = File.join(dir, 'test')
-
-    puts '--- Running successfull case ---'
-    Examples::DownloadFile.run(source: VALID_FILE_URI, to: filepath)
-
-    puts "\n--- Running failing case with `vital: true`---\n"
-    begin
-      Examples::DownloadFile.run(
-        source: NON_EXESTENT_FILE_URI,
-        to: filepath,
-        vital: true,
-      )
-    rescue StandardError
-      UberTask.logger.info 'Error was raised'.red
-    end
-
-    puts "\n--- Running failing case with `vital: false`---\n"
-    Examples::DownloadFile.run(
-      source: NON_EXESTENT_FILE_URI,
-      to: filepath,
-      vital: false,
-    )
-    UberTask.logger.info 'Error wasn\'t raised'.green
-
-    puts "\n--- Running failing case with `retry_count: 1`---\n"
-    Examples::DownloadFile.run(
-      source: NON_EXESTENT_FILE_URI,
-      to: filepath,
-      retry_count: 1,
-    )
-
-    puts "\n--- Running failing case with `default_retry_wait: 0`---\n"
-    Examples::DownloadFile.run(
-      source: NON_EXESTENT_FILE_URI,
-      to: filepath,
-      default_retry_wait: 0,
-    )
-  end
-end

examples/failing_task.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'uber_task'
+
+module Examples
+  class FailingTask
+    Error = Class.new(StandardError)
+
+    def self.run(**task_options)
+      UberTask.run('Failing task', **task_options) do
+        raise Error, 'failed'
+      end
+    end
+  end
+end

examples/move_file.rb

@@ -2,17 +2,15 @@
 
 require 'uber_task'
 require 'colorize'
-require 'tmpdir'
 require 'fileutils'
 
 module Examples
   class MoveFile
     def self.run(from:, to:, **task_options)
       UberTask.run(
-        'Download file from external source',
+        'Move file',
         default_retry_wait: 1,
         retry_count: 3,
-        vital: false,
         **task_options,
       ) do
         UberTask.on_success do
@@ -31,54 +29,7 @@ def self.run(from:, to:, **task_options)
 
     def self.move_file!(from:, to:)
       FileUtils.mv(from, to)
-    rescue Errno::ENOENT => err
-      raise UberTask::RetryTask.new(reason: err.message)
     end
     private_class_method :move_file!
   end
 end
-
-if __FILE__ == $PROGRAM_NAME
-  Dir.mktmpdir do |dir|
-    File.open(File.join(dir, 'old_path'), 'w') do |file|
-      file.write('test')
-
-      puts '--- Running successfull case ---'
-      Examples::MoveFile.run(from: file.path, to: File.join(dir, 'new_path'))
-    end
-
-    ### Notice that task has `vital: true` so error is raised
-    puts "\n--- Running failing case with `vital: true`---\n"
-    begin
-      Examples::MoveFile.run(
-        from: 'invalid_path',
-        to: File.join(dir, 'new_path'),
-        vital: true,
-      )
-    rescue StandardError
-      UberTask.logger.info 'Error was raised'.red
-    end
-
-    ### Notice that task has `vital: false` so error isn't raised
-    puts "\n--- Running failing case with `vital: false`---\n"
-    Examples::MoveFile.run(
-      from: 'invalid_path',
-      to: File.join(dir, 'new_path'),
-      vital: false,
-    )
-
-    puts "\n--- Running failing case with `retry_count: 1`---\n"
-    Examples::MoveFile.run(
-      from: 'invalid_path',
-      to: File.join(dir, 'new_path'),
-      retry_count: 1,
-    )
-
-    puts "\n--- Running failing case with `default_retry_wait: 3`---\n"
-    Examples::MoveFile.run(
-      from: 'invalid_path',
-      to: File.join(dir, 'new_path'),
-      default_retry_wait: 3,
-    )
-  end
-end