graph_weaver 0.4.4 → 0.5.0

data/lib/graph_weaver/client.rb

@@ -4,6 +4,7 @@
 require_relative "codegen"
 require_relative "errors"
 require_relative "inflect"
+require_relative "parsing"
 require_relative "retry"
 require_relative "schema_loader"
 require_relative "transport/http"
@@ -12,31 +13,45 @@ require_relative "transport/http"
 # generation:
 #
 #      github = GraphWeaver.new("https://api.github.com/graphql", auth: token, cache: true)
-#      github.register_scalar("DateTime", Time, serialize: :iso8601, requires: "time")
 #
-#      RepoQuery = github.parse("queries/repo.graphql")   # implicit schema + transport
-#      github.execute!("query { viewer { login } }")      # one-shot
+#      RepoQuery = github.parse("queries/repo.graphql")   # implicit schema + client
+#      github.run!("query { viewer { login } }")          # one-shot
 #
 # The first argument is a url (a transport is built; the schema comes
 # from introspection on first use, cached per cache:/ttl:) or a schema
-# source — a live schema class (which also executes in-process), or a
-# path/SDL/introspection dump via SchemaLoader. Pass transport: to
-# bring your own transport for a schema source.
+# source — a live schema class (which also executes in-process, through
+# an InProcess wrapper that takes context:), or a path/SDL/introspection
+# dump via SchemaLoader.
 #
-# Clients are independent: each has its own transport, schema, and
-# scalar registrations, so one app can talk to several GraphQL servers —
-# even ones that disagree about what a "DateTime" is.
+# transport: means "which transport" alongside a url — :http (the
+# default, always, whatever else the Gemfile loads) or :faraday — and
+# "this transport" alongside a schema source.
+#
+# Clients are independent: each has its own transport and schema, so one
+# app can talk to several GraphQL servers. Scalar/enum/type registrations
+# are a codegen concern and live in one global registry (see
+# GraphWeaver.register_scalar) — the same registry the rake tasks bake.
 class GraphWeaver::Client
+  include GraphWeaver::Parsing
+
   URL = %r{\Ahttps?://}i
 
-  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil, &middleware)
+  def initialize(source, auth: nil, headers: {}, retries: false, transport: nil, cache: nil, ttl: nil,
+    open_timeout: nil, read_timeout: nil, context: nil, &middleware)
+    check_source!(source)
+
     if source.is_a?(String) && source.match?(URL)
-      raise ArgumentError, "pass a url or transport:, not both" if transport
+      raise ArgumentError, "context: applies to a schema class executing in-process" if context
 
-      @transport = wrap_retries(build_transport(source, auth:, headers:, &middleware), retries)
+      built = build_transport(source, auth:, headers:, kind: transport, open_timeout:, read_timeout:, &middleware)
+      @transport = wrap_retries(built, retries)
     else
-      if auth || middleware || retries != false
-        raise ArgumentError, "auth:/retries:/middleware apply to a url — got a schema source"
+      if auth || middleware || retries || open_timeout || read_timeout
+        raise ArgumentError, "auth:/retries:/timeouts/middleware apply to a url — got a schema source"
+      end
+      if transport.is_a?(Symbol)
+        # naming a bundled transport only builds one from a url
+        raise ArgumentError, "transport: #{transport.inspect} needs a url — got a schema source; pass a built transport"
       end
       if cache || ttl
         # a schema source never introspects, so a cache would silently no-op
@@ -46,14 +61,21 @@ class GraphWeaver::Client
       # a live schema class doubles as an in-process transport; a loaded
       # dump has no resolvers, so it is type information only
       @schema = source.is_a?(Module) ? source : GraphWeaver::SchemaLoader.load(source)
-      @transport = transport || (source if source.is_a?(Module))
+
+      if context && !(source.is_a?(Module) && transport.nil?)
+        # nothing would ever read it — a dump has no resolvers, and an
+        # explicit transport carries its own
+        raise ArgumentError, "context: applies to a schema class executing in-process"
+      end
+
+      # InProcess adds context:, logging and branded errors to the bare
+      # schema class, which stays usable on its own everywhere else
+      @transport = transport ||
+        (GraphWeaver::InProcess.new(source, context: context || {}) if source.is_a?(Module))
     end
 
     @cache = cache
     @ttl = ttl
-    @scalars = {}
-    @enums = {}
-    @types = {}
   end
 
   # The transport queries run through: a url-built transport, an
@@ -74,123 +96,104 @@ class GraphWeaver::Client
     @schema ||= GraphWeaver::SchemaLoader.introspect(transport!, cache: @cache, ttl: @ttl)
   end
 
-  # Client-scoped scalar registration: consulted before the global
-  # registry when this client generates code, so two clients can map the
-  # same scalar name onto different Ruby types. A `Type.field` coordinate
-  # (e.g. "User.birthday") overrides just that field. Same signature as
-  # GraphWeaver.register_scalar.
-  def register_scalar(graphql_name, type, cast: nil, serialize: nil, requires: nil, coerce: nil)
-    validate_registration!("scalar", graphql_name.to_s)
-    @scalars[graphql_name.to_s] =
-      GraphWeaver::Codegen::ScalarType.new(graphql_name, type, cast:, serialize:, requires:, coerce:)
-  end
-
-  # Client-scoped enum mapping: this client's generated code speaks your
-  # T::Enum for the named GraphQL enum (see Codegen::EnumType — inference
-  # by name, map: for renames, fallback: to absorb unknown wire values).
-  def register_enum(graphql_name, type, map: nil, fallback: nil, requires: nil)
-    validate_registration!("enum", graphql_name.to_s)
-    @enums[graphql_name.to_s] =
-      GraphWeaver::Codegen::EnumType.new(graphql_name, type, map:, fallback:, requires:)
-  end
-
-  # Bulk, inference-only form: register_enums("Species" => PetKind, ...)
-  def register_enums(mappings)
-    mappings.each { |graphql_name, type| register_enum(graphql_name, type) }
-  end
-
-  # Client-scoped type helpers: include app-owned modules into every
-  # struct this client generates from the named GraphQL type — pass
-  # modules, or a block to build one inline. Additive with global
-  # registrations (see GraphWeaver.extend_type).
-  def extend_type(graphql_name, *mixins, requires: nil, **kw, &block)
-    validate_registration!("type", graphql_name.to_s)
-    aliases = GraphWeaver::Codegen.take_aliases(kw)
-    entry = @types[graphql_name.to_s] ||= { mixins: [], requires: [], aliases: {} }
-    GraphWeaver::Codegen.add_type_helpers(entry, graphql_name, mixins, requires, block, aliases)
-  end
-
-  # Parse a query (a .graphql path or raw string) into a typed module
-  # bound to this client's schema, scalars, enums, helpers, and transport
-  # (including a live schema class executing in-process — the module came
-  # from this client, so it runs against it; pass a client per call to
-  # override, e.g. with a fake).
-  def parse(query, name: nil)
-    GraphWeaver.parse(schema:, query:, name:, client: transport,
-      scalars: @scalars, enums: @enums, types: @types)
-  end
-
-  # Parse every .graphql query in a directory into typed modules, named
-  # like generation would name them — the no-build-step analog of
-  # generate! + load_generated!:
-  #
-  #      github.load_queries!                        # queries/person.graphql => ::PersonQuery
-  #      github.load_queries!(namespace: Github)     # => Github::PersonQuery
-  #
-  # Reloadable (constants are replaced), so it suits consoles and dev.
-  # Returns the modules.
-  def load_queries!(dir = nil, namespace: Object)
-    dirs = dir ? [dir] : GraphWeaver.queries_paths
-    dirs.flat_map { |d| Dir[File.join(d, "*.graphql")].sort }.map do |path|
-      name = "#{GraphWeaver::Inflect.camelize(File.basename(path, ".graphql"))}Query"
-      namespace.send(:remove_const, name) if namespace.const_defined?(name, false)
-      GraphWeaver.log(:info) { "loaded #{name} from #{path}" }
-      namespace.const_set(name, parse(path))
-    end
+  # The client contract, same as every transport: a query and its
+  # variables in, the raw response hash out. (#run is the one-shot that
+  # parses and returns the typed envelope.)
+  def execute(query, variables: {}, operation_name: nil)
+    transport!.execute(query, variables:, operation_name:)
   end
 
-  # One-shot dynamic execution — parse + execute, returning the typed
-  # Response envelope (execute! returns the result or raises). Variables
+  # One-shot dynamic execution — parse + run, returning the typed
+  # Response envelope (run! returns the result or raises). Variables
   # are plain kwargs, exactly as on a generated module; graphql-cased
   # string keys work too.
-  def execute(query, **variables)
+  def run(query, **variables)
     mod = parse(query)
     kwargs = variables.to_h { |key, value| [GraphWeaver::Inflect.underscore(key.to_s).to_sym, value] }
-    mod.execute(transport!, **kwargs)
+    mod.execute(**kwargs)
   end
 
-  def execute!(query, **variables)
-    execute(query, **variables).data!
+  def run!(query, **variables)
+    run(query, **variables).data!
   end
 
   private
 
-  # Fail a typo'd registration at the call site when the schema is
-  # already in hand (a schema-source client, or a url client after first
-  # use) — immediate feedback in consoles. Lazily-introspecting clients
-  # get the same check at generation time instead; never trigger an
-  # introspection just to validate a name.
-  def validate_registration!(kind, name)
-    return unless @schema
-
-    GraphWeaver::Codegen.validate_registration!(@schema, kind, name)
+  # Anything already speaking the client contract — another Client,
+  # InProcess, Retry, a transport, a fake, the test router — carries no
+  # schema to generate from, so it can't stand in as the schema source.
+  # Without this it is handed to SchemaLoader and fails as `undefined
+  # method 'lstrip'`.
+  def check_source!(source)
+    # a graphql-ruby schema class executes too, and *is* a schema source
+    return if source.is_a?(Module) || !source.respond_to?(:execute)
+
+    raise GraphWeaver::Error, "#{source.class} is a client, not a schema source — pass the schema, and this " \
+      "as its transport: GraphWeaver.new(schema, transport: client). For a live schema class " \
+      "with a context: GraphWeaver.new(schema, context: { ... })."
   end
 
   # auth: is a token — "Bearer" is assumed unless the string carries its
-  # own scheme ("Basic dXNlcjpwYXNz..."). Transport pick: Faraday when
-  # the app already loads it (its middleware/proxy/timeout ecosystem
-  # comes along), the zero-dependency Transport::HTTP otherwise.
-  # Detection is `defined?(Faraday)` — deliberately NOT a require:
-  # faraday rides along transitively in most bundles (stripe, octokit,
-  # ...), and try-requiring would switch transports on apps that never
-  # chose it. With faraday under `require: false`, load it before
-  # building the client.
-  def build_transport(url, auth:, headers:, &middleware)
+  # own scheme ("Basic dXNlcjpwYXNz...").
+  #
+  # Transport pick: always Transport::HTTP unless you ask for Faraday
+  # (transport: :faraday, or a middleware block, which is Faraday's
+  # anyway). Deliberately NOT `defined?(Faraday)`: faraday rides along
+  # transitively in most bundles (stripe, octokit, ...), so sniffing for
+  # it lets an unrelated gem swap your transport — along with its
+  # timeouts and, since Faraday's default net_http adapter reconnects
+  # per request, your connection reuse. Same code, same transport.
+  def build_transport(url, auth:, headers:, kind:, open_timeout: nil, read_timeout: nil, &middleware)
     headers = headers.dup
     if auth
       headers["Authorization"] ||= auth.include?(" ") ? auth : "Bearer #{auth}"
     end
 
-    if defined?(::Faraday)
-      require_relative "transport/faraday"
-      GraphWeaver::Transport::Faraday.new(url, headers:, &middleware)
-    elsif middleware
-      raise ArgumentError, "middleware blocks require the faraday gem"
+    # nil means "the transport's default" — both bundled ones agree on it
+    timeouts = { open_timeout:, read_timeout: }.compact
+
+    transport =
+      if transport_kind(kind, middleware) == :faraday
+        build_faraday(url, headers:, timeouts:, &middleware)
+      else
+        GraphWeaver::Transport::HTTP.new(url, headers:, **timeouts)
+      end
+
+    GraphWeaver.log(:info) { "transport: #{transport.class} -> #{url}" }
+    transport
+  end
+
+  # Which bundled transport a url client builds: the explicit
+  # transport:, else Faraday when a middleware block asks for it.
+  def transport_kind(kind, middleware)
+    case kind
+    when nil then middleware ? :faraday : :http
+    when :faraday then :faraday
+    when :http
+      raise ArgumentError, "middleware blocks are Faraday's — pass transport: :faraday" if middleware
+
+      :http
     else
-      GraphWeaver::Transport::HTTP.new(url, headers:)
+      raise ArgumentError, "transport: takes :http or :faraday alongside a url, got #{kind.inspect}"
     end
   end
 
+  # The faraday gem is optional, so a missing one reads as a Gemfile
+  # problem rather than a stack trace out of require.
+  def build_faraday(url, headers:, timeouts:, &middleware)
+    begin
+      require_relative "transport/faraday"
+    rescue LoadError
+      nil # reported below, alongside a gem that loaded but wasn't there
+    end
+
+    unless defined?(::Faraday)
+      raise ArgumentError, "the faraday transport needs the faraday gem — add it to your Gemfile"
+    end
+
+    GraphWeaver::Transport::Faraday.new(url, headers:, **timeouts, &middleware)
+  end
+
   # retries: is off by default — true for Retry defaults, or a
   # Hash of its options
   def wrap_retries(transport, retries)

data/lib/graph_weaver/codegen/aliases.rb

@@ -0,0 +1,217 @@
+# typed: true
+# frozen_string_literal: true
+
+# Registered aliases (extend_type alias:): dotted paths that project a nested
+# selection onto the struct that owns it — `entity: "_entities.first"`,
+# `tag: "meta.tag"` — as typed delegators. Resolved against the walked node
+# tree, so a path the query doesn't select fails at generation.
+#
+# Mixed into Codegen — methods run with the generator instance state. The
+# subsystem hangs off one seam: object_node's
+# `node.aliases = resolve_aliases(node)`.
+
+# the other half: extend_type, which populates the registry read here
+require_relative "type_helpers"
+
+class GraphWeaver::Codegen
+  module Aliases
+    include Kernel # for sorbet: hosts are Objects
+
+    private
+
+    # Resolve each registered alias (extend_type alias:) for this struct's type
+    # against its actual selection — path -> a typed delegator emitted into the
+    # struct body. Validated here, per query, so an unselected or untraversable
+    # path fails at generation with a pointed message.
+    def resolve_aliases(node)
+      type_aliases(node.graphql_type).filter_map do |name, spec|
+        # a bad accessor name (reserved, or colliding with a real field) is a
+        # registration mistake — it fails for every query, so it always raises,
+        # even for optional aliases (which otherwise mask it as "doesn't fit").
+        check_alias_name!(node, name)
+        begin
+          resolve_alias(node, name, spec[:segments])
+        rescue UnknownSegment => e
+          # names nothing in the schema, so no selection would fit — offering
+          # optional: as the way out would just hide the typo
+          raise e.class, qualify(node, e.message)
+        rescue GraphWeaver::Error => e
+          # a path that doesn't fit THIS query's selection: optional simply
+          # omits the accessor; strict breaks generation for every query on the
+          # type, so name the one that failed and the way out
+          next nil if spec[:optional]
+
+          raise e.class, "#{qualify(node, e.message)} " \
+            "— pass optional: true to skip selections that don't fit"
+        end
+      end
+    end
+
+    # Name the failing query module — unless the message already names it,
+    # since a module and the type it queries can share a name (module Query
+    # on type Query would otherwise stutter).
+    def qualify(node, message)
+      return message if @module_name.nil? || @module_name == node.graphql_type
+
+      "#{@module_name}: #{message}"
+    end
+
+    def check_alias_name!(node, name)
+      taken = node.fields.any? { |f| f.prop == name } ||
+        ALIAS_RESERVED.include?(name) || RUBY_KEYWORDS.include?(name)
+      return unless taken
+
+      raise GraphWeaver::Error,
+        "alias #{name.inspect} on #{node.graphql_type} collides with an existing field or method"
+    end
+
+    # Registered aliases for a GraphQL type (see extend_type alias:).
+    def type_aliases(graphql_name)
+      GraphWeaver::Codegen.type_registry[graphql_name]&.dig(:aliases) || {}
+    end
+
+    # methods every generated struct already answers to; Ruby keywords are
+    # checked alongside (RUBY_KEYWORDS is defined by the class this mixes into)
+    ALIAS_RESERVED = %w[from_h serialize to_h].to_set.freeze
+    # list selectors — pick one element out of a list-typed hop, always nilable
+    # (the list may be empty). Everything else is a field prop.
+    LIST_SELECTORS = %w[first last].freeze
+    # A segment naming no field of the GraphQL type at all — no selection could
+    # ever satisfy it, so it's a typo (or a wire-cased name), not a path that
+    # doesn't fit this query. optional: skips the latter, never this.
+    UnknownSegment = Class.new(GraphWeaver::Error)
+
+    # Walk a dotted path through this struct's selected shape, building the
+    # delegator expression (`meta&.tag`, `_entities.first&.name`) and its return
+    # type. A segment is a field prop, or `first`/`last` to pick a list element.
+    # Everything is checked against the node tree: a field on a non-object, a
+    # selector on a non-list, or an unselected segment raises. Any nilable hop
+    # (a nullable field, or a list element) makes the accessor nilable.
+    def resolve_alias(node, name, segments)
+      cur = T.let(node, T.untyped)           # the node the path has reached
+      cur_nilable = T.let(false, T::Boolean) # is the expression so far nilable
+      nilable = T.let(false, T::Boolean)     # is the accessor overall nilable
+      containers = T.let([], T::Array[String]) # nested-struct class names on the way to the leaf
+      expr = +""
+
+      segments.each do |seg|
+        # the first hop reads off the struct itself — spelled `self.` when the
+        # prop is a Ruby keyword (`self.next`), which bare would be the keyword
+        connector = if !expr.empty?
+          cur_nilable ? "&." : "."
+        else
+          RUBY_KEYWORDS.include?(seg) ? "self." : ""
+        end
+
+        # `first`/`last` select an element only when the current hop is actually a
+        # list; otherwise they're an ordinary field (a schema field named `first`)
+        if LIST_SELECTORS.include?(seg) && list_of(cur)
+          expr << connector << seg
+          cur = list_of(cur).of
+          cur_nilable = true # first/last is nil on an empty list
+          nilable = true
+        else
+          obj = object_of(cur)
+          unless obj
+            hint = if list_of(cur)
+              " — use .first or .last to pick an element"
+            elsif LIST_SELECTORS.include?(seg)
+              " — .#{seg} needs a list"
+            else
+              ""
+            end
+            raise GraphWeaver::Error,
+              "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' can't be read here (not an object)#{hint}"
+          end
+          # the object a field is read from is the lexical container of its result
+          # (nested structs emit inside their parent); the aliased struct itself is
+          # the delegator's own scope, so it contributes no prefix
+          containers << obj.class_name unless obj.equal?(node)
+          field = obj.fields.find { |f| f.prop == seg }
+          unless field
+            check_segment_exists!(node, name, obj, seg)
+            props = obj.fields.map(&:prop)
+            suggestion = GraphWeaver.did_you_mean(props, seg)
+            hint = suggestion ? " — did you mean '#{suggestion}'?" : " (have: #{props.join(", ")})"
+            raise GraphWeaver::Error,
+              "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a selected field#{hint}"
+          end
+          expr << connector << seg
+          cur = field.node
+          cur_nilable = !field.node.non_null?
+          nilable ||= cur_nilable
+        end
+      end
+
+      leaf = qualified_alias_type(cur, containers)
+      type = nilable && leaf != "T.untyped" ? "T.nilable(#{leaf})" : leaf
+      ObjectNode::Alias.new(name, expr, type)
+    end
+
+    # Separate "this query didn't select it" from "no query could": a segment
+    # the schema doesn't declare on the type is a mistake in the registration,
+    # so it raises even for an optional alias — which otherwise turns a typo
+    # (or a wire-cased 'findPets') into an accessor that silently vanishes.
+    def check_segment_exists!(node, name, obj, seg)
+      type = obj.graphql_type && @schema.get_type(obj.graphql_type)
+      return unless type.respond_to?(:fields)
+
+      known = type.fields.keys.map { |field| GraphWeaver::Inflect.underscore(field) }
+      return if seg == "__typename" || known.include?(seg)
+
+      prop = GraphWeaver::Inflect.underscore(seg)
+      hint = if prop != seg && known.include?(prop)
+        # paths are the Ruby prop chain, not the GraphQL one — the classic miss
+        " — GraphQL fields generate snake_case props; use '#{prop}'"
+      elsif (suggestion = GraphWeaver.did_you_mean(known, prop))
+        " — did you mean '#{suggestion}'?"
+      else
+        " (has: #{known.sort.join(", ")})"
+      end
+
+      raise UnknownSegment,
+        "alias #{name.inspect} on #{node.graphql_type}: '#{seg}' is not a field of #{obj.graphql_type}#{hint}"
+    end
+
+    # The leaf's Sorbet type as referenced from the aliased struct. Generated
+    # nested constants (structs, enums, unions) must carry the container path,
+    # since the delegator's `sig` is emitted in an outer struct where a bare
+    # `Sub` wouldn't resolve; scalars, mapped enums, and hoisted union refs are
+    # already top-level. `containers` is the class-name chain to the leaf.
+    def qualified_alias_type(node, containers)
+      node = node.of if node.is_a?(NonNull)
+      prefix = containers.empty? ? "" : "#{containers.join("::")}::"
+
+      case node
+      when List
+        element = node.of.is_a?(NonNull) ? qualified_alias_type(node.of, containers) : begin
+          inner = qualified_alias_type(node.of, containers)
+          inner == "T.untyped" ? inner : "T.nilable(#{inner})"
+        end
+        "T::Array[#{element}]"
+      when ObjectNode, NarrowedNode then "#{prefix}#{node.class_name}"
+      # enums are emitted at module level (see Emit#module_level?), or aliased
+      # there from the shared enums module — either way, no container prefix
+      when EnumNode then node.class_name
+      when UnionNode then "#{prefix}#{node.bare_type}"
+      else node.bare_type # Scalar, MappedEnum, UnionRefNode — already top-level
+      end
+    end
+
+    # the List a node wraps (through NON_NULL), or nil
+    def list_of(node)
+      node = T.let(node, T.untyped)
+      node = node.of while node.is_a?(NonNull)
+      node if node.is_a?(List)
+    end
+
+    # the ObjectNode a node resolves to for field access (through NON_NULL and a
+    # narrowed abstract member), or nil — unions/scalars/lists can't be read into
+    def object_of(node)
+      node = T.let(node, T.untyped)
+      node = node.of while node.is_a?(NonNull)
+      node = node.nested if node.is_a?(NarrowedNode)
+      node if node.is_a?(ObjectNode)
+    end
+  end
+end