GraphQL Extension for Forge

Production-ready GraphQL server extension powered by gqlgen, providing type-safe GraphQL APIs with automatic code generation, schema management, and full observability support.

Features

✅ Type-safe GraphQL - Automatic code generation from GraphQL schemas
✅ Multiple transports - HTTP (GET/POST), WebSocket subscriptions
✅ Built-in optimization - Query complexity limits, automatic persisted queries (APQ)
✅ DataLoader support - N+1 query optimization with batching and caching
✅ Custom directives - Authentication, authorization, and custom logic
✅ Apollo Federation v2 - Microservices composition ready
✅ File uploads - Multipart form data support
✅ GraphQL Playground - Interactive query exploration
✅ Full observability - Logging, metrics, and tracing integration
✅ DI integration - Access to Forge services via dependency injection

Installation

go get github.com/xraph/forge/extensions/graphql
go get github.com/99designs/gqlgen@v0.17.45

Quick Start

1. Define Your GraphQL Schema

Create schema/schema.graphql:

directive @auth(requires: String) on FIELD_DEFINITION

type Query {
  hello(name: String!): String!
  version: String!
}

type Mutation {
  echo(message: String!): String!
}

2. Generate Code

go run github.com/99designs/gqlgen generate

3. Implement Resolvers

Edit schema.resolvers.go:

func (r *queryResolver) Hello(ctx context.Context, name string) (string, error) {
    r.logger.Debug("hello query called", forge.F("name", name))
    return fmt.Sprintf("Hello, %s!", name), nil
}

4. Register Extension

package main

import (
    "context"
    "github.com/xraph/forge"
    "github.com/xraph/forge/extensions/graphql"
)

func main() {
    // Create Forge app
    app := forge.NewApp(forge.DefaultAppConfig())

    // Register GraphQL extension
    gqlExt := graphql.NewExtension(
        graphql.WithEndpoint("/graphql"),
        graphql.WithPlayground(true),
        graphql.WithMaxComplexity(1000),
        graphql.WithQueryCache(true, 5*time.Minute),
    )
    
    if err := app.RegisterExtension(gqlExt); err != nil {
        log.Fatal(err)
    }

    // Start the app
    if err := app.Start(context.Background()); err != nil {
        log.Fatal(err)
    }

    // Run server
    if err := app.Run(context.Background(), ":8080"); err != nil {
        log.Fatal(err)
    }
}

5. Query Your API

# Query
curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ hello(name: \"World\") }"}'

# Or visit the playground
open http://localhost:8080/playground

Configuration

Full Configuration Example

config := graphql.DefaultConfig()
config.Endpoint = "/api/graphql"
config.PlaygroundEndpoint = "/api/playground"
config.EnablePlayground = true
config.EnableIntrospection = true

// Performance
config.MaxComplexity = 1000
config.MaxDepth = 15
config.QueryTimeout = 30 * time.Second

// DataLoader
config.EnableDataLoader = true
config.DataLoaderBatchSize = 100
config.DataLoaderWait = 10 * time.Millisecond

// Caching
config.EnableQueryCache = true
config.QueryCacheTTL = 5 * time.Minute
config.MaxCacheSize = 1000

// Security
config.EnableCORS = true
config.AllowedOrigins = []string{"https://example.com"}
config.MaxUploadSize = 10 * 1024 * 1024 // 10MB

// Observability
config.EnableMetrics = true
config.EnableTracing = true
config.EnableLogging = true
config.LogSlowQueries = true
config.SlowQueryThreshold = 1 * time.Second

ext := graphql.NewExtensionWithConfig(config)

Environment Variables/Config File

# config.yaml
extensions:
  graphql:
    endpoint: "/graphql"
    playground_endpoint: "/playground"
    enable_playground: true
    enable_introspection: true
    max_complexity: 1000
    max_depth: 15
    query_timeout: 30s
    enable_dataloader: true
    dataloader_batch_size: 100
    dataloader_wait: 10ms
    enable_query_cache: true
    query_cache_ttl: 5m
    max_cache_size: 1000
    enable_cors: true
    allowed_origins:
      - "https://example.com"
    max_upload_size: 10485760
    enable_metrics: true
    enable_tracing: true
    enable_logging: true
    log_slow_queries: true
    slow_query_threshold: 1s

Advanced Features

DataLoader for N+1 Query Optimization

import "github.com/xraph/forge/extensions/graphql/dataloader"

// Create a loader
config := dataloader.DefaultLoaderConfig()
loader := dataloader.NewLoader(config, func(ctx context.Context, keys []interface{}) ([]interface{}, []error) {
    // Batch load users by IDs
    ids := make([]int, len(keys))
    for i, key := range keys {
        ids[i] = key.(int)
    }
    
    users, err := db.GetUsersByIDs(ctx, ids)
    if err != nil {
        errs := make([]error, len(keys))
        for i := range errs {
            errs[i] = err
        }
        return nil, errs
    }
    
    // Return in same order as keys
    results := make([]interface{}, len(keys))
    for i, user := range users {
        results[i] = user
    }
    return results, make([]error, len(keys))
})

// Use in resolver
func (r *userResolver) Friends(ctx context.Context, obj *User) ([]*User, error) {
    friends, err := loader.LoadMany(ctx, obj.FriendIDs)
    if err != nil {
        return nil, err
    }
    return friends.([]*User), nil
}

Custom Directives

Define in schema:

directive @auth(requires: String) on FIELD_DEFINITION

type Query {
  adminOnly: String! @auth(requires: "admin")
  user: String! @auth
}

Implement directive:

import "github.com/xraph/forge/extensions/graphql/directives"

// Configure in gqlgen.yml
// directives:
//   auth:
//     skip_runtime: false

// Use built-in auth directive or implement custom
func (r *Resolver) Directive() generated.DirectiveRoot {
    return generated.DirectiveRoot{
        Auth: directives.Auth,
    }
}

Apollo Federation v2

Configure in gqlgen.yml:

federation:
  filename: generated/federation.go
  package: generated
  version: 2

Define federated schema:

extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@key", "@external"])

type User @key(fields: "id") {
  id: ID!
  name: String!
}

extend type Product @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!
}

File Uploads

scalar Upload

type Mutation {
  uploadFile(file: Upload!): String!
}

func (r *mutationResolver) UploadFile(ctx context.Context, file graphql.Upload) (string, error) {
    content, err := io.ReadAll(file.File)
    if err != nil {
        return "", err
    }
    
    // Process file...
    return fmt.Sprintf("Uploaded %s (%d bytes)", file.Filename, len(content)), nil
}

Dependency Injection

Access Forge services in resolvers:

type Resolver struct {
    container forge.Container
    logger    forge.Logger
    metrics   forge.Metrics
    config    Config
}

func (r *queryResolver) GetData(ctx context.Context) (*Data, error) {
    // Resolve database from DI using helper function
    db, err := database.GetDatabase(r.container)
    if err != nil {
        return nil, err
    }
    
    // Use services
    r.logger.Info("fetching data")
    r.metrics.Counter("data_requests").Inc()
    
    return db.QueryData(ctx)
}

Observability

Logging

// Automatic operation logging
[DEBUG] graphql operation start {operation: "GetUser", type: "query"}
[DEBUG] graphql operation complete {operation: "GetUser", duration: "15ms"}

// Slow query logging
[WARN] slow query detected {operation: "ComplexQuery", duration: "1.5s", query: "..."}

// Error logging
[ERROR] graphql error {operation: "UpdateUser", error: "validation failed", path: ["updateUser"]}

Metrics

Automatically collected:

graphql_operation_duration_seconds - Operation latency histogram
graphql_operation_total - Total operations counter

Both tagged with:

operation - Operation name
type - query, mutation, or subscription

Tracing

Full distributed tracing support via OpenTelemetry integration.

Testing

func TestGraphQLQuery(t *testing.T) {
    container := forge.NewContainer()
    logger := forge.NewNoopLogger()
    metrics := forge.NewNoOpMetrics()
    config := graphql.DefaultConfig()

    server, err := graphql.NewGraphQLServer(config, logger, metrics, container)
    if err != nil {
        t.Fatal(err)
    }

    handler := server.HTTPHandler()

    query := `{"query":"{ hello(name: \"Test\") }"}`
    req := httptest.NewRequest("POST", "/graphql", strings.NewReader(query))
    req.Header.Set("Content-Type", "application/json")
    w := httptest.NewRecorder()
    
    handler.ServeHTTP(w, req)

    if w.Code != 200 {
        t.Errorf("expected 200, got %d", w.Code)
    }
}

Performance Best Practices

Enable Query Caching - Use APQ for frequently executed queries
Set Complexity Limits - Prevent resource exhaustion
Use DataLoader - Batch and cache data loading
Enable Compression - Reduce bandwidth
Monitor Slow Queries - Optimize with logging and tracing

Troubleshooting

Schema Changes Not Reflected

Regenerate code after schema changes:

cd v2/extensions/graphql
go run github.com/99designs/gqlgen generate

Type Conflicts

Rename conflicting types in graphql.go or use autobind in gqlgen.yml:

autobind:
  - github.com/xraph/forge/extensions/graphql/models

High Memory Usage

Reduce MaxCacheSize
Lower DataLoaderBatchSize
Set reasonable MaxComplexity

Examples

See v2/examples/graphql-*/ for complete examples:

graphql-basic/ - Simple query and mutation
graphql-auth/ - Authentication and authorization
graphql-dataloader/ - DataLoader optimization
graphql-federation/ - Microservices composition
graphql-subscriptions/ - Real-time subscriptions

API Reference

Extension Methods

NewExtension(opts ...ConfigOption) forge.Extension
NewExtensionWithConfig(config Config) forge.Extension

Config Options

WithEndpoint(endpoint string)
WithPlayground(enable bool)
WithIntrospection(enable bool)
WithMaxComplexity(max int)
WithMaxDepth(max int)
WithTimeout(timeout time.Duration)
WithDataLoader(enable bool)
WithQueryCache(enable bool, ttl time.Duration)
WithCORS(origins ...string)
WithMetrics(enable bool)
WithTracing(enable bool)
WithRequireConfig(require bool)
WithConfig(config Config)

License

Part of the Forge framework - see main repository for license.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GraphQL Extension for Forge

Features

Installation

Quick Start

1. Define Your GraphQL Schema

2. Generate Code

3. Implement Resolvers

4. Register Extension

5. Query Your API

Configuration

Full Configuration Example

Environment Variables/Config File

Advanced Features

DataLoader for N+1 Query Optimization

Custom Directives

Apollo Federation v2

File Uploads

Dependency Injection

Observability

Logging

Metrics

Tracing

Testing

Performance Best Practices

Troubleshooting

Schema Changes Not Reflected

Type Conflicts

High Memory Usage

Examples

API Reference

Extension Methods

Config Options

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

GraphQL Extension for Forge

Features

Installation

Quick Start

1. Define Your GraphQL Schema

2. Generate Code

3. Implement Resolvers

4. Register Extension

5. Query Your API

Configuration

Full Configuration Example

Environment Variables/Config File

Advanced Features

DataLoader for N+1 Query Optimization

Custom Directives

Apollo Federation v2

File Uploads

Dependency Injection

Observability

Logging

Metrics

Tracing

Testing

Performance Best Practices

Troubleshooting

Schema Changes Not Reflected

Type Conflicts

High Memory Usage

Examples

API Reference

Extension Methods

Config Options

License