GraphQL - 💧 Mizu

Overview

The graphql middleware provides GraphQL query validation and security features including depth limiting, complexity analysis, introspection control, and field blocking. Use it when you need:

Query depth and complexity validation
Introspection query control
Field-level access control
Operation allowlisting
Protection against malicious queries

Installation

import "github.com/go-mizu/mizu/middlewares/graphql"

Quick Start

app := mizu.New()

// Use default validation (max depth: 10, max complexity: 100)
app.Use(graphql.New())

app.Post("/graphql", yourGraphQLHandler)

Configuration

Options

Option	Type	Default	Description
`MaxDepth`	`int`	`10`	Maximum query depth allowed
`MaxComplexity`	`int`	`100`	Maximum query complexity allowed
`DisableIntrospection`	`bool`	`false`	Disable introspection queries
`AllowedOperations`	`[]string`	`nil`	Whitelist of allowed operation names
`BlockedFields`	`[]string`	`nil`	List of fields to block
`ErrorHandler`	`func(*mizu.Ctx, error) error`	`nil`	Custom error handler

Examples

Basic Setup

// Use with default settings
app.Use(graphql.New())

app.Post("/graphql", yourGraphQLHandler)

Custom Depth and Complexity Limits

app.Use(graphql.WithOptions(graphql.Options{
    MaxDepth:      5,
    MaxComplexity: 50,
}))

Production Configuration

// Production-ready settings with introspection disabled
app.Use(graphql.Production())

Disable Introspection

// Block __schema and __type queries
app.Use(graphql.NoIntrospection())

Block Sensitive Fields

// Prevent access to specific fields
app.Use(graphql.BlockFields("password", "secret", "apiKey"))

Allowlist Operations

app.Use(graphql.WithOptions(graphql.Options{
    AllowedOperations: []string{"GetUser", "ListPosts", "CreateComment"},
}))

Custom Error Handler

app.Use(graphql.WithOptions(graphql.Options{
    MaxDepth: 10,
    ErrorHandler: func(c *mizu.Ctx, err error) error {
        return c.JSON(http.StatusForbidden, map[string]any{
            "errors": []map[string]string{
                {"message": "Query validation failed", "detail": err.Error()},
            },
        })
    },
}))

API Reference

Functions

// New creates GraphQL validation middleware with default options
func New() mizu.Middleware

// WithOptions creates GraphQL validation middleware with custom options
func WithOptions(opts Options) mizu.Middleware

// MaxDepth creates middleware with a specific max depth
func MaxDepth(depth int) mizu.Middleware

// MaxComplexity creates middleware with a specific max complexity
func MaxComplexity(complexity int) mizu.Middleware

// NoIntrospection creates middleware that disables introspection
func NoIntrospection() mizu.Middleware

// Production creates middleware with production-ready settings
func Production() mizu.Middleware

// BlockFields creates middleware that blocks specific fields
func BlockFields(fields ...string) mizu.Middleware

Error Types

const (
    ErrQueryTooDeep          = "query exceeds maximum depth"
    ErrQueryTooComplex       = "query exceeds maximum complexity"
    ErrIntrospectionDisabled = "introspection queries are disabled"
    ErrOperationNotAllowed   = "operation not allowed"
    ErrBlockedField          = "query contains blocked field"
)

Technical Details

Query Validation Process

The middleware validates GraphQL queries through the following process:

Request Filtering: Only processes POST requests with application/json content type
Query Parsing: Parses the request body into a Query structure containing:
- query: The GraphQL query string
- operationName: Named operation identifier
- variables: Query variables map
Validation Chain: Applies validations in order:
- Introspection check (if enabled)
- Operation allowlist check (if configured)
- Depth calculation and validation
- Complexity calculation and validation
- Blocked fields check (if configured)
Body Restoration: Restores the request body for downstream handlers

Depth Calculation

Query depth is calculated by counting the maximum nesting level of braces {}:

Tracks current depth using a counter
Increments on {, decrements on }
Records the maximum depth reached

Example:

{ users { posts { id } } }  // Depth: 3

Complexity Calculation

Query complexity is estimated using:

Count of field selections with braces: \w+\s*(?:\([^)]*\))?\s*{
Plus total count of opening braces {

This provides a simple heuristic for query cost.

Introspection Detection

Introspection queries are detected using regex pattern matching for:

__schema - Schema introspection
__type - Type introspection

Implementation Notes

The middleware preserves the request body after validation for downstream handlers
Non-POST requests and non-JSON requests bypass validation
Failed JSON parsing allows the request to pass through (handled by GraphQL server)
Default limits provide reasonable protection for most applications

Best Practices

Disable introspection in production
Set appropriate depth limits based on your schema
Use complexity limits to prevent resource exhaustion
Block sensitive fields at the middleware level
Implement custom error handlers for better user experience
Combine with rate limiting for additional protection

Testing

Test Coverage

Test Case	Description	Expected Behavior
`TestNew`	Default middleware creation	Accepts valid queries with default limits
`TestWithOptions_MaxDepth`	Query depth validation	Rejects queries exceeding max depth (4 > 2)
`TestWithOptions_MaxComplexity`	Query complexity validation	Rejects queries exceeding max complexity
`TestWithOptions_DisableIntrospection`	Introspection blocking	Blocks `__schema` and `__type` queries
`TestWithOptions_BlockedFields`	Field blocking	Rejects queries containing blocked fields (password, secret)
`TestSkipNonPOST`	GET request handling	Allows non-POST requests to pass through
`TestMaxDepth`	MaxDepth helper function	Accepts queries within depth limit (2 ≤ 3)
`TestMaxComplexity`	MaxComplexity helper function	Accepts queries within complexity limit
`TestNoIntrospection`	NoIntrospection helper	Blocks `__type` introspection queries
`TestProduction`	Production configuration	Applies production settings (depth:10, complexity:100, no introspection)
`TestBlockFields`	BlockFields helper	Blocks specified mutation fields (deleteMutation, adminAccess)
`TestCustomErrorHandler`	Custom error handling	Uses custom error handler with HTTP 403 status

Security Considerations

Query Depth Attacks

Deep nested queries can cause exponential computation:

{ users { friends { friends { friends { ... } } } } }

Mitigation: Set MaxDepth based on your schema’s maximum legitimate nesting.

Query Complexity Attacks

Complex queries can exhaust server resources:

{ users { posts { comments { author { posts { comments { ... } } } } } } }

Mitigation: Use MaxComplexity to limit total query cost.

Introspection Leaks

Introspection exposes your entire schema structure:

{ __schema { types { name fields { name } } } }

Mitigation: Disable introspection in production with NoIntrospection() or Production().

Sensitive Field Access

Prevent access to sensitive fields:

{ users { password ssn apiKey } }

Mitigation: Use BlockFields() to prevent access to sensitive data.

jsonrpc - JSON-RPC support
ratelimit - Rate limiting
timeout - Request timeout

​Overview

​Installation

​Quick Start

​Configuration

​Options

​Examples

​Basic Setup

​Custom Depth and Complexity Limits

​Production Configuration

​Disable Introspection

​Block Sensitive Fields

​Allowlist Operations

​Custom Error Handler

​API Reference

​Functions

​Error Types

​Technical Details

​Query Validation Process

​Depth Calculation

​Complexity Calculation

​Introspection Detection

​Implementation Notes

​Best Practices

​Testing

​Test Coverage

​Security Considerations

​Query Depth Attacks

​Query Complexity Attacks

​Introspection Leaks

​Sensitive Field Access

​Related Middlewares