lighthouse-graphql 0.4.0 → 0.6.0

data/docs/types.md

@@ -0,0 +1,218 @@
+# Unions, Interfaces and Scalars
+
+The SDL declares every type. Object types resolve their fields through
+directives, the default reader, or a [type class](resolvers.md#type-classes).
+Three more kinds need Ruby to say how their values work:
+
+- a **union** or an **interface** needs to know which object type each value is;
+- a custom **scalar** needs to know how to read its values from a query and write
+  them to a response.
+
+Lighthouse answers both as [PHP Lighthouse](https://lighthouse-php.com/master/the-basics/types.html)
+does by default, and lets you take over with a class, in graphql-ruby's
+`app/graphql/types` structure, or with a directive.
+
+## Unions and interfaces
+
+```graphql
+type Query {
+  search(term: String!): [SearchResult!]!
+  latestActivity: [Authored!]!
+}
+
+union SearchResult = Post | User
+
+interface Authored {
+  id: ID!
+  author: User!
+}
+
+type Post implements Authored { id: ID! title: String! author: User! }
+type Comment implements Authored { id: ID! body: String! author: User! }
+```
+
+A resolver returns records, of any of the types:
+
+```ruby
+class Resolvers::Search < Resolvers::BaseResolver
+  def resolve(term:)
+    Post.where('title LIKE ?', "%#{term}%").to_a + User.where('name LIKE ?', "%#{term}%").to_a
+  end
+end
+```
+
+```graphql
+{
+  search(term: "Grace") {
+    __typename
+    ... on Post { title }
+    ... on User { name }
+  }
+}
+```
+
+### The default
+
+Each value resolves to the first of these that is one of the union's (or the
+interface's) types:
+
+1. a Hash's `__typename` (`{ __typename: 'Movie', title: 'Heat' }`);
+2. the type named after the value's class (a `Post` record is a `Post`), or after
+   one of its superclasses, so an `Admin < User` STI record is a `User` when no
+   `Admin` type exists;
+3. the type whose [`@model`](directives.md#model) names the value's model. With
+   `type Article @model(class: "Post")`, a `Post` record is an `Article`.
+
+Most schemas need nothing else.
+
+### A type class
+
+When the default is not enough, say when the values are Hashes from a search
+service rather than records, write the union's class as graphql-ruby does
+(`rails g graphql:union SearchResult`): `Types::<Name>Type`, with `resolve_type`.
+Its base, `Types::BaseUnion`, includes `Lighthouse::GraphQL::Type` after
+`lighthouse:install` (see [opting in](#opting-in-and-base-classes)). It returns a
+type name, or a type class, which stands for the SDL type of its `graphql_name`:
+
+```ruby
+# app/graphql/types/search_result_type.rb
+module Types
+  class SearchResultType < BaseUnion
+    def self.resolve_type(object, context)
+      return unless object.is_a?(Hash)
+
+      object['index'] == 'users' ? Types::UserType : 'Post'
+    end
+  end
+end
+```
+
+An interface's goes in graphql-ruby's `definition_methods`:
+
+```ruby
+# app/graphql/types/authored_type.rb
+module Types
+  module AuthoredType
+    include BaseInterface
+
+    definition_methods do
+      def resolve_type(object, context)
+        object['index'] == 'comments' ? 'Comment' : 'Post' if object.is_a?(Hash)
+      end
+    end
+  end
+end
+```
+
+`nil` leaves the value to the default, so the class only handles the cases that
+need it. The SDL still declares the members: `possible_types` in the class are
+ignored.
+
+### `@union` and `@interface`
+
+PHP Lighthouse's directives name the class in the schema instead. It has
+`resolve_type(object, context)` or `call(object, context)`, and is looked up in the
+types namespace (nested names too), then as written:
+
+```graphql
+union SearchResult @union(resolveType: "SearchResultResolver") = Post | User
+interface Authored @interface(resolveType: "AuthoredResolver") { id: ID! }
+```
+
+The directive comes first, then the type class, then the default.
+
+### When nothing resolves a value
+
+A value no step resolves, or one resolved to a type the union or interface does
+not include, raises `Lighthouse::DefinitionError`. It is a server bug, not a client
+error, and the message names the ways out:
+
+```text
+Lighthouse could not tell the type of a Tag in the union SearchResult (Post | User):
+name a type after its class, map one to it with @model(class: "Tag"), or resolve
+it in Types::SearchResultType.resolve_type or with @union(resolveType:).
+```
+
+A `@union` or `@interface` naming no class, or a type class of another kind than
+its SDL type (a union class for an interface), fails when the schema is built.
+
+## Scalars
+
+```graphql
+"An ISO 8601 date and time."
+scalar DateTime
+
+type Post {
+  createdAt: DateTime!
+}
+
+type Query {
+  latestActivity(since: DateTime): [Authored!]!
+}
+```
+
+Write the scalar's class with graphql-ruby's `rails g graphql:scalar DateTime`:
+`Types::<Name>Type`, a `Types::BaseScalar`, which includes `Lighthouse::GraphQL::Type`
+after `lighthouse:install`:
+
+```ruby
+# app/graphql/types/date_time_type.rb
+module Types
+  class DateTimeType < BaseScalar
+    def self.coerce_input(value, context)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      raise GraphQL::CoercionError, "#{value.inspect} is not an ISO 8601 date and time"
+    end
+
+    def self.coerce_result(value, context)
+      value.utc.iso8601
+    end
+  end
+end
+```
+
+- `coerce_input` reads an argument or variable. The resolver gets its result, here a
+  `Time`. Raising `GraphQL::CoercionError` (or returning `nil`) makes the argument
+  invalid, and the client gets the message.
+- `coerce_result` writes a value a field returns, here `Post#created_at`.
+
+`@scalar(class:)`, PHP Lighthouse's directive, names the class in the schema
+instead, looked up in the types namespace, then as written:
+
+```graphql
+scalar Money @scalar(class: "Money::GraphQLScalar")
+```
+
+A scalar with neither passes its values through unchanged. A `@scalar` naming no
+class with `coerce_input` and `coerce_result` fails when the schema is built.
+
+## Opting in, and base classes
+
+Only a class including `Lighthouse::GraphQL::Type` counts: any other
+`Types::SearchResultType` or `Types::DateTimeType` is left alone. `lighthouse:install`
+includes the concern in graphql-ruby's `Types::BaseObject`, `BaseInterface`,
+`BaseUnion` and `BaseScalar`, so every type class inheriting from them counts. In an
+app that did not run it, include the concern by hand, in those bases or in each
+class: a subclass of `GraphQL::Schema::Object`, `Union` or `Scalar`, or a module
+including `GraphQL::Schema::Interface`.
+
+The classes are looked up in [`namespaces[:types]`](configuration.md#namespaces)
+(default `['Types']`). When the schema's `base_types` name a base for a kind,
+graphql-ruby builds the SDL's types of that kind from it, and a type class of that
+kind must inherit from it, or the schema does not build:
+
+```ruby
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: {
+    base_types: {
+      object: Types::BaseObject,
+      union: Types::BaseUnion,
+      interface: Types::BaseInterface,
+      scalar: Types::BaseScalar
+      # query_type:, node:, resolver:, mutation:, ... (resolvers.md#handing-the-bases-to-the-schema)
+    }
+  }
+)
+end
+```

data/docs/uploads.md

@@ -0,0 +1,107 @@
+# File Uploads
+
+Clients send files with the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec),
+which Apollo Upload Client, urql and most GraphQL clients speak: a multipart form with
+the operation as JSON, a map of where each file goes, and the files.
+`Lighthouse::GraphQL::Controller` reads it, so the endpoint needs nothing more.
+
+## The `Upload` scalar
+
+Declare it, and use it for arguments:
+
+```graphql
+"A file sent with a multipart request."
+scalar Upload
+
+type Mutation {
+  updateAvatar(avatar: Upload!): User! @update @inject(context: "current_user.id", name: "id")
+}
+```
+
+Lighthouse reads its values itself (`Lighthouse::GraphQL::Upload`): the resolver gets
+the uploaded file, an `ActionDispatch::Http::UploadedFile`. A value that is not a file
+makes the argument invalid. `Upload` is for arguments only, never a field's result.
+
+An ActiveStorage attachment takes the file as it is: with `has_one_attached :avatar`
+on `User`, the mutation above attaches it.
+
+## `@upload`
+
+`@upload` stores the file first, and passes along what was stored instead, as PHP
+Lighthouse's `@upload` does on a Laravel disk. The file goes to your app's
+ActiveStorage, the way the rest of the app stores files:
+
+```graphql
+type Mutation {
+  updateAvatar(avatar: Upload! @upload(path: "avatars")): User!
+    @guard
+    @update
+    @inject(context: "current_user.id", name: "id")
+}
+```
+
+| | PHP Lighthouse (Laravel) | lighthouse-graphql (ActiveStorage) |
+| --- | --- | --- |
+| `disk` | a disk of `config/filesystems.php`; `filesystems.default` without it | a service of `config/storage.yml`; `config.active_storage.service` without it |
+| `path` (`"/"`) | the directory the file is stored in | the directory the blob's key starts with (`avatars/<token>`); at `"/"`, ActiveStorage's own key |
+| `public` (`false`) | the file's visibility | must agree with the service's (see below) |
+| the argument holds | the stored path | the blob's **signed id** |
+
+The signed id is what an attachment attribute attaches (`user.avatar = signed_id`) and
+`ActiveStorage::Blob.find_signed` finds; the blob keeps the file's name and content
+type. Lists of files are stored one by one, and `null` stays `null`.
+
+ActiveStorage makes a whole service public (`public: true` in `config/storage.yml`)
+or private, never one file. So `public:` must agree with the service's, and the schema
+never says a file is private that anyone can read: `@upload(public: true)` on a private
+service fails, and so does `@upload` (`public: false`) on a public one. A service
+`config/storage.yml` does not declare fails too.
+
+To store files somewhere else (S3, GCS, Azure or a service of your own), declare an
+ActiveStorage service for it and name it with `disk:`, as a Laravel app declares a disk:
+
+```yaml
+# config/storage.yml
+avatars:
+  service: S3
+  bucket: my-app-avatars
+  region: us-east-1
+  public: true
+```
+
+```graphql
+updateAvatar(avatar: Upload! @upload(disk: "avatars", path: "users", public: true)): User!
+```
+
+`@upload` runs once `@guard`, the `@can*` family and `@validator` have let the call
+through, so a refused call stores nothing.
+
+## The request
+
+```shell
+curl localhost:3000/graphql \
+  -H 'Authorization: Bearer <token>' \
+  -F operations='{ "query": "mutation($avatar: Upload!) { updateAvatar(avatar: $avatar) { avatarUrl } }", "variables": { "avatar": null } }' \
+  -F map='{ "0": ["variables.avatar"] }' \
+  -F 0=@me.png
+```
+
+A batch sends an array as `operations`, and maps files to `"0.variables.avatar"`,
+`"1.variables.files.0"`, and so on.
+
+A multipart request is also what an HTML form on another site can send. If the GraphQL
+controller authenticates with the session cookie, keep Rails' CSRF protection on it
+(`protect_from_forgery`, on by default in `ActionController::Base`) and have clients send
+the `X-CSRF-Token` header, as PHP Lighthouse has them send `X-Requested-With` for its
+`EnsureXHR` middleware. A controller that authenticates with a token header is not exposed.
+
+In a request spec:
+
+```ruby
+avatar = Rack::Test::UploadedFile.new('spec/fixtures/me.png', 'image/png')
+post '/graphql', params: {
+  operations: { query: mutation, variables: { avatar: nil } }.to_json,
+  map: { '0' => ['variables.avatar'] }.to_json,
+  '0' => avatar
+}
+```

data/lib/generators/lighthouse/base_classes.rb

@@ -3,72 +3,50 @@
 require 'rails/generators'
 require 'lighthouse-graphql'
 
-# The base class graphql-ruby's convention puts in each namespace:
-# Resolvers::BaseResolver, Mutations::BaseMutation and
-# Subscriptions::BaseSubscription. The classes Lighthouse generates inherit from
-# them, so what every class of a kind shares (a concern, graphql-ruby's base type
-# hookups) is written once, in the base. graphql-ruby's `graphql:install` writes
-# the first two the same way.
+# The base class graphql-ruby's convention puts in each namespace, which the
+# classes Lighthouse generates inherit from.
+#
+# graphql-ruby's `graphql:install` writes Resolvers::BaseResolver,
+# Mutations::BaseMutation and every Types::Base*, and `lighthouse:install`
+# builds on them: Lighthouse does not write copies of them. It writes only the
+# base graphql-ruby has none of, Subscriptions::BaseSubscription, which
+# includes Lighthouse's subscription concern.
 #
 # A base that already exists is never replaced, not even with --force: it holds
-# the app's own code, and one written by graphql-ruby works as it is.
+# the app's own code.
 module Lighthouse::Generators::BaseClasses
-  BASES = {
-    queries: {
-      name: 'BaseResolver',
-      source: <<~RUBY
-        # What every class resolving a Query field shares: Lighthouse resolves
-        # Query.latestPosts to Resolvers::LatestPosts by convention, and every such
-        # class inherits from this one. graphql-ruby's `graphql:install` writes the
-        # same class.
-        class BaseResolver < GraphQL::Schema::Resolver
-        end
-      RUBY
-    },
-    mutations: {
-      name: 'BaseMutation',
-      source: <<~RUBY
-        # What every class resolving a Mutation field shares: Lighthouse resolves
-        # Mutation.publishPost to Mutations::PublishPost by convention, and every such
-        # class inherits from this one. The SDL declares the arguments, so it is a
-        # plain GraphQL::Schema::Mutation; the GraphQL::Schema::RelayClassicMutation
-        # graphql-ruby's `graphql:install` writes (one `input:` argument) works too.
-        class BaseMutation < GraphQL::Schema::Mutation
-        end
-      RUBY
-    },
-    subscriptions: {
-      name: 'BaseSubscription',
-      source: <<~RUBY
-        # What every class resolving a Subscription field shares. The concern is PHP
-        # Lighthouse's model: every subscriber of a field gets every broadcast, and the
-        # class's `filter?` decides who receives it. A subclass that defines
-        # graphql-ruby's own `authorized?` or `update` keeps them, and `topic_by
-        # :arguments` brings back graphql-ruby's exact-argument matching.
-        class BaseSubscription < GraphQL::Schema::Subscription
-          include Lighthouse::GraphQL::Subscription
-        end
-      RUBY
-    }
+  NAMES = { subscriptions: 'BaseSubscription' }.freeze
+
+  # The bases Lighthouse writes itself, graphql-ruby having none.
+  SOURCES = {
+    subscriptions: <<~RUBY
+      # What every class resolving a Subscription field shares. The concern is PHP
+      # Lighthouse's model: every subscriber of a field gets every broadcast, and the
+      # class's `filter?` decides who receives it. A subclass that defines
+      # graphql-ruby's own `authorized?` or `update` keeps them, and `topic_by
+      # :arguments` brings back graphql-ruby's exact-argument matching.
+      class BaseSubscription < GraphQL::Schema::Subscription
+        include Lighthouse::GraphQL::Subscription
+      end
+    RUBY
   }.freeze
 
   private
 
   # The base class name for `kind` (`BaseResolver`), or nil for a kind without one.
   def base_class_name(kind)
-    BASES.dig(kind, :name)
+    NAMES[kind]
   end
 
-  # Write the base class of `kind` into `namespace`, unless its file exists.
+  # Write the base class of `kind` into `namespace` when it is missing.
   def write_base_class(kind, namespace)
-    base = BASES[kind]
-    return unless base
+    return unless base_class_name(kind)
 
     path = base_class_path(kind, namespace)
     if File.exist?(File.join(destination_root, path))
       say_status :skip, "#{path} already exists", :yellow
     else
-      create_file path, ruby_source(namespace.split('::'), base[:source])
+      create_file path, ruby_source(namespace.split('::'), SOURCES.fetch(kind))
     end
   end
 

data/lib/generators/lighthouse/install/graphql_ruby_install.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# What graphql-ruby's `graphql:install` wrote in an app, as lighthouse:install
+# reads it: where its schema class is (under app/, beside its types: --directory,
+# --schema), which of its classes exist (--relay, --skip-mutation-root-type), and
+# the parts of its templates Lighthouse takes out.
+module Lighthouse::Generators::GraphqlRubyInstall
+  # graphql-ruby's code-first root types and Node interface, by base_types key (RootTypes).
+  ROOT_TYPES = { query_type: 'QueryType', mutation_type: 'MutationType', subscription_type: 'SubscriptionType', node: 'NodeType' }.freeze
+
+  # graphql-ruby's base types, by base_types key.
+  TYPE_BASES = {
+    object: 'BaseObject', interface: 'BaseInterface', union: 'BaseUnion', scalar: 'BaseScalar',
+    enum: 'BaseEnum', input_object: 'BaseInputObject'
+  }.freeze
+
+  # Where Lighthouse::GraphQL::Type goes in graphql-ruby's base types: after the
+  # class line, or the interface's own include.
+  TYPE_CONCERN_ANCHORS = {
+    'base_object' => /^([ \t]*)class BaseObject < GraphQL::Schema::Object\n/,
+    'base_union' => /^([ \t]*)class BaseUnion < GraphQL::Schema::Union\n/,
+    'base_scalar' => /^([ \t]*)class BaseScalar < GraphQL::Schema::Scalar\n/,
+    'base_interface' => /^([ \t]*)include GraphQL::Schema::Interface\n/
+  }.freeze
+
+  # The example field graphql-ruby's install puts in each root type.
+  TEST_FIELD = /\n+[ \t]*# TODO: remove me\n[ \t]*field :test_field,.*?\n[ \t]*def test_field\n.*?\n[ \t]*end\n/m
+
+  # The `resolve_type` stub graphql-ruby's install puts in the schema class.
+  RESOLVE_TYPE_STUB = /
+    \n+[ \t]*\#\ Union\ and\ Interface\ Resolution\n
+    [ \t]*def\ self\.resolve_type\(.*?\)\n
+    (?:[ \t]*\#.*\n)*
+    [ \t]*raise\(GraphQL::RequiredImplementationMissingError\)\n
+    [ \t]*end\n
+  /x
+
+  private
+
+  # The file of graphql-ruby's schema class under app/ (--schema picks one by name), or nil.
+  def schema_path
+    @schema_path ||= Dir[File.join(destination_root, 'app', '**', '*.rb')].filter_map do |file|
+      name = schema_class_name(File.read(file))
+      file.delete_prefix("#{destination_root}/") if name && (options[:schema].nil? || name.demodulize == options[:schema].camelize)
+    end.first
+  end
+
+  def schema_class_name(source)
+    source[/^[ \t]*class (\S+) < (?:GraphQL::Schema|Lighthouse::GraphQL::RbLightHouse\.get_schema)\b/, 1] ||
+      source[/^[ \t]*(\S+) = Lighthouse::GraphQL::RbLightHouse\.get_schema\b/, 1]
+  end
+
+  def schema_name
+    schema_class_name(read(schema_path)).demodulize
+  end
+
+  def lighthouse?(source)
+    source.include?('Lighthouse::GraphQL::RbLightHouse.get_schema')
+  end
+
+  # graphql-ruby's install: its defaults, an API app's smaller stack, the name --schema gives.
+  def graphql_install_options
+    { schema: options[:schema], api: api_only? || nil }.compact
+  end
+
+  def api_only?
+    exist?('config/application.rb') && read('config/application.rb').match?(/^\s*config\.api_only\s*=\s*true/)
+  end
+
+  # graphql-ruby writes its types beside the schema class (--directory).
+  def directory
+    File.dirname(schema_path)
+  end
+
+  def types_path(file)
+    File.join(directory, 'types', file)
+  end
+
+  # Lighthouse's base_types: every class graphql-ruby's install wrote, found
+  # where it writes it, as [key, constant] pairs.
+  def base_types
+    @base_types ||= type_classes(ROOT_TYPES) + resolver_classes + type_classes(TYPE_BASES)
+  end
+
+  def type_classes(names)
+    names.filter_map { |key, name| [key, "Types::#{name}"] if exist?(types_path("#{name.underscore}.rb")) }
+  end
+
+  def resolver_classes
+    classes = { resolver: %w[resolvers BaseResolver], mutation: %w[mutations BaseMutation] }
+    classes[:subscription] = %w[subscriptions BaseSubscription] if subscription_base?
+    classes.filter_map do |key, (folder, name)|
+      [key, "#{folder.camelize}::#{name}"] if exist?(File.join(directory, folder, "#{name.underscore}.rb"))
+    end
+  end
+
+  def subscription_base?
+    options[:subscriptions] || exist?(File.join(directory, 'subscriptions', 'base_subscription.rb'))
+  end
+
+  def graphql_ruby_controller?(source)
+    source.include?('def prepare_variables(variables_param)') && source.include?('def handle_error_in_development(e)') &&
+      source.include?("#{schema_name}.execute(query, variables: variables, context: context, operation_name: operation_name)")
+  end
+
+  def read(path)
+    File.read(File.join(destination_root, path))
+  end
+
+  def exist?(path)
+    File.exist?(File.join(destination_root, path))
+  end
+end