relaton 2.2.0.pre.alpha.1 → 3.0.0.pre.alpha.2

data/lib/relaton/cie/util.rb

@@ -0,0 +1,8 @@
+module Relaton
+  module Cie
+    module Util
+      extend Relaton::Bib::Util
+      PROGNAME = "relaton-cie".freeze
+    end
+  end
+end

data/lib/relaton/cie.rb

@@ -0,0 +1,29 @@
+require "nokogiri"
+# require "parslet"
+require "pubid"
+require "relaton/index"
+require "relaton/bib"
+# require "relaton_bib/name_parser"
+require_relative "version"
+require_relative "cie/util"
+require_relative "cie/item_data"
+require_relative "cie/item"
+require_relative "cie/bibitem"
+require_relative "cie/bibdata"
+require_relative "cie/bibliography"
+require_relative "cie/scrapper"
+
+module Relaton
+  module Cie
+    INDEXFILE = "index-v2".freeze
+
+    # Returns hash of XML reammar
+    # @return [String]
+    def self.grammar_hash
+      # gem_path = File.expand_path "..", __dir__
+      # grammars_path = File.join gem_path, "grammars", "*"
+      # grammars = Dir[grammars_path].sort.map { |gp| File.read gp }.join
+      Digest::MD5.hexdigest Relaton::VERSION # grammars
+    end
+  end
+end

data/lib/relaton/core/array_wrapper.rb

@@ -0,0 +1,20 @@
+module Relaton
+  module Core
+    module ArrayWrapper
+      #
+      # Wrap into Array if not Array
+      #
+      # @param [Object] content
+      #
+      # @return [Array<Object>]
+      #
+      def array(content)
+        case content
+        when Array then content
+        when nil then []
+        else [content]
+        end
+      end
+    end
+  end
+end

data/lib/relaton/core/data_fetcher.rb

@@ -0,0 +1,244 @@
+require "fileutils"
+
+module Relaton
+  module Core
+    class DataFetcher
+      # attr_accessor :docs
+      #
+      # Initialize fetcher
+      #
+      # @param [String] output path to output directory
+      # @param [String] format output format (yaml, xml, bibxml)
+      #
+      def initialize(output, format)
+        @output = output
+        @format = format
+        @ext = format.sub "bibxml", "xml"
+        @files = Set.new
+        # path => docid that reserved it, for #unique_output_file. Distinct
+        # from @files, which flavors use for their own duplicate handling:
+        # this one has to know WHICH document owns a path, not just that it
+        # is taken.
+        @file_docids = {}
+        # Paths this process wrote during this run; see #write_unique.
+        @written = Set.new
+        # Set true by a fetcher that writes from forked worker processes,
+        # where @file_docids cannot see a peer's claim. See #write_unique.
+        @cross_process = false
+        # @docs = []
+        @errors = Hash.new(true)
+      end
+
+      # API method for external service
+      #
+      # @return the value returned by the instance `#fetch`, so callers can act
+      #   on the outcome (e.g. relaton-iso returns whether it rebuilt).
+      def self.fetch(source = nil, output: "data", format: "yaml")
+        t1 = Time.now
+        puts "Started at: #{t1}"
+        FileUtils.mkdir_p output
+        result = new(output, format).fetch(source)
+        t2 = Time.now
+        puts "Stopped at: #{t2}"
+        puts "Done in: #{(t2 - t1).round} sec."
+        result
+      end
+
+      def fetch(source = nil)
+        raise NotImplementedError, "#{self.class}#fetch method must be implemented"
+      end
+
+      def gh_issue
+        return @gh_issue if defined? @gh_issue
+
+        channel = gh_issue_channel
+        if channel[0]
+          @gh_issue = Relaton::Logger::Channels::GhIssue.new(*channel)
+          Relaton.logger_pool[:gh_issue] = Relaton::Logger::Log.new(@gh_issue, levels: [:error])
+        end
+        @gh_issue
+      end
+
+      def gh_issue_channel
+        [ENV.fetch("GITHUB_REPOSITORY", nil), "Error fetching documents"]
+      end
+
+      def report_errors
+        gh_issue # register the channel before logging
+        @errors.select { |_, v| v }.each do |key, value|
+          # A String value IS the message: a specific, per-document failure
+          # such as an unparseable identifier, reported through this same
+          # channel without needing a per-flavor override. A boolean means
+          # "this field failed for every record" — what the flavors' own
+          # ERROR_KEYS track — and its message is derived from the key.
+          log_error value.is_a?(String) ? value : "Failed to fetch #{key}"
+        end
+        @gh_issue&.create_issue
+      end
+
+      def log_error(_msg)
+        raise NoMatchingPatternError, "#{self.class}#log_error method must be implemented"
+      end
+
+      # Most filesystems cap a single path component at 255 bytes.
+      MAX_BASENAME_BYTES = 255
+
+      # Create-or-fail. The failure is the point: it is how one process learns
+      # that another already holds a path. See #write_unique.
+      EXCLUSIVE = File::WRONLY | File::CREAT | File::EXCL
+
+      # @param [String] document ID
+      # @return [String] filename based on PubID identifier
+      #
+      # A docid can be pathologically long (pubid's `to_s` for amendment docs
+      # embeds the full "(Amendment to … as amended by …)" clause), which would
+      # make the basename exceed the OS limit and raise Errno::ENAMETOOLONG on
+      # write. When that happens, truncate the sanitized id and append a short
+      # digest of the full docid so the filename stays bounded, unique, and
+      # deterministic (every call site round-trips through this method).
+      def output_file(docid)
+        id = docid.downcase.gsub(/[.,\s\/:()-]+/, "-").delete_suffix("-")
+        ext = ".#{@ext}"
+        limit = MAX_BASENAME_BYTES - ext.bytesize
+        if id.bytesize > limit
+          require "digest"
+          suffix = "-#{Digest::SHA1.hexdigest(docid)[0, 12]}"
+          # `id` has no consecutive "-" (gsub collapsed runs above), so
+          # truncation leaves at most one trailing "-" — delete_suffix is
+          # enough and avoids a polynomial-ReDoS regex on the docid.
+          id = id.byteslice(0, limit - suffix.bytesize).scrub("").delete_suffix("-") + suffix
+        end
+        File.join @output, "#{id}#{ext}"
+      end
+
+      #
+      # Reserve a unique output path for `docid`.
+      #
+      # `output_file` sanitizes ".", ",", "/", ":", "(", ")", "-" and whitespace
+      # all to "-", so two DISTINCT docids can map to one path — live instance in
+      # relaton-data-iana: `rpki/signed-objects` and `rpki-signed-objects` both
+      # give `data/rpki-signed-objects.yaml`. A caller that merely warns and
+      # writes anyway leaves one file holding the wrong document for one of two
+      # index ids: a wrong answer, not a missing one.
+      #
+      # Returns `output_file(docid)` when that path is free, or when it is
+      # already held by this SAME docid — a genuine duplicate is the caller's
+      # business (skip / merge / last-wins), and this method must not turn one
+      # into two files. Only a real clash with a DIFFERENT docid gets a variant,
+      # suffixed with a digest of this docid so the name depends on the document
+      # and not on encounter order: adding a record never renames an existing
+      # file. (Which member of a clashing pair keeps the plain path does follow
+      # write order, which is stable for a given corpus.)
+      #
+      # @param [String] docid
+      # @return [String] path, reserved for this docid
+      #
+      def unique_output_file(docid)
+        file = output_file docid
+        owner = @file_docids[file]
+        file = digest_output_file(docid) unless owner.nil? || owner == docid
+        reserve file, docid
+      end
+
+      #
+      # Write `content` for `docid`, never clobbering a different document.
+      #
+      # `output_file` is not injective, so the plain path may belong to someone
+      # else. `unique_output_file` settles that within this process; the file is
+      # then created with `O_EXCL` so a peer *process* cannot be clobbered
+      # either. Returns the path actually written.
+      #
+      # The four outcomes, each load-bearing:
+      #
+      # * **We already wrote this path for this docid** — plain overwrite, so a
+      #   genuine duplicate stays one file and the flavor's own duplicate
+      #   handling (skip / merge / last-wins) still decides what happens.
+      # * **`O_EXCL` succeeds** — the normal case.
+      # * **`EEXIST`, single process** — `unique_output_file` has already proved
+      #   that no peer of ours holds this path, so the file can only be a
+      #   leftover from an earlier crawl. Overwrite it. Every single-process
+      #   flavor takes this branch, and it involves no guesswork.
+      # * **`EEXIST`, `@cross_process`** — a peer's file and a leftover are
+      #   indistinguishable, so take a path of our own rather than risk
+      #   destroying a record. The caller reconciles the names afterwards, in
+      #   the parent, where it can see every docid (see
+      #   `Relaton::Ietf::DataFetcher#reconcile_output_files`).
+      #
+      # Deliberately NOT a wall-clock "is this file older than the crawl?" test.
+      # A crawl runs into a populated `data/`, so `EEXIST` is the common case on
+      # a re-run and such a test would decide it for every record; its
+      # false-"stale" direction is the silent overwrite this method exists to
+      # prevent, and coarse filesystem mtime granularity makes that reachable.
+      #
+      # @param [String] docid
+      # @param [String] content serialized document
+      # @return [String] path written
+      #
+      def write_unique(docid, content)
+        file = unique_output_file docid
+        return force_write(file, content) if @written.include?(file)
+
+        File.write file, content, mode: EXCLUSIVE, encoding: "UTF-8"
+        @written << file
+        file
+      rescue Errno::EEXIST
+        return force_write(file, content) unless @cross_process
+
+        force_write reserve(digest_output_file(docid), docid), content
+      end
+
+      #
+      # Serialize bibliographic item
+      #
+      # @param [RelatonCcsds::BibliographicItem] bib <description>
+      #
+      # @return [String] serialized bibliographic item
+      #
+      def serialize(bib)
+        send "to_#{@format}", bib
+      end
+
+      def to_yaml(bib)
+        raise NotImplementedError, "#{self.class}#to_yaml method must be implemented"
+      end
+
+      def to_xml(bib)
+        raise NotImplementedError, "#{self.class}#to_xml method must be implemented"
+      end
+
+      def to_bibxml(bib)
+        raise NotImplementedError, "#{self.class}#to_bibxml method must be implemented"
+      end
+
+      private
+
+      # Write, clobbering whatever is there. The caller has already established
+      # that the path is ours to take.
+      def force_write(file, content)
+        File.write file, content, encoding: "UTF-8"
+        @written << file
+        file
+      end
+
+      # Record `docid` as the owner of `file`, unless someone got there first,
+      # and return `file`. The reservation table must never hand one path to two
+      # documents; see #unique_output_file.
+      def reserve(file, docid)
+        @file_docids[file] ||= docid
+        file
+      end
+
+      # `output_file`'s path with a docid digest appended to the basename, kept
+      # inside the same byte cap. Deterministic: same docid, same name.
+      def digest_output_file(docid)
+        require "digest"
+        ext = ".#{@ext}"
+        suffix = "-#{Digest::SHA1.hexdigest(docid)[0, 12]}"
+        stem = File.basename output_file(docid), ext
+        limit = MAX_BASENAME_BYTES - ext.bytesize - suffix.bytesize
+        stem = stem.byteslice(0, limit).scrub("").delete_suffix("-") if stem.bytesize > limit
+        File.join @output, "#{stem}#{suffix}#{ext}"
+      end
+    end
+  end
+end

data/lib/relaton/core/date_parser.rb

@@ -0,0 +1,42 @@
+module Relaton
+  module Core
+    module DateParser
+      # @param date [String, Integer, Date] date
+      # @param str [Boolean] return string or Date
+      # @return [Date, String, nil] date
+      def parse_date(date, str: true) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
+        return date if date.is_a?(Date)
+
+        case date.to_s
+        when /(?<date>\w+\s\d{4})/ # February 2012
+          format_date $~[:date], "%B %Y", str, "%Y-%m"
+        when /(?<date>\w+\s\d{1,2},\s\d{4})/ # February 11, 2012
+          format_date $~[:date], "%B %d, %Y", str, "%Y-%m-%d"
+        when /(?<date>\d{4}-\d{1,2}-\d{1,2})/ # 2012-02-03 or 2012-2-3
+          format_date $~[:date], "%Y-%m-%d", str
+        when /(?<date>\d{4}-\d{1,2})/ # 2012-02 or 2012-2
+          format_date $~[:date], "%Y-%m", str
+        when /(?<date>\d{4})/ # 2012
+          format_date $~[:date], "%Y", str
+        end
+      end
+
+      private
+
+      #
+      # Parse date string to Date object and format it
+      #
+      # @param [String] date date string
+      # @param [String] format format string
+      # @param [Boolean] str return string if true in other case return Date
+      # @param [String, nil] outformat output format
+      #
+      # @return [Date, String] date object or formatted date string
+      #
+      def format_date(date, format, str, outformat = nil)
+        date = Date.strptime(date, format)
+        str ? date.strftime(outformat || format) : date
+      end
+    end
+  end
+end

data/lib/relaton/core/governor.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "time" # Time.parse, for an HTTP-date Retry-After
+
+module Relaton
+  module Core
+    #
+    # Process-wide, thread-safe rate-limit back-pressure for a crawl.
+    #
+    # Promoted here from `Relaton::W3c::Governor`, which is now a thin binding
+    # of it, when the ITU-R crawler became the second flavor to need
+    # cross-thread throttling. What stays with a flavor is only which errors
+    # mean "throttled" (THROTTLE_ERRORS / .throttle?) and which env vars tune it
+    # (ENV_PREFIX); the ladder, the jitter, the give-up latch and the
+    # Retry-After parsing are shared.
+    #
+    # The problem it solves, as first met on api.w3.org: that host sits behind
+    # Cloudflare, whose rate limiting is bimodal — a run either never trips it
+    # or trips it and stays banned for hours. Before this
+    # existed, each of the crawl's workers reacted to its own 429s in isolation
+    # with a backoff capped at ~31s — far too short to outlast the ban, and the
+    # retries themselves kept the limiter engaged. The Aug-2026 crawl spent 4h56m
+    # doing nothing but re-tripping the limiter, permanently discarding 1,412
+    # documents, before it aborted.
+    #
+    # The governor gives the whole worker pool one shared cooldown. When any
+    # thread sees a 429 it opens (or extends) that cooldown; every other thread
+    # observes it in #wait. Cooldowns escalate per *round* — 60s, 120s, ... to a
+    # 15-minute cap — and after GIVE_UP_AFTER consecutive rounds without a single
+    # success the crawl is declared rate-limited and gives up (~15 min) so CI
+    # fails fast instead of grinding for five hours.
+    #
+    # `clock:` and `sleeper:` are injectable so specs exercise the real
+    # arithmetic without wall-clock waits.
+    #
+    class Governor
+      # First cooldown, in seconds. Deliberately minute-scale: a Cloudflare ban
+      # window outlasts any second-scale backoff.
+      BASE_COOLDOWN = 60
+
+      # Ceiling for a single cooldown, including a server-supplied Retry-After
+      # (which must not be able to park a worker for an hour).
+      MAX_COOLDOWN = 900
+
+      # Consecutive throttle rounds with no intervening success before the crawl
+      # is considered banned. With the ladder above that is ~15 min of cooldown
+      # (60+120+240+480 s; the fifth round latches before its own wait).
+      GIVE_UP_AFTER = 5
+
+      # Fraction of the cooldown added as random jitter, so the workers do not
+      # all resume on the same instant and immediately re-trip the limiter.
+      JITTER_FRACTION = 0.1
+
+      # Which errors mean "you are being rate-limited", as opposed to "this
+      # resource is broken". Core ships none: the distinction is the one thing
+      # only the flavor knows, and getting it wrong in either direction is
+      # expensive — a broken resource routed here opens a pool-wide cooldown
+      # for one bad record, and a throttle routed the other way gets recorded
+      # as permanent data loss (which is exactly what the W3C crawl did before
+      # this class existed). Subclasses override the constant, or #throttle?
+      # when the signal is a status code rather than an exception class.
+      THROTTLE_ERRORS = [].freeze
+
+      # Prefix for the three duration knobs, so two flavors crawling in one
+      # process cannot share a cooldown ladder by accident. A subclass sets its
+      # own ("RELATON_W3C", "RELATON_ITU"); the suffixes are fixed.
+      ENV_PREFIX = "RELATON"
+
+      # Whether this error means the server is rate-limiting us.
+      #
+      # Class membership is the common case. A flavor whose server signals
+      # throttling with a *status code* on a shared exception class (ITU: 503 on
+      # /rec) overrides this instead of the constant.
+      #
+      # @param error [StandardError]
+      # @return [Boolean]
+      def self.throttle?(error)
+        self::THROTTLE_ERRORS.any? { |klass| error.is_a? klass }
+      end
+
+      attr_reader :base, :max, :give_up_after, :env_prefix
+
+      def initialize(base: nil, max: nil, give_up_after: nil,
+                     clock: nil, sleeper: nil, jitter: nil, env_prefix: nil)
+        @env_prefix = env_prefix || self.class::ENV_PREFIX
+        # Remembered so #reset! can re-read the env knobs for the next crawl
+        # without discarding values a caller passed explicitly.
+        @overrides = { base: base, max: max, give_up_after: give_up_after }
+        load_limits
+        @clock = clock || -> { Time.now }
+        @sleeper = sleeper || ->(secs) { sleep secs }
+        @jitter = jitter || ->(secs) { Kernel.rand * secs * self.class::JITTER_FRACTION }
+        @mutex = Mutex.new
+        @cooldown_until = nil
+        @penalty = nil
+        @rounds = 0
+        @events = 0
+        @abandoned = false
+        @abandoned_rounds = nil
+      end
+
+      #
+      # Block until the shared cooldown expires. Called before every request.
+      #
+      # The mutex is never held across the sleep — the deadline is read under
+      # the lock and the sleeping happens outside it, so a cooling-down worker
+      # cannot block another thread from recording its own throttle.
+      #
+      # @return [Numeric] seconds actually slept (0.0 when there was nothing to
+      #   wait for, including once the crawl has given up)
+      #
+      def wait
+        slept = 0.0
+        waited_for = nil
+        loop do
+          # Once we have given up there is nothing left to wait for, and stalling
+          # here would delay the shutdown by up to a full cooldown.
+          deadline, remaining = @mutex.synchronize do
+            gave_up? ? [nil, 0.0] : [@cooldown_until, cooldown_remaining]
+          end
+          break unless remaining.positive?
+          # Re-check after sleeping so a cooldown *extended* mid-round (a later
+          # Retry-After asking for longer) also holds back the workers already
+          # sleeping — they would otherwise wake on the stale deadline and
+          # re-trip the limiter. Looping only on a later deadline keeps a stalled
+          # clock from spinning here.
+          break if waited_for && deadline && deadline <= waited_for
+
+          waited_for = deadline
+          delay = remaining + @jitter.call(remaining)
+          @sleeper.call(delay)
+          slept += delay
+        end
+        slept
+      end
+
+      #
+      # Record a 429 and open/extend the shared cooldown.
+      #
+      # @param retry_after [Integer, nil] seconds from the response's Retry-After
+      #
+      # @return [Boolean] true when the crawl should give up
+      #
+      def throttled!(retry_after: nil)
+        @mutex.synchronize do
+          now = @clock.call
+          @events += 1
+          if @cooldown_until.nil? || now >= @cooldown_until
+            open_round(now, retry_after)
+          elsif retry_after
+            # Mid-round, the server may still ask for longer than we planned.
+            extend_round(now + capped(retry_after))
+          end
+          # Giving up latches. Otherwise a straggler worker succeeding after the
+          # producer already stopped paginating would clear @rounds and let the
+          # crawl save the truncated index it just decided to abandon.
+          #
+          # @rounds is snapshotted at the same moment, because #succeeded!
+          # resets it: read afterwards it names whatever has re-accumulated
+          # since, not the threshold that was crossed. The abort message is
+          # the only place an operator learns why the crawl stopped.
+          unless @abandoned
+            @abandoned = @rounds >= @give_up_after
+            @abandoned_rounds = @rounds if @abandoned
+          end
+          @abandoned
+        end
+      end
+
+      #
+      # Record a successful request: the limiter has released us.
+      #
+      def succeeded!
+        @mutex.synchronize do
+          @rounds = 0
+          @cooldown_until = nil
+          # Decay rather than reset, so a limiter that keeps flapping still
+          # climbs the ladder instead of restarting at `base` every time.
+          @penalty = @penalty && @penalty > @base ? [@penalty / 2.0, @base].max : nil
+        end
+      end
+
+      # @return [Boolean] give_up_after consecutive rounds passed with no success
+      def exhausted?
+        @mutex.synchronize { gave_up? }
+      end
+
+      # Clear all state for a fresh crawl. Resets in place rather than handing
+      # back a new object so callers (and specs) holding this instance keep
+      # observing the live governor.
+      def reset!
+        @mutex.synchronize do
+          load_limits
+          @cooldown_until = nil
+          @penalty = nil
+          @rounds = 0
+          @events = 0
+          @abandoned = false
+          @abandoned_rounds = nil
+        end
+      end
+
+      # @return [Integer] consecutive throttle rounds since the last success
+      def throttle_rounds
+        @mutex.synchronize { @rounds }
+      end
+
+      # The consecutive-round count as it stood when the give-up latched, for
+      # the abort message. Distinct from #throttle_rounds, which stays LIVE
+      # because a crawler logs it per retry as the current round (see
+      # Relaton::Itu::DataCrawlerR) and #succeeded! resets it.
+      #
+      # @return [Integer, nil] nil while the crawl is still running
+      def give_up_rounds
+        @mutex.synchronize { @abandoned_rounds }
+      end
+
+      # @return [Integer] every 429 observed, for reporting
+      def throttle_count
+        @mutex.synchronize { @events }
+      end
+
+      #
+      # Seconds requested by a rate-limited response's Retry-After header.
+      #
+      # lutaml-hal >= 0.2.5 carries a `{ status:, headers: }` hash on every error
+      # mapped from a response (nil for locally raised ones), so anything without
+      # one yields nil.
+      #
+      # @param error [StandardError]
+      #
+      # @return [Integer, nil]
+      #
+      def self.retry_after(error)
+        return nil unless error.respond_to?(:response)
+
+        response = error.response
+        headers = response.is_a?(Hash) ? (response[:headers] || response["headers"]) : nil
+        return nil unless headers.respond_to?(:[])
+
+        seconds_from headers["retry-after"] || headers["Retry-After"]
+      end
+
+      #
+      # Retry-After is either delta-seconds or an HTTP-date (RFC 9110). The date
+      # form is parsed properly rather than by scanning digits, which would pick
+      # up the day-of-month and back off for a wildly wrong duration; a date
+      # already in the past yields 0, i.e. "no extra floor".
+      #
+      def self.seconds_from(value)
+        str = value.to_s.strip
+        return nil if str.empty?
+        return str.to_i if str.match?(/\A\d+\z/)
+
+        begin
+          [(Time.parse(str) - Time.now).ceil, 0].max
+        rescue ArgumentError
+          nil
+        end
+      end
+
+      # A blank or non-positive override is treated as unset.
+      def self.env_int(name, default)
+        value = ENV[name].to_s.strip
+        return default if value.empty?
+
+        parsed = value.to_i
+        parsed.positive? ? parsed : default
+      end
+
+      private
+
+      # "<PREFIX>_THROTTLE_<SUFFIX>", the one thing ENV_PREFIX exists for.
+      def env_name(suffix)
+        "#{@env_prefix}_THROTTLE_#{suffix}"
+      end
+
+      # Read the duration knobs, letting explicit constructor args win over the
+      # environment. Re-read on #reset! so the env vars behave like a flavor's
+      # sibling knobs, which are class methods evaluated per crawl rather than
+      # frozen when the flavor was autoloaded.
+      def load_limits
+        @base = @overrides[:base] || self.class.env_int(env_name("BASE"), self.class::BASE_COOLDOWN)
+        @max = @overrides[:max] || self.class.env_int(env_name("MAX"), self.class::MAX_COOLDOWN)
+        @give_up_after = @overrides[:give_up_after] ||
+          self.class.env_int(env_name("GIVEUP"), self.class::GIVE_UP_AFTER)
+      end
+
+      # Start a new escalation step. Retry-After raises the floor but never
+      # lowers our own ladder — the server's hint is a minimum, not a discount.
+      def open_round(now, retry_after)
+        @rounds += 1
+        ladder = @penalty ? [@penalty * 2, @max].min : @base
+        hint = retry_after ? capped(retry_after) : 0
+        @penalty = [ladder, hint].max
+        @cooldown_until = now + @penalty
+      end
+
+      def extend_round(deadline)
+        @cooldown_until = deadline if deadline > @cooldown_until
+      end
+
+      def cooldown_remaining
+        return 0.0 unless @cooldown_until
+
+        [@cooldown_until - @clock.call, 0.0].max
+      end
+
+      def capped(seconds)
+        [seconds, @max].min
+      end
+
+      # Callers must already hold the mutex. Latched by #throttled! — never
+      # recomputed from @rounds, which #succeeded! resets.
+      def gave_up?
+        @abandoned
+      end
+    end
+  end
+end

data/lib/relaton/core/hash_keys_sybolizer.rb

@@ -0,0 +1,19 @@
+module Relaton
+  module Core
+    module HashKeysSymbolizer
+      def symbolize_hash_keys(obj)
+        case obj
+        when Array
+          obj.map { |e| symbolize_hash_keys(e) }
+        when Hash
+          obj.each_with_object({}) do |(k, v), h|
+            key = k.is_a?(String) ? k.to_sym : k
+            h[key] = symbolize_hash_keys(v)
+          end
+        else
+          obj
+        end
+      end
+    end
+  end
+end