Skip to content

Commit 63cb2c1

Browse files
revise global timeouts explanation (#1647)
revise global timeouts explanation (#1643) 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. Co-authored-by: Kenneth Jenkins <[email protected]>
1 parent ce33151 commit 63cb2c1

File tree

1 file changed

+17
-9
lines changed

1 file changed

+17
-9
lines changed

content/docs/reference/global-timeouts.mdx

+17-9
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,9 @@ You can set also set [route-level timeouts](/docs/reference/routes/timeouts).
2525

2626
## Read Timeout
2727

28-
**Read Timeout** sets the maximum amount of time for the client to receive an entire HTTP request stream.
28+
**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.
29+
30+
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.)
2931

3032
### How to configure
3133

@@ -34,7 +36,7 @@ You can set also set [route-level timeouts](/docs/reference/routes/timeouts).
3436

3537
| **Config file keys** | **Environment variables** | **Type** | **Default** |
3638
| :-- | :-- | :-- | :-- |
37-
| `timeout_read` | `TIMEOUT_READ` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `30s` |
39+
| `timeout_read` | `TIMEOUT_READ` | [Go Duration] string | `30s` |
3840

3941
### Examples
4042

@@ -56,7 +58,7 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time
5658

5759
| **[Parameter name](/docs/k8s/reference#timeouts)** | **Type** | **Defaults** |
5860
| :-- | :-- | :-- |
59-
| `timeouts.read` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `30s` |
61+
| `timeouts.read` | [Go Duration] string | `30s` |
6062

6163
### Examples
6264

@@ -70,7 +72,9 @@ timeouts:
7072
7173
## Write Timeout
7274
73-
**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.
75+
**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.
76+
77+
This timeout is disabled if set to `0`.
7478

7579
### How to configure
7680

@@ -79,7 +83,7 @@ timeouts:
7983

8084
| **Config file keys** | **Environment variables** | **Type** | **Default** |
8185
| :-- | :-- | :-- | :-- |
82-
| `timeout_write` | `TIMEOUT_WRITE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `0` |
86+
| `timeout_write` | `TIMEOUT_WRITE` | [Go Duration] string | `0` (no timeout) |
8387

8488
### Examples
8589

@@ -101,7 +105,7 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time
101105

102106
| **[Parameter name](/docs/k8s/reference#timeouts)** | **Type** | **Default** |
103107
| :-- | :-- | :-- |
104-
| `timeouts.write` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `0` |
108+
| `timeouts.write` | [Go Duration] string | `0` (no timeout) |
105109

106110
### Examples
107111

@@ -115,7 +119,9 @@ timeouts:
115119

116120
## Idle Timeout
117121

118-
**Idle Timeout** sets the time at which an upstream or downstream connection will be terminated if there are no active streams.
122+
**Idle Timeout** sets the time at which an upstream or downstream connection will be terminated if there are no active requests/responses.
123+
124+
This timeout is disabled if set to `0`.
119125

120126
### How to configure
121127

@@ -124,7 +130,7 @@ timeouts:
124130

125131
| **Config file keys** | **Environment variables** | **Type** | **Default** |
126132
| :-- | :-- | :-- | :-- |
127-
| `timeout_idle` | `TIMEOUT_IDLE` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `5m` |
133+
| `timeout_idle` | `TIMEOUT_IDLE` | [Go Duration] string | `5m` |
128134

129135
### Examples
130136

@@ -146,7 +152,7 @@ Set **Global Timeouts** in the Console: ![Global timeouts in Console](./img/time
146152

147153
| **[Parameter name](/docs/k8s/reference#timeouts)** | **Type** | **Default** |
148154
| :-- | :-- | :-- |
149-
| `timeouts.idle` | `string` ([Go Duration](https://golang.org/pkg/time/#Duration.String) formatting) | `5m` |
155+
| `timeouts.idle` | [Go Duration] string | `5m` |
150156

151157
### Examples
152158

@@ -157,3 +163,5 @@ timeouts:
157163

158164
</TabItem>
159165
</Tabs>
166+
167+
[go duration]: https://golang.org/pkg/time/#Duration.String

0 commit comments

Comments
 (0)