apache / apache/iggy

feat: add deferred polling timeout to PollMessages

Open
#3,470 2 comments 0 reactions 0 assignees View on GitHub
api enhancement server
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.