Skip to content

Commit

Permalink
Reorganize existing modules to match new format.
Browse files Browse the repository at this point in the history 
There are no meaningful changes in this changeset, it just moves around
sections and text in the docs of existing modules to match the new
format used by the docs for request/response headers and the oauth
modules.
  • Loading branch information
@inconshreveable
inconshreveable committed Aug 15, 2023
1 parent 7056064 commit 1dc67e6
Show file tree
Hide file tree
Showing 7 changed files with 327 additions and 282 deletions.
127 changes: 58 additions & 69 deletions docs/cloud-edge/modules/circuit-breaker.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ upstream application once again.

### Agent CLI

```
```bash
ngrok http 80 --circuit-breaker 0.5
```

Expand All @@ -39,7 +39,7 @@ tunnels:
### SSH
```
```bash
ssh -R 443:localhost:80 connect.ngrok-agent.com http --circuit-breaker 0.5
```

Expand Down Expand Up @@ -131,6 +131,62 @@ Circuit Breaker is a supported Edge module which can be applied to routes.
- [Circuit Breaker Edge Module API Resource](/api/resources/https-edge-route-circuit-breaker-module/)
## Behavior
The Circuit Breaker module is an implementation of [Netflix's Hystrix circuit
breaker specification](https://github.com/Netflix/Hystrix/wiki/How-it-Works).
If the upstream server responds with more than the threshold percentage of
requests with 5XX status codes, the circuit breaker preemptively reject all
subsequent requests at the ngrok edge with a 503 until the upstream server's
error rate drops below the threshold percentage.
Circuit breaker state is tracked on each ngrok edge server individually. There
are many ngrok edge servers which means that your upstream server may observe
requests even after you would expect the circuit breaker to open. All of
ngrok's edge servers will eventually open their circuits to protect an failing
upstream application but the behavior you observe may not exactly match the
parameters you've set because circuit breaker state is tracked individually on
each of ngrok's edge servers.
## Reference
### Configuration
The Agent and Agent SDKs do not support configuration of some parameters of the
Circuit Breaker.
| Parameter | Default | Description |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Error Threshold** | | The threshold percentage of upstream requests that must fail before the circuit is opened expressed a decimal value between 0 and 1. ngrok defines any HTTP response with a status code greater than or equal to 500 as an error response that counts toward the circuit breaker threshold. |
| **Tripped Duration** | 10 | The number of seconds to reject requests, once the circuit is opened, before rechecking if the circuit should again be closed. |
| **Rolling Window** | 10 | The window of time we keep metrics for the circuit breaker, the error threshold only considers successes and errors that fall within this window. |
| **Number of Buckets** | 10 | The number of discrete time intervals the rolling window duration is divided into. Along with the rolling window duration, this defines the granularity at which requests expire out of the rolling window. Max 128. |
| **Volume Threshold** | 20 | The minimum number of requests required in a rolling window that will trip the circuit. |
### Upstream Headers {#upstream-headers}
This module does not add any upstream headers.
### Errors
| Code | HTTP Status | Error |
| ----------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| [ERR_NGROK_3202](/errors/err_ngrok_3202/) | `503` | This error is returned if the circuit breaker is open because the upstream service is failing. |

### Events

When the Circuit Breaker module is enabled, it populates the following fields in
[http_request_complete.v0](/events/reference/#http-request-complete) events.

| Fields |
| -------------------------- |
| `circuit_breaker.decision` |

### Limits

This module is available on all plans.

## Try it out

This short Go program below that demonstrates Circuit Breaker behavior. Create
Expand Down Expand Up @@ -225,70 +281,3 @@ func makeRequests(appURL string) {
}
}
```

## Behavior

If the upstream server responds with more than the threshold percentage of
requests with 5XX status codes, the circuit breaker preemptively rejects all
subsequent requests at the ngrok edge with a 503 until the upstream server's
error rate drops below the threshold percentage.

The Circuit Breaker module is an implementation of [Netflix's Hystrix circuit
breaker specification](https://github.com/Netflix/Hystrix/wiki/How-it-Works).

### What contributes to the threshold?

ngrok defines any HTTP response with a status code greater than or equal to 500
as an error response that counts toward the circuit breaker threshold.

### Parameters

Circuit Breaker behavior can be customized. Defaults will be chosen for you for some values in two cases.

- If you enable the module via the Agent or Agent SDK. They don't allow you to
customize a number of the module's parameters.
- If you enable the module via the Edge API and don't explicitly set values for
all parameters.

| Parameter | Default | Description |
| --------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Error Threshold** | - | The threshold percentage of upstream requests that must fail before the circuit is opened. |
| **Tripped Duration** | 10 seconds | The number of seconds to reject requests, once the circuit is opened, before rechecking if the circuit should again be closed. |
| **Rolling Window** | 10 seconds | The window of time we keep metrics for the circuit breaker, the error threshold only considers successes and errors that fall within this window. |
| **Number of Buckets** | 10 buckets | The number of discrete time intervals the rolling window duration is divided into. Along with the rolling window duration, this defines the granularity at which requests expire out of the rolling window. |
| **Volume Threshold** | 20 requests | The minimum number of requests required in a rolling window that will trip the circuit. |

### Circuit Breaker State {#state}

At the time of writing, circuit breaker state is kept on each ngrok edge server
individually. There are many ngrok edge servers which means that your upstream
server may observe requests even after you would expect the circuit breaker to
open. All of ngrok's edge servers will eventually open their circuits to
protect an overloaded upstream but the behavior you observe may not exactly
match the parameters you've set because those parameters are applied
individually on each of ngrok's edge servers.

## Reference

### Upstream Headers {#upstream-headers}

No additional upstream headers are added by the Circuit Breaker module.

### Events

When the Circuit Breaker module is enabled, it populates the following fields in
[http_request_complete.v0](/events/reference/#http-request-complete) events.

| Fields |
| -------------------------- |
| `circuit_breaker.decision` |

### Errors

If the Circuit Breaker is open because the upstream service is failing, the
ngrok edge will return [ERR_NGROK_3202](/errors/err_ngrok_3202/) with a 503
Service Unavailable HTTP status code.

### Licensing

The Circuit Breaker module is available on all plans.
163 changes: 84 additions & 79 deletions docs/cloud-edge/modules/compression.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,13 +16,13 @@ ngrok takes no action.

### Agent CLI

```
```bash
ngrok http 80 --compression
```

### Agent Configuration File

```
```yaml
tunnels:
example:
proto: http
Expand All @@ -32,13 +32,13 @@ tunnels:
### SSH
```
```bash
ssh -R 443:localhost:80 connect.ngrok-agent.com http --compression
```

### Go SDK

```
```go
import (
"context"
"net"
Expand All @@ -61,7 +61,7 @@ func listenCompressed(ctx context.Context) net.Listener {

### Rust SDK

```
```rust
use ngrok::prelude::*;

async fn start_tunnel() -> anyhow::Result<impl Tunnel> {
Expand Down Expand Up @@ -121,12 +121,84 @@ has no configuration parameters. It is either enabled or disabled.
- [Compression Edge Module API Resource](/api/resources/https-edge-route-compression-module/)
## Behavior
### Streaming Compression
When ngrok performs compression, the response body is not buffered; the
response body is compressed as it is streamed through the ngrok edge.
### Algorithm Choice
If a request specifies `Accept-Encoding` but no requested values are supported,
ngrok takes no action and the upstream response is returned without
modification.

ngrok negotiates the encoding type as defined by the RFC for `Accept-Encoding`.
It respects q-values and chooses the `Accept-Encoding` supported algorithm with
the highest q-value.

ngrok supports the following compression algorithms in the `Accept-Encoding`
header.

| Algorithm | Supported |
| ---------- | --------- |
| `br` | no |
| `compress` | no |
| `deflate` | yes |
| `gzip` | yes |

### Response Headers

When ngrok performs compression, the following changes are made to
the HTTP response header:

- The `Content-Length` header is removed
- A `Content-Encoding` header is added with the negotiated algorithm
- A `Vary: Accept-Encoding` header is added

### Compression Level

The compression level is a value which indicates whether the compression
algorithm should prefer to save more space at the expense of being slower and
using more compute. This value is not currently configurable. ngrok
automatically chooses a value that provides a reasonable tradeoff.

## Reference

### Configuration

This module does not support any configuration. It is either enabled or
disabled.

### Upstream Headers {#upstream-headers}

This module does not add any upstream headers.

### Errors

This module does not return any errors.

### Events

When this module is enabled, it populates the following fields in
[http_request_complete.v0](/events/reference/#http-request-complete) events.

| Fields |
| ------------------------- |
| `compression.algorithm` |
| `compression.bytes_saved` |

### Limits

This module is available on all plans.

## Try it out

For testing purposes, create a directory with a file in it and then enter that
directory.

```
```bash
mkdir test-dir
cd test-dir
echo "hello world" > t.txt
Expand All @@ -139,13 +211,13 @@ for our compression testing.
First let's see what this looks like without using compression by running the
following in your `test-dir` directory:

```
```bash
ngrok http file://`pwd` --domain your-domain.ngrok.app
```

Then in another terminal while ngrok is still running:

```
```bash
curl --compressed -D - https://your-domain.ngrok.app/
```

Expand All @@ -155,7 +227,7 @@ curl --compressed -D - https://your-domain.ngrok.app/

You should get a response that looks like:

```
```http
HTTP/2 200
content-type: text/html; charset=utf-8
date: Tue, 18 Jul 2023 09:52:49 GMT
Expand All @@ -172,20 +244,20 @@ content-length: 39
Now let's try it again with compression. Stop your ngrok agent and restart it
by changing the command to:

```
```bash
ngrok http file://`pwd` --domain your-domain.ngrok.app --compression
```

Rerun the same curl command:

```
```bash
curl --compressed -D - https://your-domain.ngrok.app/
```

This time you should see that HTTP response headers include `content-encoding:
deflate` indicating that the response was compressed.

```
```http
HTTP/2 200
content-encoding: deflate
content-type: text/html; charset=utf-8
Expand All @@ -199,70 +271,3 @@ vary: Accept-Encoding
<a href="t.txt">t.txt</a>
</pre>
```

## Behavior

### Streaming Compression

When ngrok performs compression, the response body is not buffered; the
response body is compressed as it is streamed through the ngrok edge.

### Algorithm Choice

If a request specifies `Accept-Encoding` but no requested values are supported,
ngrok takes no action and the upstream response is returned without
modification.

ngrok negotiates the encoding type as defined by the RFC for `Accept-Encoding`.
It respects q-values and chooses the `Accept-Encoding` supported algorithm with
the highest q-value.

ngrok supports the following compression algorithms in the `Accept-Encoding`
header.

| Algorithm | Supported |
| ---------- | --------- |
| `br` | no |
| `compress` | no |
| `deflate` | yes |
| `gzip` | yes |

### Response Headers

When ngrok performs compression, the following changes are made to
the HTTP response header:

- The `Content-Length` header is removed
- A `Content-Encoding` header is added with the negotiated algorithm
- A `Vary: Accept-Encoding` header is added

### Compression Level

The compression level is a value which indicates whether the compression
algorithm should prefer to save more space at the expense of being slower and
using more compute. This value is not currently configurable. ngrok
automatically chooses a value that provides a reasonable tradeoff.

## Reference

### Upstream Headers {#upstream-headers}

No additional upstream headers are added by the Compression module.

### Events

When the compression module is enabled, it populates the following fields in
[http_request_complete.v0](/events/reference/#http-request-complete) events.

| Fields |
| ------------------------- |
| `compression.algorithm` |
| `compression.bytes_saved` |

### Errors

The compression module does not return any errors.

### Licensing

The compression module is available on the Free tier.
Loading

0 comments on commit 1dc67e6

Please sign in to comment.