knative / knative/docs

Link to Eventing Data Plane Contract/SPEC

Open
#4,943 7 comments 0 reactions 0 assignees View on GitHub
kind/eventing kind/functions priority/awaiting-more-evidence triage/accepted
Dominant language
HTML
Stars
5.1k
Forks
1.3k
PR merge metrics
No merged PRs in 30d

Description

**Describe the change you'd like to see**
Speaking to many function authors (i.e. Knative Service with Eventing), especially newcomers, most of them are not aware of the underlying data plane contract, e.g. used by `brokers`. This can lead to issues where retry and error behavior by a function (`Kservice`) is incorrectly assumed/handled.

Examples [`SPEC`](https://github.com/knative/specs/blob/main/specs/eventing/data-plane.md#event-acknowledgement-and-delivery-retry) says to retry on `404` which is typically not what users expect (`404`s are usually not retriable and the SPEC bends the rules here IMHO a bit for a particular use case).

**Proposal:** add a section to the docs describing the impact of the data plane contract to Knative function authors so at least they are aware of the behavior. The only issue is that not all implementations might strictly follow the SPEC, so this should be considered best effort/best practice for now until we are sure that all implementations strictly follow the SPEC.

**Additional context**
Add any other context or screenshots about the feature request here.

Contributor guide

Open the contributing guide

Research direction

Start by reading the linked Eventing Data Plane SPEC, especially its event acknowledgement and delivery retry section, then locate the function-author documentation area where this guidance belongs. Add a section explaining the contract's retry and error behavior, including that implementations may vary, and verify that the result clearly communicates best-practice expectations to newcomers.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.