ecoportal-api 0.10.3 → 0.10.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dde26458f8ba991809f2218f6a4594101350f861a811d1bf4c6b508b2194ef67
-  data.tar.gz: f9bd67ceaea38ec6ea82d9a53ae0651c36fb7f74e417b37029acd7d72fd00d97
+  metadata.gz: 31b8d7b7f90a351a2335c73140458010669a42bf19538f0ec8a65df565881374
+  data.tar.gz: 064e126df498599971d9c3ea999cba7b85eb303d944ea34738f17490c60c435b
 SHA512:
-  metadata.gz: '09dd4b2cde2bd8f6c6689433c7472fedb6110d076603afcd8edc39f5275aed0296470e57900eaceb335dc875f31554d515925c6b1eae060786a055ac706f6a66'
-  data.tar.gz: 3363216e775f38601146617ee80abab13625163c46739f536d77f94c17247fcce139331cad8af02b4cbcc0848a352211a34c476d0d766082e18b5d4b222f43cf
+  metadata.gz: b9020a08208cdc1da174e9addb03bb81e5d484fccc461f45e739edaf32a5a998e1b8508f8fdf3663282733352de1e025f2c4486ebda68109d153c4c1c8326d6b
+  data.tar.gz: 2d4fa049b1cb31edcd28d783a50589922ce04560a2cab5e6a409abc7c3b21ffc807aad6a09a592013eb800b4e3c35e2ecc926d0f7c1e12a061df820e0dc1c37b

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.10.4] - 2024-10-xx
+## [0.10.6] - 2024-10-xx
 
 ### Added
 
@@ -10,6 +10,28 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+## [0.10.5] - 2024-10-16
+
+### Fixed
+
+- `Ecoportal::API::V1::Job::Awaiter`
+  - Made it calculate TimeOut always on `0.2` throughput
+
+## [0.10.4] - 2024-10-15
+
+### Added
+
+- `Ecoportal::API::Common::Client::RateThrottling`
+  - See: <https://github.com/zombocom/rate_throttle_client?tab=readme-ov-file#ratethrottleclient>
+  - Add adapter to the RateLimit, may it be present.
+  - **Default:** `:proportional_decrease`
+
+### Changed
+
+- `Ecoportal::API::Common::Client::TimeOut`
+  - Const `MIN_SIZE` changed from `10` to `5` to speed up small requests.
+- Full revamp of `Job` endpoint
+
 ## [0.10.3] - 2024-10-01
 
 ### Changed

data/ecoportal-api.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
     'oscar@ecoportal.co.nz'
   ]
 
-  spec.summary       = %q{A collection of helpers for interacting with the ecoPortal MS's various APIs}
+  spec.summary       = "A collection of helpers for interacting with the ecoPortal MS's various APIs"
   spec.homepage      = "https://www.ecoportal.com"
   spec.licenses      = %w[MIT]
 
@@ -28,17 +28,18 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'pry'      , '~> 0.14'
+  spec.add_development_dependency 'pry',       '~> 0.14'
   spec.add_development_dependency 'rake',      '>= 13.0.3', '< 14'
   spec.add_development_dependency 'redcarpet', '>= 3.6.0',  '< 4'
   spec.add_development_dependency 'rspec',     '>= 3.12.0', '< 4'
   spec.add_development_dependency 'rubocop',   '~> 1'
   spec.add_development_dependency 'rubocop-rake', '~> 0'
-  spec.add_development_dependency 'yard',      '~> 0.9'
+  spec.add_development_dependency 'yard',         '~> 0.9'
 
   spec.add_dependency 'dotenv',        '~> 3'
   spec.add_dependency 'elastic-apm',   '>= 4.7',   "< 5"
   spec.add_dependency 'http',          '~> 5.1',   "< 6"
+  spec.add_dependency 'rate_throttle_client', '~> 0.1'
 end
 
 # rubocop:enable Gemspec/DevelopmentDependencies

data/lib/ecoportal/api/common/client/rate_throttling.rb

@@ -0,0 +1,43 @@
+require 'rate_throttle_client'
+
+module Ecoportal
+  module API
+    module Common
+      class Client
+        module RateThrottling
+          private
+
+          def rate_throttling(strategy: nil, &block)
+            throttle(strategy).call(&block)
+          end
+
+          def throttle(strategy = nil)
+            @throttle ||= {}
+
+            return @throttle[strategy] if @throttle.key?(strategy)
+
+            @throttle[strategy] = throttle_class(strategy).new
+          end
+
+          def throttle_class(strategy = default_throttle_strategy)
+            case strategy
+            when :gradual_decrease
+              RateThrottleClient::ExponentialIncreaseGradualDecrease
+            when :proportional_decrease
+              RateThrottleClient::ExponentialIncreaseProportionalDecrease
+            when :remaining_decrease
+              # requires RateLimit-Remaining in the response
+              RateThrottleClient::ExponentialIncreaseProportionalRemainingDecrease
+            else # :backoff
+              RateThrottleClient::ExponentialBackoff
+            end
+          end
+
+          def default_throttle_strategy
+            :proportional_decrease
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/client/throughput/stats.rb

@@ -0,0 +1,119 @@
+module Ecoportal
+  module API
+    module Common
+      class Client
+        class Throughput
+          class Stats
+            DEFAULT_SD = 1.0
+            DUMMY_DIFF = 0.001
+            CONFIDENCE = {
+              _90:  1645,
+              _95:  1.96,
+              _98:  2.326,
+              _99:  2.576,
+              _995: 2.807
+            }.freeze
+            DEFAULT_CONFI = :_99
+
+            attr_reader :average, :standard_deviation, :count
+            attr_reader :default_margin_error
+
+            def initialize(average, margin: DEFAULT_CONFI)
+              @average              = average.to_f
+              @standard_deviation   = default_sd
+              @count                = 1
+              @default_margin_error = margin || DEFAULT_CONFI
+            end
+
+            def empty?
+              count <= 1
+            end
+
+            def max(value = default_margin_error)
+              confidence_interval(value).max
+            end
+
+            def min(value = default_margin_error)
+              confidence_interval(value).min
+            end
+
+            def record!(value)
+              if count == 1
+                @average = value
+              else
+                @average = ((average * count) + value) / (count + 1)
+              end
+
+              @standard_deviation = new_sd(value)
+              @count += 1
+              average
+            end
+
+            alias_method :<<, :record!
+
+            # @return [Interval]
+            def confidence_interval(value = default_margin_error)
+              me   = margin_error(value)
+              pair = [me * -1, me].map {|err| average + err}
+              (pair.first..pair.last)
+            end
+
+            protected
+
+            def margin_error(value = default_margin_error)
+              to_z(value) * (standard_deviation / Math.sqrt(count))
+            end
+
+            private
+
+            def new_sd(value)
+              pre_sum = (sd_per_item ** 2) * count
+              cur_sum = pre_sum + ((value - average) ** 2)
+              Math.sqrt(cur_sum / count)
+            end
+
+            #         (diff^2) * N
+            #  SD^2 = -------------
+            #             N - 1
+            #
+            #  (diff^2) * N = SD^2 * (N - 1)
+            #
+            #            --------------
+            #  diff = 2 /  SD^2 * (N - 1)
+            #          V   -------------
+            #                 N
+            def sd_per_item
+              base = (sd_for_calcs ** 2) * (count - 1) / count.to_f
+              Math.sqrt(base)
+            end
+
+            def sd_for_calcs
+              return standard_deviation unless empty?
+
+              standard_deviation + dummy_diff
+            end
+
+            def dummy_diff
+              self.class::DUMMY_DIFF
+            end
+
+            def to_z(value)
+              value = default_margin_error unless confidences.key?(value)
+
+              confidences[value]
+            end
+
+            def confidences
+              self.class::CONFIDENCE
+            end
+
+            def default_sd
+              default = self.class::DEFAULT_SD
+              default * average / 10
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/client/throughput.rb

@@ -0,0 +1,93 @@
+require 'ecoportal/api/common/client/throughput/stats'
+
+module Ecoportal
+  module API
+    module Common
+      class Client
+        class Throughput
+          MIN_THROUGHPUT = 0.2  # records per second
+          MAX_THROUGHPUT = 12
+
+          attr_reader :default_approach
+
+          def initialize(approach = :conservative)
+            @default_approach = approach || :conservative
+          end
+
+          def eta_for(count, approach: default_approach, ratio: self.ratio(approach))
+            to_seconds(count, ratio: ratio)
+          end
+
+          def ratio(approach = default_approach)
+            case approach
+            when :min
+              min_throughput
+            when :last
+              @last_throughput || stats.average
+            when :average
+              stats.average
+            when :optimistic
+              [stats.max, max_throughput].min
+            else # :conservative
+              [stats.min, min_throughput].max
+            end.then do |relation|
+              next relation if relation < max_throughput
+
+              max_throughput
+            end
+          end
+
+          def record!(secs = nil, count: nil)
+            return ratio if secs.to_f.zero? || count.to_i.zero?
+
+            (count / secs.to_f).round(3).tap do |last|
+              stats << @last_throughput = last
+            end
+          end
+
+          # Keeps track of the current processing speed
+          # @note it needs to be called in specific spots
+          def push(value)
+            stats.record!(value)
+          end
+          alias_method :<<, :push
+
+          def around_min_throughput?(margin)
+            rate = ratio
+            return true if rate == min_throughput
+
+            right_under = min_throughput * (1 - margin)
+            return false if rate < right_under
+
+            right_above = min_throughput * (1 + margin)
+            return false if rate > right_above
+
+            true
+          end
+
+          protected
+
+          def stats
+            @stats ||= Stats.new(min_throughput)
+          end
+
+          def to_seconds(count, ratio: min_throughput)
+            return 1 unless count
+
+            (count.ceil / ratio.to_f).ceil
+          end
+
+          private
+
+          def min_throughput
+            self.class::MIN_THROUGHPUT
+          end
+
+          def max_throughput
+            self.class::MAX_THROUGHPUT
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/client/time_out.rb

@@ -3,23 +3,65 @@ module Ecoportal
     module Common
       class Client
         module TimeOut
-          MIN_THROUGHPUT = 0.2 # people per second
-          MIN_SIZE       = 10
+          TIMEOUT_MARGIN = 0.15 # adaptative timeout with margin
+          MIN_SIZE       = 5    # requests
+
+          protected
+
+          attr_writer :throughput
+
+          # Keeps track of the current processing speed
+          # @note it needs to be called in specific spots
+          def throughput!(secs = nil, count: nil)
+            throughput.record!(secs, count: count)
+          end
+
+          def throughput
+            @throughput ||= Throughput.new
+          end
+
+          def to_count(value)
+            value ||= 0
+            return min_size if value.positive? && value < min_size
+            return value    if value.positive?
+
+            1
+          end
 
           private
 
-          def min_throughput
-            self.class::MIN_THROUGHPUT
+          def eta_for(count, approach: :conservative)
+            kargs = {}.tap do |params|
+              next params.merge!({ratio: rectified_throughput}) if approach == :conservative
+
+              params.merge!({approach: approach})
+            end
+
+            throughput.eta_for(to_count(count), **kargs)
           end
 
-          def min_size
-            self.class::MIN_SIZE
+          def timeout_for(count, waited: 0, max_wait: nil, approach: :conservative)
+            (waited + eta_for(count, approach: approach)).then do |time|
+              next time unless max_wait
+
+              [max_wait, time].min
+            end
           end
 
-          def timeout_for(count)
-            count = 1        unless count&.positive?
-            count = min_size if count < min_size
-            (count.ceil / min_throughput).ceil
+          def rectified_throughput
+            throughput.ratio * (1 - timeout_margin)
+          end
+
+          def around_min_throughput?
+            throughput.around_min_throughput?(timeout_margin)
+          end
+
+          def timeout_margin
+            self.class::TIMEOUT_MARGIN
+          end
+
+          def min_size
+            self.class::MIN_SIZE
           end
         end
       end

data/lib/ecoportal/api/common/client.rb

@@ -2,6 +2,8 @@ require 'http'
 
 require 'ecoportal/api/common/client/error'
 require 'ecoportal/api/common/client/elastic_apm_integration'
+require 'ecoportal/api/common/client/rate_throttling'
+require 'ecoportal/api/common/client/throughput'
 require 'ecoportal/api/common/client/time_out'
 require 'ecoportal/api/common/client/with_retry'
 
@@ -23,6 +25,9 @@ module Ecoportal
       # @attr_reader host [String] the remote target server.
       class Client
         include WithRetry
+        include RateThrottling
+
+        DEFAULT_HOST = 'live.ecoportal.com'.freeze
 
         attr_accessor :logger
         attr_reader :host
@@ -34,7 +39,7 @@ module Ecoportal
         # @param logger [Logger] an object with `Logger` interface to generate logs.
         # @param deep_logging [Boolean] whether or not batch responses should be logged
         # @return [Client] an object that holds the configuration of the api connection.
-        def initialize(api_key:, version: "v1", host: "live.ecoportal.com", logger: nil, deep_logging: false)
+        def initialize(api_key:, version: "v1", host: DEFAULT_HOST, logger: nil, deep_logging: false)
           @version      = version
           @api_key      = api_key
           @logger       = logger
@@ -163,7 +168,9 @@ module Ecoportal
             log(:debug) { "Data: #{JSON.pretty_generate(data)}" }
           end
 
-          with_retry(&block).tap do |result|
+          with_retry do
+            rate_throttling(&block)
+          end.tap do |result|
             next unless deep_logging?
 
             end_time = Time.now.to_f

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

@@ -0,0 +1,116 @@
+module Ecoportal
+  module API
+    class V1
+      class Job
+        class Awaiter
+          include Common::Client::TimeOut
+
+          DELAY_STATUS_CHECK = 4
+          MIN_STATUS_CHECK   = 2
+
+          TIMEOUT_APPROACH   = :min # :conservative # adaptative timeout
+          TIMEOUT_FALLBACK   = :min
+
+          attr_reader :job, :job_id, :total
+          attr_accessor :timeout_approach
+
+          def initialize(job, job_id:, total:)
+            @job     = job
+            @job_id  = job_id
+            @total   = total
+            @checked = false
+            self.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
+            end
+          end
+
+          def await_completion! # rubocop:disable Metrics/AbcSize
+            max_timeout = timeout_for(total, approach: timeout_approach)
+
+            # 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
+
+              adapted = waited
+              adapted = waited - (delay_status_check / 2) if delay_status_check
+              ratio   = throughput!(adapted, count: done)
+
+              break status if status.complete?(total)
+
+              pending = status.pending(total)
+              left    = max_timeout - waited
+
+              timeout!(status, timeout: max_timeout) unless left.positive?
+
+              delay_status_check = status_check_in(pending, timeout_in: left)
+
+              msg  = " ... Awaiting #{delay_status_check} s. -- "
+              msg << " TimeOut: #{left.round(2)} s. "
+              msg << "(job '#{job_id}') "
+              msg << "Done: #{done} (est. #{ratio} rec/s) "
+              msg << "     \r"
+
+              print msg
+              $stdout.flush
+
+              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
+  end
+end

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

@@ -0,0 +1,42 @@
+module Ecoportal
+  module API
+    class V1
+      class Job
+        class Status
+          attr_reader :id, :progress
+
+          def initialize(id, complete, errored, progress)
+            @id       = id
+            @complete = complete
+            @errored  = errored
+            @progress = progress
+          end
+
+          def complete?(total = nil)
+            return @complete if total.nil?
+
+            progress >= total
+          end
+
+          def pending(total)
+            return 1 unless total
+            return 0 if total <= progress
+
+            total - progress
+          end
+
+          def errored?
+            @errored
+          end
+
+          def to_s
+            msg = complete? ? "Completed" : "In progress"
+            msg = "Errored" if errored?
+            msg << " with #{progress} done."
+            msg
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+require 'ecoportal/api/v1/job/status'
+require 'ecoportal/api/v1/job/awaiter'
+
+module Ecoportal
+  module API
+    class V1
+      class Job
+        attr_reader :client, :person_class
+
+        # @param client [Common::Client] a `Common::Client` object that holds the configuration of the api connection.
+        # @return [People] an instance object ready to make people api requests.
+        def initialize(client, person_class:)
+          @client       = client
+          @person_class = person_class
+          @created      = false
+        end
+
+        # Allows to preserve the learned througoutput
+        def new
+          self.class.new(client, person_class: person_class).tap do |out|
+            out.awaiter = @awaiter
+          end
+        end
+
+        def created?
+          @created
+        end
+
+        # @return [Ecoportal::API::Common::Response] the results of the batch job
+        def batch(recover: false)
+          raise_if_already_launched! unless recover
+
+          @operation ||= Common::BatchOperation.new(
+            "/people",
+            person_class,
+            logger: client.logger
+          )
+
+          yield operation unless recover
+
+          total   = operation.count
+          job_id  = create(operation, recover: recover)
+          stat    = awaiter(
+            job_id: job_id,
+            total:  total
+          ).await_completion!
+
+          job_result(job_id, operation) if stat&.complete?(total)
+        end
+
+        def status(job_id)
+          response = client.get("/people/job/#{CGI.escape(job_id)}/status")
+          body     = response && body_data(response.body)
+
+          msg      = "Status error (#{response.status}) - "
+          msg     << "Errors: #{body}"
+          raise msg unless response.success?
+
+          Status.new(*body.values_at(*%w[id complete errored progress]))
+        end
+
+        protected
+
+        attr_writer :awaiter
+
+        def awaiter(job_id:, total:, preserve: true)
+          return @awaiter = Awaiter.new(self, job_id: job_id, total: total) unless preserve && @awaiter
+
+          @awaiter = @awaiter.new(job_id: job_id, total: total)
+        end
+
+        private
+
+        attr_reader :operation
+
+        def operations
+          @operations ||= {}
+        end
+
+        def job_operation(job_id)
+          operations[job_id]
+        end
+
+        def raise_if_already_launched!
+          return unless created?
+
+          msg  = "Missusage: job was already created."
+          msg << " Can't call batch more than once"
+          raise msg
+        end
+
+        # @return [Ecoportal::API::Common::Response] the results of the batch job
+        def job_result(job_id, operation)
+          client.get("/people/job/#{CGI.escape(job_id)}").tap do |response|
+            operation.process_response(response)
+          end
+        end
+
+        # @return [String] the `id` of the created batch job
+        def create(operation, recover: false)
+          raise_if_already_launched! unless recover
+
+          job_id = nil
+
+          client.post("/people/job", data: operation.as_json).tap do |response|
+            job_id = body_data(response.body)["id"] if response.success?
+
+            next if job_id
+
+            msg  = "Could not create job - Error (#{response.status}): "
+            msg << body_data(response.body).to_s
+            raise msg
+          end
+
+          if job_id
+            @created = true
+            operations[job_id] = operation
+          end
+
+          job_id
+        end
+
+        # Hook for other api versions to obtain the raw data of a response
+        # @note this was introduced to allow `v2` to reuse this class
+        def body_data(body)
+          body
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/v1/people.rb

@@ -6,11 +6,8 @@ module Ecoportal
       class People
         extend Common::BaseClass
         include Common::DocHelpers
-        include Common::Client::TimeOut
         include Enumerable
 
-        DELAY_STATUS_CHECK = 5
-
         class_resolver :person_class, "Ecoportal::API::V1::Person"
 
         attr_reader :client
@@ -143,7 +140,7 @@ module Ecoportal
         # @param job_mode [Boolean] whether or not it should use batch jobs
         # @return [Ecoportal::API::Common::Response] the results of the batch
         def batch(job_mode: true, &block)
-          return job(&block) if job_mode
+          return job.batch(&block) if job_mode
 
           operation = Common::BatchOperation.new(
             "/people",
@@ -159,33 +156,11 @@ module Ecoportal
           end
         end
 
-        # @return [Ecoportal::API::Common::Response] the results of the batch job
-        def job
-          operation = Common::BatchOperation.new(
-            "/people",
-            person_class,
-            logger: client.logger
-          )
-
-          yield operation
-
-          total   = operation.count
-          timeout = timeout_for(total)
-
-          job_id  = create_job(operation)
-          status  = wait_for_job_completion(job_id, timeout: timeout, total: total)
+        # @return [Ecoportal::API::V1::Job]
+        def job(preserve_stats: true)
+          return @last_job = Job.new(client, person_class: person_class) unless preserve_stats && @last_job
 
-          # @todo
-          # if total == status.progress
-          if status&.complete?(total)
-            job_result(job_id, operation)
-          else
-            msg  = "Job '#{job_id}' not complete (size: #{total}).\n"
-            msg << "  Probably timeout after #{timeout} seconds.\n"
-            msg << "  Current status: #{status}"
-
-            raise API::Errors::TimeOut, msg
-          end
+          @last_job = @last_job.new
         end
 
         # Creates a new `Person` object.
@@ -196,59 +171,6 @@ module Ecoportal
 
         private
 
-        def job_status(job_id)
-          response = client.get("/people/job/#{CGI.escape(job_id)}/status")
-          body     = response && body_data(response.body)
-
-          msg      = "Status error (#{response.status}) - "
-          msg     << "Errors: #{body}"
-          raise msg unless response.success?
-
-          JobStatus.new(*body.values_at(*%w[id complete errored progress]))
-        end
-
-        # @return [Ecoportal::API::Common::Response] the results of the batch job
-        def job_result(job_id, operation)
-          client.get("/people/job/#{CGI.escape(job_id)}").tap do |response|
-            operation.process_response(response)
-          end
-        end
-
-        def wait_for_job_completion(job_id, timeout:, total:)
-          # 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
-
-          loop do
-            status = job_status(job_id)
-            break status if status.complete?(total)
-
-            left = (before + timeout) - Time.now
-            break status unless left.positive?
-            # break status if Time.now >= before + timeout
-
-            msg  = " ... Await job "
-            msg << "('#{job_id}'; done: #{status.progress}): "
-            msg << "#{left.ceil} sec.    \r"
-
-            print msg
-            $stdout.flush
-
-            sleep(DELAY_STATUS_CHECK)
-            status
-          end
-        end
-
-        # @return [String] the `id` of the created batch job
-        def create_job(operation)
-          job_id = nil
-          client.post("/people/job", data: operation.as_json).tap do |response|
-            job_id = body_data(response.body)["id"] if response.success?
-            raise "Could not create job - Error (#{response.status}): #{body_data(response.body)}" unless job_id
-          end
-          job_id
-        end
-
         # Hook for other api versions to obtain the raw data of a response
         # @note this was introduced to allow `v2` to reuse this class
         def body_data(body)
@@ -262,3 +184,4 @@ end
 require 'ecoportal/api/v1/schema_field_value'
 require 'ecoportal/api/v1/person_details'
 require 'ecoportal/api/v1/person'
+require 'ecoportal/api/v1/job'

data/lib/ecoportal/api/v1.rb

@@ -46,6 +46,5 @@ module Ecoportal
   end
 end
 
-require 'ecoportal/api/v1/job_status'
 require 'ecoportal/api/v1/person_schemas'
 require 'ecoportal/api/v1/people'

data/lib/ecoportal/api/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.10.5
 platform: ruby
 authors:
 - Tapio Saarinen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-09-30 00:00:00.000000000 Z
+date: 2024-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -180,6 +180,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '6'
+- !ruby/object:Gem::Dependency
+  name: rate_throttle_client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description:
 email:
 - tapio@ecoportal.co.nz
@@ -212,6 +226,9 @@ files:
 - lib/ecoportal/api/common/client/elastic_apm_integration.rb
 - lib/ecoportal/api/common/client/error.rb
 - lib/ecoportal/api/common/client/error/checks.rb
+- lib/ecoportal/api/common/client/rate_throttling.rb
+- lib/ecoportal/api/common/client/throughput.rb
+- lib/ecoportal/api/common/client/throughput/stats.rb
 - lib/ecoportal/api/common/client/time_out.rb
 - lib/ecoportal/api/common/client/with_retry.rb
 - lib/ecoportal/api/common/doc_helpers.rb
@@ -239,7 +256,9 @@ files:
 - lib/ecoportal/api/internal/schema_field_value.rb
 - lib/ecoportal/api/logger.rb
 - lib/ecoportal/api/v1.rb
-- lib/ecoportal/api/v1/job_status.rb
+- lib/ecoportal/api/v1/job.rb
+- lib/ecoportal/api/v1/job/awaiter.rb
+- lib/ecoportal/api/v1/job/status.rb
 - lib/ecoportal/api/v1/people.rb
 - lib/ecoportal/api/v1/person.rb
 - lib/ecoportal/api/v1/person_details.rb

data/lib/ecoportal/api/v1/job_status.rb

@@ -1,33 +0,0 @@
-module Ecoportal
-  module API
-    class V1
-      class JobStatus
-        attr_reader :id, :progress
-
-        def initialize(id, complete, errored, progress)
-          @id       = id
-          @complete = complete
-          @errored  = errored
-          @progress = progress
-        end
-
-        def complete?(total = nil)
-          return @complete if total.nil?
-
-          progress >= total
-        end
-
-        def errored?
-          @errored
-        end
-
-        def to_s
-          msg = complete? ? "Completed" : "In progress"
-          msg = "Errored" if errored?
-          msg << " with #{progress} done."
-          msg
-        end
-      end
-    end
-  end
-end