From 889b2b4527e8f731bd1c7ecd0e2b16e9da043d69 Mon Sep 17 00:00:00 2001 From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> Date: Tue, 8 Oct 2024 10:49:36 -0700 Subject: [PATCH 1/2] revise global timeouts explanation Update the Read Timeout and Write Timeout descriptions. Call out the special behavior of the 0 value for all three. Add a sentence to discourage turning off the Read Timeout. --- content/docs/reference/global-timeouts.mdx | 26 ++++++++++++++-------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/content/docs/reference/global-timeouts.mdx b/content/docs/reference/global-timeouts.mdx index a4236d062..827fbe73f 100644 --- a/content/docs/reference/global-timeouts.mdx +++ b/content/docs/reference/global-timeouts.mdx @@ -25,7 +25,9 @@ You can set also set [route-level timeouts](/docs/reference/routes/timeouts). ## Read Timeout -**Read Timeout** sets the maximum amount of time for the client to receive an entire HTTP request stream. +**Read Timeout** sets the maximum amount of time for a downstream client to complete a single HTTP request. The time starts when a request is begun and ends either when Pomerium has proxied the entire request body to the upstream service, or when Pomerium has begun sending a response back to the client. + +This timeout is disabled if set to `0`. (This is not recommended, as a malicious client could consume significant resources by beginning many incomplete requests.) ### How to configure @@ -34,7 +36,7 @@ You can set also set [route-level timeouts](/docs/reference/routes/timeouts). | **Config file keys** | **Environment variables** | **Type** | **Default** | | :-- | :-- | :-- | :-- | -| `timeout_read` | `TIMEOUT_READ` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `30s` | +| `timeout_read` | `TIMEOUT_READ` | [Go Duration] string | `30s` | ### Examples @@ -56,7 +58,7 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time | **[Parameter name](/docs/k8s/reference#timeouts)** | **Type** | **Defaults** | | :-- | :-- | :-- | -| `timeouts.read` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `30s` | +| `timeouts.read` | [Go Duration] string | `30s` | ### Examples @@ -70,7 +72,9 @@ timeouts: ## Write Timeout -**Write Timeout** sets the maximum time that a stream’s lifetime will span. An HTTP request/response exchange fully consumes a single stream. So, the `write_timeout` value must be greater than `read_timeout`, as it covers both the HTTP request and response time. +**Write Timeout** sets the maximum time for a single HTTP request/response pair to fully complete. This should be greater than the [**Read Timeout**](#read-timeout) setting as this includes both the request and response time. + +This timeout is disabled if set to `0`. ### How to configure @@ -79,7 +83,7 @@ timeouts: | **Config file keys** | **Environment variables** | **Type** | **Default** | | :-- | :-- | :-- | :-- | -| `timeout_write` | `TIMEOUT_WRITE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `0` | +| `timeout_write` | `TIMEOUT_WRITE` | [Go Duration] string | `0` (no timeout) | ### Examples @@ -101,7 +105,7 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time | **[Parameter name](/docs/k8s/reference#timeouts)** | **Type** | **Default** | | :-- | :-- | :-- | -| `timeouts.write` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `0` | +| `timeouts.write` | [Go Duration] string | `0` (no timeout) | ### Examples @@ -115,7 +119,9 @@ timeouts: ## Idle Timeout -**Idle Timeout** sets the time at which an upstream or downstream connection will be terminated if there are no active streams. +**Idle Timeout** sets the time at which an upstream or downstream connection will be terminated if there are no active requests/responses. + +This timeout is disabled if set to `0`. ### How to configure @@ -124,7 +130,7 @@ timeouts: | **Config file keys** | **Environment variables** | **Type** | **Default** | | :-- | :-- | :-- | :-- | -| `timeout_idle` | `TIMEOUT_IDLE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `5m` | +| `timeout_idle` | `TIMEOUT_IDLE` | [Go Duration] string | `5m` | ### Examples @@ -146,7 +152,7 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time | **[Parameter name](/docs/k8s/reference#timeouts)** | **Type** | **Default** | | :-- | :-- | :-- | -| `timeouts.idle` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `5m` | +| `timeouts.idle` | [Go Duration] string | `5m` | ### Examples @@ -157,3 +163,5 @@ timeouts: + +[Go Duration]: https://golang.org/pkg/time/#Duration.String From d80481cc3492ffa01cbead7e8e01970e547f6e4d Mon Sep 17 00:00:00 2001 From: Kenneth Jenkins <51246568+kenjenkins@users.noreply.github.com> Date: Tue, 8 Oct 2024 12:32:21 -0700 Subject: [PATCH 2/2] prettier --- content/docs/reference/global-timeouts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/reference/global-timeouts.mdx b/content/docs/reference/global-timeouts.mdx index 827fbe73f..8771a7a30 100644 --- a/content/docs/reference/global-timeouts.mdx +++ b/content/docs/reference/global-timeouts.mdx @@ -164,4 +164,4 @@ timeouts: -[Go Duration]: https://golang.org/pkg/time/#Duration.String +[go duration]: https://golang.org/pkg/time/#Duration.String