Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/connect-spec-definitions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@apollo/subgraph': minor
---

Add Apollo Connectors spec definitions. A subgraph that `@link`s `https://specs.apollo.dev/connect/v0.1` through `v0.4` now gets the `@connect` and `@source` directives and their supporting types, following the link's `import` list and `as` namespace, with the definitions composition (v2.15+) expects. Connector usage itself is still validated by composition.

A connectors subgraph's `_service { sdl }` leaves out the `_service` / `_entities` fields and the `_Service`, `_Any` and `_Entity` types, which composition rejects in a connectors subgraph. The schema still serves them.
10 changes: 10 additions & 0 deletions .changeset/link-handling-fixes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
'@apollo/subgraph': patch
---

Align `@link` handling with composition:

- `@link(as: ...)` is now honoured for the federation link, so elements that aren't imported are namespaced under the alias instead of `federation__`.
- `@link(url: "https://specs.apollo.dev/link/v1.0", import: [...])` now names `Import` and `Purpose` after its imports instead of always using `link__Import` / `link__Purpose`.
- A `@link` URL with a trailing slash after the version (`.../federation/v2.9/`) is now rejected, matching composition.
- A `@link` URL with extra path segments under a known specification (`https://specs.apollo.dev/federation/extra/v1.0`) now links a custom specification (`extra`), as in composition, instead of being read as a federation link.
20 changes: 20 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,26 @@ await startStandaloneServer(server, { listen: { port: 4001 } });
Entity references are resolved through `__resolveReference`, either from a
resolver map or from `extensions.apollo.subgraph.resolveReference` on the type.

### Apollo Connectors

Schemas that `@link` the [Apollo Connectors](https://www.apollographql.com/docs/graphos/connectors)
specification (`https://specs.apollo.dev/connect/v0.1` through `v0.4`) get the
`@connect` and `@source` directives and their supporting types, so connectors
schemas can be built, printed and inspected:

```graphql
extend schema
@link(url: "https://specs.apollo.dev/federation/v2.12", import: ["@key"])
@link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@connect", "@source"])
@source(name: "api", http: { baseURL: "https://api.example.com" })
```

Connectors are executed by the router, not by this library, and whether they are
used correctly is validated by composition. Because composition requires every
field of a connectors subgraph to be resolved by a connector, `_service { sdl }`
leaves out the `_service` / `_entities` fields and their `_Service`, `_Any` and
`_Entity` types; the schema still serves them.

## Development

```sh
Expand Down
94 changes: 94 additions & 0 deletions src/__tests__/buildSubgraphSchema.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -341,6 +341,30 @@ describe('@link', () => {
).toThrow(UnsupportedFederationVersionError);
});

it('rejects a federation @link url with a trailing slash', () => {
expect(() =>
buildSubgraphSchema(
parse(`${fed2('v2.9/')} type Query { hello: String }`),
),
).toThrow(UnsupportedFederationVersionError);
});

it('treats a url with extra path segments under federation as a custom specification', () => {
const schema = buildSubgraphSchema(
parse(`
${fed2('v2.9', '"@key"')}
extend schema @link(url: "https://specs.apollo.dev/federation/extra/v1.0", import: ["@foo"])
directive @foo on FIELD_DEFINITION
type Product @key(fields: "id") { id: ID! name: String @foo }
`),
);

expect(schema.getDirective('key')).toBeDefined();
expect(
(schema.getType('_Entity') as GraphQLUnionType).getTypes(),
).toHaveLength(1);
});

it('rejects an import the linked version does not define', () => {
expect(() =>
buildSubgraphSchema(
Expand All @@ -363,6 +387,76 @@ describe('@link', () => {
).toThrow(MultipleFederationLinksError);
});

it('namespaces federation definitions under the @link alias', () => {
const schema = buildSubgraphSchema(
parse(`
extend schema @link(url: "https://specs.apollo.dev/federation/v2.9", as: "fed")
type Product @fed__key(fields: "id") { id: ID! }
`),
);

expect(schema.getDirective('fed__key')).toBeDefined();
expect(schema.getDirective('federation__key')).toBeUndefined();
expect(schema.getType('fed__FieldSet')).toBeDefined();
expect(
(schema.getType('_Entity') as GraphQLUnionType).getTypes(),
).toHaveLength(1);
});

it('names link specification types after the link spec imports', () => {
const schema = buildSubgraphSchema(
parse(`
schema @link(url: "https://specs.apollo.dev/link/v1.0", import: ["Import", { name: "Purpose", as: "LinkPurpose" }]) {
query: Query
}
extend schema @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@key"])
type Query { hello: String }
`),
);

expect(schema.getType('Import')).toBeDefined();
expect(schema.getType('LinkPurpose')).toBeDefined();
expect(schema.getType('link__Import')).toBeUndefined();
expect(schema.getType('link__Purpose')).toBeUndefined();
expect(
schema
.getDirective('link')!
.args.map((arg) => `${arg.name}: ${arg.type}`),
).toEqual([
'url: String',
'as: String',
'for: LinkPurpose',
'import: [Import]',
]);
});

it('namespaces link specification types that are not imported', () => {
const schema = buildSubgraphSchema(
parse(`
schema @link(url: "https://specs.apollo.dev/link/v1.0") { query: Query }
extend schema @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@key"])
type Query { hello: String }
`),
);

expect(schema.getType('link__Import')).toBeDefined();
expect(schema.getType('link__Purpose')).toBeDefined();
});

it('rejects an import the link specification does not define', () => {
expect(() =>
buildSubgraphSchema(
parse(`
schema @link(url: "https://specs.apollo.dev/link/v1.0", import: ["FieldSet"]) { query: Query }
extend schema @link(url: "https://specs.apollo.dev/federation/v2.9")
type Query { hello: String }
`),
),
).toThrow(
'Cannot import "FieldSet": it is not part of the link specification v1.0.',
);
});

it('defines @link for a schema that only links a custom specification', () => {
const schema = buildSubgraphSchema(
parse(`
Expand Down
Loading