From 99356f7faf0d1d55764f0ce5ce900e843cb9e4f9 Mon Sep 17 00:00:00 2001
From: Vladimir Razuvaev <vladimir.razuvaev@gmail.com>
Date: Fri, 18 Aug 2017 20:56:47 +0700
Subject: [PATCH] Docs on security

---
 docs/security.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml       |  4 +--
 2 files changed, 91 insertions(+), 2 deletions(-)
 create mode 100644 docs/security.md

diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 0000000..8919e38
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,89 @@
+# Query Complexity Analysis
+
+This is a PHP port of [Query Complexity Analysis](http://sangria-graphql.org/learn/#query-complexity-analysis) in Sangria implementation.
+
+Complexity analysis is a separate validation rule which calculates query complexity score before execution.
+Every field in the query gets a default score 1 (including ObjectType nodes). Total complexity of the 
+query is the sum of all field scores. For example, the complexity of introspection query is **109**.
+
+If this score exceeds a threshold, a query is not executed and an error is returned instead.
+
+Complexity analysis is disabled by default. To enabled it, add validation rule:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules\QueryComplexity;
+use GraphQL\Validator\DocumentValidator;
+
+$rule = new QueryComplexity($maxQueryComplexity = 100);
+DocumentValidator::addRule($rule);
+
+GraphQL::executeQuery(/*...*/);
+```
+This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries/#custom-validation-rules).
+
+To customize field score add **complexity** function to field definition:
+```php
+<?php
+use GraphQL\Type\Definition\Type;
+use GraphQL\Type\Definition\ObjectType;
+
+$type = new ObjectType([
+    'name' => 'MyType',
+    'fields' => [
+        'someList' => [
+            'type' => Type::listOf(Type::string()),
+            'args' => [
+                'limit' => [
+                    'type' => Type::int(),
+                    'defaultValue' => 10
+                ]
+            ],
+            'complexity' => function($childrenComplexity, $args) {
+                return $childrenComplexity * $args['limit'];
+            }
+        ]
+    ]
+]);
+```
+
+# Limiting Query Depth
+
+This is a PHP port of [Limiting Query Depth](http://sangria-graphql.org/learn/#limiting-query-depth) in Sangria implementation.
+For example max depth of the introspection query is **7**.
+
+It is disabled by default. To enable it, add following validation rule:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules\QueryDepth;
+use GraphQL\Validator\DocumentValidator;
+
+$rule = new QueryDepth($maxDepth = 10);
+DocumentValidator::addRule($rule);
+
+GraphQL::executeQuery(/*...*/);
+```
+
+This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries/#custom-validation-rules).
+
+# Disabling Introspection
+
+This is a PHP port of [graphql-disable-introspection](https://github.com/helfer/graphql-disable-introspection).
+It is a separate validation rule which prohibits queries that contain **__type** or **__schema** fields. 
+
+Introspection is enabled by default. To disable it, add following validation rule:
+
+```php
+<?php
+use GraphQL\GraphQL;
+use GraphQL\Validator\Rules\DisableIntrospection;
+use GraphQL\Validator\DocumentValidator;
+
+DocumentValidator::addRule(new DisableIntrospection());
+
+GraphQL::executeQuery(/*...*/);
+```
+This will set the rule globally. Alternatively you can provide validation rules [per execution](executing-queries/#custom-validation-rules).
diff --git a/mkdocs.yml b/mkdocs.yml
index d811696..fa29042 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,10 +15,10 @@ pages:
   - Schema: type-system/schema.md
   - Using Type Language: type-system/type-language.md
 - Executing Queries: executing-queries.md
-- Fetching Data (resolving fields): data-fetching.md
+- Fetching Data: data-fetching.md
 - Handling Errors: error-handling.md
 # - Mutations: mutations.md
-# - Security: security.md
+- Security: security.md
 # - Performance tips: performance.md
 - How it works: how-it-works.md
 - Class Reference: reference.md