feat: Apollo Federation v2 support (#4)

.github/workflows/compatibility.yaml

@@ -10,22 +10,19 @@ jobs:
   compatibility:
     timeout-minutes: 30
     runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: compatibility
 
     steps:
       - uses: actions/checkout@v3
       - name: Setup .NET
         uses: actions/setup-dotnet@v3
         with:
           dotnet-version: 7.0.x
-      # - name: Restore dependencies
-      #   run: dotnet restore
-      # - name: Build
-      #   run: dotnet build --no-restore
-      # - name: Generate schema file
-      #   run: dotnet run --project compatibility/Products.csproj schema export --output products.graphql 
+      - name: Restore dependencies
+        run: dotnet restore
+      - name: Build
+        run: dotnet build --no-restore
+      - name: Generate schema file
+        run: dotnet run --project compatibility/Products.csproj schema export --output products.graphql 
       - name: Compatibility Test
         uses: apollographql/federation-subgraph-compatibility@v2
         with:

.gitignore

@@ -3,6 +3,7 @@ obj
 out
 
 # compatibility stuff
+products.graphql
 package.json
 package-lock.json
 results.md

README.md

@@ -34,7 +34,8 @@ var builder = WebApplication.CreateBuilder(args);
 
 builder.Services
     .AddGraphQLServer()
-    .AddApolloFederation()
+    // .AddApolloFederation() // use this instead if you want to opt-in to fed v1 
+    .AddApolloFederationV2() 
     // register your types and services
     ;
 
@@ -51,7 +52,7 @@ Apollo Federation requires subgraphs to provide some additional metadata to make
 the supergraph by the specified `@key`s. Since entities can be extended by various subgraphs, we need an extra entry point to access the entities, i.e. subgraphs need to
 implement reference resolvers for entities that they support.
 
-Currently `ApolloGraphQL.HotChocolate.Federation` supports only Apollo Federation v1. See [Apollo documentation](https://www.apollographql.com/docs/federation/) for additional Federation details.
+See [Apollo documentation](https://www.apollographql.com/docs/federation/) for additional Federation details.
 
 ### Annotation
 
@@ -97,14 +98,23 @@ type Product @key(fields: "id") {
 
 #### Federation Attributes
 
-Directives
+Federation v1 directives
 
-* `Key` applicable on objects, see [`@key` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#key)
 * `Extends` applicable on objects, see [`@extends` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#extends)
 * `External` applicable on fields, see [`@external` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#external)
+* `Key` applicable on objects, see [`@key` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#key)
 * `Provides` applicable on fields, see [`@provides` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#provides)
 * `Requires` applicable on fields, see [`@requires` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#requires)
 
+Federation v2 directives (includes all of the v1 directives)
+
+* `ApolloTag` applicable on schema, see [`@tag` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#tag)
+* `ComposeDirective` applicable on schema, see [`@composeDirective` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#composedirective)
+* `Inaccessible` applicable on all type definitions, see [`@inaccessible` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#inaccessible)
+* `InterfaceObject` applicable on objects, see [`@interfaceObject` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#interfaceobject)
+* `Link` applicable on schema, see [`@link` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#the-link-directive)
+* `Shareable` applicable on schema, see [`@shareable` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#shareable)
+
 Entity resolution
 
 * `Map` applicable on entity resolver method paramaters, allows you to map complex argument to a simpler representation value, e.g. `[Map("foo.bar")] string bar`
@@ -159,6 +169,85 @@ type Product @key(fields: "id") {
 }
 ```
 
+#### Descriptor Extensions
+
+Federation v1 directives
+
+* `ExtendsType` applicable on objects, see [`@extends` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#extends)
+* `External` applicable on fields, see [`@external` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#external)
+* `Key(fieldset)` applicable on objects, see [`@key` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#key)
+* `Provides(fieldset)` applicable on fields, see [`@provides` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#provides)
+* `Requires(fieldset)` applicable on fields, see [`@requires` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#requires)
+
+Federation v2 directives (includes all of the v1 directives)
+
+* `ApolloTag` applicable on all type definitions, see [`@tag` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#tag)
+* `ComposeDirective(name)` applicable on schema, see [`@composeDirective` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#composedirective)
+* `Inaccessible` applicable on all type definitions, see [`@inaccessible` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#inaccessible)
+* `InterfaceObject` applicable on objects, see [`@interfaceObject` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#interfaceobject)
+* `Key(fieldset, resolvable?)` applicable on objects, see [`@key` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#key)
+* `Link(url, [import]?)` applicable on schema, see [`@link` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#the-link-directive)
+* `Shareable` applicable on fields and objects, see [`@shareable` documentation](https://www.apollographql.com/docs/federation/federated-types/federated-directives#shareable)
+
+Entity resolution
+
+* you have to provide `ResolveReferenceWith` function to be able to resolve the entities
+
+### Advanced Use Cases
+
+#### Generating schema at build time
+
+See [HotChocolate documentation](https://chillicream.com/docs/hotchocolate/v13/server/command-line) for details on the server support for command line interface.
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services
+    .AddGraphQLServer()
+    .AddApolloFederationV2()
+    // register your types and services
+    ;
+
+var app = builder.Build();
+app.MapGraphQL();
+app.RunWithGraphQLCommands();
+```
+
+You can then generate your schema by running
+
+```shell
+dotnet run -- schema export --output schema.graphql
+```
+
+#### `@composedDirective` usage
+
+By default, Supergraph schema excludes all custom directives. The `@composeDirective`` is used to specify custom directives that should be preserved in the Supergraph schema.
+
+`ApolloGraphQL.HotChocolate.Federation` provides common `FederatedSchema` class that automatically includes Apollo Federation v2 `@link` definition. When applying any custom
+schema directives, you should extend this class and add required attributes/directives.
+
+When applying `@composedDirective` you also need to `@link` it your specification. Your custom schema should then be passed to the `AddApolloFederationV2` extension.
+
+```csharp
+[ComposeDirective("@custom")]
+[Link("https://myspecs.dev/myCustomDirective/v1.0", new string[] { "@custom" })]
+public class CustomSchema : FederatedSchema
+{
+}
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services
+    .AddGraphQLServer()
+    .AddApolloFederationV2(new CustomSchema())
+    // register your types and services
+    ;
+
+var app = builder.Build();
+app.MapGraphQL();
+app.Run();
+```
+
 ## Contact
 
 If you have a specific question about the library or code, please start a discussion in the [Apollo community forums](https://community.apollographql.com/) or start a conversation on our [Discord server](https://discord.gg/graphos).

compatibility/Program.cs

@@ -5,7 +5,9 @@
 
 builder.Services
     .AddGraphQLServer()
-    .AddApolloFederation()
+    .AddApolloFederationV2(new CustomSchema())
+    .AddType<CustomDirectiveType>()
+    .AddType<Inventory>()
     .AddQueryType<Query>()
     .RegisterService<Data>();
 

compatibility/README.md

@@ -10,6 +10,12 @@ Install compatibility script
 npm install --dev @apollo/federation-subgraph-compatibility
 ```
 
+Generate test schema
+
+```shell
+dotnet run --project compatibility/Products.csproj schema export --output products.graphql
+```
+
 Run compatibility tests
 
 ```shell

compatibility/Types/CustomAttribute.cs

@@ -0,0 +1,11 @@
+using HotChocolate.Types.Descriptors;
+
+namespace Products;
+
+public sealed class CustomAttribute : ObjectTypeDescriptorAttribute
+{
+    protected override void OnConfigure(IDescriptorContext context, IObjectTypeDescriptor descriptor, Type type)
+    {
+        descriptor.Directive(CustomDirectiveType.CustomDirectiveName);
+    }
+}

compatibility/Types/CustomDirectiveType.cs

@@ -0,0 +1,11 @@
+namespace Products;
+
+public sealed class CustomDirectiveType : DirectiveType
+{
+    public const string CustomDirectiveName = "custom";
+
+    protected override void Configure(IDirectiveTypeDescriptor descriptor)
+        => descriptor
+            .Name(CustomDirectiveName)
+            .Location(DirectiveLocation.Object);
+}

compatibility/Types/CustomSchema.cs

@@ -0,0 +1,11 @@
+using ApolloGraphQL.HotChocolate.Federation;
+using ApolloGraphQL.HotChocolate.Federation.Two;
+
+namespace Products;
+
+[ComposeDirective("@custom")]
+[Link("https://myspecs.dev/myCustomDirective/v1.0", new string[] { "@custom" })]
+public class CustomSchema : FederatedSchema
+{
+
+}

compatibility/Types/Data.cs

@@ -27,4 +27,8 @@ public class Data
     {
         new ("apollo-federation-v1", "@apollo/federation-v1", "Migrate to Federation V2", DefaultUser)
     };
+
+    public List<Inventory> Inventories() => new List<Inventory> {
+        new ("apollo-oss")
+    };
 }

compatibility/Types/Inventory.cs

@@ -0,0 +1,28 @@
+using ApolloGraphQL.HotChocolate.Federation;
+
+namespace Products;
+
+[Key("id")]
+[InterfaceObject]
+public class Inventory
+{
+
+    public Inventory(string id)
+    {
+        Id = id;
+    }
+
+    [ID]
+    public string Id { get; }
+
+    public List<DeprecatedProduct> DeprecatedProducts(Data repository) => repository.DeprecatedProducts;
+
+    [ReferenceResolver]
+    public static Inventory? GetInventoryById(
+        string id,
+        Data repository)
+    {
+        return repository.Inventories().FirstOrDefault(
+            r => r.Id.Equals(id));
+    }
+}

compatibility/Types/Product.cs

@@ -5,6 +5,7 @@ namespace Products;
 [Key("id")]
 [Key("sku package")]
 [Key("sku variation { id }")]
+[Custom]
 public class Product
 {
     public Product(string id, string? sku, string? package, ProductVariation? variation, ProductDimension? dimensions, User? createdBy, string? notes, List<ProductResearch> research)
@@ -33,6 +34,7 @@ public Product(string id, string? sku, string? package, ProductVariation? variat
     [Provides("totalProductsCreated")]
     public User? CreatedBy { get; }
 
+    [ApolloTag("internal")]
     public string? Notes { get; }
 
     public List<ProductResearch> Research { get; }

compatibility/Types/ProductDimension.cs

@@ -1,5 +1,8 @@
+using ApolloGraphQL.HotChocolate.Federation;
+
 namespace Products;
 
+[Shareable]
 public class ProductDimension
 {
     public ProductDimension(string size, double weight, string? unit)
@@ -13,5 +16,6 @@ public ProductDimension(string size, double weight, string? unit)
 
     public double? Weight { get; }
 
+    [Inaccessible]
     public string? Unit { get; }
 }

compatibility/Types/Query.cs

@@ -1,8 +1,5 @@
-using ApolloGraphQL.HotChocolate.Federation;
-
 namespace Products;
 
-[ExtendServiceType]
 public class Query
 {
     public Product? GetProduct([ID] string id, Data repository)

compatibility/Types/User.cs

@@ -3,7 +3,7 @@
 namespace Products;
 
 [Key("email")]
-[ExtendServiceType]
+[Extends]
 public class User
 {
     public User(string email, string? name)
@@ -26,6 +26,7 @@ public User(string email, string? name)
     [External]
     public string Email { get; set; }
 
+    [Override("users")]
     public string? Name { get; }
 
     [External]

examples/AnnotationBased/Inventory/Product.cs

@@ -3,7 +3,7 @@
 namespace Inventory;
 
 [Key("upc")]
-[ExtendServiceType]
+[Extends]
 public class Product
 {
     public Product(string upc)

examples/AnnotationBased/Reviews/Product.cs

@@ -3,7 +3,7 @@
 namespace Reviews;
 
 [Key("upc")]
-[ExtendServiceType]
+[Extends]
 public class Product
 {
     public Product(string upc)