From 65d5bf4b46be27bb6a5e1b5cd5ab48a4f48b52c9 Mon Sep 17 00:00:00 2001 From: rtribotte Date: Wed, 20 Nov 2024 16:43:55 +0100 Subject: [PATCH 1/3] fix: align backend timeout documentation, and Traefik timeouts sequence diagram --- apis/openapi/zz_generated.openapi.go | 2 +- apis/v1/httproute_types.go | 2 +- .../experimental/gateway.networking.k8s.io_httproutes.yaml | 4 ++-- .../crd/standard/gateway.networking.k8s.io_httproutes.yaml | 4 ++-- geps/gep-1742/index.md | 6 +++--- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/apis/openapi/zz_generated.openapi.go b/apis/openapi/zz_generated.openapi.go index 811e47ee48..0ae34706a1 100644 --- a/apis/openapi/zz_generated.openapi.go +++ b/apis/openapi/zz_generated.openapi.go @@ -5009,7 +5009,7 @@ func schema_sigsk8sio_gateway_api_apis_v1_HTTPRouteTimeouts(ref common.Reference }, "backendRequest": { SchemaProps: spec.SchemaProps{ - Description: "BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being sent from the gateway to when the full response has been received from the backend.\n\nSetting a timeout to the zero duration (e.g. \"0s\") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST instead interpret the zero duration as the longest possible value to which the timeout can be set.\n\nAn entire client HTTP transaction with a gateway, covered by the Request timeout, may result in more than one call from the gateway to the destination backend, for example, if automatic retries are supported.\n\nThe value of BackendRequest must be a Gateway API Duration string as defined by GEP-2257. When this field is unspecified, its behavior is implementation-specific; when specified, the value of BackendRequest must be no more than the value of the Request timeout (since the Request timeout encompasses the BackendRequest timeout).\n\nSupport: Extended", + Description: "BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being sent from the gateway to when the response headers have been received from the backend.\n\nSetting a timeout to the zero duration (e.g. \"0s\") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST instead interpret the zero duration as the longest possible value to which the timeout can be set.\n\nAn entire client HTTP transaction with a gateway, covered by the Request timeout, may result in more than one call from the gateway to the destination backend, for example, if automatic retries are supported.\n\nThe value of BackendRequest must be a Gateway API Duration string as defined by GEP-2257. When this field is unspecified, its behavior is implementation-specific; when specified, the value of BackendRequest must be no more than the value of the Request timeout (since the Request timeout encompasses the BackendRequest timeout).\n\nSupport: Extended", Type: []string{"string"}, Format: "", }, diff --git a/apis/v1/httproute_types.go b/apis/v1/httproute_types.go index 8037c4f17b..628dbfe3c7 100644 --- a/apis/v1/httproute_types.go +++ b/apis/v1/httproute_types.go @@ -347,7 +347,7 @@ type HTTPRouteTimeouts struct { // BackendRequest specifies a timeout for an individual request from the gateway // to a backend. This covers the time from when the request first starts being - // sent from the gateway to when the full response has been received from the backend. + // sent from the gateway to when the response headers have been received from the backend. // // Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout // completely. Implementations that cannot completely disable the timeout MUST diff --git a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml index e9d59f53ff..7fc5282752 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml @@ -2674,7 +2674,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the full response has been received from the backend. + sent from the gateway to when the response headers have been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST @@ -5722,7 +5722,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the full response has been received from the backend. + sent from the gateway to when the response headers have been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST diff --git a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml index 0959fb2321..96243fc9d6 100644 --- a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml @@ -2362,7 +2362,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the full response has been received from the backend. + sent from the gateway to when the response headers have been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST @@ -5077,7 +5077,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the full response has been received from the backend. + sent from the gateway to when the response headers have been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST diff --git a/geps/gep-1742/index.md b/geps/gep-1742/index.md index 2019b5e505..fa7c41c73a 100644 --- a/geps/gep-1742/index.md +++ b/geps/gep-1742/index.md @@ -270,15 +270,15 @@ sequenceDiagram Note right of P: respondingTimeouts
readTimeout C->>P: Finishes request deactivate P - P->>U: Connection Started activate U + P->>U: Connection Started Note right of U: forwardingTimeouts
dialTimeout deactivate U + activate U P->>U: Starts sending Request P->>U: Finishes request P->>U: Finishes Headers U->>P: Starts Response - activate U note right of U: forwardingTimeouts
responseHeaderTimeout U->>P: Finishes Headers deactivate U @@ -418,7 +418,7 @@ type HTTPRouteTimeouts struct { // BackendRequest specifies a timeout for an individual request from the gateway // to a backend. This covers the time from when the request first starts being - // sent from the gateway to when the full response has been received from the backend. + // sent from the gateway to when the response headers have been received from the backend. // // An entire client HTTP transaction with a gateway, covered by the Request timeout, // may result in more than one call from the gateway to the destination backend, From 1e4b826cf68cc3fd8e9d9db9976483c40e91394c Mon Sep 17 00:00:00 2001 From: rtribotte Date: Tue, 18 Feb 2025 14:43:21 +0100 Subject: [PATCH 2/3] align the sequence diagram with go doc --- apis/openapi/zz_generated.openapi.go | 2 +- apis/v1/httproute_types.go | 2 +- .../experimental/gateway.networking.k8s.io_httproutes.yaml | 4 ++-- config/crd/standard/gateway.networking.k8s.io_httproutes.yaml | 4 ++-- geps/gep-1742/index.md | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/apis/openapi/zz_generated.openapi.go b/apis/openapi/zz_generated.openapi.go index 0ae34706a1..811e47ee48 100644 --- a/apis/openapi/zz_generated.openapi.go +++ b/apis/openapi/zz_generated.openapi.go @@ -5009,7 +5009,7 @@ func schema_sigsk8sio_gateway_api_apis_v1_HTTPRouteTimeouts(ref common.Reference }, "backendRequest": { SchemaProps: spec.SchemaProps{ - Description: "BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being sent from the gateway to when the response headers have been received from the backend.\n\nSetting a timeout to the zero duration (e.g. \"0s\") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST instead interpret the zero duration as the longest possible value to which the timeout can be set.\n\nAn entire client HTTP transaction with a gateway, covered by the Request timeout, may result in more than one call from the gateway to the destination backend, for example, if automatic retries are supported.\n\nThe value of BackendRequest must be a Gateway API Duration string as defined by GEP-2257. When this field is unspecified, its behavior is implementation-specific; when specified, the value of BackendRequest must be no more than the value of the Request timeout (since the Request timeout encompasses the BackendRequest timeout).\n\nSupport: Extended", + Description: "BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being sent from the gateway to when the full response has been received from the backend.\n\nSetting a timeout to the zero duration (e.g. \"0s\") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST instead interpret the zero duration as the longest possible value to which the timeout can be set.\n\nAn entire client HTTP transaction with a gateway, covered by the Request timeout, may result in more than one call from the gateway to the destination backend, for example, if automatic retries are supported.\n\nThe value of BackendRequest must be a Gateway API Duration string as defined by GEP-2257. When this field is unspecified, its behavior is implementation-specific; when specified, the value of BackendRequest must be no more than the value of the Request timeout (since the Request timeout encompasses the BackendRequest timeout).\n\nSupport: Extended", Type: []string{"string"}, Format: "", }, diff --git a/apis/v1/httproute_types.go b/apis/v1/httproute_types.go index 628dbfe3c7..8037c4f17b 100644 --- a/apis/v1/httproute_types.go +++ b/apis/v1/httproute_types.go @@ -347,7 +347,7 @@ type HTTPRouteTimeouts struct { // BackendRequest specifies a timeout for an individual request from the gateway // to a backend. This covers the time from when the request first starts being - // sent from the gateway to when the response headers have been received from the backend. + // sent from the gateway to when the full response has been received from the backend. // // Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout // completely. Implementations that cannot completely disable the timeout MUST diff --git a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml index 7fc5282752..e9d59f53ff 100644 --- a/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/experimental/gateway.networking.k8s.io_httproutes.yaml @@ -2674,7 +2674,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the response headers have been received from the backend. + sent from the gateway to when the full response has been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST @@ -5722,7 +5722,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the response headers have been received from the backend. + sent from the gateway to when the full response has been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST diff --git a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml index 96243fc9d6..0959fb2321 100644 --- a/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml +++ b/config/crd/standard/gateway.networking.k8s.io_httproutes.yaml @@ -2362,7 +2362,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the response headers have been received from the backend. + sent from the gateway to when the full response has been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST @@ -5077,7 +5077,7 @@ spec: description: |- BackendRequest specifies a timeout for an individual request from the gateway to a backend. This covers the time from when the request first starts being - sent from the gateway to when the response headers have been received from the backend. + sent from the gateway to when the full response has been received from the backend. Setting a timeout to the zero duration (e.g. "0s") SHOULD disable the timeout completely. Implementations that cannot completely disable the timeout MUST diff --git a/geps/gep-1742/index.md b/geps/gep-1742/index.md index fa7c41c73a..58542809f7 100644 --- a/geps/gep-1742/index.md +++ b/geps/gep-1742/index.md @@ -357,9 +357,9 @@ sequenceDiagram P->>U: Finishes Headers U->>P: Starts Response U->>P: Finishes Headers - note right of P: timeouts.backendRequest end time note left of P: timeouts.request end time U->>P: Finishes Response + note right of P: timeouts.backendRequest end time note right of P: Repeat if retry P->>C: Starts Response P->>C: Finishes Headers From 7e53a74628232158d4de72762edb377f4861af86 Mon Sep 17 00:00:00 2001 From: rtribotte Date: Wed, 19 Feb 2025 09:42:44 +0100 Subject: [PATCH 3/3] review --- geps/gep-1742/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/geps/gep-1742/index.md b/geps/gep-1742/index.md index 58542809f7..fbd0a797f1 100644 --- a/geps/gep-1742/index.md +++ b/geps/gep-1742/index.md @@ -348,13 +348,13 @@ sequenceDiagram note left of P: timeouts.request start time (min) C->>P: Starts sending Request C->>P: Finishes Headers - C->>P: Finishes request + C->>P: Finishes Request note left of P: timeouts.request start time (max) P->>U: Connection Started note right of P: timeouts.backendRequest start time P->>U: Starts sending Request - P->>U: Finishes request P->>U: Finishes Headers + P->>U: Finishes Request U->>P: Starts Response U->>P: Finishes Headers note left of P: timeouts.request end time @@ -418,7 +418,7 @@ type HTTPRouteTimeouts struct { // BackendRequest specifies a timeout for an individual request from the gateway // to a backend. This covers the time from when the request first starts being - // sent from the gateway to when the response headers have been received from the backend. + // sent from the gateway to when the full response has been received from the backend. // // An entire client HTTP transaction with a gateway, covered by the Request timeout, // may result in more than one call from the gateway to the destination backend,