graphql-armory 0.1.0.pre3 → 0.1.0.pre5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3eacfaa8caea3d5963df1d9a12f30efd9b9dc5232bae15b73475fef3f519ad85
-  data.tar.gz: 1176b251773ecf02e4a71cacabe1b4ef4c3f4345ca9d88efdf2ba103be4bf84a
+  metadata.gz: 431eab2604e80c473f2037cf636158113056cbd60e9fb408c8f6f91696586b55
+  data.tar.gz: aaa7d67cd478e2a0b8faf0b069eeb3e7a8051e2304caa55c8e522ddcc1a121bc
 SHA512:
-  metadata.gz: 0d8e40044eef04927178f8a75bd0394b833686f6ee4e2a04c5734b1b84fa7644d66c683b8456d1b1d2dbc916c3c3714f15a060a6757f04af2632d8e40b7dd469
-  data.tar.gz: 548f98bc7e3b373f49172d29dfe89a20ea3cf9a1f70eeba4ee9161e38ce429e46c30c27cfdb4afd1d591d221d10f34d56eaa41f1cffca514b62d7821dd8ce88f
+  metadata.gz: 308f9883d87cd8f5ec8ebc711477779d95a3a149c3fb4e770f9866fc10f6f476c99a788c8493fa03317f3963f71f0aab8da786904ecb78c3ac269f82345ae565
+  data.tar.gz: 31179d1a3c3a4b7d5a71027d2b1ce18f983843b10c87e6418c9763a89a33ec33dd7669fdc1bc3dddc2abe0876f37716495c50b4fb05393c58f8b9a38c79015e3

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.1.0.pre5 (2026-10-29)
+
+Rate limiting (roadmap module 4). Docs: `docs/rate-limiting.md`. All four modules now follow the Useful Objects doctrine.
+
+- Rate limiting, part 1: `use GraphQL::Armory::RateLimits::Points, store:, limit:, window:` charges each query its complexity against a bucket of points per client (`context[:rate_limit_key]`) that refills over the window. Over-limit queries are refused before running, with their cost, what remains and when to retry; soft mode (the default) only records. `RateLimits::MemoryStore` for tests and single processes. Docs: `docs/rate-limiting.md`.
+- Rate limiting, part 2: `use GraphQL::Armory::RateLimits::Concurrency, store:, limit:, stale_after: 60` lets each client run at most `limit` operations at the same time. A query analyzer takes a slot before the operation runs (or refuses it, `RATE_LIMITED`); a trace releases every slot when the multiplex ends, even when it raises. Slots expire after `stale_after` seconds. `MemoryStore` gains `acquire` and `release`.
+- Rate limiting, part 3: clients can see their budget on every response. `Points` takes `extensions: true` to add `rateLimit` (`cost`, `limit`, `remaining`, `resetIn`) to the response extensions, and `Points.headers(result)` answers `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`.
+- Rate limiting, part 4: `RateLimits::RedisStore.new(redis:)` keeps buckets and slots in Redis, shared by every process. Each change is one Lua script and the time comes from Redis, so concurrent requests never race and servers agree on the clock. Keys expire on their own. The app adds the redis gem.
+- Rate limiting follows the Useful Objects doctrine like authorization: `Points.new` and `Concurrency.new` are inert and refuse every query (`Store::Null`), `build` checks the settings and wires the store, `call` is the actuator. `RateLimits::Store::Substitute` (a MemoryStore on a test clock that records calls and fails when told) and `RateLimits::Controls` are there for your specs.
+- Encrypted IDs and persisted queries follow the same doctrine: `IDs::Lookup.new` is inert (`Encoder::Null`) and `build` wires `Encoder.default`; `PersistedQueries::Gate` holds the decision, with an inert `new` (`Store::Null`, strict) and `build`. `Encoder::Substitute`, `PersistedQueries::Store::Substitute` and `Controls` for both are there for your specs. `IDs` now refuses at boot a `find:` that is not callable and an encoder without `encode` and `decode`.
+
+## 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.pre5`). 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.pre5"  # a prerelease: `gem install graphql-armory --pre`
 gem "pundit"      # or "cancancan", for the authorization module
 ```
 
@@ -24,9 +24,9 @@ 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. |
-| 4 | Rate limiting | ⬜ | | 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 | ✅ | [docs/rate-limiting.md](docs/rate-limiting.md) | Released in 0.1.0.pre5 (prerelease). Points per client (query complexity) and operations at the same time, `MemoryStore` and `RedisStore`, the budget in response extensions and headers. A processing-time layer is planned for later. |
 | 5 | Stable (keyset) connections | ⬜ | | Research not started. |
 | 6 | Subscriptions over Pusher / Ably | ⬜ | | Research not started. |
 | 7 | Response caching | ⬜ | | 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.pre5 && git push origin v0.1.0.pre5
 ```
 
 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/encrypted-ids.md

@@ -103,6 +103,10 @@ return nil if encoder.nil?                                  # nothing in the cha
 log_legacy_id(id) if encoder == GraphQL::Armory::Encoder::Legacy
 ```
 
+### Testing with IDs
+
+`Encoder::Substitute` encodes reversibly without a key and records what it encoded and decoded, for specs of code that uses an encoder; never hand out real IDs with it. `IDs::Controls::Encoder.example` is an Encoder subclass with a fixed test key, and `IDs::Controls::Record.example(id:)` a record to build IDs from. `IDs::Lookup.new`, with nothing wired, hands out no ID and honours none (`Encoder::Null`); `IDs::Lookup.build(encoder:, find:)` takes the same settings as `use`.
+
 ## Reference
 
 | Declaration | Meaning |

data/docs/persisted-queries.md

@@ -0,0 +1,188 @@
+# 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.
+
+### Testing with persisted queries
+
+`PersistedQueries::Store::Substitute.new(*queries)` holds the given queries under their SHA-256, like an Apollo manifest, and records the ids it was asked for (`fetched`). `PersistedQueries::Controls::Operations`, `Query.example` and `Root.example` are a small schema and its operations to test against. The decision itself is `PersistedQueries::Gate`: `Gate.build(store:, strict:)` takes the same settings as `use`, and `gate.(context, query_text, document)` answers `[refusal, document]`. `Gate.new`, with nothing wired, refuses every request (`Store::Null`, strict).
+
+## 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/docs/rate-limiting.md

@@ -0,0 +1,293 @@
+# Rate limiting
+
+Each client gets a budget of work per minute, measured in what its queries cost, not in how many requests it sends.
+
+## The problem
+
+A REST API can limit requests per minute because requests cost roughly the same. GraphQL requests do not:
+
+```graphql
+{ me { name } }                                                   # almost free
+{ invoices(first: 1000) { lines { product { reviews { author { name } } } } } }  # seconds of work
+```
+
+A limit of 100 requests per minute lets a client send 100 of the second kind, by mistake or on purpose, and keep your servers busy while everyone else waits. Counting requests does not stop it.
+
+## The solution
+
+`GraphQL::Armory::RateLimits::Points` charges every query its **complexity**: the score graphql-ruby already computes from the fields a query asks for, before running it. Each client has a bucket of points that refills over a window:
+
+- **Refused before running.** A query that costs more than the client has left is refused before any field resolves, so it costs your servers nothing. It is not charged either.
+- **Predictable for clients.** The refusal says what the query cost, what remains and when to retry, so a client can adapt.
+- **Per client.** Each client key (a user, an API token, an IP) has its own bucket; you can give each key its own limit.
+- **Safe to roll out.** Soft mode, the default, charges and records but refuses nothing, so you can watch real traffic before turning it on.
+
+`GraphQL::Armory::RateLimits::Concurrency` adds a second rule: at most N operations running at the same time per client ([Operations at the same time](#operations-at-the-same-time)). Both keep their state in a store: `MemoryStore` for tests and one process, `RedisStore` for production ([Sharing limits between processes](#sharing-limits-between-processes)). Planned: a layer that measures processing time (see [Planned](#planned)).
+
+## How to use it
+
+```ruby
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::RateLimits::Points,
+    store: GraphQL::Armory::RateLimits::MemoryStore.new,
+    limit: 1_000,   # points
+    window: 60,     # seconds: the bucket refills 1,000 points every minute
+    soft: false     # refuse; leave it out (soft mode) while you measure
+end
+```
+
+Name the client in the context:
+
+```ruby
+context = {
+  current_user: current_user,
+  rate_limit_key: current_user ? "user:#{current_user.id}" : "ip:#{request.remote_ip}"
+}
+AppSchema.execute(params[:query], variables: params[:variables], context: context)
+```
+
+A query without a key raises `RateLimits::ConfigurationError`, so a forgotten controller is caught at once instead of running unlimited. To build the key another way, pass `key: ->(query) { ... }`.
+
+### What a query costs
+
+graphql-ruby scores a query before running it:
+
+- Every field costs **1 point**, unless you give it another score.
+- Inside a connection, the fields selected under each node cost **page size × their points** (`first:` or `last:`, variables included).
+- Fractional complexities are charged in whole points, rounded up.
+
+A worked example:
+
+```graphql
+query {
+  viewer {                            # 1
+    invoices(first: 50) {             # 1
+      nodes {                         # 1
+        number                        # 50 invoices × 1
+        lines(first: 20) {            # 50 × 1
+          nodes {                     # 50 × 1
+            product                   # 50 × 20 lines × 1
+            comments(first: 10) {     # 50 × 20 × 1
+              nodes {                 # 50 × 20 × 1
+                body                  # 50 × 20 × 10 comments × 1
+              }
+            }
+          }
+        }
+      }
+    }
+    followers(first: 10) {            # 1
+      nodes {                         # 1
+        name                          # 10 followers × 1
+      }
+    }
+  }
+}
+```
+
+Calculation:
+
+```
+3                                   = viewer, invoices, nodes
++ 50 × 3                 =    150   = number, lines, nodes, for each invoice
++ 50 × 20 × 3            =  3,000   = product, comments, nodes, for each line
++ 50 × 20 × 10 × 1       = 10,000   = body, for each comment
++ 2 + 10 × 1             =     12   = followers, nodes, and name for each follower
+                         = 13,165 points
+```
+
+With `limit: 1_000` this query can never run; asking for `invoices(first: 5)` instead costs about a tenth. The numbers were measured with graphql-ruby's own analysis, so they are exactly what the limiter charges.
+
+Give expensive fields a higher score where you define them, so their cost reflects real work:
+
+```ruby
+field :report, ReportType, null: false, complexity: 40      # 40 points instead of 1
+field :create_invoice, mutation: Mutations::CreateInvoice, complexity: 10  # 10 points plus its selections
+```
+
+Three settings make the scores fair. Large public APIs (GitHub, Shopify, see [References](#references)) do the same:
+
+- **Paginate every list.** A plain list field (`[Invoice]`) costs its fields **once**, however many items it returns, so 10,000 invoices cost like one. Use connections for anything that can grow. A connection asked for without `first:` or `last:` is sized by the schema's `default_page_size`, or else by `default_max_page_size`. If neither is set, graphql-ruby raises `GraphQL::Error` while scoring the query (a server error, not a refusal), so set one of them. GitHub goes further and requires `first:` or `last:` on every connection.
+- **Cap a single query.** graphql-ruby's `max_complexity 1_000` refuses any query above that score, whatever the client's budget. Shopify caps single queries at 1,000 points.
+- **Make writes cost more.** Give mutations a higher `complexity:`: `complexity: 10` charges 10 points for the mutation field itself, plus the fields it selects. Shopify charges 10 points per mutation by default.
+
+See graphql-ruby's [complexity and depth guide](https://graphql-ruby.org/queries/complexity_and_depth) for computed costs.
+
+### When a client runs out
+
+The response holds only the refusal:
+
+```json
+{
+  "errors": [{
+    "message": "Rate limit exceeded: this query costs 40 points and 20 remain (1000 every 60 seconds). Retry in 2 seconds.",
+    "extensions": { "code": "RATE_LIMITED", "cost": 40, "remaining": 20, "retryAfter": 2 }
+  }]
+}
+```
+
+A query that costs more than the whole limit can never run, and says so: `this query costs 1200 points and the limit is 1000 every 60 seconds, so it can never run.` Its extensions hold `cost` and `limit`.
+
+### Showing clients their budget
+
+A client that only learns its budget when it is refused cannot pace itself. GitHub sends the budget in headers on every response; Shopify puts it in the response's `extensions`. You can do either, or both.
+
+In the response, with `extensions: true`:
+
+```ruby
+use GraphQL::Armory::RateLimits::Points, store: store, limit: 1_000, window: 60, soft: false, extensions: true
+```
+
+```json
+{
+  "data": { "report": { "total": 120 } },
+  "extensions": { "rateLimit": { "cost": 40, "limit": 1000, "remaining": 960, "resetIn": 3 } }
+}
+```
+
+`resetIn` is the number of seconds until the bucket is full again. It is on refused responses too, and absent for a client with no limit. It is off by default, so responses do not change until you turn it on.
+
+In HTTP headers, from your controller:
+
+```ruby
+result = AppSchema.execute(params[:query], variables: params[:variables], context: context)
+response.headers.merge!(GraphQL::Armory::RateLimits::Points.headers(result))
+render json: result
+```
+
+That sets `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds until the bucket is full), or nothing when the query had no limit. It works whether or not `extensions:` is on, and reads each query's own budget, also in a multiplex. The `rateLimit` key of the response extensions belongs to the limiter: do not write it yourself.
+
+### Different limits per client
+
+```ruby
+use GraphQL::Armory::RateLimits::Points, store: store, window: 60,
+  limit: ->(key, query) { key.start_with?("partner:") ? 10_000 : 1_000 }
+```
+
+The callable answers a positive Integer, or nil for no limit (for example an internal service). Anything else raises.
+
+### Operations at the same time
+
+Points limit how much work a client asks for per minute. They do not stop a client that sends 30 cheap requests at once and occupies every server process while they run: GitHub, for one, also caps concurrent requests. Add `Concurrency` next to `Points`:
+
+```ruby
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::RateLimits::Concurrency,
+    store: store,      # the same store as Points
+    limit: 5,          # operations running at once per client
+    soft: false
+end
+```
+
+It uses the same `rate_limit_key`. Before an operation runs it takes one of the client's slots; when the operation ends, it gives the slot back, even if the operation raised or another analyzer refused it. A client whose slots are all taken is refused before any field resolves:
+
+```json
+{
+  "errors": [{
+    "message": "Too many operations at the same time: 5 are already running for this client (limit 5). Retry when one finishes.",
+    "extensions": { "code": "RATE_LIMITED", "limit": 5, "active": 5 }
+  }]
+}
+```
+
+A process that crashes never gives its slots back, so each slot expires after `stale_after:` seconds (60 by default). Set it above your longest request timeout. Soft mode, per-key limits (`limit: ->(key, query) { ... }`) and `on_store_error:` work as for `Points`; what happened is in `result.context[:rate_limit_concurrency]` (`{ key:, limit:, active:, soft:, limited: }`).
+
+### Rolling it out
+
+1. Install it in soft mode (leave out `soft:`). Queries run as before; each one records what it cost.
+2. Send what it recorded to your metrics: `result.context[:rate_limit_points]` is `{ key:, cost:, limit:, remaining:, window:, soft:, limited: }`, and `limited: true` marks the queries that would have been refused.
+3. When the limits fit your traffic, set `soft: false`.
+
+### Sharing limits between processes
+
+`MemoryStore` keeps buckets in one process: with four Puma workers on two servers, a client gets the limit eight times over, and a restart refills every bucket. In production use `RedisStore`, which keeps them in Redis, shared by every process:
+
+```ruby
+# Gemfile: gem "redis"
+RATE_LIMIT_STORE = GraphQL::Armory::RateLimits::RedisStore.new(redis: Redis.new(url: ENV.fetch("REDIS_URL")))
+
+class AppSchema < GraphQL::Schema
+  use GraphQL::Armory::RateLimits::Points, store: RATE_LIMIT_STORE, limit: 1_000, window: 60, soft: false
+  use GraphQL::Armory::RateLimits::Concurrency, store: RATE_LIMIT_STORE, limit: 5, soft: false
+end
+```
+
+- **Atomic.** Each charge, slot taken and slot released is one Lua script, so two requests of the same client never both spend the last points.
+- **One clock.** The time comes from Redis (`TIME`), not from each server, so servers whose clocks drift still agree on when a bucket refills.
+- **Small.** A client costs two keys, `graphql-armory:rate-limits:points:<key>` and `...:slots:<key>`; both expire once they no longer matter (a window, or `stale_after`, after the last use). Pass `prefix:` to share one Redis with other apps.
+- **Fails open.** When Redis is down or slow, the client raises, the query runs, and `on_store_error` is called: make that hook alert. Set the client's timeouts (for example `Redis.new(url: ..., timeout: 0.2)`) so a slow Redis cannot slow every request.
+
+The gem does not depend on the redis gem: add it to your Gemfile. A single `Redis` client is safe to share between threads.
+
+### Testing your limits
+
+`RateLimits::Store::Substitute` is a `MemoryStore` on a clock your test moves, that records its calls and fails when told, so specs need no mocks and no sleeping:
+
+```ruby
+store = GraphQL::Armory::RateLimits::Store::Substitute.new
+schema = Class.new(AppSchema) { use GraphQL::Armory::RateLimits::Points, store: store, limit: 100, window: 60, soft: false }
+
+store.now += 30                                     # half a window later
+store.fail_with(IOError.new("down"), on: :take)     # the next charges raise, as a broken Redis would
+store.answer(:take, [0, 0])                         # an answer no real store gives
+store.calls                                         # [[:take, "user:1", { cost: 40, limit: 100, window: 60, force: false }], ...]
+```
+
+`occupy(key)` holds a slot for an operation running elsewhere and `held(key)` counts the slots held. `RateLimits::Controls::Query.example`, `Root.example` and `Context.example` are a small schema and context to test against. `Points.new` and `Concurrency.new`, with nothing wired, refuse every query (`Store::Null`), and check every setting they are given: `soft: true` with no store raises, since it would count nothing; `Points.build(...)` and `Concurrency.build(...)` take the same settings as `use`.
+
+## Reference
+
+`use GraphQL::Armory::RateLimits::Points, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, extensions: false`
+
+- `store:` answers `take(key, cost:, limit:, window:, force:)` with `[taken, remaining]`. `MemoryStore.new(clock: ...)` keeps buckets in the process; `RedisStore` shares them (below).
+- `limit:` a positive Integer, or a callable `(key, query)` answering a positive Integer or nil.
+- `window:` positive seconds over which `limit` points refill, continuously.
+- `soft:` `true` (default) charges and records without refusing; `false` refuses.
+- `key:` a callable `(query)` answering the client key; by default `context[:rate_limit_key]`. It must be a non-empty String.
+- `on_store_error:` a callable `(error, query)` called when the store raises; the query then runs (fails open). By default it warns.
+- `extensions:` `true` adds `"rateLimit" => { cost, limit, remaining, resetIn }` to every response of a limited client; `false` (default) leaves responses unchanged.
+- `Points.headers(result)` answers the `RateLimit-*` headers for a result, or `{}`.
+- Instrumentation: `context[:rate_limit_points]`.
+
+`use GraphQL::Armory::RateLimits::Concurrency, store:, limit:, stale_after: 60, soft: true, key: nil, on_store_error: nil`
+
+- `store:` answers `acquire(key, token:, limit:, ttl:, force:)` with `[acquired, active]` and `release(key, token:)`. `MemoryStore` does both.
+- `limit:` operations at once per client: a positive Integer, or a callable `(key, query)` answering a positive Integer or nil.
+- `stale_after:` positive seconds after which a slot that was never released expires.
+- `soft:`, `key:` and `on_store_error:` as for `Points`. When the store raises on release, `on_store_error` is called and the slot expires after `stale_after`.
+- Instrumentation: `context[:rate_limit_concurrency]`.
+
+`GraphQL::Armory::RateLimits::RedisStore.new(redis:, prefix: "graphql-armory:rate-limits:", clock: nil)`
+
+- `redis:` a redis-rb client (>= 4.8), or anything answering `eval(script, keys:, argv:)` and `evalsha(sha, keys:, argv:)` the same way. Needs Redis 5 or later. Works with Redis Cluster: each script touches one key.
+- `prefix:` a non-empty String put before every key.
+- `clock:` nil (default) reads Redis's clock; a callable answering seconds replaces it, for tests.
+
+Invalid settings raise `RateLimits::ConfigurationError` at boot.
+
+## Guarantees and limits
+
+- A query this limiter refuses resolves no field and is not charged. A query that fails validation is not charged. A query refused by another analyzer (`max_depth`, `max_complexity`) is still charged: graphql-ruby runs every analyzer.
+- Each query in a multiplex is charged on its own.
+- `Concurrency` takes one slot per query of a multiplex, and releases them all when the multiplex ends, even when the queries share one context hash. If a release fails, that slot expires after `stale_after`; the others are still released.
+- A query run with its own trace (`context: { trace: ... }`) cannot be released by `Concurrency`, so it raises `ConfigurationError` instead of taking a slot.
+- A resolver that runs another query for the same client (a nested `execute`) takes a second slot while the first is held.
+- A subscription holds a slot only while its first result runs, not while it stays subscribed.
+- When queries of a multiplex share one context hash, `context[:rate_limit_points]` and `context[:rate_limit_concurrency]` hold the last query's record: give each query its own context hash to read every record.
+- The cost is graphql-ruby's estimate before running, not the time a query really takes: a field that is slow but scored 1 costs 1. Score expensive fields, and add the processing-time layer when it ships.
+- Field scores are yours: graphql-ruby treats a negative or NaN complexity as 0, so such a field is free, like `complexity: 0`. A complexity that is nil or a String makes graphql-ruby raise before the limiter runs, so the query does not run.
+- When the store fails, queries run unlimited and `on_store_error` is called. Choose that hook to alert. `RedisStore` also counts a bucket whose fields were changed into something that is not a number as a store failure, rather than reading it as full.
+- `MemoryStore` keeps buckets and slots in one process and forgets them on restart: with several processes, each one gives a client the full limit. It keeps one entry per client key it has seen. Use `RedisStore` in production.
+
+## Planned
+
+- **Processing time, a second layer:** a budget of milliseconds per client per window, measured as queries run, for costs the complexity score does not see.
+
+## References
+
+The same technique, charging queries a calculated cost against a budget per client, is used by large public GraphQL APIs:
+
+- GitHub: [Rate limits and query limits for the GraphQL API](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api): a points budget per hour, where connections' `first`/`last` drive the cost, and a `rateLimit` field showing what remains.
+- Shopify: [GraphQL Admin API rate limits](https://shopify.dev/docs/apps/build/apis/graphql-admin/rate-limits): a calculated query cost against a bucket that refills continuously; Shopify also refunds the difference when the real cost is lower than the estimate.
+- Cha et al., [A Principled Approach to GraphQL Query Cost Analysis](https://arxiv.org/abs/2009.05632) (ESEC/FSE 2020, IBM Research): estimating a query's cost statically, before running it, and why naive estimates over- or under-count.
+- graphql-ruby: [Complexity and depth](https://graphql-ruby.org/queries/complexity_and_depth), the cost this limiter charges.

data/lib/graphql/armory/encoder/null.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    class Encoder
+      # The encoder of an object nobody wired: it hands out no ID and honours none.
+      module Null
+        def self.encode(_text, nonce: false)
+          raise ConfigurationError, "no encoder wired: give an Encoder (or use Encoder.default)"
+        end
+
+        def self.decode(_text, nonce: false)
+          raise InvalidError
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/encoder/substitute.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    class Encoder
+      # Encodes reversibly without a key or any cryptography, records what it encoded and decoded, and fails when
+      # told: for tests of the objects that use an encoder. Never use it to hand out real IDs: anyone can forge them.
+      class Substitute
+        PREFIX = "substitute:"
+
+        attr_reader :encoded, :decoded
+
+        def initialize
+          @encoded = []
+          @decoded = []
+          @failure = nil
+        end
+
+        # Raises `error` from every encode and decode until `recover`.
+        def fail_with(error)
+          @failure = error
+        end
+
+        def recover
+          @failure = nil
+        end
+
+        def encode(text, nonce: false)
+          @encoded << text.to_s
+          raise @failure if @failure
+
+          PREFIX + URLSafeBase64.encode(text.to_s.b)
+        end
+
+        def decode(text, nonce: false)
+          @decoded << text.to_s
+          raise @failure if @failure
+          raise InvalidError unless text.to_s.start_with?(PREFIX)
+
+          URLSafeBase64.decode(text.to_s.delete_prefix(PREFIX)).force_encoding(Encoding::UTF_8)
+        rescue ArgumentError
+          raise InvalidError
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/encoder.rb

@@ -135,3 +135,5 @@ end
 require "graphql/armory/encoder/versioned"
 require "graphql/armory/encoder/legacy"
 require "graphql/armory/encoder/default"
+require "graphql/armory/encoder/null"
+require "graphql/armory/encoder/substitute"