federation: add support for Apollo Federation subgraph spec v2.3

Updates `federation` module to support Apollo Federation subgraph spec v2.3

Changes:
* v2.2 - update `@shareable` definition to be repeatable to allow annotating both types and their extensions (NOTE: this functionality is not applicable to `graphql-kotlin`)
* v2.3 - adds new `@interfaceObject` directive that allows you to extend interface entity functionality in subgraphs, i.e. by applying `@interfaceObject` directive on a type we provide meta information to the composition logic that this entity type is actually an interface in the supergraph. This allows us to extend interface functionality without knowing any of its implementing types.

Author: dariuszkuc

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/FederatedSchemaGeneratorHooks.kt

@@ -20,13 +20,16 @@ import com.apollographql.federation.graphqljava.printer.ServiceSDLPrinter.genera
 import com.apollographql.federation.graphqljava.printer.ServiceSDLPrinter.generateServiceSDLV2
 import com.expediagroup.graphql.generator.annotations.GraphQLName
 import com.expediagroup.graphql.generator.directives.DirectiveMetaInformation
+import com.expediagroup.graphql.generator.federation.directives.COMPOSE_DIRECTIVE_NAME
 import com.expediagroup.graphql.generator.federation.directives.COMPOSE_DIRECTIVE_TYPE
 import com.expediagroup.graphql.generator.federation.directives.EXTENDS_DIRECTIVE_TYPE
 import com.expediagroup.graphql.generator.federation.directives.EXTERNAL_DIRECTIVE_TYPE
 import com.expediagroup.graphql.generator.federation.directives.FEDERATION_SPEC_URL
 import com.expediagroup.graphql.generator.federation.directives.FieldSet
 import com.expediagroup.graphql.generator.federation.directives.INACCESSIBLE_DIRECTIVE_NAME
 import com.expediagroup.graphql.generator.federation.directives.INACCESSIBLE_DIRECTIVE_TYPE
+import com.expediagroup.graphql.generator.federation.directives.INTERFACE_OBJECT_DIRECTIVE_NAME
+import com.expediagroup.graphql.generator.federation.directives.INTERFACE_OBJECT_DIRECTIVE_TYPE
 import com.expediagroup.graphql.generator.federation.directives.KEY_DIRECTIVE_NAME
 import com.expediagroup.graphql.generator.federation.directives.KEY_DIRECTIVE_TYPE
 import com.expediagroup.graphql.generator.federation.directives.KEY_DIRECTIVE_TYPE_V2
@@ -75,7 +78,9 @@ open class FederatedSchemaGeneratorHooks(
     private val validator = FederatedSchemaValidator()
 
     private val federationV2OnlyDirectiveNames: Set<String> = setOf(
+        COMPOSE_DIRECTIVE_NAME,
         INACCESSIBLE_DIRECTIVE_NAME,
+        INTERFACE_OBJECT_DIRECTIVE_NAME,
         LINK_DIRECTIVE_NAME,
         OVERRIDE_DIRECTIVE_NAME,
         SHAREABLE_DIRECTIVE_NAME
@@ -93,6 +98,7 @@ open class FederatedSchemaGeneratorHooks(
         EXTENDS_DIRECTIVE_TYPE,
         EXTERNAL_DIRECTIVE_TYPE,
         INACCESSIBLE_DIRECTIVE_TYPE,
+        INTERFACE_OBJECT_DIRECTIVE_TYPE,
         KEY_DIRECTIVE_TYPE,
         LINK_DIRECTIVE_TYPE,
         OVERRIDE_DIRECTIVE_TYPE,

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/InterfaceObjectDirective.kt

@@ -0,0 +1,84 @@
+/*
+ * Copyright 2023 Expedia, Inc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.expediagroup.graphql.generator.federation.directives
+
+import com.expediagroup.graphql.generator.annotations.GraphQLDirective
+import graphql.introspection.Introspection
+
+/**
+ * ```graphql
+ * directive @interfaceObject on OBJECT
+ * ```
+ *
+ * This directive provides meta information to the router that this entity type defined within this subgraph is an interface in the supergraph. This allows you to extend functionality
+ * of an interface across the supergraph without having to implement (or even be aware of) all its implementing types.
+ *
+ * Example:
+ * Given an interface that is defined in another subgraph
+ *
+ * ```graphql
+ * interface Product @key(fields: "id") {
+ *   id: ID!
+ *   description: String
+ * }
+ *
+ * type Book implements Product @key(fields: "id") {
+ *   id: ID!
+ *   description: String
+ *   pages: Int!
+ * }
+ *
+ * type Movie implements Product @key(fields: "id") {
+ *   id: ID!
+ *   description: String
+ *   duration: Int!
+ * }
+ * ```
+ *
+ * We can extend Product entity in our subgraph and a new field directly to it. This will result in making this new field available to ALL implementing types.
+ *
+ * ```kotlin
+ * @InterfaceObjectDirective
+ * data class Product(val id: ID) {
+ *     fun reviews(): List<Review> = TODO()
+ * }
+ * ```
+ *
+ * Which generates the following subgraph schema
+ *
+ * ```graphql
+ * type Product @key(fields: "id") @interfaceObject {
+ *   id: ID!
+ *   reviews: [Review!]!
+ * }
+ * ```
+ */
+@GraphQLDirective(
+    name = INTERFACE_OBJECT_DIRECTIVE_NAME,
+    description = INTERFACE_OBJECT_DIRECTIVE_DESCRIPTION,
+    locations = [Introspection.DirectiveLocation.OBJECT]
+)
+annotation class InterfaceObjectDirective
+
+internal const val INTERFACE_OBJECT_DIRECTIVE_NAME = "interfaceObject"
+private const val INTERFACE_OBJECT_DIRECTIVE_DESCRIPTION = "Provides meta information to the router that this entity type is an interface in the supergraph."
+
+internal val INTERFACE_OBJECT_DIRECTIVE_TYPE: graphql.schema.GraphQLDirective = graphql.schema.GraphQLDirective.newDirective()
+    .name(INTERFACE_OBJECT_DIRECTIVE_NAME)
+    .description(INTERFACE_OBJECT_DIRECTIVE_DESCRIPTION)
+    .validLocations(Introspection.DirectiveLocation.OBJECT)
+    .build()

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/LinkDirective.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Expedia, Inc
+ * Copyright 2023 Expedia, Inc
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ import graphql.schema.GraphQLList
 import graphql.schema.GraphQLNonNull
 
 const val LINK_SPEC_URL = "https://specs.apollo.dev/link/v1.0/"
-const val FEDERATION_SPEC_URL = "https://specs.apollo.dev/federation/v2.1"
+const val FEDERATION_SPEC_URL = "https://specs.apollo.dev/federation/v2.3"
 
 /**
  * ```graphql

generator/graphql-kotlin-federation/src/main/kotlin/com/expediagroup/graphql/generator/federation/directives/ShareableDirective.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Expedia, Inc
+ * Copyright 2023 Expedia, Inc
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,7 +21,7 @@ import graphql.introspection.Introspection.DirectiveLocation
 
 /**
  * ```graphql
- * directive @shareable on FIELD_DEFINITION | OBJECT
+ * directive @shareable repeatable on FIELD_DEFINITION | OBJECT
  * ```
  *
  * Shareable directive indicates that given object and/or field can be resolved by multiple subgraphs. If an object is marked as `@shareable` then all its fields are automatically shareable without the
@@ -44,6 +44,7 @@ import graphql.introspection.Introspection.DirectiveLocation
  * }
  * ```
  */
+@Repeatable
 @GraphQLDirective(
     name = SHAREABLE_DIRECTIVE_NAME,
     description = SHAREABLE_DIRECTIVE_DESCRIPTION,

generator/graphql-kotlin-federation/src/test/kotlin/com/expediagroup/graphql/generator/federation/FederatedSchemaV2GeneratorTest.kt

@@ -30,7 +30,7 @@ class FederatedSchemaV2GeneratorTest {
     fun `verify can generate federated schema`() {
         val expectedSchema =
             """
-            schema @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.1"){
+            schema @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@interfaceObject", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.3"){
               query: Query
             }
 
@@ -60,6 +60,9 @@ class FederatedSchemaV2GeneratorTest {
                 if: Boolean!
               ) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
 
+            "Provides meta information to the router that this entity type is an interface in the supergraph."
+            directive @interfaceObject on OBJECT
+
             "Space separated list of primary keys needed to access federated object"
             directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 

generator/graphql-kotlin-federation/src/test/kotlin/com/expediagroup/graphql/generator/federation/data/integration/intfObject/IntfObjectSchema.kt

@@ -0,0 +1,18 @@
+package com.expediagroup.graphql.generator.federation.data.integration.intfObject
+
+import com.expediagroup.graphql.generator.federation.data.queries.federated.v1.Review
+import com.expediagroup.graphql.generator.federation.directives.FieldSet
+import com.expediagroup.graphql.generator.federation.directives.InterfaceObjectDirective
+import com.expediagroup.graphql.generator.federation.directives.KeyDirective
+import com.expediagroup.graphql.generator.scalars.ID
+
+class IntfObjectQuery {
+
+    fun product(id: ID): Product = TODO()
+}
+
+@InterfaceObjectDirective
+@KeyDirective(fields = FieldSet("id"))
+data class Product(val id: ID) {
+    fun reviews(): List<Review> = TODO()
+}

generator/graphql-kotlin-federation/src/test/kotlin/com/expediagroup/graphql/generator/federation/execution/ServiceQueryResolverTest.kt

@@ -86,7 +86,7 @@ scalar CustomScalar"""
 
 const val BASE_SERVICE_SDL =
 """
-schema @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.1"){
+schema @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@interfaceObject", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.3"){
   query: Query
 }
 
@@ -102,6 +102,9 @@ directive @external on FIELD_DEFINITION
 "Marks location within schema as inaccessible from the GraphQL Gateway"
 directive @inaccessible on SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINITION | INTERFACE | UNION | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 
+"Provides meta information to the router that this entity type is an interface in the supergraph."
+directive @interfaceObject on OBJECT
+
 "Space separated list of primary keys needed to access federated object"
 directive @key(fields: FieldSet!) repeatable on OBJECT | INTERFACE
 
@@ -145,7 +148,7 @@ scalar FieldSet
 
 const val FEDERATED_SERVICE_SDL_V2 =
 """
-schema @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.1"){
+schema @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@interfaceObject", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.3"){
   query: Query
 }
 
@@ -163,6 +166,9 @@ directive @external on FIELD_DEFINITION
 "Marks location within schema as inaccessible from the GraphQL Gateway"
 directive @inaccessible on SCALAR | OBJECT | FIELD_DEFINITION | ARGUMENT_DEFINITION | INTERFACE | UNION | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
 
+"Provides meta information to the router that this entity type is an interface in the supergraph."
+directive @interfaceObject on OBJECT
+
 "Space separated list of primary keys needed to access federated object"
 directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
 

generator/graphql-kotlin-federation/src/test/kotlin/com/expediagroup/graphql/generator/federation/validation/integration/ComposeDirectiveIT.kt

@@ -21,7 +21,7 @@ class ComposeDirectiveIT {
             )
 
             val expected = """
-                schema @composeDirective(name : "custom") @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.1"){
+                schema @composeDirective(name : "custom") @link(import : ["@composeDirective", "@extends", "@external", "@inaccessible", "@interfaceObject", "@key", "@override", "@provides", "@requires", "@shareable", "@tag", "FieldSet"], url : "https://specs.apollo.dev/federation/v2.3"){
                   query: Query
                 }
 

website/docs/schema-generator/federation/federated-directives.md

@@ -211,6 +211,60 @@ type Product {
 }
 ```
 
+## `@interfaceObject` directive
+
+:::note
+Only available in Federation v2.
+:::
+
+```graphql
+directive @interfaceObject on OBJECT
+```
+
+This directive provides meta information to the router that this entity type defined within this subgraph is an interface in the supergraph. This allows you to extend functionality
+of an interface across the supergraph without having to implement (or even be aware of) all its implementing types.
+
+Example:
+Given an interface that is defined somewhere in our supergraph
+
+```graphql
+interface Product @key(fields: "id") {
+  id: ID!
+  description: String
+}
+
+type Book implements Product @key(fields: "id") {
+  id: ID!
+  description: String
+  pages: Int!
+}
+
+type Movie implements Product @key(fields: "id") {
+  id: ID!
+  description: String
+  duration: Int!
+}
+```
+
+We can extend `Product` entity in our subgraph and a new field directly to it. This will result in making this new field available to ALL implementing types.
+
+```kotlin
+@InterfaceObjectDirective
+@KeyDirective(fields = FieldSet("id"))
+data class Product(val id: ID) {
+    fun reviews(): List<Review> = TODO()
+}
+```
+
+Which generates the following subgraph schema
+
+```graphql
+type Product @key(fields: "id") @interfaceObject {
+  id: ID!
+  reviews: [Review!]!
+}
+```
+
 ## `@key` directive
 
 ```graphql
@@ -470,7 +524,7 @@ Only available in Federation v2.
 :::
 
 ```graphql
-directive @shareable on FIELD_DEFINITION | OBJECT
+directive @shareable repeatable on FIELD_DEFINITION | OBJECT
 ```
 
 Shareable directive indicates that given object and/or field can be resolved by multiple subgraphs. If an object is marked as `@shareable` then all its fields are automatically shareable without the