graphiti 2.0.0.beta.11 → 2.0.0.beta.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a639e421891e5d5e650d2d8131a75905cb9ffd0fb40cdfd15239ca5caf29d12f
-  data.tar.gz: 95172bbff224d598c959d5acc93c30861e01c50540fdea871ea5029473bf5259
+  metadata.gz: 6e73d0272cfabe57d3eb0cbc82ad7199dea624afead6856ca72c1107857fa144
+  data.tar.gz: 795ddb1e77c8f61d2e74c66c333ccc4acd5c37ccb6aa3b4c7cb816f52dfe1b71
 SHA512:
-  metadata.gz: 24c275cfcaecdba9ced126b7970b37962998673a3a8609c885a69befc53adba646ec2c7d9517198509e358ebba5300f3b336c86f02df98af9d18a6f4a4c306c3
-  data.tar.gz: e7d2fd4e0d0ff74b68ea4d3673399d1b72897ad7c8647fa38835ff2b58c850d58ba95a1145a52f55893e88e36eb0aa90bece72a2e6e593173661d16100666edc
+  metadata.gz: f5ff1c0630702209372d0512afd16d29c87d6f561c551e08a5080bd25efa8b3bae465d33729129289a3ade41db781b779bffd753b55f6cf7cf02389662fa835e
+  data.tar.gz: '0785ff7bd32570ef7bf588c7287b4704d7f9daf50bafb47f0739f02b054086a297cef4427364f818b5ab540a72935447bead5898957f597a400a40b435f4a81f'

data/.github/workflows/ci.yml

@@ -85,6 +85,12 @@ jobs:
           bundler-cache: true
       - name: Run tests
         run: bundle exec rspec
+      # spec_helper narrows "bundle exec rspec" to spec/integration/rails when
+      # APPRAISAL_INITIALIZED is set, so the step above never runs the library
+      # suite. This is the only cell that runs it against a pinned Rails.
+      - name: Run the library suite against this Rails
+        if: matrix.appraisal
+        run: env -u APPRAISAL_INITIALIZED bundle exec rspec
   example-app:
     name: "Example app (employee_directory)"
     runs-on: ubuntu-latest

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 graphiti changelog
 
+# [2.0.0-beta.12](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.11...v2.0.0-beta.12) (2026-08-30)
+
+
+### Bug Fixes
+
+* compare each concurrency path against itself in the table to better illustrate the performance wins ([d0f0e92](https://github.com/graphiti-api/graphiti/commit/d0f0e92860b3b4affe3fca6dbb9b871fe8a1374f))
+
+
+### Features
+
+* add schema rake tasks, so checking a schema no longer means running the suite ([6f4783d](https://github.com/graphiti-api/graphiti/commit/6f4783d5654659125b7eb358bf1175b6feaacb7c))
+* declare Graphiti's client errors in rescue_responses ([e369824](https://github.com/graphiti-api/graphiti/commit/e369824d6e11b671ffd212caad3d0a43a7ceefcf))
+* mark deprecated settings in the generated ApplicationResource ([52b0642](https://github.com/graphiti-api/graphiti/commit/52b0642e689a16d14dacaf4e28a2641f10774cf0))
+* take error text from locale keys ([d01fd06](https://github.com/graphiti-api/graphiti/commit/d01fd06fc1ede8c3dd798ec48de4d5b01645d87e)), closes [#216](https://github.com/graphiti-api/graphiti/issues/216)
+
 # [2.0.0-beta.11](https://github.com/graphiti-api/graphiti/compare/v2.0.0-beta.10...v2.0.0-beta.11) (2026-08-27)
 
 

data/lib/generators/graphiti/generator_mixin.rb

@@ -50,11 +50,12 @@ module Graphiti
     end
 
     def resource_setting_hint(setting)
-      return setting[:note] if setting[:note]
-      return unless setting[:values]
+      hint = setting[:note] || setting[:values]&.map(&:inspect)
+        &.to_sentence(two_words_connector: " or ", last_word_connector: ", or ")
 
-      setting[:values].map(&:inspect)
-        .to_sentence(two_words_connector: " or ", last_word_connector: ", or ")
+      return hint unless setting[:deprecated]
+
+      ["deprecated, removed in 3.0", hint].compact.join(". ")
     end
 
     def graphiti_config

data/lib/generators/graphiti/install_generator.rb

@@ -1,4 +1,5 @@
 require_relative "generator_mixin"
+require_relative "locale_generator"
 
 module Graphiti
   class InstallGenerator < ::Rails::Generators::Base
@@ -17,6 +18,8 @@ module Graphiti
       to = File.join("app/resources", "application_resource.rb")
       template("application_resource.rb.erb", to)
 
+      invoke(Graphiti::LocaleGenerator, [], options)
+
       inject_into_file "app/controllers/application_controller.rb", after: "class ApplicationController < ActionController::API\n" do
         app_controller_code
       end

data/lib/generators/graphiti/locale_generator.rb

@@ -0,0 +1,30 @@
+module Graphiti
+  class LocaleGenerator < ::Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :"omit-comments",
+      type: :boolean,
+      default: false,
+      aliases: ["-c"],
+      desc: "Generate without documentation comments"
+
+    desc "Writes the error text Graphiti renders, ready to edit"
+    def locale
+      template("locale.yml.erb", File.join("config/locales", "graphiti.en.yml"))
+    end
+
+    private
+
+    def omit_comments?
+      @options["omit-comments"]
+    end
+
+    def default_messages
+      Graphiti::Util::SimpleErrors::DEFAULT_MESSAGES
+    end
+
+    def default_format
+      Graphiti::Util::SimpleErrors::DEFAULT_FORMAT
+    end
+  end
+end

data/lib/generators/graphiti/templates/locale.yml.erb

@@ -0,0 +1,22 @@
+<%- unless omit_comments? -%>
+# Everything Graphiti puts in an errors payload.
+# For another language, add a block below or a graphiti.<locale>.yml file.
+<%- end -%>
+en:
+  graphiti:
+    errors:
+<%- unless omit_comments? -%>
+      # Titles and details are keyed by error code, and Graphiti ships none.
+      # Without a key you get the HTTP status name and no detail.
+      #
+      # internal_server_error:
+      #   title: "Something went wrong"
+      #   detail: "We've probably received an error report already, but please contact us if the issue persists."
+      #
+      # format joins them: "data.attributes.title is an unknown attribute".
+<%- end -%>
+      format: <%= default_format.inspect %>
+      messages:
+<%- default_messages.each do |code, message| -%>
+        <%= code %>: <%= message.inspect %>
+<%- end -%>

data/lib/graphiti/error_serializers/conflict_request.rb

@@ -11,7 +11,7 @@ module Graphiti
         "conflict"
       end
 
-      def title
+      def default_title
         "Conflict Error"
       end
     end

data/lib/graphiti/error_serializers/deprecated_constants.rb

@@ -1,25 +1,15 @@
-# The graphiti_errors gem was absorbed into graphiti in 2.0. Only its
-# serializers survived, as Graphiti::ErrorSerializers. The rest of it (the
-# GraphitiErrors controller mixin and its exception handlers) is replaced by
-# rescue_registry rather than renamed, so there is deliberately nothing here to
-# alias it to. A custom error renderer reaching for one of the serializers gets
-# pointed at the new name instead of a bare NameError. Remove in 3.0.
+# Only graphiti_errors' serializers survived the 2.0 merge. Remove in 3.0.
 module GraphitiErrors
-  # `include GraphitiErrors` in ApplicationController was this gem's headline
-  # usage. Including an empty module succeeds, so without this an upgraded app
-  # boots clean and then serves Rails' default HTML error pages instead of
-  # JSON:API ones, with nothing to indicate why.
+  # Including an empty module succeeds, so silence here means HTML error pages.
   def self.included(klass)
     raise <<~MSG
-      GraphitiErrors was merged into graphiti as of 2.0 and `include GraphitiErrors`
-      no longer does anything.
-
-      Exception handling now goes through rescue_registry. Replace it with:
+      GraphitiErrors merged into graphiti in 2.0 and this include does nothing. Use:
 
         include Graphiti::Rails::Controller
 
-      which registers Graphiti's own handlers. Your own go alongside them with
-      `register_exception`, available on every controller.
+      Your own exceptions register alongside Graphiti's with `register_exception`.
+      `registered_exception?` is now `RescueRegistry.handles_exception?`, and
+      `handle_exception` went with the rendering. See graphiti.dev/upgrading.
     MSG
   end
 

data/lib/graphiti/error_serializers/invalid_request.rb

@@ -49,6 +49,12 @@ module Graphiti
       end
 
       def title
+        return default_title unless defined?(::I18n)
+
+        ::I18n.t :title, scope: [:graphiti, :errors, code], default: default_title
+      end
+
+      def default_title
         "Request Error"
       end
 

data/lib/graphiti/rails/exception_handlers.rb

@@ -40,6 +40,23 @@ module Graphiti
         end
         super
       end
+
+      private
+
+      def title_from_status
+        translate(:title) || super
+      end
+
+      # rescue_registry's default tells the client its engineers have been notified.
+      def default_detail_for_status
+        translate(:detail)
+      end
+
+      def translate(key)
+        return unless defined?(::I18n)
+
+        ::I18n.t key, scope: [:graphiti, :errors, error_code], default: nil
+      end
     end
 
     class FallbackHandler < ExceptionHandler

data/lib/graphiti/rails/railtie.rb

@@ -20,6 +20,16 @@ module Graphiti
         load File.expand_path("../../tasks/graphiti.rake", __dir__)
       end
 
+      # ActionDispatch has already copied config.action_dispatch.rescue_responses into the wrapper by now.
+      initializer "graphiti-rails.rescue_responses", after: "action_dispatch.configure" do
+        responses = ActionDispatch::ExceptionWrapper.rescue_responses
+
+        Graphiti::Rails::CLIENT_ERROR_STATUSES.each do |exception, status|
+          # rescue_responses answers :internal_server_error for a missing key, so ||= never assigns.
+          responses[exception] = status unless responses.key?(exception)
+        end
+      end
+
       initializer "graphiti-rails.config" do |app|
         Graphiti::Rails.handled_exception_formats = app.config.graphiti.handled_exception_formats
         Graphiti::Rails.respond_to_formats = app.config.graphiti.respond_to_formats

data/lib/graphiti/rails/rake_helpers.rb

@@ -15,6 +15,11 @@ module Graphiti
         @session ||= ActionDispatch::Integration::Session.new(::Rails.application)
       end
 
+      # An engine runs the task from its own directory, not the host application's root.
+      def schema_path(path = nil)
+        path.nil? ? Graphiti.config.schema_path : File.expand_path(path, Dir.pwd)
+      end
+
       def setup_rails!
         ::Rails.application.eager_load!
         ::Rails.application.config.cache_classes = true

data/lib/graphiti/rails.rb

@@ -38,6 +38,24 @@ module Graphiti
       DEPRECATOR
     )
 
+    # Rails reports an exception to the error reporter unless its rescue_responses names it.
+    CLIENT_ERROR_STATUSES = {
+      "Graphiti::Errors::InvalidRequest" => :bad_request,
+      "Graphiti::Errors::RemoteWrite" => :bad_request,
+      "Graphiti::Errors::SingularSideload" => :bad_request,
+      "Graphiti::Errors::InvalidInclude" => :bad_request,
+      "Graphiti::Errors::UnsupportedSort" => :bad_request,
+      "Graphiti::Errors::UnsupportedOperator" => :bad_request,
+      "Graphiti::Errors::InvalidFilterValue" => :bad_request,
+      "Graphiti::Errors::RequiredFilter" => :bad_request,
+      "Graphiti::Errors::UnsupportedPageSize" => :bad_request,
+      "Graphiti::Errors::UnsupportedBeforeCursor" => :bad_request,
+      "Graphiti::Errors::UnsupportedPagination" => :bad_request,
+      "Graphiti::Errors::FilterGroupMissingRequiredFilters" => :bad_request,
+      "Graphiti::Errors::RecordNotFound" => :not_found,
+      "Graphiti::Errors::ConflictRequest" => :conflict
+    }.freeze
+
     # @!attribute self.handled_exception_formats
     # A list of formats as symbols whose exceptions will be handled by Graphiti. See {Railtie}.
     cattr_accessor :handled_exception_formats, default: []

data/lib/graphiti/request_validators/update_validator.rb

@@ -13,11 +13,7 @@ module Graphiti
 
       def attribute_mismatch(attr_path)
         @error_class = Graphiti::Errors::ConflictRequest
-        @errors.add(
-          attr_path.join("."),
-          :attribute_mismatch,
-          message: "does not match the server endpoint"
-        )
+        @errors.add(attr_path.join("."), :attribute_mismatch)
       end
 
       def required_payload?

data/lib/graphiti/request_validators/validator.rb

@@ -54,14 +54,14 @@ module Graphiti
         page = @params[:page]
         return if page.nil? || page.respond_to?(:each_pair)
 
-        @errors.add(:page, :invalid, message: "must be an object")
+        @errors.add(:page, :invalid)
       end
 
       def validate_data_shape
         data = @params[:data]
         return true if data.nil? || data.respond_to?(:each_pair)
 
-        @errors.add(:data, :invalid, message: "must be an object")
+        @errors.add(:data, :invalid)
         false
       end
 
@@ -69,7 +69,7 @@ module Graphiti
         relationships.each_key do |name|
           unless resource.class.sideload(name.to_sym)
             full_key = fully_qualified_key(name, payload_path, :relationships)
-            @errors.add(full_key, :invalid_relationship, message: "is not a valid relationship")
+            @errors.add(full_key, :invalid_relationship)
           end
         end
 
@@ -110,11 +110,11 @@ module Graphiti
             begin
               attributes[key] = resource.typecast(key, value, :writable)
             rescue Graphiti::Errors::UnknownAttribute
-              @errors.add(fully_qualified_key(key, payload_path), :unknown_attribute, message: "is an unknown attribute")
+              @errors.add(fully_qualified_key(key, payload_path), :unknown_attribute)
             rescue Graphiti::Errors::InvalidAttributeAccess
-              @errors.add(fully_qualified_key(key, payload_path), :unwritable_attribute, message: "cannot be written")
+              @errors.add(fully_qualified_key(key, payload_path), :unwritable_attribute)
             rescue Graphiti::Errors::TypecastFailed => e
-              @errors.add(fully_qualified_key(key, payload_path), :type_error, message: "should be type #{e.type_name}")
+              @errors.add(fully_qualified_key(key, payload_path), :type_error, type: e.type_name)
             end
           end
         end

data/lib/graphiti/schema/check.rb

@@ -0,0 +1,69 @@
+module Graphiti
+  class Schema
+    class Check
+      attr_reader :path, :errors
+
+      def initialize(schema, path)
+        @path = path
+        @schema = schema
+        @generated = normalize(schema)
+        @committed = normalize(JSON.parse(File.read(path))) if File.exist?(path)
+        @errors = @committed ? SchemaDiff.new(@committed, @generated).compare : []
+      end
+
+      def missing?
+        @committed.nil?
+      end
+
+      def stale?
+        !missing? && @committed != @generated
+      end
+
+      def compatible?
+        errors.empty?
+      end
+
+      def ok?
+        !missing? && !stale? && compatible?
+      end
+
+      def write!
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, JSON.pretty_generate(@schema))
+        path
+      end
+
+      def message
+        return "Schema is up to date: #{path}" if ok?
+        return "#{missing_message}\n\n#{regenerate}" if missing?
+        return "#{incompatible_message}\n\n#{errors.join("\n")}" unless compatible?
+
+        "Schema file is outdated: #{path}\n\n#{regenerate}"
+      end
+
+      private
+
+      def normalize(schema)
+        JSON.parse(JSON.generate(schema))
+      end
+
+      def missing_message
+        "Schema file not found: #{path}"
+      end
+
+      def incompatible_message
+        <<~MSG.chomp
+          Found backwards-incompatibilities in schema: #{path}
+
+          Re-run with FORCE_SCHEMA=true to accept them and overwrite the file.
+
+          Incompatibilities:
+        MSG
+      end
+
+      def regenerate
+        "Run `rake graphiti:schema:generate` and commit the file."
+      end
+    end
+  end
+end

data/lib/graphiti/schema.rb

@@ -11,19 +11,18 @@ module Graphiti
       new(resources).generate
     end
 
-    def self.generate!(resources = nil)
-      schema = generate(resources)
+    def self.generate!(resources = nil, path: Graphiti.config.schema_path, force: ENV["FORCE_SCHEMA"] == "true")
+      result = check(resources, path: path)
+      return result.errors if !force && !result.compatible?
 
-      if ENV["FORCE_SCHEMA"] != "true" && File.exist?(Graphiti.config.schema_path)
-        old = JSON.parse(File.read(Graphiti.config.schema_path))
-        errors = Graphiti::SchemaDiff.new(old, schema).compare
-        return errors if errors.any?
-      end
-      FileUtils.mkdir_p(Graphiti.config.schema_path.to_s.gsub("/schema.json", ""))
-      File.write(Graphiti.config.schema_path, JSON.pretty_generate(schema))
+      result.write!
       []
     end
 
+    def self.check(resources = nil, path: Graphiti.config.schema_path)
+      Check.new(generate(resources), path)
+    end
+
     def initialize(resources)
       @resources = resources.sort_by(&:name)
       @remote_resources = @resources.select(&:remote?)

data/lib/graphiti/spec_helpers/rspec.rb

@@ -127,22 +127,14 @@ module Graphiti
         end
       end
 
-      def self.schema!(resources = nil)
+      def self.schema!(resources = nil, path: nil)
         ::RSpec.describe "Graphiti Schema" do
           it "generates a backwards-compatible schema" do
-            message = <<~MSG
-              Found backwards-incompatibilities in schema! Run with FORCE_SCHEMA=true to ignore.
+            check = Graphiti::Schema.check(resources, path: path || Graphiti.config.schema_path)
+            forced = ENV["FORCE_SCHEMA"] == "true"
+            check.write! if check.compatible? || forced
 
-              Incompatibilities:
-
-            MSG
-
-            errors = Graphiti::Schema.generate!(resources)
-            errors.each do |e|
-              message << "#{e}\n"
-            end
-
-            expect(errors.empty?).to eq(true), message
+            expect(check.compatible? || forced).to eq(true), check.message
           end
         end
       end

data/lib/graphiti/util/simple_errors.rb

@@ -6,6 +6,21 @@ module Graphiti
     class SimpleErrors
       include Enumerable
 
+      # Overridable under graphiti.errors.messages.
+      DEFAULT_MESSAGES = {
+        missing: "is missing",
+        invalid: "must be an object",
+        invalid_relationship: "is not a valid relationship",
+        unwritable_relationship: "cannot be written",
+        unknown_attribute: "is an unknown attribute",
+        unwritable_attribute: "cannot be written",
+        type_error: "should be type %{type}",
+        attribute_mismatch: "does not match the server endpoint"
+      }.freeze
+
+      # Joins an attribute to its message, like Rails' own errors.format.
+      DEFAULT_FORMAT = "%{attribute} %{message}"
+
       attr_reader :messages, :details
 
       def initialize(validation_target)
@@ -50,11 +65,9 @@ module Graphiti
       end
       alias_method :blank?, :empty?
 
-      def add(attribute, code, message: nil)
-        message ||= "is #{code.to_s.humanize.downcase}"
-
+      def add(attribute, code, message: nil, **interpolations)
         details[attribute.to_sym] << {error: code}
-        messages[attribute.to_sym] << message
+        messages[attribute.to_sym] << translate(code, message, **interpolations, attribute: attribute)
       end
 
       def added?(attribute, code)
@@ -73,11 +86,19 @@ module Graphiti
 
       def full_message(attribute, message)
         return message if attribute == :base
-        "#{attribute} #{message}"
+
+        translate(:format, DEFAULT_FORMAT, [:graphiti, :errors], attribute: attribute, message: message)
       end
 
       private
 
+      def translate(key, fallback, scope = [:graphiti, :errors, :messages], **interpolations)
+        fallback ||= DEFAULT_MESSAGES.fetch(key) { "is #{key.to_s.humanize.downcase}" }
+        return fallback % interpolations unless defined?(::I18n)
+
+        ::I18n.t(key, scope: scope, default: fallback, **interpolations)
+      end
+
       def apply_default_array(hash)
         hash.default_proc = proc { |h, key| h[key] = [] }
         hash

data/lib/graphiti/version.rb

@@ -1,3 +1,3 @@
 module Graphiti
-  VERSION = "2.0.0.beta.11"
+  VERSION = "2.0.0.beta.12"
 end

data/lib/graphiti.rb

@@ -175,6 +175,7 @@ require "graphiti/audit"
 require "graphiti/audit/report"
 require "graphiti/schema"
 require "graphiti/schema_diff"
+require "graphiti/schema/check"
 require "graphiti/adapters/abstract"
 require "graphiti/resource/sideloading"
 require "graphiti/resource/links"

data/lib/tasks/graphiti.rake

@@ -16,6 +16,24 @@ namespace :graphiti do
     Graphiti::Debugger.flush if debug
   end
 
+  namespace :schema do
+    desc "Write the schema file. Refuses backwards-incompatible changes unless FORCE_SCHEMA=true. Takes an optional path, defaulting to Graphiti.config.schema_path."
+    task :generate, [:path] => [:environment] do |_, args|
+      check = Graphiti::Schema.check(path: helpers.schema_path(args[:path]))
+      abort check.message unless check.compatible? || ENV["FORCE_SCHEMA"] == "true"
+
+      puts "Schema written: #{check.write!}"
+    end
+
+    desc "Fail unless the committed schema file exists, is up to date, and is backwards-compatible. Takes an optional path, defaulting to Graphiti.config.schema_path."
+    task :check, [:path] => [:environment] do |_, args|
+      check = Graphiti::Schema.check(path: helpers.schema_path(args[:path]))
+      abort check.message unless check.ok?
+
+      puts check.message
+    end
+  end
+
   desc "Audit every relationship: what will raise, what loads to render ids, which render no ids, and which checks passed."
   task audit: [:environment] do
     helpers.setup_rails!

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 2.0.0.beta.11
+  version: 2.0.0.beta.12
 platform: ruby
 authors:
 - Lee Richmond
@@ -287,6 +287,7 @@ files:
 - lib/generators/graphiti/api_test_generator.rb
 - lib/generators/graphiti/generator_mixin.rb
 - lib/generators/graphiti/install_generator.rb
+- lib/generators/graphiti/locale_generator.rb
 - lib/generators/graphiti/resource_generator.rb
 - lib/generators/graphiti/resource_test_generator.rb
 - lib/generators/graphiti/templates/application_resource.rb.erb
@@ -294,6 +295,7 @@ files:
 - lib/generators/graphiti/templates/create_request_spec.rb.erb
 - lib/generators/graphiti/templates/destroy_request_spec.rb.erb
 - lib/generators/graphiti/templates/index_request_spec.rb.erb
+- lib/generators/graphiti/templates/locale.yml.erb
 - lib/generators/graphiti/templates/resource.rb.erb
 - lib/generators/graphiti/templates/resource_reads_spec.rb.erb
 - lib/generators/graphiti/templates/resource_writes_spec.rb.erb
@@ -359,6 +361,7 @@ files:
 - lib/graphiti/responders.rb
 - lib/graphiti/runner.rb
 - lib/graphiti/schema.rb
+- lib/graphiti/schema/check.rb
 - lib/graphiti/schema_diff.rb
 - lib/graphiti/scope.rb
 - lib/graphiti/scoping/base.rb