graphql-rails 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8386088857c27bbcdea43d4891771e8bea89e8f7
-  data.tar.gz: 2bedc9fc92d44483612f9253df2dfde7ce2f8973
+  metadata.gz: 3a7c5384076b014463594f7ff514f7575c158d7e
+  data.tar.gz: ffc42b92d06723a1ea3605d1c11f2ccb2fd1f880
 SHA512:
-  metadata.gz: df543107f1fa308fb2228f7951b70ac28c263f0aea93024d121dfcf093d75e515b146bd71655fc0e6e23beb548924d28c7700284833c3f8725b4c573c8c2eec7
-  data.tar.gz: 06057d2317334ed33e8a16e4f7f35e9b6f8209c2f8207ae03c57421a1f28a3b076879f2fd924e74ac76828caf07b6c875b1feae2b8de7efd32d5545cc12f05b2
+  metadata.gz: ba44e7314732609e798b8bff7bbf931f26673af2aa835c5af3e65be9fa35a230c66f79c2ce2e0a2b2d854e7892029268ac15ead3ebb78bbb8a475ff1d4903068
+  data.tar.gz: 25341849de64f37b1691a3735749a695a8769eaf6c3076aa1249fe7797d7939dda2e10d36c1d0a9229484627f3483de58cdab6a3f3a78cc12b8a45014577cd9b

data/app/controllers/graphql/rails/schema_controller.rb

@@ -1,19 +1,23 @@
 module GraphQL
   module Rails
     class SchemaController < ActionController::Base
+      # Extensions are dynamically loaded once during engine initialization;
+      # however, this controller can be reloaded at any time by Rails. To
+      # preserve extensions, we use the ControllerExtensions module as a cache.
       include ControllerExtensions
+
+      # Defined in order of increasing specificity.
       rescue_from Exception, :with => :internal_error
       rescue_from GraphQL::ParseError, :with => :invalid_query
       rescue_from JSON::ParserError, :with => :invalid_variables
 
+      # Execute a GraphQL query against the current schema.
       def execute
-        query_string = params[:query]
-        query_variables = to_hash(params[:variables])
         render json: Schema.instance.execute(
-          query_string,
-          variables: query_variables,
+          params[:query],
+          variables: to_hash(params[:variables]),
           context: context,
-          debug: true
+          debug: Rails.config.debug
         )
       end
 
@@ -51,7 +55,9 @@ module GraphQL
         invalid_request 'Unable to parse variables'
       end
 
-      def internal_error
+      def internal_error(e)
+        Rails.logger.error 'Unexpected exception during execution'
+        Rails.logger.exception e
         render_error 500, 'Internal error'
       end
     end

data/config/initializers/graphiql.rb

@@ -1 +1,3 @@
+# There is no apparent harm to enabling CSRF token-passing for GraphiQL, even
+# if the Rails app doesn't use CSRF protection.
 GraphiQL::Rails.config.csrf = true

data/lib/graphql/rails.rb

@@ -3,14 +3,16 @@ require 'graphql'
 require 'graphql/relay'
 require 'graphiql/rails'
 
+# Order dependent.
+
 require 'graphql/rails/version'
-require 'graphql/rails/dsl'
-require 'graphql/rails/engine'
-require 'graphql/rails/config'
 require 'graphql/rails/config'
+require 'graphql/rails/engine'
+
+require 'graphql/rails/dsl'
 require 'graphql/rails/types'
-require 'graphql/rails/node_identification'
-require 'graphql/rails/controller_extensions'
 require 'graphql/rails/schema'
 require 'graphql/rails/callbacks'
 require 'graphql/rails/operations'
+require 'graphql/rails/node_identification'
+require 'graphql/rails/controller_extensions'

data/lib/graphql/rails/callbacks.rb

@@ -1,19 +1,27 @@
 module GraphQL
   module Rails
     class Operations
+      # Implement callback methods on Operations.
+      # These are akin to the 'filters' available on ActionController::Base.
+      # http://api.rubyonrails.org/classes/AbstractController/Callbacks.html
       module Callbacks
         extend ActiveSupport::Concern
         include ActiveSupport::Callbacks
 
+        # All callbacks are registered under the :perform_operation event.
         included do
           define_callbacks :perform_operation
         end
 
         module ClassMethods
+          # Callbacks can be registered with the following methods:
+          # before_operation, before_filter
+          # around_operation, around_filter
+          # after_operation, after_filter
           [:before, :after, :around].each do |callback|
-            define_method "#{callback}_operation" do |*names, &blk|
-              insert_callbacks(names, blk) do |name, options|
-                set_callback(:perform_operation, callback, name, options)
+            define_method "#{callback}_operation" do |*names, &block|
+              insert_callbacks(names, block) do |target, options|
+                set_callback :perform_operation, callback, target, options
               end
             end
             alias_method :"#{callback}_filter", :"#{callback}_operation"
@@ -21,11 +29,13 @@ module GraphQL
 
           private
 
+          # Convert :only and :except options into :if and :unless blocks.
           def normalize_callback_options(options)
             normalize_callback_option(options, :only, :if)
             normalize_callback_option(options, :except, :unless)
           end
 
+          # Convert an operation name-based condition into an executable block.
           def normalize_callback_option(options, from, to)
             return unless options[from]
             check = -> do
@@ -34,6 +44,7 @@ module GraphQL
             options[to] = Array(options[to]) + [check]
           end
 
+          # Normalize the arguments passed during callback registration.
           def insert_callbacks(callbacks, block = nil)
             options = callbacks.extract_options!
             normalize_callback_options(options)

data/lib/graphql/rails/config.rb

@@ -2,12 +2,17 @@ module GraphQL
   module Rails
     extend self
 
+    # Yields the configuration object to a block, per convention.
     def configure
       yield config
     end
 
+    # Configuration for this gem.
     def config
       @config ||= OpenStruct.new({
+        # Should graphql-ruby be placed into debug mode?
+        :debug => ::Rails.env.development?,
+
         # Should the GraphiQL web interface be served?
         :graphiql => ::Rails.env.development?,
 
@@ -19,6 +24,10 @@ module GraphQL
         # This is necessary to conform to the Relay Global Object ID spec.
         :global_ids => true,
 
+        # Maximum nesting for GraphQL queries.
+        # Specify nil for unlimited nesting depth.
+        :max_depth => 8,
+
         # Should the following extensions be loaded?
         :mongoid => defined?(::Mongoid),
         :cancan => defined?(::CanCan),

data/lib/graphql/rails/controller_extensions.rb

@@ -1,22 +1,25 @@
 module GraphQL
   module Rails
+    # Extensions are dynamically loaded once during engine initialization;
+    # however, SchemaController can be reloaded at any time by Rails. To
+    # preserve extensions to SchemaController, they're registered here.
     module ControllerExtensions
       extend self
 
       def add(&block)
-        callbacks.push block
+        extensions.push block
       end
 
       def included(base)
-        callbacks.each do |callback|
-          base.class_eval(&callback)
+        extensions.each do |extensions|
+          base.class_eval(&extensions)
         end
       end
 
       private
 
-      def callbacks
-        @callbacks ||= []
+      def extensions
+        @extensions ||= []
       end
     end
   end

data/lib/graphql/rails/dsl.rb

@@ -1,5 +1,12 @@
 module GraphQL
   module Rails
+    # Object that runs a block in the context of itself, but delegates unknown
+    # methods back to the block's original context. This is useful for creating
+    # DSLs to aid with object initialization.
+    #
+    # Note that this class extends from BasicObject, which means that _all_
+    # global classes and modules must be prefixed by a double-colon (::) in
+    # order to resolve.
     class DSL < BasicObject
       def run(&block)
         @self = eval('self', block.binding)

data/lib/graphql/rails/engine.rb

@@ -11,10 +11,10 @@ module GraphQL
     class Engine < ::Rails::Engine
       isolate_namespace GraphQL::Rails
 
+      # Even though we aren't using symbolic autoloading of operations, they
+      # must be included in autoload_paths in order to be unloaded during
+      # reload operations.
       initializer 'graphql-rails.autoload', :before => :set_autoload_paths do |app|
-        # Even though we aren't using symbolic autoloading of operations, they
-        # must be included in autoload_paths in order to be unloaded during
-        # reload operations.
         @graph_path = app.root.join('app', 'graph')
         app.config.autoload_paths += [
           @graph_path.join('types'),
@@ -22,6 +22,7 @@ module GraphQL
         ]
       end
 
+      # Extend the Rails logger with a facility for logging exceptions.
       initializer 'graphql-rails.logger', :after => :initialize_logger do |app|
         logger = ::Rails.logger.clone
         logger.class_eval do
@@ -37,14 +38,16 @@ module GraphQL
         Rails.logger.debug 'Initialized logger'
       end
 
+      # Extensions depend upon a loaded Rails app, so we load them dynamically.
       initializer 'graphql-rails.extensions', :after => :load_config_initializers do |app|
-        # These depend upon a loaded Rails app, so we load them dynamically.
         extensions = File.join(File.dirname(__FILE__), 'extensions', '*.rb')
         Dir[extensions].each do |file|
           require file
         end
       end
 
+      # Hook into Rails reloading in order to clear state from internal
+      # stateful modules and reload operations from the Rails app.
       initializer 'graphql-rails.prepare', :before => :add_to_prepare_blocks do
         # The block executes in the context of the reloader, so we have to
         # preserve a reference to the engine instance.
@@ -54,6 +57,7 @@ module GraphQL
         end
       end
 
+      # Clear state and load operations from the Rails app.
       def reload!
         Types.clear
         Schema.clear

data/lib/graphql/rails/extensions/cancan.rb

@@ -3,6 +3,8 @@ module GraphQL
     if Rails.config.cancan
       Rails.logger.debug 'Loading CanCan extensions'
 
+      # Implement methods from CanCan::ControllerAdditions in Operations.
+      # http://www.rubydoc.info/github/ryanb/cancan/CanCan/ControllerAdditions
       Operations.class_eval do
         extend Forwardable
         def_delegators :current_ability, :can?, :cannot?
@@ -26,7 +28,7 @@ module GraphQL
           begin
             @authorized = true
             current_ability.authorize!(*args)
-          rescue CanCan::AccessDenied
+          rescue ::CanCan::AccessDenied
             raise 'You are not authorized to perform this operation'
           end
         end
@@ -36,10 +38,12 @@ module GraphQL
         end
 
         def current_user
-          ctx[:current_user]
+          context[:current_user]
         end
       end
 
+      # Make the current_user available during GraphQL execution via the
+      # operation context object.
       ControllerExtensions.add do
         before_filter do
           context[:current_user] = current_user

data/lib/graphql/rails/extensions/mongoid.rb

@@ -3,26 +3,30 @@ module GraphQL
     if Rails.config.mongoid
       Rails.logger.debug 'Loading Mongoid extensions'
 
+      # Use the built-in RelationConnection to handle Mongoid relations.
       GraphQL::Relay::BaseConnection.register_connection_implementation(
         ::Mongoid::Relations::Targets::Enumerable,
         GraphQL::Relay::RelationConnection
       )
 
+      # Mongoid type extension for the GraphQL type system.
       module Mongoid
         extend self
 
-        NAMESPACE = 'MG'
-
+        # Clear internal state, probably due to a Rails reload.
         def clear
           @types = nil
         end
 
+        # Resolve an arbitrary type to a GraphQL type.
+        # Returns nil if the type isn't a Mongoid document.
         def resolve(type)
           types[type] || build_type(type)
         end
 
+        # Lookup an arbitrary object from its GraphQL type name and ID.
         def lookup(type_name, id)
-          return if Types.use_namespaces? && !type_name.starts_with?(NAMESPACE)
+          return unless type_name.starts_with?(namespace)
           types.each_pair do |type, graph_type|
             return type.find(id) if graph_type.name == type_name
           end
@@ -31,6 +35,17 @@ module GraphQL
 
         private
 
+        # Namespace for Mongoid types, if namespaces are required.
+        def namespace
+          if Types.use_namespaces?
+            'MG'
+          else
+            ''
+          end
+        end
+
+        # Cached mapping of Mongoid types to GraphQL types, initialized with
+        # mappings for common built-in scalar types.
         def types
           @types ||= {
             ::Mongoid::Boolean => GraphQL::BOOLEAN_TYPE,
@@ -38,27 +53,35 @@ module GraphQL
           }
         end
 
+        # Build a GraphQL type for a Mongoid document.
+        # Returns nil if the type isn't a Mongoid document.
         def build_type(type)
           return nil unless type.included_modules.include?(::Mongoid::Document)
           Rails.logger.debug "Building Mongoid::Document type: #{type.name}"
 
-          # TODO: Support parent types/interfaces.
-          type_name = to_name(type)
+          # Build and cache the GraphQL type.
+          # TODO: Map type inheritance to GraphQL interfaces.
+          type_name = Types.to_type_name(type.name, namespace)
           types[type] = GraphQL::ObjectType.define do
             name type_name
 
+            # Add the global node ID, if enabled.
             if Rails.config.global_ids
               interfaces [NodeIdentification.interface]
               global_id_field :id
             end
 
+            # Add each field from the document.
+            # TODO: Support field exclusion and renaming.
             type.fields.each_value do |field_value|
-              field field_value.name do
+              field Types.to_field_name(field_value.name) do
+                property field_value.name.to_sym
                 type -> { Types.resolve(field_value.type) }
                 description field_value.label unless field_value.label.blank?
               end
             end
 
+            # Add each relationship from the document as a Relay connection.
             type.relations.each_value do |relationship|
               # TODO: Add polymorphic support.
               if relationship.polymorphic?
@@ -69,25 +92,17 @@ module GraphQL
               end
 
               if relationship.many?
-                connection relationship.name do
+                connection Types.to_field_name(relationship.name) do
                   type -> { Types.resolve(relationship.klass).connection_type }
                 end
               else
-                field relationship.name do
+                field Types.to_field_name(relationship.name) do
                   type -> { Types.resolve(relationship.klass) }
                 end
               end
             end
           end
         end
-
-        def to_name(type)
-          if Types.use_namespaces?
-            NAMESPACE + type.name
-          else
-            type.name
-          end
-        end
       end
 
       Types.add_extension Mongoid

data/lib/graphql/rails/node_identification.rb

@@ -1,5 +1,6 @@
 module GraphQL
   module Rails
+    # Implements globally-unique object IDs for Relay compatibility.
     NodeIdentification = GraphQL::Relay::GlobalNodeIdentification.define do
       object_from_id -> (id, ctx) do
         Types.lookup(*NodeIdentification.from_global_id(id))

data/lib/graphql/rails/operations.rb

@@ -1,9 +1,16 @@
 module GraphQL
   module Rails
+    # Base type for operations classes in the Rails app.
+    # Operations are specified in a manner similar to controller actions, and
+    # can access variables and state localized to the current operation.
+    # Classes can define callbacks similar to controller 'filters'.
     class Operations
       extend Forwardable
       include Callbacks
 
+      # Initialize an instance with state pertaining to the current operation.
+      # Accessors for this state are created and proxied through to the
+      # specified options hash.
       def initialize(options = {})
         @options = OpenStruct.new(options)
         self.class.instance_eval do
@@ -11,9 +18,21 @@ module GraphQL
         end
       end
 
+      # Define a query operation.
+      # Definitions should have the following form:
+      #
+      #   query :find_cats => [Cat] do
+      #     description 'This query returns a list of Cat models'
+      #     argument :age, Integer, :required
+      #     argument :breed, String
+      #     resolve do
+      #       raise 'Too old' if args[:age] > 20
+      #       Cat.find(age: args[:age], breed: args[:breed])
+      #     end
+      #   end
       def self.query(hash, &block)
         hash = extract_pair(hash)
-        Rails.logger.debug "Adding query: #{to_name(hash[:name])}"
+        Rails.logger.debug "Adding query: #{Types.to_field_name(hash[:name])}"
 
         definition = QueryDefinition.new(self)
         definition.run(&block)
@@ -25,26 +44,10 @@ module GraphQL
       end
 
       # TODO: Implement mutations and subscriptions.
-      # TODO: Implement model functions (only, exclude, rename, etc.)
 
       private
 
-      def self.extract_pair(hash)
-        unless hash.length == 1
-          raise 'Hash must contain a single :name => Type pair.'
-        end
-        {name: hash.keys.first, type: hash.values.first}
-      end
-
-      # TODO: Ensure consistent naming convention around everything.
-      def self.to_name(symbol)
-        if Rails.config.camel_case
-          symbol.to_s.camelize(:lower)
-        else
-          symbol.to_s
-        end
-      end
-
+      # DSL for query definition.
       class QueryDefinition < DSL
         attr_reader :field
 
@@ -55,7 +58,7 @@ module GraphQL
 
         def name(name)
           @name = name
-          @field.name = to_name(name)
+          @field.name = Types.to_field_name(name)
         end
 
         def type(type)
@@ -69,25 +72,30 @@ module GraphQL
 
         def argument(name, type, required = false)
           argument = ::GraphQL::Argument.new
-          argument.name = to_name(name)
+          argument.name = Types.to_field_name(name)
           argument.type = Types.resolve(type, required == :required)
           @field.arguments[argument.name] = argument
         end
 
         def resolve(&block)
           field.resolve = -> (obj, args, ctx) do
+            # Instantiate the Operations class with state on this query.
             instance = @klass.new({
               op: :query, name: @name, type: @type,
-              obj: obj, args: args, ctx: ctx
+              obj: obj, args: args, ctx: ctx, context: ctx
             })
 
             begin
+              # Run callbacks for this Operations class.
               instance.run_callbacks(:perform_operation) do
+                # Call out to the app-defined resolver.
                 instance.instance_eval(&block)
               end
             rescue => e
+              # Surface messages from standard errors in GraphQL response.
               ::GraphQL::ExecutionError.new(e.message)
             rescue ::Exception => e
+              # Log and genericize other runtime errors.
               Rails.logger.error "Unexpected exception during query: #{@name}"
               Rails.logger.exception e
               ::GraphQL::ExecutionError.new('Internal error')
@@ -95,6 +103,14 @@ module GraphQL
           end
         end
       end
+
+      # Extract parts from a hash passed to the operation definition DSL.
+      def self.extract_pair(hash)
+        unless hash.length == 1
+          raise 'Hash must contain a single :name => Type pair.'
+        end
+        {name: hash.keys.first, type: hash.values.first}
+      end
     end
   end
 end

data/lib/graphql/rails/schema.rb

@@ -1,8 +1,11 @@
 module GraphQL
   module Rails
+    # Defines the GraphQL schema, consisting of
+    # queries, mutations, and subscriptions.
     module Schema
       extend self
 
+      # Clear internal state, probably due to a Rails reload.
       def clear
         @schema = nil
         @fields = Hash.new { |hash, key| hash[key] = [] }
@@ -10,6 +13,7 @@ module GraphQL
 
       TYPES = [:query, :mutation, :subscription]
 
+      # Register a field in the GraphQL schema.
       TYPES.each do |type|
         define_method "add_#{type.to_s}" do |field|
           @schema = nil # Invalidate cached schema.
@@ -17,19 +21,23 @@ module GraphQL
         end
       end
 
+      # Lazily build the GraphQL schema instance.
       def instance
-        # TODO: Support max_depth and types.
-        # TODO: Sweep available options and expose in config.
         @schema ||= GraphQL::Schema.new begin
-          TYPES.reduce({}) do |schema, type|
+          TYPES.reduce({
+            max_depth: Rails.config.max_depth,
+          }) do |schema, type|
             fields = @fields[type]
             unless fields.empty?
+              # Build an object for each operation type.
               schema[type] = GraphQL::ObjectType.define do
                 name type.to_s.capitalize
                 description "Root #{type.to_s} for this schema"
+                # Add a field for each operation.
                 fields.each do |value|
                   field value.name, field: value
                 end
+                # Add the global node ID lookup query.
                 if Rails.config.global_ids && type == :query
                   field :node, field: NodeIdentification.field
                 end

data/lib/graphql/rails/types.rb

@@ -1,8 +1,11 @@
 module GraphQL
   module Rails
+    # Type system responsible for resolving GraphQL types.
+    # Delegates creation of GraphQL types to ORM-specific extensions.
     module Types
       extend self
 
+      # Clear internal state, probably due to a Rails reload.
       def clear
         @types = nil
         extensions.each do |extension|
@@ -11,23 +14,25 @@ module GraphQL
       end
 
       # Resolve an arbitrary type to a GraphQL type.
+      # Lists can be specified with single-element arrays; for example:
+      # [String] resolves to a list of GraphQL::STRING_TYPE objects.
       def resolve(type, required = false)
         if type.nil?
-          raise 'Cannot resolve nil type.'
+          raise 'Cannot resolve nil type'
         elsif required
           resolve(type).to_non_null_type
         elsif type.is_a?(GraphQL::BaseType)
           type
         elsif type.is_a?(Array)
           unless type.length == 1
-            raise 'Lists must be specified with single-element arrays.'
+            raise 'Lists must be specified with single-element arrays'
           end
           resolve(type.first).to_list_type
         elsif types.include?(type)
           resolve(types[type])
         else
           resolve(try_extensions(:resolve, type) || begin
-            # TODO: Remove this hack.
+            # TODO: Decide whether to use String as a fallback, or raise.
             Rails.logger.warn "Unable to resolve type: #{type.name}"
             String
           end)
@@ -52,6 +57,29 @@ module GraphQL
         extensions.push extension
       end
 
+      # Convert a type name to a string with the correct convention,
+      # applying an optional namespace.
+      def to_type_name(name, namespace = '')
+        return namespace + to_type_name(name) unless namespace.blank?
+        if Rails.config.camel_case
+          name.to_s.camelize(:upper)
+        else
+          name.to_s
+        end
+      end
+
+      # Convert a field name to a string with the correct convention.
+      def to_field_name(name)
+        # camelize strips leading underscores, which is undesirable.
+        if name.to_s.starts_with?('_')
+          "_#{to_field_name(name.to_s[1..-1])}"
+        elsif Rails.config.camel_case
+          name.to_s.camelize(:lower)
+        else
+          name.to_s
+        end
+      end
+
       private
 
       # Default mapping of built-in scalar types to GraphQL types.
@@ -74,6 +102,7 @@ module GraphQL
         }
       end
 
+      # List of registered extensions.
       def extensions
         @extensions ||= []
       end

data/lib/graphql/rails/version.rb

@@ -1,5 +1,5 @@
 module GraphQL
   module Rails
-    VERSION = '0.0.1'
+    VERSION = '0.0.2'
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: graphql-rails
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - James Reggio
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-07 00:00:00.000000000 Z
+date: 2016-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -67,13 +67,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.2'
 description: |
-  Zero-configuration GraphQL + Relay support for Rails.
-
-  - Adds a route to process GraphQL operations.
-  - Provides a visual editor (GraphiQL) for development.
-  - Allows you to specify GraphQL queries and mutations as though they were controller actions.
-  - Automatically maps Mongoid models to GraphQL types.
-  - Seamlessly integrates with CanCan.
+  Zero-configuration GraphQL + Relay support for Rails. Adds a route to process
+  GraphQL operations and provides a visual editor (GraphiQL) during development.
+  Allows you to specify GraphQL queries and mutations as though they were
+  controller actions. Automatically maps Mongoid models to GraphQL types.
+  Seamlessly integrates with CanCan.
 email:
 - james.reggio@gmail.com
 executables: []
@@ -110,7 +108,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - '>='