forest_admin_datasource_pylon 1.41.0

data/lib/forest_admin_datasource_pylon/collections/contact/schema_definition.rb

@@ -0,0 +1,93 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Contact < CursorCollection
+      # A column is writable when `POST /contacts` or `PATCH /contacts/{id}`
+      # accepts it, in the shape it is read under — the Json columns holding
+      # objects rather than plain strings are left read-only, see below. No
+      # column is sortable — neither `GET /contacts` nor `POST /contacts/search`
+      # exposes a sort parameter, so advertising a sortable column would let the
+      # UI ask for an order the API cannot honour.
+      #
+      # Filter operators are not chosen here: they come from
+      # `ApiFilters::API_FILTERS`, which mirrors the allow-list of the API. A
+      # column missing from that table gets no operator, so the UI offers no
+      # filter of this collection's own that Pylon would refuse — the absence
+      # family the agent derives above the datasource being the exception
+      # `Query::OperatorMaps::Table` describes. A contact carries no timestamp at all —
+      # Pylon returns none.
+      module SchemaDefinition
+        ManyToOneSchema = BaseCollection::ManyToOneSchema
+        OneToManySchema = BaseCollection::OneToManySchema
+
+        private
+
+        def define_schema
+          define_identity_fields
+          define_contact_fields
+          define_portal_fields
+        end
+
+        # `account_id` is both the key of the relation and a column the contacts
+        # search filters, which is what lets the account side list its contacts
+        # server-side and the embedder resolve the account of a page of contacts
+        # in one request.
+        #
+        # `requested_issues` rather than `issues`: a contact is the requester of
+        # an issue, never its assignee — that side belongs to PylonUser.
+        def define_relations
+          add_field('account', ManyToOneSchema.new(foreign_collection: 'PylonAccount',
+                                                   foreign_key: 'account_id', foreign_key_target: 'id'))
+          add_field('requested_issues', OneToManySchema.new(foreign_collection: 'PylonIssue',
+                                                            origin_key: 'requester_id', origin_key_target: 'id'))
+        end
+
+        def define_identity_fields
+          add_column('id', 'String', is_primary_key: true)
+          add_column('name', 'String', writable: true)
+          # Flattened from the nested `{ id: ..., external_ids: ... }` object
+          # Pylon returns, and kept as a column next to the `account` relation
+          # it is the key of: the search endpoint filters it. Writable, which is
+          # what opens the relation editor — see the party fields of PylonIssue.
+          add_column('account_id', 'String', writable: true)
+          # Read-only Json, and deliberately unfilterable although the search
+          # endpoint does not offer it either: the API matches bare external-id
+          # strings while the column shows `{external_id, label}` objects, so a
+          # filter would run on something the operator cannot see.
+          add_column('external_ids', 'Json')
+        end
+
+        # `email` and `primary_phone_number` carry the primary value; the lists
+        # hold every address and number, and neither list is filterable.
+        #
+        # `email` is written on a create and `emails` on an update, one direction
+        # each: `POST /contacts` takes the primary address alone, and the other
+        # ones are set on an existing contact. Two writable projections of the
+        # same addresses would otherwise travel in one patch, the list leaving
+        # out whatever the primary carries.
+        #
+        # `phone_numbers` is not writable at all: it holds objects, and the
+        # shape the endpoint takes them in is not the one the column shows.
+        def define_contact_fields
+          add_column('email', 'String', writable: true)
+          add_column('emails', 'Json', writable: true)
+          add_column('primary_phone_number', 'String', writable: true)
+          add_column('phone_numbers', 'Json')
+          add_column('avatar_url', 'String', writable: true)
+        end
+
+        def define_portal_fields
+          # Left as String rather than Enum: Pylon documents no_access / member
+          # / admin, but an organization can define its own portal roles, which
+          # is what `portal_role_id` points at. The id is the one written and the
+          # name is read-only, like `role_id` and `role_name` on PylonUser:
+          # whichever of two projections Pylon ignored would come back stale.
+          add_column('portal_role', 'String')
+          add_column('portal_role_id', 'String', writable: true)
+          # Owned by the integrations the contact was seen through; no endpoint
+          # takes it.
+          add_column('integration_user_ids', 'Json')
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/contact/serializer.rb

@@ -0,0 +1,20 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Contact < CursorCollection
+      module Serializer
+        NATIVE_FIELDS = %w[id name email emails primary_phone_number phone_numbers avatar_url
+                           portal_role portal_role_id external_ids integration_user_ids].freeze
+
+        private
+
+        def serialize(contact)
+          attrs = contact.is_a?(Hash) ? contact : {}
+          record = NATIVE_FIELDS.to_h { |field| [field, attrs[field]] }
+          record['account_id'] = nested_id(attrs['account'])
+          add_custom_field_values(record, attrs['custom_fields'])
+          record
+        end
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/contact.rb

@@ -0,0 +1,45 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Contact < CursorCollection
+      include SchemaDefinition
+      include Serializer
+
+      # `POST /contacts` takes the primary address alone; the other ones are set
+      # on an existing contact, through the list.
+      CREATE_ONLY = %w[email].freeze
+      UPDATE_ONLY = %w[emails].freeze
+
+      def initialize(datasource, custom_fields: [])
+        super(datasource, 'PylonContact', custom_fields: custom_fields, searchable: true)
+      end
+
+      protected
+
+      def filter_table = ApiFilters
+
+      def create_record(payload) = datasource.client.create_contact(payload)
+      def update_record(id, payload) = datasource.client.update_contact(id, payload)
+      def delete_record(id) = datasource.client.delete_contact(id)
+
+      def create_only_fields = CREATE_ONLY
+      def update_only_fields = UPDATE_ONLY
+
+      def unsortable_warning
+        '[forest_admin_datasource_pylon] PylonContact cannot honour the requested order; neither GET /contacts ' \
+          'nor POST /contacts/search takes a sort parameter, so contacts come back in the order the API imposes.'
+      end
+
+      def search_page(limit:, cursor:, filter:, search_text:)
+        datasource.client.search_contacts(limit: limit, cursor: cursor, filter: filter, search_text: search_text)
+      end
+
+      def list_page(limit:, cursor:)
+        datasource.client.list_contacts(limit: limit, cursor: cursor)
+      end
+
+      def fetch_one(id)
+        datasource.client.fetch_contact(id)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/cursor_collection.rb

@@ -0,0 +1,131 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    # Base for the collections Pylon exposes through three endpoints: a plain
+    # cursor-paginated listing (`GET /accounts`, `GET /contacts`: 300 requests
+    # per minute), a search over the same pages (`POST /accounts/search`: 120)
+    # and a single record (`GET /accounts/{id}`: 300).
+    #
+    # Their search endpoint filters `id` server-side, so — unlike Issue — they
+    # declare it in `api_filters` and never need the primary-key short-circuit:
+    # every predicate, `id` included and under an `or` as well, is translated and
+    # answered by one search request. The routing below is therefore only about
+    # spending the cheapest budget that answers the question exactly, never about
+    # what Pylon can express.
+    #
+    # None of these endpoints takes a sort parameter, so `sortable_fields` stays
+    # the empty default of the base and each collection names, through
+    # `unsortable_warning`, the order it got instead of the one it asked for.
+    class CursorCollection < BaseCollection
+      include RecordSerialization
+      include RelationEmbedder
+
+      # Pylon documents no maximum number of values on an `in` filter; the chunk
+      # keeps the request body and the page answering it bounded.
+      ID_CHUNK_SIZE = 100
+
+      def list(caller, filter, projection)
+        records = fetch_records(caller, filter)
+        rows = records.map { |record| project(record, projection) }
+        embed_relations(records, rows, projection)
+        rows
+      end
+
+      # The search endpoint filters `id` server-side, which is what lets a whole
+      # page of foreign keys be read in one request per chunk.
+      def records_indexed_by_id(ids)
+        ids.each_slice(ID_CHUNK_SIZE).with_object({}) do |chunk, indexed|
+          search_by_ids(chunk).each { |record| indexed[record['id']] = record }
+        end
+      end
+
+      protected
+
+      # Every collection read this way has a search endpoint, hence a table of
+      # its own: the empty default of the base would silently turn each of its
+      # filters into a refusal.
+      def filter_table = raise(NotImplementedError, "#{self.class} did not implement filter_table")
+
+      # One page of the listing endpoint, as a Client::SearchPage.
+      def list_page(limit:, cursor:) = raise(NotImplementedError, "#{self.class} did not implement list_page")
+
+      # One record straight from its own endpoint.
+      def fetch_one(id) = raise(NotImplementedError, "#{self.class} did not implement fetch_one")
+
+      private
+
+      # The `id` filter goes through the translator rather than being written by
+      # hand, so the shape on the wire is the one this collection's `api_filters`
+      # produce — one spelling of an id filter, not two to keep in step. The
+      # cursor is followed defensively: a chunk is asked for as a single page,
+      # and Pylon is free to answer it over several.
+      def search_by_ids(ids)
+        pylon_filter = Query::ConditionTreeTranslator.call(Leaf.new('id', Operators::IN, ids),
+                                                           api_filters: api_filters)
+        records = walker.walk(offset: 0, limit: ids.size) do |batch, cursor|
+          search_page(limit: batch, cursor: cursor, filter: pylon_filter, search_text: nil)
+        end
+        records.map { |record| serialize(record) }
+      end
+
+      def fetch_records(caller, filter)
+        warn_unsortable(filter&.sort)
+
+        with_resolved_relations(caller, filter) do |query|
+          next listed_records(query) if browsing?(query)
+
+          id = single_id_lookup(query)
+          next page_window(records_by_id(id), query) if id
+
+          search_records(caller, query)
+        end
+      end
+
+      # Nothing to filter and nothing to search: the listing endpoint returns
+      # the same records for a budget two and a half times larger than the
+      # search one.
+      def browsing?(filter)
+        return true if filter.nil?
+
+        filter.condition_tree.nil? && no_search?(filter)
+      end
+
+      # The walk of `search_records`, over the listing endpoint: it hands out
+      # cursor pages just the same, it only takes no filter.
+      def listed_records(filter)
+        offset, limit = translate_page(filter&.page)
+
+        records = walker.walk(offset: offset, limit: limit) { |batch, cursor| list_page(limit: batch, cursor: cursor) }
+        records.map { |record| serialize(record) }
+      end
+
+      # A record detail is `id equals X` alone: reading it through the record
+      # endpoint keeps the search budget for the pages that need it.
+      #
+      # Only a bare leaf takes that path. An `and` also carrying a scope is left
+      # to the search endpoint, which filters the id and the rest server-side in
+      # one request — where a lookup would have to apply the leftovers in memory,
+      # and would refuse the ones it cannot evaluate there.
+      def single_id_lookup(filter)
+        tree = filter.condition_tree
+        return nil unless tree.is_a?(Leaf) && no_search?(filter)
+
+        ids = extract_id_lookup(tree)&.ids
+        ids&.one? ? ids.first : nil
+      end
+
+      # A record the operator can no longer reach — deleted, or outside the
+      # token's scope — reads as "no record" rather than as a failed page.
+      def records_by_id(id)
+        record = fetch_one(id)
+        return [] if record.nil?
+
+        serialized = serialize(record)
+        matches_id?(serialized, id) ? [serialized] : []
+      rescue APIError => e
+        raise unless e.status == 404
+
+        []
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/fetch_all_collection.rb

@@ -0,0 +1,192 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    # Base for the collections whose Pylon endpoint hands back the whole
+    # collection of the organization in a single response: `GET /users` and
+    # `GET /teams` take no cursor, no filter and no sort at all.
+    #
+    # Filtering, sorting and paginating that response in memory is exact rather
+    # than approximate: the records in hand ARE every record Pylon holds, so a
+    # window cut out of them carries the same rows a server-side query would
+    # have returned. This is what keeps the in-memory pass out of the trap this
+    # datasource refuses elsewhere — a result that looks filtered without being
+    # filtered — which only arises when a single page of a larger dataset is all
+    # one has. The cost is bandwidth, not correctness.
+    #
+    # Each `list` re-reads the endpoint, so what the operator sees is what Pylon
+    # holds now rather than what it held when the process booted. One request
+    # per list against the 300 a minute these endpoints grant, spaced out by
+    # `RateLimiter`, is a budget no list view comes near.
+    class FetchAllCollection < BaseCollection
+      # The filters a column may advertise, per column type. Restricted to the
+      # operators `ConditionTreeLeaf#match` evaluates natively or
+      # `ConditionTreeEquivalent` rewrites into that native set, because the
+      # in-memory pass is the only pass there is here: an operator with no
+      # equivalence makes `match` return nil, which `apply` reads as "no match"
+      # and would silently empty the page instead of filtering it.
+      OPERATOR_CANDIDATES = {
+        'String' => [Operators::EQUAL, Operators::NOT_EQUAL, Operators::IN, Operators::NOT_IN,
+                     Operators::PRESENT, Operators::BLANK, Operators::CONTAINS, Operators::I_CONTAINS,
+                     Operators::NOT_CONTAINS, Operators::STARTS_WITH, Operators::ENDS_WITH],
+        'Boolean' => [Operators::EQUAL, Operators::NOT_EQUAL, Operators::IN, Operators::NOT_IN,
+                      Operators::PRESENT, Operators::BLANK]
+      }.freeze
+
+      # Candidates are re-checked against the toolkit rather than trusted, so an
+      # equivalence the toolkit stops providing takes the filter out of the
+      # schema instead of turning every page using it into an empty one.
+      def self.operators_for(column_type)
+        Array(OPERATOR_CANDIDATES[column_type]).select do |operator|
+          Equivalent.equivalent_tree?(operator, IN_MEMORY_OPERATORS, column_type)
+        end
+      end
+
+      # Countable, alone among the Pylon collections: the count answered here is
+      # taken over every record Pylon holds, not over the pages a cursor walk
+      # happened to collect, so it is the figure a server-side count would have
+      # given rather than a fraction of it presented as the whole -- the very
+      # reason `BaseCollection#aggregate` refuses everywhere else. One request
+      # per count, against the 300 a minute these endpoints grant.
+      def initialize(datasource, name, **options)
+        super
+        enable_count
+      end
+
+      def list(caller, filter, projection)
+        records = sort_in_memory(filtered_records(caller, filter), filter&.sort)
+
+        page_window(records, filter).map { |record| project(record, projection) }
+      end
+
+      # Exact, like the filter and the sort above it: the records in hand are
+      # every record Pylon holds, so a count or a group computed over them is
+      # the one a server-side aggregation would have answered — which is why
+      # these columns stay groupable where every other Pylon column is not.
+      #
+      # The rows are keyed with strings because that is how the agent reads
+      # them, while `Aggregation#apply` hands them back keyed with symbols.
+      def aggregate(caller, filter, aggregation, limit = nil)
+        aggregation.apply(filtered_records(caller, filter), timezone_for(caller), limit)
+                   .map { |row| { 'group' => row[:group], 'value' => row[:value] } }
+      end
+
+      # One request answers any number of ids: the endpoint hands back the
+      # complete dataset, so the ids only pick rows out of it. Read again on
+      # every pass, like `list` — the freshness this collection trades bandwidth
+      # for is not worth losing to a cache of related records.
+      #
+      # Only the wanted entities are serialized: a page of a pointing collection
+      # asks for a handful of ids, against every record the organization has.
+      def records_indexed_by_id(ids)
+        wanted = Array(ids)
+
+        fetch_all.each_with_object({}) do |entity, indexed|
+          next unless entity.is_a?(Hash) && wanted.include?(entity['id'])
+
+          indexed[entity['id']] = serialize(entity)
+        end
+      end
+
+      protected
+
+      # A column is read-only unless the collection declares it `writable`.
+      # Scalar columns are sortable and groupable because the in-memory sort and
+      # aggregation honour anything asked of them; a Json column is none of the
+      # three, as it holds a list whose Pylon semantics have no in-memory
+      # counterpart — the same reason the primary-key residual guard refuses one.
+      def add_column(name, type, is_primary_key: false, writable: false)
+        add_field(name, ColumnSchema.new(column_type: type,
+                                         filter_operators: self.class.operators_for(type),
+                                         is_primary_key: is_primary_key,
+                                         is_sortable: type != 'Json',
+                                         is_groupable: type != 'Json',
+                                         is_read_only: !writable))
+      end
+
+      # Pylon defines custom fields on issues, accounts and contacts only, so
+      # neither collection read this way has any. Refused rather than ignored:
+      # `serialize` has no hook here to read a custom-field value with, and the
+      # in-memory pass no table to clamp the declared operators against, so a
+      # declaration would register a column reading nil on every row forever.
+      def add_custom_fields(custom_fields)
+        return [] if custom_fields.empty?
+
+        raise ConfigurationError,
+              "#{name} takes no custom field: Pylon defines them on issues, accounts and contacts only."
+      end
+
+      # The complete collection, straight from its unpaginated endpoint.
+      def fetch_all = raise(NotImplementedError, "#{self.class} did not implement fetch_all")
+
+      # One Pylon entity flattened into a record matching the schema.
+      def serialize(_entity) = raise(NotImplementedError, "#{self.class} did not implement serialize")
+
+      private
+
+      # The complete dataset, serialized and narrowed to the rows the filter
+      # keeps: what `list` pages and what `aggregate` counts are the same rows.
+      #
+      # Relation conditions are resolved first, like everywhere else: neither
+      # collection read this way declares a ManyToOne today, so what this refuses
+      # is a condition on the reverse side, which `match` would otherwise read as
+      # a missing column and answer by dropping every row.
+      def filtered_records(caller, filter)
+        with_resolved_relations(caller, filter) do |query|
+          filter_in_memory(fetch_all.map { |entity| serialize(entity) }, caller, query)
+        end
+      end
+
+      # The tree is applied over the complete dataset, so the rows it keeps are
+      # the rows Pylon would have kept. `guard_nil_comparisons` is still worth
+      # its cost: nothing in the schema advertises a bare comparison, but a
+      # scope, a segment or a customizer can send one, and it would otherwise
+      # raise on the nulls Pylon returns for an unset column.
+      def filter_in_memory(records, caller, filter)
+        tree = guard_nil_comparisons(filter&.condition_tree)
+        return records if tree.nil?
+
+        tree.apply(records, self, timezone_for(caller))
+      end
+
+      # Every requested order is honoured, including the ascending primary-key
+      # sort the agent injects when the request asks for none, so there is no
+      # unsortable order to report.
+      #
+      # Neither Ruby's `sort` nor the toolkit's `Sort#apply` can be used as is:
+      # `sort` is not stable, and `<=>` answers nil on a null, on two booleans
+      # and on mixed types, which leaves the comparator undefined and the order
+      # arbitrary. Ties therefore fall back to the position the API returned the
+      # record in, and values are compared by `compare_values`.
+      def sort_in_memory(records, sort)
+        clauses = normalized_sort_clauses(sort)
+        return records if clauses.empty?
+
+        records.each_with_index.sort do |(left, left_index), (right, right_index)|
+          compare_clauses(left, right, clauses).nonzero? || (left_index <=> right_index)
+        end.map(&:first)
+      end
+
+      def compare_clauses(left, right, clauses)
+        clauses.each do |field, ascending|
+          comparison = compare_values(left[field], right[field])
+          next if comparison.zero?
+
+          return ascending ? comparison : -comparison
+        end
+
+        0
+      end
+
+      # Nulls sort last on an ascending order and first on a descending one, the
+      # way a database orders them; values `<=>` cannot compare — two booleans,
+      # for one — are compared through their string form rather than left
+      # undefined, which puts `false` before `true`, again like a database.
+      def compare_values(left, right)
+        return 0 if left.nil? && right.nil?
+        return 1 if left.nil?
+        return -1 if right.nil?
+
+        (left <=> right) || (left.to_s <=> right.to_s)
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/issue/api_filters.rb

@@ -0,0 +1,41 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Issue < BaseCollection
+      # The allow-list of `POST /issues/search`, transcribed from the API
+      # reference: a field absent from this table cannot be filtered at all, and
+      # an operator absent from a field's map is rejected by Pylon.
+      #
+      # It is the single source of truth for filtering — `define_schema` derives
+      # every column's `filter_operators` from it, so this collection declares no
+      # filter the translator would then refuse; the absence family the agent
+      # derives on top of it is the exception `Query::OperatorMaps::Table`
+      # describes.
+      module ApiFilters
+        Maps = Query::OperatorMaps
+
+        extend Maps::Table
+
+        CUSTOM_FIELD_OPS = Maps::CUSTOM_FIELD_OPS
+
+        # `param` carries the read-to-filter renames: an issue is read with
+        # `type` / `resolution_time` / `latest_message_time` but filtered on
+        # `issue_type` / `resolved_at` / `latest_message_activity_at`.
+        API_FILTERS = {
+          'state' => { ops: Maps::EQUALITY },
+          'type' => { param: 'issue_type', ops: Maps::EQUALITY.merge(Maps::PRESENCE) },
+          'account_id' => { ops: Maps::EQUALITY.merge(Maps::PRESENCE) },
+          'requester_id' => { ops: Maps::EQUALITY.merge(Maps::PRESENCE) },
+          'assignee_id' => { ops: Maps::EQUALITY.merge(Maps::PRESENCE) },
+          'team_id' => { ops: Maps::EQUALITY },
+          'title' => { ops: Maps::FULL_TEXT },
+          'body_html' => { ops: Maps::FULL_TEXT },
+          'tags' => { ops: Maps::MEMBERSHIP },
+          'created_at' => { ops: Maps::TIME },
+          'updated_at' => { ops: Maps::TIME },
+          'resolution_time' => { param: 'resolved_at', ops: Maps::TIME },
+          'latest_message_time' => { param: 'latest_message_activity_at', ops: Maps::TIME }
+        }.freeze
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/collections/issue/id_lookup_reader.rb

@@ -0,0 +1,88 @@
+module ForestAdminDatasourcePylon
+  module Collections
+    class Issue < BaseCollection
+      # Reading issues named by their id, which Pylon serves one request at a
+      # time: `POST /issues/search` cannot filter on id, so the short-circuit
+      # `BaseCollection` extracts is answered by `GET /issues/{id}` per id.
+      #
+      # Split out of the collection for what it costs: everything here exists to
+      # bound that fan-out, and none of it is about the shape of an issue.
+      module IdLookupReader
+        include RecordSerialization
+
+        private
+
+        # The records are already narrowed to the ids the filter asked for, so
+        # applying the conditions left over by the short-circuit in memory
+        # cannot return a record the API would have excluded. The reverse —
+        # dropping a record over a condition memory evaluates differently from
+        # Pylon — is ruled out by `extract_id_lookup`, which refuses such
+        # residuals.
+        #
+        # Without a residual the ids are the answer, in order, so the window is
+        # taken off them before any of them is read: one request per record the
+        # caller asked to see, and none for the records it did not. A residual
+        # takes that away — which records the window holds is only known once
+        # they are all read — so past the cap the selection is refused rather
+        # than answered with a fraction of itself.
+        def records_by_id(caller, lookup, filter)
+          return fetch_by_ids(page_of_ids(lookup.ids, filter)) if lookup.residual.nil?
+
+          refuse_wide_lookup(lookup.ids.size) if lookup.ids.size > MAX_ID_LOOKUPS
+
+          page_window(lookup.residual.apply(fetch_by_ids(lookup.ids), self, timezone_for(caller)), filter)
+        end
+
+        # The ids of the window, capped: `MAX_ID_LOOKUPS` bounds a page rather
+        # than a selection here, a page being what each of these requests buys.
+        def page_of_ids(ids, filter)
+          offset, limit = translate_page(filter&.page)
+          wanted = limit ? Array(ids[offset, limit]) : ids.drop(offset)
+          capped = wanted.first(MAX_ID_LOOKUPS)
+          warn_truncated_lookup(wanted.size) if wanted.size > capped.size
+
+          capped
+        end
+
+        # `GET /issues/{id}` accepts the issue number as well as the UUID, so a
+        # record answering with an id other than the one asked for is dropped:
+        # see `matches_id?`.
+        def fetch_by_ids(ids)
+          ids.filter_map do |id|
+            record = fetch_issue(id)
+            next if record.nil?
+
+            serialized = serialize(record)
+            serialized if matches_id?(serialized, id)
+          end
+        end
+
+        # A record the operator can no longer reach — deleted, or outside the
+        # token's scope — reads as "no record" rather than as a failed page.
+        def fetch_issue(id)
+          datasource.client.fetch_issue(id)
+        rescue APIError => e
+          raise unless e.status == 404
+
+          nil
+        end
+
+        def warn_truncated_lookup(asked)
+          ForestAdminDatasourcePylon.logger.warn(
+            "[forest_admin_datasource_pylon] Asked for a page of #{asked} issues by id, reading the first " \
+            "#{MAX_ID_LOOKUPS}: Pylon answers one issue per request, and the requests are sequential. " \
+            'Ask for a smaller page to reach the records past this point.'
+          )
+        end
+
+        def refuse_wide_lookup(count)
+          raise UnsupportedOperatorError,
+                "This selection names #{count} issues by id and filters them further, which PylonIssue answers " \
+                "with one request per named issue — more than the #{MAX_ID_LOOKUPS} one page covers. Reading " \
+                'only some of them would drop records the other conditions keep, and silently answer a page ' \
+                'that is missing them. Name fewer issues, or drop the other conditions.'
+        end
+      end
+    end
+  end
+end