graphql-armory 0.1.0.pre3 → 0.1.0.pre5

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

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

data/lib/graphql/armory/ids.rb

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

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

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

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

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module GraphQL
+  module Armory
+    module PersistedQueries
+      # The operations a client build produced, loaded from Apollo's persisted query manifest or Relay's
+      # persisted output. Every id must be the digest of its query, so an edited manifest cannot put another
+      # query behind an id; every query is parsed once, here. Any problem raises at boot, and no message
+      # quotes the manifest's values: they may hold query text.
+      class Manifest
+        DIGESTS = { sha256: Digest::SHA256, sha1: Digest::SHA1, md5: Digest::MD5 }.freeze
+        APOLLO_FORMAT = "apollo-persisted-query-manifest"
+        ID_LIKE = /\A[A-Za-z0-9_.:-]{1,128}\z/
+
+        Operation = Struct.new(:id, :name, :body, :document, keyword_init: true)
+
+        def self.load(path, digest: :sha256)
+          data = begin
+            JSON.parse(File.read(path, mode: "r:bom|utf-8"))
+          rescue JSON::ParserError
+            # Not the parser's message: it quotes the file's content.
+            raise ConfigurationError, "#{path} is not valid JSON"
+          rescue SystemCallError => error
+            raise ConfigurationError, "#{path} cannot be read (#{error.class})"
+          end
+          new(data, digest: digest)
+        end
+
+        # `digest:` is how ids were made: :sha256 (Apollo), :md5 or :sha1 (Relay's options), or false for ids
+        # that are not digests (then nothing proves an id belongs to its query).
+        def initialize(data, digest: :sha256)
+          unless digest == false || DIGESTS.key?(digest)
+            raise ConfigurationError, "unknown digest #{digest.inspect}: use #{DIGESTS.keys.map(&:inspect).join(", ")} or false"
+          end
+
+          @digest = digest && DIGESTS.fetch(digest)
+          @operations = entries(data).each_with_index.with_object({}) do |((id, name, body), index), operations|
+            operation = operation(index, id, name, body)
+            raise ConfigurationError, "operation #{label(index, id)} appears twice in the manifest" if operations.key?(id)
+
+            operations[id] = operation
+          end.freeze
+          raise ConfigurationError, "the manifest holds no operations: is it the right file?" if @operations.empty?
+        end
+
+        def fetch(id)
+          @operations[id]
+        end
+
+        def size
+          @operations.size
+        end
+
+        private
+
+        # [id, name, body] triples from either format. A Relay map may have an operation keyed "format", so a
+        # Hash is Apollo's when its format says so, or when it has both "format" and "operations".
+        def entries(data)
+          raise ConfigurationError, unknown_format unless data.is_a?(Hash)
+          return apollo_entries(data) if data["format"] == APOLLO_FORMAT || (data.key?("format") && data.key?("operations"))
+
+          data.map { |id, body| [id, nil, body] }
+        end
+
+        def apollo_entries(data)
+          raise ConfigurationError, "unknown manifest format: expected #{APOLLO_FORMAT}" unless data["format"] == APOLLO_FORMAT
+          raise ConfigurationError, "unsupported manifest version: expected 1" unless data["version"].eql?(1)
+          raise ConfigurationError, "the manifest's operations must be an array" unless data["operations"].is_a?(Array)
+
+          data["operations"].each_with_index.map do |entry, index|
+            raise ConfigurationError, "manifest entry #{index} is not an object" unless entry.is_a?(Hash)
+
+            entry.values_at("id", "name", "body")
+          end
+        end
+
+        def operation(index, id, name, body)
+          unless id.is_a?(String) && body.is_a?(String) && (name.nil? || name.is_a?(String))
+            raise ConfigurationError, "manifest entry #{index} needs a String id, a String body and a String name or none"
+          end
+          if @digest && @digest.hexdigest(body) != id
+            raise ConfigurationError, "operation #{label(index, id)} is not the digest of its query: the manifest was edited, or `digest:` is wrong"
+          end
+
+          # Copies, so neither the caller's data nor a fetched operation can change what a later fetch returns.
+          Operation.new(id: id.dup.freeze, name: name&.dup&.freeze, body: body.dup.freeze, document: parse(label(index, id), body)).freeze
+        end
+
+        def parse(label, body)
+          GraphQL.parse(body)
+        rescue GraphQL::ParseError
+          raise ConfigurationError, "operation #{label} does not parse"
+        end
+
+        # The id names the operation in errors only when it looks like an id; otherwise it may be query text.
+        def label(index, id)
+          id.match?(ID_LIKE) ? id : "at entry #{index}"
+        end
+
+        def unknown_format
+          "unknown manifest format: expected Apollo's persisted query manifest or Relay's persisted output"
+        end
+      end
+    end
+  end
+end

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

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

data/lib/graphql/armory/persisted_queries.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "json"
+
+module GraphQL
+  module Armory
+    # Persisted queries: clients send the id of an operation their build produced, and the server runs the
+    # stored query. With strict mode on, it refuses queries it does not hold.
+    #
+    #   class AppSchema < GraphQL::Schema
+    #     use GraphQL::Armory::PersistedQueries, store: Manifest.load("persisted-queries.json"), strict: true
+    #   end
+    #
+    #   AppSchema.execute(params[:query], context: { operation_id: PersistedQueries.operation_id(params) })
+    #
+    # Hooks only `Schema.query_class`: the stored document goes to the query as `document:`, so it is parsed once,
+    # at boot, and runs the same on both engines.
+    module PersistedQueries
+      class ConfigurationError < Armory::Error; end
+
+      UNKNOWN_OPERATION = "Unknown operation id"
+      MISMATCH = "The operation id and the query do not match"
+      RAW_QUERY_REFUSED = "Only persisted operations are allowed: send an operation id"
+
+      # What a refused request holds: nothing to run.
+      EMPTY_DOCUMENT = GraphQL::Language::Nodes::Document.new(definitions: [])
+
+      # Validates nothing and answers the refusal, through the query's public `static_validator:` option.
+      class Refusal < GraphQL::StaticValidation::Validator
+        def initialize(schema, message)
+          super(schema: schema)
+          @message = message
+        end
+
+        def validate(_query, **)
+          { errors: [GraphQL::StaticValidation::Error.new(@message)], remaining_timeout: nil }
+        end
+      end
+
+      # `store:` answers `fetch(id)` with an operation (`body` and `document`) or nil: a Manifest, or your own.
+      # `strict: true` refuses raw queries unless the context holds `armory_allow_raw_query: true`.
+      def self.use(schema, store:, strict: false)
+        gate = Gate.build(store: store, strict: strict)
+
+        if schema.singleton_class.include?(Guard)
+          raise ConfigurationError, "#{schema} already uses PersistedQueries (here or in a parent schema): use it once"
+        end
+
+        schema.instance_variable_set(:@armory_persisted_queries, gate)
+        schema.singleton_class.prepend(Guard)
+        schema.query_class(schema.query_class)
+      end
+
+      # Decides what a request runs: answers `[refusal, document]`, where a refusal is the error message, a
+      # document is the stored operation to run instead of the request's text, and `[nil, nil]` runs the request
+      # as it came.
+      class Gate
+        # Wires the app's store with `use`'s defaults; `use` goes through here.
+        def self.build(store:, strict: false)
+          new(store: store, strict: strict)
+        end
+
+        # `new` is inert: with no store wired it refuses every request. It checks what it is given, so it never
+        # lets raw queries through without a store either.
+        def initialize(store: Store::Null.new, strict: true)
+          if store.is_a?(Hash) || !store.respond_to?(:fetch)
+            raise ConfigurationError, "store: must answer fetch(id) with an operation or nil, like a Manifest"
+          end
+          raise ConfigurationError, "strict: must be true or false, got #{strict.inspect}" unless strict == true || strict == false
+          raise ConfigurationError, "strict: false needs a store: with the Null store only raw queries would run" if !strict && store.is_a?(Store::Null)
+
+          @store = store
+          @strict = strict
+        end
+
+        def call(context, text, document)
+          operation_id = context[:operation_id] if context.respond_to?(:[])
+
+          if !operation_id.nil?
+            operation = operation_id.is_a?(String) ? @store.fetch(operation_id) : nil
+            if operation.nil?
+              [UNKNOWN_OPERATION, nil]
+            elsif document || (text && !same_query?(text, operation))
+              [MISMATCH, nil]
+            else
+              [nil, operation.document]
+            end
+          elsif @strict && !(context.respond_to?(:[]) && context[:armory_allow_raw_query] == true)
+            [RAW_QUERY_REFUSED, nil]
+          else
+            [nil, nil]
+          end
+        end
+
+        private
+
+        # Apollo's clients may send the query with its id; graphql-ruby's subscriptions resend it printed.
+        def same_query?(text, operation)
+          text == operation.body || text == operation.document.to_query_string
+        end
+      end
+
+      # Keeps the lookup in every query class the schema uses, including one set after `use` or by a child schema.
+      module Guard
+        UNSET = Object.new.freeze
+
+        def query_class(new_query_class = UNSET)
+          return super() if UNSET.equal?(new_query_class)
+          return super(new_query_class) if new_query_class.include?(Lookup)
+
+          super(Class.new(new_query_class) { include Lookup })
+        end
+
+        def armory_persisted_queries
+          @armory_persisted_queries || superclass.armory_persisted_queries
+        end
+      end
+
+      # The operation id a request sent, from Rack or Rails params: `operationId`, `extensions.operationId` or
+      # Apollo's `extensions.persistedQuery.sha256Hash` (`extensions` may arrive as a JSON string on GET).
+      # Answers nil when there is none, or when it is not a non-empty String.
+      def self.operation_id(params)
+        params = plain(params)
+        extensions = params["extensions"]
+        extensions = parse_json(extensions) if extensions.is_a?(String)
+        extensions = plain(extensions)
+        persisted_query = plain(extensions["persistedQuery"])
+
+        [params["operationId"], extensions["operationId"], persisted_query["sha256Hash"]].find do |candidate|
+          candidate.is_a?(String) && !candidate.empty?
+        end
+      end
+
+      def self.plain(value)
+        value = value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+        value.is_a?(Hash) ? value : {}
+      end
+      private_class_method :plain
+
+      def self.parse_json(text)
+        JSON.parse(text)
+      rescue JSON::ParserError
+        nil
+      end
+      private_class_method :parse_json
+
+      # Swaps the request's query for the stored document, or for nothing with an error when it is refused.
+      module Lookup
+        def initialize(schema, query_string = nil, **options)
+          text = query_string || options[:query]
+          text = nil if text == ""
+          refusal, document = schema.armory_persisted_queries.(options[:context], text, options[:document])
+
+          return super if refusal.nil? && document.nil?
+          return super(schema, nil, **options, query: nil, document: document) if refusal.nil?
+
+          # A refused request fails validation with the refusal as its only error, so neither engine runs it. Its
+          # text is never parsed; a document the app built itself is kept, for `Schema.validate`, which validates it
+          # with its own validator.
+          super(schema, nil, **options, query: nil, document: options[:document] || EMPTY_DOCUMENT, validate: true, static_validator: Refusal.new(schema, refusal))
+        end
+      end
+    end
+  end
+end
+
+require "graphql/armory/persisted_queries/manifest"
+require "graphql/armory/persisted_queries/store"
+require "graphql/armory/persisted_queries/controls"

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Lets each client run at most `limit` operations at the same time:
+      #
+      #   use GraphQL::Armory::RateLimits::Concurrency, store: GraphQL::Armory::RateLimits::MemoryStore.new,
+      #     limit: 5, soft: false
+      #
+      # A query analyzer takes a slot before the operation runs, or refuses it before any field resolves; a trace
+      # releases every slot its multiplex took when the multiplex ends, even when it raises. A slot a crashed
+      # process never released expires after `stale_after` seconds. Soft mode (the default) records but refuses
+      # nothing. What happened is in `context[:rate_limit_concurrency]`.
+      class Concurrency
+        CONTEXT_KEY = :rate_limit_concurrency
+        NAMESPACE = :graphql_armory
+
+        def self.use(schema, store:, limit:, stale_after: 60, soft: true, key: nil, on_store_error: nil)
+          concurrency = build(store: store, limit: limit, stale_after: stale_after, soft: soft, key: key, on_store_error: on_store_error)
+          schema.query_analyzer(Class.new(Analyzer) { define_method(:concurrency) { concurrency } })
+          schema.trace_with(Release)
+        end
+
+        # Wires the app's store with `use`'s defaults (soft mode); `use` goes through here.
+        def self.build(store:, limit:, stale_after: 60, soft: true, key: nil, on_store_error: nil)
+          new(store: store, limit: limit, stale_after: stale_after, soft: soft, key: key, on_store_error: on_store_error)
+        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, stale_after: 60, soft: false, key: nil, on_store_error: nil)
+          unless Settings.store_answers?(store, acquire: %i[token limit ttl force], release: %i[token])
+            raise ConfigurationError, "store: must answer acquire(key, token:, limit:, ttl:, force:) and release(key, token:), like a MemoryStore"
+          end
+
+          @store = store
+          @limit = Settings.wired_limit(limit, store)
+          @stale_after = Settings.seconds(:stale_after, stale_after)
+          @soft = Settings.wired_soft(soft, store)
+          @key = Settings.key_reader(key)
+          @on_store_error = Settings.store_error_handler(on_store_error)
+        end
+
+        # Takes a slot for the query: the refusal when none is free, or nil to let it run.
+        def call(query)
+          unless query.current_trace.is_a?(Release)
+            raise ConfigurationError, "this query runs with its own trace (context[:trace]), so Concurrency could never release its slot: remove context[:trace] or add trace_with to that trace"
+          end
+
+          key = Settings.key_for(@key, query)
+          limit = Settings.limit_for(@limit, key, query)
+          if limit.nil?
+            record(query, key: key, limit: nil, active: nil, limited: false)
+            return nil
+          end
+
+          token = SecureRandom.hex(16)
+          answer = begin
+            @store.acquire(key, token: token, limit: limit, ttl: @stale_after, force: @soft)
+          rescue StandardError => error
+            @on_store_error.call(error, query)
+            return nil
+          end
+          acquired, active = Settings.checked(answer, :acquire, "the Integer slots held")
+
+          # Per query, not in the context hash: queries of a multiplex may share one hash.
+          query.context.namespace(NAMESPACE)[:concurrency_slot] = [self, key, token] if acquired || @soft
+          record(query, key: key, limit: limit, active: active, limited: !acquired)
+          refusal(limit, active) unless acquired || @soft
+        end
+
+        def release(query, key, token)
+          @store.release(key, token: token)
+        rescue StandardError => error
+          @on_store_error.call(error, query)
+        end
+
+        private
+
+        def record(query, **info)
+          query.context[CONTEXT_KEY] = { **info.slice(:key, :limit, :active), soft: @soft, limited: info[:limited] }
+        end
+
+        def refusal(limit, active)
+          GraphQL::AnalysisError.new(
+            "Too many operations at the same time: #{active} are already running for this client (limit #{limit}). Retry when one finishes.",
+            extensions: { "code" => "RATE_LIMITED", "limit" => limit, "active" => active }
+          )
+        end
+
+        # Takes the slot during analysis, before anything runs.
+        class Analyzer < GraphQL::Analysis::Analyzer
+          def result
+            concurrency.(query)
+          end
+        end
+
+        # Releases the slots of every query in the multiplex once it is done, whatever happened. Analysis runs
+        # inside `execute_multiplex` on both engines, so every slot taken is released here.
+        module Release
+          def execute_multiplex(multiplex:)
+            super
+          ensure
+            # Every slot is released even if one release raises (an on_store_error that raises); the first such
+            # error is raised afterwards.
+            failure = nil
+            multiplex.queries.each do |query|
+              slots = query.context.namespace(NAMESPACE)
+              concurrency, key, token = slots.delete(:concurrency_slot)
+              next unless concurrency
+
+              begin
+                concurrency.release(query, key, token)
+              rescue StandardError => error
+                failure ||= error
+              end
+            end
+            raise failure if failure
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Test data for the rate limiters, reusable by apps and other gems.
+      module Controls
+        # A Query type: `cheap` costs 1 point, `report` costs 40, `broken` raises when resolved.
+        module Query
+          def self.example
+            Class.new(GraphQL::Schema::Object) do
+              graphql_name "Query"
+              field :cheap, String, null: false
+              field :report, String, null: false, complexity: 40
+              field :broken, String, null: false
+            end
+          end
+        end
+
+        # The root object for Query.example; it adds the name of each field it resolves to `resolved`.
+        module Root
+          def self.example(resolved = [])
+            Class.new do
+              define_method(:cheap) { resolved << :cheap; "ok" }
+              define_method(:report) { resolved << :report; "big" }
+              define_method(:broken) { raise IOError, "disk on fire" }
+            end.new
+          end
+        end
+
+        # A query context naming its client.
+        module Context
+          def self.example(key: "user:1", **context)
+            { RateLimits::KEY => key, **context }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Armory
+    module RateLimits
+      # Buckets kept in this process's memory: for tests, development and single-process servers. Several
+      # processes each keep their own buckets, so a client gets the limit once per process; share a store between
+      # processes in production.
+      class MemoryStore
+        def self.monotonic_clock
+          -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        end
+
+        def initialize(clock: self.class.monotonic_clock)
+          @clock = clock
+          @buckets = {}
+          @slots = {}
+          @mutex = Mutex.new
+        end
+
+        # Token bucket: holds up to `limit` points and refills `limit` points every `window` seconds, continuously.
+        # Takes `cost` points when they are there; with `force: true` takes them anyway, down to zero. Answers
+        # whether they were there and the whole points left.
+        def take(key, cost:, limit:, window:, force: false)
+          @mutex.synchronize do
+            now = @clock.call
+            level, at = @buckets.fetch(key) { [limit, now] }
+            level = [level + ([now - at, 0].max * limit / window.to_f), limit].min
+
+            taken = cost <= level
+            level = [level - cost, 0].max if taken || force
+            @buckets[key] = [level, [now, at].max]
+
+            [taken, level.floor]
+          end
+        end
+
+        # Slots for operations running at the same time: at most `limit` per key, each held by a token until
+        # released or until `ttl` seconds pass (a process that crashed never releases). Takes a slot when one is
+        # free; with `force: true` takes it anyway. Answers whether one was free and the slots now held.
+        def acquire(key, token:, limit:, ttl:, force: false)
+          @mutex.synchronize do
+            now = @clock.call
+            slots = (@slots[key] ||= {})
+            slots.delete_if { |_token, expires_at| expires_at <= now }
+
+            acquired = slots.size < limit
+            slots[token] = now + ttl if acquired || force
+
+            [acquired, slots.size]
+          end
+        end
+
+        def release(key, token:)
+          @mutex.synchronize do
+            slots = @slots[key] or return
+            slots.delete(token)
+            @slots.delete(key) if slots.empty?
+          end
+        end
+      end
+    end
+  end
+end