Implementation of @internal directive

[andrewmcgivery]

What

In #371, there is a proposal to add a @internal directive to allow for fields that are available internally to the graph but are not exposed externally to consumers through the Gateway schema.

A previous PR removed these fields during the compose process but it was pointed out by @trevor-scheer that the approach would break Gateway functionality such as @requires.

This PR looks to solve this by removing the @internal fields during the gateway.load process and onSchemaChange event. This means that Gateway will has access to the full schema but Apollo Server exposes a schema that does not contain these fields.

Example

# Schema Definition
extend type Query {
   myNormalField: String
   myInternalField: String @internal
}

# Exposed Schema
type Query {
   myNormalField: String
}

Caveats and Unresolved Items

• I haven't finished adding tests, comments, docs, etc. I wanted to submit this to get some feedback and make sure this is something Apollo is still interested in before spending a huge amount of time
• There are some failing rust tests that I would need to fix
• The @internal directive as added to the SupergraphSdl so that it is maintained when the schema is composed and validated in Gateway but it is removed before the schema is provided to Apollo Server
• This is my first deep dive into the federation code so this approach may be naive.
• Hoping for some feedback if this is something the Apollo team is interested in moving forward

[prasek]

@andrewmcgivery thanks for this PR. @internal support is on our near term radar and we'd love to incorporate your thinking here into an upcoming release. stay tuned for an update, thanks!

[glasser]

Agreed that this can be a great starting point.

For transparency: our biggest issue with implementing this is a design question about how to represent this feature in the supergraph SDL. The supergraph SDL is specified in the join spec which is based on the core spec for declaring the use of other specs, and we're not sure if the directive that means "this field is external" in supergraph should be defined as part of join or core. We hope to resolve this soon!

[andrewmcgivery]

Appreciate the responses @prasek and @glasser!

[monkybrain]

What is the current status of the @internal directive? Can't find it in the official docs so presume it's still not released? @andrewmcgivery @prasek

[prasek]

@andrewmcgivery @monkybrain we're calling this @inaccessible now

• here's a working example
  • https://github.com/apollographql/supergraph-demo-fed2/pull/132
• you can now import the @inaccessible directive into your subgraph schemas
  • with @link(import: - see https://www.apollographql.com/docs/federation/federation-spec/#link
  • subgraph libraries that support Fed 2: https://www.apollographql.com/docs/federation/other-servers/
  • if your subgraph library doesn't support automatically adding the Fed 2 directive definitions for @link(import:, you can manually add the directive definition for @inaccessible to your subgraph schema and it should work
  • see https://specs.apollo.dev/inaccessible/v0.2/ for reference, but note the examples describe @inaccessible usage on a supergraph schema

@benweatherman @hwillson we need to add @inaccessible (and @tag) to the Apollo Federation subgraph specification.

• it's not mentioned except in the @link(import: example

[prasek]

cc @StephenBarlow

[monkybrain]

Thanks for the update @prasek!