graphiti 1.11.1 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86630b0954711272a5cb2d37e3ba983eea16b580626fe6ef37479b5cbe1ef26b
-  data.tar.gz: 331e7c4a78b57a7362986bd0f49348cee046df52683e0f27e82564d8ff4fa3e9
+  metadata.gz: 0ffd673e5dc4ec50d5b5aeb01abcb192894c6451cd9bfd54eca081f76bdf1d49
+  data.tar.gz: 45ed5cf75d703bd9b573015cd7f798cdc8fe1d5606d198bbdbda09d8e9dd7383
 SHA512:
-  metadata.gz: b6ee44eadb2f7e6a7c37801326557a1e88bd6921dc5aca76cbd94fe4159bd8d54bfc617c92086b9dc7d9bbdcc3d5925d846213f334dbe5f25726394842acb50a
-  data.tar.gz: c1c0e49eb82a6afde05dac7628175e582590fc17fb04bf2aabe64050a31a5870e3f1dfcd1e07d21186635ae923cad1b6b51e4d811d9e86f1437576389da13d99
+  metadata.gz: 1472ab72a4ba8982a06a99d4959460ddae1e350ac6f1ce579dbe694c9c2cac6901e46d74b61532895f248e29848361aa311f39320201cb94f002874d64b34386
+  data.tar.gz: 44d3d9fbb1f78c6ba6a1fe005dc19a9f64a7b15236075b224571d585754928352d032a5acccd7f6165695990ff5a66750868a13ebd87fec9d33e9446e599fb97

data/.github/workflows/ci.yml

@@ -4,6 +4,7 @@ on:
   push:
     branches: [main]
   pull_request: {}
+  workflow_dispatch: {}
 
 concurrency:
   group: ci-${{ github.head_ref || github.ref }}

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 graphiti changelog
 
+# [1.12.0](https://github.com/graphiti-api/graphiti/compare/v1.11.1...v1.12.0) (2026-07-29)
+
+
+### Bug Fixes
+
+* GQL name chaining ([#415](https://github.com/graphiti-api/graphiti/issues/415)) [skip ci] ([930928a](https://github.com/graphiti-api/graphiti/commit/930928a8779037efbcc1989eef5cf579c608e431))
+
+
+### Features
+
+* conditional relationships evaluate readable/writable guards per-request ([#450](https://github.com/graphiti-api/graphiti/issues/450)) ([3ed3187](https://github.com/graphiti-api/graphiti/commit/3ed3187068d268cd85ee1c36dc8135aa92abd05c))
+* pass the model and attribute name to writable guards ([#511](https://github.com/graphiti-api/graphiti/issues/511)) [skip ci] ([24a8a94](https://github.com/graphiti-api/graphiti/commit/24a8a94f801867f57cc7c1ae9c6a9bdbfec05c24))
+
 ## [1.11.1](https://github.com/graphiti-api/graphiti/compare/v1.11.0...v1.11.1) (2026-07-28)
 
 # [1.11.0](https://github.com/graphiti-api/graphiti/compare/v1.10.3...v1.11.0) (2026-07-28)

data/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+## Commit messages
+
+Releases are cut automatically by [semantic-release](https://github.com/semantic-release/semantic-release)
+from commit messages, so the prefix you use decides whether a release happens
+and how the version changes.
+
+Format: `type: subject`, or `type(scope): subject`.
+
+### Types that release
+
+| Prefix | Version bump | Use for |
+| ------ | ------------ | ------- |
+| `fix:` | patch (`1.2.3` → `1.2.4`) | A bug fix users would notice |
+| `perf:` | patch | A performance improvement |
+| `feat:` | minor (`1.2.3` → `1.3.0`) | New functionality |
+
+### Types that do not release
+
+`build:` `chore:` `ci:` `docs:` `refactor:` `style:` `test:`
+
+These land on `main` without publishing a gem. Use them for anything with no
+user-facing change — test fixes, CI tweaks, internal refactors. They are still
+included in the next release's notes.
+
+### Breaking changes
+
+Either add `!` after the type, or a `BREAKING CHANGE:` footer. Both produce a
+major bump (`1.2.3` → `2.0.0`):
+
+```
+feat!: remove deprecated sideload API
+```
+
+```
+feat: replace sideload API
+
+BREAKING CHANGE: `allow_sideload` no longer accepts a :scope option.
+```
+
+The `!` works with a scope too: `feat(adapters)!: ...`
+
+Describe what breaks and what to do instead — the footer text is published in
+the release notes verbatim.
+
+### Notes
+
+- Only the **commit** prefix matters, not the PR title, unless the PR is
+  squash-merged with the title as the commit subject.
+- The prefix must be lowercase and followed by `: ` — `Fix: thing` and
+  `fix:thing` are both unparsed, and an unparsed commit never triggers a
+  release.
+- If nothing since the last tag is `fix:`, `perf:`, `feat:`, or breaking, no
+  release is cut. That is expected.
+
+## Running the tests
+
+```sh
+bundle exec rspec
+```
+
+The Rails integration specs are gated behind an environment variable and are
+**silently skipped** without it — a plain `rspec` run reports success while
+covering none of the ActiveRecord adapter:
+
+```sh
+BUNDLE_GEMFILE=gemfiles/rails_8_0_graphiti_rails.gemfile \
+  APPRAISAL_INITIALIZED=1 \
+  bundle exec rspec spec/integration/rails/
+```
+
+Lint with:
+
+```sh
+bundle exec standardrb
+```

data/graphiti.gemspec

@@ -18,6 +18,24 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.required_ruby_version = ">= 2.7"
 
+  # TODO: remove once the 1.12 upgrade window has passed
+  spec.post_install_message = <<~MSG
+    Graphiti: relationship readable:/writable: guards are now enforced.
+
+    Symbols, strings, and procs passed to a relationship's readable/writable
+    guards were always interpreted as true and never actually called before this
+    conditional relationship change. They are now evaluated per-request, where
+    unreadable relationships are omitted from responses and includes, and unwritable
+    relationships reject writes.
+
+    To list every affected relationship in your app:
+
+      bin/rails runner 'puts Graphiti.guarded_relationships'
+
+    Audit these before deploying. Apps using schema.json will also see affected 
+    relationships flagged as "became guarded" by the schema check.
+  MSG
+
   spec.add_dependency "jsonapi-serializable", "~> 0.3.0"
   spec.add_dependency "jsonapi-renderer", "~> 0.2", ">= 0.2.2"
   spec.add_dependency "dry-types", ">= 0.15.0", "< 2.0"

data/lib/graphiti/hash_renderer.rb

@@ -70,13 +70,13 @@ module Graphiti
 
           serializers = v.send(:resources)
           name = graphql ? k.to_s.camelize(:lower) : k
-          name_chain = name_chain.dup
-          name_chain << k unless name_chain.last == k
+          subchain = name_chain.dup
+          subchain << k unless subchain.last == k
 
           unless remote_resource? && serializers.nil?
             payload = if serializers.is_a?(Array)
               data = serializers.map { |rr|
-                rr.to_hash(fields: fields, include: nested_include, graphql: graphql, name_chain: name_chain)
+                rr.to_hash(fields: fields, include: nested_include, graphql: graphql, name_chain: subchain)
               }
               graphql ? {nodes: data} : data
             elsif serializers.nil?
@@ -86,7 +86,7 @@ module Graphiti
                 end
               end
             else
-              serializers.to_hash(fields: fields, include: nested_include, graphql: graphql, name_chain: name_chain)
+              serializers.to_hash(fields: fields, include: nested_include, graphql: graphql, name_chain: subchain)
             end
 
             attrs[name.to_sym] = payload

data/lib/graphiti/query.rb

@@ -211,10 +211,13 @@ module Graphiti
           allowlist = allowlist[@resource.context_namespace] if allowlist
         end
 
-        allowlist ? Util::IncludeParams.scrub(requested, allowlist) : requested
-      end
+        scrubbed = allowlist ? Util::IncludeParams.scrub(requested, allowlist) : requested
 
-      @include_hash
+        scrubbed.filter do |key, value|
+          sideload = @resource.class.sideload(key)
+          sideload.nil? ? true : sideload.readable?
+        end
+      end
     end
 
     def stats

data/lib/graphiti/request_validators/validator.rb

@@ -83,20 +83,22 @@ module Graphiti
       end
 
       def typecast_attributes(resource, attributes, action, payload_path)
-        attributes.each_pair do |key, value|
-          # Only validate id if create action, otherwise it's only used for lookup
-          next if action != :create &&
-            key == :id &&
-            resource.class.config[:attributes][:id][:writable] == false
-
-          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")
-          rescue Graphiti::Errors::InvalidAttributeAccess
-            @errors.add(fully_qualified_key(key, payload_path), :unwritable_attribute, message: "cannot be written")
-          rescue Graphiti::Errors::TypecastFailed => e
-            @errors.add(fully_qualified_key(key, payload_path), :type_error, message: "should be type #{e.type_name}")
+        resource.with_guarded_write(action, attributes[:id]) do
+          attributes.each_pair do |key, value|
+            # Only validate id if create action, otherwise it's only used for lookup
+            next if action != :create &&
+              key == :id &&
+              resource.class.config[:attributes][:id][:writable] == false
+
+            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")
+            rescue Graphiti::Errors::InvalidAttributeAccess
+              @errors.add(fully_qualified_key(key, payload_path), :unwritable_attribute, message: "cannot be written")
+            rescue Graphiti::Errors::TypecastFailed => e
+              @errors.add(fully_qualified_key(key, payload_path), :type_error, message: "should be type #{e.type_name}")
+            end
           end
         end
       end

data/lib/graphiti/resource.rb

@@ -67,6 +67,32 @@ module Graphiti
       adapter.base_scope(model)
     end
 
+    # Exposes write context to attribute guards for the duration of the block.
+    # @api private
+    def with_guarded_write(action, id)
+      @guarded_write = {action: action, id: id}
+      yield
+    ensure
+      remove_instance_variable(:@guarded_write) if defined?(@guarded_write)
+      remove_instance_variable(:@guard_model) if defined?(@guard_model)
+    end
+
+    # The model a writable guard is being asked about. Resolved lazily and
+    # memoized, so it costs nothing unless a guard asks for it, and is only
+    # resolved once per payload. On create, this is a new unsaved instance.
+    # @api private
+    def guard_model
+      return @guard_model if defined?(@guard_model)
+
+      @guard_model = if !defined?(@guarded_write)
+        nil
+      elsif @guarded_write[:action] == :create || @guarded_write[:id].nil?
+        build(model)
+      else
+        self.class._find(id: @guarded_write[:id]).data
+      end
+    end
+
     def typecast(name, value, flag)
       att = get_attr!(name, flag, request: true)
       type_name = att[:type]

data/lib/graphiti/schema.rb

@@ -247,6 +247,10 @@ module Graphiti
             schema[:single] = true
           end
 
+          if config.guarded?
+            schema[:guard] = true
+          end
+
           r[name] = schema
         end
       end

data/lib/graphiti/schema_diff.rb

@@ -102,6 +102,10 @@ module Graphiti
           next
         end
 
+        if new_rel[:guard] && !old_rel[:guard]
+          @errors << "#{old_resource[:name]}: relationship #{name.inspect} became guarded."
+        end
+
         if new_rel[:resource] != old_rel[:resource]
           @errors << "#{old_resource[:name]}: relationship #{name.inspect} changed resource from #{old_rel[:resource]} to #{new_rel[:resource]}."
         end

data/lib/graphiti/serializer.rb

@@ -28,6 +28,9 @@ module Graphiti
           prev = Util::Hash.deep_dup(field_condition_blocks)
           super
           self.field_condition_blocks = prev
+          # _register_condition mutates the hash, which ancestors share by
+          # reference until reassigned - copy first so the guard doesn't leak.
+          self.relationship_condition_blocks = Util::Hash.deep_dup(relationship_condition_blocks)
           _register_condition(relationship_condition_blocks, name, options)
         end
 

data/lib/graphiti/sideload.rb

@@ -99,11 +99,15 @@ module Graphiti
     end
 
     def readable?
-      !!@readable
+      evaluate_flag @readable
     end
 
     def writable?
-      !!@writable
+      evaluate_flag @writable
+    end
+
+    def guarded?
+      dynamic_flag?(@readable) || dynamic_flag?(@writable)
     end
 
     def single?
@@ -454,20 +458,50 @@ module Graphiti
       Util::Class.namespace_for(klass)
     end
 
-    # TODO: call this at runtime to support procs
+    def dynamic_flag?(flag)
+      flag.is_a?(Symbol) || flag.is_a?(String) || flag.is_a?(Proc)
+    end
+
+    # The guard method may be defined on either resource. The declaring side
+    # wins (`has_many :positions, readable: :admin?` calls EmployeeResource#admin?,
+    # matching how attribute guards resolve). If the related resource is the only place
+    # that defines it, the guard runs there. For instance, PositionResource#admin? can guard
+    # every relationship that points at positions.
+
     def evaluate_flag(flag)
       return false if flag.blank?
 
-      case flag.class.name
-      when "Symbol", "String"
-        resource.send(flag)
-      when "Proc"
-        resource.instance_exec(&flag)
+      case flag
+      when Symbol, String
+        guard_resource(flag).send(flag)
+      when Proc
+        evaluate_guard_proc(flag)
       else
         !!flag
       end
     end
 
+    # Private methods are eligible - guards are often not part of a
+    # resource's public API.
+    def guard_resource(method_name)
+      if !parent_resource.respond_to?(method_name, true) &&
+          resource.respond_to?(method_name, true)
+        resource
+      else
+        parent_resource
+      end
+    end
+
+    # A proc can't be introspected the way a method name can, so run it
+    # against the declaring resource and only reach for the related one if
+    # that resource turns out not to define what the proc references.
+    def evaluate_guard_proc(flag)
+      parent_resource.instance_exec(&flag)
+    rescue NameError => error
+      raise error unless resource.respond_to?(error.name, true)
+      resource.instance_exec(&flag)
+    end
+
     def context
       Graphiti.context[:object]
     end

data/lib/graphiti/util/attribute_check.rb

@@ -50,14 +50,41 @@ module Graphiti
         end
       end
 
+      # Guards may optionally accept the model being written and the attribute
+      # name, mirroring readable guards.
       def guard_passes?
-        !!resource.send(attribute[flag])
+        result = case guard_arity
+        when 0 then call_guard
+        when 1 then call_guard(resource.guard_model)
+        else call_guard(resource.guard_model, name.to_s)
+        end
+        !!result
+      end
+
+      def call_guard(*args)
+        if guard.is_a?(Proc)
+          resource.instance_exec(*args, &guard)
+        else
+          resource.send(guard, *args)
+        end
+      end
+
+      def guard_arity
+        method = guard.is_a?(Proc) ? guard : resource.method(guard)
+        # Negative arity means optional or splatted params - hand over
+        # everything and let the guard take what it wants.
+        method.arity.negative? ? 2 : method.arity
+      end
+
+      def guard
+        attribute[flag]
       end
 
       def guarded?
-        request? &&
-          attribute[flag].is_a?(Symbol) &&
-          attribute[flag] != :required
+        return false unless request?
+        return false if guard == :required
+
+        guard.is_a?(Symbol) || guard.is_a?(String) || guard.is_a?(Proc)
       end
 
       def supported?

data/lib/graphiti/util/serializer_relationships.rb

@@ -19,8 +19,7 @@ module Graphiti
       private
 
       def apply?(sideload)
-        @serializer.relationship_blocks[sideload.name].nil? &&
-          sideload.readable?
+        @serializer.relationship_blocks[sideload.name].nil?
       end
     end
 
@@ -32,7 +31,8 @@ module Graphiti
       end
 
       def apply
-        @serializer.relationship(@sideload.name, &block)
+        sideload = @sideload
+        @serializer.relationship(@sideload.name, if: -> { sideload.readable? }, &block)
       end
 
       # If we can't eagerly validate links on app boot, we do it at runtime

data/lib/graphiti/version.rb

@@ -1,3 +1,3 @@
 module Graphiti
-  VERSION = "1.11.1"
+  VERSION = "1.12.0"
 end

data/lib/graphiti.rb

@@ -62,6 +62,18 @@ module Graphiti
     @resources ||= []
   end
 
+  # Every guarded relationship, e.g. ["EmployeeResource.positions"]
+  def self.guarded_relationships
+    ::Rails.application.eager_load! if defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+    resources.flat_map { |resource_class|
+      resource_class.config[:sideloads]
+        .select { |_name, sideload| sideload.guarded? }
+        .keys
+        .map { |relationship_name| "#{resource_class.name || "(anonymous resource)"}.#{relationship_name}" }
+    }.uniq.sort
+  end
+
   def self.broadcast(name, payload)
     # AS::N prefers domain naming format with more specific towards end
     name = "#{name}.graphiti"

data/package.json

@@ -37,43 +37,66 @@
         {
           "releaseRules": [
             {
-              "type": "*!",
+              "breakingMarker": "!",
               "release": "major"
             },
+            {
+              "breaking": true,
+              "release": "major"
+            },
+            {
+              "revert": true,
+              "release": "patch"
+            },
             {
               "type": "feat",
               "release": "minor"
             },
             {
-              "type": "build",
+              "type": "fix",
               "release": "patch"
             },
             {
-              "type": "ci",
+              "type": "perf",
               "release": "patch"
             },
+            {
+              "type": "build",
+              "release": false
+            },
+            {
+              "type": "ci",
+              "release": false
+            },
             {
               "type": "chore",
-              "release": "patch"
+              "release": false
             },
             {
               "type": "docs",
-              "release": "patch"
+              "release": false
             },
             {
               "type": "refactor",
-              "release": "patch"
+              "release": false
             },
             {
               "type": "style",
-              "release": "patch"
+              "release": false
             },
             {
               "type": "test",
-              "release": "patch"
+              "release": false
             }
           ],
           "parserOpts": {
+            "headerPattern": "^(\\w*)(?:\\((.*)\\))?(!)?: (.*)$",
+            "headerCorrespondence": [
+              "type",
+              "scope",
+              "breakingMarker",
+              "subject"
+            ],
             "noteKeywords": [
               "BREAKING CHANGE",
               "BREAKING CHANGES",
@@ -85,7 +108,20 @@
           }
         }
       ],
-      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "parserOpts": {
+            "headerPattern": "^(\\w*)(?:\\((.*)\\))?(!)?: (.*)$",
+            "headerCorrespondence": [
+              "type",
+              "scope",
+              "breakingMarker",
+              "subject"
+            ]
+          }
+        }
+      ],
       [
         "@semantic-release/changelog",
         {
@@ -99,7 +135,8 @@
         "@semantic-release/git",
         {
           "assets": [
-            "CHANGELOG.md"
+            "CHANGELOG.md",
+            "lib/graphiti/version.rb"
           ],
           "message": "${nextRelease.version} CHANGELOG [skip ci]\n\n${nextRelease.notes}"
         }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphiti
 version: !ruby/object:Gem::Version
-  version: 1.11.1
+  version: 1.12.0
 platform: ruby
 authors:
 - Lee Richmond
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jsonapi-serializable
@@ -242,6 +242,7 @@ files:
 - Appraisals
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -370,7 +371,14 @@ homepage: https://github.com/graphiti-api/graphiti
 licenses:
 - MIT
 metadata: {}
-post_install_message:
+post_install_message: "Graphiti: relationship readable:/writable: guards are now enforced.\n\nSymbols,
+  strings, and procs passed to a relationship's readable/writable\nguards were always
+  interpreted as true and never actually called before this\nconditional relationship
+  change. They are now evaluated per-request, where\nunreadable relationships are
+  omitted from responses and includes, and unwritable\nrelationships reject writes.\n\nTo
+  list every affected relationship in your app:\n\n  bin/rails runner 'puts Graphiti.guarded_relationships'\n\nAudit
+  these before deploying. Apps using schema.json will also see affected \nrelationships
+  flagged as \"became guarded\" by the schema check.\n"
 rdoc_options: []
 require_paths:
 - lib