graphql-armory 0.1.0.pre4 → 0.1.0.pre5

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.pre4"
+    VERSION = "0.1.0.pre5"
   end
 end

data/lib/graphql/armory.rb

@@ -14,3 +14,4 @@ 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.pre4
+  version: 0.1.0.pre5
 platform: ruby
 authors:
 - Israel
@@ -44,6 +44,7 @@ files:
 - 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
@@ -78,10 +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