graphql-armory 0.1.0.pre3 → 0.1.0.pre5

data/lib/graphql/armory/rate_limits/points.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Charges each query its complexity, as graphql-ruby computes it before running it, against a bucket of
+      # points per client that refills over a window:
+      #
+      #   use GraphQL::Armory::RateLimits::Points, store: GraphQL::Armory::RateLimits::MemoryStore.new,
+      #     limit: 1_000, window: 60, soft: false
+      #
+      # A query that costs more than the client has left is refused before any field resolves, and charged
+      # nothing. Soft mode (the default) charges and records but refuses nothing. What happened is in
+      # `context[:rate_limit_points]`.
+      class Points
+        CONTEXT_KEY = :rate_limit_points
+        NAMESPACE = :graphql_armory
+
+        def self.use(schema, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, extensions: false)
+          points = build(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, extensions: extensions)
+          schema.query_analyzer(Class.new(Analyzer) { define_method(:points) { points } })
+        end
+
+        # HTTP headers for the budget a result recorded: `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`
+        # (seconds until the bucket is full again). Empty when the query had no limit.
+        def self.headers(result)
+          info = result.context.namespace(NAMESPACE)[:points]
+          return {} unless info && info[:limit]
+
+          { "RateLimit-Limit" => info[:limit].to_s, "RateLimit-Remaining" => info[:remaining].to_s, "RateLimit-Reset" => reset_in(info).to_s }
+        end
+
+        def self.reset_in(info)
+          ((info[:limit] - info[:remaining]) * info[:window] / info[:limit].to_f).ceil
+        end
+
+        # Wires the app's store with `use`'s defaults (soft mode); `use` goes through here.
+        def self.build(store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, extensions: false)
+          new(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, extensions: extensions)
+        end
+
+        # `new` is inert: with no store wired it refuses every query. It checks every setting, so no partial
+        # configuration lets a query through either.
+        def initialize(store: Store::Null.new, limit: 1, window: 60, soft: false, key: nil, on_store_error: nil, extensions: false)
+          unless Settings.store_answers?(store, take: %i[cost limit window force])
+            raise ConfigurationError, "store: must answer take(key, cost:, limit:, window:, force:), like a MemoryStore"
+          end
+          raise ConfigurationError, "extensions: must be true or false, got #{extensions.inspect}" unless extensions == true || extensions == false
+
+          @store = store
+          @limit = Settings.wired_limit(limit, store)
+          @window = Settings.seconds(:window, window)
+          @soft = Settings.wired_soft(soft, store)
+          @key = Settings.key_reader(key)
+          @on_store_error = Settings.store_error_handler(on_store_error)
+          @extensions = extensions
+        end
+
+        # The refusal for a query that costs `cost`, or nil to let it run.
+        def call(query, cost)
+          key = Settings.key_for(@key, query)
+          limit = Settings.limit_for(@limit, key, query)
+          if limit.nil?
+            record(query, key: key, cost: cost, limit: nil, remaining: nil, limited: false)
+            return nil
+          end
+
+          answer = begin
+            @store.take(key, cost: cost, limit: limit, window: @window, force: @soft)
+          rescue StandardError => error
+            # No record: a context hash shared with an earlier query must not keep its numbers.
+            query.context[CONTEXT_KEY] = nil
+            @on_store_error.call(error, query)
+            return nil
+          end
+          taken, remaining = Settings.checked(answer, :take, "the Integer points left")
+
+          info = record(query, key: key, cost: cost, limit: limit, remaining: remaining, limited: !taken)
+          if @extensions
+            query.context.response_extensions["rateLimit"] =
+              { "cost" => cost, "limit" => limit, "remaining" => remaining, "resetIn" => self.class.reset_in(info) }
+          end
+          refusal(cost, limit, remaining) unless taken || @soft
+        end
+
+        private
+
+        # In the context hash for instrumentation, and per query for `headers`: queries of a multiplex may share one
+        # context hash, where the last query's record wins.
+        def record(query, **info)
+          info = { **info.slice(:key, :cost, :limit, :remaining), window: @window, soft: @soft, limited: info[:limited] }
+          query.context.namespace(NAMESPACE)[:points] = info
+          query.context[CONTEXT_KEY] = info
+        end
+
+        def refusal(cost, limit, remaining)
+          if cost > limit
+            return GraphQL::AnalysisError.new(
+              "Rate limit exceeded: this query costs #{cost} points and the limit is #{limit} every #{@window} seconds, so it can never run.",
+              extensions: { "code" => "RATE_LIMITED", "cost" => cost, "limit" => limit }
+            )
+          end
+
+          retry_after = ((cost - remaining) * @window / limit.to_f).ceil
+          GraphQL::AnalysisError.new(
+            "Rate limit exceeded: this query costs #{cost} points and #{remaining} remain (#{limit} every #{@window} seconds). Retry in #{retry_after} seconds.",
+            extensions: { "code" => "RATE_LIMITED", "cost" => cost, "remaining" => remaining, "retryAfter" => retry_after }
+          )
+        end
+
+        # graphql-ruby's own complexity analysis, then the charge.
+        class Analyzer < GraphQL::Analysis::QueryComplexity
+          def result
+            cost = super
+            unless cost.is_a?(Numeric) && cost.finite? && !cost.negative?
+              raise ConfigurationError, "the query complexity is #{cost.inspect}: field complexities must be numbers of zero or more"
+            end
+
+            # Fractional complexities (`complexity: 0.5`) are charged whole points, rounded up.
+            points.(query, cost.ceil)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/rate_limits/redis_store.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Buckets and slots kept in Redis, shared by every process of the app: the store for production.
+      #
+      #   store = GraphQL::Armory::RateLimits::RedisStore.new(redis: Redis.new(url: ENV.fetch("REDIS_URL")))
+      #
+      # Each change is one Lua script, so concurrent requests never race, and the time comes from Redis's own clock,
+      # so processes on different machines agree on it. Keys live under `prefix` and expire once they no longer
+      # matter. `redis:` is a redis-rb client (>= 4.8), or anything answering `eval` and `evalsha` the same way;
+      # its errors reach the limiters, which let the query through and call `on_store_error`. This gem does not
+      # depend on the redis gem: the app adds it.
+      class RedisStore
+        DEFAULT_PREFIX = "graphql-armory:rate-limits:"
+
+        # The time in seconds: the one given by the caller (tests), or Redis's own clock.
+        CLOCK = <<~LUA
+          local function clock(given)
+            if given ~= "" then return tonumber(given) end
+            local time = redis.call("TIME")
+            return tonumber(time[1]) + tonumber(time[2]) / 1000000
+          end
+        LUA
+
+        # Same token bucket as MemoryStore#take. The bucket expires once a whole window has passed: it is full
+        # again by then, the same as no bucket at all. An expiry is only ever pushed later, never brought closer, so
+        # a limiter with a shorter window sharing the key cannot cut it short. The points left go back as a string:
+        # Redis would truncate a Lua number past 2**63. A bucket whose fields are not numbers is an error, so the
+        # limiter calls on_store_error instead of reading it as full.
+        TAKE = <<~LUA
+          #{CLOCK}
+          local cost, limit, window = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])
+          local force, now = ARGV[4] == "1", clock(ARGV[5])
+          local state = redis.call("HMGET", KEYS[1], "level", "at")
+          local level, at = tonumber(state[1]), tonumber(state[2])
+          if not (state[1] or state[2]) then
+            level, at = limit, now
+          elseif not (level and at) or level ~= level or at ~= at or level < 0 or level == math.huge or math.abs(at) == math.huge then
+            return redis.error_reply("graphql-armory: corrupt rate limit bucket at " .. KEYS[1])
+          end
+          level = math.min(level + math.max(now - at, 0) * limit / window, limit)
+
+          local taken = cost <= level
+          if taken or force then level = math.max(level - cost, 0) end
+          redis.call("HSET", KEYS[1], "level", string.format("%.17g", level), "at", string.format("%.17g", math.max(now, at)))
+          local keep = math.ceil(window * 1000) + 1000
+          if redis.call("PTTL", KEYS[1]) < keep then redis.call("PEXPIRE", KEYS[1], keep) end
+
+          return { taken and 1 or 0, string.format("%.0f", math.floor(level)) }
+        LUA
+
+        # Same slots as MemoryStore#acquire: a sorted set of tokens scored by when they expire. The key lives as long
+        # as its latest slot, whatever ttl each acquire passed.
+        ACQUIRE = <<~LUA
+          #{CLOCK}
+          local token, limit, ttl = ARGV[1], tonumber(ARGV[2]), tonumber(ARGV[3])
+          local force, now = ARGV[4] == "1", clock(ARGV[5])
+          redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", string.format("%.17g", now))
+
+          local acquired = redis.call("ZCARD", KEYS[1]) < limit
+          if acquired or force then
+            redis.call("ZADD", KEYS[1], string.format("%.17g", now + ttl), token)
+            local latest = tonumber(redis.call("ZRANGE", KEYS[1], -1, -1, "WITHSCORES")[2])
+            redis.call("PEXPIRE", KEYS[1], math.ceil((latest - now) * 1000) + 1000)
+          end
+
+          return { acquired and 1 or 0, redis.call("ZCARD", KEYS[1]) }
+        LUA
+
+        RELEASE = <<~LUA
+          return redis.call("ZREM", KEYS[1], ARGV[1])
+        LUA
+
+        def initialize(redis:, prefix: DEFAULT_PREFIX, clock: nil)
+          unless redis.respond_to?(:eval) && redis.respond_to?(:evalsha)
+            raise ConfigurationError, "redis: must be a Redis client that runs scripts (eval and evalsha), like Redis.new from the redis gem"
+          end
+          raise ConfigurationError, "prefix: must be a non-empty String, got #{prefix.inspect}" unless prefix.is_a?(String) && !prefix.empty?
+          raise ConfigurationError, "clock: must be nil (Redis's clock) or answer call with the time in seconds" unless clock.nil? || clock.respond_to?(:call)
+
+          @redis = redis
+          @prefix = prefix
+          @clock = clock
+        end
+
+        def take(key, cost:, limit:, window:, force: false)
+          taken, level = script(TAKE, "#{@prefix}points:#{key}", cost, limit, seconds(window), flag(force), now)
+          [taken == 1, Integer(level, 10)]
+        end
+
+        def acquire(key, token:, limit:, ttl:, force: false)
+          acquired, held = script(ACQUIRE, "#{@prefix}slots:#{key}", token, limit, seconds(ttl), flag(force), now)
+          [acquired == 1, held]
+        end
+
+        def release(key, token:)
+          script(RELEASE, "#{@prefix}slots:#{key}", token)
+          nil
+        end
+
+        private
+
+        def flag(value)
+          value ? "1" : "0"
+        end
+
+        # Lua reads decimal numbers only: not "1/2" (a Rational) nor a Time.
+        def seconds(value)
+          Float(value).to_s
+        end
+
+        def now
+          @clock ? seconds(@clock.call.to_f) : ""
+        end
+
+        # EVALSHA sends only the script's digest; Redis forgets scripts on restart or SCRIPT FLUSH, and then EVAL
+        # sends it whole once more.
+        def script(source, key, *argv)
+          argv = argv.map(&:to_s)
+          @redis.evalsha(Digest::SHA1.hexdigest(source), keys: [key], argv: argv)
+        rescue StandardError => error
+          raise unless error.message.start_with?("NOSCRIPT")
+
+          @redis.eval(source, keys: [key], argv: argv)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # What a limiter keeps its state in: `MemoryStore`, `RedisStore`, or any object answering the same methods.
+      # `Null` and `Substitute` are the inert and the test stand-ins.
+      module Store
+        # The store of a limiter nobody wired: it refuses every charge and slot, so `Points.new` and
+        # `Concurrency.new` never let a query through.
+        class Null
+          def take(_key, cost:, limit:, window:, force: false)
+            [false, 0]
+          end
+
+          def acquire(_key, token:, limit:, ttl:, force: false)
+            [false, 0]
+          end
+
+          def release(_key, token:)
+            nil
+          end
+        end
+
+        # A MemoryStore on a clock the test moves (`now`), that records its calls, fails when told and answers what
+        # it is told: for tests, instead of hand-written fakes.
+        class Substitute
+          attr_accessor :now
+          attr_reader :calls
+
+          def initialize(now: 0.0)
+            @now = now
+            @memory = MemoryStore.new(clock: -> { @now })
+            @calls = []
+            @failures = {}
+            @answers = {}
+          end
+
+          # Raises `error` from `on` (:take, :acquire, :release, or :all) for the next `times` calls, or every call.
+          def fail_with(error, on: :all, times: nil)
+            raise ArgumentError, "on: must be :take, :acquire, :release or :all, got #{on.inspect}" unless %i[take acquire release all].include?(on)
+            raise ArgumentError, "times: must be nil (every call) or a positive Integer, got #{times.inspect}" unless times.nil? || (times.is_a?(Integer) && times.positive?)
+
+            @failures[on] = [error, times]
+          end
+
+          def recover
+            @failures.clear
+          end
+
+          # Answers `value` from `method` instead of the real answer, for answers no real store gives.
+          def answer(method, value)
+            @answers[method] = value
+          end
+
+          # Holds a slot for an operation running elsewhere. Not recorded in `calls`.
+          def occupy(key, token: SecureRandom.hex(8), ttl: 60)
+            @memory.acquire(key, token: token, limit: 1, ttl: ttl, force: true)
+            token
+          end
+
+          # The slots held for `key` now. Not recorded in `calls`.
+          def held(key)
+            probe = SecureRandom.hex(8)
+            held = @memory.acquire(key, token: probe, limit: 1, ttl: 1, force: true).last - 1
+            @memory.release(key, token: probe)
+            held
+          end
+
+          def take(key, cost:, limit:, window:, force: false)
+            perform(:take, key, cost: cost, limit: limit, window: window, force: force) do
+              @memory.take(key, cost: cost, limit: limit, window: window, force: force)
+            end
+          end
+
+          def acquire(key, token:, limit:, ttl:, force: false)
+            perform(:acquire, key, token: token, limit: limit, ttl: ttl, force: force) do
+              @memory.acquire(key, token: token, limit: limit, ttl: ttl, force: force)
+            end
+          end
+
+          def release(key, token:)
+            perform(:release, key, token: token) { @memory.release(key, token: token) }
+            nil
+          end
+
+          private
+
+          def perform(method, key, **arguments)
+            @calls << [method, key, arguments]
+            fail!(method)
+            return @answers[method] if @answers.key?(method)
+
+            yield
+          end
+
+          def fail!(method)
+            on = @failures.key?(method) ? method : :all
+            error, times = @failures[on]
+            return unless error
+
+            if times
+              times -= 1
+              times.zero? ? @failures.delete(on) : @failures[on] = [error, times]
+            end
+            raise error
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graphql/armory/rate_limits.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    # Rate limits built for GraphQL, where requests differ wildly in cost. Each client is named by
+    # `context[:rate_limit_key]` (or a `key:` callable) and limited through a store: `MemoryStore` for tests and
+    # a single process, a shared store for several processes.
+    module RateLimits
+      class ConfigurationError < Armory::Error; end
+
+      KEY = :rate_limit_key
+
+      # The settings every limiter shares, checked at boot.
+      module Settings
+        module_function
+
+        def key_reader(key)
+          return ->(query) { query.context[KEY] } if key.nil?
+          raise ConfigurationError, "key: must be a callable that takes the query, got #{key.inspect}" unless key.respond_to?(:call)
+
+          key
+        end
+
+        def key_for(reader, query)
+          key = reader.call(query)
+          return key if key.is_a?(String) && !key.empty?
+
+          raise ConfigurationError, "no client key for this query: put a non-empty String in context[:#{KEY}], or give the limiter a key: callable"
+        end
+
+        def soft(value)
+          raise ConfigurationError, "soft: must be true or false, got #{value.inspect}" unless value == true || value == false
+
+          value
+        end
+
+        # A limit callable may answer nil (no limit for that key), so on the Null store it could let queries through.
+        def wired_limit(value, store)
+          limit(value)
+          raise ConfigurationError, "a limit: callable needs a store: on the Null store a nil answer would let queries run unlimited" if value.respond_to?(:call) && store.is_a?(Store::Null)
+
+          value
+        end
+
+        # Soft mode counts but never refuses, so on the Null store it would let everything through uncounted.
+        def wired_soft(value, store)
+          soft(value)
+          raise ConfigurationError, "soft: true needs a store: the Null store counts nothing, so every query would run unlimited" if value && store.is_a?(Store::Null)
+
+          value
+        end
+
+        def limit(limit)
+          return limit if limit.respond_to?(:call) || positive_integer?(limit)
+
+          raise ConfigurationError, "limit: must be a positive Integer, or a callable taking the key and the query, got #{limit.inspect}"
+        end
+
+        def limit_for(limit, key, query)
+          return limit unless limit.respond_to?(:call)
+
+          answer = limit.call(key, query)
+          return answer if answer.nil? || positive_integer?(answer)
+
+          raise ConfigurationError, "limit: answered #{answer.inspect} for #{key}: it must answer a positive Integer, or nil for no limit"
+        end
+
+        def positive_integer?(value)
+          value.is_a?(Integer) && value.positive?
+        end
+
+        def seconds(name, value)
+          return value if value.is_a?(Numeric) && value.positive? && value.finite?
+
+          raise ConfigurationError, "#{name}: must be a positive number of seconds, got #{value.inspect}"
+        end
+
+        # Whether `store` answers each method with the keywords this gem passes, so a wrong signature fails at
+        # boot instead of failing open on every query.
+        def store_answers?(store, methods)
+          methods.all? do |name, keywords|
+            next false unless store.respond_to?(name)
+
+            parameters = store.method(name).parameters
+            next false unless parameters.any? { |type, _| %i[req opt rest].include?(type) } # the key
+            next true if parameters.any? { |type, _| type == :keyrest }
+
+            (keywords - parameters.select { |type, _| type == :key || type == :keyreq }.map(&:last)).empty?
+          end
+        end
+
+        # A store answer that is not [true or false, a whole number] would let queries through: 0 is truthy.
+        def checked(answer, method, meaning)
+          granted, count = answer if answer.is_a?(Array) && answer.size == 2
+          return answer if (granted == true || granted == false) && count.is_a?(Integer) && !count.negative?
+
+          raise ConfigurationError, "store: #{method} answered #{answer.inspect}: it must answer [true or false, #{meaning}]"
+        end
+
+        def store_error_handler(handler)
+          return ->(error, _query) { warn("graphql-armory rate limit store failed, query let through: #{error.class}: #{error.message}") } if handler.nil?
+          raise ConfigurationError, "on_store_error: must be a callable that takes the error and the query" unless handler.respond_to?(:call)
+
+          handler
+        end
+      end
+    end
+  end
+end
+
+require "graphql/armory/rate_limits/memory_store"
+require "graphql/armory/rate_limits/store"
+require "graphql/armory/rate_limits/redis_store"
+require "graphql/armory/rate_limits/points"
+require "graphql/armory/rate_limits/concurrency"
+require "graphql/armory/rate_limits/controls"

data/lib/graphql/armory/version.rb

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

data/lib/graphql/armory.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphql-armory
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre3
+  version: 0.1.0.pre5
 platform: ruby
 authors:
 - Israel
@@ -43,6 +43,8 @@ files:
 - README.md
 - docs/authorization.md
 - docs/encrypted-ids.md
+- docs/persisted-queries.md
+- docs/rate-limiting.md
 - lib/graphql-armory.rb
 - lib/graphql/armory.rb
 - lib/graphql/armory/authorization.rb
@@ -77,8 +79,22 @@ files:
 - lib/graphql/armory/encoder.rb
 - lib/graphql/armory/encoder/default.rb
 - lib/graphql/armory/encoder/legacy.rb
+- lib/graphql/armory/encoder/null.rb
+- lib/graphql/armory/encoder/substitute.rb
 - lib/graphql/armory/encoder/versioned.rb
 - lib/graphql/armory/ids.rb
+- lib/graphql/armory/ids/controls.rb
+- lib/graphql/armory/persisted_queries.rb
+- lib/graphql/armory/persisted_queries/controls.rb
+- lib/graphql/armory/persisted_queries/manifest.rb
+- lib/graphql/armory/persisted_queries/store.rb
+- lib/graphql/armory/rate_limits.rb
+- lib/graphql/armory/rate_limits/concurrency.rb
+- lib/graphql/armory/rate_limits/controls.rb
+- lib/graphql/armory/rate_limits/memory_store.rb
+- lib/graphql/armory/rate_limits/points.rb
+- lib/graphql/armory/rate_limits/redis_store.rb
+- lib/graphql/armory/rate_limits/store.rb
 - lib/graphql/armory/version.rb
 - lib/tasks/graphql_armory.rake
 homepage: https://github.com/israelb/graphql-armory