Denovo1998 opened a new pull request, #24372:
URL: https://github.com/apache/pulsar/pull/24372
<!--
### Contribution Checklist
- PR title format should be *[type][component] summary*. For details, see
*[Guideline - Pulsar PR Naming
Convention](https://pulsar.apache.org/contribute/develop-semantic-title/)*.
- Fill out the template below to describe the changes contributed by the
pull request. That will give reviewers the context they need to do the review.
- Each pull request should address only one issue, not mix up code from
multiple issues.
- Each commit in the pull request has a meaningful commit message
- Once all items of the checklist are addressed, remove the above text and
this checklist, leaving only the filled out template below.
-->
<!-- Either this PR fixes an issue, -->
Fixes #xyz
<!-- or this PR is one task of an issue -->
Main Issue: #xyz
<!-- If the PR belongs to a PIP, please add the PIP link here -->
PIP: #xyz
<!-- Details of when a PIP is required and how the PIP process work, please
see: https://github.com/apache/pulsar/blob/master/pip/README.md -->
### Motivation
When consumers encounter transient failures while processing messages, a
common requirement is to retry processing after a certain delay. Before this
feature, developers typically resorted to:
1. **Using Retry/Dead Letter Topics (DLQ)**: Consumers would republish
failed messages to a dedicated retry topic. This approach suffered from **write
amplification** (message produced again) and **read amplification** (additional
consumption from the retry topic), and increased architectural complexity.
2. **Application-Level Custom Delay Logic**: Implementing delay logic using
external components (e.g., databases, scheduling frameworks) significantly
increased system complexity and external dependencies.
These existing solutions introduced varying degrees of overhead, complexity,
or inflexibility. This change aims to provide a native, efficient mechanism for
consumer-side delayed message redelivery.
### Modifications
This change introduces the capability for Pulsar consumers to negatively
acknowledge (Nack) messages with a specified custom delay. The key
modifications include:
1. **Client API Extension**:
* New methods `negativeAcknowledge(MessageId messageId, long delay,
TimeUnit unit)` and `negativeAcknowledge(Message<?> message, long delay,
TimeUnit unit)` have been added to the `org.apache.pulsar.client.api.Consumer`
interface.
2. **Protocol Enhancement**:
* The `CommandRedeliverUnacknowledgedMessages` protobuf command has
been augmented with an optional `delay_at_time` (uint64) field. This field
carries the absolute timestamp at which the message is expected to be
redelivered.
3. **Broker-Side Core Logic Adjustments**:
* **`ServerCnx`**: Updated to recognize and process the
`delay_at_time` field in `CommandRedeliverUnacknowledgedMessages`.
* **`Consumer` / `Subscription` / `Dispatcher`**:
* Relevant interfaces and implementations have been extended to
handle redelivery requests with a `delayAtTime`.
* `PersistentDispatcherMultipleConsumers` (and its classic
variant) now leverage the topic-level `DelayedDeliveryTracker` to manage Nacked
messages with a specified delay. The message's position and the target
`delayAtTime` are added to the tracker, which triggers redelivery when the
specified time is reached.
* This feature is primarily effective for `Shared` and `Key_Shared`
subscription types to provide precise delay semantics.
With these modifications, consumers can directly request the broker to
redeliver a message after a specific delay, leading to:
* **Elimination of write and read amplification**: No need to republish
messages to other topics.
* **Simplified application architecture**: Removes the need for external
delay mechanisms or complex application-level logic.
* **Fine-grained control**: Allows consumers to dynamically set retry
delays per message based on specific conditions.
* **Enhanced resource efficiency**: Leverages the broker's internal
delayed message delivery mechanism.
### Verifying this change
- [x] Make sure that the change passes the CI checks.
*(Please pick either of the following options)*
This change is a trivial rework / code cleanup without any test coverage.
*(or)*
This change is already covered by existing tests, such as *(please describe
tests)*.
*(or)*
This change added tests and can be verified as follows:
*(example:)*
- *Added integration tests for end-to-end deployment with large payloads
(10MB)*
- *Extended integration test for recovery after broker failure*
### Does this pull request potentially affect one of the following parts:
<!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
*If the box was checked, please highlight the changes*
- [ ] Dependencies (add or upgrade a dependency)
- [x] The public API
- [ ] The schema
- [ ] The default values of configurations
- [ ] The threading model
- [ ] The binary protocol
- [ ] The REST endpoints
- [ ] The admin CLI options
- [ ] The metrics
- [ ] Anything that affects deployment
### Documentation
<!-- DO NOT REMOVE THIS SECTION. CHECK THE PROPER BOX ONLY. -->
- [ ] `doc` <!-- Your PR contains doc changes. -->
- [x] `doc-required` <!-- Your PR changes impact docs and you will update
later -->
- [ ] `doc-not-needed` <!-- Your PR changes do not impact docs -->
- [ ] `doc-complete` <!-- Docs have been already added -->
### Matching PR in forked repository
PR in forked repository: <!-- ENTER URL HERE -->
<!--
After opening this PR, the build in apache/pulsar will fail and instructions
will
be provided for opening a PR in the PR author's forked repository.
apache/pulsar pull requests should be first tested in your own fork since
the
apache/pulsar CI based on GitHub Actions has constrained resources and quota.
GitHub Actions provides separate quota for pull requests that are executed
in
a forked repository.
The tests will be run in the forked repository until all PR review comments
have
been handled, the tests pass and the PR is approved by a reviewer.
-->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
