feat(graphql): implement federation support

Author: ayanalamMOON

configs/default.yaml

@@ -80,4 +80,16 @@ graphql:
     enable_http_handler: true       # Expose /graphql/docs endpoint
     auto_export: false              # Auto-write docs to file after generation
     export_path: ""                 # Optional output file path for schema docs
+  federation:
+    enabled: true                   # Enable GraphQL federation support (_service/_entities)
+    service_name: "helios"         # Service name exposed to supergraph composition
+    service_version: "1.0.0"       # Service version metadata
+    include_service_sdl: true       # Expose schema SDL via _service.sdl
+    strict_entities: false          # If true, unknown/invalid entities fail the entire request
+    entity_types:                   # Allowed federated entity types
+      - "User"
+      - "KVPair"
+      - "Job"
+      - "ShardNode"
+      - "RaftPeer"
 

docs/GRAPHQL_IMPLEMENTATION.md

@@ -1458,6 +1458,116 @@ When `enable_http_handler` is true, gateway exposes:
 4. **Enable auto-export** in environments where docs need to be persisted.
 5. **Use type-specific queries** (`schemaTypeDocumentation`) for targeted tooling.
 
+## GraphQL Federation Support
+
+Helios now supports Apollo-style federation primitives for service composition in a supergraph.
+
+### Implementation
+
+Federation support is implemented and integrated in:
+
+- `internal/graphql/federation.go` (federation config + manager)
+- `internal/graphql/resolver.go` (`_service`, `_entities`, and federation config resolvers)
+- `internal/graphql/handler.go` (federation query routing)
+- `internal/graphql/schema.go` (federation SDL: directives, `_Service`, `_Entity`, entity keys)
+
+### Federation Capabilities
+
+- `_service { sdl }` for schema composition
+- `_entities(representations: [_Any!]!)` entity resolution
+- Config query: `federationConfig`
+- Entity support for: `User`, `KVPair`, `Job`, `ShardNode`, `RaftPeer`
+- Strict/non-strict entity resolution modes
+
+### Configuration
+
+Add to `configs/default.yaml` under `graphql`:
+
+```yaml
+graphql:
+  federation:
+    enabled: true
+    service_name: "helios"
+    service_version: "1.0.0"
+    include_service_sdl: true
+    strict_entities: false
+    entity_types:
+      - "User"
+      - "KVPair"
+      - "Job"
+      - "ShardNode"
+      - "RaftPeer"
+```
+
+### Programmatic Setup
+
+```go
+handler := graphql.NewHandler(resolver, authService,
+    graphql.WithFederationConfig(&graphql.FederationConfig{
+        Enabled:           true,
+        ServiceName:       "helios",
+        ServiceVersion:    "1.0.0",
+        IncludeServiceSDL: true,
+        StrictEntities:    false,
+        EntityTypes:       []string{"User", "KVPair", "Job", "ShardNode", "RaftPeer"},
+    }),
+)
+```
+
+### Federation Queries
+
+Service SDL:
+
+```graphql
+query {
+  _service {
+    sdl
+  }
+}
+```
+
+Entity resolution:
+
+```graphql
+query ResolveEntities($representations: [_Any!]!) {
+  _entities(representations: $representations)
+}
+```
+
+Variables:
+
+```json
+{
+  "representations": [
+    { "__typename": "User", "id": "<user-id>" },
+    { "__typename": "KVPair", "key": "data:example" }
+  ]
+}
+```
+
+Runtime federation config:
+
+```graphql
+query {
+  federationConfig {
+    enabled
+    serviceName
+    serviceVersion
+    includeServiceSDL
+    strictEntities
+    entityTypeCount
+    entityTypes
+  }
+}
+```
+
+### Best Practices
+
+1. Keep `include_service_sdl` enabled for composition environments.
+2. Use `strict_entities: true` in controlled environments to surface bad representations early.
+3. Restrict `entity_types` to only entities you actually expose.
+4. Monitor `_entities` traffic patterns and cache hot entity lookups upstream when possible.
+
 ## Troubleshooting
 
 ### Common Issues
@@ -1490,7 +1600,7 @@ Planned features:
 - [x] Rate limiting per resolver (implemented in `internal/graphql/rate_limiter.go`)
 - [x] Persisted queries (implemented in `internal/graphql/persisted_queries.go`)
 - [x] Automatic schema documentation (implemented in `internal/graphql/schema_documentation.go`)
-- [ ] GraphQL Federation support
+- [x] GraphQL Federation support (implemented in `internal/graphql/federation.go`)
 - [ ] Custom directives
 - [ ] File upload support
 

internal/config/config.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"strings"
 	"sync"
 	"time"
 
@@ -114,6 +115,7 @@ type GraphQLConfig struct {
 	MaxComplexity        int                     `yaml:"max_complexity" json:"max_complexity"`
 	AllowedOrigins       []string                `yaml:"allowed_origins" json:"allowed_origins"`
 	SchemaDocs           GraphQLSchemaDocsConfig `yaml:"schema_docs" json:"schema_docs"`
+	Federation           GraphQLFederationConfig `yaml:"federation" json:"federation"`
 }
 
 // GraphQLSchemaDocsConfig contains automatic schema documentation settings.
@@ -127,6 +129,16 @@ type GraphQLSchemaDocsConfig struct {
 	ExportPath        string `yaml:"export_path" json:"export_path"`
 }
 
+// GraphQLFederationConfig contains GraphQL federation settings.
+type GraphQLFederationConfig struct {
+	Enabled           bool     `yaml:"enabled" json:"enabled"`
+	ServiceName       string   `yaml:"service_name" json:"service_name"`
+	ServiceVersion    string   `yaml:"service_version" json:"service_version"`
+	IncludeServiceSDL bool     `yaml:"include_service_sdl" json:"include_service_sdl"`
+	StrictEntities    bool     `yaml:"strict_entities" json:"strict_entities"`
+	EntityTypes       []string `yaml:"entity_types" json:"entity_types"`
+}
+
 // NewManager creates a new configuration manager
 func NewManager(configPath string) (*Manager, error) {
 	cfg, err := loadConfigFromFile(configPath)
@@ -764,6 +776,18 @@ func (c *Config) Validate() error {
 		}
 	}
 
+	if strings.TrimSpace(c.GraphQL.Federation.ServiceName) == "" {
+		return fmt.Errorf("graphql.federation.service_name cannot be empty")
+	}
+	if strings.TrimSpace(c.GraphQL.Federation.ServiceVersion) == "" {
+		return fmt.Errorf("graphql.federation.service_version cannot be empty")
+	}
+	for i, entityType := range c.GraphQL.Federation.EntityTypes {
+		if strings.TrimSpace(entityType) == "" {
+			return fmt.Errorf("graphql.federation.entity_types[%d] cannot be empty", i)
+		}
+	}
+
 	return nil
 }
 
@@ -840,6 +864,17 @@ func (c *Config) ApplyDefaults() {
 	if c.GraphQL.SchemaDocs.DefaultFormat == "" {
 		c.GraphQL.SchemaDocs.DefaultFormat = "markdown"
 	}
+
+	// GraphQL federation defaults
+	if c.GraphQL.Federation.ServiceName == "" {
+		c.GraphQL.Federation.ServiceName = "helios"
+	}
+	if c.GraphQL.Federation.ServiceVersion == "" {
+		c.GraphQL.Federation.ServiceVersion = "1.0.0"
+	}
+	if len(c.GraphQL.Federation.EntityTypes) == 0 {
+		c.GraphQL.Federation.EntityTypes = []string{"User", "KVPair", "Job", "ShardNode", "RaftPeer"}
+	}
 }
 
 // Export exports the configuration as YAML

internal/config/config_test.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 )
@@ -1058,3 +1059,49 @@ func TestConfigDiffFieldChanges(t *testing.T) {
 		t.Errorf("Expected 0 immutable changes, got %d", len(immutableChanges))
 	}
 }
+
+func TestGraphQLFederationDefaults(t *testing.T) {
+	cfg := &Config{}
+	cfg.ApplyDefaults()
+
+	if cfg.GraphQL.Federation.ServiceName != "helios" {
+		t.Errorf("expected default federation service name helios, got %q", cfg.GraphQL.Federation.ServiceName)
+	}
+	if cfg.GraphQL.Federation.ServiceVersion != "1.0.0" {
+		t.Errorf("expected default federation service version 1.0.0, got %q", cfg.GraphQL.Federation.ServiceVersion)
+	}
+	if len(cfg.GraphQL.Federation.EntityTypes) == 0 {
+		t.Fatal("expected default federation entity types")
+	}
+}
+
+func TestGraphQLFederationValidation(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.yaml")
+
+	invalidConfig := `
+immutable:
+  node_id: "test-node"
+observability:
+  log_level: "INFO"
+graphql:
+  federation:
+    service_name: "helios"
+    service_version: "1.0.0"
+    entity_types:
+      - "User"
+      - ""
+`
+
+	if err := os.WriteFile(configPath, []byte(invalidConfig), 0644); err != nil {
+		t.Fatalf("Failed to write config: %v", err)
+	}
+
+	_, err := NewManager(configPath)
+	if err == nil {
+		t.Fatal("expected validation error for empty federation entity type")
+	}
+	if !strings.Contains(err.Error(), "graphql.federation.entity_types") {
+		t.Fatalf("expected federation entity types validation error, got: %v", err)
+	}
+}