[improve] PIP-411: Expose Peek Messages API to Non-Admin Clients

[sandeep-mst]

Fixes #24051

Main Issue: #24051

PIP: #411

Motivation

Apache Pulsar currently exposes the Peek Messages API only under the Admin API, which prevents non-admin applications from using this functionality. Some non-admin applications—such as monitoring tools or custom client applications—need to peek at messages without consuming them.
It is easier to restrict a client without admin access by denying it the admin client object. But in some cases they need the ability to peek messages which actually doesn't require admin access as peekMessages works with consume permissions..
Exposing this functionality via a new endpoint will:

• Enhance usability for a broader range of applications.
• Simplify the development of non-admin clients by providing direct access to message peeking.
• Maintain consistency by leveraging the existing internal Peek Messages logic.

Modifications

• Endpoint Creation:
  A new REST endpoint (e.g., /lookup/peek) will be added within the Lookup API, enabling non-admin clients to access the Peek Messages functionality.

• LookupService:
  The LookupService interface will be extended to include a new peekMessages method. This method will be implemented in both HttpLookupService and BinaryProtoLookupService, ensuring support for peeking messages across both HTTP and binary protocol lookup mechanisms.

• Authorization Checks:
  The new endpoint will include proper authorization checks to ensure that only permitted non-admin clients can use it.

• Internal Delegation:
  Requests received on the new endpoint will be internally delegated to the existing Peek Messages logic, avoiding code duplication while preserving consistent behavior.

• Documentation Update:
  The API documentation and reference materials will be updated to include details about the new endpoint, request parameters, response formats, and error conditions.

Verifying this change

• Added unit and integration tests to validate:

  • The new endpoint correctly delegates to the internal Peek Messages logic.
  • Authorization checks are enforced as expected.
  • Backward compatibility is maintained (existing Admin API remains unchanged).

• Manual testing will be conducted to verify non-admin clients can access the new endpoint while admin clients continue to use the current API.

Does this pull request potentially affect one of the following parts:

• Dependencies (add or upgrade a dependency)
• 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

This PR affects the REST endpoints (by adding a new endpoint) and binary protocol of the same.

Documentation

• doc
• doc-required
• doc-not-needed
• doc-complete

Matching PR in forked repository

PR in forked repository: cognitree#20