eco-helpers 3.3.3 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c5e64bb2f9a25359774eb01482180a7efdbade0e2b6e4d02a56a4c9dbb1d91f
-  data.tar.gz: ea2fd73dc9709ca1710e9aff527f0ae856a55fe0638a7c3862b71bfd9ce5270c
+  metadata.gz: 0d846f9dd8c67e9ece8e82f76b48f57abb6f2281a827906fa0deea759793a2a4
+  data.tar.gz: 31010d6385deea25c65e005f2d056e07cc1c00e18cc3257c080863a9042c5393
 SHA512:
-  metadata.gz: 37dfa8178019e8a4854f3b98386682def2ff8f51b1f7c9dcf95dff4947eea662f14145ab93434ceb8f749acc7981d6904114bc8ad8f4f6d251ed217a28a43ce5
-  data.tar.gz: 4653193b58ac2f88bb76b06c4ee094331b2f034ccae4929d5722398105e2035a982e136fd6fda78d207c33e5ddc4aff9f5c489a11abd155382607d94bca8105d
+  metadata.gz: ca7ad30915e09c003d99c0cf291b0ef2a1834179883de98402380d144bb231cf9f12f2fe802b5b2fed2387b8d63e6e3eee8e4363decdd3636863af0bc702edc8
+  data.tar.gz: ed532533a05a25f09b65118104a8627f7bf0fde3b212b2fcd562d499770fdd19de4588caefd388eebb5c91cd9689ab6cbfcf3456e47dafeb69acfab9231956a8

data/CHANGELOG.md

@@ -4,18 +4,49 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-## [3.3.3] - 2026-09-30
-
-Security republish of 3.3.2. **Backwards-compatible; no code change**: same dependencies, same
-behaviour. Supersedes the published versions of this line, which are to be yanked.
-
-### Security
-
-- Removed customer and internal identifiers from shipped code comments and this changelog (a
-  comment listing customer organisations and their case names; internal repository names and
-  internal documentation paths). Comments and changelog only.
-- Packaging: the three runtime JSON files are declared in `.release-smoke-allow`, and the release
-  tasks accept `release/*` maintenance branches.
+## [3.4.0] - 2026-09-29
+
+**MERGE ONLY AFTER `ecoportal-api-graphql` 3.0.0 IS PUBLISHED** -- this release's gemspec
+floor (`~> 3.0`) cannot resolve against rubygems.org until then; tested here against a
+locally built 3.0.0 CANDIDATE gem (see `docs/worklog.md`'s 2026-09-29 entry for the exact
+build/install steps), not the published artifact.
+
+### Changed
+
+- **BREAKING for consumers still on `ecoportal-api-graphql` 2.x:** requires
+  `ecoportal-api-graphql ~> 3.0` (was `~> 2.0`). That gem's own 3.0.0 removes
+  `Base::Page::DataField::ImageGallery#file_container_ids` / `#file_container_ids=` --
+  an Image Gallery image was never a `FileContainer`. Replaced by `#images` / `#image_ids` /
+  `#add_source_images([{source_id:, file_name:}, ...])` after
+  `FileUpload::Client#upload_image`. A repo-wide sweep of `eco-helpers` itself for
+  `file_container_ids` / `fileContainerIds` / `fileContainers` found **0 hits** -- no caller
+  in `lib/`, `spec/`, `docs/`, `bin/` used the removed accessors (the one look-alike,
+  `FileField#file_container_id` in `lib/eco/api/usecases/ooze_samples/helpers_migration/
+  copying.rb`, is the UNRELATED APIv2/REST `File` field type's own singular accessor, not
+  Image Gallery, not affected). No code change was needed in `eco-helpers` for this bump.
+- `Eco::API::Session::Concurrency::BoundedWorkerPool` / `RetryPolicy`
+  (`lib/eco/api/session/concurrency/`) are now the CANONICAL, supported concurrency
+  primitives in this gem (dropped the "draft, nothing has switched to this copy yet"
+  header wording) -- see `README.md`'s new "Concurrency primitives" section. No
+  pre-existing inline `Thread.new`/`Queue.new`/subprocess-retry-loop exists anywhere under
+  `lib/eco/api/session` or `lib/eco/api/usecases` to migrate onto them (checked by grep at
+  promotion time); a future caller picks these up directly, as-is.
+
+### Fixed
+
+- `Eco::Language::Klass::AutoLoader#autoload_children!` only tolerated a `TypeError` from a
+  malformed pending child (its own comment: "must be the singleton class"); a pending child
+  raising any OTHER `StandardError` while being constructed (e.g. an anonymous, never fully
+  configured `Class.new(SomeAutoloadedBase)` test double left alive in `ObjectSpace` by an
+  entirely unrelated spec elsewhere in the same process -- `Parser`/`ErrorHandler`
+  characterization specs create these on purpose) propagated out of the NEXT, unrelated
+  caller's own `autoload_children!` cycle instead. Broadened the rescue to `TypeError,
+  StandardError`, matching the existing rescue's own documented intent ("can't create from
+  this class... just ignore"). Pre-existing, GC-timing-sensitive flake -- confirmed
+  reproducible (non-deterministically) against the CURRENT `ecoportal-api-graphql` 2.2.0
+  floor too, not something the 3.0 bump introduced; surfaced while testing this release
+  against the 3.0.0 candidate, where it reproduced deterministically across three
+  consecutive runs before the fix and cleared across three consecutive runs after.
 
 ## [3.3.2] - 2026-09-02
 

data/README.md

@@ -1,6 +1,34 @@
 # API Helpers (eco-helpers)
 
-Some helpers to define a framework of use cases.
+## Why this repo exists
+
+`eco-helpers` is the team's **central integrations library** -- one of the oldest repos in the
+fleet. It sits between the raw EcoPortal API clients (`ecoportal-api`, `ecoportal-api-v2`,
+`ecoportal-api-graphql`) and the end scripts, adding file management/access, SFTP access, and
+more (`net-sftp`, `net-ssh`, `aws-sdk-s3` are runtime dependencies -- see `eco-helpers.gemspec`).
+
+> "If there is a repo that should somehow be the reference of our integrations that is the
+> eco-helpers repo... [ep-graphql is powerful but raw] ...but if we have an intermediate layer
+> with helpers that allow to build integrations by taking into account not just raw api access,
+> but also file managing/access, SFTP access, etc. that is the eco-helpers for sure."
+> -- owner, 2026-09-23
+
+```mermaid
+flowchart LR
+  A["Raw API clients<br/>ecoportal-api / -v2 / -graphql"] --> B["eco-helpers<br/>integrations layer"]
+  B --> C["End scripts<br/>automation, CLI, use cases"]
+```
+*Layering per the owner's own description (source: memory
+`project-imports-process-and-eco-helpers-owner-truth.md`, 2026-09-24).*
+
+### What is inside
+
+- `lib/eco/api/` -- API integration layer (session, use-cases, microcases, policies, org resources)
+- `lib/eco/cli/` + `lib/eco/cli_default/` -- CLI framework and default options/filters/people workflows
+- `lib/eco/csv/` -- CSV reading, streaming, splitting
+- `lib/eco/data/` -- data utilities (fuzzy match, hashes, locations, strings, files)
+- `lib/eco/language/` -- logging, curry, and auxiliary utilities
+- `lib/eco/assets/` -- static assets (language files etc.)
 
 ## Installation
 
@@ -19,6 +47,39 @@ Or install it yourself as:
     $ gem install eco-helpers
 
 
+## Concurrency primitives
+
+`Eco::API::Session::Concurrency` (`lib/eco/api/session/concurrency/`) is the supported home
+for session-level concurrency primitives, as of 3.4.0:
+
+- **`BoundedWorkerPool`** -- a generic, bounded pool of OS threads (pure `Thread`/`Queue`/
+  `Mutex`, no extra gem) for running the SAME block over a list of items with a hard ceiling
+  on how many run simultaneously. Results come back in the same order as the input,
+  regardless of finish order; one item's block raising is captured as that item's own
+  `Result#error`, never re-raised, never aborts sibling work already in flight or queued
+  (unless `stop_on_error: true`). See the class's own header for the full contract and
+  thread-safety notes.
+- **`RetryPolicy`** -- a pure decision service (never sleeps itself) for whether/how long to
+  wait before retrying a whole failed subprocess call, given its captured output and exit
+  status: rate-limit/5xx-aware, bounded exponential backoff with full jitter, honours a
+  captured `Retry-After` header. See the module's own header for why an OUTER,
+  subprocess-level retry is worth having even though the underlying GraphQL gem already
+  retries transient errors INSIDE one call.
+
+Both are generic (no case-specific or org-specific logic) and fully specced against
+synthetic blocks only -- no subprocess, no network, nothing case-specific. See
+`spec/eco/api/session/concurrency/`.
+
 ## Changelog
 
 See {file:CHANGELOG.md} for a list of changes.
+
+<!-- audit-status:start -->
+### Fleet audit status
+
+This repo is under the Fleet Audit & Amendment Programme (FAAP). No audit run yet -- this is the notice MR; the first `granular`-tier run populates this block with counts by severity and status.
+
+Guidelines (read before any change): `docs/audits/guidelines.md`
+Deviations register: `docs/audits/deviations.md`
+Run index: `docs/audits/README.md`
+<!-- audit-status:end -->

data/lib/eco/api/session/concurrency/bounded_worker_pool.rb

@@ -0,0 +1,150 @@
+# PROMOTED FROM a downstream script repo (services/bounded_worker_pool.rb @ 41dedad)
+# NAMESPACE: PROVISIONAL (owner ruling DSL-02) -- kept the original class/module name
+# (`BoundedWorkerPool`) under `Eco::API::Session::Concurrency::*`, the session-level
+# concurrency primitives location proposed by WP-6 (see
+# the repo's internal docs, Option A).
+#
+# CANONICAL, 3.4.0 (release/3.4.0-prep) -- this is the supported concurrency primitive for
+# a bounded pool of OS threads in this gem; see `README.md`'s own "Concurrency primitives"
+# section. No PRE-EXISTING inline `Thread.new`/`Queue.new` concurrency exists anywhere else
+# under `lib/eco/api/session` or `lib/eco/api/usecases` to migrate onto this (checked by
+# grep, both directories, at promotion time) -- there was nothing to switch, so none of this
+# gem's own call sites change as part of this promotion; a FUTURE caller (this gem's own
+# batch/CLI code, or a downstream consumer such as a downstream script's wave runner, the
+# original motivating caller) picks this up directly, as-is.
+#
+# the wave-concurrency work (2026-09-19) -- generic, reusable bounded-concurrency runner. Pure
+# Ruby stdlib (`Thread`/`Queue`/`Mutex`) -- no new gem, matching this repo's own "PLAIN DATA IN/
+# service-first" convention (see any other `Custom::Template::Services::*` file's header).
+#
+# WHY THIS EXISTS: `run_wave.rb` shells out to `ruby main.rb ...` once PER ITEM, per stage
+# (build/force-install/publish/tooltips) -- ~47 items, each a live network round trip, run
+# strictly sequentially. A pass is minutes of network WAIT, not CPU work, so a bounded pool of
+# OS threads (each blocking on its own `Open3.capture3` call) is the right tool: Ruby (MRI)
+# threads release the GVL during blocking I/O (`Open3.capture3` waits on the child process, a
+# blocking syscall), so N threads genuinely overlap N in-flight subprocess calls rather than
+# contending for CPU.
+#
+# CONTRACT (every point specced in isolation, synthetic blocks only -- no subprocess, no
+# network, nothing case-specific here):
+#   - `concurrency:` is a HARD CEILING on simultaneously-RUNNING blocks -- never exceeded.
+#   - Results come back in the SAME order as `items`, regardless of which one finishes first
+#     (a slow item 1 and a fast item 2 must never swap positions in the returned Array).
+#   - One item's block RAISING is CAPTURED as that item's own `Result#error`, never re-raised
+#     to the caller, and never aborts sibling work already in flight or already queued --
+#     UNLESS `stop_on_error:` says otherwise (below).
+#   - Empty `items` returns `[]` immediately, no thread ever spawned.
+#
+# `stop_on_error:` (default `false`, OPT-IN, generic -- not `run_wave.rb`-specific): once ANY
+# dispatched item's block raises, no item still WAITING in the queue is ever started (each
+# such item's own `Result#skipped?` reads `true`, `#value`/`#error` both `nil`) -- but anything
+# ALREADY running when the failure is observed is allowed to finish (there is no clean way to
+# interrupt a live `Open3.capture3` mid-flight, and killing the child process would leave that
+# item's own live state ambiguous, worse than letting it complete). At `concurrency: 1` this
+# reproduces "stop at the first failure, never attempt the next item" EXACTLY -- with a single
+# worker, "already running" and "already failed" can never overlap, so the second item is
+# always still in the QUEUE (never started) the instant the first one fails. `run_wave.rb`'s
+# own force-install/build wiring relies on this exact property for byte-for-byte parity with
+# its pre-concurrency sequential behaviour at `--concurrency 1` (see
+# `run_wave_concurrency_spec.rb`'s own "concurrency 1 equivalence" examples).
+#
+# THREAD SAFETY OF `results[index] = ...` FROM MULTIPLE THREADS: safe under MRI (this repo's
+# only Ruby implementation, per rbenv) -- the GVL serializes bytecode execution, so concurrent
+# writes to DISTINCT indices of one Array never race or corrupt its internal structure (a
+# well-established MRI pattern; JRuby/TruffleRuby would need an explicit lock here too, but
+# this repo does not target them). The ONE piece of state actually SHARED and mutated across
+# threads (`aborted`, for `stop_on_error:`) is behind an explicit `Mutex` regardless, so this
+# file makes no silent assumptions beyond that documented one.
+
+module Eco
+  module API
+    class Session
+      module Concurrency
+        module BoundedWorkerPool
+          # One item's own outcome. Exactly one of `value`/`error` is non-nil unless `skipped?`
+          # is true, in which case both are `nil` -- the block was never even called for it.
+          Result = Struct.new(:item, :value, :error, :skipped, keyword_init: true) do
+            def skipped?
+              !!skipped
+            end
+
+            # @return [Boolean] true only for a NORMAL completion -- neither raised nor skipped.
+            def ok?
+              !skipped? && error.nil?
+            end
+          end
+
+          class << self
+            # @param items [Array] anything, plain data -- never mutated.
+            # @param concurrency [Integer] hard ceiling on simultaneously-RUNNING blocks. Values
+            #   `<= 0` are treated as `1` (never zero threads, never negative) -- callers own
+            #   their own upper-bound policy (`run_wave.rb`'s own `--concurrency` option caps at
+            #   8, enforced there, not here: this file is generic and takes no opinion on what a
+            #   sane ceiling is for any particular caller).
+            # @param stop_on_error [Boolean] see the file header.
+            # @yieldparam item [Object] one element of `items`.
+            # @yieldreturn [Object] becomes that item's `Result#value`.
+            # @return [Array<Result>] one per `items` element, in `items`' own order.
+            def run(items, concurrency:, stop_on_error: false, &block)
+              list = Array(items)
+              return [] if list.empty?
+
+              worker_count = [concurrency.to_i, 1].max
+              run_state = RunState.new(
+                queue: build_queue(list, worker_count), results: Array.new(list.size),
+                abort_state: {aborted: false}, state_mutex: Mutex.new, stop_on_error: stop_on_error, block: block
+              )
+
+              threads = Array.new(worker_count) { Thread.new { worker_loop(run_state) } }
+              threads.each(&:join)
+
+              run_state.results
+            end
+
+            # Bundles the per-run shared state every worker thread reads/writes, so
+            # `#worker_loop`/`#run_one` stay under the 5-parameter style ceiling without losing
+            # any of it -- plain data, no behaviour of its own. Internal (declared above `private`
+            # only because Ruby constants ignore access modifiers -- rubocop Lint/UselessConstantScoping).
+            RunState = Struct.new(:queue, :results, :abort_state, :state_mutex, :stop_on_error, :block,
+                                  keyword_init: true)
+
+            private
+
+            # One `[index, item]` pair per real item, `worker_count` `:done` sentinels at the
+            # tail (one per worker, so every worker eventually sees its own stop signal and the
+            # pool's own `Thread#join`s all return -- a `Queue` blocks `#pop` forever otherwise).
+            def build_queue(list, worker_count)
+              queue = Queue.new
+              list.each_with_index {|item, index| queue << [index, item]}
+              worker_count.times { queue << :done }
+              queue
+            end
+
+            def worker_loop(run_state)
+              loop do
+                entry = run_state.queue.pop
+                break if entry == :done
+
+                index, item = entry
+                if run_state.stop_on_error && run_state.state_mutex.synchronize {run_state.abort_state[:aborted]}
+                  run_state.results[index] = Result.new(item: item, value: nil, error: nil, skipped: true)
+                  next
+                end
+
+                run_one(index, item, run_state)
+              end
+            end
+
+            def run_one(index, item, run_state)
+              value = run_state.block.call(item)
+              run_state.results[index] = Result.new(item: item, value: value, error: nil, skipped: false)
+            rescue StandardError => e
+              run_state.results[index] = Result.new(item: item, value: nil, error: e, skipped: false)
+              run_state.state_mutex.synchronize {run_state.abort_state[:aborted] = true} if run_state.stop_on_error
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/session/concurrency/retry_policy.rb

@@ -0,0 +1,139 @@
+# PROMOTED FROM a downstream script repo (services/retry_policy.rb @ 41dedad)
+# NAMESPACE: PROVISIONAL (owner ruling DSL-02) -- kept the original class/module name
+# (`RetryPolicy`) under `Eco::API::Session::Concurrency::*`, the session-level concurrency
+# primitives location proposed by WP-6 (see
+# the repo's internal docs, Option A).
+#
+# CANONICAL, 3.4.0 (release/3.4.0-prep) -- this is the supported subprocess-level retry
+# decision primitive in this gem; see `README.md`'s own "Concurrency primitives" section.
+# `lib/eco/api/session/batch/launcher/retry.rb`'s own `offer_retry_on`/`batch_mode_on` are a
+# DIFFERENT, PRE-EXISTING retry mechanism (interactive Y/n prompt + a fixed
+# `ALLOWED_RETRIES` count around the people-batch HTTP endpoint's own error classes,
+# `Ecoportal::API::Errors::TimeOut`/`StartTimeOut`) -- not a shelled-out-subprocess retry,
+# nothing to switch onto this file. `lib/eco/api/usecases/graphql/samples/location/service/
+# tree_diff.rb`'s `sleep(5)` is an unconditional cooldown pause between comparisons, not a
+# retry loop either. Neither is this file's concern; checked (grep, both directories) at
+# promotion time -- there is no PRE-EXISTING inline concurrency/retry loop that duplicates
+# this file's own job to wire onto it. A FUTURE caller (this gem's own batch/CLI code, or a
+# downstream consumer such as a downstream script's wave runner, the original motivating
+# caller) picks this up directly, as-is.
+#
+# the wave-concurrency work (2026-09-19) -- decides WHETHER/HOW LONG to wait before retrying
+# one shelled-out subprocess call, never sleeps itself (pure decision service, easily specced
+# without a slow test) and never distinguishes idempotent-vs-not (that policy is the CALLER's
+# own job -- `run_wave.rb` only ever calls this for stages it has independently classified as
+# safe to retry -- see that file's own PER-STAGE RETRY TABLE comment).
+#
+# WHY A SUBPROCESS-LEVEL RETRY EXISTS AT ALL, GIVEN THE GEM ALREADY RETRIES: confirmed by
+# reading `ecoportal-api-graphql` (2.2.0) `lib/ecoportal/api/common/graphql/http_client.rb`
+# (`#execute`'s own comment, verbatim): every GraphQL call already routes through the
+# inherited `Common::Client` pipeline ("instrument -> with_retry { rate_throttling }"), which
+# already retries 429/Cloudflare-1015/5xx/connection errors INSIDE one call, transparently, long
+# before either the case code or this file ever sees anything. So by the time a shelled-out
+# `ruby main.rb ...` subprocess actually EXITS non-zero for an HTTP reason, that gem-level
+# budget has ALREADY been exhausted (or the whole process crashed before ever making a call,
+# e.g. a DNS blip at startup). Retrying the WHOLE subprocess is therefore a coarser, OUTER
+# layer of defence -- a fresh process gets a FRESH inner retry budget too (useful for
+# transient token/DNS issues an in-process retry cannot fix) -- not a duplicate of the gem's
+# own retries.
+#
+# THE MARKER THIS FILE READS -- NO CASE-FILE CHANGE NEEDED: grepped every
+# downstream template case file for an HTTP-status-distinguishing marker
+# (429/Retry-After/5xx) -- none add one themselves; they let the gem's own exception surface
+# verbatim on an uncaught crash. That exception already IS a stable, distinguishing marker:
+# `Ecoportal::API::Common::Client::Error::UnexpectedServerError#initialize` (ecoportal-api
+# 0.10.18, lib/ecoportal/api/common/client/error.rb) formats its message
+# `"Code: #{code} -- Error: #{msg}"` -- printed verbatim to STDERR (captured into `execute`'s
+# own combined stdout+stderr) whenever a subprocess crashes uncaught on a non-2xx HTTP
+# response. `HTTP_CODE_PATTERN` below matches THAT exact, already-existing text -- nothing was
+# added to any case file for this to work. Recorded here as an INFERRED-FROM-STATIC-READ
+# finding, not live-verified against a real 429 -- if a live retry never actually fires when
+# expected, re-check this pattern against a real crash's captured output first.
+module Eco
+  module API
+    class Session
+      module Concurrency
+        module RetryPolicy
+          # HTTP statuses worth retrying the WHOLE subprocess for: rate limiting (429) and the
+          # standard 5xx server-error family. Never 4xx other than 429 (a 400/403/404/422 is a
+          # REQUEST defect -- retrying it verbatim would just fail the same way every time).
+          RETRYABLE_HTTP_CODES = [429, 500, 502, 503, 504].freeze
+
+          # See the file header -- `Ecoportal::API::Common::Client::Error::UnexpectedServerError`'s
+          # own message format, verbatim.
+          HTTP_CODE_PATTERN = /Code:\s*(\d+)\s*--\s*Error:/
+
+          # Case-insensitive: HTTP header names are conventionally capitalised in a raw dump, but
+          # nothing here guarantees a subprocess's captured text preserves that casing exactly.
+          RETRY_AFTER_PATTERN = /Retry-After:\s*(\d+)/i
+
+          BASE_DELAY_SECONDS = 1.0
+          MAX_DELAY_SECONDS = 30.0
+
+          # One decision, after ONE attempt has already run and been captured.
+          Decision = Struct.new(:should_retry, :delay_seconds, :reason, keyword_init: true) do
+            def retry?
+              !!should_retry
+            end
+          end
+
+          class << self
+            # @param output [String] combined stdout+stderr from the attempt just completed.
+            # @param status [Process::Status, nil] `nil` when the subprocess itself could not be
+            #   spawned at all (see `run_wave.rb#execute`'s own `rescue StandardError` branch) --
+            #   treated as a hard failure, never retryable (nothing about a spawn failure is an
+            #   HTTP status).
+            # @param attempt [Integer] 1-based -- the attempt that JUST ran.
+            # @param max_attempts [Integer] total attempts allowed, INCLUDING the first -- so
+            #   `max_attempts: 3` permits at most 2 retries after the initial attempt.
+            # @return [Decision]
+            def decide(output:, status:, attempt:, max_attempts: 3)
+              return Decision.new(should_retry: false, delay_seconds: 0, reason: :ok) if status&.success?
+              if attempt >= max_attempts
+                return Decision.new(should_retry: false, delay_seconds: 0,
+                                    reason: :max_attempts_reached)
+              end
+
+              code = retryable_http_code(output)
+              return Decision.new(should_retry: false, delay_seconds: 0, reason: :not_retryable) unless code
+
+              delay = retry_after_seconds(output) || backoff_delay_seconds(attempt)
+              Decision.new(should_retry: true, delay_seconds: delay, reason: :"http_#{code}")
+            end
+
+            # @return [Integer, nil] the HTTP status code found in `output`, only when it is one
+            #   of {RETRYABLE_HTTP_CODES} -- `nil` for anything else (including a code that WAS
+            #   found but is not on the retryable list, e.g. a 400).
+            def retryable_http_code(output)
+              match = HTTP_CODE_PATTERN.match(output.to_s)
+              return nil unless match
+
+              code = match[1].to_i
+              RETRYABLE_HTTP_CODES.include?(code) ? code : nil
+            end
+
+            # @return [Integer, nil] the server-requested wait, in seconds, when a `Retry-After`
+            #   header value was captured in the output -- takes priority over the computed
+            #   backoff below when present (the server knows better than a guess).
+            def retry_after_seconds(output)
+              match = RETRY_AFTER_PATTERN.match(output.to_s)
+              match && match[1].to_i
+            end
+
+            # Bounded exponential backoff with FULL jitter (AWS Architecture Blog's own
+            # "Exponential Backoff And Jitter", the well-established shape): a uniform random
+            # pick in `[0, capped)`, `capped = min(BASE * 2**(attempt-1), MAX)`. Full jitter
+            # (not merely +/- a percentage) is deliberate -- it is what actually de-correlates N
+            # concurrent workers that all hit a 429 in the SAME instant (`--concurrency N`'s own
+            # reason to exist) from retrying in lockstep and re-triggering the same rate limit.
+            # @return [Float] seconds, `0 <= delay < capped`.
+            def backoff_delay_seconds(attempt)
+              capped = [BASE_DELAY_SECONDS * (2**(attempt - 1)), MAX_DELAY_SECONDS].min
+              rand * capped
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/language/klass/auto_loader.rb

@@ -21,9 +21,18 @@ module Eco::Language::Klass
 
       pending_children.each do |klass|
         @child = klass.new(object)
-      rescue TypeError => _e
-        # Can't create from this class (must be the singleton class)
-        # Just ignore
+      rescue StandardError => _e
+        # Can't create from this class (must be the singleton class), OR the class was
+        # never fully configured for a real registration -- e.g. an anonymous
+        # `Class.new(SomeAutoloadedBase)` test double left behind, un-configured, by an
+        # ENTIRELY UNRELATED spec elsewhere in the same process (this scan walks
+        # `ObjectSpace`, a process-wide, cross-spec-file concern -- see
+        # `spec/eco/language/klass/auto_loader_spec.rb`'s own "malformed pending child"
+        # example, and `spec/support/fakes/c7_person_entry_fakes.rb`'s header, for two
+        # already-documented instances of this exact class of fragility). Best-effort
+        # discovery: one malformed/unrelated pending child must never abort loading the
+        # REST of the pending children, still less raise into a caller that has nothing
+        # to do with it. Just ignore, same as the original TypeError case above.
       ensure
         autoloaded_children.push(klass)
       end

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.3.3'.freeze
+  VERSION = '3.4.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.3.3
+  version: 3.4.0
 platform: ruby
 authors:
 - Oscar Segura
@@ -259,20 +259,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-v2
   requirement: !ruby/object:Gem::Requirement
@@ -713,6 +713,8 @@ files:
 - lib/eco/api/session/batch/policies.rb
 - lib/eco/api/session/batch/searcher.rb
 - lib/eco/api/session/batch/status.rb
+- lib/eco/api/session/concurrency/bounded_worker_pool.rb
+- lib/eco/api/session/concurrency/retry_policy.rb
 - lib/eco/api/session/config.rb
 - lib/eco/api/session/config/api.rb
 - lib/eco/api/session/config/apis.rb