graphql-armory 0.1.0.pre3 → 0.1.0.pre4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3eacfaa8caea3d5963df1d9a12f30efd9b9dc5232bae15b73475fef3f519ad85
-  data.tar.gz: 1176b251773ecf02e4a71cacabe1b4ef4c3f4345ca9d88efdf2ba103be4bf84a
+  metadata.gz: 5f463135c3578c6248c02f5610cb6bd1bc3f88fe9c26867e8cbd5164c84be408
+  data.tar.gz: 0344af8ea82c901fb5ad36cd1d236039f30afe3969142305b3e9b48d0890e5ab
 SHA512:
-  metadata.gz: 0d8e40044eef04927178f8a75bd0394b833686f6ee4e2a04c5734b1b84fa7644d66c683b8456d1b1d2dbc916c3c3714f15a060a6757f04af2632d8e40b7dd469
-  data.tar.gz: 548f98bc7e3b373f49172d29dfe89a20ea3cf9a1f70eeba4ee9161e38ce429e46c30c27cfdb4afd1d591d221d10f34d56eaa41f1cffca514b62d7821dd8ce88f
+  metadata.gz: 171b49d43c89c1c306949b7e30c56aa71687ccff9f3028f99e8b5f181f4a80b650d8a58e996090013bfa8e800632848109e557842f8ee78aecffbf0893d8d14a
+  data.tar.gz: 477b8904c178b41c690f2c308004f0d0a8f441d4df144e4ff2cb4e1a06babe6a33c401728edfcc7ebfd0a14c8ae336c8d7ce12bf4de0944b11e2171cdc02c0c8

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.1.0.pre4 (2026-10-29)
+
+Persisted queries / operation allowlist (roadmap module 3). Docs: `docs/persisted-queries.md`.
+
+- Persisted queries, part 1: `GraphQL::Armory::PersistedQueries::Manifest` loads Apollo's persisted query manifest or Relay's persisted output, checks every id is the digest of its query (sha256, md5 or sha1) and parses each query once; any problem raises at boot.
+- Persisted queries, part 2: `use GraphQL::Armory::PersistedQueries, store:, strict:` runs the stored operation a request names by id (`context[:operation_id]`; `PersistedQueries.operation_id(params)` reads it from `operationId`, `extensions.operationId` or `extensions.persistedQuery.sha256Hash`). Unknown ids and mismatched queries are refused; strict mode refuses raw queries unless the context holds `armory_allow_raw_query: true`. Docs: `docs/persisted-queries.md`.
+
 ## 0.1.0.pre3 (2026-10-29)
 
 Encrypted, versioned IDs and cursors (roadmap module 2), and a docs page per module.

data/README.md

@@ -6,12 +6,12 @@
 
 Open-source extensions for [graphql-ruby](https://github.com/rmosolgo/graphql-ruby), built on its public extension points: no fork, no monkey patching. One gem, one module at a time; each module has its own page in [`docs/`](docs) with the problem it solves, how to use it, and its limits.
 
-> **Status: early development.** Prereleases on RubyGems (`0.1.0.pre3`). The API may change before 1.0.
+> **Status: early development.** Prereleases on RubyGems (`0.1.0.pre4`). The API may change before 1.0.
 
 ## Install
 
 ```ruby
-gem "graphql-armory", "~> 0.1.0.pre3"  # a prerelease: `gem install graphql-armory --pre`
+gem "graphql-armory", "~> 0.1.0.pre4"  # a prerelease: `gem install graphql-armory --pre`
 gem "pundit"      # or "cancancan", for the authorization module
 ```
 
@@ -24,8 +24,8 @@ Status: ✅ released, 🚧 in progress, ⬜ not started. Update this table in th
 | Order | Module | Status | Docs | Current limits |
 |---|---|---|---|---|
 | 1 | Authorization (Pundit, CanCanCan) | ✅ | [docs/authorization.md](docs/authorization.md) | Released in 0.1.0.pre2 (prerelease). Pundit and CanCanCan (the audit checks less with CanCanCan). Global IDs in `loads:` decoded through `object_from_id`; `loads:` inside input objects scoped with `include Base`. `Execution::Next` needs graphql >= 2.6.2. |
-| 2 | Encrypted, versioned IDs and cursors | ✅ | [docs/encrypted-ids.md](docs/encrypted-ids.md) | Released in 0.1.0.pre3 (prerelease). `Encoder` (AES-256-GCM), versioned chains and `Legacy`, `Encoder.default` (ENV or Rails), `use GraphQL::Armory::IDs`. Composite primary keys not supported. |
-| 3 | Persisted queries / operation whitelisting | ⬜ | | Research not started. |
+| 2 | Encrypted, versioned IDs and cursors | ✅ | [docs/encrypted-ids.md](docs/encrypted-ids.md) | Released in 0.1.0.pre4 (prerelease). `Encoder` (AES-256-GCM), versioned chains and `Legacy`, `Encoder.default` (ENV or Rails), `use GraphQL::Armory::IDs`. Composite primary keys not supported. |
+| 3 | Persisted queries / operation allowlist | ✅ | [docs/persisted-queries.md](docs/persisted-queries.md) | Released in 0.1.0.pre4 (prerelease). Allowlist from a build manifest (Apollo, Relay), `use GraphQL::Armory::PersistedQueries` with strict mode. A runtime store (database, sync endpoint) is planned for later. |
 | 4 | Rate limiting | ⬜ | | Research not started. |
 | 5 | Stable (keyset) connections | ⬜ | | Research not started. |
 | 6 | Subscriptions over Pusher / Ably | ⬜ | | Research not started. |
@@ -53,7 +53,7 @@ GRAPHQL_VERSION="~> 2.4.0" docker compose run --rm test         # another graphq
 Releases are published from GitHub Actions with RubyGems Trusted Publishing (`.github/workflows/release.yml`): no API key is stored and no OTP is asked. Bump `GraphQL::Armory::VERSION` and the CHANGELOG on `main`, then push the matching tag:
 
 ```
-git tag v0.1.0.pre3 && git push origin v0.1.0.pre3
+git tag v0.1.0.pre4 && git push origin v0.1.0.pre4
 ```
 
 The workflow checks that the tag matches the version, runs the specs and pushes the gem. It only publishes a tag on a commit of `main`. The `release` environment can require a maintainer's approval first (on a public repository, or a private one on a paid GitHub plan).

data/docs/persisted-queries.md

@@ -0,0 +1,184 @@
+# Persisted queries
+
+Your API runs the operations your clients were built with, and nothing else.
+
+## The problem
+
+A GraphQL endpoint accepts any query anyone writes. Authorization decides what each user may read, but the endpoint still:
+
+- **Runs queries you never wrote.** Anyone with a token can send deep, wide or expensive queries, or explore the schema field by field to find something you forgot to protect.
+- **Parses and validates every request.** A large query costs CPU before a single field resolves.
+- **Sends the full query text on every request.** Mobile clients pay that in bandwidth.
+
+## The solution
+
+Your client's build step (Apollo's persisted query manifest generator, or the Relay compiler's `persistConfig`) writes every operation the app uses to a JSON file. The server loads that file and clients send the operation's id instead of its text:
+
+- **An allowlist.** In strict mode the server refuses any query that is not in the file, before validating it, so a raw query cannot even probe field names.
+- **Tamper-evident.** Every id must be the digest (SHA-256 by default) of its query. A manifest edited by hand to put another query behind an id is refused when the app boots.
+- **Parsed once.** Each stored query is parsed at boot and handed to graphql-ruby as a document, so a request skips parsing.
+- **Smaller requests.** The client sends a 64-character id and the variables.
+- **Both engines.** It hooks only `Schema.query_class`, so it works on the interpreter and on `Execution::Next`.
+
+## Who does what
+
+Two separate pieces work together. Your client tooling writes the list; this gem enforces it on the server.
+
+| Piece | Who provides it | What it does |
+|---|---|---|
+| `persisted-queries.json` | Apollo or Relay, in your client's build | Lists every operation the app uses. You do not write or edit it by hand. |
+| `PersistedQueries::Manifest` | this gem | Loads the file at boot and checks that nobody edited it. |
+| `use GraphQL::Armory::PersistedQueries` | this gem | Runs the operation a request names by id, and in strict mode refuses everything else. |
+
+Think of an event: the client tooling prints the guest list, and this gem is the guard at the door. A list without a guard stops nobody. Apollo's own router (GraphOS Router, Enterprise plan) can enforce the list; Apollo Server's built-in `persistedQueries` option is only a cache (automatic persisted queries) and still runs any query. Open-source graphql-ruby has no equivalent (GraphQL-Pro has its OperationStore), so without this gem a Ruby API ignores the file and keeps running any query it receives.
+
+Your part is to copy the file the client build produced into the server (for example as `persisted-queries.json` in the Rails root) and deploy it.
+
+### What the file looks like
+
+Apollo's manifest, written by `generate-persisted-query-manifest` (`@apollo/generate-persisted-query-manifest`, see [Apollo's guide](https://www.apollographql.com/docs/react/data/persisted-queries)):
+
+```json
+{
+  "format": "apollo-persisted-query-manifest",
+  "version": 1,
+  "operations": [
+    {
+      "id": "6c5d8a12c92cffe7786b5a6d288f56d479973fd0f35b31bce215a4df9cf554ef",
+      "name": "Invoices",
+      "type": "query",
+      "body": "query Invoices { invoices { number total } }"
+    }
+  ]
+}
+```
+
+Relay's persisted output, written by `relay-compiler` with `persistConfig` (see [Relay's guide](https://relay.dev/docs/guides/persisted-queries/)), is a flat map of id to query:
+
+```json
+{
+  "904cd33a4439518767fd75402dd7e47b": "query Invoices { invoices { number total } }"
+}
+```
+
+Each id is the digest of its exact query text: SHA-256 in Apollo's manifest, MD5 in this Relay example (load it with `digest: :md5`). Change a query without regenerating its id and the app refuses to boot, naming that id.
+
+A client then sends only the id and the variables:
+
+```json
+{ "operationId": "6c5d8a12c92cffe7786b5a6d288f56d479973fd0f35b31bce215a4df9cf554ef", "variables": {} }
+```
+
+## How to use it
+
+Load the manifest and add the plugin:
+
+```ruby
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::PersistedQueries,
+    store: GraphQL::Armory::PersistedQueries::Manifest.load(Rails.root.join("persisted-queries.json")),
+    strict: true
+end
+```
+
+Pass the operation id from the request in the context:
+
+```ruby
+class GraphqlController < ApplicationController
+  def execute
+    result = AppSchema.execute(
+      params[:query],
+      variables: params[:variables],
+      operation_name: params[:operationName],
+      context: {
+        current_user: current_user,
+        operation_id: GraphQL::Armory::PersistedQueries.operation_id(params),
+        armory_allow_raw_query: current_user&.staff? || Rails.env.development?
+      }
+    )
+    render json: result
+  end
+end
+```
+
+`PersistedQueries.operation_id(params)` reads the id where clients send it: `operationId`, `extensions.operationId`, or Apollo's `extensions.persistedQuery.sha256Hash` (`extensions` may be a JSON string, as in GET requests). The first one present wins, in that order. It answers nil when there is no id, or when it is not a non-empty String. Params must have String keys, as Rack and Rails params do. An empty `query` sent with an id (a GET request with `query=`) counts as no query.
+
+What each request does:
+
+| Request | Result |
+|---|---|
+| An id the manifest holds | Runs the stored operation with the request's variables and operation name. |
+| An id plus the same query (Apollo's clients may send both) | Runs the stored operation. |
+| An id plus a different query | Refused: `The operation id and the query do not match`. Neither runs. |
+| An id the manifest does not hold | Refused: `Unknown operation id`. |
+| A raw query, strict mode off | Runs as usual. Use this while clients migrate. |
+| A raw query, strict mode on | Refused: `Only persisted operations are allowed: send an operation id`, unless the context holds `armory_allow_raw_query: true`. |
+
+A refused request fails validation with that message as its only error, so nothing resolves, even when the app executes with `validate: false`.
+
+### Relay
+
+Relay's persisted output is a flat map of id to query text. Tell the manifest which digest Relay was configured with:
+
+```ruby
+GraphQL::Armory::PersistedQueries::Manifest.load("persisted-queries.json", digest: :md5)
+```
+
+`digest: false` accepts ids that are not digests (names such as `invoices-v1`). Then nothing proves an id belongs to its query: anyone who can edit the file can change what an id runs.
+
+Relay's example network layer sends the id as `doc_id`. Pass it yourself: `operation_id: params[:doc_id]`.
+
+### Rolling it out
+
+1. Generate the manifest in the client build and ship it with the server.
+2. Add the plugin with `strict: false`. Clients that send ids get stored operations; everything else keeps working.
+3. When every client in use sends ids, turn on `strict: true`.
+
+Deploy the server with the new manifest before, or with, the clients that use its new operations: until then they get `Unknown operation id`. Keep old operations in the file while old app versions are still in use.
+
+## Reference
+
+`Manifest.new(data, digest: :sha256)`, `Manifest.load(path, digest: :sha256)`
+
+- Reads Apollo's persisted query manifest (`format: "apollo-persisted-query-manifest"`, `version: 1`) or Relay's flat map.
+- `digest:` is `:sha256`, `:sha1`, `:md5` or `false`.
+- `fetch(id)` answers the operation (`id`, `name`, `body`, `document`, all frozen) or nil. `size` counts them.
+- Raises `PersistedQueries::ConfigurationError` at boot for: invalid JSON, an unreadable file, an unknown format or version, an id that is not the digest of its query, a query that does not parse, a duplicate id, an entry that is not an object, or an empty manifest. Messages never quote the file's queries.
+
+`use GraphQL::Armory::PersistedQueries, store:, strict: false`
+
+- `store:` answers `fetch(id)` with an object that has `body` and `document`, or nil. A Manifest, or your own store.
+- `strict:` is `true` or `false`.
+- Works with your own `query_class`, whether it is set before `use`, after it, or in a child schema: the plugin subclasses it.
+- `use` it once per schema hierarchy. A second `use`, on the same schema or a child, raises instead of replacing the first one's settings.
+- A store whose `fetch` raises or answers something without `document` makes the request raise: it fails closed, as an exception.
+
+Context keys: `operation_id` (a String; anything else is an unknown id), `armory_allow_raw_query` (only `true` allows).
+
+## Guarantees and limits
+
+- A request with an id runs only the stored document for that id, or nothing.
+- In strict mode a raw query runs only when the app's context says `armory_allow_raw_query: true`. The plugin does not decide who is staff: your controller does.
+- Queries built by your own code as `GraphQL::Query` objects (for example in `multiplex`) bypass the plugin's lookup. In strict mode they are not refused either: the check happens when the plugin's query class builds the query.
+- In strict mode, schema introspection run through the plugin is refused too. `Schema.to_json` and `rake graphql:schema:json` need `context: { armory_allow_raw_query: true }` (the rake task's `load_context`). `Schema.to_definition` and `Schema.validate` are not affected.
+- The manifest lives in the server's code: adding an operation needs a deploy. See the runtime store below.
+- Subscriptions: graphql-ruby re-runs a subscription with its printed query, which the plugin accepts when it matches the stored document. Subscriptions are not tested with persisted queries yet.
+
+## Planned: a runtime store
+
+The manifest is the simplest store: one file, no database, deployed with the code. Teams that ship clients independently of the server (mobile apps, several frontends) need operations published without a server deploy. That is planned for later, behind the same `store:` interface:
+
+- **A database table** (ActiveRecord) holding operations per client, with the digest checked on write.
+- **A sync endpoint** the client build calls to publish its operations, authenticated per client with an HMAC of the request body and a secret per client.
+- **Several clients**, each with its own operations and secret, so one client cannot publish under another's name.
+- **Archiving** operations that old app versions no longer use, without deleting their history.
+- **Publishing without redeploying**: the server reads new operations as soon as they are synced.
+
+Until then, any object that answers `fetch(id)` with an operation can be passed as `store:`.
+
+## References
+
+- Apollo Client: [Persisted queries](https://www.apollographql.com/docs/react/data/persisted-queries) — generating the manifest with `@apollo/generate-persisted-query-manifest` and sending ids.
+- Apollo iOS: [Persisted queries](https://www.apollographql.com/docs/ios/fetching/apqs).
+- Relay: [Persisted queries](https://relay.dev/docs/guides/persisted-queries/) — `persistConfig`, local persisting to a file, `doc_id` in the network layer.
+- Relay: [Compiler config](https://relay.dev/docs/getting-started/compiler-config/).

data/lib/graphql/armory/persisted_queries/manifest.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # The operations a client build produced, loaded from Apollo's persisted query manifest or Relay's
+      # persisted output. Every id must be the digest of its query, so an edited manifest cannot put another
+      # query behind an id; every query is parsed once, here. Any problem raises at boot, and no message
+      # quotes the manifest's values: they may hold query text.
+      class Manifest
+        DIGESTS = { sha256: Digest::SHA256, sha1: Digest::SHA1, md5: Digest::MD5 }.freeze
+        APOLLO_FORMAT = "apollo-persisted-query-manifest"
+        ID_LIKE = /\A[A-Za-z0-9_.:-]{1,128}\z/
+
+        Operation = Struct.new(:id, :name, :body, :document, keyword_init: true)
+
+        def self.load(path, digest: :sha256)
+          data = begin
+            JSON.parse(File.read(path, mode: "r:bom|utf-8"))
+          rescue JSON::ParserError
+            # Not the parser's message: it quotes the file's content.
+            raise ConfigurationError, "#{path} is not valid JSON"
+          rescue SystemCallError => error
+            raise ConfigurationError, "#{path} cannot be read (#{error.class})"
+          end
+          new(data, digest: digest)
+        end
+
+        # `digest:` is how ids were made: :sha256 (Apollo), :md5 or :sha1 (Relay's options), or false for ids
+        # that are not digests (then nothing proves an id belongs to its query).
+        def initialize(data, digest: :sha256)
+          unless digest == false || DIGESTS.key?(digest)
+            raise ConfigurationError, "unknown digest #{digest.inspect}: use #{DIGESTS.keys.map(&:inspect).join(", ")} or false"
+          end
+
+          @digest = digest && DIGESTS.fetch(digest)
+          @operations = entries(data).each_with_index.with_object({}) do |((id, name, body), index), operations|
+            operation = operation(index, id, name, body)
+            raise ConfigurationError, "operation #{label(index, id)} appears twice in the manifest" if operations.key?(id)
+
+            operations[id] = operation
+          end.freeze
+          raise ConfigurationError, "the manifest holds no operations: is it the right file?" if @operations.empty?
+        end
+
+        def fetch(id)
+          @operations[id]
+        end
+
+        def size
+          @operations.size
+        end
+
+        private
+
+        # [id, name, body] triples from either format. A Relay map may have an operation keyed "format", so a
+        # Hash is Apollo's when its format says so, or when it has both "format" and "operations".
+        def entries(data)
+          raise ConfigurationError, unknown_format unless data.is_a?(Hash)
+          return apollo_entries(data) if data["format"] == APOLLO_FORMAT || (data.key?("format") && data.key?("operations"))
+
+          data.map { |id, body| [id, nil, body] }
+        end
+
+        def apollo_entries(data)
+          raise ConfigurationError, "unknown manifest format: expected #{APOLLO_FORMAT}" unless data["format"] == APOLLO_FORMAT
+          raise ConfigurationError, "unsupported manifest version: expected 1" unless data["version"].eql?(1)
+          raise ConfigurationError, "the manifest's operations must be an array" unless data["operations"].is_a?(Array)
+
+          data["operations"].each_with_index.map do |entry, index|
+            raise ConfigurationError, "manifest entry #{index} is not an object" unless entry.is_a?(Hash)
+
+            entry.values_at("id", "name", "body")
+          end
+        end
+
+        def operation(index, id, name, body)
+          unless id.is_a?(String) && body.is_a?(String) && (name.nil? || name.is_a?(String))
+            raise ConfigurationError, "manifest entry #{index} needs a String id, a String body and a String name or none"
+          end
+          if @digest && @digest.hexdigest(body) != id
+            raise ConfigurationError, "operation #{label(index, id)} is not the digest of its query: the manifest was edited, or `digest:` is wrong"
+          end
+
+          # Copies, so neither the caller's data nor a fetched operation can change what a later fetch returns.
+          Operation.new(id: id.dup.freeze, name: name&.dup&.freeze, body: body.dup.freeze, document: parse(label(index, id), body)).freeze
+        end
+
+        def parse(label, body)
+          GraphQL.parse(body)
+        rescue GraphQL::ParseError
+          raise ConfigurationError, "operation #{label} does not parse"
+        end
+
+        # The id names the operation in errors only when it looks like an id; otherwise it may be query text.
+        def label(index, id)
+          id.match?(ID_LIKE) ? id : "at entry #{index}"
+        end
+
+        def unknown_format
+          "unknown manifest format: expected Apollo's persisted query manifest or Relay's persisted output"
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/persisted_queries.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQL
+  module Armory
+    # Persisted queries: clients send the id of an operation their build produced, and the server runs the
+    # stored query. With strict mode on, it refuses queries it does not hold.
+    #
+    #   class AppSchema < GraphQL::Schema
+    #     use GraphQL::Armory::PersistedQueries, store: Manifest.load("persisted-queries.json"), strict: true
+    #   end
+    #
+    #   AppSchema.execute(params[:query], context: { operation_id: PersistedQueries.operation_id(params) })
+    #
+    # Hooks only `Schema.query_class`: the stored document goes to the query as `document:`, so it is parsed once,
+    # at boot, and runs the same on both engines.
+    module PersistedQueries
+      class ConfigurationError < Armory::Error; end
+
+      UNKNOWN_OPERATION = "Unknown operation id"
+      MISMATCH = "The operation id and the query do not match"
+      RAW_QUERY_REFUSED = "Only persisted operations are allowed: send an operation id"
+
+      # What a refused request holds: nothing to run.
+      EMPTY_DOCUMENT = GraphQL::Language::Nodes::Document.new(definitions: [])
+
+      # Validates nothing and answers the refusal, through the query's public `static_validator:` option.
+      class Refusal < GraphQL::StaticValidation::Validator
+        def initialize(schema, message)
+          super(schema: schema)
+          @message = message
+        end
+
+        def validate(_query, **)
+          { errors: [GraphQL::StaticValidation::Error.new(@message)], remaining_timeout: nil }
+        end
+      end
+
+      # `store:` answers `fetch(id)` with an operation (`body` and `document`) or nil: a Manifest, or your own.
+      # `strict: true` refuses raw queries unless the context holds `armory_allow_raw_query: true`.
+      def self.use(schema, store:, strict: false)
+        if store.is_a?(Hash) || !store.respond_to?(:fetch)
+          raise ConfigurationError, "store: must answer fetch(id) with an operation or nil, like a Manifest"
+        end
+        raise ConfigurationError, "strict: must be true or false, got #{strict.inspect}" unless strict == true || strict == false
+
+        if schema.singleton_class.include?(Guard)
+          raise ConfigurationError, "#{schema} already uses PersistedQueries (here or in a parent schema): use it once"
+        end
+
+        schema.instance_variable_set(:@armory_persisted_queries, [store, strict].freeze)
+        schema.singleton_class.prepend(Guard)
+        schema.query_class(schema.query_class)
+      end
+
+      # Keeps the lookup in every query class the schema uses, including one set after `use` or by a child schema.
+      module Guard
+        UNSET = Object.new.freeze
+
+        def query_class(new_query_class = UNSET)
+          return super() if UNSET.equal?(new_query_class)
+          return super(new_query_class) if new_query_class.include?(Lookup)
+
+          super(Class.new(new_query_class) { include Lookup })
+        end
+
+        def armory_persisted_queries
+          @armory_persisted_queries || superclass.armory_persisted_queries
+        end
+      end
+
+      # The operation id a request sent, from Rack or Rails params: `operationId`, `extensions.operationId` or
+      # Apollo's `extensions.persistedQuery.sha256Hash` (`extensions` may arrive as a JSON string on GET).
+      # Answers nil when there is none, or when it is not a non-empty String.
+      def self.operation_id(params)
+        params = plain(params)
+        extensions = params["extensions"]
+        extensions = parse_json(extensions) if extensions.is_a?(String)
+        extensions = plain(extensions)
+        persisted_query = plain(extensions["persistedQuery"])
+
+        [params["operationId"], extensions["operationId"], persisted_query["sha256Hash"]].find do |candidate|
+          candidate.is_a?(String) && !candidate.empty?
+        end
+      end
+
+      def self.plain(value)
+        value = value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+        value.is_a?(Hash) ? value : {}
+      end
+      private_class_method :plain
+
+      def self.parse_json(text)
+        JSON.parse(text)
+      rescue JSON::ParserError
+        nil
+      end
+      private_class_method :parse_json
+
+      # Swaps the request's query for the stored document, or for nothing with an error when it is refused.
+      module Lookup
+        def initialize(schema, query_string = nil, **options)
+          store, strict = schema.armory_persisted_queries
+          context = options[:context]
+          operation_id = context[:operation_id] if context.respond_to?(:[])
+          text = query_string || options[:query]
+          text = nil if text == ""
+
+          refusal, document =
+            if !operation_id.nil?
+              operation = operation_id.is_a?(String) ? store.fetch(operation_id) : nil
+              if operation.nil?
+                UNKNOWN_OPERATION
+              elsif options[:document] || (text && !same_query?(text, operation))
+                MISMATCH
+              else
+                [nil, operation.document]
+              end
+            elsif strict && !(context.respond_to?(:[]) && context[:armory_allow_raw_query] == true)
+              RAW_QUERY_REFUSED
+            end
+
+          return super if refusal.nil? && document.nil?
+          return super(schema, nil, **options, query: nil, document: document) if refusal.nil?
+
+          # A refused request fails validation with the refusal as its only error, so neither engine runs it. Its
+          # text is never parsed; a document the app built itself is kept, for `Schema.validate`, which validates it
+          # with its own validator.
+          super(schema, nil, **options, query: nil, document: options[:document] || EMPTY_DOCUMENT, validate: true, static_validator: Refusal.new(schema, refusal))
+        end
+
+        private
+
+        # Apollo's clients may send the query with its id; graphql-ruby's subscriptions resend it printed.
+        def same_query?(text, operation)
+          text == operation.body || text == operation.document.to_query_string
+        end
+      end
+    end
+  end
+end
+
+require "graphql/armory/persisted_queries/manifest"

data/lib/graphql/armory/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Armory
-    VERSION = "0.1.0.pre3"
+    VERSION = "0.1.0.pre4"
   end
 end

data/lib/graphql/armory.rb

@@ -13,3 +13,4 @@ end
 require "graphql/armory/encoder"
 require "graphql/armory/authorization"
 require "graphql/armory/ids"
+require "graphql/armory/persisted_queries"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql-armory
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre3
+  version: 0.1.0.pre4
 platform: ruby
 authors:
 - Israel
@@ -43,6 +43,7 @@ files:
 - README.md
 - docs/authorization.md
 - docs/encrypted-ids.md
+- docs/persisted-queries.md
 - lib/graphql-armory.rb
 - lib/graphql/armory.rb
 - lib/graphql/armory/authorization.rb
@@ -79,6 +80,8 @@ files:
 - lib/graphql/armory/encoder/legacy.rb
 - lib/graphql/armory/encoder/versioned.rb
 - lib/graphql/armory/ids.rb
+- lib/graphql/armory/persisted_queries.rb
+- lib/graphql/armory/persisted_queries/manifest.rb
 - lib/graphql/armory/version.rb
 - lib/tasks/graphql_armory.rake
 homepage: https://github.com/israelb/graphql-armory