Merge pull request #22 from rockneurotiko/support_apollo_federation

Support Apollo Federation

Author: rockneurotiko

.tool-versions

@@ -1,2 +1,2 @@
-erlang 28.1.1
-elixir 1.19.2-otp-28
+erlang 28.3
+elixir 1.19.4-otp-28

CHANGELOG.md

@@ -3,6 +3,9 @@
 All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
+### Added
+- Add `federation` and `F` options, this will read `@link` directive and add Apollo Federation directives based to parse and validate the schema
+
 ### Fixed
 - When reading an absinthe schema, print the errors if there were some compilation error
 

README.md

@@ -32,6 +32,7 @@ GraphQL Query provides a library for **validating, parsing, and formatting Graph
   - [Parsing and Validating Schemas](#parsing-and-validating-schemas)
   - [Schema Modules](#schema-modules)
   - [Document Validation Against Schema](#document-validation-against-schema)
+- [Apollo Federation Support](#apollo-federation-support)
 - [Formatter Integration](#formatter-integration)
 - [Manual API](#manual-api)
 - [Roadmap](#roadmap)
@@ -64,6 +65,7 @@ GraphQL Query provides a library for **validating, parsing, and formatting Graph
 - ✅ **Mix format integration** for `~GQL` sigil, `.graphql` and `.gql` files
 - ✅ **Schema modules** with automatic recompilation on schema changes
 - ✅ **Absinthe schema integration** for validating queries against existing Absinthe schemas
+- ✅ **Apollo Federation v2 support** for validating federated schemas with `@key`, `@shareable`, etc.
 - ✅ **Flexible validation modes**: compile-time, runtime, or ignore
 - ✅ **JSON encoding support** for Document structs (JSON/Jason protocols)
 - ⚡ Backed by Rust for fast parsing and validation
@@ -172,6 +174,7 @@ Req.post!("/api", json: user_query)
   - `s` → Parse as schema
   - `q` → Parse as query (this is the default behaviour)
   - `f` → Parse as fragment
+  - `F` → Enable Apollo Federation v2 directives (for schemas)
 
 ```elixir
 import GraphqlQuery
@@ -232,6 +235,7 @@ query GetUser($id: ID!) {
   - `schema: SchemaModule` → Specify the schema module to validate the query or fragment with
   - `fragments: [GraphqlQuery.Fragment.t()]` → Add reusable fragments to queries
   - `format: true` → Apply automatic formatting when converting to string
+  - `federation: true` → Enable Apollo Federation v2 directive support (for schemas)
 
 Example project structure:
 
@@ -276,6 +280,7 @@ end
   - `schema: SchemaModule` → Specify the schema module to validate the query or fragment with
   - `fragments: [GraphqlQuery.Fragment.t()]` → Add reusable fragments to queries
   - `format: true` → Apply automatic formatting when converting to string
+  - `federation: true` → Enable Apollo Federation v2 directive support (for schemas)
 
 ```elixir
 defmodule Example do
@@ -629,6 +634,103 @@ end
 
 ---
 
+## Apollo Federation Support
+
+GraphQL Query supports **Apollo Federation v2** directives, allowing you to validate federated schemas that use directives like `@key`, `@shareable`, `@external`, and others.
+
+### Enabling Federation Support
+
+Enable federation validation by setting the `federation: true` option. This makes all Apollo Federation v2 directives available in your schema.
+
+**With sigil (using `F` modifier):**
+
+```elixir
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key", "@shareable"])
+
+type User @key(fields: "id") {
+  id: ID!
+  name: String! @shareable
+}
+"""sF  # s = schema, F = federation
+```
+
+**With `gql` macro:**
+
+```elixir
+gql [type: :schema, federation: true], """
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key"])
+
+type Product @key(fields: "id") {
+  id: ID!
+  price: Float
+}
+"""
+```
+
+**With `gql_from_file` macro:**
+
+```elixir
+gql_from_file "priv/graphql/federated_schema.graphql", type: :schema, federation: true
+```
+
+**With `document_with_options`:**
+
+```elixir
+document_with_options type: :schema, federation: true do
+  ~GQL"""
+  extend schema @link(url: "https://specs.apollo.dev/federation/v2.9", import: ["@key"])
+  
+  type Order @key(fields: "id") {
+    id: ID!
+    total: Float
+  }
+  """s
+end
+```
+
+**At module level:**
+
+```elixir
+defmodule MyApp.FederatedSchema do
+  use GraphqlQuery, federation: true
+  
+  def schema do
+    ~GQL"""
+    extend schema @link(url: "https://specs.apollo.dev/federation/v2.5", import: ["@key"])
+    
+    type User @key(fields: "id") {
+      id: ID!
+      name: String!
+    }
+    """s
+  end
+end
+```
+
+### Supported Federation Versions
+
+The library supports multiple Apollo Federation v2 versions. Specify the version in your `@link` directive:
+
+- `v2.0` - Base Apollo Federation v2 directives
+- `v2.5` - Adds `@authenticated` and `@requiresScopes`
+- `v2.9` - Adds `@cost` and `@listSize`
+
+Unknown versions automatically fall back to standard validation without federation directives.
+
+### Implementation Note
+
+When `federation: true` is enabled, **all Apollo Federation directives are available** for use in your schema, regardless of what you specify in the `@link` import list. This simplified approach covers the vast majority of use cases and makes it easier to work with federated schemas.
+
+The following directives are available:
+- Core directives: `@key`, `@requires`, `@provides`, `@external`, `@tag`, `@extends`, `@shareable`, `@inaccessible`, `@override`, `@composeDirective`, `@interfaceObject`
+- Authentication (v2.5+): `@authenticated`, `@requiresScopes`, `@policy`
+- Cost control (v2.9+): `@cost`, `@listSize`
+
+---
+
 ## Formatter Integration
 
 Add to `.formatter.exs`:

docs/cheatsheet.cheatmd

@@ -25,7 +25,8 @@ defmodule MyApp.Queries do
     ignore: false,
     evaluate: false,
     fragments: [],
-    format: false
+    format: false,
+    federation: false
 end
 ```
 {: .wrap}
@@ -193,6 +194,9 @@ type Query {
 
 # Schema document
 ~GQL""s
+
+# Federation support (for schemas)
+~GQL""sF
 ```
 {: .wrap}
 
@@ -250,6 +254,9 @@ query = gql_from_file("priv/queries/get_user.graphql", runtime: true)
 
 # Apply formatting when transformed to string
 query = gql_from_file("priv/queries/get_user.graphql", format: true)
+
+# Enable Apollo Federation directives (for schemas)
+schema = gql_from_file("priv/federated_schema.graphql", type: :schema, federation: true)
 ```
 {: .wrap}
 
@@ -320,6 +327,9 @@ query = gql [runtime: true], ""
 
 # Apply automatic formatting when transforming to string
 query = gql [format: true], "query{user{id name}}"
+
+# Enable Apollo Federation directives (for schemas)
+schema = gql [type: :schema, federation: true], ""
 ```
 {: .wrap}
 
@@ -419,6 +429,172 @@ Jason.encode!(query)
 ```
 {: .wrap}
 
+## Apollo Federation
+{: .col-2}
+
+### Federation Schema with Sigil
+
+```elixir
+# Use the "F" modifier to enable federation directives
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@shareable"])
+
+type User @key(fields: "id") {
+  id: ID!
+  name: String! @shareable
+  email: String!
+}
+"""sF # <- "s" for schema, "F" for federation
+```
+{: .wrap}
+
+### Federation with gql Macro
+
+```elixir
+# Use federation: true option
+schema = gql [type: :schema, federation: true], """
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.5", 
+    import: ["@key", "@authenticated"])
+
+type Product @key(fields: "id") @authenticated {
+  id: ID!
+  name: String!
+  price: Float
+}
+"""
+```
+{: .wrap}
+
+### Federation with gql_from_file
+
+```elixir
+# Load federated schema from file
+schema = gql_from_file(
+  "priv/federated_schema.graphql",
+  type: :schema,
+  federation: true
+)
+```
+{: .wrap}
+
+### Federation with document_with_options
+
+```elixir
+document_with_options type: :schema, federation: true do
+  ~GQL"""
+  extend schema
+    @link(url: "https://specs.apollo.dev/federation/v2.0", 
+      import: ["@key"])
+
+  type Order @key(fields: "id") {
+    id: ID!
+    total: Float
+  }
+  """s
+end
+```
+{: .wrap}
+
+### Module-level Federation
+
+```elixir
+defmodule MyApp.FederatedSchema do
+  use GraphqlQuery, federation: true
+
+  def schema do
+    ~GQL"""
+    extend schema
+      @link(url: "https://specs.apollo.dev/federation/v2.0", 
+        import: ["@key", "@external"])
+
+    type User @key(fields: "id") {
+      id: ID!
+      reviews: [Review!]! @external
+    }
+    """s
+  end
+end
+```
+{: .wrap}
+
+### Supported Federation Versions
+
+```elixir
+# Federation v2.0 - Base directives
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0", 
+    import: ["@key", "@requires", "@provides", "@external", 
+             "@tag", "@extends", "@shareable", "@inaccessible", 
+             "@override"])
+"""sF
+
+# Federation v2.5 - Adds authentication
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.5", 
+    import: ["@authenticated", "@requiresScopes"])
+"""sF
+
+# Federation v2.9 - Adds cost control
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.9", 
+    import: ["@cost", "@listSize"])
+"""sF
+```
+{: .wrap}
+
+### Federation with Renamed Directives
+
+```elixir
+# Rename directives with "as:"
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0", 
+    import: [{name: "@key", as: "@primaryKey"}])
+
+type Product @primaryKey(fields: "id") {
+  id: ID!
+  name: String!
+}
+"""sF
+```
+{: .wrap}
+
+### Federation with Custom Namespace
+
+```elixir
+# Use custom namespace prefix
+~GQL"""
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0", 
+    import: ["@key"], as: "fed")
+
+type User @key(fields: "id") {
+  id: ID!
+  # Non-imported directives use the prefix
+  name: String! @fed__shareable
+}
+"""sF
+```
+{: .wrap}
+
+### Federation Options in use GraphqlQuery
+
+```elixir
+defmodule MyApp.Schemas do
+  use GraphqlQuery,
+    federation: true,
+    # ... other options
+    schema: nil,
+    runtime: false
+end
+```
+{: .wrap}
+
 ## Full example!
 
 #### schema.ex