feat: add deferred polling timeout to PollMessages
- Dominant language
- Rust
- Stars
- 4.9k
- Forks
- 432
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 173
Description
## Summary
Add deferred-response polling to `PollMessages`.
This comes from discussion #2854: https://github.com/apache/iggy/discussions/2854
The goal is to let consumers wait for data without busy polling.
## Problem
Today `poll_messages()` returns immediately when no messages are available. Consumers that need low latency must poll frequently, which creates avoidable CPU churn, network traffic, and client-side retry logic.
The core user ask is: "wake me up when data arrives."
## Proposed behavior
Add a wait timeout to `PollMessages`:
- timeout `0` keeps current behavior and returns immediately
- timeout `> 0` waits until matching data is readable or timeout expires
- timeout expiry returns the normal empty poll response, not an error
- auto-commit still happens only when messages are returned
For the binary protocol, use an additive `u64` timeout value in microseconds.
For the Rust SDK, expose the timeout through an idiomatic API using existing time abstractions where appropriate.
## Scope
First PR scope:
- binary protocol request support
- common/http request support if needed for API parity
- Rust SDK/client API support
- current `core/server` implementation
- focused protocol, server, and integration/e2e tests
Out of scope for the first PR:
- unsolicited push frames
- subscribe/unsubscribe commands
- generic notification API
- backlog/control-plane events
- all foreign SDKs
## Server implementation direction
When no messages are available and timeout is greater than zero:
1. Do not block the shard/message pump.
2. Register a lightweight waiter for the resolved stream/topic/partition.
3. Complete the waiter when data becomes readable or the timeout expires.
4. Return an empty successful poll response on timeout.
5. Remove waiters on timeout, completion, cancellation, disconnect, and partition/topic removal.
Wakeups should happen only after data is readable. The response remains the data, not a separate notification signal.
## `server-ng` portability
`core/server` may be deprecated soon, so the first PR should keep the current-server wiring small and portable.
The reusable pieces should be:
- binary protocol shape
- common request/API types
- Rust SDK API
- behavior tests
- integration/e2e coverage
The current `core/server` waiter implementation should avoid large refactors or abstractions that would make the upcoming `core/server-ng` port harder.
## Acceptance criteria
- `poll_messages` without timeout keeps existing behavior.
- timeout `0` keeps existing immediate-poll behavior.
- timeout `> 0` waits when no data is available.
- producing data to the same readable partition wakes the pending poll.
- timeout returns an empty successful poll response.
- timeout does not auto-commit.
- auto-commit still happens when messages are returned and `auto_commit=true`.
- disconnected or timed-out consumers do not leave stale waiters.
- consumer-group polling still respects existing assignment and offset rules.
- tests are deterministic and not timing-flaky.
- current `core/server` changes are small enough to port to `core/server-ng`.
## Related links
- Discussion: https://github.com/apache/iggy/discussions/2854
- Previous blocking poll issue: https://github.com/apache/iggy/issues/829
- Original notification issue moved to discussion: https://github.com/apache/iggy/issues/2851
- Duplicate blocking polling issue: https://github.com/apache/iggy/issues/3002
Contributor guide
Research direction
Start by tracing the existing PollMessages binary protocol, common/HTTP request types, Rust SDK API, and current core/server implementation. Run the focused protocol, server, integration, and e2e tests to understand current polling and auto-commit behavior. Done means deterministic coverage for timeout, wakeup, expiry, cleanup, assignment rules, and a small current-server change that remains portable to core/server-ng.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- backend-api-design, distributed-systems, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100