graphql-armory 0.1.0.pre8 → 0.1.0.pre9

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

@@ -17,9 +17,17 @@ module GraphQL
       class Time
         CONTEXT_KEY = :rate_limit_time
         NAMESPACE = :graphql_armory
+        BUCKET_PREFIX = "time:"
 
-        def self.use(schema, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, clock: Clock.monotonic, extensions: false)
-          build(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, clock: clock, extensions: extensions).install(schema)
+        def self.use(schema, store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, sinks: [], clock: Clock.monotonic, extensions: false)
+          build(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, sinks: sinks, clock: clock, extensions: extensions).install(schema)
+        end
+
+        # Where a client's milliseconds live in the store: apart from its points, so Points and Time can share a store
+        # and a key. Read a balance with this, not with the client's key. In the key's encoding: interpolating a UTF-16
+        # key would raise inside the limiter's rescue, which fails open.
+        def self.bucket_key(key)
+          BUCKET_PREFIX.encode(key.encoding) + key
         end
 
         # HTTP headers for the budget a result recorded: `RateLimit-Time-Limit` and `RateLimit-Time-Remaining` in
@@ -37,13 +45,13 @@ module GraphQL
         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, clock: Clock.monotonic, extensions: false)
-          new(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, clock: clock, extensions: extensions)
+        def self.build(store:, limit:, window: 60, soft: true, key: nil, on_store_error: nil, sinks: [], clock: Clock.monotonic, extensions: false)
+          new(store: store, limit: limit, window: window, soft: soft, key: key, on_store_error: on_store_error, sinks: sinks, clock: clock, 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, clock: Clock.monotonic, extensions: false)
+        def initialize(store: Store::Null.new, limit: 1, window: 60, soft: false, key: nil, on_store_error: nil, sinks: [], clock: Clock.monotonic, 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
@@ -53,7 +61,7 @@ module GraphQL
           @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)
+          @on_store_error = Settings.store_error_handler(on_store_error, limiter: :time, sinks: sinks)
           @clock = Settings.clock(clock)
           now # a clock that answers anything but a finite number fails here, not by charging nothing
           @extensions = Settings.extensions(extensions)
@@ -63,8 +71,21 @@ module GraphQL
         # Adds the analyzer and the trace to the schema.
         def install(schema)
           time = self
-          schema.query_analyzer(Class.new(Analyzer) { define_method(:time) { time } })
+          schema.query_analyzer(Class.new(Analyzer) do
+            define_method(:time) { time }
+            define_singleton_method(:armory_limiter) { time }
+          end)
           schema.trace_with(@trace)
+          schema.trace_with(AnalysisGuard)
+        end
+
+        def soft?
+          @soft
+        end
+
+        # Whether this query's client has no limit to charge.
+        def exempt?(query)
+          Settings.exempt?(@key, @limit, query)
         end
 
         # The refusal for a client with no milliseconds left, or nil to let the operation run (and be charged).
@@ -74,6 +95,8 @@ module GraphQL
           end
 
           key = Settings.key_for(@key, query)
+          return call_several(query, key) if key.is_a?(Array)
+
           limit = Settings.limit_for(@limit, key, query)
           if limit.nil?
             record(query, key: key, limit: nil, remaining: nil, limited: false)
@@ -81,7 +104,7 @@ module GraphQL
           end
 
           answer = begin
-            @store.take(key, cost: 0, limit: limit, window: @window, force: false)
+            @store.take(self.class.bucket_key(key), cost: 0, limit: limit, window: @window, force: false)
           rescue StandardError => error
             # Fail open, and still measure: the charge may find the store back.
             query.context[CONTEXT_KEY] = nil
@@ -135,27 +158,92 @@ module GraphQL
 
         private
 
+        # Each key is charged on its own: a store failure on one, or a hook that raises for it, leaves the others charged. The
+        # first error a hook raises is raised afterwards.
         def charge_one(query, debt, cost)
-          answer = @store.take(debt[:key], cost: cost, limit: debt[:limit], window: @window, force: true)
-          _taken, remaining = Settings.checked(answer, :take, "the Integer milliseconds left")
-          settle(query, debt, cost, remaining)
-        rescue StandardError => error
+          failure = nil
+          charged = (debt[:others] || {}).to_h do |key, limit|
+            [key, charge_key(key, limit, cost)]
+          rescue StandardError => error
+            failure ||= heard(query, error)
+            [key, nil]
+          end
+          begin
+            settle(query, debt, cost, charge_key(debt[:key], debt[:limit], cost), charged)
+          rescue StandardError => error
+            failure ||= heard(query, error)
+          end
+          raise failure if failure
+        end
+
+        def charge_key(key, limit, cost)
+          answer = @store.take(self.class.bucket_key(key), cost: cost, limit: limit, window: @window, force: true)
+          Settings.checked(answer, :take, "the Integer milliseconds left").last
+        end
+
+        # What the hook raised for this error, if it did.
+        def heard(query, error)
           @on_store_error.call(error, query)
+          nil
+        rescue StandardError => raised
+          raised
+        end
+
+        # Reads every balance. A refusal charges none, as with one key; otherwise every key owes the whole time. A key whose
+        # store fails at the read still owes it, and the others still decide.
+        def call_several(query, keys)
+          limits = Settings.limits_for(@limit, keys, query)
+          if limits.empty?
+            record(query, key: keys.first, limit: nil, remaining: nil, limited: false, keys: [])
+            return nil
+          end
+
+          budgets = limits.filter_map do |key, limit|
+            answer = begin
+              @store.take(self.class.bucket_key(key), cost: 0, limit: limit, window: @window, force: false)
+            rescue StandardError => error
+              @on_store_error.call(error, query)
+              next
+            end
+            { key: key, limit: limit, remaining: Settings.checked(answer, :take, "the Integer milliseconds left").last }
+          end
+          if budgets.empty?
+            query.context[CONTEXT_KEY] = nil
+            first, *rest = limits.to_a
+            owe(query, first[0], first[1], others: rest.to_h)
+            return nil
+          end
+
+          limited = budgets.any? { |budget| budget[:remaining].zero? }
+          binding = budgets.select { |budget| budget[:remaining].zero? }.min_by { |budget| budget[:limit] } || budgets.min_by { |budget| budget[:remaining] }
+          info = record(query, key: binding[:key], limit: binding[:limit], remaining: binding[:remaining], limited: limited, keys: budgets)
+          extension = announce(query, info) if @extensions
+          return refusal(binding[:limit]) if limited && !@soft
+
+          owe(query, binding[:key], binding[:limit], info, extension, others: limits.reject { |key, _limit| key == binding[:key] })
+          nil
         end
 
         # What the client has left once the charge is in, in the record and in the extensions announced earlier.
-        def settle(query, debt, cost, remaining)
+        def settle(query, debt, cost, remaining, others = {})
           info = (debt[:info] || base_record(key: debt[:key], limit: debt[:limit], limited: false)).merge(remaining: remaining, elapsed: cost)
+          if info[:keys]
+            current = others.compact.merge(debt[:key] => remaining)
+            info[:keys] = info[:keys].map { |budget| budget.merge(remaining: current.fetch(budget[:key], budget[:remaining])) }
+            # Keys with different limits refill at different rates during the run, so the binding one may have changed.
+            info = info.merge(info[:keys].min_by { |budget| budget[:remaining] })
+            remaining = info[:remaining]
+          end
           query.context.namespace(NAMESPACE)[:time] = info
           query.context[CONTEXT_KEY] = info
-          debt[:extension]&.merge!("remaining" => remaining, "elapsed" => cost, "resetIn" => Points.reset_in(info))
+          debt[:extension]&.merge!("limit" => info[:limit], "remaining" => remaining, "elapsed" => cost, "resetIn" => Points.reset_in(info))
         end
 
         # Per query and per limiter, not in the context hash: queries of a multiplex may share one hash, and a
         # schema may use several limiters.
-        def owe(query, key, limit, info = nil, extension = nil)
+        def owe(query, key, limit, info = nil, extension = nil, others: {})
           charges = (query.context.namespace(NAMESPACE)[:time_charges] ||= {})
-          charges[self] = { key: key, limit: limit, info: info, extension: extension }
+          charges[self] = { key: key, limit: limit, info: info, extension: extension, others: others }
         end
 
         def record(query, **info)
@@ -165,8 +253,8 @@ module GraphQL
         end
 
         # `elapsed` is nil until the operation ends and is charged; it stays nil for a refused one.
-        def base_record(key:, limit:, limited:, remaining: nil)
-          { key: key, limit: limit, remaining: remaining, elapsed: nil, window: @window, soft: @soft, limited: limited }
+        def base_record(key:, limit:, limited:, remaining: nil, keys: nil)
+          { key: key, limit: limit, remaining: remaining, elapsed: nil, window: @window, soft: @soft, limited: limited, **(keys ? { keys: keys } : {}) }
         end
 
         # The budget before the run; the charge completes the same hash, which the response already holds.
@@ -200,7 +288,7 @@ module GraphQL
         # Asks for the balance during analysis, before anything runs.
         class Analyzer < GraphQL::Analysis::Analyzer
           def result
-            time.(query)
+            AnalysisGuard.answer(query, time) { time.(query) }
           end
         end
       end

data/lib/graphql/armory/rate_limits.rb

@@ -9,6 +9,8 @@ module GraphQL
       class ConfigurationError < Armory::Error; end
 
       KEY = :rate_limit_key
+      # Each key costs store round trips on every query, so a list cannot grow with what a client sends.
+      MAX_KEYS = 5
 
       # The settings every limiter shares, checked at boot.
       module Settings
@@ -21,11 +23,28 @@ module GraphQL
           key
         end
 
+        # A String, or a list of them for a query that draws from several buckets.
         def key_for(reader, query)
           key = reader.call(query)
           return key if key.is_a?(String) && !key.empty?
+          return key if several_keys?(key)
 
-          raise ConfigurationError, "no client key for this query: put a non-empty String in context[:#{KEY}], or give the limiter a key: callable"
+          raise ConfigurationError, "no client key for this query: put a non-empty String, or a list of up to #{MAX_KEYS} different ones, in context[:#{KEY}], or give the limiter a key: callable"
+        end
+
+        def exempt?(reader, limit, query)
+          key = key_for(reader, query)
+          key.is_a?(Array) ? limits_for(limit, key, query).empty? : limit_for(limit, key, query).nil?
+        end
+
+        def several_keys?(keys)
+          keys.is_a?(Array) && keys.size.between?(1, MAX_KEYS) && keys.all? { |key| key.is_a?(String) && !key.empty? } && keys.map(&:b).uniq.size == keys.size
+        end
+
+        # The limit of each key, with the keys that have none left out. All of them are asked before any store call, so
+        # a limit that raises leaves nothing charged or held.
+        def limits_for(limit, keys, query)
+          keys.to_h { |key| [key, limit_for(limit, key, query)] }.compact
         end
 
         def soft(value)
@@ -110,11 +129,15 @@ module GraphQL
           value
         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)
+        def store_error_handler(handler, limiter: nil, sinks: [])
+          raise ConfigurationError, "on_store_error: must be a callable that takes the error and the query" unless handler.nil? || handler.respond_to?(:call)
 
-          handler
+          telemetry = Telemetry.build(sinks: sinks)
+          handler ||= ->(error, _query) { warn("graphql-armory rate limit store failed, query let through: #{error.class}") }
+          lambda do |error, query|
+            telemetry.record(:rate_limit_store_failed, context: query.context, limiter: limiter, error: error.class.to_s)
+            handler.call(error, query)
+          end
         end
       end
     end
@@ -125,6 +148,7 @@ require "graphql/armory/rate_limits/memory_store"
 require "graphql/armory/rate_limits/store"
 require "graphql/armory/rate_limits/clock"
 require "graphql/armory/rate_limits/redis_store"
+require "graphql/armory/rate_limits/analysis_guard"
 require "graphql/armory/rate_limits/points"
 require "graphql/armory/rate_limits/concurrency"
 require "graphql/armory/rate_limits/time"

data/lib/graphql/armory/telemetry.rb

@@ -4,16 +4,34 @@ module GraphQL
   module Armory
     # Records what a module decided (a request allowed, an ID refused, an operation run) and hands it to its sinks.
     # A sink is anything that responds to `call(signal, data)`: a lambda that logs, a metrics client, or
-    # `Telemetry::Notifications`. Never put record attributes, IDs, keys or queries in `data`: a client chooses
+    # `Telemetry::Notifications`. A sink that requires a third argument also receives the query's context, to read who
+    # asked from it; the context never goes in `data`. Never put record attributes, IDs, keys or queries in `data`: a client chooses
     # those, and they would end up in the app's logs.
     class Telemetry
       class ConfigurationError < Armory::Error; end
 
-      def self.build(sinks: [])
-        new(sinks: sinks)
+      # The class alone: an error's message may quote what the sink was sending, or its credentials.
+      DEFAULT_ON_SINK_ERROR = ->(error, signal) { warn("graphql-armory sink failed on #{signal}, request continues: #{error.class}") }
+
+      def self.build(sinks: [], on_sink_error: nil)
+        new(sinks: sinks, on_sink_error: on_sink_error)
+      end
+
+      # What a sink reads the context through: it decides nothing, so it cannot change who the query runs as. An object in
+      # the context is the app's own, and stays as it is. `inspect` stays out of it, so a sink that logs its arguments logs no token.
+      class ContextView
+        def initialize(context)
+          @context = context
+        end
+
+        def [](key) = @context[key]
+        def fetch(key, *default, &block) = @context.fetch(key, *default, &block)
+        def dig(key, *rest) = @context.dig(key, *rest)
+        def key?(key) = @context.key?(key)
+        def inspect = "#<#{self.class.name}>"
       end
 
-      def initialize(sinks: [])
+      def initialize(sinks: [], on_sink_error: nil)
         # Messages name a class, never `inspect` a value: a metrics client holds its API key.
         raise ConfigurationError, "sinks: must be an Array of callables taking (signal, data), got #{sinks.class}" unless sinks.is_a?(Array)
 
@@ -24,18 +42,56 @@ module GraphQL
           raise ConfigurationError, "sink #{sink.is_a?(Module) ? sink.name : sink.class} is not available: the library it reports to is not loaded"
         end
 
-        @sinks = sinks.dup.freeze
+        raise ConfigurationError, "on_sink_error: must be a callable taking the error and the signal, found a #{on_sink_error.class}" unless on_sink_error.nil? || on_sink_error.respond_to?(:call)
+
+        @sinks = sinks.map { |sink| [sink, takes_context?(sink)] }.freeze
+        @on_sink_error = on_sink_error || DEFAULT_ON_SINK_ERROR
+      end
+
+      # Whether anything hears what is recorded.
+      def listening?
+        !@sinks.empty?
       end
 
       # Every sink gets the same frozen data, so one sink (or a subscriber) cannot change what the next one sees.
-      def record(signal, **data)
+      def record(signal, context: nil, **data)
         return nil if @sinks.empty?
 
         data = data.to_h { |key, value| [key, value.is_a?(String) ? value.dup.freeze : value] }.freeze
-        @sinks.each { |sink| sink.call(signal, data) }
+        view = ContextView.new(context || {}) if @sinks.any? { |_sink, takes_context| takes_context }
+        @sinks.each do |sink, takes_context|
+          takes_context ? sink.call(signal, data, view) : sink.call(signal, data)
+        rescue StandardError => error
+          @on_sink_error.call(error, signal)
+        end
         nil
       end
 
+      private
+
+      # Only a sink that requires it: one taking `*arguments` or a defaulted third may log whatever it gets. A sink whose
+      # `call` cannot be read (a BasicObject, one behind method_missing) takes two.
+      def takes_context?(sink)
+        callable = Proc === sink || Method === sink ? sink : ::Kernel.instance_method(:method).bind_call(sink, :call)
+        return callable.arity == 3 if Proc === callable && !callable.lambda?
+
+        parameters = callable.parameters
+        refuse_uncallable(sink, parameters)
+        parameters.count { |type, _| type == :req } == 3
+      rescue NameError, TypeError
+        false
+      end
+
+      # It would raise on every signal, and with sinks that no longer fail the request nobody would notice.
+      def refuse_uncallable(sink, parameters)
+        required = parameters.count { |type, _| type == :req }
+        optional = parameters.count { |type, _| type == :opt }
+        rest = parameters.any? { |type, _| type == :rest }
+        return unless required > 3 || parameters.any? { |type, _| type == :keyreq } || (required + optional < 2 && !rest)
+
+        raise ConfigurationError, "sink #{sink.is_a?(Module) ? sink.name : sink.class} must take (signal, data) or (signal, data, context)"
+      end
+
       # Reports every signal as an ActiveSupport::Notifications event named "<signal>.graphql_armory", with the
       # signal's data as payload: `sinks: [GraphQL::Armory::Telemetry::Notifications]`.
       module Notifications
@@ -50,10 +106,11 @@ module GraphQL
 
       # Keeps what was recorded and fails when told, for tests.
       class Substitute
-        attr_reader :recorded
+        attr_reader :recorded, :contexts
 
         def initialize
           @recorded = []
+          @contexts = []
           @failure = nil
         end
 
@@ -66,13 +123,18 @@ module GraphQL
           @failure = nil
         end
 
-        def record(signal, **data)
+        def record(signal, context: nil, **data)
+          @contexts << context
           raise @failure if @failure
 
           @recorded << [signal, data]
           nil
         end
 
+        def listening?
+          true
+        end
+
         def recorded?(signal)
           @recorded.any? { |recorded_signal, _| recorded_signal == signal }
         end

data/lib/graphql/armory/version.rb

@@ -2,6 +2,6 @@
 
 module GraphQL
   module Armory
-    VERSION = "0.1.0.pre8"
+    VERSION = "0.1.0.pre9"
   end
 end

data/lib/graphql/armory.rb

@@ -17,3 +17,4 @@ require "graphql/armory/ids"
 require "graphql/armory/persisted_queries"
 require "graphql/armory/rate_limits"
 require "graphql/armory/keyset"
+require "graphql/armory/railtie" if defined?(::Rails::Railtie)

data/lib/tasks/graphql_armory.rake

@@ -3,9 +3,16 @@
 require "graphql/armory"
 
 namespace :graphql_armory do
-  desc "Lists every type, field and argument of a schema that no authorization rule covers (exit 1 if any)"
-  task :audit, [:schema] => (Rake::Task.task_defined?(:environment) ? [:environment] : []) do |_task, args|
-    status = GraphQL::Armory::Authorization::Audit::Command.new.(args[:schema])
-    exit(status) unless status.zero?
+  # The Railtie loads this before Rails defines :environment, so the action looks it up when it runs. An app may also load this by hand.
+  action = GraphQL::Armory::Authorization::Audit::Command::RAKE_ACTION
+  unless Rake::Task.task_defined?("graphql_armory:audit") && Rake::Task["graphql_armory:audit"].actions.include?(action)
+    desc "Lists every type, field and argument of a schema that no authorization rule covers (exit 1 if any)"
+    task :audit, [:schema, :baseline], &action
+  end
+
+  baseline_action = GraphQL::Armory::Authorization::Audit::Command::BASELINE_ACTION
+  unless Rake::Task.task_defined?("graphql_armory:audit_baseline") && Rake::Task["graphql_armory:audit_baseline"].actions.include?(baseline_action)
+    desc "Writes the audit's problems to a baseline file, or removes from it what is gone; it never adds to a file that exists"
+    task :audit_baseline, [:schema, :baseline], &baseline_action
   end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: graphql-armory
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre8
+  version: 0.1.0.pre9
 platform: ruby
 authors:
 - Israel
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -33,7 +33,8 @@ description: 'Open-source extensions for graphql-ruby built on its public extens
   points. The first module is authorization: deny-by-default coverage, scoped lists
   and connections, IDOR-safe lookups, mutations, interfaces and unions, visibility
   driven by the policy, and a schema audit for CI.'
-executables: []
+executables:
+- graphql-armory-publish
 extensions: []
 extra_rdoc_files: []
 files:
@@ -47,6 +48,7 @@ files:
 - docs/persisted-queries.md
 - docs/rate-limiting.md
 - docs/telemetry.md
+- exe/graphql-armory-publish
 - lib/graphql-armory.rb
 - lib/graphql/armory.rb
 - lib/graphql/armory/authorization.rb
@@ -55,6 +57,7 @@ files:
 - lib/graphql/armory/authorization/adapters/pundit.rb
 - lib/graphql/armory/authorization/adapters/substitute.rb
 - lib/graphql/armory/authorization/audit.rb
+- lib/graphql/armory/authorization/audit/baseline.rb
 - lib/graphql/armory/authorization/audit/command.rb
 - lib/graphql/armory/authorization/audit/denial_hooks.rb
 - lib/graphql/armory/authorization/audit/edge_rules.rb
@@ -64,8 +67,12 @@ files:
 - lib/graphql/armory/authorization/audit/interface_rules.rb
 - lib/graphql/armory/authorization/audit/introspection_fields.rb
 - lib/graphql/armory/authorization/audit/library_methods.rb
+- lib/graphql/armory/authorization/audit/observed_rules.rb
 - lib/graphql/armory/authorization/audit/overrides.rb
 - lib/graphql/armory/authorization/audit/own_checks.rb
+- lib/graphql/armory/authorization/audit/payload_reuse.rb
+- lib/graphql/armory/authorization/audit/plain_resolvers.rb
+- lib/graphql/armory/authorization/audit/reach.rb
 - lib/graphql/armory/authorization/audit/report.rb
 - lib/graphql/armory/authorization/audit/type_rules.rb
 - lib/graphql/armory/authorization/audit/visibility_models.rb
@@ -103,8 +110,13 @@ files:
 - 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/manifests.rb
+- lib/graphql/armory/persisted_queries/publisher.rb
+- lib/graphql/armory/persisted_queries/redis_store.rb
 - lib/graphql/armory/persisted_queries/store.rb
+- lib/graphql/armory/railtie.rb
 - lib/graphql/armory/rate_limits.rb
+- lib/graphql/armory/rate_limits/analysis_guard.rb
 - lib/graphql/armory/rate_limits/clock.rb
 - lib/graphql/armory/rate_limits/concurrency.rb
 - lib/graphql/armory/rate_limits/controls.rb