GEP-1742: HTTPRoute Timeouts API

geps/gep-1742.md

@@ -301,8 +301,99 @@ Could not find any HTTP specific timeouts. PRs welcomed. 😊
 
 ## API
 
-TBD.
+The above diagrams show that there are many different kinds of configurable timeouts
+supported by Gateway implementations: connect, idle, request, upstream, downstream.
+Although there may be opportunity for the specification of a common API for more of
+them in the future, this GEP will focus on the L7 timeouts in HTTPRoutes that are
+most valuable to clients.
+
+From the above analysis, it appears that most implementations are capable of supporting
+the configuration of simple downstream request timeouts on HTTPRoute rules. This is a
+relatively small addition (one new field) that would benefit many users.
+
+Because request timeouts are very much related to retry attempts, we also propose
+addressing issue: [#1731](https://github.com/kubernetes-sigs/gateway-api/issues/1731)
+by adding another field for retry conifguration in an HTTPRoute rule. This would also
+benefit many users and seems to be implementable by many (most?) Gateway implementations.
+
+### GO
+
+```go
+type HTTPRouteRule struct {
+	// Timeout for HTTP requests, disabled by default.
+	Timeout *time.Duration `json:"timeout,omitempty"`
+	// Retry policy for HTTP requests.
+	Retries *HTTPRetry `json:"retries,omitempty"`
+	// ...
+}
+
+type HTTPRetry struct {
+	// Number of retries to be allowed for a given request.
+	Attempts int32 `json:"attempts,omitempty"`
+	// Timeout per attempt for a given request, including the initial call and any retries.
+	// Default is the value of the HTTPRouteRule request Timeout.
+	PerTryTimeout *time.Duration `json:"perTryTimeout,omitempty"`
+	// Specifies one or more conditions under which retry takes place.
+	RetryOn []string `json:"retryOn,omitempty"`
+	// Flag to specify whether the retries should retry to other localities.
+	RetryRemoteLocalities *bool `json:"retryRemoteLocalities,omitempty"`
+}
+```
+
+### YAML
+
+```yaml
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: HTTPRoute
+metadata:
+  name: timeout-example
+spec:
+  ...
+  rules:
+  - backendRefs:
+    - name: some-service
+      port: 8080
+    timeout: 10s
+    retries:
+      attempts: 3
+      perTryTimeout: 2s
+      retryOn: [ "503" ]
+```
+
+### Timeout values
+
+Timeout and PerTryTimeout values are formatted as 1h/1m/1s/1ms and MUST BE >= 1ms.
+
+### Retry attempts
+
+By default, the number of retry attempts is implementation dependent. An implementation MAY
+provide external mechanisims for controlling the default retry behavior.
+
+When a request Timeout in the HTTPRouteRule or PerTryTimeout value is configured, the actual
+number of retries attempted may be reduced depending on the specified request Timeout and
+PerTryTimeout values.
+
+An implementation MUST ensure that the number of retries never exceeds the Attempts value,
+if specified.
+
+The interval between retries is implementation dependent but SHOULD be a minimum of 25ms.
+
+### RetryOn Conditions
+
+The value of an individual RetryOn condition can be either an HTTP status codes (e.g., 503)
+or some other identifier known to the implementation.
+
+An implementation MUST support any HTTP status code value for a RetryOn condition.
+
+The default conditions that will trigger retries, if no RetryOn conditions are specified,
+is implementation dependent.
+
+### RetryRemoteLocalities
 
+When an implementation supports prioritizing endpoints based on their locations, this field
+can be used to control whether or not retry attempts should only select endpoints with the
+same priority (RetryRemoteLocalities=false) or any healthy endpoint, regardless of location
+(RetryRemoteLocalities=true).
 
 ## Alternatives