Query complexity

CHANGELOG.md

@@ -5,6 +5,7 @@
 - **Breaking Change**: change `ClassType` type and export it in package index
 - **Breaking Change**: refactor generic `createUnionType` to remove the 10 types limit (note: requires TypeScript 3.0.1)
 - add support for subscribing to dynamic topics - based on args/ctx/root (#137)
+- add support for query complexity analysis - integration with `graphql-query-complexity` (#139)
 
 ## v0.13.1
 ### Fixes

dev.js

@@ -8,6 +8,7 @@ require("ts-node/register/transpile-only");
 // require("./examples/redis-subscriptions/index.ts");
 // require("./examples/resolvers-inheritance/index.ts");
 // require("./examples/simple-subscriptions/index.ts");
+//  require("./examples/query-complexity/index.ts");
 // require("./examples/simple-usage/index.ts");
 // require("./examples/using-container/index.ts");
 // require("./examples/using-scoped-container/index.ts");

docs/complexity.md

@@ -0,0 +1,81 @@
+---
+title: Query Complexity
+---
+A single GraphQL query can potentially generate huge workload for a server, like thousands of database operations which can be used to cause DDoS attacks. To keep track and limit of what each GraphQL operation can do , `TypeGraphQL` provides you the option of integrating with Query Complexity tools like  [graphql-query-complexity](https://github.com/ivome/graphql-query-complexity).
+
+
+The cost analysis-based solution is very promising, since you can define a “cost” per field and then analyze the AST to estimate the total cost of the GraphQL query. Of course all the analysis is handled by `graphql-query-complexity` .
+
+All you need to do is define your complexity cost for the fields (fields, mutattions, subscriptions) in`TypeGraphQL` and implement `graphql-query-complexity` in whatever GraphQL server you have.
+
+## How to use?
+At first, you need to pass `complexity` as an option to the decorator on a field/query/mutation.
+
+Example of complexity
+```typescript
+
+@ObjectType()
+class MyObject {
+  @Field({ complexity: 2 })
+  publicField: string;
+
+  @Field({ complexity: ({args, childComplexity}) => childComplexity + 1 })
+  complexField: string;
+}
+```
+
+You can omit the `complexity` option if the complexity value is 1. 
+You can pass complexity as option to any of `@Field`, `@FieldResolver`, `@Mutation` & `@Subscription`. For the same property, if both the `@Fieldresolver` as well as `@Field` have complexity defined , then the complexity passed to the field resolver decorator takes precedence. 
+
+In next step, you need to integrate `graphql-query-complexity` with your GraphQL server. 
+
+```typescript
+  // Create GraphQL server
+  const server = new GraphQLServer({ schema });
+
+  // Configure server options
+  const serverOptions: Options = {
+    port: 4000,
+    endpoint: "/graphql",
+    playground: "/playground",
+    validationRules: req => [
+      queryComplexity({
+        // The maximum allowed query complexity, queries above this threshold will be rejected
+        maximumComplexity: 8,
+        // The query variables. This is needed because the variables are not available
+        // in the visitor of the graphql-js library
+        variables: req.query.variables,
+        // Optional callback function to retrieve the determined query complexity
+        // Will be invoked weather the query is rejected or not
+        // This can be used for logging or to implement rate limiting
+        onComplete: (complexity: number) => {
+          console.log("Query Complexity:", complexity);
+        },
+        estimators: [
+          // Using fieldConfigEstimator is mandatory to make it work with type-graphql
+          fieldConfigEstimator(),
+          // This will assign each field a complexity of 1 if no other estimator
+          // returned a value. We can define the default value for field not explicitly annotated
+          simpleEstimator({
+            defaultComplexity: 1,
+          }),
+        ],
+      }),
+    ],
+  };
+
+  // Start the server
+  server.start(serverOptions, ({ port, playground }) => {
+    console.log(
+      `Server is running, GraphQL Playground available at http://localhost:${port}${playground}`,
+    );
+  });
+```
+
+And it's done! 😉 .
+
+For more info about how query complexity is computed, please visit[graphql-query-complexity](https://github.com/ivome/graphql-query-complexity).
+
+
+## Example
+You can see how this works together in the [simple query complexity example](https://github.com/19majkel94/type-graphql/tree/master/examples/query-complexity).

examples/query-complexity/examples.gql

@@ -0,0 +1,15 @@
+
+query GetRecipesWithComplexityError {
+  recipes {
+    title
+    averageRating,
+    ratingsCount
+  }
+}
+
+query GetRecipesWithoutComplexityError {
+  recipes {
+    title
+    averageRating
+  }
+}

examples/query-complexity/index.ts

@@ -0,0 +1,65 @@
+import "reflect-metadata";
+import { GraphQLServer, Options } from "graphql-yoga";
+import { buildSchema } from "../../src";
+import queryComplexity, { simpleEstimator, fieldConfigEstimator } from "graphql-query-complexity";
+import { RecipeResolver } from "./recipe-resolver";
+import { ValidationContext } from "graphql";
+
+async function bootstrap() {
+  // build TypeGraphQL executable schema
+  const schema = await buildSchema({
+    resolvers: [RecipeResolver],
+  });
+
+  // Create GraphQL server
+  const server = new GraphQLServer({ schema });
+
+  // Configure server options
+  const serverOptions: Options = {
+    port: 4000,
+    endpoint: "/graphql",
+    playground: "/playground",
+    validationRules: req => [
+      /**
+       * This  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.
+       * More documentation can be found (here)[https://github.com/ivome/graphql-query-complexity]
+       */
+      queryComplexity({
+        // The maximum allowed query complexity, queries above this threshold will be rejected
+        maximumComplexity: 8,
+        // The query variables. This is needed because the variables are not available
+        // in the visitor of the graphql-js library
+        variables: req.query.variables,
+        // Optional callback function to retrieve the determined query complexity
+        // Will be invoked weather the query is rejected or not
+        // This can be used for logging or to implement rate limiting
+        onComplete: (complexity: number) => {
+          console.log("Query Complexity:", complexity);
+        },
+        // 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: [
+          fieldConfigEstimator(),
+          // Add more estimators here...
+          // This will assign each field a complexity of 1 if no other estimator
+          // returned a value.
+          simpleEstimator({
+            defaultComplexity: 1,
+          }),
+        ],
+      }) as ((context: ValidationContext) => any),
+    ],
+  };
+
+  // Start the server
+  server.start(serverOptions, ({ port, playground }) => {
+    console.log(
+      `Server is running, GraphQL Playground available at http://localhost:${port}${playground}`,
+    );
+  });
+}
+
+bootstrap();

examples/query-complexity/recipe-resolver.ts

@@ -0,0 +1,22 @@
+import { Resolver, Query, FieldResolver, Arg, Root, Int, ResolverInterface } from "../../src";
+
+import { Recipe } from "./recipe-type";
+import { createRecipeSamples } from "./recipe-samples";
+
+@Resolver(of => Recipe)
+export class RecipeResolver implements ResolverInterface<Recipe> {
+  private readonly items: Recipe[] = createRecipeSamples();
+
+  @Query(returns => [Recipe], { description: "Get all the recipes from around the world " })
+  async recipes(): Promise<Recipe[]> {
+    return await this.items;
+  }
+  /* Complexity in field resolver overrides complexity of equivalent field type*/
+  @FieldResolver({ complexity: 10 })
+  ratingsCount(
+    @Root() recipe: Recipe,
+    @Arg("minRate", type => Int, { nullable: true }) minRate: number = 0.0,
+  ): number {
+    return recipe.ratings.filter(rating => rating >= minRate).length;
+  }
+}

examples/query-complexity/recipe-samples.ts

@@ -0,0 +1,26 @@
+import { plainToClass } from "class-transformer";
+
+import { Recipe } from "./recipe-type";
+
+export function createRecipeSamples() {
+  return plainToClass(Recipe, [
+    {
+      description: "Desc 1",
+      title: "Recipe 1",
+      ratings: [0, 3, 1],
+      creationDate: new Date("2018-04-11"),
+    },
+    {
+      description: "Desc 2",
+      title: "Recipe 2",
+      ratings: [4, 2, 3, 1],
+      creationDate: new Date("2018-04-15"),
+    },
+    {
+      description: "Desc 3",
+      title: "Recipe 3",
+      ratings: [5, 4],
+      creationDate: new Date(),
+    },
+  ]);
+}

examples/query-complexity/recipe-type.ts

@@ -0,0 +1,41 @@
+import { Field, ObjectType, Int, Float } from "../../src";
+
+@ObjectType({ description: "Object representing cooking recipe" })
+export class Recipe {
+  /*
+    By default, every field gets a complexity of 1.
+    Which can be customized by passing the complexity parameter
+  */
+  @Field({ complexity: 6 })
+  title: string;
+
+  @Field({ complexity: 5 })
+  description?: string;
+
+  @Field(type => [Int])
+  ratings: number[];
+
+  @Field(type => Int, { complexity: 5 })
+  ratingsCount: number;
+
+  @Field(type => Float, {
+    nullable: true,
+    /*
+    By default, every field gets a complexity of 1.
+    You can also pass a calculation function in the complexity option
+    to determine a custom complexity.
+    This function will provide the complexity of
+    the child nodes as well as the field input arguments.
+    That way you can make a more realistic estimation of individual field complexity values:
+   */
+    complexity: ({ childComplexity }) => childComplexity + 1,
+  })
+  get averageRating(): number | null {
+    const ratingsCount = this.ratings.length;
+    if (ratingsCount === 0) {
+      return null;
+    }
+    const ratingsSum = this.ratings.reduce((a, b) => a + b, 0);
+    return ratingsSum / ratingsCount;
+  }
+}

examples/simple-usage/index.ts

@@ -1,7 +1,6 @@
 import "reflect-metadata";
 import { GraphQLServer, Options } from "graphql-yoga";
 import { buildSchema } from "../../src";
-
 import { RecipeResolver } from "./recipe-resolver";
 
 async function bootstrap() {