docs: document Oathkeeper bounded retry controls

docs/oathkeeper/pipeline.md

@@ -19,6 +19,48 @@ This chapter explains the different pipeline handlers available to you:
 - [Error handlers](pipeline/error.md): are responsible for executing logic after, for example, authentication or authorization
   failed. Ory Oathkeeper supports different error handlers and we will add more as the project progresses.
 
+## Retry policy for external HTTP handlers
+
+The `oauth2_client_credentials` and `oauth2_introspection` authenticators, the `remote` and `remote_json` authorizers, and the
+`hydrator` mutator make outbound HTTP requests and share the same retry policy. Configure the policy under `config.retry` for the
+authenticators and authorizers. For the hydrator, configure it under `config.api.retry`.
+
+The bounded retry policy is opt-in. Set both `deadline` and `max_backoff_delay` to enable it; setting only one is invalid. The
+optional corrected-policy fields are also invalid unless both required fields are present.
+
+| Field                   | Description                                                                                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `deadline`              | Maximum duration of the complete operation, including all attempts, backoff, and the final response body. Must be greater than zero.                 |
+| `max_backoff_delay`     | Maximum delay between attempts. Must be greater than zero.                                                                                           |
+| `max_attempts`          | Total attempts, including the initial request. Defaults to `5` and must be between `1` and `5`.                                                      |
+| `initial_backoff_delay` | Initial exponential backoff delay. Defaults to the smaller of `1s` and `max_backoff_delay`, and can't exceed `max_backoff_delay`.                    |
+| `per_attempt_timeout`   | Optional timeout for each attempt, including its response body. Without it, an individual attempt can use the entire remaining operation `deadline`. |
+
+Retries stop when either `max_attempts` is reached or the operation `deadline` expires. `429 Too Many Requests` responses aren't
+retried. Their status and `Retry-After` header remain available to the pipeline handler, which determines how to represent the
+failure to Oathkeeper's caller.
+
+```yaml
+retry:
+  deadline: 2s
+  max_backoff_delay: 100ms
+  max_attempts: 3
+  initial_backoff_delay: 50ms
+  per_attempt_timeout: 500ms
+```
+
+The legacy `max_delay` and `give_up_after` fields remain accepted for compatibility when the bounded policy isn't enabled. They
+are deprecated, their historical behavior and defaults differ by handler, and they are ignored when `deadline` and
+`max_backoff_delay` are set.
+
+| Handler                     | Legacy `max_delay` | Legacy `give_up_after` |
+| --------------------------- | ------------------ | ---------------------- |
+| `oauth2_client_credentials` | `1s`               | `2s`                   |
+| `oauth2_introspection`      | `500ms`            | `1s`                   |
+| `remote`                    | `500ms`            | `1s`                   |
+| `remote_json`               | `500ms`            | `1s`                   |
+| `hydrator`                  | `100ms`            | `1s`                   |
+
 ## Templating
 
 Some handlers such as the [ID Token Mutator](pipeline/mutator.md#id_token) support templating using

docs/oathkeeper/pipeline/authn.md

@@ -491,9 +491,8 @@ This authenticator will use the username from the HTTP Basic Authorization heade
 ### `oauth2_client_credentials` configuration
 
 - `token_url` (string, required) - The OAuth 2.0 Token Endpoint that will be used to validate the client credentials.
-- `retry` (object, optional) - Configures timeout and delay settings for the request against the token endpoint
-  - `give_up_after` (string) timeout
-  - `max_delay` (string) time to wait between retries
+- `retry` (object, optional) - Configures the [shared retry policy](../pipeline.md#retry-policy-for-external-http-handlers) for
+  requests to the token endpoint.
 - `cache` (object, optional) - Enables caching of requested tokens
   - `enabled` (bool, optional) - Enable the cache, will use exp time of token to determine when to evict from cache. Defaults to
     false.
@@ -512,6 +511,12 @@ authenticators:
 
     config:
       token_url: https://my-website.com/oauth2/token
+      retry:
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ```yaml
@@ -523,6 +528,12 @@ authenticators:
   - handler: oauth2_client_credentials
     config:
       token_url: https://my-website.com/oauth2/token
+      retry:
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ### `oauth2_client_credentials` access rule example
@@ -619,9 +630,8 @@ Token Introspection to check if the token is valid and if the token was granted
   - `cookie` (string, required, one of) - The cookie (case sensitive) that must contain a Bearer token for request authentication.
     It can't be set along with `header` or `query_parameter`
 - `introspection_request_headers` (object, optional) - Additional headers to add to the introspection request.
-- `retry` (object, optional) - Configure the retry policy
-  - `max_delay` (string, optional, default to 500ms) - Maximum delay to wait before retrying the request
-  - `give_up_after` (string, optional, default to 1s) - Maximum delay allowed for retries
+- `retry` (object, optional) - Configures the [shared retry policy](../pipeline.md#retry-policy-for-external-http-handlers) for
+  requests to the introspection endpoint.
 - `cache` (object, optional) - Enables caching of incoming tokens
   - `enabled` (bool, optional) - Enable the cache, will use exp time of token to determine when to evict from cache. Defaults to
     false.
@@ -665,8 +675,11 @@ authenticators:
       introspection_request_headers:
         x-forwarded-proto: https
       retry:
-        max_delay: 300ms
-        give_up_after: 2s
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
       cache:
         enabled: true
         ttl: 60s
@@ -706,8 +719,11 @@ authenticators:
         x-forwarded-proto: https
         x-foo: bar
       retry:
-        max_delay: 300ms
-        give_up_after: 2s
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ### `oauth2_introspection` access rule example

docs/oathkeeper/pipeline/authz.md

@@ -278,11 +278,8 @@ with the original body request as body. If the endpoint returns a "200 OK" respo
   [Session](../pipeline.md#session) for more details.
 - `forward_response_headers_to_upstream` (slice of strings, optional) - The HTTP headers that will be allowed from remote
   authorizer responses. If returned, headers on this list will be forward to upstream services.
-- `retry` (object, optional) - Configures timeout and delay settings for the request against the token endpoint
-  - `give_up_after` (string) max delay duration of retry. The value will be parsed by the Go
-    [duration parser](https://pkg.go.dev/time#ParseDuration).
-  - `max_delay` (string) time to wait between retries and max service response time. The value will be parsed by the Go
-    [duration parser](https://pkg.go.dev/time#ParseDuration).
+- `retry` (object, optional) - Configures the [shared retry policy](../pipeline.md#retry-policy-for-external-http-handlers) for
+  requests to the remote authorizer.
 
 #### `remote` example
 
@@ -297,6 +294,12 @@ authorizers:
       remote: http://my-remote-authorizer/authorize
       headers:
         X-Subject: "{{ print .Subject }}"
+      retry:
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ```yaml
@@ -310,6 +313,12 @@ authorizers:
       remote: http://my-remote-authorizer/authorize
       headers:
         X-Subject: "{{ print .Subject }}"
+      retry:
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ### `remote` access rule example
@@ -369,11 +378,8 @@ response code, the access is denied.
   [Session](../pipeline.md#session) for more details.
 - `forward_response_headers_to_upstream` (slice of strings, optional) - The HTTP headers that will be allowed from remote
   authorizer responses. If returned, headers on this list will be forward to upstream services.
-- `retry` (object, optional) - Configures timeout and delay settings for the request against the token endpoint
-  - `give_up_after` (string) max delay duration of retry. The value will be parsed by the Go
-    [duration parser](https://pkg.go.dev/time#ParseDuration).
-  - `max_delay` (string) time to wait between retries and max service response time. The value will be parsed by the Go
-    [duration parser](https://pkg.go.dev/time#ParseDuration).
+- `retry` (object, optional) - Configures the [shared retry policy](../pipeline.md#retry-policy-for-external-http-handlers) for
+  requests to the remote authorizer.
 
 #### `remote_json` example
 
@@ -393,6 +399,12 @@ authorizers:
           "subject": "{{ print .Subject }}",
           "resource": "{{ printIndex .MatchContext.RegexpCaptureGroups 0 }}"
         }
+      retry:
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ```yaml
@@ -411,6 +423,12 @@ authorizers:
           "subject": "{{ print .Subject }}",
           "resource": "{{ printIndex .MatchContext.RegexpCaptureGroups 0 }}"
         }
+      retry:
+        deadline: 2s
+        max_backoff_delay: 100ms
+        max_attempts: 3
+        initial_backoff_delay: 50ms
+        per_attempt_timeout: 500ms
 ```
 
 ### `remote_json` access rule example

docs/oathkeeper/pipeline/mutator.md

@@ -476,7 +476,8 @@ Because the cache key is quite complex, the caching handler has a higher chance
 
 - `api.url` (string - required) - The API URL.
 - `api.auth.basic.*` (optional) - Enables HTTP Basic Authorization.
-- `api.auth.retry.*` (optional) - Configures the retry logic.
+- `api.retry` (object, optional) - Configures the [shared retry policy](../pipeline.md#retry-policy-for-external-http-handlers)
+  for requests to the hydrator API.
 - `cache.ttl` (optional) - Configures how long to cache hydrate requests
 
 ```yaml
@@ -493,8 +494,11 @@ mutators:
             username: someUserName
             password: somePassword
         retry:
-          give_up_after: 2s
-          max_delay: 100ms
+          deadline: 2s
+          max_backoff_delay: 100ms
+          max_attempts: 3
+          initial_backoff_delay: 50ms
+          per_attempt_timeout: 500ms
       cache:
         ttl: 60s
 ```
@@ -514,8 +518,11 @@ mutators:
             username: someUserName
             password: somePassword
         retry:
-          give_up_after: 2s
-          max_delay: 100ms
+          deadline: 2s
+          max_backoff_delay: 100ms
+          max_attempts: 3
+          initial_backoff_delay: 50ms
+          per_attempt_timeout: 500ms
       cache:
         ttl: 60s
 ```