forest_admin_datasource_graphql_hasura 1.37.0

data/README.md

@@ -0,0 +1,121 @@
+# Forest Admin — Hasura GraphQL datasource
+
+Surface tables exposed by a [Hasura](https://hasura.io) GraphQL API as Forest Admin collections,
+including **Rails-style polymorphic associations** (`belongs_to :commentable, polymorphic: true`).
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'forest_admin_datasource_graphql_hasura'
+```
+
+## Usage
+
+```ruby
+ForestAdminRails::Agent.instance.add_datasource(
+  ForestAdminDatasourceGraphqlHasura::Datasource.new(
+    uri: 'https://my-instance.hasura.app/v1/graphql',
+    headers: { 'x-hasura-admin-secret' => ENV['HASURA_ADMIN_SECRET'] }
+  )
+)
+```
+
+Collections are named after the Rails class name derived from the table name
+(`transfers` → `Transfer`). This matches the values stored in Rails `*_type` columns, which is
+what makes polymorphic relations resolvable by the Forest Admin frontend.
+
+## Polymorphic associations
+
+Rails represents `belongs_to :commentable, polymorphic: true` with two columns
+(`commentable_type`, `commentable_id`). Hasura cannot express the type condition, so teams
+declare one manual object relationship per target, joining on `commentable_id` alone.
+
+This datasource detects the pattern (a `<base>_type`/`<base>_id` column pair whose object
+relationships all join on `<base>_id`) and emits:
+
+- a `PolymorphicManyToOne` (`Comment.commentable`) instead of the ambiguous per-target
+  relations — the Forest UI shows the native polymorphic widget;
+- a `PolymorphicOneToMany` on each target (`Transfer.comments`, filtered on
+  `commentable_type = 'Transfer'`), so related data never leaks records of another type.
+
+The detection uses the Hasura metadata API (`/v1/metadata`, derived from `uri`). When that
+endpoint is not reachable (common in production), declare the associations explicitly:
+
+```ruby
+ForestAdminDatasourceGraphqlHasura::Datasource.new(
+  uri: '...',
+  polymorphic_relations: { 'comments' => { 'commentable' => %w[transfers cards] } }
+)
+```
+
+For namespaced models, override the type value stored by Rails:
+
+```ruby
+type_values: { 'bank_accounts' => 'Banking::Account' }
+```
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `uri` | Hasura GraphQL endpoint (required) |
+| `headers` | HTTP headers, e.g. admin secret or JWT |
+| `metadata_uri` | Metadata endpoint (default: `uri` with `/v1/graphql` → `/v1/metadata`; not derived — and detection skipped — when `uri` has no `/v1/graphql` segment) |
+| `included_tables` / `excluded_tables` | Allow/deny lists of table names |
+| `polymorphic_relations` | Explicit polymorphic declarations (see above) |
+| `type_values` | Table → Rails class name overrides |
+| `timeout` | HTTP timeout in seconds (default 30) |
+
+## Requirements and limitations
+
+- **A polymorphic association is only detected from a Hasura `manual_configuration`
+  relationship** joining on the polymorphic foreign key (or from `polymorphic_relations`).
+  A relationship backed by a real foreign key constraint is treated as a plain belongs_to,
+  so a business enum named `<something>_type` sitting next to a `<something>_id` foreign key
+  is left alone.
+- **Grouped aggregations** (charts) work on a foreign key, or on a `<relation>:<column>`
+  path through a ManyToOne (leaderboard charts) whose reverse relationship is declared in
+  Hasura: Hasura exposes GROUP BY only through nested `<relation>_aggregate` fields. A
+  foreign key without a declared reverse relationship is advertised as non-groupable, like
+  every other column, and date truncation is not supported. Rows whose foreign key is NULL
+  form a bucket of their own, as SQL grouping would. Dangling foreign keys (possible on a
+  constraint-less relationship) keep a group per value when grouping by the foreign key (up
+  to 100 distinct dangling values, then a clear error) and fall into the NULL bucket when
+  grouping through a parent column, as a LEFT JOIN would. Parent rows are filtered by the
+  chart's predicate and paginated by 1000; a chart spanning more than 10 000 parent rows
+  fails with a clear error rather than returning partial numbers.
+- **Tables without a primary key** (typically untracked views) are skipped: Forest cannot
+  address their records.
+- Filtering and sorting through a polymorphic relation is not possible (a Forest Admin
+  limitation shared with the ActiveRecord datasource).
+- Pattern operators (`contains`, `starts with`…) are only offered on genuine text columns.
+  Postgres enums and custom Hasura scalars get equality and nullity operators, because
+  their Hasura comparison expressions have no `_like`/`_ilike`. Text matching is
+  case-insensitive, like the ActiveRecord datasource.
+- Nested creates/updates are out of scope: mutations write scalar columns (including
+  `jsonb`), never related records.
+- A `*_type` value matching no exposed collection (a legacy STI subclass name, an excluded
+  target) leaves the reference empty and logs a warning, rather than failing the page.
+- `bytea` and `money` columns are surfaced as text (Hasura returns them hex-encoded and in
+  Postgres money form respectively).
+- Customized root fields (`custom_root_fields`, `custom_name`) and the `graphql-default`
+  naming convention are followed for introspection, metadata matching and query generation —
+  renamed mutation and aggregate roots included, as long as the metadata API is reachable to
+  declare them (unreachable metadata falls back to the derived names). One gap: Rails
+  polymorphism *detection* relies on snake_case `<base>_type`/`<base>_id` column pairs, so
+  camelized columns need the `polymorphic_relations` option.
+- Errors Hasura returns (a permission rule, an invalid value) surface as HTTP 400 with the
+  original message; an unreachable endpoint (timeout, DNS, TLS, non-2xx response) surfaces
+  as HTTP 503, so infrastructure incidents stay visible to monitoring.
+
+## Validating against a real instance
+
+`validation/` holds a Postgres + Hasura stack seeded with a Rails-like schema and an
+end-to-end script covering the scenarios above:
+
+```bash
+docker compose -f validation/docker-compose.yml up -d
+bash validation/setup_hasura.sh
+BUNDLE_GEMFILE=Gemfile-test bundle exec ruby validation/validate.rb
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/forest_admin_datasource_graphql_hasura.gemspec

@@ -0,0 +1,35 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift lib unless $LOAD_PATH.include?(lib)
+
+require_relative 'lib/forest_admin_datasource_graphql_hasura/version'
+
+Gem::Specification.new do |spec|
+  spec.name        = 'forest_admin_datasource_graphql_hasura'
+  spec.version     = ForestAdminDatasourceGraphqlHasura::VERSION
+  spec.authors     = ['Forest Admin']
+  spec.email       = ['contact@forestadmin.com']
+  spec.homepage    = 'https://www.forestadmin.com'
+  spec.summary     = 'Hasura GraphQL datasource for Forest Admin Ruby agent.'
+  spec.description = 'Surface tables exposed by a Hasura GraphQL API as Forest Admin collections, ' \
+                     'including Rails-style polymorphic associations.'
+  spec.license     = 'GPL-3.0'
+  spec.required_ruby_version = '>= 3.0.0'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/ForestAdmin/agent-ruby'
+  spec.metadata['changelog_uri']   = 'https://github.com/ForestAdmin/agent-ruby/blob/main/CHANGELOG.md'
+  spec.metadata['rubygems_mfa_required'] = 'false'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ validation/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 6.1'
+  spec.add_dependency 'zeitwerk', '~> 2.3'
+end

data/lib/forest_admin_datasource_graphql_hasura/client.rb

@@ -0,0 +1,117 @@
+require 'json'
+require 'openssl'
+require 'net/http'
+require 'uri'
+
+module ForestAdminDatasourceGraphqlHasura
+  # GraphQL-over-HTTP client for Hasura (queries, mutations and the metadata
+  # API), on Net::HTTP so the gem needs no HTTP dependency.
+  class Client
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    # Wrapped in TransportError (503) so they reach the user as an actionable
+    # message without masquerading as a client mistake: errors Hasura itself
+    # returns are the only ones raised as GraphqlError (400).
+    TRANSPORT_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Net::HTTPBadResponse, IOError, SocketError,
+      SystemCallError, OpenSSL::SSL::SSLError, JSON::ParserError
+    ].freeze
+
+    def execute(query, variables = {})
+      body = JSON.generate({ query: query, variables: variables })
+      response = post(@configuration.uri, body)
+
+      raise TransportError, "GraphQL endpoint returned HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+      # A 204 is a success with a nil body, which JSON.parse would turn into an
+      # unwrapped TypeError.
+      raise TransportError, 'GraphQL endpoint returned an empty body' if response.body.nil? || response.body.empty?
+
+      payload = JSON.parse(response.body)
+      raise TransportError, 'GraphQL endpoint returned an unexpected body' unless payload.is_a?(Hash)
+
+      if payload['errors']&.any?
+        messages = payload['errors'].map { |e| e['message'] }.join('; ')
+        raise GraphqlError, messages
+      end
+
+      # A 200 with neither data nor errors is malformed, and letting a nil out
+      # would crash the caller with an opaque NoMethodError.
+      data = payload['data']
+      raise TransportError, 'GraphQL endpoint returned no data' if data.nil?
+
+      data
+    rescue *TRANSPORT_ERRORS => e
+      raise TransportError, "Could not reach the GraphQL endpoint (#{e.class}): #{e.message}"
+    end
+
+    # Returns nil when the endpoint is unreachable or forbidden, which is common
+    # in production: introspection then falls back to the configuration and to
+    # naming conventions. Every fallback branch warns — losing the metadata
+    # silently disables polymorphism detection and custom root field
+    # resolution, and each cause deserves something to grep for.
+    def fetch_metadata
+      if @configuration.metadata_uri.nil?
+        return metadata_fallback("no metadata endpoint could be derived from uri (no '/v1/graphql' " \
+                                 "segment); set the 'metadata_uri' option")
+      end
+
+      body = JSON.generate({ type: 'export_metadata', version: 2, args: {} })
+      response = post(@configuration.metadata_uri, body)
+
+      return metadata_fallback("the metadata endpoint answered HTTP #{response.code}") unless
+        response.is_a?(Net::HTTPSuccess)
+
+      parse_metadata(response.body)
+    rescue *TRANSPORT_ERRORS => e
+      metadata_fallback("the metadata endpoint is not reachable (#{e.class})")
+    end
+
+    private
+
+    # Guards mirror Client#execute: a 204 passes the HTTPSuccess check with a
+    # nil body, and a JSON body need not be an object. Parse errors are caught
+    # here rather than by the transport rescue, whose "not reachable" message
+    # would be misleading — the endpoint did answer.
+    def parse_metadata(body)
+      return metadata_fallback('the metadata endpoint returned an empty body') if body.nil? || body.empty?
+
+      payload = JSON.parse(body)
+      return metadata_fallback("the metadata response is not a JSON object (#{payload.class})") unless
+        payload.is_a?(Hash)
+
+      metadata = payload['metadata'] || payload
+      return metadata if metadata.is_a?(Hash) && metadata['sources']
+
+      shape = metadata.is_a?(Hash) ? "top-level keys: #{metadata.keys.first(5).join(", ")}" : metadata.class
+      metadata_fallback("the metadata response carries no sources (#{shape})")
+    rescue JSON::ParserError
+      metadata_fallback('the metadata response is not valid JSON')
+    end
+
+    def metadata_fallback(reason)
+      ForestAdminDatasourceGraphqlHasura.logger.warn(
+        "[forest_admin_datasource_graphql_hasura] Hasura metadata unavailable: #{reason}; " \
+        'falling back to configuration and naming conventions.'
+      )
+      nil
+    end
+
+    def post(url, body)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @configuration.timeout
+      http.open_timeout = @configuration.timeout
+      http.write_timeout = @configuration.timeout
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['Content-Type'] = 'application/json'
+      @configuration.headers.each { |key, value| request[key] = value }
+      request.body = body
+
+      http.request(request)
+    end
+  end
+end

data/lib/forest_admin_datasource_graphql_hasura/collection.rb

@@ -0,0 +1,180 @@
+module ForestAdminDatasourceGraphqlHasura
+  class Collection < ForestAdminDatasourceToolkit::Collection
+    ForestException = ForestAdminDatasourceToolkit::Exceptions::ForestException
+    Projection = ForestAdminDatasourceToolkit::Components::Query::Projection
+
+    PLACEHOLDER_REFERENCE = { '*' => nil }.freeze
+
+    attr_reader :table_name, :names
+
+    def initialize(datasource, table, client, converter)
+      super(datasource, converter.collection_name_of(table.name))
+
+      @table = table
+      @table_name = table.name
+      # root is the select root field; base (the GraphQL type name) is what
+      # generated type names derive from; the operation roots carry their own
+      # resolved names, custom or derived. See Query::QueryBuilder.
+      @names = { root: table.name, base: table.type_name }.merge(table.root_fields || {})
+      @client = client
+      @converter = converter
+
+      add_fields(converter.build_fields(table))
+      enable_count
+      schema[:aggregation_capabilities][:supported_date_operations] = []
+    end
+
+    def list(_caller, filter, projection)
+      selection = build_selection(projection)
+      operation = Query::QueryBuilder.list(@names, filter, selection)
+      records = execute(:list, operation)[@names[:root]] || []
+
+      records.map { |record| materialize_polymorphics(record, projection) }
+    end
+
+    def create(_caller, data)
+      operation = Query::QueryBuilder.create(@names, [writable_columns(data)], column_names)
+      returning = execute(:create, operation).dig(@names[:insert], 'returning')
+
+      raise GraphqlError, "No record returned by #{@names[:insert]}" if returning.nil? || returning.empty?
+
+      returning.first
+    end
+
+    def update(_caller, filter, data)
+      if empty_condition?(filter)
+        raise ForestException,
+              "Refusing to update every row of '#{name}': the filter carries no condition."
+      end
+
+      operation = Query::QueryBuilder.update(@names, filter, writable_columns(data))
+      execute(:update, operation)
+    end
+
+    def delete(_caller, filter)
+      operation = Query::QueryBuilder.delete(@names, filter)
+      execute(:delete, operation)
+    end
+
+    def aggregate(_caller, filter, aggregation, limit = nil)
+      Query::Aggregator.new(self).run(filter, aggregation, limit)
+    end
+
+    # Whether a relationship rests on a real foreign key constraint — only the
+    # Hasura metadata knows, and only introspection saw it. False when manual
+    # or when the metadata was unreachable (constraint unproven).
+    def constraint_backed?(relation_name)
+      @table.relationships.any? { |rel| rel.name == relation_name && rel.manual == false }
+    end
+
+    # Wraps every Hasura call so the failing operation is named in the error,
+    # keeping the class (GraphqlError or TransportError) and thus the status.
+    def execute(operation_name, operation)
+      @client.execute(operation[:query], operation[:variables])
+    rescue GraphqlError, TransportError => e
+      raise e.class, "GraphQL #{operation_name} failed on '#{name}': #{e.message}"
+    end
+
+    protected
+
+    # A PolymorphicManyToOne cannot be joined by Hasura, so its discriminator
+    # columns are selected instead and the relation is rebuilt by the serializer
+    # from those two values (see materialize_polymorphics). Protected: called on
+    # the target collection to resolve nested selections.
+    def build_selection(projection)
+      selection = projection.columns.reject { |column| column == '*' }
+
+      projection.relations.each do |relation_name, relation_projection|
+        field = schema[:fields][relation_name]
+        next if field.nil?
+
+        if field.type == 'PolymorphicManyToOne'
+          selection << field.foreign_key
+          selection << field.foreign_key_type_field
+        else
+          target = datasource.get_collection(field.foreign_collection)
+          nested = target.build_selection(relation_projection)
+          selection << "#{relation_name} { #{nested.join(" ")} }"
+        end
+      end
+
+      selection = selection.uniq
+      # An empty projection is a valid toolkit input, but `table { }` is not
+      # valid GraphQL: fall back to the primary key.
+      selection.empty? ? Array(@table.primary_key.first || column_names.first) : selection
+    end
+
+    # The serializer reads the reference off the discriminator columns, so the
+    # relation key only carries a placeholder — which has to be non-empty, since
+    # an empty hash drops the relation from the JSON:API payload. A type matching
+    # no exposed collection stays unresolved: the serializer looks the collection
+    # up by that raw value and would fail the whole page. Nested records walk
+    # down to their own collection, mirroring build_selection: a projection can
+    # reach a polymorphic relation through an ordinary one. Protected, like
+    # build_selection, so target collections can be delegated to.
+    def materialize_polymorphics(record, projection)
+      projection.relations.each do |relation_name, relation_projection|
+        field = schema[:fields][relation_name]
+        next if field.nil?
+
+        if field.type == 'PolymorphicManyToOne'
+          materialize_placeholder(record, relation_name, field)
+        else
+          materialize_nested(record[relation_name], field, relation_projection)
+        end
+      end
+
+      record
+    end
+
+    private
+
+    def column_names
+      @column_names ||= @table.columns.map(&:name)
+    end
+
+    # Selects on the schema rather than on the value type, so that a `jsonb`
+    # column — whose value is a hash, like a relation payload would be — is kept.
+    def writable_columns(data)
+      data.select { |key, _| column_names.include?(key.to_s) }
+    end
+
+    def materialize_placeholder(record, relation_name, field)
+      type_value = record[field.foreign_key_type_field]
+      resolvable = type_value && field.foreign_key_targets.key?(type_value.to_s.gsub('::', '__'))
+      warn_unknown_type(relation_name, type_value) if type_value && !resolvable
+
+      # An explicit nil check: false is a legitimate key value on a boolean
+      # primary key, absent is not.
+      record[relation_name] = resolvable && !record[field.foreign_key].nil? ? PLACEHOLDER_REFERENCE : nil
+    end
+
+    def materialize_nested(nested, field, relation_projection)
+      target = datasource.get_collection(field.foreign_collection)
+
+      case nested
+      when Hash then target.materialize_polymorphics(nested, relation_projection)
+      when Array then nested.each { |row| target.materialize_polymorphics(row, relation_projection) }
+      end
+    end
+
+    def warn_unknown_type(relation_name, type_value)
+      @warned_types ||= Set.new
+      return unless @warned_types.add?("#{relation_name}/#{type_value}")
+
+      ForestAdminDatasourceGraphqlHasura.logger.warn(
+        "[forest_admin_datasource_graphql_hasura] '#{name}.#{relation_name}' references the type " \
+        "'#{type_value}', which matches no exposed collection; those references are shown empty. " \
+        "Use the 'type_values' option if the Rails class name differs from the table name."
+      )
+    end
+
+    # Only guards update: a bulk delete with "select all" legitimately carries no
+    # condition, and wiping is then the requested semantic.
+    def empty_condition?(filter)
+      condition = Query::FilterConverter.convert(filter&.condition_tree)
+
+      condition.nil? || condition.empty?
+    end
+  end
+end

data/lib/forest_admin_datasource_graphql_hasura/configuration.rb

@@ -0,0 +1,72 @@
+module ForestAdminDatasourceGraphqlHasura
+  class Configuration
+    # polymorphic_relations declares associations explicitly when the metadata API
+    # is unreachable: { 'comments' => { 'commentable' => %w[transfers cards] } }.
+    # type_values overrides the Rails class name a table maps to, for those that
+    # `classify` gets wrong: { 'bank_accounts' => 'Banking::Account' }.
+    DEFAULTS = {
+      headers: {},
+      metadata_uri: nil,
+      included_tables: nil,
+      excluded_tables: [],
+      polymorphic_relations: {},
+      type_values: {},
+      timeout: 30
+    }.freeze
+
+    attr_reader :uri, :headers, :metadata_uri, :included_tables, :excluded_tables,
+                :polymorphic_relations, :type_values, :timeout
+
+    def initialize(uri:, **options)
+      raise ConfigurationError, 'uri is required' if uri.nil? || uri.empty?
+
+      unknown = options.keys - DEFAULTS.keys
+      raise ConfigurationError, "Unknown option(s): #{unknown.join(", ")}" if unknown.any?
+
+      @uri = uri
+      # An explicit nil means "the default" (`headers: nil` must not crash every
+      # request), and `default.dup` keeps the DEFAULTS hashes and arrays from
+      # being shared — and mutated — across Configuration instances.
+      DEFAULTS.each do |option, default|
+        instance_variable_set("@#{option}", options[option].nil? ? default.dup : options[option])
+      end
+      validate_polymorphic_relations
+      validate_table_lists
+      # Only derivable from the conventional endpoint path: substituting on any
+      # other uri would silently post metadata commands to the GraphQL endpoint.
+      @metadata_uri ||= uri.include?('/v1/graphql') ? uri.sub('/v1/graphql', '/v1/metadata') : nil
+    end
+
+    # Accepts every spelling a table goes by (root field and type name): an
+    # exclusion must hold under renaming, or it would silently re-expose data.
+    def table_allowed?(*table_names)
+      return false if table_names.any? { |name| excluded_tables.include?(name) }
+      return (table_names & included_tables).any? unless included_tables.nil?
+
+      true
+    end
+
+    private
+
+    # A String by mistake (`included_tables: "users"`) would silently become a
+    # substring check instead of a name match.
+    def validate_table_lists
+      return if excluded_tables.is_a?(Array) && (included_tables.nil? || included_tables.is_a?(Array))
+
+      raise ConfigurationError, 'included_tables and excluded_tables must be arrays of table names'
+    end
+
+    # A misshapen declaration would otherwise crash deep inside introspection as
+    # an opaque NoMethodError instead of naming the option.
+    def validate_polymorphic_relations
+      valid = polymorphic_relations.is_a?(Hash) && polymorphic_relations.all? do |_, bases|
+        bases.is_a?(Hash) && bases.all? { |_, targets| targets.is_a?(Array) }
+      end
+
+      return if valid
+
+      raise ConfigurationError,
+            "polymorphic_relations must be { 'table' => { 'association' => ['target', ...] } }"
+    end
+  end
+end

data/lib/forest_admin_datasource_graphql_hasura/datasource.rb

@@ -0,0 +1,81 @@
+module ForestAdminDatasourceGraphqlHasura
+  class Datasource < ForestAdminDatasourceToolkit::Datasource
+    attr_reader :client, :configuration
+
+    def initialize(uri:, **options)
+      super()
+
+      @configuration = Configuration.new(uri: uri, **options)
+      @client = Client.new(@configuration)
+
+      register_collections
+    end
+
+    private
+
+    def register_collections
+      tables = Introspection::Introspector.new(@client, @configuration).introspect
+      tables = deduplicate_collection_names(tables)
+      # Detection runs on the surviving tables only, so a polymorphic target
+      # can never carry the primary key of a table dedup dropped.
+      Introspection::PolymorphismDetector.new(@configuration).detect(tables)
+      converter = Introspection::SchemaConverter.new(tables, @configuration)
+
+      tables.each do |table|
+        add_collection(Collection.new(self, table, @client, converter))
+      end
+
+      mark_groupable_foreign_keys
+
+      ForestAdminDatasourceGraphqlHasura.logger.info(
+        "[forest_admin_datasource_graphql_hasura] #{tables.size} collections registered " \
+        "(#{tables.sum { |table| table.polymorphics.size }} polymorphic relations detected)."
+      )
+    end
+
+    # `user_status` and `user_statuses` both classify to `UserStatus`, and the
+    # toolkit refuses a duplicate collection name with an error that names
+    # neither table: keep the first (alphabetically, for determinism) and say
+    # which tables collided and how to fix it.
+    def deduplicate_collection_names(tables)
+      converter = Introspection::SchemaConverter.new(tables, @configuration)
+
+      tables.group_by { |table| converter.collection_name_of(table.name) }.flat_map do |name, group|
+        next group.first if group.size == 1
+
+        kept, *dropped = group.sort_by(&:name)
+        ForestAdminDatasourceGraphqlHasura.logger.warn(
+          "[forest_admin_datasource_graphql_hasura] Tables #{group.map(&:name).sort.join(", ")} all map " \
+          "to the collection name '#{name}'; only '#{kept.name}' is exposed " \
+          "(#{dropped.map(&:name).join(", ")} skipped). Disambiguate with the 'type_values' option."
+        )
+        kept
+      end
+    end
+
+    # The capabilities route publishes is_groupable, and grouping goes through the
+    # parent's nested `<relation>_aggregate`, which only exists when Hasura
+    # declares the reverse array relationship: marking a foreign key without one
+    # would have the UI offer a group-by that the aggregator then rejects.
+    def mark_groupable_foreign_keys
+      collections.each_value do |collection|
+        collection.schema[:fields].each_value do |field|
+          next unless field.type == 'ManyToOne' && reverse_declared?(collection, field)
+
+          foreign_key = collection.schema[:fields][field.foreign_key]
+          foreign_key.is_groupable = true if foreign_key.respond_to?(:is_groupable=)
+        end
+      end
+    end
+
+    def reverse_declared?(collection, relation)
+      parent = get_collection(relation.foreign_collection)
+
+      parent.schema[:fields].each_value.any? do |field|
+        field.type == 'OneToMany' &&
+          field.foreign_collection == collection.name &&
+          field.origin_key == relation.foreign_key
+      end
+    end
+  end
+end