forest_admin_datasource_pylon 1.41.0

data/lib/forest_admin_datasource_pylon/collections/writes.rb

@@ -0,0 +1,417 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    # The write half of every Pylon collection. Included by `BaseCollection`, so
+    # a collection only declares the client calls, through the `*_record` hooks,
+    # and the fields Pylon accepts in one direction only. A hook left alone
+    # refuses the verb — no POST or DELETE on users, no DELETE on teams —
+    # instead of the contract's NotImplementedError, read by the agent as a 500.
+    #
+    # What may be written is `is_read_only` on the column, the way `api_filters`
+    # is what may be filtered: no second list to keep in step with the schema.
+    module Writes # rubocop:disable Metrics/ModuleLength
+      # Re-declared rather than borrowed from BaseCollection: a method defined
+      # here resolves a constant against this module and its ancestors, never
+      # against the class including it.
+      Filter     = ForestAdminDatasourceToolkit::Components::Query::Filter
+      Page       = ForestAdminDatasourceToolkit::Components::Query::Page
+      Projection = ForestAdminDatasourceToolkit::Components::Query::Projection
+      Leaf       = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Nodes::ConditionTreeLeaf
+      Operators  = ForestAdminDatasourceToolkit::Components::Query::ConditionTree::Operators
+
+      # What one filter-driven update or delete may spend, in requests. Pylon
+      # writes one record per request, so a selection costing more than this is
+      # refused rather than written halfway.
+      #
+      # The cap is about the round-trips, not the quota: `RateLimiter` spaces the
+      # requests out inside the documented budget, which no pass this size comes
+      # near — but no throttling makes a hundred sequential writes a wait the
+      # operator watches, or a request the agent times out on first. Refusing is
+      # the honest answer where a partial write is not recoverable.
+      #
+      # The budget covers the whole pass, not its writes: where a record is read
+      # through its own endpoint, resolving the selection costs a request per
+      # record and reading a stored value costs another, so a cap counting the
+      # writes alone would let one pass spend three times this.
+      MAX_WRITE_REQUESTS = 20
+
+      # The refusal comes before the payload and the ids: everything on the way
+      # there answers with something else — a count, a field of the wrong
+      # direction — for a selection that was never the problem.
+      def create(_caller, data)
+        refuse_write('created') unless write_endpoint?(:create_record)
+
+        serialize(create_record(build_payload(writable_attributes(data), :create)))
+      rescue APIError => e
+        surface_write_rejection(e)
+      end
+
+      # What the patch may write is settled before the ids are, so a patch naming
+      # nothing writable is refused, and refused for what it names rather than
+      # for how many records it would have reached.
+      def update(caller, filter, patch)
+        refuse_write('updated') unless write_endpoint?(:update_record)
+
+        attributes = writable_attributes(patch)
+        refuse_unwritable_patch(patch) if attributes.empty? && names_fields?(patch)
+        # A patch naming nothing at all asked for nothing: the front sends one on
+        # a form whose every field is a relation, which `Update` writes through
+        # its own route.
+        return if attributes.empty?
+
+        ids = ids_for(caller, filter, extra_reads: stored_read?(attributes) ? 1 : 0)
+        return if ids.empty?
+
+        payload = build_payload(attributes, :update, caller: caller, ids: ids)
+        return if payload.empty?
+
+        write_each(ids, 'updated') { |id| update_record(id, payload) }
+      end
+
+      def delete(caller, filter)
+        refuse_write('deleted') unless write_endpoint?(:delete_record)
+
+        write_each(ids_for(caller, filter), 'deleted') { |id| delete_record(id) }
+      end
+
+      protected
+
+      # One Pylon write endpoint each, overridden by the collections having one.
+      def create_record(_payload) = refuse_write('created')
+      def update_record(_id, _payload) = refuse_write('updated')
+      def delete_record(_id) = refuse_write('deleted')
+
+      # The Forest schema carries a single read-only flag per column, so both
+      # directions offer these; the two lists tell them apart at write time.
+      def create_only_fields = [].freeze
+      def update_only_fields = [].freeze
+
+      # Columns whose Pylon write name differs from the one they are read under.
+      def payload_renames = {}.freeze
+
+      # What reading one record costs here. Nothing where the search endpoint
+      # filters `id`, a whole selection travelling in one request whatever its
+      # size; one request where an id is read through its own endpoint.
+      def requests_per_record_read = 0
+
+      # How many records one write may reach: the budget divided by what each of
+      # them costs — the write itself, plus the `reads` the path still owes it.
+      def max_write_targets(reads: 0)
+        MAX_WRITE_REQUESTS / (1 + (reads * requests_per_record_read))
+      end
+
+      # How many ids a filter may name before the resolution is refused rather
+      # than spent: the same reach, a named id being read before it is written
+      # to. `nil` is no bound, a read costing nothing per record.
+      def max_resolvable_ids(reads: 0)
+        return nil if requests_per_record_read.zero?
+
+        max_write_targets(reads: reads)
+      end
+
+      # The records a filter-driven write applies to: exact, or refused — the
+      # caller writes one request per id and reports success for the whole
+      # selection, so a subset may never be answered quietly.
+      #
+      # An `id equals`/`id in` filter alone — what the record detail and the bulk
+      # selection send — costs no request. Anything else goes through `list`.
+      def ids_for(caller, filter, extra_reads: 0)
+        tree = filter&.condition_tree
+        if (named = id_values(tree)) && no_search?(filter)
+          cap = max_write_targets(reads: extra_reads)
+          refuse_too_many_targets(named.size, cap) if named.size > cap
+          return named
+        end
+
+        # A selection naming ids is resolved by reading each of them; any other
+        # one by a single page of the collection's own read, whose cost does not
+        # grow with the count.
+        named_ids = filtered_ids(tree)
+        reads     = extra_reads + (named_ids ? 1 : 0)
+        bound     = named_ids && max_resolvable_ids(reads: reads)
+        refuse_unresolvable_selection(named_ids.size, bound) if bound && named_ids.size > bound
+
+        resolve_ids_by_list(caller, filter, reads: reads)
+      end
+
+      private
+
+      # The `*_record` hook is the declaration that the collection wired the
+      # endpoint, read here rather than repeated in a list of supported verbs.
+      def write_endpoint?(hook)
+        method(hook).owner != Writes
+      end
+
+      # One request per record, so a failure on the k-th leaves the k-1 before it
+      # written. The error names them: raising the API error alone reads as
+      # "nothing happened", and retrying on that reading would write them twice.
+      def write_each(ids, verb)
+        written = []
+
+        ids.each do |id|
+          yield id
+          written << id
+        rescue APIError => e
+          # Always raises, so nothing reaches the partial report below: with no
+          # record written the failure is the whole of what happened.
+          surface_write_rejection(e) if written.empty?
+
+          refuse_partial_write(verb, written, id, ids.size, e)
+        end
+      end
+
+      # A 4xx names something the operator did, and travels as the
+      # ValidationError whose message the agent surfaces where the APIError it
+      # arrived as would be answered with 'Unexpected error'. Anything else is
+      # Pylon or the network failing, which no edit of theirs would change.
+      #
+      # Only the write goes through here: a 4xx raised while resolving the
+      # selection still reaches them as a 500, reporting a read failure as a
+      # refused write being the worse of the two.
+      def surface_write_rejection(error)
+        raise error unless (400..499).cover?(error.status.to_i)
+
+        raise WriteRejectedError, error.message
+      end
+
+      # One record past the cap is asked for, so an overflow is seen rather than
+      # guessed from a full page.
+      def resolve_ids_by_list(caller, filter, reads:)
+        cap     = max_write_targets(reads: reads)
+        window  = Page.new(offset: 0, limit: cap + 1)
+        query   = (filter || Filter.new).override(page: window)
+        records = list(caller, query, Projection.new(['id']))
+        refuse_unbounded_targets(cap) if records.size > cap
+
+        records.filter_map { |record| record['id'] }.uniq
+      end
+
+      # The ids a filter names, as a leaf of its own or inside a top-level `and`.
+      # Unlike `extract_id_lookup`, nothing is asserted about the rest of the
+      # tree — the leftovers travel to `list` — so this counts records *named*,
+      # never records the write applies to: what it bounds is the resolution.
+      #
+      # The `id` leaves of an `and` intersect, as they do there: this is the
+      # count a refusal is worded around, and the first of two would refuse a
+      # selection narrower than the number it names.
+      def filtered_ids(node)
+        named = id_values(node)
+        return named if named
+        return nil unless and_branch?(node)
+
+        named = Array(node.conditions).filter_map { |child| id_values(child) }
+        return nil if named.empty?
+
+        named.reduce(:&)
+      end
+
+      # The writable attributes, in the shape the endpoint takes them.
+      def build_payload(attributes, direction, caller: nil, ids: [])
+        attrs = honour_write_direction(attributes, direction, caller, ids)
+        # Pylon fills in what a create leaves out; on an update a nil is the
+        # operator clearing a value, so it travels.
+        attrs = attrs.compact if direction == :create
+
+        custom, native = split_custom_fields(attrs)
+        payload = native.transform_keys { |field| payload_renames.fetch(field, field) }
+        payload['custom_fields'] = custom unless custom.empty?
+        payload
+      end
+
+      # Everything else is dropped rather than refused: the front sends the
+      # fields of its form, and a read-only one reaching the payload is the
+      # agent's doing, not a request the operator made.
+      #
+      # What that leniency may not do is reduce a whole patch to nothing and let
+      # the edit be reported as performed -- see `refuse_unwritable_patch`. Only
+      # an update needs the guard: a create reduced to nothing still reaches
+      # Pylon, which refuses it with a reason of its own.
+      def writable_attributes(data)
+        attrs = data.is_a?(Hash) ? data.transform_keys(&:to_s) : {}
+
+        attrs.select { |field, _value| writable_column?(field) }
+      end
+
+      def names_fields?(data) = data.is_a?(Hash) && data.any?
+
+      def writable_column?(field)
+        column = schema[:fields][field]
+
+        column&.type == 'Column' && !column.is_read_only
+      end
+
+      # Whether the patch will have `stored_values` read every record it reaches
+      # before a field of the wrong direction is dropped or refused, which the
+      # cap has to charge it for: see `ids_for`.
+      def stored_read?(attributes) = (attributes.keys & create_only_fields).any?
+
+      # A field of the other direction is dropped when it asks for nothing, and
+      # refused when the operator really changed it: answering an edit with a
+      # success Pylon did not perform is worse than an error naming the field.
+      #
+      # Only a create can tell without reading, Pylon filling it in with exactly
+      # what a blank value asks for. On an update the stored value is what
+      # settles it — an unchecked box is nothing over a stored `false`, and a
+      # real edit over a stored `true`.
+      def honour_write_direction(attrs, direction, caller, ids)
+        wrong = attrs.keys & (direction == :create ? update_only_fields : create_only_fields)
+        return attrs if wrong.empty?
+
+        asked = if direction == :create
+                  wrong.reject { |field| blank_write_value?(attrs[field]) }
+                else
+                  wrong - unchanged_fields(caller, ids, wrong, attrs)
+                end
+        refuse_wrong_direction(asked, direction) unless asked.empty?
+
+        attrs.except(*wrong)
+      end
+
+      # What a form sends for a field the operator never touched: no value at
+      # all, an unchecked box, an empty list. A `0` or a string is a value only
+      # the other endpoint could write.
+      def blank_write_value?(value)
+        return true if value.nil? || value == false
+        return value.empty? if value.respond_to?(:empty?)
+
+        false
+      end
+
+      # The wrong-direction fields already holding the value the patch asks for.
+      # One record the read did not hand back is enough to refuse them all:
+      # nothing here may claim a value is unchanged on a record it never read.
+      def unchanged_fields(caller, ids, fields, attrs)
+        return [] if fields.empty?
+
+        stored = stored_values(caller, ids, fields)
+        return [] if stored.size < ids.size
+
+        fields.select { |field| stored.all? { |record| same_write_value?(record[field], attrs[field]) } }
+      end
+
+      # Two blanks are the same state: Pylon returns a null where the form sends
+      # `false` or an empty string for the same untouched field. Strings are
+      # compared stripped, `body_html` travelling through an editor that may hand
+      # back the markup it was given re-indented — and refusing an edit nobody
+      # made is the one error the operator cannot act on.
+      def same_write_value?(stored, asked)
+        return true if blank_write_value?(stored) && blank_write_value?(asked)
+        return stored.to_s.strip == asked.to_s.strip if stored.is_a?(String) || asked.is_a?(String)
+
+        stored == asked
+      end
+
+      # Read only when the patch names a field of the wrong direction, and only
+      # for those fields. One request where the endpoint filters `id`, one per
+      # record where an id is read through its own endpoint — which the cap does
+      # charge the patch for, `stored_read?` declaring it before the ids are
+      # resolved.
+      #
+      # By id rather than through the caller's filter: that filter was already
+      # resolved into these ids, so re-running it would spend those requests
+      # twice and, carrying no page, walk every record it matches.
+      def stored_values(caller, ids, fields)
+        query = Filter.new(condition_tree: Leaf.new('id', Operators::IN, ids),
+                           page: Page.new(offset: 0, limit: ids.size))
+
+        list(caller, query, Projection.new(['id'] + fields))
+      end
+
+      # Pylon reads its custom fields back as a map indexed by slug and writes
+      # them as a list, `values` for a multi-value field and `value` for every
+      # other — a select by the slug of its option, what the Enum advertises.
+      def split_custom_fields(attrs)
+        by_column = custom_fields_by_column
+        entries = []
+
+        native = attrs.each_with_object({}) do |(field, value), rest|
+          custom_field = by_column[field]
+          custom_field ? entries << custom_field_entry(custom_field, value) : rest[field] = value
+        end
+
+        [entries, native]
+      end
+
+      def custom_fields_by_column
+        @custom_fields_by_column ||= custom_fields.to_h { |field| [field[:column_name], field] }
+      end
+
+      def custom_field_entry(custom_field, value)
+        slug = custom_field[:column_name]
+        return { 'slug' => slug, 'values' => Array(value) } if custom_field[:multi_value]
+
+        { 'slug' => slug, 'value' => value }
+      end
+
+      def refuse_write(verb)
+        raise UnsupportedWriteError,
+              "A #{name} record cannot be #{verb}: the Pylon API exposes no endpoint for it."
+      end
+
+      # Every offending field at once: refusing them one at a time would have the
+      # operator undo one, retry, and learn about the next.
+      def refuse_wrong_direction(fields, direction)
+        them = fields.one? ? 'it' : 'them'
+        detail = if direction == :create
+                   "Pylon only accepts #{them} on an existing record: create the record, then edit it."
+                 else
+                   "Pylon only accepts #{them} when the record is created, and exposes no endpoint to change " \
+                     "#{them} afterwards."
+                 end
+
+        named = fields.map { |field| "'#{field}'" }.join(', ')
+        raise UnsupportedWriteError, "#{named} cannot be set here on a #{name}: #{detail}"
+      end
+
+      # A patch every key of which was dropped would write nothing and answer
+      # the operator with a successful edit: the route then re-reads the record
+      # and hands back the values it already had, so what they see is their
+      # change reverting with no reason given. Refused instead, naming the keys.
+      #
+      # Nothing is refused while anything remains writable -- a form resending a
+      # read-only column alongside a real edit performs the edit, and the column
+      # is dropped as it always was.
+      def refuse_unwritable_patch(patch)
+        named = patch.keys.map { |field| "'#{field}'" }.join(', ')
+        raise UnsupportedWriteError,
+              "This edit of a #{name} names only #{named}, and none of them can be written here: a read-only " \
+              'column, or a field this collection does not declare. Nothing would reach Pylon, and answering ' \
+              'the edit with a success would report a change that never landed.'
+      end
+
+      # The count is exact here, the filter having named the ids.
+      def refuse_too_many_targets(count, cap)
+        refuse_write_reach("applies to #{count} #{name} records, more than the #{cap} one pass covers")
+      end
+
+      # The resolution only knows the selection overflows: reporting the size of
+      # its window would name 21 records to a selection holding thousands.
+      def refuse_unbounded_targets(cap)
+        refuse_write_reach("applies to more than the #{cap} #{name} records one pass covers")
+      end
+
+      def refuse_write_reach(reach)
+        raise UnsupportedWriteError,
+              "This write #{reach}: Pylon writes one record per request, and a write stopping halfway — on a " \
+              'timeout, or on the first record Pylon refuses — would report a success it did not perform. ' \
+              'Narrow the selection to reach the records past this point.'
+      end
+
+      # How many of the named ids the rest of the filter matches is unknown here,
+      # so the count is reported as what it is: records named.
+      def refuse_unresolvable_selection(count, bound)
+        raise UnsupportedWriteError,
+              "This write names #{count} #{name} records and filters them further, which #{name} answers with " \
+              "one request per named record, on top of the one each write costs: more than the #{bound} one " \
+              'pass covers. Select fewer records, or drop the other conditions to write the ones named.'
+      end
+
+      def refuse_partial_write(verb, written, failed_id, total, error)
+        raise PartialWriteError,
+              "#{written.size} of #{total} #{name} records were #{verb} and then '#{failed_id}' failed: " \
+              "#{error.message}. The records already #{verb} are #{written.join(", ")}, and they stay " \
+              "#{verb} — the ones after them were left untouched. Retry the write on the untouched records " \
+              "alone: retrying the whole selection would perform it twice on the ones already #{verb}."
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/configuration.rb

@@ -0,0 +1,84 @@
+module ForestAdminDatasourcePylon
+  class Configuration
+    DEFAULT_BASE_URL = 'https://api.usepylon.com'.freeze
+
+    attr_reader :api_key, :base_url, :open_timeout, :timeout, :retry_policy, :rate_limiter,
+                :boot_open_timeout, :boot_timeout, :boot_retry_policy
+
+    # `rate_limiter: nil` takes the throttling out of the stack, leaving the 429
+    # retry as the only rate-limit handling. For the deployment metering on its
+    # own side, or the one that would rather see the 429.
+    #
+    # The `boot_` trio governs what the datasource reads while it is being
+    # constructed, where the wait is a Rails boot the operator sits through
+    # rather than a request that has already returned a page.
+    def initialize(api_key:, base_url: nil, open_timeout: 5, timeout: 30, retry_policy: RetryPolicy.new,
+                   rate_limiter: RateLimiter.new, boot_open_timeout: 3, boot_timeout: 10,
+                   boot_retry_policy: RetryPolicy.boot)
+      @api_key      = api_key
+      @base_url     = base_url || DEFAULT_BASE_URL
+      @open_timeout = open_timeout
+      @timeout      = timeout
+      @retry_policy = retry_policy
+      @rate_limiter = rate_limiter
+      @boot_open_timeout = boot_open_timeout
+      @boot_timeout      = boot_timeout
+      @boot_retry_policy = boot_retry_policy
+      validate!
+    end
+
+    # Pylon exposes unversioned paths (`/issues`, `/me`) directly under the host.
+    def url
+      @base_url.chomp('/')
+    end
+
+    # Whatever precedes the endpoint in the path, for a base url mounted under a
+    # subpath — an egress proxy, or a mock server. Empty against the API itself.
+    # `RateLimits` is keyed on the endpoint, so this has to come off a path
+    # before the table is asked: left on, every anchored rule misses and the
+    # whole datasource meters in one fallback bucket.
+    def base_path
+      @base_path ||= URI.parse(url).path
+    end
+
+    # The base url as something safe to print. `api_key` is not the only
+    # credential a Configuration holds: the url is operator-supplied, and an
+    # egress proxy fronting Pylon is spelled `https://user:pass@proxy.internal`,
+    # so its user-info is a password too. Whoever prints the url prints this.
+    #
+    # Cut with a regexp rather than through `URI`: nothing validates that the
+    # base url parses, and an `inspect` raising on the way to a Rails error page
+    # would replace the page with its own failure.
+    def redacted_url
+      url.sub(%r{://[^/@]+@}, '://[FILTERED]@')
+    end
+
+    # `api_key` is a bearer token, and nothing prints a Configuration on
+    # purpose: what reaches an `inspect` is a Rails error page, or a
+    # `logger.debug` of something holding one. The default would put the token
+    # in clear there.
+    #
+    # One of three, not the whole of it: the token also rides in the headers of
+    # the client's Faraday connections, which print them in clear, so `Client`
+    # and `Datasource` mask their own. Together they cut every path from an
+    # object this package hands out to the credential.
+    def inspect
+      "#<#{self.class.name} base_url=#{redacted_url.inspect} api_key=[FILTERED]>"
+    end
+
+    private
+
+    def validate!
+      missing = []
+      missing << 'api_key' if blank?(@api_key)
+      return if missing.empty?
+
+      raise ConfigurationError,
+            "ForestAdminDatasourcePylon missing required config: #{missing.join(", ")}"
+    end
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/datasource.rb

@@ -0,0 +1,53 @@
+module ForestAdminDatasourcePylon
+  class Datasource < ForestAdminDatasourceToolkit::Datasource
+    attr_reader :client, :configuration
+
+    def initialize(api_key:, **options)
+      super()
+      @configuration = Configuration.new(api_key: api_key, **options)
+      @client = Client.new(@configuration)
+
+      register_collections
+    end
+
+    # The datasource is what a Rails error page or a `logger.debug` is likeliest
+    # to print, and it holds the client whose connections carry the bearer
+    # token. Every collection reaches that token the same way, through the
+    # `@datasource` the toolkit's Collection keeps, so cutting the chain here
+    # covers them too -- and spares the recursive dump the default `inspect`
+    # walks into, a datasource and its collections pointing at each other.
+    def inspect
+      "#<#{self.class.name} collections=#{collections.keys.inspect}>"
+    end
+
+    private
+
+    # The five collections are registered together: each one declares relations
+    # pointing at the others, and a relation whose foreign collection is missing
+    # is a schema the agent refuses to boot on.
+    #
+    # Their custom fields are introspected here, one call per object type, as
+    # Pylon indexes its definitions by object type and asks for one on every
+    # call. Each entry stays on the collection it belongs to: a custom field is
+    # filtered through the very slug it is read by, which the collection's
+    # `api_filters` already carries, so there is no datasource-wide mapping to
+    # hold — and two Pylon datasources in the same agent share nothing.
+    #
+    # An introspection that fails costs the custom columns, not the datasource:
+    # `fetch_custom_fields` degrades and the agent boots on the native schema.
+    # The first failure also stands for the object types after it, each call
+    # being bounded per request rather than across the three — see
+    # `CustomFieldsIntrospector`.
+    def register_collections
+      custom_fields = Schema::CustomFieldsIntrospector.new(@client)
+
+      add_collection(Collections::Issue.new(self, custom_fields: custom_fields.issue_custom_fields))
+      add_collection(Collections::Account.new(self, custom_fields: custom_fields.account_custom_fields))
+      add_collection(Collections::Contact.new(self, custom_fields: custom_fields.contact_custom_fields))
+      # Pylon carries custom fields on issues, accounts and contacts only:
+      # neither an agent nor a team has any.
+      add_collection(Collections::User.new(self))
+      add_collection(Collections::Team.new(self))
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/issue_enums.rb

@@ -0,0 +1,20 @@
+module ForestAdminDatasourcePylon
+  # The closed sets `POST /issues` and `PATCH /issues/{id}` document, shared by
+  # the plugins building forms over them.
+  module IssueEnums
+    # Accepted on a create, and absent from every read: Pylon never returns the
+    # priority of an issue, which is why no column carries it.
+    PRIORITY = %w[urgent high medium low].freeze
+
+    # Where the first message of a created issue is delivered. `internal` is the
+    # absence of a delivery, and travels as no `destination_metadata` at all.
+    DESTINATION = %w[email slack in_app_chat customer_portal sms whatsapp internal].freeze
+
+    INTERNAL_DESTINATION = 'internal'.freeze
+
+    # The one state every organization has: the others Pylon ships, and the
+    # custom ones defined on top of them, are named by the option that writes
+    # them rather than listed here.
+    CLOSED_STATE = 'closed'.freeze
+  end
+end

data/lib/forest_admin_datasource_pylon/pagination/cursor_walker.rb

@@ -0,0 +1,103 @@
+module ForestAdminDatasourcePylon
+  module Pagination
+    # Forest asks for an offset/limit window; Pylon only knows how to hand out
+    # the next page of a cursor. Bridging the two means walking pages until the
+    # window is covered, then slicing. Deep offsets therefore cost one request
+    # per page, which is why the walk is capped: the requests are sequential —
+    # a cursor is only known once the page before it came back — so an unbounded
+    # walk is a list view the operator waits on, page after page, well before it
+    # is a quota `/issues/search` grants 120 requests a minute of.
+    class CursorWalker
+      MAX_PAGES = 20
+      MAX_RECORDS = 5_000
+
+      def initialize(max_pages: MAX_PAGES, max_records: MAX_RECORDS)
+        @max_pages = max_pages
+        @max_records = max_records
+      end
+
+      # Yields `(limit, cursor)` and expects a Client::SearchPage back.
+      #
+      # A nil limit asks for every record past the offset: the walk then runs
+      # until Pylon says there is no page left, or until a cap stops it. That
+      # distinction is the whole point of accepting nil rather than a limit
+      # standing in for "everything": a walk told to collect a thousand records
+      # stops at a thousand having covered the window it was given, and reports
+      # nothing, while a walk told to collect everything and stopped by a cap
+      # knows it is handing back less than it was asked for, and says so.
+      def walk(offset:, limit:, &page_source)
+        offset = offset.to_i.clamp(0, nil)
+        limit = limit&.to_i
+        return [] if limit && !limit.positive?
+
+        records = collect(offset, limit, &page_source)
+
+        limit ? (records[offset, limit] || []) : records.drop(offset)
+      end
+
+      private
+
+      # The walk itself: pages are collected until the window is covered, the
+      # source says there is nothing left, or a cap stops it. The slicing is
+      # `walk`'s, this only decides how far to go.
+      def collect(offset, limit)
+        needed = limit && (offset + limit)
+        records = []
+        cursor = nil
+        seen = Set.new
+        pages = 0
+
+        loop do
+          page = yield(batch_size(needed, records.size), cursor)
+          records.concat(page.records)
+          pages += 1
+
+          break if stop?(page, seen)
+          break if needed && records.size >= needed
+
+          if capped?(pages, records.size)
+            log_truncation(offset: offset, limit: limit, pages: pages, collected: records.size)
+            break
+          end
+
+          cursor = page.next_cursor
+        end
+
+        records
+      end
+
+      # An empty page, a cursor that does not move and a cursor already followed
+      # all stop the walk; Pylon does none of the three today, but a walk driven
+      # by a remote value stops on its own terms rather than on the caps only.
+      #
+      # The whole set is kept rather than the previous cursor alone, like
+      # `Client#collect_pages`: a cycle wider than one page would otherwise
+      # collect the same pages over and over until a cap cut it short, and hand
+      # back the duplicates as records.
+      def stop?(page, seen)
+        page.next_cursor.nil? || page.records.empty? || !seen.add?(page.next_cursor)
+      end
+
+      def capped?(pages, collected)
+        pages >= @max_pages || collected >= @max_records
+      end
+
+      # Bounded by the record budget left, and by the window still missing when
+      # there is one, so the walk never collects past @max_records.
+      def batch_size(needed, collected)
+        budget = @max_records - collected
+        budget = [needed - collected, budget].min if needed
+        budget.clamp(1, Client::MAX_SEARCH_LIMIT)
+      end
+
+      def log_truncation(offset:, limit:, pages:, collected:)
+        window = limit ? "offset=#{offset} limit=#{limit}" : "every record past offset=#{offset}"
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] Stopped paginating after #{pages} page(s) / #{collected} record(s) " \
+          "while fetching #{window}; results are truncated. " \
+          'Narrow the filter to reach records past this point.'
+        )
+      end
+    end
+  end
+end