From 0889920fb034a06ab2b82b82d7350ce77f4299ab Mon Sep 17 00:00:00 2001 From: Ryan Grant Date: Mon, 23 Sep 2024 15:36:27 -0700 Subject: [PATCH 1/4] update http inbound/outbound to new phases --- docs/agent/config/v2.mdx | 88 +++++++++---------- docs/agent/config/v3.mdx | 82 ++++++++--------- docs/guides/device-gateway/sdk.md | 8 +- docs/http/traffic-policy/index.mdx | 24 ++--- docs/integrations/digitalocean/gslb.mdx | 6 +- docs/integrations/linode/gslb.mdx | 6 +- examples/agent-cli/http-traffic-policy.mdx | 4 +- examples/agent-config/http-traffic-policy.mdx | 4 +- .../javascript-sdk/http-traffic-policy.mdx | 42 +++++++-- examples/python-sdk/http-traffic-policy.mdx | 42 +++++++-- .../actions/add-headers/behavior.mdx | 4 +- traffic-policy/actions/add-headers/config.mdx | 6 +- ...-add-client-ip-headers-to-all-requests.mdx | 2 +- .../examples/http-add-headers-to-response.mdx | 2 +- .../actions/compress-response/config.mdx | 4 +- ...essing-api-responses-based-on-url-path.mdx | 2 +- .../actions/custom-response/behavior.mdx | 8 +- .../actions/custom-response/config.mdx | 4 +- .../examples/http-html-maintenance-page.mdx | 2 +- .../http-json-single-interpolation.mdx | 2 +- ...http-plain-text-multiple-interpolation.mdx | 2 +- .../deny/http/examples/http-basic-example.mdx | 2 +- .../actions/jwt-validation/config.mdx | 2 +- .../jwt-validation/examples/basic-example.mdx | 2 +- .../examples/integration-auth0/example.mdx | 2 +- traffic-policy/actions/log/config.mdx | 4 +- .../actions/log/examples/basic-example.mdx | 2 +- traffic-policy/actions/rate-limit/config.mdx | 4 +- .../rate-limit/examples/basic-example.mdx | 2 +- traffic-policy/actions/redirect/config.mdx | 2 +- .../redirect/examples/1-basic-example.mdx | 2 +- .../redirect/examples/2-with-regex.mdx | 2 +- .../examples/3-with-string-interpolation.mdx | 2 +- .../actions/remove-headers/behavior.mdx | 4 +- .../actions/remove-headers/config.mdx | 4 +- ...ttp-removing-headers-from-all-requests.mdx | 2 +- .../actions/restrict-ips/config.mdx | 4 +- .../http/examples/1-basic-example.mdx | 2 +- .../http/examples/2-using-ip-policies.mdx | 2 +- .../http/examples/3-testing-traffic.mdx | 2 +- traffic-policy/actions/url-rewrite/config.mdx | 2 +- .../url-rewrite/examples/1-basic-example.mdx | 2 +- .../url-rewrite/examples/2-with-regex.mdx | 2 +- .../examples/3-with-string-interpolation.mdx | 2 +- traffic-policy/gallery.mdx | 54 ++++++------ 45 files changed, 257 insertions(+), 197 deletions(-) diff --git a/docs/agent/config/v2.mdx b/docs/agent/config/v2.mdx index e224c8218..386d7ed4f 100644 --- a/docs/agent/config/v2.mdx +++ b/docs/agent/config/v2.mdx @@ -478,50 +478,50 @@ You can configure a single ngrok agent to tunnel to multiple services within a s ### HTTP Configuration -| | | | -| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `basic_auth` | Array of `username:password` Strings | This is a list of username:password combinations to use for basic authenticate. Passwords must be at least 8 characters long. | -| `circuit_breaker` | Float | Reject requests when 5XX responses exceed this ratio | -| `compression` | `true`, `false` | gzip compress HTTP responses from your web service | -| `host_header` | `rewrite`, `preserve`, custom | Rewrite the HTTP Host header to this value, or `preserve` to leave it unchanged. The `rewrite` option will rewrite the host header to match the hostname of the upstream service you are sending traffic to. | -| `domain` | Any valid domain or hostname that you have previously registered with ngrok. | The domain to request. If using a custom domain, this requires registering in the [ngrok dashboard](https://dashboard.ngrok.com/cloud-edge/domains) and setting a DNS CNAME value. When using wildcard domains you will need to surround the value with single quotes (domain: '\*.example.com'). | -| `inspect` | `true`, `false` | enable/disable the http request inspection in the web and agent API (default: true) | -| `ip_restriction.allow_cidrs` | Array of CIDRs | Rejects connections that do not match the given CIDRs | -| `ip_restriction.deny_cidrs` | Array of CIDRs | Rejects connections that match the given CIDRs and allows all other CIDRs. | -| `mutual_tls_cas` | Valid system path | The path to the TLS certificate authority to verify client certs in mutual TLS | -| `oauth.allow_domains` | Array of Strings | Allow only OAuth2 users with these email domains | -| `oauth.allow_emails` | Array of Strings | Allow only OAuth users with these emails | -| `oauth.oauth_scopes` | Array of Strings | Request these OAuth2 scopes when a user authenticates | -| `oauth.provider` | String | enforce authentication OAuth2 provider on the endpoint, e.g. 'google'. For a lit of available providers, see [OAuth2 providers](/http/oauth/#supported-providers). | -| [`policy.inbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.inbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.inbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.inbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| `proto` | `http` | The tunnel protocol name. This defines the type of tunnel you would like to start. | -| `proxy_proto` | String | The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this tunnel, empty if not using. Example values are 1 or 2. | -| `request_header.add` | Array of `key:value` Strings | The headers to add to the request in the key:value format. | -| `request_header.remove` | Array of Strings | The header keys to remove from the request. | -| `response_header.add` | Array of Strings | The headers to add to the response in the key:value format. | -| `response_header.remove` | Array of Strings | The header keys to remove from the response. | -| `schemes` | `http`, `https` | Create an HTTP or HTTPS endpoint (or both) | -| `subdomain` | Any valid combination of letters, numbers, hyphens or periods. | subdomain name to request. If unspecified, ngrok provides a unique subdomain based on your account type. | -| [`traffic_policy.inbound.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an inbound rule that is part of a traffic policy | -| [`traffic_policy.inbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the inbound policy rule applies to | -| [`traffic_policy.inbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this inbound policy rule is activated | -| [`traffic_policy.inbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | -| [`traffic_policy.outbound.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an outbound rule that is part of a traffic policy | -| [`traffic_policy.outbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the outbound policy rule applies to | -| [`traffic_policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this outbound policy rule is activated | -| [`traffic_policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | -| `user_agent_filter.allow` | Array of Strings | Allows User-Agents that match against these RE2 Regular Expressions | -| `user_agent_filter.deny` | Array of Strings | Denies User-Agents that match against these RE2 Regular Expressions | -| `verify_webhook.provider` | String | Verify webhooks are signed by this provider, e.g. 'slack'. For a full list of providers, see [Webhook Verification Providers](/http/webhook-verification/#supported-providers). | -| `verify_webhook.secret` | String | The secret used by provider to sign webhooks, if there is one | -| `websocket_tcp_converter` | `true`, `false` | Convert ingress websocket connections to TCP upstream | +| | | | +| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `basic_auth` | Array of `username:password` Strings | This is a list of username:password combinations to use for basic authenticate. Passwords must be at least 8 characters long. | +| `circuit_breaker` | Float | Reject requests when 5XX responses exceed this ratio | +| `compression` | `true`, `false` | gzip compress HTTP responses from your web service | +| `host_header` | `rewrite`, `preserve`, custom | Rewrite the HTTP Host header to this value, or `preserve` to leave it unchanged. The `rewrite` option will rewrite the host header to match the hostname of the upstream service you are sending traffic to. | +| `domain` | Any valid domain or hostname that you have previously registered with ngrok. | The domain to request. If using a custom domain, this requires registering in the [ngrok dashboard](https://dashboard.ngrok.com/cloud-edge/domains) and setting a DNS CNAME value. When using wildcard domains you will need to surround the value with single quotes (domain: '\*.example.com'). | +| `inspect` | `true`, `false` | enable/disable the http request inspection in the web and agent API (default: true) | +| `ip_restriction.allow_cidrs` | Array of CIDRs | Rejects connections that do not match the given CIDRs | +| `ip_restriction.deny_cidrs` | Array of CIDRs | Rejects connections that match the given CIDRs and allows all other CIDRs. | +| `mutual_tls_cas` | Valid system path | The path to the TLS certificate authority to verify client certs in mutual TLS | +| `oauth.allow_domains` | Array of Strings | Allow only OAuth2 users with these email domains | +| `oauth.allow_emails` | Array of Strings | Allow only OAuth users with these emails | +| `oauth.oauth_scopes` | Array of Strings | Request these OAuth2 scopes when a user authenticates | +| `oauth.provider` | String | enforce authentication OAuth2 provider on the endpoint, e.g. 'google'. For a lit of available providers, see [OAuth2 providers](/http/oauth/#supported-providers). | +| [`policy.inbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.inbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.inbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.inbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| `proto` | `http` | The tunnel protocol name. This defines the type of tunnel you would like to start. | +| `proxy_proto` | String | The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this tunnel, empty if not using. Example values are 1 or 2. | +| `request_header.add` | Array of `key:value` Strings | The headers to add to the request in the key:value format. | +| `request_header.remove` | Array of Strings | The header keys to remove from the request. | +| `response_header.add` | Array of Strings | The headers to add to the response in the key:value format. | +| `response_header.remove` | Array of Strings | The header keys to remove from the response. | +| `schemes` | `http`, `https` | Create an HTTP or HTTPS endpoint (or both) | +| `subdomain` | Any valid combination of letters, numbers, hyphens or periods. | subdomain name to request. If unspecified, ngrok provides a unique subdomain based on your account type. | +| [`traffic_policy.on_http_request.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an `on_http_request` rule that is part of a traffic policy | +| [`traffic_policy.on_http_request.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the `on_http_request` policy rule applies to | +| [`traffic_policy.on_http_request.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this `on_http_request` policy rule is activated | +| [`traffic_policy.on_http_request.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | +| [`traffic_policy.on_http_response.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an `on_http_response` rule that is part of a traffic policy | +| [`traffic_policy.on_http_response.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the `on_http_response` policy rule applies to | +| [`traffic_policy.on_http_response.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this `on_http_response` policy rule is activated | +| [`traffic_policy.on_http_response.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | +| `user_agent_filter.allow` | Array of Strings | Allows User-Agents that match against these RE2 Regular Expressions | +| `user_agent_filter.deny` | Array of Strings | Denies User-Agents that match against these RE2 Regular Expressions | +| `verify_webhook.provider` | String | Verify webhooks are signed by this provider, e.g. 'slack'. For a full list of providers, see [Webhook Verification Providers](/http/webhook-verification/#supported-providers). | +| `verify_webhook.secret` | String | The secret used by provider to sign webhooks, if there is one | +| `websocket_tcp_converter` | `true`, `false` | Convert ingress websocket connections to TCP upstream | ### TCP Configuration diff --git a/docs/agent/config/v3.mdx b/docs/agent/config/v3.mdx index ca054658b..fb9e8c612 100644 --- a/docs/agent/config/v3.mdx +++ b/docs/agent/config/v3.mdx @@ -69,7 +69,7 @@ endpoints: metadata: foo123 url: foo.ngrok.io traffic_policy: - inbound: + on_http_request: - actions: - type: custom-response config: @@ -159,46 +159,46 @@ You can configure a single ngrok agent to start multiple endpoints to different ### HTTP Configuration -| Name | Type | Description | -| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `circuit_breaker` | Float | Reject requests when 5XX responses exceed this ratio | -| `compression` | `true`, `false` | gzip compress HTTP responses from your web service | -| `url` | Any valid domain or hostname that you have previously registered with ngrok. | The domain to request. If using a custom domain, this requires registering in the [ngrok dashboard](https://dashboard.ngrok.com/cloud-edge/domains) and setting a DNS CNAME value. When using wildcard domains you will need to surround the value with single quotes (domain: '\*.example.com'). | -| `inspect` | `true`, `false` | enable/disable the http request inspection in the web and agent API (default: true) | -| `ip_restriction.allow_cidrs` | Array of CIDRs | Rejects connections that do not match the given CIDRs | -| `ip_restriction.deny_cidrs` | Array of CIDRs | Rejects connections that match the given CIDRs and allows all other CIDRs. | -| `mutual_tls_cas` | Valid system path | The path to the TLS certificate authority to verify client certs in mutual TLS | -| `oauth.allow_domains` | Array of Strings | Allow only OAuth2 users with these email domains | -| `oauth.allow_emails` | Array of Strings | Allow only OAuth users with these emails | -| `oauth.oauth_scopes` | Array of Strings | Request these OAuth2 scopes when a user authenticates | -| `oauth.provider` | String | enforce authentication OAuth2 provider on the endpoint, e.g. 'google'. For a lit of available providers, see [OAuth2 providers](/http/oauth/#supported-providers). | -| [`policy.inbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.inbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.inbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.inbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| [`policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | -| `proto` | `http` | The endpoint protocol name. This defines the type of endpoint you would like to start. | -| `proxy_protocol` | String | The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this endpoint, empty if not using. Example values are 1 or 2. | -| `request_header.add` | Array of `key:value` Strings | The headers to add to the request in the key:value format. | -| `request_header.remove` | Array of Strings | The header keys to remove from the request. | -| `response_header.add` | Array of Strings | The headers to add to the response in the key:value format. | -| `response_header.remove` | Array of Strings | The header keys to remove from the response. | -| [`traffic_policy.inbound.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an inbound rule that is part of a traffic policy | -| [`traffic_policy.inbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the inbound policy rule applies to | -| [`traffic_policy.inbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this inbound policy rule is activated | -| [`traffic_policy.inbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | -| [`traffic_policy.outbound.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an outbound rule that is part of a traffic policy | -| [`traffic_policy.outbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the outbound policy rule applies to | -| [`traffic_policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this outbound policy rule is activated | -| [`traffic_policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | -| `user_agent_filter.allow` | Array of Strings | Allows User-Agents that match against these RE2 Regular Expressions | -| `user_agent_filter.deny` | Array of Strings | Denies User-Agents that match against these RE2 Regular Expressions | -| `verify_webhook.provider` | String | Verify webhooks are signed by this provider, e.g. 'slack'. For a full list of providers, see [Webhook Verification Providers](/http/webhook-verification/#supported-providers). | -| `verify_webhook.secret` | String | The secret used by provider to sign webhooks, if there is one | -| `websocket_tcp_converter` | `true`, `false` | Convert ingress websocket connections to TCP upstream | +| Name | Type | Description | +| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `circuit_breaker` | Float | Reject requests when 5XX responses exceed this ratio | +| `compression` | `true`, `false` | gzip compress HTTP responses from your web service | +| `url` | Any valid domain or hostname that you have previously registered with ngrok. | The domain to request. If using a custom domain, this requires registering in the [ngrok dashboard](https://dashboard.ngrok.com/cloud-edge/domains) and setting a DNS CNAME value. When using wildcard domains you will need to surround the value with single quotes (domain: '\*.example.com'). | +| `inspect` | `true`, `false` | enable/disable the http request inspection in the web and agent API (default: true) | +| `ip_restriction.allow_cidrs` | Array of CIDRs | Rejects connections that do not match the given CIDRs | +| `ip_restriction.deny_cidrs` | Array of CIDRs | Rejects connections that match the given CIDRs and allows all other CIDRs. | +| `mutual_tls_cas` | Valid system path | The path to the TLS certificate authority to verify client certs in mutual TLS | +| `oauth.allow_domains` | Array of Strings | Allow only OAuth2 users with these email domains | +| `oauth.allow_emails` | Array of Strings | Allow only OAuth users with these emails | +| `oauth.oauth_scopes` | Array of Strings | Request these OAuth2 scopes when a user authenticates | +| `oauth.provider` | String | enforce authentication OAuth2 provider on the endpoint, e.g. 'google'. For a lit of available providers, see [OAuth2 providers](/http/oauth/#supported-providers). | +| [`policy.inbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.inbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.inbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.inbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.name`](/docs/http/traffic-policy/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| [`policy.outbound.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | `policy` has been renamed to `traffic_policy` in agent version 3.14.0. | +| `proto` | `http` | The endpoint protocol name. This defines the type of endpoint you would like to start. | +| `proxy_protocol` | String | The version of [PROXY protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to use with this endpoint, empty if not using. Example values are 1 or 2. | +| `request_header.add` | Array of `key:value` Strings | The headers to add to the request in the key:value format. | +| `request_header.remove` | Array of Strings | The header keys to remove from the request. | +| `response_header.add` | Array of Strings | The headers to add to the response in the key:value format. | +| `response_header.remove` | Array of Strings | The header keys to remove from the response. | +| [`traffic_policy.on_http_request.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an `on_http_request` rule that is part of a traffic policy | +| [`traffic_policy.on_http_request.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the `on_http_request` policy rule applies to | +| [`traffic_policy.on_http_request.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this `on_http_request` policy rule is activated | +| [`traffic_policy.on_http_request.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | +| [`traffic_policy.on_http_response.name`](/docs/http/traffic-policy/index.mdx) | String | The name of an `on_http_response` rule that is part of a traffic policy | +| [`traffic_policy.on_http_response.expressions`](/docs/http/traffic-policy/expressions/index.mdx) | Array of Strings | Expressions written using [CEL](https://github.com/google/cel-spec) that filter traffic the `on_http_response` policy rule applies to | +| [`traffic_policy.on_http_response.actions.type`](/docs/http/traffic-policy/actions/index.mdx) | String | The type of action that should be executed when this `on_http_response` policy rule is activated | +| [`traffic_policy.on_http_response.actions.config`](/docs/http/traffic-policy/actions/index.mdx) | custom | The configuration required for the specific type of action specified | +| `user_agent_filter.allow` | Array of Strings | Allows User-Agents that match against these RE2 Regular Expressions | +| `user_agent_filter.deny` | Array of Strings | Denies User-Agents that match against these RE2 Regular Expressions | +| `verify_webhook.provider` | String | Verify webhooks are signed by this provider, e.g. 'slack'. For a full list of providers, see [Webhook Verification Providers](/http/webhook-verification/#supported-providers). | +| `verify_webhook.secret` | String | The secret used by provider to sign webhooks, if there is one | +| `websocket_tcp_converter` | `true`, `false` | Convert ingress websocket connections to TCP upstream | ### TCP Configuration diff --git a/docs/guides/device-gateway/sdk.md b/docs/guides/device-gateway/sdk.md index 998fe01bc..6e3919ae8 100644 --- a/docs/guides/device-gateway/sdk.md +++ b/docs/guides/device-gateway/sdk.md @@ -279,7 +279,7 @@ the request: "protocol": "http", "forwards_to": "localhost:8001", "domain": "device123.sitea.configurable-domain.com", - "policy": "{\"inbound\": [], \"outbound\": [{\"expressions\": [], \"name\": \"Add headers to requests\", \"actions\": [{\"type\": \"add-headers\", \"config\": {\"headers\": {\"is-ngrok\": \"0000000000\"}}}]}]}" + "policy": "{\"on_http_request\": [], \"on_http_response\": [{\"expressions\": [], \"name\": \"Add headers to requests\", \"actions\": [{\"type\": \"add-headers\", \"config\": {\"headers\": {\"is-ngrok\": \"0000000000\"}}}]}]}" } ] ``` @@ -293,7 +293,7 @@ curl -k \ -X POST \ -H "Content-Type: application/json" \ -d '{"protocol": "http", "forwards_to": "{HOST}:{PORT}","domain":"{YOUR_DOMAIN}", "policy": \ - {"inbound":[],"outbound":[{"expressions":[],"name":"Add headers to requests","actions":[{"type":"add-headers","config":{"headers":{"is-ngrok":"444"}}}]}]}}' \ + {"on_http_request":[],"on_http_response":[{"expressions":[],"name":"Add headers to requests","actions":[{"type":"add-headers","config":{"headers":{"is-ngrok":"444"}}}]}]}}' \ https://{YOUR_AGENT_DOMAIN}/tunnels ``` @@ -306,8 +306,8 @@ You should receive a `200` response similar to the following: "forwards_to": "localhost:8001", "domain": "device123.sitea.configurable-domain.com", "policy": { - "inbound": [], - "outbound": [ + "on_http_request": [], + "on_http_response": [ { "expressions": [], "name": "Add headers to requests", diff --git a/docs/http/traffic-policy/index.mdx b/docs/http/traffic-policy/index.mdx index 2b97bc695..1bf57dcd5 100644 --- a/docs/http/traffic-policy/index.mdx +++ b/docs/http/traffic-policy/index.mdx @@ -23,7 +23,7 @@ import TrafficPolicyWarning from "/shared/warnings/traffic-policy-preview.mdx"; ## Overview This module allows you to assign a policy to your endpoints containing a series -of inbound and outbound rules that can be used to influence and control traffic +of `on_http_request` and `on_http_response` rules that can be used to influence and control traffic to and from your upstream service. Policy rules are composed of expressions that filter the traffic on which they are applicable @@ -60,8 +60,8 @@ and actions that should take effect. ## Behavior -Policy rules are evaluated sequentially in the order they are configured with inbound rules taking effect before the -upstream server is reached and outbound rules taking effect after the upstream server responds. Whether or not the configured +Policy rules are evaluated sequentially in the order they are configured with `on_http_request` rules taking effect before the +upstream server is reached and `on_http_response` rules taking effect after the upstream server responds. Whether or not the configured actions are performed is determined at runtime by the expressions. ### Expression Evaluation @@ -86,15 +86,15 @@ See [actions](./actions) for all available actions. ### Configuration -| Parameter | Description | -| --------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **inbound** | A list of policy rules that will be applied to inbound traffic in the order specified. | -| **outbound** | A list of policy rules that will be applied to outbound traffic in the order specified. | -| **name** | Policy rules can optionally be given a name for convenience. | -| **expressions** | A list of CEL expressions that filter which traffic a policy rule will apply to. | -| **actions** | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. | -| **type** | The type of action. | -| **config** | The configuration details of how an action should execute. Each action has its own configuration structure. | +| Parameter | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| **on_http_request** | A list of policy rules that will be applied to inbound http traffic in the order specified. | +| **on_http_response** | A list of policy rules that will be applied to outbound http traffic in the order specified. | +| **name** | Policy rules can optionally be given a name for convenience. | +| **expressions** | A list of CEL expressions that filter which traffic a policy rule will apply to. | +| **actions** | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. | +| **type** | The type of action. | +| **config** | The configuration details of how an action should execute. Each action has its own configuration structure. | ## Edges diff --git a/docs/integrations/digitalocean/gslb.mdx b/docs/integrations/digitalocean/gslb.mdx index 4579256c7..e73dbe49f 100644 --- a/docs/integrations/digitalocean/gslb.mdx +++ b/docs/integrations/digitalocean/gslb.mdx @@ -266,14 +266,14 @@ You have two options: -H "Authorization: Bearer ${NGROK_API_KEY}" \ -H "Content-Type: application/json" \ -H "Ngrok-Version: 2" \ - -d '{"enabled":true,"outbound":[{"actions":[{"type":"add-headers","config":{"headers": {"is-ngrok": "1","country": "${.ngrok.geo.country_code}"}}}],"name":"Add ngrok headers"}]}' + -d '{"enabled":true,"on_http_response":[{"actions":[{"type":"add-headers","config":{"headers": {"is-ngrok": "1","country": "${.ngrok.geo.country_code}"}}}],"name":"Add ngrok headers"}]}' ``` - In the Traffic Policy module section of your [Edge](https://dashboard.ngrok.com/cloud-edge/edges) in the ngrok dashboard, click the **Edit Traffic Policy** button and then the **YAML** button and add the YAML below. ```yaml - inbound: [] - outbound: + on_http_request: [] + on_http_response: - expressions: [] name: Add ngrok headers actions: diff --git a/docs/integrations/linode/gslb.mdx b/docs/integrations/linode/gslb.mdx index ddaafe17d..242aee374 100644 --- a/docs/integrations/linode/gslb.mdx +++ b/docs/integrations/linode/gslb.mdx @@ -258,14 +258,14 @@ You have two options: -H "Authorization: Bearer ${NGROK_API_KEY}" \ -H "Content-Type: application/json" \ -H "Ngrok-Version: 2" \ - -d '{"enabled":true,"outbound":[{"actions":[{"type":"add-headers","config":{"headers": {"is-ngrok": "1","country": "${.ngrok.geo.country_code}"}}}],"name":"Add ngrok headers"}]}' + -d '{"enabled":true,"on_http_response":[{"actions":[{"type":"add-headers","config":{"headers": {"is-ngrok": "1","country": "${.ngrok.geo.country_code}"}}}],"name":"Add ngrok headers"}]}' ``` - In the Traffic Policy module section of your [Edge](https://dashboard.ngrok.com/cloud-edge/edges) in the ngrok dashboard, where you can click the **Edit Traffic Policy** button and add the YAML below. ```yaml - inbound: [] - outbound: + on_http_request: [] + on_http_response: - expressions: [] name: Add ngrok headers actions: diff --git a/examples/agent-cli/http-traffic-policy.mdx b/examples/agent-cli/http-traffic-policy.mdx index 115e5e92f..eca842507 100644 --- a/examples/agent-cli/http-traffic-policy.mdx +++ b/examples/agent-cli/http-traffic-policy.mdx @@ -3,7 +3,7 @@ ngrok http 80 --traffic-policy-file /path/to/policy.yml ``` ```yaml title="policy.yml" -inbound: +on_http_request: - name: FooBarParamNotFound expressions: - "'bar' in getQueryParam('foo')" @@ -20,7 +20,7 @@ inbound: - "req.content_length > 5000" actions: - type: deny -outbound: +on_http_response: - name: "LogUnsuccessfulRequests" expressions: - "res.status_code < 200 && res.status_code >= 300" diff --git a/examples/agent-config/http-traffic-policy.mdx b/examples/agent-config/http-traffic-policy.mdx index 22ff85a43..9ad4f9731 100644 --- a/examples/agent-config/http-traffic-policy.mdx +++ b/examples/agent-config/http-traffic-policy.mdx @@ -4,7 +4,7 @@ tunnels: proto: http addr: 80 traffic_policy: - inbound: + on_http_request: - name: FooBarParamNotFound expressions: - "'bar' in getQueryParam('foo')" @@ -21,7 +21,7 @@ tunnels: - "req.content_length > 5000" actions: - type: deny - outbound: + on_http_response: - name: "LogUnsuccessfulRequests" expressions: - "res.status_code < 200 && res.status_code >= 300" diff --git a/examples/javascript-sdk/http-traffic-policy.mdx b/examples/javascript-sdk/http-traffic-policy.mdx index d2fa0101f..bfa3a2361 100644 --- a/examples/javascript-sdk/http-traffic-policy.mdx +++ b/examples/javascript-sdk/http-traffic-policy.mdx @@ -6,7 +6,7 @@ const fs = require("fs"); const listener = await ngrok.forward({ addr: 8080, authtoken_from_env: true, - policy: fs.readFileSync("/path/to/policy.json", "utf8"), + traffic_policy: fs.readFileSync("/path/to/policy.json", "utf8"), }); console.log(`Ingress established at: ${listener.url()}`); @@ -15,14 +15,13 @@ const fs = require("fs"); :::info -Traffic Policies can be defined in `json` only when using the SDKs. -Support for `yaml` is coming soon! +Traffic Policies can be defined in `json` or `yaml`! ::: ```json title="policy.json" { - "inbound": [ + "on_http_request": [ { "name": "FooBarParamNotFound", "expressions": ["'bar' in getQueryParam('foo')"], @@ -43,7 +42,7 @@ Support for `yaml` is coming soon! "actions": [{ "type": "deny" }] } ], - "outbound": [ + "on_http_response": [ { "name": "LogUnsuccessfulRequests", "expressions": ["res.status_code < 200 && res.status_code >= 300"], @@ -60,6 +59,37 @@ Support for `yaml` is coming soon! } ``` +```yaml title="policy.yaml" +--- +on_http_request: +- name: FooBarParamNotFound + expressions: + - "'bar' in getQueryParam('foo')" + actions: + - type: custom-response + config: + status_code: 404 + content: not found + headers: + content-type: text/plain +- name: BazCookieForLargeRequests + expressions: + - "!hasReqCookie('baz')" + - req.content_length > 5000 + actions: + - type: deny +on_http_response: +- name: LogUnsuccessfulRequests + expressions: + - res.status_code < 200 && res.status_code >= 300 + actions: + - type: log + config: + metadata: + hostport: example.com:443 + success: false +``` + Javascript SDK Docs: -- [https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#policy](https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#policy) +- [https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#trafficPolicy](https://ngrok.github.io/ngrok-javascript/classes/HttpListenerBuilder.html#trafficPolicy) diff --git a/examples/python-sdk/http-traffic-policy.mdx b/examples/python-sdk/http-traffic-policy.mdx index b3f9e5f45..c6ef70554 100644 --- a/examples/python-sdk/http-traffic-policy.mdx +++ b/examples/python-sdk/http-traffic-policy.mdx @@ -1,19 +1,18 @@ ```python with open('/path/to/policy.json') as f: policy = json.load(f) - listener = await session.http_endpoint().policy(policy).listen() + listener = await session.http_endpoint().traffic_policy(policy).listen() ``` :::info -Traffic Policies can be defined in `json` only when using the SDKs. -Support for `yaml` is coming soon! +Traffic Policies can be defined in `json` or `yaml`! ::: ```json title="policy.json" { - "inbound": [ + "on_http_request": [ { "name": "FooBarParamNotFound", "expressions": ["'bar' in getQueryParam('foo')"], @@ -34,7 +33,7 @@ Support for `yaml` is coming soon! "actions": [{ "type": "deny" }] } ], - "outbound": [ + "on_http_response": [ { "name": "LogUnsuccessfulRequests", "expressions": ["res.status_code < 200 && res.status_code >= 300"], @@ -51,6 +50,37 @@ Support for `yaml` is coming soon! } ``` +```yaml title="policy.yaml" +--- +on_http_request: +- name: FooBarParamNotFound + expressions: + - "'bar' in getQueryParam('foo')" + actions: + - type: custom-response + config: + status_code: 404 + content: not found + headers: + content-type: text/plain +- name: BazCookieForLargeRequests + expressions: + - "!hasReqCookie('baz')" + - req.content_length > 5000 + actions: + - type: deny +on_http_response: +- name: LogUnsuccessfulRequests + expressions: + - res.status_code < 200 && res.status_code >= 300 + actions: + - type: log + config: + metadata: + hostport: example.com:443 + success: false +``` + Python SDK Docs: -- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.policy) +- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy) diff --git a/traffic-policy/actions/add-headers/behavior.mdx b/traffic-policy/actions/add-headers/behavior.mdx index 0c67848eb..cdd7e6824 100644 --- a/traffic-policy/actions/add-headers/behavior.mdx +++ b/traffic-policy/actions/add-headers/behavior.mdx @@ -1,7 +1,7 @@ ## Behavior -When executed as an inbound policy, this action will add headers on an incoming http request before reaching the upstream server with -the configured headers. When executed as an outbound policy, the configured headers are added to the response from the upstream server. +When configured in the `on_http_request` phase, this action will add headers on an incoming http request before reaching the upstream server with +the configured headers. When configured in the `on_http_response` phase, the configured headers are added to the response from the upstream server. ### Addition Only diff --git a/traffic-policy/actions/add-headers/config.mdx b/traffic-policy/actions/add-headers/config.mdx index 860dcba70..4d6afee9d 100644 --- a/traffic-policy/actions/add-headers/config.mdx +++ b/traffic-policy/actions/add-headers/config.mdx @@ -13,10 +13,10 @@ reference for this action. | --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `headers` | `map[string]string` | Map of header key to header value to be added. Minimum `1`, Maximum `10`. Supports [CEL Interpolation](#cel-interpolation) in header values. | -### Supported Directions +### Supported Phases -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` ### Supported Schemes diff --git a/traffic-policy/actions/add-headers/examples/http-add-client-ip-headers-to-all-requests.mdx b/traffic-policy/actions/add-headers/examples/http-add-client-ip-headers-to-all-requests.mdx index f8a5d75b0..2b88b02cd 100644 --- a/traffic-policy/actions/add-headers/examples/http-add-client-ip-headers-to-all-requests.mdx +++ b/traffic-policy/actions/add-headers/examples/http-add-client-ip-headers-to-all-requests.mdx @@ -13,7 +13,7 @@ configuration will add the client IP address to all HTTP requests. yamlMetastring="{4-7}" jsonMetastring="{5-12}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/add-headers/examples/http-add-headers-to-response.mdx b/traffic-policy/actions/add-headers/examples/http-add-headers-to-response.mdx index 911ed73f8..8c9d05562 100644 --- a/traffic-policy/actions/add-headers/examples/http-add-headers-to-response.mdx +++ b/traffic-policy/actions/add-headers/examples/http-add-headers-to-response.mdx @@ -14,7 +14,7 @@ the method is `GET` and the URL starts with `/status/200`. yamlMetastring="{6-10}" jsonMetastring="{8-16}" config={{ - outbound: [ + on_http_response: [ { expressions: [ 'req.method == "GET" && req.url.path.startsWith("/status/200")', diff --git a/traffic-policy/actions/compress-response/config.mdx b/traffic-policy/actions/compress-response/config.mdx index 543685142..32cc82fe1 100644 --- a/traffic-policy/actions/compress-response/config.mdx +++ b/traffic-policy/actions/compress-response/config.mdx @@ -26,8 +26,8 @@ Full list of supported compression algorithms: ### Supported Directions -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` ### Supported Schemes diff --git a/traffic-policy/actions/compress-response/examples/compressing-api-responses-based-on-url-path.mdx b/traffic-policy/actions/compress-response/examples/compressing-api-responses-based-on-url-path.mdx index a6cbb6bdd..7ffbc3c6b 100644 --- a/traffic-policy/actions/compress-response/examples/compressing-api-responses-based-on-url-path.mdx +++ b/traffic-policy/actions/compress-response/examples/compressing-api-responses-based-on-url-path.mdx @@ -14,7 +14,7 @@ action with an expression to compress traffic on specific URL paths. jsonMetastring="{8-18}" yamlMetastring="{6-12}" config={{ - outbound: [ + on_http_response: [ { expressions: ["req.url.path.startsWith('/api/')"], actions: [ diff --git a/traffic-policy/actions/custom-response/behavior.mdx b/traffic-policy/actions/custom-response/behavior.mdx index b11570d8b..680db28c2 100644 --- a/traffic-policy/actions/custom-response/behavior.mdx +++ b/traffic-policy/actions/custom-response/behavior.mdx @@ -3,14 +3,14 @@ If this action is executed, no subsequent actions in your traffic policy will be executed. -### Inbound Usage +### `on_http_request` Usage -When used as an inbound policy, this action bypasses the upstream server and +When used during the `on_http_request` phase, this action bypasses the upstream server and immediately returns the configured response to the caller. -### Outbound Usage +### `on_http_response` Usage -When used as an outbound policy, this action overwrites the response from the +When used during the `on_http_response`, this action overwrites the response from the upstream server with the configured response. ### Inferring Content-Type diff --git a/traffic-policy/actions/custom-response/config.mdx b/traffic-policy/actions/custom-response/config.mdx index 334b4ea2e..cb5ad7f99 100644 --- a/traffic-policy/actions/custom-response/config.mdx +++ b/traffic-policy/actions/custom-response/config.mdx @@ -17,8 +17,8 @@ reference for this action. ### Supported Directions -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` ### Supported Schemes diff --git a/traffic-policy/actions/custom-response/examples/http-html-maintenance-page.mdx b/traffic-policy/actions/custom-response/examples/http-html-maintenance-page.mdx index fe3a33d8a..2f297f0ca 100644 --- a/traffic-policy/actions/custom-response/examples/http-html-maintenance-page.mdx +++ b/traffic-policy/actions/custom-response/examples/http-html-maintenance-page.mdx @@ -14,7 +14,7 @@ custom HTML maintenance page back for all requests to your endpoint. jsonMetastring="{5-14}" yamlMetastring="{4-10}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/custom-response/examples/http-json-single-interpolation.mdx b/traffic-policy/actions/custom-response/examples/http-json-single-interpolation.mdx index f44dfcfea..fc083c882 100644 --- a/traffic-policy/actions/custom-response/examples/http-json-single-interpolation.mdx +++ b/traffic-policy/actions/custom-response/examples/http-json-single-interpolation.mdx @@ -14,7 +14,7 @@ JSON response with CEL Interpolation for the connection start time. jsonMetastring="{8-17}" yamlMetastring="{6-12}" config={{ - inbound: [ + on_http_request: [ { expressions: ["req.url.path == '/api/example'"], actions: [ diff --git a/traffic-policy/actions/custom-response/examples/http-plain-text-multiple-interpolation.mdx b/traffic-policy/actions/custom-response/examples/http-plain-text-multiple-interpolation.mdx index d26158093..b8abc78fa 100644 --- a/traffic-policy/actions/custom-response/examples/http-plain-text-multiple-interpolation.mdx +++ b/traffic-policy/actions/custom-response/examples/http-plain-text-multiple-interpolation.mdx @@ -14,7 +14,7 @@ configuration demonstrates how to use the `custom-response` action to return a jsonMetastring="{8-17}" yamlMetastring="{6-12}" config={{ - inbound: [ + on_http_request: [ { expressions: ["req.url.path == '/api/example'"], actions: [ diff --git a/traffic-policy/actions/deny/http/examples/http-basic-example.mdx b/traffic-policy/actions/deny/http/examples/http-basic-example.mdx index a5129892d..c10af5e6d 100644 --- a/traffic-policy/actions/deny/http/examples/http-basic-example.mdx +++ b/traffic-policy/actions/deny/http/examples/http-basic-example.mdx @@ -13,7 +13,7 @@ configuration will deny all inbound traffic with a `404` on your endpoint. yamlMetastring="{4-10}" jsonMetastring="{5-10}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/jwt-validation/config.mdx b/traffic-policy/actions/jwt-validation/config.mdx index 5495db9f6..791223547 100644 --- a/traffic-policy/actions/jwt-validation/config.mdx +++ b/traffic-policy/actions/jwt-validation/config.mdx @@ -76,7 +76,7 @@ reference for this action. ### Supported Directions -- `inbound` +- `on_http_request` ### Supported Schemes diff --git a/traffic-policy/actions/jwt-validation/examples/basic-example.mdx b/traffic-policy/actions/jwt-validation/examples/basic-example.mdx index dc1bc5141..a22962a17 100644 --- a/traffic-policy/actions/jwt-validation/examples/basic-example.mdx +++ b/traffic-policy/actions/jwt-validation/examples/basic-example.mdx @@ -14,7 +14,7 @@ more real world example check out our [Auth0 guide](/docs/integrations/auth0/jwt jsonMetastring="{5-51}" yamlMetastring="{4-28}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/jwt-validation/examples/integration-auth0/example.mdx b/traffic-policy/actions/jwt-validation/examples/integration-auth0/example.mdx index 0ceaab0b1..2e64cd691 100644 --- a/traffic-policy/actions/jwt-validation/examples/integration-auth0/example.mdx +++ b/traffic-policy/actions/jwt-validation/examples/integration-auth0/example.mdx @@ -4,7 +4,7 @@ import ConfigExample from "/src/components/ConfigExample.tsx"; snippetText={null} showLineNumbers={true} config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/log/config.mdx b/traffic-policy/actions/log/config.mdx index 0e9c41185..38d682936 100644 --- a/traffic-policy/actions/log/config.mdx +++ b/traffic-policy/actions/log/config.mdx @@ -15,5 +15,5 @@ reference for this action. ### Supported Directions -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` diff --git a/traffic-policy/actions/log/examples/basic-example.mdx b/traffic-policy/actions/log/examples/basic-example.mdx index 11dccb2ca..41cf5be83 100644 --- a/traffic-policy/actions/log/examples/basic-example.mdx +++ b/traffic-policy/actions/log/examples/basic-example.mdx @@ -13,7 +13,7 @@ configuration will log a message with the endpoint identifier for every request. yamlMetastring="{4-10}" jsonMetastring="{5-13}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/rate-limit/config.mdx b/traffic-policy/actions/rate-limit/config.mdx index 90e9971a8..0e1afb2c2 100644 --- a/traffic-policy/actions/rate-limit/config.mdx +++ b/traffic-policy/actions/rate-limit/config.mdx @@ -19,8 +19,8 @@ reference for this action. ### Supported Directions -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` ### Supported Schemes diff --git a/traffic-policy/actions/rate-limit/examples/basic-example.mdx b/traffic-policy/actions/rate-limit/examples/basic-example.mdx index 8167a00f1..51ac2b683 100644 --- a/traffic-policy/actions/rate-limit/examples/basic-example.mdx +++ b/traffic-policy/actions/rate-limit/examples/basic-example.mdx @@ -14,7 +14,7 @@ all incoming requests by the `Host` header. jsonMetastring="{5-13}" yamlMetastring="{4-8}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/redirect/config.mdx b/traffic-policy/actions/redirect/config.mdx index 65d5bfc63..1c01b24da 100644 --- a/traffic-policy/actions/redirect/config.mdx +++ b/traffic-policy/actions/redirect/config.mdx @@ -19,7 +19,7 @@ reference for this action. ### Supported Directions -- `inbound` +- `on_http_request` ### Supported Schemes diff --git a/traffic-policy/actions/redirect/examples/1-basic-example.mdx b/traffic-policy/actions/redirect/examples/1-basic-example.mdx index c612fa9f6..bd3935d58 100644 --- a/traffic-policy/actions/redirect/examples/1-basic-example.mdx +++ b/traffic-policy/actions/redirect/examples/1-basic-example.mdx @@ -14,7 +14,7 @@ requests from `/products` to `/store/products`. jsonMetastring="{5-12}" yamlMetastring="{4-13}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/redirect/examples/2-with-regex.mdx b/traffic-policy/actions/redirect/examples/2-with-regex.mdx index d59026a42..0dc2ab1d7 100644 --- a/traffic-policy/actions/redirect/examples/2-with-regex.mdx +++ b/traffic-policy/actions/redirect/examples/2-with-regex.mdx @@ -14,7 +14,7 @@ requests from an old API endpoint to a new one. jsonMetastring="{8-18}" yamlMetastring="{6-16}" config={{ - inbound: [ + on_http_request: [ { expressions: ["req.url.path.startsWith('/api/')"], actions: [ diff --git a/traffic-policy/actions/redirect/examples/3-with-string-interpolation.mdx b/traffic-policy/actions/redirect/examples/3-with-string-interpolation.mdx index cbcb6f792..7aff41bdd 100644 --- a/traffic-policy/actions/redirect/examples/3-with-string-interpolation.mdx +++ b/traffic-policy/actions/redirect/examples/3-with-string-interpolation.mdx @@ -14,7 +14,7 @@ while using CEL Interpolation. jsonMetastring="{5,11}" yamlMetastring="{4,8}" config={{ - inbound: [ + on_http_request: [ { expressions: ["req.url.path in ['/api/v2/geo', '/api/v2/geo/']"], actions: [ diff --git a/traffic-policy/actions/remove-headers/behavior.mdx b/traffic-policy/actions/remove-headers/behavior.mdx index 4b4be527c..c9aa75e57 100644 --- a/traffic-policy/actions/remove-headers/behavior.mdx +++ b/traffic-policy/actions/remove-headers/behavior.mdx @@ -1,7 +1,7 @@ ## Behavior -When executed as an inbound policy, this action will remove headers on an incoming http request before reaching the upstream server with -the configured headers. When executed as an outbound policy, the configured headers are removed to the response from the upstream server. +When executed during the `on_http_request` phase, this action will remove headers on an incoming http request before reaching the upstream server with +the configured headers. When executed during the `on_http_response`, the configured headers are removed to the response from the upstream server. ### Removal Only diff --git a/traffic-policy/actions/remove-headers/config.mdx b/traffic-policy/actions/remove-headers/config.mdx index ea5d4795a..d78481290 100644 --- a/traffic-policy/actions/remove-headers/config.mdx +++ b/traffic-policy/actions/remove-headers/config.mdx @@ -15,8 +15,8 @@ reference for this action. ### Supported Directions -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` ### Supported Schemes diff --git a/traffic-policy/actions/remove-headers/examples/http-removing-headers-from-all-requests.mdx b/traffic-policy/actions/remove-headers/examples/http-removing-headers-from-all-requests.mdx index 341c4b486..36d8eba7d 100644 --- a/traffic-policy/actions/remove-headers/examples/http-removing-headers-from-all-requests.mdx +++ b/traffic-policy/actions/remove-headers/examples/http-removing-headers-from-all-requests.mdx @@ -15,7 +15,7 @@ using the `remove-headers` action. jsonMetastring="{5-13}" yamlMetastring="{4-8}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/config.mdx b/traffic-policy/actions/restrict-ips/config.mdx index 355bdfa8f..2ae43c255 100644 --- a/traffic-policy/actions/restrict-ips/config.mdx +++ b/traffic-policy/actions/restrict-ips/config.mdx @@ -18,5 +18,5 @@ reference for this action. ### Supported Directions -- `inbound` -- `outbound` +- `on_http_request` +- `on_http_response` diff --git a/traffic-policy/actions/restrict-ips/http/examples/1-basic-example.mdx b/traffic-policy/actions/restrict-ips/http/examples/1-basic-example.mdx index 4fdd9eff5..727c89fee 100644 --- a/traffic-policy/actions/restrict-ips/http/examples/1-basic-example.mdx +++ b/traffic-policy/actions/restrict-ips/http/examples/1-basic-example.mdx @@ -14,7 +14,7 @@ using the `restrict-ips` action. yamlMetastring="{4-10}" jsonMetastring="{5-16}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/http/examples/2-using-ip-policies.mdx b/traffic-policy/actions/restrict-ips/http/examples/2-using-ip-policies.mdx index 2bc324597..b432164e2 100644 --- a/traffic-policy/actions/restrict-ips/http/examples/2-using-ip-policies.mdx +++ b/traffic-policy/actions/restrict-ips/http/examples/2-using-ip-policies.mdx @@ -14,7 +14,7 @@ action with [IP Policies](/docs/api/resources/ip-policies/). yamlMetastring="{4-10}" jsonMetastring="{5-13}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/http/examples/3-testing-traffic.mdx b/traffic-policy/actions/restrict-ips/http/examples/3-testing-traffic.mdx index 671956357..352c555f9 100644 --- a/traffic-policy/actions/restrict-ips/http/examples/3-testing-traffic.mdx +++ b/traffic-policy/actions/restrict-ips/http/examples/3-testing-traffic.mdx @@ -14,7 +14,7 @@ action with the `restrict-ips` action and [IP Policies](/docs/api/resources/ip-p yamlMetastring="{6,9-17}" jsonMetastring="{8,14-26}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/actions/url-rewrite/config.mdx b/traffic-policy/actions/url-rewrite/config.mdx index 717d33d67..a47683624 100644 --- a/traffic-policy/actions/url-rewrite/config.mdx +++ b/traffic-policy/actions/url-rewrite/config.mdx @@ -17,7 +17,7 @@ reference for this action. ### Supported Directions -- `inbound` +- `on_http_request` ### Supported Schemes diff --git a/traffic-policy/actions/url-rewrite/examples/1-basic-example.mdx b/traffic-policy/actions/url-rewrite/examples/1-basic-example.mdx index cd8e92678..1909f930f 100644 --- a/traffic-policy/actions/url-rewrite/examples/1-basic-example.mdx +++ b/traffic-policy/actions/url-rewrite/examples/1-basic-example.mdx @@ -14,7 +14,7 @@ rewrite the request URL from `/products` to `/products.php`. jsonMetastring="{5,8-14}" yamlMetastring="{4,6-13}" config={{ - inbound: [ + on_http_request: [ { expressions: ["req.url.path == '/products'"], actions: [ diff --git a/traffic-policy/actions/url-rewrite/examples/2-with-regex.mdx b/traffic-policy/actions/url-rewrite/examples/2-with-regex.mdx index 52a080e23..651570212 100644 --- a/traffic-policy/actions/url-rewrite/examples/2-with-regex.mdx +++ b/traffic-policy/actions/url-rewrite/examples/2-with-regex.mdx @@ -14,7 +14,7 @@ rewrite the request URL from `/products/*` to `/products.php`. jsonMetastring="{5,8-14}" yamlMetastring="{4,6-13}" config={{ - inbound: [ + on_http_request: [ { expressions: ["req.url.path.startsWith('/products')"], actions: [ diff --git a/traffic-policy/actions/url-rewrite/examples/3-with-string-interpolation.mdx b/traffic-policy/actions/url-rewrite/examples/3-with-string-interpolation.mdx index 961fa2b7a..2e8dd9ebd 100644 --- a/traffic-policy/actions/url-rewrite/examples/3-with-string-interpolation.mdx +++ b/traffic-policy/actions/url-rewrite/examples/3-with-string-interpolation.mdx @@ -15,7 +15,7 @@ policy rule (no expression) by leveraging [CEL Interpolation](#cel-interpolation jsonMetastring="{5,8-14}" yamlMetastring="{4-13}" config={{ - inbound: [ + on_http_request: [ { actions: [ { diff --git a/traffic-policy/gallery.mdx b/traffic-policy/gallery.mdx index 27d472b06..d08babb89 100644 --- a/traffic-policy/gallery.mdx +++ b/traffic-policy/gallery.mdx @@ -3,7 +3,7 @@ import ConfigExample from "/src/components/ConfigExample.tsx"; export const Deny = () => ( ( export const CustomResponse = () => ( ( export const RateLimit = () => ( ( export const UserAgentFilter = () => ( ( export const AddRobotsTxt = () => ( ( export const AddRobotsTxtSpecific = () => ( ( export const BlockSpecificBots = () => ( ( export const JWTsRateLimiting = () => ( ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -223,7 +223,7 @@ export const JWTsRateLimiting = () => ( export const RateLimitAuthentication = () => ( ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -265,7 +265,7 @@ export const RateLimitAuthentication = () => ( export const BlockCountries = () => ( ', '']", @@ -282,7 +282,7 @@ export const BlockCountries = () => ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -290,7 +290,7 @@ export const BlockCountries = () => ( export const RateLimitPricing = () => ( ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -370,7 +370,7 @@ export const RateLimitPricing = () => ( export const DeprecateVersion = () => ( ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -394,7 +394,7 @@ export const DeprecateVersion = () => ( export const ManipulateHeaders = () => ( ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -419,8 +419,8 @@ export const ManipulateHeaders = () => ( export const AddCompression = () => ( ( export const EnforceTLS = () => ( '1.3'"], name: "Reject requests using old TLS versions", @@ -456,7 +456,7 @@ export const EnforceTLS = () => ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); @@ -464,8 +464,8 @@ export const EnforceTLS = () => ( export const LogUnsuccessful = () => ( = '300'"], name: "Log unsuccessful requests", @@ -490,7 +490,7 @@ export const LogUnsuccessful = () => ( export const LimitSize = () => ( ( ], }, ], - outbound: [], + on_http_response: [], }} /> ); From 62704a22c7e13029711f6304eb7893145ddf513b Mon Sep 17 00:00:00 2001 From: Ryan Grant Date: Wed, 25 Sep 2024 08:55:24 -0700 Subject: [PATCH 2/4] update tcp/tls inbound to on_tcp_connect --- docs/guides/device-gateway/arm64.md | 2 +- docs/tcp/traffic-policy/index.mdx | 25 +++++----- docs/tls/traffic-policy/expressions/index.mdx | 2 +- docs/tls/traffic-policy/index.mdx | 26 +++++----- examples/agent-cli/tcp-traffic-policy.mdx | 2 +- examples/agent-cli/tls-traffic-policy.mdx | 2 +- examples/agent-config/tcp-traffic-policy.mdx | 2 +- examples/agent-config/tls-traffic-policy.mdx | 2 +- .../javascript-sdk/http-traffic-policy.mdx | 50 +++++++++---------- .../javascript-sdk/tcp-traffic-policy.mdx | 6 +-- .../javascript-sdk/tls-traffic-policy.mdx | 6 +-- examples/python-sdk/http-traffic-policy.mdx | 50 +++++++++---------- examples/python-sdk/tcp-traffic-policy.mdx | 6 +-- examples/python-sdk/tls-traffic-policy.mdx | 6 +-- .../deny/tcp/examples/tcp-basic-example.mdx | 2 +- .../deny/tls/examples/tls-basic-example.mdx | 2 +- .../tcp/examples/1-basic-example.mdx | 2 +- .../tcp/examples/2-using-ip-policies.mdx | 2 +- .../tcp/examples/3-testing-traffic.mdx | 2 +- .../tls/examples/1-basic-example.mdx | 2 +- .../tls/examples/2-using-ip-policies.mdx | 2 +- .../tls/examples/3-testing-traffic.mdx | 2 +- 22 files changed, 100 insertions(+), 103 deletions(-) diff --git a/docs/guides/device-gateway/arm64.md b/docs/guides/device-gateway/arm64.md index 2baf1efc1..cd3911286 100644 --- a/docs/guides/device-gateway/arm64.md +++ b/docs/guides/device-gateway/arm64.md @@ -120,7 +120,7 @@ Now that you have SSH tunneling and service ingress handled via ngrok, you may a ```yaml --- - inbound: + on_tcp_connect: - actions: - name: "Restrict all IPs except trusted CIDRs" type: "restrict-ips" diff --git a/docs/tcp/traffic-policy/index.mdx b/docs/tcp/traffic-policy/index.mdx index 73be002a8..fbbb64ea7 100644 --- a/docs/tcp/traffic-policy/index.mdx +++ b/docs/tcp/traffic-policy/index.mdx @@ -23,8 +23,8 @@ import TrafficPolicyWarning from "/shared/warnings/traffic-policy-preview.mdx"; ## Overview This module allows you to assign a policy to your endpoints containing a series -of inbound and outbound rules that can be used to influence and control traffic -to and from your upstream service. +of `on_tcp_connect` rules that can be used to influence and control traffic +to your upstream service. Policy rules are composed of expressions that filter the traffic on which they are applicable and actions that should take effect. @@ -60,8 +60,8 @@ and actions that should take effect. ## Behavior -Policy rules are evaluated sequentially in the order they are configured with inbound rules taking effect before the -upstream server is reached and outbound rules taking effect after the upstream server responds. Whether or not the configured +Policy rules are evaluated sequentially in the order they are configured with `on_tcp_connect` rules taking effect before the +upstream server is reached. Whether or not the configured actions are performed is determined at runtime by the expressions. ### Expression Evaluation @@ -84,15 +84,14 @@ See [actions](./actions) for all available actions. ### Configuration -| Parameter | Description | -| --------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **inbound** | A list of policy rules that will be applied to inbound traffic in the order specified. | -| **outbound** | A list of policy rules that will be applied to outbound traffic in the order specified. | -| **name** | Policy rules can optionally be given a name for convenience. | -| **expressions** | A list of CEL expressions that filter which traffic a policy rule will apply to. | -| **actions** | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. | -| **type** | The type of action. | -| **config** | The configuration details of how an action should execute. Each action has its own configuration structure. | +| Parameter | Description | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| **on_tcp_connect** | A list of policy rules that will be applied to inbound traffic in the order specified. | +| **name** | Policy rules can optionally be given a name for convenience. | +| **expressions** | A list of CEL expressions that filter which traffic a policy rule will apply to. | +| **actions** | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. | +| **type** | The type of action. | +| **config** | The configuration details of how an action should execute. Each action has its own configuration structure. | ## Edges diff --git a/docs/tls/traffic-policy/expressions/index.mdx b/docs/tls/traffic-policy/expressions/index.mdx index 7fe78e2b5..f15b76e0b 100644 --- a/docs/tls/traffic-policy/expressions/index.mdx +++ b/docs/tls/traffic-policy/expressions/index.mdx @@ -5,7 +5,7 @@ pagination_next: tls/traffic-policy/expressions/writing-guide # Overview -Traffic Policy module enables you to filter inbound and outbound traffic with [Common Expression Language (CEL)](https://github.com/google/cel-spec) expressions. Each policy rule expression must evaluate to true in order for +Traffic Policy module enables you to filter inbound traffic with [Common Expression Language (CEL)](https://github.com/google/cel-spec) expressions. Each policy rule expression must evaluate to true in order for the rule's actions to take effect against traffic. - [Learn how to write CEL expressions](/docs/tls/traffic-policy/expressions/writing-guide). diff --git a/docs/tls/traffic-policy/index.mdx b/docs/tls/traffic-policy/index.mdx index a7dd67f6e..3bdba177e 100644 --- a/docs/tls/traffic-policy/index.mdx +++ b/docs/tls/traffic-policy/index.mdx @@ -23,8 +23,8 @@ import TrafficPolicyWarning from "/shared/warnings/traffic-policy-preview.mdx"; ## Overview This module allows you to assign a policy to your endpoints containing a series -of inbound and outbound rules that can be used to influence and control traffic -to and from your upstream service. +of `on_tcp_connect` rules that can be used to influence and control traffic +to your upstream service. Policy rules are composed of expressions that filter the traffic on which they are applicable and actions that should take effect. @@ -60,9 +60,8 @@ and actions that should take effect. ## Behavior -Policy rules are evaluated sequentially in the order they are configured with inbound rules taking effect before the -upstream server is reached and outbound rules taking effect after the upstream server responds. Whether or not the configured -actions are performed is determined at runtime by the expressions. +Policy rules are evaluated sequentially in the order they are configured with `on_tcp_connect` rules taking effect before the +upstream server is reached. Whether or not the configured actions are performed is determined at runtime by the expressions. ### Expression Evaluation @@ -84,15 +83,14 @@ See [actions](./actions) for all available actions. ### Configuration -| Parameter | Description | -| --------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **inbound** | A list of policy rules that will be applied to inbound traffic in the order specified. | -| **outbound** | A list of policy rules that will be applied to outbound traffic in the order specified. | -| **name** | Policy rules can optionally be given a name for convenience. | -| **expressions** | A list of CEL expressions that filter which traffic a policy rule will apply to. | -| **actions** | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. | -| **type** | The type of action. | -| **config** | The configuration details of how an action should execute. Each action has its own configuration structure. | +| Parameter | Description | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| **on_tcp_connect** | A list of policy rules that will be applied to inbound traffic in the order specified. | +| **name** | Policy rules can optionally be given a name for convenience. | +| **expressions** | A list of CEL expressions that filter which traffic a policy rule will apply to. | +| **actions** | A list of actions that will execute sequentially if the associated policy rule's expressions all match on the traffic. | +| **type** | The type of action. | +| **config** | The configuration details of how an action should execute. Each action has its own configuration structure. | ## Edges diff --git a/examples/agent-cli/tcp-traffic-policy.mdx b/examples/agent-cli/tcp-traffic-policy.mdx index aeb3b5ec5..205c10f8e 100644 --- a/examples/agent-cli/tcp-traffic-policy.mdx +++ b/examples/agent-cli/tcp-traffic-policy.mdx @@ -3,7 +3,7 @@ ngrok tcp 22 --traffic-policy-file /path/to/policy.yml ``` ```yaml title="policy.yml" -inbound: +on_tcp_connect: - name: "LimitToKnownIPs" expressions: - "conn.client_ip != '8.8.8.8'" diff --git a/examples/agent-cli/tls-traffic-policy.mdx b/examples/agent-cli/tls-traffic-policy.mdx index b79957935..1558f0342 100644 --- a/examples/agent-cli/tls-traffic-policy.mdx +++ b/examples/agent-cli/tls-traffic-policy.mdx @@ -3,7 +3,7 @@ ngrok tls 80 --traffic-policy-file /path/to/policy.yml ``` ```yaml title="policy.yml" -inbound: +on_tcp_connect: - name: "LimitToKnownIPs" expressions: - "conn.client_ip != '8.8.8.8'" diff --git a/examples/agent-config/tcp-traffic-policy.mdx b/examples/agent-config/tcp-traffic-policy.mdx index b47bb2f62..647c18478 100644 --- a/examples/agent-config/tcp-traffic-policy.mdx +++ b/examples/agent-config/tcp-traffic-policy.mdx @@ -4,7 +4,7 @@ tunnels: proto: tcp addr: 22 traffic_policy: - inbound: + on_tcp_connect: - name: DenyTrafficOutsideUS expressions: - "conn.geo.country_code != 'US'" diff --git a/examples/agent-config/tls-traffic-policy.mdx b/examples/agent-config/tls-traffic-policy.mdx index 210966344..e884368dc 100644 --- a/examples/agent-config/tls-traffic-policy.mdx +++ b/examples/agent-config/tls-traffic-policy.mdx @@ -4,7 +4,7 @@ tunnels: proto: tls addr: 443 traffic_policy: - inbound: + on_tcp_connect: - name: EnforceTLS1.3 expressions: - "conn.TLS.Version != 'TLS 1.3'" diff --git a/examples/javascript-sdk/http-traffic-policy.mdx b/examples/javascript-sdk/http-traffic-policy.mdx index bfa3a2361..0234aee7f 100644 --- a/examples/javascript-sdk/http-traffic-policy.mdx +++ b/examples/javascript-sdk/http-traffic-policy.mdx @@ -62,32 +62,32 @@ Traffic Policies can be defined in `json` or `yaml`! ```yaml title="policy.yaml" --- on_http_request: -- name: FooBarParamNotFound - expressions: - - "'bar' in getQueryParam('foo')" - actions: - - type: custom-response - config: - status_code: 404 - content: not found - headers: - content-type: text/plain -- name: BazCookieForLargeRequests - expressions: - - "!hasReqCookie('baz')" - - req.content_length > 5000 - actions: - - type: deny + - name: FooBarParamNotFound + expressions: + - "'bar' in getQueryParam('foo')" + actions: + - type: custom-response + config: + status_code: 404 + content: not found + headers: + content-type: text/plain + - name: BazCookieForLargeRequests + expressions: + - "!hasReqCookie('baz')" + - req.content_length > 5000 + actions: + - type: deny on_http_response: -- name: LogUnsuccessfulRequests - expressions: - - res.status_code < 200 && res.status_code >= 300 - actions: - - type: log - config: - metadata: - hostport: example.com:443 - success: false + - name: LogUnsuccessfulRequests + expressions: + - res.status_code < 200 && res.status_code >= 300 + actions: + - type: log + config: + metadata: + hostport: example.com:443 + success: false ``` Javascript SDK Docs: diff --git a/examples/javascript-sdk/tcp-traffic-policy.mdx b/examples/javascript-sdk/tcp-traffic-policy.mdx index fbfbc2e74..9b1de7aaa 100644 --- a/examples/javascript-sdk/tcp-traffic-policy.mdx +++ b/examples/javascript-sdk/tcp-traffic-policy.mdx @@ -7,7 +7,7 @@ const fs = require("fs"); addr: 8080, proto: "tcp", authtoken_from_env: true, - policy: fs.readFileSync("/path/to/policy.json", "utf8"), + traffic_policy: fs.readFileSync("/path/to/policy.json", "utf8"), }); console.log(`Ingress established at: ${listener.url()}`); @@ -16,7 +16,7 @@ const fs = require("fs"); ```yaml title="policy.json" { - "inbound": + "on_tcp_connect": [ { "name": "DenyTrafficOutsideUS", @@ -41,4 +41,4 @@ const fs = require("fs"); Javascript SDK Docs: -- [https://ngrok.github.io/ngrok-javascript/classes/TcpListenerBuilder.html#policy](https://ngrok.github.io/ngrok-javascript/classes/TcpListenerBuilder.html#policy) +- [https://ngrok.github.io/ngrok-javascript/classes/TcpListenerBuilder.html#trafficPolicy](https://ngrok.github.io/ngrok-javascript/classes/TcpListenerBuilder.html#trafficPolicy) diff --git a/examples/javascript-sdk/tls-traffic-policy.mdx b/examples/javascript-sdk/tls-traffic-policy.mdx index a741098b9..a426c6cd7 100644 --- a/examples/javascript-sdk/tls-traffic-policy.mdx +++ b/examples/javascript-sdk/tls-traffic-policy.mdx @@ -7,7 +7,7 @@ const fs = require("fs"); addr: 8080, proto: "tls", authtoken_from_env: true, - policy: fs.readFileSync("/path/to/policy.json", "utf8"), + traffic_policy: fs.readFileSync("/path/to/policy.json", "utf8"), }); console.log(`Ingress established at: ${listener.url()}`); @@ -16,7 +16,7 @@ const fs = require("fs"); ```yaml title="policy.json" { - "inbound": + "on_tcp_connect": [ { "name": "DenyTrafficOutsideUS", @@ -41,4 +41,4 @@ const fs = require("fs"); Javascript SDK Docs: -- [https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#policy](https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#policy) +- [https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#trafficPolicy](https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#trafficPolicy) diff --git a/examples/python-sdk/http-traffic-policy.mdx b/examples/python-sdk/http-traffic-policy.mdx index c6ef70554..e1654b383 100644 --- a/examples/python-sdk/http-traffic-policy.mdx +++ b/examples/python-sdk/http-traffic-policy.mdx @@ -53,32 +53,32 @@ Traffic Policies can be defined in `json` or `yaml`! ```yaml title="policy.yaml" --- on_http_request: -- name: FooBarParamNotFound - expressions: - - "'bar' in getQueryParam('foo')" - actions: - - type: custom-response - config: - status_code: 404 - content: not found - headers: - content-type: text/plain -- name: BazCookieForLargeRequests - expressions: - - "!hasReqCookie('baz')" - - req.content_length > 5000 - actions: - - type: deny + - name: FooBarParamNotFound + expressions: + - "'bar' in getQueryParam('foo')" + actions: + - type: custom-response + config: + status_code: 404 + content: not found + headers: + content-type: text/plain + - name: BazCookieForLargeRequests + expressions: + - "!hasReqCookie('baz')" + - req.content_length > 5000 + actions: + - type: deny on_http_response: -- name: LogUnsuccessfulRequests - expressions: - - res.status_code < 200 && res.status_code >= 300 - actions: - - type: log - config: - metadata: - hostport: example.com:443 - success: false + - name: LogUnsuccessfulRequests + expressions: + - res.status_code < 200 && res.status_code >= 300 + actions: + - type: log + config: + metadata: + hostport: example.com:443 + success: false ``` Python SDK Docs: diff --git a/examples/python-sdk/tcp-traffic-policy.mdx b/examples/python-sdk/tcp-traffic-policy.mdx index 7a4d80b74..0e4659d03 100644 --- a/examples/python-sdk/tcp-traffic-policy.mdx +++ b/examples/python-sdk/tcp-traffic-policy.mdx @@ -1,12 +1,12 @@ ```python with open('/path/to/policy.json') as f: policy = json.load(f) - listener = await session.http_endpoint().policy(policy).listen() + listener = await session.http_endpoint().traffic_policy(policy).listen() ``` ```yaml title="policy.json" { - "inbound": + "on_tcp_connect": [ { "name": "DenyTrafficOutsideUS", @@ -31,4 +31,4 @@ with open('/path/to/policy.json') as f: Python SDK Docs: -- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.policy) +- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy) diff --git a/examples/python-sdk/tls-traffic-policy.mdx b/examples/python-sdk/tls-traffic-policy.mdx index 6498e572c..b6ca8c061 100644 --- a/examples/python-sdk/tls-traffic-policy.mdx +++ b/examples/python-sdk/tls-traffic-policy.mdx @@ -1,12 +1,12 @@ ```python with open('/path/to/policy.json') as f: policy = json.load(f) - listener = await session.http_endpoint().policy(policy).listen() + listener = await session.http_endpoint().traffic_policy(policy).listen() ``` ```yaml title="policy.json" { - "inbound": + "on_tcp_connect": [ { "name": "DenyTrafficOutsideUS", @@ -31,4 +31,4 @@ with open('/path/to/policy.json') as f: Python SDK Docs: -- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.policy) +- [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy) diff --git a/traffic-policy/actions/deny/tcp/examples/tcp-basic-example.mdx b/traffic-policy/actions/deny/tcp/examples/tcp-basic-example.mdx index c01cd463d..3db178e2a 100644 --- a/traffic-policy/actions/deny/tcp/examples/tcp-basic-example.mdx +++ b/traffic-policy/actions/deny/tcp/examples/tcp-basic-example.mdx @@ -13,7 +13,7 @@ configuration will deny all inbound traffic on your endpoint. yamlMetastring="{4-10}" jsonMetastring="{5-7}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/deny/tls/examples/tls-basic-example.mdx b/traffic-policy/actions/deny/tls/examples/tls-basic-example.mdx index 5a77a0f09..c06740a15 100644 --- a/traffic-policy/actions/deny/tls/examples/tls-basic-example.mdx +++ b/traffic-policy/actions/deny/tls/examples/tls-basic-example.mdx @@ -13,7 +13,7 @@ configuration will deny all inbound traffic on your endpoint. yamlMetastring="{4-10}" jsonMetastring="{5-7}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/tcp/examples/1-basic-example.mdx b/traffic-policy/actions/restrict-ips/tcp/examples/1-basic-example.mdx index d09af4965..87d2a23bd 100644 --- a/traffic-policy/actions/restrict-ips/tcp/examples/1-basic-example.mdx +++ b/traffic-policy/actions/restrict-ips/tcp/examples/1-basic-example.mdx @@ -14,7 +14,7 @@ using the `restrict-ips` action. yamlMetastring="{4-10}" jsonMetastring="{5-16}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/tcp/examples/2-using-ip-policies.mdx b/traffic-policy/actions/restrict-ips/tcp/examples/2-using-ip-policies.mdx index 40a4afb2c..79521e911 100644 --- a/traffic-policy/actions/restrict-ips/tcp/examples/2-using-ip-policies.mdx +++ b/traffic-policy/actions/restrict-ips/tcp/examples/2-using-ip-policies.mdx @@ -14,7 +14,7 @@ action with [IP Policies](/docs/api/resources/ip-policies/). yamlMetastring="{4-10}" jsonMetastring="{5-13}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/tcp/examples/3-testing-traffic.mdx b/traffic-policy/actions/restrict-ips/tcp/examples/3-testing-traffic.mdx index 15cce2a92..14eae7a70 100644 --- a/traffic-policy/actions/restrict-ips/tcp/examples/3-testing-traffic.mdx +++ b/traffic-policy/actions/restrict-ips/tcp/examples/3-testing-traffic.mdx @@ -14,7 +14,7 @@ action with the `restrict-ips` action and [IP Policies](/docs/api/resources/ip-p yamlMetastring="{6,9-17}" jsonMetastring="{8,14-26}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/tls/examples/1-basic-example.mdx b/traffic-policy/actions/restrict-ips/tls/examples/1-basic-example.mdx index 8a7cf1c87..157c32674 100644 --- a/traffic-policy/actions/restrict-ips/tls/examples/1-basic-example.mdx +++ b/traffic-policy/actions/restrict-ips/tls/examples/1-basic-example.mdx @@ -14,7 +14,7 @@ using the `restrict-ips` action. yamlMetastring="{4-10}" jsonMetastring="{5-16}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/tls/examples/2-using-ip-policies.mdx b/traffic-policy/actions/restrict-ips/tls/examples/2-using-ip-policies.mdx index d58f14caa..17bda80c8 100644 --- a/traffic-policy/actions/restrict-ips/tls/examples/2-using-ip-policies.mdx +++ b/traffic-policy/actions/restrict-ips/tls/examples/2-using-ip-policies.mdx @@ -14,7 +14,7 @@ action with [IP Policies](/docs/api/resources/ip-policies/). yamlMetastring="{4-10}" jsonMetastring="{5-13}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { diff --git a/traffic-policy/actions/restrict-ips/tls/examples/3-testing-traffic.mdx b/traffic-policy/actions/restrict-ips/tls/examples/3-testing-traffic.mdx index 85be548fa..9f69b60bc 100644 --- a/traffic-policy/actions/restrict-ips/tls/examples/3-testing-traffic.mdx +++ b/traffic-policy/actions/restrict-ips/tls/examples/3-testing-traffic.mdx @@ -14,7 +14,7 @@ action with the `restrict-ips` action and [IP Policies](/docs/api/resources/ip-p yamlMetastring="{6,9-17}" jsonMetastring="{8,14-26}" config={{ - inbound: [ + on_tcp_connect: [ { actions: [ { From b4e9b5726756c6ee823197422299906fbc5e4d38 Mon Sep 17 00:00:00 2001 From: Ryan Grant Date: Wed, 25 Sep 2024 09:32:12 -0700 Subject: [PATCH 3/4] update action index page (forgot) --- docs/http/traffic-policy/actions/index.mdx | 26 +++++++++++----------- docs/tcp/traffic-policy/actions/index.mdx | 10 ++++----- docs/tls/traffic-policy/actions/index.mdx | 10 ++++----- 3 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/http/traffic-policy/actions/index.mdx b/docs/http/traffic-policy/actions/index.mdx index 03254e7c7..4c7ed277f 100644 --- a/docs/http/traffic-policy/actions/index.mdx +++ b/docs/http/traffic-policy/actions/index.mdx @@ -9,16 +9,16 @@ pagination_label: Actions Traffic Policy actions enable you to modify the behavior of traffic flowing through your endpoints. The following actions are available for use on your endpoints: -| Type | Description | Supported On | -| -------------------------------------- | --------------------------------------------------------------------- | ----------------- | -| [add-headers](add-headers) | Add custom headers to incoming requests or outgoing responses. | Inbound, Outbound | -| [compress-response](compress-response) | Compress HTTP response bodies from your upstream server. | Inbound, Outbound | -| [custom-response](custom-response) | Send a predefined custom response directly to the client. | Inbound, Outbound | -| [deny](deny) | Block incoming traffic to an endpoint. | Inbound | -| [jwt-validation](jwt-validation) | Validate JSON Web Tokens (JWT). | Inbound | -| [log](log) | Add metadata to events for logging and monitoring. | Inbound, Outbound | -| [rate-limit](rate-limit) | Rate limit traffic to your upstream servers. | Inbound | -| [redirect](redirect) | Redirect users through URL transformations using regular expressions. | Inbound | -| [remove-headers](remove-headers) | Remove headers from incoming requests or outgoing responses. | Inbound, Outbound | -| [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | Inbound | -| [url-rewrite](url-rewrite) | Rewrite request URLs transparently using regular expressions. | Inbound | +| Type | Description | Supported On | +| -------------------------------------- | --------------------------------------------------------------------- | --------------------------------- | +| [add-headers](add-headers) | Add custom headers to incoming requests or outgoing responses. | on_http_request, on_http_response | +| [compress-response](compress-response) | Compress HTTP response bodies from your upstream server. | on_http_request, on_http_response | +| [custom-response](custom-response) | Send a predefined custom response directly to the client. | on_http_request, on_http_response | +| [deny](deny) | Block incoming traffic to an endpoint. | on_http_request | +| [jwt-validation](jwt-validation) | Validate JSON Web Tokens (JWT). | on_http_request | +| [log](log) | Add metadata to events for logging and monitoring. | on_http_request, on_http_response | +| [rate-limit](rate-limit) | Rate limit traffic to your upstream servers. | on_http_request | +| [redirect](redirect) | Redirect users through URL transformations using regular expressions. | on_http_request | +| [remove-headers](remove-headers) | Remove headers from incoming requests or outgoing responses. | on_http_request, on_http_response | +| [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | on_http_request | +| [url-rewrite](url-rewrite) | Rewrite request URLs transparently using regular expressions. | on_http_request | diff --git a/docs/tcp/traffic-policy/actions/index.mdx b/docs/tcp/traffic-policy/actions/index.mdx index 523063744..b8ff84e03 100644 --- a/docs/tcp/traffic-policy/actions/index.mdx +++ b/docs/tcp/traffic-policy/actions/index.mdx @@ -8,8 +8,8 @@ pagination_next: tcp/traffic-policy/actions/deny Traffic Policy actions enable you to modify the behavior of traffic flowing through your endpoints. The following actions are available for use on your endpoints: -| Type | Description | Supports | -| ---------------------------- | ------------------------------------------- | -------- | -| [deny](deny) | Reject incoming traffic to an endpoint. | Inbound | -| [log](log) | Emit an event with custom defined metadata. | Inbound | -| [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | Inbound | +| Type | Description | Supports | +| ---------------------------- | ------------------------------------------- | -------------- | +| [deny](deny) | Reject incoming traffic to an endpoint. | on_tcp_connect | +| [log](log) | Emit an event with custom defined metadata. | on_tcp_connect | +| [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | on_tcp_connect | diff --git a/docs/tls/traffic-policy/actions/index.mdx b/docs/tls/traffic-policy/actions/index.mdx index 938bdc4ab..274d1a3f2 100644 --- a/docs/tls/traffic-policy/actions/index.mdx +++ b/docs/tls/traffic-policy/actions/index.mdx @@ -8,8 +8,8 @@ pagination_next: tls/traffic-policy/actions/deny Traffic Policy actions enable you to modify the behavior of traffic flowing through your endpoints. The following actions are available for use on your endpoints: -| Type | Description | Supports | -| ---------------------------- | ------------------------------------------- | -------- | -| [deny](deny) | Reject incoming traffic to an endpoint. | Inbound | -| [log](log) | Emit an event with custom defined metadata. | Inbound | -| [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | Inbound | +| Type | Description | Supports | +| ---------------------------- | ------------------------------------------- | -------------- | +| [deny](deny) | Reject incoming traffic to an endpoint. | on_tcp_connect | +| [log](log) | Emit an event with custom defined metadata. | on_tcp_connect | +| [restrict-ips](restrict-ips) | Allow or deny traffic based on source IP. | on_tcp_connect | From 5ae3b5f5ac890d42e739cc1c88acbc492b60991a Mon Sep 17 00:00:00 2001 From: Ryan Grant Date: Wed, 25 Sep 2024 10:04:55 -0700 Subject: [PATCH 4/4] update sdk examples --- examples/go-sdk/http-traffic-policy.mdx | 136 +++++++++++------- examples/go-sdk/tcp-traffic-policy.mdx | 80 ++++++++--- examples/go-sdk/tls-traffic-policy.mdx | 80 ++++++++--- .../javascript-sdk/tcp-traffic-policy.mdx | 73 +++++++--- .../javascript-sdk/tls-traffic-policy.mdx | 73 +++++++--- examples/python-sdk/tcp-traffic-policy.mdx | 73 +++++++--- examples/python-sdk/tls-traffic-policy.mdx | 73 +++++++--- 7 files changed, 416 insertions(+), 172 deletions(-) diff --git a/examples/go-sdk/http-traffic-policy.mdx b/examples/go-sdk/http-traffic-policy.mdx index c46643dd7..b8f3bddd7 100644 --- a/examples/go-sdk/http-traffic-policy.mdx +++ b/examples/go-sdk/http-traffic-policy.mdx @@ -11,63 +11,95 @@ import ( func ngrokListener(ctx context.Context) (net.Listener, error) { return ngrok.Listen(ctx, config.HTTPEndpoint( - config.WithPolicy( - policy.Policy{ - Inbound: []policy.Rule{ - { - Name: "FooBarParamNotFound", - Expressions: []string{"'bar' in getQueryParam('foo')"}, - Actions: []policy.Action{ - { - Type: "custom-response", - Config: map[string]any{ - "status_code": 400, - "content": "not found", - "headers": { - "content-type": "text/plain" - } - }, - }, - }, - }, - { - Name: "BazCookieForLargeRequests", - Expressions: []string{ - "!hasReqCookie('baz')", - "req.content_length > 5000", - }, - Actions: []policy.Action{ - { - Type: "deny", - }, - }, - }, - }, - Outbound: []policy.Rule{ - { - Name: "LogUnsuccessfulRequests", - Expressions: []string{"res.status_code < 200 && res.status_code >= 300"}, - Actions: []policy.Action{ - { - Type: "log", - Config: map[string]any{ - "metadata": map[string]any{ - "hostport": "example.com:443", - "success": false, - }, - }, - }, - }, - }, - }, - }, - ), + config.WithPolicyString(getPolicyFromFile()), ), ngrok.WithAuthtokenFromEnv(), ) } + +func getPolicyFromFile() string { + b, _ := os.ReadFile("./policy.yaml") + return string(b) +} +``` + +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" +{ + "on_http_request": [ + { + "name": "FooBarParamNotFound", + "expressions": ["'bar' in getQueryParam('foo')"], + "actions": [ + { + "type": "custom-response", + "config": { + "status_code": 404, + "content": "not found", + "headers": { "content-type": "text/plain" } + } + } + ] + }, + { + "name": "BazCookieForLargeRequests", + "expressions": ["!hasReqCookie('baz')", "req.content_length > 5000"], + "actions": [{ "type": "deny" }] + } + ], + "on_http_response": [ + { + "name": "LogUnsuccessfulRequests", + "expressions": ["res.status_code < 200 && res.status_code >= 300"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { "hostport": "example.com:443", "success": false } + } + } + ] + } + ] +} +``` + +```yaml title="policy.yaml" +--- +on_http_request: + - name: FooBarParamNotFound + expressions: + - "'bar' in getQueryParam('foo')" + actions: + - type: custom-response + config: + status_code: 404 + content: not found + headers: + content-type: text/plain + - name: BazCookieForLargeRequests + expressions: + - "!hasReqCookie('baz')" + - req.content_length > 5000 + actions: + - type: deny +on_http_response: + - name: LogUnsuccessfulRequests + expressions: + - res.status_code < 200 && res.status_code >= 300 + actions: + - type: log + config: + metadata: + hostport: example.com:443 + success: false ``` Go Package Docs: -- [https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithPolicy](https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithPolicy) +- [https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithPolicyString](https://pkg.go.dev/golang.ngrok.com/ngrok/config#WithPolicyString) diff --git a/examples/go-sdk/tcp-traffic-policy.mdx b/examples/go-sdk/tcp-traffic-policy.mdx index 4a1f24196..23635acdb 100644 --- a/examples/go-sdk/tcp-traffic-policy.mdx +++ b/examples/go-sdk/tcp-traffic-policy.mdx @@ -10,28 +10,72 @@ import ( func ngrokListener(ctx context.Context) (net.Listener, error) { return ngrok.Listen(ctx, config.TCPEndpoint( - config.WithPolicy( - policy.Policy{ - Inbound: []policy.Rule{ - { - Name: "LimitToKnownIPs", - Expressions: []string{ - "conn.client_ip != '8.8.8.8'", - "conn.client_ip != '9.9.9.9'", - }, - Actions: []policy.Action{ - { - Type: "deny", - }, - }, - }, - }, - }, - ), + config.WithTrafficPolicy(getPolicyFromFile()), ), ngrok.WithAuthtokenFromEnv(), ) } + +func getPolicyFromFile() string { + b, _ := os.ReadFile("./policy.yaml") + return string(b) +} +``` + +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" +{ + "on_tcp_connect": [ + { + "name": "DenyTrafficOutsideUS", + "expressions": ["conn.Geo.CountryCode != 'US'"], + "actions": [ + { + "type": "deny" + } + ] + }, + { + "name": "LogRequestsFromKnownIP", + "expressions": ["conn.ClientIP == '110.0.0.1"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { + "event": "known-ip", + "data": "110.0.0.1" + } + } + } + ] + } + ] +} +``` + +```yaml title="policy.yaml" +--- +on_tcp_connect: + - name: DenyTrafficOutsideUS + expressions: + - conn.Geo.CountryCode != 'US' + actions: + - type: deny + - name: LogRequestsFromKnownIP + expressions: + - conn.ClientIP == '110.0.0.1 + actions: + - type: log + config: + metadata: + event: known-ip + data: 110.0.0.1 ``` Go Package Docs: diff --git a/examples/go-sdk/tls-traffic-policy.mdx b/examples/go-sdk/tls-traffic-policy.mdx index 7a4129b5c..ae63ba7e3 100644 --- a/examples/go-sdk/tls-traffic-policy.mdx +++ b/examples/go-sdk/tls-traffic-policy.mdx @@ -10,28 +10,72 @@ import ( func ngrokListener(ctx context.Context) (net.Listener, error) { return ngrok.Listen(ctx, config.TLSEndpoint( - config.WithPolicy( - policy.Policy{ - Inbound: []policy.Rule{ - { - Name: "LimitToKnownIPs", - Expressions: []string{ - "conn.ClientIP != '8.8.8.8'", - "conn.ClientIP != '9.9.9.9'", - }, - Actions: []policy.Action{ - { - Type: "deny", - }, - }, - }, - }, - }, - ), + config.WithPolicyString(getPolicyFromFile()), ), ngrok.WithAuthtokenFromEnv(), ) } + +func getPolicyFromFile() string { + b, _ := os.ReadFile("./policy.yaml") + return string(b) +} +``` + +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" +{ + "on_tcp_connect": [ + { + "name": "DenyTrafficOutsideUS", + "expressions": ["conn.Geo.CountryCode != 'US'"], + "actions": [ + { + "type": "deny" + } + ] + }, + { + "name": "LogRequestsFromKnownIP", + "expressions": ["conn.ClientIP == '110.0.0.1"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { + "event": "known-ip", + "data": "110.0.0.1" + } + } + } + ] + } + ] +} +``` + +```yaml title="policy.yaml" +--- +on_tcp_connect: + - name: DenyTrafficOutsideUS + expressions: + - conn.Geo.CountryCode != 'US' + actions: + - type: deny + - name: LogRequestsFromKnownIP + expressions: + - conn.ClientIP == '110.0.0.1 + actions: + - type: log + config: + metadata: + event: known-ip + data: 110.0.0.1 ``` Go Package Docs: diff --git a/examples/javascript-sdk/tcp-traffic-policy.mdx b/examples/javascript-sdk/tcp-traffic-policy.mdx index 9b1de7aaa..a3310c3f6 100644 --- a/examples/javascript-sdk/tcp-traffic-policy.mdx +++ b/examples/javascript-sdk/tcp-traffic-policy.mdx @@ -14,31 +14,62 @@ const fs = require("fs"); })(); ``` -```yaml title="policy.json" +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" { - "on_tcp_connect": - [ - { - "name": "DenyTrafficOutsideUS", - "expressions": ["conn.geo.country_code != 'US'"], - "actions": [{ "type": "deny" }], - }, - { - "name": "LogRequestsFromKnownIP", - "expressions": ["conn.client_ip == '110.0.0.1"], - "actions": - [ - { - "type": "log", - "config": - { "metadata": { "event": "known-ip", "data": "110.0.0.1" } }, - }, - ], - }, - ], + "on_tcp_connect": [ + { + "name": "DenyTrafficOutsideUS", + "expressions": ["conn.Geo.CountryCode != 'US'"], + "actions": [ + { + "type": "deny" + } + ] + }, + { + "name": "LogRequestsFromKnownIP", + "expressions": ["conn.ClientIP == '110.0.0.1"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { + "event": "known-ip", + "data": "110.0.0.1" + } + } + } + ] + } + ] } ``` +```yaml title="policy.yaml" +--- +on_tcp_connect: + - name: DenyTrafficOutsideUS + expressions: + - conn.Geo.CountryCode != 'US' + actions: + - type: deny + - name: LogRequestsFromKnownIP + expressions: + - conn.ClientIP == '110.0.0.1 + actions: + - type: log + config: + metadata: + event: known-ip + data: 110.0.0.1 +``` + Javascript SDK Docs: - [https://ngrok.github.io/ngrok-javascript/classes/TcpListenerBuilder.html#trafficPolicy](https://ngrok.github.io/ngrok-javascript/classes/TcpListenerBuilder.html#trafficPolicy) diff --git a/examples/javascript-sdk/tls-traffic-policy.mdx b/examples/javascript-sdk/tls-traffic-policy.mdx index a426c6cd7..8c5a10c6e 100644 --- a/examples/javascript-sdk/tls-traffic-policy.mdx +++ b/examples/javascript-sdk/tls-traffic-policy.mdx @@ -14,31 +14,62 @@ const fs = require("fs"); })(); ``` -```yaml title="policy.json" +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" { - "on_tcp_connect": - [ - { - "name": "DenyTrafficOutsideUS", - "expressions": ["conn.Geo.CountryCode != 'US'"], - "actions": [{ "type": "deny" }], - }, - { - "name": "LogRequestsFromKnownIP", - "expressions": ["conn.ClientIP == '110.0.0.1"], - "actions": - [ - { - "type": "log", - "config": - { "metadata": { "event": "known-ip", "data": "110.0.0.1" } }, - }, - ], - }, - ], + "on_tcp_connect": [ + { + "name": "DenyTrafficOutsideUS", + "expressions": ["conn.Geo.CountryCode != 'US'"], + "actions": [ + { + "type": "deny" + } + ] + }, + { + "name": "LogRequestsFromKnownIP", + "expressions": ["conn.ClientIP == '110.0.0.1"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { + "event": "known-ip", + "data": "110.0.0.1" + } + } + } + ] + } + ] } ``` +```yaml title="policy.yaml" +--- +on_tcp_connect: + - name: DenyTrafficOutsideUS + expressions: + - conn.Geo.CountryCode != 'US' + actions: + - type: deny + - name: LogRequestsFromKnownIP + expressions: + - conn.ClientIP == '110.0.0.1 + actions: + - type: log + config: + metadata: + event: known-ip + data: 110.0.0.1 +``` + Javascript SDK Docs: - [https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#trafficPolicy](https://ngrok.github.io/ngrok-javascript/classes/TlsListenerBuilder.html#trafficPolicy) diff --git a/examples/python-sdk/tcp-traffic-policy.mdx b/examples/python-sdk/tcp-traffic-policy.mdx index 0e4659d03..472e7d7a7 100644 --- a/examples/python-sdk/tcp-traffic-policy.mdx +++ b/examples/python-sdk/tcp-traffic-policy.mdx @@ -4,31 +4,62 @@ with open('/path/to/policy.json') as f: listener = await session.http_endpoint().traffic_policy(policy).listen() ``` -```yaml title="policy.json" +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" { - "on_tcp_connect": - [ - { - "name": "DenyTrafficOutsideUS", - "expressions": ["conn.geo.country_code != 'US'"], - "actions": [{ "type": "deny" }], - }, - { - "name": "LogRequestsFromKnownIP", - "expressions": ["conn.client_ip == '110.0.0.1"], - "actions": - [ - { - "type": "log", - "config": - { "metadata": { "event": "known-ip", "data": "110.0.0.1" } }, - }, - ], - }, - ], + "on_tcp_connect": [ + { + "name": "DenyTrafficOutsideUS", + "expressions": ["conn.Geo.CountryCode != 'US'"], + "actions": [ + { + "type": "deny" + } + ] + }, + { + "name": "LogRequestsFromKnownIP", + "expressions": ["conn.ClientIP == '110.0.0.1"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { + "event": "known-ip", + "data": "110.0.0.1" + } + } + } + ] + } + ] } ``` +```yaml title="policy.yaml" +--- +on_tcp_connect: + - name: DenyTrafficOutsideUS + expressions: + - conn.Geo.CountryCode != 'US' + actions: + - type: deny + - name: LogRequestsFromKnownIP + expressions: + - conn.ClientIP == '110.0.0.1 + actions: + - type: log + config: + metadata: + event: known-ip + data: 110.0.0.1 +``` + Python SDK Docs: - [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy) diff --git a/examples/python-sdk/tls-traffic-policy.mdx b/examples/python-sdk/tls-traffic-policy.mdx index b6ca8c061..472e7d7a7 100644 --- a/examples/python-sdk/tls-traffic-policy.mdx +++ b/examples/python-sdk/tls-traffic-policy.mdx @@ -4,31 +4,62 @@ with open('/path/to/policy.json') as f: listener = await session.http_endpoint().traffic_policy(policy).listen() ``` -```yaml title="policy.json" +:::info + +Traffic Policies can be defined in `json` or `yaml`! + +::: + +```json title="policy.json" { - "on_tcp_connect": - [ - { - "name": "DenyTrafficOutsideUS", - "expressions": ["conn.Geo.CountryCode != 'US'"], - "actions": [{ "type": "deny" }], - }, - { - "name": "LogRequestsFromKnownIP", - "expressions": ["conn.ClientIP == '110.0.0.1"], - "actions": - [ - { - "type": "log", - "config": - { "metadata": { "event": "known-ip", "data": "110.0.0.1" } }, - }, - ], - }, - ], + "on_tcp_connect": [ + { + "name": "DenyTrafficOutsideUS", + "expressions": ["conn.Geo.CountryCode != 'US'"], + "actions": [ + { + "type": "deny" + } + ] + }, + { + "name": "LogRequestsFromKnownIP", + "expressions": ["conn.ClientIP == '110.0.0.1"], + "actions": [ + { + "type": "log", + "config": { + "metadata": { + "event": "known-ip", + "data": "110.0.0.1" + } + } + } + ] + } + ] } ``` +```yaml title="policy.yaml" +--- +on_tcp_connect: + - name: DenyTrafficOutsideUS + expressions: + - conn.Geo.CountryCode != 'US' + actions: + - type: deny + - name: LogRequestsFromKnownIP + expressions: + - conn.ClientIP == '110.0.0.1 + actions: + - type: log + config: + metadata: + event: known-ip + data: 110.0.0.1 +``` + Python SDK Docs: - [https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy](https://ngrok.github.io/ngrok-python/http_listener_builder.html#ngrok.HttpListenerBuilder.traffic_policy)