synthra 0.1.0

data/docs/GRAPHQL_FEDERATION.md

@@ -0,0 +1,651 @@
+# GraphQL Federation Export
+
+FakeDataDSL can export your schemas to **GraphQL Federation 2.0** compatible SDL, perfect for microservices architectures using Apollo Federation, Netflix DGS, or other federated GraphQL implementations.
+
+## Quick Start
+
+```bash
+# Export single schema
+fake_data_dsl export schemas/user.dsl -f graphql-federation -o user.graphql
+
+# Export all schemas
+fake_data_dsl export schemas/ --all -f graphql-federation -o schema.graphql
+```
+
+```ruby
+# Ruby API
+schema = FakeDataDSL.load("schemas/user.dsl")
+graphql = FakeDataDSL::Export::GraphQLFederation.new(schema).export
+
+puts graphql
+```
+
+## Basic Usage
+
+### Single Schema Export
+
+```ruby
+# Input schema (user.dsl)
+# User:
+#   id: uuid
+#   name: name
+#   email: email
+#   role: enum(user, admin, moderator)
+#   active: boolean
+#   created_at: timestamp
+
+schema = FakeDataDSL.load("schemas/user.dsl")
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema)
+puts exporter.export
+```
+
+Output:
+
+```graphql
+extend schema
+  @link(url: "https://specs.apollo.dev/federation/v2.0")
+
+type User @key(fields: "id") {
+  id: ID!
+  name: String!
+  email: String!
+  role: UserRole!
+  active: Boolean!
+  created_at: DateTime!
+}
+
+enum UserRole {
+  USER
+  ADMIN
+  MODERATOR
+}
+
+extend type Query {
+  user(id: ID!): User
+  users(first: Int, after: String): UserConnection!
+}
+
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+### Multiple Schemas
+
+```ruby
+# Export multiple schemas as one federated graph
+exporter = FakeDataDSL::Export::GraphQLFederation.new(
+  FakeDataDSL.load("schemas/user.dsl"),
+  FakeDataDSL.load("schemas/order.dsl"),
+  FakeDataDSL.load("schemas/product.dsl")
+)
+
+puts exporter.export
+```
+
+## Federation Directives
+
+### @key Directive
+
+Entity keys are automatically inferred from `id` fields or fields marked with `@key`:
+
+```ruby
+# In DSL
+User:
+  id: uuid @key
+  email: email @key  # Additional key
+
+# Output
+type User @key(fields: "id") @key(fields: "email") {
+  id: ID!
+  email: String!
+}
+```
+
+### @external and @provides
+
+For cross-service references:
+
+```ruby
+# In DSL
+Order:
+  id: uuid
+  user_id: Ref(User.id)  # Reference to User service
+  items: array(OrderItem, 1..10)
+  total: money
+
+# Configure federation
+FakeDataDSL::Export::GraphQLFederation.configure do |config|
+  config.external_types = ["User"]
+  config.provides = {
+    "Order" => { "user" => "id name email" }
+  }
+end
+```
+
+Output:
+
+```graphql
+type Order @key(fields: "id") {
+  id: ID!
+  user: User! @provides(fields: "id name email")
+  items: [OrderItem!]!
+  total: Float!
+}
+
+type User @key(fields: "id", resolvable: false) @external {
+  id: ID!
+}
+```
+
+### @shareable
+
+Mark types as shareable across services:
+
+```ruby
+# In DSL
+Address:
+  @shareable
+  street: text
+  city: city
+  country: country
+```
+
+Output:
+
+```graphql
+type Address @shareable {
+  street: String!
+  city: String!
+  country: String!
+}
+```
+
+## Subgraph Configuration
+
+### Service Definition
+
+```ruby
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema,
+  service_name: "users-service",
+  service_url: "https://users.example.com/graphql",
+  version: "2.0"
+)
+```
+
+### Multiple Subgraphs
+
+Generate separate files for each subgraph:
+
+```ruby
+# Define subgraph boundaries
+subgraphs = {
+  "users" => ["User", "Profile"],
+  "orders" => ["Order", "OrderItem"],
+  "products" => ["Product", "Category"]
+}
+
+subgraphs.each do |name, types|
+  schemas = types.map { |t| FakeDataDSL.schema(t) }
+  exporter = FakeDataDSL::Export::GraphQLFederation.new(*schemas,
+    service_name: "#{name}-service"
+  )
+  
+  File.write("subgraphs/#{name}.graphql", exporter.export)
+end
+```
+
+## Type Mapping
+
+### DSL to GraphQL Types
+
+| DSL Type | GraphQL Type |
+|----------|--------------|
+| `uuid` | `ID!` |
+| `text`, `name`, `email` | `String!` |
+| `number` | `Int!` |
+| `float`, `money` | `Float!` |
+| `boolean` | `Boolean!` |
+| `date` | `Date!` |
+| `timestamp` | `DateTime!` |
+| `enum(...)` | Custom Enum |
+| `array(...)` | `[Type!]!` |
+| `optional` (`?`) | Nullable |
+| `json` | `JSON` (custom scalar) |
+
+### Custom Scalars
+
+```ruby
+FakeDataDSL::Export::GraphQLFederation.configure do |config|
+  config.custom_scalars = {
+    "date" => "Date",
+    "timestamp" => "DateTime",
+    "json" => "JSON",
+    "money" => "BigDecimal",
+    "url" => "URL",
+    "email" => "Email"
+  }
+end
+```
+
+Output includes scalar definitions:
+
+```graphql
+scalar Date
+scalar DateTime
+scalar JSON
+scalar BigDecimal
+scalar URL
+scalar Email
+```
+
+## Mutations
+
+### Auto-Generated Mutations
+
+```ruby
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema,
+  generate_mutations: true
+)
+```
+
+Output:
+
+```graphql
+extend type Mutation {
+  createUser(input: CreateUserInput!): User!
+  updateUser(id: ID!, input: UpdateUserInput!): User!
+  deleteUser(id: ID!): Boolean!
+}
+
+input CreateUserInput {
+  name: String!
+  email: String!
+  role: UserRole
+  active: Boolean
+}
+
+input UpdateUserInput {
+  name: String
+  email: String
+  role: UserRole
+  active: Boolean
+}
+```
+
+### Custom Mutations
+
+```ruby
+# In DSL with @mutation annotation
+User:
+  id: uuid
+  name: name
+  email: email
+  
+  @mutations
+    create: CreateUser(name!, email!, role?)
+    update: UpdateUser(id!, name?, email?, role?)
+    deactivate: DeactivateUser(id!, reason?)
+```
+
+## Subscriptions
+
+```ruby
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema,
+  generate_subscriptions: true
+)
+```
+
+Output:
+
+```graphql
+extend type Subscription {
+  userCreated: User!
+  userUpdated(id: ID): User!
+  userDeleted: ID!
+}
+```
+
+## Entity Resolution
+
+### _entities Query
+
+Federation requires an `_entities` query for entity resolution:
+
+```ruby
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema,
+  include_entities_query: true  # default: true
+)
+```
+
+Output:
+
+```graphql
+union _Entity = User | Order | Product
+
+type Query {
+  _entities(representations: [_Any!]!): [_Entity]!
+  _service: _Service!
+}
+
+type _Service {
+  sdl: String!
+}
+
+scalar _Any
+```
+
+## Interfaces and Unions
+
+### Interfaces
+
+```ruby
+# In DSL
+Node:
+  @interface
+  id: uuid
+
+User < Node:
+  name: name
+  email: email
+
+Product < Node:
+  title: text
+  price: money
+```
+
+Output:
+
+```graphql
+interface Node {
+  id: ID!
+}
+
+type User implements Node @key(fields: "id") {
+  id: ID!
+  name: String!
+  email: String!
+}
+
+type Product implements Node @key(fields: "id") {
+  id: ID!
+  title: String!
+  price: Float!
+}
+```
+
+### Unions
+
+```ruby
+# In DSL
+SearchResult:
+  @union User | Product | Order
+```
+
+Output:
+
+```graphql
+union SearchResult = User | Product | Order
+
+extend type Query {
+  search(query: String!): [SearchResult!]!
+}
+```
+
+## Pagination
+
+### Relay-Style Connections
+
+```ruby
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema,
+  pagination_style: :relay  # default
+)
+```
+
+Output:
+
+```graphql
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+```
+
+### Offset Pagination
+
+```ruby
+exporter = FakeDataDSL::Export::GraphQLFederation.new(schema,
+  pagination_style: :offset
+)
+```
+
+Output:
+
+```graphql
+type UserList {
+  items: [User!]!
+  total: Int!
+  offset: Int!
+  limit: Int!
+}
+
+extend type Query {
+  users(offset: Int, limit: Int): UserList!
+}
+```
+
+## CLI Options
+
+```bash
+fake_data_dsl export [SCHEMA_PATH] -f graphql-federation [OPTIONS]
+
+Options:
+  -o, --output PATH           Output file path
+  --service-name NAME         Service name for subgraph
+  --service-url URL           Service URL for federation
+  --federation-version VER    Federation version (1 or 2, default: 2)
+  --no-mutations              Don't generate mutations
+  --no-subscriptions          Don't generate subscriptions
+  --no-pagination             Don't generate connection types
+  --pagination-style STYLE    Pagination style (relay or offset)
+  --external-types TYPES      Comma-separated external type names
+```
+
+Examples:
+
+```bash
+# Basic export
+fake_data_dsl export schemas/ -f graphql-federation -o schema.graphql
+
+# With service configuration
+fake_data_dsl export schemas/user.dsl -f graphql-federation \
+  --service-name users \
+  --service-url https://users.api.example.com/graphql \
+  -o users.graphql
+
+# Minimal export (no mutations/subscriptions)
+fake_data_dsl export schemas/ -f graphql-federation \
+  --no-mutations --no-subscriptions \
+  -o types-only.graphql
+```
+
+## API Reference
+
+### GraphQLFederation.new
+
+```ruby
+FakeDataDSL::Export::GraphQLFederation.new(*schemas, options = {})
+```
+
+**Parameters:**
+- `schemas` - One or more Schema objects
+- `options[:service_name]` - Subgraph service name
+- `options[:service_url]` - Subgraph service URL
+- `options[:version]` - Federation version ("1" or "2")
+- `options[:generate_mutations]` - Include mutations (default: false)
+- `options[:generate_subscriptions]` - Include subscriptions (default: false)
+- `options[:pagination_style]` - :relay or :offset
+- `options[:include_entities_query]` - Include _entities (default: true)
+- `options[:external_types]` - Array of external type names
+- `options[:custom_scalars]` - Hash of DSL type => GraphQL scalar
+
+### GraphQLFederation#export
+
+```ruby
+exporter.export
+# => String containing complete GraphQL SDL
+```
+
+### GraphQLFederation#export_to_file
+
+```ruby
+exporter.export_to_file("schema.graphql")
+```
+
+## Integration Examples
+
+### Apollo Router
+
+```yaml
+# supergraph.yaml
+federation_version: 2
+subgraphs:
+  users:
+    routing_url: https://users.example.com/graphql
+    schema:
+      file: ./users.graphql  # Generated by FakeDataDSL
+  orders:
+    routing_url: https://orders.example.com/graphql
+    schema:
+      file: ./orders.graphql
+```
+
+### Netflix DGS
+
+```kotlin
+// The generated schema works with DGS
+@DgsComponent
+class UserDataFetcher {
+    @DgsQuery
+    fun user(@InputArgument id: String): User {
+        // Resolver implementation
+    }
+    
+    @DgsEntityFetcher(name = "User")
+    fun user(values: Map<String, Any>): User {
+        // Entity resolver for federation
+    }
+}
+```
+
+### Apollo Server
+
+```javascript
+// The generated schema works with Apollo Server
+import { buildSubgraphSchema } from '@apollo/subgraph';
+import { readFileSync } from 'fs';
+
+const typeDefs = gql(readFileSync('./user.graphql', 'utf8'));
+
+const server = new ApolloServer({
+  schema: buildSubgraphSchema({ typeDefs, resolvers })
+});
+```
+
+## Best Practices
+
+### 1. One Entity Per Service
+
+```ruby
+# Good: Clear ownership
+# users-service owns User, Profile
+# orders-service owns Order, OrderItem
+
+# Avoid: Shared ownership
+# Both services define User (unless @shareable)
+```
+
+### 2. Use @key Thoughtfully
+
+```ruby
+# Good: Natural keys
+User:
+  id: uuid @key
+  email: email @key  # Secondary lookup
+
+# Avoid: Composite keys when unnecessary
+User:
+  id: uuid @key
+  tenant_id: uuid @key  # Only if truly needed
+```
+
+### 3. Keep Schemas Aligned
+
+```ruby
+# Use the DSL as source of truth
+# Generate GraphQL from DSL, not the other way around
+```
+
+## Troubleshooting
+
+### Missing @key Directive
+
+```ruby
+# Make sure id field exists or add @key annotation
+User:
+  id: uuid  # Auto-detected as key
+  
+# Or explicit
+User:
+  user_id: uuid @key  # Explicit key
+```
+
+### Enum Name Conflicts
+
+```ruby
+# Use namespaced enums
+User:
+  status: enum(active, inactive) @enum_name(UserStatus)
+
+Product:
+  status: enum(draft, published) @enum_name(ProductStatus)
+```
+
+### Circular References
+
+```ruby
+# Federation handles this via external types
+# User service:
+User:
+  orders: array(Ref(Order))
+
+# Order service:
+Order:
+  user: Ref(User) @external
+```
+
+## See Also
+
+- [GraphQL Export](GRAPHQL_EXPORT.md) - Standard GraphQL (non-federated)
+- [OpenAPI Export](OPENAPI_EXPORT.md)
+- [Protobuf Export](PROTOBUF_EXPORT.md)
+- [Type Reference](type_reference.md)