项目作者: slicknode

项目描述 :
GraphQL query complexity analysis and validation for graphql-js
高级语言: TypeScript
项目地址: git://github.com/slicknode/graphql-query-complexity.git
创建时间: 2017-08-02T09:47:32Z
项目社区:https://github.com/slicknode/graphql-query-complexity

开源协议:MIT License

下载


GraphQL Query Complexity Analysis for graphql-js

npm
npm version
Twitter Follow

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

This library was originally developed as part of the Slicknode GraphQL Framework + Headless CMS.

Works with graphql-js reference implementation.

Installation

Install the package via npm

  1. npm install -S graphql-query-complexity

Usage

Create the rule with a maximum query complexity:

  1. import {
  2. createComplexityRule,
  3. simpleEstimator
  4. } from 'graphql-query-complexity';
  5. const rule = createComplexityRule({
  6. // The maximum allowed query complexity, queries above this threshold will be rejected
  7. maximumComplexity: 1_000,
  8. // The query variables. This is needed because the variables are not available
  9. // in the visitor of the graphql-js library
  10. variables: {},
  11. // The context object for the request (optional)
  12. context: {}
  13. // Specify operation name when evaluating multi-operation documents
  14. operationName?: string,
  15. // The maximum number of query nodes to evaluate (fields, fragments, composite types).
  16. // If a query contains more than the specified number of nodes, the complexity rule will
  17. // throw an error, regardless of the complexity of the query.
  18. //
  19. // Default: 10_000
  20. maxQueryNodes?: 10_000,
  21. // Optional callback function to retrieve the determined query complexity
  22. // Will be invoked whether the query is rejected or not
  23. // This can be used for logging or to implement rate limiting
  24. onComplete: (complexity: number) => {console.log('Determined query complexity: ', complexity)},
  25. // Optional function to create a custom error
  26. createError: (max: number, actual: number) => {
  27. return new GraphQLError(`Query is too complex: ${actual}. Maximum allowed complexity: ${max}`);
  28. },
  29. // Add any number of estimators. The estimators are invoked in order, the first
  30. // numeric value that is being returned by an estimator is used as the field complexity.
  31. // If no estimator returns a value, an exception is raised.
  32. estimators: [
  33. // Add more estimators here...
  34. // This will assign each field a complexity of 1 if no other estimator
  35. // returned a value.
  36. simpleEstimator({
  37. defaultComplexity: 1
  38. })
  39. ]
  40. });

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)
  • fieldExtensionsEstimator: The field extensions estimator lets you set a numeric value or a custom estimator
    function in the field config extensions of your schema.
  • 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:

  1. type ComplexityEstimatorArgs = {
  2. // The composite type (interface, object, union) that the evaluated field belongs to
  3. type: GraphQLCompositeType;
  4. // The GraphQLField that is being evaluated
  5. field: GraphQLField<any, any>;
  6. // The GraphQL node that is being evaluated
  7. node: FieldNode;
  8. // The input arguments of the field
  9. args: { [key: string]: any };
  10. // The complexity of all child selections for that field
  11. childComplexity: number;
  12. // The context object for the request if it was provided
  13. context?: Record<string, any>;
  14. };
  15. 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:

  1. import {
  2. simpleEstimator,
  3. createComplexityRule,
  4. } from 'graphql-query-complexity';
  5. import express from 'express';
  6. import graphqlHTTP from 'express-graphql';
  7. import schema from './schema';
  8. const app = express();
  9. app.use(
  10. '/api',
  11. graphqlHTTP(async (request, response, { variables }) => ({
  12. schema,
  13. validationRules: [
  14. createComplexityRule({
  15. estimators: [
  16. // Configure your estimators
  17. simpleEstimator({ defaultComplexity: 1 }),
  18. ],
  19. maximumComplexity: 1000,
  20. variables,
  21. onComplete: (complexity: number) => {
  22. console.log('Query Complexity:', complexity);
  23. },
  24. }),
  25. ],
  26. }))
  27. );

Calculate query complexity

If you want to calculate the complexity of a GraphQL query outside of the validation phase, for example to
return the complexity value in a resolver, you can calculate the complexity via getComplexity:

  1. import { getComplexity, simpleEstimator } from 'graphql-query-complexity';
  2. import { parse } from 'graphql';
  3. // Import your schema or get it form the info object in your resolver
  4. import schema from './schema';
  5. // You can also use gql template tag to get the parsed query
  6. const query = parse(`
  7. query Q($count: Int) {
  8. some_value
  9. some_list(count: $count) {
  10. some_child_value
  11. }
  12. }
  13. `);
  14. try {
  15. const complexity = getComplexity({
  16. estimators: [simpleEstimator({ defaultComplexity: 1 })],
  17. schema,
  18. query,
  19. variables: {
  20. count: 10,
  21. },
  22. });
  23. console.log(complexity); // Output: 3
  24. } catch (e) {
  25. // Log error in case complexity cannot be calculated (invalid query, misconfiguration, etc.)
  26. console.error('Could not calculate complexity', e.message);
  27. }

Prior Art

This project is inspired by the following prior projects: