lighthouse-graphql 0.5.0 → 0.6.0

data/docs/security.md

@@ -10,20 +10,24 @@ Lighthouse works the same way on top of webonyx's validation rules.
 
 ## Setting the limits
 
-The limits are graphql-ruby's own schema settings. Set them on the schema
-Lighthouse builds:
+The limits are graphql-ruby's own schema settings. Set them in the body of the
+schema class, as in any graphql-ruby schema (graphql-ruby's install writes
+`max_depth(15)` there):
 
 ```ruby
 # app/graphql/app_schema.rb
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(options: { using: { GraphQL::Dataloader => {} } })
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: { object: Types::BaseObject } })
+  use GraphQL::Dataloader
 
-AppSchema.max_complexity(300)   # refuse queries that score over 300
-AppSchema.max_depth(12)         # refuse queries nested deeper than 12 fields
-AppSchema.disable_introspection_entry_points if Rails.env.production?
+  max_complexity(300)   # refuse queries that score over 300
+  max_depth(12)         # refuse queries nested deeper than 12 fields
+  disable_introspection_entry_points if Rails.env.production?
+end
 ```
 
-You can also set them on a base schema class you hand to `get_schema` with
-`options: { base_schema: MyBaseSchema }`.
+A schema assigned to a constant (`AppSchema = get_schema(...)`) takes them as calls
+on it (`AppSchema.max_complexity(300)`). You can also set them on a base schema class
+you hand to `get_schema` with `options: { base_schema: MyBaseSchema }`.
 
 A query over the limit isn't executed. Its response holds only the error:
 
@@ -211,17 +215,61 @@ GraphQL::Analysis.analyze_query(query, [GraphQL::Analysis::QueryComplexity]).fir
 
 ## Rate limiting
 
-[`@throttle`](directives.md#throttle) caps how often one client may call a field —
-a login, a search, an expensive mutation:
+Rails' own [`rate_limit`](https://api.rubyonrails.org/classes/ActionController/RateLimiting/ClassMethods.html)
+limits the endpoint: every operation counts, and past the limit Rails answers 429.
+[`@throttle`](directives.md#throttle) is the same limit on one field — a login, a search,
+an expensive mutation — beside it:
+
+```ruby
+class GraphqlController < ApplicationController
+  include Lighthouse::GraphQL::Controller
+
+  lighthouse_schema AppSchema
+  rate_limit to: 600, within: 1.minute, name: 'endpoint'
+
+  private
+
+  def too_many_requests
+    render json: { errors: [{ message: 'Too many requests. Try again later.' }] }, status: :too_many_requests
+  end
+end
+```
 
 ```graphql
 type Mutation {
-  login(email: String!, password: String!): User @throttle(maxAttempts: 5, decayMinutes: 1)
+  login(email: String!, password: String!): User @throttle(maxAttempts: 5)
+  createTag(name: String!): Tag! @throttle(maxAttempts: 20, by: "current_user.id", with: "too_many_requests") @guard @create
 }
 ```
 
-Attempts are counted in [`cache_store`](configuration.md#cache_store), so use a store
-the app servers share (Redis, Solid Cache) in production; `:null_store` counts
-nothing. A client is the signed-in user, else the `:remote_ip` the controller concern
-puts in the context (override `graphql_context` to set another). A refused call never
-reaches `@guard` or the resolver.
+`@throttle` counts as `rate_limit` does, under its key (`rate-limit:<scope>:<name>:<by>`):
+
+- **Where.** In the controller's `cache_store`: `config.action_controller.cache_store`,
+  or `Rails.cache` when the app sets none (a controller can set its own with
+  `self.cache_store =`). Use a store the app servers share (Redis, Solid Cache) in
+  production; `:null_store` counts nothing.
+- **Who.** The client's IP, as `rate_limit`'s default. `by:` reads another value off the
+  context, as `@inject` does (`by: "current_user.id"`); when it is `nil`, as for a guest,
+  those calls count together, as in Rails.
+- **What counts together.** Each field counts under its own name (`Query.login`), apart
+  from the endpoint's `rate_limit` (`endpoint`). Give fields, or a field and a
+  controller's `rate_limit`, the same `name:` to count them together; `prefix:` is
+  `rate_limit`'s `scope:` (the controller's path by default).
+- **Past the limit.** As `rate_limit`'s default, `ActionController::TooManyRequests` is
+  raised, and Rails answers the request with a 429 (in development too); on Rails 7.2,
+  which has no such error, `head :too_many_requests`. With `with:`, the controller's
+  method runs instead, as `rate_limit`'s `with:`. If it renders or redirects, the request
+  ends with that response and the operation stops there, as when a `before_action`
+  renders. If it returns, the call goes through. If it raises a `GraphQL::ExecutionError`,
+  only that field fails, and the rest of the operation is answered:
+
+  ```ruby
+  def rate_limited = raise(GraphQL::ExecutionError, 'Too many requests. Try again later.')
+  ```
+
+  Without Action Pack, the field fails (`Rate limit for Query.x exceeded. Try again later.`).
+- **Instrumentation.** Each refused call is a `rate_limit.action_controller` event, with
+  `rate_limit`'s payload (`request`, `count`, `to`, `within`, `by`, `name`, `scope`,
+  `cache_key`).
+
+A refused call never reaches `@guard` or the resolver.

data/docs/subscriptions.md

@@ -38,18 +38,24 @@ end
 
 graphql-ruby delivers subscriptions through a *backend* that stores who subscribed
 and sends the updates: ActionCable (bundled), or a gem such as Pusher or Ably.
-Lighthouse needs none of its own; give the schema one. `get_schema` passes the
-`using:` option to graphql-ruby, as `use` does in a class-based schema:
+Lighthouse needs none of its own; give the schema one with `use`, in the schema
+class body, as in any graphql-ruby schema:
 
 ```ruby
 # app/graphql/app_schema.rb
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-  options: { using: { GraphQL::Subscriptions::ActionCableSubscriptions => {} } }
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: { base_types: { subscription: Subscriptions::BaseSubscription } }   # and the other bases
 )
+  use GraphQL::Dataloader
+  use GraphQL::Subscriptions::ActionCableSubscriptions
+end
 ```
 
-Options of the backend go in the hash (`{ ActionCableSubscriptions => { namespace: 'my-app' } }`).
-Assign the schema to a constant: a [queued](#queueing) broadcast finds it by name.
+Options of the backend go after it (`use GraphQL::Subscriptions::ActionCableSubscriptions, namespace: 'my-app'`).
+A schema assigned to a constant instead (`AppSchema = get_schema(...)`) takes the
+backend through the `using:` option, as `use` does:
+`options: { using: { GraphQL::Subscriptions::ActionCableSubscriptions => {} } }`.
+Either way the schema has a name, which a [queued](#queueing) broadcast finds it by.
 
 Then add the channel graphql-ruby documents, which runs the operation and keeps
 the client's subscription ids ([the full example](https://graphql-ruby.org/subscriptions/action_cable_implementation.html)):
@@ -182,7 +188,7 @@ the base every subscription inherits from, as graphql-ruby's convention puts wha
 all classes of a kind share in their base:
 
 ```ruby
-# app/graphql/subscriptions/base_subscription.rb  (rails generate lighthouse:install)
+# app/graphql/subscriptions/base_subscription.rb  (rails generate lighthouse:install --subscriptions)
 module Subscriptions
   class BaseSubscription < GraphQL::Schema::Subscription
     include Lighthouse::GraphQL::Subscription
@@ -411,8 +417,9 @@ end
 
 The job carries the schema's name, the subscription's name, the trigger arguments,
 the scope and the root; an Active Record model is serialized with GlobalID, any
-other root must be something ActiveJob can serialize. A schema built by
-`get_schema` and assigned to a constant (`AppSchema = ...`) has the name; an
+other root must be something ActiveJob can serialize. A schema class
+(`class AppSchema < ...get_schema(...)`), or a schema assigned to a constant
+(`AppSchema = ...`), has the name; an
 anonymous one raises `Lighthouse::DefinitionError` when a queued broadcast needs
 it. The `activejob` gem is optional: nothing loads it unless a broadcast is queued.
 

data/docs/types.md

@@ -69,17 +69,15 @@ Most schemas need nothing else.
 
 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` including `Lighthouse::GraphQL::Type`, with `resolve_type`.
-It returns a type name, or a type class, which stands for the SDL type of its
-`graphql_name`:
+(`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
-    include Lighthouse::GraphQL::Type
-
     def self.resolve_type(object, context)
       return unless object.is_a?(Hash)
 
@@ -96,7 +94,6 @@ An interface's goes in graphql-ruby's `definition_methods`:
 module Types
   module AuthoredType
     include BaseInterface
-    include Lighthouse::GraphQL::Type
 
     definition_methods do
       def resolve_type(object, context)
@@ -154,15 +151,14 @@ type Query {
 }
 ```
 
-Write the scalar's class with graphql-ruby's `rails g graphql:scalar DateTime`,
-`Types::<Name>Type` including `Lighthouse::GraphQL::Type`:
+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
-    include Lighthouse::GraphQL::Type
-
     def self.coerce_input(value, context)
       Time.iso8601(value.to_s)
     rescue ArgumentError
@@ -194,10 +190,12 @@ 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`, such as the ones a graphql-ruby
-app already has, is left alone. The concern can be included in a subclass of
-`GraphQL::Schema::Object`, `Union` or `Scalar`, or in a module including
-`GraphQL::Schema::Interface`.
+`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,
@@ -205,15 +203,16 @@ graphql-ruby builds the SDL's types of that kind from it, and a type class of th
 kind must inherit from it, or the schema does not build:
 
 ```ruby
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
   options: {
     base_types: {
       object: Types::BaseObject,
       union: Types::BaseUnion,
       interface: Types::BaseInterface,
       scalar: Types::BaseScalar
-      # resolver:, mutation:, subscription: (resolvers.md#handing-the-bases-to-the-schema)
+      # query_type:, node:, resolver:, mutation:, ... (resolvers.md#handing-the-bases-to-the-schema)
     }
   }
 )
+end
 ```

data/docs/uploads.md

@@ -27,7 +27,9 @@ on `User`, the mutation above attaches it.
 
 ## `@upload`
 
-`@upload` stores the file first, and passes along what was stored instead:
+`@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 {
@@ -38,23 +40,42 @@ type Mutation {
 }
 ```
 
-By default the file becomes an ActiveStorage blob: on the service `disk:` names (the
-default service without it), with its key under `path:`. The argument then holds the
-blob's **signed id**, which an attachment attribute attaches (`user.avatar = signed_id`)
-and `ActiveStorage::Blob.find_signed` finds. Lists of files are stored one by one.
+| | 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.
 
-To store files elsewhere, give [`upload_store`](configuration.md#upload_store) an
-object with `call(file, disk:, path:, public:)`; the argument holds what it returns:
-
-```ruby
-Lighthouse.configure do |config|
-  config.upload_store = ->(file, path: '/', **) { S3Uploader.put(file, prefix: path) }   # returns the key
-end
-```
-
 ## The request
 
 ```shell
@@ -68,6 +89,12 @@ curl localhost:3000/graphql \
 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

data/lib/generators/lighthouse/base_classes.rb

@@ -4,19 +4,18 @@ require 'rails/generators'
 require 'lighthouse-graphql'
 
 # The base class graphql-ruby's convention puts in each namespace, which the
-# classes Lighthouse generates inherit from: Resolvers::BaseResolver,
-# Mutations::BaseMutation and Subscriptions::BaseSubscription.
+# classes Lighthouse generates inherit from.
 #
-# graphql-ruby's `graphql:install` writes the first two (and every Types::Base*),
-# and `lighthouse:install` runs it: Lighthouse does not write copies of them. It
-# writes only the base graphql-ruby has none of, BaseSubscription, which
-# includes Lighthouse's subscription concern. A generator that finds a base
-# missing says how to get it.
+# 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.
 module Lighthouse::Generators::BaseClasses
-  NAMES = { queries: 'BaseResolver', mutations: 'BaseMutation', subscriptions: 'BaseSubscription' }.freeze
+  NAMES = { subscriptions: 'BaseSubscription' }.freeze
 
   # The bases Lighthouse writes itself, graphql-ruby having none.
   SOURCES = {
@@ -39,19 +38,15 @@ module Lighthouse::Generators::BaseClasses
     NAMES[kind]
   end
 
-  # Write the base class of `kind` into `namespace` when Lighthouse owns it and
-  # it is missing; say how to get one graphql-ruby owns.
+  # Write the base class of `kind` into `namespace` when it is missing.
   def write_base_class(kind, namespace)
     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
-    elsif SOURCES[kind]
-      create_file path, ruby_source(namespace.split('::'), SOURCES[kind])
     else
-      say_status :missing, "#{path}: graphql-ruby writes it — run `bin/rails g lighthouse:install` (which runs graphql:install), " \
-                           "or write #{namespace}::#{base_class_name(kind)} yourself", :red
+      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