forest_admin_datasource_pylon 1.41.0

data/lib/forest_admin_datasource_pylon/query/condition_tree_translator.rb

@@ -0,0 +1,151 @@
+module ForestAdminDatasourcePylon
+  module Query
+    # See https://docs.usepylon.com/pylon-docs/developer/api/api-reference/issues
+    #
+    # Translates a Forest condition tree into the structured JSON filter of
+    # `POST /issues/search`:
+    #
+    #   leaf   -> { 'field' => …, 'operator' => …, 'value' | 'values' => … }
+    #   branch -> { 'operator' => 'and' | 'or', 'subfilters' => [...] }
+    #
+    # Pylon nests sub-filters, so — unlike the Zendesk query string — OR is
+    # translated natively instead of being rejected.
+    #
+    # Anything the API cannot express raises UnsupportedOperatorError: a filter
+    # that is dropped returns unfiltered rows which look filtered. The wire
+    # format of the values, and the refusals that go with it, live in FilterValue.
+    class ConditionTreeTranslator
+      Branch = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeBranch
+      Leaf   = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+
+      # Pylon rejects sub-filters nested deeper than three levels.
+      MAX_DEPTH = 3
+
+      LIST_OPERATORS      = %w[in not_in].freeze
+      VALUELESS_OPERATORS = %w[is_set is_unset].freeze
+
+      # The comparisons Pylon reads as a moment in time: what tells FilterValue
+      # that a bare date is a date, and not a piece of text a field happens to
+      # hold. Read off the emitted operator rather than off the column type,
+      # which the translator does not see -- and it is the operator that decides
+      # the format anyway.
+      TIME_OPERATORS      = %w[time_is_after time_is_before].freeze
+
+      def self.call(condition_tree, api_filters: {}, timezone: nil)
+        return nil if condition_tree.nil?
+
+        new(api_filters: api_filters, timezone: timezone).translate(condition_tree)
+      end
+
+      def initialize(api_filters: {}, timezone: nil)
+        @api_filters = api_filters || {}
+        @value = FilterValue.new(timezone: timezone)
+      end
+
+      def translate(node, depth = 1)
+        case node
+        when Branch then translate_branch(node, depth)
+        when Leaf   then translate_leaf(node)
+        else
+          raise UnsupportedOperatorError, "Unknown condition node: #{node.class}"
+        end
+      end
+
+      private
+
+      def translate_branch(branch, depth)
+        conditions = Array(branch.conditions)
+        if conditions.empty?
+          raise UnsupportedOperatorError, "Condition tree aggregator '#{branch.aggregator}' carries no condition."
+        end
+
+        # Validated before the unwrap below, so a branch is refused on the
+        # aggregator it carries rather than on how many conditions it holds.
+        operator = aggregator(branch)
+
+        # A lone condition needs no wrapper, and spending no nesting level on it
+        # keeps trees the agent builds one branch at a time under Pylon's cap.
+        return translate(conditions.first, depth) if conditions.size == 1
+
+        raise_too_deep(depth) if depth > MAX_DEPTH
+
+        { 'operator' => operator,
+          'subfilters' => conditions.map { |condition| translate(condition, depth + 1) } }
+      end
+
+      def aggregator(branch)
+        value = branch.aggregator.to_s.downcase
+        return value if %w[and or].include?(value)
+
+        raise UnsupportedOperatorError,
+              "Unknown condition tree aggregator #{branch.aggregator.inspect}; expected 'And' or 'Or'."
+      end
+
+      def translate_leaf(leaf)
+        spec = @api_filters[leaf.field]
+        raise_unfilterable_field(leaf.field) unless spec
+
+        operator = spec[:ops][leaf.operator]
+        raise_unsupported_operator(leaf, spec) unless operator
+        ensure_filterable_absence!(leaf, spec)
+
+        with_value({ 'field' => (spec[:param] || leaf.field).to_s, 'operator' => operator }, operator, leaf)
+      end
+
+      def with_value(filter, operator, leaf)
+        return filter if VALUELESS_OPERATORS.include?(operator)
+        return filter.merge('values' => @value.list(leaf)) if LIST_OPERATORS.include?(operator)
+
+        filter.merge('value' => @value.single(leaf, time: TIME_OPERATORS.include?(operator)))
+      end
+
+      # `present`, `blank` and `missing` are advertised on every field carrying
+      # an equality or a membership filter: the agent derives them from those
+      # above the datasource and rewrites them into a comparison with an empty
+      # value. Only a field the API reference documents `is_set` / `is_unset` on
+      # can answer one, and it answers it through those operators, never through
+      # the rewritten comparison -- which Pylon would match against the empty
+      # value as if it were a value of its own.
+      #
+      # Refused here rather than in FilterValue, which sees the empty value but
+      # not whether the field has a presence filter to answer it with.
+      def ensure_filterable_absence!(leaf, spec)
+        return unless absence_condition?(leaf)
+        return if spec[:ops].values.any? { |candidate| VALUELESS_OPERATORS.include?(candidate) }
+
+        raise UnsupportedOperatorError,
+              "Pylon cannot filter '#{leaf.field}' for absence: the field carries no is_set / is_unset filter " \
+              'in the Pylon API reference, so a present, blank or missing condition on it cannot be translated. ' \
+              'Filter for absence on a field that does, or filter on a value instead.'
+      end
+
+      # The shape the absence operators are rewritten into: a nil value, or a
+      # list holding nothing but blanks. An empty list is not one of them -- it
+      # comes from a filter carrying no value at all, which FilterValue reports.
+      def absence_condition?(leaf)
+        return true if leaf.value.nil?
+        return false unless leaf.value.is_a?(Array) && leaf.value.any?
+
+        leaf.value.all? { |value| value.nil? || value.to_s.empty? }
+      end
+
+      def raise_too_deep(depth)
+        raise UnsupportedOperatorError,
+              "Pylon rejects a filter nested deeper than #{MAX_DEPTH} levels (reached #{depth}); " \
+              'flatten the segment or the filter.'
+      end
+
+      def raise_unfilterable_field(field)
+        raise UnsupportedOperatorError,
+              "Pylon cannot filter on '#{field}'; add it to the collection's api_filters " \
+              'after checking it against the Pylon API reference.'
+      end
+
+      def raise_unsupported_operator(leaf, spec)
+        raise UnsupportedOperatorError,
+              "Operator '#{leaf.operator}' is not supported on field '#{leaf.field}'. " \
+              "Supported: #{spec[:ops].keys.join(", ")}."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/query/filter_value.rb

@@ -0,0 +1,135 @@
+require 'date'
+require 'active_support/core_ext/time/zones'
+
+module ForestAdminDatasourcePylon
+  module Query
+    # How a Forest filter value reaches the wire, and every way it can fail to.
+    # Split from the translator, which knows the shape of the condition tree but
+    # not the format of what the leaves carry.
+    class FilterValue
+      # A date carrying no time of day, which is what the frontend sends for a
+      # Dateonly column -- a shape only a custom field has, no native column
+      # being typed that way.
+      DATE_ONLY = /\A\d{4}-\d{2}-\d{2}\z/
+
+      # The identifier is stored stripped, not only checked stripped: kept as it
+      # came, a `" Europe/Paris "` passes the blank guard and then fails the zone
+      # lookup, and `format_date` falls back to UTC -- a day boundary quietly off
+      # by the offset, which is the failure this guard exists to prevent.
+      def initialize(timezone: nil)
+        identifier = timezone.to_s.strip
+
+        @timezone = identifier.empty? ? 'UTC' : identifier
+      end
+
+      # `time` says the operator this value travels with is one of Pylon's time
+      # comparisons, which is what decides whether a bare date is a date or a
+      # piece of text: the same string on a text field is a value of its own.
+      def single(leaf, time: false)
+        raise_nil_value(leaf.field) if leaf.value.nil?
+
+        format(leaf.value, time: time, field: leaf.field)
+      end
+
+      # Dropping the blanks would silently answer a different question: `not_in
+      # [nil, 'open']` was asked to exclude the blank records and would come
+      # back including them. An empty list is just as bad the other way round,
+      # translating to a filter matching everything.
+      #
+      # No time comparison takes a list, so nothing here is read as a date.
+      def list(leaf)
+        values = Array(leaf.value)
+        raise_empty_list(leaf) if values.empty?
+        raise_blank_in_list(leaf) if values.any? { |value| value.nil? || value.to_s.empty? }
+
+        values.map { |value| format(value, field: leaf.field) }
+      end
+
+      private
+
+      # Booleans travel as they are: the filter is JSON, not a query string, so
+      # only the dates and the numbers the agent widened need a wire format.
+      def format(value, time: false, field: nil)
+        case value
+        when Time, DateTime then value.to_time.utc.iso8601
+        when Date           then format_date(value)
+        when Float          then format_float(value, field)
+        when String         then time ? format_time_string(value) : value
+        else                     value
+        end
+      end
+
+      # The agent casts every Number column with `to_f`
+      # (`ConditionTreeParser.cast_to_type`), so an integer custom field would be
+      # filtered with `42.0` -- a form none of its values carry. A float with
+      # nothing after the point travels as the integer it is; a decimal keeps its
+      # own.
+      #
+      # A cast that overflowed to Infinity, or a NaN, is refused rather than
+      # passed on: `to_i` raises on both, and so does the JSON encoder a step
+      # later, either way as a 500 naming nothing the operator can act on.
+      def format_float(value, field)
+        raise_out_of_range(value, field) unless value.finite?
+
+        value == value.to_i ? value.to_i : value
+      end
+
+      # `time_is_after` receives a timestamp everywhere else in this datasource,
+      # a native date column being read and filtered as one: a Dateonly custom
+      # field cannot be the one field sending the same operator another shape.
+      # The bound is the one a Ruby `Date` already gets -- midnight in the
+      # timezone of the caller.
+      #
+      # A string this operator cannot read as a date is left to Pylon, which
+      # names what it refuses better than a guess here would.
+      def format_time_string(value)
+        return value unless DATE_ONLY.match?(value)
+
+        format_date(Date.parse(value))
+      rescue Date::Error
+        value
+      end
+
+      # Only reached by a condition tree built in Ruby -- a segment or a scope
+      # written as code -- and by the bare date above. Everything else coming
+      # through HTTP arrives as an ISO8601 timestamp, already expressed in the
+      # timezone of the caller: the agent casts a date filter with `value.to_s`,
+      # and the toolkit formats the bounds it derives from Today / Previous*
+      # itself.
+      def format_date(value)
+        Time.use_zone(@timezone) { Time.zone.local(value.year, value.month, value.day).utc.iso8601 }
+      rescue ArgumentError
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] unknown timezone '#{@timezone}', falling back to UTC"
+        )
+        value.strftime('%Y-%m-%dT00:00:00Z')
+      end
+
+      # A filter carrying a nil value reads as a presence check on most APIs,
+      # which is silently the wrong query.
+      def raise_nil_value(field)
+        raise UnsupportedOperatorError,
+              "Filter value on '#{field}' is nil; use the PRESENT or BLANK operator to filter for absence."
+      end
+
+      def raise_blank_in_list(leaf)
+        raise UnsupportedOperatorError,
+              "Operator '#{leaf.operator}' on field '#{leaf.field}' was given a list holding a blank value; " \
+              'Pylon matches an absent value through is_set / is_unset only, so filter for absence with the ' \
+              'PRESENT or BLANK operator rather than listing nil or an empty string.'
+      end
+
+      def raise_empty_list(leaf)
+        raise UnsupportedOperatorError,
+              "Operator '#{leaf.operator}' on field '#{leaf.field}' was given an empty list; " \
+              'pass at least one value.'
+      end
+
+      def raise_out_of_range(value, field)
+        raise UnsupportedOperatorError,
+              "Filter value on '#{field}' is #{value}, which is not a number Pylon can be asked for; " \
+              'filter with a value inside the range of a double.'
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/query/operator_maps.rb

@@ -0,0 +1,108 @@
+module ForestAdminDatasourcePylon
+  module Query
+    # The operator maps the Pylon search endpoints share. A map spells each
+    # Forest operator as the Pylon operator honouring it; a collection's
+    # `API_FILTERS` table then assembles, field by field, the maps its endpoint
+    # accepts according to the API reference.
+    #
+    # Sharing the maps is what keeps those tables readable as the allow-lists
+    # they transcribe, and keeps one wire spelling from being fixed in one
+    # collection and left wrong in the next.
+    module OperatorMaps
+      Operators = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+
+      # `not_equal` is deliberately absent: the toolkit derives it from
+      # `not_in`, so declaring it would only add a second spelling.
+      EQUALITY = { Operators::EQUAL => 'equals',
+                   Operators::IN => 'in',
+                   Operators::NOT_IN => 'not_in' }.freeze
+
+      # MISSING is mapped as well although Pylon spells absence one way only:
+      # the toolkit rewrites it into `equal nil` when it is left out, which the
+      # translator cannot express, so a field the API does check for absence
+      # would refuse the very filter it can answer.
+      PRESENCE = { Operators::PRESENT => 'is_set',
+                   Operators::BLANK => 'is_unset',
+                   Operators::MISSING => 'is_unset' }.freeze
+
+      # Declaring the bare comparisons rather than before/after is what lets
+      # the toolkit rewrite Today / PreviousWeek / ... into a pair of bounds,
+      # which is also why `time_range` never has to be emitted.
+      TIME = { Operators::GREATER_THAN => 'time_is_after',
+               Operators::LESS_THAN => 'time_is_before' }.freeze
+
+      # Pylon exposes a single substring operator and documents no case
+      # semantics for it, so both Forest spellings map onto that one operator --
+      # or the UI would offer a case-sensitive "contains" and a case-insensitive
+      # one behaving identically.
+      SUBSTRING = { Operators::CONTAINS => 'string_contains',
+                    Operators::I_CONTAINS => 'string_contains' }.freeze
+
+      # The same, for the endpoints that also accept the negation. A field
+      # filtered through SUBSTRING alone must not advertise it: Pylon rejects
+      # `string_does_not_contain` where it is not documented.
+      FULL_TEXT = SUBSTRING.merge(Operators::NOT_CONTAINS => 'string_does_not_contain',
+                                  Operators::NOT_I_CONTAINS => 'string_does_not_contain').freeze
+
+      # A list-valued field -- `tags`, `domains`: `in` matches it against
+      # several candidates at once.
+      #
+      # Pylon also accepts `contains` / `does_not_contain` on such a field, and
+      # they are deliberately left out: the columns are typed `Json`, the only
+      # type the toolkit has for a list, and `Rules` allows a Json column the
+      # base and array operators alone. A declared `contains` would be refused
+      # by `ConditionTreeValidator` on the way in -- "the given operator
+      # 'contains' is not allowed with the columnType schema: 'Json'" -- so the
+      # UI would offer a filter that errors instead of one Pylon answers.
+      # Typing the columns `['String']` is not the way out either: no branch of
+      # `get_allowed_operators_for_column_type` reads an array type, and the
+      # validator raises a NoMethodError on it. Reaching those two operators
+      # takes a toolkit change, which is not this datasource's to make here.
+      MEMBERSHIP = { Operators::IN => 'in',
+                     Operators::NOT_IN => 'not_in' }.freeze
+
+      # A custom field is filtered through its slug, so its operators come from
+      # the column the integrator declared rather than from a table; every
+      # search endpoint accepts this same set on one.
+      CUSTOM_FIELD_OPS = EQUALITY.merge(PRESENCE).merge(TIME).merge(FULL_TEXT).freeze
+
+      # Extended by a collection's `ApiFilters` module, whose `API_FILTERS` is
+      # the single source of truth for what its endpoint filters: the schema
+      # derives every column's `filter_operators` from it, so no collection
+      # declares a filter the translator would then refuse.
+      #
+      # One family escapes those tables. The agent derives `present`, `blank` and
+      # `missing` from an equality or a membership filter, above the datasource,
+      # and rewrites them into a comparison with an empty value. Only a field
+      # carrying PRESENCE can answer one -- Pylon matches an absent value through
+      # `is_set` / `is_unset` alone -- so on every other field the translator
+      # refuses the rewritten condition and names the filter to change, rather
+      # than sending a comparison Pylon would answer as if the empty value were
+      # a value of its own.
+      module Table
+        def forest_operators(field)
+          self::API_FILTERS.dig(field, :ops)&.keys || []
+        end
+
+        # Read off the extending module rather than off this one, so the
+        # `CUSTOM_FIELD_OPS` a collection declares is the single source both
+        # this spelling and `allowed_custom_field_operators` come from: an
+        # endpoint accepting less on a custom field narrows one constant.
+        def for_custom_field(schema)
+          { ops: self::CUSTOM_FIELD_OPS.slice(*Array(schema&.filter_operators)) }
+        end
+      end
+
+      # The table of a collection whose endpoint filters nothing server-side: no
+      # field, and no operator on a custom field either. It is the default of
+      # `BaseCollection#filter_table`, so a collection read whole and filtered
+      # in memory needs no table of its own.
+      module EmptyTable
+        extend Table
+
+        API_FILTERS      = {}.freeze
+        CUSTOM_FIELD_OPS = {}.freeze
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/rate_limiter.rb

@@ -0,0 +1,139 @@
+module ForestAdminDatasourcePylon
+  # Spaces requests out so the budget of an endpoint is spent rather than
+  # exceeded: a sliding window per endpoint, and a wait until the next slot when
+  # the window is full.
+  #
+  # This sits in front of the 429 retry rather than replacing it. The retry
+  # answers a 429 Pylon already sent, which costs a full rate-limit window to
+  # recover from (Retry-After runs up to 60s); waiting half a second for a slot
+  # is the same throughput at a fraction of the latency. The retry stays as the
+  # backstop for what this cannot see — another process, or another agent, on
+  # the same token.
+  #
+  # One limiter per Configuration, so per token: Pylon meters the token, and two
+  # agents holding different ones do not share a budget.
+  class RateLimiter
+    WINDOW = 60.0
+
+    # How long one attempt may be held back before it is let through anyway. The
+    # limiter exists to avoid a 429, not to guarantee one never happens: past
+    # this point the window is saturated by more than this agent's own traffic,
+    # so queueing behind it would trade a retry the client already handles for a
+    # request the operator watches spin. It goes out, and the warning says why.
+    #
+    # Per attempt, not per request: `retry` replays up to `max_retries` times and
+    # each replay asks for a slot of its own, so a request can spend this bound
+    # once per attempt, on top of the backoff `retry` waits itself. None of it
+    # runs under the Faraday timeout, which only covers the adapter.
+    #
+    # The region this smooths is narrow, and it is worth being plain about it.
+    # On a stream over budget the waits accumulate rather than settling, so the
+    # bound is crossed sooner the further over it sits: measured against a
+    # 120/min endpoint, a stream 1% over budget throttles its first thousand
+    # requests and then lets roughly one in twelve through unthrottled, one 5%
+    # over gives up after two hundred and lets half through, and past ~10% over
+    # the bound is crossed as soon as the window fills — request 121 — after
+    # which almost nothing is throttled at all. A burst arriving at once books
+    # its next slot a whole window out and goes straight through from the first
+    # request past the budget. Under real saturation the 429 retry is the
+    # defence, not this; what this buys is the region just over budget, and a
+    # budget the code knows rather than one it discovers as a 429.
+    DEFAULT_MAX_WAIT = 5.0
+
+    attr_reader :max_wait, :window
+
+    def initialize(limits: RateLimits, window: WINDOW, max_wait: DEFAULT_MAX_WAIT, clock: nil, sleeper: nil)
+      @limits  = limits
+      @window  = window.to_f
+      @max_wait = max_wait.to_f
+      @clock   = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @mutex   = Mutex.new
+      @slots   = {}
+      @warned  = {}
+    end
+
+    # Blocks until the endpoint has room, then returns. Called once per attempt,
+    # retries included: a replayed request spends the budget a first one did.
+    def acquire(method, path)
+      rule = @limits.for(method, path)
+      wait, warn = @mutex.synchronize { reserve(rule) }
+
+      warn_saturated(rule, wait) if warn
+      return if wait <= 0 || wait > @max_wait
+
+      @sleeper.call(wait)
+    end
+
+    private
+
+    # The reservation happens under the lock and the waiting outside it: holding
+    # the mutex across the sleep would serialize every thread behind the slowest
+    # one, and threads waiting on unrelated endpoints have no reason to queue.
+    #
+    # What is recorded is the moment the request will be made, not the moment it
+    # was asked for, so concurrent callers each take a distinct slot and spread
+    # out instead of all waking onto the same one.
+    #
+    # Returns the wait the caller owes and whether this is the bypass worth a log
+    # line — both settled here, the second being shared state like the first.
+    def reserve(rule)
+      taken = (@slots[rule.name] ||= [])
+      now   = @clock.call
+      expire(taken, now)
+
+      slot   = next_slot(taken, rule.limit, now)
+      wait   = slot - now
+      bypass = wait > @max_wait
+      # Past the bound the request goes out now, so the slot it books is now:
+      # recording the one it declined to wait for would meter a request nobody
+      # ever made and push the whole window further out.
+      insert(taken, bypass ? now : slot)
+
+      [wait, bypass && first_warning?(rule, now)]
+    end
+
+    # The bookings that have left the window are its leading run, the list being
+    # kept ordered.
+    def expire(taken, now)
+      taken.shift(taken.bsearch_index { |at| at > now - @window } || taken.size)
+    end
+
+    # Now while the window still has room, otherwise a window past the limit-th
+    # most recent booking, which is the one that has to fall out of it first —
+    # an index that only reads as such on an ordered list.
+    def next_slot(taken, limit, now)
+      return now if taken.size < limit
+
+      taken[taken.size - limit] + @window
+    end
+
+    # A booking has one position in an ordered list, so it goes there rather than
+    # onto the end followed by a sort: `now` lands before the slots already
+    # reserved further out, and the list is what `next_slot` reads an index off.
+    def insert(taken, booking)
+      taken.insert(taken.bsearch_index { |at| at >= booking } || taken.size, booking)
+    end
+
+    # One line per endpoint per window. What the warning reports is a saturation
+    # that lasts, so a line per request puts one on every request it describes —
+    # a thousand of them for a couple of minutes over budget, burying the first,
+    # which is the only one the operator needed.
+    def first_warning?(rule, now)
+      last = @warned[rule.name]
+      return false if last && now - last < @window
+
+      @warned[rule.name] = now
+      true
+    end
+
+    def warn_saturated(rule, wait)
+      ForestAdminDatasourcePylon.logger.warn(
+        "[forest_admin_datasource_pylon] #{rule.name} is at its budget of #{rule.limit} requests per " \
+        "#{@window.round}s; the next slot is #{wait.round(1)}s out, past the #{@max_wait.round(1)}s this waits. " \
+        'Letting the request through — Pylon may answer 429, which the client retries. Further requests over ' \
+        "this budget are let through too, and this says so once per #{@window.round}s."
+      )
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/rate_limits.rb

@@ -0,0 +1,96 @@
+module ForestAdminDatasourcePylon
+  # The per-endpoint budgets Pylon documents, in requests per minute, read off
+  # the API reference (docs.usepylon.com/pylon-docs/developer/api/api-reference,
+  # one page per resource — each endpoint states its own "Rate limit:" line).
+  #
+  # Pylon meters per endpoint, not per token, so every rule owns its own window:
+  # two endpoints allowing 300 each are 600 requests, and pooling them would
+  # throttle at half the budget the API grants.
+  #
+  # An endpoint absent from the table falls back to DEFAULT_LIMIT, the lowest
+  # figure documented anywhere on the API. An undocumented quota is not an
+  # absent one, and the generous guess is the one an operator discovers as a 429.
+  #
+  # Every endpoint the client calls has a rule, writes included: the budget of a
+  # write is no more uniform than that of a read — `POST /accounts` is granted
+  # ten times `POST /issues`, and `PATCH /accounts/{id}` two and a half times
+  # `PATCH /issues/{id}` — so leaving one to the fallback throttles it at a
+  # fraction of what Pylon grants, which is the failure this table exists to
+  # avoid rather than a safe default.
+  class RateLimits
+    DEFAULT_LIMIT = 30
+
+    # Ids are escaped before being joined to a path, so a segment never carries
+    # a slash and this matches exactly one of them.
+    ID = '[^/]+'.freeze
+
+    Rule = Struct.new(:name, :limit, keyword_init: true)
+
+    # Every rule is anchored, so `/issues`, `/issues/{id}` and
+    # `/issues/{id}/messages` are three distinct buckets rather than three
+    # readings of the same prefix, and the order of this list carries no meaning.
+    #
+    # `name` is what the window is keyed on and what a log line shows, so it
+    # spells the endpoint rather than its budget: two endpoints sharing a figure
+    # must not share a window.
+    RULES = [
+      ['post /issues/search',           :post,   %r{\A/issues/search\z},              120],
+      ['post /accounts/search',         :post,   %r{\A/accounts/search\z},            120],
+      ['post /contacts/search',         :post,   %r{\A/contacts/search\z},            120],
+      ['get /issues/:id/messages',      :get,    %r{\A/issues/#{ID}/messages\z},      120],
+      ['get /issues',                   :get,    %r{\A/issues\z},                      30],
+      ['post /issues',                  :post,   %r{\A/issues\z},                      30],
+      ['get /issues/:id',               :get,    %r{\A/issues/#{ID}\z},               300],
+      ['patch /issues/:id',             :patch,  %r{\A/issues/#{ID}\z},               120],
+      ['get /accounts',                 :get,    %r{\A/accounts\z},                   300],
+      ['get /accounts/:id',             :get,    %r{\A/accounts/#{ID}\z},             300],
+      ['get /contacts',                 :get,    %r{\A/contacts\z},                   300],
+      ['get /contacts/:id',             :get,    %r{\A/contacts/#{ID}\z},             300],
+      ['get /users',                    :get,    %r{\A/users\z},                      300],
+      ['get /users/:id',                :get,    %r{\A/users/#{ID}\z},                300],
+      ['get /teams',                    :get,    %r{\A/teams\z},                      300],
+      ['get /teams/:id',                :get,    %r{\A/teams/#{ID}\z},                300],
+      ['get /custom-fields',            :get,    %r{\A/custom-fields\z},              300],
+      ['get /me',                       :get,    %r{\A/me\z},                         300],
+      ['post /accounts',                :post,   %r{\A/accounts\z},                   300],
+      ['patch /accounts/:id',           :patch,  %r{\A/accounts/#{ID}\z},             300],
+      ['post /contacts',                :post,   %r{\A/contacts\z},                   300],
+      ['patch /contacts/:id',           :patch,  %r{\A/contacts/#{ID}\z},             300],
+      ['delete /issues/:id',            :delete, %r{\A/issues/#{ID}\z},               120],
+      ['patch /teams/:id',              :patch,  %r{\A/teams/#{ID}\z},                120],
+      ['patch /users/:id',              :patch,  %r{\A/users/#{ID}\z},                120],
+      ['delete /accounts/:id',          :delete, %r{\A/accounts/#{ID}\z},              30],
+      ['delete /contacts/:id',          :delete, %r{\A/contacts/#{ID}\z},              30],
+      ['post /teams',                   :post,   %r{\A/teams\z},                       30]
+    ].map { |name, verb, pattern, limit| [verb, pattern, Rule.new(name: name, limit: limit)] }.freeze
+
+    class << self
+      def for(method, path)
+        verb = method.to_s.downcase.to_sym
+        normalized = normalize(path)
+
+        found = RULES.find { |rule_verb, pattern, _rule| rule_verb == verb && pattern.match?(normalized) }
+        found ? found[2] : fallback(verb, normalized)
+      end
+
+      private
+
+      # Faraday hands back the path of the resolved URL, which carries the
+      # leading slash the rules are written against and, on a base url mounted
+      # under a subpath, whatever precedes it.
+      def normalize(path)
+        stripped = path.to_s.chomp('/')
+        stripped.start_with?('/') ? stripped : "/#{stripped}"
+      end
+
+      # An unlisted endpoint is bucketed by its first segment rather than by its
+      # full path: keying on the path would open a window per record id, so a
+      # fan-out over a hundred records would meter as a hundred endpoints each
+      # one request in.
+      def fallback(verb, path)
+        segment = path.split('/').reject(&:empty?).first
+        Rule.new(name: "#{verb} /#{segment} (undocumented)", limit: DEFAULT_LIMIT)
+      end
+    end
+  end
+end