feat (FEDERATION) nuwave#911: Initial idea of how we could implement …

…the federation support into lighthouse

config/config.php

@@ -201,6 +201,20 @@
 
     'transactional_mutations' => true,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Apollo federation support
+    |--------------------------------------------------------------------------
+    |
+    | Possible types are "service" and "gateway". Defaults to
+    | "service" because you may implement more services than gateways ;)
+    |
+    */
+
+    'federation' => [
+        'type'    => 'service',
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | GraphQL Subscriptions

src/Exceptions/FederationException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Nuwave\Lighthouse\Exceptions;
+
+use Exception;
+
+class FederationException extends Exception
+{
+    //
+}

src/Federation/Directives/ExtendsDirective.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class ExtendsDirective extends BaseDirective
+{
+    /**
+     * Directive name.
+     *
+     * @return string
+     */
+    public function name(): string
+    {
+        return 'extends';
+    }
+
+    /**
+     * @return string
+     * @see https://www.apollographql.com/docs/apollo-server/federation/federation-spec/#schema-modifications-glossary
+     */
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */
+            <<<'SDL'
+"""
+Some libraries such as graphql-java don't have native support for type extensions in their printer. Apollo Federation 
+supports using an @extends directive in place of extend type to annotate type references:
+
+    type User @key(fields: "id") @extends {
+
+instead of:
+
+    extend type User @key(fields: "id") {
+"""
+directive @extends on OBJECT | INTERFACE
+SDL;
+    }
+}

src/Federation/Directives/ExternalDirective.php

@@ -0,0 +1,35 @@
+<?php
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class ExternalDirective extends BaseDirective
+{
+    /**
+     * Name of the directive.
+     *
+     * @return string
+     */
+    public function name(): string
+    {
+        return 'external';
+    }
+
+    /**
+     * @return string
+     * @see https://www.apollographql.com/docs/apollo-server/federation/federation-spec/#schema-modifications-glossary
+     */
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */
+            <<<'SDL'
+"""
+Individual federated services should be runnable without having the entire graph present. Fields marked with @external 
+are declarations of fields that are defined in another service. All fields referred to in @key, @requires, and @provides
+directives need to have corresponding @external fields in the same service.
+"""
+directive @external on FIELD_DEFINITION
+SDL;
+    }
+}

src/Federation/Directives/KeyDirective.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class KeyDirective extends BaseDirective
+{
+    /**
+     * Directive name.
+     *
+     * @return string
+     */
+    public function name(): string
+    {
+        return 'key';
+    }
+
+    /**
+     * @return string
+     * @see https://www.apollographql.com/docs/apollo-server/federation/federation-spec/#schema-modifications-glossary
+     */
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */
+            <<<'SDL'
+"""
+The @key directive is used to indicate a combination of fields that can be used to uniquely identify and fetch an object
+or interface. Multiple keys can be defined on a single object type:
+
+    type User @key(fields: "id") @key(fields: "another_field") @extends {
+"""
+directive @key(
+    """
+    Fields that can be used to uniquely identify and fetch an object or interface
+    """
+    fields: _FieldSet!
+) on OBJECT | INTERFACE
+SDL;
+    }
+}

src/Federation/Directives/ProvidesDirective.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class ProvidesDirective extends BaseDirective
+{
+    /**
+     * Name of the directive.
+     *
+     * @return string
+     */
+    public function name(): string
+    {
+        return 'provides';
+    }
+
+    /**
+     * @return string
+     * @see https://www.apollographql.com/docs/apollo-server/federation/federation-spec/#schema-modifications-glossary
+     */
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */
+            <<<'SDL'
+"""
+The @provides directive is used to annotate the expected returned fieldset from a field on a base type that is 
+guaranteed to be selectable by the gateway. Given the following example:
+
+    type Review @key(fields: "id") {
+      product: Product @provides(fields: "name")
+    }
+    
+    extend type Product @key(fields: "upc") {
+      upc: String @external
+      name: String @external
+    }
+"""
+directive @provides(
+    """
+    Annotate the expected returned fieldset from a field on a base type that is guaranteed to be selectable by the 
+    gateway.
+    """
+    fields: _FieldSet!
+) on FIELD_DEFINITION
+SDL;
+    }
+}

src/Federation/Directives/RequiresDirective.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace Nuwave\Lighthouse\Federation\Directives;
+
+use Nuwave\Lighthouse\Schema\Directives\BaseDirective;
+
+class RequiresDirective extends BaseDirective
+{
+    /**
+     * Name of the directive.
+     *
+     * @return string
+     */
+    public function name(): string
+    {
+        return 'requires';
+    }
+
+    /**
+     * @return string
+     * @see https://www.apollographql.com/docs/apollo-server/federation/federation-spec/#schema-modifications-glossary
+     */
+    public static function definition(): string
+    {
+        return /* @lang GraphQL */
+            <<<'SDL'
+"""
+The @requires directive is used to annotate the required input fieldset from a base type for a resolver. It is used to 
+develop a query plan where the required fields may not be needed by the client, but the service may need additional 
+information from other services. For example:
+
+    extend type User @key(fields: "id") {
+      id: ID! @external
+      email: String @external
+      reviews: [Review] @requires(fields: "email")
+    }
+"""
+directive @requires(
+    """
+    It is used to develop a query plan where the required fields may not be needed by the client, but the service may 
+    need additional information from other services.
+    """
+    fields: _FieldSet!
+) on FIELD_DEFINITION
+SDL;
+    }
+}