DeliverySpec.RetryAfterMax field

Flag name: delivery-retryafter

Stage: Alpha, disabled by default

Tracking issue: #5811

Persona: Developer

When using the delivery spec to configure event delivery parameters, you can use the retryAfterMax field to specify how HTTP Retry-After headers are handled when calculating backoff times for retrying 429 and 503 responses. You can specify a delivery spec for Channels, Subscriptions, Brokers, Triggers, and any other resource spec that accepts the delivery field.

The retryAfterMax field only takes effect if you configure the delivery spec to perform retries, and only pertains to retry attempts on 429 and 503 response codes. The field provides an override to prevent large Retry-After durations from impacting throughput, and must be specified using the ISO 8601 format. The largest of the normal backoff duration and the Retry-After header value will be used for the subsequent retry attempt. Specifying a “zero” value of PT0S effectively disables Retry-After support.

Prior to this experimental feature, Knative Eventing implementations have not supported Retry-After headers, and this is an attempt to provide a path for standardizing that support. To begin, the feature is opt-in, but the final state will be opt-out as follows:

Feature StageFeature FlagretryAfterMax Field AbsentretryAfterMax Field Present
Alpha / BetaDisabledAccepted by Webhook Validation & Retry-After headers NOT enforcedRejected by WebHook Validation
Alpha / BetaEnabledAccepted by Webhook Validation & Retry-After headers NOT enforcedAccepted by Webhook Validation & Retry-After headers enforced if max override > 0
Stable / GAn/aRetry-After headers enforced without max overrideRetry-After headers enforced if max override > 0

The following example shows a Subscription that retries sending an event three times, and respects Retry-After headers while imposing a maximum backoff of 120 seconds:

  1. apiVersion: messaging.knative.dev/v1
  2. kind: Subscription
  3. metadata:
  4.   name: example-subscription
  5.   namespace: example-namespace
  6. spec:
  7.   subscriber:
  8.     ref:
  9.       apiVersion: serving.knative.dev/v1
  10.       kind: Service
  11.       name: example-sink
  12.   delivery:
  13.     backoffDelay: PT2S
  14.     backoffPolicy: linear
  15.     retry: 3
  16.     retryAfterMax: PT120S

Note

While the experimental feature flag enforces all DeliverySpec usage of the retryAfterMax field through Webhook validation, it does not guarantee all implementations, such as Channels or Sources, actually implement support for the field. The shared HTTPMessageSender.SendWithRetries() logic has been enhanced to support this feature, and all implementations using it to perform retries will automatically benefit. Sandbox implementations not based on this shared library, for example RabbitMQ or Google Pub/Sub, would require additional development effort to respect the retryAfterMax field.