apollo-federation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 446efb9b173791b74a0bfc8b6dff598f2540517b30fdcf3425a0b332303bf1f6
+  data.tar.gz: e7ddcd984c0ce2d9573b98459006577478bbdb5cc5347f6198eba17b5aae5494
+SHA512:
+  metadata.gz: f1978c886ed68a721c277c6589c8890445480a85998120f7454b40f45144afebb63f55ba8425473e1d04a82c39e1005639b368c5cd90d0cf5d0138a1180fb0a2
+  data.tar.gz: 811f1c1eaf17c1c4a795b6bd1bce88a95cb2699d0e4d54e3dc152a04702f340e25b4af158de14f9d5e954d564a6693d048df7ff76ac93571abac8d00f894529e

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0 (Jun 21, 2019)
+
+* First release

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Gusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# apollo-federation
+
+This gem extends the [GraphQL Ruby](http://graphql-ruby.org/) gem to add support for creating an [Apollo Federation](https://www.apollographql.com/docs/apollo-server/federation/introduction/) schema.
+
+## DISCLAIMER
+
+This gem is still in a beta stage and may have some bugs or incompatibilities. See the [Known Issues and Limitations](#known-issues-and-limitations) below. If you run into any problems, please [file an issue](https://github.com/Gusto/apollo-federation-ruby/issues).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'apollo-federation'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install apollo-federation
+
+## Getting Started
+
+Include the `ApolloFederation::Field` module in your base field class:
+
+```ruby
+require 'apollo-federation'
+
+class BaseField < GraphQL::Schema::Field
+  include ApolloFederation::Field
+end
+```
+
+Include the `ApolloFederation::Object` module in your base object class:
+
+```ruby
+class BaseObject < GraphQL::Schema::Object
+  include ApolloFederation::Object
+
+  field_class BaseField
+end
+```
+
+Finally, include the `ApolloFederation::Schema` module in your schema:
+
+```ruby
+class MySchema < GraphQL::Schema
+  include ApolloFederation::Schema
+end
+```
+
+## Example
+
+The [`example`](./example/) folder contains a Ruby implementation of Apollo's [`federation-demo`](https://github.com/apollographql/federation-demo). To run it locally, install the Ruby dependencies:
+
+    $ bundle
+
+Install the Node dependencies:
+
+    $ yarn
+
+Start all of the services:
+
+    $ yarn start-services
+
+Start the gateway:
+
+    $ yarn start-gateway
+
+This will start up the gateway and serve it at http://localhost:5000.
+
+
+## Usage
+
+The API is designed to mimic the API of [Apollo's federation library](https://www.apollographql.com/docs/apollo-server/federation/introduction/). It's best to read and understand the way federation works, in general, before attempting to use this library.
+
+### Extending a type
+[Apollo documentation](https://www.apollographql.com/docs/apollo-server/federation/core-concepts/#extending-external-types)
+
+Call `extend_type` within your class definition:
+
+```ruby
+class User < BaseObject
+  extend_type
+end
+```
+
+### The `@key` directive
+[Apollo documentation](https://www.apollographql.com/docs/apollo-server/federation/core-concepts/#entities-and-keys)
+
+Call `key` within your class definition:
+
+```ruby
+class User < BaseObject
+  key fields: 'id'
+end
+```
+
+### The `@external` directive
+[Apollo documentation](https://www.apollographql.com/docs/apollo-server/federation/core-concepts/#referencing-external-types)
+
+Pass the `external: true` option to your field definition:
+
+```ruby
+class User < BaseObject
+  field :id, ID, null: false, external: true
+end
+```
+
+### The `@requires` directive
+[Apollo documentation](https://www.apollographql.com/docs/apollo-server/federation/advanced-features/#computed-fields)
+
+Pass the `requires:` option to your field definition:
+
+```ruby
+class Product < BaseObject
+  field :price, Int, null: true, external: true
+  field :weight, Int, null: true, external: true
+  field :shipping_estimate, Int, null: true, requires: { fields: "price weight"}
+end
+```
+
+### The `@provides` directive
+[Apollo documentation](https://www.apollographql.com/docs/apollo-server/federation/advanced-features/#using-denormalized-data)
+
+Pass the `provides:` option to your field definition:
+
+```ruby
+class Review < BaseObject
+  field :author, 'User', null: true, provides: { fields: 'username' }
+end
+```
+
+### Reference resolvers
+[Apollo documentation](https://www.apollographql.com/docs/apollo-server/api/apollo-federation/#__resolvereference)
+
+Define a `resolve_reference` class method on your object. The method will be passed the reference from another service and the context for the query.
+
+```ruby
+class User < BaseObject
+  def self.resolve_reference(reference, context)
+    USERS.find { |user| user[:id] == reference[:id] }
+  end
+end
+```
+
+## Known Limitations and Issues
+ - Currently only works with class-based schemas
+ - Does add directives to the output of `Schema.to_definition`. Since `graphql-ruby` doesn't natively support schema directives, the directives will only be visible to the [Apollo Gateway](https://www.apollographql.com/docs/apollo-server/api/apollo-gateway/) through the `Query._service` field (see the [Apollo Federation specification](https://www.apollographql.com/docs/apollo-server/federation/federation-spec/))

data/lib/apollo-federation.rb

@@ -0,0 +1,4 @@
+require 'apollo-federation/version'
+require 'apollo-federation/schema'
+require 'apollo-federation/object'
+require 'apollo-federation/field'

data/lib/apollo-federation/any.rb

@@ -0,0 +1,17 @@
+require 'graphql'
+
+module ApolloFederation
+  class Any < GraphQL::Schema::Scalar
+    graphql_name '_Any'
+
+    def self.coerce_input(value, _ctx)
+      # TODO: Should we convert it to a Mash-like object?
+      result = Hash.new
+      value.each_key do |key|
+        result[key.to_sym] = value[key]
+      end
+
+      result
+    end
+  end
+end

data/lib/apollo-federation/entities_field.rb

@@ -0,0 +1,46 @@
+require 'graphql'
+require 'apollo-federation/any'
+
+module ApolloFederation
+  module EntitiesField
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      extend GraphQL::Schema::Member::HasFields
+
+      def define_entities_field(entity_type)
+        field(:_entities, [entity_type, null: true], null: false) do
+          argument :representations, [Any], required: true
+        end
+      end
+    end
+
+    def _entities(representations:)
+      representations.map do |reference|
+        typename = reference[:__typename]
+        # TODO: Use warden or schema?
+        type = context.warden.get_type(typename)
+        if type.nil? || type.kind != GraphQL::TypeKinds::OBJECT
+          # TODO: Raise a specific error class?
+          raise "The _entities resolver tried to load an entity for type \"#{typename}\", but no object type of that name was found in the schema"
+        end
+
+        # TODO: Handle non-class types?
+        type_class = type.metadata[:type_class]
+        result = type_class.respond_to?(:resolve_reference) ?
+          type_class.resolve_reference(reference, context) :
+          reference
+
+        # TODO: This isn't 100% correct: if (for some reason) 2 different resolve_reference calls
+        # return the same object, it might not have the right type
+        # Right now, apollo-federation just adds a __typename property to the result,
+        # but I don't really like the idea of modifying the resolved object
+        context[result] = type
+        # TODO: Handle lazy objects?
+        result
+      end
+    end
+  end
+end

data/lib/apollo-federation/entity.rb

@@ -0,0 +1,11 @@
+require 'graphql'
+
+module ApolloFederation
+  class Entity < GraphQL::Schema::Union
+    graphql_name '_Entity'
+
+    def self.resolve_type(object, context)
+      context[object]
+    end
+  end
+end

data/lib/apollo-federation/federated_document_from_schema_definition.rb

@@ -0,0 +1,63 @@
+require 'graphql'
+require 'apollo-federation/service'
+
+module ApolloFederation
+  class FederatedDocumentFromSchemaDefinition < GraphQL::Language::DocumentFromSchemaDefinition
+    FEDERATION_TYPES = [
+      '_Any',
+      '_Entity',
+      '_Service',
+    ]
+    FEDERATION_QUERY_FIELDS = [
+      '_entities',
+      '_service',
+    ]
+
+    def build_object_type_node(object_type)
+      object_node = super
+      if query_type?(object_type)
+        federation_fields = object_node.fields.select { |field| FEDERATION_QUERY_FIELDS.include?(field.name) }
+        federation_fields.each { |field| object_node = object_node.delete_child(field) }
+      end
+      merge_directives(object_node, object_type.metadata[:federation_directives])
+    end
+
+    def build_field_node(field_type)
+      field_node = super
+      merge_directives(field_node, field_type.metadata[:federation_directives])
+    end
+
+    def build_type_definition_nodes(types)
+      non_federation_types = types.select do |type|
+        if query_type?(type)
+          !type.fields.values.all? { |field| FEDERATION_QUERY_FIELDS.include?(field.graphql_name) }
+        else
+          !FEDERATION_TYPES.include?(type.graphql_name)
+        end
+      end
+      super(non_federation_types)
+    end
+
+    private
+
+    def query_type?(type)
+      type == warden.root_type_for_operation('query')
+    end
+
+    def merge_directives(node, directives)
+      (directives || []).each do |directive|
+        node = node.merge_directive(
+          name: directive[:name],
+          arguments: build_arguments_node(directive[:arguments])
+        )
+      end
+      node
+    end
+
+    def build_arguments_node(arguments)
+      (arguments || []).map do |arg|
+        GraphQL::Language::Nodes::Argument.new(name: arg[:name], value: arg[:values])
+      end
+    end
+  end
+end

data/lib/apollo-federation/field.rb

@@ -0,0 +1,34 @@
+require 'apollo-federation/has_directives'
+
+module ApolloFederation
+  module Field
+    include HasDirectives
+
+    def initialize(*args, external: false, requires: nil, provides: nil, **kwargs, &block)
+      if external
+        add_directive(name: 'external')
+      end
+      if requires
+        add_directive(
+          name: 'requires',
+          arguments: [
+            name: 'fields',
+            values: requires[:fields],
+          ],
+        )
+      end
+      if provides
+        add_directive(
+          name: 'provides',
+          arguments: [
+            name: 'fields',
+            values: provides[:fields],
+          ],
+        )
+      end
+
+      # Pass on the default args:
+      super(*args, **kwargs, &block)
+    end
+  end
+end

data/lib/apollo-federation/has_directives.rb

@@ -0,0 +1,15 @@
+
+module ApolloFederation
+  module HasDirectives
+    def add_directive(name:, arguments: nil)
+      @federation_directives ||= []
+      @federation_directives << { name: name, arguments: arguments }
+    end
+
+    def to_graphql
+      field_defn = super # Returns a GraphQL::Field
+      field_defn.metadata[:federation_directives] = @federation_directives
+      field_defn
+    end
+  end
+end

data/lib/apollo-federation/object.rb

@@ -0,0 +1,28 @@
+require 'apollo-federation/has_directives'
+
+module ApolloFederation
+  module Object
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      include HasDirectives
+
+      # TODO: We should support extending interfaces at some point
+      def extend_type
+        add_directive(name: 'extends')
+      end
+
+      def key(fields:)
+        add_directive(
+          name: 'key',
+          arguments: [
+            name: 'fields',
+            values: fields,
+          ],
+        )
+      end
+    end
+  end
+end

data/lib/apollo-federation/schema.rb

@@ -0,0 +1,57 @@
+require 'apollo-federation/entities_field'
+require 'apollo-federation/service_field'
+require 'apollo-federation/entity'
+require 'apollo-federation/federated_document_from_schema_definition.rb'
+
+module ApolloFederation
+  module Schema
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def to_graphql
+        orig_defn = super
+
+        if query.nil?
+          base = GraphQL::Schema::Object
+        else
+          base = query.metadata[:type_class]
+        end
+
+        federation_query = Class.new(base) do
+          graphql_name 'Query'
+
+          include EntitiesField
+          include ServiceField
+        end
+
+        possible_entities = orig_defn.types.values.select do |type|
+          !type.introspection? && !type.default_scalar? &&
+            type.metadata[:federation_directives]&.any? {|directive| directive[:name] == 'key'}
+        end
+
+        if possible_entities.length > 0
+          entity_type = Class.new(Entity) do
+            possible_types(*possible_entities)
+          end
+          # TODO: Should/can we encapsulate all of this inside the module? What's the best/most Ruby
+          # way to split this out?
+          federation_query.define_entities_field(entity_type)
+        end
+
+        query(federation_query)
+
+        super
+      end
+
+      def federation_sdl
+        @sdl ||= begin
+          document_from_schema = FederatedDocumentFromSchemaDefinition.new(self)
+          GraphQL::Language::Printer.new.print(document_from_schema.document)
+        end
+      end
+    end
+  end
+end
+

data/lib/apollo-federation/service.rb

@@ -0,0 +1,9 @@
+require 'graphql'
+
+module ApolloFederation
+  class Service < GraphQL::Schema::Object
+    graphql_name '_Service'
+
+    field(:sdl, String, null: true)
+  end
+end

data/lib/apollo-federation/service_field.rb

@@ -0,0 +1,14 @@
+require 'graphql'
+require 'apollo-federation/service'
+
+module ApolloFederation
+  module ServiceField
+    extend GraphQL::Schema::Member::HasFields
+
+    field(:_service, Service, null: false)
+
+    def _service
+      { sdl: context.schema.class.federation_sdl }
+    end
+  end
+end

data/lib/apollo-federation/version.rb

@@ -0,0 +1,3 @@
+module ApolloFederation
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: apollo-federation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Noa Elad
+- Rylan Collins
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-06-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: graphql
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A Ruby implementation of Apollo Federation
+email:
+- noa.elad@gusto.com
+- rylan@gusto.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/apollo-federation.rb
+- lib/apollo-federation/any.rb
+- lib/apollo-federation/entities_field.rb
+- lib/apollo-federation/entity.rb
+- lib/apollo-federation/federated_document_from_schema_definition.rb
+- lib/apollo-federation/field.rb
+- lib/apollo-federation/has_directives.rb
+- lib/apollo-federation/object.rb
+- lib/apollo-federation/schema.rb
+- lib/apollo-federation/service.rb
+- lib/apollo-federation/service_field.rb
+- lib/apollo-federation/version.rb
+homepage: https://github.com/Gusto/apollo-federation-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Gusto/apollo-federation-ruby
+  changelog_uri: https://github.com/Gusto/apollo-federation-ruby/releases
+  source_code_uri: https://github.com/Gusto/apollo-federation-ruby
+  bug_tracker_uri: https://github.com/Gusto/apollo-federation-ruby/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A Ruby implementation of Apollo Federation
+test_files: []