From 0342762d32eaf5571be574fe3928b591db51b54f Mon Sep 17 00:00:00 2001
From: Lars de Bruijn <9264036+ldebruijn@users.noreply.github.com>
Date: Thu, 17 Oct 2024 11:48:05 +0200
Subject: [PATCH] doc(http): Add specific HTTP configuration documentation
 (#141)

---
 docs/README.md        |  6 ++++-
 docs/configuration.md | 38 +++++++++-------------------
 docs/http.md          | 58 +++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 75 insertions(+), 27 deletions(-)
 create mode 100644 docs/http.md

diff --git a/docs/README.md b/docs/README.md
index f0b0ebb..e59c92a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,11 +14,15 @@ Protect supports various running modes for different needs and purposes.
 * `validate` runs as a CLI tool, validating your Persisted Operations against your schema and configured protections (see [this page](configuration.md#graphql-protect---validate-run-mode) for more info how to set this up)
 * `version` outputs versioning info of protect
 
+## HTTP configuration
+
+* [HTTP Configuration](http.md)
+* 
 ## Protections
 
 This section contains all the documentation about each protection feature.
 
-* [Persisted Operations](protections/trusted_documents)
+* [Persisted Operations](protections/trusted_documents.md)
 * [Block Field Suggestions](protections/block_field_suggestions.md)
 * [Max Aliases](protections/max_aliases.md)
 * [Max Tokens](protections/max_tokens.md)
diff --git a/docs/configuration.md b/docs/configuration.md
index 38f7534..58be58b 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -12,11 +12,17 @@ The following outlines the structure of the yaml, as well as outlines the **defa
 
 ```yaml
 web:
+  # Maximum duration to read the entire request
   read_timeout: 5s
+  # Maximum duration before timing out writes of the response
   write_timeout: 10s
+  # Maximum time to wait between idle requests for keep alive
   idle_timeout: 120s
+  # Time to wait until forcibly shutting down protect, after receiving a shutdown signal
   shutdown_timeout: 20s
+  # host and port to listen on
   host: 0.0.0.0:8080
+  # path that receives GraphQL traffic
   path: /graphql
   # limit the maximum size of a request body that is allowed
   # this helps prevent OOM attacks through excessively large request payloads.
@@ -24,10 +30,14 @@ web:
   request_body_max_bytes: 102400
 
 target:
+  # Target host and port to send traffic to after validating
   host: http://localhost:8081
+  # Dial timeout waiting for a connection to complete with the target upstream
   timeout: 10s
+  # Interval of keep alive probes
   keep_alive: 180s
-  target:
+  tracing:
+    # Headers to redact when sending tracing information
     redacted_headers: []
       
 schema:
@@ -170,28 +180,4 @@ max_batch:
     enabled: true
     # The maximum number of operations within a single batched request.
     max: 5
-```
-
-## HTTP Request Body Max Byte size
-
-To prevent OOM attacks through excessively large request bodies, a default limit is posed on request body size of `100kb`. This limit is generally speaking ample space for GraphQL request bodies, while also providing solid protections.
-
-You can modify this limit by changing the following configuration option
-
-```yaml
-web:
-  # limit the maximum size of a request body that is allowed
-  # this helps prevent OOM attacks through excessively large request payloads.
-  # A limit of `0` disables this protection.
-  request_body_max_bytes: 102400
-```
-
-### Metrics
-
-A metric is exposed to track if and when a request is rejected that exceeds this limit.
-
-```
-graphql_protect_http_request_max_body_bytes_exceeded_count{}
-```
-
-No metrics are produced for requests that do not exceed this limit.
\ No newline at end of file
+```
\ No newline at end of file
diff --git a/docs/http.md b/docs/http.md
new file mode 100644
index 0000000..1c9b440
--- /dev/null
+++ b/docs/http.md
@@ -0,0 +1,58 @@
+# HTTP Configuration
+
+## HTTP server configuration
+
+```yaml
+web:
+  # Maximum duration to read the entire request
+  read_timeout: 5s
+  # Maximum duration before timing out writes of the response
+  write_timeout: 10s
+  # Maximum time to wait between idle requests for keep alive
+  idle_timeout: 120s
+  # Time to wait until forcibly shutting down protect, after receiving a shutdown signal
+  shutdown_timeout: 20s
+  # host and port to listen on
+  host: 0.0.0.0:8080
+  # path that receives GraphQL traffic
+  path: /graphql
+  # limit the maximum size of a request body that is allowed
+  # this helps prevent OOM attacks through excessively large request payloads.
+  # A limit of `0` disables this protection.
+  request_body_max_bytes: 102400
+
+target:
+  # Target host and port to send traffic to after validating
+  host: http://localhost:8081
+  # Dial timeout waiting for a connection to complete with the target upstream
+  timeout: 10s
+  # Interval of keep alive probes
+  keep_alive: 180s
+  tracing:
+    # Headers to redact when sending tracing information
+    redacted_headers: []
+```
+
+## HTTP Request Body Max Byte size
+
+To prevent OOM attacks through excessively large request bodies, a default limit is posed on request body size of `100kb`. This limit is generally speaking ample space for GraphQL request bodies, while also providing solid protections.
+
+You can modify this limit by changing the following configuration option
+
+```yaml
+web:
+  # limit the maximum size of a request body that is allowed
+  # this helps prevent OOM attacks through excessively large request payloads.
+  # A limit of `0` disables this protection.
+  request_body_max_bytes: 102400
+```
+
+### Metrics
+
+A metric is exposed to track if and when a request is rejected that exceeds this limit.
+
+```
+graphql_protect_http_request_max_body_bytes_exceeded_count{}
+```
+
+No metrics are produced for requests that do not exceed this limit.
\ No newline at end of file