ecoportal-api 0.10.5 → 0.10.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 31b8d7b7f90a351a2335c73140458010669a42bf19538f0ec8a65df565881374
-  data.tar.gz: 064e126df498599971d9c3ea999cba7b85eb303d944ea34738f17490c60c435b
+  metadata.gz: ae05088d3d0542b2200a614b0043d8580cd713cbfcf4fb473b17be4f1930aafe
+  data.tar.gz: 90259cfa1c993c457b2bcfcd57d343538c7bf4f3746b21c921eb1be3e92dc370
 SHA512:
-  metadata.gz: b9020a08208cdc1da174e9addb03bb81e5d484fccc461f45e739edaf32a5a998e1b8508f8fdf3663282733352de1e025f2c4486ebda68109d153c4c1c8326d6b
-  data.tar.gz: 2d4fa049b1cb31edcd28d783a50589922ce04560a2cab5e6a409abc7c3b21ffc807aad6a09a592013eb800b4e3c35e2ecc926d0f7c1e12a061df820e0dc1c37b
+  metadata.gz: '058bd304110936dc08ee37c77c081b65fc08b68a29f60ff74ead0798e0894100a26f6a85b60ce4d38c447d74707f78eec55a69755002ec10c6b36b98f4db8b67'
+  data.tar.gz: 7340fe5e7875a9a2b3aefda197927fbfe733299c0dc0494b3b09b59db24ae7bac80b135ea0fb9fd1d7b5abc1ed246a715e3f3b14ee5d26e45a8bef2f14017815

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.10.6] - 2024-10-xx
+## [0.10.7] - 2024-10-xx
 
 ### Added
 
@@ -10,6 +10,26 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+## [0.10.6] - 2024-10-28
+
+### Added
+
+- `Ecoportal::API::V1::Job::Status`
+  - **added** methods `started?`, `progressing?` and `progress_increase`
+- `Ecoportal::API::Errors::StartTimeOut` specificity on timeout error.
+
+### Changed
+
+- Refactored `Ecoportal::API::V1::Awaiter` into:
+  - `Awaiter::Timer`: account for last waited, and manage time outs
+  - `Awaiter::StatusFrequency`: next awaiting time
+
+### Fixed
+
+- `Portal::API::V1::Awaiter`
+  - `throughput` based on progress during last wait
+  - this helps to better detect non progressing jobs
+
 ## [0.10.5] - 2024-10-16
 
 ### Fixed

data/lib/ecoportal/api/errors/time_out.rb

@@ -3,6 +3,9 @@ module Ecoportal
     module Errors
       class TimeOut < Errors::Base
       end
+
+      class StartTimeOut < TimeOut
+      end
     end
   end
 end

data/lib/ecoportal/api/v1/job/awaiter/status_frequency.rb

@@ -0,0 +1,49 @@
+module Ecoportal
+  module API
+    class V1
+      class Job
+        class Awaiter
+          module StatusFrequency
+            include Common::Client::TimeOut
+
+            DELAY_STATUS_CHECK = 4
+            MIN_STATUS_CHECK   = 2
+
+            private
+
+            def status_checked?
+              @status_checked || false
+            end
+
+            def status_check_in(pending, timeout_in:)
+              # first check to be faster
+              unless status_checked?
+                @status_checked = true unless pending.zero? # <= increases job status requests!
+                return min_delay_status_check
+              end
+
+              return default_delay_status_check if around_min_throughput?
+
+              eta           = eta_for(pending, approach: :optimistic)
+              check_in_max  = [eta, timeout_in].min * 0.90
+
+              check_in_best = check_in_max / 2.0
+              default_5     = default_delay_status_check * 5
+
+              top_check     = [default_5, check_in_best].min.ceil
+              [top_check, min_delay_status_check].max
+            end
+
+            def default_delay_status_check
+              self.class::DELAY_STATUS_CHECK
+            end
+
+            def min_delay_status_check
+              self.class::MIN_STATUS_CHECK
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v1/job/awaiter/timer.rb

@@ -0,0 +1,158 @@
+module Ecoportal
+  module API
+    class V1
+      class Job
+        class Awaiter
+          TIMER_ARGS = %i[
+            total timeout
+            start last ldelay
+            status lstatus
+          ].freeze
+
+          Timer = Struct.new(*TIMER_ARGS) do
+            self::MAX_START_DELAY = 60
+
+            attr_reader :timestamp
+
+            def initialize(...)
+              @timestamp = Time.now
+              super
+              yield(self) if block_given?
+            end
+
+            alias_method :original_start, :start
+            # `start` time only counts from the moment that
+            # it already started to progress
+            def start
+              return timestamp unless lstatus&.started?
+
+              original_start || timestamp
+            end
+
+            alias_method :original_last, :last
+            def last
+              original_last || start
+            end
+
+            def new(**kargs, &block)
+              self.class.new(**new_kargs.merge(kargs), &block)
+            end
+
+            def job_id
+              status.id
+            end
+
+            def complete?
+              status.complete?(total)
+            end
+
+            def started?
+              status.started?
+            end
+
+            def pending
+              status.pending(total)
+            end
+
+            def progress
+              status.progress
+            end
+
+            def increased
+              status.progress_increase(lstatus)
+            end
+
+            def waited
+              timestamp - start
+            end
+
+            def lwaited
+              timestamp - last
+            end
+
+            def net_waited
+              last_delay = ldelay || 0
+              waited - (last_delay / 2)
+            end
+
+            def time_left
+              (timeout - waited).round(2)
+            end
+
+            def time_left_to_start
+              return max_start_delay if started?
+
+              (max_start_delay - waited).round(2)
+            end
+
+            def timeout_in
+              return time_left if started?
+
+              time_left_to_start
+            end
+
+            # timeout library is evil. So we make poor-man timeout.
+            # https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/
+            def timeout?
+              !time_left.positive?
+            end
+
+            def start_timeout?
+              return false if status.started?
+
+              !time_left_to_start.positive?
+            end
+
+            def on_timeout!(&block)
+              return start_timeout!(&block) if start_timeout?
+              return timeout!(&block)       if timeout?
+
+              false
+            end
+
+            def timeout!
+              return false unless timeout?
+
+              yield(self)
+
+              msg  = "Job '#{job_id}' not complete (size: #{total}).\n"
+              msg << "  Timed out after #{timeout} seconds.\n"
+              msg << "  Current status: #{status}"
+
+              raise API::Errors::TimeOut, msg
+            end
+
+            def start_timeout!
+              return false unless start_timeout?
+
+              yield(self)
+
+              msg  = "Job '#{job_id}' not started (size: #{total}).\n"
+              msg << "  Start timed out after #{max_start_delay} seconds.\n"
+              msg << "  Current status: #{status}"
+
+              raise API::Errors::StartTimeOut, msg
+            end
+
+            protected
+
+            def new_kargs
+              %i[total timeout start].each_with_object({}) do |key, kargs|
+                kargs[key] = send(key)
+              end.tap do |kargs|
+                kargs[:start]   = timestamp
+                kargs[:lstatus] = status
+              end
+            end
+
+            private
+
+            def max_start_delay
+              self.class::MAX_START_DELAY
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v1/job/awaiter.rb

@@ -1,64 +1,77 @@
+require_relative 'awaiter/timer'
+require_relative 'awaiter/status_frequency'
+
 module Ecoportal
   module API
     class V1
       class Job
         class Awaiter
           include Common::Client::TimeOut
-
-          DELAY_STATUS_CHECK = 4
-          MIN_STATUS_CHECK   = 2
+          include StatusFrequency
 
           TIMEOUT_APPROACH   = :min # :conservative # adaptative timeout
           TIMEOUT_FALLBACK   = :min
 
-          attr_reader :job, :job_id, :total
-          attr_accessor :timeout_approach
+          attr_reader :job_api, :job_id, :total
 
-          def initialize(job, job_id:, total:)
-            @job     = job
+          def initialize(job_api, job_id:, total:)
+            @job_api = job_api
             @job_id  = job_id
             @total   = total
-            @checked = false
-            self.timeout_approach = self.class::TIMEOUT_APPROACH
+          end
+
+          attr_writer :timeout_approach
+
+          def timeout_approach
+            @timeout_approach ||= self.class::TIMEOUT_APPROACH
           end
 
           # Allows to preserve the learned throughput
           def new(**kargs)
-            self.class.new(job, **kargs).tap do |out|
-              out.throughput = throughput
+            self.class.new(job_api, **kargs).tap do |out|
+              out.throughput       = throughput
+              out.timeout_approach = timeout_approach
             end
           end
 
           def await_completion! # rubocop:disable Metrics/AbcSize
-            max_timeout = timeout_for(total, approach: timeout_approach)
+            timeout = timeout_for(total, approach: timeout_approach)
+
+            first = 1
+            timer = Timer.new(
+              total:   total,
+              timeout: timeout,
+              ldelay:  first
+            )
 
-            # timeout library is evil. So we make poor-man timeout.
-            # https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/
-            before = Time.now
             delay_status_check = nil
 
             loop do
-              status  = job.status(job_id)
-              done    = status.progress
-              waited  = Time.now - before
+              sleep(first.tap {first = nil}) if first
 
-              adapted = waited
-              adapted = waited - (delay_status_check / 2) if delay_status_check
-              ratio   = throughput!(adapted, count: done)
+              timer = timer.new(
+                status: job_api.status(job_id),
+                ldelay: delay_status_check
+              )
 
-              break status if status.complete?(total)
+              # ratio = throughput!(timer.net_waited, count: timer.progress)
+              ratio = throughput!(timer.lwaited, count: timer.increased)
 
-              pending = status.pending(total)
-              left    = max_timeout - waited
+              break timer.status if timer.complete?
 
-              timeout!(status, timeout: max_timeout) unless left.positive?
+              timer.on_timeout! do
+                @timeout_approach = self.class::TIMEOUT_FALLBACK
+              end
 
-              delay_status_check = status_check_in(pending, timeout_in: left)
+              delay_status_check = status_check_in(
+                timer.pending,
+                timeout_in: timer.timeout_in
+              )
 
               msg  = " ... Awaiting #{delay_status_check} s. -- "
-              msg << " TimeOut: #{left.round(2)} s. "
+              msg << " TimeOut: #{timer.time_left} s. "
               msg << "(job '#{job_id}') "
-              msg << "Done: #{done} (est. #{ratio} rec/s) "
+              msg << "Done: #{timer.progress} (est. #{ratio.round(2)} rec/s) "
               msg << "     \r"
 
               print msg
@@ -67,48 +80,6 @@ module Ecoportal
               sleep(delay_status_check)
             end
           end
-
-          private
-
-          def timeout!(status, timeout:)
-            self.timeout_approach = self.class::TIMEOUT_FALLBACK
-
-            msg  = "Job '#{job_id}' not complete (size: #{total}).\n"
-            msg << "  Timed out after #{timeout} seconds.\n"
-            msg << "  Current status: #{status}"
-
-            raise API::Errors::TimeOut, msg
-          end
-
-          def checked?
-            @checked
-          end
-
-          def status_check_in(pending, timeout_in:)
-            unless checked?
-              @checked = true
-              return min_delay_status_check
-            end
-
-            return default_delay_status_check if around_min_throughput?
-
-            eta           = eta_for(pending, approach: :optimistic)
-            check_in_max  = [eta, timeout_in].min * 0.90
-
-            check_in_best = check_in_max / 2.0
-            default_5     = default_delay_status_check * 5
-
-            top_check     = [default_5, check_in_best].min.ceil
-            [top_check, min_delay_status_check].max
-          end
-
-          def default_delay_status_check
-            self.class::DELAY_STATUS_CHECK
-          end
-
-          def min_delay_status_check
-            self.class::MIN_STATUS_CHECK
-          end
         end
       end
     end

data/lib/ecoportal/api/v1/job/status.rb

@@ -9,7 +9,15 @@ module Ecoportal
             @id       = id
             @complete = complete
             @errored  = errored
-            @progress = progress
+            @progress = progress || 0
+          end
+
+          def started?
+            progress.positive?
+          end
+
+          def progressing?(prev)
+            progress_increase(prev).positive?
           end
 
           def complete?(total = nil)
@@ -25,6 +33,12 @@ module Ecoportal
             total - progress
           end
 
+          def progress_increase(prev = 0)
+            prev   = prev.progress if prev.is_a?(self.class)
+            prev ||= 0
+            progress - prev
+          end
+
           def errored?
             @errored
           end

data/lib/ecoportal/api/version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    VERSION = '0.10.5'.freeze
+    VERSION = '0.10.6'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api
 version: !ruby/object:Gem::Version
-  version: 0.10.5
+  version: 0.10.6
 platform: ruby
 authors:
 - Tapio Saarinen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-10-15 00:00:00.000000000 Z
+date: 2024-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -258,6 +258,8 @@ files:
 - lib/ecoportal/api/v1.rb
 - lib/ecoportal/api/v1/job.rb
 - lib/ecoportal/api/v1/job/awaiter.rb
+- lib/ecoportal/api/v1/job/awaiter/status_frequency.rb
+- lib/ecoportal/api/v1/job/awaiter/timer.rb
 - lib/ecoportal/api/v1/job/status.rb
 - lib/ecoportal/api/v1/people.rb
 - lib/ecoportal/api/v1/person.rb