Skip to content
GraphQL query complexity analysis and validation for graphql-js
Branch: master
Clone or download
Latest commit 2804b7e Feb 14, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Migrate codebase to TypeScript, upgrade dependencies Aug 22, 2018
src Ignore fields without complexity directive in directiveEstimator #15 Feb 10, 2019
.babelrc
.eslintrc
.gitignore Initial commit Aug 2, 2017
LICENSE Initial commit Aug 2, 2017
README.md Fix fieldConfig estimator readme url Sep 6, 2018
package.json 0.2.3 Feb 14, 2019
tsconfig.json
yarn.lock

README.md

GraphQL Query Complexity Analysis for graphql-js

This library provides GraphQL query analysis to reject complex queries to your GraphQL server. This can be used to protect your GraphQL servers against resource exhaustion and DoS attacks.

Works with graphql-js reference implementation.

Installation

Install the package via npm

npm install -S graphql-query-complexity

Usage

Create the rule with a maximum query complexity:

import queryComplexity, {
  simpleEstimator
} from 'graphql-query-complexity';

const rule = queryComplexity({
  // The maximum allowed query complexity, queries above this threshold will be rejected
  maximumComplexity: 1000,
  
  // The query variables. This is needed because the variables are not available
  // in the visitor of the graphql-js library
  variables: {},
  
  // Optional callback function to retrieve the determined query complexity
  // Will be invoked whether the query is rejected or not
  // This can be used for logging or to implement rate limiting
  onComplete: (complexity: number) => {console.log('Determined query complexity: ', complexity)},
  
  // Optional function to create a custom error
  createError: (max: number, actual: number) => {
    return new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`);
  },
  
  // Add any number of estimators. The estimators are invoked in order, the first
  // numeric value that is being returned by an estimator is used as the field complexity.
  // If no estimator returns a value, an exception is raised. 
  estimators: [
    // Add more estimators here...
    
    // This will assign each field a complexity of 1 if no other estimator
    // returned a value. 
    simpleEstimator({
      defaultComplexity: 1
    })
  ]
});

Configuration / Complexity Estimators

The complexity calculation of a GraphQL query can be customized with so called complexity estimators. A complexity estimator is a simple function that calculates the complexity for a field. You can add any number of complexity estimators to the rule, which are then executed one after another. The first estimator that returns a numeric complexity value determines the complexity for that field.

At least one estimator has to return a complexity value, otherwise an exception is raised. You can for example use the simpleEstimator as the last estimator in your chain to define a default value.

You can use any of the available estimators to calculate the complexity of a field or write your own:

  • simpleEstimator: The simple estimator returns a fixed complexity for each field. Can be used as last estimator in the chain for a default value.
  • directiveEstimator: Set the complexity via a directive in your schema definition (for example via GraphQL SDL)
  • fieldConfigEstimator: The field config estimator lets you set a numeric value or a custom estimator function in the field config of your schema.
  • legacyEstimator: The legacy estimator implements the logic of previous versions. Can be used to gradually migrate your codebase to new estimators.
  • PRs welcome...

Consult the documentation of each estimator for information about how to use them.

Creating Custom Estimators

An estimator has the following function signature:

type ComplexityEstimatorArgs = {
  // The composite type (interface, object, union) that the evaluated field belongs to
  type: GraphQLCompositeType,
  
  // The GraphQLField that is being evaluated
  field: GraphQLField<any, any>,
  
  // The input arguments of the field
  args: {[key: string]: any},
  
  // The complexity of all child selections for that field
  childComplexity: number
}

type ComplexityEstimator = (options: ComplexityEstimatorArgs) => number | void;

Usage with express-graphql

To use the query complexity analysis validation rule with express-graphql, use something like the following:

import queryComplexity from 'graphql-query-complexity';
import express from 'express';
import graphqlHTTP from 'express-graphql';
import schema from './schema';

const app = express();
app.use('/api', graphqlHTTP(async (request, response, {variables}) => ({
  schema,
  validationRules: [ queryComplexity({
    maximumComplexity: 1000,
    variables,
    onComplete: (complexity: number) => {console.log('Query Complexity:', complexity);},
  }) ]
})));

Prior Art

This project is inspired by the following prior projects:

You can’t perform that action at this time.