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

pip/pip-411.md

@@ -0,0 +1,82 @@
+# PIP-411: Expose Peek Messages API to Non-Admin Clients
+
+# Background knowledge
+Apache Pulsar currently exposes the Peek Messages API only under the Admin API. This API allows admin to view (peek) messages on a topic without consuming them, but it is tied to admin API prevents non-admin applications from utilizing this functionality.
+
+# Motivation
+Many non-admin applications—such as monitoring tools, debugging utilities, or custom client applications—need the ability to peek at topic messages without using admin API. Exposing this functionality via a new endpoint would:
+- Enhance usability for a broader range of applications.
+- Simplify the development of non-admin clients.
+
+# Goals
+
+## In Scope
+- Introduce a new endpoint (e.g., within the Lookup API) to expose the Peek Messages functionality for non-admin clients.
+- Leverage the existing internal implementation of the Peek Messages API.
+- Update API documentation to reflect the new endpoint.
+
+## Out of Scope
+- Redesigning the internal logic of message peeking.
+- Modifying the existing Admin API for Peek Messages.
+- Overhauling the overall security model; only adjustments related to this new endpoint are in scope.
+
+# High Level Design
+Add a new REST endpoint within the Lookup API (for example, `/lookup/peek`) that internally delegates to the existing Peek Messages logic. This endpoint will incorporate authorization checks tailored for non-admin clients, ensuring that only allowed users can access the peek functionality while maintaining security standards.
+
+# Detailed Design
+
+## Design & Implementation Details
+- **Endpoint Creation:** Develop a new REST endpoint (e.g., `/lookup/peek`) within the Lookup API.
+- **Authorization Checks:** Allow non-admin clients to access this endpoint by validating their permissions appropriately, ensuring they meet the minimum criteria to peek messages(consume).
+- **Internal Delegation:** Route requests from the new endpoint to the existing Peek Messages logic to avoid code duplication and preserve consistency.
+- **Testing:** Write unit and integration tests to verify correct behavior, including edge cases and potential security issues.
+- **Documentation:** Update the Pulsar documentation and API reference to include the new endpoint, detailing request parameters, expected responses, and error conditions.
+
+## Public-facing Changes
+
+### Public API
+- A new REST endpoint (e.g., `/lookup/peek`) will be added for non-admin clients.
+- The API documentation will be updated to include this endpoint and its usage guidelines.
+
+### Binary protocol
+- No changes to the binary protocol are anticipated.
+
+### Configuration
+- No additional configuration parameters are required. Existing authorization settings will govern access to the new endpoint.
+
+### CLI
+- No changes to CLI tools are planned for this enhancement.
+
+### Metrics
+- No changes to metrics end
+
+# Monitoring
+Standard logging and monitoring practices will be applied to track usage, detect any anomalies, and ensure that the new endpoint performs within expected parameters.
+
+# Security Considerations
+- **Authorization:** Ensure that only users with appropriate permissions can access the new peek functionality.
+- **Risk Mitigation:** Evaluate and address any potential security implications of exposing peek functionality to non-admin clients.
+- **Testing:** Rigorously test for any security vulnerabilities introduced by the new endpoint.
+
+# Backward & Forward Compatibility
+
+## Upgrade
+This proposal introduces an additional endpoint without modifying the existing Admin API, ensuring backward compatibility. Users relying on the current API can continue as before.
+
+## Downgrade / Rollback
+If issues arise, the new endpoint can be disabled or removed without affecting the core functionality of the Admin API.
+
+## Pulsar Geo-Replication Upgrade & Downgrade/Rollback Considerations
+No special considerations for geo-replication are expected.
+
+# Alternatives
+- **Continue with Admin API:** Continue using the existing Admin API for Peek Messages, which restricts usage to admin users.
+- **Develop a Separate Preview Mechanism:** Build an entirely new mechanism for peeking messages, which would require significant architectural changes and is less desirable compared to leveraging existing functionality.
+
+# General Notes
+This proposal aims to enhance the developer experience by allowing non-admin clients to access message peek capabilities in a controlled and secure manner. Community input and further discussion will be essential to refine the implementation details.
+
+# Links
+* Mailing List discussion thread: 
+* Mailing List voting thread: 
+* GitHub Issue: [Enhancement] Make Peek Messages API available for non-admin clients (#24051)