[Experimental] DeliverySpec RetryAfter
- Dominant language
- Go
- Stars
- 1.6k
- Forks
- 631
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 6
Description
**Description**
The **Retry-After** header is a standard part of the HTTP spec which can be returned with **429** and **503** responses in order to specify a duration, or timestamp, which subsequent retries should wait before attempting to resend. It provides downstream event recipients with a mechanism to provide back-pressure when requests are arriving too frequently. The event retry mechanism in Knative eventing currently does not respect the **Retry-After** header. The intent of this new experimental-feature is to expose the _ability_ for users to _opt-in_ to respecting the **Retry-After** header.
**Design Overview**
Following the pattern established in the experimental-features process, and closely mirroring the implementation in the similar [Delivery Timeout experimental-feature](https://github.com/knative/eventing/issues/5148), the plan is to enhance the `DeliverySpec` to include a new _optional_ `retryAfter` component. Use of this new component will be gated by the `delivery-retryafter` experimental feature flag in the `config-features` ConfigMap and enforced via WebHook validation.
Example DeliverySpec with new `retryAfter` component...
```yaml
delivery:
backoffDelay: PT0.5S
backoffPolicy: exponential
retry: 3
retryAfter:
enabled: true
maxDuration: "PT30S"
```
The new `retryAfter` component will only take effect if the `retry` value is specified and is at least **1**. The _optional_ `maxDuration` field provides an override to prevent excessive backoff durations as might be desirable in certain use cases.
**Exit Criteria**
`DeliverySpec` allows optional configuration of retry behavior for **429** and **503** **Retry-After** headers.
**Experimental Feature Flag Name**
`delivery-retryafter`
**Experimental Feature Stages**
The following is the proposed plan for moving through the stages of the experimental feature process...
- Alpha: _(Target 1.1 Release)_
- [x] Initial Implementation, Unit Tests, e2e Test #5813
- [x] User Documentation [DeliverySpec.RetryAfter Experimental-Feature docs#4361](https://github.com/knative/docs/pull/4361)
- [X] Refactor Flaky Unit Tests #5943, #5981
- [X] Fix Channel Backed MT Broker To Proxy Response Headers #5946
- [X] Adjust KafkaChannel CRD to allow experimental-features in delivery spec #1025.
- Beta: _(minimum of 1 release after Alpha)_
- [ ] Changes / Fixes based on Alpha ?
- [ ] Documentation Enhancements ?
- [ ] Conformance Tests ?
- Stable: _(minimum of 2 releases after Beta)_
- [ ] Remove `delivery-retryafter` feature flag.
- [ ] Remove eventing WebHook validation enforcement.
- [ ] Add requirements to support `DeliverySpec.RetryAfter` to knative/specs repo
**Affected WG**
- Eventing WG
- Eventing-Kafka WG _(previously Event-Delivery)_
**Additional Context**
- Resources
[Experimental Features Process](https://github.com/knative/eventing/blob/main/docs/experimental-features.md)
[Retry-After HTTP 1.1 RFC](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3)
[Retry-After Mozilla Docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After)
[CloudEvent Webhook Spec](https://github.com/cloudevents/spec/blob/v1.0.1/http-webhook.md)
- History
An initial attempt at supporting Retry-After headers was made in March 2021 and is mostly documented in [Knative Eventing Discussion #5011](https://github.com/knative/eventing/discussions/5011). This second attempt has been briefly discussed at the [Eventing WG](https://docs.google.com/document/d/1Xha-FeunojN49OJN7W0WBnPMcRtp1ycYpbkiir6XsE0/edit#heading=h.971zl4s8d35p) in the past few weeks.
Contributor guide
Research direction
Start with docs/experimental-features.md and compare the Delivery Timeout process in issue #5148. Then trace the DeliverySpec, the delivery-retryafter entry in the config-features ConfigMap, and WebHook validation; the remaining work is defined by the unchecked beta and stable criteria, including conformance support and eventual feature-flag removal.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100