graphql-armory 0.1.0.pre4 → 0.1.0.pre5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f463135c3578c6248c02f5610cb6bd1bc3f88fe9c26867e8cbd5164c84be408
-  data.tar.gz: 0344af8ea82c901fb5ad36cd1d236039f30afe3969142305b3e9b48d0890e5ab
+  metadata.gz: 431eab2604e80c473f2037cf636158113056cbd60e9fb408c8f6f91696586b55
+  data.tar.gz: aaa7d67cd478e2a0b8faf0b069eeb3e7a8051e2304caa55c8e522ddcc1a121bc
 SHA512:
-  metadata.gz: 171b49d43c89c1c306949b7e30c56aa71687ccff9f3028f99e8b5f181f4a80b650d8a58e996090013bfa8e800632848109e557842f8ee78aecffbf0893d8d14a
-  data.tar.gz: 477b8904c178b41c690f2c308004f0d0a8f441d4df144e4ff2cb4e1a06babe6a33c401728edfcc7ebfd0a14c8ae336c8d7ce12bf4de0944b11e2171cdc02c0c8
+  metadata.gz: 308f9883d87cd8f5ec8ebc711477779d95a3a149c3fb4e770f9866fc10f6f476c99a788c8493fa03317f3963f71f0aab8da786904ecb78c3ac269f82345ae565
+  data.tar.gz: 31179d1a3c3a4b7d5a71027d2b1ce18f983843b10c87e6418c9763a89a33ec33dd7669fdc1bc3dddc2abe0876f37716495c50b4fb05393c58f8b9a38c79015e3

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## 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`.

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.pre4`). 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.pre4"  # 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
 ```
 
@@ -26,7 +26,7 @@ Status: ✅ released, 🚧 in progress, ⬜ not started. Update this table in th
 | 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.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. |
+| 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.pre4 && git push origin v0.1.0.pre4
+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

@@ -136,6 +136,10 @@ Relay's example network layer sends the id as `doc_id`. Pass it yourself: `opera
 
 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)`

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"

data/lib/graphql/armory/ids/controls.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module IDs
+      # Test data for encrypted IDs, reusable by apps and other gems.
+      module Controls
+        # An Encoder subclass with a fixed test key. Never use its key in production.
+        module Encoder
+          def self.example(key: "k" * 32)
+            Class.new(Armory::Encoder) { key(key) }
+          end
+        end
+
+        # A record with an id, as `id_from_object` receives it.
+        module Record
+          def self.example(id: 1)
+            Struct.new(:id).new(id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/ids.rb

@@ -17,7 +17,7 @@ module GraphQL
       SEPARATOR = "/"
 
       def self.use(schema, encoder: nil, find: nil)
-        lookup = Lookup.new(encoder: encoder || Encoder.default, find: find)
+        lookup = Lookup.build(encoder: encoder, find: find)
         schema.define_singleton_method(:id_from_object) { |object, type, _context| lookup.id_for(object, type) }
         schema.define_singleton_method(:object_from_id) { |id, context| lookup.object_for(id, context) }
       end
@@ -26,7 +26,18 @@ module GraphQL
       class Lookup
         attr_reader :encoder, :find
 
-        def initialize(encoder:, find: nil)
+        # Wires the default encoder unless one is given; `use` goes through here.
+        def self.build(encoder: nil, find: nil)
+          new(encoder: encoder || Encoder.default, find: find)
+        end
+
+        # `new` is inert: with no encoder wired it hands out no ID and honours none. It checks what it is given.
+        def initialize(encoder: Encoder::Null, find: nil)
+          unless %i[encode decode].all? { |name| encoder.respond_to?(name) }
+            raise Encoder::ConfigurationError, "encoder: must answer encode and decode, like an Encoder subclass"
+          end
+          raise Encoder::ConfigurationError, "find: must be nil or a callable taking the type, the key and the context" unless find.nil? || find.respond_to?(:call)
+
           @encoder = encoder
           @find = find
         end
@@ -74,3 +85,5 @@ module GraphQL
     end
   end
 end
+
+require "graphql/armory/ids/controls"

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # Test data for persisted queries, reusable by apps and other gems.
+      module Controls
+        # The operations a client build would persist for Query.example.
+        module Operations
+          def self.invoices = "query Invoices { invoices }"
+          def self.greeting = "query Greeting($name: String!) { greeting(name: $name) }"
+        end
+
+        # A Query type with two persisted operations' fields and a `secret` no operation asks for.
+        module Query
+          def self.example
+            Class.new(GraphQL::Schema::Object) do
+              graphql_name "Query"
+              field :invoices, [String], null: false
+              field :greeting, String, null: false do
+                argument :name, String
+              end
+              field :secret, String, null: false
+            end
+          end
+        end
+
+        # The root object for Query.example; it adds the name of each field it resolves to `resolved`.
+        module Root
+          def self.example(resolved = [])
+            Class.new do
+              define_method(:invoices) { resolved << :invoices; ["A-1"] }
+              define_method(:greeting) { |name:| resolved << :greeting; "Hello #{name}" }
+              define_method(:secret) { resolved << :secret; "s3cr3t" }
+            end.new
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # What the plugin fetches operations from: a `Manifest`, or any object answering `fetch(id)`. `Null` and
+      # `Substitute` are the inert and the test stand-ins.
+      module Store
+        # The store of a plugin nobody wired: it holds no operation, so every id is unknown.
+        class Null
+          def fetch(_id)
+            nil
+          end
+        end
+
+        # Holds the given queries under the SHA-256 of each, like an Apollo manifest, records the ids it was asked
+        # for and fails when told: for tests, instead of hand-written stores.
+        class Substitute
+          attr_reader :fetched
+
+          def initialize(*queries)
+            @manifest = Manifest.new(queries.to_h { |query| [Digest::SHA256.hexdigest(query), query] })
+            @fetched = []
+            @failure = nil
+          end
+
+          # Raises `error` from every fetch until `recover`.
+          def fail_with(error)
+            @failure = error
+          end
+
+          def recover
+            @failure = nil
+          end
+
+          def fetch(id)
+            @fetched << id
+            raise @failure if @failure
+
+            @manifest.fetch(id)
+          end
+        end
+      end
+    end
+  end
+end