apollographql / apollo-federation-subgraph-compatibility Goto Github PK

See #166 for details.

See #166 for details

It would be nice to push spec changes to maintainers beforehand

• provide options for maintainers contacts, they push in through CI or put in implementation folder some how

graphql-dotnet/graphql-dotnet#1233

While Federation v2 is an extension of v1, due to the smart entity type merging, GraphQL schema that we ask to be implemented in the subgraphs contains some redundant information (e.g. unnecessary @extends, @external, etc). We should update our template and separate out expected Federation v1 and v2 schemas to have clear definitions of what is the expected schema produced by the different versions of Apollo Federation.

Follow up questions:

• do we need separate v1/v2 tests?

See #166 for details.

We're not currently checking to see if a _FieldSet (Fed 1) / FieldSet (Fed 2) scalar is available in the implemented products subgraph. Let's confirm:

• If we should be testing for this
• That we should test for _FieldSet with Fed 1 and FieldSet with Fed 2
• Find out why _FieldSet was renamed to FieldSet

The graphql-dotnet tests are currently failing:

#10 [build 6/6] RUN dotnet publish -c release -o /app --no-restore
#10 sha256:ba50bd92d2acfabf68124ead2e96346ee9dbaeafcf2933b7e7148ba18e2a3f2b
#10 0.255 Could not execute because the application was not found or a compatible .NET SDK is not installed.
#10 0.255 Possible reasons for this include:
#10 0.255   * You intended to execute a .NET program:
#10 0.255       The application 'publish' does not exist.
#10 0.255   * You intended to execute a .NET SDK command:
#10 0.255       A compatible installed .NET SDK for global.json version [6.0.100-rc.2.21505.57] from [/source/global.json] was not found.
#10 0.255       Install the [6.0.100-rc.2.21505.57] .NET SDK or update [/source/global.json] with an installed .NET SDK:
#10 0.256         6.0.201 [/usr/share/dotnet/sdk]
#10 ERROR: executor failed running [/bin/sh -c dotnet publish -c release -o /app --no-restore]: exit code: 145

We'll need to tweak the docker config a bit to fix the SDK mismatch.

See #166 for details

We are explicitly redefining @override in our products subgraph. It is imported with all other directives so we should double check whether this redundant definition should be removed or ALL other directive definitions should also be included.

README mentions the @requires test but currently product subgraph DOES NOT contains the directive. Currently @requires directive is specified in the inventory subgraph only which means that we are actually not testing the functionality against implementing libraries.

Proposed changes:

• update Users subgraph

type User @key(fields:"email") {
  email:ID!
  name: String
  totalProductsCreated: Int
  yearsOfEmployment: Int! # <-- new field
}

• update Products subgraph to test @requires functionality

extend type User @key(fields: "email") {
  averageProductsCreatedPerYear: Int @requires(fields: "yearsOfEmployment") # <-- test `@requires` functionality
  email: ID! @external
  name: String @override(from: "users")
  totalProductsCreated: Int @external
  yearsOfEmployment: Int! @external # <-- field from the users subgraph used by @requires
}

Updated implementations:

• absinthe-federation (Elixir)
• apollo-server (JavaScript / TypeScript)
• appsync (AWS Hosted)
• ariadne (Python)
• async-graphql (Rust)
• caliban (Scala)
• dgs (Java / Kotlin)
• express-graphql (JavaScript / TypeScript)
• federation-jvm (Java / Kotlin)
• gqlgen (Go)
• graphene (Python)
• graphql-dotnet (C# / .NET)
• graphql-java-kickstart (Java / Kotlin)
• graphql-kotlin (Java / Kotlin)
• graphql-yoga (JavaScript / TypeScript)
• hotchocolate (C# / .NET)
• lighthouse (PHP)
• mercurius (JavaScript / TypeScript)
• nestjs (JavaScript / TypeScript)
• php (PHP)
• pothos (JavaScript / TypeScript)
• ruby (Ruby)
• stepzen (StepZen Hosted)
• strawberry-graphql (Python)

Not sure the best way to test this but we just noticed that absinthe_federation did not have up-to-date locations defined on a few federation directives. Not sure if they were wrong from the beginning or if @apollo/subgraph updated its implementation but it would be nice to know when that happens and have this test suite notify subgraph maintainers of those types of changes. absinthe_federation PR to update directive definitions for reference DivvyPayHQ/absinthe_federation#58

When receiving multiple representations, does it matter what order we return the entities in or should they match the order the representations are given in?

The test suite does not cover this and the specs does not either. So based on that I would assume no, but would be nice with a confirmation.

This is for the current pr #68 for adding support for Lighthouse, as we would like to know if we need to keep the order or not.

See #166 for details.

There is an interesting discussion about adding Federation support to graphql-go here: graphql-go/graphql#492

graphql-go is intended to be more of a graphql-js clone, which means Federation support doesn't necessarily belong in the library itself, but it looks like there are API changes that could be made to graphql-go to make it easier to use with Federation. The above linked to issue dives into this a bit (graphql-go/graphql#492 (comment)), but we'll need to validate this and see if any other changes are needed (see also graphql-go/graphql#541). If we can help get these changes in place, we can then think about potentially creating a Go based Federation helper library, like we've done with @apollo/subgraph (JS/Node) and federation-jvm (Java/JVM).

Update the compatibility suite to validate:

• @shareable
• @link
• @tag

Reference: https://www.apollographql.com/docs/federation/v2/federation-2/moving-to-federation-2#add-schema-definitions-to-non-apollo-subgraphs

So some issues that I encountered when I was trying to check for spec compliance locally, that I think should be addressed to help other maintainers with their implementations.

• There aren't very clear instructions on how to run everything without docker. Usually when I am testing this I am just trying to get it to run with a local instance so that I can verify the fixes that go into caliban, so I don't really want to have to deploy and run docker. There are scripts for running the user and inventory graphs, but the script for running the gateway doesn't point to a real directory (also I had to change the paths of the subgraphs because they point to dist folders that don't get built).
• The testing schemas appear inconsistent, the required one is this but the one in the reference for graphql-yoga is this
• There should probably be a step to have the implementation generate the schema, at the moment it is just sitting alongside the implementation but the two could be completely different.

Are there any requirements to add federation 2 compatibility vs federation 1?

I'm not 100% on what they might be 🤷 but is it worth pointing out compatibility e.g. @provides might no longer be a valid check for fed2?

It'd be great if the tests for each feature returned a rich response, like a diff of the expected and actual output, instead of just a boolean. You could write the diffs to a separate log file to make it easier to determine the error.

See #166 for details.

See #166 for details

Issue to track which subgraph implementations should be updated due to the recent schema changes introduced for better @requires (#150) and @key (#165) tests.

Subgraph implementations:

• absinthe-federation (Elixir)
• apollo-server (JavaScript / TypeScript)
• #179
• #180
• #181
• #182
• dgs (Java / Kotlin)
• #183
• federation-jvm (Java / Kotlin)
• #184
• #185
• #186
• #187
• graphql-kotlin (Java / Kotlin)
• #188
• #189
• #190
• #191
• #192
• #193
• #194
• #195
• #196
• strawberry-graphql (Python)

Related issues:

• supersedes #128
• schema change introduced in #150
• schema change introduced in #165

Currently our tests execute

query ($representations: [_Any!]!) {
  _entities(representations: $representations) {
    ...on Product { sku }
  }
}

with various representations and verify we got some response. As long as implementing libraries have valid federated resolver that can handle various representations, then tests are marked as successful even though those @key definitions might not be present in the SDL.

See #166 for details.

Since ExpediaGroup/graphql-kotlin#1459 was merged (thanks @dariuszkuc!).

Container fails to start locally and from Github actions.

The ❌ emoji we use in our test results can sometimes make things look worse than they should, as not all libraries will want to have full Federation support (e.g. some libraries might just want to support API-side joins and the use of entities in other subgraphs). Let's find a more toned down emoji or another way to indicate certain features that aren't supported (and that aren't as required to support, depending on the library).

For example:

This work consists of 2 main parts:

1. Validate that Federation JVM 2.0 (with Fed 2 support) can be used with DGS to provide full Federation 2 support.
2. Work with the DGS folks to facilitate updating to Federation JVM 2.0

Spec details in apollographql/federation#2065.

It would be really great to help get Fed 2 support in place for async-graphql.

async-graphql/async-graphql#982

Container fails to start locally and from Github actions.

It would be helpful to know which libraries support schema contracts @tag directive. Would also be a good signal to maintainers to add support for it

See #166 for details.

See #166 for details.

https://github.com/mercurius-js/mercurius

I'm planning on taking a swing at getting a PR open for this in the next few weeks, but wanted to get an issue open in case I get pulled away, or if anyone else has started any work for this.

The test for @inaccessible tests that the field unit marked with @inaccessible can be returned directly from products.
@inaccessible

However the spec for @inaccessible says:
The processor implementing @inaccessible must ensure that it returns a public‐facing API with all @inaccessible items removed:

I read that as unit must be removed from the public api and so should not be able to be selected.

https://specs.apollo.dev/inaccessible/v0.2/

Maybe it's because @inaccessible has a different definition here:
https://www.apollographql.com/docs/federation/federated-types/federated-directives#inaccessible

but it's unclear, since the actual federation spec does not list @inaccessible so I assume it's defined from https://specs.apollo.dev/inaccessible/v0.2/

code-first libraries will probably generate the subgraph SDL differently from the products.graphql file. ruby alphabetizes fields, for example

• Support for graphql-java-tools / graphql-spring-boot
• apollographql/federation-jvm graphql-java-tools sample

See #166 for details.

It would be nice to have a CLI-like tool to invoke this test from CI.

• Complete abstracting test framework

This would help individual libraries prevent releasing something that breaks the spec vs catching the break after the release

We're receiving more and more requests to validate Federation support with hosted services. This project is mostly validating Federation support with locally run applications/subgraphs (that are committed to the repo), but does support validating remote subgraphs (including those hosted in the cloud / behind an API). We're currently using an nginx based proxy approach with AppSync, that could be used with other providers. We should:

• Document this approach in the README
• Explain how custom headers like those needed for auth can be included
• Adjust the test results to clearly identify if they're the result of running against a local or remote subgraph

Currently products subgraph defines Product entity with multiple @key directives. Various @key use cases (single field, multiple field, composite object keys) are tested directly against the target subgraph by passing _entities query and various representations.

This testing approach is somewhat problematic as not every implementation supports repeatable directives, which means that while entity resolution logic might be fine there will be only a single @key directive present in the schema. Gateway will not be able to query the entities using other keys as they will not exist in the supergraph schema.

Proposed changes:

• keep current Product with multiple @key directives but use it to verify single field key and repeatable directive use case
• introduce new entity with multiple field @key
• introduce new entity with composite object keys (i.e. field set specifies key from an object, foo { bar }) @key

Composed directives like @inaccessible and @tag must not use @federation__ prefix and be consistently named across subgraph implementations.

See comments in:

• apollographql/federation#1976

We should update the compatibility tests to ensure this.