[DOCU-2274] Upstream timeout plugin

.github/styles/kong/dictionary.txt

@@ -8,12 +8,14 @@ autogenerate
 autogenerated
 autogenerates
 aws
+backtrace
 Bintray
 Bitnami
 blockquote
 blockquotes
 body_filter
 boolean
+cleartext
 client_payload
 client_status
 CloudFormation
@@ -76,6 +78,7 @@ inso
 instrumentations
 io
 ip
+ips
 iptables
 Istio
 jetstack
@@ -86,6 +89,7 @@ jwk
 jwks
 jwt
 kafka
+keepalive
 Keycloak
 keyspace
 kiali
@@ -175,6 +179,7 @@ requery
 Resty
 rockspec
 routable
+ruleset
 runtime
 runtimes
 deduplication
@@ -222,6 +227,7 @@ unary
 uncheck
 uncomment
 uncommenting
+unencrypted
 Unicode
 unix
 unnormalized

app/_data/tables/plugin_index.yml

@@ -316,6 +316,14 @@
       notes: --
       url: /hub/kong-inc/route-by-header
 
+    - name: Upstream Timeout
+      free: No
+      plus: No
+      Enterprise: Yes
+      network_config_opts: All
+      notes: --
+      url: /hub/kong-inc/upstream-timeout
+
     - name: WebSocket Size Limit
       free: No
       plus: Yes

app/_hub/kong-inc/upstream-timeout/_index.md

@@ -0,0 +1,57 @@
+---
+name: Upstream Timeout
+publisher: Kong Inc.
+categories:
+  - traffic-control
+type: plugin
+
+desc: Set timeouts on routes and override service-level timeouts
+description: |
+  Use the Upstream Timeout plugin to configure route-specific timeouts.
+  This plugin overrides any service-level timeout settings.
+
+kong_version_compatibility:
+  enterprise_edition:
+    compatible: true
+
+cloud: true
+enterprise: true
+plus: false
+
+params:
+  name: upstream-timeout
+  service_id: false
+  consumer_id: false
+  route_id: true
+  protocols:
+    - http
+    - https
+  dbless_compatible: yes
+  config:
+    - name: connect_timeout
+      required: false
+      default: null
+      value_in_examples: 4000
+      datatype: integer
+      description: |
+        The timeout, in milliseconds, for establishing a connection to the upstream server.
+        Overrides the service object [`connect_timeout`](/gateway/latest/how-kong-works/routing-traffic/#proxying-and-upstream-timeouts) setting, if the setting exists.
+    - name: send_timeout
+      required: false
+      default: null
+      value_in_examples: 5000
+      datatype: integer
+      description: |
+        The timeout, in milliseconds, between two
+        successive write operations when sending a request to the upstream server.
+        Overrides the service object [`write_timeout`](/gateway/latest/how-kong-works/routing-traffic/#proxying-and-upstream-timeouts) setting, if the setting exists.
+    - name: read_timeout
+      required: false
+      default: null
+      value_in_examples: 5000
+      datatype: integer
+      description: |
+        The timeout, in milliseconds, between two
+        successive read operations when receiving a response from the upstream server.
+        Overrides the service object [`read_timeout`](/gateway/latest/how-kong-works/routing-traffic/#proxying-and-upstream-timeouts) setting, if the setting exists.
+---

app/_hub/kong-inc/upstream-timeout/versions.yml

@@ -0,0 +1,12 @@
+strategy: gateway
+delegate_releases: true
+
+overrides:
+  2.8.x: 0.1.1
+  2.7.x: 0.1.1
+  2.6.x: 0.1.1
+  2.5.x: 0.1.1
+  2.4.x: 0.1.1
+  2.3.x: 0.1.1
+  2.2.x: 0.1.1
+  2.1.x: 0.1.0

src/gateway/how-kong-works/routing-traffic.md

@@ -908,15 +908,15 @@ upstream services. Below, we detail what happens internally between the time
 {{site.base_gateway}} *matches* an HTTP request with a registered route, and the actual
 *forwarding* of the request.
 
-### 1. Load balancing
+### Load balancing
 
 {{site.base_gateway}} implements load balancing capabilities to distribute proxied
 requests across a pool of instances of an upstream service.
 
 You can find more information about configuring load balancing by consulting
 the [Load Balancing Reference][load-balancing-reference].
 
-### 2. Plugins execution
+### Plugins execution
 
 {{site.base_gateway}} is extensible via "plugins" that hook themselves in the request/response
 lifecycle of the proxied requests. Plugins can perform a variety of operations
@@ -934,7 +934,7 @@ rules of [plugins association][plugin-association-rules] apply.
 These configured plugins will run their `access` phase, which you can find more
 information about in the [Plugin development guide][plugin-development-guide].
 
-### 3. Proxying and upstream timeouts
+### Proxying and upstream timeouts
 
 Once {{site.base_gateway}} has executed all the necessary logic (including plugins), it is ready
 to forward the request to your upstream service. This is done via Nginx's
@@ -953,6 +953,7 @@ properties of a service:
 
 {{site.base_gateway}} will send the request over HTTP/1.1, and set the following headers:
 
+<!-- vale off -->
 - `Host: <your_upstream_host>`, as previously described in this document.
 - `Connection: keep-alive`, to allow for reusing the upstream connections.
 - `X-Real-IP: <remote_addr>`, where `$remote_addr` is the variable bearing
@@ -985,6 +986,7 @@ properties of a service:
   if provided. Otherwise, the value of the `$request_uri` variable (with
   the query string stripped) provided by [ngx_http_core_module][ngx-server-port-variable]
   will be used.
+<!-- vale on-->
 
   {:.note}
   > **Note**: {{site.base_gateway}} returns `"/"` for an empty path, but it doesn't do any other
@@ -1002,7 +1004,7 @@ client and your upstream services:
 More information on this topic is covered in the
 [Proxy WebSocket traffic][proxy-websocket] section.
 
-### 4. Errors and retries
+### Errors and retries
 
 Whenever an error occurs during proxying, {{site.base_gateway}} uses the underlying
 Nginx [retries][ngx-http-proxy-retries] mechanism to pass the request on to
@@ -1023,7 +1025,7 @@ directly configurable through {{site.base_gateway}}, but can be added using a cu
 configuration. See the [configuration reference][configuration-reference] for
 more details.
 
-### 5. Response
+### Response
 
 {{site.base_gateway}} receives the response from the upstream service and sends it back to the
 downstream client in a streaming fashion. At this point, {{site.base_gateway}} executes
@@ -1115,7 +1117,7 @@ associating the uploaded certificate to it.
 
 Note that one of the SNI names defined in `snis` above contains a wildcard
 (`*.tls-example.com`). An SNI may contain a single wildcard in the leftmost (prefix) or
-rightmost (suffix) postion. This can be useful when maintaining multiple subdomains. A
+rightmost (suffix) position. This can be useful when maintaining multiple subdomains. A
 single `sni` configured with a wildcard name can be used to match multiple
 subdomains, instead of creating an SNI for each.
 

src/gateway/plugin-development/custom-logic.md

@@ -34,18 +34,18 @@ of {{site.base_gateway}}'s execution life-cycle:
 
 | Function name       | Phase             | Request Protocol        | Description
 |---------------------|-------------------|-------------------------|------------
-| `init_worker`       | [init_worker]     | *                       | Executed upon every Nginx worker process's startup.
-| `certificate`       | [ssl_certificate] | https, grpcs, wss       | Executed during the SSL certificate serving phase of the SSL handshake.
-| `rewrite`           | [rewrite]         | *                       | Executed for every request upon its reception from a client as a rewrite phase handler. <br> In this phase, neither the `Service` nor the `Consumer` have been identified, hence this handler will only be executed if the plugin was configured as a global plugin.
-| `access`            | [access]          | http(s), grpc(s), ws(s) | Executed for every request from a client and before it is being proxied to the upstream service.
-| `ws_handshake`      | [access]          | ws(s)                   | Executed for every request to a WebSocket service just before completing the WebSocket handshake.
-| `response`          | [access]          | http(s), grpc(s)        | Replaces both `header_filter()` and `body_filter()`. Executed after the whole response has been received from the upstream service, but before sending any part of it to the client.
-| `header_filter`     | [header_filter]   | http(s), grpc(s)        | Executed when all response headers bytes have been received from the upstream service.
-| `ws_client_frame`   | [content]         | ws(s)                   | Executed for each WebSocket message received from the client.
-| `ws_upstream_frame` | [content]         | ws(s)                   | Executed for each WebSocket message received from the upstream service.
-| `body_filter`       | [body_filter]     | http(s), grpc(s)        | Executed for each chunk of the response body received from the upstream service. Since the response is streamed back to the client, it can exceed the buffer size and be streamed chunk by chunk. This function can be called multiple times if the response is large. See the [lua-nginx-module] documentation for more details.
-| `log`               | [log]             | http(s), grpc(s)        | Executed when the last response byte has been sent to the client.
-| `ws_close`          | [log]             | ws(s)                   | Executed after the WebSocket connection has been terminated.
+| `init_worker`       | [init_worker]     | *                        | Executed upon every Nginx worker process's startup.
+| `certificate`       | [ssl_certificate] | `https`, `grpcs`, `wss`  | Executed during the SSL certificate serving phase of the SSL handshake.
+| `rewrite`           | [rewrite]         | *                        | Executed for every request upon its reception from a client as a rewrite phase handler. <br> In this phase, neither the `Service` nor the `Consumer` have been identified, hence this handler will only be executed if the plugin was configured as a global plugin.
+| `access`            | [access]          | `http(s)`, `grpc(s)`, `ws(s)` | Executed for every request from a client and before it is being proxied to the upstream service.
+| `ws_handshake`      | [access]          | `ws(s)`                  | Executed for every request to a WebSocket service just before completing the WebSocket handshake.
+| `response`          | [access]          | `http(s)`, `grpc(s)`     | Replaces both `header_filter()` and `body_filter()`. Executed after the whole response has been received from the upstream service, but before sending any part of it to the client.
+| `header_filter`     | [header_filter]   | `http(s)`, `grpc(s)`     | Executed when all response headers bytes have been received from the upstream service.
+| `ws_client_frame`   | [content]         | `ws(s)`                  | Executed for each WebSocket message received from the client.
+| `ws_upstream_frame` | [content]         | `ws(s)`                  | Executed for each WebSocket message received from the upstream service.
+| `body_filter`       | [body_filter]     | `http(s)`, `grpc(s)`     | Executed for each chunk of the response body received from the upstream service. Since the response is streamed back to the client, it can exceed the buffer size and be streamed chunk by chunk. This function can be called multiple times if the response is large. See the [lua-nginx-module] documentation for more details.
+| `log`               | [log]             | `http(s)`, `grpc(s)`     | Executed when the last response byte has been sent to the client.
+| `ws_close`          | [log]             | `ws(s)`                  | Executed after the WebSocket connection has been terminated.
 
 {:.note}
 > **Note:** If a module implements the `response` function, {{site.base_gateway}} will automatically activate the "buffered proxy" mode, as if the [`kong.service.request.enable_buffering()` function][enable_buffering] had been called. Because of a current Nginx limitation, this doesn't work for HTTP/2 or gRPC upstreams.
@@ -72,20 +72,6 @@ packets with the same origin and destination host and port as a single
 connection.  After a configurable time without any packet, the connection is
 considered closed and the `log` function is executed.
 
-[HTTP Module]: https://github.com/openresty/lua-nginx-module
-[Stream Module]: https://github.com/openresty/stream-lua-nginx-module
-[init_worker]: https://github.com/openresty/lua-nginx-module#init_worker_by_lua_by_lua_block
-[ssl_certificate]: https://github.com/openresty/lua-nginx-module#ssl_certificate_by_lua_block
-[rewrite]: https://github.com/openresty/lua-nginx-module#rewrite_by_lua_block
-[access]: https://github.com/openresty/lua-nginx-module#access_by_lua_block
-[header_filter]: https://github.com/openresty/lua-nginx-module#header_filter_by_lua_block
-[body_filter]: https://github.com/openresty/lua-nginx-module#body_filter_by_lua_block
-[log]: https://github.com/openresty/lua-nginx-module#log_by_lua_block
-[preread]: https://github.com/openresty/stream-lua-nginx-module#preread_by_lua_block
-[enable_buffering]: /gateway/{{page.kong_version}}/plugin-development/pdk/kong.service.request/#kongservicerequestenable_buffering
-[content]: https://github.com/openresty/lua-nginx-module#content_by_lua_block
-
-
 ## handler.lua specifications
 
 {{site.base_gateway}} processes requests in **phases**. A plugin is a piece of code that gets
@@ -200,7 +186,7 @@ end
 ```
 
 The plugin's logic doesn't need to be all defined inside the `handler.lua` file.
-It can be be split into several Lua files (also called *modules*).
+It can be split into several Lua files (also called *modules*).
 The `handler.lua` module can use `require` to include other modules in your plugin.
 
 For example, the following plugin splits the functionality into three files.
@@ -400,6 +386,8 @@ open-source package.
 
 The current order of execution for the bundled plugins is:
 
+<!-- vale off -->
+
 Plugin                      | Priority
 ----------------------------|----------
 pre-function                | 1000000
@@ -425,6 +413,7 @@ request-transformer         | 801
 response-transformer        | 800
 aws-lambda                  | 750
 azure-functions             | 749
+upstream-timeout            | 400
 opentelemetry               | 14
 prometheus                  | 13
 http-log                    | 12
@@ -440,13 +429,17 @@ request-termination         | 2
 correlation-id <span class="badge oss"></span> | 1
 post-function               | -1000
 
+<!-- vale on -->
+
 {% endnavtab %}
 {% navtab Enterprise %}
 The following list includes all plugins bundled with a {{site.base_gateway}}
 Enterprise subscription.
 
 The current order of execution for the bundled plugins is:
 
+<!-- vale off -->
+
 Plugin                      | Priority
 ----------------------------|----------
 pre-function                | 1000000
@@ -496,6 +489,7 @@ route-transformer-advanced  | 780
 kafka-upstream              | 751
 aws-lambda                  | 750
 azure-functions             | 749
+upstream-timeout            | 400
 proxy-cache-advanced        | 100
 proxy-cache                 | 100
 graphql-proxy-cache-advanced | 99
@@ -520,5 +514,20 @@ post-function               | -1000
 
 {% endnavtab %}
 {% endnavtabs %}
+
 [lua-nginx-module]: https://github.com/openresty/lua-nginx-module
 [pdk]: /gateway/{{page.kong_version}}/plugin-development/pdk
+[HTTP Module]: https://github.com/openresty/lua-nginx-module
+[Stream Module]: https://github.com/openresty/stream-lua-nginx-module
+[init_worker]: https://github.com/openresty/lua-nginx-module#init_worker_by_lua_by_lua_block
+[ssl_certificate]: https://github.com/openresty/lua-nginx-module#ssl_certificate_by_lua_block
+[rewrite]: https://github.com/openresty/lua-nginx-module#rewrite_by_lua_block
+[access]: https://github.com/openresty/lua-nginx-module#access_by_lua_block
+[header_filter]: https://github.com/openresty/lua-nginx-module#header_filter_by_lua_block
+[body_filter]: https://github.com/openresty/lua-nginx-module#body_filter_by_lua_block
+[log]: https://github.com/openresty/lua-nginx-module#log_by_lua_block
+[preread]: https://github.com/openresty/stream-lua-nginx-module#preread_by_lua_block
+[enable_buffering]: /gateway/{{page.kong_version}}/plugin-development/pdk/kong.service.request/#kongservicerequestenable_buffering
+[content]: https://github.com/openresty/lua-nginx-module#content_by_lua_block
+
+<!-- vale on -->