From 3234333e999dea792e7aefaf9cc823ccce70a44a Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 28 Oct 2025 11:42:52 -0400 Subject: [PATCH 1/4] Update `add-headers` action docs Improves language of and adds better examples to this action reference doc --- snippets/shared/phases-explanation.mdx | 1 + traffic-policy/actions/add-headers.mdx | 30 +++++++++++++++----------- traffic-policy/concepts/phases.mdx | 5 ++++- 3 files changed, 23 insertions(+), 13 deletions(-) create mode 100644 snippets/shared/phases-explanation.mdx diff --git a/snippets/shared/phases-explanation.mdx b/snippets/shared/phases-explanation.mdx new file mode 100644 index 0000000000..3359d00416 --- /dev/null +++ b/snippets/shared/phases-explanation.mdx @@ -0,0 +1 @@ +In Traffic Policy, a phase represents a distinct point in the lifecycle of a request as it moves through an ngrok endpoint. Phases allow you to inspect, process, and manage traffic at key moments. \ No newline at end of file diff --git a/traffic-policy/actions/add-headers.mdx b/traffic-policy/actions/add-headers.mdx index 00f77f7e45..429b31d16a 100644 --- a/traffic-policy/actions/add-headers.mdx +++ b/traffic-policy/actions/add-headers.mdx @@ -5,25 +5,29 @@ description: Add headers to an HTTP request or response before it is delivered u --- import { ConfigField } from "/snippets/ConfigTable.jsx"; import ActionVariablesDescription from "/snippets/traffic-policy/common/action-variables-description.mdx"; +import PhasesExplanation from "/snippets/shared/phases-explanation.mdx"; The Add Headers action enables you to add custom headers to an HTTP request or response before delivery to the upstream service or client. This is useful for attaching metadata like request identifiers, applying security controls, or adjusting how applications process traffic. -## Configuration Reference +## Configuration reference The [Traffic Policy](/traffic-policy/) configuration reference for this action. -### Supported Phases +### Supported phases -`on_http_request`, `on_http_response` + + +- `on_http_request`: When called in this phase, the specified headers are added to incoming http requests before reaching the upstream service. +- `on_http_response`: When called in this phase, the specified headers are added to the http response from the upstream service, before being delivered. ### Type `add-headers` -### Configuration Fields +### Configuration fields Map of header key to header value to be added. @@ -33,17 +37,19 @@ The [Traffic Policy](/traffic-policy/) configuration reference for this action. ## Behavior -When configured in the `on_http_request` phase, this action will add the specified headers to incoming http requests before reaching the upstream server. When -configured in the `on_http_response` phase, the specified headers are added to the http response from the upstream server. +This Action's behavior varies based on which [phase](#supported-phases) it's used in. + +### Addition only + +This action will only **add** headers to the request or response. +If the header already exists, it will append another header with the same key (unless it's the `host` header. See [Special Cases](#special-cases)). -### Addition Only +#### Replacing headers -This action will only add headers to the request or response. If the header already exists -it will append another header with the same key unless it is the `host` header, -see [Special Cases](#special-cases). +To replace or remove headers, first use the [`remove-headers`](/traffic-policy/actions/remove-headers) action. +Then add the header with the desired value. +The following snippet demonstrates a basic example. -To replace or remove headers use the [`remove-headers`](/traffic-policy/actions/remove-headers) action then -add the header with the desired value. ### Case Sensitivity diff --git a/traffic-policy/concepts/phases.mdx b/traffic-policy/concepts/phases.mdx index 39bd5bd9e4..89d885861d 100644 --- a/traffic-policy/concepts/phases.mdx +++ b/traffic-policy/concepts/phases.mdx @@ -1,8 +1,11 @@ --- title: Phases +description: Learn about the different phases in the lifecycle of a request to your ngrok endpoints, and what actions you can take during them. --- -In Traffic Policy, a phase represents a distinct point in the lifecycle of a request as it moves through an ngrok endpoint. Phases allow you to inspect, process, and manage traffic at key moments. +import PhasesExplanation from "/snippets/shared/phases-explanation.mdx"; + + ## Traffic Policy Phases From 5e17f9096f453821cd972da9106feca945dfc972 Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 28 Oct 2025 11:48:03 -0400 Subject: [PATCH 2/4] Update add-headers.mdx --- traffic-policy/actions/add-headers.mdx | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/traffic-policy/actions/add-headers.mdx b/traffic-policy/actions/add-headers.mdx index 429b31d16a..4d9f5e4ef0 100644 --- a/traffic-policy/actions/add-headers.mdx +++ b/traffic-policy/actions/add-headers.mdx @@ -50,8 +50,7 @@ To replace or remove headers, first use the [`remove-headers`](/traffic-policy/a Then add the header with the desired value. The following snippet demonstrates a basic example. - -### Case Sensitivity +### Case sensitivity Header keys added through this action are normalized to lowercase per the [HTTP/2 specification](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2). @@ -60,7 +59,7 @@ Header keys added through this action are normalized to lowercase per the [HTTP/ Since actions are run in the order they are specified, to modify headers that have been added by other actions you must place this action after them in your traffic policy document. -### Special Cases +### Special cases - Adding the `host` header override the existing value instead of appending another header. - You may not add or remove the `user-agent` header. @@ -68,12 +67,12 @@ after them in your traffic policy document. ## Examples -### Adding Client IP Headers to all HTTP requests +### Adding Client IP headers to all HTTP requests The following [Traffic Policy](/traffic-policy/) configuration will add the client IP address to all HTTP requests. -#### Example Traffic Policy Document +#### Example traffic policy document ```yaml policy.yml @@ -110,7 +109,7 @@ https://httpbin.org and we are adding the following header to all requests: - `x-client-ip` with the value `${conn.client_ip}` to demonstrate the use of CEL interpolation to include the client IP address. -#### Example Request +#### Example request ```bash $ curl -i https://httpbin.ngrok.app/get @@ -132,7 +131,7 @@ content-type: application/json The following [Traffic Policy](/traffic-policy/) configuration will add headers to the response from the upstream service when the method is `GET` and the URL starts with `/status/200`. -#### Example Traffic Policy Document +#### Example traffic policy document ```yaml policy.yml highlight={3} @@ -178,7 +177,7 @@ https://httpbin.org and we will be adding two headers: to demonstrate the use of CEL interpolation to include the request connection start time. -### Example Request +### Example request ```bash $ curl -i https://httpbin.ngrok.app/status/200 @@ -190,7 +189,7 @@ x-custom-header: my-custom-value x-string-interpolation-example: started at 2024-07-13T00:10:16Z ``` -## Action Result Variables +## Action result variables From bd5a6e3918ccbdc1f7ca313259073da752fcea8b Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Tue, 28 Oct 2025 12:15:57 -0400 Subject: [PATCH 3/4] More progress --- traffic-policy/actions/add-headers.mdx | 95 +++++++++++++++++++++++++- 1 file changed, 92 insertions(+), 3 deletions(-) diff --git a/traffic-policy/actions/add-headers.mdx b/traffic-policy/actions/add-headers.mdx index 4d9f5e4ef0..2be53a61dd 100644 --- a/traffic-policy/actions/add-headers.mdx +++ b/traffic-policy/actions/add-headers.mdx @@ -37,19 +37,108 @@ The [Traffic Policy](/traffic-policy/) configuration reference for this action. ## Behavior -This Action's behavior varies based on which [phase](#supported-phases) it's used in. +This Action's behavior varies based on which [request phase](#supported-phases) it's used in. ### Addition only This action will only **add** headers to the request or response. If the header already exists, it will append another header with the same key (unless it's the `host` header. See [Special Cases](#special-cases)). +#### Adding to existing headers + +For example, you could use this action to add the client's IP to `x-forwarded-for`, appending information about the client making the request, so the upstream server can see where the request originated, regardless of the proxies it passed through. + + + +This example uses a connection variable. See [the connection variable reference](https://ngrok.com/docs/traffic-policy/variables/connection#conn-client-ip) to learn more. + + + +```yaml policy.yml +on_http_request: + - actions: + - type: "add-headers" + config: + headers: + x-forwarded-for: "${conn.client_ip}" +``` +```json policy.json +{ + "on_http_request": [ + { + "actions": [ + { + "type": "add-headers", + "config": { + "headers": { + "x-forwarded-for": "${conn.client_ip}" + } + } + } + ] + } + ] +} +``` + + +The server will see an `x-forwarded-for` header with the client's IP chain, which might look like this: + +```bash +x-forwarded-for: 233.1.111.1, 11.5.5.5 +``` + #### Replacing headers -To replace or remove headers, first use the [`remove-headers`](/traffic-policy/actions/remove-headers) action. -Then add the header with the desired value. +To replace or remove headers, first use the [`remove-headers`](/traffic-policy/actions/remove-headers) action, then add the header with the desired value. The following snippet demonstrates a basic example. + + +```yaml policy.yml +on_http_request: +- actions: + - type: remove-headers + config: + headers: + - x-example-header-1 + - type: add-headers + config: + headers: + x-example-header-2: Example Value +``` + +```json policy.json +{ + "on_http_request": [ + { + "actions": [ + { + "type": "remove-headers", + "config": { + "headers": [ + "x-example-header-1" + ] + } + }, + { + "type": "add-headers", + "config": { + "headers": { + "x-example-header-2": "Example Value" + } + } + } + ] + } + ] +} +``` + + + +See [our Adding and Removing Headers examples](/traffic-policy/examples/add-and-remove-headers) for use cases. + ### Case sensitivity Header keys added through this action are normalized to lowercase per the [HTTP/2 specification](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2). From 515f7d3935a1002b7e8313906d6272de1bfc4827 Mon Sep 17 00:00:00 2001 From: Shaquil Hansford Date: Wed, 5 Nov 2025 14:07:24 -0500 Subject: [PATCH 4/4] Add examples to behavior section --- traffic-policy/actions/add-headers.mdx | 38 ++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 6 deletions(-) diff --git a/traffic-policy/actions/add-headers.mdx b/traffic-policy/actions/add-headers.mdx index 2be53a61dd..2fe0fa01cc 100644 --- a/traffic-policy/actions/add-headers.mdx +++ b/traffic-policy/actions/add-headers.mdx @@ -48,9 +48,9 @@ If the header already exists, it will append another header with the same key (u For example, you could use this action to add the client's IP to `x-forwarded-for`, appending information about the client making the request, so the upstream server can see where the request originated, regardless of the proxies it passed through. - -This example uses a connection variable. See [the connection variable reference](https://ngrok.com/docs/traffic-policy/variables/connection#conn-client-ip) to learn more. +This example uses a connection variable. +See [the connection variable reference](https://ngrok.com/docs/traffic-policy/variables/connection#conn-client-ip) to learn more. @@ -137,20 +137,46 @@ on_http_request: + See [our Adding and Removing Headers examples](/traffic-policy/examples/add-and-remove-headers) for use cases. + ### Case sensitivity -Header keys added through this action are normalized to lowercase per the [HTTP/2 specification](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2). +Header keys are case-insensitive. +All header keys added with `add-headers` are normalized to lowercase, per the [HTTP/2 specification](https://datatracker.ietf.org/doc/html/rfc7540#section-8.1.2). + +For example, the following snippets, despite specifying a capitalized `Authorization` header, would yield a lower-case `authorization` header. + + +```yaml policy.yml +- type: add-headers + config: + headers: + Authorization: ax10malv +``` +```json policy.json +{ + "type": "add-headers", + "config": { + "headers": { + "Authorization": "ax10malv" + } + } +} +``` + ### Ordering -Since actions are run in the order they are specified, to modify headers that have been added by other actions you must place this action -after them in your traffic policy document. +Actions are run in the same order that they're defined in your traffic policy. +If you want an `add-headers` action to modify headers created or modified in other actions, it must be defined after them in your traffic policy document. ### Special cases -- Adding the `host` header override the existing value instead of appending another header. +These are the special cases in which this action will behave differently from how this reference document has specified. + +- Adding the `host` header overrides the existing value instead of appending another header. - You may not add or remove the `user-agent` header. - You may not use this action to add the `ngrok-skip-browser-warning` header to skip the ngrok browser warning on free accounts. For more information, check out the [free plan limits guide](/pricing-limits/free-plan-limits#removing-the-interstitial-page).