[DISCUSS] PIP-482: Peek messages from topic subscription with messagePosition

[Pruthviraj Chandru via dev]

Hi Pulsar community,

I would like to revive the discussion on PIP-482: Peek messages from topic
subscription with messagePosition.

Today, Topics.peekMessages / peekMessagesAsync in the Java admin client
hardcode messagePosition = 1, so callers can only inspect messages from the
head of a subscription backlog. The underlying REST endpoint already
accepts an arbitrary position:
http

GET 
/admin/v3/persistent/{tenant}/{namespace}/{topic}/subscription/{subName}/position/{messagePosition}

The most common impact is admin UI pagination — showing the 91st–100th
backlog messages requires fetching and discarding the first 90, which is
wasteful on both client and broker.

The proposal is to:

   - Add a position-aware default overload to the Topics interface — no new
   abstract method and no server changes needed.
   - Preserve full source and binary compatibility with all existing
   peekMessages / peekMessagesAsync overloads.
   - Validate messagePosition >= 1 at the client with a clear
   IllegalArgumentException.
   - Leave MessageId-based peek and a PeekOptions builder to future PIPs.

The main point on which I would appreciate feedback is:

   1. Is the default overload approach the right compatibility strategy, or
   would a different API shape be preferred?

PIP draft PR: https://github.com/apache/pulsar/pull/27140

Feedback is welcome in this thread or as inline comments on the draft PR.

Thanks,
Pruthviraj