[FEATURE] Kafka add `transactional` and `isolationLevel` to operation bindings
- Dominant language
- No language data
- Stars
- 79
- Forks
- 81
- PR merge metrics
- No merged PRs in 30d
Description
### Why do we need this improvement?
Kafka's transactional model has two sides that need to be expressed in an
AsyncAPI document:
- A producer that writes transactionally should say so explicitly.
- A consumer reading from a transactional topic should declare the isolation
level it uses, because the default (`read_uncommitted`) exposes it to
messages from aborted transactions.
There is currently no way to express either of these in the binding spec.
### How will this change help?
It will help to properly configure implementing projects with the proper transactionality and isolation level
### Screenshots
_No response_
### How could it be implemented/designed?
## Proposed changes
Both fields are added to the **Operation Binding Object**.
| Field Name | Type | Description | Applicability [default] | Constraints |
|---|---|---|---|---|
| `transactional` | boolean | Marks this producer as transactional. When `true`, the Kafka client MUST be configured with a `transactional.id` at runtime. | OPTIONAL [`false`] — `send` only | MUST NOT be set on `receive` operations |
| `isolationLevel` | string | The isolation level for this consumer. Controls visibility of messages from transactional producers. | OPTIONAL [`read_uncommitted`] — `receive` only | MUST be one of `read_uncommitted`, `read_committed`. SHOULD be `read_committed` when consuming from a transactional topic |
## Examples
Producer:
```yaml
operations:
publishPaymentEvent:
action: send
bindings:
kafka:
transactional: true
bindingVersion: '0.5.0'
```
Consumer:
```yaml
operations:
consumePaymentEvents:
action: receive
bindings:
kafka:
groupId:
type: string
enum: ['payments-consumer-group']
isolationLevel: read_committed
bindingVersion: '0.5.0'
```
## Notes
The actual `transactional.id` value and its naming strategy are deployment
concerns, not contract concerns. The binding documents intent; the infrastructure
layer owns the runtime value.
End-to-end exactly-once semantics also requires `acks=all` on the producer and
`min.insync.replicas >= 2` on the topic. Those are outside the scope of this
proposal but worth documenting in a follow-up or in a spec note.
## Related
- Kafka docs: [`transactional.id`](https://kafka.apache.org/documentation/#producerconfigs_transactional.id)
- Kafka docs: [`isolation.level`](https://kafka.apache.org/documentation/#consumerconfigs_isolation.level)
### 🚧 Breaking changes
No
### 👀 Have you checked for similar open issues?
- [x] I checked and didn't find a similar issue
### 🏢 Have you read the Contributing Guidelines?
- [x] I have read the [Contributing Guidelines](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md)
### Are you willing to work on this issue?
Yes I am willing to submit a PR!
Contributor guide
Research direction
Start at the Kafka Operation Binding Object definition and review how existing operation fields, send/receive applicability, and binding versions are represented. Implement the proposed transactional and isolationLevel entries with their stated defaults and constraints, then verify the producer and consumer YAML examples reflect the specification.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kafka
- Domain
- api, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100