forest_admin_datasource_pylon 1.41.0

data/lib/forest_admin_datasource_pylon/retry_policy.rb

@@ -0,0 +1,86 @@
+module ForestAdminDatasourcePylon
+  # Everything governing how the client reacts to a failed request, in one
+  # place: which statuses and exceptions are worth another attempt, on which
+  # verbs, and how long to wait.
+  class RetryPolicy
+    # What one attempt may be held back before the retry is abandoned instead.
+    # faraday-retry gives up outright when Retry-After exceeds max_interval
+    # (`return if retry_after > max_interval`), so this is also the bound on what
+    # a 429 costs: past it the client raises at once rather than sleeping.
+    #
+    # A fifth of a Pylon window rather than the whole of it, on purpose. Pylon
+    # quotas are per-minute, so a 429 carries a Retry-After of up to 60s, and
+    # honouring it three times over parked the calling thread for three minutes
+    # -- long after the Forest server timed out the request nobody will now read,
+    # and multiplied by the 20 sequential calls a single list view may spend
+    # (`MAX_ID_LOOKUPS`). The figure is what keeps the sleeps of one whole
+    # request under a minute: `max_retries` waits of this, plus the
+    # `RateLimiter::DEFAULT_MAX_WAIT` each of the four attempts may also pay.
+    #
+    # The trade, plainly: a Retry-After past this makes the 429 surface as an
+    # error where it used to be waited out, which is most of them -- the value
+    # being the remainder of the minute window. Absorbing them is `RateLimiter`'s
+    # job, metering each endpoint inside its budget before Pylon has to answer
+    # 429 at all; this retry is the backstop for the traffic the limiter cannot
+    # see, and a backstop may cost less than what it protects.
+    DEFAULT_MAX_INTERVAL = 12
+
+    STATUSES = [429, 502, 503, 504].freeze
+
+    # faraday-retry's defaults plus ConnectionFailed: a dropped connection is
+    # exactly the transient failure a resilient client should absorb, and it is
+    # not retried out of the box.
+    EXCEPTIONS = [
+      Errno::ETIMEDOUT, 'Timeout::Error', Faraday::TimeoutError,
+      Faraday::RetriableResponse, Faraday::ConnectionFailed
+    ].freeze
+
+    # The verbs that change nothing, so any transient failure is worth another
+    # attempt. Narrower than faraday-retry's idempotent default: a 502 or a
+    # dropped connection on the way back from a DELETE Pylon did perform is
+    # replayed into a 404, which the write path then surfaces as a deletion that
+    # failed when it landed.
+    #
+    # A 429 stays safe to retry on any verb, Pylon having rejected the request
+    # before processing it, and travels through retry_if rather than through this
+    # list: faraday-retry ORs the two, so methods can only widen the set, never
+    # restrict it.
+    RETRYABLE_METHODS = %i[get head options].freeze
+    RETRY_IF = ->(env, _exception) { env[:status] == 429 }
+
+    # The same mechanism as DEFAULT_MAX_INTERVAL, tightened for a call that must
+    # not hold the boot: what a request may wait once the agent is serving is
+    # more than an operator watching Rails come up should pay per object type.
+    BOOT_MAX_INTERVAL = 2
+
+    BACKOFF_FACTOR = 2
+
+    attr_reader :max_retries, :interval, :max_interval
+
+    # One retry rather than none, for what is read once and never revisited: a
+    # transient failure there costs its result for the whole life of the process,
+    # and half a second absorbs the hiccup without waiting a 429 out.
+    def self.boot
+      new(max_retries: 1, interval: 0.5, max_interval: BOOT_MAX_INTERVAL)
+    end
+
+    def initialize(max_retries: 3, interval: 0.5, max_interval: DEFAULT_MAX_INTERVAL)
+      @max_retries  = max_retries
+      @interval     = interval
+      @max_interval = max_interval
+    end
+
+    def to_faraday_options
+      {
+        max: @max_retries,
+        interval: @interval,
+        max_interval: @max_interval,
+        backoff_factor: BACKOFF_FACTOR,
+        retry_statuses: STATUSES,
+        exceptions: EXCEPTIONS,
+        methods: RETRYABLE_METHODS,
+        retry_if: RETRY_IF
+      }
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/schema/custom_fields_introspector.rb

@@ -0,0 +1,203 @@
+module ForestAdminDatasourcePylon
+  module Schema
+    # Turns the custom fields an organization defined in Pylon into columns, as
+    # entries shaped `{ column_name:, schema:, multi_value: }` — what
+    # `add_custom_fields` registers on a collection, and what the payload
+    # builder writes a value back through.
+    #
+    # `column_name` is the Pylon slug verbatim, and there is no second key
+    # carrying it: the slug is both what a read payload indexes the values by and
+    # what a search filter sends as `field`, so renaming the column would add a
+    # mapping to keep in step for nothing.
+    #
+    # Pylon defines custom fields per object type, and asks for that type on
+    # every call: `issue`, `account` and `contact` are the three this datasource
+    # has a collection for — it also exposes `task`, `project`, `meeting` and
+    # `opportunity`, while users and teams carry no custom field at all.
+    class CustomFieldsIntrospector
+      ColumnSchema = ForestAdminDatasourceToolkit::Schema::ColumnSchema
+      Maps         = Query::OperatorMaps
+
+      # A type absent from this table is skipped rather than guessed at: a column
+      # whose Forest type does not match what Pylon holds would filter and
+      # display wrong, which is worse than not being there.
+      #
+      # `user` holds a Pylon user id, kept a String rather than turned into a
+      # relation to PylonUser: a custom field is registered after the relations
+      # are declared, and a foreign key the operator can read is what this story
+      # promises.
+      PYLON_TO_COLUMN_TYPE = {
+        'text' => 'String',
+        'url' => 'String',
+        'user' => 'String',
+        'number' => 'Number',
+        'decimal' => 'Number',
+        'boolean' => 'Boolean',
+        'date' => 'Dateonly',
+        'datetime' => 'Date',
+        'select' => 'Enum',
+        'multiselect' => 'Json'
+      }.freeze
+
+      # The types Pylon writes back through `values` rather than `value`.
+      MULTI_VALUE_TYPES = %w[multiselect].freeze
+
+      BASE_OPS = (Maps::EQUALITY.keys + Maps::PRESENCE.keys).freeze
+
+      # A date drops the membership operators on the way, `Rules` granting a DATE
+      # or a DATEONLY column no array operator -- the hazard already documented
+      # for MEMBERSHIP in `operator_maps.rb`. Native date columns declare the
+      # comparisons alone for the same reason.
+      #
+      # Dropping them is not what keeps `in` out of the UI, though, and nothing
+      # here can: `OperatorsEquivalenceCollectionDecorator` republishes it from
+      # the `equal` this set declares, the IN transform depending on EQUAL for
+      # every column type. A DATEONLY also gets `after_x_hours_ago` /
+      # `before_x_hours_ago` republished from the comparisons, `Times.compare`
+      # deriving them for that type where `Rules` refuses them. The validator
+      # then rejects all three, so the operator is offered a date filter the
+      # agent answers with a 400. The contradiction is the toolkit's to settle
+      # and is tracked as PRD-989; the set below is what Pylon accepts, which is
+      # the only question this table can answer.
+      TIME_OPS = (BASE_OPS - Maps::MEMBERSHIP.keys + Maps::TIME.keys).freeze
+
+      # Drawn from `CUSTOM_FIELD_OPS`, the set every search endpoint accepts on a
+      # custom field, so a collection's clamp has nothing to drop.
+      #
+      # A Number gets no comparison: Pylon documents `time_is_after` /
+      # `time_is_before` for the bare comparisons and nothing else, so a numeric
+      # range would travel as a time filter. A multiselect gets nothing at all —
+      # its membership operators are not part of what a custom field accepts.
+      OPERATORS = {
+        'String' => (BASE_OPS + Maps::FULL_TEXT.keys).freeze,
+        'Enum' => BASE_OPS,
+        'Number' => BASE_OPS,
+        'Boolean' => BASE_OPS,
+        'Date' => TIME_OPS,
+        'Dateonly' => TIME_OPS,
+        'Json' => [].freeze
+      }.freeze
+
+      def initialize(client)
+        @client = client
+        @unreachable = false
+      end
+
+      def issue_custom_fields   = introspect('issue')
+      def account_custom_fields = introspect('account')
+      def contact_custom_fields = introspect('contact')
+
+      private
+
+      # One object type per call, three of them, all of it in front of a Rails
+      # boot the operator sits through. The first failure stands for the rest:
+      # a Pylon that is down, or a token missing the permission, fails the two
+      # that follow the same way, and each is bounded per request rather than
+      # across the three — so trying them anyway spends the bound three times to
+      # learn what the first one already said.
+      def introspect(object_type)
+        return [] if @unreachable
+
+        definitions = @client.fetch_custom_fields(object_type)
+        return give_up(object_type) if definitions.nil?
+
+        definitions.filter_map { |raw| build_entry(raw, object_type) }
+      end
+
+      def give_up(object_type)
+        @unreachable = true
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] Custom fields could not be read for #{object_type}; " \
+          'the object types after it are left unread rather than held against the same failure. ' \
+          'The datasource boots on the native schema, without the custom columns.'
+        )
+        []
+      end
+
+      def build_entry(raw, object_type)
+        return nil unless raw.is_a?(Hash)
+
+        slug = raw['slug'].to_s
+        return nil if slug.empty?
+
+        column_type = PYLON_TO_COLUMN_TYPE[raw['type']]
+        return warn_unknown_type(raw, slug, object_type) if column_type.nil?
+
+        { column_name: slug, schema: build_schema(raw, column_type),
+          multi_value: MULTI_VALUE_TYPES.include?(raw['type']) }
+      end
+
+      # A custom field is writable when Pylon says it is: it flags the ones
+      # synced from an app or an integration, which its own endpoints refuse.
+      # Nothing is sortable -- no Pylon endpoint takes a sort parameter -- and
+      # nothing is groupable: one column left groupable turns `supportGroups` on
+      # for the whole collection, and the group-by the UI then offers errors.
+      def build_schema(raw, column_type)
+        opts = { column_type: column_type,
+                 filter_operators: OPERATORS.fetch(column_type, []),
+                 is_read_only: !writable_definition?(raw),
+                 is_sortable: false,
+                 is_groupable: false }
+
+        column_type == 'Enum' ? enum_schema(raw, opts) : ColumnSchema.new(**opts)
+      end
+
+      # Pylon reads a select back — and filters it — as the slug of the option,
+      # never as its label, so those are the values the column advertises.
+      #
+      # Forest refuses an Enum carrying no value: a select whose options were all
+      # removed falls back to String, so the column still shows what it holds.
+      #
+      # Read-only there whatever Pylon says of the field, unlike every other
+      # fallback here: a select is written as the slug of one of its options, so
+      # a free-text editor on one offers the operator no value the endpoint would
+      # accept. Showing what it holds is the whole of what this can do.
+      def enum_schema(raw, opts)
+        values = option_slugs(raw)
+        return ColumnSchema.new(**opts, enum_values: values) unless values.empty?
+
+        ColumnSchema.new(**opts, column_type: 'String',
+                                 filter_operators: OPERATORS.fetch('String'), is_read_only: true)
+      end
+
+      def option_slugs(raw)
+        metadata = raw['select_metadata']
+        options  = metadata.is_a?(Hash) ? metadata['options'] : nil
+
+        Array(options).filter_map do |option|
+          option['slug'] if option.is_a?(Hash) && !option['slug'].to_s.empty?
+        end
+      end
+
+      # Only an explicit `false` opens a custom field to writes. A definition
+      # carrying no flag at all is left read-only and reported: this datasource
+      # advertises nothing an endpoint would refuse, and reading the absence as
+      # "writable" would turn every field synced from an app into an editor whose
+      # every save Pylon rejects -- where reading it as "read-only" costs the
+      # capability and says so once per boot.
+      def writable_definition?(raw)
+        return true if raw['is_read_only'] == false
+        return false if raw['is_read_only'] == true
+
+        warn_unflagged_writability(raw)
+        false
+      end
+
+      def warn_unflagged_writability(raw)
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] Custom field '#{raw["slug"]}' carries no 'is_read_only' flag; " \
+          'leaving it read-only. Pylon refuses a write on the fields it syncs from an app or an integration, ' \
+          'and nothing here can tell this one apart from those without the flag.'
+        )
+      end
+
+      def warn_unknown_type(raw, slug, object_type)
+        ForestAdminDatasourcePylon.logger.warn(
+          "[forest_admin_datasource_pylon] Custom field '#{slug}' on #{object_type} has type " \
+          "#{raw["type"].inspect}, which this datasource cannot map to a Forest column; skipping."
+        )
+        nil
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/throttle.rb

@@ -0,0 +1,21 @@
+module ForestAdminDatasourcePylon
+  # Holds a request until its endpoint has budget. A middleware rather than a
+  # call in each client method: there is one code path for every request here,
+  # where the client has twenty, and this one also catches the requests the
+  # client never issues itself — the replays `retry` performs.
+  class Throttle < Faraday::Middleware
+    def initialize(app, limiter:, base_path: '')
+      super(app)
+      @limiter   = limiter
+      @base_path = base_path.to_s
+    end
+
+    # Faraday hands over the path of the resolved url, so a base url mounted
+    # under a subpath carries that prefix and no rule matches. It comes off
+    # before the limiter sees the path.
+    def call(env)
+      @limiter.acquire(env.method, env.url.path.delete_prefix(@base_path))
+      @app.call(env)
+    end
+  end
+end

data/lib/forest_admin_datasource_pylon/version.rb

@@ -0,0 +1,3 @@
+module ForestAdminDatasourcePylon
+  VERSION = "1.41.0"
+end

data/lib/forest_admin_datasource_pylon.rb

@@ -0,0 +1,70 @@
+require_relative 'forest_admin_datasource_pylon/version'
+require 'json'
+require 'logger'
+require 'set'
+require 'uri'
+require 'zeitwerk'
+require 'faraday'
+require 'faraday/retry'
+require 'forest_admin_datasource_toolkit'
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+module ForestAdminDatasourcePylon
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  # A filter Pylon cannot express. It descends from the toolkit's ValidationError
+  # rather than from the package's own Error so the agent answers 400 carrying
+  # the message instead of a 500 "Unexpected error": every one of these names a
+  # condition the operator set and can change, and the message is the only place
+  # they learn which one.
+  class UnsupportedOperatorError < ForestAdminDatasourceToolkit::Exceptions::ValidationError; end
+
+  # The three write errors below descend from ValidationError for that same
+  # reason: each names something the operator did and can undo.
+
+  # A verb Pylon's API has no endpoint for, a field it only accepts in the other
+  # direction, or a write reaching more records than one pass may cover.
+  class UnsupportedWriteError < ForestAdminDatasourceToolkit::Exceptions::ValidationError; end
+
+  # A write Pylon performed on some of its records and then failed on: one
+  # record is one request, so the ones before the failure stay written, and a
+  # retry of the whole selection would write them a second time.
+  class PartialWriteError < ForestAdminDatasourceToolkit::Exceptions::ValidationError; end
+
+  # A write Pylon itself refused, carrying the reason it gave — the likeliest
+  # way a write fails. Only its 4xx travels this way: a 5xx or a dropped
+  # connection is not the operator's to act on and stays the APIError it was.
+  class WriteRejectedError < ForestAdminDatasourceToolkit::Exceptions::ValidationError; end
+
+  # Raised when a Pylon API call fails. Carries the HTTP status and the
+  # (parsed) response body so callers — smart actions in particular — can
+  # surface Pylon's own validation message instead of a generic string.
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class << self
+    attr_writer :logger
+
+    def logger
+      @logger ||= default_logger
+    end
+
+    private
+
+    def default_logger
+      return Rails.logger if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+      Logger.new($stderr).tap { |l| l.progname = 'forest_admin_datasource_pylon' }
+    end
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: forest_admin_datasource_pylon
+version: !ruby/object:Gem::Version
+  version: 1.41.0
+platform: ruby
+authors:
+- Forest Admin
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-09-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+description: Surface Pylon issues, accounts, contacts, users and teams as Forest Admin
+  collections.
+email:
+- contact@forestadmin.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- README.md
+- Rakefile
+- forest_admin_datasource_pylon.gemspec
+- lib/forest_admin_datasource_pylon.rb
+- lib/forest_admin_datasource_pylon/client.rb
+- lib/forest_admin_datasource_pylon/client/writes.rb
+- lib/forest_admin_datasource_pylon/collections/account.rb
+- lib/forest_admin_datasource_pylon/collections/account/api_filters.rb
+- lib/forest_admin_datasource_pylon/collections/account/schema_definition.rb
+- lib/forest_admin_datasource_pylon/collections/account/serializer.rb
+- lib/forest_admin_datasource_pylon/collections/base_collection.rb
+- lib/forest_admin_datasource_pylon/collections/contact.rb
+- lib/forest_admin_datasource_pylon/collections/contact/api_filters.rb
+- lib/forest_admin_datasource_pylon/collections/contact/schema_definition.rb
+- lib/forest_admin_datasource_pylon/collections/contact/serializer.rb
+- lib/forest_admin_datasource_pylon/collections/cursor_collection.rb
+- lib/forest_admin_datasource_pylon/collections/fetch_all_collection.rb
+- lib/forest_admin_datasource_pylon/collections/issue.rb
+- lib/forest_admin_datasource_pylon/collections/issue/api_filters.rb
+- lib/forest_admin_datasource_pylon/collections/issue/id_lookup_reader.rb
+- lib/forest_admin_datasource_pylon/collections/issue/messages_embedder.rb
+- lib/forest_admin_datasource_pylon/collections/issue/schema_definition.rb
+- lib/forest_admin_datasource_pylon/collections/issue/serializer.rb
+- lib/forest_admin_datasource_pylon/collections/record_serialization.rb
+- lib/forest_admin_datasource_pylon/collections/relation_embedder.rb
+- lib/forest_admin_datasource_pylon/collections/team.rb
+- lib/forest_admin_datasource_pylon/collections/user.rb
+- lib/forest_admin_datasource_pylon/collections/writes.rb
+- lib/forest_admin_datasource_pylon/configuration.rb
+- lib/forest_admin_datasource_pylon/datasource.rb
+- lib/forest_admin_datasource_pylon/issue_enums.rb
+- lib/forest_admin_datasource_pylon/pagination/cursor_walker.rb
+- lib/forest_admin_datasource_pylon/plugins/close_issue.rb
+- lib/forest_admin_datasource_pylon/plugins/close_issue/messages.rb
+- lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification.rb
+- lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification/form_builder.rb
+- lib/forest_admin_datasource_pylon/plugins/create_issue_with_notification/payload.rb
+- lib/forest_admin_datasource_pylon/plugins/issue_targets.rb
+- lib/forest_admin_datasource_pylon/query/condition_tree_translator.rb
+- lib/forest_admin_datasource_pylon/query/filter_value.rb
+- lib/forest_admin_datasource_pylon/query/operator_maps.rb
+- lib/forest_admin_datasource_pylon/rate_limiter.rb
+- lib/forest_admin_datasource_pylon/rate_limits.rb
+- lib/forest_admin_datasource_pylon/retry_policy.rb
+- lib/forest_admin_datasource_pylon/schema/custom_fields_introspector.rb
+- lib/forest_admin_datasource_pylon/throttle.rb
+- lib/forest_admin_datasource_pylon/version.rb
+homepage: https://www.forestadmin.com
+licenses:
+- GPL-3.0
+metadata:
+  homepage_uri: https://www.forestadmin.com
+  source_code_uri: https://github.com/ForestAdmin/agent-ruby
+  changelog_uri: https://github.com/ForestAdmin/agent-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'false'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Pylon datasource for Forest Admin Ruby agent.
+test_files: []