graph_weaver 0.6.1 → 0.7.1

data/lib/graph_weaver/internal/server_input.rb

@@ -0,0 +1,251 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # A server's rejection of the input, read back into InputError values —
+    # the same value object the client-side refusal is, so an app renders one
+    # form the same way whichever side said no.
+    #
+    # Four shapes, most specific first: the `extensions.input` convention
+    # (docs/errors.md), graphql-ruby's variable-coercion `problems` array, a
+    # recognized `extensions.code`, and Hasura's argument path. Everything
+    # else is nobody's input error and stays out — and an explanation with no
+    # table entry becomes `:refused` carrying the server's own sentence,
+    # because a wrong `kind` is worse than no kind: the app will have
+    # translated it into a confident sentence.
+    #
+    # One rule for #path throughout: it is the INPUT path the server stated,
+    # or empty. A GraphQL error's own path names a selection rather than an
+    # input slot, so it is never stood in for one.
+    module ServerInput
+      # graphql-ruby names the variable only in the error's message; the
+      # problems underneath are relative to it (measured against 2.6.10).
+      VARIABLE = /\AVariable \$([A-Za-z_]\w*) /
+
+      # The explanations graphql-ruby writes for a variable that wouldn't
+      # coerce. A closed table, not a parser: anything else is :refused.
+      COERCE = /\ACould not coerce value .* to (\S+)\z/
+      NOT_A_MEMBER = /\AExpected .* to be one of: (.*)\z/
+      NOT_NULL = /\AExpected value to not be null\z/
+      NOT_DEFINED = /\AField is not defined on (\S+)\z/
+
+      # Hasura states no input code — it stamps one code on a whole class of
+      # rejections and says what the error is about in `extensions.path`, a
+      # dotted string rather than an array. So the path is the test, not the
+      # code: only one that reaches a field's arguments is about the input.
+      # "$", "$.query" and "$.selectionSet.<field>" are the query itself — a
+      # .graphql file that doesn't parse, or names an argument the schema
+      # hasn't got, is nothing a form can highlight.
+      HASURA_CODES = %w[validation-failed parse-failed].freeze
+      # lazily, so an argument of its own named `args` doesn't win the split
+      HASURA_ARGUMENT = /\A\$\.selectionSet\..+?\.args\.(.+)\z/
+      HASURA_SEGMENT = /\A([_A-Za-z]\w*)((?:\[\d+\])*)\z/
+
+      # The explanations Hasura writes that name a kind on their own (measured
+      # against Hasura v2, one curl per entry — spec/input_errors_spec.rb
+      # holds the verbatim JSON). Its scalar family, "expected <description>
+      # for type 'T', but found <json type>", is deliberately absent: one
+      # sentence covers both `limit: -5` (out of range) and `limit: "lots"`
+      # (wrong type), and telling them apart means parsing the English
+      # description rather than reading a table.
+      HASURA_NOT_A_MEMBER = /\Aexpected one of the values \[(.*)\] for type '[^']*', but found /
+      HASURA_NOT_DEFINED = /\Afield '([^']*)' not found in type: '([^']*)'\z/
+      HASURA_NULL = /\Aunexpected null value for type '[^']*'\z/
+      QUOTED = /'([^']*)'/
+
+      # InputError::DETAILS closes the key set; this closes the types, because
+      # a right key with the wrong type under it is the same smuggling. An app
+      # is entitled to errors.rb's promise that members stays an Array —
+      # details[:members].join(", ") must not raise on what a server sent.
+      # (spec/input_errors_spec.rb holds these keys to DETAILS.)
+      DETAIL_TYPES = {
+        "type" => String, "members" => Array, "min" => Numeric,
+        "max" => Numeric, "pattern" => String, "suggestion" => String,
+      }.freeze
+
+      private_constant :VARIABLE, :COERCE, :NOT_A_MEMBER, :NOT_NULL, :NOT_DEFINED,
+        :HASURA_CODES, :HASURA_ARGUMENT, :HASURA_SEGMENT, :QUOTED,
+        :HASURA_NOT_A_MEMBER, :HASURA_NOT_DEFINED, :HASURA_NULL
+
+      class << self
+        def read(error)
+          extensions = error.extensions
+          stated = extensions["input"]
+          return [convention(error.message, stated, [], nil)] if stated.is_a?(Hash)
+          return problems(error, extensions) if extensions["problems"].is_a?(Array)
+
+          kind = GraphWeaver::GraphQLError::INPUT_CODES[error.code.to_s]
+          return [coded(error, kind)] if kind
+
+          hasura(error, extensions)
+        end
+
+        private
+
+        # The convention: taken verbatim, after checking `kind` is one this
+        # version knows and `details` carries only keys a kind can mean.
+        def convention(message, stated, path, value)
+          kind = stated["kind"].to_s.to_sym
+          kind = :refused unless GraphWeaver::InputError::KINDS.include?(kind)
+          coordinate = stated["coordinate"]
+
+          build(
+            message,
+            kind:,
+            path: input_path(stated["path"]) || path,
+            coordinate: (coordinate if coordinate.is_a?(String)),
+            value: stated.key?("value") ? stated["value"] : value,
+            details: details_of(stated),
+          )
+        end
+
+        # A path a server stated for the INPUT, or nil: field names and list
+        # indices, nothing else. There is no floor under it — a GraphQL error's
+        # own path names a selection ("createOrder"), and standing that in gives
+        # #field a plausible-looking name for a slot the input hasn't got.
+        def input_path(stated)
+          return unless stated.is_a?(Array)
+
+          stated if stated.all? { |segment| segment.is_a?(String) || segment.is_a?(Integer) }
+        end
+
+        # the details a server stated that a kind can actually mean, both key
+        # and type — anything else is dropped rather than passed through
+        def details_of(stated)
+          DETAIL_TYPES.each_with_object({}) do |(key, type), out|
+            value = stated[key]
+            out[key.to_sym] = value if value.is_a?(type)
+          end
+        end
+
+        # One InputError per problem — a single coercion error routinely
+        # carries several, and they are about different fields.
+        def problems(error, extensions)
+          root = (match = error.message.match(VARIABLE)) ? [match[1]] : []
+
+          extensions["problems"].filter_map do |problem|
+            next unless problem.is_a?(Hash)
+
+            within = Array(problem["path"])
+            path = root + within
+            value = dig(extensions["value"], within)
+            message = problem["explanation"].to_s
+            stated = problem.dig("extensions", "input")
+            next convention(message, stated, path, value) if stated.is_a?(Hash)
+
+            explained(message, path, value, within)
+          end
+        end
+
+        def explained(message, path, value, within)
+          case message
+          when COERCE
+            # text that didn't parse, vs a thing that was never that type
+            build(message, kind: value.is_a?(String) ? :unparseable : :type_mismatch,
+              path:, value:, details: { type: $1 })
+          when NOT_A_MEMBER
+            build(message, kind: :not_a_member, path:, value:, details: { members: $1.split(", ") })
+          when NOT_NULL
+            build(message, kind: :missing, path:, value:)
+          when NOT_DEFINED
+            # the one explanation that names the input type, so the one that
+            # can give a coordinate — but only from the problem's OWN path.
+            # #path is the variable plus that, so its last segment is the
+            # variable name when the problem states none, and "RangeInput.range"
+            # is a slot the schema doesn't have.
+            type = $1
+            field = within.last
+            build(message, kind: :unknown, path:, value:,
+              coordinate: ("#{type}.#{field}" if field.is_a?(String)))
+          else
+            build(message, kind: :refused, path:, value:)
+          end
+        end
+
+        # Hasura: the argument is in extensions.path or this is not about the
+        # input. No value either — Hasura never echoes back what it rejected.
+        def hasura(error, extensions)
+          return [] unless HASURA_CODES.include?(error.code.to_s)
+
+          stated = extensions["path"]
+          match = stated.is_a?(String) ? stated.match(HASURA_ARGUMENT) : nil
+          path = hasura_path(match[1]) if match
+          path ? [hasura_explained(error.message, path)] : []
+        end
+
+        # "order_by[0].name" => ["order_by", 0, "name"]. nil rather than a
+        # partial read: a path this can't spell points a form at a field the
+        # server never named.
+        def hasura_path(stated)
+          stated.split(".").flat_map do |segment|
+            match = segment.match(HASURA_SEGMENT) or return nil
+            [match[1], *match[2].scan(/\d+/).map(&:to_i)]
+          end
+        end
+
+        def hasura_explained(message, path)
+          case message
+          when HASURA_NOT_A_MEMBER
+            build(message, kind: :not_a_member, path:, details: { members: $1.scan(QUOTED).flatten })
+          when HASURA_NOT_DEFINED
+            build(message, kind: :unknown, path:, coordinate: "#{$2}.#{$1}")
+          when HASURA_NULL
+            # :missing is "wasn't supplied, or was null" (docs/i18n.md)
+            build(message, kind: :missing, path:)
+          else
+            build(message, kind: :refused, path:)
+          end
+        end
+
+        # A recognized validation code. `argumentName` is the input coordinate;
+        # a code that names none names no slot, and the error's own path is a
+        # QUERY path ("query", "rangeThing", …) rather than an input one.
+        def coded(error, kind)
+          extensions = error.extensions
+          argument = extensions["argumentName"]
+          # inputObjectType is stated outright; argumentNotAccepted says which
+          # kind of thing `name` is instead. A field argument has no schema
+          # coordinate here — nothing names the field's parent type.
+          type = extensions["inputObjectType"] ||
+            (extensions["name"] if extensions["typeName"] == "InputObject")
+
+          build(
+            error.message,
+            kind:,
+            path: argument.is_a?(String) ? [argument] : [],
+            coordinate: ("#{type}.#{argument}" if type.is_a?(String) && argument.is_a?(String)),
+            value: extensions["value"],
+          )
+        end
+
+        # raised: false — this is a value read off a response, and the warn
+        # line Error#initialize writes would claim a raise that never happened.
+        #
+        # The message goes through the same filter the client side puts its own
+        # messages through: a server quotes the value it rejected as a matter of
+        # course ('Could not coerce value "hunter2" to Int'), so redacting only
+        # #value would leave half the promise kept. It is capped for the same
+        # reason — the sentence is the server's, and so is its length.
+        def build(message, kind:, path:, value: nil, coordinate: nil, details: {})
+          redact = GraphWeaver::Internal::Redact
+          GraphWeaver::InputError.new(
+            redact.cap(redact.detail(path.last, message)), kind:, path:, coordinate:, details:, raised: false,
+            value: redact.value(path.last, value),
+          )
+        end
+
+        # the problem's path walked into the variable the server echoed back
+        def dig(value, path)
+          path.reduce(value) do |node, segment|
+            case node
+            when Hash then node[segment.to_s]
+            when Array then segment.is_a?(Integer) ? node[segment] : nil
+            else return nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/graph_weaver/internal/test_clients.rb

@@ -0,0 +1,276 @@
+# typed: true
+# frozen_string_literal: true
+
+module GraphWeaver
+  module Internal
+    # The client a generated module runs against while a test mode is
+    # installed — the slot `graphql: :fake` and its siblings fill, and the one
+    # a `graphql_*` helper writes to.
+    #
+    # A tag used to work by swapping GraphWeaver.client, which is the LAST
+    # place a module looks: one generated with `client:` reads its baked
+    # DEFAULT_CLIENT first and never got there, so the tag quietly didn't
+    # apply. The mode installs itself here instead, and QueryModule asks
+    # before it reads that constant — so a tag reaches every module the
+    # example runs, bound or not.
+    #
+    # Keyed by the graph a module was generated from (its baked GRAPH), since
+    # the honest answer varies: :fake for a billing module has to fabricate
+    # billing's shapes, not the other schema's. A helper names its graphs the
+    # same way and lands in the same table, so what an example says applies to
+    # the modules it runs.
+    #
+    # Test-time only. Nothing installs a mode in production, where #for is an
+    # ivar read that returns nil.
+    module TestClients
+      # The app client slot under a mode in an app with several graphs. It
+      # fills the duck-typed slot the same way every other client does, and
+      # answers the one question asked of it with the reason there is no
+      # answer — the alternative is the real endpoint, silently.
+      class NoAppClient
+        def initialize(mode) = @mode = mode
+
+        def execute(_query, **)
+          graphs = GraphWeaver.graphs
+          raise GraphWeaver::Error, "#{@mode.inspect} stands in for a graph's modules, and this " \
+            "app has #{graphs.size} graphs (#{graphs.map { |g| g.name.inspect }.join(", ")}) — so " \
+            "GraphWeaver.client has no one right answer, and this request would have gone to the " \
+            "real endpoint. A generated module runs against its own graph's stand-in; to reach one " \
+            "directly, call the client a helper returns (graphql_fake(graph: #{graphs.first.name.inspect}), " \
+            "graphql_in_process(graph: #{graphs.first.name.inspect})). Tag the example graphql: :live " \
+            "for the app's own client."
+        end
+
+        def inspect = "#<#{self.class} #{@mode.inspect}>"
+      end
+
+      class << self
+        # Install `mode` for one example — the example's mode, which is what
+        # a graph no helper named runs against.
+        #
+        # Only the rspec hook installs, once per example after reset!. A
+        # helper doesn't: what a helper says is ONE graph's stand-in, written
+        # to the table by override!, so no helper can reset another graph's —
+        # which is how two graphs run in two modes in one example.
+        def install(mode)
+          @mode = mode
+          @clients = {}
+          @context = nil
+        end
+
+        # Back to no mode: every module resolves its own client again.
+        def reset!
+          @mode = nil
+          @clients = nil
+          @context = nil
+        end
+
+        # Whether an example is running under a mode — what tells suite setup
+        # apart from an example changing it out from under itself.
+        def installed? = !@mode.nil?
+
+        # Whether this example's stand-ins are already built — which is what
+        # makes a config setting they were built FROM too late to change.
+        def built? = !(@clients.nil? || @clients.empty?)
+
+        # The GraphQL context every stand-in runs with: this example's, else
+        # the suite baseline. graphql_context writes it, and the stand-ins
+        # already built take it in place — a :wire example's are built before
+        # the example body runs.
+        def context = @context || GraphWeaver::Testing.config.context
+
+        def context=(values)
+          @context = values
+          @clients&.each_value { |client| client.context = values if client.respond_to?(:context=) }
+        end
+
+        # `client` stands in for every graph in `graphs`, in place of the one
+        # the mode would build. This is a helper called in an example saying
+        # what the modules it names run against.
+        def override!(client, graphs)
+          graphs.each { |graph| @clients[graph&.name] = client }
+          client
+        end
+
+        # The stand-in for `mod`, or nil when there is nothing to stand in for.
+        def for(mod)
+          return unless @mode
+          # :wire takes no client slot: it serves the resolvers at the
+          # endpoint each client already posts to — the transport you ship,
+          # running unchanged, is the whole point
+          return if @mode == :wire
+          # :live is the app's own clients, untouched — so with nothing
+          # standing in there is nothing to look up
+          return if @mode == :live && !built?
+
+          # a helper's entry wins whatever the example's mode is, and :live
+          # builds nothing of its own, so an untagged example's other graphs
+          # still resolve their own clients
+          standin(graph_for!(mod))
+        end
+
+        # The stand-in `graph`'s modules run against under the installed mode,
+        # built once per example. :wire reaches it too — its clients sit
+        # behind the served endpoints rather than in the client slot, but they
+        # are the same objects graphql_context has to reach.
+        #
+        # `mode` is how a helper under a :wire tag asks for the client its own
+        # name means rather than the one :wire would have picked.
+        def standin(graph, mode = @mode)
+          @clients[graph&.name] ||= client_for(mode, graph)
+        end
+
+        # The client `mode` runs `graph` against — the one answer to "what
+        # does this tag mean", asked per module here and once per example by
+        # the rspec hook. nil for the two modes that take no client slot:
+        # :live is the app's own clients, untouched, and :wire serves the
+        # resolvers at the endpoint each client already posts to.
+        def client_for(mode, graph = app_graph)
+          config = GraphWeaver::Testing.config
+          case mode
+          when :fake
+            GraphWeaver::Testing::FakeClient.new(schema: config.reference_schema!(graph),
+              registry: graph&.registry)
+          when :in_process
+            GraphWeaver::InProcess.new(config.schema_class!(graph), context:)
+          when :router
+            router = config.built_router(graph)
+            router.context = context
+            # a router is built once per supergraph, so it has to be told
+            # where this example starts — the trace, and any faked subgraph's
+            # fabricated data. Once per router, not once per graph: two
+            # graphs naming one supergraph share it, and resetting again when
+            # the second's first module resolved wiped what the first had
+            # already accumulated, mid-example.
+            router.reset! unless @clients&.value?(router)
+            router
+          when :wire
+            # what sits behind the wire is decided the way the other tags
+            # already decide it, per graph — the most faithful thing that
+            # graph has, in the order the other tags rank them
+            client_for(wire_mode(config, graph), graph)
+          end
+        end
+
+        # What :wire serves for `graph`: its router when it is in a composed
+        # supergraph, its live schema class when it has one, else a fake of
+        # its schema — which is what an app that is a pure client of someone
+        # else's API has, and the only mode it could be.
+        #
+        # The one candidate the other modes have and :wire doesn't is
+        # GraphWeaver.client's own schema: reading it introspects the very
+        # endpoint :wire is about to stub, so it is a refusal here rather than
+        # a request into a stub that doesn't exist yet.
+        def wire_mode(config, graph)
+          return :router if config.supergraph?(graph)
+          return :in_process if config.schema_class?(graph)
+          return :fake if config.schema || graph&.named_schema?
+
+          raise GraphWeaver::Error, ":wire serves your schema at the endpoint your client posts " \
+            "to, and #{graph&.name ? "graph #{graph.name.inspect}" : "this app"} has none to " \
+            "serve — no live GraphQL::Schema class, no composed supergraph, and no type " \
+            "information (nothing at #{GraphWeaver.schema_path}, and " \
+            "GraphWeaver::Testing.config.schema is unset). Your client's own schema can't stand " \
+            "in here: reading it introspects the endpoint :wire has stubbed. Commit a dump " \
+            "(rake graph_weaver:schema:refresh URL=…), or tag the example graphql: :live."
+        end
+
+        # The graph a mode builds for when no module named one: this app's
+        # only graph. With several the honest answer varies per module, so
+        # there is no app-wide one and each module resolves its own.
+        def app_graph
+          graphs = GraphWeaver.graphs
+          graphs.first if graphs.one?
+        end
+
+        # What GraphWeaver.client holds while a mode is installed, or nil for
+        # the modes that leave the app's own there (:live, and :wire, which
+        # serves at each client's endpoint instead).
+        #
+        # One graph has one answer, so the app slot holds the same stand-in
+        # its modules resolve. With several there is none — and leaving the
+        # app's real client in the slot let a stray GraphWeaver.client.execute
+        # reach the production endpoint from an example whose tag promised no
+        # request, so the slot refuses by name instead.
+        def app_client
+          return if @mode.nil? || @mode == :live || @mode == :wire
+
+          graph = app_graph
+          graph ? standin(graph) : NoAppClient.new(@mode)
+        end
+
+        # The graphs a helper stands in for: the one `graph:` names, else the
+        # ones `schema` names, else this app's only graph. A helper that
+        # reaches no module is the silent pass this slot exists to stop, so
+        # nothing to reach is a refusal — and `advice` is what THIS helper
+        # does once it knows which graph.
+        #
+        # `graph:` leads because a graph's name is its identity everywhere
+        # else in the gem, and it is the only spelling that reaches every
+        # graph: `schema` is matched by object identity, which a graph whose
+        # schema is a dump has nothing to match with.
+        def targets!(helper, schema, advice, graph: nil)
+          return [graph!(helper, graph)] if graph
+
+          named = named_graphs(schema)
+          return named if named.any?
+
+          graphs = GraphWeaver.graphs
+          return graphs if graphs.one?
+
+          raise GraphWeaver::Error, "#{helper} stands in for the modules of one graph, and " \
+            "#{schema ? "#{schema} names none of this app's graphs" : "this app has #{graphs.size}"} " \
+            "(#{declared_names}) — say which: #{helper}(graph: #{graphs.first.name.inspect}). #{advice}"
+        end
+
+        private
+
+        # The graph `graph:` names. Its name, not its schema: that is what
+        # `rake graph_weaver:graphs` prints, what codegen bakes into a
+        # module's GRAPH, and the one handle a dump-backed graph has.
+        def graph!(helper, name)
+          found = GraphWeaver.graphs.find { |graph| graph.name == name }
+          return found if found
+
+          near = Util.did_you_mean(GraphWeaver.graphs.map { |graph| graph.name.to_s }, name.to_s)
+          raise GraphWeaver::Error, "#{helper}(graph: #{name.inspect}) names none of this app's " \
+            "graphs (#{declared_names})#{" — did you mean #{near.to_sym.inspect}?" if near}"
+        end
+
+        # The graphs `schema` names: a schema class is matched against what
+        # each graph runs in-process, which is the only thing that ties a
+        # class to a graph. A graph named by a dump can't be named this way,
+        # and correctly isn't.
+        def named_graphs(schema)
+          return [] unless schema
+
+          GraphWeaver.graphs.select { |graph| graph.live_schema.equal?(schema) }
+        end
+
+        def declared_names = GraphWeaver.graphs.map { |graph| graph.name.inspect }.join(", ")
+
+        # The graph `mod` was generated from, by the name codegen baked in.
+        # An app with several graphs and a module that names none was
+        # generated before its graph was declared, or by an older release —
+        # and guessing would fake one schema's shapes at another's module.
+        def graph_for!(mod)
+          graphs = GraphWeaver.graphs
+          return graphs.first if graphs.one?
+
+          name = mod.const_defined?(:GRAPH, false) ? mod.const_get(:GRAPH) : nil
+          found = graphs.find { |graph| graph.name == name }
+          return found if found
+
+          # Two doors produce a module, so the fix has two spellings: a file
+          # gets its GRAPH back by being regenerated, and a GraphWeaver.parse
+          # module — which generates no file, so regenerating cannot reach it
+          # — is told where it is parsed.
+          raise GraphWeaver::Error, "#{mod} doesn't say which of this app's graphs " \
+            "(#{declared_names}) it was generated from, so #{@mode.inspect} has nothing to run " \
+            "it against — regenerate it (rake graph_weaver:generate), or, if it came from " \
+            "GraphWeaver.parse, say which there (graph: #{graphs.first.name.inspect})."
+        end
+      end
+    end
+  end
+end