graphql-armory 0.1.0.pre8 → 0.1.0.pre9

data/docs/rate-limiting.md

@@ -107,7 +107,7 @@ field :create_invoice, mutation: Mutations::CreateInvoice, complexity: 10  # 10
 
 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.
+- **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, `Points` refuses that query with `This connection needs first: or last:` (code `PAGE_SIZE_REQUIRED`), in soft mode too, and charges nothing. A raise by another analyzer does not skip that refusal. graphql-ruby's install template sets neither, so set one: without it, a client that does send `first:` chooses its own page size. A schema with `max_complexity` still gets graphql-ruby's server error on that query, because its own analyzer raises it. This refusal leaves no record and no `rateLimit` extension, so it does not appear in your rate limit metrics. 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.
 
@@ -229,7 +229,7 @@ To test it, inject a clock: `Time` takes `clock:` (a callable answering seconds)
 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`.
 
-Rate limiting reports through the query context rather than through `sinks:`, because the context is also where the budget for the response comes from. To see its decisions next to the other modules' signals, send those records to the same place: [Telemetry](telemetry.md#rate-limiting).
+Rate limiting reports its charges through the query context rather than through `sinks:`, because the context is also where the budget for the response comes from. To see its decisions next to the other modules' signals, send those records to the same place: [Telemetry](telemetry.md#rate-limiting).
 
 ### Sharing limits between processes
 
@@ -247,8 +247,8 @@ 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.
+- **Small.** A client costs up to three keys, `graphql-armory:rate-limits:points:<key>`, `...:points:time:<key>` for `Time`, and `...:slots:<key>`; all 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. With `sinks:`, the failure is also recorded as `:rate_limit_store_failed`. 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.
 
@@ -270,31 +270,32 @@ store.calls                                         # [[:take, "user:1", { cost:
 
 ## Reference
 
-`use GraphQL::Armory::RateLimits::Points, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, extensions: false`
+`use GraphQL::Armory::RateLimits::Points, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, sinks: [], 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.
+- `key:` a callable `(query)` answering the client key; by default `context[:rate_limit_key]`. It must be a non-empty String, or a list of up to 5 different ones for all three limiters: a query runs only if every key allows it. The record, the headers and the extensions show the key that binds, and the record adds `keys:` with each one. The refusals a client sees never name a key. Without one, the query raises `ConfigurationError`, on every query: a key built from something that can be nil (an IP behind a misconfigured balancer) needs a fallback, such as `context[:rate_limit_key] = request.remote_ip.presence || "unknown"`, where all such clients share one bucket.
 - `on_store_error:` a callable `(error, query)` called when the store raises; the query then runs (fails open). By default it warns.
+- `sinks:` callables that hear `:rate_limit_store_failed` when the store raises; see [Telemetry](telemetry.md#rate-limiting).
 - `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`
+`use GraphQL::Armory::RateLimits::Concurrency, store:, limit:, stale_after: 60, soft: true, key: nil, on_store_error: nil, sinks: []`
 
 - `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`.
+- `soft:`, `key:`, `on_store_error:` and `sinks:` 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]`.
 
-`use GraphQL::Armory::RateLimits::Time, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, clock: Clock.monotonic, extensions: false`
+`use GraphQL::Armory::RateLimits::Time, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, sinks: [], clock: Clock.monotonic, extensions: false`
 
 - `store:` as for `Points`: it is asked for the balance with `take(key, cost: 0, ...)` and charged with `take(key, cost: milliseconds, ..., force: true)`. No store changes are needed.
 - `limit:` milliseconds per `window` per client: a positive Integer, or a callable `(key, query)` answering a positive Integer or nil.
-- `window:`, `soft:`, `key:` and `on_store_error:` as for `Points`.
+- `window:`, `soft:`, `key:`, `on_store_error:` and `sinks:` as for `Points`.
 - `clock:` a callable answering seconds, read when a multiplex starts and when it ends. By default a monotonic clock.
 - `extensions:` `true` adds `"rateLimitTime" => { limit, remaining, elapsed, resetIn }` to the response of a limited client.
 - `Time.headers(result)` answers the `RateLimit-Time-*` headers for a result, or `{}`.
@@ -312,9 +313,18 @@ Invalid settings raise `RateLimits::ConfigurationError` at boot.
 
 - 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.
+- With several keys, `Points` reads every balance and then charges, so a refused query leaves the others as they were. Two queries racing between those steps can leave a refused one having charged other keys. `Concurrency` gives back the slots a refused query took at once. `Time` charges every key the whole time; a store failure on one key does not stop the others.
+- An `ExecutionError` raised during analysis, which graphql-ruby would discard before running the query, does not skip a limiter. A refusal already given stands. A limiter not asked yet is asked on its own, so another analyzer's raise leaves the query charged and running as before. A limiter that cannot answer, because a `complexity:` lambda or its `on_store_error` hook raised, refuses the query in hard mode with the code `RATE_LIMIT_NOT_CHARGED`, and in soft mode lets it run and records `charged: false`. A client with no limit still runs, and a query with no key raises `ConfigurationError`. When a query takes this path it is visited once more per limiter not asked yet, so a `complexity:` lambda can run several times, `key:` and `limit:` are asked again, and a validation timeout can take longer. An analysis your app runs itself outside an execution charges nothing here. A trace that takes no modules from the schema (`context[:trace]` or a class given to `trace_mode`) is outside this: `Points` is not protected on such a trace.
+- A `max_depth` or `max_complexity` refusal is not a limiter's, so it is lost when an analyzer or a `complexity:` lambda raises `ExecutionError`: graphql-ruby discards every analyzer's answer and runs the query. If a lambda raises for a field a client can pick, the client can choose this. Do not raise `ExecutionError` from a lambda or an analyzer: have the analyzer's `result` return a `GraphQL::AnalysisError`.
+- On `Execution::Next`, `validate: false` ignores every refusal from analysis, the limiters' included. Never pass it for a client's query.
+- A field with `max_page_size: nil` under a schema with `default_max_page_size` is sized by that default, while at runtime it has no maximum, so it is charged less than it returns. Give such a field a number.
+- An `ExecutionError` from a multiplex analyzer's `result` raises to your app: nothing runs and no slot stays held.
+- With several keys, a key whose store fails is left out and `on_store_error` is called for it; the others still decide, so a client cannot cancel a refusal by choosing a key on a dead shard. Only when every key's store fails does the query run unlimited. A list whose members differ only in encoding counts as a duplicate and raises.
 - `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.
+- `Points` and `Time` keep separate budgets on one store and key: `Time` stores its milliseconds under `time:<key>` (`Time.bucket_key(key)`; a custom store sees that key). So do not give `Points` a key starting with `time:` that matches a `Time` key.
+- Two limiters of the same class on one store and key share one bucket: both charge it, and each caps and refills it with its own limit. Give each `use Points` or `use Time` its own store (`RedisStore.new(redis:, prefix:)`) or its own keys.
 - 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]`, `context[:rate_limit_concurrency]` and `context[:rate_limit_time]` 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 `Time` to charge what queries really take.
@@ -324,10 +334,11 @@ Invalid settings raise `RateLimits::ConfigurationError` at boot.
 
 ### Limits of `Time`
 
+- A query `Time` refuses is still charged by `Points` on the same schema, because graphql-ruby runs every analyzer.
 - A running operation is never interrupted: the one that exhausts the budget finishes, and only the next one is refused. Operations that start while a long one is still running all see the balance before it is charged, so together they can spend more than the client has; the balance then stops at zero (there is no debt).
 - `retryAfter` is the time the client needs to regain one millisecond (`window / limit` seconds, at least 1). It lets the client in again, not necessarily for an operation that takes long.
 - A multiplex has one measured time, split equally among the queries this limiter charges, rounded up to whole milliseconds: fields of different queries interleave, so their time cannot be told apart. A query refused by `Time`, and one whose key has no limit (`nil`), are not part of the split, so the time of a query with no limit is carried by the limited ones.
-- A schema may `use Time` more than once (for example per user and per IP, with different stores and keys): each limiter charges only its own. `context[:rate_limit_time]`, the response extension and `Time.headers` then hold the record of the last one.
+- A schema may `use Time` more than once, with different stores or keys (for example per user and per IP): each limiter charges only its own. `context[:rate_limit_time]`, the response extension and `Time.headers` then hold the record of the last one.
 - The clock must answer a finite number of seconds: one that does not is refused at boot, and one that breaks later raises instead of letting operations run uncharged. A clock that stands still or goes backwards charges 0.
 - Time spent before analysis finishes (parsing, validation) is charged to no one, and inside a multiplex it ends up on the queries that did run. A query that never reaches analysis (a syntax error) costs the client nothing.
 - The time is wall-clock, so it grows when the server is loaded: the same query costs a client more on a busy server. Choose `limit` with that in mind, and start in soft mode.
@@ -340,6 +351,16 @@ Every key has its own bucket. A client that gets a new key for each request (a n
 
 What you can do with the gem:
 
+- **Draw from several buckets at once.** A key may be a list of up to 5 different Strings, so rotating one identity leaves the others:
+
+  ```ruby
+  context[:rate_limit_key] = ["user:#{user.id}", "ip:#{request.remote_ip}", ("new-accounts" if user.created_at > 1.day.ago)].compact
+
+  use GraphQL::Armory::RateLimits::Points, store: store, window: 60,
+    limit: ->(key, _query) { key.start_with?("user:") ? 1_000 : key.start_with?("ip:") ? 3_000 : 500 }
+  ```
+
+  A query runs only if every key has the budget, and each key is charged. `limit:` is asked once per key, and a key it answers `nil` for is left out. The prefixes are yours: they keep kinds of key apart in the store. It costs store round trips on every query, about two per key, so use two or three. Do not build a key from the document or its variables: a client could then spend someone else's budget.
 - **Share one bucket among the clients you do not trust yet.** Build the key from something that is not free to rotate, such as the age of the account, so every new account draws from the same small budget:
 
   ```ruby

data/docs/telemetry.md

@@ -100,6 +100,20 @@ end
 
 The gem does not depend on Datadog or on any other backend. The same shape works for StatsD, Prometheus, OpenTelemetry or whatever your team uses: write the callable that turns `(signal, data)` into one call of that client. The example above follows Datadog's documented `increment(name, tags:)`; it has not been run against a live agent.
 
+### Who asked
+
+A sink that requires three arguments also receives the query's context, so it can read who was refused:
+
+```ruby
+count_probes = lambda do |signal, data, context|
+  next unless signal == :operation_refused && data[:reason] == :raw_query
+
+  Strikes.add(context[:client_ip])
+end
+```
+
+The sink reads the context through a view that answers `[]`, `fetch`, `dig` and `key?`, and cannot write to it, so a sink cannot change who the query runs as. An object held in the context is your own, and a sink can still change that. The view is empty when the query has none. A sink that takes two arguments, `*arguments` or a defaulted third never receives it, so a sink that logs what it gets does not start logging tokens. What you read from the context is yours to keep out of logs.
+
 ### What to watch for
 
 | You see | It usually means | What to do |
@@ -119,6 +133,7 @@ The gem does not depend on Datadog or on any other backend. The same shape works
 |---|---|---|
 | `:allowed` | The policy or ability said yes | `type`, `action` |
 | `:denied` | It said no, nil or anything that is not a clear yes | `type`, `action` |
+| `:observed` | It said no to a rule under `observe:`, so the data was served | `type`, `action`, `reason` |
 | `:bypassed` | The rule is `authorize :none, reason: "..."` | `type` (not on lists), `reason` |
 | `:scoped` | A list or lookup went through the user's scope | `action` |
 
@@ -153,15 +168,21 @@ The reasons of `:id_refused`:
 
 ### Rate limiting
 
-Rate limiting has no sinks. It records on every query, in the query's context, what it charged and what remains: `context[:rate_limit_points]`, `context[:rate_limit_concurrency]` and `context[:rate_limit_time]`, which carry `limited: true` for the queries it refused or, in soft mode, would have refused. See [Rolling it out](rate-limiting.md#rolling-it-out) and [Showing clients their budget](rate-limiting.md#showing-clients-their-budget). Send those to the same place as the signals above.
+Rate limiting takes `sinks:` for one signal, when its store fails:
+
+| Signal | When | Data |
+|---|---|---|
+| `:rate_limit_store_failed` | The store raised, so the query ran without a limit | `limiter`: `:points`, `:concurrency` or `:time`; `error`: the error's class name |
+
+Everything else it records on every query, in the query's context. It records on every query, in the query's context, what it charged and what remains: `context[:rate_limit_points]`, `context[:rate_limit_concurrency]` and `context[:rate_limit_time]`, which carry `limited: true` for the queries it refused or, in soft mode, would have refused. See [Rolling it out](rate-limiting.md#rolling-it-out) and [Showing clients their budget](rate-limiting.md#showing-clients-their-budget). Send those to the same place as the signals above.
 
 ## What telemetry does not cover
 
 Signals are counters of the gem's decisions. They are not a replacement for these:
 
 - **Traces.** A signal is a point event, not a span. In Datadog APM (or any tracer) a refused ID does not appear as a span of its own; it shows in the trace of the request that carried it, as the normal "not found" answer. If you want it on the trace, have your sink add a tag to the active span with your tracer's API.
-- **Who asked.** A signal says `id_refused`, not which user or IP. Correlate with your request logs through the request id, or add the user in your own sink from your request context: that is yours to hold, and stays out of the gem.
-- **Rate limiting.** It has no sinks: it records in the query's context. Send `context[:rate_limit_points]`, `context[:rate_limit_concurrency]` and `context[:rate_limit_time]` from your controller, to the same client. They hold the rate limit `key:` (a user id or an IP): send them somewhere that may hold personal data, or leave the key out.
+- **Who asked, in the signal.** A signal says `id_refused`, not which user or IP. A sink that takes three arguments receives the query's context and can read them from it: see [Who asked](#who-asked).
+- **Rate limiting's decisions.** Its sinks hear only about a failing store: what it charged is in the query's context. Send `context[:rate_limit_points]`, `context[:rate_limit_concurrency]` and `context[:rate_limit_time]` from your controller, to the same client. They hold the rate limit `key:` (a user id or an IP): send them somewhere that may hold personal data, or leave the key out.
 - **Slow or failing requests.** The gem records its decisions. Latency, errors and throughput of your GraphQL endpoint come from your APM or from graphql-ruby's own tracing.
 - **Anything that did not reach the gem.** A request rejected before GraphQL runs (a web application firewall, a body size limit, a parse error) never produces a signal.
 - **A guarantee of delivery.** Sinks run in the request and report nothing if the process dies first. Counters sent to StatsD are best effort by design.
@@ -203,22 +224,24 @@ use GraphQL::Armory::PersistedQueries, store: store, sinks: [->(signal, data) {
 
 ## Reference
 
-- `sinks:` is an option of `use GraphQL::Armory::Authorization`, `use GraphQL::Armory::IDs` and `use GraphQL::Armory::PersistedQueries`. An Array of callables taking `(signal, data)`, called in order; default `[]`.
-- `Telemetry.new(sinks: [])`, `Telemetry.build(sinks: [])`, `telemetry.record(signal, **data)` (answers nil; `data` reaches the sinks frozen).
+- `sinks:` is an option of `use GraphQL::Armory::Authorization`, `use GraphQL::Armory::IDs`, `use GraphQL::Armory::PersistedQueries` and the rate limiters. An Array of callables taking `(signal, data)` or `(signal, data, context)`, called in order; default `[]`.
+- `on_sink_error:` is an option of the same modules except the rate limiters. A callable `(error, signal)` called when a sink raises; by default it warns with the signal and the error's class. Raise from it to fail the request closed.
+- A sink that could never be called (`->(a) {}`, four required arguments, a required keyword) raises `Telemetry::ConfigurationError` at boot.
+- `Telemetry.new(sinks: [], on_sink_error: nil)`, `Telemetry.build(sinks: [], on_sink_error: nil)`, `telemetry.record(signal, context: nil, **data)` (answers nil; `data` reaches the sinks frozen).
 - `Telemetry::Notifications`: a sink that calls `ActiveSupport::Notifications.instrument("<signal>.graphql_armory", data)`. `Notifications.available?` tells whether ActiveSupport::Notifications is loaded.
-- `Telemetry::Substitute`: `record`, `recorded` (an Array of `[signal, data]`), `recorded?(signal)`, and `fail_with(error)` / `recover` to make `record` raise, as a broken sink would.
+- `Telemetry::Substitute`: `record`, `recorded` (an Array of `[signal, data]`), `contexts`, `recorded?(signal)`, and `fail_with(error)` / `recover` to make `record` raise, for code that calls `record` directly: a real `record` does not raise when a sink does.
 - `Telemetry::ConfigurationError`, raised at boot when `sinks:` is not an Array of callables, or a sink reports `available?` as false. Its message names the class of the offending value and never prints the value: a metrics client holds its API key.
 - `Authorization::Telemetry` is the same class as `Telemetry`.
 
 ## Guarantees and limits
 
 - **Sinks run inline**, in the request's thread, in the order given. A slow sink slows every request: increment a counter or enqueue, do not call a remote service.
-- **A sink that raises fails the request closed.** The error normally reaches the request, and nothing is let through because of it. One exception: the gem reads an `Encoder::InvalidError` raised while it looks an ID up (and, for an ID given to a `loads:` argument, also an `ArgumentError` or an `ActiveRecord::RecordNotFound`) as an invalid ID and answers `nil`, so a sink raising one of those does not surface (it is still closed: the record is not loaded). If you would rather a broken metrics client never fail a request, rescue inside your sink.
+- **A sink that raises does not touch the request.** The gem's decision stands, the next sink runs, and `on_sink_error:` is called. By default that prints the signal and the error's class, never its message, which may hold a credential, once per failure: one request can print many. If the record must exist before the data is served (an audit log), raise from `on_sink_error:` to fail the request closed. A `rescue_from` for that error still runs, and the object is denied whatever it answers. In encrypted IDs, an `Encoder::InvalidError` or `ArgumentError` raised from `on_sink_error:` reads as an invalid ID: the client gets `nil`, closed, and an extra `:id_refused` signal is recorded. On a rate limiter a sink always only warns: use `on_store_error:` to act on a failing store.
 - **Every sink gets the same frozen data.** The Hash and its String values are frozen, so a sink cannot change what the next one sees: trying raises `FrozenError`. The signals carry only Symbols and Strings today. `Notifications` makes one unfrozen copy per signal, which ActiveSupport passes to every subscriber: a subscriber that changes its payload changes it for the next subscriber.
 - **One request can record many signals**, one per decision (a list of invoices is several), and each query of a batch records its own.
 - **Signals are not a security log by themselves.** They tell you what the gem decided; who asked comes from your request context.
 - Names and reasons are part of the public API, but the gem is in prerelease: they may change before 1.0, and the CHANGELOG says so when they do.
-- Rate limiting reports through the query context, not through sinks.
+- Rate limiting reports its charges through the query context; its sinks hear only about a failing store.
 
 ## References
 

data/exe/graphql-armory-publish

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "graphql/armory"
+
+exit GraphQL::Armory::PersistedQueries::Publisher::Command.call(ARGV)

data/lib/graphql/armory/authorization/adapters/cancan.rb

@@ -9,15 +9,18 @@ module GraphQL
         # Answers the core's four questions with CanCanCan's public API.
         #
         # The actor is an Ability: `context[:current_ability]`, else `Ability.new(context[:current_user])`
-        # (or the class given as `ability_class:`). It is built once per query.
+        # (or the class given as `ability_class:`, and the key given as `user_key:`). It is built once per query.
         #
         # A field that declares its own action (`authorize: :manage`) passes its attribute to `can?`: with
         # `can :read, User, [:username]`, `can?(:read, user)`
         # is true even though only one attribute is readable. Fields covered by their type's rule are not asked
         # about their attribute: declare an action on the ones an attribute rule must hide.
         class CanCan
-          def initialize(ability_class: nil)
+          def initialize(ability_class: nil, user_key: :current_user)
+            raise ArgumentError, "user_key must be a Symbol or a String, got #{user_key.class}" unless user_key.is_a?(Symbol) || user_key.is_a?(String)
+
             @ability_class = ability_class
+            @user_key = user_key
           end
 
           def actor(context)
@@ -86,7 +89,8 @@ module GraphQL
 
           def ability_for(context)
             store = context.namespace(:armory)
-            store[:cancan_ability] ||= ability_class.new(context[:current_user])
+            abilities = store[:cancan_abilities] ||= {}
+            abilities[self] ||= ability_class.new(context[@user_key])
           end
 
           def ability_class

data/lib/graphql/armory/authorization/adapters/pundit.rb

@@ -12,8 +12,15 @@ module GraphQL
         # overrides and namespaced models work. A policy must answer `true`, `false` or `nil`:
         # anything else (a lazy, a record) is handed back as is and the core refuses it.
         class Pundit
+          # `user_key:` is the context key that holds the user.
+          def initialize(user_key: :current_user)
+            raise ArgumentError, "user_key must be a Symbol or a String, got #{user_key.class}" unless user_key.is_a?(Symbol) || user_key.is_a?(String)
+
+            @user_key = user_key
+          end
+
           def actor(context)
-            context[:current_user]
+            context[@user_key]
           end
 
           def authorized?(user, subject, rule)

data/lib/graphql/armory/authorization/audit/baseline.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQL
+  module Armory
+    module Authorization
+      class Audit
+        # The problems a team accepted for now, so adopting the gem on a large schema fails the build only on new ones.
+        # A report's `ok?` never changes because of it: a schema with problems is not ok, with or without a baseline.
+        #
+        #   Baseline.load("config/graphql_armory_baseline.json").(report).passes?
+        #
+        # An entry accepts one problem as it was: how many times it appeared, and what it reached (see Reach). A problem that
+        # grew, because a field or a subclass was added to what it covers, is not the problem someone accepted.
+        class Baseline
+          VERSION = 1
+          Entry = Struct.new(:kind, :path, :message, :count, :covers) do
+            def key = [kind, path, message]
+            def to_h = { "kind" => kind, "path" => path, "message" => message, "count" => count, "covers" => covers }
+          end
+
+          # What a report comes to against a baseline. It has no `ok?`, so nobody reads a pass as a clean schema.
+          class Result
+            attr_reader :report, :new_problems, :accepted, :gone, :grown
+
+            def initialize(report:, new_problems:, accepted:, gone:, grown: {})
+              @report = report
+              @new_problems = new_problems.freeze
+              @accepted = accepted.freeze
+              @gone = gone.freeze
+              @grown = grown.freeze
+              freeze
+            end
+
+            # An accepted problem that is gone fails too: left in the file, it could come back unseen.
+            def passes?
+              new_problems.empty? && gone.empty?
+            end
+
+            def to_s
+              sections = [
+                section("#{new_problems.size} new #{plural('problem', new_problems.size)}:", new_problems.map { |problem| new_line(problem) }),
+                section("#{gone.size} accepted #{plural('problem', gone.size)} no longer found (remove them from the baseline):", gone.map { |entry| "#{entry.path} (#{entry.kind}): #{entry.message}" }),
+                section("#{accepted.size} accepted in the baseline, still open:", accepted),
+                bypasses_text
+              ].compact
+              sections.unshift("Passes only because of its baseline.") if passes? && !accepted.empty?
+              sections.unshift("No problems.") if passes? && accepted.empty?
+              "#{sections.join("\n\n")}\n"
+            end
+
+            private
+
+            def new_line(problem)
+              extra = grown[problem]
+              extra ? "#{problem} (it now also reaches #{extra.join(', ')})" : problem.to_s
+            end
+
+            def section(title, lines)
+              return if lines.empty?
+
+              [title, *lines.map { |line| "  #{line}" }].join("\n")
+            end
+
+            def bypasses_text
+              section("#{report.bypasses.size} declared #{report.bypasses.size == 1 ? 'bypass' : 'bypasses'}:", report.bypasses.map { |bypass| "#{bypass.path}: #{bypass.reason}" })
+            end
+
+            def plural(word, count)
+              count == 1 ? word : "#{word}s"
+            end
+          end
+
+          # Every problem of a report, accepted as it is now.
+          def self.from(report)
+            new(report.problems.group_by { |problem| [problem.kind.to_s, problem.path, problem.message] }.map do |(kind, path, message), problems|
+              Entry.new(kind, path, message, problems.size, report.reach_of(problems.first))
+            end)
+          end
+
+          def self.load(path)
+            data = begin
+              JSON.parse(File.read(path, mode: "r:bom|utf-8"))
+            rescue JSON::ParserError, ArgumentError, EncodingError
+              # Not the parser's message: it quotes the file's content.
+              raise ConfigurationError, "the baseline #{path} is not valid JSON"
+            rescue SystemCallError => error
+              raise ConfigurationError, "the baseline #{path} cannot be read (#{error.class})"
+            end
+            unless data.is_a?(Hash) && data["version"].eql?(VERSION) && data["problems"].is_a?(Array)
+              raise ConfigurationError, "the baseline #{path} needs version #{VERSION} and a list of problems"
+            end
+
+            new(data["problems"].map { |entry| entry_from(entry, path) })
+          end
+
+          # Creates the file with every problem. A file that exists only ever loses what is gone: accepting a new problem is
+          # a manual edit, so it shows in review. Answers what was written.
+          def self.write(report, path)
+            baseline = from(report)
+            kept = File.exist?(path) ? load(path).kept_from(baseline) : baseline
+            File.write(path, "#{JSON.pretty_generate('version' => VERSION, 'problems' => kept.entries.map(&:to_h))}\n")
+            kept
+          rescue SystemCallError => error
+            raise ConfigurationError, "the baseline #{path} cannot be written (#{error.class})"
+          end
+
+          # With no count or covers an entry accepts the narrowest thing: one problem that reaches nothing.
+          def self.entry_from(entry, path)
+            unless entry.is_a?(Hash) && %w[kind path message].all? { |key| entry[key].is_a?(String) }
+              raise ConfigurationError, "the baseline #{path} needs a kind, a path and a message in each problem"
+            end
+
+            count = entry.fetch("count", 1)
+            covers = entry.fetch("covers", [])
+            unless count.is_a?(Integer) && count.positive? && covers.is_a?(Array) && covers.all?(String)
+              raise ConfigurationError, "the baseline #{path} needs a positive count and a list of Strings in covers"
+            end
+
+            Entry.new(*entry.values_at("kind", "path", "message"), count, covers)
+          end
+          private_class_method :entry_from
+
+          attr_reader :entries
+
+          # What a baseline never accepts: with no plugin, no rule runs at all, so there is nothing to adopt gradually; an own
+          # check or a denial hook reaches whatever uses it later, which no entry can pin down, and each already has its
+          # declaration with a reason (`own_checks:`, `own_denial_hooks:`).
+          REFUSED = { "plugin" => "a baseline cannot accept a schema that never installed the plugin: install it first",
+                      "own_check" => "a baseline cannot accept an own check: remove it, or declare it in own_checks: with a reason",
+                      "hook" => "a baseline cannot accept a denial hook: remove it, or declare it in own_denial_hooks: with a reason",
+                      "observed" => "a baseline cannot accept observe: it serves what the rule would refuse, and it already says why" }.freeze
+
+          # `new` is inert: it accepts nothing, so every problem is new.
+          def initialize(entries = [])
+            refused = entries.find { |entry| REFUSED.key?(entry.kind) }
+            raise ConfigurationError, "#{REFUSED.fetch(refused.kind)} (#{refused.path})" if refused
+
+            @entries = entries.map { |entry| Entry.new(entry.kind, entry.path, entry.message, entry.count || 1, entry.covers || []) }.uniq(&:key).sort_by(&:to_a).freeze
+          end
+
+          def call(report)
+            by_key = entries.to_h { |entry| [entry.key, entry] }
+            seen = Hash.new(0)
+            grown = {}
+            accepted, new_problems = report.problems.partition do |problem|
+              entry = by_key[key_of(problem)]
+              next false unless entry
+
+              extra = beyond(report.reach_of(problem), entry.covers)
+              grown[problem] = extra unless extra.empty?
+              extra.empty? && (seen[entry.key] += 1) <= entry.count
+            end
+            found = report.problems.map { |problem| key_of(problem) }
+            Result.new(report: report, new_problems: new_problems, accepted: accepted, grown: grown,
+                       gone: entries.reject { |entry| found.include?(entry.key) })
+          end
+
+          # This baseline without what `other` no longer holds: nothing grows.
+          def kept_from(other)
+            current = other.entries.to_h { |entry| [entry.key, entry] }
+            self.class.new(entries.filter_map do |entry|
+              now = current[entry.key]
+              next unless now
+
+              Entry.new(entry.kind, entry.path, entry.message, [entry.count, now.count].min, common(entry.covers, now.covers))
+            end)
+          end
+
+          private
+
+          def key_of(problem)
+            [problem.kind.to_s, problem.path, problem.message]
+          end
+
+          # What `now` holds beyond `accepted`, counting repeats: two classes may share a name.
+          def beyond(now, accepted)
+            left = accepted.tally
+            now.reject { |item| left[item].to_i.positive? && (left[item] -= 1) }
+          end
+
+          def common(one, other)
+            left = other.tally
+            one.select { |item| left[item].to_i.positive? && (left[item] -= 1) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/authorization/audit/command.rb

@@ -6,25 +6,74 @@ module GraphQL
       class Audit
         # What `rake graphql_armory:audit[YourSchema]` runs: prints the report and answers an exit status.
         class Command
+          # The rake task's action. The app's Rake file may name the task first, to add a prerequisite, so the task existing does
+          # not mean this ran: the file looks for this object among its actions.
+          RAKE_ACTION = proc do |_task, args|
+            Rake::Task[:environment].invoke if Rake::Task.task_defined?(:environment)
+            # By position: an app that declares the task again renames its arguments.
+            status = new.(args[:schema], args.to_a[1])
+            exit(status) unless status.zero?
+          end
+
+          # The baseline task's action: writes the file, or removes from it what is gone.
+          BASELINE_ACTION = proc do |_task, args|
+            Rake::Task[:environment].invoke if Rake::Task.task_defined?(:environment)
+            status = new.write_baseline(args[:schema], args.to_a[1])
+            exit(status) unless status.zero?
+          end
+
           def initialize(out: $stdout)
             @out = out
           end
 
-          def call(schema_name)
-            return fail_with("Name the schema: rake graphql_armory:audit[YourSchema]") if schema_name.to_s.empty?
+          def call(schema_name, baseline = nil)
+            with_schema(schema_name, "audit") do |schema|
+              report = Audit.(schema)
+              next judged(report, baseline) unless baseline.to_s.empty?
+
+              @out.print(report)
+              report.ok? ? 0 : 1
+            end
+          end
+
+          def write_baseline(schema_name, path)
+            return fail_with("Name the file: rake graphql_armory:audit_baseline[YourSchema,path]") if path.to_s.empty?
+
+            with_schema(schema_name, "audit_baseline") do |schema|
+              wrote(Audit.(schema), path)
+            end
+          end
+
+          private
 
-            schema = Object.const_get(schema_name)
-            report = Audit.(schema)
-            @out.print(report)
-            report.ok? ? 0 : 1
+          def judged(report, baseline)
+            result = Baseline.load(baseline).(report)
+            @out.print(result)
+            result.passes? ? 0 : 1
+          rescue ConfigurationError => error
+            fail_with(error.message)
+          end
+
+          def wrote(report, path)
+            written = Baseline.write(report, path)
+            not_accepted = Baseline.new(written.entries).(report).new_problems.size
+            @out.puts("#{path}: #{written.entries.size} accepted. Fix them: this list only ever shrinks.")
+            @out.puts("#{not_accepted} not accepted: they still fail the audit.") if not_accepted.positive?
+            0
+          rescue ConfigurationError => error
+            fail_with(error.message)
+          end
+
+          def with_schema(schema_name, task)
+            return fail_with("Name the schema: rake graphql_armory:#{task}[YourSchema]") if schema_name.to_s.empty?
+
+            yield Object.const_get(schema_name)
           rescue NameError => error
             raise unless error.name.to_s == schema_name.to_s.split("::").last
 
             fail_with("No schema named #{schema_name}")
           end
 
-          private
-
           def fail_with(message)
             @out.puts(message)
             1

data/lib/graphql/armory/authorization/audit/findings.rb

@@ -23,9 +23,10 @@ module GraphQL
             @bypasses << Report::Bypass.new(path, reason)
           end
 
-          def report
+          def report(reach = nil)
             Report.new(problems: @problems.sort_by { |problem| [problem.path, problem.kind.to_s] },
-                       bypasses: @bypasses.sort_by(&:path))
+                       bypasses: @bypasses.sort_by(&:path),
+                       reach: reach)
           end
         end
       end

data/lib/graphql/armory/authorization/audit/interface_rules.rb

@@ -15,9 +15,12 @@ module GraphQL
           end
 
           def self.audit(interface, definitions, findings)
-            bypassed = Integration.any_bypass?(definitions.select { |type| type.kind.object? && type <= interface })
+            implementers = definitions.select { |type| type.kind.object? && type <= interface }
+            bypassed = Integration.any_bypass?(implementers)
+            covered = implementers.any? { |type| type.respond_to?(:armory_rule) && PlainResolvers.covering?(type.armory_rule) }
             interface.own_fields.values.flatten.each do |field|
               path = "#{interface.graphql_name}.#{field.original_name}"
+              PlainResolvers.report(findings, path, field) if covered && !bypassed && PlainResolvers.open?(field)
               unless field.respond_to?(:armory_declared)
                 findings.problem(:unprotected, path, "its field class does not include Base, so it is not checked on a bypassed implementer") if bypassed
                 next